% % \GetFileInfo{gmdoc.sty} % \title{The \pk{gmdoc.sty} Package\thfileinfo} % \author{Natror (Grzegorz Murzynowski)} % \date{\fakeonum[0.6]\today} % \maketitle % \label{gmd} %% %% This is (a~documentation of) file \pk{gmdoc.sty}, %% intended to be used with \LaTeXe\ as a~package for %% documenting \LaTeXpar\ files and to be documented with itself. %% \stanza %% % \begin{copyrnote} % %% Written by Natror (Grzegorz Murzynowski), %% natror at o2 dot pl %% %% \copyright\,2006, 2007, 2008, 2009, 2010 by Natror (Grzegorz Murzynowski). %% %% This program is subject to the \LaTeX\ Project Public License. %% See \url{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html} ^^A %% for the details of that license.\rrthis %% %% \acro{LPPL} status: "author-maintained".\par %% %% Many thanks to my \TeX\ Guru Marcin Woli\nacute ski for his \TeX nical ^^A %% support. % %\end{copyrnote} % % \ChangesStart{v0.98c}{1000/0/0} % % \chschange{v0.96}{2006/08/22}{2395} % \chschange{v0.97}{06/09/04}{3636} % \chschange{v0.98}{06/09/04}{3636} % \chschange{v0.98a}{06/09/06}{4092} % \chschange{v0.98b}{06/9/7}{4119} % \chschange{v0.98c}{06/9/10}{4299} % \chschange{v0.98d}{06/9/15}{4409} % \chschange{v0.98e}{06/9/23}{4420} % \chschange{v0.98f}{06/9/30}{4430} % \chschange{v0.98g}{06/10/5}{4294} % \chschange{v0.98i}{06/10/14}{4352} % \chschange{v0.98j}{06/10/17}{4372} % \chschange{v0.98k}{06/10/21}{4416} % \chschange{v0.98l}{06/10/27}{4401} % \chschange{v0.98m}{06/11/14}{4349} % \chschange{v0.99}{06/11/29}{4462} % \chschange{v0.99a}{2006/12/01}{4479} % \chschange{v0.99b}{07/01/01}{4479} % \chschange{v0.99c}{07/3/2}{4486} % \chschange{v0.99c}{07/3/30}{4475} % \chschange{v0.99d}{07/4/26}{4555} % \chschange{v0.99e}{2007/4/29}{4574} % \chschange{v0.99g}{2007/11/12}{5229} % \chschange{v0.99i}{2008/8/3}{5247} % \chschange{v0.99j}{2008/8/3}{5266} % \chschange{v0.99k}{2008/8/4}{5261} % \chschange{v0.99l}{2008/8/6}{5225} % \chschange{v0.99m}{2008/8/9}{5356} % \chschange{v0.99m}{2008/8/13}{5354} % \chschange{v0.99n}{2008/8/22}{5409} % \chschange{v0.99n}{2008/8/30}{5547} % \chschange{v0.99p}{2008/10/4}{5607} % \chschange{v0.99q}{2008/10/10}{5603} % \chschange{v0.99r}{2008/11/22}{5607} % \toCTAN{2008/11/22 v0.99r} % \chschange{v0.99s}{2008/12/15}{5974} % [\env{enumargs} handling the % argument types of \cmd\DeclareCommand; handling % \cmd\verbatimspecials, including writing them to index; introduction % of \cmd\narrativett\ including \cmd\ampulexdef\ of \pk{gmverb} % internals] % \chschange{v0.991}{2010/3/2}{6134} % [compatibilising the \env{enumargs} environment with % \cmd\DeclareCommand of \pk{gmutils} v.0.991; abandoning % \pk{gmeometric}] % \toCTAN{2010/03/04 v0.991} % % % % \ifnum\catcode`\@=11 % Why this test here---will come out in chapter % \gmiflink{The driver}. ^^A~( the very first line % ^^A and about coming out already! ;-) \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{gmdoc} [2010/03/01 v0.991 a documenting package (GM)] \fi % % % % \CharacterTable {In my \TeX\ Guru's opinion the idea of % checking of the correctness of chars is a~bit obsolete % nowadays. Therefore I~define the \CharacterTable<#1> % macro to gobble its argument and to typeout a~request % for request.} % % % \newcommand*\docfm{\pk{doc}} % \newcommand*\gmdoc{\pk{gmdoc}} % % \tableofcontents % % % \division{Readme} % % This package is a~tool for documenting of \LaTeXpar\ % packages, classes etc., i.e., the \file{.sty}, \file{.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 standard % \pk{doc.sty} package, % i.e., the \file{.dtx} files are also compilable with \pk{gmdoc} % (they may need a~tiny adjustment in some special % cases). % % The tools are integrated with \pk{hyperref}'s advantages such as % hyperlinking of index entries, contents entries and % cross-references. % % The package also works with \XeTeX\ (switches automatically). % % \begin{gmlonely} % \subdivision{Installation} Unpack the \file{gmdoc-tds.zip} archive % (this is an archive conforming the \acro{TDS} standard, see % \file{CTAN/tds/tds.pdf})% in a~\file{texmf} directory % or put the \pk{gmdoc.sty}, \pk{gmdocc.cls} and \pk{gmoldcomm.sty} % somewhere in the \file{texmf/tex/latex} branch on your own. % (Creating a~\file{texmf/tex/latex/gm} directory may be % advisable if you consider using other packages written by me. And % you \emph{have} to use four of them to make \pk{gmdoc} work.) % % You should also install \pk{gmverb.sty}, \pk{gmutils.sty} and % \pk{gmiflink.sty} (e.g., put them into the same \file{gm} % directory). These packages are available on \acro{CTAN} as separate % \file{.zip} archives also in \acro{TDS}-compliant \pk{zip} % archives. % % Moreover, you should put the \file{gmglo.ist} file, a MakeIndex % style for the changes' history, into some \file{texmf/makeindex} % (sub)directory. % % Then you should refresh your \TeX\ distribution's files' database % most probably. % \end{gmlonely} % % % \subdivision{Contents of the \pk{gmdoc.zip} archive} % % The distribution of the \pk{gmdoc} package consists of the % following five files and a~\acro{TDS}-compliant archive. % \begin{verse} % \pk{gmdoc.sty}\\ % \pk{gmdocc.cls}\\ % \pk{gmglo.ist}\\ % \pk{README}\\ % \pk{gmdoc.pdf}\\ % \pk{gmdoc.tds.zip} % \end{verse} % % % \begin{gmlonely} % \subdivision{Compiling of the documentation} % % The last of the above files (the \pk{.pdf}, i.e., \emph{this ^^B % file}) is a~documentation compiled from the \pk{.sty} and % \pk{.cls} files by running \XeLaTeX\ on the \file{gmdoc.sty} % twice (|xelatex gmdoc.sty| in the directory you wish the % documentation to be in, you don't have copy the \file{.sty} file % there, \TeX\ will find it), then MakeIndex on the \file{gmdoc.idx} and % \file{gmdoc.glo} files, and then \XeLaTeX\ on \file{gmdoc.sty} % once more. (Using \LaTeX\ instead of \XeLaTeX\ should do, too.) % % MakeIndex shell commands: %\begin{verbatim} %makeindex -r gmdoc %makeindex -r -s gmglo.ist -o gmdoc.gls gmdoc.glo %\end{verbatim} % 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: % \pk{gmdoc} (\pk{gmdoc.sty} and \pk{gmdocc.cls}), \pk{gmutils.sty}, % \pk{gmverb.sty}, \pk{gmiflink.sty} and also some standard packages: % \pk{hyperref.sty}, \pk{xcolor.sty}, \pk{geometry.sty}, % \pk{multicol.sty}, \pk{lmodern.sty}, \pk{fontenc.sty} that should % be installed on your computer by default. % % If you had not installed the \pk{mwcls} classes (available on % \acro{CTAN} and present in \TeX\ Live e.g.), the result of your % compilation might differ a~bit from the \pk{.pdf} provided in this % \pk{.zip} archive in formatting: If you had not installed % \pk{mwcls}, the standard \pk{article.cls} class would be used. % \end{gmlonely} % % \subdivision{Dependencies} % % The \pk{gmdoc} bundle depends on some other packages of mine: % \begin{verse} % \pk{gmutils.sty},\\ % \pk{gmverb.sty},\\ % \pk{gmiflink.sty} %^^A% \pk{gmeometric} (for the driver of The \LaTeXe\ Source)\\ % \end{verse} % and also on some standard packages: % \begin{verse} % \pk{hyperref.sty},\\ % \pk{color.sty},\\ % \pk{geometry.sty},\\ % \pk{multicol.sty},\\ % \pk{lmodern.sty},\\ % \pk{fontenc.sty}\\ % \end{verse} % that should % be installed on your computer by default. % % % \subdivision{Bonus: \file{base} drivers} % As a~bonus and example of \docfm-compatibility % there are driver files included % (cf.\ Palestrina, \textit{Missa papae Marcelli} ;-): % % \begin{verse} % \pk{source2e_gmdoc.tex}\\ % \pk{docstrip_gmdoc.tex}\\ % \pk{doc_gmdoc.tex} % % \pk{gmoldcomm.sty}\\ % (\pk{gmsource2e.ist} is generated from \pk{source2e_gmdoc.tex})\\ % \end{verse} % % These drivers typeset the respective files from the %\[\hbox{\file{…/texmf-dist/source/latex/base}}\] % directory of the \TeX Live2007 distribution (they only read that % directory). % % Probably you should redefine the |\BasePath| macro in them % so that it points that directory on your computer. % % %\division*{Introduction} % % There are very sophisticated and effective tools for documenting % \LaTeX\ macro packages, namely the \pk{doc} package and the % \pk{ltxdoc} class. % Why did I~write another documenting package then? % % I~like comfort and \pk{doc} is 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 the \docfm's conventions are acceptable, is that % \gmdoc\ makes use of \pk{hyperref} advantages and makes % a~hyperlinking index and toc entries and the % cross-references, too. (The \CSs in the code maybe in the future.) % % The rest is striving to level the very high \pk{doc/ltxdoc}'s % standard, such as (optional) numbering of the codelines and % automatic indexing the control sequences e.g. % % The \docfm\ package was and still is a~great inspiration for me and % I~would like this humble package to be considered as a~sort of % homage to it\footnote{As Grieg's Piano Concerto is a~homage to ^^B % the Schumann's.}. If I~mention copying some code or narrative but do % not state the source explicitly, I~mean the \docfm\ package's % documentation (I~have v2.1b dated 2004/02/09). % % % % \division{The user interface} % % % \subdivision{Used terms} % % When I~write of a~\textbf{macro}, I~mean a~macro in \TeXbook's % meaning, i.e., a~control sequence whose meaning is % |\›[e⁄|g⁄|x›]def|ined. By a~\textbf{macro's parameter} I~mean each of % |#|\s in its definition. When I~write about ^^A\) % a~\textbf{macro's argument}, I~mean the value (list of tokens) % substituting the corresponding parameter of this macro. % (These understandings are according ^^A( % to \TeXbook, I~hope: \TeX\ is a~religion of Book ;-)\,.) % % I'll use a~shorthand for `control sequence', \textbf{\CS}. % % When I~talk of a~\textbf{declaration}, I~mean a~macro that expands % to a~certain assignment, such as |\itshape| or % |\@onlypreamble{⁄<⁄CS>}|. % % Talking of declarations, I'll use the \textbf{\acro{OCSR}} acronym as % a~shorthand for 'observes/ing common \TeX\ scoping rules'. % % By a~\textbf{command} I~mean a~certain abstract visible to the end % user as a~\CS but consisting possibly of more than one macro. I'll % talk of a~\textbf{command's argument} also in % the `sense\:-for\:-the\:-end\:-user', e.g., I'll talk of the % |\verb| \emph{command's} argument although \emph{the macro} % |\verb| has no |#|\ in its definition. % % The \textbf{code} to 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). % % The \textbf{commentary} or \textbf{narrative} is everything after % the comment char till the end of a~line. The \textbf{comment char} % is a~character the |\catcode| of which is 14 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 with % \gmdoc, such a~char is re|\catcode|d and its r\ocircum le is else: it % becomes the \textbf{code delimiter}. % % A~line containing any \TeX\ code (not commented out) will be called % a~\textbf{codeline}. A~line that begins with (some leading spaces % and) a~code delimiter will be called a~\textbf{comment line} or % \textbf{narration line}. % % The \textbf{user} of this package will also be addressed % as \textbf{you}.\stanza % % 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 ^^A( % (\TextUsage\heshe\ etc. commands provided by \pk{gmutils}), so let % one be not surprised if `\heshe' sees `\himher self' altered in the % same sentence :-)\,. % % % \subdivision{Preparing of the source file} % % When \LaTeXpar\ with \pk{gmdoc.sty} package loaded typesets the % comment lines, the code delimiter 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 \hisher\ splendid code and brilliant % commentary. In the latter \heshe\ may use usual \LaTeXpar\ commands. % The only requirement is, if an argument is divided in two lines, to % end such a~dividing line with \TextUsage*{\^^M} (|\|\) or with % \TextUsage*{^^B} sequence that'll enter the (active) \ which % shall gobble the line end. ^^A~and the leading code delimiter of %^^A % the next line---obsoleted by ^^A~making % ignored in the commentary. % % But there is also a~\pk{gmdoc} version of |\footnote| provided that % sets the catcodes so that you don't bother about |^^B| in the % argument, \TextUsage\qfootnote that takes the same argument(s) as % the standard |\footnote| and for emphasis there is % \TextUsage*[\qemph]{\qemph}\arg{text to emphasise}. Both of them % work also in the ‘straight’ \acro{EOL}s' scope so you don't % bother. The \TextUsage\arg\ \pk{gmutils}' command also works without % |^^B|. % % Moreover, if \heshe\ wants to add a~meta-comment i.e., a~text that % doesn't appear in the code layer nor in the narrative, \heshe\ may % use the \TextUsage*{^^A} sequence that'll be read by \TeX\ as % \, which % in \gmdoc\ is 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 \cs{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 the \docfm\ conventions. If you don't % fancy the |^^B| special sequence, instead you may restore the % standard meaning of the line end with the \TextUsage\StraightEOL\ % declaration which % \acro{OCSR}. As almost all the control % sequences, it may be used also as an environment, i.e., % |\begin{StraightEOL}|\ \dots\ |\end{StraightEOL}|. However, if for any % reason you don't want to make an environment (a~group), there's % a~|\StraightEOL|'s counterpart, the \TextUsage\QueerEOL\ declaration that % restores again the % queer\qfootnote{In my understanding % `queer' and `straight' are not the opposites excluding each % other but the counterparts that may cooperate in harmony for % people's good. And, as I~try to show with the \cs{QueerEOL} and % \cs{StraightEOL} declarations, `queer' may be very useful and % recommended while `straight' is the standard but not necessarily % normative. ^^A% (Remember also Alice's in the Wonderland exclamations % ^^A % ``What a~queer day is today''.) % } ^^A % \gmdoc's meaning of the line end. It \acro{OCSR}, 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 \docfm's not embracing some code lines in % a~\env{macrocode} environment). % % ^^A % The \pk{gmdoc}'s ‘queer’ line ends may be surprising at first. For % ^^A % example they should not occur in the arguments to the commands % ^^A % because they cause errors then. To suppress the ‘queer’ and active % ^^A % line end in the arguments of commands you should end a~line with % ^^A % \TextUsage*{^^B} which will gobble the line end safely. % % \stanza % % As in standard \TeX ing, one gets a~paragraph by a~blank line. % Such a~line should be |%|ed of course. A~fully blank line is % considered a~blank \emph{code 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 \heshe\ should prepare a~main document file, % a~\textbf{driver} henceforth, to set all the % required formattings such as |\documentclass|, paper size % etc., and load this package with a~standard command % i.e., |\usepackage{gmdoc}|, just as \docfm's documentation says: % % \begin{quotation} % If one is going to document a set of macros with the \pk{[gm]doc} % package one has to prepare a special driver file which produces % the formatted document. This driver file has the following % characteristics: \par\leftskip\CodeIndent % \stanza % % \noindent|\documentclass[|\|]{|\|}|\par % \noindent|\usepackage[|\|]{gmdoc}|\par % \\par % \noindent|\begin{document}|\par % \\par % \noindent|\end{document}|\par % \end{quotation} % % % \subdivision{The main input commands} % % To typeset a~source file you may use the \TextUsage\DocInput\ % macro that takes the (path and) name of the file \emph{with ^^B % the extension} as the only argument, e.g., % |\DocInput{mybrilliantpackage.sty}|\qfootnote{I~use the ‘broken bar’ % character as a~hyphen in verbatim texts and hyperlinks. If you % dont't like it, see \cmd\verbDiscretionaryHyphen\ in \pk{gmverb}.}. % % (Note that an \emph{installed} package or class file is findable to % \TeX\ even if you don't specify the path.) % % If a~source file is written with rather \docfm\ than \gmdoc\ in % mind, then the \TextUsage\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 in % \TextUsage*{macrocode} environments, which is not necessary when you % use |\DocInput|. Moreover, with |\OldDocInput| the\ % \env{macrocode›[*›]} environments require to be ended with % \[|% \end{macrocode›[*›]}|\] as in \docfm. (With |\DocInput| you are % not obliged to precede |\end{macrocode›[*›]}| with The % Four Spaces.) % % \stanza % If you wish to document many files in one document, you are % provided \TextUsage\DocInclude\ command, analogous to \LaTeX's % |\include| and very likely to \pk{ltxdoc}'s command of the same % name. In \gmdoc\ it has one mandatory argument that should be the % file name \emph{without extension}, just like for |\include|. % % The file extensions\label{docinclude:extensions} supported by % |\DocInclude| are \pk{.fdd}, \pk{.dtx}, \pk{.cls}, \pk{.sty}, % \pk{.tex} and \pk{.fd}. The macro looks for one of those extensions % in the order just given. If you need to document 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 \TextUsage\maketitle\ so that it makes % a~chapter heading or, in the 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 % \TextUsage\PrintFilesAuthors\ in the preamble or before the relevant % |\DocInclude|s. If you wish to undeclare printing the authors names, % there is \TextUsage*[\Skip⁄-Fil⁄-es⁄-Auth⁄-ors]{\SkipFilesAuthors} % declaration. % % Like in \pk{ltxdoc}, 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 \pk{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 % \TextUsage\includeonly|{⁄}| for % the draft versions. % % \stanza If you want to put the driver into the same \file{.sty} or % \file{.cls} file (see chapter \ref{Driver} to see how), you may % write |\DocInput{\jobname.sty}|, or |\DocInclude{\jobname}|, but % there's also a~shorthand for the latter \TextUsage\SelfInclude \ % that takes no arguments. % By the way, to avoid an infinite recursive input of \file{.aux} % files in the case of self-inclusion an \file{.auxx} file is used % instead of (main) \file{.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. % \stanza % % At the default settings, the |\›(Doc⁄|Self›)Include|d files constitute % chapters if |\chapter| is known and parts otherwise. The % |\maketitle|s of those files result in the respective headings. % % If you prefer more \pk{ltxdoc}ish 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 \TextUsage\ltxLookSetup\ declaration (allowed only in the % preamble). However, even after this declaration the files will be % included according to \gmdoc's rules not necessarily to the \docfm'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 for \docfm\ not for \gmdoc, then you % should declare \TextUsage\olddocIncludes. Unlike the previous one, % this may be used anywhere, because I~have the account of including both % \docfm-like and \gmdoc-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, \TextUsage\gmdocIncludes, that may be used anywhere, % too. Before the respective |\DocInclude|(s), of course. % % Both these declarations \acro{OCSR}. % % If you wish to document your files as with \pk{ltxdoc} \emph{and} % as with \docfm, you should declare % |\ltxLookSetup| in the preamble \emph{and} |\olddocIncludes|. % % \stanza % Talking of analogies with \pk{ltxdoc}, if you like only the page % layout provided by that class, there is the % \TextUsage\ltxPageLayout\ declaration (allowed only in preamble) % that only 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. % % \stanza % If you need to add something at the beginning of the input of file, % there's the \TextUsage\AtBegInput\ 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 % \TextUsage\AtEndInput\ declaration, also one-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 % \TextUsage\AtBegInputOnce|{|\|}| % declaration. 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. % % \stanza % One more input command is \TextUsage\IndexInput\ (the name and idea % of effect comes from \docfm). It takes the same argument as % |\DocInput|, the file's (path and) name with extension. (It % \emph{has} |\DocInput| inside). It works properly if the input file % doesn't contain explicit \ (|^^A| is \acro{OK}). % % The effect of this command is typesetting of all the input file % verbatim, with the code lines numbered and the \CSs automatically % indexed (\pk{gmdoc.sty} options are in force). % % % \subdivision{Package options} % % As many good packages, this also provides some options: % \stanza % % Due to best \TeX\ documenting traditions the codelines will be % numbered. But if the user doesn't wish that, \heshe\ may turn it off % with the \TextUsage*{linesnotnum} option. % % However, if \heshe\ agrees to have the lines numbered, \heshe\ may wish % to reset the counter of lines \himher self, e.g., when \heshe\ % documents many source files in one document. Then \heshe\ may wish % the line numbers to be reset with every |{section}|'s turn for % instance. This is the r\ocircum le of the \TextUsage*{uresetlinecount} % option, which seems to be a~bit obsolete however, since the % \TextCommonIndex\DocInclude|\DocInclude| command takes care of % a~proper reset. % % Talking of line numbering further, a~tradition seems to exist to % number only the codelines and not to number the lines of % commentary. That's the default behaviour of \pk{gmdoc} but, if % someone wants the comment lines to be numbered too, which may be % convenient for reference purposes, \heshe\ is % provided the \TextUsage*{countalllines} option. This option switches % things to use the \cs{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 \cs{ref} is the number of the most % recent codeline. % % Moreover, if \heshe\ wants to get the narration lines' number % printed, there is the starred version of that option, % \TextUsage*{countalllines*}. I~imagine someone may use it for % debug. This option is not finished in details, it causes errors with % \cs{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 %% ^^A( % {\LineNumFont 441}\, the narration acquires a~bit biblical look ;-), % {\LineNumFont 442}\,as shown in this short example. This option is intended % {\LineNumFont 443}\,for the draft versions and it is not perfect (as if anything % {\LineNumFont 444}\,in this package was). As you see, the lines % {\LineNumFont 445}\,are typeset continuously with the numbers printed. % % \stanza % By default the \pk{makeidx} package is loaded and initialised and % the \CSs occurring in the code are automatically % (hyper)indexed thanks to the \pk{hyperref} package. If the user % doesn't wish to index anything, she should use the % \TextUsage*{noindex} option. % % The index comes two possible ways: with the line numbers (if the % lines are numbered) and that's the default, or with the page numbers, if % the \TextUsage*{pageindex}\label{indexoptions} option is set. % % The references in the change history are of the same: when index is % line number, then the changes history too. % % \stanza % By default, \gmdoc\ excludes some 300 \CSs from being indexed. % They are the most common \CSs, \LaTeX\ internal % macros and \TeX\ primitives. To learn what \CSs are % excluded actually, see lines \ref{DIE1}--\ref{DIE2}. % % If you don't want all those exclusions, you may turn them off with % the \TextUsage*{indexallmacros} option. % % If you have ambiguous feelings about whether to let the default % exclusions or forbid them, see p.\,\pageref{IEIDeclarations} to % feed this ambiguity with a~couple of declarations. % % \stanza % In \docfm\ package there's a~default behaviour of putting marked % macro's or environment'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\nacute ski's classes and in any case provides the % options \TextUsage*{withmarginpar} and \TextUsage*{nomarginpar}. So, in % non-standard classes the default behaviour is to disable marginpars. % If the marginpars are enabled in \pk{gmdoc}, it will put marked % control sequences and environments into marginpars (see % \gmiflink[textUsage]{\cs{TextUsage} etc.}). These options do % not affect common using marginpars, which depends on the % document class. % % \stanza % 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 \TextUsage*{codespacesblank} % reluctantly. Moreover, if you wish the code spaces to be blank only % in some areas, then there's \TextUsage\CodeSpacesBlank\ declaration % (\acro{OCSR}). % % Another space formatting option is \TextUsage*{codespacesgrey} % suggested by Will Robertson. 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}{.5}|, you % can change it with \pk{xcolor}'s |\definecolor|. There is also an % \acro{OCSR} declaration \TextUsage\CodeSpacesGrey. % % If for any reason you wish the code spaces blank in general and % visible and grey in \env{verbatim*}s, use the declaration % \TextUsage\VisSpacesGrey\ of the \pk{gmverb} package. If you like % little tricks, you can also specify % |codespacesgrey, codespacesblank| in \pk{gmdoc} options (in this % order). % % \subdivision{The packages required} % % \pk{gmdoc} requires (loads if they're not loaded yet) some other % packages of mine, namely \pk{gmutils}, \pk{gmverb}, analogous to % Frank Mittelbach's \pk{shortvrb}, and \pk{gmiflink} for conditional % making of hyperlinks. It also requires \pk{hyperref}, % \pk{multicol}, \pk{color} and \pk{makeidx}. % % The \pk{gmverb}\gmdmarginpar{\pk{gmverb}} package redefines the % |\verb| command and the \env{verbatim} environment in 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., % |{|\|}| breaks into % |{%|\\ \|}| ^^A] bal. braces for Emacs % and \|\mylittlemacro| breaks into \|%|\\ % |\mylittlemacro|. % % This package provides the \TextUsage\verbatimspecials\ declaration % that is used in \pk{gmdocc.cls} as {\noverbatimspecials % \[|\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 \qemph{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 \TextUsage\verbeolOK\ declaration. The % plain |\verb| typesets spaces blank and |\verb*| makes them visible, % as in the standard version(s). % % Moreover, \pk{gmverb} provides the \TextUsage\MakeShortVerb\ % declaration % that takes a~one-char control sequence as the only argument and % turns the char used into a~short verbatim delimiter, e.g., after % \[\verb+\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 \verb+|\mylittlemacro|+ instead of % |\verb+\mylittlemacro+|. Because the char used in the last example % is my favourite and is used this way by DEK in \TeXbook's % format, \pk{gmverb} provides a~macro \TextUsage\dekclubs\ that % expands to the example displayed above. % % Be careful because such active chars may interfere with other % things, e.g., the \verb+|+ with the vertical line marker in \env{tabular}s and % with the \pk{tikz} package. If this happens, you can declare e.g., % \TextUsage\DeleteShortVerb\verb+\|+ and the previous meaning of the % char used shall be restored. % % One more difference between \pk{gmverb} and \pk{shortvrb} is that % the chars |\active|ated by |\MakeShortVerb|, behave as if they were % `other' in math mode, so you may type e.g., \verb+$k|n$+ to get % $k|n$ etc. % \stanza % % The \pk{gmutils}\gmdmarginpar{\pk{gmutils}} package provides a~couple of % macros similar to some basic \LaTeXpar\ ones, rather strictly % technical and (I~hope) tricky, such as |\afterfi|, |\ifnextcat|, % |\addtomacro| 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-expl3) \pk{xparse}'s % |\DeclareDocumentCommand|.\stanza % % The \gmdoc\ package uses a~lot of hyperlinking possibilities % provided by \pk{hyperref}\gmdmarginpar{\pk{hyperref}} which is therefore % probably the most important package required. The recommended % situation is that the user loads \pk{hyperref} package with \hisher\ % favourite options \emph{before} loading \pk{gmdoc}. % % If \heshe\ does not, \pk{gmdoc} shall load it with \emph{my} % favourite options. % % To avoid an error if a~(hyper)referenced label does not exist, % \pk{gmdoc} uses the \pk{gmiflink}\gmdmarginpar{\pk{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. % % \stanza % To typeset the index and the change history in balanced columns % \gmdoc\ uses the \gmdmarginpar{\pk{multicol}}\pk{multicol} package % that seems to be standard these days. % % Also the \gmdmarginpar{\pk{color}}\pk{multicol} package, required to % define the default colour of the hyperlinks, seems to be standard % already, and \pk{makeidx}. % % \subdivision[Automatic marking of definitions]{^^B % \gmhypertarget{Automatic marking of definitions}} % \gmdoc\ implements automatic detection of a~couple of % definitions. By default it detects all occurrences of the following % commands in the code: %\begin{enumerate}^^B %\item \label{def type} % |\def|, % |\newcount|, % |\newdimen|, % |\newskip|, % |\newif|, % |\newtoks|, % |\newbox|, % |\newread|,\\ % |\newwrite|, % |\newlength|, % |\newcommand›[*›]|, % |\renewcommand›[*›]|, % |\providecommand›[*›]|, % |\DeclareRobustCommand›[*›]|, % |\DeclareTextCommand›[*›]|,\\ % |\DeclareTextCommandDefault›[*›]|, % |\DeclareDocumentCommand|, % |\Decl⁄-are⁄-Com⁄-mand|\rrthis % % \item % |\newenvironment›[*›]|, % |\renewenvironment›[*›]|, % |\DeclareOption|, %^^A~ |%\DeclareDefining*\@namedef| % % \item \label{newctr} % |\newcounter|, % % \xdef\gmdenumi{\arabic{enumi}} % \end{enumerate} % % of the \pk{xkeyval} package: % \begin{enumerate}\setcounter{enumi}{\gmdenumi}^^B % \item\label{dk type} |\define@key|, % |\define@boolkey|, % |\define@choicekey|, % |\DeclareOptionX|, % % \xdef\gmdenumi{\arabic{enumi}} % \end{enumerate} % % and of the \pk{kvoptions} package: % \begin{enumerate}\setcounter{enumi}{\gmdenumi}^^B % \item \label{DSOption} % |\DeclareStringOption|, % |\DeclareBoolOption|, % |\DeclareComplementaryOption|,\\ % |\DeclareVoidOption|.\rrthis % \end{enumerate}\par % % 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 \ref*{newctr}--\ref*{DSOption} an % alternate index entries will be created: of the \CSs underlying those % definitions, e.g.\ |\newcounter{foo}| in the % code will result in indexing |foo| and |\c@foo|. % % If you want to add detection of a~defining command not listed above, % use the \TextUsage\DeclareDefining\ declaration. It comes in two % flavours: `saut\eacute' and with star. The `saut\eacute' 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 or not, is a~\CS. The starred version (without % the optional argument) declares a~defining 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 \TextUsage*{type}. Its default % value is |cs| and that is set in the `saut\eacute' 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| or |kvo|. % % |dk| stands for |\define@key| and is the type of \pk{xkeyval} % definitions of keys (group \ref{dk type} commands). When detected, % it scans further code for an optional \arg[KVprefix], mandatory % \arg{KVfamily} and mandatory \arg{key name}. The default \ % is |KV|, as in \pk{xkeyval}. % % |dox| stands for |\DeclareOptionX| and launches scanning for an % optional \arg[KV\-pre\-fix], optional |<|\|>| and mandatory % \arg{option name}. Here the default \ % is also |KV| and the default \ is the input file name. If % you want to set another default family (e.g.\ if the code of % \file{foo.sty} actually is in file \file{bar.dtx}), use % \TextUsage\DeclareDOXHead\arg{KVfamily}. This declaration has an % optional first argument that is the default \ for % |\DeclareOptionX| definitions. % % |kvo| stands for the \pk{kvoptions} package by Heiko Oberdiek. This % package provides a~handful of option defining commands (the group % \ref{DSOption} commands). Detection of such a~command launches % a~scan for mandatory \arg{option name} and alternate indexing of % a~\CS |\|\|@|\