% % \GetFileInfo{gmdoc.sty} % \title{The \pk{gmdoc.sty} Package\thfileinfo} % \author{Natror (Grzegorz Murzynowski)} % \date{\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 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. %% %% 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} % % %^^A \docstrip % \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{gmdoc} [2007/11/12 v0.99h a documenting package (GM)] % % % \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 very little adjustment, in some rather 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.) % % 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 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 six files and a~\acro{TDS}-compliant archive. % \begin{verse} % \pk{gmdoc.sty}\\ % \pk{gmdocc.cls}\\ % \pk{gmglo.ist}\\ % \pk{README}\\ % \pk{gmdocDoc.tex}\\ % \pk{gmdocDoc.pdf}\\ % \pk{gmdoc.tds.zip} % \end{verse} % % % \begin{gmlonely} % \subdivision{Compiling the Documentation} % % The last of the above files (the \pk{.pdf}, i.e., \emph{this % file}) is a~documentation compiled from the \pk{.sty} and % \pk{.cls} files by running \XeLaTeX\ on the \file{gmdocDoc.tex} % twice, then MakeIndex on the \file{gmdocDoc.idx} and % \file{gmdocDoc.glo} files, and then \XeLaTeX\ on \file{gmdocDoc.tex} % once more. (Using \LaTeX\ instead of \XeLaTeX\ should do, too.) % % MakeIndex shell commands: %\begin{verbatim} %makeindex -r gmdocDoc %makeindex -r -s gmglo.ist -o gmdocDoc.gls gmdocDoc.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{color.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 % 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}\\ % \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 Live2005 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 % authomatic 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 % hommage to it\footnote{As Grieg's Piano Concerto is a~hommage 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) % subsituting 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{|\|}|. % % Talking of declarations, I'll use the \textbf{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 the Source File} % % When \LaTeXpar\ with \pk{gmdoc.sty} package loaded typesets the % comment lines, the code delimiter is ommitted. 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 ommitted. % % 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*{^^B} sequence % that'll enter the (active) \ which shall gobble the line end. % ^^A~and the leading code delimiter of the next line---obsoleted by % ^^A~making % ignored in the commentary. % % 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 % is in \gmdoc\ active and defined to gobble the stuff between itself % and the next 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 (it 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 % 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 % \StraightEOL % queer\footnote{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 % \QueerEOL % \gmdoc's meaning of the line end. It 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). % % \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}|. % % (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{mac\-ro\-co\-de(*)} 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 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\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~filemarker 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 wish to include the driver file into your documentation, you % may write |\DocInput{\jobname.tex}|, but a~try of % |\DocInclude{\jobname}| would result with input stack overflow % caused by infinite |\input{|\|.aux}| recursion. % But there's \TextUsage\SelfInclude\ at your service that creates and % uses \pk{\.auxx} file instead of the usual % \pk{\.aux}. Its effect is analogous to the |\DocInclude|'s, but % \emph{the arguments it takes are totally different}: Since the % filename is known, there's no need to state it. The extension is % assumed to be \file{.tex}, but if it's different, you may state it in % the first and optional argument. The second argument is mandatory and % it's the stuff to be put at begin of file input, this one and no % else (with \TextCommonIndex\AtBegInputOnce|\AtBegInputOnce| hook). % For the example of usage see line \ref{SelfIncludeUsg} of % chapter~\ref*{Driver}. % % \stanza % % At the default settings, the |\Doc/SelfInclude|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 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 % succeding 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 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, \heshe\ is % provided the \TextUsage*{countalllines} option. ^^A( % {\LineNumFont 441}\,Then 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 initialized 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. % % \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 allright but not all the classes support marginpars. % That is the reason why this package enables marginparing 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 % documentclass. % % \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 % (OCSR). % % % \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|. % % 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. \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(*)|, % % \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|. % \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 uderlying 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 furher 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[KVprefix], 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 |\|\|@|\. The default \ is % the input file name. Again, if you want to set something else, you % are given the \TextUsage\DeclareKVOFam\arg{KVOfamily} that sets the % default family (and prefix: \|@|) for all the commands of % group \ref{DSOption}. % % Next key recognized by |\DeclareDefining| is \TextUsage*{star}. It % determines whether the 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 the |star| key is omitted. % % There are also \TextUsage*{KVpref} and \TextUsage*{KVfam} keys if % you want to redeclare the \pk{xkeyval} definitions with another % default prefix and family. % % For example, if you wish |\@namedef| to be detected (the original % \LaTeX\ version), declare % \[|\DeclareDefining*[star=false]\@namedef|\] or % \[|\DeclareDefining[type=text,star=false]\@namedef|\] (as stated % above, |*| is equivalent |[type=text]|). % % On the other hand, if you want some of the commands listed above % \emph{not} to be detected, write \TextUsage\HideDefining\ % in the commentary. Later % you can resume detection of it with % \TextUsage\ResumeDefining\. % % If you wish to turn entire detection mechanism off, write % \TextUsage\HideAllDefining\ in the narration layer. Then you can % resume detection with \TextUsage\ResumeAllDefining. % % The basic definition command, |\def|, seems to me a~bit % controversial. Definitely \emph{not always} it defines important % macros. But first of all, if you |\def| a~CS excluded from indexing (see % section \gmiflink{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, in the commentary before this |\def| write % \TextUsage\UnDef. That will turn off the detection just for this one % occurrence of |\def|. % % 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: % \TextUsage\HideDef. To resume detection of |\def| you are provided % also a~shorthand, \TextUsage\ResumeDef\ (but |\ResumeDefining\def| % also works). % % If you define things not with easily detectable commands, you can % mark them `manually', with the |\Define| declaration described in % the next section. % % % % \subdivision[Manual Marking the Macros and Environments]{^^B % \gmhypertarget{Manual Marking the Macros and Environments}} % % The concept (taken from \docfm ) is to index virtually all the % control sequences occurring in the code. \gmdoc\ does that by % default and needs no special command. (See below about exluding some % macros from being indexed.) % % The next concept (also taken from \docfm) is to ditinguish some % occurrences of some control sequences by putting such a~sequence % into a~marginpar and by special formatting 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' (in \docfm\ called `main'), with the reference 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.\,\pageref{indexoptions}). % % The macros and environments to be marked appear either in the code % or in the commentary. But all the definitions appear in the code, % I~suppose. Therefore the `def' marking macro is provided only for % the code case. So we have\gmhypertarget[textUsage]{} the % \TextUsage\Define, \TextUsage\CodeUsage\ and % \TextUsage\TextUsage\ commands. % % All three take one argument and all three may be starred. The % non-starred versions are intended to take a~control sequence as the % argument and the starred to take whatever (an % environment name or a~|^^A|-like and also a~CS). % % 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 \TextUsage\MakePrivateLetters\ 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 occurrence of their argument in the code. (By `scanned % occurrence' I~mean a~situation of the CS having 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 argument (which would never happen if the % argument is not a~CS). Therefore, if you want to mark a~definition % of an environment \env{foo}, you should put % \[|%\Define*{foo}|\] % right before the code line % \[|\newenvironment{foo}{%|\]^^A] % 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 dicourage 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~verbatim 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 and CSs, too. Currently, the most important difference % is that the unstarred version executes |\MakePrivateLetters| while % the starred does both |\MakePrivateLetters| and |\MakePrivateOthers| % before reading the argument. % % If you consider the marginpars a~sort of sub(sub\dots)section % marks, then you may wish to have a~command that makes a~marginpar of % the desired CS (or whatever) at the beginning of its description, % which may be fairly far from the first occurrence of its % object. Then you have the \TextUsage\Describe\ command which % puts its argument in a~marginpar and 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 \TextUsage\CodeMarginize\ % to declare what to put into a~marginpar in the \TeX\ code (it's % |\outer|) and % \TextUsage\TextMarginize\ to do so in the commentary. According to % 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 % \TextUsage\marginpartt. By default, this declaration is |\let| to % |\tt| but it may be advisable to choose a~condensed font if there is % any. Such a~choice is made by \pk{gmdocc.cls} if the Latin Modern % fonts are available: in this case \pk{gmdocc.cls} uses Latin Modern % Typewriter Light Condensed. % % If you need to put something in a~marginpar without making it typewriter % font, there's the \TextUsage\gmdmarginpar\ macro (that takes one % and mandatory argument) that only flushes its contents right. % % \stanza % 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 % \TextUsage\DefIndex\ and \TextUsage\CodeUsgIndex\ to 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 a~CS), 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 indexed 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 \TextUsage\CodeCommonIndex*\ % comes in rescue, 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 \TextUsage\TextUsgIndex\ and \TextUsage\TextCommonIndex\ % commands with % their starless versions for a~CS argument and the starred for all % kinds of the argument. % % \stanza % Moreover, as in \docfm, the \TextUsage*{macro} and % \TextUsage*{environment} environments are provided. Both take one % argument that should be a~CS for \env{macro} and `whatever' for % \env{environment}. Both add the |\MacroTopsep| glue before and after % their contents, and put their argument 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 \env{macro} commands the first scanned occurrence of % its argument to be indexed as `def' entry and \env{environment} % 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 a~CS 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 an % \env{environment} environment would look misguidedly ugly, there's % the \env{macro*} environment which \TeX nically is just an alias for % \env{environment}. % % (To be honest, if you give a~\env{macro} environment a~non-CS % argument, it will accept it and then it'll work as % \env{evironment}.) % % % \subdivision[Index Ex/Inclusions]{\gmhypertarget{Index Ex/Inclusions}} % % It's\label{IEIDeclarations} understandable\footnote{After reading ^^B( % \docfm's documentation ;-)\,.} that you don't % want some control sequences to be indexed in your documentation. The % \docfm\ package gives a~brilliant solution: the % \TextUsage\DoNotIndex\ declaration. So do I % (although here, \TeX nically it's done another % way). It OCSR. 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 in % \docfm , 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 |\DoNotIndex|es as you wish (about half as many as % many CSs may be declared, because for each CS excluded from indexing % a~special CS is declared that stores the ban sentence). % Excluding the same CS more 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). Therefore \pk{gmdoc} excludes % some 300 CSs 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 \TextUsage\DoIndex\ % declaration (OCSR) that removes a~ban on all the CSs given in the % argument, e.g., % \[|\DoIndex{\par \@@par \endgraf}|\] % % Moreover, you are provided the \TextUsage\DefaultIndexExclusions\ % and \Describe\UndoDefaultIndexExclusions^^A % \cs{Un\-do\-Def\-ault\-Ind\-ex\-Ex\-cl\-us\-ions} declarations that % act according to their names. You may use them in any configuration % with the |indexallmacros| option. Both of these declarations OCSR. % % % \subdivision{The \ds\ Directives} % % \gmdoc\ typesets the \ds\ directives and it does it quite likely as % \docfm, i.e., with math sans serif font. It does it automatically % whether you use the traditional settings or the new. % % Advised by my \TeX\ Guru, I~didn't implement the module nesting % recognition (MW told it's not that important.) % % So far \gmhypertarget{verbatim mode directive} is only % half-handled. That is, a~line beginning with |%<||<|\ will be % typeset as a~\ds\ directive, but ^^A~The magical directive divided % ^^A due to the doctex mode who saw it and coloured all after with % ^^A~salmon. % the closing line |%|\ will be not. It doesn't seem to be % hard to implement, if I~only receive some message it's really useful % for someone. % %^^A If you use the \TextUsage*{macrocode} environment, you don't have to %^^A add any CS to get \ds\ directive typeset properly: within %^^A \env{macrocode} a~|<| sign in a~line commented out is read as %^^A a~beginning of a~\ds\ directive, which means that \TeX\ looks %^^A for the closing |>| or the very next |<| as the beginning of the %^^A special directive |<<|\. In the %^^A standard case of |<|\|>| \TeX\ typesets any further text %^^A in its line as the code. %^^A %^^A If you want the \ds\ directives to be typeset without %^^A \env{macrocode}, you shoud declare \TextUsage\docstrips\ to make %^^A \TeX\ read the |<| in the comment layer as the beginning of %^^A a~\ds\ directive. In |\docstrips|'s scope the |<| signs %^^A occurring in math mode remain just inequality signs. %^^A %^^A If you wish only the first |<| met to start a~\ds\ directive %^^A typesetting, then there's \TextUsage\docstrip\ declaration that %^^A restores the previous meaning of |<| after the first using it as %^^A a~\ds\ directive opener. %^^A %^^A Both |\docstrips| and |\docstrip| OCSR and, of course you may use %^^A them as environments (which doesn't make much sense with the %^^A latter, though). %^^A % % \subdivision{The Changes History} % % The \docfm's documentation reads: % \begin{quotation} % To maintain a change history within the file, the |\changes| command may % be placed amongst the description part of the changed code. It takes three % arguments, thus: % \[|\changes{|\|}{|\|}{|\|}|\] % % The changes may be used to produce an auxiliary file (\LaTeX's % |\glossary| mechanism is used for this) which may be printed after % suitable formatting. The |\changes| [command] encloses the \ in % parentheses and appends the \ to form the printed entry in % such a change history [\dots\ obsolete remark ommitted]. % % To cause the change information to be written out, include % \TextUsage\RecordChanges\ in the driver['s preamble or just in the % source file (\pk{gmdocc.cls} does it for you)]. To read in and print % the sorted change history (in two % columns), just put the \TextUsage\PrintChanges\ command as the last % (commented-out, and thus executed during the documentation pass % through the file) command in your package file [or in the driver]. % Alternatively, this command may form one of the arguments of the % |\StopEventually| command, although a change history is probably not % required if only the description is being printed. The command % assumes that MakeIndex or some other program has processed the % \pk{.glo} file to generate a~sorted \pk{.gls} file. You need % a~special MakeIndex style file; a suitable one is supplied with % \docfm\ [and \gmdoc], called \iffalse\pk{gglo.ist}\fi^^A % [\dots\ \textbf{\pk{gmglo.ist}} for \gmdoc]. The \TextUsage\GlossaryMin, % \TextUsage\GlossaryPrologue\ and \TextUsage\GlossaryParms\ macros are % analagous to the |\Index...| versions [see % sec.~\gmiflink[IndexParams]{The Parameters} % p.\,\pageref*{IndexParams}]. (The \LaTeX\ `glossary' % mechanism is used for the change entries.) % \end{quotation} % % In \gmdoc\ (unless you turn definitions detection off), you can put % |\changes| after the line of definition of a~command to set the % default argument of |\changes| to that command. For example, %\begin{verbatim} % \newcommand*\dodecaphonic{...} % % \changes{v0.99e}{2007/04/29}{renamed from \cs{DodecaPhonic}} %\end{verbatim} % results with a~history (sub)entry: % \deksmallskip % v0.99e\par\hspace*{\parindent} (\dots)\par \hspace*{\parindent} % \cs{dodecaphonic}: \par\hspace*{2\parindent} renamed from % \cs{DodecaPhonic}, \textit{\arabic{page}} % \deksmallskip % % Such a~setting is in force till the next definition and % \emph{every} detected definition resets it. % % In \gmdoc\ |\changes| is |\outer|. % % \stanza % As mentioned in the introduction, the glossary, the changes history % that is, uses a~special MakeIndex style, \pk{gmglo.ist}. This style % declares another set of the control chars but you don't have to % worry: |\changes| takes care of setting them properly. To be % precise, |\changes| executes \TextUsage\MakeGlossaryControls\ that % is defined as % \begin{verbatim} % \def\actualchar{=} \def\quotechar{!}% % \def\levelchar{>} \edef\encapchar{\xiiclub} %\end{verbatim} % % Only if you % want to add a~control character yourself in a~changes entry, to quote % some char, that is (using level or encapsulation chars is not % recommended since |\changes| uses them itself), use rather % |\quotechar|. % % \stanza % Before writing an entry to the \pk{.glo} file, |\changes| % checks if the date (the second mandatory\equals the third argument) % is later than the date stored in the counter % \TextUsage*{ChangesStartDate}. You may set this counter with a % \Describe\ChangesStart^^B % \[|\ChangesStart{|\|}{|\|/|\|/|\|}|\] % declaration. % % If the \env{ChangesStartDate} is set to a~date contemporary to \TeX\ % i.e., not earlier than September 1982\footnote{DEK in \textit{\TeX\ ^^B % The Program} mentions that month as of \TeX\ Version 0 release.}, % then a~note shall appear at the beginning of the changes history % that informs the reader of ommitting the earlier changes entries. % % If the date stored in \env{ChangesStartDate} is earlier than \TeX, % no notification of ommitting shall be printed. This is intended for % a~rather tricky usage of the changes start date feature: you may % establish two threads of the changes history: the one for the users, % dated with four digit year, and the other for yourself only, dated % with two or three digit year. If you declare % \[|\ChangesStart{|\|}{1000/00/00}|\] % or so, the changes entries dated with less-than-four digit year % shall be ommitted and no notification shall be issued of that. % % \stanza % % While scanning the CSs in the code, \gmdoc\ counts them and prints % the information about their number on the terminal and in % \pk{.log}. Moreover, you may declare % \TextUsage\CheckSum|{|\|}| before the code and \TeX\ will % inform you whether the number stated by you is % correct or not, and what it is. As you guess, it's not my original idea % but I~took it from \docfm. % % There it is provided as a~tool for % testing whether the file is corrupted. % My \TeX\ Guru says it's a~bit old-fashioned nowadays but I~like the % idea and use it to document the file's growth. For this purpose % \gmdoc\ types out lines like % \begin{verbatim} %% \chschange{v0.98j}{2006/10/19}{4372} %% \chschange{v0.98j}{06/10/19}{4372} %\end{verbatim} % and you may place them at the beginning of the source file. Such % a~line results in setting the check sum to the number contained in % the last pair of braces and in making a~`general' changes entry that % states the check sum for version \ dated \ was \. % % \subdivision{The Parameters} % % The \pk{gmdoc} package provides some parameters specific to % typesetting the \TeX\ code: % % \stanza % \TextUsage\stanzaskip\ is a~vertical space inserted when a~blank % (code) line is met. It's equal |0.75\medskipamount| by default % (with the \emph{entire} |\medskipamount|'s stretch- and % shrinkability). Subsequent blank code lines do not increase this % space. % % At the points where narration begins a~new line after the code or an % inline comment and where a~new code line begins after the narration % (that is not an inline comment), a~\TextUsage\CodeTopsep\ glue is % added. At the beginning and the end of a~\env{macro} or % \env{environment} environment a~|\MacroTopsep| glue is added. By % default, these two skips are set equal |\stanzaskip|. % % The |\stanzaskip|'s value is assigned also to the display skips and % to |\topsep|. This is done with the \TextUsage\UniformSkips\ % declaration executed by default. If you want to change some of those % values, you should declare \TextUsage\NonUniformSkips\ in the % preamble to discard the default declaration. (To be more precise, by % default |\UniformSkips| is executed twice: when loading \gmdoc\ and % again |\AtBeginDocument| to allow you to change |\stanzaskip| and % have the other glues set due to it. |\NonUniformSkips| relaxes the % |\UniformSkips|'s occurrence at |\begin{document}|.) % % If you want to add a~vertical space of |\CodeTopsep| (equal by % default |\stanzaskip|), you are provided the \TextUsage\stanza\ % command. Similarly, if you want to add a~vertical space of the % |\MacroTopsep| amount (by default also equal |\stanzaskip|), you are % given the \TextUsage\chunkskip\ command. They both act analogously % to |\addvspace| i.e., don't add two consecutive glues but put the % bigger of them. % % Since |\CodeTopsep| glue is inserted automatically at each % transition from the code (or code with an inline comment) to the % narration and reverse, it may happen that you want not to add such % a~glue exceptionally. Then there's the \TextUsage\nostanza\ % command. % % \stanza % The \TeX\ code is indented with the \TextUsage\CodeIndent\ glue % and a~leading space increases indentation of the line by its % (space's) width. The default value of |\CodeIndent| is 1.5\,em. % % There's also a~parameter for the indent of the narration, % \TextUsage\TextIndent, but you should use it only in emergency % (otherwise what would be the margins for?). It's 0\,sp by default. % % \stanza % By default, typesetting a~|\DocInput/Include|d file is ended with % a~codeline containing the text `\EOFMark' given by the % \TextUsage\EOFMark\ macro. If you don't like such an ending, you % should end the source file with the \TextUsage\NoEOF\ macro in % a~comment, i.e., % \[|%|\|\NoEOF|\] % This macro redefines |\EOFMark| and suppresses the End % Of File token to close the input properly. It also has the % |\endinput| effect so you may put some text you don't want to % document after it. % % \stanza % % The crucial concept of \gmdoc\ is to use the line end character % as a~verbatim group opener and the comment char, usually the |%|, as % its delimiter. Therefore the `knowledge' what char starts % a~commentary is for this package crucial and utterly % important. The default assumption is that you use |%| as we % all do. So, if you use another character, then you should declare it % with \TextUsage\CodeDelim\ typing the desired char % preceded by a~backslash, e.g., |\CodeDelim\&|\,. (As just % mentioned implicitly, \possfil|\CodeDelim\%| is declared by % deafult.) % % This declaration is always global so when- and wherever you change % your mind you should express it with a~new |\CodeDelim| % declaration. % % The starred version of |\CodeDelim| changes also the verb % `hyphen', the char appearing at the verbatim line breaks that is. % % \stanza % Talking of special chars, the escape char, |\| by default, is also % very important for this package as it marks control sequences and % allows automatic indexing them for instance. Therefore, if you for % any reason choose another than |\| character to be the escape char, % you should tell \pk{gmdoc} about it with the % \TextUsage\CodeEscapeChar\ declaration. As the previous one, this too % takes its argument preceded by a~backslash, % e.g., |\CodeEscapeChar\!|. (As you may deduct from the above, % |\CodeEscapeChar\\| is declared by default.) % % The tradition is that in the packages |@| char is a~letter % i.e., of catcode \catletter. Frank Mittelbach in \docfm\ takes into account % a~possibility that a~user wishes some other chars to be letters, % too, and therefore he (F.M.) provides the % \TextUsage\MakePrivateLetters\ macro. % So do I~and like in \docfm, this macro makes |@| sign a~letter. It % also makes |*| a~letter in order to cover the starred versions % of commands. % % Analogously but for a~slightly different purpose, the % \TextUsage\AddtoPrivateOthers\ macro is provided here. It adds its % argument, which is supposed to be a~one-char CS, to the % |\doprivateothers| list, whose r\ocircum le is to allow some special chars % to appear in the marking commands' arguments (the commands described % in section \gmiflink{Macros for Marking the Macros}). The default % contents of this list is | | (the space) and |^| so you may mark the % environments names and special sequences like |^^A| safely. This % list is also extended with every char that is |\MakeShortVerb|ed. % (I~don't see a~need of removing chars from this list, but if % you do, please let me know.) % % \stanza % The line numbers (if enabled) are typeset in the % \TextUsage\LineNumFont\ declaration's scope, which % is defined as |{\normalfont\tiny}| by default. Let us also remember, that for % each counter there is a~|\the|\ macro available. The % counter for the line numbers is called \TextUsage*{codelinenum} so % the macro printing it is |\thecodelinenum|. By default we don't % change its \LaTeX's definition which is equivalent % |\arabic{codelinenum}|. % % % Three more parameter macros, are \TextUsage\IndexPrefix, % \TextUsage\EntryPrefix\ and \TextUsage\HLPrefix. All three are % provided with the account of including multiple files in one % document. % They are equal (almost) |\@empty| by default. The first may store % main level index entry of which all indexed macros and environments % would be subentries, e.g., the name of the package. The third may or % even should store a~text to distinguish equal codeline numbers of % distinct source files. It may be the file name too, of course. The % second macro is intended for another concept, namely the one from % \pk{ltxdoc} class, to distinguish the codeline numbers from % different files \emph{in the index} by the file marker. Anyway, if % you document just one file per document, there's no need of % redefining those macros, nor when you input multiple files with % |\DocInclude|. % % \pk{gmdoc} automatically indexes the control sequences % occurring in the code. Their index entries may be `common' or % distinguished in two (more) ways. The concept is to distinguish the % entries indicating the \emph{usage} of the CS and the entries % indicating the \emph{definition} of the CS. % % The special formattings of `usage' and `def' index entries are % determined by \TextUsage\UsgEntry\ and \TextUsage\DefEntry\ % one-parameter macros (the parameter shall be substituted with the % reference number) and by default are defined as |\textit| and % |\underline| respectively (as in \docfm). % % There's one more parameter macro, \TextUsage\CommonEntryCmd\ that % stores the name of the encapsulation for the `common' index % entries (not special) i.e., a~word that'll become a~CS that will % be put before an entry in the \file{.ind} file. By default it's defined % as |{relax}| and a~nontrivial use of it you may see in line % \ref{UsgHack} of the driver file of this documentation, where it % makes all the index entries of the driver's code are formatted as `usage'. % % \stanza % ^^A~Index Parameters % \gmhypertarget[IndexParams]{The index} comes in a~\env{multicols} % environment whose columns number is determined by the % \TextUsage*{IndexColumns} counter set by default to~3. To save space, % the index begins at the same page as the previous text provided % there is at least \TextUsage\IndexMin\ of the page height free. By % default, |\IndexMin|\equals\the\IndexMin. % % The text put at the beginning of the index is declared with % a~one-argument \TextUsage\IndexPrologue. Its default text at current % index option you may \gmiflink[DIPrologue]{admire} on page % \pageref*{DIPrologue}.^^A % \AtDIPrologue{\raisebox{4cm}[0sp][0sp]{\gmhypertarget[DIPrologue]}} % Of course, % you may write your own |\IndexPrologue{|\|}|, but if you like the default and want only to add % something to it, you are provided \TextUsage\AtDIPrologue\ % one-argument declaration that adds the stuff after the default % text. For instance, I~used it to add a~label and hypertarget that is % referred to two sentences earlier. % % By default the colour of the index entry hyperlinks is set black to % let Adobe Reader work faster. If you don't want this, % \Describe\IndexLinksBlack|\let\IndexLinksBlack\relax|. That leaves % the index links colour alone and hides % the text about black links from the default index prologue. % % Other index parameters are set with the \TextUsage\IndexParms\ macro % defined in line \gmifref[IndexParms]{sixty-odd} of the code. If you % want to change some of them, you don't have to use % |\renewcommand*\IndexParms| and set all of the parameters: you may % \Describe\gaddtomacro^^A % |\gaddtomacro\IndexParms{|\|}|. % (|\gaddtomacro| is an alias for \LaTeX's |\g@addto@macro| provided % by \pk{gmutils}.) % % At the default \gmdoc\ settings the \file{.idx} file is prepared for % the default settings of MakeIndex (no special style). Therefore the % index control chars are as usual. But if you need to use other % chars as MakeIndex controls, know that they are stored in the four % macros: \TextUsage\actualchar, \TextUsage\quotechar, % \TextUsage\levelchar\ and \TextUsage\encapchar\ whose meaning you % infer from their names. Any redefinition of them \emph{should be ^^B % done in the preamble} because the first usage of them takes place at % |\begin{document}| and on it depends further tests telling \TeX\ % what characters of a~scanned CS name it should quote before % writing it to the \pk{.idx} file. % % \stanza % Frank Mittelbach in \docfm\ provides the |\verbatimchar| macro to % (re)define the |\verb|'s delimiter for the index entries of the % scanned CS names etc. \gmdoc\ also uses \TextUsage\verbatimchar\ but % defines it as |{&}|. Moreover, a~macro that wraps a~CS name in |\verb| % checks whether the wrapped CS isn't |\&| and if it is, |$| is taken % as the delimiter. So there's hardly chance that you'll need to % redefine |\verbatimchar|. % % So strange delimiters are chosen deliberately to allow any `other' % chars in the environments names. % % \stanza % There's a~quadratus of commands taken from \docfm: % \TextUsage\StopEventually, \TextUsage\Finale,\\ % \TextUsage\AlsoImplementation\ and \TextUsage\OnlyDescription\ that % should be % explained simultaneously (in a~polyphonic song % e.g.). % % The |\OnlyDescription| and |\AlsoImplementation| % declarations are intended to exclude or include the code part from % the documentation. The point between the description and the % implementation part should be marked with |\StopEventually{|\|}| and |\Finale| should be typed % at the end of file. Then |\OnlyDescription| defines % |\StopEventually| to expand to its argument followed by |\endinput| % and\\ |\AlsoImplementation| defines |\StopEventually| to do nothing % but pass its argument to |\Finale|. % % % \subdivision{The Narration Macros} % % To print the control sequences' names you have the \TextUsage\verb\ macro and % its `shortverb' version whatever you define (see the \pk{gmverb} % package). % % For short verbatim texts in the inline comments \pk{gmdoc} provides % the \TextUsage\inverb\\dots\ (the name stands for % `inline verbatim') command that redefines the \pk{gmverb} breakables % to break with |%| at the beginning of the % lower line to avoid mistaking such a~broken verbatim commentary text % for the code. % % But nor |\verb(*)| neither |\inverb| will work if % you put them in an argument of another macro. For such a~situation, % or if you just prefer, \gmdoc\ (\pk{gmutils}) provides a~robust command % \TextUsage\cs, which takes one obligatory argument, the macro's name % without the backslash, e.g., |\cs{mymacro}| produces % \cs{mymacro}. I~take account of a~need of printing some other text % verbatim, too, and therefore |\cs| has the first argument % optional, which is the text to be typeset before the mandatory % argument. It's the backslash by default, but if you wish to typeset % something without the |\|, you may write {\verbeolOK |\cs[]{not % a~macro}|}. Moreover, for typesetting the environments' names, % \gmdoc\ (\pk{gmutils}) % provides the \TextUsage\env\ macro, that prints its argument % verbatim and without a~backslash, e.g., |\env{an environment}| % produces \env{an environment}. % % And for line breaking at |\cs| and |\env| there is % \TextUsage\nlpercent\ to ensure |%| if the line breaks at the % beginning of a~|\cs| or |\env| and \TextUsage\+ to use inside their % argument for a~discretionary hyphen that'll break to - at the end of % the upper line and |%| at the beginning of the lower line. By % default hyphenation of |\cs| and |\env| arguments is off, you can % allow it only at |\-| or |\+|. % % \stanza % To print packages' names sans serif there is a~\TextUsage\pk\ % one-argument command, and the \TextUsage\file\ command intended for % the filenames. % % Because we play a~lot with the |\catcode|s here and want to talk % about it, there are \TextUsage\catletter, \TextUsage\catother\ and % \TextUsage\catactive\ macros that print \catletter, \catother\ and % \catactive\ respectively to concisely mark the most used char % categories. % % I~wish my self-documenting code to be able to be typeset each % package separately or several in one document. Therefore I~need some % `flexible' sectioning commands and here they are: % \TextUsage\division, \TextUsage\subdivision\ and % \TextUsage\subsubdivision\ so far, that by default are |\let| to be % |\section|, |\subsection| and |\subsubsection| respectively. % % \stanza % One more kind of flexibility is to allow using \pk{mwcls} or the % standard classes for the same file. There was a~trouble with the % number and order of the optional arguments of the original % \pk{mwcls}'s sectioning commands. % % It's resolved in \pk{gmutils} so you are free at this point, and % even more free than in the standard classes: if you give % a~sectioning command just one optional argument, it will be the % title to toc and to the running head (that's standard in % scls\footnote{See \pk{gmutils} for some subtle details.}). If you give % \emph{two} optionals, the first will go to the running head and the % other to toc. (In both cases the mandatory argument goes only to the % page). % % \stanza % If you wish the |\DocInclude|d files make other sectionings than the % default, you may declare \TextUsage\SetFileDiv|{|\|}|. % % \stanza % % \pk{gmdoc.sty} provides also an environment \TextUsage*{gmlonely} % to wrap some text you think you may want to skip some day. When % that day comes, you write \TextUsage\skipgmlonely\ before the % instances of \env{gmlonely} you want to skip. This declaration has % an optional argument which is for a~text that'll appear in(stead of) the % first \env{gmlonely}'s instance in every |\DocInput| or % |\DocInclude|d file within |\skipgmlonely|'s scope. % % An example of use you may see in this documentation: the repeated % passages about the installation and compiling the documentation are % skipped in further chapters thanks to it. % % \stanza % \gmdoc\ (\pk{gmutils}, to be precise) provides some \TeX-related % logos:\\ % \Describe\AmSTeX typesets \AmSTeX,\\ % \Describe\BibTeX\BibTeX,\\ % \Describe\SliTeX\SliTeX,\\ % \Describe\PlainTeX\PlainTeX,\\ % \Describe\Web\Web,\\ % \Describe\TeXbook\TeXbook,\par^^A~without par there raised error % ^^A `too many unprocessed floats'. % \noindent\Describe\TB\TB\par % \noindent\Describe\eTeX\eTeX,\\ % \Describe\pdfeTeX\pdfeTeX\\ % \Describe\pdfTeX\pdfTeX\\ % \Describe\XeTeX\XeTeX\ (the first |E| will be reversed if the % \pk{graphics} package is loaded or \XeTeX\ is at work) and\\ % \Describe\LaTeXpar\LaTeXpar.\par % % \noindent\Describe\ds\ds\ not quite a~logo, but still convenient. % % \stanza % The \TextUsage*{copyrnote} environment is provided to format the % copyright note flush left in |\obeylines|' scope. % % \stanza % % To put an arbitrary text into a~marginpar and have it flushed right % just like the macros' names, you are provided the % \TextUsage\gmdmarginpar\ macro that takes one mandatory argument % which is the contents of the marginpar. % % \stanza % To make a~vertical space to separate some piece of text you are % given two macros: \TextUsage\stanza\ and \TextUsage\chunkskip. The % first adds |\stanzaskip| while the latter |\MacroTopsep|. Both of % them take care of not cumulating the vspaces. % % %\stanza % The \TextUsage*{quotation} environment is redefined just to enclose % its contents in double quotes. % \stanza % % The \TextUsage\GetFileInfo|{|\|}| command % defines \TextUsage\filedate, \Describe\fileversion\cs{fil\-e\-vers\-ion} and % \TextUsage\fileinfo\ as the respective pieces of the info (the % optional argument) provided % by \cs{Pro\-vid\-es\-Class/Pack\-age/Fi\-le} declarations. The % information of the file you process with \gmdoc\ % is provided (and therefore getable) if the file is also loaded (or % the |\Provide...| line occurs in a~|\StraightEOL| scope). % % If the input file doesn't contain |\Provides...| in the code layer, % there are commands \TextUsage\ProvideFileInfo|{|\|}[|\|]| and % \TextUsage\ProvideSelfInfo|[|\|]|. (\ should consist of: % \|/|\|/|\| |\| |\.) % % A~macro for the standard note is provided, \TextUsage\filenote, that % expands to ``This file has version number \ dated % \.'' To place such a~note in the document's title (or heading, % with |\DocInclude| at the default settings), there's % \TextUsage\thfileinfo\ macro that puts |\fileinfo| in |\thanks|. % % \stanza % Since |\noindent| didn't want to cooperate with my code and % narration layers sometimes, I~provide \TextUsage\gmdnoindent\ that % forces a~not indented paragraph if |\noindent| could not. % % \stanza % If you declare the code delimiter other than |%| and then want |%| % back, you may write \TextUsage\CDPerc\ instead of |\CodeDelim*\%|. % % If you like |&| as the code delimiter (as I~did twice), you may write % \TextUsage\CDAnd\ instead of |\CodeDelim\&|. % % %^^A \stanza %^^A For an example driver file see chapter \gmiflink{The Driver}. % % % \subdivision{A~Queerness of \cs{label}} % % You should be loyally informed that |\label| in \gmdoc\ % behaves slightly % non-standard in the \cs{Doc\-In\-put/\:Inc\-lud\-e}d files: % the automatic redefinitions of |\ref| at each code line % are \emph{global} (since the code is typeset in groups and the % |\ref|s will be out of those groups), so % a~|\ref|erence in the narrative will point at the last code line not % the last section, \emph{unlike} in the standard \LaTeX. % % % \subdivision{\docfm-Compatibility} % % One of my goals while writing \gmdoc\ was to make compilation of % \docfm-like files with \gmdoc\ possible. I~cannot guarantee the goal % has been reached but I~\emph{did} compile \pk{doc.dtx} with not % a~smallest change of that file (actually, there was a~tiny little buggie in % line 3299 which I~fixed remotely with |\AfterMacrocode| tool written % specially for that). So, % if you wish to compile a~\docfm-like file with my humble package, % just try. % % The \docfm\ commands most important in my opinion are supported by % \gmdoc. Some commands, mostly the obsolete in my opinion, are not % supported but give an info on the terminal and in \pk{.log}. % % I~assume that if one wishes to use \docfm's interface then \heshe\ % won't use \gmdoc's options but just the default. (Some \gmdoc\ % options may interfere with some \docfm\ commands, they may cancel % them e.g.) % % \stanza % The main input commands compatible with \docfm\ are % \TextUsage\OldDocInput\ and \TextUsage\DocInclude, the latter % however only in the \TextUsage\olddocIncludes\ declaration's scope. % % Within their scope/argument the \TextUsage*{macrocode} environments % behave as in \docfm, i.e.\ they are a~kind of verbatim and require to be % ended with |% \end{macrocode(*)}|. % % The default behaviour of \env{macrocode(*)} with the `new' input % commands is different however. Remember that in the `new' fashion the code % and narration layers philosophy is in force and that is sustained % within \env{macrocode(*)}. Which means basically that with `new' % settings when you write %\begin{verbatim} %% \begin{macrocode} % \alittlemacro % change it to \blaargh %%\end{macrocode} %\end{verbatim} % and |\blaargh|'s definition is |{foo}|, you'll get %\[|\alittlemacro %| change it to foo\] % (Note that `my' \env{macrocode} doesn't require % the magical |% \end|.) % % If you are used to the traditional (\docfm's) \env{macrocode} and still wish to % use \gmdoc\ new way, you have at least two options: there is the % \TextUsage*{oldmc} environment analogous to the traditional (\docfm's) % \env{macrocode} (it also has the starred version), that's the first % option (I~needed the traditional behaviour once in this % documentation, find out where \& why). The other is to write % \TextUsage\VerbMacrocodes. That declaration (OCSR) redefines % \env{macrocode} and \env{macrocode*} to behave the traditional way. % (It's always executed by |\OldDocInput| and |\olddocIncludes|.) % % \stanza % For a~more detailed discussion of what is \docfm-compatible and how, % see the code section \gmiflink[doccompa]{\docfm-Compatibiliy}. % % \StopEventually{\NoEOF} % % % \division{The Code} % % For debug \catcode`\^^C=9\relax % we set the |\catcode| of this char to \catactive\ in the comment % layer. % \catcode`\^^C\active % % \changes[^^C]{v0.98g}{06/10/10}{recatcoded for debug: in the working % pass it's made ignored and in the documenting pass it's made active} % % % \DoIndex{\par \@@par} % % The basic idea of this package is to re|\catcode| |^^M| (the line % end char) and |%| (or any other comment char) so that they start and % finish typesetting of what's between them as the \TeX\ code i.e., % verbatim and with the bells and whistles. % % The bells and whistles are (optional) numbering of the codelines, % and automatic indexing the CSs, possibly with % special format for the `def' and `usage' entries. % % As mentioned in the preface, this package aims at a~minimal markup % of the working code. A~package author writes \hisher\ splendid code % and adds a~brilliant comment in |%|ed lines and that's all. Of % course, if \heshe\ wants tomake a~|\section| or |\emph|asise, % \heshe\ has to type respective CSs. % % I~see the feature described above to be quite a~convenience, % however it has some price. See section % \gmiflink[afc]{Life Among Queer EOLs} for details, % here I~state only that in my opinion the price is not very high. % \stanza % % More detailedly, the idea is to make |^^M| (end of line char) active % and to define it to check if the next char i.e., the beginnig of the % next line is a~|%| and if so % to gobble it and just continue usual typesetting or else to start % a~verbatim scope. In fact, every such a~line end starts a~verbatim % scope which is immediately closed, if the next line begins with % (leading spaces and) the code delimiter. % % Further details are typographical parameters of verbatim scope and % how to restore normal settings after such a~scope so that a~code % line could be commented and still displayed, how to deal with % leading spaces, how to allow breaking a~moving argument in two lines % in the comment layer, how to index and marginpar macros etc. % % %\subdivision{The Package Options} % \RequirePackage{xkeyval}% we need key-vals later, but maybe we'll make % the option key-val as well. % % Maybe someone wants the code lines not to be numbered. \newif\if@linesnotnum \DeclareOption{linesnotnum}{\@linesnotnumtrue} % And maybe he or she wishes to declare resetting the line counter % along with some sectioning counter him/herself. \newif\if@uresetlinecount \DeclareOption{uresetlinecount}{\@uresetlinecounttrue} % And let the user be given a~possibility to count the comment % lines. \newif\if@countalllines \DeclareOption{countalllines}{\@countalllinestrue} % Unlike in \docfm , indexing the macros is the default and the % default reference is the code line number. \newif\if@noindex \DeclareOption{noindex}{\@noindextrue} \newif\if@pageindex \DeclareOption{pageindex}{\@pageindextrue} % It would be a~great honour to me if someone would like to document % \LaTeX\ source with this humble package but I~don't think it's % really probable so let's make an option that'll switch index exclude % list properly (see sec.\ \gmiflink{Index Exclude List}). \newif\if@indexallmacros \DeclareOption{indexallmacros}{\@indexallmacrostrue} % Some document classes don't support marginpars or disable them by % default (as my favourite Marcin Woli\nacute ski's classes). % % \changes{v0.98e}{06/09/23}{wrapped in \cs{@ifundefined} (a~bug fix: % before the bare \cs{newif} falsified the \cs{if@marginparsused} % switch when it had been defined and set True by the \pk{mwart} % class.)} \@ifundefined{if@marginparsused}{\newif\if@marginparsused}{} % This switch is copied from \pk{mwbk.cls} for compatibility with % it. Thanks to it loading an \pk{mwcls} with |[withmarginpar]| option % shall switch marginpars on in this package, too. % % To be compatible with the standard classes, let's |\let|: \@ifclassloaded{article}{\@marginparsusedtrue}{} %\label{mparclause1} \@ifclassloaded{report}{\@marginparsusedtrue}{} \@ifclassloaded{book}{\@marginparsusedtrue}{} % \label{mparclause2} And if you don't use \pk{mwcls} nor standard % classes, then you have the options:\Define*{withmarginpar} \DeclareOption{withmarginpar}{\@marginparsusedtrue} \DeclareOption{nomarginpar}{\@marginparsusedfalse} % The order of the above conditional switches and options is significant. % Thanks to it the options are available also in the % standard classes and in \pk{mwcls}. % % \stanza % To make the code spaces blank (they are visible by default except % the leading ones). \newif\if@codespacesblank \DeclareOption{codespacesblank}{\@codespacesblanktrue} \ProcessOptions % \subdivision{The Dependencies and Preliminaries} % % We require another package of mine that provides some tricky macros % analogous to the \LaTeX\ standard ones, such as |\newgif| and % |\@ifnextcat|. \RequirePackage{gmutils}[2007/11/09] % A~standard package for defining colours, \RequirePackage{color} % and a~colour definition for the hyperlinks not to be too bright \definecolor{deepblue}{rgb}{0,0,.85} % And the standard package probably most important for \gmdoc: % If the user doesn't load \pk{hyperref} with \hisher\ favourite % options, we do, with \emph{ours}. If \heshe\ has % done it, we change only the links' colour. % % \changes[hyperref]{v0.97}{06/09/04}{linkcolor made deep blue} % \changes[hyperref]{v0.99g}{2007/10/30}{added bypass of encoding for loading % \pk{url}} \@ifXeTeX{\XeTeXdefaultencoding "cp1250"}{} \@ifpackageloaded{hyperref}{\hypersetup{colorlinks=true, linkcolor=deepblue, urlcolor=blue, filecolor=blue}}{% \RequirePackage[colorlinks=true, linkcolor=deepblue, urlcolor=blue, filecolor=blue, pdfstartview=FitH, pdfview=FitBH, \@ifXeTeX{xetex,}{} pdfpagemode=UseNone]{hyperref}} \@ifXeTeX{\XeTeXdefaultencoding "utf-8"}{} % Now a~little addition to \pk{hyperref}, a~conditional hyperlinking % possibility with the |\gmhypertarget| and |\gmiflink| macros. It % \emph{has} to be loaded \emph{after} \pk{hyperref}. \RequirePackage{gmiflink} % And a~slight redefinition of \env{verbatim}, |\verb(*)| and % providing of |\MakeShortVerb(*)|. \RequirePackage{gmverb}[2007/11/09] \if@noindex \AtBeginDocument{\gag@index}% for the latter macro see line % \ref{gag@index}. \else \RequirePackage{makeidx}\makeindex \fi % Now, a~crucial statement about the code delimiter in the input file. % Providing a~special declaration for the assignment is intended for % documenting the packages that play with |%|'s % |\catcode|. Some macros for such plays are defined % \gmiflink[CDAnd]{further}. % % The declaration comes in the starred and unstarred version. The % unstarred version besides declaring the code delimiter declares % the same char as the verb(atim) `hyphen'. The starred version % doesn't change the verb 'hyphen'. That is intended for the special % tricks e.g.\ for the \env{oldmc} environment. % % If you want to change the verb `hyphen', there is the % |\VerbHyphen\|\ % declaration provided by \pk{gmverb}. % % \changes{v0.98c}{06/9/8}{\cs{CodeDelim} renamed from a~rather confusing % \cs{NewCommentChar}; also the internal \cs{code@delim} is renamed % from as much confusing \cs{commentchar} and a~\cs{glet} for % \cs{verb}s \cs{verbhyphen} is added; similarly % \cs{[Un]CodeDelimAnd} renamed from \cs{[un]commentand}} % % \changes{v0.98m}{06/11/10}{\cs{CDAnd} and \cs{CDPerc} renamed from % \cs{CodeDelimAnd} and \cs{UnCodeDelimAnd} and both those commands % simplified to just declaring the code delimiter} % % \changes{v0.99a}{06/12/1}{split into the starred and unstarred % versions} % % \Define\code@delim \def\CodeDelim{\@ifstar\Code@Delim@St\Code@Delim} \def\Code@Delim#1{% {\escapechar\m@ne \@xa\gdef\@xa\code@delim\@xa{\string#1}}} % (|\@xa| is |\expandafter|, see \pk{gmutils}.)\DoNotIndex\@xa \def\Code@Delim@St#1{\Code@Delim{#1}\VerbHyphen{#1}} % It is an invariant of \gmdoc ing that |\code@delim| stores the % current code delimiter (of catcode 12). % % The |\code@delim| should be \catother\ so a~space is not allowed as % a~code delimiter. I~don't think it \emph{really} to be a~limitation. % % And let's assume you do as we all do: \CodeDelim*\% % We'll play with |\everypar|, a~bit, and if you use such things as % the |{itemize}| environment, an error would occur if we didn't % store the previous value of |\everypar| and didn't restore it at % return to the narration. So let's assign a~|\toks| list to store the % original |\everypar|: \newtoks\gmd@preverypar \newcommand*\settexcodehangi{% \hangindent=\verbatimhangindent \hangafter=\@ne}% we'll use % it in the inline comment case. |\verbatimhangindent| is provided by the % \pk{gmverb} package and\equals3\,em by default. % \DefIndex\@@settexcodehangi \@ifdefinable\@@settexcodehangi{\let\@@settexcodehangi=\settexcodehangi} %^^A~\gmdeverycodeline{\@@settexcodehangi} % We'll play a~bit with |\leftskip|, so let the user have a~parameter % instead. For normal text (i.e.\ the comment): \newlength\TextIndent % I~assume it's originally equal to |\leftskip|, i.e.\ |\z@|. And for % the \TeX\ code: % \HideAllDefining \newlength\CodeIndent % \label{CodeIndent} % \Define\CodeIndent \CodeIndent=1,5em\relax % And the vertical space to be inserted where there are blank lines in the % source code: \@ifundefined{stanzaskip}{\newlength\stanzaskip}{} % I~use |\stanzaskip| in \pk{gmverse} package and % derivatives for typesetting poetry. A~computer program code \emph{is} % poetry. % \Define\stanzaskip \stanzaskip=\medskipamount \advance\stanzaskip by-.25\medskipamount% to preserve the stretch- and % shrinkability.\par % %\stanza % A~vertical space between the commentary and the code seems % to enhance readability so declare \newskip\CodeTopsep \newskip\MacroTopsep % And let's set them. For \ae sthetic % minimality\StraightEOL\footnote{The terms `minimal' and `minimalist' % used in \gmdoc\ are among others\ inspired by the \emph{South Park} % cartoon's episode \emph{Mr.\ Hankey The~Christmas (\dots)}\/ in % which `Philip Glass, a~Minimalist New York composer' appears in % a~`non-denominational non-offensive Christmas play' ^^A( % ;-)\,. (Philip Glass composed the music to the \emph{Qatsi} % trilogy among others)}\QueerEOL\ let's unify them and the other most important % vertical spaces used in \gmdoc. I~think a~macro that gathers all % these assignments may be handy. % \ResumeAllDefining % \Define\MacroTopsep % \Define\CodeTopsep % \Define\UniformSkips \def\UniformSkips{%\label{UniformSkips} % \Define\CodeTopsep \Define\MacroTopsep \CodeTopsep=\stanzaskip \MacroTopsep=\stanzaskip \abovedisplayskip=\stanzaskip %\nostanza % \leftskip0sp \noindent |%\abovedisplayshortskip| % remains untouched as it is 0.0\,pt plus 3.0\,pt by default.\par % % \nostanza \belowdisplayskip=\stanzaskip \belowdisplayshortskip=.5\stanzaskip% due to DEK's idea of making the % short below display skip half of the normal. \advance\belowdisplayshortskip by\smallskipamount \advance\belowdisplayshortskip by-1\smallskipamount% We advance % \nlpercent\cs{be\+low\+dis\+play\+short\+skip} forth and back to % give it the \nlpercent\cs{small\+skip\+am\+ount}'s shrink- and % stretchability components. \topsep=\stanzaskip \partopsep=\z@ } % We make it the default, \UniformSkips % \gmdnoindent but we allow you to change the benchmark glue % i.e., |\stanzaskip| in the preamble and still have the other glues % set due to it: we launch |\UniformSkips| again after the % preamble. \AtBeginDocument{\UniformSkips} % So, if you don't want them at all i.e., you don't want to set other % glues due to |\stanzaskip|, you should use the following % declaration. That shall discard the unwanted setting already placed % in the |\begin{document}| hook. % \newcommand*\NonUniformSkips{\@relaxen\UniformSkips} % Why do we launch |\UniformSkips| twice then? The first time is % to set all the \gmdoc-specific glues \emph{somehow}, which allows % you to set not all of them, and the second % time to set them due to a~possible change of |\stanzaskip|. % % \stanza % And let's define a~macro to insert a~space % for a~chunk of documentation, e.g., to mark the beginning of new % macro's explanation and code. \newcommand*\chunkskip{% \skip0=\MacroTopsep \if@codeskipput\advance\skip0 by-\CodeTopsep\fi \par\addvspace{\skip0}\@codeskipputgtrue} % And, for a~smaller part of text, \newcommand*\stanza{% \skip0=\stanzaskip \if@codeskipput\advance\skip0 by-\CodeTopsep\fi \par\addvspace{\skip0}\@codeskipputgtrue} % Since the stanza skips are inserted automatically most often (cf.\ lines % \ref{codeskip}, \ref{codeskip2}, \ref{codeskip3}, \ref{codeskip4}, % \ref{codeskip5}), sometimes you may need to forbid them. \newcommand*\nostanza{% \@codeskipputgtrue\@afternarrgfalse\@aftercodegtrue}% In the `code % to narration' case the first switch is enough but in the countercase % `narration to code' both the second and third are necessary while % the first is not. % % % To count the lines where they have begun not before them \newgif\if@newline % |\newgif| is |\newif| with global effect i.e., it defines |\...gtrue| % and |\...gfalse| switchers that switch respective Boolean switch % \emph{globally}. See \pk{gmutils} package for details. % \stanza % % To handle the \ds\ directives not \emph{any} |%<...|. % \Define\if@dsdir \newgif\if@dsdir % This switch will be falsified at the first char of a~code line. (We % need a~switch independent of the one indicationg whether the line % has or has not been counted because of two reasons: 1.\ line % numbering is optional, 2.\ counting the line falsifies that switch % \emph{before} the first char.) % % \subdivision{The Core} % % Now we define main |\input|ing command that'll change catcodes. % The macros used by it are defined later. % \newcommand*\DocInput{\bgroup\@makeother\_\Doc@Input} \begingroup\catcode`\^^M=\active% \firstofone{\endgroup% \newcommand*{\Doc@Input}[1]{\egroup\begingroup% % \changes{v0.98}{06/09/05}{\cs{@makeother\protect\bslash_} added} % \DefIndex\gmd@inputname \edef\gmd@inputname{#1}% we'll use it in some notifications. % \DefIndex\gmd@currentlabel@before \let\gmd@currentlabel@before=\@currentlabel% we store it because % we'll do |\xdef|s of |\@currentlabel| to make proper references % to the line numbers so we want to restore current % |\@currentlabel| after our group. % \CodeUsgIndex\clubpenalty \CodeUsgIndex\widowpenalty \gmd@setclubpenalty% we wrapped the assignment of |\clubpenalty| % in a~macro because we'll repeat it twice more. \@clubpenalty\clubpenalty \widowpenalty=3333 % Most paragraphs of the code will be % one-line most probably and many of the narration, too.\par %\vskip-\stanzaskip % \changes[\DocInput]{v0.95}{06/08/15}{\cs{club-} % and \cs{widowpenalty} set both to 3333} %\CodeUsgIndex\tolerance \tolerance=1000 % as in \docfm. % \CodeUsgIndex\CodeSpacesBlank \if@codespacesblank\CodeSpacesBlank\fi% \label{cspb}The default is % that the code spaces are visible but here this may be cancelled % due to the \cs{co\+de\+spa\+ces\+blank} option. \catcode`\^^M=\active% % \CodeUsgIndex\code@delim \@xa\@makeother\csname\code@delim\endcsname% % \CodeUsgIndex\gmd@resetlinecount \gmd@resetlinecount% due to the option |uresetlinecount| % we reset the linenumber counter or do nothing. % \CodeUsgIndex\@beginputhook \@beginputhook% my first use of it is to redefine |\maketitle| % just at this point not globally. \CodeUsgIndex\everypar \everypar=\@xa{\@xa\@codetonarrskip\the\everypar}% % \Define*{^^M} \let^^M=\gmd@textEOL% % \Define\gmd@guardedinput \edef\gmd@guardedinput{% \@nx\@@input #1\relax% |\@nx| is % |\noexpand|, see \pk{gmutils}.\DoNotIndex\@nx % \inverb|\@@input| is the % true \TeX's \inverb|\input|. \CodeUsgIndex\EOFMark \gmd@iihook% cf.\ line \ref{iihook} \@nx\EOFMark% to pretty finish the input, see % line~\ref{eofMark}.\CodeUsgIndex\code@delim \@nx\CodeDelim\@xa\@nx\csname\code@delim\endcsname% to % ensure the code delimiter is the same as at the beginning of % input. % \changes[\DocInput]{v0.99c}{2007/03/02}{added ensuring the % code delimiter to be the same at the end as at the beginning} \@nx^^M\code@delim% % \label{guardians} }% we add guardians after % |\input|ing a~file; somehow an error occurred without them. \catcode`\%=9 % for \docfm -compatibility.\label{ignorePercent} \setcounter{CheckSum}{0}% we initialize the counter for the number % of the escape chars (the assignment is |\global|). \@xa\@xa\@xa^^M\gmd@guardedinput%\label{eeeEOL} \par% % \CodeUsgIndex\@endinputhook \@endinputhook% It's a~hook to let postpone % some stuff till the end of input. We use it e.g.\ for the % \docfm-(not)likeliness notifications. \glet\@currentlabel=\gmd@currentlabel@before% we restore % value from before this group. In a~very special case this could % cause unexpected behaviour of crossrefs, but anyway we acted % globally and so acts \pk{hyperref}. \endgroup% }% end of |\Doc@Input|'s definition. }% end of |\firstofone|'s argument. % So, having the main macro outlined, let's fill in the details. % % First, define the queer EOL. We define a~macro that |^^M| will be % let to. |\gmd@textEOL| % will be used also for checking the |%^^M| case (|\@ifnextchar| % does |\ifx|). % \def\gmd@textEOL{ % a~space just like in normal \TeX. We put it first to % cooperate with \inverb|\^^M|'s |\expandafter\ignorespaces|. It's no % problem since a~space | |${}_{10}$ doesn't drive \TeX\ out of % the vmode. \ifhmode\@afternarrgtrue\@codeskipputgfalse\fi% being in % the horizontal mode means we've just typeset some narration so we % turn the respective switches: the one bringing the message `we are % after narration' to True (|@afternarr|) and the `we have put the % code-narration glue' to False (|@codeskipput|). Since we are in % a~verbatim group and the information should be brought outside it, % we switch the switches globally (the letter |g| in both). \@newlinegtrue% to |\refstep| the lines' counter at the proper % point. \@dsdirgtrue% to handle the \ds\ directives. \@xa\@trimandstore\the\everypar\@trimandstore%we store the % previous value of |\everypar| register to restore it at % a~proper point. See line \ref{@trimandstore} for the details. \begingroup%^^A ##### maybe we prefer to restore the genuine |\par| % ^^A~before the group? % ^^A \let\gmd@narrpar\par% we store the possibly redefined |\par| to % ^^A~typeset the previous narration appropriately. % ^^A \def\par{\gmd@narrpar\let\par\@@par}% the first |\par| will be % ^^A~the one brought from the narration but then, \gmd@setclubpenalty% Most paragraphs will be % one-line most probably. Since some sectioning commands may change % \inverb|\clubpenalty|, we set it again here and also after this % group. \aftergroup\gmd@setclubpenalty% \let\par\@@par% inside the verbatim group we wish |\par| to be genuine. % \CodeUsgIndex\ttverbatim \ttverbatim% it does |\tt| and makes specials % other or |\active|-and-breakable. \gmd@DoTeXCodeSpace% \@makeother\|% because |\ttverbatim| doesn't do that. \MakePrivateLetters% see line \ref{MPL}.\par \@xa\@makeother\code@delim% we are % almost sure the code comment char is among the chars having % been \catother ed already. For `almost' see the % \gmiflink[IndexInput]{\cs{IndexInput}} macro's definition.\par % So, we've opened a~verbatim group and want to peek at the next % character. If it's |%|, then we just continue narration, else we % process the leading spaces supposed there are any and, if after % them is a~|%|, we just continue the commentary as in the % previous case or else we typeset the \TeX\ code. \@xa\@ifnextchar\@xa{\code@delim}{%\label{ifContNarr} % \CodeUsgIndex\gmd@continuenarration \gmd@continuenarration}{% \CodeUsgIndex\gmd@dolspaces \gmd@dolspaces% it will launch |\gmd@typesettexcode|. }% end of |\@ifnextchar|'s else. }% end of |\gmd@textEOL|'s definition. \def\gmd@setclubpenalty{\clubpenalty=3333 } % \stanza % For convenient adding things to the begin- and endinput hooks: \def\AtEndInput{\g@addto@macro\@endinputhook} \def\@endinputhook{} %\label{@endinputhook} % Simili modo \def\AtBegInput{\g@addto@macro\@beginputhook} \def\@beginputhook{} % For the index input hooking now declare a~macro, we define it % another way at line \ref{iihook}. \emptify\gmd@iihook % And let's use it instantly to avoid a~disaster while reading in the % table of contents. % \DefIndex\gmd@@toc \AtBegInput{\let\gmd@@toc\tableofcontents \def\tableofcontents{% \label{straighttoc} \@ifQueerEOL{\StraightEOL\gmd@@toc\QueerEOL}{\gmd@@toc}}} % As you'll learn from lines \ref{QueerEOL} and \ref{StraightEOL}, we % use those two strange declarations to change and restore the very % special meaning of the line end. Without such changes % |\tableofcontents| would cause a~disaster (it did indeed). And to % check the catcode of |^^M| is the r\ocircum le of |\@ifQueerEOL|: % % \changes{v0.98a}{06/09/06}{\cs{tableofcontents}, \cs{PrintIndex} % and \cs{PrintChanges} modified to work properly in the `queer line % ends' environment.} \long\def\@ifQueerEOL#1#2{%% \changes{v0.98a}{06/09/06}{added} \ifnum\the\catcode`\^^M=\active \afterfi{#1}\else\afterfi{#2}\fi} % The declaration below is useful if you % wish to put sth.\ just in the nearest input/included file and no % else: at the moment of putting the stuff it will erase it from the % hook. You may declare several |\AtBegInputOnce|s, they add up. % %^^A Define*{hook@oncecnt} %^^A CodeDefIndex*\c@hook@oncecnt %^^A\newcounter{hook@oncecnt} % \Define\gmd@ABIOnce \@emptify\gmd@ABIOnce \AtBegInput\gmd@ABIOnce \long\def\AtBegInputOnce#1{% % \changes{v0.98a}{06/09/05}{The counter \cs[]{hook@oncecnt} added % to number the self-destructing cs's (thence the hooks add up) and % the prefix changed to \cs[]{gmd/AtBI/NeuroOncer}} % \changes{v0.98l}{06/10/26}{After the Tiger's suggestion, defining % a~unique macro for each use of \* substituted with just one macro in % the begin input hook and adding to this macro.} %^^A \stepcounter{hook@oncecnt}% %^^A \@xa\long\@xa\edef% \CodeUsgIndex*{NeuroOncer} %^^A \csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname{% %^^A \@nx\glet\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname\relax}% %^^A \@xa\addtomacro\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname{#1}% %^^A \@xa\AtBegInput\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname \gaddtomacro\gmd@ABIOnce{\g@emptify\gmd@ABIOnce#1}} % Many tries of finishing the input cleanly led me to setting the % guardians as in line \ref{guardians} and to \def\EOFMark{\} % \label{eofMark}Other solutions did print the last code delimiter or % would require managing a~special case for the macros typesetting % \TeX\ code to suppress the last line's numbering etc. % % If you don't like it, see line \ref{NoEOF}. % \stanza % % Due to the |codespacesblank| option in the line \ref{cspb} we launch % the macro defined below to change the meaning of a~\pk{gmdoc}-kernel % macro. % \DefIndex\gmd@DoTeXCodeSpace \begin{obeyspaces}% \gdef\gmd@DoTeXCodeSpace{% \obeyspaces\let =\breakablexiispace}% % \stanza % \Define\CodeSpacesBlank % \changes{v0.98a}{06/09/06}{a~kernel \cs{gmd@verbatimspace} renamed % to \cs{gmd@texcodespace} and a~bug fixed.} % \CodeUsgIndex\gmobeyspaces % \DefIndex\gmd@texcodespace \gdef\CodeSpacesBlank{% \let\gmd@DoTeXCodeSpace\gmobeyspaces% \let\gmd@texcodespace=\ }% the latter |\let| is for the |\if...|s. %\stanza % \Define\CodeSpacesSmall \gdef\CodeSpacesSmall{% \def\gmd@DoTeXCodeSpace{% \obeyspaces\def {\,\hskip\z@}}% \def\gmd@texcodespace{\,\hskip\z@}}% % \end{obeyspaces} % How the continuing of the narration should look like? \def\gmd@continuenarration{% \endgroup \gmd@countnarrationline% see \gmiflink[countnarr]{below}. \@xa\@trimandstore\the\everypar\@trimandstore \everypar=\@xa{\@xa\@codetonarrskip\the\everypar}% \@xa\gmd@checkifEOL\@gobble} % Simple, isn't it? (We gobble the `other' code delimiter. Despite of % |\egroup| it's \catother\ because it was touched by |\futurelet| % contained in |\@ifnextchar| in line \ref{ifContNarr}. And in line % \ref{ContNarr2} it's been read as \catother. That's why it % works in spite of that |%| is of category `ignored'.) %\gmhypertarget[countnarr]{Whether} we count the narration lines % depends on the option |countalllines| which is off by default. \if@countalllines \def\gmd@countnarrationline{% \if@newline \grefstepcounter{codelinenum}\@newlinegfalse% the % |\grefstepcounter| macro, defined in \pk{gmverb}, is a~global % version of |\refstepcounter|, observing the redefinition made % to |\refstepcounter| by \pk{hyperref}. \everypar=\@xa{% \@xa\@codetonarrskip\the\gmd@preverypar}%^^A % the \cs{hy\+p\+er\+lab\+el\+@\+li\+ne} macro puts % a~hypertarget in a~|\raise| i.e., drives \TeX\ into the % horizontal mode so |\everypar| shall be issued. Therefore we % should restore it. \hyperlabel@line {\LineNumFont\thecodelinenum}\,\ignorespaces \fi}% \DefIndex\gmd@countnarrationline \else \@emptify\gmd@countnarrationline% \fi % And typesetting the \TeX\ code? \begingroup\catcode`\^^M=\active% \firstofone{\endgroup% \DefIndex\gmd@typesettexcode \def\gmd@typesettexcode{% \gmd@parfixclosingspace% it's to eat a~space closing the % paragraph, see \gmiflink[closingspace]{below}. It contains % |\par|. % % A~verbatim group has already been opened by \cs{ttverb\+at\+im} and % additional |\catcode|. \everypar={\@@settexcodehangi}% At first attempt we thought % of giving the user a~|\toks| list to insert at the beginning of % every code line, but what for? % \Define*{^^M}^^A \def^^M{% \@newlinegtrue% to |\refstep| the counter in proper place. \@dsdirgtrue% to handle the \ds\ directives. \global\gmd@closingspacewd=\z@% \label{noclosingspace}we % don't wish to eat a~closing space after a~codeline, because % there isn't any and a~negative rigid |\hskip| added to % |\parfillskip| would produce a~blank line. \ifhmode\par\@codeskipputgfalse\else% \if@codeskipput% \else\addvspace{\stanzaskip}\@codeskipputgtrue% \fi% if we've just met a~blank (code) line, we insert % a~|\stanzaskip| glue. % \label{codeskip} \fi% \prevhmodegfalse% we want to know later that now we are in the % vmode. \@ifnextchar{\gmd@texcodespace}{% \@dsdirgfalse\gmd@dolspaces}{\gmd@charbychar}% }% end of |^^M|'s definition.\label{debug!2} % \DefIndex\gmd@texcodeEOL \let\gmd@texcodeEOL=^^M% for further checks inside |\gmd@charbychar|. \raggedright\leftskip=\CodeIndent% \if@aftercode\gmd@nocodeskip1{iaC}\else\if@afternarr% % ^^A~\def^^C{\showthe\hyphenpenalty\showthe\rightskip} \if@codeskipput\else\gmd@codeskip1\@codeskipputgtrue\@aftercodegfalse\fi% % \label{codeskip3} \else\gmd@nocodeskip1{naN}\fi\fi% if now we are % switching from the narration into the code, we insert a~proper % vertical space. \@aftercodegtrue\@afternarrgfalse% \ifdim\gmd@ldspaceswd>\z@% and here the leading spaces. \leavevmode\@dsdirgfalse% \if@newline\grefstepcounter{codelinenum}\@newlinegfalse% \fi% \printlinenumber% if we don't want the lines to be numbered, % the respective option \inverb|\let|s this CS to |\relax|. \hyperlabel@line% \mark@envir% index and/or marginize an environment if there is % some to be done so, see line \ref{mark@envir}. \hskip\gmd@ldspaceswd% \advance\hangindent by\gmd@ldspaceswd% \xdef\settexcodehangi{% \@nx\hangindent=\the\hangindent% and also set the % hanging indent setting for the same line comment case. BTW., % this |%| or rather lack of it costed me five hours of % debugging and rewriting. Active lineends require extreme % caution. \@nx\hangafter=1\space}%^^A~\@nx\relax \else% \glet\settexcodehangi=\@@settexcodehangi%\\ %|%| |\printlinenumber| here produced line numbers for blank lines % which is what we don't want. \fi% of |\ifdim| \gmd@ldspaceswd=\z@% \prevhmodegfalse% we have done |\par| so we are not in the % hmode. \@aftercodegtrue% we want to know later that now we are % typesetting a~codeline. \gmd@charbychar% we'll eat the code char by char to scan all the % macros and thus to deal properly with the case |\%| in which the % |%| will be scanned and won't % launch closing of the verbatim group. }% }% end of |\gmd@typesettexcode|'s definitions's group's |\firstofone|. % % \stanza % % Now let's deal with the leading spaces once forever. We wish not to % typeset | |s but to add the width of every leading space to the % paragraph's indent and to the hanging indent, but only if there'll % be any code character not being |%| in this line (e.g., the end of % line). If there'll be only |%|, we want just to continue the comment % or start a~new one. (We don't have to worry about whether we should % |\par| or not.) % \DefIndex\gmd@spacewd \newlength\gmd@spacewd% to store the width of a~(leading) % | |\catother. % \DefIndex\gmd@ldspaceswd \newlength\gmd@ldspaceswd% to store total length of gobbled leading %spaces. % It costed me some time to reach that in my verbatim scope a~space % isn't \catother\ but \catactive, namely |\let| to % |\breakablexiispace|. % So let us |\let| for future: % \Define\gmd@texcodespace \let\gmd@texcodespace=\breakablexiispace % And now let's try to deal with those spaces. \def\gmd@dolspaces{% \ifx\gmd@texcodespace\@let@token \@dsdirgfalse \afterfi{\settowidth{\gmd@spacewd}{\xiispace}% \gmd@ldspaceswd=\z@ \gmd@eatlspace}% \else\afterfi{% about this smart macro and other of its family see % \pk{gmutils} sec.\,3. \par\gmd@typesettexcode}% \fi} % And now, the iterating inner macro that'll eat the leading spaces. \def\gmd@eatlspace#1{% \ifx\gmd@texcodespace#1% \advance\gmd@ldspaceswd by\gmd@spacewd% we don't % |\advance| it |\global|ly because the current group may be closed % iff we meet |%| and then we'll won't indent the line anyway. \afteriffifi\gmd@eatlspace \else \if\code@delim\@nx#1% \gmd@ldspaceswd=\z@ \gmd@continuenarration#1%\label{ContNarr2} \else \afterfifi{\gmd@typesettexcode#1}% \fi \fi}% % We want to know whether we were in hmode before reading current % |\code@delim|. We'll need to switch the switch globally. \newgif\ifprevhmode % \addvspace\medskipamount % % And the main iterating inner macro which eats every single char of % verbatim text to check the end. The case |\%| should be excluded % and it is indeed. \newcommand*\gmd@charbychar[1]{% \ifhmode\prevhmodegtrue \else\prevhmodegfalse\fi \if\code@delim\@nx#1% \afteriffifi{\gmd@percenthack% to typeset |%| if a~comment % continues the~codeline. \endgroup% \gmd@checkifEOLmixd}% to see if next is |^^M| and then do |\par|. \else% i.e., we've not met the code delimiter \if\code@escape@char\@nx#1% \@dsdirgfalse% yes, just here not before the whole |\if| because % then we would discard checking for \ds\ directives doable by % the active |%| at the `old macrocode' setting. \afterfifi{\gmd@counttheline#1\scan@macro}% \else \afterfifi{\gmd@EOLorcharbychar#1}% \fi \fi} % One more inner macro because |^^M| in \TeX\ code wants to peek at the % next char and possibly launch |\gmd@charbychar|. We deal with % counting the lines thorougly. Increasing the counter is divided into % cases and it's very low level in one case because |\refstepcounter| and % |\stepcounter| added some stuff that caused blank lines, at % least with \pk {hyperref} package loaded. \def\gmd@EOLorcharbychar#1{% \ifx\gmd@texcodeEOL#1% \if@newline \if@countalllines\global\advance\c@codelinenum by\@ne \@newlinegfalse\fi \fi \afterfi{#1}%\label{printhashone1}here we print |#1|. \else% i.e., |#1| is \emph{not} a~(very active) line end, \afterfi {\gmd@counttheline#1\gmd@charbychar}% \label{printhashone2}or here % we print |#1|. Here we would also possibly mark an environment % but there's no need of it because declaring an environment to % be marked requires a~bit of commentary and here we are after % a~code |^^M| with no commentary. \fi} \def\gmd@counttheline{% \ifvmode \if@newline \grefstepcounter{codelinenum}\@newlinegfalse \hyperlabel@line \fi \printlinenumber \mark@envir \else \if@newline \grefstepcounter{codelinenum}\@newlinegfalse \hyperlabel@line \fi \fi} % If before reading current |%| char we were in horizontal mode, then % we wish to print |%| (or another code delimiter). \def\gmd@percenthack{% \ifprevhmode\code@delim\aftergroup\space% We add a~space after |%|, % because I~think it looks better. It's done |\aftergroup| to make % the spaces possible after the |%| not to be % typeset. \else\aftergroup\gmd@narrcheckifds@ne% remember that % \cs{gmd\-@\-pre\-cent\-hack} is only called when we've the code % delimiter and soon we'll close the verbatim group and right after % |\endgroup| there waits |\gmd@checkifEOLmixd|. \fi} \def\gmd@narrcheckifds@ne#1{%^^A\typeout{narr@ne if ds \on@line}% \@dsdirgfalse\@ifnextchar<{% \@xa\gmd@docstripdirective\@gobble}{#1}} % The macro below is used to look for the |%^^M| case to make % a~commented blank line make a~new paragraph. % Long searched and very simple at last. \def\gmd@checkifEOL{% \gmd@countnarrationline \everypar=\@xa{\@xa\@codetonarrskip% we add the % macro that'll insert a~vertical space if we leave the code and % enter the narration. \the\gmd@preverypar}% \@ifnextchar{\gmd@textEOL}{% \@dsdirgfalse\par\ignorespaces}{\gmd@narrcheckifds}}% % We check if it's |%<|, a~\ds\ directive that is. \def\gmd@narrcheckifds{%^^A\typeout{narr if ds \on@line}% \@dsdirgfalse\@ifnextchar<{% \@xa\gmd@docstripdirective\@gobble}{\ignorespaces}} % In the `mixed' line case it should be a~bit more complex, though. On % the other hand, there's no need to checking for \ds\ directives. \def\gmd@checkifEOLmixd{% \gmd@countnarrationline \everypar=\@xa{\@xa\@codetonarrskip\the\gmd@preverypar}% % % \label{longlinethatshouldbebroken} \@afternarrgfalse\@aftercodegtrue \ifhmode\@codeskipputgfalse\fi \@ifnextchar{\gmd@textEOL}{% {\raggedright\gmd@endpe\par}% without |\raggedright| this |\par| % would be justified which is not appropriate for a~long codeline % that should be broken, e.g., \ref{longlinethatshouldbebroken}. \prevhmodegfalse \gmd@endpe\ignorespaces}{% % If a~codeline ends with |%| % (|prevhmode|${}=={}$True) first |\gmd@endpe| sets the parameters % at the \TeX\ code values and |\par| closes a~paragraph and the % latter |\gmd@endpe| sets the parameters at the narration values. % In the other case both |\gmd@endpe|s do the same % and |\par| between them does nothing. % \DefIndex\par \def\par{% \ifhmode% (I~added this |\ifhmode| as a~result of a~heavy % debug.) %^^A \typeout{par of 1766 in hmode \on@line}% \@@par \if@afternarr \if@aftercode \if@codeskipput\else\gmd@codeskip2\@aftercodegfalse\@codeskipputgtrue\fi %\label{codeskip4} \else\gmd@nocodeskip2{naC}% \fi \else\gmd@nocodeskip2{naN}% \fi \prevhmodegfalse\gmd@endpe% when taken out of |\ifhmode|, this % line caused some codeline numbers were typeset with % |\leftskip|${}=0$. \everypar=\@xa{% \@xa\@codetonarrskip\the\gmd@preverypar}% \let\par\@@par% %^^A else %^^A \typeout{par of 1766 in NOT hmode \on@line}% \fi}% \gmd@endpe\ignorespaces}} % As we announced, we play with |\leftskip| inside the verbatim % group and therefore we wish to restore normal |\leftskip| when back to % normal text i.e.\ the commentary. But, if normal text starts in the % same line as the code, then we still wish to indent such a~line. \def\gmd@endpe{% \ifprevhmode \settexcodehangi%\unskip ndent \leftskip=\CodeIndent %^^A \typeout{gmd@endpe in prevhmode \on@line}% \else \leftskip=\TextIndent \hangindent=\z@ \everypar=\@xa{% \@xa\@codetonarrskip\the\gmd@preverypar}% %^^A \typeout{gmd@endpe in not prevhmode \on@line}% \fi} % % % \subdivision{Numbering (or Not) of the Lines} % % Maybe you want codelines to be numbered and maybe you want to % reset the counter within sections. \if@uresetlinecount% with |uresetlinecount| option\dots \@relaxen\gmd@resetlinecount% \dots\ we turn % resetting the counter by \cs{Doc\+In\+put} off\dots \newcommand*\resetlinecountwith[1]{% \newcounter{codelinenum}[#1]}% \dots\ and provide a~new % declaration of the counter. \else% With the option turned off\dots \newcounter{DocInputsCount}% \newcounter{codelinenum}[DocInputsCount]% \dots\ we declare the % |\DocInput|s' number counter andthe codeline counter % to be reset with stepping of it. % \changes[\c@DocInputsCount]{v0.98c}{06/9/8}{added for fixing % duplication of \pk{hyperref} labels in the case of a~multiple % \cs{DocInput}} \newcommand*\gmd@resetlinecount{\stepcounter{DocInputsCount}}% \dots % and let the |\DocInput| increment the |\DocInput|s number count % and thus reset the codeline count. It's for unique naming of the % \pk{hyperref} labels. \fi % Let's define printing the line number as we did in \pk{gmvb} % package. \newcommand*\printlinenumber{% \leavevmode\llap{\rlap{\LineNumFont$\phantom{999}$\llap{\thecodelinenum}}% \hskip\leftskip}} \def\LineNumFont{\normalfont\tiny} \if@linesnotnum\@relaxen\printlinenumber\fi \newcommand*\hyperlabel@line{% \if@pageindex% It's good to be able to switch it any time not just % define it once according to the value of the switch set by the % option. \else \raisebox{2ex}[1ex][\z@]{\gmhypertarget[clnum.% \HLPrefix\arabic{codelinenum}]{}}% \fi} % % \subdivision{Spacing with \cs{everypar}} % % Last but not least, let's define the macro inserting a~vertical space % between the code and the narration. Its parameter is % a~\gmhypertarget[relic parameter]{relic} of a~very heavy debug of % the automatic vspacing mechanism. Let it remain at least until this % package is 2.0 version. \newcommand*\gmd@codeskip[1]{\@@par\addvspace\CodeTopsep\@codeskipputgtrue} %\label{codeskip2} % Sometimes we add the |\CodeTopsep| vertical space in % |\everypar|. When this happens, first we remove the |\parindent| % empty box, but this doesn't reverse putting |\parskip| to the main % vertical list. And if |\parskip| is put, |\addvspace| shall see it % not the `true' last skip. \Describe*{@codeskipput}Therefore we need % a~Boolean switch to keep the knowledge of putting similar vskip % before |\parskip|. % \Define\if@codeskipput \newgif\if@codeskipput % The below is another relic of the heavy debug of the automatic % vspacing. Let's give it the same removal clause as % \gmiflink[relic parameter]{above}. \newcommand*\gmd@nocodeskip[2]{} % And here is how the two relic macros looked like during the % debug. As you see, they are disabled by a~false |\if| (look at it % closely ;-). \if1 1 \renewcommand*\gmd@codeskip[1]{% \hbox{\rule{1cm}{3pt} #1!!!}} \renewcommand*\gmd@nocodeskip[2]{% \hbox{\rule{1cm}{0.5pt} #1: #2 }} \fi % We'll wish to execute |\gmd@codeskip| wherever a~codeline (possibly with % an inline comment) is followed by a~homogenic comment line or % reverse. Let us dedicate a~Boolean switch to this then. % \Define\if@aftercode \newgif\if@aftercode % This switch will be set true in the moments when we are able to % switch from the \TeX\ code into the narration and the below one when % we are able to switch reversely. % \Define\if@afternarr \newgif\if@afternarr % To insert vertical glue between the \TeX\ code and the narration % we'll be playing with |\everypar|. More precisely, we'll add a~macro % that the |\parindent| box shall move and the glue shall put. \long\def\@codetonarrskip{% \if@codeskipput\else \if@afternarr\gmd@nocodeskip4{iaN}\else \if@aftercode % We are at the beginning of |\everypar|, i.e., \TeX\ has just entered % the hmode and put the |\parindent| box. Let's remove it then. {\setbox0=\lastbox}% % Now we can put the vertical space and state we are not `aftercode'. \gmd@codeskip4\@codeskipputgtrue %\label{codeskip5} \leftskip\TextIndent% this line is a~patch against % a~bug-or-feature that in certain cases the narration |\leftskip| % is left equal the code leftskip. (It happens when there're % subsequent code lines after an inline comment not ended with % an explicit |\par|.) \else\gmd@nocodeskip4{naC}% \fi% \fi \fi\@aftercodegfalse} % But we play with |\everypar| for other reasons too, and while restoring it, % we don't want to add the |\@codetonarrskip| macro infinitely many % times. So let us define a~macro that'll check if |\everypar| begins % with |\@codetonarrskip| and trim it if so. We'll use this macro with % proper |\expandafter|ing in order to give it the contents of % |\everypar|. The work should be done in two steps first of which % will be checking whether |\everypar| is nonempty (we can't have two % delimited parameters for a~macro: if we define a~two-parameter % macro, the first is undelimited so it has to be nonempty; it costed % me some one hour to understand it). \long\def\@trimandstore#1\@trimandstore{% \def\@trimandstore@hash{#1}% \ifx\@trimandstore@hash\@empty% we check if |#1| is % nonempty. The |\if|\inverb*|\relax#1\relax| trick is not % recommended here because using it we couldn't avoid expanding |#1| % if it'd be expandable. \gmd@preverypar={}% \else \afterfi{\@xa\@trimandstore@ne\the\everypar\@trimandstore}% \fi} \long\def\@trimandstore@ne#1#2\@trimandstore{%\label{@trimandstore} \def\trimmed@everypar{#2}% \ifx\@codetonarrskip#1% \gmd@preverypar=\@xa{\trimmed@everypar}% \else \gmd@preverypar=\@xa{\the\everypar}% \fi} % We prefer not to repeat |#1| and |#2| within the |\if|s and we even % define an auxiliary macro because |\everypar| may contain some % |\if|s or |\fi|s. % % % \subdivision[Life Among Queer EOLs]{Life Among Queer \gmhypertarget[afc]{EOLs}} % % When I~showed this package to my \TeX\ Guru he commended it and % immediately pointed some disadvantages in the comparison with the % \docfm\ package. % % One of them was an expected difficulty of breaking a~moving argument % (e.g., of a~sectioning macro) in two lines. To work it around let's % define a~line-end eater: \catcode`\^^B=\active% note we re|\catcode| \ globally, for the % entire document. \foone{\catcode`\^^M=\active}%% \Define*{^^B} {\def\QueerCharTwo{% \def^^B##1^^M{\ignorespaces}}% } \QueerCharTwo \AtBegInput{\@ifQueerEOL{\catcode`\^^B\active}{}\QueerCharTwo}% \label{QCh2} % We repeat redefinition of \ at begin of the documenting % input, because \pk{doc.dtx} suggests that some packages (namely % \pk{inputenc}) may re|\catcode| such unusual characters. % % \changes{v0.98d}{06/9/11}{re\cs{catcode}ing and defining % \cs{char1} and \cs{char2} added atto begin doc input} % % \stanza % As you see the |^^B| active char is defined to gobble everything % since itself till the end of line and the very end of line. This is % intended for harmless continuing a~line. The price is affecting the % line numbering when |countalllines| option is enabled. % % I~also liked the \docfm's idea of comment${}^2$ i.e., the % possibility of marking some text so that it doesn't appear nor in the % working version neither in the documentation, got by making % |^^A| (i.e., \) a~comment char. % % However, in this package such a~trick would work another way: here % the line ends are active, a~comment char would disable them and that % would cause disasters. So let's do it an |\active| way. \catcode`\^^A=\active% note we re|\catcode| \ globally, for the % entire document. \foone{\catcode`\^^M=\active}%%\DefIndex\QueerCharOne \Define*{^^A} {\def\QueerCharOne{% \def^^A{% \bgroup\let\do\@makeother\dospecials\gmd@gobbleuntilM}}% \def\gmd@gobbleuntilM#1^^M{\egroup\ignorespaces^^M}% } \QueerCharOne \AtBegInput{\@ifQueerEOL{\catcode`\^^A\active}\QueerCharOne}% see note % after line \ref{QCh2}. % As I~suggested in the users' guide, |\StraightEOL| and |\QueerEOL| are % intended to cooperate in harmony for the user's good. They take care % not only of redefining the line end but also these little things % related to it. % % One usefulness of |\StraightEOL| is allowing linebreaking of the % command arguments. Another making possible executing some code lines % during the documentation pass. % % \changes{v0.98b}{06/09/07}{\cs{QueerM} and \cs{StraightM} renamed % to \cs{QueerEOL} and \cs{StraightEOL} and other (internal) macros % ending with \cs[]{M}} \def\StraightEOL{%\label{StraightEOL} \catcode`\^^M=5 \catcode`\^^A=14 \catcode`\^^B=14 \def\^^M{\ }} \foone{\catcode`\^^M=\active}% {\def\QueerEOL{%\label{QueerEOL} \catcode`\^^M=\active% \let^^M\gmd@textEOL% % ^^A~ $$$$$$$$ \catcode`\^^A=\active% \catcode`\^^B=\active% I~only re|\catcode| \ and \ % hoping no one but me is \emph{that} perverse to make them % |\active| and (re)define. (Let me know if I'm wrong at this point.) \let\^^M=\gmd@bslashEOL}% } % \iffalse % They won't work in \verb+|verbatim|+ scopes but the clubs redefine % the active lineend to be a~breakable (and visible) space, so % breaking a~`clubbed' text in two lines will not cause a~disaster but % you get e.g., |...^^B %...|. % \fi % \gmhypertarget[closingspace]{To make} |^^M| behave more like a~`normal' % lineend I~command it to add a~| |${}\subs{10}$ at first. It works % but has one uwelcome feature: if the line has nearly |\textwidth|, % this closing space may cause line breaking and setting a~blank line. % To fix this I~|\advance| the |\parfillskip|: \def\gmd@parfixclosingspace{{% \advance\parfillskip by-\gmd@closingspacewd\par}} % We'll put it in a~group surrounding |\par| but we need to check if % this |\par| is executed after narration or after the code, % i.e., whether the closing space was added or not. \newskip\gmd@closingspacewd \newcommand*\gmd@setclosingspacewd{% \global\gmd@closingspacewd=\fontdimen2\font% plus\fontdimen3\font minus\fontdimen4\font\relax} % % See also line \ref{noclosingspace} to see what we do in the codeline % case when no closing space is added. % And one more detail: \bgroup\catcode`\^^M=\active% \firstofone{\egroup% \DefIndex*{\^^M}\changes{v0.99c}{2007/03/30}{a~bug fix: redefinition of it left solely to \cs{QueerEOL}} \def\gmd@bslashEOL{\ \@xa\ignorespaces^^M}} % The |\QueerEOL| declaration will |\let| it to |\^^M| to make % |\^^M| behave properly. If this definition was ommitted, |\^^M| % would just expand to |\ | and thus not gobble the leading |%| of the % next line leave alone typesetting the \TeX\ code. I~type |\ | etc. % instead of just |^^M| which adds a~space itself because I~take % account of a~possibility of redefining the |\ | CS by the user, just % like in normal \TeX. % We'll need it for restoring queer definitions for \docfm-compatibility. % % % \subdivision{Adjustment of \env{verbatim} and \cs{verb}} % % To make \env{verbatim(*)} typeset its contents with the \TeX\ code's % indentation: % \Define\@verbatim \gaddtomacro\@verbatim{\leftskip=\CodeIndent} % And a~one more little definition to accomodate |\verb| and pals for the % lines commented out. \AtBegInput{\long\def\check@percent#1{% \@xa\ifx\code@delim#1\else\afterfi{#1}\fi}} % We also redefine \pk{gmverb}'s |\AddtoPrivateOthers| that has been % provided just with \pk{gmdoc}'s need in mind. \def\AddtoPrivateOthers#1{% \@xa\def\@xa\doprivateothers\@xa{% \doprivateothers\do#1}}% % We also redefine an internal |\verb|'s macro |\gm@verb@eol| to put a~proper % line end if a~line end char is met in a~short verbatim: we have to % check if we are in `queer' or `straight' EOLs area. \begingroup \obeylines% \DefIndex\gm@verb@eol \AtBegInput{\def\gm@verb@eol{\obeylines% \def^^M{\verb@egroup\@latex@error{% \@nx\verb ended by end of line}% \@ifQueerEOL{\gmd@textEOL}{\@ehc}}}}% \endgroup % \subdivision{Macros for Marking The Macros} % % A~great inspiration for this part was the \docfm\ package again. % I~take some macros from it, and some tasks I~solve a~different way, % e.g., the |\| (or another escapechar) is not active, because anyway % all the chars of code are scanned one by one. And exclusions from % indexing are supported not with a~list stored as |\toks| register % but with separate control sequences for each excluded CS. % % \stanza % % The \docfm\ package shows a~very general approach to the indexing % issue. It assumes using a~special MakeIndex style and doesn't use % explicit MakeIndex controls but provides specific macros to hide % them. But here in \pk{gmdoc} we prefer no special style for the % index. % \Define\actualchar \Define\quotechar \Define\encapchar % \Define\levelchar % \changes[\actualchar]{v0.98e}{06/09/23}{a~bug fix: making the % \cs[]{@} \protect\catother\space again} \edef\actualchar{\string @} \edef\quotechar{\string "} \edef\encapchar{\xiiclub} \edef\levelchar{\string !} % However, for the glossary, i.e., the change history, a~special style % is required, e.g., \pk{gmglo.ist}, and the above macros are % redefined by the |\changes| command due to \pk{gmglo.ist} and % \pk{gglo.ist} settings. % % Moreover, if you insist on using a~special MakeIndex style, you may % redefine the above four macros in the preamble. The |\edef|s that % process them further are postponed till |\begin{document}|. % % % \Define\code@escape@char \def\CodeEscapeChar#1{% \begingroup \escapechar\m@ne \xdef\code@escape@char{\string#1}% \endgroup} % As you see, to make a~proper use of this macro you should give it % a~|\|\ CS as an argument. It's an invariant assertion that % |\code@escape@char| stores `other' version of the code layer % escape char. % \CodeUsgIndex\CodeEscapeChar \CodeEscapeChar\\ % As mentioned in \docfm, someone may have some chars \catletter ed. \@ifundefined{MakePrivateLetters}{%\label{MPL} \def\MakePrivateLetters{\makeatletter\catcode`\*=11 }}{} % A~tradition seems to exist to write about e.g., `command |\section| and % command |\section*|' and such an uderstanding also of `macro' is % noticeable in \docfm. Making the |*| a~letter solves the problem of % scanning starred commands. % % \stanza % And you may wish some special chars to be \catother. \def\MakePrivateOthers{\let\do=\@makeother \doprivateothers} % We use this macro to re|\catcode| the space for marking the % environments' names and the caret for marking chars such as |^^M|, see % line \ref{TextUsage}. So let's define the list: \def\doprivateothers{\do\ \do\^} % Two chars for the beginning, and also the |\MakeShortVerb| command % shall this list enlarge with the char(s) declared. % (There's no need to add the backslash to this list since all the % relevant commands |\string| their argument whatever it is.) % % \changes{v0.98c}{06/9/9}{\cs{} removed from \cs{doprivateothers} % list and \cs{string} added instead to commands that process the % `environments' names;} % Now the main macro indexing a~macro's name. It would be a~verbatim % :-) copy of the \docfm 's one if I~didn't ommit some lines % irrelevant with my approach. \def\scan@macro#1{% we are sure to scan at least one token and % therefore we define this macro as one-parameter.\par % Unlike in \docfm , here we have the escape char \catother\ so we % may just have it printed during main scan char by char, i.e., in the % lines \ref{printhashone1} and \ref{printhashone2}.\par % So, we step the checksum counter first, \step@checksum% \label{checksumUse}(see line \ref{checksum} for % details),\par % Then, unlike in \docfm , we do \emph{not} check if the scanning is % allowed, because here it's always allowed and required.\par % Of course, I~can imagine horrible perversities, but I~don't think % they should really be taken into account. Giving the letter |a| % |\catcode| other than \catletter\ surely would be one of those % perversities. Therefore I~feel safe to take the character |a| as % a~benchmark letter. \ifcat a\@nx#1% \quote@char#1% \xdef\macro@iname{\gmd@maybequote#1}% global for symmetry with % line \ref{x474}. \xdef\macro@pname{\string#1}%\label{stringing0} we'll print entire % name of the macro later.\par % We |\string| it here and in the lines \ref{stringing1} and % \ref{stringing2} to be sure it is whole \catother\ for easy % testing for special indexentry formats, see line % \ref{pnametestDef} etc. Here we are sure the result of |\string| % is \catother\ since its argument is \catletter. \afterfi{\@ifnextcat{a}{\gmd@finishifstar#1}{\finish@macroscan}}% \else% |#1| is not a~letter, so we have just scanned a~one-char % CS.\par % Another reasonable |\catcode|s assumption seems to be that the % digits are \catother. Then we don't have to % type (|%|)|\expandafter\@gobble\string\a|. We do the |\uccode| % trick to be sure that the char we write as the macro's name is % \catother. {\uccode`9=`#1% \uppercase{\xdef\macro@iname{9}}%\label{x474} }% \quote@char#1% \xdef\macro@iname{\gmd@maybequote\macro@iname}% \xdef\macro@pname{\xiistring#1}%\label{stringing1} \afterfi \finish@macroscan \fi} % The |\xiistring| macro, provided by \pk{gmutils}, is used instead of % original |\string| because we wish to get | |\catother (`other' space). % % \stanza % Now, let's explain some details, i.e., let's define them. We call % the following macro having known |#1| to be \catletter. \def\continue@macroscan#1{% \quote@char#1% \xdef\macro@iname{\macro@iname \gmd@maybequote#1}% \xdef\macro@pname{\macro@pname \string#1}%\label{stringing2} we know % \inverb*|#1| to be \catletter, so % we don't need \inverb|\xiistring|. \@ifnextcat{a}{\gmd@finishifstar#1}{\finish@macroscan}% } % As you may guess, |\@ifnextcat| is defined analogously to |\@ifnextchar| but % the test it does is |\ifcat| (not |\ifx|). (Note it wouldn't % work for an active char as the `pattern'.) %\stanza % We treat the star specially since in usual \LaTeX\ it should finish % the scanning of a~CS name---we want to avoid scanning % |\command*argum| as one CS. \def\gmd@finishifstar#1{% \if*\@nx#1\afterfi\finish@macroscan% note we protect |#1| against % expansion. In \pk{gmdoc} verbatim scopes some chars are active % (e.g. \inverb|\|\,). \else\afterfi\continue@macroscan \fi} % If someone \emph{really} uses |*| as a~letter please let me know. \def\quote@char#1{{\uccode`9=`#1% at first I~took digit 1 for this % |\uccode|ing but then |#1| meant |#|\<\#1> in |\uppercase|'s % argument, of course. \uppercase{% \DefIndex\gmd@maybequote \gmd@ifinmeaning 9\of \indexcontrols {\glet\gmd@maybequote\quotechar}% {\g@emptify\gmd@maybequote}% }% }} % And now let's take care of the MakeIndex control characters. We'll % define a~list of them to check whether we should quote a~char or % not. But we'll do it at |\begin{document}| to allow the user to use % some special MakeIndex style and in such a~case to redefine the four % MakeIndex controls' macros. We enrich this list with the backslash % because sometimes MakeIndex didn't like it unquoted. % \Define\indexcontrols % \changes{v0.98d}{06/9/15}{relativized to the index control macros: % previously the controls were given explicitly as the standard ones.} \AtBeginDocument{\xdef\indexcontrols{% \bslash\levelchar\encapchar\actualchar\quotechar}} \long\def \gmd@ifinmeaning#1\of#2#3#4{% explained in the text % paragraph below. \changes{v0.99g}{2007/11/06}{made more elegant: % \cs{if} changed to \cs{ifx} made four parameters and not expanding % to an open \cs{iftrue/false}. Also renamed from \cs{@ifismember}} \long\def\gmd@in@@##1#1##2\gmd@in@@{% \ifx^^A##2^^A\afterfi{#4}% \else\afterfi{#3}% \fi}% \@xa\gmd@in@@#2#1\gmd@in@@}% %^^A % To hide the Booleans from \TeX\ in some contexts define %^^A \def\gmd@@iftrue{\iftrue} %^^A \def\gmd@@iffalse{\iffalse} %^^A \def\gmd@@fi{\fi} %^^A % A~try to |\let| instead of |\def| resulted with the `incomplete if' %^^A % error: \TeX\ looks at the meanings not the names while counting %^^A % |\if|s. % This macro is used for catching chars that are % MakeIndex's controls. How does it work? % % |\quote@char| sort of re|\catcode|s its argument through the % |\uccode| trick: assigns the argument as the uppercase code of the % digit 9 and does further work in the |\uppercase|'s scope so the % digit 9 (a~benchmark `other') is substituted by |#1| but the % |\catcode| remains so |\gmd@ifinmeaning| gets |\quote@char|'s |#1| % `other'ed as the first argument. % % The meaning of the |\gmd@ifinmeaning| parameters is as follows: %\begin{enumargs}^^B %\item the token(s) whose presence we check, %\item the macro in whose meaning we search |#1| (the first token of % this argument is expanded one level with |\expandafter|), %\item the `if found' stuff, %\item the `if not found' stuff. %\end{enumargs} % % In |\quote@char| the second argument for |\gmd@ifinmeaning| is % |\indexcontrols| defined as the (expanded and `other') sequence of % the MakeIndex controls. |\gmd@ifinmeaning| defines its inner macro % |\gmd@in@@| to take two parameters separated by the first and the % second |\gmd@ifinmeaning|'s parameter, which are here the char % investigated by |\quote@char| and the |\indexcontrols| list. The % inner macro's parameter string is delimited by the macro itself, why % not. |\gmd@in@@| is put before a~string consisting of % |\gmd@ifinmeaning|'s second and first parameters (in such a~reversed % order) and |\gmd@in@@| itself. In such a~sequence it looks for % something fitting its parameter pattern. |\gmd@in@@| is sure to find % the parameters delimiter (|\gmd@in@@| itself) and the separator, % |\ifismember|'s |#1| i.e., the investigated char, because they are % just there. But the investigated char may be found not near the end, % where we put it, but among the MakeIndex controls' list. Then the % rest of this list and |\ifismember|'s |#1| put by us become the % secong argument of |\gmd@in@@|. What |\gmd@in@@| does with its % arguments, is just a~check whether the second one is empty. This may % happen \emph{iff} the investigated char hasn't been found among the % MakeIndex controls' list and then |\gmd@in@@| shall expand to % |\iffalse|, otherwise it'll expand to |\iftrue|. (The |\after...| % macros are employed not to (mis)match just got |\if...| with the % test's |\fi|.) ``(Deep breath.) You got that?'' If not, try % \docfm's explanation of |\ifnot@excluded|, pp.\,36--37 of the v2.1b % dated 2004/02/09 documentation, where a~similar construction is % attributed to Michael Spivak. % % Since version 0.99g |\gmd@ifinmeaning| is used also in testing % whether a~detector is already present in the carrier in the % mechanism of automatic detection of definitions (line \ref{550}). \newif\ifgmd@glosscs% we use this switch to keep the information % whether a~history entry is a~CS or not. \newcommand*\finish@macroscan{%\label{506}\par % First we check if the current CS is not just being defined. The % switch may be set true in line \ref{519} \ifgmd@adef@cshook% if so, we throw it into marginpar and index as % a~def entry\dots \@ifundefined{gmd/iexcl/\macro@pname}{% \dots\ if it's not excluded % from indexing. \@xa\Code@MarginizeMacro\@xa{\macro@pname}% \@xa\@defentryze\@xa{\macro@pname}{1}}{}%% here we declare the kind of % index entry and define |\last@defmark| used by \cs{changes} \global\gmd@adef@cshookfalse% we falsify the hook that was set % true just for this CS. \fi % We have the CS's name for indexing in |\macro@iname| and % for print in |\macro@pname|. So we index it. We do it a~bit % countercrank way because we wish to use more general indexing % macro. \if\verbatimchar\macro@pname% \label{3039}it's important that |\verbatimchar| % comes before the macro's name: when it was reverse, the |\tt| CS % turned this test true and left the |\verbatimchar| what resulted % with `|\+tt|' typeset. Note that this test should turn true iff % the scanned macro name shows to be the default % |\verb|'s delimiter. In such a~case we give % |\verb| another delimiter, namely |$|: \def\im@firstpar{[$]}%^^A$ \else\def\im@firstpar{}\fi \@xa \index@macro\im@firstpar\macro@iname\macro@pname % \label{3049} \maybe@marginpar\macro@pname \macro@pname \let\next\gmd@charbychar \gmd@detectors% \label{519} for automatic detection of % definitions. Defined and % explained in the next section. It redefines % |\next| if detects a~definition command amd thus % sets the switch of line \ref{506} true. \next } % Now, the~macro that checks whether the just scanned macro should be % put into a~marginpar: it checks the meaning of a~very special CS: % whose name consists of |gmd/2marpar/| and of the examined macro's % name. \def\maybe@marginpar#1{% %^^A\ifx#1\mname@tomarginpar \@ifundefined{gmd/2marpar/#1}{}{% \@xa\Text@Marginize\@xa{\bslash#1}% |\expandafter|s % \possfil because the |\Text@Marginize| command applies |\string| to its % argument. \inverb |\macro@pname|, which will be the only possible % argument to % \cs{may\+be\+@mar\+g\+in\+par}, % contains the macro's name % without the escapechar so we added it here. % ^^A\gdef\mname@tomarginpar{} \@xa\g@relaxen\csname gmd/2marpar/#1\endcsname% we reset the switch. }} % Since version 0.99g we introduce automatic detection of definitions, % it will be implemented in the next section. The details of indexing % CSs are implemented in the section after it. % % \subdivision{Automatic detection of definitions} % % To begin with, let's introduce a~general declaration of a~defining % command. |\DeclareDefining| comes in two flavours: `saut\eacute', % and with star. The `saut\eacute' version without an optional % argument declares a~defining command of the kind of |\def| and % |\newcommand|: whether wrapped in braces or not, its main argument % is a~CS. The star 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 |star|. It determines whether the % 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 the |star| key is % omitted. % % Another key is |type|. Its possible values are the (backslashless) % names of the defining commands, see below. % % We provide now more keys for the \pk{xkeyval}ish definitions: % |KVpref| (the key prefix) and |KVfam| (the key family). If not set by % the user, they are assigned the default values as in \pk{xkeyval}: % |KVpref| letters |KV| and |KVfam| the input file name. The latter % assignment is done only for the |\DeclareOptionX| defining command % because in other \pk{xkeyval} definitions (|\define@(...)key|) the % family is mandatory. % %\stanza % Let's make a~version of |\@ifstar| that would work with % |*|\catletter. It's analogous to |\@ifstar|. \foone{\catcode`\*=11 } {\def\@ifstarl#1{\@ifnextchar *{\@firstoftwo{#1}}}} % % \subsubdivision{\cs{DeclareDefining} and the detectors} % % Note that the main argument of the next declaration should be a~CS % \emph{without star}, unless you wish to declare only the starred % version of a~command. The effect of this command is always global. \outer\def\DeclareDefining{\begingroup \MakePrivateLetters \@ifstarl {\gdef\gmd@adef@defaulttype{text}\Declare@Dfng}% {\gdef\gmd@adef@defaulttype{cs}\Declare@Dfng}% } % The keys except |star| depend of |\gmd@adef@currdef|, therefore we % set them having known both arguments \newcommand*\Declare@Dfng[2][]{% \endgroup \Declare@Dfng@inner{#1}{#2}% \ifgmd@adef@star% this swith may be set false in first % \inverb|\Declare@Dfng@inner| (it's the |star| key). \Declare@Dfng@inner{#1}{#2*}% The catcode of |*| doesn't matter since % it's in \inverb|\csname|\nlpercent\dots\inverb|\endcsname| % everywhere. \fi} % \Define\gmd@adef@currdef \def\Declare@Dfng@inner#1#2{% \edef\gmd@resa{% \@nx\setkeys[gmd]{adef}{type=\gmd@adef@defaulttype}}% \gmd@resa {\escapechar\m@ne \xdef\gmd@adef@currdef{\string#2}% }% \gmd@adef@setkeysdefault \setkeys[gmd]{adef}{#1}% \@xa\gmd@ifinmeaning \csname gmd@detect@\gmd@adef@currdef\endcsname % \label{550} \of\gmd@detectors{}{% \@xa\gaddtomacro\@xa\gmd@detectors\@xa{% \csname gmd@detect@\gmd@adef@currdef\endcsname}}% we add a~CS\\ % |%| |\gmd@detect@|\ (a~\textbf{detector})to the % meaning of the \textbf{detectors' carrier}. And we define it to % detect the \inverb|#2| command. \@xa\xdef\csname gmd@detectname@\gmd@adef@currdef\endcsname{% \gmd@adef@currdef}% \edef\@tempa{% this |\edef| is to expand |\gmd@adef@TYPE|. \global\@nx\@namedef{gmd@detect@\gmd@adef@currdef}{% \@nx\ifx \@xa\@nx\csname gmd@detectname@\gmd@adef@currdef\endcsname \@nx\macro@pname \@nx\n@melet{next}{gmd@adef@\gmd@adef@TYPE}% \@nx\n@melet{gmd@adef@currdef}{gmd@detectname@\gmd@adef@currdef}% \@nx\fi}}% \@tempa \SMglobal\StoreMacro*{gmd@detect@\gmd@adef@currdef}% we store the CS to % allow its temporary discarding later. } \def\gmd@adef@setkeysdefault{% \setkeys[gmd]{adef}{star,prefix,KVpref}} % Note we don't set |KVfam|. We do not so because for % |\define@key|-likes family is a~mandatory argument and for % |\DeclareOptionX| the default family is set to the input file name % in line \ref{defDOXfam}. \define@boolkey[gmd]{adef}{star}[true]{} % The |prefix@|\ keyvalue will be used to create additional % index entry for detected definiendum (a~\textbf{definiendum} is the % thing defined, e.g. in |\newenvironment{foo}| the env.\ \env{foo}). % For instance, |\newcounter| is declared with |[prefix=\bslash c@]| % in line \ref{newcounter} and therefore |\newcounter{foo}| occurring % in the code will index both |foo| and |\c@foo| (as definition % entries). \UnDef \define@key[gmd]{adef}{prefix}[]{% \edef\gmd@resa{% \def\@xa\@nx\csname gmd@adef@prefix@\gmd@adef@currdef \endcsname{% #1}}% \gmd@resa} \def\gmd@KVprefdefault{KV}% in a~separate macro because we'll need % it in \cs{ifx}. % A~macro |\gmd@adef@KVprefixset@|\ if defined, will falsify % an \cs{ifnum} test that will decide whether create additional index % entry together with the tests for |prefix|\ and % \UnDef \define@key[gmd]{adef}{KVpref}[\gmd@KVprefdefault]{% \edef\gmd@resa{#1}% \ifx\gmd@resa\gmd@KVprefdefault \else \@namedef{gmd@adef@KVprefixset@\gmd@adef@currdef}{1}% \gmd@adef@setKV% whenever the |KVpref|fix is set (not default), the % declared command is assumed to be \pk{keyval}ish. \fi \edef\gmd@resa{#1}% because |\gmd@adef@setKV| redefined it. \edef\gmd@resa{% \def\@xa\@nx\csname gmd@adef@KVpref@\gmd@adef@currdef\endcsname{% \ifx\gmd@resa\empty \else#1@\fi}}% as in \pk{xkeyval}, if the KV prefix is not % empty, we add \inverb|@| to it. \gmd@resa} % Analogously to |KVpref|, |KVfam| declared in |\DeclareDefining| % will override the family scanned from the code and, in % |\DeclareOptionX| case, the default family which is the input file % name (only for the command being declared). \define@key[gmd]{adef}{KVfam}[]{% \edef\gmd@resa{#1}% \@namedef{gmd@adef@KVfamset@\gmd@adef@currdef}{1}% \edef\gmd@resa{% \def\@xa\@nx\csname gmd@adef@KVfam@\gmd@adef@currdef\endcsname{% \ifx\gmd@resa\empty \else#1@\fi}}% \gmd@resa \gmd@adef@setKV}% whenever the |KVfam|ily is set, the declared command is % assumed to be \pk{keyval}ish. \define@choicekey[gmd]{adef}{type} [\gmd@adef@typevals\gmd@adef@typenr] {% the list of possible types of defining commands def, newcommand, cs,% equivalent to the two above, covers all the cases of defining % a~CS, including the \PlainTeX\ \inverb|\new...| and % \LaTeX\ |\newlength|. newenvironment, text,% equivalent to the one above, covers all the commands defining % its first mandatory argument that should be text, % \inverb|\DeclareOption| e.g. define@key,% special case of more arguments important; covers the % \pk{xkeyval} defining commands. dk,% a~shorthand for the one above. DeclareOptionX,% another case of special arguments configuration, % covers the \pk{xkeyval} homonym. dox,% a~shorthand for the one above. kvo% one of option defining commands of the \pk{kvoptions} package % by Heiko Oberdiek (a~package available o~CTAN in the % \pk{oberdiek} bundle). } {% In fact we collapse all the types just to four so far: \ifcase\gmd@adef@typenr% if |def| \gmd@adef@settype{cs}{0}% \or% when |newcommand| \gmd@adef@settype{cs}{0}% \or% when |cs| \gmd@adef@settype{cs}{0}% \or% when |newenvironment| \gmd@adef@settype{text}{0}% \or% when |text| \gmd@adef@settype{text}{0}% \or% when |define@key| \gmd@adef@settype{dk}{1}% \or% when |dk| \gmd@adef@settype{dk}{1}% \or% when |DeclareOptionX| \gmd@adef@settype{dox}{1}% \or% when |dox| \gmd@adef@settype{dox}{1}% \or% when |kvo| \gmd@adef@settype{text}{1}%% The \pk{kvoptions} option %% definitions take first mandatory % argument as the option name and they define a~\pk{keyval} key % whose macro's name begins with the prefix/family, either default or % explicitly declared. The \pk{kvoptions} prefix/family is % supported in \pk{gmdoc} with \inverb|[KVpref=, KVfam=|\|]|. \fi} \def\gmd@adef@settype#1#2{% \def\gmd@adef@TYPE{#1}% \ifnum1=#2 % now we define (or not) a~quasi-switch that fires for % the \pk{keyval}ish definition commands. \gmd@adef@setKV \fi} \def\gmd@adef@setKV{% \edef\gmd@resa{% \def\@xa\@nx\csname gmd@adef@KV@\gmd@adef@currdef\endcsname{1}% }% \gmd@resa} % We initialize the carrier of detectors: \emptify\gmd@detectors % The definiendum of a~command of the |cs| type is the next control % sequence. Therefore we only need a~self-relaxing hook in % |\finish@macroscan|. \newif\ifgmd@adef@cshook \def\gmd@adef@cs{\global\gmd@adef@cshooktrue\gmd@charbychar} % For other kinds of definitions we'll employ active chars of their % arguments' opening braces, brackets and seargants. In \pk{gmdoc} % code layer scopes the left brace is active so we only add a~hook to % its meaning (see line \ref{gm@lbracehook} in \pk{gmverb}) and \ref and here % we switch it according to the type of detected definition. \def\gmd@adef@text{\gdef\gmd@lbracecase{1}\gmd@charbychar} \foone{% \catcode`\[\active % ^^A>\] \catcode`\<\active} {%\par % The detector of \pk{xkeyval} |\define@(...)key|: \def\gmd@adef@dk{% \let[\gmd@adef@scanKVpref \catcode`\[\active % ^^A\]] \gdef\gmd@lbracecase{2}% \gmd@adef@dfKVpref\gmd@KVprefdefault% We set the default value of % the \pk{xkeyval} prefix. Each time again because an assignment % in \inverb|\gmd@adef@dfKVpref| is global. \gmd@adef@checklbracket} % The detector of \pk{xkeyval} |\DeclareOptionX|: \def\gmd@adef@dox{% \let[\gmd@adef@scanKVpref \let<\gmd@adef@scanDOXfam \catcode`[\active % ^^A]] \catcode`<\active \gdef\gmd@lbracecase{1}% \gmd@adef@dfKVpref\gmd@KVprefdefault% We set the default values of % the \pk{xkeyval} prefix\dots \edef\gmd@adef@fam{\gmd@inputname}% \dots\ and family. \gmd@adef@dofam % \label{defDOXfam} \gmd@adef@checkDOXopts}% } % The case when the right bracket is next to us is special because it % is already touched by |\futurelet| (of CSs scanning macro's % \cs{@ifnextcat}), therefore we need a~`future' test. \def\gmd@adef@checklbracket{% \@ifnextchar[{\gmd@adef@scanKVpref}\gmd@charbychar}% note that % the prefix scanning macro gobbles its first argument (undelimited) % which in this case is |[|. %^^A]]} % After a~|\DeclareOptionX|-like defining command not only the prefix % in square brackets may occur but also the family in % seargants. Therefore we have to test presence of both of them. \def\gmd@adef@checkDOXopts{% \@ifnextchar[{\gmd@adef@scanKVpref}%^^A}] {\@ifnextchar<{\gmd@adef@scanDOXfam}\gmd@charbychar}} %^^A[ \def\gmd@adef@scanKVpref#1#2]{% \gmd@adef@dfKVpref{#2}% [#2]\gmd@charbychar} \def\gmd@adef@dfKVpref#1{% \ifnum1=0\csname gmd@adef@KVprefixset@\gmd@adef@currdef\endcsname \relax \else \edef\gmu@resa{% \gdef\@xa\@nx \csname gmd@adef@KVpref@\gmd@adef@currdef\endcsname{% \ifx\relax#1\relax \else#1@% \fi}}% \gmu@resa \fi} \def\gmd@adef@scanDOXfam{% \ifnum12=\catcode`\>\relax \let\next\gmd@adef@scanfamoth \else \ifnum13=\catcode`\>\relax \let\next\gmd@adef@scanfamact \else \PackageError{gmdoc}{> neither `other' nor `active'! Make it `other' with \bslash AddtoPrivateOthers\bslash\>.}% \fi \fi \next} \def\gmd@adef@scanfamoth#1>{% \edef\gmd@adef@fam{\@gobble#1}% there is always % \cs{gmd@charbychar} first. \gmd@adef@dofam <\gmd@adef@fam>% \gmd@charbychar} \foone{\catcode`\>\active} {\def\gmd@adef@scanfamact#1>{% \edef\gmd@adef@fam{\@gobble#1}% there is always % \cs{gmd@charbychar} first. \gmd@adef@dofam <\gmd@adef@fam>% \gmd@charbychar}% } % The hook of the left brace consists of \cs{ifcase} that logically % consists of three subcases: % \begin{itemize}^^B % \item [0]---the default: do nothing in particular; % \item [1]---the detected defining command has one mandatory % argument (is of the |text| type, including \pk{kvoptions} option definition); % \item [2--3]---we are after detection of a~|\define@key|-like command % so we have to scan \emph{two} mandatory arguments (case 2 is for % the family, case 3 for the key name). % \end{itemize} % % \def\gm@lbracehook{% \ifcase\gmd@lbracecase\relax \or% when 1 \afterfi{% \gdef\gmd@lbracecase{0}% \gmd@adef@scanname}% \or% when 2---the first mandatory argument of two (|\define@(...)key|) \afterfi{% \gdef\gmd@lbracecase{3}% \gmd@adef@scanDKfam}% \or% when 3---the second mandatory argument of two (the key name). \afterfi{% \gdef\gmd@lbracecase{0}% \gmd@adef@scanname}% \fi} \def\gmd@lbracecase{0}% we initialize the hook caser. % And we define the inner left brace macros: \foone{\catcode`\[1 \catcode`\]2 \catcode`\}12 } [% Note that till line \ref{738} the square brackets are grouping % and the right brace is `other'. ^^A{ %\par Define the macro that reads and processes the |\define@key| %family argument. It has the parameter delimited with `other' right %brace. An active left brace that has launched this macro had been %passed through iterating |\gmd@charbychar| that now stands next right %to us. \def\gmd@adef@scanDKfam#1}[%^^A{ \edef\gmd@adef@fam[\@gobble#1]% there is always % \cs{gmd@charbychar} first. \gmd@adef@dofam \gmd@adef@fam}% \gmd@charbychar] % ^^A{ \def\gmd@adef@scanname#1}[%^^A{ \@makeother\[%^^A\] \@makeother\<% % The scanned name begins with |\gmd@charbychar|, we have to be % careful. \gmd@adef@deftext[#1]% \@gobble#1}% \gmd@charbychar] ] \def\gmd@adef@dofam{% \ifnum1=0\csname gmd@adef@KVfamset@\gmd@adef@currdef\endcsname \relax% a~family declared with |\DeclareDefining| overrides the % one currently scanned. \else \edef\gmu@resa{% \gdef\@xa\@nx \csname gmd@adef@KVfam@\gmd@adef@currdef\endcsname {\ifx\gmd@adef@fam\empty \else\gmd@adef@fam @% \fi}}% \gmu@resa \fi} \def\gmd@adef@deftext#1{% \edef\macro@pname{\@gobble#1}% we gobble |\gmd@charbychar|, cf. above. \@xa\Text@Marginize\@xa{\macro@pname}% \gmd@adef@indextext \edef\gmd@adef@altindex{% \csname gmd@adef@prefix@\gmd@adef@currdef \endcsname}% %\hskip-\parindent and we add the \pk{xkeyval} header if we are in \pk{xkeyval} % definition. \ifnum1=0\csname gmd@adef@KV@\gmd@adef@currdef \endcsname\relax% The\\ CS % \inverb|\gmd@adef@KV@|\ is defined |{1}| (so \cs{ifnum} % gets |1=01\relax|---\hskip0sptrue) iff \ is a~\pk{keyval} % definition. In that case we check for the \inverb|KVpref|ix and % \inverb|KVfam|ily. (Otherwise |\gmd@adef@KV@|\ is undefined % so \cs{ifnum} gets |1=0\relax|---false.) \edef\gmd@adef@altindex{% \gmd@adef@altindex \csname gmd@adef@KVpref@\gmd@adef@currdef \endcsname}% \edef\gmd@adef@altindex{% \gmd@adef@altindex \csname gmd@adef@KVfam@\gmd@adef@currdef \endcsname}% \fi \ifx\gmd@adef@altindex\empty \else% we make another index entry of the definiendum with prefix/KVheader. \edef\macro@pname{\gmd@adef@altindex\macro@pname}% \gmd@adef@indextext \fi} \def\gmd@adef@indextext{% \@xa\@defentryze\@xa{\macro@pname}{0}% declare the definiendum has to % have a~definition entry and in the changes history should appear % without backslash. \gmd@doindexingtext% redefine |\do| to an indexing macro. % \label{gmd@doindexingtext 2nd use} \@xa\do\@xa{\macro@pname}} %^^A %\iffalse if we decided to manage \verbatimchar %^^A \iffalse %^^A \if\verbatimchar\macro@pname% cf. lines \ref{3039}--\ref{3049} %^^A \def\im@firstpar{[$]}%^^A$ %^^A \else\def\im@firstpar{}% %^^A \fi %^^A \@xa \index@macro\im@firstpar\macro@iname\macro@pname %^^A \fi %^^A %\fi %^^A % % \stanza % So we have implemented automatic detection of definitions. Let's now % introduce some. % % \subsubdivision{Default defining commands} % Some commands are easy to declare as defining: % \HideAllDefining % \DeclareDefining\DeclareDefining %^^A\DeclareDefining[type=dox, star=false]\def \DeclareDefining[star=false]\def %^^A\show\gmd@detectors % \ResumeAllDefining But |\def| definitely \emph{not always} defines % an important macro. Sometimes it's just a~scratch assignment. % Therefore we define the next declaration. It turns the next % occurence of |\def| off (only the next one). \def\UnDef{% \gdef\gmd@detect@def{% \ifx\gmd@detectname@def\macro@pname \def\next{\SMglobal\RestoreMacro\gmd@detect@def}% ^^A we define % ^^A \inverb|\next| not restore the macro here just in case of % ^^A multiple declaration of |\def| (in that case there would be % ^^A multiple occurences of the macro to be restored in the carrier % ^^A \inverb|\gmd@detectors| and we wish % ^^A all of them not to fire this one time) That's probably too % ^^A much care since there's the test in line \ref{550}. \fi}% } \StoreMacro\UnDef% because the `hiding' commands relax it. \def\HideDef{\HideDefining\def\relaxen\UnDef} \def\ResumeDef{\ResumeDefining\def\RestoreMacro\UnDef} % Note that I~\emph{don't} declare |\gdef|, |\edef| neither % |\xdef|. In my opinion their use as `real' definition is very rare % and then you may use |\Define| implemented later. % \HideAllDefining \DeclareDefining\DeclareDefining \DeclareDefining[star=false]\newcount \DeclareDefining[star=false]\newdimen \DeclareDefining[star=false]\newskip \DeclareDefining[star=false]\newif \DeclareDefining[star=false]\newtoks \DeclareDefining[star=false]\newbox \DeclareDefining[star=false]\newread \DeclareDefining[star=false]\newwrite \DeclareDefining[star=false]\newlength \DeclareDefining\newcommand \DeclareDefining\renewcommand \DeclareDefining\providecommand \DeclareDefining\DeclareRobustCommand \DeclareDefining\DeclareTextCommand \DeclareDefining\DeclareTextCommandDefault \DeclareDefining*\newenvironment \DeclareDefining*\renewenvironment \DeclareDefining*\DeclareOption %|%\DeclareDefining*\@namedef| % \HideDefining\DeclareDefining % \DeclareDefining\bslash \DeclareDefining*[prefix=\bslash c@]\newcounter% \label{newcounter} % this prefix provides indexing also |\c@|\. \DeclareDefining[type=dk, prefix=\bslash]\define@key \DeclareDefining[type=dk, prefix=\bslash if]\define@boolkey% the % alternate index entry will be % \cs{if}\|@|\|@|\ \DeclareDefining[type=dk, prefix=\bslash]\define@choicekey \DeclareDefining[type=dox, prefix=\bslash]\DeclareOptionX% the % alternate index entry will be \cs{}\|@|\|@|\ %\PrintChanges \PrintIndex % % %^^A~place for general changes: % \ChangesGeneral % % \changes{v0.98a}{06/09/06}{\cs{AtBeginput}, \cs{AtEndinput}, % \cs{AtBeginputOnce} renamed to \cs{AtBegInput}, \cs{AtEndInput} % \cs{AtBegInputOnce} respect.} % % \changes{v0.98c}{06/9/9}{making \cs{Define} and \cs{CodeUsage} % markers to add up; bug fixes in indexing macros and change of % concept of \cs{Code(Define$\quotechar|$Usage)*}: hence they serve not only for % environments but also for implicit def/use of macros} % % \changes{v0.98d}{06/9/11}{mostly editing the narrative, marking % special index entries etc.; queering \cs{char1} and \cs{char2} % repeated \cs{AtBegInput}} % % \changes{v0.98e}{06/09/24}{Some macros moved to \pk{gmutils}: % \cs{cs} and pals and one-chars with queer \cs{catcode}s} % % \changes{v0.98f}{06/09/27}{A~bug fixed: \cs{Code@MarginizeMacro} set % to define a~CS and the corresponding test set to check if it's % undefined. In all three such definitions and resets after the use, % \cs{def} is changed to \cs{(g)let}} % % \changes{v0.98g}{06/10/10}{among others, \cs{discretionary}s for breaking % a~CS to percent at the beginning of the lower line. Moreover, fixing % a~bug/feature that leaves the code leftskip in the narration when an % inline comment is followed by another codeline (w.o.\ explicit % \cs{par}). And lots of finishing touches to the text. A~special font % for the marginpar CSs among others} % % \changes{v0.98l}{06/10/26}{in \cs{AtBegInputOnce} an auxiliary macro % for each use substituted with one macro added at begin input. In % \cs{gmd@evpaddonce} a~counter substituted with a~numeric % macro. \cs{@ifQueerEOL} made polite i.e., a~two-argument not % expanding to an open \cs{if...}} % % \changes{v0.99}{06/11/24}{\env{oldmc(*)} implemented that's % (hope)fully compatible with \docfm's \env{macrocode(*)}. Moreover, % a~declaration letting \gmdoc's \env{macrocode} to \env{oldmc(*)}} % % \changes{v0.99a}{06/11/30}{The \ds\ directives implemented fully % automatic (no more need of \cs{doctrip(s)} declarations). Moreover, % some minor changes due to \TeX ing The Source.} % % \changes{v0.99b}{2007/01/01}{Thanks to the \cs{edverbs} declaration % in the class, displayed shortverbs simplified; Emacs mode changed to % doctex. Author's true name more exposed} % % \changes{v0.99c}{2007/03/02}{A~bug fixed in \cs{DocInput} and all % \cs{expandafter}s changed to \cs{@xa} and \cs{noexpand}s to % \cs{@nx}} % % \changes{v0.99c}{2007/03/12}{The \TeX-related logos now are declared % with \cs{DeclareLogo} provided in \pk{gmutils}} % % \changes{v0.99d}{2007/04/13}{\cs{afterfi} \& pals made two-argument} % % \changes{v0.99d}{2007/04/24}{\cs{@namelet} renamed to \cs{n@melet} % to solve a~conflict with the \pk{beamer} class (in \pk{gmutils} at % first)} % % \changes{v0.99e}{2007/04/29}{a~bug fixed in \cs{DocInput} and % \cs{IndexInput}} % % \changes{v0.99g}{2007/11/12}{The bundle goes \XeTeX. The % \TeX-related logos now are moved to \pk{gmutils}. \hathat{A} % becomes more comment-like thanks to re\cs{catcode}'ing. Automatic % detection of definitions implemented} % % \changes{v0.99h}{2007/11/16}{Fixed behaviour of sectioning commands % (optional two heading skip check) of \pk{mwcls/gmutils} and % respective macro added in \pk{gmdocc}. I~made a~\file{tds} archive} % % % \Finale % (For my GNU Emacs:) %%% Local Variables: %%% mode: doctex %%% TeX-master: "../../../../LaTeX/TeXGuru/gmdoc/gmdocDoc.tex" %%% End: