1 % \begin{meta-comment} <general public licence>
3 %% mdwtools common declarations
4 %% Copyright (c) 1996, 2002, 2003, 2020 Mark Wooding
6 %% This file is part of the `mdwtools' LaTeX package collection.
8 %% `mdwtools' is free software: you can redistribute it and/or modify it
9 %% under the terms of the GNU General Public License as published by the
10 %% Free Software Foundation; either version 2 of the License, or (at your
11 %% option) any later version.
13 %% `mdwtools' is distributed in the hope that it will be useful, but
14 %% WITHOUT ANY WARRANTY; without even the implied warranty of
15 %% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
16 %% General Public License for more details.
18 %% You should have received a copy of the GNU General Public License
19 %% along with `mdwtools'. If not, write to the Free Software Foundation,
20 %% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24 % \begin{meta-comment} <file preamble>
26 \ProvidesFile{mdwtools.tex
}
27 [2020/
09/
06 1.14.0 Shared definitions for mdwtools .dtx files
]
33 %% {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
34 %% 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
35 %% Digits \0\1\2\3\4\5\6\7\8\9
36 %% Exclamation \! Double quote \" Hash (number) \#
37 %% Dollar \$ Percent \% Ampersand \&
38 %% Acute accent \' Left paren \( Right paren \)
39 %% Asterisk \* Plus \+ Comma \,
40 %% Minus \- Point \. Solidus \/
41 %% Colon \: Semicolon \; Less than \<
42 %% Equals \= Greater than \> Question mark \?
43 %% Commercial at \@ Left bracket \[ Backslash \\
44 %% Right bracket \] Circumflex \^ Underscore \_
45 %% Grave accent \` Left brace \{ Vertical bar \|
46 %% Right brace \} Tilde \~}
49 % \section{Introduction and user guide}
51 % This file is really rather strange; it gets |\input| by other package
52 % documentation files to set up most of the environmental gubbins for them.
53 % It handles almost everything, like loading a document class, finding any
54 % packages, and building and formatting the title.
56 % It also offers an opportunity for users to customise my nice documentation,
57 % by using a |mdwtools.cfg| file (not included).
60 % \subsection{Declarations}
62 % A typical documentation file contains something like
63 % \begin{listinglist} \listingsize \obeylines
68 % The initial |\input| reads in this file and sets up the various commands
69 % which may be needed. The final |\mdwdoc| actually starts the document,
70 % inserting a title (which is automatically generated), a table of
71 % contents etc., and reads the documentation file in (using the |\DocInput|
72 % command from the \package{doc} package.
74 % \subsubsection{Describing packages}
76 % \DescribeMacro{\describespackage}
77 % \DescribeMacro{\describesclass}
78 % \DescribeMacro{\describesfile}
79 % \DescribeMacro{\describesfile*}
80 % The most important declarations are those which declare what the
81 % documentation describes. Saying \syntax{"\\describespackage{<package>}"}
82 % loads the \<package> (if necessary) and adds it to the auto-generated
83 % title, along with a footnote containing version information. Similarly,
84 % |\describesclass| adds a document class name to the title (without loading
85 % it -- the document itself must do this, with the |\documentclass| command).
86 % For files which aren't packages or classes, use the |\describesfile| or
87 % |\describesfile*| command (the $*$-version won't |\input| the file, which
88 % is handy for files like |mdwtools.tex|, which are already input).
90 % \DescribeMacro{\author}
91 % \DescribeMacro{\date}
92 % \DescribeMacro{\title}
93 % The |\author|, |\date| and |\title| declarations work slightly differently
94 % to normal -- they ensure that only the \emph{first} declaration has an
95 % effect. (Don't you play with |\author|, please, unless you're using this
96 % program to document your own packages.) Using |\title| suppresses the
97 % automatic title generation.
99 % \DescribeMacro{\docdate}
100 % The default date is worked out from the version string of the package or
101 % document class whose name is the same as that of the documentation file.
102 % You can choose a different `main' file by saying
103 % \syntax{"\\docdate{"<file>"}"}.
105 % \subsubsection{Contents handling}
107 % \DescribeMacro{\addcontents}
108 % A documentation file always has a table of contents. Other
109 % contents-like lists can be added by saying
110 % \syntax{"\\addcontents{"<extension>"}{"<command>"}"}. The \<extension>
111 % is the file extension of the contents file (e.g., \lit{lot} for the
112 % list of tables); the \<command> is the command to actually typeset the
113 % contents file (e.g., |\listoftables|).
115 % \subsubsection{Other declarations}
117 % \DescribeMacro{\implementation}
118 % The \package{doc} package wants you to say
119 % \syntax{"\\StopEventually{"<stuff>"}"}' before describing the package
120 % implementation. Using |mdwtools.tex|, you just say |\implementation|, and
121 % everything works. It will automatically read in the licence text (from
122 % |gpl.tex|, and wraps some other things up.
125 % \subsection{Other commands}
127 % The |mdwtools.tex| file includes the \package{syntax} and \package{sverb}
128 % packages so that they can be used in documentation files. It also defines
129 % some trivial commands of its own.
132 % Saying \syntax{"\\<"<text>">" is the same as "\\synt{"<text>"}"}; this
133 % is a simple abbreviation.
135 % \DescribeMacro{\smallf}
136 % Saying \syntax{"\\smallf" <number>"/"<number>} typesets a little fraction,
137 % like this: \smallf 3/4. It's useful when you want to say that the default
138 % value of a length is 2 \smallf 1/2\,pt, or something like that.
141 % \subsection{Customisation}
143 % You can customise the way that the package documentation looks by writing
144 % a file called |mdwtools.cfg|. You can redefine various commands (before
145 % they're defined here, even; |mdwtools.tex| checks most of the commands that
146 % it defines to make sure they haven't been defined already.
148 % \DescribeMacro{\indexing}
149 % If you don't want the prompt about whether to generate index files, you
150 % can define the |\indexing| command to either \lit{y} or \lit{n}. I'd
151 % recommend that you use |\providecommand| for this, to allow further
152 % customisation from the command line.
154 % \DescribeMacro{\mdwdateformat}
155 % If you don't like my date format (maybe you're American or something),
156 % you can redefine the |\mdwdateformat| command. It takes three arguments:
157 % the year, month and date, as numbers; it should expand to something which
158 % typesets the date nicely. The default format gives something like
159 % `10 May 1996'. You can produce something rather more exotic, like
160 % `10\textsuperscript{th} May \textsc{\romannumeral 1996}' by saying
162 %\newcommand{\mdwdateformat}[3]{%
163 % \number#3\textsuperscript{\numsuffix{#3}}\ %
165 % \textsc{\romannumeral #1}%
168 % \DescribeMacro{\monthname}
169 % \DescribeMacro{\numsuffix}
170 % Saying \syntax{"\\monthname{"<number>"}"} expands to the name of the
171 % numbered month (which can be useful when doing date formats). Saying
172 % \syntax{"\\numsuffix{"<number>"}"} will expand to the appropriate suffix
173 % (`th' or `rd' or whatever) for the \<number>. You'll have to superscript
174 % it yourself, if this is what you want to do. Putting the year number
175 % in roman numerals is just pretentious |;-)|.
177 % \DescribeMacro{\mdwhook}
178 % After all the declarations in |mdwtools.tex|, the command |\mdwhook| is
179 % executed, if it exists. This can be set up by the configuration file
180 % to do whatever you want.
182 % There are lots of other things you can play with; you should look at the
183 % implementation section to see what's possible.
187 % \section{Implementation}
193 % The first thing is that I'm not a \LaTeX\ package or anything official
194 % like that, so I must enable `|@|' as a letter by hand.
200 % Now input the user's configuration file, if it exists. This is fairly
204 \@input
{mdwtools.cfg
}
207 % Well, that's the easy bit done.
210 % \subsection{Initialisation}
212 % Obviously the first thing to do is to obtain a document class. Obviously,
213 % it would be silly to do this if a document class has already been loaded,
214 % either by the package documentation or by the configuration file.
216 % The only way I can think of for finding out if a document class is already
217 % loaded is by seeing if the |\documentclass| command has been redefined
218 % to raise an error. This isn't too hard, really.
220 % If my \package{strayman} document class is available, then I'd prefer to
224 \ifx\documentclass\@twoclasseserror
\else
225 \IfFileExists{strayman.cls
}
226 {\documentclass[a4paper]{strayman
}}
227 {\documentclass[a4paper]{ltxdoc
}}
228 \ifx\doneclasses\mdw@undefined
\else\doneclasses\fi
232 % If I can use better fonts, then that would be nice.
235 \usepackage[T1]{fontenc}
236 \IfFileExists{mdwfonts.sty
}
237 {\usepackage[palatino, helvetica, courier, maths=cmr
]{mdwfonts
}}{}
240 % As part of my standard environment, I'll load some of my more useful
241 % packages. If they're already loaded (possibly with different options),
242 % I'll not try to load them again.
245 \@ifpackageloaded
{doc
}{}{\usepackage{doc
}}
246 \@ifpackageloaded
{syntax
}{}{\usepackage[rounded
]{syntax
}}
247 \@ifpackageloaded
{sverb
}{}{\usepackage{sverb
}}
250 % If I'm not using the \package{ltxdoc} document class then I'll need some of
251 % its definitions. I've no idea why these aren't part of \package{doc}\ldots
253 % \begin{macro}{\cmd}
256 \def\cmd#1{\expandafter\cmd@i
\string#1\x}
257 \def\cmd@i
#1#2\x{\cs{#2}}
258 \DeclareRobustCommand\cs[1]{\texttt{\char`\\
#1}}
263 % \begin{macro}{\marg}
264 % \begin{macro}{\oarg}
265 % \begin{macro}{\parg}
267 \def\@arg
#1#2#3{\texttt{#1}\meta{#2}\texttt{#3}}
268 \def\marg#1{\@arg
{\char`\
{}{#1}{\char`\
}}}
269 \def\oarg#1{\@arg
{[}{#1}{]}}
270 \def\parg#1{\@arg
{(
}{#1}{)
}}
276 % \subsection{Some macros for interaction}
278 % I like the \LaTeX\ star-boxes, although it's a pain having to cope with
279 % \TeX's space-handling rules. I'll define a new typing-out macro which
280 % makes spaces more significant, and has a $*$-version which doesn't put
281 % a newline on the end, and interacts prettily with |\read|.
283 % First of all, I need to make spaces active, so I can define things about
287 \begingroup\obeyspaces
290 % Now to define the main macro. This is easy stuff. Spaces must be
291 % carefully rationed here, though.
293 % I'll start a group, make spaces active, and make spaces expand to ordinary
294 % space-like spaces. Then I'll look for a star, and pass either |\message|
295 % (which doesn't start a newline, and interacts with |\read| well) or
296 % |\immediate\write 16| which does a normal write well.
300 \begingroup\catcode`\
\active\let \space%
301 \@ifstar
{\mdwtype@i
{\message}}{\mdwtype@i
{\immediate\write\sixt@@n
}}%
306 % Now for the easy bit. I have the thing to do, and the thing to do it to,
307 % so do that and end the group.
310 \def\mdwtype@i
#1#2{#1{#2}\endgroup}
314 % \subsection{Decide on indexing}
316 % A configuration file can decide on indexing by defining the |\indexing|
317 % macro to either \lit{y} or \lit{n}. If it's not set, then I'll prompt
320 % First of all, I want a switch to say whether I'm indexing.
326 % Right: now I need to decide how to make progress. If the macro's not set,
327 % then I want to set it, and start a row of stars.
330 \ifx\indexing\@@undefined
331 \mdwtype{*****************************
}
336 % Now enter a loop, asking the user whether to do indexing, until I get
342 \if y
\indexing\@tempswatrue
\createindextrue\fi
343 \if Y
\indexing\@tempswatrue
\createindextrue\fi
344 \if n
\indexing\@tempswatrue
\createindexfalse\fi
345 \if N
\indexing\@tempswatrue
\createindexfalse\fi
347 \mdwtype*
{* Create index files? (y/n) *
}
348 \read\sixt@@n to
\indexing%
352 % Now, based on the results of that, display a message about the indexing.
355 \mdwtype{*****************************
}
357 \mdwtype{* Creating index files *
}
358 \mdwtype{* This may take some time *
}
360 \mdwtype{* Not creating index files *
}
362 \mdwtype{*****************************
}
365 % Now I can play with the indexing commands of the \package{doc} package
366 % to do whatever it is that the user wants.
378 % And register lots of plain \TeX\ things which shouldn't be indexed.
379 % This contains lots of |\if|\dots\ things which don't fit nicely in
380 % conditionals, which is a shame. Still, it doesn't matter that much,
384 \DoNotIndex{\def,
\long,
\edef,
\xdef,
\gdef,
\let,
\global}
385 \DoNotIndex{\if,
\ifnum,
\ifdim,
\ifcat,
\ifmmode,
\ifvmode,
\ifhmode,
%
386 \iftrue,
\iffalse,
\ifvoid,
\ifx,
\ifeof,
\ifcase,
\else,
\or,
\fi}
387 \DoNotIndex{\box,
\copy,
\setbox,
\unvbox,
\unhbox,
\hbox,
%
388 \vbox,
\vtop,
\vcenter}
389 \DoNotIndex{\@empty,
\immediate,
\write}
390 \DoNotIndex{\egroup,
\bgroup,
\expandafter,
\begingroup,
\endgroup}
391 \DoNotIndex{\divide,
\advance,
\multiply,
\count,
\dimen}
392 \DoNotIndex{\relax,
\space,
\string}
393 \DoNotIndex{\csname,
\endcsname,\@spaces,
\openin,
\openout,
%
395 \DoNotIndex{\catcode,
\endinput}
396 \DoNotIndex{\jobname,
\message,
\read,
\the,
\m@ne,
\noexpand}
397 \DoNotIndex{\hsize,
\vsize,
\hskip,
\vskip,
\kern,
\hfil,
\hfill,
\hss}
398 \DoNotIndex{\m@ne,
\z@,
\z@skip,\@ne,
\tw@,
\p@
}
399 \DoNotIndex{\dp,
\wd,
\ht,
\vss,
\unskip}
402 % Last bit of indexing stuff, for now: I'll typeset the index in two columns
403 % (the default is three, which makes them too narrow for my tastes).
406 \setcounter{IndexColumns
}{2}
410 % \subsection{Selectively defining things}
412 % I don't want to tread on anyone's toes if they redefine any of these
413 % commands and things in a configuration file. The following definitions
414 % are fairly evil, but should do the job OK.
416 % \begin{macro}{\@gobbledef}
418 % This macro eats the following |\def|inition, leaving not a trace behind.
421 \def\@gobbledef
#1#
{\@gobble
}
426 % \begin{macro}{\tdef}
427 % \begin{macro}{\tlet}
429 % The |\tdef| command is a sort of `tentative' definition -- it's like
430 % |\def| if the control sequence named doesn't already have a definition.
431 % |\tlet| does the same thing with |\let|.
436 \expandafter\def\expandafter#1%
438 \expandafter\@gobbledef
%
441 \def\tlet#1#2{\ifx#1\@@undefined
\let#1=
#2\fi}
448 % \subsection{General markup things}
450 % Now for some really simple things. I'll define how to typeset package
451 % names and environment names (both in the sans serif font, for now).
454 \tdef\package{\textsf}
458 % I'll define the |\<|\dots|>| shortcut for syntax items suggested in the
459 % \package{syntax} package.
462 \tdef\<
#1>
{\synt{#1}}
465 % And because it's used in a few places (mainly for typesetting lengths),
466 % here's a command for typesetting fractions in text.
469 \tdef\smallf#1/
#2{\ensuremath{^
{#1}\!/\!_
{#2}}}
473 % \subsection{Custom description lists}
475 % For some bizarre reason, the \LaTeX\ \env{description} environment sets
476 % |\itemindent| so that the label starts |\labelsep| into the left margin,
477 % and the default |\makelabel| must therefore contain a hack to compensate.
478 % This is fixed in the \package{strayman} document class, and by the
479 % \package{mdwlist} package in this collection. But this introduces a
480 % problem: if I want to set a \env{description} list with custom labels, how
481 % can I do this without messing up the spacing?
483 % Detection of the relevant packages is done in an awfully hacky way, because
484 % \LaTeXe\ seems to go out of its way to forget which packages have been
485 % loaded at |\begin{document}| time.
488 \def\setdescriptionlabel#1{%
489 \if1\ifx\sectindent\xxundefined% strayman?
490 \ifx\defaultdesc\xxundefined% mdwlist?
492 \def\makelabel#
#1{\hskip\labelsep\relax#1}%
494 \def\makelabel#
#1{#1}%
500 % \subsection{A table environment}
502 % \begin{environment}{tab}
504 % Most of the packages don't use the (obviously perfect) \package{mdwtab}
505 % package, because it's big, and takes a while to load. Here's an
506 % environment for typesetting centred tables. The first (optional) argument
507 % is some declarations to perform. The mandatory argument is the table
508 % preamble (obviously).
512 \newenvironment{tab
}[2][\relax]{%
527 % \subsection{Commenting out of stuff}
529 % \begin{environment}{meta-comment}
531 % Using |\iffalse|\dots|\fi| isn't much fun. I'll define a gobbling
532 % environment using the \package{sverb} stuff.
535 \ignoreenv{meta-comment
}
541 % \subsection{Float handling}
543 % This gubbins will try to avoid float pages as much as possible, and (with
544 % any luck) encourage floats to be put on the same pages as text.
547 \def\textfraction{0.1}
548 \def\topfraction{0.9}
549 \def\bottomfraction{0.9}
550 \def\floatpagefraction{0.7}
553 % Now redefine the default float-placement parameters to allow `here' floats.
556 \def\fps@figure
{htbp
}
561 % \subsection{Other bits of parameter tweaking}
563 % Make \env{grammar} environments look pretty, by indenting the left hand
564 % sides by a large amount.
570 % I don't like being told by \TeX\ that my paragraphs are hard to linebreak:
571 % I know this already. This lot should shut \TeX\ up about most problems.
579 % Also make \TeX\ shut up in the index. The \package{multicol} package
580 % irritatingly plays with |\hbadness|. This is the best hook I could find
581 % for playing with this setting.
584 \expandafter\def\expandafter\IndexParms\expandafter{%
590 % The other thing I really don't like is `Marginpar moved' warnings. This
591 % will get rid of them, and lots of other \LaTeX\ warnings at the same time.
594 \let\@latex@warning@no@line\@gobble
597 % Put some extra space between table rows, please.
600 \def\arraystretch{1.2}
603 % Most of the code is at guard level one, so typeset that in upright text.
606 \setcounter{StandardModuleDepth
}{1}
610 % \subsection{Contents handling}
612 % I use at least one contents file (the main table of contents) although
613 % I may want more. I'll keep a list of contents files which I need to
616 % There are two things I need to do to contents files here:
618 % \item I must typeset the table of contents at the beginning of the
620 % \item I want to typeset tables of contents in two columns (using the
621 % \package{multicol} package).
624 % The list consists of items of the form
625 % \syntax{"\\do{"<extension>"}{"<command>"}"}, where \<extension> is the
626 % file extension of the contents file, and \<command> is the command to
629 % \begin{macro}{\docontents}
631 % This is where I keep the list of contents files. I'll initialise it to
632 % just do the standard contents table.
635 \def\docontents{\do{toc
}{\tableofcontents}}
640 % \begin{macro}{\addcontents}
642 % By saying \syntax{"\\addcontents{"<extension>"}{"<command>"}"}, a document
643 % can register a new table of contents which gets given the two-column
644 % treatment properly. This is really easy to implement.
647 \def\addcontents#1#2{%
648 \toks@
\expandafter{\docontents\do{#1}{#2}}%
649 \edef\docontents{\the\toks@
}%
656 % \subsection{Finishing it all off}
658 % \begin{macro}{\finalstuff}
660 % The |\finalstuff| macro is a hook for doing things at the end of the
661 % document. Currently, it inputs the licence agreement as an appendix.
664 \tdef\finalstuff{\appendix\part*
{Appendix
}\input{gpl
}}
669 % \begin{macro}{\implementation}
671 % The |\implementation| macro starts typesetting the implementation of
672 % the package(s). If we're not doing the implementation, it just does
673 % this lot and ends the input file.
675 % I define a macro with arguments inside the |\StopEventually|, which causes
676 % problems, since the code gets put through an extra level of |\def|fing
677 % depending on whether the implementation stuff gets typeset or not. I'll
678 % store the code I want to do in a separate macro.
681 \def\implementation{\StopEventually{\attheend}}
684 % Now for the actual activity. First, I'll do the |\finalstuff|. Then, if
685 % \package{doc}'s managed to find the \package{multicol} package, I'll add
686 % the end of the environment to the end of each contents file in the list.
687 % Finally, I'll read the index in from its formatted |.ind| file.
693 \def\do#
#1#
#2{\addtocontents{#
#1}{\protect\end{multicols
}}}%
696 \ifx\backmatter\@@undefined
\else\backmatter\fi%
704 % \subsection{File version information}
706 % \begin{macro}{\mdwpkginfo}
708 % For setting up the automatic titles, I'll need to be able to work out
709 % file versions and things. This macro will, given a file name, extract
710 % from \LaTeX\ the version information and format it into a sensible string.
712 % First of all, I'll put the original string (direct from the
713 % |\Provides|\dots\ command). Then I'll pass it to another macro which can
714 % parse up the string into its various bits, along with the original
719 \edef\@tempa
{\csname ver@
#1\endcsname}%
720 \expandafter\mdwpkginfo@i\@tempa\@@
#1\@@
%
724 % Now for the real business. I'll store the string I build in macros called
725 % \syntax{"\\"<filename>"date", "\\"<filename>"version" and
726 % "\\"<filename>"info"}, which store the file's date, version and
727 % `information string' respectively. (Note that the file extension isn't
728 % included in the name.)
730 % This is mainly just tedious playing with |\expandafter|. The date format
731 % is defined by a separate macro, which can be modified from the
732 % configuration file.
735 \def\mdwpkginfo@i
#1/
#2/
#3 #4 #5\@@
#6.
#7\@@
{%
736 \expandafter\def\csname #6date
\endcsname%
737 {\protect\mdwdateformat{#1}{#2}{#3}}%
738 \expandafter\def\csname #6version
\endcsname{#4}%
739 \expandafter\def\csname #6info
\endcsname{#5}%
745 % \begin{macro}{\mdwdateformat}
747 % Given three arguments, a year, a month and a date (all numeric), build a
748 % pretty date string. This is fairly simple really.
751 \tdef\mdwdateformat#1#2#3{\number#3\
\monthname{#2}\
\number#1}
754 January
\or February
\or March
\or April
\or May
\or June
\or%
755 July
\or August
\or September
\or October
\or November
\or December
%
767 \fi\fi\fi\fi\fi\fi\fi%
773 % \begin{macro}{\mdwfileinfo}
775 % Saying \syntax{"\\mdwfileinfo{"<file-name>"}{"<info>"}"} extracts the
776 % wanted item of \<info> from the version information for file \<file-name>.
779 \def\mdwfileinfo#1#2{\mdwfileinfo@i
{#2}#1.\@@
}
780 \def\mdwfileinfo@i
#1#2.
#3\@@
{\csname#2#1\endcsname}
786 % \subsection{List handling}
788 % There are several other lists I need to build. These macros will do
789 % the necessary stuff.
791 % \begin{macro}{\mdw@ifitem}
793 % The macro \syntax{"\\mdw@ifitem"<item>"\\in"<list>"{"<true-text>"}"^^A
794 % "{"<false-text>"}"} does \<true-text> if the \<item> matches any item in
795 % the \<list>; otherwise it does \<false-text>.
798 \def\mdw@ifitem
#1\in#2{%
801 \def\do#
#1{\def\@tempb
{#
#1}\ifx\@tempa\@tempb\@tempswatrue
\fi}%
803 \if@tempswa
\expandafter\@firstoftwo
\else\expandafter\@secondoftwo
\fi%
809 % \begin{macro}{\mdw@append}
811 % Saying \syntax{"\\mdw@append"<item>"\\to"<list>} adds the given \<item>
812 % to the end of the given \<list>.
815 \def\mdw@append
#1\to#2{%
817 \toks\tw@
\expandafter{#2}%
818 \edef#2{\the\toks\tw@
\the\toks@
}%
824 % \begin{macro}{\mdw@prepend}
826 % Saying \syntax{"\\mdw@prepend"<item>"\\to"<list>} adds the \<item> to the
827 % beginning of the \<list>.
830 \def\mdw@prepend
#1\to#2{%
832 \toks\tw@
\expandafter{#2}%
833 \edef#2{\the\toks@
\the\toks\tw@
}%
839 % \begin{macro}{\mdw@add}
841 % Finally, saying \syntax{"\\mdw@add"<item>"\\to"<list>} adds the \<item>
842 % to the list only if it isn't there already.
845 \def\mdw@add
#1\to#2{\mdw@ifitem
#1\in#2{}{\mdw@append
#1\to#2}}
851 % \subsection{Described file handling}
853 % I'l maintain lists of packages, document classes, and other files
854 % described by the current documentation file.
856 % First of all, I'll declare the various list macros.
864 % \begin{macro}{\describespackage}
866 % A document file can declare that it describes a package by saying
867 % \syntax{"\\describespackage{"<package-name>"}"}. I add the package to
868 % my list, read the package into memory (so that the documentation can
869 % offer demonstrations of it) and read the version information.
872 \def\describespackage#1{%
873 \mdw@ifitem
#1\in\dopackages{}{%
874 \mdw@append
#1\to\dopackages%
883 % \begin{macro}{\describesclass}
885 % By saying \syntax{"\\describesclass{"<class-name>"}"}, a document file
886 % can declare that it describes a document class. I'll assume that the
887 % document class is already loaded, because it's much too late to load
891 \def\describesclass#1{\mdw@add
#1\to\doclasses\mdwpkginfo{#1.cls
}}
896 % \begin{macro}{\describesfile}
898 % Finally, other `random' files, which don't have the status of real \LaTeX\
899 % packages or document classes, can be described by saying \syntax{^^A
900 % "\\describesfile{"<file-name>"}" or "\\describesfile*{"<file-name>"}"}.
901 % The difference is that the starred version will not |\input| the file.
905 \@ifstar
{\describesfile@i\@gobble
}{\describesfile@i
\input}%
907 \def\describesfile@i
#1#2{%
908 \mdw@ifitem
#2\in\dootherfiles{}{%
909 \mdw@add
#2\to\dootherfiles%
919 % \subsection{Author and title handling}
921 % I'll redefine the |\author| and |\title| commands so that I get told
922 % whether I need to do it myself.
924 % \begin{macro}{\author}
926 % This is easy: I'll save the old meaning, and then redefine |\author| to
927 % do the old thing and redefine itself to then do nothing.
930 \let\mdw@author
\author
931 \def\author{\let\author\@gobble
\mdw@author
}
936 % \begin{macro}{\title}
938 % And oddly enough, I'll do exactly the same thing for the title, except
939 % that I'll also disable the |\mdw@buildtitle| command, which constructs
940 % the title automatically.
944 \def\title{\let\title\@gobble
\let\mdw@buildtitle
\relax\mdw@title
}
949 % \begin{macro}{\date}
951 % This works in a very similar sort of way.
954 \def\date#1{\let\date\@gobble
\def\today{#1}}
959 % \begin{macro}{\datefrom}
961 % Saying \syntax{"\\datefrom{"<file-name>"}"} sets the document date from
962 % the given filename.
966 \protected@edef\@tempa
{\noexpand\date{\csname #1date
\endcsname}}%
973 % \begin{macro}{\docfile}
975 % Saying \syntax{"\\docfile{"<file-name>"}"} sets up the file name from which
976 % documentation will be read.
980 \def\@tempa#
#1.#
#2\@@
{\def\@basefile
{#
#1.#
#2}\def\@basename
{#
#1}}%
981 \edef\@tempb
{\noexpand\@tempa
#1\noexpand\@@
}%
986 % I'll set up a default value as well.
989 \docfile{\jobname.dtx
}
995 % \subsection{Building title strings}
997 % This is rather tricky. For each list, I need to build a legible looking
1000 % \begin{macro}{\mdw@addtotitle}
1003 %\syntax{"\\mdw@addtotitle{"<list>"}{"<command>"}{"<singular>"}{"<plural>"}"}
1004 % I can add the contents of a list to the current title string in the
1005 % |\mdw@title| macro.
1008 \tdef\mdw@addtotitle
#1#2#3#4{%
1011 % Now to get to work. I need to keep one `lookahead' list item, and a count
1012 % of the number of items read so far. I'll keep the lookahead item in
1013 % |\@nextitem| and the counter in |\count@|. Things are even worse because
1014 % the footnote symbols should appear \emph{after} the separating punctuation,
1015 % so we need to delay those by another cycle, hence we have |\@nextnote| and
1022 % Now I'll define what to do for each list item. The |\protect| command is
1023 % already set up appropriately for playing with |\edef| commands.
1029 % The first job is to add the previous item to the title string. If this
1030 % is the first item, though, I'll just add the appropriate \lit{The } or
1031 % \lit{ and the } string to the title (this is stored in the |\@prefix|
1032 % macro). Also maintain a parallel version which doesn't have the footnotes
1033 % in: this will be suitable for a running header.
1038 \ifcase\count@\@prefix
%
1040 \else,\@prevnote\ \@nextitem
%
1043 \edef\mdw@runningtitle
{%
1045 \ifcase\count@\@prefix
%
1052 % That was rather easy. Now I'll set up the |\@previtem| and |\@nextitem|
1053 % macros for the next time around the loop.
1056 \edef\@nextitem
{\protect#2{#
#1}}%
1057 \let\@prevnote\@nextnote
1060 The
\protect#2{#
#1} #3 is currently at version
%
1061 \mdwfileinfo{#
#1}{version
}, dated
\mdwfileinfo{#
#1}{date
}.
%
1066 % Finally, I need to increment the counter.
1069 \advance\count@\@ne
%
1073 % Now execute the list.
1079 % I still have one item left over, unless the list was empty. I'll add
1086 \or\@nextitem\@nextnote
\space#3%
1087 \or\@prevnote\ and \@nextitem\@nextnote
\space#4%
1088 \else,\@prevnote\ and \@nextitem\@nextnote
\space#4%
1091 \edef\mdw@runningtitle
{%
1094 \or\@nextitem
\space#3%
1095 \or\ and \@nextitem
\space#4%
1096 \else,\ and \@nextitem
\space#4%
1101 % Finally, if $|\count@| \ne 0$, I must set |\@prefix| to \lit{ and the }.
1104 \ifnum\count@>
\z@
\def\@prefix
{ and the
}\fi%
1110 % \begin{macro}{\mdw@buildtitle}
1112 % This macro will actually do the job of building the title string.
1115 \tdef\mdw@buildtitle
{%
1118 % First of all, I'll open a group to avoid polluting the namespace with
1119 % my gubbins (although the code is now much tidier than it has been in
1120 % earlier releases).
1126 % The title building stuff makes extensive use of |\edef|. I'll set
1127 % |\protect| appropriately. (For those not in the know,
1128 % |\@unexpandable@protect| expands to `|\noexpand\protect\noexpand|',
1129 % which prevents expansion of the following macro, and inserts a |\protect|
1130 % in front of it ready for the next |\edef|.)
1133 \let\@@protect
\protect\let\protect\@unexpandable@protect
%
1136 % Set up some simple macros ready for the main code.
1140 \def\mdw@runningtitle
{}%
1144 % Now build the title. This is fun.
1147 \mdw@addtotitle
\dopackages\package{package
}{packages
}%
1148 \mdw@addtotitle
\doclasses\package{document class
}{document classes
}%
1149 \mdw@addtotitle
\dootherfiles\texttt{file
}{files
}%
1152 % Now I want to end the group and set the title from my string. The
1153 % following hacking will do this.
1158 \noexpand\title{\noexpand\mdw@titlehack
\mdw@title
}%
1159 \def\noexpand\@headertitle
{\mdw@runningtitle
}%
1167 % \begin{macro}{\mdw@titlehack}
1169 % Wait! Did you notice that |\mdw@titlehack|? What's that about?
1171 % It turns out that the default document classes hack the footnote insertion
1172 % commands to make footnote symbols take up no horizontal space in the title.
1173 % Apparently this makes author names look as if they're centred properly when
1174 % there are affiliation footnotes. Anyway, \package{doc} perpetuates this
1175 % silliness, but it makes a mess of the version markers I insert, so I must
1176 % deploy countermeasures.
1179 \def\mdw@titlehack
{\def\@makefnmark
{$
\m@th^
{\@thefnmark
}$
}}
1184 % \subsection{Starting the main document}
1186 % \begin{macro}{\mdwdoc}
1188 % Once the document preamble has done all of its stuff, it calls the
1189 % |\mdwdoc| command, which takes over and really starts the documentation
1196 % First, I'll construct the title string.
1200 \author{Mark Wooding
}%
1203 % Set up the date string based on the date of the package which shares
1204 % the same name as the current file.
1207 \datefrom\@basename
%
1210 % Set up verbatim characters after all the packages have started.
1217 % Start the document, and put the title in.
1221 \ifx\frontmatter\@@undefined
\else\frontmatter\fi%
1225 % This is nasty. It makes maths displays work properly in demo environments.
1226 % \emph{The \LaTeX\ Companion} exhibits the bug which this hack fixes. So
1230 \abovedisplayskip\z@
%
1233 % Now start the contents tables. After starting each one, I'll make it
1238 \ifhave@multicol
\addtocontents{#
#1}{%
1239 \protect\begin{multicols
}{2}%
1247 % Input the main file now.
1250 \ifx\mainmatter\@@undefined
\else\mainmatter\fi%
1251 \DocInput{\@basefile
}%
1254 % That's it. I'm done.
1264 % \subsection{And finally\dots}
1266 % Right at the end I'll put a hook for the configuration file.
1269 \ifx\mdwhook\@@undefined
\else\expandafter\mdwhook\fi
1272 % That's all the code done now. I'll change back to `user' mode, where
1273 % all the magic control sequences aren't allowed any more.
1280 % Oh, wait! What if I want to typeset this documentation? Aha. I'll cope
1281 % with that by comparing |\jobname| with my filename |mdwtools|. However,
1282 % there's some fun here, because |\jobname| contains category-12 letters,
1283 % while my letters are category-11. Time to play with |\string| in a messy
1289 \edef\@tempa
{\expandafter\@gobble
\string\mdwtools}
1290 \edef\@tempb
{\jobname}
1292 \describesfile*
{mdwtools.tex
}
1293 \docfile{mdwtools.tex
}
1303 % \hfill Mark Wooding, \today