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