Grzegorz Murzynowski
The gmdoc Bundle
*Copyright © , , , ,
by Grzegorz ‘Natror’ Murzynowski natror (at) gmail (dot) com
This program is subject to the LATEX Project Public License.
See http://www.ctan.org/tex--
archive/help/Catalogue/licenses.lppl.htmlfor the details of that license.
LPPLstatus: ”author-maintained”.
Many thanks to my TEX Guru Marcin Woliński for his TEXnical support.
For the documentation please refer to the file(s) gmdoc.{gmd,pdf}.
〈⋆master〉
(A handful of meta-settings skipped)
〈/master〉
〈⋆ins〉
\def\supposedJobname{%
\supposedJobname
gmdoc%
}
\let\xA\expandafter
\let\nX\noexpand
\long\def\firstofone#{#}
\unless\ifnum\strcmp␣{\jobname}␣{\supposedJobname}␣=
If we want to generate files from this file, we should call
xelatex␣--jobname=
〈sth. else〉Then the
\strcmp
primitive expands to some nonzero value and the conditional turns true.
\NeedsTeXFormat{LaTeXe}[//]
\def\gmBundleName{%
\gmBundleName
gmdoc%
}
\def\currentBundle{%
\currentBundle
docbundle%
}
\edef\batchfile{\gmBundleName␣.gmd}
\input␣docstrip.tex
\def\NOO{\FromDir\gmBundleFile␣.gmd}
\NOO
Note it’s
\def
so the BundleName expands to its current value.
\let\skiplines\relax
\let\endskiplines\relax
\askforoverwritefalse
\def\MetaPrefixS{\MetaPrefix\space}
\MetaPrefixS
\def\perCentS{\perCent\space}
\perCentS
\begingroup
\endlinechar=\newlinechar
\catcode\newlinechar=\relax%
\catcode`\^=\relax%
\catcode`\�=\relax␣%
Tifinagh Letter Yay
\catcode`\\=�relax␣%
�catcode`�⁄=�relax␣%
�firstofone{�endgroup␣%
�def�preamBeginningLeaf{%
�RCSInfo
�MetaPrefixS␣This␣is␣file␣“�outFileName”␣generated␣with␣
the␣DocStrip␣utility.
�MetaPrefixS
�ReferenceLines␣%
�MetaPrefix␣%
}%
of\preamBeginningLeaf
�def�copyRightLeaf{Copyright␣©␣}%
�def�licenseNoteLeaf{%
This␣program␣is␣subject␣to␣the␣LaTeX␣Project␣Public␣
License.
�MetaPrefixS␣See␣␣
http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html
�MetaPrefixS␣for␣the␣details␣of␣that␣license.
�MetaPrefix
�MetaPrefixS␣LPPL␣status:␣"author-maintained".
�MetaPrefix␣%
}%
of\licenseNoteLeaf
�def�preamEndingLeaf{%
�gmBundleFile.{gmd,pdf}�gobble{␣or␣\file{%
Natror-OperaOmnia.{gmd,pdf}}}.
�MetaPrefixS␣␣%
}%
of\preamEndingLeaf
�def�providesStatement{%
\NeedsTeXFormat{LaTeXe}
\Provides�gmFileKind{�gmOutName}
�space�space�space�space[�gmFileDate�space␣
�gmFileVersion�space␣�gmFileInfo�space␣(GM)]
}%
}%
of\firstofone
of changed catcodes.
\def\beforeDot#.#\empty{#}
\beforeDot
* This file has version number v. dated //.
\def\firstoftwo##{#}
\firstoftwo
\def\secondoftwo##{#}
\secondoftwo
To gobble the default heading lines put by DocStrip:
\Name\def{ds@heading}#{}
\def\csnameIf#{%
\csnameIf
\ifcsname#\endcsname
\csname#\xA\endcsname
\fi
}
\def\writeto#{\edef\destdir{#}}
\writeto
\def\FromDir{}
\FromDir
\def\writefrom#{\def\FromDir{#/}}
\writefrom
\FromDir
\def\WritePreamble#{%
\WritePreamble
\xA\ifx\csname␣pre@\@stripstring#\endcsname\empty
\else
\edef\outFileName{\@stripstring#}%
\edef\gmOutName{%
\xA\beforeDot\outFileName\empty
}%
of\gmOutName
\edef\gmOutTitle{%
\xA\xA\xA\detokenize\xA\xA\xA{%
\csname␣\gmOutName␣Title\endcsname}%
}%
of\gmOutTitle
\edef\gmOutYears{%
\csnameIf␣{\gmOutName␣Years}%
}%
\edef\gmOutThanks{%
\ifcsname␣\gmOutName␣Thanks\endcsname
\xA\xA\xA\detokenize\xA\xA\xA{%
\csname␣\gmOutName␣Thanks\endcsname
}%
\fi
}%
\edefInfo{Date}% \gmFileDate
\edefInfo{Version}% \gmFileVersion
\edefInfo{Info}% \gmFileInfo
\StreamPut#{\csname␣pre@\@stripstring#\endcsname}%
\fi}
First we look for the info at the leaf-level, then at standalone level, then at the bundle level. If we don’t find it, it’ll be empty.
\def\edefInfo#{%
\edefInfo
\Name\edef{gmFile#}{%
\ifcsname␣\gmOutName␣Leaf#\endcsname␣%
e.g.gmbaseLeafVersion
\xA\xA\xA\detokenize\xA\xA\xA{%
\csname␣\gmOutName␣Leaf#\endcsname
}%
\else
\ifcsname␣\gmOutName␣#\endcsname␣%
e.g.gmbaseVersion
\xA\xA\xA\detokenize\xA\xA\xA{%
\csname␣\gmOutName␣#\endcsname
}%
\else
\ifcsname␣\gmBundleFile␣#\endcsname␣%
e.g.gmutilsVersion
\xA\xA\xA\detokenize\xA\xA\xA{%
\csname␣\gmBundleFile␣#\endcsname
}%
\fi
\fi
\fi
}%
of edefined macro
}%
of\edefInfo
\let\gmOutName\relax
\let\gmOutTitle\relax
\let\gmOutYears\relax
\let\gmFileDate\relax
\let\gmFileVersion\relax
\let\gmFileInfo\relax
\let\gmOutThanks\relax
\let\gmBundleFile\relax
\let\gmFileKind\relax
\declarepreamble\gmdLeaf
\preamBeginningLeaf
\copyRightLeaf␣\gmOutYears
by␣Grzegorz␣‘Natror’␣Murzynowski
natror␣(at)␣gmail␣(dot)␣com
\licenseNoteLeaf
For␣the␣documentation␣please␣refer␣to␣the␣file(s)
\preamEndingLeaf
\providesStatement
\endpreamble
\keepsilent
We declare all the preambles later and use the
\empty
Docstrip preamble.
\errorcontextlines=
\@makeother\^^A
\@makeother\^^B
\@makeother\^^C
\@makeother\^^V
\def\gmfile
\gmfile
#%
file name
#%
DocStrip directive(s)
#%
file extension
{%
\file{gm#.#}{\from{\gmBundleFile/\NOO}{#}}%
}
\def\pack#{\gmfile{#}{#}{sty}}
\pack
\begingroup\catcode`\␣=
\catcode`\^^I=\relax
\catcode`\^^M=\relax
\firstofone{\endgroup
\def\gmBundleFile{gmdoc}
\gmBundleFile
\generate{
\usepreamble\gmdLeaf
\def\gmFileKind{␣␣␣␣Package␣␣␣␣}
\gmFileKind
\writeto{␣␣␣␣gmdoc␣␣␣␣}
\pack{␣␣␣␣doc␣␣␣␣}
\def\gmFileKind{␣␣␣␣Class␣␣␣␣}
\gmFileKind
\gmfile{␣␣␣␣docc␣␣␣␣}{␣␣␣␣docc␣␣␣␣}{␣␣␣␣cls␣␣␣␣}
\writefrom{␣␣␣␣gmdoc␣␣␣␣}
\writeto{␣␣␣␣␣␣␣␣gmdoc/Sourcee␣␣␣␣}
\usepreamble\gmdStandalone
\file{␣␣␣␣␣␣␣␣Sourcee_gmdoc.tex␣␣␣␣}{\from{\NOO}{␣␣␣␣
LaTeXsource␣␣␣␣}}
\writeto{␣␣␣␣gmdoc/doc␣␣␣␣}
\file{␣␣␣␣␣␣␣␣doc_gmdoc.tex␣␣␣␣}{\from{\NOO}{␣␣␣␣
docbygmdoc␣␣␣␣}}
\writeto{␣␣␣␣gmdoc/docstrip␣␣␣␣}
\file{␣␣␣␣␣␣␣␣docstrip_gmdoc.tex␣␣␣␣}{\from{\NOO}{␣␣␣␣
docstrip␣␣␣␣}}
}
}%
of changed catcodes’\firstofone
\Msg{%
⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆}
\Msg{␣}
\Msg{␣␣To␣finish␣the␣installation␣you␣have␣to␣move}
\Msg{␣␣␣the␣generated␣files␣into␣a␣directory␣searched␣by␣TeX.}
\Msg{␣}
\Msg{␣␣To␣type-set␣the␣documentation,␣run␣the␣file␣‘\NOO’}
\Msg{␣␣twice␣through␣LaTeX␣and␣maybe␣MakeIndex␣it.␣␣}
\Msg{␣}
\Msg{%
⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆⋆}
\csname␣fi\endcsname␣%
probably for the directive’s clause
\csname␣endinput\expandafter\endcsname␣%
\fi␣%
of unless job name other than name of this file, which indicates the DocStrip pass.〈/ins〉
Contents
Readme. . . . Installation. . . . Contents of thegmdoc.ziparchive . . . Compiling of the documentation . . . Bonus:basedrivers . . . . Introduction . . . . The user interface. . . . Used terms . . . . Preparing of the source file . . . . The main input commands . . . .
Package options . . . .
The packages required . . . .
Automatic marking of definitions. . .
Manual marking of the macros and environments . . . .
Index ex/inclusions . . . .
The DocStrip directives . . . .
The changes history . . . .
The parameters . . . .
The narration macros. . .
A queerness of\label . . .
doc-compatibility . . .
The driver part . . .
The code . . .
The package options . . .
The dependencies and preliminaries .
The core . . .
Numbering (or not) of the lines . . . .
Spacing with\everypar . . .
Life among queerEOLs . . .
Adjustments ofverbatimand\verb
Macros for marking of the macros . .
Automatic detection of definitions . .
\DeclareDefiningand the
detectors . . . .
Default defining commands . . . .
Suspending (‘hiding’) and
resuming detection . . .
Indexing ofCSes . . .
Index exclude list . . .
Index parameters . . .
The DocStrip directives . . .
The changes history . . . .
The checksum . . .
Macros fromltxdoc . . .
\DocIncludeand theltxdoc-like
setup. . .
Redefinition of\maketitle . . .
The file’s date and version information
Miscellanea . . .
doc-compatibility . . .
gmdocingdoc.dtx . . .
\OCRInclude . . .
Polishing, development and bugs . . .
[No] 〈eof〉 . . .
Intro . . .
Usage . . .
The Code. . .
Thegmoldcommpackage . . .
Some Typesetting Remarks . . .
The Body. . .
Index . . .
Change History . . .
〈⋆doc〉
Readme
This package is a tool for documenting of (LA)TEX packages, classes etc., i.e., the.sty,.cls files etc. The author just writes the code and adds the commentary preceded with
%
sign (or another properly declared). No special environments are necessary.The package tends to be (optionally) compatible with the standarddoc.stypackage, i.e., the.dtx files are also compilable withgmdoc(they may need a tiny adjustment in some special cases).
The tools are integrated withhyperref’s advantages such as hyperlinking of index entries, contents entries and cross-references.
The package also works with X E TEX (switches automatically).
Installation
Unpack the\jobname-tds.ziparchive (this is an archive that conforms theTDSstandard, seeCTAN/tds/tds.pdf) in some texmf directory or just put thegmutils.stysomewhere in the texmf/\:tex/\:latex branch. Creating a texmf/\:tex/\:latex/\:gm directory may be advisable if you consider using other packages written by me.
Then you should refresh your TEX distribution’s files’ database most probably.
Contents of the gmdoc.zip archive
The distribution of thegmutilspackage consists of the following three files and aTDS- compliant archive.
gmdoc.gmd README gmdoc.pdf gmdoc.tds.zip
Compiling of the documentation
The last of the above files (the.pdf, i.e.,this file) is a documentation compiled from the .gmd file by running LATEX on the gmdoc.gmd file twice (
xelatex␣gmdoc.gmd
in the directory you wish the documentation to be in), then MakeIndex on the\jobname.idx file, and then LATEX on\jobname.\gmdExtonce more.MakeIndex shell commands:
makeindex -r gmdoc
makeindex -r -s gmglo.ist -o gmdoc.gls gmdoc.glo
The
-r
switch is to forbid MakeIndex to make implicit ranges since the (code line) numbers will be hyperlinks.Compiling the documentation requires the packages: gmdoc (gmdoc.sty and gm- docc.cls),gmverb.sty, thegmutils bundle, gmiflink.styand also some standard packages:
hyperref.sty,color.sty,geometry.sty,multicol.sty,lmodern.sty,fontenc.stythat should be in- stalled on your computer by default.
Moreover, you should put thegmglo.istfile, a MakeIndex style for the changes’ his- tory, into sometexmf/makeindex(sub)directory.
Then you should refresh your TEX distribution’s files’ database most probably.
If you had not installed themwclsclasses (available onCTANand present in TEX Live e.g.), the result of your compilation might differ a bit from the.pdfprovided in this.zip archive in formatting: If you had not installedmwcls, the standardarticle.clsclass would be used.
Bonus: base drivers
As a bonus and example ofdoc-compatibility there are driver files included (cf. Palest- rina,Missa papae Marcelli;-):
source2e_gmdoc.tex docstrip_gmdoc.tex doc_gmdoc.tex gmoldcomm.sty
(gmsource2e.istis generated fromsource2e_gmdoc.tex) These drivers typeset the respective files from the
…/texmf-dist/source/latex/base
directory of the TEXLive distribution (they only read that directory).
Probably you should redefine the
\BasePath
macro in them so that it points that directory on your computer.Introduction
There are very sophisticated and effective tools for documenting LATEX macro packages, namely the doc package and the ltxdoc class. Why did I write another documenting package then?
I like comfort anddocis not comfortable enough for me. It requires special marking of the macro code to be properly typeset when documented. I want TEX to know ‘itself’
where the code begins and ends, without additional marks.
That’s the difference. One more difference, more important for the people for whom thedoc’s conventions are acceptable, is thatgmdocmakes use ofhyperrefadvantages and makes a hyperlinking index and toc entries and the cross-references, too. (TheCSes in the code maybe in the future.)
The rest is striving to level the very highdoc/ltxdoc’s standard, such as (optional) numbering of the codelines and automatic indexing the control sequences e.g.
Thedocpackage was and still is a great inspiration for me and I would like this hum- ble package to be considered as a sort of homage to it. If I mention copying some code or narrative but do not state the source explicitly, I mean thedocpackage’s documentation (I have v.b dated //).
The user interface Used terms
When I write of amacro, I mean a macro inThe TEX book’s meaning, i.e., a control se- quence whose meaning is
\
[e
|g
|x
]def
ined. By a macro’s parameter I mean each of#
〈digit〉s in its definition. When I write about amacro’s argument, I mean the value (list of tokens) substituting the corresponding parameter of this macro. (These under- standings are according toThe TEX book, I hope: TEX is a religion of Book ;-) .)I’ll use a shorthand for ‘control sequence’,CS.
When I talk of adeclaration, I mean a macro that expands to a certain assignment, such as
\itshape
or\@onlypreamble{
〈CS〉}
.Talking of declarations, I’ll use theOCSRacronym as a shorthand for ’observes/ing common TEX scoping rules’.
By acommandI mean a certain abstract visible to the end user as aCSbut consisting possibly of more than one macro. I’ll talk of acommand’s argumentalso in the ‘sense - for -the -end -user’, e.g., I’ll talk of the
\verb
command’s argument althoughthe macro\verb
has no#
〈digit〉in its definition.Thecodeto be typeset verbatim (and with all the bells and whistles) is everything that’s not commented out in the source file and what is not a leading space(s).
Thecommentary ornarrativeis everything after the comment char till the end of a line. Thecomment charis a character the
\catcode
of which is usually i.e., when the file works; if you don’t play with the\catcode
s, it’s just the%
. When the file is documented withgmdoc, such a char is re\catcode
d and its rôle is else: it becomes the code delimiter.A line containing any TEX code (not commented out) will be called acodeline. A line that begins with (some leading spaces and) a code delimiter will be called acomment lineornarration line.
As Grieg’s Piano Concerto is a homage to the Schumann’s.
Theuserof this package will also be addressed asyou.
Not to favour any particular gender (of the amazingly rich variety, I mean, not of the vulgarly simplified two-element set), in this documentation I use alternating pronouns of third person (
\heshe
etc. commands provided bygmutils), so let one be not surprised\heshe
if ‘they’ sees ‘themself’ altered in the same sentence :-) . Preparing of the source file
When (LA)TEX with gmdoc.stypackage loaded typesets the comment lines, the code de- limiter is omitted. If the comment continues a codeline, the code delimiter is printed.
It’s done so because ending a TEX code line with a
%
is just a concatenation with the next line sometimes. Comments longer than one line are typeset continuously with the code delimiters omitted.The user should just write their splendid code and brilliant commentary. In the lat- ter they may use usual (LA)TEX commands. The only requirement is, if an argument is divided in two lines, to end such a dividing line with
\^^M
(\
〈line end〉) or with^^B
\^^M
^^B
sequence that’ll enter the (active)〈char〉which shall gobble the line end.But there is also agmdocversion of
\footnote
provided that sets the catcodes so that you don’t bother about^^B
in the argument,\qfootnote
that takes the same ar-\qfootnote
gument(s) as the standard
\footnote
and for emphasis there is\qemph{
〈text to em-\qemph
phasise〉
}
. Both of them work also in the ‘straight’EOLs’ scope so you don’t bother. The\arg
gmutils’ command also works without^^B
.\arg
Moreover, if they wants to add a meta-comment i.e., a text that doesn’t appear in the code layer nor in the narrative, they may use the
^^A
sequence that’ll be read by TEX as^^A
〈char〉, which ingmdocis active and defined to gobble the stuff between itself and the line end.
Note that
^^A
behaves much like comment char although it’s active in fact: it re\catcode
s the special characters including\
,{
and}
so you don’t have to worry about unbalanced braces or\if
s in its scope. But^^B
doesn’t re\catcode
anything (which would be useless in an argument) so any text between^^B
and line end has to be balanced.However, it may be a bit confusing for someone acquainted with thedocconventions.
If you don’t fancy the
^^B
special sequence, instead you may restore the standard mean- ing of the line end with the\StraightEOL
declaration whichOCSR. As almost all the\StraightEOL
control sequences, it may be used also as an environment, i.e.,
\begin{StraightEOL}
…
\end{StraightEOL}
. However, if for any reason you don’t want to make an envi- ronment (a group), there’s a\StraightEOL
’s counterpart, the\QueerEOL
declaration\QueerEOL
that restores again the queergmdoc’s meaning of the line end. ItOCSR, too. One more point to use
\StraightEOL
is where you wish some code lines to be executed both while loading the file and during the documentation pass (it’s analogous to doc’s not embracing some code lines in amacrocode
environment).As in standard TEXing, one gets a paragraph by a blank line. Such a line should be
%
ed of course. A fully blank line is considered a blankcode line and hence results in a vertical space in the documentation. As in the environments for poetry known to me, subsequent blank lines do not increase such a space.Then they should prepare a main document file, adriverhenceforth, to set all the required formattings such as
\documentclass
, paper size etc., and load this pack- In my understanding ‘queer’ and ‘straight’ are not the opposites excluding each other but the coun- terparts that may cooperate in harmony for people’s good. And, as I try to show with the\QueerEOLand
\StraightEOLdeclarations, ‘queer’ may be very useful and recommended while ‘straight’ is the standard but not necessarily normative.
age with a standard command i.e.,
\usepackage{gmdoc}
, just asdoc’s documentation says:“If one is going to document a set of macros with the[gm]docpackage one has to prepare a special driver file which produces the formatted document. This driver file has the following characteristics:
\documentclass[
〈options〉]{
〈document class〉}
\usepackage[
〈options, probably none〉]{gmdoc}
〈preamble〉
\begin{document}
〈special input commands〉
\end{document}
”
The main input commands
To typeset a source file you may use the
\DocInput
macro that takes the (path and)\DocInput
name of the file with the extension as the only argument, e.g.,
\DocInput{mybril¦
liantpackage.sty}
.(Note that aninstalledpackage or class file is findable to TEX even if you don’t specify the path.)
If a source file is written with ratherdocthangmdocin mind, then the
\OldDocInput
\OldDocInput
command may be more appropriate (e.g., if you break the arguments of commands in the commentary in lines). It also takes the file (path and) name as the argument.
When using
\OldDocInput
, you have to wrap all the code inmacrocode
environ-macrocode
ments, which is not necessary when you use
\DocInput
. Moreover, with\OldDocIn¦
put
themacrocode
[⋆
]environments require to be ended with%␣␣␣␣\end{macrocode
[⋆
]}
as indoc. (With
\DocInput
you are not obliged to precede\end{macrocode
[⋆
]}
with The Four Spaces.)If you wish to document many files in one document, you are provided
\DocIn¦
\DocInclude
clude
command, analogous to LATEX’s\include
and very likely toltxdoc’s command of the same name. Ingmdocit has one mandatory argument that should be the file name without extension, just like for\include
.The file extensions supported by
\DocInclude
are.fdd,.dtx,.cls,.sty,.texand.fd. The macro looks for one of those extensions in the order just given. If you need to doc- ument files of other extensions, please let me know and most probably we’ll make it possible.\DocInclude
has also an optional first argument that is intended to be the path of the included file with the levels separated by/
(slash) and also ended with a slash. The path given to\DocInclude
as the first and optional argument will not appear in the headings nor in the footers.\DocInclude
redefines\maketitle
so that it makes a chapter heading or, in the\maketitle
classes that don’t support
\chapter
, a part heading, in both cases with respective toc entries. The default assumption is that all the files have the same author(s) so there’s no need to print them in the file heading. If you wish the authors names to be printed, you should write\PrintFilesAuthors
in the preamble or before the relevant\DocIn¦
\PrintFilesAuthors
clude
s. If you wish to undeclare printing the authors names, there is\SkipFiles¦
\SkipFilesAuthors
Authors
declaration. I use the ‘broken bar’ character as a hyphen in verbatim texts and hyperlinks. If you dont’t like it, see
\verbDiscretionaryHypheningmverb.
Like inltxdoc, the name of an included file appears in the footer of each page with date and version info (if they are provided).
The
\DocInclude
d files are numbered with the letters, the lowercase first, as in ltxdoc. Such a file-marker also precedes the index entries, if the (default) codeline index option is in force.As with
\include
, you may declare\includeonly{
〈filenames separated with com-\includeonly
mas〉
}
for the draft versions.If you want to put the driver into the same .styor .cls file (see chapter to see how), you may write
\DocInput{\jobname.sty}
, or\DocInclude{\jobname}
, but there’s also a shorthand for the latter\SelfInclude
that takes no arguments. By\SelfInclude
the way, to avoid an infinite recursive input of.auxfiles in the case of self-inclusion an .auxxfile is used instead of (main).aux.
By the way, to say TEX to (self)include only the current file, most probably you should say
\includeonly{\jobname}
not\includeonly{myfile}
because of the catcodes.At the default settings, the
\
(Doc
|Self
)Include
d files constitute chapters if\chap¦
ter
is known and parts otherwise. The\maketitle
s of those files result in the respec- tive headings.If you prefer moreltxdocish look, in which the files always constitute the parts and those parts have a part’s title pages with the file name and the files’
\maketitle
s result in (article-like) titles not division headings, then you are provided the\ltxLookSetup
\ltxLookSetup
declaration (allowed only in the preamble). However, even after this declaration the files will be included according togmdoc’s rules not necessarily to thedoc’s ones (i.e., with minimal marking necessary at the price of active line ends (therefore not allowed between a command and its argument nor inside an argument)).
On the other hand, if you like the look offered by me but you have the files prepared fordocnot forgmdoc, then you should declare
\olddocIncludes
. Unlike the previous\olddocIncludes
one, this may be used anywhere, because I have the account of including bothdoc-like andgmdoc-like files into one document. This declaration just changes the internal input command and doesn’t change the sectioning settings.
It seems possible that you wish to document the ‘old-doc’ files first and the ‘new-doc’
ones after, so the above declaration has its counterpart,
\gmdocIncludes
, that may be\gmdocIncludes
used anywhere, too. Before the respective
\DocInclude
(s), of course.Both these declarationsOCSR.
If you wish to document your files as withltxdocandas withdoc, you should declare
\ltxLookSetup
in the preambleand\olddocIncludes
.Talking of analogies withltxdoc, if you like only the page layout provided by that class, there is the
\ltxPageLayout
declaration (allowed only in preamble) that only\ltxPageLayout
changes the margins and the text width (it’s intended to be used with the default paper size). This declaration is contained in the
\ltxLookSetup
declaration.If you need to add something at the beginning of the input of file, there’s the
\AtBe¦
\AtBegInput
gInput
declaration that takes one mandatory argument which is the stuff to be added.This declaration is global. It may be used more than one time and the arguments of each occurrence of it add up and are put at the beginning of input of every subsequent files.
Simili modo, for the end of input, there’s the
\AtEndInput
declaration, also one-\AtEndInput
argument, global and cumulative.
If you need to add something at the beginning of input of only one file, put before the respective input command an
\AtBegInputOnce{
〈the stuff to be added〉}
declara-\AtBegInputOnce
tion. It’s also global which means that the groups do not limit its scope but it adds its argument only at the first input succeeding it (the argument gets wrapped in a macro that’s
\relax
ed at the first use).\AtBegInputOnce
s add up, too.
One more input command is
\IndexInput
(the name and idea of effect comes from\IndexInput
doc). It takes the same argument as
\DocInput
, the file’s (path and) name with exten- sion. (Ithas\DocInput
inside). It works properly if the input file doesn’t contain explicit〈char〉(
^^A
isOK).The effect of this command is typesetting of all the input file verbatim, with the code lines numbered and theCSes automatically indexed (gmdoc.styoptions are in force).
Package options
As many good packages, this also provides some options:
Due to best TEX documenting traditions the codelines will be numbered. But if the user doesn’t wish that, they may turn it off with the
linesnotnum
option.linesnotnum
However, if they agrees to have the lines numbered, they may wish to reset the counter of lines themself, e.g., when they documents many source files in one docu- ment. Then they may wish the line numbers to be reset with every
{section}
’s turn for instance. This is the rôle of theuresetlinecount
option, which seems to be a bituresetlinecount
obsolete however, since the
\DocInclude
command takes care of a proper reset.Talking of line numbering further, a tradition seems to exist to number only the code- lines and not to number the lines of commentary. That’s the default behaviour ofgmdoc but, if someone wants the comment lines to be numbered too, which may be conve- nient for reference purposes, they is provided the
countalllines
option. This optioncountalllines
switches things to use the
\inputlineno
primitive for codeline numbers so you get the numbers of the source file instead of number only of the codelines. Note however, that there are no hypertargets made to the narration lines and the value of\ref
is the number of the most recent codeline.Moreover, if they wants to get the narration lines’ number printed, there is the starred version of that option,
countalllines⋆
. I imagine someone may use it for debug.countalllines⋆
This option is not finished in details, it causes errors with
\addvspace
because it puts a hyperlabel at every line. When it is in force, all the index entries are referenced with the line numbers and the narration acquires a bit biblical look ;-),as shown in this short example. This option is intendedfor the draft versions and it is not perfect (as if anythingin this package was). As you see, the linesare typeset continuously with the numbers printed.By default themakeidxpackage is loaded and initialised and the CSes occurring in the code are automatically (hyper)indexed thanks to thehyperrefpackage. If the user doesn’t wish to index anything, she should use the
noindex
option.noindex
The index comes two possible ways: with the line numbers (if the lines are num- bered) and that’s the default, or with the page numbers, if the
pageindex
option ispageindex
set.
The references in the change history are of the same: when index is line number, then the changes history too.
By default,gmdocexcludes some CSes from being indexed. They are the most common CSes, LATEX internal macros and TEX primitives. To learn what CSes are ex- cluded actually, see lines–.
If you don’t want all those exclusions, you may turn them off with the
indexallmacros indexallmacros
option.
If you have ambiguous feelings about whether to let the default exclusions or forbid them, see p.to feed this ambiguity with a couple of declarations.
Indoc package there’s a default behaviour of putting marked macro’s or environ- ment’s name to a marginpar. In the standard classes it’s alright but not all the classes support marginpars. That is the reason why this package enables marginpar-ing when
in standard classes, enables or disables it due to the respective option when with Marcin Woliński’s classes and in any case provides the options
withmarginpar
andwithmarginpar
nomarginpar
. So, in non-standard classes the default behaviour is to disable margin-nomarginpar
pars. If the marginpars are enabled ingmdoc, it will put marked control sequences and environments into marginpars (see\TextUsageetc.). These options do not affect com- mon using marginpars, which depends on the document class.
My suggestion is to make the spaces in the code visible except the leading ones and that’s the default. But if you wish all the code spaces to be blank, I give the option
codespacesblank
reluctantly. Moreover, if you wish the code spaces to be blank onlycodespacesblank
in some areas, then there’s
\CodeSpacesBlank
declaration (OCSR).\CodeSpacesBlank
Another space formatting option is
codespacesgrey
suggested by Will Robertson.codespacesgrey
It makes the spaces of code visible only not black but grey. The name of their colour is
visspacesgrey
and by default it’s defined as{gray}{.}
, you can change it with xcolor’s\definecolor
. There is also anOCSRdeclaration\CodeSpacesGrey
.\CodeSpacesGrey
If for any reason you wish the code spaces blank in general and visible and grey in
verbatim⋆
s, use the declaration\VisSpacesGrey
of thegmverbpackage. If you\VisSpacesGrey
like little tricks, you can also specify
codespacesgrey,␣codespacesblank
ingmdoc options (in this order).The packages required
gmdocrequires (loads if they’re not loaded yet) some other packages of mine, namely gmutils, gmverb, analogous to Frank Mittelbach’s shortvrb, and gmiflink for conditional making of hyperlinks. It also requireshyperref,multicol,colorandmakeidx.
Thegmverbpackage redefines the
\verb
command and theverbatim
environment gmverbin such a way that␣,
{
and\
are breakable, the first with no ‘hyphen’ and the other two with the comment char as a hyphen, i.e.,{
〈subsequent text〉}
breaks into{%
〈subsequent text〉
}
and〈text〉\mylittlemacro
breaks into〈text〉%
\mylittlemacro
.This package provides the
\verbatimspecials
declaration that is used in gm-\verbatimspecials
docc.clsas
\verbatimspecials⁄«»[¿]
to set
⁄
(fractional slash) to the escape char,«
and»
to group begin and end respectively and¿
to math shift in verbatims (also the short ones). Note however that this declaration has no effect on the code layer.As the standard LATEX one, my
\verb
issues an error when a line end occurs in its scope. But, if you’d like to allow line ends in short verbatims, there’s the\verbeolOK
\verbeolOK
declaration. The plain
\verb
typesets spaces blank and\verb⋆
makes them visible, as in the standard version(s).Moreover,gmverbprovides the
\MakeShortVerb
declaration that takes a one-char\MakeShortVerb
control sequence as the only argument and turns the char used into a short verbatim delimiter, e.g., after
\MakeShortVerb⋆\|
(as you see, the declaration has the starred version, which is for visible spaces, and non- starred for blank spaces) to get
\mylittlemacro
you may type|\mylittlemacro|
instead of
\verb+\mylittlemacro+
. Because the char used in the last example is my favourite and is used this way by DEK inThe TEX book’s format,gmverbprovides a macro\dekclubs
that expands to the example displayed above.\dekclubs
Be careful because such active chars may interfere with other things, e.g., the
|
with the vertical line marker intabular
s and with thetikzpackage. If this happens, you can declare e.g.,\DeleteShortVerb\|
and the previous meaning of the char used shall\DeleteShortVerb
be restored.
One more difference betweengmverbandshortvrbis that the chars
\active
ated by\MakeShortVerb
, behave as if they were ‘other’ in math mode, so you may type e.g.,k|n
to getk|netc.Thegmutilspackage provides a couple of macros similar to some basic (LA)TEX ones, gmutils
rather strictly technical and (I hope) tricky, such as
\afterfi
,\ifnextcat
,\ad¦
dtomacro
etc. It’s this package that provides the macros for formatting of names of macros and files, such as\cs
,\marg
,\pk
etc. Moreover, it provides a powerful tool for defining commands with weird optional and Knuthian arguments,\DeclareCommand
, inspired by ancient (pre-expl)xparse’s\DeclareDocumentCommand
.Thegmdocpackage uses a lot of hyperlinking possibilities provided byhyperrefwhich hyperref
is therefore probably the most important package required. The recommended situation is that the user loadshyperrefpackage with their favourite optionsbeforeloadinggmdoc.
If they does not,gmdocshall load it withmyfavourite options.
To avoid an error if a (hyper)referenced label does not exist,gmdocuses thegmiflink gmiflink
package. It works e.g., in the index when the codeline numbers have been changed: then they are still typeset, only not as hyperlinks but as a common text.
To typeset the index and the change history in balanced columnsgmdoc uses the multicolpackage that seems to be standard these days.
multicol
Also the multicolpackage, required to define the default colour of the hyperlinks, color
seems to be standard already, andmakeidx. Automatic marking of definitions
gmdocimplements automatic detection of a couple of definitions. By default it detects all occurrences of the following commands in the code:
.
\def
,\newcount
,\newdimen
,\newskip
,\newif
,\newtoks
,\newbox
,\newread
,\newwrite
,\newlength
,\newcommand
[⋆
],\renewcommand
[⋆
],\providecommand
[⋆
],\DeclareRobustCommand
[⋆
],\DeclareTextCommand
[⋆
],\DeclareTextCommandDefault
[⋆
],\DeclareDocumentCommand
,\DeclareCommand
.
\newenvironment
[⋆
],\renewenvironment
[⋆
],\DeclareOption
,.
\newcounter
,of thexkeyvalpackage:
.
\define@key
,\define@boolkey
,\define@choicekey
,\DeclareOptionX
, and of thekvoptionspackage:.
\DeclareStringOption
,\DeclareBoolOption
,\DeclareComplementaryOption
,\DeclareVoidOption
.What does ‘detects’ mean? It means that the main argument of detected command will be marked as defined at this point, i.e. thrown to a margin note and indexed with a ‘definition’ entry. Moreover, for the definitions – an alternate index entries will be created: of theCSes underlying those definitions, e.g.
\newcounter{foo}
in the code will result in indexingfoo
and\c@foo
.If you want to add detection of a defining command not listed above, use the
\De¦
\DeclareDefining
clareDefining
declaration. It comes in two flavours: ‘sauté’ and with star. The ‘sauté’version (without star and without an optional argument) declares a defining command of the kind of
\def
and\newcommand
: its main argument, whether wrapped in braces FMI: the implementation took me / hrs.
or not, is a CS. The starred version (without the optional argument) declares a defin- ing command of the kind of
\newenvironment
and\DeclareOption
: whose main mandatory argument is text. Both versions provide an optional argument in which you can set the keys.Probably the most important key is
type
. Its default value iscs
and that is set intype
the ‘sauté’ version. Another possible value is
text
and that is set in the starred version.You can also set three other types (any keyval setting of the type overrides the default and ‘starred’ setting):
dk
,dox
orkvo
.dk
stands for\define@key
and is the type ofxkeyval definitions of keys (group commands). When detected, it scans further code for an optional[
〈KVprefix〉]
, manda- tory{
〈KVfamily〉}
and mandatory{
〈key name〉}
. The default〈KVprefix〉isKV
, as in xkeyval.dox
stands for\DeclareOptionX
and launches scanning for an optional[
〈KV- prefix〉]
, optional<
〈KVfamily〉>
and mandatory{
〈option name〉}
. Here the default〈KVprefix〉 is also
KV
and the default 〈KVfamily〉is the input file name. If you want to set another default family (e.g. if the code offoo.sty actually is in file bar.dtx), use\DeclareDOXHead{
〈KVfamily〉}
. This declaration has an optional first argument that\DeclareDOXHead
is the default〈KVprefix〉for
\DeclareOptionX
definitions.kvo
stands for the kvoptions package by Heiko Oberdiek. This package provides a handful of option defining commands (the group commands). Detection of such a command launches a scan for mandatory{
〈option name〉}
and alternate indexing of aCS\
〈KVOfamily〉@
〈option name〉. The default〈KVOfamily〉is the input file name.Again, if you want to set something else, you are given the
\DeclareKVOFam{
〈KVO-\DeclareKVOFam
family〉
}
that sets the default family (and prefix: 〈KVOfamily〉@
) for all the commands of group.Next key recognised by
\DeclareDefining
isstar
. It determines whether thestar
starred version of a defining command should be taken into account. For example,
\newcommand
should be declared with[star=true]
while\def
with[star=false]
. You can also write just[star]
instead of[star=true]
. It’s the default if thestar
key is omitted.There are also
KVpref
andKVfam
keys if you want to redeclare thexkeyvaldefinitionsKVpref
KVfam
with another default prefix and family.For example, if you wish
\@namedef
to be detected (the original LATEX version), de- clare\DeclareDefining⋆[star=false]\@namedef
or\DeclareDefining[type=text,star=false]\@namedef
(as stated above,⋆
is equivalent to[type=text]
).On the other hand, if you want some of the commands listed abovenotto be de- tected, write
\HideDefining\
〈command〉 in the commentary. If both 〈command〉\HideDefining
and 〈command⋆〉 are detected, then both will be hidden.
\HideDefining
is always\global
. Later you can resume detection of〈command〉and〈command⋆〉with\Re¦
\ResumeDefining
sumeDefining
〈command〉 which is always\global
too. Moreover, if you wish to suspend automatic detection of the defining 〈command〉 only once (the next occur- rence), there is\HideDefining⋆
which suspends detection of the next occurrence of〈command〉. So, if you wish to ‘hide’
\providecommand⋆
once, write\HideDefining⋆\providecommand⋆
If you wish to turn entire detection mechanism off, write
\HideAllDefining
in\HideAllDefining
Thestarkey is provided because the default setting of\MakePrivateLettersis such that⋆is a letter so e.g.\newcommand⋆is scanned as oneCS. However, if the\makestarlowdeclaration is in force (e.g. with thegmdocc) this is not so—\newcommand⋆is scanned as theCS\newcommandanda star.
the narration layer. Then you can resume detection with
\ResumeAllDefining
. Both\ResumeAllDefining
declarations are
\global
.The basic definition command,
\def
, seems to me a bit ambiguous. Definitelynot always it defines important macros. But first of all, if you\def
a CS excluded from indexing (see section Index ex/inclusions), it will not be marked even if detection of\def
is on. But if the\def
’s argument is not excluded from indexing and you still don’t want it to be marked at this point, you can write\HideDefining⋆\def
or\UnDef
for\UnDef
short.
If you don’t like
\def
to be detected more times, you may write\HideDefining%
\def
of course, but there’s a shorthand for this:\HideDef
which has the starred version\HideDef
\HideDef
* equivalent to\UnDef
. To resume detection of\def
you are provided also\HideDef
a shorthand,
\ResumeDef
(but\ResumeDefining\def
also works).\ResumeDef
Since I use
\pdef
most often, I provide also\UnPdef
, analogous to\UnDef
.\UnPdef
If you define things not with easily detectable commands, you can mark them ‘man- ually’, with the
\Define
declaration described in the next section.Manual Marking of the Macros and Environments
The concept (taken fromdoc) is to index virtually all the control sequences occurring in the code.gmdocdoes that by default and needs no special command. (See below about excluding some macros from being indexed.)
The next concept (also taken fromdoc) is to distinguish some occurrences of some control sequences by putting such a sequence into a marginpar and by special format- ting of its index entry. That is what I call marking the macros. gmdoc provides also a possibility of analogous marking for the environments’ names and other sequences such as
^^A
.This package provides two kinds of special formatting of the index entries: ‘usage’, with the reference number italic by default, and ‘def’ (indoccalled ‘main’), with the ref- erence number roman (upright) and underlined by default. All the reference numbers, also those with no special formatting, are made hyperlinks to the page or the codeline according to the respective indexing option (see p.).
The macros and environments to be marked appear either in the code or in the com- mentary. But all the definitions appear in the code, I suppose. Therefore the ‘def’ mark- ing macro is provided only for the code case. So we have the
\Define
,\CodeUsage
\Define
\CodeUsage
and\TextUsage
commands.\TextUsage
The arguments to all three are as follows:#
[⋆
] to indicate whether we mark a singleCSor more than one token(s): without star for a singleCS, with star for environment names etc., the starred version executes\@sanitize
,[#] o
version to be marginized and printed here,# m
version to be put to the index, and also (printed here and) marginized if the previous argument is missing.Note that if you give a single CS to the starred version (e.g. the next
\MakePri¦
vateLetters
is done so to hyphenate it in the text), you have to wrap it in braces be- cause command\@sanitize
s the specials including backslash.You don’t have to bother whether
@
is a letter while documenting because even if not, these commands do make it a letter, or more precisely, they execute\MakePrivate¦
\MakePrivateLetters
Letters
whatever it does: At the default settings this command makes⋆
a letter, too, so a starred version of a command is a proper argument to any of the three commands unstarred.The
\Define
and\CodeUsage
commands, if unstarred, mark the next scanned oc- currence of their argument in the code. (By ‘scanned occurrence’ I mean a situation of theCShaving been scanned in the code which happens iff its name was preceded by the
char declared as
\CodeEscapeChar
). The starred versions of those commands mark just the next codeline and don’t make TEX looks for the scanned occurrence of their ar- gument (which would never happen if the argument is not aCS). Therefore, if you want to mark a definition of an environmentfoo
, you should put%\Define⋆{foo}
right before the code line
\newenvironment{foo}{%
i.e., not separated by another code line. The starred versions of the
\Code
…commands are also intended to mark implicit definitions of macros, e.g.,\Define⋆\@foofalse
before the line\newif\if@foo
.They both are
\outer
to discourage their use inside macros because they actually re\catcode
before taking their arguments.The
\TextUsage
(one-argument) command is intended to mark usage of a verba- tim occurrence of a TEX object in the commentary. Unlike\CodeUsage
or\Define
, it typesets its argument which means among others that the marginpar appears usually at the same line as the text you wanted to mark. This command also has the starred version primarily intended for the environments names, and secondarily for^^A
-likes andCSes, too. Currently, the most important difference is that the unstarred version ex- ecutes\MakePrivateLetters
while the starred does both\MakePrivateLetters
and\MakePrivateOthers
before reading the argument.If you consider the marginpars a sort of sub(sub…)section marks, then you may wish to have a command that makes a marginpar of the desiredCS(or whatever) at the be- ginning of its description, which may be fairly far from the first occurrence of its object.
Then you have the
\Describe
command which puts its argument in a marginpar and\Describe
indexes it as a ‘usage’ entry but doesn’t print it in the text. It’s
\outer
.All four commands just described put their (
\string
ed) argument into a marginpar (if the marginpars are enabled) and create an index entry (if indexing is enabled).But what if you want just to make a marginpar with macro’s or environment’s name?
Then you have
\CodeMarginize
to declare what to put into a marginpar in the TEX\CodeMarginize
code (it’s
\outer
) and\TextMarginize
to do so in the commentary. According to\TextMarginize
the spirit of this part of the interface, these commands also take one argument and have their starred versions for strings other than control sequences.
The marginpars (if enabled) are ‘reverse’ i.e., at the left margin, and their contents is flush right and typeset in a font declared with
\marginpartt
. By default, this decla-\marginpartt
ration is
\let
to\tt
but it may be advisable to choose a condensed font if there is any.Such a choice is made bygmdocc.clsif the Latin Modern fonts are available: in this case gmdocc.clsuses Latin Modern Typewriter Light Condensed.
If you need to put something in a marginpar without making it typewriter font, there’s the
\gmdmarginpar
macro (that takes one and mandatory argument) that only\gmdmarginpar
flushes its contents right.
On the other hand, if you don’t want to put a CS(or another verbatim text) in a marginpar but only to index it, then there are
\DefIndex
and\CodeUsgIndex
to\DefIndex
\CodeUsgIndex
declare special formatting of an entry. The unstarred versions of these commands look for their argument’s scanned occurrence in the code (the argument should be aCS), and the starred ones just take the next code line as the reference point. Both these commands are\outer
.In the code all the control sequences (except the excluded ones, see below) are in- dexed by default so no explicit command is needed for that. But the environments and other special sequences are not and the two commands described above in their
⋆
ed
versions contain the command for indexing their argument. But what if you wish to index a not scanned stuff as a usual entry? The
\CodeCommonIndex
* comes in rescue,\CodeCommonIndex
starred for the symmetry with the two previous commands (without
⋆
it just gobbles it’s argument—it’s indexed automatically anyway). It’s\outer
.Similarly, to index a TEX object occurring verbatim in the narrative, you have
\Text¦
\TextUsgIndex
UsgIndex
and\TextCommonIndex
commands with their starless versions for a CS\TextCommonIndex
argument and the starred for all kinds of the argument.
Moreover, as indoc, the
macro
andenvironment
environments are provided. Bothmacro
environment
take one argument that should be a CS formacro
and ‘whatever’ forenvironment
. Both add the\MacroTopsep
glue before and after their contents, and put their argu- ment in a marginpar at the first line of their contents (since it’s done with\strut
, you should not put any blank line (%
ed or not) between\begin{macro/environment}
and the first line of the contents). Then
macro
commands the first scanned occurrence of its argument to be indexed as ‘def’ entry andenvironment
commands TEX to index the argument as if it occurred in the next code line (also as ‘def’ entry).Since it’s possible that you define aCS implicitly i.e., in such a way that it cannot be scanned in the definition (with
\csname
…\endcsname
e.g.) and wrapping such a definition (and description) in anenvironment
environment would look misguid- edly ugly, there’s themacro⋆
environment which TEXnically is just an alias forenvi¦
ronment
.(To be honest, if you give a
macro
environment a non-CSargument, it will accept it and then it’ll work asenvironment
.)Index ex/inclusions
It’s understandablethat you don’t want some control sequences to be indexed in your documentation. Thedocpackage gives a brilliant solution: the
\DoNotIndex
declara-\DoNotIndex
tion. So do I (although here, TEXnically it’s done another way). ItOCSR. This declaration takes one argument consisting of a list of control sequences not to be indexed. The items of this list may be separated with commas, as indoc, but it’s not obligatory. The whole list should come in curly braces (except when it’s one-element), e.g.,
\DoNotIndex{\some@macros,\are⋆␣\too\auxiliary\?}
(The spaces after the control sequences are ignored.) You may use as many
\DoNotIn¦
dex
es as you wish (about half as many as manyCSes may be declared, because for each CS excluded from indexing a specialCS is declared that stores the ban sentence). Ex- cluding the sameCSmore than once makes no problem.I assume you wish most of LATEX macros, TEX primitives etc. to be excluded from your index (as I do). Thereforegmdocexcludes some CSes by default. If you don’t like it, just set the
indexallmacros
package option.On the third hand, if you like the default exclusions in general but wish to undo just a couple of them, you are given
\DoIndex
declaration (OCSR) that removes a ban on all\DoIndex
theCSes given in the argument, e.g.,
\DoIndex{\par␣\@@par␣\endgraf}
Moreover, you are provided the
\DefaultIndexExclusions
and\UndoDef¦
\DefaultIndexExclusions
\UndoDefaultIndexExclusions aultIndexExclusions
declarations that act according to their names. You may use them in any configuration with theindexallmacros
option. Both of these declarations OCSR. After readingdoc’s documentation ;-) .
