diff options
Diffstat (limited to 'Master/texmf-doc/doc/english/dtxtut/dtxtut.tex')
-rw-r--r-- | Master/texmf-doc/doc/english/dtxtut/dtxtut.tex | 2075 |
1 files changed, 0 insertions, 2075 deletions
diff --git a/Master/texmf-doc/doc/english/dtxtut/dtxtut.tex b/Master/texmf-doc/doc/english/dtxtut/dtxtut.tex deleted file mode 100644 index 1dc4ea129a9..00000000000 --- a/Master/texmf-doc/doc/english/dtxtut/dtxtut.tex +++ /dev/null @@ -1,2075 +0,0 @@ -%%% ==================================================================== -%%% @LaTeX-file{ -%%% author = "Scott Pakin", -%%% version = "2.0a", -%%% date = "05 November 2004", -%%% time = "01:36:46 MST", -%%% filename = "dtxtut.tex", -%%% checksum = "54933 2075 7618 70409" -%%% email = "scott+dtx@pakin.org (Internet)", -%%% codetable = "ISO/ASCII", -%%% keywords = "LaTeX, packages, .ins files, .dtx files, -%%% literate programming", -%%% supported = "yes", -%%% abstract = "This tutorial is intended for advanced -%%% LaTeX 2e users who want to learn how to -%%% create .ins and .dtx files for distributing -%%% their homebrewed classes and style files.", -%%% docstring = "The checksum field above contains a CRC-16 -%%% checksum as the first value, followed by -%%% the equivalent of the standard UNIX wc -%%% (word count) utility output of lines, -%%% words, and characters. This is produced by -%%% Robert Solovay's checksum utility. This file -%%% header was produced with the help of Nelson -%%% Beebe's filehdr utility. Both checksum and -%%% filehdr are available from CTAN -%%% (http://www.ctan.org)." -%%% -%%% } -%%% ==================================================================== - -\documentclass[11pt]{ltxguide} -\usepackage{varioref} -\usepackage{makeidx} -\usepackage{alltt} -\IfFileExists{tocbibind.sty}{\usepackage{tocbibind}}{} -\IfFileExists{hyperref.sty}{\usepackage[bookmarksopen]{hyperref}}{} - -\title{How to Package Your \LaTeX{} Package} -\author{Scott Pakin \texttt{<scott+dtx@pakin.org>}} -\date{5 November 2004} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -% Define a term. -\newcommand{\defn}[2][X]{% - \ifx#1X - \emph{#2}\index{#2}% - \else - \emph{#2}\index{#1}% - \fi -} - -% Make a version of \dots that allows a subsequent line break. -\newcommand{\dotsbrk}{\dots\linebreak[0]} - -% If we have url.sty loaded, use that for formatting URLs. -\ifx\url\undefined -\else - \let\URL=\url -\fi - -% Define formatting for various packages. -\newcommand{\DOC}{\textsf{Doc}\index{Doc@\textsf{Doc}}} -\newcommand{\ds}{\textsf{DocStrip}\index{DocStrip@\textsf{DocStrip}}} -\newcommand{\svrb}{\texttt{shortvrb}\index{shortvrb@\texttt{shortvrb}}} - -% Customize varioref's messages. -\def\reftextbefore{on the preceding page} -\def\reftextfacebefore{on the preceding page} -\def\reftextcurrent{above} % We promise not to make any forward references. - -% Define some macros to help automate indexing. -\makeindex -{\catcode`\|=0 \catcode`\\=12 - |gdef|bslash{\}} -\newcommand{\defmacro}[1]{% % Define a macro. - \texttt{\bslash#1}% - \index{#1@\texttt{\string\bslash{}#1}}% -} -\newcommand{\usemacro}[1]{% % Use a macro. - \texttt{\bslash#1}% - \index{#1@\texttt{\string\bslash{}#1}}% -} -\newcommand{\indexmacro}[1]{% % Index a macro (no display). - \index{#1@\texttt{\string\bslash{}#1}}% -} -{\catcode`\|=12 % Same as \indexmacro, but - \gdef\indexmacroBegin#1{% % for ranges of text - \index{#1@\texttt{\string\bslash{}#1}|(}% - } - \gdef\indexmacroEnd#1{% - \index{#1@\texttt{\string\bslash{}#1}|)}% - } -} -\newcommand{\defthing}[1]{% % Define a non-macro thing. - \texttt{#1}% - \index{#1@\texttt{#1}}% -} -\newcommand{\usething}[1]{% % Use a non-macro thing. - \texttt{#1}% - \index{#1@\texttt{#1}}% -} -\newcommand{\indexthing}[1]{% % Index a non-macro thing. - \index{#1@\texttt{#1}}% -} -{\catcode`\|=12 % Same as \indexthing, but - \gdef\indexthingBegin#1{% % for ranges of text - \index{#1@\texttt{#1}|(}% - } - \gdef\indexthingEnd#1{% - \index{#1@\texttt{#1}|)}% - } -} - -% Define shortcuts to index commonly used terms. -\newcommand{\insfile}{% - \texttt{.ins}\index{installer file}} -\newcommand{\dtxfile}{% - \texttt{.dtx}\index{documented LaTeX file@documented \string\LaTeX{} file}} -\newcommand{\styfile}{% - \texttt{.sty}\index{style file}} -\newcommand{\clsfile}{% - \texttt{.cls}\index{class file}} -\newcommand{\CTAN}{% - CTAN\index{Comprehensive \string\TeX{} Archive Network}} -\newcommand{\swiftexel}{% - \texttt{swiftex.el}\index{swiftex.el@\texttt{swiftex.el}}} -\newcommand{\Emacs}{% - Emacs\index{Emacs}} -\newcommand{\latex}[1][\LaTeX]{% - #1\index{LaTeX@\LaTeX}} - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{document} -\sloppy -\maketitle - -\begin{abstract} - This tutorial is intended for advanced \latex[\LaTeXe]{} users who - want to learn how to create \insfile{} and \dtxfile{} files for - distributing their homebrewed classes and style files. -\end{abstract} - - -\section{Introduction} - -\paragraph{Requirements} -We assume that you already know how to \emph{program} in \latex\@. -That is, you should know how to use \usemacro{newcommand}, -\usemacro{newenvironment}, and preferably a smidgen of \TeX\@. You -should also be familiar with ``\clsguide'', which is available from -\CTAN{} (\URL{http://www.ctan.org}) and comes with most -\latex[\LaTeXe]{} distributions in a file called |clsguide.dvi|. -Finally, you should know how to install packages\index{package} that -are shipped as a \dtxfile{} file plus a \insfile{} file. - -\index{package|(} -\paragraph{Terminology} -A \defn[style file]{style \textnormal{(\styfile{})} file} is primarily a -collection of macro and environment definitions. One or more style -files (\eg a main style file that \usemacro{input}s or -\usemacro{RequirePackage}s multiple helper files) is called a -\defn{package}. Packages are loaded into a document with -\usemacro{usepackage}|{<main .sty file>}|\index{style file}. In the -rest of this document, we use the notation ``\m{package}'' to -represent the name of your package. -\index{package|)} - -\paragraph{Motivation} -The important parts of a package\index{package} are the code, the -documentation of the code, and the user documentation. Using the -\DOC{} and \ds{} programs, it's possible to combine all three of these -into a single, \defn[documented LaTeX file@documented \string\LaTeX{} -file]{documented \LaTeX \textnormal{(\dtxfile{})} file}. The primary -advantage of a \dtxfile{} file is that it enables you to use arbitrary -\latex{} constructs to comment\index{comments} your code. Hence, -macros, environments, code stanzas, variables, and so forth can be -explained using tables, figures, mathematics, and font changes. Code -can be organized into sections using \latex's sectioning commands. -\index{indexing|(} -\DOC{} even facilitates generating a unified index that indexes both -macro definitions (in the \latex{} code) and macro descriptions (in -the user documentation). -\index{indexing|)} -This emphasis on writing verbose, nicely typeset -comments\index{comments} for code---essentially treating a program as -a book that describes a set of algorithms---is known as \defn{literate -programming}~\cite{Knuth1984:literate} and has been in use since the -early days of \TeX. - -This tutorial will teach you how to write basic \dtxfile{} files and -the \insfile{} files that manipulate them. Although there is much -overlap with chapter~14 of \emph{The \latex{} -Companion}~\cite{Goossens1994:companion}, this document is structured -as a step-by-step tutorial, while \emph{The \latex{} Companion} is -more reference-like. Furthermore, this tutorial shows how to write a -single file that serves as both documentation and driver file, which -is a more typical usage of the \DOC{} system than using separate -files. - - -\index{installer file|(} - -\section{The \texttt{.ins} file} -\label{sec:ins-file} - -The first step in preparing a package for distribution is to write an -\defn[installer file]{installer \textnormal{(\insfile{})} file}. An -installer file extracts the code from a \dtxfile{} file, uses \ds{} to -strip off the comments\index{comments} and documentation, and outputs -a \styfile{} file. The good news is that a \insfile{} file is -typically fairly short and doesn't change significantly from one -package\index{package} to another. - -\index{license|(} -\insfile{} files usually start with comments\index{comments} -specifying the copyright\index{copyright} and license information: - -\begin{verbatim} - %% - %% Copyright (C) <year> by <your name> - %% - %% This file may be distributed and/or modified under the - %% conditions of the LaTeX Project Public License, either - %% version 1.2 of this license or (at your option) any later - %% version. The latest version of this license is in: - %% - %% http://www.latex-project.org/lppl.txt - %% - %% and version 1.2 or later is part of all distributions of - %% LaTeX version 1999/12/01 or later. - %% -\end{verbatim} - -\noindent -\index{package|(} -The \latex{} Project Public License\index{LaTeX Project Public -License@\LaTeX{} Project Public License} (LPPL) is the license under -which most packages---and \latex{} itself---are distributed. Of -course, you can release your package under any license you want; the -LPPL is merely the most common license for \latex{} packages. The -LPPL specifies that a user can do whatever he wants with your -package---including sell it and give you nothing in return. The only -restrictions are that he must give you credit for your work, and he -must change the name of the package if he modifies anything to avoid -versioning confusion. -\index{package|)} -\index{license|)} -\index{LPPL|see{\LaTeX{} Project Public License}} - -The next step is to load \ds: - -\begin{verbatim} - \input docstrip.tex -\end{verbatim} - - -\indexmacroBegin{keepsilent} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - \defmacro{keepsilent} -\end{decl} - -By default, \ds{} gives a line-by-line account of its activity. These -messages aren't terribly useful, so most people turn them off: - -\begin{verbatim} - \keepsilent -\end{verbatim} - -\indexmacroEnd{keepsilent} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{usedir} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - \defmacro{usedir} \arg{directory} -\end{decl} - -A system administrator can specify the base directory under which all -\TeX-related files should be installed, \eg |/usr/share/texmf|. (See -``\usemacro{BaseDirectory}'' in the \ds{} manual.) The \insfile{} -file specifies where its files should be installed relative to that. -The following is typical: - -\begin{verbatim} - \usedir{tex/latex/<package>} -\end{verbatim} - -\indexmacroEnd{usedir} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{preamble} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{endpreamble} - -\begin{decl} - \defmacro{preamble} \\ - \m{text} \\ - \defmacro{endpreamble} -\end{decl} - -\index{comments|(} -The next step is to specify a \defn{preamble}, which is a block of -commentary that will be written to the top of every generated file: - -\begin{verbatim} - \preamble - - This is a generated file. - - Copyright (C) <year> by <your name> - - This file may be distributed and/or modified under the - conditions of the LaTeX Project Public License, either - version 1.2 of this license or (at your option) any later - version. The latest version of this license is in: - - http://www.latex-project.org/lppl.txt - - and version 1.2 or later is part of all distributions of - LaTeX version 1999/12/01 or later. - - \endpreamble -\end{verbatim} - -\index{comments|)} - -\noindent -The preceding preamble would cause |<package>.sty|\index{style file} -to begin as follows: - -\begin{verbatim} - %% - %% This is file `<package>.sty', - %% generated with the docstrip utility. - %% - %% The original source files were: - %% - %% <package>.dtx (with options: `package') - %% - %% This is a generated file. - %% - %% Copyright (C) <year> by <your name> - %% - %% This file may be distributed and/or modified under the - %% conditions of the LaTeX Project Public License, either - %% version 1.2 of this license or (at your option) any later - %% version. The latest version of this license is in: - %% - %% http://www.latex-project.org/lppl.txt - %% - %% and version 1.2 or later is part of all distributions of - %% LaTeX version 1999/12/01 or later. - %% -\end{verbatim} - -\indexmacroEnd{endpreamble} -\indexmacroEnd{preamble} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{generate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{file} -\indexmacroBegin{from} - -\begin{decl} - \defmacro{generate} - |{|\defmacro{file} |{<style-file>}| - |{|\defmacro{from} |{<dtx-file>}| |{<tag>}}}| -\end{decl} - -We now reach the most important part of a \insfile{} file: the -specification of what files to generate from the \dtxfile{} file. The -following tells \ds{} to generate |<package>.sty|\index{style file} -from |<package>.dtx| by extracting only those parts marked as -``|package|'' in the \dtxfile{} file. (Marking parts of a \dtxfile{} -file is described in Section~\ref{sec:dtx-file}.) - -\label{code:generate} -\begin{verbatim} - \generate{\file{<package>.sty}{\from{<package>.dtx}{package}}} -\end{verbatim}% -\index{style file} - -\noindent -\usemacro{generate} can extract any number of files from a given -\dtxfile{} file. It can even extract a single file from multiple -\dtxfile{} files. See the \ds{} manual for details. - -\indexmacroEnd{from} -\indexmacroEnd{file} -\indexmacroEnd{generate} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{Msg} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - \defmacro{Msg} \arg{text} -\end{decl} - -The next part of a \insfile{} file consists of commands to output a -message to the user, telling him what files need to be installed and -reminding him how to produce the user documentation. The following -set of \usemacro{Msg} commands is typical: - -\begin{verbatim} - \obeyspaces - \Msg{****************************************************} - \Msg{* *} - \Msg{* To finish the installation you have to move the *} - \Msg{* following file into a directory searched by TeX: *} - \Msg{* *} - \Msg{* <package>.sty *} - \Msg{* *} - \Msg{* To produce the documentation run the file *} - \Msg{* <package>.dtx through LaTeX. *} - \Msg{* *} - \Msg{* Happy TeXing! *} - \Msg{* *} - \Msg{****************************************************} -\end{verbatim}% -\index{style file}% - -\indexmacroEnd{Msg} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -Note the use of \usemacro{obeyspaces} to inhibit \TeX{} from -collapsing multiple spaces into one. - - -\indexmacroBegin{endbatchfile} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - \usemacro{endbatchfile} -\end{decl} - -Finally, we tell \ds{} that we've reached the end of the \insfile{} file: - -\begin{verbatim} - \endbatchfile -\end{verbatim} - -\indexmacroEnd{endbatchfile} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -Appendix~\ref{sec:skeleton-ins-file-style} lists a complete, skeleton -\insfile{} file. Appendix~\ref{sec:skeleton-ins-file-class} is -similar but contains slight modifications intended to produce a class -(\clsfile) file instead of a style (\styfile) file. - -\index{installer file|)} -\index{documented LaTeX file@documented \LaTeX{} file|(} - - -\section{The \texttt{.dtx} file} -\label{sec:dtx-file} - -\index{package|(} -A \dtxfile{} file contains both the commented source code and the user -documentation for the package. Running a \dtxfile{} file through -|latex| typesets the user documentation, which usually also includes a -nicely typeset version of the commented\index{comments} source code. -\index{package|)} - -Due to some \DOC{} trickery, a \dtxfile{} file is actually evaluated -\emph{twice}. The first time, only a small piece of \latex{} driver -code is evaluated. The second time, \emph{comments}\index{comments} -in the \dtxfile{} file are evaluated, as if there were no ``|%|'' -preceding them. This can lead to a good deal of confusion when -writing \dtxfile{} files and occasionally leads to some awkward -constructions. Fortunately, once the basic structure of a \dtxfile{} file -is in place, filling in the code is fairly straightforward. - - -\subsection{Prologue} - -\index{comments|(} - -\dtxfile{} files generally begin with a copyright\index{copyright} and -license\index{license} comment: - -\begin{verbatim} - % \iffalse meta-comment - % - % Copyright (C) <year> by <your name> - % - % This file may be distributed and/or modified under the - % conditions of the LaTeX Project Public License, either - % version 1.2 of this license or (at your option) any later - % version. The latest version of this license is in: - % - % http://www.latex-project.org/lppl.txt - % - % and version 1.2 or later is part of all distributions of - % LaTeX version 1999/12/01 or later. - % - % \fi -\end{verbatim} - -\index{comments|)} - -\noindent -The \usemacro{iffalse} and |\fi| are needed because the second time -the \dtxfile{} file is processed, |%| characters at the beginning of lines -are ignored. To prevent the -copyright\index{copyright}/license\index{license} from being evaluated -as \latex{} code, we have to surround it with -\usemacro{iffalse}\dotsbrk|\fi|. Adding ``\usething{meta-comment}'' -after ``\usemacro{iffalse}'' is nothing more than a convention for -indicating that the comment\index{comments} is intended to be read by -a human, not by \DOC{}, \ds{}, or \latex. - -\indexmacroBegin{NeedsTeXFormat} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{ProvidesPackage} - -\begin{decl} - \defmacro{NeedsTeXFormat} \arg{format-name} \oarg{release-date} \\ - \defmacro{ProvidesPackage} \arg{package-name} \oarg{release-info} -\end{decl} - -The next few lines are also surrounded by -\usemacro{iffalse}\dotsbrk|\fi| so as not to be processed by |latex| -on the second pass through the \dtxfile{} file. However, these lines are -intended not for a human reader, but for \ds{} (hence, no -``\usething{meta-comment}''): - -\label{code:ProvidesPackage} -\begin{verbatim} - % \iffalse - %<<package>>\NeedsTeXFormat{LaTeX2e}[1999/12/01] - %<<package>>\ProvidesPackage{<package>} - %<<package>> [<YYYY>/<MM>/<DD> v<version> <description>] - % -\end{verbatim}% -\indexmacro{NeedsTeXFormat}% -\indexmacro{ProvidesPackage} - -\noindent -(We'll encounter the |\fi| shortly.) - -Remember the \usemacro{generate} line in the \insfile{} file -(page~\pageref{code:generate})? It ended with the tag ``|package|''. -This tells \ds{} to write lines that begin with ``|%<<package>>|'' to -the \styfile{} file, stripping off the ``|%<<package>>|'' in the -process. Hence, our \styfile{} file will begin with the following: - -\begin{verbatim} - \NeedsTeXFormat{LaTeX2e}[1999/12/01] - \ProvidesPackage{<package>} - [<YYYY>/<MM>/<DD> v<version> <description>] -\end{verbatim}% -\indexmacro{NeedsTeXFormat}% -\indexmacro{ProvidesPackage} - -\noindent -For example: - -\begin{verbatim} - \NeedsTeXFormat{LaTeX2e}[1999/12/01] - \ProvidesPackage{skeleton} - [2002/03/25 v1.0 .dtx skeleton file] -\end{verbatim}% -\label{code:ProvidesPackage-example}% -\indexmacro{NeedsTeXFormat}% -\indexmacro{ProvidesPackage} - -\noindent -\index{package|(} -The \usemacro{NeedsTeXFormat} line ensures that the package won't run -under a version of \latex[\LaTeXe]{} older than what the package was -tested with. The date and version strings in the -\usemacro{ProvidesPackage} line are used by \DOC{} to set the -\usemacro{filedate} and \usemacro{fileversion} macros. Note the -date\index{date format} format; \emph{YYYY/MM/DD} is used throughout -\latex[\LaTeXe]{} and should be used in your packages as well. -\index{package|)} - -\indexmacroEnd{ProvidesPackage} -\indexmacroEnd{NeedsTeXFormat} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{EnableCrossrefs} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{CodelineIndex} -\indexmacroBegin{RecordChanges} -\indexmacroBegin{DocInput} - -\begin{decl} - \defmacro{EnableCrossrefs} \\ - \defmacro{CodelineIndex} \\ - \defmacro{RecordChanges} \\ - \defmacro{DocInput} \arg{filename} \label{desc:CodelineIndex} -\end{decl} - -Next comes the only part of the \dtxfile{} file that isn't commented out -(\ie doesn't begin each line with |%|): - -\begin{verbatim} - %<<*driver>> - \documentclass{ltxdoc} - \usepackage{<package>} - \EnableCrossrefs - \CodelineIndex - \RecordChanges - \begin{document} - \DocInput{<package>.dtx} - \end{document} - %<</driver>> - % \fi -\end{verbatim} - -The preceding code stanza is what |latex| evaluates on its first pass -through the \dtxfile{} file. We'll now examine that stanza line-by-line: - -\begin{enumerate} - \item Putting code between ``|%<<*driver>>|'' and ``|%<</driver>>|'' - is a \ds{} shorthand for prefixing each line with ``|%<<driver>>|''. - This demarcates the \DOC{} driver\index{driver code} code. - - \item The \usemacro{documentclass} should almost always be - \usething{ltxdoc}, as that loads \DOC{} and provides a few useful - macros for formatting program documentation. - -\index{package|(} - \item You should always \usemacro{usepackage} your package. If you - don't, \DOC{} won't see the package's \usemacro{ProvidesPackage} - line and won't know how to set \usemacro{filedate} and - \usemacro{fileversion} (see page~\pageref{code:GetFileInfo}). This - is also where you should \usemacro{usepackage} any other packages - needed to typeset the user documentation. -\index{package|)} - - \item \usemacro{EnableCrossrefs} tells \DOC{} that you want it to - construct an index for your code---normally a good idea. The - alternative is \usemacro{DisableCrossrefs}, which speeds up - processing by a negligible amount. - - \item \usemacro{CodelineIndex} tells \DOC{} that the index should - refer to program line numbers instead of page numbers. (The - alternative is \usemacro{PageIndex}.) \usemacro{CodelineIndex} - makes index entries easier to find at the expense of making the - index less self-consistent (because descriptions of macros and - environments are always indexed by page number). The index does, - however, begin with a note of explanation. - - \item \label{item:RecordChanges} On page~\pageref{code:changes}, - we'll see how to log the changes made in each revision of the - package\index{package}. \usemacro{RecordChanges} tells \DOC{} that - it should keep and aggregate the log entries. - - \item There should be only one command between the - |\begin{document}| and |\end{document}|: a \usemacro{DocInput} call - with which the \dtxfile{} file inputs itself. This enables a master - file to \usemacro{DocInput} multiple files in order to produce a - single document that covers more than one package\index{package} but - contains a unified index\index{indexing}. Master documentation - files are described~\vpageref{sec:master-files}. -\end{enumerate} - -\indexmacroEnd{DocInput} -\indexmacroEnd{RecordChanges} -\indexmacroEnd{CodelineIndex} -\indexmacroEnd{EnableCrossrefs} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{OnlyDescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - \defmacro{OnlyDescription} \label{desc:OnlyDescription} -\end{decl} - -Another command that sometimes appears in the preamble (\ie before the -|\begin{document}|) is \usemacro{OnlyDescription}, which tells \DOC{} -to typeset only the user documentation, not the package\index{package} -code/comments\index{comments}. It's usually best to omit -\usemacro{OnlyDescription} (or add it commented out). A user can -always add it manually or even enable \usemacro{OnlyDescription} for -\emph{all} \dtxfile{} files by adding the following to his -\defthing{ltxdoc.cfg} file: - -\begin{verbatim} - \AtBeginDocument{\OnlyDescription} -\end{verbatim}% -\indexmacro{AtBeginDocument} - -\indexmacroEnd{OnlyDescription} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\bigskip -The remainder of this section covers |latex|'s second pass through the -\dtxfile{} file. Consequently, all subsequent examples are prefixed -with percent signs. - -\indexmacroBegin{CheckSum} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\index{checksumming|(} - -\begin{decl} - \defmacro{CheckSum} \arg{number} \label{decl:CheckSum} -\end{decl} - -\DOC{} supports a very simplistic form of document checksumming, to -help ensure that a package\index{package} didn't get corrupted in -transport. \DOC{} merely counts the number of backslashes that occur -in the code. If the number matches the checksum, \DOC{} gives a -success message: - -\begin{verbatim} - ******************* - * Checksum passed * - ******************* -\end{verbatim} - -\noindent -Otherwise, it says what the correct checksum should be: - -\begin{verbatim} - ! Package doc Error: Checksum not passed (<incorrect><<>><correct>). -\end{verbatim}% -\indexthing{Checksum not passed} - -\noindent -To specify the checksum in a \dtxfile{} file, merely add a \usemacro{CheckSum} -statement: - -\begin{verbatim} - % \CheckSum{<number>} -\end{verbatim} - -\noindent -If \m{number} is~|0|, or if the \dtxfile{} file lacks a -\usemacro{CheckSum} line entirely, then \DOC{} outputs the following -warning message: - -\begin{verbatim} - ********************************** - * This macro file has no checksum! - * The checksum should be <number>! - ********************************** -\end{verbatim} - -\noindent -During code development it is convenient to specify |\CheckSum{0}| so -you don't receive an error message every time you run |latex|. But -don't forget to replace ``|0|'' with the correct number before -releasing your package\index{package}! - -\index{checksumming|)} -\indexmacroEnd{CheckSum} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{CharacterTable} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - \defmacro{CharacterTable} \arg{text} -\end{decl} - -The second mechanism that \DOC{} uses to ensure that a \dtxfile{} file -is uncorrupted is a character table. If you put the following command -verbatim into your \dtxfile{} file, then \DOC{} will ensure that no -unexpected character translation took place in transport:\footnote{The -character table is commonly prefixed with double percent signs so that -it gets written to the \texttt{.sty}\index{style file} file. This -seems unnecessary and is therefore shown here with single percent -signs.} - -\begin{verbatim} - % \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 \~} -\end{verbatim} - -\noindent -A success message looks like this: - -\begin{verbatim} - *************************** - * Character table correct * - *************************** -\end{verbatim} - -\noindent -and an error message looks like this: - -\begin{verbatim} - ! Package doc Error: Character table corrupted. -\end{verbatim}% -\indexthing{Character table corrupted} - -\indexmacroEnd{CharacterTable} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{changes} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - \defmacro{changes} \arg{version} \arg{date} \arg{description} - \label{code:changes} -\end{decl} - -\index{package|(} - -On page~\pageref{item:RecordChanges} we learned that \DOC{} has a -mechanism for recording changes to the package. The command is -``|\changes{<version>}{<date>}{<description>}|'', and it's common to -use \usemacro{changes} for the initial version of the package to log -the package's creation date: - -\index{package|)} - -\begin{verbatim} - % \changes{v1.0}{2002/03/25}{Initial version} -\end{verbatim} - -One nice feature of the \usemacro{changes} command is that it knows -whether it was used internally to a macro/environment definition. As -Figure~\ref{fig:change-history} shows, top-level changes are prefixed -with ``General:'', and internal changes are prefixed with the name of -the enclosing macro or environment. - -\begin{figure}[htbp] - \centering - \index{change history} - \fbox{% - \begin{minipage}[t]{0.75\textwidth} - {\normalfont\Large\bfseries Change History\vskip 2.3ex plus 0.2ex} - v1.0 \\ - \hspace*{2em} General: Top-level comment \dotfill 1 \\ - v1.2j \\ - \hspace*{2em} \texttt{myMacro}: Internal macro comment \dotfill 5 - \end{minipage}% - }% - \caption{Sample change history} - \label{fig:change-history} -\end{figure} - -\indexmacroEnd{changes} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{GetFileInfo} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{filedate} -\indexmacroBegin{fileversion} -\indexmacroBegin{fileinfo} - -\begin{decl} - \defmacro{GetFileInfo} \arg{style-file} \label{code:GetFileInfo} \\[1ex] - \defmacro{filedate} \\ - \defmacro{fileversion} \\ - \defmacro{fileinfo} -\end{decl} - -Next, we tell \DOC{} to parse the \usemacro{ProvidesPackage} command -(page~\pageref{code:ProvidesPackage}), calling the three components of -\usemacro{ProvidesPackage}'s argument, respectively, -``\usemacro{filedate}'', ``\usemacro{fileversion}'', and -``\usemacro{fileinfo}'': - -\begin{verbatim} - % \GetFileInfo{<package>.sty} -\end{verbatim}% -\index{style file}% -\indexmacro{GetFileInfo} - -\noindent -For instance, the \usemacro{ProvidesPackage} example -shown~\vpageref{code:ProvidesPackage-example} would be parsed as -follows: - -| |% -\begin{tabular}{@{}l@{\qquad$\equiv$\qquad}l@{}} - \usemacro{filedate} & 2002/03/25 \\ - \usemacro{fileversion} & v1.0 \\ - \usemacro{fileinfo} & .dtx skeleton file -\end{tabular} - -\indexmacroEnd{fileinfo} -\indexmacroEnd{fileversion} -\indexmacroEnd{filedate} -\indexmacroEnd{GetFileInfo} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{DoNotIndex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\index{indexing|(} - -\begin{decl} - \defmacro{DoNotIndex} \arg{macro-name \textnormal{, \dots}} -\end{decl} - -When producing an index, \DOC{} normally indexes \emph{every} control -sequence (\ie backslashed word or symbol) in the code. The problem -with this level of automation is that many control sequences are -uninteresting from the perspective of understanding the code. For -example, a reader probably doesn't want to see every location where -|\if| is used---or |\the| or |\let| or |\begin| or any of numerous -other control sequences. - -As its name implies, the \usemacro{DoNotIndex} command gives \DOC{} a -list of control\index{control sequences} sequences that should not be -indexed. \usemacro{DoNotIndex} can be used any number of times, and -it accepts any number of control\index{control sequences} sequence -names per invocation: - -\begin{verbatim} - % \DoNotIndex{\#,\$,\%,\&,\@,\\,\{,\},\^,\_,\~,\ } - % \DoNotIndex{\@ne} - % \DoNotIndex{\advance,\begingroup,\catcode,\closein} - % \DoNotIndex{\closeout,\day,\def,\edef,\else,\empty,\endgroup} -\end{verbatim} -\centerline{$\vdots$} - -\index{indexing|)} -\indexmacroEnd{DoNotIndex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\subsection{User documentation} - -We can finally start writing the user documentation. A typical -beginning looks like this: - -\begin{verbatim} - % \title{The \textsf{<package>} package\thanks{This document - % corresponds to \textsf{<package>}~\fileversion, - % dated~\filedate.}} - % \author{<your name> \\ \texttt{<your e-mail address>}} - % - % \maketitle -\end{verbatim}% -\indexmacro{title} -\indexmacro{author} -\indexmacro{maketitle} - -\noindent -\index{package|(} -The title can certainly be more creative, but note that it's common -for package names to be typeset with \usemacro{textsf} and for -\usemacro{thanks} to be used to specify the package version and date. -This yields one of the advantages of literate\index{literate -programming} programming: Whenever you change the package version (the -optional second argument to \usemacro{ProvidesPackage}), the user -documentation is updated accordingly. Of course, you still have to -ensure manually that the user documentation accurately describes the -updated package. -\index{package|)} - -Write the user documentation as you would any \latex{} document, -except that you have to precede each line with a ``|%|''. Note that -the \usething{ltxdoc} document class is derived from |article|, so the -top-level sectioning command is \usemacro{section}, not -\usemacro{chapter}. - - -\indexmacroBegin{DescribeMacro} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{DescribeEnv} - -\begin{decl} - \defmacro{DescribeMacro} \arg{macro} \\ - \defmacro{DescribeEnv} \arg{environment} -\end{decl} - -\DOC{} provides a couple of commands to help format user -documentation. If you include -``|\DescribeMacro{<macro>}|''\footnote{``\m{macro}'' should include -the backslash.} within a paragraph, \DOC{} will stick ``\m{macro}'' in -the margin to make it easy for a reader to see. \DOC{} will also add -\m{macro} to the index and format the corresponding page number to -indicate that this is where the macro is described (as opposed to the -place in the source code where the macro is defined). - -\usemacro{DescribeEnv} is the analogous command for describing an -environment. Both \usemacro{DescribeMacro} and \usemacro{DescribeEnv} -can be used multiple times within a paragraph. - -\indexmacroEnd{DescribeEnv} -\indexmacroEnd{DescribeMacro} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexmacroBegin{marg} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{oarg} -\indexmacroBegin{parg} -\indexmacroBegin{meta} - -\begin{decl} - \defmacro{marg} \arg{argument} \\ - \defmacro{oarg} \arg{argument} \\ - \defmacro{parg} \arg{argument} \\ - \defmacro{meta} \arg{text} -\end{decl} - -The \usething{ltxdoc} document class provides three commands to help -typeset macro and environment syntax -(Table~\ref{tbl:argument-formatting}). \usemacro{marg} formats -mandatory arguments, \usemacro{oarg} formats optional arguments, and -\usemacro{parg} formats picture arguments. All three of these utilize -\usemacro{meta} to typeset the argument proper. \usemacro{meta} is -also useful on its own. For example, ``\texttt{This needs a} -|\meta{dimen}|.'' is typeset as ``This needs a \m{dimen}.'' - -\begin{table}[htbp] - \centering - \caption{Argument-formatting commands} - \label{tbl:argument-formatting} - \begin{tabular}{@{}ll@{}} - \hline - \multicolumn{1}{@{}c}{Command} & - \multicolumn{1}{c@{}}{Result} \\ - \hline - \usemacro{marg}|{text}| & |{<text>}| \\ - \usemacro{oarg}|{text}| & |[<text>]| \\ - \usemacro{parg}|{text}| & |(<text>)| \\ - \hline - \end{tabular} -\end{table} - -In addition to those commands, \DOC{} facilitates the typesetting of -macro descriptions by automatically loading the \svrb{} -package\index{package}. \svrb{} lets you use \verb+|+\dots\verb+|+ -as a convenient shorthand for |\verb|\verb+|+\dots\verb+|+. For -instance, ``\verb+|\mymacro|+ |\oarg{pos}| |\marg{width}| -|\marg{text}|'' is typeset as follows: - -\begin{verbatim} - \mymacro [<pos>] {<width>} {<text>} -\end{verbatim} - -\noindent -Like \usemacro{verb}, the \verb+|+\dots\verb+|+ shorthand does not -work within \usemacro{footnote} or other fragile macros. - -\indexmacroEnd{meta} -\indexmacroEnd{parg} -\indexmacroEnd{oarg} -\indexmacroEnd{marg} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\subsection{Code and commentary} - -\indexmacroBegin{StopEventually} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexmacroBegin{Finale} - -\begin{decl} - \defmacro{StopEventually} |{<text>}| \\ - \defmacro{Finale} -\end{decl} - -The package's\index{package} source code is delineated by putting it -between \usemacro{StopEventually} and \usemacro{Finale}. Note that -\usemacro{CheckSum} (page~\pageref{decl:CheckSum}) applies only to the -package's\index{package} source code. \usemacro{StopEventually} takes -an argument, which is a block of text to typeset after the code. If -\usemacro{OnlyDescription} (page~\pageref{desc:OnlyDescription}) is -specified, then nothing after the \usemacro{StopEventually} will be -output---including text that follows \usemacro{Finale}. -\usemacro{StopEventually}'s \m{text} parameter is therefore the -mechanism for providing a piece of text that should be output -regardless of whether or not a code listing is typeset. It commonly -includes a bibliography section and/or one or more of the following -commands. - -\indexmacroEnd{Finale} -\indexmacroEnd{StopEventually} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\begin{decl} - \defmacro{PrintChanges} \\ - \defmacro{PrintIndex} -\end{decl} - -\indexmacroBegin{PrintChanges} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\index{change history|(} - -\usemacro{PrintChanges} produces an unnumbered section called ``Change -History''. (See Figure~\vref{fig:change-history}). The Change -History section aggregates all of the \usemacro{changes} commands in -the \dtxfile{} file into a single list of per-version modifications. -This makes it easy to keep track of what changed from version to -version. - -\usemacro{PrintChanges} uses \latex's glossary mechanism. Running -|latex| on |<package>.dtx| produces change-history data in -|<package>.glo|. To produce the actual change history -(|<package>.gls|), the user should run the \usething{makeindex} -program as follows: - -\begin{verbatim} - makeindex -s gglo.ist -o <package>.gls <package>.glo -\end{verbatim} - -\index{change history|)} -\indexmacroEnd{PrintChanges} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\indexmacroBegin{PrintIndex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\index{indexing|(} - -\usemacro{PrintIndex} produces an unnumbered section called ``Index''. -The index automatically includes entries for all macros and -environments that are used, defined, or described in the document. -All environments are additionally listed under ``environments''. -Table~\ref{tbl:index-formatting} illustrates the way that various -entries are formatted. In that table, ``27'' refers to a page number, -and ``123'' refers to a line number.\footnote{If -\texttt{\string\CodelineIndex} (page~\pageref{desc:CodelineIndex}) -were not used then ``123'' would refer to a page number.} Note that -macro/environment definitions and uses are included in the index only -if the document includes a code listing (\ie -\usemacro{OnlyDescription} was not specified). - -\begin{table}[htbp] - \centering - \caption{Formatting of entries in the index} - \label{tbl:index-formatting} - \begin{tabular}{@{}llp{6cm}@{}} - \hline - Item & Function & Formatting in index \\ - \hline - Macro & Used & |\myMacro| \dotfill~123 \\ - Macro & Defined & |\myMacro| \dotfill~\underline{123} \\ - Macro & Described & |\myMacro| \dotfill~\textit{27} \\ - Environment & Defined & |myEnv| (environment) \dotfill~\underline{123} \\ - Environment & Described & |myEnv| (environment) \dotfill~\textit{27} \\ - \multicolumn{2}{@{}l}{Other (\ie an explicit \texttt{\string\index})} - & myItem \dotfill~27 \\ - \hline - \end{tabular} -\end{table} - -The default formatting for an explicit \usemacro{index} command uses a -roman page number. This leads to confusion, as roman page numbers -otherwise indicate line numbers in the package source code. The -solution is to specify ``|usage|'' formatting to the \usemacro{index} -command: - -\begin{verbatim} - \index{explicit indexing|usage} -\end{verbatim} - -Running |latex| on |<package>.dtx| produces index data in -|<package>.idx|. To produce the actual index (|<package>.ind|), the -user should run the \usething{makeindex} program as follows: - -\begin{verbatim} - makeindex -s gind.ist -o <package>.ind <package>.idx -\end{verbatim} - -A code index is a nice ``value added'' made possible by -literate\index{literate programming} programming. It requires -virtually no extra effort and greatly helps code maintainers to find -macro definitions and see what other macros a package\index{package} -depends upon. - -\index{indexing|)} -\indexmacroEnd{PrintIndex} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexthingBegin{macrocode} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\begin{decl} - |\begin{macrocode}| \\ - \m{code} \\ - |\end{macrocode}| -\end{decl} - -Code fragments listed between |\begin{macrocode}| and -|\end{macrocode}| are extracted verbatim into the \styfile{} file. -When typeset, the code fragments are shown with a running line counter -to make it easy to refer to a specific line. Here are some key points -to remember about the \usething{macrocode} environment: - -\begin{enumerate} - \item There must be \emph{exactly} four spaces between the ``|%|'' - and the ``|\begin{macrocode}|'' or ``|\end{macrocode}|''. - Otherwise, \DOC{} won't detect the end of the code - fragment.\footnote{Trivia: Only the - \texttt{\string\end\string{macrocode\string}} needs this precise - spacing and then, only for typesetting the documentation. - Nevertheless, it's good practice to use - ``\texttt{\%\textvisiblespace\textvisiblespace\textvisiblespace\textvisiblespace}'' - for the \texttt{\string\begin\string{macrocode\string}}, as well.} - - \item The lines of code within - |\begin{macrocode}|\dotsbrk|\end{macrocode}| should not begin with - ``|%|''. The code gets written exactly as it is to the \insfile{} - file, with no |%|-stripping. -\end{enumerate} - -The following is a sample code fragment. It happens to be a complete -macro definition, but this is not necessary; any fragment of \latex{} -code can appear within a \usething{macrocode} environment. - -\label{code:mymacro} -\begin{verbatim} - % \begin{macrocode} - \newcommand{\mymacro}{This is - a \LaTeX{} macro.} - % \end{macrocode} -\end{verbatim} - -\noindent -\DOC{} formats the preceding code fragment as follows: - -\begin{tabbing} -| |\={\tiny 9} \=\kill - \> {\tiny 1} \> |\newcommand{\mymacro}{This is| \\ - \> {\tiny 2} \> | a \LaTeX{} macro.}| -\end{tabbing} - -\noindent -Note that line numbers are unique across the entire program (as -opposed to being reset at the top of each page). If -\usemacro{PrintIndex} is used in the \dtxfile{} file containing the -preceding definition of |\mymacro|, the index will automatically -include entries for |\newcommand|, |\mymacro|, and |\LaTeX|, unless -any of these are \usemacro{DoNotIndex}'ed. - -\indexthingEnd{macrocode} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - - -\indexthingBegin{macro} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -\indexthingBegin{environment} - -\begin{decl} - |\begin{macro}{<macro>}| \\ - \qquad $\vdots$ \\ - |\end{macro}| \\ - \\ - |\begin{environment}{<environment>}| \\ - \qquad $\vdots$ \\ - |\end{environment}| \\ -\end{decl} - -The \usething{macro} and \usething{environment} environments are used -to delineate a complete macro or environment definition. -\usething{macro}/\usething{environment} environments generally contain -one or more \usething{macrocode} environments interspersed with code -documentation. The following is a more complete version of the -\usething{macrocode} example shown~\vpageref{code:mymacro}. - -\begin{verbatim} - % \begin{macro}{\mymacro} - % We define a trivial macro, |\mymacro|, to illustrate - % the use of the |macro| environment. - % \begin{macrocode} - \newcommand{\mymacro}{This is - a \LaTeX{} macro.} - % \end{macrocode} - % \end{macro} -\end{verbatim} - -\noindent -The typeset version is shown below: - -\begin{tabbing} -| \mymacro|\qquad\={\tiny 9} \= \kill -| \mymacro| \> We define a trivial macro, |\mymacro|, to illustrate the \\ - \> use of the \usething{macro} environment. \\ - \> {\tiny 1} \> |\newcommand{\mymacro}{This is| \\ - \> {\tiny 2} \> | a \LaTeX{} macro.}| -\end{tabbing} - -\DOC{} typesets the macro/environment name in the margin for increased -visibility. \DOC{} also adds the appropriate entries to the index. -(See Table~\vref{tbl:index-formatting} for examples of how these -entries are formatted.) Note that -|\begin{macro}|\dotsbrk|\end{macro}| is not required to indicate a -macro definition. It can also be used to indicate definitions of -\latex{} datatypes, such as counters, lengths, and boxes: - -\begin{verbatim} - % \begin{macro}{myCounter} - % This is an example of using the |macro| environment to format - % something other than a macro. - % \begin{macrocode} - \newcounter{myCounter} - % \end{macrocode} - % \end{macro} -\end{verbatim}% -\indexthing{macrocode} - -\usething{macro} and \usething{environment} environments can be -nested. This capability is useful not only for macros that define -other macros, but also when defining a group of related datatypes that -share a description: - -\begin{verbatim} - % \begin{macro}{\thingheight} - % \begin{macro}{\thingwidth} - % \begin{macro}{\thingdepth} - % These lengths keep track of the dimensions of our |\thing| - % box. (Actually, we're just trying to show how to nest - % |macro| environments.) - % \begin{macrocode} - \newlength{\thingheight} - \newlength{\thingwidth} - \newlength{\thingdepth} - % \end{macrocode} - % \end{macro} - % \end{macro} - % \end{macro} -\end{verbatim}% -\indexthing{macro}% -\indexthing{macrocode} - -\noindent -Descriptionless \usething{macro} environments should generally be -avoided, as the formatting is a little ugly; the macro name appears on -its own line, to the left of an ``empty'' description, but the code -doesn't start until the next line. - -There can be multiple \usething{macrocode} environments within a -|\begin{macro}|\dotsbrk|\end{macro}| or -|\begin{environment}|\dotsbrk|\end{environment}| block. -\index{comments|(} This is the mechanism by which code can be -commented internally to a macro/environment. (It's considered bad -style to use ``|%|'' for comments within a \usething{macrocode} -block.) Here's an example of the way that a nontrivial macro might be -commented: - -\begin{verbatim} - % \begin{macro}{\complexMacro} - % Pretend that this is a very complex macro that needs - % to have its various pieces documented. - % \begin{macrocode} - \newcommand{\complexMacro}{% - % \end{macrocode} - % Initialize all of our counters to zero. - % \begin{macrocode} - \setcounter{count@i}{0}% - \setcounter{count@ii}{0}% - \setcounter{count@iii}{0}% - \setcounter{count@iv}{0}% - % \end{macrocode} - % Do some really complicated processing. - % \begin{macrocode} -\end{verbatim}% -\indexthing{macrocode} -| |$\vdots$ -\begin{verbatim} - % \end{macrocode} - % We're all finished now. - % \begin{macrocode} - } - % \end{macrocode} - % \end{macro} -\end{verbatim}% -\indexthing{macrocode} - -\indexthingEnd{environment} -\indexthingEnd{macro} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -\index{comments|)} - -Appendix~\ref{sec:skeleton-dtx-file-style} lists a complete, skeleton -\dtxfile{} file that encapsulates a \styfile{} file and its -documentation. - -\index{class file|(} - -\paragraph{Class files} -The procedure to produce a class file from a \dtxfile{} file is far -less straightforward than the procedure to produce a style file. The -problem is that \usemacro{DocInput} relies on the -|\usepackage{|\m{package}|}| line (more precisely, the -\usemacro{ProvidesPackage} line within \m{package}|.sty|) to set the -\usemacro{fileversion} and \usemacro{filedate} macros. However, a -class file can't be loaded with |\usepackage|. Nor can we simply load -it with |\documentclass{|\m{package}|}| because only one class can be -loaded per document and we need that class to be |ltxdoc|. - -The solution is to use \usemacro{ProvidesFile} to make the file -version and date available to the \dtxfile{} file. -Appendix~\ref{sec:skeleton-dtx-file-class} lists a complete, skeleton -\dtxfile{} file that encapsulates a \clsfile{} file and its -documentation. It resembles the skeleton file shown in -Appendix~\ref{sec:skeleton-dtx-file-style} but has a differently -structured header section. - -\index{class file|)} - - -\index{documented LaTeX file@documented \LaTeX{} file|)} - - -\section{Tips, tricks, and recommendations} - -\begin{itemize} - \item Write lots of good documentation! It really helps others - understand your code and the package\index{package} as a whole. - - \item If you believe the \latex{} community at large would be - interested in your package then you should upload it to \CTAN{} at - \URL{http://www.ctan.org/upload}. As a central repository of all - things \TeX-related, \CTAN{} makes it easier for others to find your - \latex{} package than if it were located on your personal home page. - -\index{documentation, prebuilt PDF|(} - \item When distributing your package, be sure to include a - |README|\index{README file@\texttt{README} file} file describing - what your package does as well as \emph{prebuilt} documentation, - preferably as a PDF file. Prebuilt documentation saves users the - bother of having to download your package, install it, and build the - documentation before even knowing what the package is supposed to do - or if it meets their needs. -\index{documentation, prebuilt PDF|)} - - \item Use \latex's sectioning commands to organize the code and - clarify its structure (\eg |\subsection{|\texttt{Initialization - macros}|}|, |\subsection{|\texttt{Helper functions}|}|, - |\subsection{|\texttt{Exported macros and environments}|}|,~\dots). - -\index{comments|(} - - \item Although commentary really belongs only in the typeset - documentation, it is also possible to write comments that are - visible only in the \styfile{} file, in both the typeset - documentation and the \styfile{} file, or only in the \dtxfile{} - source. Table~\ref{tbl:comment-visibility} shows how to control - comment visibility. - -\index{comments|)} - - \begin{table}[hbp] - \centering - \caption{Comment visibility} - \label{tbl:comment-visibility} - \newcommand{\yes}{Y}% - \newcommand{\no}{N}% - \index{style file}% - \index{comments}% - \begin{tabular}{@{}ccl@{}} - \hline - Appears & Appears \\ - in docs & in \styfile{} & \raisebox{1.5ex}[0pt]{Mechanism} \\ - \hline - - \no & \no & |% ^^A <comment>| \\[2ex] - - \no & \yes & |% \iffalse| \\ - & & |%% <comment>| \\ - & & |% \fi| \\[2ex] - - \yes & \no & |% <comment>| \\[2ex] - - \yes & \yes & |%% <comment>| \\ - \hline - \end{tabular} - \end{table} - - \item All lines between |<<*package>>| and |<</package>>|, except - those within a \usething{macrocode} environment, should begin with - ``|%|''. Don't use any blank lines; these would get written to the - \styfile{} file (and oughtn't). - - -\index{package|(} -\index{"@@\texttt{"@}!in macro names|(} - \item It is good practice for \latex{} programs to use ``|@|'' - within the names of macros, lengths, counters, etc.\ that are - declared globally, but intended to be used only internally to the - package. This prevents a user from corrupting package state by - inadvertently redefining package internals.\footnote{Within a - \LaTeX{} document, ``|@|'' is set to category code~12 (``other''), - not category code~11 (``letter''), so the user can't easily define - or use a macro with ``|@|'' in its name.} Another good practice is - to prefix all global names that are internal to the package with the - name of the package (\eg ``|\<package>@thing|'' instead of - ``|\@thing|'' or---even worse---just ``|\thing|''). This helps - avoid inter-package naming conflicts. Finally, because decimal - digits are not normally allowed in macro names, it is common to use - roman\index{roman numerals} numerals instead, for example: |\arg@i|, - |\arg@ii|, |\arg@iii|, |\arg@iv|, etc. -\index{"@@\texttt{"@}!in macro names|)} -\index{package|)} - - \item You can use \usemacro{index} in the normal way to index things - other than macros and environments. - - \item If you use \Emacs{} as your text editor, try out \swiftexel's - |doctex-mode|\index{doctex-mode@\texttt{doctex-mode}}, an \Emacs{} - mode designed specifically for writing \dtxfile{} files. - \swiftexel{} is available from \CTAN{}. - - As a more primitive alternative, look up \Emacs's |string-rectangle| - and |kill-rectangle| commands. These help a great deal with adding - and removing a ``|%|'' at the beginning of every line in a region. - - \item Be sure to read ``The \ds{} Program'' and ``The \DOC{} and - \svrb{} Packages'', the documentation for \ds{} and \DOC{}, - respectively (provided in \dtxfile{} format, of course). These - explain how to do more advanced things with \insfile{} and - \dtxfile{} files than this tutorial covered. Some advanced topics - include the following: - - \begin{itemize} \item Extracting multiple \styfile{} - files from a single \dtxfile{} file. - - \item Putting different preambles in different - \styfile{} files. - - \item Extracting something other than a \styfile{} file (\eg a - configuration file or a Perl script) from a \dtxfile{} file. - - \item Changing the formatting of the typeset documentation. - \end{itemize} -\end{itemize} - - -\section{Obscure packaging features} - -This section describes various bits of wizardry that can be -accomplished with \DOC{} and \ds. Few packages require these -techniques but they are included here for convenient reference. - -\subsection{Master documentation files} -\label{sec:master-files} - -\DOC{} supports ``master'' documentation files that typeset multiple -\dtxfile{} files. The advantage is that a set of related \dtxfile{} -files can be typeset with continuous section numbering and a single, -unified index. In fact, the \latex[\LaTeXe]{} source code itself is -typeset using a master document (|source2e.tex|) that includes all of -the myriad \dtxfile{} files that comprise \latex[\LaTeXe]. - -To help produce master documents, the \usething{ltxdoc} class -provides a command called ``\usemacro{DocInclude}''. -\usething{ltxdoc}'s \usemacro{DocInclude} is much like \DOC's -\usemacro{DocInput}---it even uses it internally---but has the -following additional features. - - \begin{itemize} - \item \usemacro{PrintIndex} is automatically handled properly. - - \item Every \usemacro{DocInclude}'d file is given a title page. - - \item \usemacro{tableofcontents} works as expected. \dtxfile{} - filenames are used as ``chapter'' names. - \end{itemize} - -\noindent -Note that \usemacro{DocInclude}, unlike \usemacro{DocInput}, assumes -a \dtxfile{} extension. - -Appendix~\ref{sec:skeleton-master-file} presents a master-document -skeleton that uses \usemacro{DocInclude} to typeset |<file1>.dtx|, -|<file2>.dtx|, and |<file3>.dtx| as a single document. If you prefer -a more manual approach (\eg if you dislike \usemacro{DocInclude}'s -per-file title pages), you can still use \usemacro{DocInput}. -\index{indexing|(} -Just make sure to redefine \usemacro{PrintIndex} to do nothing; -otherwise, each file will get its own index. After all of the -\dtxfile{} files have been typeset, call the original -\usemacro{PrintIndex} command to print a unified index: - -\begin{verbatim} - \begin{document} - \let\origPrintIndex=\PrintIndex \let\PrintIndex=\relax - \DocInput{<file1>.dtx} - \DocInput{<file2>.dtx} - \DocInput{<file3>.dtx} - \origPrintIndex - \end{document} -\end{verbatim}% -\indexmacro{PrintIndex}% -\indexmacro{DocInput} - -\index{indexing|)} - -\subsection{Single-file package distributions} - -Although \latex{} packages are typically distributed as both -a~\insfile{} and a \dtxfile{} file, it is possible to distribute a -package as a single file. The trick is to include the entire -\insfile{} at the top of the \dtxfile{} file, right after the -|%<package>| lines: - -\begin{alltt} - %\string<*batchfile\string> - \string\begingroup - \(\vdots\) - <Entire contents of the {\normalfont\texttt{.ins}} file> - \(\vdots\) - \string\endgroup - %\string</batchfile\string> -\end{alltt} - -\noindent -Omit the \usemacro{endbatchfile} to allow \latex{} to continue on with -the rest of the \dtxfile{} file. Also, to avoid the ``\texttt{File} -\m{sty-file} \texttt{already exists on the system. Overwrite it? -[y/n]}'' message you can put ``\usemacro{askforoverwritefalse}'' -before the first \usemacro{generate} command. (This will -automatically overwrite the existing \styfile{} file. Wrapping the -\usemacro{generate} command(s) within -``\usemacro{IfFileExists}|{|\m{sty-file}|}{}{|\dots|}|'' will suppress -the overwriting.) You should also move the \styfile{} installation -instructions to the end of the \dtxfile{} file so they don't scroll -off the user's screen. You'll need to use \usemacro{typeout} as -\usemacro{Msg} won't be defined: - -\begin{verbatim} - % \Finale - % - % \typeout{**************************************************} - % \typeout{*} - % \typeout{* To finish the installation you have to move the} - % \typeout{* following file into a directory searched by TeX:} - % \typeout{*} - % \typeout{* \space\space skeleton.sty} - % \typeout{*} - % \typeout{* Documentation is in skeleton.dvi.} - % \typeout{*} - % \typeout{* Happy TeXing!} - % \typeout{**************************************************} - \endinput -\end{verbatim} - - -\subsection{Class and style files with shared versioning information} - -Some packages contain both a \clsfile{} and \styfile{} file. It may -be desirable to have these extracted from the same \insfile{} file and -share the same versioning string. The \ds{} documentation explains -how to extract multiple files from a single \usemacro{generate} call: - -\begin{verbatim} - \generate{\file{<package>.cls}{\from{<package>.dtx}{class}} - \file{<package>.sty}{\from{<package>.dtx}{package}}} -\end{verbatim} - -Using a single versioning string for both the \clsfile{} and -\styfile{} files can be accomplished by changing the following lines -in the \dtxfile{} file shown in -Appendix~\ref{sec:skeleton-dtx-file-class}: - -\begin{verbatim} - %<<class>>\NeedsTeXFormat{LaTeX2e}[1999/12/01] - %<<class>>\ProvidesClass{<package>} - %<<*class>> - [<YYYY>/<MM>/<DD> v<version> <brief description>] - %<</class>> -\end{verbatim} - -The replacement code specifies which lines belong to the class file -and which belong to the style file: - -\begin{verbatim} - %<<class|package>>\NeedsTeXFormat{LaTeX2e}[1999/12/01] - %<<class>>\ProvidesClass{<package>} - %<<package>>\ProvidesPackage{<package>} - %<<*class|package>> - [<YYYY>/<MM>/<DD> v<version> <brief description>] - %<</class|package>> -\end{verbatim} - - -\appendix - -\section{Skeleton files} - -This section contains complete skeletons of the types of files -discussed in the rest of the document. These skeletons can be used as -templates for creating your own packages.\index{package} - -\index{installer file|(} - -\subsection{A skeleton \texttt{.ins} file to generate a \texttt{.sty} file} -\label{sec:skeleton-ins-file-style} - -\begin{verbatim} -%% -%% Copyright (C) <year> by <your name> -%% -%% This file may be distributed and/or modified under the -%% conditions of the LaTeX Project Public License, either -%% version 1.2 of this license or (at your option) any later -%% version. The latest version of this license is in: -%% -%% http://www.latex-project.org/lppl.txt -%% -%% and version 1.2 or later is part of all distributions of -%% LaTeX version 1999/12/01 or later. -%% - -\input docstrip.tex -\keepsilent - -\usedir{tex/latex/<package>} - -\preamble - -This is a generated file. - -Copyright (C) <year> by <your name> - -This file may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either -version 1.2 of this license or (at your option) any later -version. The latest version of this license is in: - - http://www.latex-project.org/lppl.txt - -and version 1.2 or later is part of all distributions of -LaTeX version 1999/12/01 or later. - -\endpreamble - -\generate{\file{<package>.sty}{\from{<package>.dtx}{package}}} - -\Msg{*********************************************************} -\Msg{*} -\Msg{* To finish the installation you have to move the} -\Msg{* following file into a directory searched by TeX:} -\Msg{*} -\Msg{* \space\space <package>.sty} -\Msg{*} -\Msg{* To produce the documentation run the file <package>.dtx} -\Msg{* through LaTeX.} -\Msg{*} -\Msg{* Happy TeXing!} -\Msg{*********************************************************} - -\endbatchfile -\end{verbatim} - - -\subsection{A skeleton \texttt{.ins} file to generate a \texttt{.cls} file} -\label{sec:skeleton-ins-file-class} - -\begin{verbatim} -%% -%% Copyright (C) <year> by <your name> -%% -%% This file may be distributed and/or modified under the -%% conditions of the LaTeX Project Public License, either -%% version 1.2 of this license or (at your option) any later -%% version. The latest version of this license is in: -%% -%% http://www.latex-project.org/lppl.txt -%% -%% and version 1.2 or later is part of all distributions of -%% LaTeX version 1999/12/01 or later. -%% - -\input docstrip.tex -\keepsilent - -\usedir{tex/latex/<package>} - -\preamble - -This is a generated file. - -Copyright (C) <year> by <your name> - -This file may be distributed and/or modified under the -conditions of the LaTeX Project Public License, either -version 1.2 of this license or (at your option) any later -version. The latest version of this license is in: - - http://www.latex-project.org/lppl.txt - -and version 1.2 or later is part of all distributions of -LaTeX version 1999/12/01 or later. - -\endpreamble - -\generate{\file{<package>.cls}{\from{<package>.dtx}{class}}} - -\Msg{*********************************************************} -\Msg{*} -\Msg{* To finish the installation you have to move the} -\Msg{* following file into a directory searched by TeX:} -\Msg{*} -\Msg{* \space\space <package>.cls} -\Msg{*} -\Msg{* To produce the documentation run the file <class>.dtx} -\Msg{* through LaTeX.} -\Msg{*} -\Msg{* Happy TeXing!} -\Msg{*********************************************************} - -\endbatchfile -\end{verbatim} - -\index{installer file|)} -\index{documented LaTeX file@documented \LaTeX{} file|(} - - -\subsection{A skeleton \texttt{.dtx} file to generate a \texttt{.sty} file} -\label{sec:skeleton-dtx-file-style} - -\begin{verbatim} -% \iffalse meta-comment -% -% Copyright (C) <year> by <your name> -% ----------------------------------- -% -% This file may be distributed and/or modified under the -% conditions of the LaTeX Project Public License, either version 1.2 -% of this license or (at your option) any later version. -% The latest version of this license is in: -% -% http://www.latex-project.org/lppl.txt -% -% and version 1.2 or later is part of all distributions of LaTeX -% version 1999/12/01 or later. -% -% \fi -% -% \iffalse -%<<package>>\NeedsTeXFormat{LaTeX2e}[1999/12/01] -%<<package>>\ProvidesPackage{<package>} -%<<package>> [<YYYY>/<MM>/<DD> v<version> <brief description>] -% -%<<*driver>> -\documentclass{ltxdoc} -\usepackage{<package>} -\EnableCrossrefs -\CodelineIndex -\RecordChanges -\begin{document} - \DocInput{<package>.dtx} -\end{document} -%<</driver>> -% \fi -% -% \CheckSum{0} -% -% \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 \~} -% -% -% \changes{v1.0}{<YYYY>/<MM>/<DD>}{Initial version} -% -% \GetFileInfo{<package>.sty} -% -% \DoNotIndex{<list of control sequences>} -% -% \title{The \textsf{<package>} package\thanks{This document -% corresponds to \textsf{<package>}~\fileversion, -% dated \filedate.}} -% \author{<your name> \\ \texttt{<your e-mail address>}} -% -% \maketitle -% -% \begin{abstract} -% Put text here. -% \end{abstract} -% -% \section{Introduction} -% -% Put text here. -% -% \section{Usage} -% -% \DescribeMacro{\YOURMACRO} -% Put description of |\YOURMACRO| here. -% -% \DescribeEnv{YOURENV} -% Put description of |YOURENV| here. -% -% \StopEventually{\PrintIndex} -% -% \section{Implementation} -% -% \begin{macro}{\YOURMACRO} -% Put explanation of |\YOURMACRO|'s implementation here. -% \begin{macrocode} -\newcommand{\YOURMACRO}{} -% \end{macrocode} -% \end{macro} -% -% \begin{environment}{YOURENV} -% Put explanation of |YOURENV|'s implementation here. -% \begin{macrocode} -\newenvironment{YOURENV}{}{} -% \end{macrocode} -% \end{environment} -% -% \Finale -\endinput -\end{verbatim} - - -\subsection{A skeleton \texttt{.dtx} file to generate a \texttt{.cls} file} -\label{sec:skeleton-dtx-file-class} - -\begin{verbatim} -% \iffalse meta-comment -% -% Copyright (C) <year> by <your name> -% ----------------------------------- -% -% This file may be distributed and/or modified under the -% conditions of the LaTeX Project Public License, either version 1.2 -% of this license or (at your option) any later version. -% The latest version of this license is in: -% -% http://www.latex-project.org/lppl.txt -% -% and version 1.2 or later is part of all distributions of LaTeX -% version 1999/12/01 or later. -% -% \fi -% -% \iffalse -%<<*driver>> -\ProvidesFile{<package>.dtx} -%<</driver>> -%<<class>>\NeedsTeXFormat{LaTeX2e}[1999/12/01] -%<<class>>\ProvidesClass{<package>} -%<<*class>> - [<YYYY>/<MM>/<DD> v<version> <brief description>] -%<</class>> -% -%<<*driver>> -\documentclass{ltxdoc} -\EnableCrossrefs -\CodelineIndex -\RecordChanges -\begin{document} - \DocInput{<package>.dtx} -\end{document} -%<</driver>> -% \fi -% -% \CheckSum{0} -% -% \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 \~} -% -% -% \changes{v1.0}{<YYYY>/<MM>/<DD>}{Initial version} -% -% \GetFileInfo{<package>.dtx} -% -% \DoNotIndex{<list of control sequences>} -% -% \title{The \textsf{<package>} class\thanks{This document -% corresponds to \textsf{<package>}~\fileversion, -% dated \filedate.}} -% \author{<your name> \\ \texttt{<your e-mail address>}} -% -% \maketitle -% -% \begin{abstract} -% Put text here. -% \end{abstract} -% -% \section{Introduction} -% -% Put text here. -% -% \section{Usage} -% -% \DescribeMacro{\YOURMACRO} -% Put description of |\YOURMACRO| here. -% -% \DescribeEnv{YOURENV} -% Put description of |YOURENV| here. -% -% \StopEventually{\PrintIndex} -% -% \section{Implementation} -% -% \begin{macro}{\YOURMACRO} -% Put explanation of |\YOURMACRO|'s implementation here. -% \begin{macrocode} -\newcommand{\YOURMACRO}{} -% \end{macrocode} -% \end{macro} -% -% \begin{environment}{YOURENV} -% Put explanation of |YOURENV|'s implementation here. -% \begin{macrocode} -\newenvironment{YOURENV}{}{} -% \end{macrocode} -% \end{environment} -% -% \Finale -\endinput -\end{verbatim} - -\index{documented LaTeX file@documented \LaTeX{} file|)} - -\subsection{A skeleton master-document file (\texttt{.tex})} -\label{sec:skeleton-master-file} - -\begin{verbatim} -\documentclass{ltxdoc} -\usepackage{<file1>} -\usepackage{<file2>} -\usepackage{<file3>} - -\title{<title>} -\author{<you>} - -\EnableCrossrefs -\CodelineIndex -\RecordChanges - -\begin{document} - \maketitle - - \begin{abstract} - <abstract> - \end{abstract} - - \tableofcontents - - \DocInclude{<file1>} - \DocInclude{<file2>} - \DocInclude{<file3>} -\end{document} -\end{verbatim} - - -% The following was generated by BibTeX and slightly touched up by hand. -\vfill -\begin{thebibliography}{1} - \bibitem{Goossens1994:companion} - Michel Goossens, Frank Mittelbach, and Alexander Samarin. - \newblock \emph{The {\LaTeX} Companion}. - \newblock Addison~Wesley, Reading, Massachusetts, October~1, 1994. - \newblock ISBN~\mbox{0-201-54199-8}. - - \bibitem{Knuth1984:literate} - Donald~E. Knuth. - \newblock Literate programming. - \newblock \emph{The Computer Journal}, 27(2):97--111, May 1984. - \newblock British Computer Society. Available from - \URL{http://www.literateprogramming.com/knuthweb.pdf}. -\end{thebibliography} - -% Print an index. -\index{sty@\texttt{.sty}|see{style file}} -\index{cls@\texttt{.cls}|see{class file}} -\index{ins@\texttt{.ins}|see{installer file}} -\index{dtx@\texttt{.dtx}|see{documented \LaTeX{} file}} -\index{CTAN|see{Comprehensive \TeX{} Archive Network}} -\printindex - -\end{document} |