diff options
Diffstat (limited to 'Master/texmf-dist/source/latex/base/doc.dtx')
-rw-r--r-- | Master/texmf-dist/source/latex/base/doc.dtx | 135 |
1 files changed, 85 insertions, 50 deletions
diff --git a/Master/texmf-dist/source/latex/base/doc.dtx b/Master/texmf-dist/source/latex/base/doc.dtx index d17bf9fd758..c397911f67e 100644 --- a/Master/texmf-dist/source/latex/base/doc.dtx +++ b/Master/texmf-dist/source/latex/base/doc.dtx @@ -35,26 +35,10 @@ %<+package|shortvrb>\NeedsTeXFormat{LaTeX2e}[1994/12/01] %<+package> \ProvidesPackage{doc} %<+shortvrb>\ProvidesPackage{shortvrb} -%<+package|shortvrb> [2014/09/29 v2.1e +%<+package|shortvrb> [2016/02/15 v2.1g %<+package|shortvrb> Standard LaTeX documentation package (FMi)] %\catcode`\<=12 % -% \CheckSum{2179} -%% \CharacterTable -%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z -%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z -%% Digits \0\1\2\3\4\5\6\7\8\9 -%% Exclamation \! Double quote \" Hash (number) \# -%% Dollar \$ Percent \% Ampersand \& -%% Acute accent \' Left paren \( Right paren \) -%% Asterisk \* Plus \+ Comma \, -%% Minus \- Point \. Solidus \/ -%% Colon \: Semicolon \; Less than \< -%% Equals \= Greater than \> Question mark \? -%% Commercial at \@ Left bracket \[ Backslash \\ -%% Right bracket \] Circumflex \^ Underscore \_ -%% Grave accent \` Left brace \{ Vertical bar \| -%% Right brace \} Tilde \~} %% %\iffalse This is a METACOMMENT % Everything up to the next `\ fi' (without a blank) will @@ -155,6 +139,8 @@ % \changes{v1.9t}{1995/05/11}{Use \cs{GetFileInfo}} % \GetFileInfo{doc.sty} % +% \CheckSum{2202} ^^A % keep the checksum in this file +% % \title{The \DOC{} and \texttt{shortvrb} Packages\thanks % {This file has version number \fileversion{} dated \filedate{}.}} % \author{Frank Mittelbach\thanks{Further commentary added at Royal @@ -1045,26 +1031,37 @@ % be typed in, since only the \DOC{} package should look at this % command. % +% % Another problem of mailing files is possible truncation. To detect % these sort of errors we provide a |\CheckSum| macro. The check-sum % of a file is simply the number of backslashes in the code, i.e.\ all % lines between the \textsf{macrocode} environments. But don't be % afraid: you don't have count the code-lines yourself; this is done -% by the \DOC{} package for you. You simply have to use +% by the \DOC{} package for you. You simply have add +% \begin{quote} +% |% \CheckSum{0}| +% \end{quote} +% near the beginning of the file and +% use % the |\StopEventually| (which starts looking for backslashes) and the % |\Finale| command. The latter will inform you either that your file % has no check-sum (telling you the right number) or that your number -% is incorrect (this time telling you both the correct and the -% incorrect one). Then you go to the top of your file inserting the +% is incorrect if you put in anything other than zero but guessed wrong (this time +% telling you both the correct and the +% incorrect one). Then you go to the top of your file again and change the +% line to the right number, i.e. % line % \begin{quote} -% |%% \CheckSum{|\meta{number}|}| +% |% \CheckSum{|\meta{number}|}| % \end{quote} -% and that's all. If you precede it only with one percent then the -% line will not show up in \texttt{docstrip} versions of the file. -% You should do so whenever you are using conditional code (see -% \texttt{docstrip} documentation) since then the check-sum will not -% reflect the number of backslashes in the stripped of versions. +% and that's all. +% +% While |\CharacterTable| and |\CheckSum| have been important features +% in the early days of the public internet when \DOC{} was written as +% the mail gateways back then were rather unreliable and often mangled +% files they are these days more a nuicance than any help. They are +% therefore now fully optional and no longer recommended for use with new files. +% % % \DescribeMacro\bslash % From time to time, it is necessary to print a |\| without @@ -1199,8 +1196,6 @@ % \texttt{verbatim*} Environments. % \newblock File \texttt{verbatim.doc}, version 1.4i. % \end{thebibliography} -% ^^A\PrintIndex -% ^^A\PrintChanges % % \ifmulticols % \addtocontents{toc}{\protect\end{multicols}} @@ -1273,7 +1268,7 @@ % % \subsection{Macros surrounding the `definition parts'} % -% \begin{macro}{\macrocode} +% \begin{environment}{macrocode} % Parts of the macro definition will be surrounded by the % environment \textsf{macrocode}. Put more precisely, they will be % enclosed by a macro whose argument (the text to be set @@ -1303,7 +1298,7 @@ % \begin{macrocode} \xmacro@code} % \end{macrocode} -% \end{macro} +% \end{environment} % % % \begin{macro}{\macro@code} @@ -1803,7 +1798,7 @@ % % % -% \begin{macro}{\macrocode*} +% \begin{environment}{macrocode*} % \begin{macro}{\endmacrocode*} % Just as in the \textsf{verbatim} environment, there is also a % `star' variant of the \textsf{macrocode} environment in which a @@ -1833,7 +1828,7 @@ \expandafter\let\csname endmacrocode*\endcsname = \endmacrocode % \end{macrocode} % \end{macro} -% \end{macro} +% \end{environment} % % % @@ -1996,8 +1991,8 @@ % % % -% \begin{macro}{\verbatim} -% \begin{macro}{\verbatim*} +% \begin{environment}{verbatim} +% \begin{environment}{verbatim*} % \changes{v1.7i}{1992/07/12}{Added changed definition for verbatim!*.} % The \textsf{verbatim} environment holds no secrets; it consists of % the normal \LaTeX{} environment. We also set the @@ -2012,8 +2007,8 @@ \@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim \MacroFont \@sxverbatim} % \end{macrocode} -% \end{macro} -% \end{macro} +% \end{environment} +% \end{environment} % % \begin{macro}{\@verbatim} % Additionally we redefine the |\@verbatim| macro so that it @@ -2184,7 +2179,7 @@ \MakePrivateLetters \m@cro@ \iftrue} % \end{macrocode} % -% \begin{macro}{\environment} +% \begin{environment}{environment} % \changes{v1.8c}{1993/10/25}{Environment added} % The ``environment'' envrionment will be implemented just like the % ``macro'' environment flagging any differences in the code by @@ -2195,7 +2190,7 @@ \catcode`\\12 \MakePrivateLetters \m@cro@ \iffalse} % \end{macrocode} -% \end{macro} +% \end{environment} % % After scanning the argument we close the group to get the normal % |\catcode|$\,$s back. Then we assign a special value to @@ -2210,7 +2205,17 @@ % We also save the name being described in |\saved@macroname| for % use in conjunction with the |\changes| macro. % \begin{macrocode} - \edef\saved@macroname{\string#2}% + \edef\saved@macroname{\string#2}% + #1 +% \end{macrocode} +% If documenting an environment we put is name in |\saved@indexname| +% otherwise the name without the backslash. +% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} +% \begin{macrocode} + \let\saved@indexname\saved@macroname + \else + \edef\saved@indexname{\expandafter\@gobble\string#2}% + \fi % \end{macrocode} % Now there follows a variation of |\makelabel| which is used % should the environment not be nested, or should it lie between @@ -3520,7 +3525,7 @@ % \end{macro} % % -% \begin{macro}{\theindex} +% \begin{environment}{theindex} % Now we start the multi-column mechanism, if appropriate. We use the % \LaTeX{} counter |\c@IndexColumns| declared above to denote % the number of columns and insert the `index prologue' text (which @@ -3541,7 +3546,7 @@ % \begin{macrocode} \IndexParms \let\item\@idxitem \ignorespaces}% % \end{macrocode} -% \end{macro} +% % \begin{macro}{\endtheindex} % \changes{v1.4t}{1989/04/24}{Incorporated new multicols env.} % At the end of the index, we have only to end the \textsf{multicols} @@ -3563,6 +3568,8 @@ \fi % \end{macrocode} % \end{macro} +% \end{environment} +% % Here are the necessary \textsf{makeindex} declarations. We disable % scanning of macro names inside the index with "\scan@allowedfalse\n" % to avoid recursion. @@ -3864,8 +3871,10 @@ \actualchar \generalname \else - \expandafter\@gobble - \saved@macroname +% \end{macrocode} +% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} +% \begin{macrocode} + \saved@indexname \actualchar \string\verb\quotechar*% \verbatimchar\saved@macroname @@ -3892,6 +3901,14 @@ % \end{macrocode} % \end{macro} % +% \begin{macro}{\saved@indexname} +% \changes{v2.1g}{2016/02/15}{Use \cs{saved@indexname}} +% The macroname being document without a backslash for the index +% (or the environment name which doesn't have one in the first place). +% \begin{macrocode} +\def\saved@indexname{} +% \end{macrocode} +% \end{macro} % % \begin{macro}{\generalname} % \changes{v1.9u}{1995/08/06}{Macro added} @@ -3937,7 +3954,7 @@ % \end{macro} % % -% \begin{macro}{\theglossary} +% \begin{environment}{theglossary} % \changes{BHK}{1989/04/26}{Added to support % \texttt{\protect\bslash changes}.} % \changes{v1.5p}{1989/09/28}{Now call \cs{multicols} first.} @@ -3966,7 +3983,8 @@ \fi % \end{macrocode} % \end{macro} -% \end{macro} +% \end{environment} +% % Here are the necessary \textsf{makeindex} declarations with scanning % disabled as for the index. % \begin{macrocode} @@ -4016,9 +4034,16 @@ % \changes{BHK}{1989/04/26}{Added to support % \texttt{\protect\bslash changes}.} % Unless the user specifies otherwise, we set the change history -% using the same parameters as for the index. +% using the same parameters as for the index except that we make it sort +% of ragged right as it contains text that often doesn't break nicely in +% small columns. +% \changes{v2.1g}{2016/02/15}{Use ragged setting by default} % \begin{macrocode} -\@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms}{} +\@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms + \expandafter\def\expandafter\GlossaryParms\expandafter{\GlossaryParms + \rightskip 15pt plus 1fil + \parfillskip -15pt plus -1fil\relax} +}{} % \end{macrocode} % \end{macro} % \begin{macro}{\PrintChanges} @@ -4502,8 +4527,15 @@ % This reports the sum compared with the value ("\bslash@cnt") the % file advertises. It's called from "\Finale" (if that hasn't been % re-defined). +% \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum +% is specified in the file} % \begin{macrocode} \def\check@checksum{\relax + \ifnum\check@sum>\m@ne +% \end{macrocode} +% We do nothing if the checksum in the file is negative (or not given as +% it is initialized with -1). +% \begin{macrocode} \ifnum\check@sum=\z@ \typeout{**********************************}% \typeout{* This macro file has no checksum!}% @@ -4521,7 +4553,8 @@ Try to get a correct version.}% \fi \fi - \global\check@sum\z@} + \fi + \global\check@sum\m@ne} % \end{macrocode} % \end{macro} % @@ -4532,9 +4565,11 @@ % \changes{v1.5k}{1989/09/04}{Macro added to support checksum.} % We need to define counters, "\bslash@cnt" for the number of % backslashes counted and "\check@sum" for the value advertised by the -% file. +% file if any. A negative value means there is no checksum checking which is the default. +% \changes{v2.1f}{2016/02/12}{Suppress \cs{CheckSum} check if no checksum +% is specified in the file} % \begin{macrocode} -\newcount\check@sum \check@sum = \z@ +\newcount\check@sum \check@sum = \m@ne \newcount\bslash@cnt \bslash@cnt = \z@ % \end{macrocode} % \end{macro} |