diff options
Diffstat (limited to 'macros/latex/contrib/crumbs/crumbs.dtx')
-rw-r--r-- | macros/latex/contrib/crumbs/crumbs.dtx | 351 |
1 files changed, 351 insertions, 0 deletions
diff --git a/macros/latex/contrib/crumbs/crumbs.dtx b/macros/latex/contrib/crumbs/crumbs.dtx new file mode 100644 index 0000000000..ee9a6b168c --- /dev/null +++ b/macros/latex/contrib/crumbs/crumbs.dtx @@ -0,0 +1,351 @@ +% \iffalse meta-comment +% (The MIT License) +% +% Copyright (c) 2021-2022 Yegor Bugayenko +% +% Permission is hereby granted, free of charge, to any person obtaining a copy +% of this software and associated documentation files (the 'Software'), to deal +% in the Software without restriction, including without limitation the rights +% to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +% copies of the Software, and to permit persons to whom the Software is +% furnished to do so, subject to the following conditions: +% +% The above copyright notice and this permission notice shall be included in all +% copies or substantial portions of the Software. +% +% THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +% IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +% FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +% AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +% LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +% OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +% SOFTWARE. +% \fi + +% \CheckSum{0} +% +% \CharacterTable +% {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 +% 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 +% Digits \0\1\2\3\4\5\6\7\8\9 +% Exclamation \! Double quote \" Hash (number) \# +% Dollar \$ Percent \% Ampersand \& +% Acute accent \' Left paren \( Right paren \) +% Asterisk \* Plus \+ Comma \, +% Minus \- Point \. Solidus \/ +% Colon \: Semicolon \; Less than \< +% Equals \= Greater than \> Question mark \? +% Commercial at \@ Left bracket \[ Backslash \\ +% Right bracket \] Circumflex \^ Underscore \_ +% Grave accent \` Left brace \{ Vertical bar \| +% Right brace \} Tilde \~} + +% \GetFileInfo{crumbs.dtx} +% \DoNotIndex{\endgroup,\begingroup,\let,\else,\fi,\newcommand,\newenvironment} + +% \iffalse +%<*driver> +\ProvidesFile{crumbs.dtx} +%</driver> +%<package>\NeedsTeXFormat{LaTeX2e} +%<package>\ProvidesPackage{crumbs} +%<*package> +[2022-10-03 0.4.1 Inputable Shell Executions] +%</package> +%<*driver> +\documentclass{ltxdoc} +\usepackage[tt=false, type1=true]{libertine} +\usepackage{crumbs} +\usepackage{href-ul} +\PageIndex +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\begin{document} + \DocInput{crumbs.dtx} + \PrintChanges + \PrintIndex +\end{document} +%</driver> +% \fi + +% \title{|crumbs|: \LaTeX{} Package \\ for Navigation Crumbs\thanks{The sources are in GitHub at \href{https://github.com/yegor256/crumbs}{yegor256/crumbs}}} +% \author{Yegor Bugayenko \\ \texttt{yegor256@gmail.com}} +% \date{\filedate, \fileversion} +% +% \maketitle +% +% \section{Introduction} +% +% This package helps you add navigation crumbs to your document, +% which is most useful for presentations and slide decks: +%\iffalse +%<*verb> +%\fi +\begin{verbatim} +\documentclass{article} +\usepackage{crumbs} +\usepackage{fancyhdr} + \fancyhf{} + \pagestyle{fancy} + \fancyhead[L]{\crumbs / \subcrumbs} +\begin{document} +\section{Introduction} +Some text here. +\section{Related Works} +Some other text here. +\end{document} +\end{verbatim} +%\iffalse +%</verb> +%\fi + +% \begin{macro}{\crumb} +% You may redefine |\crumb{}| and |\subcrumb{}| +% commands, if you want your crumbs to look nicer, for example: +%\iffalse +%<*verb> +%\fi +\begin{verbatim} +\renewcommand\crumb[2]{{ + \ifnum\value{section}=\value{crumbi} + \color{orange} + \fi + #1 +}} +\end{verbatim} +%\iffalse +%</verb> +%\fi +% \end{macro} +% The command will be called by |\crumbs| with two arguments. The first one +% will be the short name of the crumb, the second one will be the long one. +% The counter |crumbi| will be equal to the position of the crumb +% being rendered, starting from zero. + +% \begin{macro}{\subcrumb} +% The same for |\subcrumb{}|, but the comparison should be +% done not between |section| and |crumbi|, but between +% |subsection| and |subcrumbi| counters. +% \end{macro} + +% \begin{macro}{\section} +% The first parameter of both |\crumb{}| and |\subcrumb{}| +% is the optional parameter of |\section{}| and |\subsection{}| +% calls respectively. The second one is the mandatory parameter of them, which +% is the full text of the section and sub-section. +% When you use |crumbs| package, you can use |\section| and |\subsection| with +% an optional argument, which will be used in the crumbs, e.g.: +%\iffalse +%<*verb> +%\fi +\begin{verbatim} +\section[Details]{More Details About The Method} +\subsection[SLR]{Systematic Literature Review} +\end{verbatim} +%\iffalse +%</verb> +%\fi +% \end{macro} + +% \section{Package Options} + +% \begin{macro}{dry} +% You may turn on the ``dry'' mode, which will prohibit the package to +% renew |\section{}| and |\subsection{}| commands. +% You will still be able to use the crumbs mechanism through +% |\crumbection{}| and |\subcrumbection{}| commands, for example: +%\iffalse +%<*verb> +%\fi +\begin{verbatim} +\documentclass{article} +\usepackage[dry]{crumbs} +\begin{document} +\crumbection[Intro]{Introduction} % Add it to \crumbs +\section{Introduction} % Print it to the page +Hello, world! +\end{document} +\end{verbatim} +%\iffalse +%</verb> +%\fi +% \end{macro} + +% \begin{macro}{increment} +% You can also instruct it to increment +% |\section{}| and |\subsection{}| +% on each call to |\crumbection{}| and |\subcrumbection{}| +% respectively. Just use the |increment| package option. +% \end{macro} + +% \section{How It Works} + +% On the first run, a new file |jobname.crumbs| is created, +% where all |\section| and |\subsection| commands +% are being logged. + +% On the second run, the file is loaded and two commands are being +% created: |\crumbs| and |\subcrumbs|. The first +% one is a collection of |\crumb{}| calls, while the second +% one is a collection of |\subcrumb{}| ones. + +% \StopEventually{} + +% \section{Implementation} + +% \changes{v0.2.0}{2021/07/10}{Initial version} + +% \iffalse +\RequirePackage{xkeyval} +\RequirePackage{etoolbox} +\makeatletter\newif\ifcrumbs@dry\makeatother +\makeatletter\DeclareOption{dry}{\crumbs@drytrue}\makeatother +\makeatletter\newif\ifcrumbs@increment\makeatother +\makeatletter\DeclareOption{increment}{\crumbs@incrementtrue}\makeatother +\ProcessOptions\relax +% \fi + +% \begin{macro}{\crumbs} +% It is implemented with the help of |catchfile| package. First, +% we define special commands for special characters inside the +% |jobname.crumbs| files, as suggested \href{https://tex.stackexchange.com/a/12414/1449}{here}: +% \begin{macrocode} +\makeatletter\newcommand\crumbs@back{\@backslashchar}\makeatother +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\appendtofile} +% Then, we define a new command |\appendtofile|: +% \begin{macrocode} +\RequirePackage{catchfile} + \newwrite\appendwrite + \ExplSyntaxOn\cs_new:Npn\appendtofile#1#2{% + \begingroup + \IfFileExists{#1}% + {\CatchFileDef{\filecontent}{#1}{\endlinechar=`^^J\catcode\endlinechar=12\relax}}% keep existing end-of-lines + {\let\filecontent\empty}% + \immediate\openout\appendwrite=#1\relax + \immediate\write\appendwrite{\unexpanded\expandafter{\filecontent} \text_purify:n{#2}}% + \immediate\closeout\appendwrite + \endgroup + }\ExplSyntaxOff +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\subcrumbs} +% The command |\subcrumbs| prints all sub-crumbs for the current subsection: +% \begin{macrocode} +\newcommand\subcrumbs{% + \ifnum\value{section}=0\else% + \expandafter\ifcsname crumbs\romannumeral\the\value{section}\endcsname% + \csname crumbs\romannumeral\the\value{section}\endcsname{}% + \fi% + \fi% +} +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\crumbection} +% The command |\crumbection| registers a new crumb: +% \begin{macrocode} +\makeatletter\newcommand\crumbection[2][]{% + \def\temp{#1}% + \ifx\crumbs\empty% + \appendtofile{\jobname.crumbs}{% + \crumbs@back ifx\crumbs@back crumbs\crumbs@back empty% + \crumbs@back gappto\crumbs@back crumbs\{\crumbs@back setcounter\{crumbi\}\{0\}\}% + \crumbs@back fi% + \crumbs@back gappto\crumbs@back crumbs\{\crumbs@back stepcounter\{crumbi\}\crumbs@back crumb{\ifx\temp\empty \{#2\}\else \{#1\}\fi}{\{#2\}}\}% + }% + \fi% + \ifcrumbs@increment\stepcounter{section}\fi% +}\makeatother +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\subcrumbection} +% The command |\subcrumbection| registers a new subcrumb: +% \begin{macrocode} +\makeatletter\newcommand\subcrumbection[2][]{% + \def\temp{#1}% + \ifx\crumbs\empty% + \appendtofile{\jobname.crumbs}{% + \crumbs@back ifcsname crumbs\romannumeral\the\value{section}\crumbs@back endcsname\crumbs@back else + \crumbs@back expandafter\crumbs@back newcommand\crumbs@back csname crumbs\romannumeral\the\value{section}\crumbs@back endcsname\{% + \crumbs@back setcounter\{subcrumbi\}\{0\}% + \}% + \crumbs@back fi% + \crumbs@back expandafter\crumbs@back gappto\crumbs@back csname crumbs\romannumeral\the\value{section}\crumbs@back endcsname\{% + \crumbs@back stepcounter\{subcrumbi\}% + \crumbs@back subcrumb{\ifx\temp\empty \{#2\}\else \{#1\}\fi}{\{#2\}}\}% + }% + \fi% + \ifcrumbs@increment\stepcounter{subsection}\fi% +}\makeatother +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\section} +% We also redefined |\section| and |\subsection| commands: +% \begin{macrocode} +\makeatletter\ifcrumbs@dry% + \message{Since "dry" mode is ON we don't renew "section" and "subsection" commands}% +\else% + \NewCommandCopy\crumbs@oldsection\section + \renewcommand\section[2][]{% + \crumbection[#1]{#2}% + \crumbs@oldsection{#2}% + } + \NewCommandCopy\crumbs@oldsubsection\subsection + \renewcommand\subsection[2][]{% + \subcrumbection[#1]{#2}% + \crumbs@oldsubsection{#2}% + } +\fi\makeatletter +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\crumb} +% We define default implementations of |\crumb| command: +% \begin{macrocode} +\ifcsname crumb\endcsname% + \message{The command "crumb" is already defined}% +\else% + \newcommand\crumb[2]{#1}% +\fi% +% \end{macrocode} +% \end{macro} + +% \begin{macro}{\subcrumb} +% We define default implementations of |\subcrumb| command: +% \begin{macrocode} +\ifcsname subcrumb\endcsname% + \message{The command "subcrumb" is already defined}% +\else% + \newcommand\subcrumb[2]{#1}% +\fi% +% \end{macrocode} +% \end{macro} + +% \begin{macro}{crumbi} +% We also define a few counters: +% \begin{macrocode} +\newcommand*\crumbs{} +\newcounter{crumbi} +\newcounter{subcrumbi} +% \end{macrocode} +% \end{macro} + +% Finally, we load the file into the document: +% \begin{macrocode} +\AtBeginDocument{\IfFileExists{\jobname.crumbs}{\input{\jobname.crumbs}}{}} +% \end{macrocode} + +% \Finale + +%\clearpage +% +%\PrintChanges +%\clearpage +%\PrintIndex |