diff options
Diffstat (limited to 'info/dtxtut')
| -rw-r--r-- | info/dtxtut/README | 31 | ||||
| -rw-r--r-- | info/dtxtut/cskeleton.dtx | 130 | ||||
| -rw-r--r-- | info/dtxtut/cskeleton.ins | 55 | ||||
| -rw-r--r-- | info/dtxtut/dtxtut.pdf | bin | 0 -> 304588 bytes | |||
| -rw-r--r-- | info/dtxtut/dtxtut.tex | 2107 | ||||
| -rw-r--r-- | info/dtxtut/skeleton.dtx | 127 | ||||
| -rw-r--r-- | info/dtxtut/skeleton.ins | 55 |
7 files changed, 2505 insertions, 0 deletions
diff --git a/info/dtxtut/README b/info/dtxtut/README new file mode 100644 index 0000000000..70d96cbcff --- /dev/null +++ b/info/dtxtut/README @@ -0,0 +1,31 @@ + + +-------------------------------------+ + | HOW TO PACKAGE YOUR LATEX PACKAGE | + | By Scott Pakin, scott+dtx@pakin.org | + +-------------------------------------+ + +This tutorial is intended for advanced LaTeX2e users who want to learn +how to create .ins and .dtx files for distributing their homebrewed +classes and style files. + +Distributed files include: + + README -- This file + dtxtut.pdf -- Preformatted tutorial + dtxtut.tex -- Tutorial source code (LaTeX2e) + skeleton.ins -- A sample .ins file (generates .sty) + skeleton.dtx -- A sample .dtx file (generates .sty) + cskeleton.ins -- A sample .ins file (generates .cls) + cskeleton.dtx -- A sample .dtx file (generates .cls) + + +The author would like to thank the following people (in alphabetical +order) for their suggestions on improving dtxtut and the skeleton +files: + + * Robin Fairbairns + * Marcel Heldoorn + * Alex Hirzel + * Rolf Niepraschk + * Hans Fredrik Nordhaug + * Will Robertson diff --git a/info/dtxtut/cskeleton.dtx b/info/dtxtut/cskeleton.dtx new file mode 100644 index 0000000000..dd833da90e --- /dev/null +++ b/info/dtxtut/cskeleton.dtx @@ -0,0 +1,130 @@ +% \iffalse meta-comment +% +% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org> +% ------------------------------------------------------- +% +% This file may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% 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.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% \fi +% +% \iffalse +%<*driver> +\ProvidesFile{cskeleton.dtx} +%</driver> +%<class>\NeedsTeXFormat{LaTeX2e}[1999/12/01] +%<class>\ProvidesClass{cskeleton} +%<*class> + [2004/11/05 v1.0 .dtx skeleton file] +%</class> +% +%<*driver> +\documentclass{ltxdoc} +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\begin{document} + \DocInput{cskeleton.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}{2004/11/05}{Initial version} +% +% \GetFileInfo{cskeleton.dtx} +% +% \DoNotIndex{\newcommand,\newenvironment} +% +% +% \title{The \textsf{cskeleton} class\thanks{This document +% corresponds to \textsf{cskeleton}~\fileversion, dated \filedate.}} +% \author{Scott Pakin \\ \texttt{scott+dtx@pakin.org}} +% +% \maketitle +% +% \section{Introduction} +% +% Put text here. +% +% \section{Usage} +% +% Put text here. +% +% \DescribeMacro{\dummyMacro} +% This macro does nothing.\index{doing nothing|usage} It is merely an +% example. If this were a real macro, you would put a paragraph here +% describing what the macro is supposed to do, what its mandatory and +% optional arguments are, and so forth. +% +% \DescribeEnv{dummyEnv} +% This environment does nothing. It is merely an example. +% If this were a real environment, you would put a paragraph here +% describing what the environment is supposed to do, what its +% mandatory and optional arguments are, and so forth. +% +% \StopEventually{\PrintChanges\PrintIndex} +% +% \section{Implementation} +% +% For simplicity, we'll derive everything from the standard |article| +% class. +% \begin{macrocode} +\LoadClassWithOptions{article} +% \end{macrocode} +% +% \begin{macro}{\dummyMacro} +% This is a dummy macro. If it did anything, we'd describe its +% implementation here. +% \begin{macrocode} +\newcommand{\dummyMacro}{} +% \end{macrocode} +% \end{macro} +% +% \begin{environment}{dummyEnv} +% This is a dummy environment. If it did anything, we'd describe its +% implementation here. +% \begin{macrocode} +\newenvironment{dummyEnv}{% +}{% +% \end{macrocode} +% \changes{v1.0a}{2004/11/05}{Added a spurious change log entry to +% show what a change \emph{within} an environment definition looks +% like.} +% Don't use |%| to introduce a code comment within a |macrocode| +% environment. Instead, you should typeset all of your comments with +% \LaTeX---doing so gives much prettier results. For comments within a +% macro/environment body, just do an |\end{macrocode}|, include some +% commentary, and do another |\begin{macrocode}|. It's that simple. +% \begin{macrocode} +} +% \end{macrocode} +% \end{environment} +% +% \Finale +\endinput diff --git a/info/dtxtut/cskeleton.ins b/info/dtxtut/cskeleton.ins new file mode 100644 index 0000000000..b99b06df69 --- /dev/null +++ b/info/dtxtut/cskeleton.ins @@ -0,0 +1,55 @@ +%% +%% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org> +%% +%% This file may be distributed and/or modified under the conditions of +%% the LaTeX Project Public License, either version 1.3 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.3 or later is part of all distributions of LaTeX version +%% 2005/12/01 or later. +%% + +\input docstrip.tex +\keepsilent + +\usedir{tex/latex/cskeleton} + +\preamble + +This is a generated file. + +Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org> + +This file may be distributed and/or modified under the conditions of +the LaTeX Project Public License, either version 1.3 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.3 or later is part of all distributions of LaTeX version +2005/12/01 or later. + +\endpreamble + +\generate{\file{cskeleton.cls}{\from{cskeleton.dtx}{class}}} + +\obeyspaces +\Msg{*************************************************************} +\Msg{* *} +\Msg{* To finish the installation you have to move the following *} +\Msg{* file into a directory searched by TeX: *} +\Msg{* *} +\Msg{* cskeleton.cls *} +\Msg{* *} +\Msg{* To produce the documentation run the file cskeleton.dtx *} +\Msg{* through LaTeX. *} +\Msg{* *} +\Msg{* Happy TeXing! *} +\Msg{* *} +\Msg{*************************************************************} + +\endbatchfile diff --git a/info/dtxtut/dtxtut.pdf b/info/dtxtut/dtxtut.pdf Binary files differnew file mode 100644 index 0000000000..e6bf6c21ee --- /dev/null +++ b/info/dtxtut/dtxtut.pdf diff --git a/info/dtxtut/dtxtut.tex b/info/dtxtut/dtxtut.tex new file mode 100644 index 0000000000..cf9d73698e --- /dev/null +++ b/info/dtxtut/dtxtut.tex @@ -0,0 +1,2107 @@ +%%% ==================================================================== +%%% @LaTeX-file{ +%%% author = "Scott Pakin", +%%% version = "2.1", +%%% date = "13 September 2015", +%%% time = "23:06:32 MDT", +%%% filename = "dtxtut.tex", +%%% checksum = "38789 2107 7734 71546" +%%% 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} +\usepackage{tocbibind} +\usepackage[bookmarksopen]{hyperref} +\usepackage{hyperxmp} + +% Define this document's metadata. +\title{How to Package Your \LaTeX{} Package} +\author{Scott Pakin \texttt{<scott+dtx@pakin.org>}} +\date{13 September 2015} +\hypersetup{% + pdftitle={How to Package Your LaTeX Package}, + pdfauthor={Scott Pakin}, + pdfcontactemail={scott+dtx@pakin.org}, + pdfcontacturl={http://www.pakin.org/\xmptilde scott}, + pdfsubject={Writing .ins and .dtx files for LaTeX}, + pdfkeywords={LaTeX package documentation, literate programming, typesetting, installer files}, + pdfcaptionwriter={Scott Pakin}, + pdfcopyright={Copyright (C) 2015 Scott Pakin}, + pdflicenseurl={http://latex-project.org/lppl/}, + pdflang={en-US} +} + +% 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.3 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.3 or later is part of all distributions of + %% LaTeX version 2005/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.3 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.3 or later is part of all distributions of + LaTeX version 2005/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.3 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.3 or later is part of all distributions of + %% LaTeX version 2005/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.3 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.3 or later is part of all distributions of + % LaTeX version 2005/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}[2005/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}[2005/12/01] + \ProvidesPackage{<package>} + [<YYYY>/<MM>/<DD> v<version> <description>] +\end{verbatim}% +\indexmacro{NeedsTeXFormat}% +\indexmacro{ProvidesPackage} + +\noindent +For example: + +\begin{verbatim} + \NeedsTeXFormat{LaTeX2e}[2005/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 \usething{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 Because macro names can be long, consider using the + \defthing{idxlayout} package to reduce the number of columns in + the index. (It provides control over other aspects of index + formatting, as well.) + + \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{Advanced packaging techniques} + +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} +\label{sec:single-file} + +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}[2005/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}[2005/12/01] + %<<class>>\ProvidesClass{<package>} + %<<package>>\ProvidesPackage{<package>} + %<<*class|package>> + [<YYYY>/<MM>/<DD> v<version> <brief description>] + %<</class|package>> +\end{verbatim} + +\subsection{Gallery of advanced packaging techniques} + +See the \dtxfile\ gallery on +\CTAN\ \URL{https://www.ctan.org/tex-archive/info/dtxgallery} for +examples of various packaging possibilities, including the following: + +\begin{itemize} + \item single-file package distributions (cf.~Section~\ref{sec:single-file}) + + \item conditional code inclusion (cf.~Table~\ref{tbl:comment-visibility}) + + \item rearranging code for presentation in the documentation +\end{itemize} + + +\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.3 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.3 or later is part of all distributions of +%% LaTeX version 2005/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.3 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.3 or later is part of all distributions of +LaTeX version 2005/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.3 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.3 or later is part of all distributions of +%% LaTeX version 2005/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.3 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.3 or later is part of all distributions of +LaTeX version 2005/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.3 +% 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.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% \fi +% +% \iffalse +%<<package>>\NeedsTeXFormat{LaTeX2e}[2005/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.3 +% 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.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% \fi +% +% \iffalse +%<<*driver>> +\ProvidesFile{<package>.dtx} +%<</driver>> +%<<class>>\NeedsTeXFormat{LaTeX2e}[2005/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} diff --git a/info/dtxtut/skeleton.dtx b/info/dtxtut/skeleton.dtx new file mode 100644 index 0000000000..83a7b52fee --- /dev/null +++ b/info/dtxtut/skeleton.dtx @@ -0,0 +1,127 @@ +% \iffalse meta-comment +% +% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org> +% ------------------------------------------------------- +% +% This file may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% 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.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% \fi +% +% \iffalse +%<*driver> +\ProvidesFile{skeleton.dtx} +%</driver> +%<package>\NeedsTeXFormat{LaTeX2e}[2005/12/01] +%<package>\ProvidesPackage{skeleton} +%<*package> + [2004/11/05 v1.0 .dtx skeleton file] +%</package> +% +%<*driver> +\documentclass{ltxdoc} +\usepackage{skeleton}[2004/11/05] +\EnableCrossrefs +\CodelineIndex +\RecordChanges +\begin{document} + \DocInput{skeleton.dtx} + \PrintChanges + \PrintIndex +\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}{2004/11/05}{Initial version} +% +% \GetFileInfo{skeleton.dtx} +% +% \DoNotIndex{\newcommand,\newenvironment} +% +% +% \title{The \textsf{skeleton} package\thanks{This document +% corresponds to \textsf{skeleton}~\fileversion, dated \filedate.}} +% \author{Scott Pakin \\ \texttt{scott+dtx@pakin.org}} +% +% \maketitle +% +% \section{Introduction} +% +% Put text here. +% +% \section{Usage} +% +% Put text here. +% +% \DescribeMacro{\dummyMacro} +% This macro does nothing.\index{doing nothing|usage} It is merely an +% example. If this were a real macro, you would put a paragraph here +% describing what the macro is supposed to do, what its mandatory and +% optional arguments are, and so forth. +% +% \DescribeEnv{dummyEnv} +% This environment does nothing. It is merely an example. +% If this were a real environment, you would put a paragraph here +% describing what the environment is supposed to do, what its +% mandatory and optional arguments are, and so forth. +% +% \StopEventually{} +% +% \section{Implementation} +% +% \begin{macro}{\dummyMacro} +% This is a dummy macro. If it did anything, we'd describe its +% implementation here. +% \begin{macrocode} +\newcommand{\dummyMacro}{} +% \end{macrocode} +% \end{macro} +% +% \begin{environment}{dummyEnv} +% This is a dummy environment. If it did anything, we'd describe its +% implementation here. +% \begin{macrocode} +\newenvironment{dummyEnv}{% +}{% +% \end{macrocode} +% \changes{v1.0a}{2004/11/05}{Added a spurious change log entry to +% show what a change \emph{within} an environment definition looks +% like.} +% Don't use |%| to introduce a code comment within a |macrocode| +% environment. Instead, you should typeset all of your comments with +% \LaTeX---doing so gives much prettier results. For comments within a +% macro/environment body, just do an |\end{macrocode}|, include some +% commentary, and do another |\begin{macrocode}|. It's that simple. +% \begin{macrocode} +} +% \end{macrocode} +% \end{environment} +% +% \Finale +\endinput diff --git a/info/dtxtut/skeleton.ins b/info/dtxtut/skeleton.ins new file mode 100644 index 0000000000..0f2277429b --- /dev/null +++ b/info/dtxtut/skeleton.ins @@ -0,0 +1,55 @@ +%% +%% Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org> +%% +%% This file may be distributed and/or modified under the conditions of +%% the LaTeX Project Public License, either version 1.3 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.3 or later is part of all distributions of LaTeX version +%% 2005/12/01 or later. +%% + +\input docstrip.tex +\keepsilent + +\usedir{tex/latex/skeleton} + +\preamble + +This is a generated file. + +Copyright (C) 2015 by Scott Pakin <scott+dtx@pakin.org> + +This file may be distributed and/or modified under the conditions of +the LaTeX Project Public License, either version 1.3 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.3 or later is part of all distributions of LaTeX version +2005/12/01 or later. + +\endpreamble + +\generate{\file{skeleton.sty}{\from{skeleton.dtx}{package}}} + +\obeyspaces +\Msg{*************************************************************} +\Msg{* *} +\Msg{* To finish the installation you have to move the following *} +\Msg{* file into a directory searched by TeX: *} +\Msg{* *} +\Msg{* skeleton.sty *} +\Msg{* *} +\Msg{* To produce the documentation run the file skeleton.dtx *} +\Msg{* through LaTeX. *} +\Msg{* *} +\Msg{* Happy TeXing! *} +\Msg{* *} +\Msg{*************************************************************} + +\endbatchfile |