From e0c6872cf40896c7be36b11dcc744620f10adf1d Mon Sep 17 00:00:00 2001 From: Norbert Preining Date: Mon, 2 Sep 2019 13:46:59 +0900 Subject: Initial commit --- macros/latex/base/ltxdoc.dtx | 588 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 588 insertions(+) create mode 100644 macros/latex/base/ltxdoc.dtx (limited to 'macros/latex/base/ltxdoc.dtx') diff --git a/macros/latex/base/ltxdoc.dtx b/macros/latex/base/ltxdoc.dtx new file mode 100644 index 0000000000..329353d123 --- /dev/null +++ b/macros/latex/base/ltxdoc.dtx @@ -0,0 +1,588 @@ +% \iffalse meta-comment +% +% Copyright 1993-2018 +% The LaTeX3 Project and any individual authors listed elsewhere +% in this file. +% +% This file is part of the LaTeX base system. +% ------------------------------------------- +% +% It may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3c +% of this license or (at your option) any later version. +% The latest version of this license is in +% https://www.latex-project.org/lppl.txt +% and version 1.3c or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This file has the LPPL maintenance status "maintained". +% +% The list of all files belonging to the LaTeX base distribution is +% given in the file `manifest.txt'. See also `legal.txt' for additional +% information. +% +% The list of derived (unpacked) files belonging to the distribution +% and covered by LPPL is defined by the unpacking scripts (with +% extension .ins) which are part of the distribution. +% +% \fi +% \iffalse +% +%\NeedsTeXFormat{LaTeX2e} +%\ProvidesClass{ltxdoc} +% [2018/03/15 v2.0x Standard LaTeX documentation class] +% +%<*driver> +\documentclass{ltxdoc} +\GetFileInfo{ltxdoc.cls} +\providecommand\dst{\expandafter{\normalfont\scshape docstrip}} +\title{The file \texttt{ltxdoc.dtx} for use with + \LaTeXe.\thanks{This file has version + number \fileversion, dated \filedate.}\\[2pt] + It contains the code for \texttt{ltxdoc.cls}} +\date{\filedate} +\author{David Carlisle} +\begin{document} + \MaintainedByLaTeXTeam{latex} + \maketitle + \DocInput{ltxdoc.dtx} +\end{document} +% +% +% \fi +% +% +% \changes{v2.0i}{1994/04/29}{Update the documentation.} +% \changes{v2.0s}{1998/08/17}{(RmS) Documentation fixes.} +% +% \section{Documentation of the \LaTeX\ sources} +% +% This class file is designed for documenting the \LaTeX\ source files. +% You may however find it generally useful as a class for typesetting +% the documentation of files produced in `doc' format. +% +% Each documented file in the standard distribution comes with extension +% |dtx|. The appropriate class package or initex file will be extracted +% from the source by the docstrip system. Each |dtx| file may be +% directly processed with \LaTeXe, for example +%\begin{verbatim} +% latex2e docclass.dtx +%\end{verbatim} +% would produce the documentation of the Class and package interface. +% +% Each file that is used in producing the \LaTeXe\ format (ie not +% including the standard class and packages) will be printed together in +% one document if you \LaTeX\ the file |sources2e.tex|. This has the +% advantage that one can produce a full index of macro usage across all +% the source files. +% +% If you need to customise the typesetting of any of these files, there +% are two options: +% \begin{itemize} +% \item You can use \dst\ with the module `driver' to extract a small +% \LaTeX\ file that you may edit to use whatever class or package +% options you require, before inputting the source file. +% \item You can create a file |ltxdoc.cfg|. This configuration file will +% be read whenever the |ltxdoc| class is used, and so can be used to +% customise the typesetting of all the source files, without having to +% edit lots of small driver files. +%\end{itemize} +% +% The second option is usually more convenient. Various possibilities +% are discussed in the next section. +% +% \section{Customisation} +% +% The simplest form of customisation is to pass more options to the +% |article| class which is loaded by |ltxdoc|. For instance if you wish +% all the documentation to be formatted for A4 paper, add the following +% line to |ltxdoc.cfg|: +%\begin{verbatim} +% \PassOptionsToClass{a4paper}{article} +%\end{verbatim} +% +% All the source files are in two parts, separated by |\StopEventually|. +% The first part (should) contain `user' documentation. The second part +% is a full documented listing of the source code. The |doc| package +% provides the command |\OnlyDescription| which suppresses the code +% listings. This may also be used in the configuration file, but as the +% |doc| package is read later, you must delay the execution of +% |\OnlyDescription| until after the |doc| package has been read. The +% simplest way is to use |\AtBeginDocument|. Thus you could put the +% following in your |ltxdoc.cfg|. +%\begin{verbatim} +% \AtBeginDocument{\OnlyDescription} +%\end{verbatim} +% +% +% If the full source listing |sources2e.tex| is processed, then an index +% and change history are produced by default, however indices are not +% normally produced for individual files. +% +% As an example, consider |ltclass.dtx|, which contains the sources for +% the new class and package interface commands. With no |cfg| +% file, a 19~page document is produced. With the above configuration +% a slightly more readable document (4~pages) is produced. +% +% Conversely, if you really want to read the source listings in detail, +% you will want to have an index. Again the index commands provided by +% the doc package may be used, but their execution must be delayed. +%\begin{verbatim} +% \AtBeginDocument{\CodelineIndex\EnableCrossrefs} +% \AtEndDocument{\PrintIndex} +%\end{verbatim} +% +% The |doc| package writes index files to be sorted using MakeIndex with +% the |gind| style, so one would then use a command such as +%\begin{verbatim} +% makeindex -s gind.ist ltclass.idx +%\end{verbatim} +% and re-run \LaTeX. +% +% Similarly to print a Change history, you would add +%\begin{verbatim} +% \AtBeginDocument{\RecordChanges} +% \AtEndDocument{\PrintChanges} +%\end{verbatim} +% to |ltxdoc.cfg|, and use MakeIndex with a command such as +%\begin{verbatim} +% makeindex -s gglo.ist -o ltclass.gls ltclass.glo +%\end{verbatim} +% +% Finally if you do not want to list all the sections of |source2e.tex|, +% you can use |\includeonly| in the |cfg| file: +%\begin{verbatim} +% \includeonly{ltvers,ltboxes} +%\end{verbatim} +% +% \StopEventually{} +% +% +% \section{Options} +% +% \begin{macrocode} +%<*class> +\DeclareOption{a5paper}{\@latexerr{Option not supported}% + {}} +% \end{macrocode} +% +% \begin{macrocode} +\DeclareOption*{% + \PassOptionsToClass {\CurrentOption}{article}} +% \end{macrocode} +% +% \section{Configuration} +% Input a local configuration file, if it exists. +% \begin{macrocode} +\InputIfFileExists{ltxdoc.cfg} + {\typeout{*************************************^^J% + * Local config file ltxdoc.cfg used^^J% + *************************************}} + {} +% \end{macrocode} +% +% +% \section{Option Processing} +% +% \begin{macrocode} +\ProcessOptions +% \end{macrocode} +% +% \section{Loading article and doc} +% +% \begin{macrocode} +\LoadClass{article} +% \end{macrocode} +% +% \begin{macrocode} +\RequirePackage{doc} +% \end{macrocode} +% +% Make \verb+|+ be a `short verb' character, but not in the document +% preamble, where an active character may interfere with packages that +% are loaded. +% \begin{macrocode} +\AtBeginDocument{\MakeShortVerb{\|}} +% \end{macrocode} +% +% As `doc' documents tend to have a lot of monospaced material, +% Set up some |tt| substitutions to occur silently. +% \changes{v2.0p}{1995/11/02}{Add font substitutions} +% \changes{v2.0t}{1999/04/17}{Replaced octal number, CAR} +% \begin{macrocode} +\DeclareFontShape{OT1}{cmtt}{bx}{n}{<-> ssub * cmtt/m/n}{} +\DeclareFontFamily{OMS}{cmtt}{\skewchar\font 48} % '60 +\DeclareFontShape{OMS}{cmtt}{m}{n}{<-> ssub * cmsy/m/n}{} +\DeclareFontShape{OMS}{cmtt}{bx}{n}{<-> ssub * cmsy/b/n}{} +% \end{macrocode} +% This substitution is in the standard fd file, but not silent. +% \begin{macrocode} +\DeclareFontShape{OT1}{cmss}{m}{it}{<->ssub*cmss/m/sl}{} +% \end{macrocode} +% +% \begin{macrocode} +\CodelineNumbered +\DisableCrossrefs +% \end{macrocode} +% +% Increase the text width slightly so that with the standard fonts +% 72 columns of code may appear in a |macrocode| environment. +% \changes{v2.0c}{1994/03/15}{Set \cs{textwidth}.} +% \begin{macrocode} +\setlength{\textwidth}{355pt} +% \end{macrocode} +% +% Increase the marginpar width slightly, for long command names. +% And increase the left margin by a similar amount +% \changes{v2.0l} +% {1994/05/25}{Increase \cs{marginparwidth}} +% \changes{v2.0q}{1995/11/28} +% {Increase \cs{marginparwidth} and page margin.} +% \begin{macrocode} +\addtolength\marginparwidth{30pt} +\addtolength\oddsidemargin{20pt} +\addtolength\evensidemargin{20pt} +% \end{macrocode} +% +% +% \begin{macrocode} +\setcounter{StandardModuleDepth}{1} +% \end{macrocode} +% +% \section{Useful abbreviations} +% +% |\cmd{\foo}| Prints |\foo| verbatim. It may be used inside moving +% arguments. It can \emph{not} be use to record commands that are defined as +% ``|\outer|'' nor is it possible to use it on conditionals such as +% |\iftrue| or defined by |\newif|. +% |\cs{foo}| also prints |\foo|, for those who prefer that +% syntax. (This second form can be used to record all types of command so the +% above restrictions do not apply. +% \begin{macro}{\cmd} +% \changes{v2.0k}{1994/05/21}{New definition, so \cmd\{ works.} +% \begin{macro}{\cs} +% \changes{v2.0d}{1994/03/17}{Add \cs{cs}} +% \begin{macrocode} +\def\cmd#1{\cs{\expandafter\cmd@to@cs\string#1}} +\def\cmd@to@cs#1#2{\char\number`#2\relax} +\DeclareRobustCommand\cs[1]{\texttt{\char`\\#1}} +% \end{macrocode} +% \end{macro} +% \end{macro} +% +% \changes{v2.0r}{1996/01/11}{Removed \cs{star} since useless pr/2039} +% +% \begin{macro}{\marg} +% \changes{v2.0d}{1994/03/17}{Add \cs{marg}} +% |\marg{text}| prints \marg{text}, `mandatory argument'. +% \begin{macrocode} +\providecommand\marg[1]{% + {\ttfamily\char`\{}\meta{#1}{\ttfamily\char`\}}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\oarg} +% |\oarg{text}| prints \oarg{text}, `optional argument'. +% \begin{macrocode} +\providecommand\oarg[1]{% + {\ttfamily[}\meta{#1}{\ttfamily]}} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\parg} +% |\parg{te,xt}| prints \parg{te,xt}, `picture mode argument'. +% \changes{v2.0h}{1994/04/28}{Add \cs{parg}} +% \changes{v2.0o}{1995/08/09}{Use \cs{meta} when showing arguments} +% \begin{macrocode} +\providecommand\parg[1]{% + {\ttfamily(}\meta{#1}{\ttfamily)}} +% \end{macrocode} +% \end{macro} +% +% +% \section{Old Comments} +% +% The \LaTeXe\ sources contain a lot of code inherited from +% \LaTeX2.09. The comments in this code were not designed to be +% typeset, and do not contain the necessary \LaTeX\ markup. The +% \texttt{oldcomments} environment typesets these comments, +% automatically sensing when any control sequence appears, and +% implicitly adding the |\verb|. This procedure does not produce +% particularly beautiful pages, but it allows us to fully document new +% sections, and have some form of typeset comments on all the old +% code. +% \changes{v2.0e}{1994/03/18}{Use a fixed font.} +% +% Scan control names and put them in tt. +% Will actually (incorrectly) scan past |\\| but this does not matter as +% this is almost never followed by a letter in practice. +% (ie |\\foo|) would put |foo| in |\ttfamily|. +% \begin{macrocode} +\def\oc@scan#1{% + \ifx\oc@bslash#1% + \egroup\let\next\oc@bslash\else + \ifcat a\noexpand#1% + #1\let\next\oc@scan\else + \ifx\oc@percent#1% + \def\next{\char`\%\egroup}% + \else + #1\let\next\egroup + \fi\fi\fi\next} +% \end{macrocode} +% +% \begin{macrocode} +\def\oc@bslash{\bgroup\oc@ttf\char`\\\oc@scan}% +% \end{macrocode} +% +% \begin{macrocode} +\def\oc@verb#1{% + \catcode`#1\active + \uccode`\~`#1% + \uppercase{\def~{{\oc@ttf\char`#1}}}} +% \end{macrocode} +% +% \begin{macrocode} +\begingroup + \obeyspaces% + \catcode`\/=\catcode`\\ + /catcode`/\/active + /catcode`<=/catcode`{% + /catcode`>=/catcode`}% + /catcode`/{/active% + /catcode`/}/active% + /gdef/oldc< \end{oldcomments}>% + /gdef/begmac< \begin{macrocode}>% + /gdef/obs>>% +/endgroup% +% \end{macrocode} +% +% \begin{macrocode} +\begingroup + \catcode`\/=\catcode`\\ + \catcode`\\=13 + /catcode`/|=/catcode`/% + /catcode`/%=13 + /gdef/oldcomments{| + /makeatletter + /let/do/oc@verb/dospecials + /frenchspacing/@vobeyspaces/obs + /raggedright + /oc@verb/>| + /oc@verb/<| + /let\/oc@bslash + /let%/oc@percent + /obeylines + /parindent/z@ + /ttfamily/expandafter/let/expandafter/oc@ttf/the/font + /rmfamily + /hfuzz/maxdimen + } +/endgroup +% \end{macrocode} +% +% \begin{macrocode} +\begingroup + \sloppy% + \obeylines% + \gdef\oc@percent#1^^M{% + \ifvmode% + \def\commentline{#1}% + \ifx\commentline\oldc% + \end{oldcomments}% + \else% + \ifx\commentline\begmac% + \begin{macrocode}% + \else% + \leavevmode% + #1^^M% + \fi\fi% + \else% + {\oc@ttf\char`\%}#1^^M% + \fi}% +\endgroup% +% \end{macrocode} +% +% +% \section{DocInclude} +% +% \begin{macrocode} +\@addtoreset{CodelineNo}{part} +% \end{macrocode} +% +% \begin{macro}{\DocInclude} +% More or less exactly the same as |\include|, but uses |\DocInput| +% on a |dtx| file, not |\input| on a |tex| file. +% \changes{v2.0b}{1994/03/14}{Rename from \cs{docinclude}} +% \changes{v2.0f}{1994/03/25}{Use \cs{part}} +% \changes{v2.0u}{1999/08/08}{Also works for .fdd (M. Schroeder)} +% \begin{macrocode} +\def\partname{File} +% \end{macrocode} +% +% \begin{macrocode} +\newcommand*{\DocInclude}[1]{% + \relax + \clearpage + \docincludeaux + \IfFileExists{#1.fdd}% + {\def\currentfile{#1.fdd}}% + {\def\currentfile{#1.dtx}}% + \ifnum\@auxout=\@partaux + \@latexerr{\string\include\space cannot be nested}\@eha + \else \@docinclude#1 \fi} +\def\@docinclude#1 {\clearpage +\if@filesw \immediate\write\@mainaux{\string\@input{#1.aux}}\fi +\@tempswatrue\if@partsw \@tempswafalse\edef\@tempb{#1}\@for +\@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}\fi +\if@tempswa \let\@auxout\@partaux \if@filesw +\immediate\openout\@partaux #1.aux +\immediate\write\@partaux{\relax}\fi +% \end{macrocode} +% We need to save (and later restore) various index-related +% commands which might be changed by the included file. +% \begin{macrocode} +\let\@ltxdoc@PrintIndex\PrintIndex +\let\PrintIndex\relax +\let\@ltxdoc@PrintChanges\PrintChanges +\let\PrintChanges\relax +\let\@ltxdoc@theglossary\theglossary +\let\@ltxdoc@endtheglossary\endtheglossary +\part{\currentfile}% + {\let\ttfamily\relax + \xdef\filekey{\filekey, \thepart={\ttfamily\currentfile}}}% +\DocInput{\currentfile}% +\let\PrintIndex\@ltxdoc@PrintIndex +\let\PrintChanges\@ltxdoc@PrintChanges +\let\theglossary\@ltxdoc@theglossary +\let\endtheglossary\@ltxdoc@endtheglossary +\clearpage +\@writeckpt{#1}\if@filesw \immediate\closeout\@partaux \fi +\else\@nameuse{cp@#1}\fi\let\@auxout\@mainaux} +% \end{macrocode} +% +% \changes{v2.0x}{2018/03/15}{Set up \cs{protect} in index entries} +% \begin{macrocode} +\gdef\codeline@wrindex#1{\if@filesw +% \end{macrocode} +% Set \cs{protect} to a suitable value in the index entries (we +% can't use |\set@display@protect| as that would result in different +% numer of spaces after a command depending on the number of +% expansion happening prior to writing the index). +% \begin{macrocode} + \begingroup + \let\protect\noexpand + \immediate\write\@indexfile + {\string\indexentry{#1}% + {\filesep\number\c@CodelineNo}}% + \endgroup\fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +\let\filesep\@empty +% \end{macrocode} +% +% +% \begin{macro}{\aalph} +% Special form of |\alph| as currently |source2e.tex| +% includes more than 26 files +% \changes{v2.0n}{1994/05/27}{Use uppercase letters, for makeindex}. +% \begin{macrocode} +\def\aalph#1{\@aalph{\csname c@#1\endcsname}} +\def\@aalph#1{% + \ifcase#1\or a\or b\or c\or d\or e\or f\or g\or h\or i\or + j\or k\or l\or m\or n\or o\or p\or q\or r\or s\or + t\or u\or v\or w\or x\or y\or z\or A\or B\or C\or + D\or E\or F\or G\or H\or I\or J\or K\or L\or M\or + N\or O\or P\or Q\or R\or S\or T\or U\or V\or W\or + X\or Y\or Z\else\@ctrerr\fi} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\docincludeaux} +% \changes{v2.06}{1994/03/31}{Use \cs{footnotesize} in file key.} +% \changes{v2.0k}{1994/05/21}{Use \cs{aalph}} +% \changes{v2.0v}{2017/03/13}{Use \cs{parbox}[t] in file +% key to maintain space between the text block and the page foot.} +% \begin{macrocode} +\def\docincludeaux{% + \def\thepart{\aalph{part}}\def\filesep{\thepart-}% + \let\filekey\@gobble + \g@addto@macro\index@prologue{% + \gdef\@oddfoot{\parbox[t]{\textwidth}{\strut\footnotesize + \raggedright{\bfseries File Key:} \filekey}}% + \let\@evenfoot\@oddfoot}% + \global\let\docincludeaux\relax + \gdef\@oddfoot{% + \expandafter\ifx\csname ver@\currentfile\endcsname\relax + File \thepart: {\ttfamily\currentfile} % + \else + \GetFileInfo{\currentfile}% + File \thepart: {\ttfamily\filename} % + Date: \filedate\ % + Version \fileversion + \fi + \hfill\thepage}% + \let\@evenfoot\@oddfoot}% +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\MaintainedByLaTeXTeam} +% \changes{v2.0v}{2015/03/25}{macro added} +% \changes{v2.0w}{2015/03/25}{use display block not footnote text} +% Generate boilerplate reference to bug database. +% \begin{macrocode} +\def\MaintainedBy#1{\gdef\@maintainedby{#1}} +% \end{macrocode} +% +% \begin{macrocode} +\let\@maintainedby\@empty +% \end{macrocode} +% +% \begin{macrocode} +\def\MaintainedByLaTeXTeam#1{% +{\gdef\@maintainedby{% +This file is maintained by the \LaTeX{} Project team.\\% +Bug reports can be opened (category \texttt{#1}) at\\% +\url{https://latex-project.org/bugs.html}.}}} +% \end{macrocode} +% +% \begin{macrocode} +\def\@maketitle{% + \newpage + \null + \vskip 2em% + \begin{center}% + \let \footnote \thanks + {\LARGE \@title \par}% + \vskip 1.5em% + {\large + \lineskip .5em% + \begin{tabular}[t]{c}% + \@author + \end{tabular}\par}% + \vskip 1em% + {\large \@date}% + \ifx\@maintainedby\@empty + \else + \vskip 1em% + \fbox{\fbox{\begin{tabular}{@{}l@{}}\@maintainedby\end{tabular}}}% + \fi + \end{center}% + \par + \vskip 1.5em} +% \end{macrocode} +% \end{macro} +% +% \begin{macro}{\url} +% \begin{macrocode} +\providecommand\url{\texttt} +% \end{macrocode} +% \end{macro} +% +% \begin{macrocode} +\def\task#1#2{} +% +% \end{macrocode} +% \Finale +% -- cgit v1.2.3