summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/base/doc.dtx
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2016-04-02 22:19:48 +0000
committerKarl Berry <karl@freefriends.org>2016-04-02 22:19:48 +0000
commit54aa09d5d6925008eb25609ce953c1b99fd2d2c7 (patch)
treed8e052725306f427e156556aeb2bec689f8245cc /Master/texmf-dist/source/latex/base/doc.dtx
parent54e58adfc76118f03b1bd2f7dedfb2140dce7696 (diff)
latex2e (1apr16), now including amsmath
git-svn-id: svn://tug.org/texlive/trunk@40218 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/source/latex/base/doc.dtx')
-rw-r--r--Master/texmf-dist/source/latex/base/doc.dtx135
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}