Debian Codegraph @

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

raw
1 % \iffalse
2 %<*never>
3 \documentclass{ltxdoc}
4
5 \AtBeginDocument{\CodelineIndex\EnableCrossrefs}
6 \AtEndDocument{\PrintIndex}
7 \GetFileInfo{stack.cls}
8 \def\pack#1{\texttt{#1}}
9 \begin{document}
10 \def\docdate{2002/01/20}
11 \CheckSum{12}
12 \DocInput{stack.dtx}
13 \end{document}
14 %</never>
15 % \fi
16 % \iffalse
17 %
18 % (c) 2002 Benjamin BAYART. Freely redistributable under lppl.
19 %
20 % \fi
21 % \CheckSum{110}
22 % \DoNotIndex{\edef,\advance,\else,\csname,\endcsname,\expandafter}
23 % \DoNotIndex{\ifx,\fi,\input,\ifnum,\relax,\newcount,\romannumeral}
24 % \DoNotIndex{\the,\typeout,\xdef,\global,\newcommand,\RequirePackage}
25 % \DoNotIndex{\PackageError,\ProvidesPackage,\gdef}
26 %% \CharacterTable
27 %% {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
28 %% 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
29 %% Digits \0\1\2\3\4\5\6\7\8\9
30 %% Exclamation \! Double quote \" Hash (number) \#
31 %% Dollar \$ Percent \% Ampersand \&
32 %% Acute accent \' Left paren \( Right paren \)
33 %% Asterisk \* Plus \+ Comma \,
34 %% Minus \- Point \. Solidus \/
35 %% Colon \: Semicolon \; Less than \<
36 %% Equals \= Greater than \> Question mark \?
37 %% Commercial at \@ Left bracket \[ Backslash \\
38 %% Right bracket \] Circumflex \^ Underscore \_
39 %% Grave accent \` Left brace \{ Vertical bar \|
40 %% Right brace \} Tilde \~}
41 %
42 % \title{Using stacks independently from \TeX's one}
43 % \author{Benjamin \textsc{Bayart}}
44 % \date{\filedate}
45 % \maketitle
46 % \begin{abstract}
47 % This package is aimed to provide a new stack mechanisme independent
48 % from the \TeX\ stack itself. The first use was to have a system where
49 % |\input| become directory recursive. I.e.~to provide a kind of
50 % |\chdir| command: when you include a file ``\emph{a}'', it's directory become
51 % the current one, until the end of ``\emph{a}''. See the ``sample package''
52 % section for full explanation.
53 %
54 % This package by itself is of no use, except for some macro-developpers.
55 % \end{abstract}
56 % \tableofcontents
57 %
58 % \section{User's guide}
59 %
60 % \subsection{The \pack{stack} package}
61 %
62 % All of the macros provided by this package are supposed for
63 % package developpers (the is no meaning for a stack in a final
64 % document, only to be used in a package), so, all of those macros
65 % have capital letters in their names, following old guidelines
66 % for \LaTeX3 project.
67 %
68 % The first macro is the one to create a new stack:\newline
69 % \cs{NewStack}\marg{stack}\marg{default}\newline
70 % Well, it just initializes all the required data for the stack.
71 % \emph{default} is the value of the top of the stack if the stack is
72 % empty.
73 %
74 % The second one is the macro to push a new value on top of the
75 % stack:\newline
76 % \cs{Push}\marg{stack}\marg{value}\newline
77 %
78 % The third one is to remove the value on the top (i.e. to pop):\newline
79 % \cs{Pop}\marg{stack}
80 %
81 % Finally, the most usefull one is the command to obtain the value
82 % on the top of the stack:\newline
83 % \cs{Stack}\marg{stack}
84 %
85 % Another one is provided, but only for debugging purpose, it will
86 % |\typeout| the current value on the top of the stack:\newline
87 % \cs{ShowTop}\marg{stack}
88 %
89 % \subsection{The \pack{relinput} package}
90 %
91 % |relinput| provides only one macro which syntax is:\newline
92 % \cs{relinput}\marg{directory}\marg{file}.
93 %
94 % This will move the ``current directory'' into \emph{directory},
95 % from there include \emph{file}, and then go back to what was
96 % the current directory before you call the macro.
97 %
98 % A good way to understand it is to try to split a large document
99 % in a large number of files. Say a first level of directories
100 % for the parts, a second one for the chapters, a third one for
101 % the sections, and in each one a file per subsection.
102 %
103 % So, we will have this kind of directory tree:
104 % \begin{macrocode}
105 %<*never>
106 part-one/
107 part-one/thepart.tex
108 part-one/chapter-one/
109 part-one/chapter-one/thechapter.tex
110 part-one/chapter-one/section-one/
111 part-one/chapter-one/section-one/thesection.tex
112 part-one/chapter-one/section-one/subsec1.tex
113 part-one/chapter-one/section-one/subsec2.tex
114 part-one/chapter-one/section-two/
115 part-one/chapter-one/section-three/
116 part-one/chapter-two/
117 part-one/chapter-two/thechapter.tex
118 part-two/
119 part-two/thepart.tex
120 part-two/chapter-one/
121 part-two/chapter-one/thechapter.tex
122 % \end{macrocode}
123 %
124 % And so on.
125 %
126 % The main file only says:
127 % \begin{macrocode}
128 \relinput{part-one}{thepart.tex}
129 \relinput{part-two}{thepart.tex}
130 % \end{macrocode}
131 %
132 % The file |part-one/thepart.tex| states:
133 % \begin{macrocode}
134 \relinput{chapter-one}{thechapter.tex}
135 \relinput{chapter-two}{thechapter.tex}
136 % \end{macrocode}
137 %
138 % And so on for the other files, untill
139 % |part-one/chapter-one/section-one/thesection.tex| which says:
140 % \begin{macrocode}
141 \relinput{.}{subsec1.tex}
142 \relinput{.}{subsec2.tex}
143 %</never>
144 % \end{macrocode}
145 %
146 % With such a scheme, when you work on a chapter, you don't have to
147 % remember in which directory it is, and, even better, if you
148 % decide to rename the |chapter-one| directory to |introduction|
149 % you have only one file to modify.
150 %
151 % By using the usual \LaTeX\ mechanism you would have to edit the
152 % same file, plus all the files in this directory which include
153 % others (that's a rather large number of files).
154 %
155 % \section{Test file}
156 %
157 % The test application for |stack| is a ``relative dir input''. The basic
158 % macro is |\relinput| which takes two arguments: first a directory
159 % where to go (from the previous one) and then a file to include.
160 %
161 % In your main file (|./file.tex|) if you do |\relinput{dir}{file2.tex}|
162 % then \TeX\ will include |./dir/file2.tex|. If, in |file2|, you do
163 % |\relinput{dir2}{file3.tex}|, then, \TeX\ will include |./dir/dir2/file3.tex|.
164 %
165 % Really interesting if you have a large document with a lot of files
166 % in which case you can move a directory and have only minors corrections
167 % to do in a few files, and, anyway, no corrections in the files \emph{in}
168 % this directory, but only to files \emph{out} of the directory.
169 %
170 % This test file is provided as a small package |relinput|.
171 % \begin{macrocode}
172 %<*test>
173 \ProvidesPackage{relinput}[2002/01/20 v1.00 Relative input]
174 \RequirePackage{stack}
175 \NewStack{reldir}{.}
176 % \end{macrocode}
177 % \begin{macro}{\relinput}
178 % \begin{macrocode}
179 \newcommand\relinput[2]{%
180 \Push{reldir}{\Stack{reldir}/#1}%
181 \input{\Stack{reldir}/#2}%
182 \Pop{reldir}%
183 }
184 %</test>
185 % \end{macrocode}
186 % \end{macro}
187 %
188 % \StopEventually{}
189 %
190 % \section{Code for the \pack{stack} package}
191 %
192 % \subsection{Identification}
193 %
194 % \begin{macrocode}
195 %<*package>
196 \ProvidesPackage{stack}[2002/01/20 v1.0 Multi-stack system]
197 % \end{macrocode}
198 %
199 % \subsection{Macros by itself}
200 %
201 % In the following code, to use only one counter (in the \TeX\ meaning)
202 % we store the various values in macros, and use only the counter when
203 % we need to do computations.
204 %
205 % \begin{macro}{\tmp@stack}
206 % \begin{macrocode}
207 \newcount\tmp@stack
208 % \end{macrocode}
209 % \end{macro}
210 %
211 % Creating a new stack is, essentially, creating a new counter-like
212 % macro, initializing it to 0, and creating the macro for stack-top
213 % evaluation.
214 %
215 % \begin{macro}{\NewStack}
216 % This stack-top evaluation macro is required due to an ugly trick.
217 % During the push, we ``evaluate'' the value to push with an
218 % |\edef|, because one might want to push something which contain the
219 % previous top of the stack (see the example package provided).
220 % If the |\Stack| macro computes the real value on the top of the
221 % stack, then, the expanded definition in |\Push| will contain more
222 % or less the \emph{content} of |\Stack| and not the value.
223 %
224 % Another way would be to have a |\csname...\endcsname| pair within
225 % another one in an |\ifx| condition, which doesn't work.
226 %
227 % \begin{macrocode}
228 \newcommand\NewStack[2]{%
229 \expandafter\gdef\csname #1@count\endcsname{0}%
230 \expandafter\do@stack@macro\csname #1@count\endcsname{#1}{#2}%
231 }
232 \newcommand\do@stack@macro[3]{%
233 \expandafter\newcommand\expandafter*%
234 \csname stack@#2\endcsname{%
235 \expandafter\ifx\csname #2@\romannumeral#1\endcsname\relax
236 #3%
237 \else
238 \csname #2@\romannumeral#1\endcsname
239 \fi
240 }%
241 }
242 % \end{macrocode}
243 % \end{macro}
244 %
245 % \begin{macro}{\Stack}
246 % I'd rather remove the ``check'' code, but, well, it would suppose
247 % the end-user of the macro is a fair developper, which is not
248 % realistic.
249 %
250 % If the stack has been properly created, we call the top-stack evaluation
251 % macro.
252 %
253 % \begin{macrocode}
254 \newcommand\Stack[1]{%
255 \ifx\csname #1@count\endcsname\relax
256 \PackageError{stack}{Undefined stack #1}{You should first create the
257 stack with \NewStack}%
258 \else
259 \csname stack@#1\endcsname
260 \fi
261 }
262 % \end{macrocode}
263 % \end{macro}
264 %
265 % \begin{macro}{\Push}
266 % \begin{macro}{\Pop}
267 % The |\Push| macro is one of the most complex ones.
268 %
269 % First, we check if the stack is properly defined.
270 % \begin{macrocode}
271 \newcommand\Push[2]{%
272 \ifx\csname #1@count\endcsname\relax
273 \PackageError{stack}{Undefined stack #1}{You should first create the
274 stack with \NewStack}%
275 \else
276 % \end{macrocode}
277 %
278 % We store the new top-value in a macro, just because one might do
279 % |\Push{stack}{\Stack{stack}.ext}| in witch case the expansion of
280 % the value to push is something rather tricky.
281 %
282 % Then, we step the depth of the stack (put the depth in the scractch
283 % counter, advance this counter, have the value back in the macro).
284 %
285 % Only after that the value to be pushed is stored in the corresponding
286 % slot.
287 % \begin{macrocode}
288 \edef\stack@newtop{#2}%
289 \tmp@stack\csname #1@count\endcsname\relax
290 \global\advance\tmp@stack by 1\relax
291 \expandafter\xdef\csname #1@count\endcsname{\the\tmp@stack}%
292 \expandafter\xdef\csname #1@\romannumeral\tmp@stack\endcsname
293 {\stack@newtop}%
294 \fi
295 }
296 % \end{macrocode}
297 %
298 % The |\Pop| macro is more simple: if the stack is properly defined and
299 % the depth is more than zero, then down-step the depth.
300 % \begin{macrocode}
301 \newcommand\Pop[1]{%
302 \ifx\csname #1@count\endcsname\relax
303 \PackageError{stack}{Undefined stack #1}{You should first create the
304 stack with \NewStack}%
305 \else
306 \tmp@stack\csname #1@count\endcsname\relax
307 \ifnum\tmp@stack>0\relax
308 \advance\tmp@stack by -1\relax
309 \expandafter\xdef\csname #1@count\endcsname{\the\tmp@stack}%
310 \fi
311 \fi
312 }
313 % \end{macrocode}
314 % \end{macro}
315 % \end{macro}
316 %
317 % Now, a debug only macro.
318 % \begin{macro}{ShowTop}
319 % \begin{macrocode}
320 \newcommand\ShowTop[1]{%
321 {\edef\top{\Stack{#1}}%
322 \typeout{The top of #1: \top}}}
323 % \end{macrocode}
324 % \end{macro}
325 %
326 % That's all folks.
327 % \begin{macrocode}
328 %</package>
329 % \end{macrocode}
330 %
331 % \Finale
332 % \end{document}