summaryrefslogtreecommitdiff
path: root/support/classpack/classpack.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /support/classpack/classpack.dtx
Initial commit
Diffstat (limited to 'support/classpack/classpack.dtx')
-rw-r--r--support/classpack/classpack.dtx3028
1 files changed, 3028 insertions, 0 deletions
diff --git a/support/classpack/classpack.dtx b/support/classpack/classpack.dtx
new file mode 100644
index 0000000000..39c95c16fb
--- /dev/null
+++ b/support/classpack/classpack.dtx
@@ -0,0 +1,3028 @@
+% \iffalse meta-comment
+%
+% Extracted from classpack.xml
+% classpack.dtx is copyright © 2012-2013 by Peter Flynn <peter@silmaril.ie>
+%
+% This work 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.
+%
+% This work has the LPPL maintenance status `maintained'.
+%
+% The current maintainer of this work is Peter Flynn <peter@silmaril.ie>
+%
+% This work consists of the files classpack.dtx and classpack.ins,
+% the derived file classpack.sty, and any ancillary files listed
+% in the MANIFEST.
+%
+% \fi
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[2011/06/27]
+%<package>\ProvidesPackage{classpack}[2013/05/28 v0.77
+%<package> XML mastering for LaTeX classes and packages]
+%<*driver>
+\PassOptionsToPackage{svgnames}{xcolor}
+\documentclass[12pt]{ltxdoc}
+%%
+%% Packages added automatically
+%%
+\let\SavedShow\show
+\usepackage[utf8x]{inputenc}% was detected.
+\AtBeginDocument{\let\show\SavedShow}
+\DeclareUnicodeCharacter{9251}{\textvisiblespace}
+\usepackage[T1]{fontenc}% was detected.
+\usepackage{lmodern}% was detected.
+\usepackage{mflogo}% was detected.
+\usepackage{array}% tgroup was detected.
+\usepackage{calc}% was detected.
+\usepackage[inline]{enumitem}% orderedlist/@spacing='compact' was detected.
+\setlist[description]{style=unboxed}
+\usepackage{fancybox}% guibutton was detected.
+\usepackage{fancyvrb}% programlisting was detected.
+\usepackage{fmtcount}% xref/@linkend='varlistentry' was detected.
+\usepackage[textwidth=150mm,textheight=8.5in]{geometry}% was detected.
+\usepackage{listings}% programlisting was detected.
+\lstdefinelanguage[DocBook]{XML} {morekeywords={abstract,address,affiliation,annotation,arg,author, book,chapter,classname,cmdsynopsis,command,constraintdef,contrib, copyright,cover,date,email,emphasis,envar,filename,firstname, footnote,guibutton,guilabel,guimenu,guimenuitem,guisubmenu, holder,info,itemizedlist,listitem,literal,member,option, orderedlist,orgdiv,orgname,package,para,parameter,part, personname,phrase,procedure,productname,programlisting,quote, refsection,remark,constructorsynopsis,methodparan,modifier, funcparams,olink,bibliography,biblioentry,biblioset,subtitle, artpagenums,volumenum,issuenum, releaseinfo,replaceable,revdescription,revhistory,revision, sect1,sect2,sect3,sect4,seg,seglistitem,segmentedlist,segtitle, simplelist,step,surname,systemitem,tag,term,title,uri,userinput, variablelist,varlistentry,wordasword,xref,year,xml:id,xlink:href},}
+\lstdefinelanguage[TEI]{XML} {morekeywords={TEI.2,teiHeader,div2,head,p,num,val,xml:id}, }[keywords,comments,strings]
+\lstloadlanguages{[LaTeX]TeX,[DocBook]XML,XSLT,bash,R}
+\lstset{basicstyle=\small\color{Black}\ttfamily, literate= {Ö}{{\"O}}1 {Ä}{{\"A}}1 {Ü}{{\"U}}1 {ß}{{\ss}}2 {ü}{{\"u}}1 {á}{{\'a}}1 {é}{{\'e}}1 {í}{{\'i}}1 {ó}{{\'o}}1 {ú}{{\'u}}1 {ä}{{\"a}}1 {ö}{{\"o}}1, keywordstyle=\color{DarkGreen}\bfseries, commentstyle=\color{Gray}\upshape, stringstyle=\color{DarkRed}\upshape, emphstyle=\color{MediumBlue}\itshape, showstringspaces=false, columns=fullflexible, keepspaces=true}
+\usepackage{makeidx}% was detected.
+\makeindex
+\usepackage{nicefrac}% was detected.
+\def\textonehalf{\ensuremath{\nicefrac12}}
+\usepackage{parskip}% was detected.
+\usepackage{url}% uri was detected.
+\usepackage{varioref}% xref was detected.
+\vrefwarning
+\labelformat{chapter}{Chapter~#1}
+\makeatletter
+\labelformat{chapter}{\@chapapp~#1}
+\makeatother
+\labelformat{section}{section~#1}
+\labelformat{subsection}{section~#1}
+\labelformat{subsubsection}{section~#1}
+\labelformat{paragraph}{section~#1}
+\labelformat{figure}{Figure~#1}
+\labelformat{table}{Table~#1}
+\labelformat{item}{item~#1}
+\renewcommand{\reftextcurrent}{elsewhere on this page}
+\def\reftextafter{on the \reftextvario{next}{following} page}
+\usepackage[svgnames]{xcolor}% was detected.
+\makeatletter
+\@ifundefined{T}{\newcommand{\T}[2]{{\fontencoding{T1}\selectfont#2}}}{}
+\makeatother
+\usepackage{dox}% was detected.
+\doxitem{Attribute}{attribute}{attributes}
+\doxitem{AttributeValue}{attributevalue}{attribute values}
+\doxitem{Class}{class}{classes}
+\doxitem{Colour}{colour}{colours}
+\doxitem{Counter}{counter}{counters}
+\doxitem{DTD}{dtd}{DTDs/Schemas}
+\doxitem{Element}{element}{element types}
+\doxitem{Entity}{entity}{entities}
+\doxitem{Error}{error}{errors}
+\doxitem{Function}{function}{functions}
+\doxitem[macrolike]{Length}{length}{lengths}
+\doxitem{Mode}{mode}{mode}
+\doxitem{Option}{option}{options}
+\doxitem{Package}{package}{packages}
+\doxitem{Template}{template}{templates}
+\newcommand{\LabelFont}[2][\relax]{\strut {\fontencoding\encodingdefault \fontfamily{lmtt}\fontseries{lc}\selectfont#1#2}\space}
+\makeatletter
+\def\PrintDescribeAttribute#1{\LabelFont{@#1}}
+\makeatother
+\def\PrintDescribeAttributeValue#1{\LabelFont[\itshape]{#1}}
+\def\PrintDescribeClass#1{\LabelFont{#1}}
+\def\PrintDescribeColour#1{\LabelFont[\color{#1}]{#1}}
+\def\PrintDescribeCounter#1{\LabelFont{#1}}
+\def\PrintDescribeDTD#1{\LabelFont{#1}}
+\def\PrintDescribeElement#1{\LabelFont{<#1>}}
+\def\PrintDescribeEntity#1{\LabelFont{\&#1;}}
+\def\PrintDescribeError#1{\LabelFont[\color{Red}!]{#1}}
+\def\PrintDescribeFunction#1{\LabelFont{#1}}
+\def\PrintDescribeLength#1{\LabelFont{#1}}
+\def\PrintDescribeMode#1{\LabelFont[\sffamily]{\textlangle#1\textrangle}}
+\def\PrintDescribeOption#1{\LabelFont[\itshape]{#1}}
+\def\PrintDescribePackage#1{\LabelFont{#1}}
+\def\PrintDescribeTemplate#1{\LabelFont[\fontfamily{lmss}\fontseries{sbc}\selectfont]{#1}}
+\usepackage{apacite}
+%%
+%% Packages added by author
+%%
+\usepackage{dejavu}
+\usepackage{textgreek}
+\usepackage{classpack}
+%%
+%% Settings for docstrip and latexdoc
+%%
+\EnableCrossrefs
+\CodelineIndex
+\RecordChanges
+\newlength{\revmarg}
+\setlength{\revmarg}{1in}
+\newcommand{\vstrut}{\vrule height1.2em depth.6667ex width0pt}
+\newcommand{\prestrut}{\vrule height1em width0pt}
+\newcommand{\poststrut}{\vrule depth.5ex width0pt}
+\begin{document}\raggedright\hyphenation{ele-ment attri-bute-value}
+ \DocInput{classpack.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+% \CheckSum{45}
+%
+% \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{v0.77}{2013/05/28}{Removed unwanted definitions: classorpackage.}
+% \changes{v0.76}{2013/05/05}{Modified documentation: Started working on Makefile.}
+% \changes{v0.75}{2013/03/14}{Added secondary files: Secondary output files possible; reversed usage of role attribute on keywords;.}
+% \changes{v0.74}{2013/02/21}{Added experimental autopackage: This implements automated package inclusion based on the markup used by the author..}
+% \changes{v0.73}{2012/06/19}{Added readme.xml and db2plaintext.xsl: This implements dynamic README generation..}
+% \changes{v0.72}{2012/02/11}{Wrote internal documentation: Created the classpack.xml template as an example..}
+% \changes{v0.71}{2012/02/08}{First time this was used to document itself: The title element and subtitle element are now subsumed beneath the generated title in the output..}
+%
+% \GetFileInfo{classpack.dtx}
+%
+% \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty}
+% \DoNotIndex{\@flushglue,\@gobble,\@input}
+% \DoNotIndex{\@makefnmark,\@makeother,\@maketitle}
+% \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa}
+% \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue}
+% \DoNotIndex{\@thanks,\@thefnmark,\@topnum}
+% \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin}
+% \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces}
+% \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup}
+% \DoNotIndex{\mathcal,\csname,\def,\documentstyle,\dospecials,\edef}
+% \DoNotIndex{\egroup}
+% \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist}
+% \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global}
+% \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn}
+% \DoNotIndex{\ifcase}
+% \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item}
+% \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower}
+% \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing}
+% \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc}
+% \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut}
+% \DoNotIndex{\strutbox}
+% \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt}
+% \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@}
+% \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim}
+% \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary}
+% \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle}
+% \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode}
+% \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip}
+% \DoNotIndex{\nopagebreak}
+% \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle}
+% \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb}
+% \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar}
+% \DoNotIndex{\[,\{,\},\]}
+% \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode}
+% \DoNotIndex{\baselineskip,\begin,\tw@}
+% \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q}
+% \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H}
+% \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z}
+% \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0}
+% \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_}
+% \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother}
+% \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment}
+% \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined}
+% \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc}
+% \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar}
+% \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode}
+% \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting}
+% \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf}
+% \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse}
+% \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault}
+% \DoNotIndex{\bfdefault,\DeclareRobustCommand}
+% \DoNotIndex{\varname}
+% \DoNotIndex{\section}
+% \DoNotIndex{\subsection}
+% \DoNotIndex{\raggedright}
+% \DoNotIndex{\sffamily}
+% \DoNotIndex{\usepackage}
+% \DoNotIndex{\title}
+% \DoNotIndex{\author}
+% \DoNotIndex{\abstractname}
+% \DoNotIndex{\changes}
+% \DoNotIndex{\RequirePackage}
+% \DoNotIndex{\LoadPackage}
+% \DoNotIndex{\makeindex}
+% \DoNotIndex{\makeatletter}
+% \DoNotIndex{\makeatother}
+% \DoNotIndex{\def}
+% \DoNotIndex{\newwrite}
+% \DoNotIndex{\classorpackage}
+% \DoNotIndex{\@@doxdescribe}
+% \DoNotIndex{\build}
+% \DoNotIndex{\label}
+% \DoNotIndex{\small}
+% \DoNotIndex{\ttfamily}
+% \DoNotIndex{\cite}
+% \DoNotIndex{\citefield}
+% \DoNotIndex{\url}
+% \DoNotIndex{\ref}
+% \DoNotIndex{\parskip}
+% \DoNotIndex{\java}
+% \DoNotIndex{\./build}
+% \setcounter{secnumdepth}{5}
+% \setcounter{tocdepth}{5}
+% \setcounter{IndexColumns}{2}
+% \setlength{\columnsep}{3pc}
+%
+% \def\fileversion{0.77}
+% \def\filedate{2013/05/28}
+% \title{The \textsf{classpack} \LaTeXe\ package\thanks{%
+% This document corresponds to \textsf{classpack}
+% \textit{v.}\ \fileversion, dated \filedate.}\enspace\thanks{%
+% Development has been supported by UCC Electronic Publishing Unit.}
+% \\[1em]\Large
+% XML mastering for \LaTeX{} classes and packages}
+% \author{Peter Flynn\\\normalsize Silmaril Consultants\\[-.25ex]\normalsize Textual Therapy Division\\\normalsize(\url{peter@silmaril.ie})}
+% \maketitle
+% \renewcommand{\abstractname}{Summary}\thispagestyle{empty}
+% \begin{abstract}
+% \parskip=0.5\baselineskip
+% \advance\parskip by 0pt plus 2pt
+% \parindent=0pt% \noindent
+% \LaTeX{} document classes and packages are normally
+% created, maintained, and distributed in
+% {\ttfamily{}.dtx} format using the
+% \textsf{ltxdoc} class, which provides facilities for
+% modular or fragmentary coding combined with interleaved
+% documentation. However, the accurate construction of these
+% files is technically challenging.\par
+% \emph{ClassPack} allows a developer to
+% create an XML document containing user documentation and
+% annotated code, based on the
+% \emph{DocBook} vocabulary (with some minor
+% abuses). An XSLT2 script then generates the
+% {\ttfamily{}.dtx} and {\ttfamily{}.ins} files,
+% ensuring that all the relevant pieces are emitted in the
+% correct order and in the correct syntax.\par
+% This is experimental software, and is incomplete. It has
+% been successfully used in-house by the author since 2008 for
+% several institutional and commercial packages and classes.
+% There are some known deficiencies which remain to be
+% corrected, and some legacy code (originally included for one
+% specific package) which needs to be removed to an external
+% file.\par
+% A paper describing the system has been accepted for the
+% Balisage markup conference 2013 in Montréal.\par
+% \end{abstract}
+% \clearpage
+% \tableofcontents
+% \clearpage
+% \section{Introduction}
+% \LaTeX{} document classes (templates) and packages (styles)
+% are traditionally distributed as pairs of
+% {\ttfamily{}.dtx} and{\ttfamily{}.ins} files,
+% written to the specifications and recommendations of the
+% \textsf{doc}, \textsf{ltxdoc}, and
+% \textsf{clsguide} packages.\par
+% \begin{itemize}
+% \item The {\ttfamily{}.dtx} (Doc\TeX{}) file is a
+% literate-programming document, containing modular code and
+% annotations interleaved in such a way that each fragment
+% of code and its explanation are adjacent;
+% \item The {\ttfamily{}.ins} file is an installer:
+% when run through \LaTeX{}, it extracts the code from the
+% {\ttfamily{}.dtx} file into the relevant class
+% ({\ttfamily{}.cls}), package
+% ({\ttfamily{}.sty}), and other files;
+% \item Running \LaTeX{} on the {\ttfamily{}.dtx} file
+% itself extracts and typesets the documentation.
+% \end{itemize}
+% The construction of a {\ttfamily{}.dtx} document
+% is quite complex, with a special set of tags and conventions
+% to allow documentation to be separately identifiable to code.
+% The file format relies on the documentation being shielded by
+% a leading percent-space (\verb|%␣|) armour
+% on each line to prevent it being interpreted as part of the
+% code; and the environment tags surrounding the code itself
+% must be shielded by four such spaces
+% (\verb|%␣␣␣␣|). Apart from the
+% documentation, the treatment of the code and control
+% statements resembles more a data specification (which in some
+% ways it is) than a conventional text document.\par
+% XML, particularly in its traditional
+% `document' mode, as distinct from its
+% use as a data exchange format, offers many similar features to
+% \LaTeX{} (for example, the named identification of document
+% components), but with a rigid and invariable syntax that can
+% be checked programmatically by any validating XML processor.
+% By contrast, a \LaTeX{} document (and more specifically, a
+% {\ttfamily{}.dtx} document) can only be proved by
+% running it through \LaTeX{} itself: there is no equivalent to
+% the `pre-flight' type of standalone parsing or
+% validating available with XML.\par
+% The \emph{DocBook} vocabulary of XML
+% is designed for technical documentation in computing. It
+% provides markup both for textual documentation
+% \emph{and} for data-like structures that occur
+% in computer documentation, making it a viable candidate for
+% describing a literate-programming type of document such as
+% Doc\TeX{}.\par
+% The \emph{ClassPack} system is an
+% experiment in using \emph{DocBook} XML as
+% the storage format for \LaTeX{} class and package source code,
+% using the XLST2 language to transform the XML into pairs of
+% {\ttfamily{}.dtx} and {\ttfamily{}.ins} files.
+% There are a number of advantages to this approach:\par
+% \begin{itemize}
+% \item XML's syntax and document construction is extremely
+% robust, and the design of the language means that an XML
+% file can be machine-checked for errors of syntax and
+% construction;
+% \item XML markup is traditionally self-descriptive, with
+% element types being named according to what they are
+% intended to contain. For example, a variable name can be
+% marked up as
+% \verb|<varname>foo</varname>|.\par
+% While it is perfectly possible to create a
+% {\ttfamily{}\textbackslash{}varname} control sequence (macro) to do
+% the same in \LaTeX{}, it is rarely done. Instead, authors
+% have typically preferred to use visual formatting like
+% \verb|\textit{foo}| for italics or
+% \verb|\verb+foo+| for monospace type.
+% This method means the variable reference is not
+% immediately identifiable as containing a variable
+% name~--- it could be anything;
+% \item Given suitably-descriptive markup, sharing document
+% fragments between applications can be done
+% programmatically, so a fragment implementing a \LaTeX{}
+% feature (with its associated documentation) can be re-used
+% in other class and package applications at the XML level
+% (eg with XInclude, or as an external entity) without the
+% need for manual cutting and pasting;
+% \item \label{xmltools}There is a very wide range of software (editors and
+% processors, both free and non-free) available to handle
+% XML documents, including a lot of useful tools for
+% document management and information extraction.
+% \end{itemize}
+% Everything comes at a cost. The drawbacks of using XML for
+% this include:\par
+% \begin{itemize}
+% \item It's another language to learn. Despite being so
+% widespread, it's not yet a common skill. In particular,
+% programmers dislike XML because it's a markup language,
+% not a programming language, and the syntax is different
+% from that of programming languages;
+% \item Although there is plenty of software for editing XML,
+% it is not well-developed for text documents in synchronous
+% typographic form (often called
+% `WYSIWYG'); even the best or most
+% expensive editors are designed for XML experts, not for
+% the average user.
+% \end{itemize}
+% \subsection{Contents}
+% The \emph{ClassPack} framework is
+% enabled by two principal software components:\par
+% \begin{enumerate}
+% \item An XML vocabulary (the
+% \emph{DocBook}~{\small DTD}\index{DTD}
+% or Schema) used for naming the component parts of
+% documentation and code, and specifying where they belong
+% and how they fit together;
+% \item An XSLT2 script to implement the logic of
+% combination and separation needed to create the
+% {\ttfamily{}.dtx} and {\ttfamily{}.ins}
+% files.
+% \end{enumerate}
+% The XML vocabulary used is
+% \emph{DocBook}, which is in widespread
+% use for the documentation of computer systems, and is
+% well-supported on all platforms. The current system uses
+% version 5. Although it is highly modular and easily adapted
+% for many purposes, only a few minor changes have been made
+% for its use here, but a number of element types have been
+% put to uses not envisaged by the developers.\par
+% This habit of using (some say, abusing) XML markup for
+% different purposes is very common, and often deprecated
+% because it is usually undocumented. This document explains
+% what has been [ab]used and for what reasons. Once this
+% system settles down, a more formal expression of the
+% vocabulary can be made from the RNG source, removing the
+% parts that are not required, and making it simpler to edit
+% with.\par
+% The adaptation of \emph{DocBook} in
+% this version subsists mainly in the addition of some
+% attributes and entity declarations to allow the conversion
+% to \LaTeX{} of special characters and other features that
+% would otherwise involve extensive re-parsing of the
+% character data content (text). The changes also implement a
+% few modifications to the way the \LaTeX{} code is output by
+% the XSLT2 program for typographical purposes.\par
+% As an example, the entity defining the em rule character
+% \texttt{\&mdash;} is declared as a \LaTeX{}
+% tie (non-breaking space) followed by an em rule followed by
+% a normal space (\verb|~---␣|), so that it
+% can be used between words~--- like this~--- without the
+% need to worry about special spacing in the XML, or the
+% inadvertent breaking of a line before the rule:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XML]
+can be used between words&mdash;like this&mdash;without the
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% If a
+% document style requires the use of unspaced dashes, all that
+% needs changing is the entity declaration, not the whole
+% document.\par
+% The current driver in Document Type
+% Definition~(\textsc{dtd})\index{Document Type Definition|see{DTD}}\index{DTD|textbf} format is listed in \vref{savedtd}, and is distributed as file
+% {\ttfamily{}doctexbook.dtd} so that it can be
+% referenced as such in a document without having to copy and
+% paste the declarations into every document.\par
+% \subsection{Invocation}\label{invocation}
+% To create or edit a \emph{ClassPack}
+% XML document you must have the
+% \emph{ClassPack} DTD
+% \emph{and} the DocBook DTD installed and known
+% to your XML editor. The DTD customisation file,
+% {\ttfamily{}docbooktex.dtd} is distributed with this
+% package; an RNG schema version will be available in the
+% future.\par
+% With the DTD, the standard procedure is to specify it in
+% the first line of your XML document. Your class or package
+% documents must therefore start with a Document Type
+% Declaration. This can specify the Formal
+% Public Identifier~(\textsc{fpi})\index{Formal Public Identifier|see{FPI}}\index{FPI|textbf} and the filename of the
+% DTD:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XML]
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC
+ "+//Silmaril//DTD DocBook 5.0 for DocTeX//EN"
+ "doctexbook.dtd">
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% or
+% you can omit the {\small FPI}\index{FPI} and specify the DTD as a \texttt{SYSTEM} keyword instead:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XML]
+<?xml version="1.0"?>
+<!DOCTYPE book SYSTEM "doctexbook.dtd">
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% The DTD file {\ttfamily{}doctexbook.dtd} can be
+% anywhere on your system: in these examples it is assumed to
+% be in the same directory as your document. If you store it
+% elsewhere, just give the full filepath, for example:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XML]
+<?xml version="1.0"?>
+<!DOCTYPE book SYSTEM "/usr/local/lib/xml/dtds/doctexbook.dtd">
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% When you open a document starting like this, a
+% conformant XML editor will look for
+% {\ttfamily{}doctexbook.dtd} and read it, so that it
+% then knows the names of all the element types that you can
+% use, and how they fit together into a document.\par
+% \subsection{Document structure}
+% Every XML document must have one outermost enclosing
+% element (the `root' element) which
+% holds everything else. The root element type used in a
+% ClassPack document is \texttt{book}, as described in
+% detail in \vref{setup}.\par
+% Within the \texttt{book} element, the
+% \emph{metadata} (information about the
+% document) is held in an \texttt{info} element, the
+% \emph{user documentation} in a \texttt{part}
+% element with the ID of \texttt{doc}, and the
+% \emph{annotated code} in a second
+% \texttt{part} element, with the ID of
+% \texttt{code}.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<?xml version="1.0"?>
+<!DOCTYPE book SYSTEM "doctexbook.dtd">
+<book>
+ <info>...</info>
+ <part xml:id="doc">...</part>
+ <part xml:id="code">...</part>
+ <part xml:id="files">...</part>
+</book>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% An optional third \texttt{part} with the ID of
+% \texttt{files} can be used to include ancillary files that
+% are to be recreated as-is, without separate annotation or
+% display, such as sample data or example documents (see \vref{ancfiles}).\par
+% Ancillary files that require annotating must go in the
+% \texttt{code} part as described in
+% \vref{secfiles}.\par
+% \subsubsection{User documentation}
+% The documentation for the end user is descriptive text
+% which explains how to use the package or class. The main
+% division within a ClassPack \texttt{part} is the
+% \texttt{chapter}, which can contain \texttt{sect1}
+% sections, which can contain \texttt{sect2} subsections,
+% and so on, as described in
+% \vref{hierarchy}. User documentation must go in
+% a \texttt{chapter} and its sub-elements: it must not be
+% directly in the \texttt{part}.\par
+% (Because the \textsf{latexdoc} package is
+% based on the \textsf{article} package, the
+% ClassPack \texttt{chapter}\thinspace{}s become
+% \textsf{latexdoc}~{\ttfamily{}\textbackslash{}section}s;
+% the ClassPack \texttt{sect1}\thinspace{}s become
+% \textsf{latexdoc}~{\ttfamily{}\textbackslash{}subsection}s,
+% and so on.)\par
+% \paragraph{Structure}
+% Your document can use most of the conventional
+% structural features of any DocBook document: paragraphs,
+% lists, figures, tables, and examples of code (both
+% illustrative and for extraction) as described in \vref{pool}. Most of the specialist constructs of
+% DocBook are not implemented in ClassPack except for a
+% few used in the \texttt{info} section for setup
+% purposes. You should refer to the list of markup in
+% \vref{pool} for exactly which element types
+% do what.\par
+% \paragraph{Inline markup}
+% Within the text you can use much of the conventional
+% semantic markup provided in
+% \emph{DocBook} as described in \vref{flow}.\par
+% \subsubsection{Annotated code}
+% In the \texttt{code} Part, you annotate the inner
+% workings of your package or class. The use of the
+% \texttt{chapter} and \texttt{sect1} divisional
+% structure is also mandated here: everything within the
+% chapters is regarded as the package or class.\par
+% Your code can be explained in fragments, either as
+% alternating \texttt{para} and \texttt{programlisting}
+% elements, or as \texttt{annotation} elements, each one
+% describing a single macro or environment or other object,
+% and containing \texttt{para} and
+% \texttt{programlisting} (this makes it indexable). See
+% the examples in \vref{pool}.\par
+% \subsubsection{Ancillary files}\label{ancfiles}
+% There are two types of extractable ancillary
+% file:\par
+% \begin{itemize}
+% \item Ancillary files to be annotated and extracted
+% along with the class or package file must each go in
+% their own \texttt{appendix} element immediately
+% after the last of the \texttt{chapter} element of
+% the package or class in the \texttt{code}
+% Part
+% \item Ancillary files which just need to be extracted
+% whole, and do not have any separate documentation must
+% go in the \texttt{files} Part as described in \vref{ancfiles}.
+% \end{itemize}
+% \subsection{Tooling up}
+% You need the following tools:\par
+% \begin{itemize}
+% \item an XML editor: I use
+% \emph{Emacs} with
+% \emph{psgml-mode} and
+% \emph{xxml-mode}, but any competent
+% XML editor will do
+% \item an XSLT2 processor: I use
+% \emph{Saxon} (this also means I
+% installed \emph{Java})
+% \item a full installation of \LaTeX{}
+% \item a PDF reader
+% \item XML tools: I find the
+% \emph{LTxml2} toolkit from Edinburgh
+% University invaluable for ad-hoc querying of
+% documents.
+% \end{itemize}
+% \clearpage
+% \section{Setting up a ClassPack document}
+% Using \emph{ClassPack} to create and
+% maintain \LaTeX{} classes and packages requires the following
+% initial steps. These are only done once, at the start of a new
+% class or package. A few items need periodic updating, such as
+% the version number, when it changes; the revision history; and
+% the list of packages, as and when needed.\par
+% \begin{enumerate}
+% \item setting up the configuration (see \vref{setup})
+% to specify the name, date, version, type, audience, status,
+% and other key metadata;
+% \item setting up the documentary metadata (see \vref{metadata}) such as the title, author, contact
+% details, abstract, and the initial entry in the revision
+% history;
+% \item setting up the list of packages (see \vref{constraints}) required for
+% \begin{enumerate*}[label=\emph{\alph*})]
+% \item the documentation (see \vref{docpax})
+% and
+% \item the class or package itself (see \vref{classtypax})
+% \end{enumerate*}, plus any additional initialization
+% commands needed for the documentation.
+% \end{enumerate}
+% \emph{Note particularly that the list of packages
+% required by the class or package itself is
+% \emph{not} stored inline to the code of the
+% class or package. It is stored separately for reasons that
+% are explained in detail in \vref{constraints}.}\par
+% \subsection{Configuration and setup}\label{setup}
+% The \texttt{book} element is the outermost container
+% for the document. It is used to carry the configuration
+% information in attributes, for example:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<book xml:id="classpack" arch="class" version="0" revision="71"
+ status="beta" conformance="LaTeX2e" condition="2011-06-27"
+ os="all" audience="lppl" security="0" vendor="Silmaril"
+ xml:base="tex/latex" xlink:role="xxx" userlevel="cls"
+ annotations="\raggedright" remap="a4paper,12pt">
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \begin{description}[style=unboxed]
+% \item[\texttt{xml:id}\thinspace:]\label{rootid}This \textsc{must} be the
+% name of the class or package. It will be used as the
+% \LaTeX{} filename (with {\ttfamily{}.cls} or
+% {\ttfamily{}.sty} and
+% {\ttfamily{}.ins} added automatically), so it
+% \textsc{should} be all lowercase
+% and \textsc{must} consist of
+% letters, digits, and hyphens only, starting with a
+% letter.\par
+% The XML rules for IDs require this restriction,
+% which currently makes it impossible to use ClassPack
+% to maintain a class or packages whose name begins with
+% a digit.
+% \item[\texttt{arch}\thinspace:]\label{arch}The `architecture' of the
+% document, which defines the type of file you are going
+% to produce; this must be either \texttt{"class"} or \texttt{"package"}, corresponding
+% exactly with the value of the \texttt{userlevel}
+% attribute below.
+% \item[\texttt{userlevel}\thinspace:]\label{userlevel}The file type of the class or package document;
+% this must be either {\ttfamily{}cls} or
+% {\ttfamily{}sty}, corresponding
+% exactly with the value of the \texttt{arch}
+% attribute above.
+% \item[\texttt{version}\thinspace:]The major version of the class or package.
+% Conventionally, development (α) or pre-release
+% (β) versions of software start at version
+% zero.
+% \item[\texttt{revision}\thinspace:]\label{revno}The sub-version or release of your class or
+% package. This is combined with the major version
+% number, separated by a dot, to produce the complete
+% version number.\par
+% The most recent revision history entry gets tested
+% against this when the file is processed, and an error
+% message is displayed if the version numbers do not
+% match, as a warning that you have updated one without
+% updating the other, and may therefore have forgotten
+% to document a change (see the \texttt{revision}
+% element in
+% `\textbf{\texttt{revhistory}}', the last item in the list in \vref{revhist}).
+% \item[\texttt{status}\thinspace:]The development status of the class or package, eg
+% \texttt{"alpha"}, \texttt{"beta"}, \texttt{"candidate"}, \texttt{"draft"}, \texttt{"final"}, etc.
+% \item[\texttt{conformance}\thinspace:]The \TeX{} format required to process the
+% {\ttfamily{}.dtx} document. Only the value
+% \texttt{"LaTeX2e"} is supported at
+% the moment.
+% \item[\texttt{condition}\thinspace:]The version of the format identified in \texttt{conformance}, expressed as an
+% ISO date (\texttt{"yyyy-mm-dd"}).\par
+% Note that this is \emph{not} in the
+% \LaTeX{} format
+% ({\ttfamily{}yyyy/mm/dd}).
+% \item[\texttt{os}\thinspace:]The operating system[s] for which the class or
+% package is relevant. Currently, only the value \texttt{"all"} is supported.
+% \item[\texttt{audience}\thinspace:]The licence under which the class or package is
+% made available. For normal publicly-available \LaTeX{}
+% classes or packages which will be uploaded to CTAN,
+% use the value \texttt{"lppl"}
+% (\LaTeX{} Project Public Licence).\par
+% A copy of the LPPL is distributed with ClassPack
+% in a file called {\ttfamily{}lppl.xml}, which
+% must be copied or soft-linked (aliased) to each
+% directory in which you process ClassPack
+% documents.\par
+% Classes or packages for private or commercial use
+% will probably need to use another value, but it is
+% used as a filename, so a {\ttfamily{}.xml}
+% file with that name must exist in the directory in
+% which your ClassPack document is processed. It must
+% contain a
+% \emph{DocBook}~\texttt{chapter}
+% element containing the text of the licence, which will
+% be included at the end of the documentation.
+% \item[\texttt{security}\thinspace:]The checksum value emitted by
+% \textsf{ltxdoc} when it processes your class
+% or package to format your documentation. See the
+% documentation for the \textsf{ltxdoc} package for details.\par
+% Setting this to zero avoids the \LaTeX{} error
+% message during early development, when every edit
+% would change the checksum. As with the version values,
+% you must update this value, if non-zero, to match the
+% one that \textsf{ltxdoc} reports.
+% \item[\texttt{vendor}\thinspace:]Your name, or the name of the organisation
+% responsible for the work on this class or package.
+% \item[\texttt{remap}\thinspace:]Any options to pass to the
+% \textsf{ltxdoc} package, such as
+% \textbf{\texttt{a4paper}}, \textbf{\texttt{12pt}},
+% etc.\par
+% This, and the following \texttt{annotations}
+% attribute, make it easier to change the global
+% formatting of the documentation.
+% \item[\texttt{annotations}\thinspace:]Any \LaTeX{} commands required for global
+% application at the start of the documentation that
+% cannot easily be included anywhere else (eg
+% {\ttfamily{}\textbackslash{}raggedright},
+% {\ttfamily{}\textbackslash{}sffamily}, etc).
+% \item[\texttt{xml:base}\thinspace:]The name of the \emph{subdirectory}
+% where the resulting {\ttfamily{}.cls} or
+% {\ttfamily{}.sty} file should be installed in
+% a TDS-compliant \TeX{} installation, relative to the
+% {\ttfamily{}texmf/tex/latex} directory of the
+% tree. For most packages, this means the name of the
+% directory you want created by the installation
+% {\ttfamily{}.tds.zip} file, in which the
+% {\ttfamily{}.cls} or {\ttfamily{}.sty}
+% file will be put.
+% \item[\texttt{xlink:role}\thinspace:]\label{selfspec}\textsc{Optional}. If this
+% is set to a value, then the package being written will
+% be included in the setup for the documentation
+% (perhaps so that it can be used in examples), with the
+% value of this attribute being used as the optional
+% argument to the generated
+% {\ttfamily{}\textbackslash{}usepackage} command.\par
+% If the package is required with no options, use
+% this attribute but set it to null (\texttt{""}). The date constraint is
+% added automatically, using the current package date as
+% defined by the most recent entry in the
+% \texttt{revhistory}.\par
+% Note that this only works for packages, not
+% classes. Classes cannot not be documented using
+% themselves.
+% \end{description}
+% It is essential to get these values correct, otherwise
+% subsequent processing will produce unexpected
+% results, or no results at all.\par
+% \subsection{Metadata}\label{metadata}
+% The titling, specification of packages (separately for
+% the documentation and for the class or package itself),
+% revision history, abstract, copyright, and availability are
+% all kept at the top of the document in an element called
+% \texttt{info}, immediately after the \texttt{book} start-tag:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<info>
+ <cover>...</cover>
+ <!-- THE METADATA STARTS HERE -->
+ <title>XML mastering for &amp;LaTeX; document classes...
+ <author>...
+ <copyright>...
+ <releaseinfo>http://latex.silmaril.ie/software</releaseinfo>
+ <annotation>...
+ <abstract>...
+ <revhistory>...
+</info>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% Of these, the \texttt{cover} element is the most
+% complex, as it is [ab]used to hold all the details of
+% packages and settings required for the class or package
+% \emph{and} for the production of the
+% documentation. It therefore gets the whole of
+% \vref{constraints} to itself.\par
+% The other metadata element types are more obvious, and
+% largely use the \emph{DocBook} markup as
+% intended.\par
+% \begin{description}[style=unboxed]
+% \item[\texttt{title}\thinspace:]This contains the title of the class or package in
+% natural language. This is \emph{not} the
+% content of the {\ttfamily{}\textbackslash{}title} command in
+% \LaTeX{} terms, in the {\ttfamily{}.dtx} file,
+% which is automatically preset to the phrase
+% `The \textsf{{\itshape name}}
+% \LaTeXe{} document class' (or
+% `package'; where
+% {\itshape name} is the name of your
+% class or package as specified in the \texttt{xml:id} attribute of the
+% \texttt{book} root element).\par
+% The title you give in
+% \emph{this}~\texttt{title}
+% element is the explanatory subtitle which appears
+% \emph{under} the automatically-generated
+% one on the first page of the typeset
+% documentation.
+% \item[\texttt{author}\thinspace:]The \texttt{author} element provides identity
+% markup for the author[s], using a
+% \texttt{personname} element for each author,
+% containing subelements for firstname, surname, and
+% other forms of naming; optionally followed by an
+% \texttt{affiliation} element, where you can identify
+% employer or other status; address; email; and URI, as
+% in the following example. The name, affiliation, and
+% email address are used in the
+% {\ttfamily{}\textbackslash{}author} command of the
+% {\ttfamily{}.dtx} file.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<author role="maintainer">
+ <personname>
+ <firstname>Peter</firstname>
+ <surname>Flynn</surname>
+ </personname>
+ <affiliation>
+ <orgname>Silmaril Consultants</orgname>
+ <orgdiv>Textual Therapy Division</orgdiv>
+ </affiliation>
+ <address>Cork, Ireland</address>
+ <email>peter@silmaril.ie</email>
+ <uri>http://blogs.silmaril.ie/peter</uri>
+ <contrib role="sponsor">UCC</contrib>
+</author>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% For multiple authors, you must enclose multiple
+% \texttt{author} elements (one per author) in an
+% outer \texttt{authorgroup} container element. One of
+% the authors must be identified as the maintainer of
+% the package or class, by adding the \texttt{role}
+% attribute with the value
+% {\ttfamily{}maintainer}.\par
+% A \texttt{contrib} element with a \texttt{role} attribute set to \texttt{"sponsor"} can be added in an
+% \texttt{author} block, to give the
+% name of an organisation sponsoring the development of
+% the class or package.
+% \item[\texttt{copyright}\thinspace:]This element lets you identify the \texttt{year}
+% and the name of the \texttt{holder} (you, your
+% employer, or some other entity).
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<copyright>
+ <year>2012</year>
+ <holder>Silmaril Consultants</holder>
+</copyright>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \item[\texttt{releaseinfo}\thinspace:]In the absence of other ways of identifying where
+% to find your class or package (assuming it will
+% eventually find its way onto CTAN), this element can
+% be used to hold the URI of a location where it can be
+% downloaded, such as your personal or business web
+% site.
+% \item[\texttt{annotation}\thinspace:]This element is used for a warning or notice you
+% want placed in the Preamble of the
+% {\ttfamily{}.ins} file, which is used for
+% extracting your class or package from the
+% {\ttfamily{}.dtx} file, where it will be seen
+% by users installing the software.
+% \item[\texttt{abstract}\thinspace:]The Abstract is formatted on the front page of
+% your documentation. Like any abstract, it should
+% summarise what the class or package does, and who might
+% want to use it.\par
+% The \texttt{abstract} element may start with an
+% optional \texttt{title} element, which (if present)
+% will be used to change the value of the
+% {\ttfamily{}\textbackslash{}abstractname} in the
+% {\ttfamily{}.dtx} file
+% (`Summary' is a common
+% choice).\par
+% The rest of the abstract is just paragraphs; note
+% that lists, block quotations, figures, tables, etc are
+% not allowed in an Abstract.
+% \item[\texttt{revhistory}\thinspace:]\label{revhist}This holds the top-level information about each
+% major and minor revision, outlining the main changes.
+% The version number of the most recent revision, as
+% identified by the latest value of the \texttt{conformance} attribute of the
+% \texttt{date} element, must match the version number
+% composed from the major version and the revision in
+% the \texttt{book} root element (see `\textbf{\texttt{revision}}', the \ordinalstringnum{5} item in the list in \vref{revno}).\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<revision version="0.72">
+ <date conformance="2012-02-11"/>
+ <revdescription>
+ <itemizedlist>
+ <title>Wrote internal documentation</title>
+ <listitem>
+ <para>Created the classpack.xml template
+ as an example.</para>
+ </listitem>
+ </itemizedlist>
+ </revdescription>
+</revision>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% Comments on individual changes to the code should
+% be documented \emph{at the code
+% location}, using the \texttt{remark}
+% element (see \vref{maintenance}), eg\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<remark version="0.70" revision="2010-05-29">Added
+ timestamp</remark>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% These \texttt{remark} elements get collated as
+% {\ttfamily{}\textbackslash{}changes} commands, and gathered
+% together in the changelog by \textsf{ltxdoc}
+% during processing.
+% \end{description}
+% \subsection{Packages and related commands}\label{constraints}
+% As mentioned above, the \texttt{cover} element is used
+% to provide a place where packages and other \LaTeX{}
+% preliminaries can be specified. Using this structure means
+% each entry is separately editable, and the same structure is
+% used both for packages for the documentation
+% \emph{and} packages for the class or package
+% itself.\par
+% It would of course have been possible just to allow a
+% slab of \LaTeX{} code at these points, but that would have made
+% commenting and documentation harder, and would also have
+% made it more difficult to perform an XML
+% element-copy--element-paste or an XInclude when using
+% one package or class's settings as the basis for another.\par
+% The most important reason is that specifying package
+% lists as separately-identifiable blocks makes it possible to
+% automate the invocation of frequently-used packages,
+% parameters, options, or settings which you may store
+% separately for re-use (see \vref{autospec}) by
+% adding your own modifications that you like to have included
+% whenever you use a particular package.\par
+% In particular, the
+% \emph{autopackage} feature added to
+% ClassPack in v0.74 means that most packages needed for
+% documentation are now detected automatically on the basis of
+% features you use in your documentation, making it
+% unnecessary to specify them by hand. For example, if you use
+% compact lists, ClassPack will detect this and add the
+% \textsf{enumitem} package for you.\par
+% The XSLT2 program also uses this markup in order to
+% modify the behaviour of the \LaTeX{} code at several points
+% (such as fixing the broken abstract formatting when the
+% \textsf{parskip} package is used).\par
+% There are at least two, possibly four, sections in the
+% \texttt{cover} element where the packages, commands, and
+% other data can be defined:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<constraintdef xml:id="docpackages">
+ ...packages for the user documentation are defined here...
+</constraintdef>
+
+<constraintdef xml:id="startdoc">
+ ...special commands for the user documentation go here...
+</constraintdef>
+
+<constraintdef xml:id="clspackages" linkend="options">
+ ...packages needed for the class or package are defined here...
+</constraintdef>
+
+<constraintdef xml:id="manifest">
+ ...files to add to the MANIFEST/zip file are listed here...
+</constraintdef>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% These exact \texttt{xml:id} values
+% are mandatory when the relevant \texttt{constraintdef}
+% elements are used, as they are referenced from elsewhere in
+% the document by the XSLT2 program. The only variation is
+% that when writing a package ({\ttfamily{}.sty}
+% file), the \texttt{"clspackages"} must read
+% \texttt{"stypackages"} instead. The first
+% three letters are used to match the three-letter filetype
+% used as the value of the \texttt{arch}
+% attribute that you specified on the \texttt{book} root
+% element (see `\textbf{\texttt{arch}}', the \ordinalstringnum{2} item in the list in \vref{arch}).\par
+% Each \texttt{constraintdef} element can
+% hold one or (in some circumstances, more) of the following
+% element types:\par
+% \begin{itemize}
+% \item \texttt{segmentedlist} (in a
+% \texttt{docpackages}, \texttt{clspackages}, or
+% \texttt{stypackages} type of \texttt{constraintdef}\emph{only}), a list structure used to
+% specify the packages required: see \vref{packspec};
+% \item \label{cmdsynopsis}\texttt{cmdsynopsis}, used for defining
+% \emph{user documentation} setup commands
+% to be placed \emph{in} the Preamble. This
+% is only meaningful in the \texttt{"docpackages"} type of
+% \texttt{constraintdef}: see \vref{cmdspec};
+% \item \texttt{procedure}, used for holding blocks of
+% \emph{user documentation} setup commands
+% to be placed \emph{after} the Preamble
+% (that is, at the start of the document body, after the
+% \verb|\begin{document}| command). This is
+% only meaningful in the \texttt{"docpackages"} type of
+% \texttt{constraintdef}.\par
+% Note that this is distinct from commands to be
+% placed \emph{in} the Preamble, which are
+% held in a more structured manner in the
+% \texttt{cmdsynopsis} element deacribed above: see
+% \vref{addcmds};
+% \item \texttt{simplelist}, a list whose
+% \texttt{member} elements are used to name additional
+% files to be included in the distribution zip file
+% ({\ttfamily{}MANIFEST}). This is only meaningful
+% in a \texttt{manifest} type of
+% \texttt{constraintdef}: see
+% \vref{manifestfiles}.
+% \end{itemize}
+% \subsubsection{Specifying packages}\label{packspec}
+% There are three parts to using
+% \texttt{constraintdef} for this:\par
+% \begin{enumerate}[noitemsep]
+% \item specifying packages for your user documentation (see
+% \vref{docpax});
+% \item specifying packages for the class or package you
+% are writing (see \vref{classtypax});
+% \item automating the inclusion of extra settings to be
+% used whenever you specify a particular package (see
+% \vref{autospec}).
+% \end{enumerate}
+% For the first two, the \texttt{segmentedlist}
+% element is used. This contains a sequence of
+% \texttt{seglistitem}\thinspace{}s, one per package, each containing a
+% \texttt{seg} element holding the package name. An
+% optional \texttt{segtitle} element may start the list,
+% and if present, is used as a comment (for the
+% documentation packages) or a subheading (class or package
+% packages).\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<segmentedlist>
+ <segtitle>Packages required for documentation</segtitle>
+ <seglistitem role="Use the Charter typeface for documentation.">
+ <seg version="2005-04-12">charter</seg>
+ </seglistitem>
+ <seglistitem role="Use Helvetica as the sans-serif, but scale it
+ to fit">
+ <seg role="scaled=0.8333">helvet</seg>
+ </seglistitem>
+ ...
+</segmentedlist>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% Each \texttt{seglistitem} provides for
+% a documentary comment about why this package is required,
+% using the \texttt{role}
+% attribute. In the case of the packages for your own class
+% or package, this comment is reproduced in the
+% documentation of the code.\par
+% The package itself is specified as the content of the
+% \texttt{seg} element in each item.\par
+% Any options for the package being loaded must be
+% supplied in the \texttt{role} attribute
+% of the \texttt{seg} element. If the
+% package must conform to a specific version, the date must
+% be provided (in ISO format) in the \texttt{version} attribute.\par
+% \paragraph{Declaring packages needed for your documentation}\label{docpax}
+% Packages required for your documentation must be
+% included in the type of list described above, in the
+% \texttt{constraintdef} element that has the \texttt{xml:id} value of \texttt{"docpackages"}. Note that some
+% packages are automatically when certain types of
+% formatting are implied: see \vref{autopackage} for details.\par
+% The relevant {\ttfamily{}\textbackslash{}usepackage} commands
+% get included in the {\ttfamily{}.dtx} file right
+% after the \verb|\begin{document}|
+% command.\par
+% If you also want the package you are maintaining to
+% be included in the documentation (perhaps so you can use
+% it for examples), remember to set the \texttt{xlink:role} attribute on the
+% \texttt{book} root element as described in `\textbf{\texttt{xlink:role}}', the last item in the list in \vref{selfspec}.\par
+% See \vref{autospec} for details of how to
+% specify package command settings that you want included
+% by default every time you specify a particular
+% package.\par
+% \paragraph{Declaring packages needed by the class or package
+% itself}\label{classtypax}
+% All the packages required for the class or package
+% being written must be included in the type of list
+% described above, in the \texttt{constraintdef} element
+% that has the \texttt{xml:id} value
+% of \texttt{"clspackages"} (for classes)
+% or \texttt{"stypackages"} (for
+% packages).\par
+% \subparagraph{Specifying where in the {\ttfamily{}.dtx}
+% file to output them\thinspace:}
+% Because your class or package design may include
+% preliminary commands needed before packages are
+% included, the relevant {\ttfamily{}\textbackslash{}RequirePackage}
+% commands must be added to the {\ttfamily{}.dtx}
+% file \emph{in a location that you must specify
+% yourself}. This is done by giving the \texttt{linkend} attribute on the
+% enclosing \texttt{constraintdef} element the value
+% of an \texttt{xml:id} which you
+% have assigned to a chapter or section in your
+% annotated code.\par
+% \emph{There is no default: you must specify
+% this link yourself, otherwise the list of required
+% packages will not be output.}\par
+% The reason is that you may need to write some of
+% your class or package code (option declarations, for
+% example, or a {\ttfamily{}\textbackslash{}LoadPackage} command),
+% \emph{before} the specified packages are
+% loaded.\par
+% \begin{itemize}
+% \item If the chapter or section you have specified
+% has content (text) in it, the
+% {\ttfamily{}\textbackslash{}RequirePackage} commands are
+% output as the content of a new chapter or section
+% immediately preceding or following it, as
+% specified by the value of the \texttt{role}
+% attribute (`before' or
+% `after').
+% \item If the chapter or section you have specified
+% is (deliberately) empty, the
+% {\ttfamily{}\textbackslash{}RequirePackage} commands are
+% output as the content of that chapter or
+% section.
+% \end{itemize}
+% As an example, let us say you specify the
+% \texttt{constraintdef} with\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<constraintdef xml:id="clspackages" linkend="options" role="after">...
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% You must then have a chapter or section in your
+% documented code with the \texttt{xml:id} value of \texttt{"options"}. If
+% it is empty (no character data content) like this:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<sect1 xml:id="options">
+ <title/>
+ <para/>
+</sect1>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% then the list of {\ttfamily{}\textbackslash{}RequirePackage} commands will
+% be output in its place.\par
+% If, on the other hand, the specified section
+% has text and code of its own:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<sect1 xml:id="options">
+ <title>Options</title>
+ <para>text...</para>
+ <programlisting>
+\some{code}
+ </programlisting>
+</sect1>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% then the list of {\ttfamily{}\textbackslash{}RequirePackage}
+% commands will be output immediately after it, as a new
+% section at the same level.\par
+% In both cases, the \texttt{segtitle} of the
+% \texttt{segmentedlist} will be used as the title of
+% the section.\par
+% \subsubsection{Automated settings for declared packages}\label{autospec}
+% There are several reasons for automating package setup:\par
+% \begin{itemize}
+% \item Many \LaTeX{} authors and designers have
+% `favourite' settings that they
+% like to use every time they specify a particular
+% package.
+% \item Some options have now become the \emph{de
+% facto} convention for their package,
+% (for example, the \textbf{\texttt{T1}} option on the
+% \textsf{fontenc} package).
+% \item There are commands that need to be used whenever a
+% particular package is invoked (for example, the
+% \textsf{makeidx} package means you need to
+% add the {\ttfamily{}\textbackslash{}makeindex} command to the
+% Preamble).
+% \item Some packages are only needed in the documentation
+% if a particular formatting feature is used (for
+% example compact list spacing requires the
+% \textsf{enumitem} package). This avoids you
+% having to remember to include a specific package when
+% you use such a feature; and to remove it if you cease
+% to use the feature.
+% \end{itemize}
+% To help automate these, an ancillary (lookup) file
+% called {\ttfamily{}prepost.xml} is used, which
+% is a \emph{DocBook} document with a
+% \texttt{refsection} root element type containing two
+% \texttt{procedure} elements, shown below.\par
+% The {\ttfamily{}prepost.xml} file must be in
+% the directory specified by your setting of the
+% {\ttfamily{}repo} runtime parameter.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<refsection>
+ <title>Commands to use before and after packages</title>
+ <procedure xml:id="prepackage">
+ ...steps...
+ </procedure>
+ <procedure xml:id="postpackage">
+ ...steps...
+ </procedure>
+</refsection>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% The \texttt{"prepackage"} procedure
+% is for material which needs to go
+% \emph{before} a package is invoked. The \texttt{"postpackage"} procedure is for
+% material which needs to go \emph{after} a
+% package is invoked.\par
+% \paragraph{Identifying each package}
+% Within these procedures, each package is identified in
+% a \texttt{step} element.\par
+% \begin{itemize}[noitemsep]
+% \item the \texttt{remap} attribute
+% holds the package name;
+% \item the \texttt{condition}
+% attribute holds the type[s] of output it is intended
+% to be effective for, \texttt{"doc"}, \texttt{"cls"}, or \texttt{"sty"} (space-separated if
+% more than one);
+% \item the \texttt{role} attribute
+% holds any default options (comma-separated);
+% \item an optional \texttt{para} element holds a
+% textual description of the package and its use. This
+% is only meaningful for packages marked in the \texttt{condition} attribute for
+% use in the class or package. If present, this gets
+% output to the code documentation.
+% \end{itemize}
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<step role="utf8x" remap="inputenc" condition="cls sty">
+ <para>UTF-8 is the default character set, to allow for use of
+ any character in any writing system. Some characters
+ are not specified for all fonts, so may have to be
+ specified manually.</para>
+</step>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% In this example, specifying
+% \textsf{inputenc} in the document, in a
+% \texttt{seg} element as described in \vref{packspec}, results in the package being
+% added with {\ttfamily{}\textbackslash{}RequirePackage} to the
+% class or package code.\par
+% \paragraph{Automating inclusion}\label{autopackage}
+% Each \texttt{step} may contain one
+% or more \texttt{constructorsynopsis} elements which
+% specify the condition[s] under which the package will
+% automatically be included \emph{without it needing
+% to be specified} in a \texttt{seg} element
+% as described in \vref{packspec}\par
+% \begin{itemize}[noitemsep]
+% \item the \texttt{condition}
+% attribute holds the name of an element type which,
+% if present in the documentation, will cause the
+% package to be included automatically;
+% \item one or more \texttt{methodparam} subelements
+% can be used to specify attribute conditions on the
+% element type named in the \texttt{condition}
+% attribute:
+% \begin{itemize}[noitemsep]
+% \item the \texttt{parameter} element specifies
+% the name of an attribute. If no
+% \texttt{modifier} element is present, the
+% specified attribute is simply tested for
+% presence (Boolean test)
+% \item a
+% \texttt{modifier} element is used to
+% specify a value for which the attribute is tested
+% \end{itemize}
+% \end{itemize}
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<step remap="dcolumn" condition="doc">
+ <constructorsynopsis condition="colspec">
+ <methodparam>
+ <parameter>align</parameter>
+ <modifier>char</modifier>
+ </methodparam>
+ </constructorsynopsis>
+</step>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% In the example above, a \texttt{colspec} element
+% anywhere in the document with an \texttt{align} attribute equal to \texttt{"char"} will cause the
+% \textsf{dcolumn} package to be included
+% automatically (the package handles decimal-column
+% alignment).\par
+% A special case involves the use of the \texttt{funcparams} subelement instead of
+% the \texttt{parameter} attribute, to
+% specify that an IDREF attribute must be checked for the
+% \emph{type} of element it refers to.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<step condition="doc" remap="fmtcount">
+ <constructorsynopsis condition="xref">
+ <methodparam>
+ <funcparams>linkend</funcparams>
+ <modifier>varlistentry</modifier>
+ </methodparam>
+ <methodparam>
+ <funcparams>linkend</funcparams>
+ <modifier>listitem</modifier>
+ </methodparam>
+ </constructorsynopsis>
+</step>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% In this example, the \textsf{fmtcount}
+% package will be included if there is an \texttt{xref}
+% element anywhere in the documentation with a \texttt{linkend} attribute which points
+% at a \texttt{varlistentry} or \texttt{listitem}
+% element~--- that is, the \texttt{xml:id} attribute whose value
+% matches the \texttt{linkend} value
+% is on such an element type (the
+% \textsf{fmtcount} package enables ordinal
+% counting, needed when making a reference to an item in a
+% list that is not numbered).\par
+% \paragraph{Adding extra code before or after a package}
+% Each \texttt{step} may also contain
+% one or more \texttt{constraintdef} elements containing
+% \texttt{cmdsynopsis} elements containing
+% \texttt{command} elements to hold \LaTeX{} code to be
+% inserted, in exactly the same format as shown in \vref{constraints}.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<step remap="apacite" condition="doc">
+ <constraintdef>
+ <cmdsynopsis>
+ <command>\AtBeginDocument{\edef\ApaciteRestoreAtCode%
+ {\catcode`@=\the\catcode`@\relax}}</command>
+ </cmdsynopsis>
+ </constraintdef>
+</step>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% If this step is given in the \texttt{"prepackage"} section, the code is
+% inserted \emph{before} the package is
+% included; if the step is given in the \texttt{"postpackage"} section, the code
+% is inserted \emph{after} the package is
+% included.\par
+% A package listed in this file can be given default
+% options by specifying them in the \texttt{role} attribute of the
+% \texttt{step} element. It is then unnecessary to specify
+% them additionally in the main document (although it won't
+% matter, as they are checked for duplication).\par
+% \subsubsection{Defining commands required for documentation setup}\label{cmdspec}
+% Documenting classes or packages will often require
+% additional commands to be defined in order to set up special
+% counters or lengths, establish conditions, or create new
+% macros to be used in your documentation.\par
+% \emph{This is quite different from needing to
+% issue standard \LaTeX{} commands in order to
+% set existing standard \LaTeX{} values, such as }\verb|\setlength{\parskip}{5mm}|.
+% \emph{That kind of adjustment is dealt with in \vref{addcmds}.}\par
+% Commands to be defined for the documentation to work
+% must go in \texttt{cmysynopsis} elements in the
+% \texttt{constraintdef} element that has the \texttt{xml:id} value of \texttt{"docpackages"},
+% \emph{after} the end of the
+% \texttt{segmentedlist} of packages.\par
+% The commands are specified with the command name
+% (control sequence) or environment name
+% \emph{separately} from the definition: this
+% allows a structure to be imposed which enables the
+% identification and re-use of these specifications.\par
+% In giving the commands (control sequences) that you
+% define, you specify just the names, with no backslash; and
+% the definitions you give must not have the outermost set
+% of curly braces. Both the backslash and the curly braces
+% are added by the XSLT2 program when writing the
+% {\ttfamily{}.dtx} file.\par
+% Commands containing an `at'
+% sign ({\ttfamily{}@}) in their name or
+% definition are automatically enclosed in
+% {\ttfamily{}\textbackslash{}makeatletter} and
+% {\ttfamily{}\textbackslash{}makeatother} commands.\par
+% There are several attributes which specify what you
+% are defining, so that the data is output to the
+% {\ttfamily{}.dtx} file correctly:\par
+% \begin{description}[style=unboxed]
+% \item[Simple commands\thinspace:]A simple new \LaTeX{} command with a textual
+% expansion is defined with the \texttt{command}
+% element holding the name of the command being
+% defined, and an \texttt{arg} element holding the
+% definition.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis>
+ <command>LyX</command>
+ <arg>L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX</arg>
+</cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\newcommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX}
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \item[Renewed commands\thinspace:]If the command is a renewal of an existing
+% command, use a \texttt{role}
+% attribute of \texttt{"renew"} on
+% the \texttt{command} element.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis>
+ <command role="renew">vstrut</command>
+ <arg>\vrule height1.2em depth.6667ex width0pt</arg>
+</cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\renewcommand{\vstrut}{\vrule height1.2em depth.6667ex width0pt}
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \item[Plain \TeX{} commands\thinspace:]A {\ttfamily{}\textbackslash{}def} command in Plain \TeX{}
+% syntax can be specified with the attribute \texttt{xml:lang} set to \texttt{"TeX"} on the
+% \texttt{command} element.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis xml:lang="TeX">
+ <command>hline</command>
+ <arg>\noalign{\ifnum0=`}\fi
+ \@ifnextchar[{\@@hline}{\@@hline[\arrayrulewidth]}</arg>
+</cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\def\hline{\noalign{\ifnum0=`}\fi
+ \@ifnextchar[{\@@hline}{\@@hline[\arrayrulewidth]}
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \item[Commands with arguments\thinspace:]If a defined command needs arguments, specify
+% the number of arguments in the \texttt{wordsize} attribute of the
+% \texttt{arg} element:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis>
+ <command>componentbox</command>
+ <arg wordsize="2">\begin{tabular}[m]{@{}|c|@{}}\hline
+ \cellcolor{#1}\hbox to1em{\hss%\vrule height1em width0pt
+ \raisebox{.2ex}{\ttfamily\tiny#2}\hss}\\\hline
+ \end{tabular}</arg>
+</cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\newcommand{\componentbox}[2]{\begin{tabular}[m]{@{}|c|@{}}\hline
+ \cellcolor{#1}\hbox to1em{\hss%\vrule height1em width0pt
+ \raisebox{.2ex}{\ttfamily\tiny#2}\hss}\\\hline
+ \end{tabular}
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% If a default first argument is required, the
+% value must be provided in the \texttt{condition} attribute of the
+% \texttt{command} element.\par
+% There is no provision in this version of the
+% software for the specification of the extended argument array
+% provided by the \textsf{xargs} package.
+% \item[Counters, lengths, and \texttt{\textbackslash{}newwrite}s\thinspace:]Counters, lengths, and
+% {\ttfamily{}\textbackslash{}newwrite} commands can be defined
+% by using the \texttt{remap}
+% attribute set to the value \texttt{"counter"}, \texttt{"length"} or \texttt{"newwrite"} as appropriate. in
+% this case, no \texttt{arg} element is
+% required unless a counter or length is to be
+% assigned a default value.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis>
+ <command remap="newwrite">fnotes</command></cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\newwrite\fnotes
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% However, if the length or counter needs an
+% initial value, give it in an \texttt{arg} element.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis>
+ <command remap="length">revmarg</command>
+ <arg>3cm</arg>
+</cmdsynopsis>
+<cmdsynopsis>
+ <command remap="counter">cards</command>
+ <arg>42</arg>
+</cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\newlength{\revmarg}\setlength{\revmarg}{3cm}
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \item[References to attributes\thinspace:]One specialist use is predefined: assigning the
+% type of document (class or package) to a command:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis>
+ <command>classorpackage</command>
+ <arg remap="arch"/>
+</cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\newcommand{\classorpackage}{...}
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% where [\dots{}] is the type of the current
+% document. The \texttt{arch} element in this case
+% has no content, but uses the \texttt{remap} attribute to specify
+% the name of an attribute (here, \texttt{arch}) on the
+% \texttt{book} root element. This results in the
+% command {\ttfamily{}\textbackslash{}classorpackage} being set
+% equal to \texttt{"class"} or \texttt{"package"}; this value is used
+% to provide a value for the entity \texttt{\&doctype;}. This entity can
+% then be used in shared XML documentation to refer to
+% the current document by type, knowing that it will
+% be correctly translated to the type of document when
+% the {\ttfamily{}.dtx} file is
+% created.
+% \item[Environments\thinspace:]The same principle applies to environments as to
+% commands, but there are two arguments: one for the
+% `before' and one for the
+% `after':\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<cmdsynopsis>
+ <command remap="environment">panel</command>
+ <arg wordsize="1" condition="\relax">\begin{Sbox}%
+ \begin{minipage}{3in}%
+ \if#1\relax\else\subsubsection*{#1}\fi</arg>
+ <arg>\end{minipage}\end{Sbox}%
+ \begin{center}\fbox{\theSbox}\end{center}%</arg>
+</cmdsynopsis>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This creates the definition:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+\newenvironment{panel}{%
+ \begin{Sbox}%
+ \begin{minipage}{3in}%
+ \if#1\relax\else\subsubsection*{#1}\fi
+}{%
+ \end{minipage}\end{Sbox}%
+ \begin{center}\fbox{\theSbox}\end{center}%
+}
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% The controls for the number of arguments and any
+% default argument must go on the first \texttt{arg}
+% element. The same rule about setting the \texttt{role} attribute to \texttt{"renew"} applies as for
+% generating commands.
+% \end{description}
+% \subsubsection{Additional setup commands}\label{addcmds}
+% Quite separately from the business of defining new
+% commands (or redefining existing ones) dealt with in \vref{cmdspec}, there is also usually a need to issue
+% commands that establish or reset a value needed for the
+% documentation.\par
+% Commands that you want implemented every time you use
+% a particular package should go in your
+% {\ttfamily{}prepost.xml} file, as described in
+% \vref{autospec}. This section is for commands or
+% settings that only refer to the documentation for the
+% current class or package being written.\par
+% These commands go in the third of the types of
+% \texttt{constraintdef} element, with the \texttt{xml:id} value of \texttt{"startdoc"} because they are output
+% at the start of the documentation
+% (\emph{after} the
+% \verb|\begin{document}|).\par
+% They follow exactly the same syntax as those in the
+% {\ttfamily{}prepost.xml} file:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<constraintdef xml:id="startdoc">
+ <procedure>
+ <step>
+ <cmdsynopsis>
+ <command>\setcounter{tocdepth}{5}</command>
+ <command>\setcounter{secnumdepth}{5}</command>
+ <command>\def\@@doxdescribe#1#2{\endgroup
+ \ifdox@noprint\else\marginpar{\raggedleft
+ \textcolor{DarkRed}{\@nameuse{PrintDescribe#1}{#2}}}\fi
+ \ifdox@noindex\else\@nameuse{Special#1Index}{#2}\fi
+ \endgroup\@esphack\ignorespaces}</command>
+ </cmdsynopsis>
+ </step>
+ </procedure>
+</constraintdef>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% The {\ttfamily{}\textbackslash{}@@doxdescribe} command is an
+% oddity here: it appears not to work if placed in the
+% {\ttfamily{}prepost.xml} document, where it gets
+% issued in the Preamble; instead it goes here, where it
+% gets issued after the
+% \verb|\begin{document}|.\par
+% \subsubsection{The Manifest}\label{manifestfiles}
+% The fourth and last variant of the
+% \texttt{constraintdef} element (with the \texttt{xml:id} attribute of \texttt{"manifest"}) is very simple. It is a
+% list of the names of any separate files that you want
+% included in the Zip file that the {\ttfamily{}build} command produces. This
+% means anything other than the {\ttfamily{}.dtx},
+% {\ttfamily{}.ins}, and {\ttfamily{}.pdf}
+% files that get included automatically.\par
+% The content of this element is a
+% \texttt{simplelist}, containing \texttt{member}
+% elements, one per file:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<constraintdef xml:id="manifest">
+ <simplelist>
+ <member>doctexbook.dtd</member>
+ <member>db2dtx.xsl</member>
+ <member>db2bibtex.xsl</member>
+ <member>prepost.xml</member>
+ <member>lppl.xml</member>
+ <member>decommentbbl.awk</member>
+ </simplelist>
+</constraintdef>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \subsubsection{The README file}\label{readme}
+% One additional output file is produced automatically
+% by the XSLT2 program: the plaintext README file which
+% accompanies all classes and packages, with a brief
+% description of usage and installation, for the benefit of
+% people who cannot or will not read the PDF
+% documentation.\par
+% This is generated automatically from the file
+% {\ttfamily{}readme.xml}, which is a DocBook5
+% \texttt{chapter} document with some changes to the
+% character entities to accommodate plain text. Note that
+% this document does \emph{not} use the
+% {\ttfamily{}doctexbook.dtd} used for your normal
+% class or package {\small XML} document. A sample
+% is included in the \textsf{classpack}
+% distribution.\par
+% The {\ttfamily{}readme.xml} file uses the
+% \texttt{olink} element type to act as a placeholder for
+% transcluded atomic information from the main document
+% (pending implementation of the proposed DocBook
+% Transclusions method). This element must have a
+% \texttt{targetptr} and a \texttt{type} attribute
+% specifying (respectively) the name of the element type and
+% the relevant attribute in the main document. For example,
+% to include the name of the class or package, we
+% use:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+<olink targetptr="book" type="xml:id"/>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% Two other element types have also had
+% \texttt{targetptr} and \texttt{type} attributes
+% added: \texttt{sect1} and \texttt{anchor}. These are
+% used to specify the inclusion of whole sections or
+% fragments of the main document, such as the Abstract or
+% the Copyright.\par
+% The text is reformatted in plain text, omitting all
+% markup. Only a few element types have been implemented for
+% this in this version: see the ancillary XSLT2 routines in
+% {\ttfamily{}db2plaintext.xsl} for details.\par
+% The resulting {\ttfamily{}README} file
+% includes the Abstract from your class or package
+% {\small XML} document as the first section. The
+% {\ttfamily{}db2plaintext.xsl} program uses a
+% template called \DescribeTemplate{normtext}\texttt{normtext} to
+% reformat text. This handles the conversion of entities
+% which occur in your Abstract (those declared in
+% {\ttfamily{}doctexbook.dtd}): by default, \texttt{\&TeX;}, \texttt{\&LaTeX;}, and \texttt{\&thinsp;} are catered for, but if
+% you use any others, you must modify the code in this
+% template to deal with them, using a nested
+% \DescribeFunction{replace()}\texttt{replace()} function.\par
+% \clearpage
+% \section{Using \emph{ClassPack}}\label{content}
+% The body of your docmentation is held in a \texttt{part}
+% element with the \texttt{xml:id} attribute
+% set to \texttt{"doc"}.\par
+% The tag-set of \emph{DocBook} is very
+% large, and only a part of it is needed for this purpose,
+% although support for additional elements is easily added in
+% the XSLT2 program.\par
+% The following sections describe the elements that are
+% currently supported, for the hierarchical structure (chapters,
+% sections, subsections, etc); the block-level structure
+% (tables, figures, lists, etc; what
+% \emph{DocBook} refers to as the
+% `pool') and for the inline markup (element types
+% in mixed content, used mostly in paragraph-like
+% situations).\par
+% \subsection{Hierarchical markup}\label{hierarchy}
+% The outline top-level structure is described in \vref{invocation} and \vref{setup}.\par
+% The \texttt{part}\thinspace{}s do not have any title or direct
+% textual content themselves: they just act as containers to
+% keep the user documentation separate from the documented
+% code and any other files that may be stored and
+% extracted.\par
+% Within a \texttt{part}, the major subdivision is the
+% \texttt{chapter}, which translates to a
+% {\ttfamily{}\textbackslash{}section} in the {\ttfamily{}.dtx}
+% file. You should use the \texttt{chapter} element as your
+% major structural division. Each part (user documentation,
+% documented code, and additional files) must have at least
+% one chapter.\par
+% Within chapters, the sections, subsections, and lower
+% structural divisions are identified with \texttt{sect1},
+% \texttt{sect2}, and so on. You can use as many or as few
+% of these as you feel you need to organise your writing. In
+% the documented code, it is a good idea to modularise the
+% class or package, so that you can describe each part of it
+% in a logical and consistent manner.\par
+% The nested arrangement of chapters containing sections
+% conaining subsections should already be familiar to \LaTeX{}
+% users, although \LaTeX{} itself only uses headings as
+% separators, and has no physical
+% `containment' of the hierarchical
+% divisions of a document in the way that it does for the
+% block-level structures (environments).\par
+% Each of these hierarchical divisions must have a
+% \texttt{title} element (see `\textbf{\texttt{title}}', the first item in the list in \vref{title}),
+% and can also have an \texttt{xml:id}
+% attribute to act as a target (like a \LaTeX{}
+% {\ttfamily{}\textbackslash{}label}) for cross-referencing (see `\textbf{\texttt{xref}}', the last item in the list in \vref{xref}).\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<part xml:id="doc">...
+ <chapter xml:id="ui">
+ <title>User interface</title>
+ ...
+ <sect1>
+ <title>Font selection</title>
+ ...
+ </sect1>
+ <sect1 xml:id="margins">
+ <title>Margins and spacing</title>
+ ...
+ </sect1>
+ </chapter>
+ ...
+</part>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% \subsection{Structural markup (block-level elements)}\label{pool}
+% Within chapters, sections, subsections, etc, you can
+% have any arrangement or mixture of paragraphs, tables,
+% lists, figures, quotations, code samples, and other
+% conventional structures that will be familiar to you from
+% \LaTeX{} environments.\par
+% The only requirement is that each hierarchical division
+% must start with a title, and must contain at least one other
+% structural component. Supported element types are:\par
+% \begin{description}[style=unboxed]
+% \item[\texttt{title}\thinspace:]\label{title}a title, used in all chapters, [sub]sections,
+% figures, and tables (where it equates to a caption);
+% and also optionally in lists, sidebars, and other
+% block-level element types.
+% \item[\texttt{para}\thinspace:]for normal paragraphs.
+% \item[\texttt{itemizedlist}\thinspace:]for bulleted lists, containing
+% \texttt{listitem}\thinspace{}s which contain paragraphs.
+% \item[\texttt{orderedlist}\thinspace:]for numbered lists; the structure is identical to
+% an \texttt{itemizedlist}.
+% \item[\texttt{variablelist}\thinspace:]for description lists like this one (the
+% \texttt{term} element in each
+% \texttt{varlistentry} holds the reference term; the
+% descriptive part is in the same \texttt{listitem}
+% structure as for itemized and bulleted lists.
+% \item[\texttt{simplelist}\thinspace:]for plain unnumbered, unbulleted lists; each item
+% goes in a \texttt{member} element.
+% \item[\texttt{programlisting}\thinspace:]for listings of code: use without attributes in
+% the Code section. In the Documentation section, the
+% basic style is in {\ttfamily{}\textbackslash{}small} type,
+% black, {\ttfamily{}\textbackslash{}ttfamily}, and the following
+% attributes control the appearance:
+% \par\medskip{\sffamily\small
+% \begingroup
+% \centering
+% \begin{tabular}{@{}%
+% >{\ttfamily\prestrut\arraybackslash}l<{\poststrut\arraybackslash}%
+% >{\raggedright{}\prestrut\arraybackslash}p{9cm}<{\poststrut\arraybackslash}%
+% @{}}
+% \hline
+% \vstrut
+% wordsize&either a size command or a
+% pointsize/baseline like
+% {\ttfamily{}8/9}\\
+% language&{\ttfamily{}LaTeX} (default),
+% {\ttfamily{}DocBook},
+% {\ttfamily{}bash}, or another
+% language supported by the
+% \textsf{listings} package\\
+% arch&{\ttfamily{}framed} will box
+% the listing\\
+% remap&\LaTeX{} styling commands for tokens to
+% emphasise\\
+% annotations&comma-separated list of tokens to
+% emphasise\\[2pt]\hline
+% \end{tabular}
+% \par\endgroup
+% }
+% \item[\texttt{figure}\thinspace:]for Figures, containing a \texttt{caption} and a
+% \texttt{media} element.
+% \item[\texttt{table}\thinspace:]for Tables; the structure is explained in detail
+% in \vref{table}.
+% \item[\texttt{sidebar}\thinspace:]for sidebars.
+% \item[\texttt{warning}\thinspace:]for warnings.
+% \end{description}
+% \subsubsection{Ancillary files documented inline}\label{secfiles}
+% These are files which you want extracted at
+% installation time, which you describe
+% \emph{and} show in the user documentation
+% (the \texttt{doc} part).\par
+% \emph{Files which you want extracted which are
+% \emph{not} documented or shown in the user
+% documentation must go in the \texttt{files} part (see
+% \vref{ancfiles}).}\par
+% \subsubsection{Bibliography}\label{bibs}
+% If bibliographic citations and reference is required,
+% the references themselves must be stored in a
+% \texttt{bibliography} element immediately after the last
+% \texttt{chapter} element in \emph{either}
+% the `doc' part
+% \emph{or} the `code'
+% part. This must contain a \texttt{biblioentry} element
+% for each entry you wish to cite (for how to cite, see
+% `\textbf{\texttt{biblioref}}', the first item in the list in \vref{bibrefs}).\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[DocBook]XML}]
+<bibliography xreflabel="apacite" label="apacite">
+ <biblioentry xml:id="tb97" xreflabel="article">
+ <biblioset>
+ <author>
+ <personname>
+ <surname>Flynn</surname>
+ <firstname>Peter</firstname>
+ </personname>
+ </author>
+ <title>Typographers' Inn</title>
+ <subtitle>Where have all the flowers gone?</subtitle>
+ </biblioset>
+ <artpagenums>21-22</artpagenums>
+ <title>TUGboat</title>
+ <volumenum>31</volumenum>
+ <issuenum>1</issuenum>
+ <date YYYY-MM-DD="2010"/>
+ </biblioentry>
+</bibliography>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% The \texttt{bibliography} element
+% \textsc{must} have a \texttt{label} attribute giving the name
+% of the \BibTeX{} style file to use (without the
+% {\ttfamily{}.bst} filetype). The
+% \textsf{apacite} style is recommended.\par
+% If the specified style requires a \LaTeX{} style
+% package for formatting (often called by the same name, eg
+% \textsf{apacite}, \textsf{natbib},
+% \textsf{chicago}, etc), this
+% \textsc{must} be given in an \texttt{xreflabel} attribute (without the
+% {\ttfamily{}.sty} filetype).\par
+% There \textsc{may} also be an
+% \texttt{xlink:href} attribute giving
+% the name of the \BibTeX{} file (without the
+% {\ttfamily{}.bib} filetype) to which the
+% references should be written: the default is the name of
+% the class or package itself (as defined in `\textbf{\texttt{xml:id}}', the first item in the list in \vref{rootid}).\par
+% Each \texttt{biblioentry} element
+% \textsc{must} have both an \texttt{xml:id} attribute by which it can
+% be cited with the \texttt{biblioref} element; and a \texttt{type} attribute classifying it
+% with one of the standard \BibTeX{} document types (article,
+% book, incollection, etc)\par
+% \subsection{Inline markup (elements in mixed content)}\label{flow}
+% \par
+% \begin{description}[style=unboxed]
+% \item[\texttt{biblioref}\thinspace:]\label{bibrefs}a citation (bibliographic reference) to an item in
+% the Bibliography; the \texttt{linkend} attribute must be
+% the value of the \texttt{xml:id}
+% of a \texttt{biblioentry} element (see \vref{bibs}); this value is passed to a
+% {\ttfamily{}\textbackslash{}cite} command.
+% \item[\texttt{citetitle}\thinspace:]the title of a document being mentioned; usually
+% formatted in italics or quotes; may be empty, with a \texttt{linkend} attribute pointing to
+% an entry in the Bibliography (as for
+% \texttt{biblioref}), in which case the title is
+% automatically extracted and formatted, or passed to a
+% {\ttfamily{}\textbackslash{}citefield} command.
+% \item[\texttt{code}\thinspace:]a fragment of computer or data code, formatted in
+% monospace type.
+% \item[\texttt{emphasis}\thinspace:]emphasis according to style, usually italics.
+% \item[\texttt{exceptionname}\thinspace:]used for the keywords of RFC2119 in formal admonishments.
+% \item[\texttt{filename}\thinspace:]name of a file, a full filepath, or just a part of
+% the name (eg a filetype).
+% \item[\texttt{firstterm}\thinspace:]the defining instance of a specialist term; this
+% may or may not actually be the first occurrence.
+% \item[\texttt{footnote}\thinspace:]a footnote; contains a paragraph.
+% \item[\texttt{foreignphrase}\thinspace:]for foreign-language expressions; identify the
+% language with the \texttt{xml:lang} attribute if the
+% phrase is long enough to need the
+% \textsf{babel} package.
+% \item[\texttt{guibutton}\thinspace:]represents a GUI {\fboxsep2pt\ovalbox{\sffamily Button}}.
+% \item[\texttt{guilabel}\thinspace:]represents a GUI
+% {\fboxsep2pt\fbox{\sffamily Label}}.
+% \item[\texttt{guimenu}\thinspace:]represents a GUI
+% \textsf{\bfseries Menu}.
+% \item[\texttt{guimenuitem}\thinspace:]represents a GUI
+% \textsf{\itshape Menu item}.
+% \item[\texttt{guisubmenu}\thinspace:]represents a GUI
+% \textsf{Sub-menu item}.
+% \item[\texttt{literal}\thinspace:]marks a {\ttfamily{}literal string} on which
+% no interpretation is to be performed (markup characters
+% like backslashes and curly braces will
+% not be escaped; the \texttt{xml:lang} attribute can be set to
+% the name of the language (eg \texttt{"TeX"}, \texttt{"LaTeX"}, etc.
+% \item[\texttt{phrase}\thinspace:]marks a phrase used as-is (ie not a quote from
+% anyone in particular) by enclosing it in quotation marks.
+% \item[\texttt{productname}\thinspace:]marks a product or program name, eg
+% \emph{Emacs}.
+% \item[\texttt{quote}\thinspace:]marks a quote from someone by putting it in
+% quotation marks.
+% \item[\texttt{replaceable}\thinspace:]identifies text, commands, or keywords to be
+% typed, for which the user must substitute a meaningful
+% value, eg {\itshape password} (in
+% italics).
+% \item[\texttt{systemitem}\thinspace:]identifies generic computer-related strings such
+% as system commands, hostnames, Regular Expressions, etc
+% which need to be printed in monospace to eliminate any
+% confusion over 1/l/I, 0/1/I, etc.
+% \item[\texttt{type}\thinspace:]marks a span for which special typographical
+% treatment is needed. The \texttt{role} attribute must be set
+% to `font' and the \texttt{remap} attribute must be set
+% to the NFSS2e three-character
+% \textsf{fontname}.
+% \item[\texttt{uri}\thinspace:]marks a URI (formats it with the
+% {\ttfamily{}\textbackslash{}url} macro).
+% \item[\texttt{wordasword}\thinspace:]marks a word that is being used as itself (usually
+% for purposes of clarification), so it goes in quotation
+% marks.
+% \item[\texttt{xref}\thinspace:]\label{xref}a cross-reference using the \texttt{linkend} attribute to point
+% at some other part of the document, which must have
+% the matching \texttt{xml:id}
+% value; the mechanism is identical to \LaTeX{}'s
+% {\ttfamily{}\textbackslash{}label}\dots{}{\ttfamily{}\textbackslash{}ref}.
+% \end{description}
+% In addition, there are six special-purpose element types
+% used for functional documentation, that create the special
+% \textsf{dox} package commands for adding \LaTeX{}
+% (and XML) terms to the index, and highlighting them in the
+% left-hand margin:\par
+% \begin{description}[style=unboxed]
+% \item[\texttt{classname}\thinspace:]a \LaTeX{} document class name like
+% \textsf{article}
+% \item[\texttt{command}\thinspace:]a \LaTeX{} or other computer command, such as
+% {\ttfamily{}\textbackslash{}parskip}; the backslash is added
+% automatically for the default case of \LaTeX{}; other
+% languages require the \texttt{xml:lang} attribute giving
+% the name of the language
+% \item[\texttt{envar}\thinspace:]a \LaTeX{} environment name like
+% \texttt{enumerate}
+% \item[\texttt{option}\thinspace:]a \LaTeX{} option to a class, package, or command,
+% like \textbf{\texttt{a4paper}}
+% \item[\texttt{package}\thinspace:]a \LaTeX{} package name like
+% \textsf{fancybox}
+% \item[\texttt{tag}\thinspace:]an XML element, attribute, attribute value, or
+% entity name: the type is specified in the \texttt{class} attribute and is one
+% of the predetermined list provided automatically by
+% \emph{DocBook} (so your XML editor
+% will guide you)
+% \end{description}
+% \subsection{Producing your class or package}\label{production}
+% The XSLT2 program generates a number of output files,
+% principally the {\ttfamily{}.dtx} and
+% {\ttfamily{}.ins} files which are the package or
+% class itself. A third output is a {\ttfamily{}build}
+% file, which is a \emph{bash} shell
+% script customised for the production of the class or package
+% you are writing. A fourth is the
+% {\ttfamily{}MANIFEST} file, used for zipping
+% everything up for distribution,\par
+% You should therefore keep each class or package
+% development in a separate directory, otherwise the
+% {\ttfamily{}build} file generated by one will
+% overwrite that generated by others.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=bash]
+#! /bin/bash
+#
+# Bourne shell script to build the class file and documentation
+# Note the following line is wrapped here to fit the width
+java -jar /usr/local/saxon/saxon9he.jar \
+ -o:classpack.dtx classpack.xml \
+ /home/peter/texmf/dev/db2dtx.xsl \
+ processor=/usr/local/saxon/saxon9he.jar \
+ appdir=/home/peter/texmf/dev \
+ cpdir=/home/peter/texmf/dev
+yes|latex classpack.ins
+pdflatex classpack.dtx
+bibtex classpack
+awk -f /home/peter/texmf/dev/decommentbbl.awk classpack.bbl >classpack.bdc
+mv classpack.bdc classpack.bbl
+pdflatex classpack.dtx
+makeindex -s gind.ist -o classpack.ind classpack.idx
+makeindex -s gglo.ist -o classpack.gls classpack.glo
+pdflatex classpack.dtx
+echo Copying files into dev tree...
+mkdir -p doc/latex/classpack
+mkdir -p source/latex/classpack
+mkdir -p tex/latex/classpack
+cp README MANIFEST classpack.pdf doc/latex/classpack
+cp classpack.dtx classpack.ins source/latex/classpack
+cp classpack.cls tex/latex/classpack
+cp db2bibtex.xsl source/latex/classpack
+cp db2dtx.xsl source/latex/classpack
+cp db2plaintext.xsl source/latex/classpack
+cp decommentbbl.awk source/latex/classpack
+cp doctexbook.dtd source/latex/classpack
+cp lppl.xml source/latex/classpack
+cp prepost.xml source/latex/classpack
+cp readme.xml source/latex/classpack
+echo Zipping up files from dev tree...
+zip -r --exclude=*.svn* --exclude=*.DS_Store* \
+ classpack-0.73.tds.zip doc/latex/classpack \
+ source/latex/classpack tex/latex/classpack
+echo Installing working copy...
+unzip -o -d ~/texmf classpack-0.73.tds.zip
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% Because this file will not exist the very first time you
+% process a new class or package, you will need to type that
+% first ({\ttfamily{}java}) command by
+% hand. The arguments are:\par
+% \begin{enumerate}
+% \item \marg{jar} the location of
+% your copy of the Saxon XSLT2 processor, a
+% {\ttfamily{}.jar} file;
+% \item \textbf{\texttt{-o:}} the name of the
+% {\ttfamily{}.dtx} file you are producing;
+% \item the name of the XML file you are processing;
+% \item the full path to the DB2DTX program;
+% \item the location of your copy of the Saxon XSLT2
+% processor (again) as the
+% {\ttfamily{}processor} parameter;
+% \item the directory you use for this class or package as
+% the {\ttfamily{}appdir};
+% \item the directory where your copy of the XSLT2 program
+% is stored as the
+% {\ttfamily{}cpdir} parameter (along with the DTD,
+% {\ttfamily{}prepost.xml},
+% {\ttfamily{}readme.xml},
+% {\ttfamily{}db2plaintext.xsl}, and
+% {\ttfamily{}lppl.xml} files) .
+% \end{enumerate}
+% For subsequent runs, you just type {\ttfamily{}./build} and the values and
+% parameters will be re-used automatically. If you ever need
+% to run the XSLT2 process by itself, use the command
+% \verb+grep java build | bash+\par
+% The remainder of the {\ttfamily{}build} tests
+% the extraction of the class or package, and compiles the
+% full documentation in the standard sequence, including any
+% bibliography, index, or glossary.\par
+% The use of the {\ttfamily{}decommentbbl.awk}
+% script on the \BibTeX{} output is to defeat the use of
+% terminal percent comment characters, which upset the
+% \textsf{ltxdoc} package because of the special use
+% of that character there.\par
+% The final stage is to create a Zip file of
+% the class or package, which is placed in the current working
+% directory and then unzipped into your personal \TeX{} tree.\par
+% \subsection{Maintaining your class or package}\label{maintenance}
+% The things to control each time you make an update are:\par
+% \begin{enumerate}
+% \item on the \texttt{book} root element, update the \texttt{version} and \texttt{revision} attributes
+% \item add a new \texttt{revision} element in the
+% Revision History, setting the \texttt{version} attribute to the
+% compound of the version and revision specified above,
+% and setting the \texttt{date} subelement's \texttt{conformance} attribute to
+% today's date in ISO format
+% \item after processing the document once, set the
+% \texttt{book} root element's \texttt{security} attribute to the
+% checksum displayed by \LaTeX{}
+% \item process the document again (run the
+% {\ttfamily{}build} script again)~--- the
+% security checksum should now match
+% \end{enumerate}
+% \clearpage
+% \section{The \emph{db2dtx} program}\label{db2dtx}
+% While the core of your class or package is the
+% \emph{DocBook} XML document, the core of
+% the \emph{classpack} system is the program
+% that turns your XML into {\ttfamily{}.dtx} and
+% {\ttfamily{}.ins} files for distribution as combined
+% code and documentation.\par
+% The \emph{db2dtx} program is written
+% in XSLT2, a declarative language for processing XML. It
+% consists of a set of templates, each of which matches a
+% pattern in the XML document, usually an element type, or an
+% element type in a particular position or with a particular
+% attribute value or subelement.\par
+% For example, there is a template which matches the
+% \texttt{biblioref} element whenever it occurs. This puts three
+% things into the output:\par
+% \begin{enumerate}
+% \item the command \verb|\cite{| with its
+% opening curly brace;
+% \item the value of the link to the bibliographic
+% entry;
+% \item the closing \verb|}| curly
+% brace.
+% \end{enumerate}
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XSLT]
+<xsl:template match="db:biblioref">
+ <xsl:text>\cite{</xsl:text>
+ <xsl:value-of select="@linkend"/>
+ <xsl:text>}</xsl:text>
+</xsl:template>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% The advantage of using a declarative language is that you
+% don't need to know when and where each element will occur:
+% XSLT2 will find them as they come up in processing, and apply
+% the template when it happens. It's basically a case of
+% `when you see one of \emph{these}, do
+% \emph{this}'.\par
+% The next few sections of this document describe each part
+% of the program and how it produces your class or package
+% files.\par
+% \subsection{XML Declaration and Namespace declarations}
+% The program starts in the usual way with the XML
+% Declaration and the \texttt{xsl:stylesheet} start-tag with
+% the Namespace declarations.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XSLT]
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:db="http://docbook.org/ns/docbook"
+ xmlns:xlink="http://www.w3.org/1999/xlink"
+ version="2.0">
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% Note that this is an XSLT2 program and requires an XSLT2
+% processor.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XSLT]
+ <!-- db2dtx.xsl
+ XSL script to transform DocBook5 documentation and code of a
+ LaTeX package or class file into a DocTeX (.dtx and .ins)
+ distribution.
+ Full processing command chain is output to file 'build'
+ Note this requires an XSLT2 processor (eg Saxon9 or above)
+ -->
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% We identify the version of the program, output methods,
+% parameters, and the single \texttt{xsl:include} file: the
+% {\ttfamily{}db2bibtex.xsl} module for handling
+% bibliographic formatting.\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language=XSLT]
+ <xsl:variable name="thisversion">
+ <xsl:text>14.7</xsl:text>
+ </xsl:variable>
+
+ <xsl:output method="text"/>
+ <xsl:output method="text" name="textFormat"/>
+
+ <xsl:include href="db2bibtex.xsl"/>
+ <xsl:include href="db2plaintext.xsl"/>
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% This is incomplete: the remainder of the program is not
+% yet included here.\par
+% \StopEventually{\label{endcode}
+% \clearpage
+% \newgeometry{left=3cm}
+% \addcontentsline{toc}{section}{Change History}
+% \label{}
+% \PrintChanges
+% \clearpage
+% \label{codeindex}
+% \addcontentsline{toc}{section}{Index}
+% \PrintIndex}
+% \setlength{\revmarg}{1in}
+% \addtolength{\revmarg}{\widthof{\MacroFont{IndexColumns}}}
+% \newgeometry{left=\revmarg}
+% \iffalse
+%<*package>
+% \fi
+% \clearpage
+% \section{Service commands}
+% \iffalse
+%%
+%% SERVICE COMMANDS
+% \fi
+% As ClassPack itself is not a document class or package
+% \emph{per se}, there is no operating
+% code.\par
+% \iffalse
+%%
+%% As ClassPack itself is not a document class or package per se, there
+%% is no operating code.
+% \fi
+% However, there are some ancillary commands commonly used
+% in documentation which should be expected by authors of
+% classes and packages using ClassPack.\par
+% \iffalse
+%%
+%% However, there are some ancillary commands commonly used in
+%% documentation which should be expected by authors of classes and
+%% packages using ClassPack.
+% \fi
+% This section therefore implements
+% {\ttfamily{}classpack.sty}, which gets invoked
+% automatically via its entry in
+% {\ttfamily{}prepost.xml}.\par
+% \iffalse
+%%
+%% This section therefore implements classpack.sty, which gets invoked
+%% automatically via its entry in prepost.xml.
+% \fi
+% \begin{counter}{IndexColumns}
+% The \textsf{doctex} package uses a default
+% three-column index, which is too narrow for most purposes. We
+% therefore make the index in two columns, and space them
+% slightly farther apart.\par
+% \iffalse
+%%
+%% The doctex package uses a default three-column index, which is too
+%% narrow for most purposes. We therefore make the index in two columns,
+%% and space them slightly farther apart.
+% \fi
+% \begin{macrocode}
+\setcounter{IndexColumns}{2}
+\setlength{\columnsep}{3pc}
+% \end{macrocode}
+% \end{counter}
+% \subsection{\TeX{} and other logos}
+% \iffalse
+%%
+%% 1 TeX and other logos
+% \fi
+% \TeX{} and \LaTeX{} are defined in the \LaTeX{} kernel, but
+% most of the others are not. The following definitions are
+% taken from the \textsf{ltugboat} package, used for
+% typesetting the TUGboat journal.\par
+% \iffalse
+%%
+%% TeX and LaTeX are defined in the LaTeX kernel, but most of the others
+%% are not. The following definitions are taken from the ltugboat
+%% package, used for typesetting the TUGboat journal.
+% \fi
+% \begin{macro}{\ConTeXt}
+% \ConTeXt{} is a typography and typesetting system meant
+% to provide users easy and consistent access to advanced
+% typographical control \cite{wp-context}.\par
+% \iffalse
+%%
+%% \ConTeXt{} is a typography and typesetting system meant to provide
+%% users easy and consistent access to advanced typographical control (,
+%% ).
+% \fi
+% \begin{macrocode}
+\def\ConTeXt{C\kern-.0333emon\-\kern-.0667em\TeX\kern-.0333emt}
+% \end{macrocode}
+% \end{macro}
+% \iffalse
+%</package>
+% \fi
+% \clearpage
+% \raggedright
+% \bibliography{classpack}
+% \bibliographystyle{apacite}
+% \begin{VerbatimOut}{classpack.bib}
+%<*ignore>
+@article{wp-context,
+author = {Anon},
+shortauthor = {Anon},
+title = {{\ConTeXt{}}},
+journal = {{Wikipedia}},
+url = {http://en.wikipedia.org/wiki/ConTeXt},
+lastchecked = {27 March 2013}
+}
+%</ignore>
+% \end{VerbatimOut}
+% \appendix
+% \iffalse
+%<*savedtd>
+% \fi
+% \clearpage
+% \section{The XML vocabulary}\label{savedtd}
+% \iffalse
+%%
+%% The XML vocabulary
+% \fi
+% There are currently no changes to the
+% \emph{DocBook} element structure.\par
+% \iffalse
+%%
+%% There are currently no changes to the DocBook element structure.
+% \fi
+% \begin{dtd}{book}
+% The DTD is a driver implementing a number of entity
+% declarations to ease the transformation to \LaTeX{}.\par
+% \iffalse
+%%
+%% The DTD is a driver implementing a number of entity declarations to
+%% ease the transformation to LaTeX.
+% \fi
+% \begin{macrocode}
+<!ENTITY % db5dtd SYSTEM "/dtds/docbook/docbook-5.0/dtd/docbook.dtd">
+<!ATTLIST date YYYY-MM-DD CDATA #IMPLIED>
+<!ATTLIST blockquote units CDATA #IMPLIED
+ begin CDATA #IMPLIED
+ end CDATA #IMPLIED>
+<!ATTLIST quote units CDATA #IMPLIED
+ begin CDATA #IMPLIED
+ end CDATA #IMPLIED>
+<!ELEMENT html:form EMPTY>
+<!ENTITY ampers "\&#38;#38;">
+<!ENTITY BiBTeX "\BibTeX{}">
+<!ENTITY BibTeX "\BibTeX{}">
+<!ENTITY BIBTeX "\BibTeX{}">
+<!ENTITY ConTeXt "\ConTeXt{}">
+<!ENTITY LaTeX "\LaTeX{}">
+<!ENTITY LaTeX2e "\LaTeXe{}">
+<!ENTITY XeTeX "\XeTeX{}">
+<!ENTITY LyX "\LyX{}">
+<!ENTITY METAFONT "\MF{}">
+<!ENTITY METAPOST "\MP{}">
+<!ENTITY TeX "\TeX{}">
+<!ENTITY bsol "{\texttt{\textbackslash}}">
+<!ENTITY date "\filedate{}">
+<!ENTITY degree "\textdegree{}">
+<!ENTITY doctype "\classorpackage{}">
+<!ENTITY filler "\hfil{}">
+<!ENTITY frac12 "\nicefrac12">
+<!ENTITY frac13 "\nicefrac13">
+<!ENTITY frac23 "\nicefrac23">
+<!ENTITY hellip "\dots{}">
+<!ENTITY mdash "~--- ">
+<!ENTITY mldr "\dotfill{}">
+<!ENTITY nbsp "~">
+<!ENTITY ndash "--">
+<!ENTITY percnt "\&#x0025;">
+<!ENTITY square "\raisebox{-1pt}{\Square}">
+<!ENTITY thinsp "\thinspace{}">
+<!ENTITY times "×">
+<!ENTITY specialUuml '{\normalfont\"{\fontfamily{cdr}\selectfont U}}'>
+<!ENTITY verbar "\menusep{}">
+<!ENTITY version "\fileversion{}">
+<!-- call the main DTD --> %db5dtd;
+% \end{macrocode}
+% \end{dtd}
+% \iffalse
+%</savedtd>
+% \fi
+% \iffalse
+%<*lxp>
+% \fi
+% \clearpage
+% \section{Reusable XML}\label{lxp}
+% \iffalse
+%%
+%% Reusable XML
+% \fi
+% In the last item in the list in \vref{xmltools}, I said that one of the
+% benefits of using XML for software generation and
+% documentation was the re-usability of the data. Here are a
+% couple of simple examples.\par
+% \iffalse
+%%
+%% In , I said that one of the benefits of using XML for software
+%% generation and documentation was the re-usability of the data. Here
+%% are a couple of simple examples.
+% \fi
+% \begin{macrocode}
+$ lxprintf -e productname "%s\n" . classpack.xml |\
+ sort | uniq -c | sort -k 1nr
+% \end{macrocode}
+% Checking that all element types have been described!\par
+% \iffalse
+%%
+%% Checking that all element types have been described!
+% \fi
+% \iffalse
+%</lxp>
+% \fi
+% \newgeometry{left=3cm}
+% \clearpage
+% \section{The \LaTeX{} Project Public License}\label{LPPL:LPPL}
+% \begin{quotation}\small\noindent
+% Everyone is allowed to distribute verbatim copies of this
+% license document, but modification of it is not allowed.
+% \end{quotation}
+% \subsection{Preamble}\label{LPPL:Preamble}
+% The \LaTeX{} Project Public License ({\small LPPL})
+% is the primary license under which the \LaTeX{} kernel and the
+% base \LaTeX{} packages are distributed.\par
+% You may use this license for any work of which you hold the
+% copyright and which you wish to distribute. This license may be
+% particularly suitable if your work is \TeX{}-related (such as a
+% \LaTeX{} package), but it is written in such a way that you can
+% use it even if your work is unrelated to \TeX{}.\par
+% The section \emph{Whether and How to Distribute Works under This
+% License}, below, gives instructions, examples, and
+% recommendations for authors who are considering distributing
+% their works under this license.\par
+% This license gives conditions under which a work may be
+% distributed and modified, as well as conditions under which
+% modified versions of that work may be distributed.\par
+% We, the \LaTeX{3} Project, believe that the conditions below
+% give you the freedom to make and distribute modified versions of
+% your work that conform with whatever technical specifications
+% you wish while maintaining the availability, integrity, and
+% reliability of that work. If you do not see how to achieve your
+% goal while meeting these conditions, then read the document
+% {\ttfamily{}cfgguide.tex} and {\ttfamily{}modguide.tex} in the base \LaTeX{}
+% distribution for suggestions.\par
+% \subsection{Definitions}\label{LPPL:Definitions}
+% In this license document the following terms are used:\par
+% \begin{description}[style=unboxed]
+% \item[Work\thinspace:]Any work being distributed under this License.
+% \item[Derived Work\thinspace:]Any work that under any applicable law is derived from
+% the Work.
+% \item[Modification\thinspace:]Any procedure that produces a Derived Work under any
+% applicable law~--- for example, the production of a file
+% containing an original file associated with the Work or a
+% significant portion of such a file, either verbatim or
+% with modifications and/or translated into another
+% language.
+% \item[Modify\thinspace:]To apply any procedure that produces a Derived Work
+% under any applicable law.
+% \item[Distribution\thinspace:]Making copies of the Work available from one person to
+% another, in whole or in part. Distribution includes (but
+% is not limited to) making any electronic components of the
+% Work accessible by file transfer protocols such as
+% {\small FTP} or {\small HTTP} or by
+% shared file systems such as Sun's Network File System
+% ({\small NFS}).
+% \item[Compiled Work\thinspace:]A version of the Work that has been processed into a
+% form where it is directly usable on a computer system.
+% This processing may include using installation facilities
+% provided by the Work, transformations of the Work, copying
+% of components of the Work, or other activities. Note that
+% modification of any installation facilities provided by
+% the Work constitutes modification of the Work.
+% \item[Current Maintainer\thinspace:]A person or persons nominated as such within the Work.
+% If there is no such explicit nomination then it is the
+% `Copyright Holder' under any applicable
+% law.
+% \item[Base Interpreter\thinspace:]A program or process that is normally needed for
+% running or interpreting a part or the whole of the
+% Work.\par
+% A Base Interpreter may depend on external components
+% but these are not considered part of the Base Interpreter
+% provided that each external component clearly identifies
+% itself whenever it is used interactively. Unless
+% explicitly specified when applying the license to the
+% Work, the only applicable Base Interpreter is a
+% `\LaTeX{}-Format' or in the case of files
+% belonging to the `\LaTeX{}-format' a program
+% implementing the `\TeX{} language'.
+% \end{description}
+% \subsection{Conditions on Distribution and Modification}\label{LPPL:Conditions}
+% \begin{enumerate}
+% \item Activities other than distribution and/or modification
+% of the Work are not covered by this license; they are
+% outside its scope. In particular, the act of running the
+% Work is not restricted and no requirements are made
+% concerning any offers of support for the Work.
+% \item \label{LPPL:item:distribute}You may distribute a complete, unmodified copy of the
+% Work as you received it. Distribution of only part of the
+% Work is considered modification of the Work, and no right to
+% distribute such a Derived Work may be assumed under the
+% terms of this clause.
+% \item You may distribute a Compiled Work that has been
+% generated from a complete, unmodified copy of the Work as
+% distributed under Clause~item~\ref{LPPL:item:distribute} above above, as
+% long as that Compiled Work is distributed in such a way that
+% the recipients may install the Compiled Work on their system
+% exactly as it would have been installed if they generated a
+% Compiled Work directly from the Work.
+% \item \label{LPPL:item:currmaint}If you are the Current Maintainer of the Work, you may,
+% without restriction, modify the Work, thus creating a
+% Derived Work. You may also distribute the Derived Work
+% without restriction, including Compiled Works generated from
+% the Derived Work. Derived Works distributed in this manner
+% by the Current Maintainer are considered to be updated
+% versions of the Work.
+% \item If you are not the Current Maintainer of the Work, you
+% may modify your copy of the Work, thus creating a Derived
+% Work based on the Work, and compile this Derived Work, thus
+% creating a Compiled Work based on the Derived Work.
+% \item \label{LPPL:item:conditions}If you are not the Current Maintainer of the Work, you
+% may distribute a Derived Work provided the following
+% conditions are met for every component of the Work unless
+% that component clearly states in the copyright notice that
+% it is exempt from that condition. Only the Current
+% Maintainer is allowed to add such statements of exemption to
+% a component of the Work.
+% \begin{enumerate}
+% \item If a component of this Derived Work can be a direct
+% replacement for a component of the Work when that
+% component is used with the Base Interpreter, then,
+% wherever this component of the Work identifies itself to
+% the user when used interactively with that Base
+% Interpreter, the replacement component of this Derived
+% Work clearly and unambiguously identifies itself as a
+% modified version of this component to the user when used
+% interactively with that Base Interpreter.
+% \item Every component of the Derived Work contains
+% prominent notices detailing the nature of the changes to
+% that component, or a prominent reference to another file
+% that is distributed as part of the Derived Work and that
+% contains a complete and accurate log of the
+% changes.
+% \item No information in the Derived Work implies that any
+% persons, including (but not limited to) the authors of
+% the original version of the Work, provide any support,
+% including (but not limited to) the reporting and
+% handling of errors, to recipients of the Derived Work
+% unless those persons have stated explicitly that they do
+% provide such support for the Derived Work.
+% \item You distribute at least one of the following with
+% the Derived Work:
+% \begin{enumerate}
+% \item A complete, unmodified copy of the Work; if your
+% distribution of a modified component is made by
+% offering access to copy the modified component from
+% a designated place, then offering equivalent access
+% to copy the Work from the same or some similar place
+% meets this condition, even though third parties are
+% not compelled to copy the Work along with the
+% modified component;
+% \item Information that is sufficient to obtain a
+% complete, unmodified copy of the Work.
+% \end{enumerate}
+% \end{enumerate}
+% \item If you are not the Current Maintainer of the Work, you
+% may distribute a Compiled Work generated from a Derived
+% Work, as long as the Derived Work is distributed to all
+% recipients of the Compiled Work, and as long as the
+% conditions of Clause~item~\ref{LPPL:item:conditions} above, above, are met
+% with regard to the Derived Work.
+% \item The conditions above are not intended to prohibit, and
+% hence do not apply to, the modification, by any method, of
+% any component so that it becomes identical to an updated
+% version of that component of the Work as it is distributed
+% by the Current Maintainer under Clause~item~\ref{LPPL:item:currmaint} above, above.
+% \item Distribution of the Work or any Derived Work in an
+% alternative format, where the Work or that Derived Work (in
+% whole or in part) is then produced by applying some process
+% to that format, does not relax or nullify any sections of
+% this license as they pertain to the results of applying that
+% process.
+% \item % \begin{enumerate}
+% \item A Derived Work may be distributed under a different
+% license provided that license itself honors the
+% conditions listed in Clause~item~\ref{LPPL:item:conditions} above above, in
+% regard to the Work, though it does not have to honor the
+% rest of the conditions in this license.
+% \item If a Derived Work is distributed under a different
+% license, that Derived Work must provide sufficient
+% documentation as part of itself to allow each recipient
+% of that Derived Work to honor the restrictions in
+% Clause~item~\ref{LPPL:item:conditions} above above, concerning
+% changes from the Work.
+% \end{enumerate}
+% \item This license places no restrictions on works that are
+% unrelated to the Work, nor does this license place any
+% restrictions on aggregating such works with the Work by any
+% means.
+% \item Nothing in this license is intended to, or may be used
+% to, prevent complete compliance by all parties with all
+% applicable laws.
+% \end{enumerate}
+% \subsection{No Warranty}\label{LPPL:Warranty}
+% There is no warranty for the Work. Except when otherwise
+% stated in writing, the Copyright Holder provides the Work
+% `as is', without warranty of any kind, either
+% expressed or implied, including, but not limited to, the implied
+% warranties of merchantability and fitness for a particular
+% purpose. The entire risk as to the quality and performance of
+% the Work is with you. Should the Work prove defective, you
+% assume the cost of all necessary servicing, repair, or
+% correction.\par
+% In no event unless required by applicable law or agreed to
+% in writing will The Copyright Holder, or any author named in the
+% components of the Work, or any other party who may distribute
+% and/or modify the Work as permitted above, be liable to you for
+% damages, including any general, special, incidental or
+% consequential damages arising out of any use of the Work or out
+% of inability to use the Work (including, but not limited to,
+% loss of data, data being rendered inaccurate, or losses
+% sustained by anyone as a result of any failure of the Work to
+% operate with any other programs), even if the Copyright Holder
+% or said author or said other party has been advised of the
+% possibility of such damages.\par
+% \subsection{Maintenance of The Work}\label{LPPL:Maintenance}
+% The Work has the status `author-maintained'
+% if the Copyright Holder explicitly and prominently states near
+% the primary copyright notice in the Work that the Work can only
+% be maintained by the Copyright Holder or simply that it is
+% `author-maintained'.\par
+% The Work has the status `maintained' if there
+% is a Current Maintainer who has indicated in the Work that they
+% are willing to receive error reports for the Work (for example,
+% by supplying a valid e-mail address). It is not required for the
+% Current Maintainer to acknowledge or act upon these error
+% reports.\par
+% The Work changes from status `maintained' to
+% `unmaintained' if there is no Current Maintainer,
+% or the person stated to be Current Maintainer of the work cannot
+% be reached through the indicated means of communication for a
+% period of six months, and there are no other significant signs
+% of active maintenance.\par
+% You can become the Current Maintainer of the Work by
+% agreement with any existing Current Maintainer to take over this
+% role.\par
+% If the Work is unmaintained, you can become the Current
+% Maintainer of the Work through the following steps:\par
+% \begin{enumerate}
+% \item Make a reasonable attempt to trace the Current
+% Maintainer (and the Copyright Holder, if the two differ)
+% through the means of an Internet or similar search.
+% \item If this search is successful, then enquire whether the
+% Work is still maintained.
+% \begin{enumerate}
+% \item If it is being maintained, then ask the Current
+% Maintainer to update their communication data within one
+% month.
+% \item \label{LPPL:item:intention}If the search is unsuccessful or no action to resume
+% active maintenance is taken by the Current Maintainer,
+% then announce within the pertinent community your
+% intention to take over maintenance. (If the Work is a
+% \LaTeX{} work, this could be done, for example, by
+% posting to \url{news:comp.text.tex}.)
+% \end{enumerate}
+% \item % \begin{enumerate}
+% \item If the Current Maintainer is reachable and agrees to
+% pass maintenance of the Work to you, then this takes
+% effect immediately upon announcement.
+% \item \label{LPPL:item:announce}If the Current Maintainer is not reachable and the
+% Copyright Holder agrees that maintenance of the Work be
+% passed to you, then this takes effect immediately upon
+% announcement.
+% \end{enumerate}
+% \item \label{LPPL:item:change}If you make an `intention announcement'
+% as described in~item~\ref{LPPL:item:intention} above above and after three
+% months your intention is challenged neither by the Current
+% Maintainer nor by the Copyright Holder nor by other people,
+% then you may arrange for the Work to be changed so as to
+% name you as the (new) Current Maintainer.
+% \item If the previously unreachable Current Maintainer becomes
+% reachable once more within three months of a change
+% completed under the terms of~item~\ref{LPPL:item:announce} above
+% or~item~\ref{LPPL:item:change} above, then that
+% Current
+% Maintainer must become or remain the Current Maintainer upon
+% request provided they then update their communication data
+% within one month.
+% \end{enumerate}
+% A change in the Current Maintainer does not, of itself,
+% alter the fact that the Work is distributed under the
+% {\small LPPL} license.\par
+% If you become the Current Maintainer of the Work, you should
+% immediately provide, within the Work, a prominent and
+% unambiguous statement of your status as Current Maintainer. You
+% should also announce your new status to the same pertinent
+% community as in~item~\ref{LPPL:item:intention} above
+% above.\par
+% \subsection{Whether and How to Distribute Works under This
+% License}\label{LPPL:Distribute}
+% This section contains important instructions, examples, and
+% recommendations for authors who are considering distributing
+% their works under this license. These authors are addressed as
+% `you' in this section.\par
+% \subsubsection{Choosing This License or Another License}\label{LPPL:Choosing}
+% If for any part of your work you want or need to use
+% \emph{distribution} conditions that differ
+% significantly from those in this license, then do not refer to
+% this license anywhere in your work but, instead, distribute
+% your work under a different license. You may use the text of
+% this license as a model for your own license, but your license
+% should not refer to the {\small LPPL} or otherwise
+% give the impression that your work is distributed under the
+% {\small LPPL}.\par
+% The document {\ttfamily{}modguide.tex} in the base \LaTeX{}
+% distribution explains the motivation behind the conditions of
+% this license. It explains, for example, why distributing
+% \LaTeX{} under the {\small GNU} General Public
+% License ({\small GPL}) was considered inappropriate.
+% Even if your work is unrelated to \LaTeX{}, the discussion in
+% {\ttfamily{}modguide.tex} may still be
+% relevant, and authors intending to distribute their works
+% under any license are encouraged to read it.\par
+% \subsubsection{A Recommendation on Modification Without
+% Distribution}\label{LPPL:WithoutDistribution}
+% It is wise never to modify a component of the Work, even
+% for your own personal use, without also meeting the above
+% conditions for distributing the modified component. While you
+% might intend that such modifications will never be
+% distributed, often this will happen by accident~--- you may
+% forget that you have modified that component; or it may not
+% occur to you when allowing others to access the modified
+% version that you are thus distributing it and violating the
+% conditions of this license in ways that could have legal
+% implications and, worse, cause problems for the community. It
+% is therefore usually in your best interest to keep your copy
+% of the Work identical with the public one. Many works provide
+% ways to control the behavior of that work without altering any
+% of its licensed components.\par
+% \subsubsection{How to Use This License}\label{LPPL:HowTo}
+% To use this license, place in each of the components of
+% your work both an explicit copyright notice including your
+% name and the year the work was authored and/or last
+% substantially modified. Include also a statement that the
+% distribution and/or modification of that component is
+% constrained by the conditions in this license.\par
+% Here is an example of such a notice and statement:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+%%% pig.dtx
+%%% Copyright 2005 M. Y. Name
+%%
+%% This work 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.
+%%
+%% This work has the LPPL maintenance status `maintained'.
+%%
+%% The Current Maintainer of this work is M. Y. Name.
+%%
+%% This work consists of the files pig.dtx and pig.ins
+%% and the derived file pig.sty.
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% Given such a notice and statement in a file, the
+% conditions given in this license document would apply, with
+% the `Work' referring to the three files
+% {\ttfamily{}pig.dtx}, {\ttfamily{}pig.ins}, and {\ttfamily{}pig.sty} (the last being generated
+% from {\ttfamily{}pig.dtx} using {\ttfamily{}pig.ins}), the `Base
+% Interpreter' referring to any
+% `\LaTeX{}-Format', and both `Copyright
+% Holder' and `Current Maintainer'
+% referring to the person
+% M.~Y.~Name\index{!}.\par
+% If you do not want the Maintenance section of
+% {\small LPPL} to apply to your Work, change
+% `maintained' above into
+% `author-maintained'. However, we recommend that
+% you use `maintained' as the Maintenance
+% section was added in order to ensure that your Work remains
+% useful to the community even when you can no longer maintain
+% and support it yourself.\par
+% \subsubsection{Derived Works That Are Not Replacements}\label{LPPL:NotReplacements}
+% Several clauses of the {\small LPPL} specify
+% means to provide reliability and stability for the user
+% community. They therefore concern themselves with the case
+% that a Derived Work is intended to be used as a (compatible or
+% incompatible) replacement of the original Work. If this is not
+% the case (e.g., if a few lines of code are reused for a
+% completely different task), then clauses 6b and 6d shall not
+% apply.\par
+% \subsubsection{Important Recommendations}\label{LPPL:Recommendations}
+% \paragraph{Defining What Constitutes the Work}
+% The {\small LPPL} requires that distributions
+% of the Work contain all the files of the Work. It is
+% therefore important that you provide a way for the licensee
+% to determine which files constitute the Work. This could,
+% for example, be achieved by explicitly listing all the files
+% of the Work near the copyright notice of each file or by
+% using a line such as:\par
+% \iffalse
+%<*ignore>
+% \fi
+\begin{lstlisting}[language={[LaTeX]TeX}]
+%% This work consists of all files listed in manifest.txt.
+\end{lstlisting}
+% \iffalse
+%</ignore>
+% \fi
+% in that place. In the absence of an unequivocal list it
+% might be impossible for the licensee to determine what is
+% considered by you to comprise the Work and, in such a case,
+% the licensee would be entitled to make reasonable
+% conjectures as to which files comprise the Work.\par
+% \iffalse
+%<*testscript>
+# This is a test script
+echo Hello, World!
+
+%</testscript>
+% \fi
+% \Finale
+