summaryrefslogtreecommitdiff
path: root/Master/texmf-doc/doc/english/dtxtut/dtxtut.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-doc/doc/english/dtxtut/dtxtut.tex')
-rw-r--r--Master/texmf-doc/doc/english/dtxtut/dtxtut.tex2075
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}