Debian Codegraph @

texmf-dist/doc/latex/mdwtools/mdwtools.tex

raw
1 % \begin{meta-comment}
2 %
3 % $Id: mdwtools.tex,v 1.4 1996/11/19 20:55:55 mdw Exp $
4 %
5 % Common declarations for mdwtools.dtx files
6 %
7 % (c) 1996 Mark Wooding
8 %
9 %----- Revision history -----------------------------------------------------
10 %
11 % $Log: mdwtools.tex,v $
12 % Revision 1.4 1996/11/19 20:55:55 mdw
13 % Entered into RCS
14 %
15 %
16 % \end{meta-comment}
17 %
18 % \begin{meta-comment} <general public licence>
19 %%
20 %% mdwtools common declarations
21 %% Copyright (c) 1996 Mark Wooding
22 %%
23 %% This program is free software; you can redistribute it and/or modify
24 %% it under the terms of the GNU General Public License as published by
25 %% the Free Software Foundation; either version 2 of the License, or
26 %% (at your option) any later version.
27 %%
28 %% This program is distributed in the hope that it will be useful,
29 %% but WITHOUT ANY WARRANTY; without even the implied warranty of
30 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
31 %% GNU General Public License for more details.
32 %%
33 %% You should have received a copy of the GNU General Public License
34 %% along with this program; if not, write to the Free Software
35 %% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
36 %%
37 % \end{meta-comment}
38 %
39 % \begin{meta-comment} <file preamble>
40 %<*mdwtools>
41 \ProvidesFile{mdwtools.tex}
42 [1996/05/10 1.4 Shared definitions for mdwtools .dtx files]
43 %</mdwtools>
44 % \end{meta-comment}
45 %
46 % \CheckSum{668}
47 %% \CharacterTable
48 %% {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
49 %% 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
50 %% Digits \0\1\2\3\4\5\6\7\8\9
51 %% Exclamation \! Double quote \" Hash (number) \#
52 %% Dollar \$ Percent \% Ampersand \&
53 %% Acute accent \' Left paren \( Right paren \)
54 %% Asterisk \* Plus \+ Comma \,
55 %% Minus \- Point \. Solidus \/
56 %% Colon \: Semicolon \; Less than \<
57 %% Equals \= Greater than \> Question mark \?
58 %% Commercial at \@ Left bracket \[ Backslash \\
59 %% Right bracket \] Circumflex \^ Underscore \_
60 %% Grave accent \` Left brace \{ Vertical bar \|
61 %% Right brace \} Tilde \~}
62 %%
63 %
64 % \section{Introduction and user guide}
65 %
66 % This file is really rather strange; it gets |\input| by other package
67 % documentation files to set up most of the environmental gubbins for them.
68 % It handles almost everything, like loading a document class, finding any
69 % packages, and building and formatting the title.
70 %
71 % It also offers an opportunity for users to customise my nice documentation,
72 % by using a |mdwtools.cfg| file (not included).
73 %
74 %
75 % \subsection{Declarations}
76 %
77 % A typical documentation file contains something like
78 % \begin{listinglist} \listingsize \obeylines
79 % |\input{mdwtools}|
80 % \<declarations>
81 % |\mdwdoc|
82 % \end{listinglist}
83 % The initial |\input| reads in this file and sets up the various commands
84 % which may be needed. The final |\mdwdoc| actually starts the document,
85 % inserting a title (which is automatically generated), a table of
86 % contents etc., and reads the documentation file in (using the |\DocInput|
87 % command from the \package{doc} package.
88 %
89 % \subsubsection{Describing packages}
90 %
91 % \DescribeMacro{\describespackage}
92 % \DescribeMacro{\describesclass}
93 % \DescribeMacro{\describesfile}
94 % \DescribeMacro{\describesfile*}
95 % The most important declarations are those which declare what the
96 % documentation describes. Saying \syntax{"\\describespackage{<package>}"}
97 % loads the \<package> (if necessary) and adds it to the auto-generated
98 % title, along with a footnote containing version information. Similarly,
99 % |\describesclass| adds a document class name to the title (without loading
100 % it -- the document itself must do this, with the |\documentclass| command).
101 % For files which aren't packages or classes, use the |\describesfile| or
102 % |\describesfile*| command (the $*$-version won't |\input| the file, which
103 % is handy for files like |mdwtools.tex|, which are already input).
104 %
105 % \DescribeMacro{\author}
106 % \DescribeMacro{\date}
107 % \DescribeMacro{\title}
108 % The |\author|, |\date| and |\title| declarations work slightly differently
109 % to normal -- they ensure that only the \emph{first} declaration has an
110 % effect. (Don't you play with |\author|, please, unless you're using this
111 % program to document your own packages.) Using |\title| suppresses the
112 % automatic title generation.
113 %
114 % \DescribeMacro{\docdate}
115 % The default date is worked out from the version string of the package or
116 % document class whose name is the same as that of the documentation file.
117 % You can choose a different `main' file by saying
118 % \syntax{"\\docdate{"<file>"}"}.
119 %
120 % \subsubsection{Contents handling}
121 %
122 % \DescribeMacro{\addcontents}
123 % A documentation file always has a table of contents. Other
124 % contents-like lists can be added by saying
125 % \syntax{"\\addcontents{"<extension>"}{"<command>"}"}. The \<extension>
126 % is the file extension of the contents file (e.g., \lit{lot} for the
127 % list of tables); the \<command> is the command to actually typeset the
128 % contents file (e.g., |\listoftables|).
129 %
130 % \subsubsection{Other declarations}
131 %
132 % \DescribeMacro{\implementation}
133 % The \package{doc} package wants you to say
134 % \syntax{"\\StopEventually{"<stuff>"}"}' before describing the package
135 % implementation. Using |mdwtools.tex|, you just say |\implementation|, and
136 % everything works. It will automatically read in the licence text (from
137 % |gpl.tex|, and wraps some other things up.
138 %
139 %
140 % \subsection{Other commands}
141 %
142 % The |mdwtools.tex| file includes the \package{syntax} and \package{sverb}
143 % packages so that they can be used in documentation files. It also defines
144 % some trivial commands of its own.
145 %
146 % \DescribeMacro{\<}
147 % Saying \syntax{"\\<"<text>">" is the same as "\\synt{"<text>"}"}; this
148 % is a simple abbreviation.
149 %
150 % \DescribeMacro{\smallf}
151 % Saying \syntax{"\\smallf" <number>"/"<number>} typesets a little fraction,
152 % like this: \smallf 3/4. It's useful when you want to say that the default
153 % value of a length is 2 \smallf 1/2\,pt, or something like that.
154 %
155 %
156 % \subsection{Customisation}
157 %
158 % You can customise the way that the package documentation looks by writing
159 % a file called |mdwtools.cfg|. You can redefine various commands (before
160 % they're defined here, even; |mdwtools.tex| checks most of the commands that
161 % it defines to make sure they haven't been defined already.
162 %
163 % \DescribeMacro{\indexing}
164 % If you don't want the prompt about whether to generate index files, you
165 % can define the |\indexing| command to either \lit{y} or \lit{n}. I'd
166 % recommend that you use |\providecommand| for this, to allow further
167 % customisation from the command line.
168 %
169 % \DescribeMacro{\mdwdateformat}
170 % If you don't like my date format (maybe you're American or something),
171 % you can redefine the |\mdwdateformat| command. It takes three arguments:
172 % the year, month and date, as numbers; it should expand to something which
173 % typesets the date nicely. The default format gives something like
174 % `10 May 1996'. You can produce something rather more exotic, like
175 % `10\textsuperscript{th} May \textsc{\romannumeral 1996}' by saying
176 %\begin{listing}
177 %\newcommand{\mdwdateformat}[3]{%
178 % \number#3\textsuperscript{\numsuffix{#3}}\ %
179 % \monthname{#2}\ %
180 % \textsc{\romannumeral #1}%
181 %}
182 %\end{listing}
183 % \DescribeMacro{\monthname}
184 % \DescribeMacro{\numsuffix}
185 % Saying \syntax{"\\monthname{"<number>"}"} expands to the name of the
186 % numbered month (which can be useful when doing date formats). Saying
187 % \syntax{"\\numsuffix{"<number>"}"} will expand to the appropriate suffix
188 % (`th' or `rd' or whatever) for the \<number>. You'll have to superscript
189 % it yourself, if this is what you want to do. Putting the year number
190 % in roman numerals is just pretentious |;-)|.
191 %
192 % \DescribeMacro{\mdwhook}
193 % After all the declarations in |mdwtools.tex|, the command |\mdwhook| is
194 % executed, if it exists. This can be set up by the configuration file
195 % to do whatever you want.
196 %
197 % There are lots of other things you can play with; you should look at the
198 % implementation section to see what's possible.
199 %
200 % \implementation
201 %
202 % \section{Implementation}
203 %
204 % \begin{macrocode}
205 %<*mdwtools>
206 % \end{macrocode}
207 %
208 % The first thing is that I'm not a \LaTeX\ package or anything official
209 % like that, so I must enable `|@|' as a letter by hand.
210 %
211 % \begin{macrocode}
212 \makeatletter
213 % \end{macrocode}
214 %
215 % Now input the user's configuration file, if it exists. This is fairly
216 % simple stuff.
217 %
218 % \begin{macrocode}
219 \@input{mdwtools.cfg}
220 % \end{macrocode}
221 %
222 % Well, that's the easy bit done.
223 %
224 %
225 % \subsection{Initialisation}
226 %
227 % Obviously the first thing to do is to obtain a document class. Obviously,
228 % it would be silly to do this if a document class has already been loaded,
229 % either by the package documentation or by the configuration file.
230 %
231 % The only way I can think of for finding out if a document class is already
232 % loaded is by seeing if the |\documentclass| command has been redefined
233 % to raise an error. This isn't too hard, really.
234 %
235 % \begin{macrocode}
236 \ifx\documentclass\@twoclasseserror\else
237 \documentclass[a4paper]{ltxdoc}
238 \ifx\doneclasses\mdw@undefined\else\doneclasses\fi
239 \fi
240 % \end{macrocode}
241 %
242 % As part of my standard environment, I'll load some of my more useful
243 % packages. If they're already loaded (possibly with different options),
244 % I'll not try to load them again.
245 %
246 % \begin{macrocode}
247 \@ifpackageloaded{doc}{}{\usepackage{doc}}
248 \@ifpackageloaded{syntax}{}{\usepackage[rounded]{syntax}}
249 \@ifpackageloaded{sverb}{}{\usepackage{sverb}}
250 % \end{macrocode}
251 %
252 %
253 % \subsection{Some macros for interaction}
254 %
255 % I like the \LaTeX\ star-boxes, although it's a pain having to cope with
256 % \TeX's space-handling rules. I'll define a new typing-out macro which
257 % makes spaces more significant, and has a $*$-version which doesn't put
258 % a newline on the end, and interacts prettily with |\read|.
259 %
260 % First of all, I need to make spaces active, so I can define things about
261 % active spaces.
262 %
263 % \begin{macrocode}
264 \begingroup\obeyspaces
265 % \end{macrocode}
266 %
267 % Now to define the main macro. This is easy stuff. Spaces must be
268 % carefully rationed here, though.
269 %
270 % I'll start a group, make spaces active, and make spaces expand to ordinary
271 % space-like spaces. Then I'll look for a star, and pass either |\message|
272 % (which doesn't start a newline, and interacts with |\read| well) or
273 % |\immediate\write 16| which does a normal write well.
274 %
275 % \begin{macrocode}
276 \gdef\mdwtype{%
277 \begingroup\catcode`\ \active\let \space%
278 \@ifstar{\mdwtype@i{\message}}{\mdwtype@i{\immediate\write\sixt@@n}}%
279 }
280 \endgroup
281 % \end{macrocode}
282 %
283 % Now for the easy bit. I have the thing to do, and the thing to do it to,
284 % so do that and end the group.
285 %
286 % \begin{macrocode}
287 \def\mdwtype@i#1#2{#1{#2}\endgroup}
288 % \end{macrocode}
289 %
290 %
291 % \subsection{Decide on indexing}
292 %
293 % A configuration file can decide on indexing by defining the |\indexing|
294 % macro to either \lit{y} or \lit{n}. If it's not set, then I'll prompt
295 % the user.
296 %
297 % First of all, I want a switch to say whether I'm indexing.
298 %
299 % \begin{macrocode}
300 \newif\ifcreateindex
301 % \end{macrocode}
302 %
303 % Right: now I need to decide how to make progress. If the macro's not set,
304 % then I want to set it, and start a row of stars.
305 %
306 % \begin{macrocode}
307 \ifx\indexing\@@undefined
308 \mdwtype{*****************************}
309 \def\indexing{?}
310 \fi
311 % \end{macrocode}
312 %
313 % Now enter a loop, asking the user whether to do indexing, until I get
314 % a sensible answer.
315 %
316 % \begin{macrocode}
317 \loop
318 \@tempswafalse
319 \if y\indexing\@tempswatrue\createindextrue\fi
320 \if Y\indexing\@tempswatrue\createindextrue\fi
321 \if n\indexing\@tempswatrue\createindexfalse\fi
322 \if N\indexing\@tempswatrue\createindexfalse\fi
323 \if@tempswa\else
324 \mdwtype*{* Create index files? (y/n) *}
325 \read\sixt@@n to\indexing%
326 \repeat
327 % \end{macrocode}
328 %
329 % Now, based on the results of that, display a message about the indexing.
330 %
331 % \begin{macrocode}
332 \mdwtype{*****************************}
333 \ifcreateindex
334 \mdwtype{* Creating index files *}
335 \mdwtype{* This may take some time *}
336 \else
337 \mdwtype{* Not creating index files *}
338 \fi
339 \mdwtype{*****************************}
340 % \end{macrocode}
341 %
342 % Now I can play with the indexing commands of the \package{doc} package
343 % to do whatever it is that the user wants.
344 %
345 % \begin{macrocode}
346 \ifcreateindex
347 \CodelineIndex
348 \EnableCrossrefs
349 \else
350 \CodelineNumbered
351 \DisableCrossrefs
352 \fi
353 % \end{macrocode}
354 %
355 % And register lots of plain \TeX\ things which shouldn't be indexed.
356 % This contains lots of |\if|\dots\ things which don't fit nicely in
357 % conditionals, which is a shame. Still, it doesn't matter that much,
358 % really.
359 %
360 % \begin{macrocode}
361 \DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
362 \DoNotIndex{\if,\ifnum,\ifdim,\ifcat,\ifmmode,\ifvmode,\ifhmode,%
363 \iftrue,\iffalse,\ifvoid,\ifx,\ifeof,\ifcase,\else,\or,\fi}
364 \DoNotIndex{\box,\copy,\setbox,\unvbox,\unhbox,\hbox,%
365 \vbox,\vtop,\vcenter}
366 \DoNotIndex{\@empty,\immediate,\write}
367 \DoNotIndex{\egroup,\bgroup,\expandafter,\begingroup,\endgroup}
368 \DoNotIndex{\divide,\advance,\multiply,\count,\dimen}
369 \DoNotIndex{\relax,\space,\string}
370 \DoNotIndex{\csname,\endcsname,\@spaces,\openin,\openout,%
371 \closein,\closeout}
372 \DoNotIndex{\catcode,\endinput}
373 \DoNotIndex{\jobname,\message,\read,\the,\m@ne,\noexpand}
374 \DoNotIndex{\hsize,\vsize,\hskip,\vskip,\kern,\hfil,\hfill,\hss}
375 \DoNotIndex{\m@ne,\z@,\z@skip,\@ne,\tw@,\p@}
376 \DoNotIndex{\dp,\wd,\ht,\vss,\unskip}
377 % \end{macrocode}
378 %
379 % Last bit of indexing stuff, for now: I'll typeset the index in two columns
380 % (the default is three, which makes them too narrow for my tastes).
381 %
382 % \begin{macrocode}
383 \setcounter{IndexColumns}{2}
384 % \end{macrocode}
385 %
386 %
387 % \subsection{Selectively defining things}
388 %
389 % I don't want to tread on anyone's toes if they redefine any of these
390 % commands and things in a configuration file. The following definitions
391 % are fairly evil, but should do the job OK.
392 %
393 % \begin{macro}{\@gobbledef}
394 %
395 % This macro eats the following |\def|inition, leaving not a trace behind.
396 %
397 % \begin{macrocode}
398 \def\@gobbledef#1#{\@gobble}
399 % \end{macrocode}
400 %
401 % \end{macro}
402 %
403 % \begin{macro}{\tdef}
404 % \begin{macro}{\tlet}
405 %
406 % The |\tdef| command is a sort of `tentative' definition -- it's like
407 % |\def| if the control sequence named doesn't already have a definition.
408 % |\tlet| does the same thing with |\let|.
409 %
410 % \begin{macrocode}
411 \def\tdef#1{
412 \ifx#1\@@undefined%
413 \expandafter\def\expandafter#1%
414 \else%
415 \expandafter\@gobbledef%
416 \fi%
417 }
418 \def\tlet#1#2{\ifx#1\@@undefined\let#1=#2\fi}
419 % \end{macrocode}
420 %
421 % \end{macro}
422 % \end{macro}
423 %
424 %
425 % \subsection{General markup things}
426 %
427 % Now for some really simple things. I'll define how to typeset package
428 % names and environment names (both in the sans serif font, for now).
429 %
430 % \begin{macrocode}
431 \tlet\package\textsf
432 \tlet\env\textsf
433 % \end{macrocode}
434 %
435 % I'll define the |\<|\dots|>| shortcut for syntax items suggested in the
436 % \package{syntax} package.
437 %
438 % \begin{macrocode}
439 \tdef\<#1>{\synt{#1}}
440 % \end{macrocode}
441 %
442 % And because it's used in a few places (mainly for typesetting lengths),
443 % here's a command for typesetting fractions in text.
444 %
445 % \begin{macrocode}
446 \tdef\smallf#1/#2{\ensuremath{^{#1}\!/\!_{#2}}}
447 % \end{macrocode}
448 %
449 %
450 % \subsection{A table environment}
451 %
452 % \begin{environment}{tab}
453 %
454 % Most of the packages don't use the (obviously perfect) \package{mdwtab}
455 % package, because it's big, and takes a while to load. Here's an
456 % environment for typesetting centred tables. The first (optional) argument
457 % is some declarations to perform. The mandatory argument is the table
458 % preamble (obviously).
459 %
460 % \begin{macrocode}
461 \@ifundefined{tab}{%
462 \newenvironment{tab}[2][\relax]{%
463 \par\vskip2ex%
464 \centering%
465 #1%
466 \begin{tabular}{#2}%
467 }{%
468 \end{tabular}%
469 \par\vskip2ex%
470 }
471 }{}
472 % \end{macrocode}
473 %
474 % \end{environment}
475 %
476 %
477 % \subsection{Commenting out of stuff}
478 %
479 % \begin{environment}{meta-comment}
480 %
481 % Using |\iffalse|\dots|\fi| isn't much fun. I'll define a gobbling
482 % environment using the \package{sverb} stuff.
483 %
484 % \begin{macrocode}
485 \ignoreenv{meta-comment}
486 % \end{macrocode}
487 %
488 % \end{environment}
489 %
490 %
491 % \subsection{Float handling}
492 %
493 % This gubbins will try to avoid float pages as much as possible, and (with
494 % any luck) encourage floats to be put on the same pages as text.
495 %
496 % \begin{macrocode}
497 \def\textfraction{0.1}
498 \def\topfraction{0.9}
499 \def\bottomfraction{0.9}
500 \def\floatpagefraction{0.7}
501 % \end{macrocode}
502 %
503 % Now redefine the default float-placement parameters to allow `here' floats.
504 %
505 % \begin{macrocode}
506 \def\fps@figure{htbp}
507 \def\fps@table{htbp}
508 % \end{macrocode}
509 %
510 %
511 % \subsection{Other bits of parameter tweaking}
512 %
513 % Make \env{grammar} environments look pretty, by indenting the left hand
514 % sides by a large amount.
515 %
516 % \begin{macrocode}
517 \grammarindent1in
518 % \end{macrocode}
519 %
520 % I don't like being told by \TeX\ that my paragraphs are hard to linebreak:
521 % I know this already. This lot should shut \TeX\ up about most problems.
522 %
523 % \begin{macrocode}
524 \sloppy
525 \hbadness\@M
526 \hfuzz10\p@
527 % \end{macrocode}
528 %
529 % Also make \TeX\ shut up in the index. The \package{multicol} package
530 % irritatingly plays with |\hbadness|. This is the best hook I could find
531 % for playing with this setting.
532 %
533 % \begin{macrocode}
534 \expandafter\def\expandafter\IndexParms\expandafter{%
535 \IndexParms%
536 \hbadness\@M%
537 }
538 % \end{macrocode}
539 %
540 % The other thing I really don't like is `Marginpar moved' warnings. This
541 % will get rid of them, and lots of other \LaTeX\ warnings at the same time.
542 %
543 % \begin{macrocode}
544 \let\@latex@warning@no@line\@gobble
545 % \end{macrocode}
546 %
547 % Put some extra space between table rows, please.
548 %
549 % \begin{macrocode}
550 \def\arraystretch{1.2}
551 % \end{macrocode}
552 %
553 % Most of the code is at guard level one, so typeset that in upright text.
554 %
555 % \begin{macrocode}
556 \setcounter{StandardModuleDepth}{1}
557 % \end{macrocode}
558 %
559 %
560 % \subsection{Contents handling}
561 %
562 % I use at least one contents file (the main table of contents) although
563 % I may want more. I'll keep a list of contents files which I need to
564 % handle.
565 %
566 % There are two things I need to do to contents files here:
567 % \begin{itemize}
568 % \item I must typeset the table of contents at the beginning of the
569 % document; and
570 % \item I want to typeset tables of contents in two columns (using the
571 % \package{multicol} package).
572 % \end{itemize}
573 %
574 % The list consists of items of the form
575 % \syntax{"\\do{"<extension>"}{"<command>"}"}, where \<extension> is the
576 % file extension of the contents file, and \<command> is the command to
577 % typeset it.
578 %
579 % \begin{macro}{\docontents}
580 %
581 % This is where I keep the list of contents files. I'll initialise it to
582 % just do the standard contents table.
583 %
584 % \begin{macrocode}
585 \def\docontents{\do{toc}{\tableofcontents}}
586 % \end{macrocode}
587 %
588 % \end{macro}
589 %
590 % \begin{macro}{\addcontents}
591 %
592 % By saying \syntax{"\\addcontents{"<extension>"}{"<command>"}"}, a document
593 % can register a new table of contents which gets given the two-column
594 % treatment properly. This is really easy to implement.
595 %
596 % \begin{macrocode}
597 \def\addcontents#1#2{%
598 \toks@\expandafter{\docontents\do{#1}{#2}}%
599 \edef\docontents{\the\toks@}%
600 }
601 % \end{macrocode}
602 %
603 % \end{macro}
604 %
605 %
606 % \subsection{Finishing it all off}
607 %
608 % \begin{macro}{\finalstuff}
609 %
610 % The |\finalstuff| macro is a hook for doing things at the end of the
611 % document. Currently, it inputs the licence agreement as an appendix.
612 %
613 % \begin{macrocode}
614 \tdef\finalstuff{\appendix\part*{Appendix}\input{gpl}}
615 % \end{macrocode}
616 %
617 % \end{macro}
618 %
619 % \begin{macro}{\implementation}
620 %
621 % The |\implementation| macro starts typesetting the implementation of
622 % the package(s). If we're not doing the implementation, it just does
623 % this lot and ends the input file.
624 %
625 % I define a macro with arguments inside the |\StopEventually|, which causes
626 % problems, since the code gets put through an extra level of |\def|fing
627 % depending on whether the implementation stuff gets typeset or not. I'll
628 % store the code I want to do in a separate macro.
629 %
630 % \begin{macrocode}
631 \def\implementation{\StopEventually{\attheend}}
632 % \end{macrocode}
633 %
634 % Now for the actual activity. First, I'll do the |\finalstuff|. Then, if
635 % \package{doc}'s managed to find the \package{multicol} package, I'll add
636 % the end of the environment to the end of each contents file in the list.
637 % Finally, I'll read the index in from its formatted |.ind| file.
638 %
639 % \begin{macrocode}
640 \tdef\attheend{%
641 \finalstuff%
642 \ifhave@multicol%
643 \def\do##1##2{\addtocontents{##1}{\protect\end{multicols}}}%
644 \docontents%
645 \fi%
646 \PrintIndex%
647 }
648 % \end{macrocode}
649 %
650 % \end{macro}
651 %
652 %
653 % \subsection{File version information}
654 %
655 % \begin{macro}{\mdwpkginfo}
656 %
657 % For setting up the automatic titles, I'll need to be able to work out
658 % file versions and things. This macro will, given a file name, extract
659 % from \LaTeX\ the version information and format it into a sensible string.
660 %
661 % First of all, I'll put the original string (direct from the
662 % |\Provides|\dots\ command). Then I'll pass it to another macro which can
663 % parse up the string into its various bits, along with the original
664 % filename.
665 %
666 % \begin{macrocode}
667 \def\mdwpkginfo#1{%
668 \edef\@tempa{\csname ver@#1\endcsname}%
669 \expandafter\mdwpkginfo@i\@tempa\@@#1\@@%
670 }
671 % \end{macrocode}
672 %
673 % Now for the real business. I'll store the string I build in macros called
674 % \syntax{"\\"<filename>"date", "\\"<filename>"version" and
675 % "\\"<filename>"info"}, which store the file's date, version and
676 % `information string' respectively. (Note that the file extension isn't
677 % included in the name.)
678 %
679 % This is mainly just tedious playing with |\expandafter|. The date format
680 % is defined by a separate macro, which can be modified from the
681 % configuration file.
682 %
683 % \begin{macrocode}
684 \def\mdwpkginfo@i#1/#2/#3 #4 #5\@@#6.#7\@@{%
685 \expandafter\def\csname #6date\endcsname%
686 {\protect\mdwdateformat{#1}{#2}{#3}}%
687 \expandafter\def\csname #6version\endcsname{#4}%
688 \expandafter\def\csname #6info\endcsname{#5}%
689 }
690 % \end{macrocode}
691 %
692 % \end{macro}
693 %
694 % \begin{macro}{\mdwdateformat}
695 %
696 % Given three arguments, a year, a month and a date (all numeric), build a
697 % pretty date string. This is fairly simple really.
698 %
699 % \begin{macrocode}
700 \tdef\mdwdateformat#1#2#3{\number#3\ \monthname{#2}\ \number#1}
701 \def\monthname#1{%
702 \ifcase#1\or%
703 January\or February\or March\or April\or May\or June\or%
704 July\or August\or September\or October\or November\or December%
705 \fi%
706 }
707 \def\numsuffix#1{%
708 \ifnum#1=1 st\else%
709 \ifnum#1=2 nd\else%
710 \ifnum#1=3 rd\else%
711 \ifnum#1=21 st\else%
712 \ifnum#1=22 nd\else%
713 \ifnum#1=23 rd\else%
714 \ifnum#1=31 st\else%
715 th%
716 \fi\fi\fi\fi\fi\fi\fi%
717 }
718 % \end{macrocode}
719 %
720 % \end{macro}
721 %
722 % \begin{macro}{\mdwfileinfo}
723 %
724 % Saying \syntax{"\\mdwfileinfo{"<file-name>"}{"<info>"}"} extracts the
725 % wanted item of \<info> from the version information for file \<file-name>.
726 %
727 % \begin{macrocode}
728 \def\mdwfileinfo#1#2{\mdwfileinfo@i{#2}#1.\@@}
729 \def\mdwfileinfo@i#1#2.#3\@@{\csname#2#1\endcsname}
730 % \end{macrocode}
731 %
732 % \end{macro}
733 %
734 %
735 % \subsection{List handling}
736 %
737 % There are several other lists I need to build. These macros will do
738 % the necessary stuff.
739 %
740 % \begin{macro}{\mdw@ifitem}
741 %
742 % The macro \syntax{"\\mdw@ifitem"<item>"\\in"<list>"{"<true-text>"}"^^A
743 % "{"<false-text>"}"} does \<true-text> if the \<item> matches any item in
744 % the \<list>; otherwise it does \<false-text>.
745 %
746 % \begin{macrocode}
747 \def\mdw@ifitem#1\in#2{%
748 \@tempswafalse%
749 \def\@tempa{#1}%
750 \def\do##1{\def\@tempb{##1}\ifx\@tempa\@tempb\@tempswatrue\fi}%
751 #2%
752 \if@tempswa\expandafter\@firstoftwo\else\expandafter\@secondoftwo\fi%
753 }
754 % \end{macrocode}
755 %
756 % \end{macro}
757 %
758 % \begin{macro}{\mdw@append}
759 %
760 % Saying \syntax{"\\mdw@append"<item>"\\to"<list>} adds the given \<item>
761 % to the end of the given \<list>.
762 %
763 % \begin{macrocode}
764 \def\mdw@append#1\to#2{%
765 \toks@{\do{#1}}%
766 \toks\tw@\expandafter{#2}%
767 \edef#2{\the\toks\tw@\the\toks@}%
768 }
769 % \end{macrocode}
770 %
771 % \end{macro}
772 %
773 % \begin{macro}{\mdw@prepend}
774 %
775 % Saying \syntax{"\\mdw@prepend"<item>"\\to"<list>} adds the \<item> to the
776 % beginning of the \<list>.
777 %
778 % \begin{macrocode}
779 \def\mdw@prepend#1\to#2{%
780 \toks@{\do{#1}}%
781 \toks\tw@\expandafter{#2}%
782 \edef#2{\the\toks@\the\toks\tw@}%
783 }
784 % \end{macrocode}
785 %
786 % \end{macro}
787 %
788 % \begin{macro}{\mdw@add}
789 %
790 % Finally, saying \syntax{"\\mdw@add"<item>"\\to"<list>} adds the \<item>
791 % to the list only if it isn't there already.
792 %
793 % \begin{macrocode}
794 \def\mdw@add#1\to#2{\mdw@ifitem#1\in#2{}{\mdw@append#1\to#2}}
795 % \end{macrocode}
796 %
797 % \end{macro}
798 %
799 %
800 % \subsection{Described file handling}
801 %
802 % I'l maintain lists of packages, document classes, and other files
803 % described by the current documentation file.
804 %
805 % First of all, I'll declare the various list macros.
806 %
807 % \begin{macrocode}
808 \def\dopackages{}
809 \def\doclasses{}
810 \def\dootherfiles{}
811 % \end{macrocode}
812 %
813 % \begin{macro}{\describespackage}
814 %
815 % A document file can declare that it describes a package by saying
816 % \syntax{"\\describespackage{"<package-name>"}"}. I add the package to
817 % my list, read the package into memory (so that the documentation can
818 % offer demonstrations of it) and read the version information.
819 %
820 % \begin{macrocode}
821 \def\describespackage#1{%
822 \mdw@ifitem#1\in\dopackages{}{%
823 \mdw@append#1\to\dopackages%
824 \usepackage{#1}%
825 \mdwpkginfo{#1.sty}%
826 }%
827 }
828 % \end{macrocode}
829 %
830 % \end{macro}
831 %
832 % \begin{macro}{\describesclass}
833 %
834 % By saying \syntax{"\\describesclass{"<class-name>"}"}, a document file
835 % can declare that it describes a document class. I'll assume that the
836 % document class is already loaded, because it's much too late to load
837 % it now.
838 %
839 % \begin{macrocode}
840 \def\describesclass#1{\mdw@add#1\to\doclasses\mdwpkginfo{#1.cls}}
841 % \end{macrocode}
842 %
843 % \end{macro}
844 %
845 % \begin{macro}{\describesfile}
846 %
847 % Finally, other `random' files, which don't have the status of real \LaTeX\
848 % packages or document classes, can be described by saying \syntax{^^A
849 % "\\describesfile{"<file-name>"}" or "\\describesfile*{"<file-name>"}"}.
850 % The difference is that the starred version will not |\input| the file.
851 %
852 % \begin{macrocode}
853 \def\describesfile{%
854 \@ifstar{\describesfile@i\@gobble}{\describesfile@i\input}%
855 }
856 \def\describesfile@i#1#2{%
857 \mdw@ifitem#2\in\dootherfiles{}{%
858 \mdw@add#2\to\dootherfiles%
859 #1{#2}%
860 \mdwpkginfo{#2}%
861 }%
862 }
863 % \end{macrocode}
864 %
865 % \end{macro}
866 %
867 %
868 % \subsection{Author and title handling}
869 %
870 % I'll redefine the |\author| and |\title| commands so that I get told
871 % whether I need to do it myself.
872 %
873 % \begin{macro}{\author}
874 %
875 % This is easy: I'll save the old meaning, and then redefine |\author| to
876 % do the old thing and redefine itself to then do nothing.
877 %
878 % \begin{macrocode}
879 \let\mdw@author\author
880 \def\author{\let\author\@gobble\mdw@author}
881 % \end{macrocode}
882 %
883 % \end{macro}
884 %
885 % \begin{macro}{\title}
886 %
887 % And oddly enough, I'll do exactly the same thing for the title, except
888 % that I'll also disable the |\mdw@buildtitle| command, which constructs
889 % the title automatically.
890 %
891 % \begin{macrocode}
892 \let\mdw@title\title
893 \def\title{\let\title\@gobble\let\mdw@buildtitle\relax\mdw@title}
894 % \end{macrocode}
895 %
896 % \end{macro}
897 %
898 % \begin{macro}{\date}
899 %
900 % This works in a very similar sort of way.
901 %
902 % \begin{macrocode}
903 \def\date#1{\let\date\@gobble\def\today{#1}}
904 % \end{macrocode}
905 %
906 % \end{macro}
907 %
908 % \begin{macro}{\datefrom}
909 %
910 % Saying \syntax{"\\datefrom{"<file-name>"}"} sets the document date from
911 % the given filename.
912 %
913 % \begin{macrocode}
914 \def\datefrom#1{%
915 \protected@edef\@tempa{\noexpand\date{\csname #1date\endcsname}}%
916 \@tempa%
917 }
918 % \end{macrocode}
919 %
920 % \end{macro}
921 %
922 % \begin{macro}{\docfile}
923 %
924 % Saying \syntax{"\\docfile{"<file-name>"}"} sets up the file name from which
925 % documentation will be read.
926 %
927 % \begin{macrocode}
928 \def\docfile#1{%
929 \def\@tempa##1.##2\@@{\def\@basefile{##1.##2}\def\@basename{##1}}%
930 \edef\@tempb{\noexpand\@tempa#1\noexpand\@@}%
931 \@tempb%
932 }
933 % \end{macrocode}
934 %
935 % I'll set up a default value as well.
936 %
937 % \begin{macrocode}
938 \docfile{\jobname.dtx}
939 % \end{macrocode}
940 %
941 % \end{macro}
942 %
943 %
944 % \subsection{Building title strings}
945 %
946 % This is rather tricky. For each list, I need to build a legible looking
947 % string.
948 %
949 % \begin{macro}{\mdw@addtotitle}
950 %
951 % By saying
952 %\syntax{"\\mdw@addtotitle{"<list>"}{"<command>"}{"<singular>"}{"<plural>"}"}
953 % I can add the contents of a list to the current title string in the
954 % |\mdw@title| macro.
955 %
956 % \begin{macrocode}
957 \tdef\mdw@addtotitle#1#2#3#4{%
958 % \end{macrocode}
959 %
960 % Now to get to work. I need to keep one `lookahead' list item, and a count
961 % of the number of items read so far. I'll keep the lookahead item in
962 % |\@nextitem| and the counter in |\count@|.
963 %
964 % \begin{macrocode}
965 \count@\z@%
966 % \end{macrocode}
967 %
968 % Now I'll define what to do for each list item. The |\protect| command is
969 % already set up appropriately for playing with |\edef| commands.
970 %
971 % \begin{macrocode}
972 \def\do##1{%
973 % \end{macrocode}
974 %
975 % The first job is to add the previous item to the title string. If this
976 % is the first item, though, I'll just add the appropriate \lit{The } or
977 % \lit{ and the } string to the title (this is stored in the |\@prefix|
978 % macro).
979 %
980 % \begin{macrocode}
981 \edef\mdw@title{%
982 \mdw@title%
983 \ifcase\count@\@prefix%
984 \or\@nextitem%
985 \else, \@nextitem%
986 \fi%
987 }%
988 % \end{macrocode}
989 %
990 % That was rather easy. Now I'll set up the |\@nextitem| macro for the
991 % next time around the loop.
992 %
993 % \begin{macrocode}
994 \edef\@nextitem{%
995 \protect#2{##1}%
996 \protect\footnote{%
997 The \protect#2{##1} #3 is currently at version %
998 \mdwfileinfo{##1}{version}, dated \mdwfileinfo{##1}{date}.%
999 }\space%
1000 }%
1001 % \end{macrocode}
1002 %
1003 % Finally, I need to increment the counter.
1004 %
1005 % \begin{macrocode}
1006 \advance\count@\@ne%
1007 }%
1008 % \end{macrocode}
1009 %
1010 % Now execute the list.
1011 %
1012 % \begin{macrocode}
1013 #1%
1014 % \end{macrocode}
1015 %
1016 % I still have one item left over, unless the list was empty. I'll add
1017 % that now.
1018 %
1019 % \begin{macrocode}
1020 \edef\mdw@title{%
1021 \mdw@title%
1022 \ifcase\count@%
1023 \or\@nextitem\space#3%
1024 \or\ and \@nextitem\space#4%
1025 \fi%
1026 }%
1027 % \end{macrocode}
1028 %
1029 % Finally, if $|\count@| \ne 0$, I must set |\@prefix| to \lit{ and the }.
1030 %
1031 % \begin{macrocode}
1032 \ifnum\count@>\z@\def\@prefix{ and the }\fi%
1033 }
1034 % \end{macrocode}
1035 %
1036 % \end{macro}
1037 %
1038 % \begin{macro}{\mdw@buildtitle}
1039 %
1040 % This macro will actually do the job of building the title string.
1041 %
1042 % \begin{macrocode}
1043 \tdef\mdw@buildtitle{%
1044 % \end{macrocode}
1045 %
1046 % First of all, I'll open a group to avoid polluting the namespace with
1047 % my gubbins (although the code is now much tidier than it has been in
1048 % earlier releases).
1049 %
1050 % \begin{macrocode}
1051 \begingroup%
1052 % \end{macrocode}
1053 %
1054 % The title building stuff makes extensive use of |\edef|. I'll set
1055 % |\protect| appropriately. (For those not in the know,
1056 % |\@unexpandable@protect| expands to `|\noexpand\protect\noexpand|',
1057 % which prevents expansion of the following macro, and inserts a |\protect|
1058 % in front of it ready for the next |\edef|.)
1059 %
1060 % \begin{macrocode}
1061 \let\@@protect\protect\let\protect\@unexpandable@protect%
1062 % \end{macrocode}
1063 %
1064 % Set up some simple macros ready for the main code.
1065 %
1066 % \begin{macrocode}
1067 \def\mdw@title{}%
1068 \def\@prefix{The }%
1069 % \end{macrocode}
1070 %
1071 % Now build the title. This is fun.
1072 %
1073 % \begin{macrocode}
1074 \mdw@addtotitle\dopackages\package{package}{packages}%
1075 \mdw@addtotitle\doclasses\package{document class}{document classes}%
1076 \mdw@addtotitle\dootherfiles\texttt{file}{files}%
1077 % \end{macrocode}
1078 %
1079 % Now I want to end the group and set the title from my string. The
1080 % following hacking will do this.
1081 %
1082 % \begin{macrocode}
1083 \edef\next{\endgroup\noexpand\title{\mdw@title}}%
1084 \next%
1085 }
1086 % \end{macrocode}
1087 %
1088 % \end{macro}
1089 %
1090 %
1091 % \subsection{Starting the main document}
1092 %
1093 % \begin{macro}{\mdwdoc}
1094 %
1095 % Once the document preamble has done all of its stuff, it calls the
1096 % |\mdwdoc| command, which takes over and really starts the documentation
1097 % going.
1098 %
1099 % \begin{macrocode}
1100 \def\mdwdoc{%
1101 % \end{macrocode}
1102 %
1103 % First, I'll construct the title string.
1104 %
1105 % \begin{macrocode}
1106 \mdw@buildtitle%
1107 \author{Mark Wooding}%
1108 % \end{macrocode}
1109 %
1110 % Set up the date string based on the date of the package which shares
1111 % the same name as the current file.
1112 %
1113 % \begin{macrocode}
1114 \datefrom\@basename%
1115 % \end{macrocode}
1116 %
1117 % Set up verbatim characters after all the packages have started.
1118 %
1119 % \begin{macrocode}
1120 \shortverb\|%
1121 \shortverb\"%
1122 % \end{macrocode}
1123 %
1124 % Start the document, and put the title in.
1125 %
1126 % \begin{macrocode}
1127 \begin{document}
1128 \maketitle%
1129 % \end{macrocode}
1130 %
1131 % This is nasty. It makes maths displays work properly in demo environments.
1132 % \emph{The \LaTeX\ Companion} exhibits the bug which this hack fixes. So
1133 % ner.
1134 %
1135 % \begin{macrocode}
1136 \abovedisplayskip\z@%
1137 % \end{macrocode}
1138 %
1139 % Now start the contents tables. After starting each one, I'll make it
1140 % be multicolumnar.
1141 %
1142 % \begin{macrocode}
1143 \def\do##1##2{%
1144 ##2%
1145 \ifhave@multicol\addtocontents{##1}{%
1146 \protect\begin{multicols}{2}%
1147 \hbadness\@M%
1148 }\fi%
1149 }%
1150 \docontents%
1151 % \end{macrocode}
1152 %
1153 % Input the main file now.
1154 %
1155 % \begin{macrocode}
1156 \DocInput{\@basefile}%
1157 % \end{macrocode}
1158 %
1159 % That's it. I'm done.
1160 %
1161 % \begin{macrocode}
1162 \end{document}
1163 }
1164 % \end{macrocode}
1165 %
1166 % \end{macro}
1167 %
1168 %
1169 % \subsection{And finally\dots}
1170 %
1171 % Right at the end I'll put a hook for the configuration file.
1172 %
1173 % \begin{macrocode}
1174 \ifx\mdwhook\@@undefined\else\expandafter\mdwhook\fi
1175 % \end{macrocode}
1176 %
1177 % That's all the code done now. I'll change back to `user' mode, where
1178 % all the magic control sequences aren't allowed any more.
1179 %
1180 % \begin{macrocode}
1181 \makeatother
1182 %</mdwtools>
1183 % \end{macrocode}
1184 %
1185 % Oh, wait! What if I want to typeset this documentation? Aha. I'll cope
1186 % with that by comparing |\jobname| with my filename |mdwtools|. However,
1187 % there's some fun here, because |\jobname| contains category-12 letters,
1188 % while my letters are category-11. Time to play with |\string| in a messy
1189 % way.
1190 %
1191 % \begin{macrocode}
1192 %<*driver>
1193 \makeatletter
1194 \edef\@tempa{\expandafter\@gobble\string\mdwtools}
1195 \edef\@tempb{\jobname}
1196 \ifx\@tempa\@tempb
1197 \describesfile*{mdwtools.tex}
1198 \docfile{mdwtools.tex}
1199 \makeatother
1200 \expandafter\mdwdoc
1201 \fi
1202 \makeatother
1203 %</driver>
1204 % \end{macrocode}
1205 %
1206 % That's it. Done!
1207 %
1208 % \hfill Mark Wooding, \today
1209 %
1210 % \Finale
1211 %
1212 \endinput