% % \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, 2008 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. %% %% \acro{LPPL} status: "author-maintained".\par %% %% Many thanks to my \TeX\ Guru Marcin Woli\nacute ski for his \TeX nical ^^A %% support. % %\end{copyrnote} % % \ChangesStart{v0.98c}{1000/0/0} % % \chschange{v0.96}{2006/08/22}{2395} % \chschange{v0.97}{06/09/04}{3636} % \chschange{v0.98}{06/09/04}{3636} % \chschange{v0.98a}{06/09/06}{4092} % \chschange{v0.98b}{06/9/7}{4119} % \chschange{v0.98c}{06/9/10}{4299} % \chschange{v0.98d}{06/9/15}{4409} % \chschange{v0.98e}{06/9/23}{4420} % \chschange{v0.98f}{06/9/30}{4430} % \chschange{v0.98g}{06/10/5}{4294} % \chschange{v0.98i}{06/10/14}{4352} % \chschange{v0.98j}{06/10/17}{4372} % \chschange{v0.98k}{06/10/21}{4416} % \chschange{v0.98l}{06/10/27}{4401} % \chschange{v0.98m}{06/11/14}{4349} % \chschange{v0.99}{06/11/29}{4462} % \chschange{v0.99a}{2006/12/01}{4479} % \chschange{v0.99b}{07/01/01}{4479} % \chschange{v0.99c}{07/3/2}{4486} % \chschange{v0.99c}{07/3/30}{4475} % \chschange{v0.99d}{07/4/26}{4555} % \chschange{v0.99e}{2007/4/29}{4574} % \chschange{v0.99g}{2007/11/12}{5229} % \chschange{v0.99i}{2008/8/3}{5247} % \chschange{v0.99j}{2008/8/3}{5266} % \chschange{v0.99k}{2008/8/4}{5261} % \chschange{v0.99l}{2008/8/6}{5225} % \chschange{v0.99m}{2008/8/9}{5356} % \chschange{v0.99m}{2008/8/13}{5354} % \chschange{v0.99n}{2008/8/22}{5409} % \chschange{v0.99n}{2008/8/30}{5547} % \chschange{v0.99p}{2008/10/4}{5607} % \chschange{v0.99q}{2008/10/10}{5603} % \chschange{v0.99r}{2008/11/22}{5607} % \toCTAN{v0.99r}{2008/11/22} % % \ifnum\catcode`\@=11 % Why this test here---will come out in chapter % \gmiflink{The driver}. ^^A~( the very first line % ^^A and about coming out already! ;-) \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{gmdoc} [2008/11/22 v0.99r a documenting package (GM)] \fi % % % % \CharacterTable {In my \TeX\ Guru's opinion the idea of % checking of the correctness of chars is a~bit obsolete % nowadays. Therefore I~define the \CharacterTable<#1> % macro to gobble its argument and to typeout a~request % for request.} % % % \newcommand*\docfm{\pk{doc}} % \newcommand*\gmdoc{\pk{gmdoc}} % % \tableofcontents % % % \division{Readme} % % This package is a~tool for documenting of \LaTeXpar\ % packages, classes etc., i.e., the \file{.sty}, \file{.cls} files % etc. The author just writes the code and adds the commentary % preceded with |%| sign (or another properly declared). No special % environments are necessary. % % The package tends to be (optionally) compatible with the standard % \pk{doc.sty} package, % i.e., the \file{.dtx} files are also compilable with \pk{gmdoc} % (they may need 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. And % you \emph{have} to use four of them to make \pk{gmdoc} work.) % % You should also install \pk{gmverb.sty}, \pk{gmutils.sty} and % \pk{gmiflink.sty} (e.g., put them into the same \file{gm} % directory). These packages are available on \acro{CTAN} as separate % \file{.zip} archives also in \acro{TDS}-compliant \pk{zip} % archives. % % Moreover, you should put the \file{gmglo.ist} file, a MakeIndex % style for the changes' history, into some \file{texmf/makeindex} % (sub)directory. % % Then you should refresh your \TeX\ distribution's files' database % most probably. % \end{gmlonely} % % % \subdivision{Contents of the \pk{gmdoc.zip} archive} % % The distribution of the \pk{gmdoc} package consists of the % following five files and a~\acro{TDS}-compliant archive. % \begin{verse} % \pk{gmdoc.sty}\\ % \pk{gmdocc.cls}\\ % \pk{gmglo.ist}\\ % \pk{README}\\ % \pk{gmdoc.pdf}\\ % \pk{gmdoc.tds.zip} % \end{verse} % % % \begin{gmlonely} % \subdivision{Compiling of the documentation} % % The last of the above files (the \pk{.pdf}, i.e., \emph{this ^^B % file}) is a~documentation compiled from the \pk{.sty} and % \pk{.cls} files by running \XeLaTeX\ on the \file{gmdoc.sty} % twice (|xelatex gmdoc.sty| in the directory you wish the % documentation to be in, you don't have copy the \file{.sty} file % there, \TeX\ will find it), then MakeIndex on the \file{gmdoc.idx} and % \file{gmdoc.glo} files, and then \XeLaTeX\ on \file{gmdoc.sty} % once more. (Using \LaTeX\ instead of \XeLaTeX\ should do, too.) % % MakeIndex shell commands: %\begin{verbatim} %makeindex -r gmdoc %makeindex -r -s gmglo.ist -o gmdoc.gls gmdoc.glo %\end{verbatim} % The |-r| switch is to forbid MakeIndex to make implicit ranges since % the (code line) numbers will be hyperlinks. % % Compiling the documentation requires the packages: % \pk{gmdoc} (\pk{gmdoc.sty} and \pk{gmdocc.cls}), \pk{gmutils.sty}, % \pk{gmverb.sty}, \pk{gmiflink.sty} and also some standard packages: % \pk{hyperref.sty}, \pk{xcolor.sty}, \pk{geometry.sty}, % \pk{multicol.sty}, \pk{lmodern.sty}, \pk{fontenc.sty} that should % be installed on your computer by default. % % If you had not installed the \pk{mwcls} classes (available on % \acro{CTAN} and present in \TeX\ Live e.g.), the result of your % compilation might differ a~bit from the \pk{.pdf} provided in this % \pk{.zip} archive in formatting: If you had not installed % \pk{mwcls}, the standard \pk{article.cls} class would be used. % \end{gmlonely} % % \subdivision{Dependencies} % % The \pk{gmdoc} bundle depends on some other packages of mine: % \begin{verse} % \pk{gmutils.sty},\\ % \pk{gmverb.sty},\\ % \pk{gmiflink.sty}\\ % \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. % %^^A\traceon % % \subdivision{Bonus: \file{base} drivers} %^^A\traceoff % As a~bonus and example of \docfm-compatibility % there are driver files included % (cf.\ Palestrina, \textit{Missa papae Marcelli} ;-): % % \begin{verse} % \pk{source2e_gmdoc.tex}\\ % \pk{docstrip_gmdoc.tex}\\ % \pk{doc_gmdoc.tex} % % \pk{gmoldcomm.sty}\\ % (\pk{gmsource2e.ist} is generated from \pk{source2e_gmdoc.tex})\\ % \end{verse} % % These drivers typeset the respective files from the %\[\hbox{\file{…/texmf-dist/source/latex/base}}\] % directory of the \TeX Live2007 distribution (they only read that % directory). % % Probably you should redefine the |\BasePath| macro in them % so that it points that directory on your computer. % % %\division*{Introduction} % % There are very sophisticated and effective tools for documenting % \LaTeX\ macro packages, namely the \pk{doc} package and the % \pk{ltxdoc} class. % Why did I~write another documenting package then? % % I~like comfort and \pk{doc} is not comfortable enough for me. It % requires special marking of the macro code to be properly typeset % when documented. I~want \TeX\ to know `itself' where the code begins % and ends, without additional marks. % % That's the difference. One more difference, more important for the % people for whom the \docfm's conventions are acceptable, is that % \gmdoc\ makes use of \pk{hyperref} advantages and makes % a~hyperlinking index and toc entries and the % cross-references, too. (The \CSs in the code maybe in the future.) % % The rest is striving to level the very high \pk{doc/ltxdoc}'s % standard, such as (optional) numbering of the codelines and % 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 % |#|\<digit>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{|\<\CS>|}|. % % Talking of declarations, I'll use the \textbf{\acro{OCSR}} acronym as % a~shorthand for 'observes/ing common \TeX\ scoping rules'. % % By a~\textbf{command} I~mean a~certain abstract visible to the end % user as a~\CS but consisting possibly of more than one macro. I'll % talk of a~\textbf{command's argument} also in % the `sense\:-for\:-the\:-end\:-user', e.g., I'll talk of the % |\verb| \emph{command's} argument although \emph{the macro} % |\verb| has no |#|\<digit> in its definition. % % The \textbf{code} to be typeset verbatim (and with all the bells % and whistles) is everything that's not commented out in the source % file and what is not a~leading space(s). % % The \textbf{commentary} or \textbf{narrative} is everything after % the comment char till the end of a~line. The \textbf{comment char} % is a~character the |\catcode| of which is 14 usually i.e., when the % file works; if you don't play with % the |\catcode|s, it's just the |%|. When the file is documented with % \gmdoc, such a~char is re|\catcode|d and its r\ocircum le is else: it % becomes the \textbf{code delimiter}. % % A~line containing any \TeX\ code (not commented out) will be called % a~\textbf{codeline}. A~line that begins with (some leading spaces % and) a~code delimiter will be called a~\textbf{comment line} or % \textbf{narration line}. % % The \textbf{user} of this package will also be addressed % as \textbf{you}.\stanza % % Not to favour any particular gender (of the amazingly rich variety, % I~mean, not of the vulgarly simplified two-element set), in this % documentation I~use alternating pronouns of third person ^^A( % (\TextUsage\heshe\ etc. commands provided by \pk{gmutils}), so let % one be not surprised if `\heshe' sees `\himher self' altered in the % same sentence :-)\,. % % % \subdivision{Preparing of the source file} % % When \LaTeXpar\ with \pk{gmdoc.sty} package loaded typesets the % comment lines, the code delimiter is 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*{\^^M} (|\|\<line end>) or with % \TextUsage*{^^B} sequence that'll enter the (active) \<char2> which % shall gobble the line end. ^^A~and the leading code delimiter of %^^A % the next line---obsoleted by ^^A~making % ignored in the commentary. % % 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 % \<char1>, which % in \gmdoc\ is active and defined to gobble the stuff between itself % and the line end. % % Note that |^^A| behaves much like comment char % although it's active in fact: it re|\catcode|s the special % characters including |\|, |{| and |}| % so you don't have to worry about unbalanced braces or \cs{if}s in % its scope. But |^^B| doesn't re|\catcode| anything (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 % \acro{OCSR}. As almost all the control % sequences, it may be used also as an environment, i.e., % |\begin{StraightEOL}|\ \dots\ |\end{StraightEOL}|. However, if for any % reason you don't want to make an environment (a~group), there's % a~|\StraightEOL|'s counterpart, the \TextUsage\QueerEOL\ declaration that % restores again the % \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 \acro{OCSR}, too. One more point to use % |\StraightEOL| is where you wish some code lines to be executed % both while loading the file and during the documentation pass % (it's analogous to \docfm's not embracing some code lines in % a~\env{macrocode} environment). % % \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[|\<options>|]{|\<document-class>|}|\par % \noindent|\usepackage[|\<options, probably none>|]{gmdoc}|\par % \<preamble>\par % \noindent|\begin{document}|\par % \<special input commands>\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\label{docinclude:extensions} supported by % |\DocInclude| are \pk{.fdd}, \pk{.dtx}, \pk{.cls}, \pk{.sty}, % \pk{.tex} and \pk{.fd}. The macro looks for one of those extensions % in the order just given. If you need to document files of other % extensions, please let me know and most probably we'll make it % possible. % % |\DocInclude| has also an optional first argument that is intended % to be the path of the included file with the levels separated by |/| % (slash) and also ended with a~slash. The path given to |\DocInclude| as % the first and optional argument will not appear in the headings nor % in the footers. % % |\DocInclude| redefines \TextUsage\maketitle\ so % that it makes a~chapter heading or, in the classes that don't % support |\chapter|, a~part heading, in both cases with % respective toc entries. The default assumption is that all the % files have the same author(s) so there's no need to print them in % the file heading. If you wish the authors names to be printed, you % should write \TextUsage\PrintFilesAuthors\ in the preamble or before % the relevant |\DocInclude|s. If you wish to undeclare printing the % authors names, there is \TextUsage\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|{|\<filenames separated by commas>|}| for % the draft versions. % % \stanza If you want to put the driver into the same \file{.sty} or % \file{.cls} file (see chapter \ref{Driver} to see how), you may % write |\DocInput{\jobname.sty}|, or |\DocInclude{\jobname.sty}|, but % there's also a~shorthand for the latter \TextUsage\SelfInclude \ % that takes no arguments. % By the way, to avoid an infinite recursive input of \file{.aux} % files in the case of self-inclusion an \file{.auxx} file is used % instead of (main) \file{.aux}. % \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 \acro{OCSR}. % % If you wish to document your files as with \pk{ltxdoc} \emph{and} % as with \docfm, you should declare % |\ltxLookSetup| in the preamble \emph{and} |\olddocIncludes|. % % \stanza % Talking of analogies with \pk{ltxdoc}, if you like only the page % layout provided by that class, there is the % \TextUsage\ltxPageLayout\ declaration (allowed only in preamble) % that only changes the margins and the text width (it's intended to % be used with the default paper size). This declaration is % contained in the |\ltxLookSetup| declaration. % % \stanza % If you need to add something at the beginning of the input of file, % there's the \TextUsage\AtBegInput\ declaration that takes one % mandatory argument which is the stuff to be added. This declaration % is global. It may be used more than one time and the arguments of % each occurrence of it add up and are put at the beginning of input % of every subsequent files. % % Simili modo, for the end of input, there's the % \TextUsage\AtEndInput\ declaration, also one-argument, global and % cumulative. % % If you need to add something at the beginning of input of only one % file, put before the respective input command an % \TextUsage\AtBegInputOnce|{|\<the stuff to be added>|}| % 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 \<char1> (|^^A| is \acro{OK}). % % The effect of this command is typesetting of all the input file % verbatim, with the code lines numbered and the \CSs automatically % indexed (\pk{gmdoc.sty} options are in force). % % % \subdivision{Package options} % % As many good packages, this also provides some options: % \stanza % % Due to best \TeX\ documenting traditions the codelines will be % numbered. But if the user doesn't wish that, \heshe\ may turn it off % with the \TextUsage*{linesnotnum} option. % % However, if \heshe\ agrees to have the lines numbered, \heshe\ may wish % to reset the counter of lines \himher self, e.g., when \heshe\ % documents many source files in one document. Then \heshe\ may wish % the line numbers to be reset with every |{section}|'s turn for % instance. This is the r\ocircum le of the \TextUsage*{uresetlinecount} % option, which seems to be a~bit obsolete however, since the % \TextCommonIndex\DocInclude|\DocInclude| command takes care of % a~proper reset. % % Talking of line numbering further, a~tradition seems to exist to % number only the codelines and not to number the lines of % commentary. That's the default behaviour of \pk{gmdoc} but, if % someone wants the comment lines to be numbered too, which may be % convenient for reference purposes, \heshe\ is % provided the \TextUsage*{countalllines} option. This option switches % things to use the \cs{inputlineno} primitive for codeline numbers so % you get the numbers of the source file instead of number only of the % codelines. Note however, that there are no hypertargets made to the % narration lines and the value of \cs{ref} is the number of the most % recent codeline. % % Moreover, if \heshe\ wants to get the narration lines' number % printed, there is the starred version of that option, % \TextUsage*{countalllines*}. I~imagine someone may use it for % debug. This option is not finished in details, it causes errors with % \cs{addvspace} because it puts a~hyperlabel at every line. When it % is in force, all the index entries are referenced % with the line numbers and %% ^^A( % {\LineNumFont 441}\, the narration acquires a~bit biblical look ;-), % {\LineNumFont 442}\,as shown in this short example. This option is intended % {\LineNumFont 443}\,for the draft versions and it is not perfect (as if anything % {\LineNumFont 444}\,in this package was). As you see, the lines % {\LineNumFont 445}\,are typeset continuously with the numbers printed. % % \stanza % By default the \pk{makeidx} package is loaded and 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. % % The references in the change history are of the same: when index is % line number, then the changes history too. % % \stanza % By default, \gmdoc\ excludes some 300 \CSs from being indexed. % They are the most common \CSs, \LaTeX\ internal % macros and \TeX\ primitives. To learn what \CSs are % excluded actually, see lines \ref{DIE1}--\ref{DIE2}. % % If you don't want all those exclusions, you may turn them off with % the \TextUsage*{indexallmacros} option. % % If you have ambiguous feelings about whether to let the default % exclusions or forbid them, see p.\,\pageref{IEIDeclarations} to % feed this ambiguity with a~couple of declarations. % % \stanza % In \docfm\ package there's a~default behaviour of putting marked % macro's or environment's name to a~marginpar. In the standard % classes it's 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 % (\acro{OCSR}). % % Another space formatting option is \TextUsage*{codespacesgrey} % suggested by Will Robertson. It makes the spaces of code visible % only not black but grey. The name of their colour is % |visspacesgrey| and by default it's defined as |{gray}{.5}|, you % can change it with \pk{xcolor}'s |\definecolor|. There is also an % \acro{OCSR} declaration \TextUsage\CodeSpacesGrey. % % If for any reason you wish the code spaces blank in general and % visible and grey in \env{verbatim*}s, use the declaration % \TextUsage\VisSpacesGrey\ of the \pk{gmverb} package. If you like % a~little tricks, you can also specify % |codespacesgrey, codespacesblank| in \pk{gmdoc} options (in this % order). % % \subdivision{The packages required} % % \pk{gmdoc} requires (loads if they're not loaded yet) some other % packages of mine, namely \pk{gmutils}, \pk{gmverb}, analogous to % Frank Mittelbach's \pk{shortvrb}, and \pk{gmiflink} for conditional % making of hyperlinks. It also requires \pk{hyperref}, % \pk{multicol}, \pk{color} and \pk{makeidx}. % % The \pk{gmverb}\gmdmarginpar{\pk{gmverb}} package redefines the % |\verb| command and the \env{verbatim} environment in such a~way that % | |, |{| and |\| are breakable, the first with no `hyphen' and the % other two with the comment char as a~hyphen, i.e., % |{|\<subsequent text>|}| breaks into % |{%|\\ \<subsequent text>|}| ^^A] bal. braces for Emacs % and \<text>|\mylittlemacro| breaks into \<text>|%|\\ % |\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(*)|, % |\DeclareDocumentCommand|, % % \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 \<KVprefix> % is |KV|, as in \pk{xkeyval}. % % |dox| stands for |\DeclareOptionX| and launches scanning for an % optional \arg[KVprefix], optional |<|\<KVfamily>|>| and mandatory % \arg{option name}. Here the default \<KVprefix> % is also |KV| and the default \<KVfamily> is the input file name. If % you want to set another default family (e.g. if the code 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 \<KVprefix> 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 |\|\<KVOfamily>|@|\<optionname>. The default \<KVOfamily> 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: \<KVOfamily>|@|) 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\<command> % in the commentary. If both \<command> and \<command*> are detected, % then both will be hidden. |\HideDefining| is always |\global|. Later % you can resume detection of \<command> and \<command*> with % \TextUsage\ResumeDefining\<command> which is always |\global| % too. Moreover, if you wish to suspend automatic detection of the % defining \<command> only once (the next occurrence), there is % |\HideDefining*| which suspends detection of the next occurrence of % \<command>. So, if you wish to `hide' |\providecommand*| once, write % \[|\HideDefining*\providecommand*|\] % % If you wish to turn entire detection mechanism off, write % \TextUsage\HideAllDefining\ in the narration layer. Then you can % resume detection with \TextUsage\ResumeAllDefining. Both % declarations are |\global|. % % The basic definition command, |\def|, seems to me a~bit % ambiguous. 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, you can write |\HideDefining*\def| or \TextUsage\UnDef\ % for short. % % If you don't like |\def| to be detected more times, you may write % |\HideDefining\def| of course, but there's a~shorthand for this: % \TextUsage\HideDef\ which has the starred version % \TextUsage\HideDef*\ equivalent |\UnDef|. 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 of the macros and environments]{^^B % \gmhypertarget{Manual Marking of 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 \acro{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 (\acro{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 \acro{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 |%<||<|\<END-TAG> 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 |%|\<END-TAG> 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 |<<|\<any text till the end of line>. In the %^^A standard case of |<|\<directive>|>| \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| \acro{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{|\<version>|}{|\<\acro{YYYY}/\acro{MM}/\acro{DD} date>|}{|\<text>|}|\] % % 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 \<date> in % parentheses and appends the \<text> 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{|\<version>|}{|\<year>|/|\<month>|/|\<day>|}|\] % 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{|\<version?>|}{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|{|\<number>|}| 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 \<first brace> dated \<second ^^B % brace> was \<third brace>. % % \stanza % There is also \TextUsage\toCTAN\arg{version}\arg{date}, a~shorthand % for % \[|\changes|\arg{version}\arg{date}|{put to \acro{CTAN} on |\<date>|}|\] % % % \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. You can use it before narration to remove the vskip before % it or after narration to suppress the vskip after it. % % \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, the end of a~|\DocInput| file is marked with % %`\EOFMark' % % \noindent given by the % \TextUsage\EOFMark\ macro. % % \stanza % If you do use the \eTeX's primitive \TextUsage\everyeof, be sure % the contents of it begins with |\relax| because it's the token that % stops the main macro scanning the code. % \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|\<counter> 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 \Describe\UsgEntry\cs{Usg\-Ent\-ry} 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 the source of % chapter \ref*{Driver}, where % |\def\CommonEntryCmd{UsgEntry}| makes all the index entries of the % driver 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 % \Describe\IndexPrologue\cs{Ind\-ex\-Pro\-lo\-gue}. 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{|\<brand new ^^B % index prologue>|}|, 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{|\<only the desired changes>|}|. % (|\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{|\<the ^^B % stuff to be executed anyway>|}| 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\<charX>\dots\<charX> (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}. % % For usage in the inline comments there are \TextUsage\incs\ and % \TextUsage\inenv\ commands that take analogous arguments and precede % the typeset command and environment names with a~|%| if at the % beginning of a~new line. % % 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 By default the multiline inline comments are typeset with % a~hanging indent (that is constant relatively to the current % indent of the code) and justified. Since vertical alignment is % determined by the parameters as they are at the moment of \cs{par}, % no one can set the code line to be typeset ragged right (to break % nicely if it's long) and the following inline comment to be % justified. Moreover, because of the hanging indent the lines of % multiline inline comments are relatively short, you may get lots of % overfulls. Therefore there is a~Boolean switch \TextUsage*{ilrr} % (\acro{OCSR}), % whose name stands for `InLine RaggedRight' and the inline comments % (and their codelines) are typeset justified in the scope of % |\ilrrfalse| which is the default. % When you write |\ilrrtrue|, then all inline comments in its scope % (and their codelines) will be typeset ragged right % (and still with the hanging indent). Moreover, you are provided % \TextUsage\ilrr\ and \TextUsage\ilju\ commands that set |\ilrrtrue| % and |\ilrrfalse| for the current inline comment only. Note you can % use them anywhere within such a~comment, as they set |\rightskip| % basically. |\ilrr| and |\ilju| are no-ops in the standalone narration. % % % % \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|{|\<sec name without ^^B % backslash>|}|. % % \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. % % If you don't like it, just call % |\RestoreEnvironment{quotation}| after loading \pk{gmdoc}. % Note however that other environments using % \env{quotation}, such as \env{abstract}, keep their shape. % % \stanza % % The \TextUsage\GetFileInfo|{|\<file name with extension>|}| 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|{|\<file name with ^^B % extension>|}[|\<info>|]|. (\<info> should consist of: % \<year>|/|\<month>|/|\<day>| |\<version number>| |\<a~short note>.) % % Since we may documentally input files that we don't load, \docfm\ in % \pk{gmdoc} e.g., we provide a~declaration to be put (in the comment % layer) before the line(s) containing |\Provides...|. The % \TextUsage\FileInfo\ command takes the subsequent stuff till the % closing |]| and subsequent line end, extracts from it the info and % writes it to the \file{.aux} and rescans the stuff. We use an % \eTeX\ primitive |\scantokens| for that purpose. % % A~macro for the standard note is provided, \TextUsage\filenote, that % expands to ``This file has version number \<version number> dated % \<date>.'' 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\&|. % % \stanza To get `\CS' which is `CS' in small caps (in |\acro| to be % precise), you can write \TextUsage\CS. This macro is |\protected| so % you can use it safely in |\changes| e.g. Moreover, it checks % whether the next token is a~letter and puts a~space if so so you % don't have to bother about \verb*|\CS\ |. % % \stanza % To enumerate the list of command's arguments or macro's parameters % there is the \TextUsage*{enumargs} environment which is a~version of % \env{enumerate} with labels like |#7|. You can use |\item| or, at % your option, \TextUsage\mand\ which is just an alias for the % former. For an optional arguments use \TextUsage\opt\ which wraps % the item label in square brackets. Moreover, to align optional and % mandatory arguments digit under digit, use % the \TextUsage*{enumargs*} environment. % % Both environments take an optional argument which is the number of % |#|s. It's 1 by default, but also can be 2 or 4 (other numbers will % typeset numbers without a~|#|). Please feel free to notify me if you % really need more hashes in that environment. % % \stanza % 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 % \cs{AfterMacrocode} tool written specially for that). So, if % you wish to compile a~\docfm-like file with my humble package, just % try. % % \TextUsage\AfterMacrocode\arg{mc number}\arg{the stuff} defines % control sequence \cs{gmd@mchook}\<mc number> with the meaning \<the\ % stuff> which is put at the end of \env{macrocode} and \env{oldmc} % number \<mc number> (after the group). % % 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 \verb*|% \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\OldMacrocodes. That declaration (\acro{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}. % %^^A \docstrip %<*package> % \division[The driver part]{\gmhypertarget{The driver} part} % % In case of a~single package, such as \pk{gmutils}, a~driver part of % the package may look as follows and you put it before % \cs{ProvidesPackage/Class}. % %\begin{verbatim} %% \skiplines we skip the driver %\ifnum\catcode`\@=12 % %\documentclass[outeroff, pagella, fontspec=quiet]{gmdocc} %\usepackage{eufrak}% for |\continuum| in the commentary. %\twocoltoc %\begin{document} % %\DocInput{\jobname.sty} %\PrintChanges %\thispagestyle{empty} %\typeout{% % Produce change log with^^J% % makeindex -r -s gmglo.ist -o \jobname.gls \jobname.glo^^J % (gmglo.ist should be put into some texmf/makeindex directory.)^^J} %\typeout{% % Produce index with^^J% % makeindex -r \jobname^^J} %\afterfi{\end{document}} % %\fi% of driver pass %%\endskiplines %\end{verbatim} % % The advantage of \TextUsage\skiplines…\TextUsage\endskiplines\ over % |\iffalse…\fi| is that the latter has to contain balanced \cs{if}s % and \cs{fi}s while the former hasn't because it sanitizes the % stuff. More precisely, it uses the \cs{dospecials} list, so it % sanitizes also the braces. % % Moreover, when the |countalllines(*)| option is in force, % |\skipfiles|…|\endskipfiles| keeps the score of skipped lines. % % \label{Driver} % {\def\CommonEntryCmd{UsgEntry}% % % Note |%\iffalse| \dots\ |%\fi| in the code layer that protects the % driver against being typeset. % % But \pk{gmdoc} is more baroque and we want to see the driver % typeset---behold. \ifnum\catcode`\@=12 % \CodeUsgIndex*{outeroff} \CodeUsgIndex*{mwrep} \documentclass[countalllines, codespacesgrey, outeroff, debug, mwrep, pagella, fontspec=quiet]{gmdocc} \twocoltoc \title{The \pk{gmdoc} Package\\ i.e., \pk{gmdoc.sty} and \pk{gmdocc.cls}} \author{Grzegorz `Natror' Murzynowski} \date{\ifcase\month\relax\or January\or February\or March\or April\or May\or June\or July\or August\or September\or October\or November\or December\fi\ 2008} %|%\includeonly{gmoldcomm}| %^^A\includeonly{gmeometric,gmoldcomm} \begin{document} %\skiplines \emptify\udigits % because orig. def. raises an error `\cs{@secondoftwo} has % an extra \}' %\endskiplines \maketitle \setcounter{page}{2}% \pk{hyperref} cries if it sees two pages % numbered~1. \tableofcontents \DoIndex\maketitle %^^A\AtBegInputOnce{\showthe\catcode`\^^B} \SelfInclude % \label{SelfIncludeUsg} \DocInclude{gmdocc} % For your convenience I~decided to add the documentations of the % three auxiliary packages: \skipgmlonely[\stanza The remarks about installation and compiling of the documentation are analogous to those in the chapter \pk{gmdoc.sty} and therefore ommitted.\stanza] \DocInclude{gmutils} \DocInclude{gmiflink} \DocInclude{gmverb} \DocInclude{gmeometric} \DocInclude{gmoldcomm} \typeout{% Produce change log with^^J% makeindex -r -s gmglo.ist -o \jobname.gls \jobname.glo^^J (gmglo.ist should be put into some texmf/makeindex directory.)^^J} \PrintChanges \typeout{% Produce index with^^J% makeindex -r \jobname^^J} \PrintIndex \afterfi{% \end{document} % MakeIndex shell commands: makeindex -r gmdoc makeindex -r -s gmglo.ist -o gmdocDoc.gls gmdocDoc.glo % (\pk{gmglo.ist} should be put into some \pk{texmf/makeindex} % directory.) %^^A( % And ``That's all, folks'' ;-)\,. }\fi% of |\ifnum\catcode`\@=12|, of the driver that is. % }^^A~of special \cs{CommonEntryCmd}'s definition. % % \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 \acro{EOL}s} 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{gmutils}[2008/08/30]% includes redefinition of % \incs{newif} to make the switches \incs{protected}. \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 \newif\if@printalllinenos \DeclareOption{countalllines}{% \@countalllinestrue \@printalllinenosfalse} \DeclareOption{countalllines*}{% \@countalllinestrue \@printalllinenostrue} % 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: \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). \DeclareOption{codespacesblank}{% \AtEndOfPackage{% to allow \inverb|codespacesgrey, codespacesblank| \AtBeginDocument{\CodeSpacesBlank}}} \DeclareOption{codespacesgrey}{% % \changes{v0.99l}{2008/08/06}{added due to Will Robertson's % suggestion} \AtEndOfPackage{% to put the declaration into the begin-document % hook after definition of \incs{visiblespace}. \AtBeginDocument{\CodeSpacesGrey}}} \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|. Since 2008/08/08 it also makes \cs{if…} switches % \cs{protected} (redefines \cs{newif}) \RequirePackage{gmutils}[2008/08/08] % A~standard package for defining colours, \RequirePackage{xcolor} % 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}} %^^A\@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, %^^A \@ifXeTeX{xetex,}{} pdfpagemode=UseNone]{hyperref}} %^^A\@ifXeTeX{\XeTeXdefaultencoding "utf-8"}{} % \changes[hyperref]{v0.99k}{2008/08/04}{removed some lines testing if % \XeTeX\ colliding with \pk{tikz} and most probably obsolete} % 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}[2008/08/20] \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\|\<one char> % 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} % \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 \gmdnoindent % |%% \abovedisplayshortskip| % remains untouched as it is 0.0\,pt plus 3.0\,pt by default. % \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 % \incs{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{% \par\addvspace{% \glueexpr\MacroTopsep \if@codeskipput-\CodeTopsep\fi \relax }\@codeskipputgtrue} % And, for a~smaller part of text, \pdef\stanza{% \par\addvspace{% \glueexpr\stanzaskip \if@codeskipput-\CodeTopsep\fi \relax}\@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{% \changes{v0.99n}{2008/08/21}{added adding % negative skip if in vmode and \cs{par}} \par \if@codeskipput\unless\if@nostanza\vskip-\CodeTopsep\relax\fi\fi \@codeskipputgtrue\@nostanzagtrue \@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. % %\stanza % To count the lines where they have begun not before them\nostanza \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\ % \changes[\DocInput]{v0.95}{06/08/15}{\cs{club-} % and \cs{widowpenalty} set both to 3333} %\CodeUsgIndex\tolerance \tolerance=1000 % as in \docfm. % ^^A \catcode`\^^M=\active% redundant with line 2304 % \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. % \Define*{^^M} \QueerEOL% \changes{v0.99m}{2008/08/09}{there was % \cs{let}\hathat{M} but \cs{QueerEOL} is better: it also % redefines \cs{}\hathat M} It has to be before the % begin-input-hook to allow change by that hook. % \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\gmd@guardedinput \edef\gmd@guardedinput{% \@nx\@@input #1\relax% |\@nx| is % |\noexpand|, see \pk{gmutils}.\DoNotIndex\@nx % \incs{@@input} is the % true \TeX's \incs{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|). \everyeof{\relax}% |\@nx| moved not to spoil input of toc e.g. \@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 \acro{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|). % \pdef\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 % \incs{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 |\@ifEOLactive|: % % \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\@ifEOLactive#1#2{% \ifnum\catcode`\^^M=\active \afterfi{#1}\else\afterfi{#2}\fi} \foone\obeylines{% \long\def\@ifQueerEOL#1#2{%% \changes{v0.98a}{06/09/06}{added} \@ifEOLactive{\ifx^^M\gmd@textEOL\afterfi{#1}\else\afterfi{#2}\fi}% {#2}}% of \cs{@ifQueerEOL} }% of \cs{foone} % 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{\<eof>} % \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\CodeSpacesVisible{% \def\gmd@DoTeXCodeSpace{% \obeyspaces\let =\breakablevisspace}}% % \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@}}% %\stanza \end{obeyspaces} \def\CodeSpacesGrey{% % \changes{v0.99l}{2008/08/06}{added due to Will Robertson's % suggestion} \CodeSpacesVisible \VisSpacesGrey% defined in \pk{gmverb} }% % Note that \cs{CodeSpacesVisible} doesn't revert \cs{CodeSpacesGrey}. \CodeSpacesVisible % How the continuing of the narration should look like? \def\gmd@continuenarration{% \endgroup \gmd@cpnarrline% 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'.) \if@countalllines %^^A erased obsolete code is backed up in gmdoc.sty~5~. %\gmhypertarget[countnarr]{If the} |countalllines| option is in force, % we get the count of lines from the \cs{inputlineno} primitive. But % if the option is |countalllines*|, we want to print the line number. %^^A \def\gmd@countnarrline{% %^^A \if@newline %^^A \gmd@countnarrline@ %^^A \fi}% \DefIndex\gmd@countnarrline \def\gmd@countnarrline@{% \gmd@grefstep{codelinenum}\@newlinegfalse \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. }% of \cs{gmd@countnarrline@} \def\gmd@grefstep#1{% instead of diligent redefining all possible % commands and environments we just assign the current value of % the respective \TeX's primitive to the \env{codelinenum} % counter. Note we decrease it by $-1$ to get the proper value % for the next line. (Well, I~don't quite know why, but it % works.) %^^A~we'll step its value by 1 because it will be put % ^^Aat the beninning of the \emph{next} line. \ifnum\value{#1}<\inputlineno \csname c@#1\endcsname\numexpr\inputlineno-1\relax \ifvmode\leavevmode\fi% this line is added 2008/08/10 after an % ^^A( % all-night debuggery ;-) that showed that at one point % \incs{gmd@grefstep} was called in vmode which caused adding % \incs{penalty 10000} to the main vertical list and thus % forbidding pagebreak during entire \inenv{oldmc}. \grefstepcounter{#1}% \fi}% We wrap stepping the counter in an \incs{ifnum} to avoid % repetition of the same ref-value (what would result in the % ``multiply defined labels'' warning).\par\ % The % \cs{grefstepcounter} macro, defined in \pk{gmverb}, is % a~global % version of \cs{ref\-step\-count\-er}, observing the redefinition % made % to \incs{refstepcounter} by \pk{hyperref}. \if@printalllinenos% Note that checking this swich makes only % sense when |countalllines| is true. \def\gmd@cpnarrline{% count and print narration line \if@newline \gmd@countnarrline@ \hyperlabel@line {\LineNumFont\thecodelinenum}\,\ignorespaces}% \fi} \else% not |printalllinenos| \emptify\gmd@cpnarrline \fi \def\gmd@ctallsetup{% In the \inenv{oldmc} environments and with the % \incs{FileInfo} declaration (when % \inenv{countalllines} option % is in force) the % code is gobbled as an argument of a~macro and % % then processed at one place (at the end of % \inenv{oldmc} % % e.g.) so if we used % \incs{inputlineno}, we would have got all % % the % lines with the same number. But we only set the counter % % not \incs{refstep} it to avoid putting a~hypertarget. \setcounter{codelinenum}{\inputlineno}% it's global. \let\gmd@grefstep\hgrefstepcounter} \else% not |countallines| (and therefore we won't print the narration % lines' numbers either) \@emptify\gmd@cpnarrline \let\gmd@grefstep\hgrefstepcounter% \label{let grefstep} if we don't % want to count all the lines, we only \incs{ref}-increase the % counter in the code layer. \emptify\gmd@ctallsetup \fi% of |\if@countalllines| \def\skiplines{\bgroup \let\do\@makeother \dospecials % not \incs{@sanitize} because the % latter doesn't recatcode braces and we want all to be quieten.\ilrr %^^A \catcode`\^^M\active what was it for? for countalllines, but %^^A~there's no need of. \gmd@skiplines} \edef\gmu@tempa{% \long\def\@nx\gmd@skiplines##1\bslash endskiplines{\egroup}} \gmu@tempa % And typesetting the \TeX\ code? \foone\obeylines{% \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\special{color push gray 0.2645}% % A~verbatim group has already been opened by \cs{ttverb\+at\+im} and % additional \cs{cat\-code}. \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{% \TeX\ code \acro{EOL} \@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. % ^^A\special{color push gray 0.2666}% \@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\@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% %^^A\special{color push gray 0.2682}% before that penalty \ifdim\gmd@ldspaceswd>\z@% and here the leading spaces. \leavevmode\@dsdirgfalse% \if@newline\gmd@grefstep{codelinenum}\@newlinegfalse% \fi% \printlinenumber% if we don't want the lines to be numbered, % the respective option \incs{let}s this \CS to \incs{relax}. \hyperlabel@line% %^^A\special{color push gray 0.2689}% seems O.K. \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. \acro{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. \if@ilgroup\aftergroup\egroup\@ilgroupfalse\fi% when we are in the inline % comment group (for ragged right or justified), we want % to \label{inline.egroup.2} % close it. But if we did it % here, we would close the verbatim group for the code. But we set % the swich false not to repeat \inverb|\aftergroup\egroup|. % ^^A\special{color push gray 0.2712}% before that penalty \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. }% of |\gmd@typesettexcode|. }% of |\foone\obeylines|. % % \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 % |\breakablevisspace|. % So let us |\let| for future: % \Define\gmd@texcodespace \let\gmd@texcodespace=\breakablevisspace % And now let's try to deal with those spaces. \def\gmd@dolspaces{% \ifx\gmd@texcodespace\@let@token \@dsdirgfalse \afterfi{\settowidth{\gmd@spacewd}{\visiblespace}% \gmd@ldspaceswd=\z@ \gmd@eatlspace}% \else\afterfi{% about this smart macro and other of its family see % \pk{gmutils} sec.\,3. % ^^A \special{color push gray 0.2748}% debug of \penalty10000 % ^^A~2008/08/10 was far % ^^A \ifnum\inputlineno>1016 \ifnum\inputlineno<1050 \show\par\fi\fi % ^^A~O.K. \if@afternarr\if@aftercode \ifilrr\bgroup \gmd@setilrr\fi \fi\fi \par% possibly after narration \if@afternarr\if@aftercode \ifilrr\egroup\fi \fi\fi \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 % \incs{advance} it \incs{global}ly because the current group may be closed % iff we meet \inverb|%| and then we'll won't indent the line anyway.\ilrr \afteriffifi\gmd@eatlspace \else \if\code@delim\@nx#1% \gmd@ldspaceswd=\z@ \afterfifi{\gmd@continuenarration#1}%\label{ContNarr2} % \changes{v0.99n}{2008/08/30}{\cs{afterfifi} added---a~bug fix} \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 % ^^A~\special{color push gray 0.2789}% \fi \if\code@delim\@nx#1% \def\next{% occurs when next a~\cs{hskip4.875pt} is to be put % ^^A\special{color push gray 0.2791}% O.K. \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 \ifx\relax#1\def\next{% % ^^A\special{color push gray 0.2798}% \endgroup}% special case of end of file thanks to |\everyeof|. \else \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. \def\next{% %^^A \debug@special{2808}% \gmd@counttheline#1\scan@macro}% \else \def\next{% %^^A \debug@special{2806}% before penalty \gmd@EOLorcharbychar#1}% \fi \fi \fi\next} \def\debug@special#1{% \ifhmode\special{color push gray 0.#1}% \else\special{color push gray 0.#1000}\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{% %^^A \debug@special{2829}% \ifx\gmd@texcodeEOL#1% \if@newline % ^^A\special{color push gray 0.281600}% no occurence % ^^A \if@countalllines\global\advance\c@codelinenum by\@ne obsolete % ^^A\fi \@newlinegfalse \fi \afterfi{#1}%\label{printhashone1}here we print |#1|. \else% i.e., |#1| is \emph{not} a~(very active) line end, \afterfi {%^^A \debug@special{2839}% this occurs frequently \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 \leavevmode %^^A \debug@special{2851}% \gmd@grefstep{codelinenum}\@newlinegfalse \hyperlabel@line \fi %^^A\debug@special{2853}% \printlinenumber % ^^A\debug@special{2855}% \mark@envir \else% not vmode \if@newline % ^^A\special{color push gray 0.2842}% didn't occur \gmd@grefstep{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~% 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. % \changes{v0.99n}{2008/08/21}{\cs{space} replaced with a~tilde to % forbid a~linebreak before an inline comment} \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@cpnarrline \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}{% %^^A\@ifnextMac{%^^A} \@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@cpnarrline \everypar=\@xa{\@xa\@codetonarrskip\the\gmd@preverypar}% % % \label{longlinethatshouldbebroken} \@afternarrgfalse\@aftercodegtrue \ifhmode\@codeskipputgfalse\fi \@ifnextchar{\gmd@textEOL}{% %^^A\@ifnextMac{%^^A} {\raggedright\gmd@endpe\par}% without \incs{raggedright} this % \incs{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{% the narration \cs{par}. \ifhmode% (I~added this |\ifhmode| as a~result of a~heavy % debug.) \if@afternarr\if@aftercode \unless\if@ilgroup\bgroup\@ilgrouptrue\fi \ifilrr\gmd@setilrr\fi \fi\fi \@@par \if@afternarr \if@aftercode \if@ilgroup\egroup\fi% \label{inline.egroup.1}if we are both after code % and after narration it means we are after an inline % comment. Then we probably end a~group opened in line % \ref{inline.bgroup} \if@codeskipput\else\gmd@codeskip2\@aftercodegfalse\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% \fi}% of \cs{par}. \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} % Now a~special treatment for an inline comment: \newif\ifilrr \def\ilrr{%\changes{v0.99n}{2008/08/21}{added} \if@aftercode \unless\if@ilgroup\bgroup\@ilgrouptrue\fi% \label{inline.bgroup} If we are % `aftercode', then we are in an inline comment. Then we open % a~group to be able to declare e.g.\ \cs{raggedright} for that % comment only. This group is closed in line \ref{inline.egroup.1} % or \ref{inline.egroup.2}. \ilrrtrue \fi} \newif\if@ilgroup \def\gmd@setilrr{\rightskip0ptplus\textwidth} \def\ilju{% when inline comments are ragged right in general but we % want just this one to be justified. \if@aftercode \unless\if@ilgroup\bgroup\@ilgrouptrue\fi \ilrrfalse \fi} \def\verbcodecorr{%\changes{v0.99n}{2008/08/21}{added} % a~correction of vertical spaces between a~\env{verbatim} and % code. We put also a~\cs{par} to allow parindent in the next % commentary. \vskip-\lastskip\vskip-4\CodeTopsep\vskip3\CodeTopsep\par} % % % \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\@nostanzagfalse} %\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 % A~switch to control |\nostanza|s: \nostanza \newgif\if@nostanza % 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. \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% % \label{codeskip5} \else\gmd@nocodeskip4{naC}% \fi \fi \fi \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|.) Before v0.99n it was just after line \ref{codeskip5}. \@aftercodegfalse\@nostanzagtrue % \changes{v0.99o}{2008/09/04}{a~bug fix: added \cs{@nostanzagtrue}} } % 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 \incs{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 \acro{EOL}s]{Life among queer \gmhypertarget[afc]{\acro{EOL}s}} % % 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| \<char2> globally, for the % entire document. \foone{\obeylines}%% \Define*{^^B} {\def\QueerCharTwo{% \protected\def^^B##1^^M{% %^^A\@newlinegtrue\gmd@countnarrline \ifhmode\unskip\space\ignorespaces\fi}}% It shouldn't be \incs{ } not to % drive \TeX\ into hmode. } \QueerCharTwo \AtBegInput{\@ifEOLactive{\catcode`\^^B\active}{}\QueerCharTwo}% \label{QCh2} % We repeat redefinition of \<char2> 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., \<char1>) 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| \<char1> globally, for the % entire document. \foone\obeylines{%%\DefIndex\QueerCharOne \Define*{^^A} \def\QueerCharOne{% \def^^A{%^^A no need to write \incs{gmd@countnarrline} because % ^^A \inverb|^^M| will contain it if \inenv{countalllines} is in force. \bgroup\let\do\@makeother\dospecials\gmd@gobbleuntilM}}% \def\gmd@gobbleuntilM#1^^M{\egroup\ignorespaces^^M}% } \QueerCharOne \AtBegInput{\@ifEOLactive{\catcode`\^^A\active}\QueerCharOne}% see note % after line \ref{QCh2}.\ilrr % 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{\ }} %^^A \unless\if@countalllines %^^A \let\StraightEOL\StraightEOLnocount %^^A \fi %^^A \foone\obeylines{% \def\QueerEOL{%\label{QueerEOL} \catcode`\^^M=\active% \let^^M\gmd@textEOL% \catcode`\^^A=\active% \catcode`\^^B=\active% I~only re|\catcode| \<char1> and \<char2> % 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}% %^^A % %^^A \if@countalllines% %^^A \def\StraightEOL{% %^^A \catcode`\^^M=\active% %^^A \let^^M\gmd@notsostraightEOL% %^^A \catcode`\^^A=\active% %^^A \catcode`\^^B=\active% I~only re|\catcode| \<char1> and \<char2> %^^A % hoping no one but me is \emph{that} perverse to make them %^^A % |\active| and (re)define. (Let me know if I'm wrong at this point.) %^^A \let\^^M=\gmd@bslashEOL}% %^^A % %^^A \fi% } %^^A % \skiplines %^^A % They won't work in \verb+|verbatim|+ scopes but the clubs redefine %^^A % the active lineend to be a~breakable (and visible) space, so %^^A % breaking a~`clubbed' text in two lines will not cause a~disaster but %^^A % you get e.g., |...^^B %...|. %^^A % \endskiplines % \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 unwelcome 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 \if@aftercode\ifilrr \gmd@setilrr \fi\fi \par}% \if@ilgroup\aftergroup\egroup\@ilgroupfalse\fi% we are in the % verbatim group so we % close the inline comment group after it if the closing is not yet set. } % 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: \foone\obeylines{%\DefIndex*{\^^M} \if 1 1% \protected\def\gmd@bslashEOL{\ \@xa\ignorespaces^^M}% }% of \cs{foone}. Note we interlace here \incs{if} with a~group. \else% \protected\def\gmd@bslashEOL{% \ifhmode\unskip\fi\ \ignorespaces} %^^A~\if@countalllines\@newlinegtrue\gmd@cpnarrline\fi% \fi % \changes{v0.99c}{2007/03/30}{a~bug fix: redefinition of it left % solely to \cs{QueerEOL}} % \changes{v0.99m}{2008/08/09}{also \cs{StraightEOL} with % \env{countalllines} package option lets \cs{}\hathat{M} to it} % % 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{% \gmd@cpnarrline% to count the verbatim lines and possibly print % their numbers. This macro is used only by the verbatim end of line. \@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}}% %^^A \foone\obeylines{% %^^A \AtBegInput{% %^^A \prependtomacro{% first the stuff then the macro (see \pk{gmutils}). %^^A \def\obeylines{\def^^M{\par}\catcode`\^^M\active}}% %^^A \@verbatim}} % 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' \acro{EOL}s 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}% \@ifEOLactive{^^M}{\@ehc}}}}% \endgroup % \subdivision{Macros for marking of 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~|\|\<one char> \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 \incs{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@@}% % 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 \cs{gmd\-@\-if\-in\-mean\-ing} 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 |$|: ^^A$ \def\im@firstpar{[$%^^A$ ]}% \else\def\im@firstpar{}\fi \@xa \index@macro\im@firstpar\macro@iname\macro@pname % \label{3049} \maybe@marginpar\macro@pname \if\xiispace\macro@pname\relax\gmd@texcodespace \else\macro@pname \fi % \changes[\finish@macroscan]{v0.99n}{2008/09/30}{the case of % \cs{\vs} taken care of} \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 and thus % sets the switch of line \ref{506} true. \next % \label{next 3690} } % 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. \incs{macro@pname}, which will be the only possible % argument to % \incs{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. \cs{Decl\-are\-Def\-in\-ing} 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 % \incs{Declare@Dfng@inner} (it's the |star| key). \Declare@Dfng@inner{#1}{#2*}% The catcode of |*| doesn't matter since % it's in % \incs{csname\+…\+\bslash end\+cs\+na\+me} % 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}% % ^^A~\typeout{@@@ gmd@adef@currdef:::\gmd@adef@currdef::::}% }% \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@|\<def name> (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\gmu@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}}% \gmu@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@|\<command> 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@|\<command> if defined, will falsify % an \cs{ifnum} test that will decide whether create additional index % entry together with the tests for |prefix|\<command> 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 \acro{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~\acro{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=|\<family>|]|. \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.\ilrr \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[%^^A] \gmd@adef@scanKVpref\gmd@charbychar}% note that % the prefix scanning macro gobbles its first argument (undelimited) % which in this case is |[|.\ilrr %^^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@|\<def. command> is defined |{1}| (so \cs{ifnum} % gets |1=01\relax|---\hskip0sptrue) iff \<def. command> is a~\pk{keyval} % definition. In that case we check for the \inverb|KVpref|ix and % \inverb|KVfam|ily. (Otherwise |\gmd@adef@KV@|\<def. command> is undefined % so \cs{ifnum} gets |1=0\relax|---false.)\ilrr \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}} % \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 \DeclareDefining[star=false]\pdef% it's a~\pk{gmutils}' shorthand for \inverb|\protected\def|. \DeclareDefining[star=false]\provide% a~\pk{gmutils}' conditional \incs{def}. \DeclareDefining[star=false]\pprovide% a~\pk{gmutils}' conditional \incs{pdef}. %^^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{{% \changes{v0.99n}{2008/08/30}{a~bug fixed: % \cs{gmd@charbychar} appended to \cs{next}---without it % a~subsequent inline comment was typeset verbatim} % \UnDef \gmd@adef@selfrestore\def }} \StoreMacro\UnDef% because the `hiding' commands relax it. \def\HideDef{% \changes{v0.99n}{2008/08/30}{added the starred version % that calls \cs{UnDef}} \@ifstar\UnDef{\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[star=false]\DeclareDocumentCommand % \changes{v0.99p}{2008/10/04}{added} \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@|\<counter>. \DeclareDefining[type=dk, prefix=\bslash]\define@key \DeclareDefining[type=dk, prefix=\bslash if]\define@boolkey% the % alternate index entry will be % \cs{if}\<KVpref>|@|\<KVfam>|@|\<key name> \DeclareDefining[type=dk, prefix=\bslash]\define@choicekey \DeclareDefining[type=dox, prefix=\bslash]\DeclareOptionX% the % alternate index entry will be \cs{}\<KVpref>|@|\<KVfam>|@|\<option name>. % % For |\DeclareOptionX| the default KVfamily is the input file % name. If the source file name differs from the name of the goal % file (you \TeX\ a~\file{.dtx} not \file{.sty} e.g.), there is the % next declaration. It takes one optional and one mandatory % argument. The optional is the |KVpref|, the mandatory the |KVfam|. % \Define\DeclareDOXHead \newcommand*\DeclareDOXHead[2][\gmd@KVprefdefault]{% \csname DeclareDefining\endcsname [type=dox, prefix=\bslash, KVpref=#1, KVfam=#2]% \HideDefining\DeclareOptionX \DeclareOptionX } % An example: %\skiplines \iffalse %\endskiplines \DeclareOptionX[Berg]<Lulu>{EvelynLear}{} % Check in the index for % \inverb|EvelynLear| and \inverb|\Berg@Lulu@EvelynLear|. % Now we set in the comment layer % |\DeclareDOXHead[Webern]{Lieder}|\DeclareDOXHead[Webern]{Lieder} and \DeclareOptionX<AntonW>{ChneOelze} % The latter example shows also overriding the option header by % declaring the default. By the way, both the example options are % not declared in the code actually. %\skiplines \fi %\endskiplines %\stanza % Now the Heiko Oberdiek's \pk{kvoptions} package option definitions: \DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareStringOption \DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareBoolOption \DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareComplementaryOption \DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareVoidOption % The \pk{kvoptions} option definitions allow setting the default % family/prefix for all definitions forth so let's provide analogon: \def\DeclareKVOFam#1{% \def\do##1{% \csname DeclareDefining\endcsname [type=kvo, prefix=\bslash, KVpref=, KVfam=#1]##1}% \do\DeclareStringOption \do\DeclareBoolOption \do\DeclareComplementaryOption \do\DeclareVoidOption } % \ResumeAllDefining^^A~ it cancels |\DD\DD| and |\DD\bslash| effect. % As a~nice exercise I~recommend to think why this list of declarations % had to be preceded (in the comment layer) with |\HideAllDefining| % and for which declarations of the above % |\DeclareDefining\DeclareDefining| did not work. (The answers are % commented out in the source file.) %^^A~ I~had to precede the list of |\DeclareDefining|s with %^^A~ |\HideAllDefining| in the commentary because the detectors of %^^A~ some commands expect certain configurations of arguments and of %^^A~ course such arguments do \emph{not} occur when such a~defining %^^A~ command is being declared. That caused errors. Another reason is %^^A~ that if not hidden, the detectors fired at the declared definers %^^A~ of \CSs and marked next |\DeclareDefining| as being defined. %^^A %^^A~ |\DD\DD| did not work for those three \pk{xkeyval} definers %^^A~ declared with |\bslash| in the optional argument. To be precise, %^^A~ it \emph{did work} perfectly: marked |\bslash| as being defined. % % One remark more: if you define (in the code) a~new defining command % (I~did: a~shorthand for |\DeclareOptionX[gmcc]<>|), declare it as % defining (in the commentary) \emph{after} it is defined. Otherwise % its first occurence shall fire the detector and mark next \CS or % worse, shall make the detector expect some arguments that it won't % find. % \subsubdivision{Suspending (`hiding') and resuming detection} % % Sometimes we want to suspend automatic detection of definitions. For % |\def| we defined suspending and resuming declarations in the % previous section. Now let's take care of detection more generally. % % \stanza % The next command has no arguments and suspends entire detection of % definitions. \def\HideAllDefining{% \ifnum0=0\csname gmd@adef@allstored\endcsname \SMglobal\StoreMacro\gmd@detectors \global\@namedef{gmd@adef@allstored}{1}% \fi \global\emptify\gmd@detectors}% we make the carrier |\empty| not |\relax| to % be able to declare new defining command in % the scope of |\HideAll...| % The |\ResumeAllDefining| command takes no arguments and restores the % meaning of the detectors' carrier stored with |\HideAllDefining| \def\ResumeAllDefining{% \ifnum1=0\csname gmd@adef@allstored\endcsname\relax \SMglobal\RestoreMacro\gmd@detectors \SMglobal\RestoreMacro\UnDef \global\@namedef{gmd@adef@allstored}{0}% \fi} % Note that |\ResumeAllDefining| discards the effect of any % |\DeclareDefining| that could have occured between % |\HideAllDefining| and itself. % % \stanza % % The |\HideDefining| command takes one argument which should be % a~defining command (always without star). |\HideDefining| suspends % detection of this command (also of its starred version) until % |\ResumeDefining| of the same command or |\ResumeAllDefining|. \def\HideDefining{\begingroup % \changes{v0.99n}{2008/08/30}{Added the starred version that hides % the defining command only once} \MakePrivateLetters \@ifstarl\Hide@DfngOnce\Hide@Dfng} \def\Hide@Dfng#1{%%\UnDef \escapechar\m@ne \gn@melet{gmd@detect@\string#1}{relax}% \gn@melet{gmd@detect@\string#1*}{relax}% \ifx\def#1\global\relaxen\UnDef\fi \endgroup} \def\Hide@DfngOnce#1{%%\UnDef \gmd@adef@selfrestore#1% \endgroup} \def\gmd@adef@selfrestore#1{% \escapechar\m@ne \@ifundefined{gmd@detect@\string#1}{% \SMglobal\@xa\StoreMacro \csname gmd@detect@\string#1\endcsname}{}% % ^^A\typeout{:::::::::::::::gmd@detect@\string#1:::::::::::::}% \global\@nameedef{gmd@detect@\string#1}{% \@nx\ifx\@xa\@nx\csname gmd@detectname@\string#1\endcsname \@nx\macro@pname \def\@nx\next{% this \incs{next} will be executed in line % % \ref{next 3690}. \SMglobal\RestoreMacro % they both are \incs{protected}. \@xa\@nx\csname gmd@detect@\string#1\endcsname \@nx\gmd@charbychar}%^^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 % ^^A~be % ^^A multiple occurences of the macro to be restored in the % ^^A~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}. \@nx\fi}% of \cs{@nameedef}. }% of \cs{gmd@adef@selfrestore}. % The |\ResumeDefining| command takes a~defining command as the % argument and resumes its automatic detection. Note that it restores % also the possibly undefined detectors of starred version of the % argument but that is harmless I~suppose until we have millions of \CSs. \def\ResumeDefining{\begingroup \MakePrivateLetters \gmd@ResumeDfng} \def\gmd@ResumeDfng#1{% \escapechar\m@ne \SMglobal\RestoreMacro*{gmd@detect@\string#1}% \SMglobal\RestoreMacro*{gmd@detect@\string#1*}% \endgroup} % \subdivision{Indexing of \CSs} % The inner macro indexing macro. |#1| is the |\verb|'s delimiter; % |#2| is assumed to be the macro's name with MakeIndex-control chars % quoted. |#3| is a~macro storing the \catother\ macro's name, usually % |\macro@pname|, built with |\string|ing every char in lines ^^A % \ref{stringing0}, \ref{stringing1} and \ref{stringing2}. |#3| is % used only to test if the entry should be specially formatted. % \changes{v0.98}{06/09/05}{Indexing the codelines improved to sort % with account of the \cs{filesep} (\cs{HLPrefix})} \newcommand*\index@macro[3][\verbatimchar]{{% \@ifundefined{gmd/iexcl/#3}%\label{iexcltest} {% |#3| is not excluded from index \@ifundefined{gmd/defentry/#3}% \label{pnametestDef} {% |#3| is not def entry \@ifundefined{gmd/usgentry/#3}%\label{pnametestUsg} {% |#3| is not usg entry \edef\kind@fentry{\CommonEntryCmd}}%\label{CECmd} {% |#3| is usg entry \def\kind@fentry{UsgEntry}% \un@usgentryze{#3}}%\label{usgentryrs} }% {% |#3| is def entry \def\kind@fentry{DefEntry}% \un@defentryze{#3}%\label{defentryrs} }% of |gmd/defentry/| test's `else' \if@pageindex\@pageinclindexfalse\fi% should it be here or % there? Definitely here because we'll wish to switch the switch % with a~declaration. \if@pageinclindex \edef\gmu@tempa{gmdindexpagecs{\HLPrefix}{\kind@fentry}{\EntryPrefix}}% \else \edef\gmu@tempa{gmdindexrefcs{\HLPrefix}{\kind@fentry}{\EntryPrefix}}% \fi \edef\gmu@tempa{\IndexPrefix#2\actualchar% \quotechar\bslash verb*#1\quoted@eschar#2#1% The last macro in % this line usually means the first two, but in some cases % it's redefined to be empty (when we use |\index@macro| to % index not a~\CS). \encapchar\gmu@tempa}% \@xa\special@index\@xa{\gmu@tempa}% We give the % indexing macro the argument expanded so that \pk{hyperref} may % see the explicit encapchar in order not to add its own % encapsulation of \verb+|hyperpage+ when the (default) % |hyperindex=true|\TextCommonIndex*{hyperindex} option is in % force. (After this setting the |\edef|s in the above may be % changed to |\def|s.) % \changes[\index@macro]{v0.98f}{06/9/30}{explicit MakeIndex % controls changed to corresponding macros. Therefore % \cs[]{hyperindex} option of \pk{hyperref} didn't see the % encapsulation and added its own. So I~expanded the % argument of the very indexing macro} }{}% closing of |gmd/iexcl/| test. }} \def\un@defentryze#1{% \@xa\g@relaxen\csname gmd/defentry/#1\endcsname \ifx\gmd@detectors\empty \g@relaxen\last@defmark \fi}% the last macro (assuming \cs{fi} is not a~macro :-) % is only used by \cs{changes}. If we are in the scope of automatic % detection of definitions, we want to be able not to use \inverb|\Define| % but write |\changes| after a~definition and get proper entry. Note % that in case of automatic detection of definitions % |\last@defmark|'s value keeps until the next definition. \def\un@usgentryze#1{% \@xa\g@relaxen\csname gmd/usgentry/#1\endcsname} \@emptify\EntryPrefix% this macro seems to be obsolete now % (v0.98d). % For the case of page-indexing a~macro in the commentary when % codeline index option is on: \newif\if@pageinclindex \newcommand*\quoted@eschar{\quotechar\bslash}% we'll redefine it when % indexing an environment. % Let's initialize |\IndexPrefix| \def\IndexPrefix{} % The |\IndexPrefix| and |\HLPrefix| (`HyperLabel Prefix') macros are % given with account of a~possibility of documenting several files % in(to) one document. In such case the user may for each file % |\def\IndexPrefix{|\<package name>|!}| for instance and it will work % as main level index entry and |\def\HLPrefix{|\<package name>|}| % as a~prefix in hypertargets in the codelines. They are redefined by % |\DocInclude| e.g. \if@linesnotnum\@pageindextrue\fi \AtBeginDocument{% \if@pageindex \def\gmdindexrefcs#1#2#3#4{\csname#2\endcsname{\hyperpage{#4}}}%^^A % in the page case we gobble the third argument that is supposed % to be the entry prefix.\ilrr \let\gmdindexpagecs=\gmdindexrefcs \else % \DefIndex\gmdindexrefcs % \DefIndex\gmdindexpagecs \def \gmdindexrefcs#1#2#3#4{\gmiflink[clnum.#4]{% \csname#2\endcsname{#4}}}% \def \gmdindexpagecs#1#2#3#4{\hyperlink{page.#4}{% \csname#2\endcsname{\gmd@revprefix{#3}#4}}}% % \stanza \DefIndex\gmd@revprefix \def\gmd@revprefix#1{% \def\gmu@tempa{#1}% \ifx\gmu@tempa\@empty p.\,\fi} \providecommand*\HLPrefix{}% it'll be the hypertargets names' prefix % in mul\-ti-docs. Moreover, it showed that if it was empty, % \pk{hyperref} saw duplicates of the hyper destinations, which % was perfectly understandable (|codelinenum.123| made by % |\refstepcounter| and |codelinenum.123| made by % |\gmhypertarget|). But since v0.98 it is not a~problem anymore % because during the automatic \inverb|\hypertarget|ing the % lines are labeled |clnum.|\<number>. When |\HLPrefix| was % defined as dot, MakeIndex rejected the entries as `illegal page % number'. \changes[\HLPrefix]{v0.98a}{06/09/05}{again % \cs{@empty}fied since \cs{hypertarget}ing the codelines names % them \cs[]{clnum} (since v0.98).} \fi} % The definition is postponed till |\begin{document}| because of the % |\PageIndex| declaration (added for \docfm-compatibility), see % line \ref{PageIndex}. % % I~design the index to contain hyperlinking numbers whether they are % the line numbers or page numbers. In both cases the last parameter % is the number, the one before the last is the name of a~formatting macro % and in linenumber case the first parameter is a~prefix for proper % reference in multi-doc. % I~take account of three kinds of formatting the numbers: 1.~the % `def' entry, 2.~a~`usage' entry, 3.~a~common entry. As in \docfm , let % them be underlined, italic and upright respectively. \def\DefEntry#1{\underline{#1}} \def\UsgEntry#1{\textit{#1}} % The third option will be just |\relax| by default: \def\CommonEntryCmd{relax} % In line \ref{CECmd} it's |\edef|ed to allow an `unm\oumlaut glich' % situation that the user wants to have the common index entries % specially formatted. I~use this to make \emph{all} the index entries % of the driver part to be `usage', see the source of chapter % \ref*{Driver}. % Now let's |\def| the macros declaring a~\CS to be indexed % special way. Each declaration puts the \catother ed name of the % macro given it as the argument into proper macro to be |\ifx|ed in % lines \ref{pnametestDef} and \ref{pnametestUsg} respectively. % Now we are ready to define a~couple of commands. % The |*| versions of % them are for marking environments and \emph{implicit} \CSs. \outer\def\DefIndex{\begingroup \MakePrivateLetters \@ifstarl{\MakePrivateOthers\Code@DefIndexStar}{\Code@DefIndex}} % \changes{v0.98d}{06/9/11}{The macros indexing and marginizing % macros (and other sequences) made \cs{long}} %\DefIndex\Code@DefIndex \long\def\Code@DefIndex#1{\endgroup{% \escapechar\m@ne% because we will compare the macro's name with % a~string without the backslash. \@defentryze{#1}{1}}} % \label{stringamacro} % \DefIndex\Code@DefIndexStar \long\def\Code@DefIndexStar#1{% \endgroup \addto@estoindex{#1}% \@defentryze{#1}{0}} \def\gmd@justadot{.} \long\def\@defentryze#1#2{% \@xa\glet\csname gmd/defentry/\string#1\endcsname\gmd@justadot% The\\ % \LaTeX\ \inverb|\@namedef| macro could not be used since it's not `long'.\ilrr % \Define\last@defmark \xdef\last@defmark{\string#1}% we |\string| the argument just in case it's % a~control sequence. But when it can be a~\CS, we |\@defentryze| in % a~scope of |\escapechar=-1|, so there will never be a~backslash at % the beginning of |\last@defmark|'s meaning (unless we % |\@defentryze| |\\|). \@xa\gdef\csname gmd/isaCS/\last@defmark\endcsname{#2}}% |#2| is % either 0 or 1. It is the information whether this entry is a~\CS or % not. \long\def\@usgentryze#1{% \@xa\let\csname gmd/usgentry/\string#1\endcsname\gmd@justadot} % Initialize |\envirs@toindex| \@emptify\envirs@toindex % Now we'll do the same for the `usage' entries: \outer\def\CodeUsgIndex{\begingroup \MakePrivateLetters \@ifstarl{\MakePrivateOthers\Code@UsgIndexStar}{\Code@UsgIndex}} % The |*| possibility is for marking environments etc. % \DefIndex\Code@UsgIndex \long\def\Code@UsgIndex#1{\endgroup{% \escapechar\m@ne \global\@usgentryze{#1}}} % \DefIndex\Code@UsgIndexStar \long\def\Code@UsgIndexStar#1{% \endgroup \addto@estoindex{#1}% \@usgentryze{#1}} % For the symmetry, if we want to mark a~control sequence or an % environment's name to be indexed as a~`normal' entry, let's have: \outer\def\CodeCommonIndex{\begingroup \MakePrivateLetters \@ifstarl{\MakePrivateOthers\Code@CommonIndexStar}{\Code@CommonIndex}} % \DefIndex\Code@CommonIndex \long\def\Code@CommonIndex#1{\endgroup} % \DefIndex\Code@CommonIndexStar \long\def\Code@CommonIndexStar#1{% \endgroup\addto@estoindex{#1}} % And now let's define commands to index the control sequences and % environments occurring in the narrative. \long\def\text@indexmacro#1{% {\escapechar\m@ne \xdef\macro@pname{\xiistring#1}}% \@xa\quote@mname\macro@pname\relax% we process the \CS's % name char by char and quote MakeIndex controls. |\relax| is the % iterating macro's stopper. The scanned \CS's quoted name shall be the % expansion of |\macro@iname|. \if\verbatimchar\macro@pname \def\im@firstpar{[$]}%^^A$ \else\def\im@firstpar{}% \fi {\do@properindex% see line \ref{do@properindex}. \@xa \index@macro\im@firstpar\macro@iname\macro@pname}} % The macro defined below (and the next one) are executed only before % a~\catother\ macro's name i.e.\ a~nonempty sequence of \catother\ % character(s). This sequence is delimited (guarded) by |\relax|. \def\quote@mname{% \def\macro@iname{}% \quote@charbychar} % \DefIndex\quote@charbychar \def\quote@charbychar#1{% \if\relax#1% finish quoting when you meet |\relax| or: \else \quote@char#1% \xdef\macro@iname{\macro@iname \gmd@maybequote#1}% \afterfi\quote@charbychar \fi} % The next command will take one argument, % which in plain version should be a~control sequence and in the % starred version also a~sequence of chars allowed in environment names or % made other by |\MakePrivateOthers| macro, taken in the curly braces. \def\TextUsgIndex{\begingroup \MakePrivateLetters \@ifstarl{\MakePrivateOthers\Text@UsgIndexStar}{\Text@UsgIndex}} % \DefIndex\Text@UsgIndex \long\def\Text@UsgIndex#1{% \endgroup\@usgentryze#1% \text@indexmacro#1} % \DefIndex\Text@UsgIndexStar \long\def\Text@UsgIndexStar#1{\endgroup\@usgentryze{#1}% \text@indexenvir{#1}} \long\def \text@indexenvir#1{% \edef\macro@pname{\xiistring#1}% \if\bslash\@xa\@firstofmany\macro@pname\@@nil% if % |\string|ed |#1| begins with a~backslash, we will gobble it % to make MakeIndex not see it. \edef\gmu@tempa{\@xa\@gobble\macro@pname}% \@tempswatrue \else \let\gmu@tempa\macro@pname \@tempswafalse \fi \@xa\quote@mname\gmu@tempa\relax% \label{quote@mname comm}we % process |\sting|ed |#1| char by char and quote MakeIndex % controls. |\relax| is the iterating macro's stopper. The quoted % |\string|ed |#1| shall be the meaning of |\macro@iname|. {\if@tempswa \def\quoted@eschar{\quotechar\bslash}% \else\@emptify\quoted@eschar\fi% we won't print any backslash before % an environment's name, but we will before a~\CS's name. \do@properindex% see line \ref{do@properindex}. \index@macro\macro@iname\macro@pname}} \def\TextCommonIndex{\begingroup \MakePrivateLetters \@ifstarl{\MakePrivateOthers\Text@CommonIndexStar}{\Text@CommonIndex}} %\DefIndex\Text@CommonIndex \long\def\Text@CommonIndex#1{\endgroup \text@indexmacro#1} % \DefIndex\Text@CommonIndexStar \long\def\Text@CommonIndexStar#1{\endgroup \text@indexenvir{#1}} % As you see in the lines \ref{defentryrs} and \ref{usgentryrs}, the % markers of special formatting are reset after first use. % But we wish the \CSs not only to be indexed special way but also % to be put in marginpars. So: \outer\def\CodeMarginize{\begingroup \MakePrivateLetters \@ifstarl {\MakePrivateOthers\egCode@MarginizeEnvir} {\egCode@MarginizeMacro}} % One more expansion level because we wish |\Code@MarginizeMacro| not % to begin with |\endgroup| because in the subsequent macros it's used % \emph{after} ending the re|\catcode|ing group. % \DefIndex\egCode@MarginizeMacro \long\def\egCode@MarginizeMacro#1{\endgroup \Code@MarginizeMacro#1} % \DefIndex\Code@MarginizeMacro \long\def\Code@MarginizeMacro#1{{\escapechar\m@ne \@xa\glet\csname gmd/2marpar/\string#1\endcsname\gmd@justadot %^^A \xdef\mname@tomarginpar{\xiistring#1} }} % \DefIndex\egCode@MarginizeEnvir \long\def\egCode@MarginizeEnvir#1{\endgroup \Code@MarginizeEnvir{#1}} % \DefIndex\Code@MarginizeEnvir \long\def\Code@MarginizeEnvir#1{\addto@estomarginpar{#1}} % And a~macro really putting the environment's name in a~marginpar % shall be trigged at the beginning of the nearest codeline. % % Here it is: \def\mark@envir{%\label{mark@envir} \ifx\envirs@tomarginpar\@empty \else \let\do\Text@Marginize \envirs@tomarginpar% \g@emptify\envirs@tomarginpar% \fi \ifx\envirs@toindex\@empty \else \gmd@doindexingtext \envirs@toindex \g@emptify\envirs@toindex% \fi} \def\gmd@doindexingtext{% \def\do##1{% the |\envirs@toindex| list contains |\string|ed % macros or environments' names in braces and each preceded % with |\do|. We extract the definition because we use it also in % line \ref{gmd@doindexingtext 2nd use}. \if\bslash\@firstofmany##1\@@nil% if % |##1| begins with a~backslash, we will gobble it for % MakeIndex not see it. \edef\gmd@resa{\@gobble##1}% \@tempswatrue \else \edef\gmd@resa{##1}\@tempswafalse \fi \@xa\quote@mname\gmd@resa\relax% see line % \ref{quote@mname comm} \& subs. for commentary. {\if@tempswa \def\quoted@eschar{\quotechar\bslash}% \else\@emptify\quoted@eschar\fi \index@macro\macro@iname{##1}}}% } % One very important thing: initialisation of the list macros: \@emptify\envirs@tomarginpar \@emptify\envirs@toindex % For convenience we'll make the `private letters' first not to bother % ourselves with |\makeatletter| for instance when we want mark some % \CS. And |\MakePrivateOthers| for the environment and other string % case. \outer\def\Define{\begingroup \MakePrivateLetters % We do |\MakePrivateLetters| before |\@ifstarl| in order to avoid % a~situation that \TeX\ sees a~control sequence with improper name % (another \CS than we wished) % (because |\@ifstarl| establishes the |\catcode|s for the next token): \@ifstarl{\MakePrivateOthers\Code@DefEnvir}{\Code@DefMacro}} \outer\def\CodeUsage{\begingroup \MakePrivateLetters \@ifstarl{\MakePrivateOthers\Code@UsgEnvir}{\Code@UsgMacro}} % And then we launch the macros that close the group and do the work. \long\def\Code@DefMacro#1{% \Code@DefIndex#1% we use the internal macro; it'll close the group. \Code@MarginizeMacro#1} % \DefIndex\Code@UsgMacro \long\def\Code@UsgMacro#1{% \Code@UsgIndex#1% here also the internal macro; it'll close the group \Code@MarginizeMacro#1} % The next macro is taken verbatim ;-) from \docfm\ and the subsequent % |\let|s, too. % \DefIndex\codeline@wrindex \def\codeline@wrindex#1{\if@filesw \immediate\write\@indexfile {\string\indexentry{#1}% {\HLPrefix\number\c@codelinenum}}\fi} \def\codeline@glossary#1{% It doesn't need to establish a~group since % it is always called in a~group. \if@pageinclindex \edef\gmu@tempa{gmdindexpagecs{\HLPrefix}{relax}{\EntryPrefix}}% \else \edef\gmu@tempa{gmdindexrefcs{\HLPrefix}{relax}{\EntryPrefix}}% \inverb|relax| stands for the formatting command. But we don't want to do anything special with the change history entries. \ilrr \fi \protected@edef\gmu@tempa{% \@nx\protected@write\@nx\@glossaryfile{}% {\string\glossaryentry{#1\encapchar\gmu@tempa}% {\HLPrefix\number\c@codelinenum}}}% \gmu@tempa } % \changes[\changes]{v0.99m}{2008/08/09}{changed to write the line % number instead of page number by default and with % \env{codelineindex} option which seems to be more reasonable % especially with the \env{countalllines} option} % We initialize it due to the option (or lack of the option): \AtBeginDocument{% \if@pageindex \let\special@index=\index \let\gmd@glossary\glossary \else % \DefIndex\special@index \let\special@index=\codeline@wrindex \let\gmd@glossary\codeline@glossary % \label{codeline indexnumber declaration} \fi}% postponed till |\begin{document}| with respect of \docfm-like % declarations. % And in case we don't want to index: \def\gag@index{\let\index=\@gobble %\label{gag@index} \let\codeline@wrindex=\@gobble} % We'll use it in one more place or two. And we'll wish to be able to % undo it so % let's copy the original meanings: % \DefIndex\@@index \DefIndex\@@codeline@wrindex \StoreMacros{\index\codeline@wrindex} \def\ungag@index{\RestoreMacros{\index\@@codeline@wrindex}} %\label{ungag@index} % Our next task is to define macros that'll mark and index an % environment or other string in the code. Because of lack of % a~backslash, no environment's name is scanned so we have to proceed % different way. But we wish the user to have symmetric tools, i.e., % the `def' or `usage' use of an environment should be declared before % the line where the environment occurs. Note the slight difference % between these and the commands to declare a~\CS marking: the latter % do not require to be used \emph{immediately} before the line containig the % \CS to be marked. We separate indexing from marginizing to leave % a~possibility of doing only one of those things. % \DefIndex\Code@DefEnvir \long\def\Code@DefEnvir#1{% \endgroup \addto@estomarginpar{#1}% \addto@estoindex{#1}% \@defentryze{#1}{0}} % \DefIndex\Code@UsgEnvir \long\def\Code@UsgEnvir#1{% \endgroup \addto@estomarginpar{#1}% \addto@estoindex{#1}% \@usgentryze{#1}} % \DefIndex\addto@estomarginpar \long\def\addto@estomarginpar#1{% \edef\gmu@tempa{\@nx\do{\xiistring#1}}% we |\string| the argument to % allow it to be a~control sequence. \@xa\addtomacro\@xa\envirs@tomarginpar\@xa{\gmu@tempa}} % \DefIndex\addto@estoindex \long\def\addto@estoindex#1{% \edef\gmu@tempa{\@nx\do{\xiistring#1}} \@xa\addtomacro\@xa\envirs@toindex\@xa{\gmu@tempa}} % And now a~command to mark a~`usage' occurrence of a~\CS, environment % or another string in the commentary. As the `code' commands this also % has plain and starred version, first for \CSs appearing explicitly and the % latter for the strings and \CSs appearing implicitly. \def\TextUsage{\begingroup %\label{TextUsage} \MakePrivateLetters \@ifstarl{\MakePrivateOthers\Text@UsgEnvir}{\Text@UsgMacro}} % \DefIndex\Text@UsgMacro \long\def\Text@UsgMacro#1{% \endgroup{\tt\xiistring#1}% \Text@Marginize#1% \begingroup\Code@UsgIndex#1% we declare the kind of formatting of the entry. \text@indexmacro#1} % \DefIndex\Text@UsgEnvir \long\def\Text@UsgEnvir#1{% \endgroup{\tt\xiistring#1}% \Text@Marginize{#1}% \@usgentryze{#1}% we declare the `usage' kind of formatting of the % entry and index the sequence |#1|. \text@indexenvir{#1}} % We don't provide commands to mark a~macro's or environment's % definition present within the narrative because we think there won't % be any: one defines macros and environments in the code not in % the commentary. \def\TextMarginize{\begingroup \MakePrivateLetters \@ifstarl{\MakePrivateOthers\egText@Marginize}{\egText@Marginize}} % \DefIndex\egText@Marginize \long\def\egText@Marginize#1{\endgroup \Text@Marginize#1} % We check whether the margin pars are enabled and proceed % respectively in either case. \if@marginparsused \reversemarginpar \marginparpush\z@ \marginparwidth8pc\relax % ^^A \settowidth{\marginparsep}{\ \ }% % % You may wish to put not only macros and environments to % a~marginpar. \long\def\gmdmarginpar#1{% \marginpar{\raggedleft\strut \hskip0ptplus100ptminus100pt% #1}}%\stanza % \else \long\def\gmdmarginpar#1{}% \fi \long\def\Text@Marginize#1{% \gmdmarginpar{\marginpartt\xiistring#1}} % Note that the above macro will just gobble its argument if the % marginpars are disabled.^^A\NoEOF so far O.K. % % It may be advisable to choose a~condensed typewriter font for the % marginpars, if there is any. (The Latin Modern font family provides % a~light condensed typewriter font, it's set in \pk{gmdocc} class.) \let\marginpartt\tt % If we pront also the narration lines' numbers, then the index entries for \CSs and % environments marked in the commentary should have codeline numbers % not page numbers and that is |\let| in line % \ref{codeline indexnumber declaration}. On the other hand, if we % don't print narration lines' numbers, then a~macro or an environment marked in % the commentary should have page number not codeline number. This we % declare here, among others\ we add the letter |p| before the page number. % \DefIndex\do@properindex \def\do@properindex{%\label{do@properindex} \if@printalllinenos\else \@pageinclindextrue \let\special@index=\index \fi} % \stanza % In \docfm\ all the `working' \TeX\ code should be braced in(to) the % \env{macrocode} environments. Here another solutions are taken so to % be \docfm-compatible we only should % nearly-ignore \env{macrocode(*)}s % with their Percent and The Four Spaces Preceding ;-)\,. I.e., to ensure % the line ends are `queer'. And that the \ds\ directives will be % typeset as the \ds\ directives. And that the usual code escape % char will be restored at |\end{macrocode}|. And to add the vertical % spaces. % % ^^A~\NoEOF so far \acro{OK} % If you know \docfm\ conventions, note that \gmdoc\ \emph{does not} % require |\end{macrocode}| to be preceded ^^A( % with any particular number of any char :-)\,. % \changes{v0.98b}{06/09/07}{To \env{macrocode(*)} default % definitions \cs{QueerEOL} added} \newenvironment*{macrocode*}{%\label{macrocode*} \if@codeskipput\else\par\addvspace\CodeTopsep\@codeskipputgtrue\fi \QueerEOL}%^^A\docstrips {\par\addvspace\CodeTopsep\CodeEscapeChar\\} % Let's remind that the starred version makes | | % visible, which is the default in \pk{gmdoc} outside % \env{macrocode}. % % So we should make the spaces \emph{invisible} for the unstarred % version. \newenvironment*{macrocode}{%\label{macrocode} \if@codeskipput\else\par\addvspace\CodeTopsep\@codeskipputgtrue\fi \QueerEOL}% \changes{v0.99l}{2008/08/06}{removed \cs{CodeSpacesBlank}} {\par\addvspace\CodeTopsep\CodeEscapeChar\\} % Note that at the end of both the above environments the |\|'s % r\ocircum le % as the code escape char is restored. This is crafted for the % |\SpecialEscapechar| macro's compatibility: this macro influences % only the first \env{macrocode} environment. The situation that the % user wants some queer escape char in general and in a~particular % \env{macrocode} yet another seems to me ``unm\oumlaut glich, % Prinzessin''\footnote{Richard Strauss after Oscar Wilde, ^^B % \textit{Salome}.}. % % \stanza % Since the first \file{.dtx} I~tried to compile after the first % published version of \gmdoc\ uses a~lot of commented out code in % \env{macrocode}s, it seems to me necessary to add a~possibility to % typeset \env{macrocode}s as if they were a~kind of \env{verbatim}, % that is to leave the code layer and narration layer philosophy. % %\Define*{oldmc} \let\oldmc\macrocode \let\endoldmc\endmacrocode %\Define*{oldmc*} \n@melet{oldmc*}{macrocode*} \n@melet{endoldmc*}{endmacrocode*} % Now we arm \env{oldmc} and \env{olmc*} with % the macro looking for |% \end|\arg{envir name}. \addtomacro\oldmc{\@oldmacrocode@launch}% \@xa\addtomacro\csname oldmc*\endcsname{% \@oldmacrocode@launch} % \DefIndex\@oldmacrocode@launch \def\@oldmacrocode@launch{% \emptify\gmd@textEOL% to disable it in |\gmd@docstripdirective| % launched within the code. \gmd@ctallsetup \glet\stored@code@delim\code@delim \@makeother\^^B\CodeDelim\^^B% \ttverbatim \gmd@DoTeXCodeSpace% \@makeother\|% because |\ttverbatim| doesn't do that. \MakePrivateLetters% see line \ref{MPL}.\par % ^^A \@xa\@makeother\code@delim \docstrips@percent \@makeother\>% % sine qua non of the automatic delimiting is replacing possible % |*|\catother in the environment's name with |*|\catletter. % Not to complicate assume |*| may occur at most once and only at % the end. We also assume the environment's name consists only of % character tokens whose catcodes (except of |*|) will be the same % in the verbatim text. \@xa\gmd@currenvxistar\@currenvir*\relax \@oldmacrocode} \foone{\catcode`*11 } {\def\gm@xistar{*}} \def\gmd@currenvxistar#1*#2\relax{% \edef\@currenvir{#1\if*#2\gm@xistar\fi}} % The trick is that |#2| may be either |*|\catother\ or empty. If it's % |*|, the test is satisfied and |\if...\fi| expands to % |\gm@xistar|. If |#2| is empty, the test is also satisfied since % |\gm@xistar| expands to |*| but there's nothing to expand to. So, if % the environment's name ends with |*|\catother, it'll be substituted % with |*|\catletter or else nothing will be added. (Note that a~|*| % not at the end of env.\ name would cause a~disaster.) %^^A~ \Define\@oldmacrocode \foone{% \catcode`[=1 \catcode`]=2 \catcode`\{=\active \@makeother\} \@makeother\^^B \catcode`/=0 \catcode`\\=\active \catcode`&=14 \catcode`*=11 \catcode`\%=\active \obeyspaces}& % \CodeEscapeChar\/ \CDAnd [& here the \cs{foone}'s second pseudo-argument begins &%\stanza /def/@oldmacrocode[& /bgroup/let =/relax&% to avoid writing |/@nx | four times. /xdef/oldmc@def[& /def/@nx/oldmc@end####1/@nx% /@nx\end& /@nx{/@currenvir}[& ####1^^B/@nx/end[/@currenvir]/@nx/gmd@oldmcfinis]]& /egroup&% now |\oldmc@edef| is defined to have one parameter delimited &% with |\end|\arg{current env.'s name} /oldmc@def& /oldmc@end]&% \CDPerc ] \def\gmd@oldmcfinis{% \@xa\CodeDelim\stored@code@delim \gmd@mchook}% see line \ref{gmd@mchook} \def\OldMacrocodes{%% \changes{v0.99m}{2008/08/10}{renamed from %% \cs{VerbMacrocodes}} \let\macrocode\oldmc \n@melet{macrocode*}{oldmc*}} % To handle \ds\ directives in the code (in the old macrocodes % case that is). % \begin{oldmc} \foone{\catcode`\%\active} {\def\docstrips@percent{\catcode`\%\active \let%\gmd@codecheckifds}} % \end{oldmc}\ % The point is, the active |%| will be expanded when just after it is % the |\gmd@charbychar| cs token and next is some char, the |^^B| code % delimiter at least. So, if that char is |<|, we wish to launch % \ds\ directive typesetting. (Thanks to |\ttverbatim| all the |<| % are `other'.) \def\gmd@codecheckifds#1#2{% note that |#1| is just to gobble % \inverb|\gmd@charbychar| token. % ^^A \typeout{code if ds \on@line}% \if@dsdir\@dsdirgfalse \if\@nx<\@nx#2\afterfifi\gmd@docstripdirective \else\afterfifi{\xiipercent#1#2}% \fi \else\afterfi{\xiipercent#1#2}% \fi} % % \begin{environment}{macro} % Almost the same we do with the \env{macro(*)} environments, stating % only their argument to be processed as the `def' entry. Of course, % we should re|\catcode| it first. % \DefIndex*\macro \newenvironment{macro}{%\label{macro} \@tempskipa=\MacroTopsep \if@codeskipput\advance\@tempskipa by-\CodeTopsep\fi \par\addvspace{\@tempskipa}\@codeskipputgtrue \begingroup\MakePrivateLetters\MakePrivateOthers% we make also the % `private others' to cover the case of other sequence in the % argument. (We'll use the |\macro| macro also in the environment % for describing and defining environments.) \gmd@ifonetoken\Hybrid@DefMacro\Hybrid@DefEnvir}% % \DefIndex*\endmacro {\par\addvspace\MacroTopsep\@codeskipputgtrue} % It came out that the \docfm's author(s) give the \env{macro} % environment also starred versions of commands as argument. It's \acro{OK} % since (the default version of) |\MakePrivateLetters| makes |*| % a~letter and therefore such a~starred version is just one \CS. % However, in \pk{doc.dtx} occur \env{macro}s that mark % \emph{implicit} definitions i.e., such that the defined \CS is not % scanned in the subsequent code. % % \begin{macro*}{macro*} % And for those who want to to use this environment % for marking implicit definitions, define the star % version: \@namedef{macro*}{\let\gmd@ifonetoken\@secondoftwo\macro} % \DefIndex*\endmacro* \@xa\let\csname endmacro*\endcsname\endmacro % Note that \env{macro} and \env{macro*} have the same effect for % more-than-one-token arguments thanks to |\gmd@ifonetoken|'s meaning % inside unstarred \env{macro} (it checks whether the argument is % one-token and if it isn't, |\gmd@ifonetoken| switches execution to % `other sequence' path). % % The two environments behave different only with a~one-token % argument: \env{macro} postpones indexing it till the first scanned % occurrence while \env{macro*} till the first code line met. % \end{macro*} % \end{environment} % % \stanza % Now, let's complete the details. % First define an |\if|-like macro that turns true when the string % given to it consists of just one token (or one |{|\<text>|}|, to % tell the whole truth). \def\gmd@ifsingle#1#2\@@nil{% \def\gmu@tempa{#2}% \ifx\gmu@tempa\@empty} % Note it expands to an open |\if...| test (unbalanced with |\fi|) so it % has to be used as all the |\if|s, with optional |\else| and % obligatory |\fi|. And cannot be used in the possibly skipped % branches of other |\if...|s (then it would result with `extra % |\fi|/extra |\else|' errors). But the below usage is safe since both % |\gmd@ifsingle| and its |\else| and |\fi| are hidden in a~macro % (that will not be |\expandafter|ed). % % Note also that giving |\gmd@ifsingle| an |\if...| or so as the first % token of the argument will not confuse \TeX\ since the first token % is just gobbled. The possibility of occurrence of |\if...| or so as % a~not-first token seems to be negligible. \def\gmd@ifonetoken#1#2#3{% \def\gmu@tempb{#3}% We hide |#3| from \TeX\ in case it's |\if...| or % so. \inverb|\gmu@tempa| is used in \inverb|\gmd@ifsingle|. \ilrr \gmd@ifsingle#3\@@nil \afterfi{\@xa#1\gmu@tempb}% \else \edef\gmu@tempa{\@xa\string\gmu@tempb}% \afterfi{\@xa#2\@xa{\gmu@tempa}}% \fi} % Now, define the mysterious |\Hybrid@DefMacro| and |\Hybrid@DefEnvir| % macros. They mark their argument with a~certain subtlety: they put % it in a~marginpar at the point where they are and postpone indexing % it till the first scanned occurrence or just the first code line met. \long\def\Hybrid@DefMacro#1{% \Code@DefIndex{#1}% this macro closes the group opened by |\macro|. \Text@MarginizeNext{#1}} \long\def\Hybrid@DefEnvir#1{% \Code@DefIndexStar{#1}% this macro also closes the group begun by % |\macro|. \Text@MarginizeNext{#1}} \long\def\Text@MarginizeNext#1{% \gmd@evpaddonce{\Text@Marginize{#1}\ignorespaces}} %^^A~\strut from before Text@Marginize deleted as unnecessary in everypar. % The following macro adds its argument to |\everypar| using an auxiliary % macro to wrap the stuff in. The auxiliary macro has % a~self-destructor built in so it |\relax|es itself after first use. \long\def\gmd@evpaddonce#1{% \global\advance\gmd@oncenum\@ne \@xa\long\@xa\edef% \CodeUsgIndex*{NeuroOncer} \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname{% \@nx\g@relaxen \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname}% Why does it % work despite it shouldn't? Because when the \CS got with % \inverb|\csname...\endcsname| is undefined, it's equivalent % |\relax| and therefore unexpandable. That's why it passes % \inverb|\edef| and is able to be assigned.\ilrr \@xa\addtomacro\csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname{#1}% \@xa\addto@hook\@xa\everypar\@xa{% \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname}% } \newcount\gmd@oncenum %^^A % We store the number uniquifying the auxiliary %^^A % macro in a~macro to save count registers (cf.\ \pk{gmutils} %^^A % sec.\ \gmiflink{To Save Precious Count Registers}). % \begin{environment}{environment} % Wrapping a~description and definition of an environment in % a~\env{macro} environment would look inappropriate (`zgrzyta\l o by' % in Polish) although there's no \TeX nical obstacle to do % so. Therefore we define the \env{environment}, because of \ae^^B % sthetic and psychological reasons. \@xa\let\@xa\environment\csname macro*\endcsname \@xa\let\@xa\endenvironment\csname endmacro*\endcsname % \end{environment} % %\subdivision[Index exclude list]{\gmhypertarget{Index exclude list}} % We want some \CSs not to be indexed, e.g., the \LaTeX\ % internals and \TeX\ primitives. % % \docfm\ takes |\index@excludelist| to be a~|\toks| register to store % the list of expelled \CSs. Here we'll deal another way. For each \CS % to be excluded we'll make (|\let|, to be precise) a~control sequence % and then we'll be checking if it's undefined (|\ifx|-equivalent % |\relax|).\footnote{This idea comes from Marcin Woli\nacute ski.} % \def\DoNotIndex{\bgroup\MakePrivateLetters\DoNot@Index} % \changes{v0.97}{06/09/04}{\cs{MakePrivateLetters} added} % \changes{v0.98}{06/09/05}{Removed since it had not worked. The % macros in the argument should be separated with commas. I~understood % why it didn't work: because 't was iside a~command. So I~put it back} % \changes{v0.98d}{06/9/11}{Unmade \cs{global}} \long\def\DoNot@Index#1{\egroup% we close the group, \let\gmd@iedir\gmd@justadot% we declare the direction of the cluding % to be \emph{ex}cluding. We act this way to be able to reverse the % exclusions easily later.\ilrr \dont@index#1.} % \DefIndex\dont@index \long\def\dont@index#1{% \def\gmu@tempa{\@nx#1}% My \TeX\ Guru's trick to deal with |\fi| % and such, i.e., to hide from \TeX\ when it is processing a~test's % branch without expanding. \if\gmu@tempa.% a~dot finishes expelling \else \if\gmu@tempa,% The list this macro is put before may % contain commas and that's O.K., we just continue the work. \afterfifi\dont@index \else% what is else shall off the Index be expelled. {\escapechar\m@ne \xdef\gmu@tempa{\string#1}}% \@xa\let% \csname gmd/iexcl/\gmu@tempa\endcsname=\gmd@iedir% In the default % case explained e.g.\ by the macro's name, the last macro's % meaning is such that the test in line \ref{iexcltest} will % turn false and the subject \CS shall not be indexed. % We |\let| not |\def| to spare \TeX's memory. \afterfifi\dont@index \fi \fi} %^^A( % Let's now give the exclude list copied \*verbatim ;-) from % \pk{doc.dtx}. I~give it in the code layer because I~suppose one will % document not \LaTeX\ source but normal packages. % % \begin{CodeSpacesSmall} % \DoNotIndex\DoNotIndex \Define\DefaultIndexExclusions \DoNotIndex\{ \DoNotIndex\}% \label{DNIbraces}the index entries of % these two \CSs would be rejected by MakeIndex anyway. \begin{MakePrivateLetters}% Yes, |\DoNotIndex| does % |\MakePrivateLetters| on its own but No, it won't have any effect % if it's given in another macro's |\def|. % \HideAllDefining \gdef\DefaultIndexExclusions{% \DoNotIndex{\@ \@@par \@beginparpenalty \@empty}%\label{DIE1} \DoNotIndex{\@flushglue \@gobble \@input}% \DoNotIndex{\@makefnmark \@makeother \@maketitle}% \DoNotIndex{\@namedef \@ne \@spaces \@tempa}% \DoNotIndex{\@tempb \@tempswafalse \@tempswatrue}% \DoNotIndex{\@thanks \@thefnmark \@topnum}% \DoNotIndex{\@@ \@elt \@forloop \@fortmp \@gtempa \@totalleftmargin}% \DoNotIndex{\" \/ \@ifundefined \@nil \@verbatim \@vobeyspaces}% \DoNotIndex{\| \~ \ \active \advance \aftergroup \begingroup \bgroup}% \DoNotIndex{\mathcal \csname \def \documentstyle \dospecials \edef}% \DoNotIndex{\egroup}% \DoNotIndex{\else \endcsname \endgroup \endinput \endtrivlist}% \DoNotIndex{\expandafter \fi \fnsymbol \futurelet \gdef \global}% \DoNotIndex{\hbox \hss \if \if@inlabel \if@tempswa \if@twocolumn}% \DoNotIndex{\ifcase}% \DoNotIndex{\ifcat \iffalse \ifx \ignorespaces \index \input \item}% \DoNotIndex{\jobname \kern \leavevmode \leftskip \let \llap \lower}% \DoNotIndex{\m@ne \next \newpage \nobreak \noexpand \nonfrenchspacing}% \DoNotIndex{\obeylines \or \protect \raggedleft \rightskip \rm \sc}% \DoNotIndex{\setbox \setcounter \small \space \string \strut}% \DoNotIndex{\strutbox}% \DoNotIndex{\thefootnote \thispagestyle \topmargin \trivlist \tt}% \DoNotIndex{\twocolumn \typeout \vss \vtop \xdef \z@}% \DoNotIndex{\, \@bsphack \@esphack \@noligs \@vobeyspaces \@xverbatim}% \DoNotIndex{\` \catcode \end \escapechar \frenchspacing \glossary}% \DoNotIndex{\hangindent \hfil \hfill \hskip \hspace \ht \it \langle}% \DoNotIndex{\leaders \long \makelabel \marginpar \markboth \mathcode}% \DoNotIndex{\mathsurround \mbox}%\verb+% \newcount \newdimen \newskip+ \DoNotIndex{\nopagebreak}% \DoNotIndex{\parfillskip \parindent \parskip \penalty \raise \rangle}% \DoNotIndex{\section \setlength \TeX \topsep \underline \unskip}% \DoNotIndex{\vskip \vspace \widetilde \\ \% \@date \@defpar}% \DoNotIndex{\[ \]}% see line \ref{DNIbraces}. \DoNotIndex{\count@ \ifnum \loop \today \uppercase \uccode}% \DoNotIndex{\baselineskip \begin \tw@}% \DoNotIndex{\a \b \c \d \e \f \g \h \i \j \k \l \m \n \o \p \q}% \DoNotIndex{\r \s \t \u \v \w \x \y \z \A \B \C \D \E \F \G \H}% \DoNotIndex{\I \J \K \L \M \N \O \P \Q \R \S \T \U \V \W \X \Y \Z}% \DoNotIndex{\1 \2 \3 \4 \5 \6 \7 \8 \9 \0}% \DoNotIndex{\! \# \$ \& \' \( \) \. \: \; \< \= \> \? \_}% |\+| % seems to be so rarely used that it may be advisable to index it. \DoNotIndex{\discretionary \immediate \makeatletter \makeatother}% \DoNotIndex{\meaning \newenvironment \par \relax \renewenvironment}% \DoNotIndex{\repeat \scriptsize \selectfont \the \undefined}% \DoNotIndex{\arabic \do \makeindex \null \number \show \write \@ehc}% \DoNotIndex{\@author \@ehc \@ifstar \@sanitize \@title}% \DoNotIndex{\if@minipage \if@restonecol \ifeof \ifmmode}% \DoNotIndex{\lccode %|%\newtoks| \onecolumn \openin \p@ \SelfDocumenting}% \DoNotIndex{\settowidth \@resetonecoltrue \@resetonecolfalse \bf}% \DoNotIndex{\clearpage \closein \lowercase \@inlabelfalse}% \DoNotIndex{\selectfont \mathcode \newmathalphabet \rmdefault}% \DoNotIndex{\bfdefault}% % From the above list I~removed some |\new...| declarations because % I~think it may be useful to see gathered the special |\new...|s of % each kind. For the same reason I~would not recommend excluding % from the index such declarations as |\AtBeginDocument|, % |\AtEndDocument|, |\AtEndOfPackage|, |\DeclareOption|, % |\DeclareRobustCommand| etc. But the % common definitions, such as |\new/providecommand| and % |\(e/g/x)def|s, as the most common, in my opinion excluded should % be.^^A\) % % \stanza % And some my exclusions: \DoNotIndex{\@@input \@auxout \@currentlabel \@dblarg}% \DoNotIndex{\@ifdefinable \@ifnextchar \@ifpackageloaded}% \DoNotIndex{\@indexfile \@let@token \@sptoken \^}% the latter comes % from \CSs like |\^^M|, see sec. \ref{Tasks}. \DoNotIndex{\addto@hook \addvspace}% \DoNotIndex{\CurrentOption}% \DoNotIndex{\emph \empty \firstofone}% \DoNotIndex{\font \fontdimen \hangindent \hangafter}% \DoNotIndex{\hyperpage \hyperlink \hypertarget}% \DoNotIndex{\ifdim \ifhmode \iftrue \ifvmode \medskipamount}% \DoNotIndex{\message}% \DoNotIndex{\NeedsTeXFormat \newcommand \newif}% \DoNotIndex{\newlabel}% \DoNotIndex{\of}% % ^^A\PassOptionsToClass\PassOptionsToPackage \DoNotIndex{\phantom \ProcessOptions \protected@edef}% \DoNotIndex{\protected@xdef \protected@write}% \DoNotIndex{\ProvidesPackage \providecommand}% \DoNotIndex{\raggedright}% \DoNotIndex{\raisebox \refstepcounter \ref \rlap}% ^^A\RequirePackage \DoNotIndex{\reserved@a \reserved@b \reserved@c \reserved@d}% \DoNotIndex{\stepcounter \subsection \textit \textsf \thepage \tiny}% \DoNotIndex{\copyright \footnote \label \LaTeX}% % \changes[\DefaultIndexExclusions]{v0.98a}{06/09/06}{more % macros added to the `exclude list'} \DoNotIndex{\@eha \@endparenv \if@endpe \@endpefalse \@endpetrue}% \DoNotIndex{\@evenfoot \@oddfoot \@firstoftwo \@secondoftwo}% \DoNotIndex{\@for \@gobbletwo \@idxitem \@ifclassloaded}% \DoNotIndex{\@ignorefalse \@ignoretrue \if@ignore}% \DoNotIndex{\@input@ \@input}% \DoNotIndex{\@latex@error \@mainaux \@nameuse}% \DoNotIndex{\@nomath \@oddfoot}%|%\@onlypreamble| should be indexed % \acro{IMO}. \DoNotIndex{\@outerparskip \@partaux \@partlist \@plus}% \DoNotIndex{\@sverb \@sxverbatim}% \DoNotIndex{\@tempcnta \@tempcntb \@tempskipa \@tempskipb}%\\ % I~think the layout parameters even the kernel, should not be % excluded: \inverb|\@topsep| \inverb|\@topsepadd|^^B % \ \inverb|\abovedisplayskip| \inverb|\clubpenalty| etc. \DoNotIndex{\@writeckpt}% \DoNotIndex{\bfseries \chapter \part \section \subsection}% \DoNotIndex{\subsubsection}% \DoNotIndex{\char \check@mathfonts \closeout}% \DoNotIndex{\fontsize \footnotemark \footnotetext \footnotesize}% \DoNotIndex{\g@addto@macro \hfilneg \Huge \huge}% \DoNotIndex{\hyphenchar \if@partsw \IfFileExists }% \DoNotIndex{\include \includeonly \indexspace}% \DoNotIndex{\itshape \language \LARGE \Large \large}% \DoNotIndex{\lastbox \lastskip \m@th \makeglossary}% \DoNotIndex{\maketitle \math@fontsfalse \math@fontstrue \mathsf}% \DoNotIndex{\MessageBreak \noindent \normalfont \normalsize}% \DoNotIndex{\on@line \openout \outer}% \DoNotIndex{\parbox \part \rmfamily \rule \sbox}% \DoNotIndex{\sf@size \sffamily \skip}% \DoNotIndex{\textsc \textup \toks@ \ttfamily \vbox}% % \changes[\DoNotIndex]{v0.97}{06/09/04}{Excluding some star-versions of % commands} % \nostanza\noindent % |%% \DoNotIndex{\begin*}| maybe in the future, if the idea gets % popular\dots \nostanza \DoNotIndex{\hspace* \newcommand* \newenvironment* \providecommand*}% \DoNotIndex{\renewenvironment* \section* \chapter*}%\label{DIE2} }% of |\DefaultIndexExclusions|.\par % I~put all the expellings into a~macro because I~want them % to be optional. \end{MakePrivateLetters} % \end{CodeSpacesSmall} \ResumeAllDefining % And we execute it due to the (lack of) counter-corresponding option: \if@indexallmacros\else \DefaultIndexExclusions \fi % If we expelled so many \CSs, someone may like it in general but % he/she may need one or two expelled to be indexed back. So % \def\DoIndex{\bgroup\MakePrivateLetters\Do@Index} % \changes{v0.97}{06/09/04}{\cs{MakePrivateLetters} added.} % \changes{v0.98}{06/09/05}{\cs{MakePrivateLetters} removed since it % hadn't worked. I~understood why it didn't work: because % 't was iside a~command and I~put it back} % \changes{v0.98d}{06/9/11}{Unmade \cs{global}} \long\def\Do@Index#1{\egroup\@relaxen\gmd@iedir\dont@index#1.}% note % we only redefine an auxiliary \CS and launch also |\dont@index| inner % macro. % And if a~user wants here make default exclusions and there do not % make them, \heshe\ may use the |\DefaultIndexExclusions| declaration % \himher self. This declaration \acro{OCSR}, but anyway let's provide the % counterpart. It \acro{OCSR}, too. % \def\UndoDefaultIndexExclusions{% \StoreMacro\DoNotIndex % ^^A\dont@index \let\DoNotIndex\DoIndex % ^^A \let\dont@index=\do@index \DefaultIndexExclusions % ^^A \RestoreMacro\dont@index \RestoreMacro\DoNotIndex} % \changes{v0.98d}{06/9/11}{Unmade \cs{global}} % % % \subdivision{Index parameters} % % \begin{quotation}The |\IndexPrologue| macro is used to place a short % message into the document above the index. It is implemented by % redefining |\index@prologue|, a macro which holds the default % text. We'd better make it a |\long| macro to allow |\par| commands % in its argument.\end{quotation} \long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack} % \label{IndexPrologue} \def\indexdiv{\@ifundefined{chapter}{\section*}{\chapter*}} % \changes{v0.98a}{06/09/06}{modified to contain the star so that % it may be redefined for tests.} \@ifundefined{index@prologue} {\def\index@prologue{\indexdiv{Index}% \markboth{Index}{Index}% Numbers written in italic refer to the \if@pageindex pages \else code lines \fi where the corresponding entry is described; numbers underlined refer to the \if@pageindex\else code line of the \fi definition; numbers in roman refer to the \if@pageindex pages\else code lines \fi where the entry is used. \if@pageindex\else \ifx\HLPrefix\@empty The numbers preceded with `p.' are page numbers. \else The numbers with no prefix are page numbers. \fi\fi \ifx\IndexLinksBlack\relax\else All the numbers are hyperlinks. % ^^A, they are made black just to let Adobe Reader work % ^^A~faster. \fi \gmd@dip@hook% this hook is intended to let a~user add % something without redefining the entire prologue, see below. }}{} % During the preparation of this package for publishing I~needed % only to add something at the end of the default index prologue. So % \DefIndex\gmd@dip@hook \@emptify\gmd@dip@hook \long\def\AtDIPrologue#1{\g@addto@macro\gmd@dip@hook{#1}} % \changes{v0.98c}{06/9/8}{added because of need} % The Author(s) of \docfm\ assume \pk{multicol} is known not to % everybody. My assumption is the other so \RequirePackage{multicol} % \begin{quotation}If \pk{multicol} is in use, when the index is % started we compute % the remaining space on the current page; if it is greater than % |\IndexMin|, the first part of the index will then be placed in the % available space. The number of columns set is controlled by the % counter |\c@IndexColumns| which can be changed with a % |\setcounter| declaration.\end{quotation} \newdimen\IndexMin \IndexMin = 133pt\relax% originally it was set % 80\,pt, but with my default prologue there's at least 4.7\,cm needed % to place the prologue and some index entries on the same page. \newcount\c@IndexColumns \c@IndexColumns = 3 \renewenvironment{theindex} {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]% \IndexLinksBlack \IndexParms \let\item\@idxitem \ignorespaces}% {\end{multicols}} \def\IndexLinksBlack{\hypersetup{linkcolor=black}}% To make Adobe % Reader work faster. \@ifundefined{IndexParms} {\def\IndexParms{% % \label{IndexParms} \parindent \z@ \columnsep 15pt \parskip 0pt plus 1pt \rightskip 15pt \mathsurround \z@ \parfillskip=-15pt plus 1 fil % \docfm\ defines this parameter % rigid but that's because of the stretchable space (more % precisely, a~|\dotfill|) between the item and the entries. But % in \pk{gmdoc} we define no such special delimiters, so we add % an ifinite stretch. \small \def\@idxitem{\par\hangindent 30pt}% \def\subitem{\@idxitem\hspace*{15pt}}% \def\subsubitem{\@idxitem\hspace*{25pt}}% \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}% \ifx\EntryPrefix\@empty\else\raggedright\fi% long (actually, % a~quite \emph{short but nonempty} entry prefix) made space % stretches so terribly large in the justified paragraphs that % we should make |\raggedright| rather. \ifnum\c@IndexColumns>\tw@\raggedright\fi% the numbers in narrow % col\-umns look better when they are |\raggedright| in my opinion. }}{} \def\PrintIndex{% we ensure the standard meaning of the line end % character not to cause a~disaster. \@ifQueerEOL{\StraightEOL\printindex\QueerEOL}% {\printindex}} % Remember that if you want to change not all the parameters, you % don't have to redefine the entire |\IndexParms| macro but you may % use a~very nice \LaTeX\ command |\g@addto@macro| (it has |\global| % effect, also with an apeless name (|\gaddtomacro|) provided by % \pk{gmutils}. (It adds its second argument at the end of definition % of its first argument provided the first argument is a~no-argument % macro.) Moreover, \pk{gmutils} provides also % |\addtomacro| that has the same effect except it's not |\global|. % % % % \subdivision{The \ds\ directives} % %^^A \StraightEOL %^^A \iffalse ^^A~ this passage is obsoleted %^^A %^^A This passage is obsoleted on 2006/11/30. %^^A %^^A In the \gmdoc\ thinking, the \ds\ directives belong to the %^^A narration layer since they all begin with |%|. For now I~don't %^^A have a~more minimal idea than to define a~pair of macros the first of %^^A which would |\active|ate the |<| and the other, assigned to the %^^A active |<|, would do the work and re`other' the |<| back. %^^A %^^A We provide two versions of the seargant-activating macro: the first %^^A makes only the first subsequent seargant typeset a~\ds\ %^^A directive (and the previous meaning of the |<| will be restored, the %^^A latter doesn't restore the previous meaning of |<| after (by) the %^^A first occurrence and the latter obeys usual scoping rules while the %^^A scoping rules of the first (|\docstrip|) are more strict: the scope %^^A is delimited by the first occurrence of the subject~|<|. %^^A %^^A Let us remeber that, just as all the control sequences except %^^A |\relax|, you can use |\docstrips| as an environment, i.e., in the %^^A |\begin{docstrips}|\dots |\end{docstrips}| syntax. And, that %^^A \env{macrocode} environment declares it. %^^A \bgroup\catcode`\<=\active %^^A \firstofone{\egroup %^^A % \stanza %^^A \newcommand*\docstrip{% %^^A \gmd@storesearg %^^A \catcode`\<=\active %^^A \gmd@setdocstrips %^^A \let\gmd@docstripshook=\gmd@restoresearg}% %^^A % \stanza %^^A \newcommand*\docstrips{% %^^A \catcode`\<=\active %^^A \gmd@setdocstrips %^^A \@emptify\gmd@docstripshook}% %^^A % \stanza %^^A \def\gmd@setdocstrips{% %^^A \def<{\ifmmode\sgtleftxii\else\afterfi\gmd@docstripdirective\fi}} %^^A %\stanza %^^A \def\gmd@storesearg{% %^^A \edef\gmd@SeargantCat{\the\catcode`\<}% %^^A \ifnum\gmd@SeargantCat=\active %^^A \let\gmd@SeargantMng=<% %^^A \fi} %^^A % \stanza %^^A \def\gmd@restoresearg{% %^^A \catcode`\<=\gmd@SeargantCat\relax %^^A \ifnum\gmd@SeargantCat=\active %^^A \let<=\gmd@SeargantMng %^^A \fi}% %^^A % \stanza %^^A }% of |\active| |<|'s |\firstofone| %^^A %^^A \fi ^^A~of the obsoletion iffalse %^^A \QueerEOL \foone{\@makeother\<\@makeother\> \glet\sgtleftxii=<} { \def\gmd@docstripdirective{% \begingroup\let\do=\@makeother \do\*\do\/\do\+\do\-\do\,\do\&\do\|\do\!\do\(\do\)\do\>\do\<% ^^Ayes, we % ^^A make \inverb|<|\catother\ since a~directive |<<|\<any text till ^^B>> % ^^A~the end of line> theoretically may occur. \@ifnextchar{<}{% \let\do=\@makeother \dospecials \gmd@docstripverb} {\gmd@docstripinner}}% \def\gmd@docstripinner#1>{% \endgroup \def\gmd@modulehashone{% \Module{#1}\space \@afternarrgfalse\@aftercodegtrue\@codeskipputgfalse}% % ^^A \gmd@docstripshook \gmd@textEOL\gmd@modulehashone} % A~word of explanation: first of all, we % close the group for changed |\catcode|s; the directive's text has its % |\catcode|s fixed. Then we put the directive's text wrapped with the % formatting macro into one macro in order to give just one token % the \gmdoc's \TeX\ code scanner. % ^^A But before we launch the \TeX\ code % ^^A scanning with all the b\&w, we virtually restore the meaning of % ^^A further |<|s to let them start further \ds\ directives, % ^^A and after this possible restore (if it \emph{actually} takes place % ^^A depends on the declaration used: |\docstrip| or |\docstrips|) we % Then launch this big \TeX\ code scanning machinery by calling % |\gmd@textEOL| which is an alias for the `narrative' meaning of the % line end. This macro opens the verbatim group and launches the % char-by-char scanner. That is this scanner because of what we % encapsulated the directive's text with the formatting into one % macro: to let it pass the scanner. % % That's why in the `old' macrocodes case the active |%| closes the % group before launching |\gmd@docstripdirective|. % % \stanza % The `verbatim' directive macro works very similarly. } \foone{\@makeother\<\@makeother\> \glet\sgtleftxii=< \catcode`\^^M=\active}% { \def\gmd@docstripverb<#1^^M{% \endgroup% \def\gmd@modulehashone{% \ModuleVerb{#1}\@afternarrgfalse\@aftercodegtrue% \@codeskipputgfalse}% \gmd@docstripshook% \gmd@textEOL\gmd@modulehashone^^M}% } % (\*Verbatim ;-) from \docfm:) \providecommand*\Module[1]{{\mod@math@codes$\langle\mathsf{#1}\rangle$}} \providecommand*\ModuleVerb[1]{{\mod@math@codes$\langle\langle\mathsf{#1}$}} \def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026 } % \subdivision{The changes history} % % The contents of this section was copied \*verbatim from the % \docfm's documentation, with only smallest necessary changes. Then ^^A(( % my additions were added :-))\,. % % \begin{quotation}To provide a change history log, the |\changes| % command has been % introduced. This takes [one optional and] three [mandatory] % arguments, respectively, [the macro that'll become the entry's % second level,] the version % number of the file, the date of the change, and some detail % regarding what change has been made [i.e., the description of the % change]. The [second] of these arguments % is otherwise ignored, but the others are written out and may be % used to generate a history of changes, to be printed at the end of % the document. [\dots\ I~ommit an obsolete remark about then-older % MakeIndex's versions.] % % The output of the |\changes| command goes into the % \<Glossary_File> and therefore uses the normal |\glossaryentry| % commands. Thus MakeIndex or a~similar program can be used to % process the output into a sorted ``glossary''. The |\changes| % command commences by taking the usual measures to hide its % spacing, and then redefines |\protect| for use within the argument % of the generated |\indexentry| command. We re-code nearly all % chars found in |\@sanitize| to letter since the use of special % package which make some characters active might upset the % |\changes| command when writing its entries to the file. However % we have to leave |%| as % comment and | | as \<space> otherwise chaos will happen. And, of % course the |\| should be available as escape character.\end{quotation} % % We put the definition inside a~macro that will be % executed by (the first use of) |\RecordChanges|. And we provide % the default definition of |\changes| as a~macro just gobbling its % arguments. We do this to provide no changes' writing out if % |\RecordChanges| is not used. % % % \changes[\changes]{v0.98e}{06/09/23}{definition put into a~macro that shall % launch it when \cs{RecordChanges} is executed and the default % defining it as a~gobbling macro} % \def\gmd@DefineChanges{% \outer\long\def\changes{\@bsphack\begingroup\@sanitize \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore \MakePrivateLetters \StraightEOL \MakeGlossaryControls \changes@}} \newcommand\changes[4][]{\PackageWarningNoLine{gmdoc}{% ^^JThe \bslash changes command used \on@line ^^Jwith no \string\RecordChanges\space declared. ^^JI shall not warn you again about it}% %^^A\gmd@countlines{#4}% \renewcommand\changes[4][]{%^^A\gmd@countlines{#4} }} \def\MakeGlossaryControls{% \edef\actualchar{\string=}\edef\quotechar{\string!}% \edef\levelchar{\string>}\edef\encapchar{\xiiclub}}%for the glossary the % `actual', the `quote' and the `level' chars are respectively |=|, % |!| and |>|, the `encap' char remains untouched. I~decided to % preserve the \docfm's settings for the compatibility. \newcommand\changes@[4][\generalname]{% % \changes[\changes]{v0.97}{06/09/04}{The optional pseudo-argument % added intended to be the macro-entry.} \if@RecentChange{#3}% if the date is later than the one stored in % \cs{c@Chang\+es\+Start\+Date}, \@tempswafalse \ifx\generalname#1% then we check whether a~\CS-entry is given % in the optional first argument or is it unchanged. \ifx\last@defmark\relax\else% if no particular \CS is % specified in |#1|, we check whether |\last@defmark| contains % something and if so, we put it into |\gmu@tempb| scratch macro. \@tempswatrue \edef\gmu@tempb{% it's a~bug fix: while typesetting traditional % \file{.dtx}es, \inverb|\last@defmark| came out with \inverb|\| at the % beginning (which resulted with \inverb|\\|\<name> in the change % log) but while typesetting the `new' way, it occurred % without the bslash. So we gobble the bslash if it's % present and two lines below we handle the exception of % \inverb|\last@defmark|\equals|{\}| (what would happen if % a~definition of \inverb|\\| was marked in new way \gmdoc ing).%^^A] \if\bslash\last@defmark\else\last@defmark\fi}% \ifx\last@defmark\bslash\let\gmu@tempb\last@defmark\fi% \n@melet{gmd@glossCStest}{gmd/isaCS/\last@defmark}% \fi \else%the first argument isx not |\generalname| i.e., %a~particular \CS is specified by it (if some day one % wishes to |\changes| |\generalname|, \heshe\ should type % |\changes[generalname]|\dots) \@tempswatrue {\escapechar\m@ne \xdef\gmu@tempb{\string#1}}% \if\bslash\@xa\@firstofmany\string#1\relax\@@nil% we check % whether \inverb|#1| is a~\CS\dots\ilrr \def\gmd@glossCStest{1}%\dots\ and tell the glossary if so. \fi % ^^A~\@xa\quote@mname\@tempb\relax \fi \@ifundefined{gmd@glossCStest}{\def\gmd@glossCStest{0}}{}% \protected@edef\gmu@tempa{\@nx\gmd@glossary{% \if\relax\GeneralName\relax\else \GeneralName% it's for the |\DocInclude| case to precede % every |\changes| of the same file with the file name, cf.\ line % \ref{GeneralName}. \fi #2\levelchar% \if@tempswa% If the macro |\last@defmark| % doesn't contain any \CS name (i.e., is empty) nor |#1| % specifies a~\CS, the current % changes entry was done at top-level. In this case we precede % it by |\generalname|. \gmu@tempb \actualchar\bslash verb*% \if\verbatimchar\gmu@tempb$\else\verbatimchar\fi \if1\gmd@glossCStest\quotechar\bslash\fi \gmu@tempb \if\verbatimchar\gmu@tempb$\else\verbatimchar\fi \else \space\actualchar\generalname \fi :\levelchar%^^A\gmd@deeolize{ #4%^^A} }}% \gmu@tempa \grelaxen\gmd@glossCStest \fi% of |\if@recentchange| %^^A\gmd@countlines{#4}% \endgroup\@esphack} % Let's initialize |\last@defmark| and |\GeneralName|. \@relaxen\last@defmark \@emptify\GeneralName \def\ChangesGeneral{\grelaxen\last@defmark}% If automatic detection of % definitions is on, the default entry of |\changes| is the meaning of % |\last@defmark|, the last detected definiendum that is. The % declaration defined here serves to start a~scope of `general' % \cs{changes}' entries. \AtBegInput{\ChangesGeneral} % Let's explain |\if@RecentChange|. We wish to check whether the % change's date is later than date declared (if any limit date % \emph{was} declared). First of all, let's establish a~counter to store % the declared date. The untouched counters are equal 0 so if no date % is declared there'll be no problem. The date will have the % \<YYYYMMDD> shape both to be easily compared and readable. \newcount\c@ChangesStartDate \def\if@RecentChange#1{% \gmd@setChDate#1\@@nil\@tempcnta \ifnum\@tempcnta>\c@ChangesStartDate} \def\gmd@setChDate#1/#2/#3\@@nil#4{% the last parameter will be a~|\count| % register. #4=#1\relax \multiply#4 by\@M \count8=#2\relax% I~know it's a~bit messy not to check whether the % |#4| |\count| is |\count8| but I~know this macro will only be used % with |\count0 | \nlpercent(\cs{@\+te\+m\+p\+cn\+ta}) and some % higher (not a~scratch) one. \multiply\count8 by100 % \advance#4 by\count8 \count8=\z@ \advance#4 by#3\relax} % Having the test defined, let's define the command setting the date % counter. |#1| is to be the version and |#2| the date % \cs[]{\{\<year>/\<month>/\<day>\}}. \def\ChangesStart#1#2{% % \changes{v0.98e}{06/09/23}{\cs{string}s added before the seargants % in the message with account of \cs{docstrip(s)}} \gmd@setChDate#2\@@nil\c@ChangesStartDate \typeout{^^JPackage gmdoc info: ^^JChanges' start date #1 memorized as \string<\the\c@ChangesStartDate\string> \on@line.^^J} \advance\c@ChangesStartDate\m@ne% we shall show the changes \emph{at ^^B % the specified day} and later. \ifnum\c@ChangesStartDate>19820900 %\unskip\StraightEOL\footnote{^^A % DEK writes in \textit{\TeX, The Program} of September 1982 as the % date of \TeX\ Version 0.}\QueerEOL\label{TeXVer0} % see \gmiflink[personalchanges]{below}. \edef\gmu@tempa{% \@nx\g@addto@macro\@nx\glossary@prologue{% The changes \if\relax\GeneralName\relax\else of \GeneralName\space\fi earlier than #1 \if\relax#1\relax #2\else(#2)\fi\space are not shown.}}% \gmu@tempa \fi} % (Explanation to line \ref{TeXVer0}.) % \gmhypertarget[personalchanges]{My} \TeX\ Guru has remarked that the % change history tool should be used for documenting the changes that % may be significant for the users not only for the author and talking % of what may be significant to the user, no changes should be hidden % since the first published version. However, the changes' start date % may be used to provide hiding the author's `personal' notes: \heshe\ % should only date the `public' changes with the four digit year and % the `personal' ones with two digit year and set % |\ChangesStart{}{1000/0/0}| or so. % % In line \ref{TeXVer0} I~establish a~test value that corresponds to % a~date earlier than any \TeX\ stuff and is not too small (early) to % ensure that hiding the two digit year changes shall not be mentioned % in the changes prologue. % % \changes{v0.98d}{2006/9/15}{An entry to show the change history % works: watch and admire. Some sixty \cs{changes} entries irrelevant % for the users-other-than-myself are hidden due to the trick % described on % p.\protect\,\protect\pageref{personalchanges}.% % \protect\StoreMacro\protect\hyperpage % \protect\def\protect\hyperpage#1{\protect\RestoreMacro\protect\hyperpage}% % \protect\gobble} % \stanza % \begin{quotation}The entries [of a~given version number] are sorted % for convenience by the name of [the macro explicitly specified as % the first argument or] the most recently introduced macroname % (i.e., that in the most recent |\begin{macro}| command [or % |\Define|]). We therefore provide [|\last@defmark|] to % record that argument, and provide a default definition in case % |\changes| is used outside a \env{macro} environment. (This is a % wicked hack to get such entries at the beginning of the sorted % list! It works providing no macro names start with |!| or |"|.) % % This macro holds the string placed before changes entries on % top-level.\end{quotation} \def\generalname{General} % \changes[\chschange]{v0.98a}{06/09/06}{added.} % % \stanza % \begin{quotation}To cause the changes to be written (to a \pk{.glo}) % file, we define |\RecordChanges| % to invoke \LaTeX's usual |\makeglossary| command.\end{quotation} % % I~add to it also the |\write|ing definition of the |\changes| macro % to ensure no changes are written out without |\RecordChanges|. % \def\RecordChanges{\makeglossary\gmd@DefineChanges \@relaxen\RecordChanges} % \changes{v0.98c}{06/09/08}{made self-\cs{relax}ing} % \changes{v0.98e}{06/09/23}{made it defining \cs{changes}} % \begin{quotation}The remaining macros are all analogues of those used % for the \env{theindex} environment. % When the glossary is started we compute the space which remains at % the bottom of the current page; if this is greater than |\GlossaryMin| then the % first part of the glossary will be placed in the available space. The number of % columns set [is] controlled by the counter |\c@GlossaryColumns| which can be % changed with a |\setcounter| declaration.\end{quotation} % \begin{CodeSpacesBlank} \newdimen\GlossaryMin \GlossaryMin = 80pt % \DefIndex*\c@GlossaryColumns \newcount\c@GlossaryColumns \c@GlossaryColumns = 2 % \end{CodeSpacesBlank} %\begin{quotation}The environment \env{theglossary} is defined in the %same manner as the \env{theindex} % environment.\end{quotation} % \newenvironment{theglossary}{% % \changes{v0.99m}{2008/08/10}{added \cs{IndexLinksBlack}} \begin{multicols}\c@GlossaryColumns [\glossary@prologue][\GlossaryMin]% \GlossaryParms \IndexLinksBlack \let\item\@idxitem \ignorespaces}% {\end{multicols}} % Here is the MakeIndex style definition: % \index{gmglo.ist@\file{gmglo.ist}} %^^A \begin{docstrips} %</package> %<+gmglo>preamble %<+gmglo>"\n \\begin{theglossary} \n %<+gmglo>\\makeatletter\n" %<+gmglo>postamble %<+gmglo>"\n\n \\end{theglossary}\n" %<+gmglo>keyword "\\glossaryentry" %<+gmglo>actual '=' %<+gmglo>quote '!' %<+gmglo>level '>' %<*package> %^^A \end{docstrips} % The MakeIndex shell command for the glossary should look as % follows: % \[|makeindex -r -s gmglo.ist -o |\<myfile>|.gls |\<myfile>|.glo|\] % ^^B % ^^B makeindex -r -s gmglo.ist -o <myfile>.gls <myfile>.glo % ^^B % where |-r| commands MakeIndex not to make implicit page ranges, % |-s| commands MakeIndex to use the style stated next not the % default settings and the |-o| option with the subsequent filename % defines the name of the output. % % \begin{quotation}The |\GlossaryPrologue| macro is used to place % a~short message above the glossary into the document. It is % implemented by redefining |\glossary@prologue|, a macro which % holds the default text. We better make it a long macro to allow % |\par| commands in its argument.\end{quotation} % \long\def\GlossaryPrologue#1{\@bsphack \def\glossary@prologue{#1}% \@esphack} % \begin{quotation}Now we test whether the default is already defined % by another package file. If not we define it.\end{quotation} % \changes{v0.98a}{06/09/06}{a~bug fixed: \cs{filediv} replaced with % \cs{indexdiv} in the default prologue.} \@ifundefined{glossary@prologue} {\def\glossary@prologue{\indexdiv{{Change History}}% \markboth{{Change History}}{{Change History}}% }}{} %\begin{quotation}Unless the user specifies otherwise, we set the %change history using the same parameters as for the index.\end{quotation} % \Define\GlossaryParms \AtBeginDocument{% \@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms}{}} %\begin{quotation} % To read in and print the sorted change history, just put the % |\PrintChanges| command as the last (commented-out, and thus % executed during the documentation pass through the file) command in % your package file. 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.\end{quotation} \Define\PrintChanges \def\PrintChanges{% to avoid a~disaster among queer EOLs: \@ifQueerEOL {\StraightEOL\@input@{\jobname.gls}\QueerEOL}% {\@input@{\jobname.gls}}% \g@emptify\PrintChanges} \pdef\toCTAN#1#2{%\ % \begin{enumargs} % \item version number, % \item date \<year/month/day>. % \end{enumargs} % \changes{v0.99r}{2008/11/22}{added} \changes{#1}{#2}{put to \acro{CTAN} on #2}} % % \subdivision{The checksum} % % % \docfm\ provides a~checksum mechanism that counts the backslashes % in the scanned code. Let's do almost the same. % % At the beginning of the source file you may put the |\CheckSum| % macro with a~number (in one of \TeX's formats) as its argument and % \TeX\ with \pk{gmdoc} shall count the number of the \emph{escape ^^B % chars} in the source file and tell you in the \file{.log} file (and % on the terminal) % whether you have typed the right number. If you don't type |\CheckSum|, % \TeX\ anyway will tell you how much it is. \newcount\check@sum \def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack} \newcounter{CheckSum} % \label{checksum} \newcommand*\step@checksum{\stepcounter{CheckSum}} % And we'll use it in the line \ref{checksumUse} (|\stepcounter| is % |\global|). See also the |\chschange| declaration, % l.\,\ref{chschange}. % % However, the check sum mechanism in \gmdoc\ behaves slightly % different than in \docfm\ which % is nicely visible while \pk{gmdoc}ing \docfm: \docfm\ states its % check sum to be 2171 and our count counts 2126. The mystery lies in % the fact that \docfm's CheckSum mechanism counts the code's % backslashes no matter what they mean and the \gmdoc's the escape % chars so, among others, |\\| at the default settings increases \docfm's % CheckSum by 2 while the \gmdoc's by 1. (There are 38 occurrences of |\\| % in \pk{doc.dtx} \env{macrocode}s, I~counted % myself.)\begin{StraightEOL}\footnote{My opinion is that nowadays % a~check sum % is not necessary for checking the completness of a~file but % I~like it as a~marker of file development and this more than % that is its r\ocircum le in \gmdoc.} % \end{StraightEOL} % % % \begin{quotation}But |\Finale| will be called at the very end of a % file. This is exactly the point were we want to know if the file % is uncorrupted. Therefore we also call |\check@checksum| at this % point.\end{quotation} % In \pk{gmdoc} we have the |\AtEndInput| hook. \AtEndInput{\check@checksum} % Based on the lines 723--741 of \pk{doc.dtx}. \def\check@checksum{\relax \ifnum\check@sum=\z@ \edef\gmu@tempa{% why \cs{edef}---see line \ref{wypis sumy} \@nx\typeout{**********************************^^J% * The input file \gmd@inputname\space has no Checksum stated.^^J% * The current checksum is \the\c@CheckSum.^^J% \gmd@chschangeline% a~check sum changes history entry, see below. * (package gmdoc info.)^^J% **********************************^^J}} \else \ifnum\check@sum=\c@CheckSum \edef\gmu@tempa{% \@nx\typeout{*****+*+*+*+*+*+*+*+*+*+^^J% * The input file \gmd@inputname: Checksum passed.^^J% \gmd@chschangeline * (package gmdoc info.)^^J% *****+*+*+*+*+*+*+*+*+*+^^J}} \else \edef\gmu@tempa{% \@nx\typeout{********!*!*!*!*!*!*!*!*!*!*!*!^^J% *! The input file \gmd@inputname:^^J% *! The CheckSum stated: \the\check@sum\space<> my count: \the\c@CheckSum.^^J% \gmd@chschangeline *! (package gmdoc info.)^^J% ********!*!*!*!*!*!*!*!*!*!*!*!^^J}}% \fi \fi \gmu@tempa \@xa\AtEndDocument\@xa{\gmu@tempa}%\label{wypis sumy} we print % the checksum notification on the terminal immediately and at end % of \TeX ing not to have to scroll the output far nor search the log. \global\check@sum\z@} % As I~mentioned above, I~use the check sum mechanism to mark the file % growth. Therefore I~provide a~macro that produces a~line on the % terminal to be put somewhere at the % beginning of the source file's commentary for instance. \def\gmd@chschangeline{% \xiipercent\space\string\chschange {\@ifundefined{fileversion}{v???}{\fileversion}}% {\the\year/\the\month/\the\day}% {\the\c@CheckSum}^^J% \xiipercent\space\string\chschange {\@ifundefined{fileversion}{v???}{\fileversion}}% {\@xa\@gobbletwo\the\year/\the\month/\the\day}% {% with two di\-g\-it year in case you use |\ChangesStart|. \the\c@CheckSum}^^J} % And here the meaning of such a~line is defined: \newcommand*\chschange[3]{%\label{chschange} \csname changes\endcsname{#1}{#2}{CheckSum #3}% |\csname...| because % \nlpercent\cs{cha\+n\+g\+es} is \inverb|\outer|. \CheckSum{#3}} % It will make a~`General' entry in the change history unless % used in some |\Define|'s scope or inside a~\env{macro} % environment. It's intended to be put % somewhere at the beginning of the documented file. % % % \changes[\CheckSum]{v0.98a}{06/09/06}{`package gmdoc info' % statement moved to the end of the checksum messages.} % \changes[\CheckSum]{v0.98b}{06/09/07}{typing out the % \cs{chschange} line added} % % % \subdivision{Macros from \pk{ltxdoc}} % % I'm not sure whether this package still remains `minimal' but % I~liked the macros provided by \pk{ltxdoc.cls} so much\dots % \stanza % % The next page setup declaration is intended to be used % with the \pk{article}'s default Letter paper size. But since \newcommand*\ltxPageLayout{% %\begin{quotation}Increase the text width slightly so that width the standard fonts % 72 columns of code may appear in a |macrocode| environment.\end{quotation} % \setlength{\textwidth}{355pt}% % \begin{quotation}Increase the marginpar width slightly, for long % command names. And increase the left margin by a similar % amount.\end{quotation} % To make these settings independent from the defaults (changed e.g.\ % in \pk{gmdocc.cls}) we replace the original |\addtolength|s with % |\setlength|s. %^^A \addtolength\marginparwidth{30pt}% %^^A \addtolength\oddsidemargin{20pt}% %^^A \addtolength\evensidemargin{20pt} \setlength\marginparwidth{95pt}% \setlength\oddsidemargin{82pt}% \setlength\evensidemargin{82pt}} % %\skiplines % \def\task#1#2{} % % What is this for? Probably to turn an obsolete command off. Or maybe % % a~\acro{TODO}? % % \endskiplines %\subdivision{\cs{DocInclude} and the \pk{ltxdoc}-like setup} % % Let's provide a~command for including % multiple files into one document. In the \pk{ltxdoc} class such % a~command is defined to include files as parts. But we prefer to % include them as chapters in the classes that provide % |\chapter|. We'll redefine |\maketitle| so that it make a~chapter or % a~part heading \emph{unlike} in \pk{ltxdoc} where the file parts % have their titlepages with only the filename and \pk{article}-like titles % made by |\maketitle|. % % But we will also provide a~possibility of typesetting multiple files % exactly like with the \pk{ltxdoc} class. % % \begin{macro}{\DocInclude} % % So, define the |\DocInclude| command, that acts % \begin{quotation}more or less exactly the same as |\include|, but % uses |\DocInput| on a \pk{dtx} [or \pk{.fdd}] file, not |\input| on % a \pk{tex} file.\end{quotation} % Our version will accept also \pk{.sty}, \pk{.cls}, and \pk{.tex} % files. % % \changes{v0.98}{06/09/05}{\cs{@makeother\protect\bslash_} added} \newcommand*\DocInclude{\bgroup\@makeother\_\Doc@Include}% First, we % make \inverb|_| `other' in order to allow it in the filenames. \newcommand*{\Doc@Include}[2][]{% originally it took just one % argument. Here we make it take two, first of which is intended to % be the path (with the closing \inverb |/|). This is intended not to print % the path in the page footers only the filename.\par % \CodeUsage\HLPrefix \egroup% having the arguments read, we close the group opened by the % previous macro for |_|\catother. \gdef\HLPrefix{\filesep}% \gdef\EntryPrefix{\filesep}% we define two rather kernel parameters % to expand to the file marker. The first will bring the information % to one of the default \inverb|\IndexPrologue|'s % |\if|s. Therefore the % definition is global. The latter is such for symmetry. \def\GeneralName{#2\actualchar\pk{#2} }% \label{GeneralName} for the % changes'history main level entry. % % Now we check whether we try to include ourselves and if % so---we'll (create and) read an \file{.auxx} file instead of % (the main) \file{.aux} to avoid an infinite recursion of |\input|s. % \edef\gmd@jobname{\jobname}% \edef\gmd@difilename{% we want the filename all `other', just as % in \inverb|\jobname|. \@xa\@xa\@xa\@gobble\@xa\string\csname#2\endcsname}% \ifx\gmd@jobname\gmd@difilename \def\gmd@auxext{auxx}% \else \def\gmd@auxext{aux}% \fi \relax %^^A\if@ltxDocInclude \clearpage % ^^A\fi \gmd@docincludeaux \def\currentfile{gmdoc-IncludeFileNotFound.000}% \let\fullcurrentfile\currentfile \IfFileExists{#1#2.fdd}{\edef\currentfile{#2.fdd}}{% it's not \pk{.fdd}, \IfFileExists{#1#2.dtx}{\edef\currentfile{#2.dtx}}{% it's not \pk{.dtx} % either, \IfFileExists{#1#2.sty}{\edef\currentfile{#2.sty}}{% it's not % \pk{.sty}, \IfFileExists{#1#2.cls}{\edef\currentfile{#2.cls}}{% it's % not \pk{.cls}, \IfFileExists{#1#2.tex}{\edef\currentfile{#2.tex}}{% it's % not \pk{.tex}, \IfFileExists{#1#2.fd}{\edef\currentfile{#2.fd}}{% so it % must be \pk{.fd} or error. \PackageError{gmdoc}{\string\DocInclude\space file #1#2.fdd/dtx/sty/cls/tex/fd not found.}}}}}}}% % \changes{v0.98j}{06/10/16}{\pk{.fdd} added in \cs{DocInclude}'s % search for the extension.} \edef\fullcurrentfile{#1\currentfile}% \ifnum\@auxout=\@partaux \@latexerr{\string\DocInclude\space cannot be nested}\@eha \else \@docinclude{#1}#2 \fi}% Why is |#2| delimited with | | not % braced as we are used to, one may ask. % \changes[\DocInclude]{v0.97}{06/09/03}{\cs{@docinclude} gets 2 params % in order to \cs{includeonly} work as expected, with only the names % (w.o. the paths)} \def\@docinclude#1#2 {% To match the macro's parameter string, is an % answer. But why is |\@docinclude| defined so? Originally, in % \pk{ltxdoc} it takes one argument and it's delimited with a~space % probably in resemblance to the true |\input| \nlpercent(|\@@input| in % \LaTeX). ^^A\if@ltxDocInclude \clearpage %^^A\fi \if@filesw \gmd@writemauxinpaux{#2.\gmd@auxext}\fi% this strange macro with % a~long name is another thing to allow |_| in the filenames (see % line \ref{gmd@writemauxinpaux}). \@tempswatrue \if@partsw \@tempswafalse\edef\gmu@tempb{#2}% \@for \gmu@tempa:=\@partlist\do{\ifx\gmu@tempa\gmu@tempb\@tempswatrue\fi}% \fi \if@tempswa \let\@auxout\@partaux \if@filesw \immediate\openout\@partaux #2.\gmd@auxext\relax% Yes, only |#2|. It's to % create and process the partial \pk{.aux(x)} files always in the main % document's (driver's) directory. % \changes[\DocInclude]{v0.97}{06/09/04}{\protect\TeX forced to % process the partial \pk{.aux}es in the main document directory} \immediate\write\@partaux{\relax}% \fi % \begin{quotation}We need to save (and later restore) various % index-related commands which might be changed by the included % file.\end{quotation} % \changes{v0.98a}{06/09/06}{\cs{MacroStoringDo} renamed (in % \pk{gmutils}) to \cs{StoringAndRelaxingDo}, and % \cs{MacroRestoringDo} to \cs{RestoringDo}.} \StoringAndRelaxingDo\gmd@doIndexRelated \if@ltxDocInclude\part{\currentfile}% In the \pk{ltxdoc}-like setup % we make a~part title page with only the filename and the file's % |\maketitle| will typeset an \pk{article}-like title. \else\let\maketitle=\InclMaketitle \fi% In the default setup we % redefine |\maketitle| to typeset a~common chapter or part heading. \if@ltxDocInclude\xdef@filekey\fi \GetFileInfo{\currentfile}% it's my (GM) addition with the account % of using file info in the included files' title/\:heading etc. \incl@DocInput{\fullcurrentfile}% originally just |\currentfile|. \if@ltxDocInclude\else\xdef@filekey\fi% in the default case we add % new file to the file key \emph{after} the input because in this % case it's the files own |\maketitle| what launches the % sectioning command that increases the counter. % \par And here is the moment to restore the index-related % commands. \RestoringDo\gmd@doIndexRelated % ^^A\if@ltxDocInclude \clearpage % ^^A\fi \gmd@writeckpt{#1#2}% \if@filesw \immediate\closeout\@partaux \fi \else\@nameuse{cp@#1#2}% \fi \let\@auxout\@mainaux}% end of |\@docinclude|. % \end{macro} % % (Two is a~sufficient number of iterations to define a~macro for.) \def\xdef@filekey{{\@relaxen\ttfamily% \label{LetTTFRelax}This % assignment is very trickly crafted: it makes \emph{all} % |\ttfamily|s present in the |\filekey|'s expansion unexpandable % not only the one added in this step. \xdef\filekey{\filekey, \thefilediv={\ttfamily\currentfile}}}} % To allow |_| in the filenames we must assure |_| will be \catother\ % while reading the filename. Therefore define % \DefIndex\gmd@writemauxinpaux \def\gmd@writemauxinpaux#1{% \label{gmd@writemauxinpaux} % this name comes from `\emph{write} outto \emph main % \emph{\pk{.aux}} to \emph{in}put \emph partial % \emph{\pk{.aux}}'.\par % We wrap |\@input{|\<partial \pk{.aux}>|}| in a~|_|\catother\ % hacked scope. This hack is especially recommended here since the % \pk{.aux} file may contain a~non-|\global| stuff that should not % be localized by a~group that we would have to establish if we % didn't use the hack. (Hope you understand it. If not, notify me % and for now I'll only give a~hint: ``Look at it with the \TeX's % eyes''. More uses of this hack are to be seen in \pk{gmutils} % where they are a~bit more explained.) \immediate\write\@mainaux{% \bgroup\string\@makeother\string\_% \string\firstofone{\egroup \string\@input{#1}}}} % We also slightly modify a~\LaTeX\ kernel macro |\@writeckpt| to % allow |_| in the file name. % \changes[\DocInclude]{v0.98a}{06/09/06}{\cs{@writeckpt} wrapped % with \cs{firstofone} hack to allow \cs[]{_} in the file names.} % \DefIndex\gmd@writeckpt \def\gmd@writeckpt#1{% \immediate\write\@partaux{% \string\bgroup\string\@makeother\string\_% \string\firstofone\@charlb\string\egroup} \@writeckpt{#1}% \immediate\write\@partaux{\@charrb}} \def\gmd@doIndexRelated{% \do\tableofcontents \do\makeindex \do\EnableCrossrefs \do\PrintIndex \do\printindex \do\RecordChanges \do\PrintChanges \do\theglossary \do\endtheglossary} \@emptify\filesep % The \pk{ltxdoc} class establishes a~special number format for % multiple file documentation numbering needed to document the \LaTeX\ % sources. I~like it too, so \def\aalph#1{\@aalph{\csname c@#1\endcsname}} \def\@aalph#1{% \ifcase#1\or a\or b\or c\or d\or e\or f\or g\or h\or i\or j\or k\or l\or m\or n\or o\or p\or q\or r\or s\or t\or u\or v\or w\or x\or y\or z\or A\or B\or C\or D\or E\or F\or G\or H\or I\or J\or K\or L\or M\or N\or O\or P\or Q\or R\or S\or T\or U\or V\or W\or X\or Y\or Z\else\@ctrerr\fi} % A~macro that initialises things for |\DocInclude|. \def\gmd@docincludeaux{% % We set the things for including the files only once. \global\@relaxen\gmd@docincludeaux % By default, we will include multiple files into one document % as chapters in the classes that provide |\chapter| and as parts % elsewhere. \ifx\filediv\relax \ifx\filedivname\relax% (nor |\filediv| neither % |\filedivname| is defined by the user) % \changes[\filediv]{v0.98a}{06/09/06}{definition moved into % \cs{DocInclude} and let \cs{relax} by default ($\quotechar=$a~bug fix).} \@ifundefined{chapter}{% \SetFileDiv{part}}%\changes[\DocInclude]{v0.98f}{06/9/29}{\cs{filediv(name)} % defined as \cs[]{(\protect\bslash)part} for the classes that % don't know \cs{chapter}} {\SetFileDiv{chapter}}% \else% (|\filedivname| is defined by the user, |\filediv| is not) \SetFileDiv{\filedivname}% why not? Inside is |\edef| so it'll work. \fi \else% (|\filediv| is defined by the user \ifx\filedivname\relax% and |\filedivname| is not) %^^A~I~deleted a~six level test which one sectioning command %^^A~|\filedivname| isx. \PackageError{gmdoc}{You've redefined \string\filediv\space without redefining \string\filedivname.}{Please redefine the two macros accordingly. You may use \string\SetFileDiv{name without bslash}.}% \fi \fi % \changes[\DocInclude]{v0.99m}{2008/08/09}{ % resetting of codeline number with every % \cs{filedivname} commented out because with the % \env{countalllines} option it caused that reset at \cs{maketitle} % after some lines of file} % ^^A \@addtoreset{codelinenum}{\filedivname}% remember it has % ^^A~a~|\global| effect in fact. For each file we'll reset % ^^A~\env{codelinenum}. \def\thefilediv{\aalph{\filedivname}}% The files will be numbered % with letters, lowercase first. \@xa\let\csname the\filedivname\endcsname=\thefilediv% This % li\-ne lets |\the|\<chapter> etc.\ equal |\thefilediv|. \def\filesep{\thefilediv-}% File separator (identifier) for the index. \let\filekey=\@gobble \g@addto@macro\index@prologue{% \gdef\@oddfoot{\parbox{\textwidth}{\strut\footnotesize \raggedright{\bfseries File Key:} \filekey}}% The footer for % the pages of index. \glet\@evenfoot\@oddfoot}% \label{oneside}anyway, it's intended to % be oneside. \g@addto@macro\glossary@prologue{% \gdef\@oddfoot{\strut Change History\hfill\thepage}% The footer % for the changes history. \glet\@evenfoot\@oddfoot}% % \changes[\DocInclude]{v0.98c}{06/9/10}{Change History footer % defined} \gdef\@oddfoot{% The footer of the file pages will be its name and, % if there is a~file info, also the date and version. \@xa\ifx\csname ver@\currentfile\endcsname\relax File \thefilediv: {\ttfamily\currentfile} % \else \GetFileInfo{\currentfile}% File \thefilediv: {\ttfamily\filename} % Date: \filedate\ % Version \fileversion \fi \hfill\thepage}% \glet\@evenfoot\@oddfoot% see line \ref{oneside}. % ^^A \show\filedivname% for debug \@xa\def\csname\filedivname name\endcsname{File}% we % redefine the name of the proper division to `File'. \ifx\filediv\section \let\division=\subsection \let\subdivision=\subsubsection \let\subsubdivision=\paragraph % If |\filediv| is higher than % |\section| we don't change the three divisions (they are % |\section|, |\subsection| and |\subsubsection| by default). % |\section| seems to me the lowest reasonable sectioning command % for the file. If |\filediv| is lower you should rather rethink % the level of a~file in your documentation not redefine the two % divisions. \fi}% end of |\gmd@docincludeaux|. % The |\filediv| and |\filedivname| macros should always be set % together. Therefore provide a~macro that takes care of both at % once. Its |#1| should be a~sectioning name without the backslash. \def\SetFileDiv#1{% \edef\filedivname{#1}% \@xa\let\@xa\filediv\csname#1\endcsname} % \changes{v0.98c}{06/9/10}{added and a~bug fixed in \cs{docincludeaux}} \def\SelfInclude{\DocInclude{\jobname}} % \changes{v0.98a}{06/09/06}{added in response to the needs of the % first user, of me that is} % \changes{v0.99l}{2008/08/05}{Made a~shorthand for % \cs{Docinclude}\cs{jobname} instead of repeating 99\% of % \cs{DocInclude}'s code} % The \pk{ltxdoc} class makes some preparations for inputting multiple % files. We are not sure if the user wishes to use \pk{ltxdoc}-like % way of documenting (maybe \heshe\ will prefer what I~offer, % \pk{gmdocc.cls} e.g.), so we put % those preparations into a~declaration. % \newif\if@ltxDocInclude \newcommand*\ltxLookSetup{% \SetFileDiv{part}% \ltxPageLayout \@ltxDocIncludetrue } \@onlypreamble\ltxLookSetup % The default is that we |\DocInclude| the files due to the original % \gmdoc\ input settings. \let\incl@DocInput=\DocInput \@emptify\currentfile% for the pages outside the % |\DocInclude|'s scope. In force for all includes. % %^^A \iffalse %^^A % \stanza %^^A % But it may be not a~usual situation to include the source files %^^A % as with \pk{ltxdoc} but with the \emph{new} |\DocInput| macro. So %^^A % let's |\def| %^^A % \Define\ltxMultidocOldSetup %^^A \newcommand*\ltxMultidocOldSetup{% %^^A \ltxMultidocSetup %^^A \let\incl@DocInput=\OldDocInput} %^^A %^^A \@onlypreamble\ltxMultidocOldSetup %^^A %^^A And, for the symmetry, if you prefer the look offered by %^^A me, but %^^A \fi % If you want to |\Doc/SelfInclude| \docfm-likes: \newcommand*\olddocIncludes{% \let\incl@DocInput=\OldDocInput} % And, if you have set the previous and want to set it back: \newcommand*\gmdocIncludes{% \let\incl@DocInput=\DocInput \AtBegInput{\QueerEOL}}% to move back the |\StraightEOL| declaration put % at begin input by |\olddocIncludes|. % % % \subdivision{Redefinition of \cs{maketitle}} % % A~not-so-slight alteration of the \TextUsage\maketitle\ command in % order it allow multiple titles in one document seems to me very % clever. So let's copy again (\pk{ltxdoc.dtx} the lines 643--656): % % \begin{quotation}The macro to generate titles is easily altered in % order that it can be used more than once (an article with many % titles). In the original, diverse macros were concealed % after use with |\relax|. We must cancel anything that may have been % put into |\@thanks|, etc., otherwise all titles will carry forward % any earlier such setting!\end{quotation} % But here in \pk{gmdoc} we'll do it locally for (each) input % not to change the main title settings if there are any. \AtBegInput{%^^A~ why provide not just \cs{def}? \providecommand*\maketitle{\par \begingroup \def \thefootnote {\fnsymbol {footnote}}% \setcounter {footnote}\z@ \def\@makefnmark{\hbox to\z@{$\m@th^{\@thefnmark}$\hss}}% \long\def\@makefntext##1{\parindent 1em\noindent \hbox to1.8em{\hss$\m@th^{\@thefnmark}$}##1}% \if@twocolumn \twocolumn [\@maketitle ]% \else \newpage \global \@topnum \z@ \@maketitle \fi % \begin{quotation}For special formatting requirements (such as in % \acro{TUG}boat), we use pagestyle |titlepage| for this; this is later defined % to be |plain|, unless already defined, as, for example, by % \pk{ltugboat.sty}.\end{quotation} \thispagestyle{titlepage}\@thanks \endgroup %\begin{quotation}If the driver file % documents many files, we don't want parts of a title of one to % propagate to the next, so we have to cancel these:\end{quotation} \setcounter {footnote}\z@ \gdef\@date{\today}\g@emptify\@thanks% \g@emptify\@author\g@emptify\@title% }%\par % \begin{quotation}When a number of articles are concatenated into % a~journal, for example, it is not usual for the title pages of % such documents to be formatted differently. Therefore, a class % such as \pk{ltugboat} can define this macro in advance. However, % if no such definition exists, we use pagestyle plain for title % pages.\end{quotation} \@ifundefined{ps@titlepage}{\let\ps@titlepage=\ps@plain}{}% % \par And let's provide |\@maketitle| just in case: an error occurred % without it at \TeX ing with \pk{mwbk.cls} because this class with the % default options does not define |\@maketitle|. The below definitions % are taken from \pk{report.cls} and \pk{mwrep.cls}. \providecommand*\@maketitle{% \newpage\null \vskip 2em\relax% \begin{center}% \titlesetup \let \footnote \thanks {\LARGE \@title \par}% \vskip 1.5em% {\large \lineskip .5em% \begin{tabular}[t]{c}% \strut \@author \end{tabular}\par}% \vskip 1em% {\large \@date}% \end{center}% \par \vskip 1.5em\relax}%\par % We'd better restore the primary meanings of the macros making % a~title. (\LaTeXe\ source, File F: ltsect.dtx Date: 1996/12/20 Version % v1.0z, lines 3.5.7.9--12.14--17.) \providecommand*\title[1]{\gdef\@title{#1}} \providecommand*\author[1]{\gdef\@author{#1}} \providecommand*\date[1]{\gdef\@date{#1}} \providecommand*\thanks[1]{\footnotemark \protected@xdef\@thanks{\@thanks \protect\footnotetext[\the\c@footnote]{#1}}% }% \providecommand*\and{%| % \begin{tabular}| \end{tabular}% \hskip 1em \@plus.17fil% \begin{tabular}[t]{c}}%| % \end{tabular}| % And finally, let's initialize \cs{tit\+le\+set\+up} if it is not yet. \providecommand*\titlesetup{}% }% end of |\AtBegInput|. % % \changes[\titlesetup]{v0.98c}{06/09/08}{\cs{provide}d \cs[]{\{\}}} % % % The \pk{ltxdoc} class redefines the |\maketitle| command to allow % multiple titles in one document. We'll do the same and something % more: our |\Doc/SelfInclude| will turn the file's |\maketitle| into % a~part or chapter heading. But, if hte |\ltxLookSetup| declaration % is in force, |\Doc/SelfInclude| will make for an included file % a~part's title page and an \pk{article}-like title. % % \stanza % Let's initialize the file division macros. \@relaxen\filediv \@relaxen\filedivname \@relaxen\thefilediv % \changes[\thefilediv]{v0.99m}{2008/08/06}{let to \cs{relax} by % default} % If we don't include files the \pk{ltxdoc}-like way, we wish to % redefine |\maketitle| so that it typesets a~division's heading. % % Now, we redefine |\maketitle| and its relatives. % \def\InclMaketitle{% % \changes{v0.98a}{06/09/05}{renamed from \cs{incl@maketitle} because % I~needed it in self-input hacks.} {\def\and{, }% we make |\and| just a~comma. {\let\thanks=\@gobble% for the toc version of the heading we % discard |\thanks|. \protected@xdef\incl@titletotoc{\@title\if@fshda\protect\space (\@author)\fi}% we add the author iff the `files have % different authors' \nlpercent(|@fshda|) }% \def\thanks##1{\footnotemark \protected@xdef\@thanks{\@thanks% to keep the previous |\thanks| % if there were any. \protect\footnotetext[\the\c@footnote]{##1}}}% for some % mysterious reasons so defined |\thanks| do typeset the footnote % mark and text but they don't hyperlink it % properly. A~\pk{hyperref} bug? \@emptify\@thanks \protected@xdef\incl@filedivtitle{% [{\incl@titletotoc}]% braces to allow |[| and % |]| in the title to toc. {\protect\@title {\smallerr% this macro is provided by the \pk{gmutils} % package after the \pk{relsize} package. \if@fshda\\[0.15em]\protect\@author \if\relax\@date\relax\else, \fi \else \if\relax\@date\relax\else\\[0.15em]\fi \fi % The default is that all the included files have the same % author(s). In this case we won't print the author(s) in % the headings. Otherwise we wish to print them. The % information which case are we in is brought by the % |\if@fshda| switch defined in line \ref{@fshda}. % % If we wish to print the author's name % (|\if@fshda|), then we'll print the date after the author, separated % with a~comma. If we don't print the author, there still may be % a~date to be printed. In such a~case we break the line, too, and % print the date with no comma. \protect\@date}}% end of |\incl@filedivtitle|'s brace (2nd % or 3rd argument). }% end of |\incl@filedivtitle|'s |\protected@xdef|.\par % We |\protect| all the title components to avoid expanding % |\footnotemark| hidden in |\thanks| during |\protected@xdef| % (and to let it be executed during the typesetting, of course). }% end of the comma-|\and|'s group. \@xa\filediv\incl@filedivtitle \@thanks \g@relaxen\@author \g@relaxen\@title \g@relaxen\@date \g@emptify\@thanks }% end of |\InclMaketitle|. % What I~make the default, is an assumption that all the % multi-documented files have the same author(s). % And with the account of the other possibility I~provide % the below switch and declaration. \newif\if@fshda % \label{@fshda} (its name comes from \textit file\textit s % \textit have \textit different \textit authors). \newcommand*\PrintFilesAuthors{\@fshdatrue} % And the counterpart, if you change your mind: \newcommand*\SkipFilesAuthors{\@fshdafalse} % \subdivision{The file's date and version information} % Define |\filedate| and friends from info in the % |\ProvidesPackage| etc.\ commands. \def\GetFileInfo#1{% \def\filename{#1}% \def\gmu@tempb##1 ##2 ##3\relax##4\relax{% \def\filedate{##1}% \def\fileversion{##2}% \def\fileinfo{##3}}% \edef\gmu@tempa{\csname ver@#1\endcsname}% \@xa\gmu@tempb\gmu@tempa\relax? ? \relax\relax} % Since we may documentally input files that we don't load, as \docfm\ % e.g., let's define a~declaration to be put (in the comment layer) % before the line(s) containing |\Provides...|. The |\FileInfo| % command takes the stuff till the closing |]| and subsequent line % end, extracts from it the info and writes it to the \file{.aux} and % rescans the stuff. \eTeX\ provides a~special primitive for that % action but we remain strictly \TeX nical and do it with writing to % a~file and inputting that file. \newcommand*\FileInfo{% \bgroup \gmd@ctallsetup \bgroup% yes, we open two groups because we want to rescan tokens in % `usual' catcodes. We cannot put \incs{gmd@ctallsetup} into the % inner macro because when that will be executed, the % \incs{inputlineno} will be too large (the last not the first line). \let\do\@makeother \do\ \do\{\do\}\do\^^M\do\\% \gmd@fileinfo} % \changes{v0.99d}{2007/04/26}{added} \foone{% \catcode`!\z@ \catcode`(\@ne \catcode`)\tw@ \let\do\@makeother \do\ % we make space `other' to keep it for scanning the code where % it may be leading. \do\{\do\}\do\^^M\do\\}%\CodeEscapeChar\! (% !def!gmd@fileinfo#1Provides#2{#3}#4[#5]#6^^M% (!egroup% we close the group of changed catcodes, the catcodes % of the arguments are set. And we are still in the group for % \incs{gmd@ctallsetup}. !gmd@writeFI(#2)(#3)(#5)% !gmd@FIrescan(#1Provides#2{#3}#4[#5]#6)% this macro will close the group. %\changes[\FileInfo]{v0.99m}{2008/08/09}{\cs{egroup} of the % inner macro moved to the end to allow \cs{gmd@ctallsetup}. From the % material passed to \cs{gmd@FIrescan} ending \hathat{M} stripped not % to cause double labels.} )% \CodeEscapeChar\\ ) \def\gmd@writeFI#1#2#3{% % ^^A \typeout{@@@ write FI}\show\relax \immediate\write\@auxout{% \global\@nx\@namedef{% ver@#2.\if P\@firstofmany#1\@@nil sty\else cls\fi}{#3}}} \foone\obeylines{% \def\gmd@FIrescan#1{% % \changes{v0.99l}{2008/08/06}{\cs{scantokens} used instead of % \cs{write} and \cs{@@input} which simplified the macro} % ^^A \newwrite\gmd@docrescanfile % ^^A \immediate\openout\gmd@docrescanfile=\jobname.docrescan\relax {\newlinechar=`\^^M\scantokens{#1}}\egroup^^M}} % And, for the case the input file doesn't contain |\Provides...|, % a~macro for explicit providing the file % info. It's written in analogy to |\ProvidesFile|, \pk{source ^^B % 2${}_\epsilon$}, file L v1.1g, l.\,102. \def\ProvideFileInfo#1{% \begingroup \catcode`\ 10 \catcode\endlinechar 10 % \@makeother\/\@makeother\&% \kernel@ifnextchar[{\gmd@providefii{#1}}{\gmd@providefii{#1}[]}%^^A] } % \changes{v0.98a}{06/09/06}{added} % \DefIndex\gmd@providefii \def\gmd@providefii#1[#2]{%\\ % (we \emph{don't} write the file info to \pk{.log}) \@xa\xdef\csname ver@#1\endcsname{#2}% \endgroup} % And a~self-reference abbreviation (intended for providing file info % for the driver): \def\ProvideSelfInfo{\ProvideFileInfo{\jobname.tex}} % A~neat conventional statement used in \docfm's documentation e.g., % to be put in |\thanks| to the title or in a~footnote: \newcommand*\filenote{This file has version number \fileversion{} dated \filedate{}.} % And exactly as |\thanks|: \newcommand*\thfileinfo{\thanks\filenote} % % % \subdivision{Miscellanea} % % The main inputting macro, |\DocInput| has been provided. But there's % another one in \docfm\ and it looks very reasonably: % \gmhypertarget[IndexInput]{\cs{IndexInput}}. Let's make analogous one % here: \foone{\obeylines}% {% \def\IndexInput#1{% \changes{v0.98b}{06/09/07}{\cs{StoreMacro}ing %% and \cs{RestoreMacro}ing % \cs{code@delim} added} \StoreMacro\code@delim% \CodeDelim\^^Z% \def\gmd@iihook{% \label{iihook}this hook is |\edef|ed! \@nx^^M% \code@delim\relax\@nx\let\@nx\EOFMark\relax}%^^A\@nx^^M \DocInput{#1}\RestoreMacro\code@delim}% } % How does it work? We assume in the input file is no explicit % \<char1>. This char is chosen as the code delimiter and will be put % at the end of input. So, entire file contents will be scanned char % by char as the code. % \stanza % % \skiplines First I~tried to use \specialcomment{gmlonely} provided by % the \pk{comment} package, but it caused errors.\endskiplines % % The below environment I~designed to be able to skip some repeating % texts while documenting several packages of mine into one % document. At the default settings it's just a~|\StraightEOL| group % and in the |\skipgmlonely| declaration's scope it gobbles its % contents. % \newenvironment{gmlonely}{\StraightEOL}{} \newcommand\skipgmlonely[1][]{% \def\gmu@tempa{%\DefIndex\gmd@skipgmltext \def\gmd@skipgmltext{% \g@emptify\gmd@skipgmltext % ^^A \gmd@deeolize{ #1%^^A} }}% not to count the lines of the substituting % text but only of the text omitted \gmu@tempa \@xa\AtBegInput\@xa{\gmu@tempa}% \renewenvironment{gmlonely}{% \StraightEOL \@fileswfalse% to forbid writing to \pk{.toc}, \pk{.idx} etc. \setbox0=\vbox\bgroup}{\egroup\gmd@skipgmltext}} % Sometimes in the commentary of this package, so maybe also others, % I~need to say some char is of category 12 (`other sign'). This I'll % mark just as \catother\ got by |\catother|. % \foone{\catcode`\_=8 }% we ensure the standard |\catcode| of |_|. { \newcommand*\catother{${}_{12}$}%\par % Similarly, if we need to say some char is of category 13 (`active'), % we'll write \catactive, got by |\catactive| \newcommand*\catactive{${}_{13}$}%\par % and a~letter, \catletter \newcommand*\catletter{${}_{11}$}%. } % % For the copyright note first I~used just \env{verse} but it requires % marking the line ends with |\\| and indents its contents while % I~prefer the copyright note to be flushed left. So \newenvironment*{copyrnote}{% \StraightEOL\everypar{\hangindent3em\relax\hangafter1 }% \par\addvspace\medskipamount\parindent\z@\obeylines}{% \@codeskipputgfalse\stanza} % % I~renew the \env{quotation} environment to make the fact of quoting % visible. \StoreEnvironment{quotation} \def\gmd@quotationname{quotation} \renewenvironment{quotation}{% % \changes{v0.99j}{2008/08/03}{Improved behaviour of redefined % \env{quotation} to be the original if used by another environment.} % The first non-me user complained that \env{abstract} comes out in % quotation marks. That is because \env{abstract} uses \env{quotation} % internally. So we first check whether the current environment is % \env{quotation} or something else. \ifx\@currenvir\gmd@quotationname \afterfi{\par``\ignorespaces}% \else\afterfi{\storedcsname{quotation}}% \fi} {\ifx\@currenvir\gmd@quotationname \afterfi{\ifhmode\unskip\fi''\par}% \else\afterfi{\storedcsname{endquotation}}% \fi} % \chunkskip % For some mysterious reasons |\noindent| doesn't work with the first % (narrative) paragraph after the code so let's work it around: \def\gmdnoindent{% \ifvmode\leavevmode\hskip-\parindent\ignorespaces \fi}% \incs{ignorespaces} is added to eat a~space inserted% by % \incs{gmd@textEOL}. Without % it it% also worked but it was a~bug: since% \incs{parindent} is % a~dimen not% skip, \TeX\ looks forward and % expands macros to check % whether% there is a~stretch or shrink part%% and therefore it % gobbled the% \incs{gmd@textEOL}'s space. % % When a~verbatim text occurs in an inline comment, it's advisable to % precede it with |%| if it begins a~not first line of such a~comment % not to mistake it for a~part of code. Moreover, if such a~short verb % breaks in its middle, it should break with the percent at the % beginning of the new line. For this purpose provide \newcommand*\inverb{% % \changes{v0.99g}{2007/11/12}{added} \@ifstar{% \def\gmu@tempa{{\tt\xiipercent}}% \@emptify\gmu@tempb% here and in the paralell points of the other % case and \inverb|\nlpercent| I~considered an \inverb|\ifhmode| % test but it's not possible to be in vertical mode while in an % inline comment. If there happens vertical mode, the commentary % begins to be `outline' (main text). \gmd@inverb}% {\@emptify\gmu@tempa \def\gmu@tempb{\gmboxedspace}% \gmd@inverb}} \newcommand*\gmboxedspace{\hbox{\normalfont{ }}} \newcommand*\gmd@nlperc[1][]{% \changes{v0.99n}{2008/08/22}{% added % \cs{hbox}es in \cs{discretionary} to score \cs{hyphenpenalty} not % \cs{exhyphenpenalty}} \ifhmode\unskip\fi \discretionary{\hbox{\gmu@tempa}}% (pre-break). I~always put % a~\incs{hbox} here to make this discretionary score the % \incs{hyphenpenalty} not \incs{exhyphenpenalty} (\TB\ p.~96) since % the latter may be 10,000 in Polish typesetting. {{\tt\xiipercent\gmboxedspace}}% (post-break) {\gmu@tempb}% (no-break). \penalty10000\hskip0sp\relax} \newcommand*\gmd@inverb[1][]{% \gmd@nlperc \ifmmode\hbox\else\leavevmode\null\fi \bgroup \ttverbatim \def\breakablevisspace{% \discretionary{\visiblespace}{\xiipercent\gmboxedspace}{\visiblespace}}% \def\breakbslash{% \discretionary{}{\xiipercent\gmboxedspace\bslash}{\bslash}}% \def\breaklbrace{% \discretionary {\xiilbrace\verbhyphen}% {\xiipercent\gmboxedspace}% {\xiilbrace}}% \gm@verb@eol %^^A \@ifstar {\@sverb@chbsl} %^^A~ {\gmobeyspaces\frenchspacing\@sverb@chbsl} \@sverb@chbsl% It's always with visible spaces. } \newcommand*\nlpercent{% \@ifstar{\def\gmu@tempa{{\tt\xiipercent}}% \@emptify\gmu@tempb \gmd@nlperc}% {\@emptify\gmu@tempa \def\gmu@tempb{\gmboxedspace}% \gmd@nlperc}} \newcommand*\incs{% an inline \cs{cs} % \changes{v0.99m}{008/08/07}{added} \@ifstar{\def\gmu@tempa{{\tt\xiipercent}}% \@emptify\gmu@tempb \gmd@nlperc\cs}% {\@emptify\gmu@tempa \def\gmu@tempb{\gmboxedspace}% \gmd@nlperc\cs}} \def\inenv{\incs[]}% an in-line \cs{env} % As you see, |\inverb| and |\nlpercent| insert a~discretionary that % breaks to |%| % at the beginning of the lower line. Without the break it's a~space % (alas at its natural width i.e., not flexible) or, with the starred % version, nothing. The starred version puts |%| also at the end of % the upper line. Then |\inverb| starts sth. like % |\verb*| but the breakables of it break to |%| in the % lower line. % % \acro{TODO}: make the space flexible (most probably it requires using sth.\ % else than |\discretionary|). %\stanza % % An optional hyphen for \CSs in the inline comment: \@ifundefined{+}{}{\typeout{^^Jgmdoc.sty: redefining \bslash+.}} \def\+{\discre{{\normalfont-}}{{\tt\xiipercent\gmboxedspace}}{}} % % \providecommand*\ds{DocStrip} % A~shorthand for |\CS|: \pdef\CS{% \changes{v0.99n}{2008/08/30}{added} \acro{CS}% \@ifnextcat a{ }{}}% we put a~space if the next token is % \catletter. It's the next best thing to checking whether the \CS % consisting of letters is followed by a~space. \pdef\CSs{\CS{}es\@ifnextcat a{ }{}}% for pluralis. % \changes{v0.99n}{2008/08/30}{added} \pdef\CSes{\CS{}es\@ifnextcat a{ }{}}% for pluralis. % \changes{v0.99n}{2008/08/30}{added} % \gmhypertarget[CDAnd]{Finally,} a~couple of macros for documenting % files playing with |%|'s % catcode(s). Instead of |%| I~used |&|. They may be at the end % because they're used in the commented thread i.e.\ after package's % |\usepackage|. \newcommand*\CDAnd{\CodeDelim\&} \newcommand*\CDPerc{\CodeDelim*\%} % And for documenting in general: % % A~general sectioning command because I~foresee a~possibility of % typesetting the same file once as independent document and another % time as a~part of bigger whole. % \Define\division \let\division=\section % \Define\subdivision \let\subdivision=\subsection % \Define\subsubdivision \let\subsubdivision=\subsubsection % % % \stanza % To kill a~tiny little bug in \file{doc.dtx} (in line 3299 |\gmu@tempb| and % |\gmu@tempc| are written plain not verbatim): \newcounter{gmd@mc} % Note it is after the \env{macrocode} group \def\gmd@mchook{\stepcounter{gmd@mc}% \label{gmd@mchook} \gmd@mcdiag \ifcsname gmd@mchook\the\c@gmd@mc\endcsname \afterfi{\csname gmd@mchook\the\c@gmd@mc\endcsname}% \fi} \long\def\AfterMacrocode#1#2{\@namedef{gmd@mchook#1}{#2}} % What have I~done? I~declare a~new counter and employ it to count the % \env{macrocode(*)}s (and \env{oldmc(*)}s too, in fact) and attach % a~hook to (after) the end of every such environment. That lets us to % put some stuff pretty far inside the compiled file (for the buggie % in \file{doc.dtx}, to redefine |\gmu@tempb/c|). % One more detail to expalin and define: the |\gmd@mcdiag| macro may % be defined to type out a~diagnostic message (the % \env{macrocode(*)}'s number, code line number and input line number). \@emptify\gmd@mcdiag \def\mcdiagOn{\def\gmd@mcdiag{% \typeout{^^J\bslash end{\@currenvir} No.\the\c@gmd@mc \space\on@line, cln.\the\c@codelinenum.}}} \def\mcdiagOff{\@emptify\gmd@mcdiag} % % An environment to display the meaning of macro parameters: its % items are automatically numbered as |#1|, |#2| etc. \newenvironment*{enumargs}[1][1]% % \changes{v0.99n}{2008/08/21}{developed for the case of inline % comment} % \changes{v0.99o}{2008/09/04}{added the optional argument which is % the number of hashes (1 by default or 2 or 4)} % \changes{v0.99p}{2008/10/4}{added optional arguments' handling} {\if@aftercode\edef\gmu@tempa{\the\leftskip}% \edef\gmu@tempb{\the\hangindent}\fi \enumerate \if@aftercode \leftskip=\glueexpr\gmu@tempa+\gmu@tempb\relax \fi \@namedef{label\@enumctr}{% \env{\if@aftercode\code@delim\space\fi \gmd@ea@bwrap \#\ifcase#1\relax\or\or\#\or\or\#\#\#\fi \csname the\@enumctr\endcsname \gmd@ea@ewrap}}% \let\mand\item \provide\gmd@ea@wraps{% \emptify\gmd@ea@ewrap \emptify\gmd@ea@bwrap}% \gmd@ea@wraps \def\opt{% \def\gmd@ea@bwrap{[}\def\gmd@ea@ewrap{]}% \item \gmd@ea@wraps}% } {\endenumerate} % The starred version is intended for lists of arguments some of which % are optional: to align them in line. \newenvironment*{enumargs*}{% \def\gmd@ea@wraps{% \def\gmd@ea@bwrap{ }\def\gmd@ea@ewrap{ }}% \enumargs}{\endenumargs} % % \subdivision[\docfm-compatibility]{\gmhypertarget[doccompa]{\docfm-compatibility}} % % \gmhypertarget[doc-likeness]{My} \TeX\ Guru recommended me to write % hyperlinking for \docfm. The suggestion came out when writing of % \gmdoc\ was at such a~stage that I~thought it to be much easier to write % a~couple of |\let|s to make \gmdoc\ able to typeset % sources written for \docfm\ than to write a~new package that adds % hyperlinking to \docfm. So\dots % % \stanza % The \docfm\ package makes |%| an ignored char. Here the |%| delimits % the code and therefore has to be `other'. But only the first one % after the code. The others we may re|\catcode| to be ignored and we % do it indeed in line \ref{ignorePercent}. % \stanza % % At the very beginning of a~\docfm-prepared file we meet a~nice % command \cs{Char\-act\-er\-Tab\-le}. My \TeX\ Guru says it's a~bit old % fashioned these days so let's just make it notify the user: \def\CharacterTable{\begingroup \@makeother\{\@makeother\}% \Character@Table} \foone{% \catcode`\[=1 \catcode`\]=2 % \@makeother\{\@makeother\}}% [ \def\Character@Table#1{#2}[\endgroup \message[^^J^^J gmdoc.sty package:^^J ==== The input file contains the \bslash CharacterTable.^^J ==== If you really need to check the correctness of the chars,^^J ==== please notify the author of gmdoc.sty at the email address^^J ==== given in the legal notice in gmdoc.sty.^^J^^J]% %^^A~\gmd@countlines[#1]\gmd@countlines[#2] ]] % Similarly as \docfm, \gmdoc\ provides \env{macrocode}, \env{macro} % and \env{environment} environments. Unlike in \docfm, % |\end{macrocode}| \emph{does not} require to be preceded with any % particular number of spaces. Unlike in \docfm, it \emph{is not} % a~kind of \env{verbatim}, however, which means the code and % narration layers remains in force inside it which means that any % text after the first |%| in a~line will be processed as narration % (and its control sequences will be executed). For a~discussion of % a~possible workaround see line \ref{AVerySpecialMacro}. % % \stanza % Let us now look over other original \docfm's control sequences and % let's `domesticate' them if they are not yet. % % The \TextUsage\DescribeMacro\ and \TextUsage\DescribeEnv\ commands % seem to correspond with my |\TextUsage| macro in its plain and starred % version respectively except they don't typeset their arguments in the text % i.e., they do two things of the three. So let's |\def| them to do these % two things in this package, too: \outer\def\DescribeMacro{% \begingroup\MakePrivateLetters \gmd@ifonetoken\Describe@Macro\Describe@Env} % Note that if the argument to |\DescribeMacro| is not % a~(possibly starred) control sequence, then as an environment's name % shall it be processed \emph{except} the \cs{Mak\-ePriv\-at\-e\-Oth\-ers} % re|\catcode|ing shall not be done to it. \outer\def\DescribeEnv{% \begingroup\MakePrivateOthers\Describe@Env} % Actually, I've used the |\Describe...| commands myself a~few times, so % let's |\def| a~common command with a~starred % version: \outer\def\Describe{% It doesn't typeset its argument in the point of % occurrence. \begingroup\MakePrivateLetters \@ifstarl{\MakePrivateOthers\Describe@Env}{\Describe@Macro}} % The below two definitions are adjusted \*s of |\Text@UsgMacro| and % |\Text@UsgEnvir|. % \DefIndex\Describe@Macro \long\def\Describe@Macro#1{% \endgroup \strut\Text@Marginize#1% \@usgentryze#1% we declare kind of formatting the entry \text@indexmacro#1\ignorespaces} % \DefIndex\Describe@Env \def\Describe@Env#1{% \endgroup \strut\Text@Marginize{#1}% \@usgentryze{#1}% we declare the `usage' kind of % formatting the entry and index the sequence |#1|. \text@indexenvir{#1}\ignorespaces} % Note that here the environments' names are typeset in |\tt| font % just like the macros', \emph{unlike} in \docfm. % % \stanza % My understanding of `minimality' includes avoiding too much freedom % as causing chaos not beauty. That's the philosophical and \ae^^B % sthetic reason why I~don't provide \TextUsage\MacroFont. In % my opinion there's a~noble tradition of typesetting the \TeX\ code % in |\tt| font nad this tradition sustained should be. If one wants % to change the tradition, let \himher\ redefine |\tt|, in \TeX\ it's % no problem. I~suppose |\MacroFont| is not used explicitly, and that % it's (re)defined at most, but just in case let's |\let|: \let\MacroFont\tt % % \stanza % We have provided \TextUsage\CodeIndent\ in line % \ref{CodeIndent}. And it corresponds with \docfm's % \Describe\MacroIndent\cs{Mac\-ro\-In\-dent} so % \Define\MacroIndent \let\MacroIndent\CodeIndent % And similarly the other skips: \Define\MacrocodeTopsep \let\MacrocodeTopsep\CodeTopsep % Note that \TextUsage\MacroTopsep\ is defined in \gmdoc\ and has % the same r\ocircum le as in \docfm. % \Define\SpecialEscapechar \let\SpecialEscapechar\CodeEscapeChar % \TextUsage\theCodelineNo\ is not used in % \pk{gmdoc}. Instead of it there is \TextUsage\LineNumFont\ % declaration and a~possibility to redefine |\thecodelinenum| as for % all the counters. Here the |\LineNumFont| is used two different % ways, to set the benchmark width for a~linenumber among others, so it's not % appropriate to put two things into one macro. Thus let's give the % user a~notice if \heshe\ defined this macro: % % Because of possible localness of the definitions it seems to be % better to add a~check at the end of each |\DocInput| or % |\IndexInput|. \AtEndInput{\@ifundefined{theCodelineNo}{}{\PackageInfo{gmdoc}{The \string\theCodelineNo\space macro has no effect here, please use \string\LineNumFont\space for setting the font and/or \string\thecodelinenum\space to set the number format.}}} % I~hope this lack will not cause big trouble. % % \stanza % For further notifications let's define a~shorthand: \def\noeffect@info#1{\@ifundefined{#1}{}{\PackageInfo{gmdoc}{^^J% The \bslash#1 macro is not supported by this package^^J and therefore has no effect but this notification.^^J If you think it should have, please contact the maintainer^^J indicated in the package's legal note.^^J}}} % The four macros formatting the macro and environment names, namely % \possfil\TextUsage\PrintDescribeMacro, % \possfil\TextUsage\PrintMacroName, % \possfil\TextUsage\PrintDescribeEnv\ and % \possfil\TextUsage\PrintEnvName\ are not % supported by \pk{gmdoc}. They seem to me to be too internal to take % care of them. Note that in the name of (\ae sthetical) minimality % and (my) convenience I~deprive you of easy knobs to set strange % formats for verbatim bits: I~think they are not advisable. % % Let us just notify the user. \AtEndInput{% \noeffect@info{PrintDescribeMacro}% \noeffect@info{PrintMacroName}% \noeffect@info{PrintDescribeEnv}% \noeffect@info{PrintEnvName}} % The \TextUsage\CodelineNumbered\ declaration of \docfm\ seems to be % equivalent to our |noindex| option with the |linesnotnum| option set % off so let's define it such a~way. \def\CodelineNumbered{\AtBeginDocument{\gag@index}} \@onlypreamble\CodelineNumbered % Note that if the |linesnotnum| option is in force, this declaration % shall not revert its effect. % % I~assume that if one wishes to use \docfm's interface then \heshe'll % not use \gmdoc's options but just the default. % % \stanza % The |\CodelineIndex| and |\PageIndex| declarations % correspond with the \pk{gmdoc}'s default and the |pageindex| option % respectively. % Therefore let's |\let| \let\CodelineIndex\@pageindexfalse \@onlypreamble\CodelineIndex \let\PageIndex\@pageindextrue % \label{PageIndex} \@onlypreamble\PageIndex % The next two declarations I~find useful and % smart: \def\DisableCrossrefs{\@bsphack\gag@index\@esphack} \def\EnableCrossrefs{\@bsphack\ungag@index \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack} % The latter definition is made due to the footnote 6 on p.\,8 of the % Frank Mittelbach's \docfm's documentation and both of them are % copies of lines 302--304 of it modulo |\|(|un|)|gag@index|. % % \stanza % The subsequent few lines I~copy almost verbatim ;-) from the lines % 611--620. \newcommand*\AlsoImplementation{\@bsphack% \long\def\StopEventually##1{\gdef\Finale{##1}}% we define % \cs{Fi\+n\+a\+le} just to expand to the argument of |\StopEventually| not % to to add anything to the end input hook because |\Finale| should % only be executed if entire document is typeset.\nostanza\par % % \hangindent\verbatimhangindent \hangafter1\relax % \gmdnoindent \leftskip\CodeIndent % |%\init@checksum| is obsolete in % \pk{gmdoc} at this point: the \env{CheckSum} counter is reset just at % the beginning of (each of virtually numerous) input(s). % \nostanza\par \@esphack} \AlsoImplementation % \begin{quotation} When the user places an |\OnlyDescription| % declaration in the driver file the document should only be typeset % up to |\StopEventually|. We therefore have to redefine this % macro.\end{quotation} \def\OnlyDescription{\@bsphack\long\def\StopEventually##1{% % \begin{quotation} In this case the argument of |\StopEventually| % should be set and afterwards \TeX\ should stop reading from % this file. Therefore we finish this macro with\end{quotation} ##1\endinput}\@esphack} % \begin{quotation} If no |\StopEventually| command is given we % silently ignore a~|\Finale| issued.\end{quotation} \@relaxen\Finale % The \TextUsage\meta\ macro is so beautifully crafted in \docfm\ that % I~couldn't resist copying it into \pk{gmutils}. It's also available % in Knuthian (\TeXbook\ format's) disguise % \Describe*{\<...>}|\<|\<the argument>|>|. % \stanza % The checksum mechanism is provided and developed for a~slightly % different purpose. % \stanza % Most of \docfm's indexing commands have already been `almost % defined' in \pk{gmdoc}: \let\SpecialMainIndex=\DefIndex % \DoNotIndex\endcsname* \def\SpecialMainEnvIndex{\csname CodeDefIndex\endcsname*}% we don't % type |\DefIndex| explicitly here because it's |\outer|, remember? % \Define\SpecialIndex \Define\SpecialUsageIndex % \Define\SpecialEnvIndex \Define\SortIndex \let\SpecialIndex=\CodeCommonIndex \let\SpecialUsageIndex=\TextUsgIndex \def\SpecialEnvIndex{\csname TextUsgIndex\endcsname*} \def\SortIndex#1#2{\index{#1\actualchar#2}} % \begin{quotation}All these macros are usually used by other macros; % you will need them only in an emergency.\end{quotation} % % Therefore I~made the assumption(s) that `Main' indexing macros are % used in my `Code' context and the 'Usage' ones in my `Text' context. % % \stanza % Frank Mittelbach in \docfm\ provides the \TextUsage\verbatimchar\ % macro to (re)define the |\verb(*)|'s delimiter for the index % entries. The \gmdoc\ package uses the same macro and its default definition % is |{&}|. When you use \docfm\ you % may have to redefine |\verbatimchar| if you use (and index) the |\+| % control sequence. \pk{gmdoc} does a~check for the analogous situation % (i.e., for processing |\&|) and % if it occurs it takes |$| as the |\verb*|'s delimiter. So strange % delimiters are chosen deliberately to allow any `other' chars in the % environments' names. If this would cause problems, please % notify me and we'll think of adjustments. % \def\verbatimchar{&} % \changes{v0.98c}{06/9/10}{put into all indexing macros for the % accordance of the `macro' and the `environment' index entries; the % \cs[]{\$} sign set as its alternative} % One more a~very neat macro provided by \docfm. I~copy it % verbatim and put into \pk{gmutils}, too. (|\DeclareRobustCommand| % doesn't issue an error if its argument has been defined, it only % informs about redefining.) \pdef\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} % \changes{v0.98}{06/09/05}{made robust.} % \TextUsage\IndexPrologue\ is defined in line % \ref{IndexPrologue}. And other \docfm\ index commands too. \@ifundefined{main}{}{\let\DefEntry=\main} \@ifundefined{usage}{}{\let\UsgEntry=\usage} % About how the \ds\ directives are supported by \pk{gmdoc}, % see section \gmiflink[docstrip]{The \ds\dots}. % This support is not \emph{that} sophisticated as in \docfm, among others, it % doesn't count the modules' nesting. Therefore if we dont want an % error while \pk{gmdoc}umenting \docfm-prepared files, better let's % define \docfm's counter for the modules' depths. \newcounter{StandardModuleDepth} % \stanza % For now let's just mark the macro for further development % \Define*\DocstyleParms \noeffect@info{DocstyleParms} % For possible further development or to notify the user once and % forever: % \Define\DontCheckModules \Define\CheckModules \@emptify\DontCheckModules \noeffect@info{DontCheckModules} \@emptify\CheckModules \noeffect@info{CheckModules} % The \TextMarginize\Module|\Module| macro \emph{is} provided exactly % as in \docfm. % \Define\AltMacroFont \@emptify\AltMacroFont \noeffect@info{AltMacroFont} % \begin{quotation} And finally the most important bit: we change the % |\catcode| of |%| so that it is ignored (which is how we are able to % produce this \pk{doc}ument!). We provide two commands to do the % actual switching.\end{quotation} \def\MakePercentIgnore{\catcode`\%9\relax} \def\MakePercentComment{\catcode`\%14\relax} % % % \subdivision{\gmdoc ing \file{doc.dtx}} % % The author(s) of \docfm\ suggest(s): \begin{quotation}For examples % of the use of most---if not all---of the features described above % consult the \file{doc.dtx} source itself.\end{quotation} % Therefore I~hope that after \file{doc.dtx} has been \gmdoc-ed, one % can say \gmdoc\ is \docfm-compatible ``at most---if not at all''. % % \TeX ing the original \docfm\ with my humble\footnote{What ^^B( % a~\emph{false} modesty! ;-)} package was a~challenge and % a~milestone experience in my \TeX\ life. % % \stanza % One of minor errors was caused by my understanding of a~`shortverb' % char: due to \pk{gmverb}, in the math mode an active `shortverb' char % expands to itself's `other' version thanks to |\string| (It's done % with \verb+|+ in mind). \docfm's % concept is different, there a~`shortverb' char should in the math % mode work as shortverb. So let it be as they wish: \pk{gmverb} % provides |\OldMakeShortVerb| and the oldstyle input commands change % the inner macros so that also |\MakeShortVerb| works as in \docfm % (cf.\ line \ref{oldmkshvrrb}). % % We also redefine the \env{macro} environment to make it mark the % first code line as the point of defining of its argument, because % \pk{doc.dtx} uses this environment also for implicit definitions. % % \changes[\OldMakeShortVerb]{v0.98a}{06/09/05}{and pals moved to % \pk{gmverb}.} %\Define\OldDocInput % \changes{v0.98}{06/09/05}{\cs{@makeother\protect\bslash_} added} % \changes{v0.98a}{06/09/05}{\cs{AtBegInput} changed into % \cs{AtBegInputOnce}.} % \changes{v0.98b}{06/09/07}{enrichments of the \env{macrocode(*)} % definitions moved to the default definitions of these envs.} \def\OldDocInput{% \changes{v0.99g}{2007/11/11}{obsolete redefinition % of the \env{macro} environment removed} \AtBegInputOnce{\StraightEOL \let\@MakeShortVerb=\old@MakeShortVerb % \label{oldmkshvrrb} \OldMacrocodes}% \bgroup\@makeother\_% it's to allow |_| in the filenames. The next % macro will close the group. \Doc@Input} % We don't swith the |@codeskipput| switch neither we check it because % in `old' world there's nothing to switch this switch in the % narration layer. % % \stanza % I~had a~hot and wild \TeX\ all the night nad what a~bliss when % the `Succesfully formated 67 page(s)' message appeared. % % My package needed fixing some bugs and adding some compatibility % adjustments (listed in the previous section) and the original % \pk{doc.dtx} source file needed a~few adjustments too because some % crucial differences came out. I'd like to write a~word about them now. % % \stanza % The first but not least is that the author(s) of \docfm\ give the % \CS marking commands non-macro arguments sometimes, e.g., % |\DescribeMacro{StandardModuleDepth}|. Therefore we should launch % the \emph{starred} versions of corresponding \gmdoc\ commands. This % means the \docfm-like commands will not look for the \CS's occurrence % in the code but will mark the first codeline met. % \stanza % % Another crucial difference is that in \gmdoc\ the narrative and the % code layers are separated with only the code delimiter and % therefore may be much more mixed than in \docfm. among others, the \env{macro} % environment is \emph{not} a~typical \env{verbatim} like: the texts % commented out within \env{macrocode} are considered a~normal % commentary i.e., not verbatim. Therefore some macros `commented out' % to be shown verbatim as an example source must have been `additionally' % verbatimized for \gmdoc\ with the shortverb chars e.g. You may also % change the code delimiter for a~while, e.g., the line % \CodeDelim\. % \AVerySpecialMacro % delete the first % when.\unskip|..|\par\CDPerc % % \gmdnoindent\label{AVerySpecialMacro} % was got with % \begin{verbatim} %\CodeDelim\. %% \AVerySpecialMacro % delete the first % when.\unskip|..|\CDPerc %\end{verbatim} % % \leftskip0sp\relax % One more difference is that my shortverb chars expand to their % \catother\ versions in the math mode while in \docfm\ remain % shortverb, so I~added a~declaration |\OldMakeShortVerb| etc. % % \stanza % Moreover, it's \TeX ing \docfm\ what inspired adding the % |\StraightEOL| and |\QueerEOL| declarations. % % % % \division{Polishing, development and bugs} % % \begin*{bulletpars} % \everypar{$\bullet$ } % \label{Tasks}|\MakePrivateLetters| theoretically may interfere % with |\active|ating some chars to allow linebreaks. But making % a~space or an opening brace a~letter seems so perverse that we may % feel safe not to take account of such a~possibility. % % When |countalllines*| option is enabled, the comment lines % that don't produce any printed output result with a~(blank) line too % because there's put a~hypertarget at the beginning of them. But for % now let's assume this option is for draft versions so hasn't be % perfect. % % Marcin Woli\nacute ski suggests to add the marginpar clauses for the % \acro{AMS} classes as we did for the standard ones in the lines % \ref{mparclause1}--\ref{mparclause2}. Most probably I~can do it on % request when I~only know the classes' names and their `marginpar % status'. % % When the |countalllines*| option is in force, some |\list| % environments shall raise the `missing |\item|' error if you don't % put the first |\item| in the same line as % |\begin{|\<environment>|}| because the (comment-) line number is % printed.^^A~\end{} % % I'm prone to make the control sequences hyperlinks to the(ir) % `definition' occurrences. It doesn't seem to be a~big work compared % with what has been done so far. % % Is |\RecordChanges| really necessary these days? Shouldn't be the % |\makeglossary| command rather executed by default?\footnote{It's ^^B % understandable that ten years earlier writing things out to the files ^^B % remarkably decelerated \TeX, but nowadays it does not in most ^^B % cases. That's why \cs{makeindex} is launched by default in \gmdoc.} % % Do you use |\listoftables| and/or |\listoffigures| in your % documentations? If so, I~should `\acro{EOL}-straighten' them like % |\tableofcontents|, I~suppose (cf.\ line \ref{straighttoc}). % % Some lines of non-printing stuff such as |\Define...| and % |\changes| connecting the narration with the code resulted with % unexpected large vertical space. Adding a~fully blank line between % the printed narration text and not printed stuff helped. % % Specifying |codespacesgrey, codespacesblank| results in typesetting % all the spaces grey including the leading ones. % % % About the \ds\ \gmiflink{verbatim mode directive} see above. % % \end{bulletpars} % \ \par\vspace*{-\baselineskip} % % \def\EOFMark{\<eof>} % \division{(No) \EOFMark} % % Until version 0.99i % a~file that is |\DocInput| had to be ended with a~comment line with % an |\EOF| or |\NoEOF| \CS that % suppressed the end-of-file character to make input end % properly. Since version 0.99i however the proper ending of input is % acheved with |\everyeof| and therefore |\EOF| and |\NoEOF| become % a~bit obsolete. % % If the user doesn't wish the documentation to be ended by % `\EOFMark', \heshe\ should redefine the |\EOFMark| \CS or end % the file with a~comment ending with |\NoEOF| macro defined % below\footnote{Thanks to Bernd Raichle at Bacho\TeX\ 2006 ^^B Pearl % Session where he presented \cs{input}ing a~file inside ^^B % \cs{edef}.}: % \foone{\catcode`\^^M\active }{% \def\@NoEOF#1^^M{% \@relaxen\EOFMark\endinput}% \def\@EOF#1^^M{\endinput}} \def\NoEOF{\QueerEOL\@NoEOF} \def\EOF{\QueerEOL\@EOF} % \changes{v0.98}{06/09/05}{extended to add it the \cs{endinput} effect} % \changes{v0.98l}{06/10/27}{divided in two macros first of which % makes queer \acro{EOL} and the latter gobbles the stuff till the \acro{EOL} to % suppress possible \cs{endinput} when used in \cs{StopEventually}} % \label{NoEOF} As you probably see, \cs{(No)EOF} have the `immediate' % |\endinput| effect: the file ends even in the middle of a~line, the % stuff after \cs{(No)EOF} will be gobbled unlike with a~bare % |\endinput|. \endinput %^^A~\docstrip %</package> %\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} % % \changes{v0.99i}{2008/08/03}{A~“feature not bug” fix: thanks to % \cs{everyeof} the \cs{(No)EOF} is now not necessary at the end of % \cs{DocInput} file.} % % \changes{v0.99m}{2008/08/08}{Counting of all lines developed (the % \env{countalllines} package option), now it % uses \cs{inputlineno}} % % \changes{v0.99n}{2008/08/24}{Inline comments' alignment developed} % % \Finale % (For my GNU Emacs:) %%% Local Variables: %%% mode: doctex %%% End: