Debian Codegraph @

texmf-dist/source/latex/crumbs/crumbs.dtx

raw
1 % \iffalse meta-comment
2 % (The MIT License)
3 %
4 % Copyright (c) 2021-2022 Yegor Bugayenko
5 %
6 % Permission is hereby granted, free of charge, to any person obtaining a copy
7 % of this software and associated documentation files (the 'Software'), to deal
8 % in the Software without restriction, including without limitation the rights
9 % to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 % copies of the Software, and to permit persons to whom the Software is
11 % furnished to do so, subject to the following conditions:
12 %
13 % The above copyright notice and this permission notice shall be included in all
14 % copies or substantial portions of the Software.
15 %
16 % THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 % IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 % FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 % AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 % LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 % OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 % SOFTWARE.
23 % \fi
24
25 % \CheckSum{0}
26 %
27 % \CharacterTable
28 % {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
29 % Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
30 % Digits \0\1\2\3\4\5\6\7\8\9
31 % Exclamation \! Double quote \" Hash (number) \#
32 % Dollar \$ Percent \% Ampersand \&
33 % Acute accent \' Left paren \( Right paren \)
34 % Asterisk \* Plus \+ Comma \,
35 % Minus \- Point \. Solidus \/
36 % Colon \: Semicolon \; Less than \<
37 % Equals \= Greater than \> Question mark \?
38 % Commercial at \@ Left bracket \[ Backslash \\
39 % Right bracket \] Circumflex \^ Underscore \_
40 % Grave accent \` Left brace \{ Vertical bar \|
41 % Right brace \} Tilde \~}
42
43 % \GetFileInfo{crumbs.dtx}
44 % \DoNotIndex{\endgroup,\begingroup,\let,\else,\fi,\newcommand,\newenvironment}
45
46 % \iffalse
47 %<*driver>
48 \ProvidesFile{crumbs.dtx}
49 %</driver>
50 %<package>\NeedsTeXFormat{LaTeX2e}
51 %<package>\ProvidesPackage{crumbs}
52 %<*package>
53 [2022-10-03 0.4.1 Inputable Shell Executions]
54 %</package>
55 %<*driver>
56 \documentclass{ltxdoc}
57 \usepackage[tt=false, type1=true]{libertine}
58 \usepackage{crumbs}
59 \usepackage{href-ul}
60 \PageIndex
61 \EnableCrossrefs
62 \CodelineIndex
63 \RecordChanges
64 \begin{document}
65 \DocInput{crumbs.dtx}
66 \PrintChanges
67 \PrintIndex
68 \end{document}
69 %</driver>
70 % \fi
71
72 % \title{|crumbs|: \LaTeX{} Package \\ for Navigation Crumbs\thanks{The sources are in GitHub at \href{https://github.com/yegor256/crumbs}{yegor256/crumbs}}}
73 % \author{Yegor Bugayenko \\ \texttt{[email protected]}}
74 % \date{\filedate, \fileversion}
75 %
76 % \maketitle
77 %
78 % \section{Introduction}
79 %
80 % This package helps you add navigation crumbs to your document,
81 % which is most useful for presentations and slide decks:
82 %\iffalse
83 %<*verb>
84 %\fi
85 \begin{verbatim}
86 \documentclass{article}
87 \usepackage{crumbs}
88 \usepackage{fancyhdr}
89 \fancyhf{}
90 \pagestyle{fancy}
91 \fancyhead[L]{\crumbs / \subcrumbs}
92 \begin{document}
93 \section{Introduction}
94 Some text here.
95 \section{Related Works}
96 Some other text here.
97 \end{document}
98 \end{verbatim}
99 %\iffalse
100 %</verb>
101 %\fi
102
103 % \begin{macro}{\crumb}
104 % You may redefine |\crumb{}| and |\subcrumb{}|
105 % commands, if you want your crumbs to look nicer, for example:
106 %\iffalse
107 %<*verb>
108 %\fi
109 \begin{verbatim}
110 \renewcommand\crumb[2]{{
111 \ifnum\value{section}=\value{crumbi}
112 \color{orange}
113 \fi
114 #1
115 }}
116 \end{verbatim}
117 %\iffalse
118 %</verb>
119 %\fi
120 % \end{macro}
121 % The command will be called by |\crumbs| with two arguments. The first one
122 % will be the short name of the crumb, the second one will be the long one.
123 % The counter |crumbi| will be equal to the position of the crumb
124 % being rendered, starting from zero.
125
126 % \begin{macro}{\subcrumb}
127 % The same for |\subcrumb{}|, but the comparison should be
128 % done not between |section| and |crumbi|, but between
129 % |subsection| and |subcrumbi| counters.
130 % \end{macro}
131
132 % \begin{macro}{\section}
133 % The first parameter of both |\crumb{}| and |\subcrumb{}|
134 % is the optional parameter of |\section{}| and |\subsection{}|
135 % calls respectively. The second one is the mandatory parameter of them, which
136 % is the full text of the section and sub-section.
137 % When you use |crumbs| package, you can use |\section| and |\subsection| with
138 % an optional argument, which will be used in the crumbs, e.g.:
139 %\iffalse
140 %<*verb>
141 %\fi
142 \begin{verbatim}
143 \section[Details]{More Details About The Method}
144 \subsection[SLR]{Systematic Literature Review}
145 \end{verbatim}
146 %\iffalse
147 %</verb>
148 %\fi
149 % \end{macro}
150
151 % \section{Package Options}
152
153 % \begin{macro}{dry}
154 % You may turn on the ``dry'' mode, which will prohibit the package to
155 % renew |\section{}| and |\subsection{}| commands.
156 % You will still be able to use the crumbs mechanism through
157 % |\crumbection{}| and |\subcrumbection{}| commands, for example:
158 %\iffalse
159 %<*verb>
160 %\fi
161 \begin{verbatim}
162 \documentclass{article}
163 \usepackage[dry]{crumbs}
164 \begin{document}
165 \crumbection[Intro]{Introduction} % Add it to \crumbs
166 \section{Introduction} % Print it to the page
167 Hello, world!
168 \end{document}
169 \end{verbatim}
170 %\iffalse
171 %</verb>
172 %\fi
173 % \end{macro}
174
175 % \begin{macro}{increment}
176 % You can also instruct it to increment
177 % |\section{}| and |\subsection{}|
178 % on each call to |\crumbection{}| and |\subcrumbection{}|
179 % respectively. Just use the |increment| package option.
180 % \end{macro}
181
182 % \section{How It Works}
183
184 % On the first run, a new file |jobname.crumbs| is created,
185 % where all |\section| and |\subsection| commands
186 % are being logged.
187
188 % On the second run, the file is loaded and two commands are being
189 % created: |\crumbs| and |\subcrumbs|. The first
190 % one is a collection of |\crumb{}| calls, while the second
191 % one is a collection of |\subcrumb{}| ones.
192
193 % \StopEventually{}
194
195 % \section{Implementation}
196
197 % \changes{v0.2.0}{2021/07/10}{Initial version}
198
199 % \iffalse
200 \RequirePackage{xkeyval}
201 \RequirePackage{etoolbox}
202 \makeatletter\newif\ifcrumbs@dry\makeatother
203 \makeatletter\DeclareOption{dry}{\crumbs@drytrue}\makeatother
204 \makeatletter\newif\ifcrumbs@increment\makeatother
205 \makeatletter\DeclareOption{increment}{\crumbs@incrementtrue}\makeatother
206 \ProcessOptions\relax
207 % \fi
208
209 % \begin{macro}{\crumbs}
210 % It is implemented with the help of |catchfile| package. First,
211 % we define special commands for special characters inside the
212 % |jobname.crumbs| files, as suggested \href{https://tex.stackexchange.com/a/12414/1449}{here}:
213 % \begin{macrocode}
214 \makeatletter\newcommand\crumbs@back{\@backslashchar}\makeatother
215 % \end{macrocode}
216 % \end{macro}
217
218 % \begin{macro}{\appendtofile}
219 % Then, we define a new command |\appendtofile|:
220 % \begin{macrocode}
221 \RequirePackage{catchfile}
222 \newwrite\appendwrite
223 \ExplSyntaxOn\cs_new:Npn\appendtofile#1#2{%
224 \begingroup
225 \IfFileExists{#1}%
226 {\CatchFileDef{\filecontent}{#1}{\endlinechar=`^^J\catcode\endlinechar=12\relax}}% keep existing end-of-lines
227 {\let\filecontent\empty}%
228 \immediate\openout\appendwrite=#1\relax
229 \immediate\write\appendwrite{\unexpanded\expandafter{\filecontent} \text_purify:n{#2}}%
230 \immediate\closeout\appendwrite
231 \endgroup
232 }\ExplSyntaxOff
233 % \end{macrocode}
234 % \end{macro}
235
236 % \begin{macro}{\subcrumbs}
237 % The command |\subcrumbs| prints all sub-crumbs for the current subsection:
238 % \begin{macrocode}
239 \newcommand\subcrumbs{%
240 \ifnum\value{section}=0\else%
241 \expandafter\ifcsname crumbs\romannumeral\the\value{section}\endcsname%
242 \csname crumbs\romannumeral\the\value{section}\endcsname{}%
243 \fi%
244 \fi%
245 }
246 % \end{macrocode}
247 % \end{macro}
248
249 % \begin{macro}{\crumbection}
250 % The command |\crumbection| registers a new crumb:
251 % \begin{macrocode}
252 \makeatletter\newcommand\crumbection[2][]{%
253 \def\temp{#1}%
254 \ifx\crumbs\empty%
255 \appendtofile{\jobname.crumbs}{%
256 \crumbs@back ifx\crumbs@back crumbs\crumbs@back empty%
257 \crumbs@back gappto\crumbs@back crumbs\{\crumbs@back setcounter\{crumbi\}\{0\}\}%
258 \crumbs@back fi%
259 \crumbs@back gappto\crumbs@back crumbs\{\crumbs@back stepcounter\{crumbi\}\crumbs@back crumb{\ifx\temp\empty \{#2\}\else \{#1\}\fi}{\{#2\}}\}%
260 }%
261 \fi%
262 \ifcrumbs@increment\stepcounter{section}\fi%
263 }\makeatother
264 % \end{macrocode}
265 % \end{macro}
266
267 % \begin{macro}{\subcrumbection}
268 % The command |\subcrumbection| registers a new subcrumb:
269 % \begin{macrocode}
270 \makeatletter\newcommand\subcrumbection[2][]{%
271 \def\temp{#1}%
272 \ifx\crumbs\empty%
273 \appendtofile{\jobname.crumbs}{%
274 \crumbs@back ifcsname crumbs\romannumeral\the\value{section}\crumbs@back endcsname\crumbs@back else
275 \crumbs@back expandafter\crumbs@back newcommand\crumbs@back csname crumbs\romannumeral\the\value{section}\crumbs@back endcsname\{%
276 \crumbs@back setcounter\{subcrumbi\}\{0\}%
277 \}%
278 \crumbs@back fi%
279 \crumbs@back expandafter\crumbs@back gappto\crumbs@back csname crumbs\romannumeral\the\value{section}\crumbs@back endcsname\{%
280 \crumbs@back stepcounter\{subcrumbi\}%
281 \crumbs@back subcrumb{\ifx\temp\empty \{#2\}\else \{#1\}\fi}{\{#2\}}\}%
282 }%
283 \fi%
284 \ifcrumbs@increment\stepcounter{subsection}\fi%
285 }\makeatother
286 % \end{macrocode}
287 % \end{macro}
288
289 % \begin{macro}{\section}
290 % We also redefined |\section| and |\subsection| commands:
291 % \begin{macrocode}
292 \makeatletter\ifcrumbs@dry%
293 \message{Since "dry" mode is ON we don't renew "section" and "subsection" commands}%
294 \else%
295 \NewCommandCopy\crumbs@oldsection\section
296 \renewcommand\section[2][]{%
297 \crumbection[#1]{#2}%
298 \crumbs@oldsection{#2}%
299 }
300 \NewCommandCopy\crumbs@oldsubsection\subsection
301 \renewcommand\subsection[2][]{%
302 \subcrumbection[#1]{#2}%
303 \crumbs@oldsubsection{#2}%
304 }
305 \fi\makeatletter
306 % \end{macrocode}
307 % \end{macro}
308
309 % \begin{macro}{\crumb}
310 % We define default implementations of |\crumb| command:
311 % \begin{macrocode}
312 \ifcsname crumb\endcsname%
313 \message{The command "crumb" is already defined}%
314 \else%
315 \newcommand\crumb[2]{#1}%
316 \fi%
317 % \end{macrocode}
318 % \end{macro}
319
320 % \begin{macro}{\subcrumb}
321 % We define default implementations of |\subcrumb| command:
322 % \begin{macrocode}
323 \ifcsname subcrumb\endcsname%
324 \message{The command "subcrumb" is already defined}%
325 \else%
326 \newcommand\subcrumb[2]{#1}%
327 \fi%
328 % \end{macrocode}
329 % \end{macro}
330
331 % \begin{macro}{crumbi}
332 % We also define a few counters:
333 % \begin{macrocode}
334 \newcommand*\crumbs{}
335 \newcounter{crumbi}
336 \newcounter{subcrumbi}
337 % \end{macrocode}
338 % \end{macro}
339
340 % Finally, we load the file into the document:
341 % \begin{macrocode}
342 \AtBeginDocument{\IfFileExists{\jobname.crumbs}{\input{\jobname.crumbs}}{}}
343 % \end{macrocode}
344
345 % \Finale
346
347 %\clearpage
348 %
349 %\PrintChanges
350 %\clearpage
351 %\PrintIndex