From 9a09aff4683470dfbaa491c0e38b230f6c88b6d9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Tue, 19 Dec 2006 01:04:11 +0000 Subject: new package gmdoc (18dec06) git-svn-id: svn://tug.org/texlive/trunk@2803 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty | 6265 ++++++++++++++++++++++++++ Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls | 307 ++ 2 files changed, 6572 insertions(+) create mode 100644 Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty create mode 100644 Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls (limited to 'Master/texmf-dist/tex/latex/gmdoc') diff --git a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty new file mode 100644 index 00000000000..cee0aa6b911 --- /dev/null +++ b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty @@ -0,0 +1,6265 @@ +% +% \GetFileInfo{gmdoc.sty} +% \title{The \pk{gmdoc.sty} Package\thfileinfo} +% \author{Grzegorz `Natror' 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 Grzegorz `Natror' Murzynowski, +%% natror at o2 dot pl +%% +%% \copyright\,2006 by Grzegorz `Natror' Murzynowski. +%% +%% This program is subject to the \LaTeX\ Project Public License. +%% See \url{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html} ^^A +%% for the details of that license. +%% +%% LPPL status: "author-maintained".\par +%% +%% Many thanks to my \TeX\ Guru Marcin Woli\'nski 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/1}{4479} +% +%^^A \docstrip +% + +\NeedsTeXFormat{LaTeX2e} +\ProvidesPackage{gmdoc} + [2006/12/30 v0.99a a documenting package (GM)] + +% +% +% \CharacterTable {In my \TeX\ Guru's opinion the idea of +% checking of the correctness of chars is a~bit obsolete +% nowadays. Therefore I~define the \CharacterTable<#1> +% macro to gobble its argument and to typeout a~request +% for request.} +% +% +% \newcommand*\docfm{\pk{doc}} +% \newcommand*\gmdoc{\pk{gmdoc}} +% +% \tableofcontents +% +% +% \division{Readme} +% +% This package is a~tool for documenting of \LaTeXpar\ +% packages, classes etc., i.e., the \file{.sty}, \file{.cls} files +% etc. The author just writes the code and adds the commentary +% preceded with |%| sign (or another properly declared). No special +% environments are necessary. +% +% The package tends to be (optionally) compatible with the standard +% \pk{doc.sty} package, +% i.e., the \file{.dtx} files are also compilable with \pk{gmdoc} +% (they may need very little adjustment, in some rather special +% cases). +% +% The tools are integrated with \pk{hyperref}'s advantages such as +% hyperlinking of index entries, contents entries and +% cross-references. +% +% \begin{gmlonely} +% \subdivision{Installation} +% +% Just put the \pk{gmdoc.sty} and \pk{gmdocc.cls} somewhere in the +% \file{texmf/\:tex/\:latex} branch. Creating +% a~\file{texmf/\:tex/\:latex/\:gm} directory may be advisable if +% you consider using other packages written by me. +% +% You should also install \pk{gmverb.sty}, \pk{gmutils.sty} +% and \pk{gmiflink.sty} (e.g., put them into the same \file{gm} +% directory). These packages are available on CTAN as separate +% \file{.zip} archives. +% +% Moreover, you should put the \file{gmglo.ist} file, a MakeIndex +% style for the changes' history, into some \file{texmf/\:makeindex} +% (sub)directory. +% +% Then you should refresh your \TeX\ distribution's files' database +% most probably. +% \end{gmlonely} +% +% +% \subdivision{Contents of the \pk{gmdoc.zip} Archive} +% +% The distribution of the \pk{gmdoc} package consists of the +% following six files. +% \begin{verse} +% \pk{gmdoc.sty}\\ +% \pk{gmdocc.cls}\\ +% \pk{gmglo.ist}\\ +% \pk{README}\\ +% \pk{gmdocDoc.tex}\\ +% \pk{gmdocDoc.pdf} +% \end{verse} +% +% +% \begin{gmlonely} +% \subdivision{Compiling the Documentation} +% +% The last of the above files (the \pk{.pdf}, i.e., \emph{this +% file}) is a~documentation compiled from the \pk{.sty} and +% \pk{.cls} files by running \LaTeX\ on the \file{gmdocDoc.tex} +% twice, then MakeIndex on the \file{gmdocDoc.idx} and +% \file{gmdocDoc.glo} files, and then \LaTeX\ on \file{gmdocDoc.tex} +% once more. +% +% MakeIndex shell commands: +%\begin{verbatim} +%makeindex -r gmdocDoc +%makeindex -r -s gmglo.ist -o gmdocDoc.gls gmdocDoc.glo +%\end{verbatim} +% The |-r| switch is to forbid MakeIndex to make implicit ranges since +% the (code line) numbers will be hyperlinks. +% +% Compiling the documentation requires the packages: +% \pk{gmdoc} (\pk{gmdoc.sty} and \pk{gmdocc.cls}), \pk{gmutils.sty}, +% \pk{gmverb.sty}, \pk{gmiflink.sty} and also some standard packages: +% \pk{hyperref.sty}, \pk{color.sty}, \pk{geometry.sty}, +% \pk{multicol.sty}, \pk{lmodern.sty}, \pk{fontenc.sty} that should +% be installed on your computer by default. +% +% If you had not installed the \pk{mwcls} classes (available on +% CTAN and present in \TeX\ Live e.g.), the result of your +% compilation might differ a~bit from the \pk{.pdf} provided in this +% \pk{.zip} archive in formatting: If you had not installed +% \pk{mwcls}, the standard \pk{article.cls} class would be used. +% \end{gmlonely} +% +% +% % \subdivision{Bonus: \file{base} Drivers} +% +% As a~bonus and example of \docfm-compatibility +% there are driver files included +% (cf.\ Palestrina, \textit{Missa papae Marceli} ;-): +% +% \begin{verse} +% \pk{source2e_gmdoc.tex}\\ +% \pk{docstrip_gmdoc.tex}\\ +% \pk{doc_gmdoc.tex} +% +% \pk{oldcomm.sty}\\ +% \pk{gmeometric.sty} +% \end{verse} +% +% These drivers typeset the respective files from the +%\[\hbox{\file{ .../texmf-dist/source/latex/base}}\] +% directory of the \TeX Live2005 distribution. +% +% Probably you should redefine the |\BasePath| macro in them +% so that it points that directory on your computer. +% +% +%\division*{Introduction} +% +% There are very sophisticated and effective tools for documenting +% \LaTeX\ macro packages, namely the \pk{doc} package and the +% \pk{ltxdoc} class. +% Why did I~write another documenting package then? +% +% I~like comfort and \pk{doc} is not comfortable enough for me. It +% requires special marking of the macro code to be properly typeset +% when documented. I~want \TeX\ to know `itself' where the code begins +% and ends, without additional marks. +% +% That's the difference. One more difference, more important for the +% people for whom the \docfm's conventions are acceptable, is that +% \gmdoc\ makes use of \pk{hyperref} advantages and makes +% a~hyperlinking index and toc entries and the +% cross-references, too. (The CSs in the code maybe in the future.) +% +% The rest is striving to level the very high \pk{doc/ltxdoc}'s +% standard, such as (optional) numbering of the codelines and +% authomatic indexing the control sequences e.g. +% +% The \docfm\ package was and still is a~great inspiration for me and +% I~would like this humble package to be considered as a~sort of +% hommage to it\footnote{As Grieg's Piano Concerto is a~hommage to ^^B +% the Schumann's.}. If I~mention copying some code or narrative but do +% not state the source explicitly, I~mean the \docfm\ package's +% documentation (I~have v2.1b dated 2004/02/09). +% +% +% +% \division{The User Interface} +% +% +% \subdivision{Used Terms} +% +% When I~write of a~\textbf{macro}, I~mean a~macro in \TeXbook's +% meaning, i.e., a~control sequence whose meaning is +% |\(e/g/x)def|ined. By a~\textbf{macro's parameter} I~mean each of +% |#|\s in its definition. When I~write about ^^A\) +% a~\textbf{macro's argument}, I~mean the value (list of tokens) +% subsituting the corresponding parameter of this macro. +% (These understandings are according ^^A( +% to \TeXbook, I~hope: \TeX\ is a~religion of Book ;-)\,.) +% +% I'll use a~shorthand for `control sequence', \textbf{CS}. +% +% When I~talk of a~\textbf{declaration}, I~mean a~macro that expands +% to a~certain assignment, such as |\itshape| or +% |\@onlypreamble{|\|}|. +% +% Talking of declarations, I'll use the \textbf{OCSR} acronym as +% a~shorthand for 'observes/ing common \TeX\ scoping rules'. +% +% By a~\textbf{command} I~mean a~certain abstract visible to the end +% user as a~CS but consisting possibly of more than one macro. I'll +% talk of a~\textbf{command's argument} also in +% the `sense\:-for\:-the\:-end\:-user', e.g., I'll talk of the +% |\verb| \emph{command's} argument although \emph{the macro} +% |\verb| has no |#|\ in its definition. +% +% The \textbf{code} to be typeset verbatim (and with all the bells +% and whistles) is everything that's not commented out in the source +% file and what is not a~leading space(s). +% +% The \textbf{commentary} or \textbf{narrative} is everything after +% the comment char till the end of a~line. The \textbf{comment char} +% is a~character the |\catcode| of which is 14 usually i.e., when the +% file works; if you don't play with +% the |\catcode|s, it's just the |%|. When the file is documented with +% \gmdoc, such a~char is re|\catcode|d and its r\^ole is else: it +% becomes the \textbf{code delimiter}. +% +% A~line containing any \TeX\ code (not commented out) will be called +% a~\textbf{codeline}. A~line that begins with (some leading spaces +% and) a~code delimiter will be called a~\textbf{comment line} or +% \textbf{narration line}. +% +% The \textbf{user} of this package will also be addressed +% as \textbf{you}.\stanza +% +% Not to favour any particular gender (of the amazingly rich variety, +% I~mean, not of the vulgarly simplified two-element set), in this +% documentation I~use alternating pronouns of third person ^^A( +% (\TextUsage\heshe\ etc. commands provided by \pk{gmutils}), so let +% one be not surprised if `\heshe' sees `\himher self' altered in the +% same sentence :-)\,. +% +% +% \subdivision{Preparing the Source File} +% +% When \LaTeXpar\ with \pk{gmdoc.sty} package loaded typesets the +% comment lines, the code delimiter is ommitted. If the comment +% continues a~codeline, the code delimiter is printed. It's done so +% because ending a~\TeX\ code line with a~|%| is often very important +% and significant. Comments longer than one line are typeset +% continuously with the code delimiters ommitted. +% +% The user should just write \hisher\ splendid code and brilliant +% commentary. In the latter \heshe\ may use usual \LaTeXpar\ commands. +% The only requirement is, if an argument is divided in two +% lines, to end such a~dividing line with \TextUsage*{^^B} sequence +% that'll enter the (active) \ which shall gobble the line end. +% ^^A~and the leading code delimiter of the next line---obsoleted by +% ^^A~making % ignored in the commentary. +% +% Moreover, if \heshe\ wants to add a~meta-comment i.e., a~text that +% doesn't appear in the code layer nor in the narrative, \heshe\ may +% use the \TextUsage*{^^A} sequence that'll be read by \TeX\ as +% \, which +% is in \gmdoc\ active and defined to gobble the stuff between itself +% and the next line end. +% +% Note, however, that both |^^A| and |^^B| are usually macros in +% \gmdoc\ and the text being gobbled is their argument so it has to be +% balanced of braces and, if it occures inside an |\if...|, it has to +% have all |\if...|s coupled with |\else|s and |\fi|s. +% +% However, it may be a~bit confusing +% for someone acquainted with the \docfm\ conventions. If you don't +% fancy the |^^B| special sequence, instead you may restore the +% standard meaning of the line end with the \TextUsage\StraightEOL\ +% declaration which +% OCSR. As almost all the control +% sequences, it may be used also as an environment, i.e., +% |\begin{StraightEOL}|\ \dots\ |\end{StraightEOL}|. However, if for any +% reason you don't want to make an environment (a~group), there's +% a~|\StraightEOL|'s counterpart, the \TextUsage\QueerEOL\ declaration that +% restores again the +% \StraightEOL +% queer\footnote{In my understanding +% `queer' and `straight' are not the opposites excluding each +% other but the counterparts that may cooperate in harmony for +% people's good. And, as I~try to show with the \cs{QueerEOL} and +% \cs{StraightEOL} declarations, `queer' may be very useful and +% recommended while `straight' is the standard but not necessarily +% normative. (Remember also Alice's in the Wonderland exclamations +% ``What a~queer day is today''.)}^^A +% \QueerEOL +% \gmdoc's meaning of the line end. It OCSR, too. One more point to use +% |\StraightEOL| is where you wish some code lines to be executed +% both while loading the file and during the documentation pass +% (it's analogous to \docfm's not embracing some code lines in +% a~\env{macrocode} environment). +% +% \stanza +% +% As in standard \TeX ing, one gets a~paragraph by a~blank line. +% Such a~line should be |%|ed of course. A~fully blank line is +% considered a~blank \emph{code line} and hence results in +% a~vertical space in the documentation. As in the environments for +% poetry known to me, subsequent blank lines do not increase such +% a~space. +% +% Then \heshe\ should prepare a~main document file, +% a~\textbf{driver} henceforth, to set all the +% required formattings such as |\documentclass|, paper size +% etc., and load this package with a~standard command +% i.e., |\usepackage{gmdoc}|, just as \docfm's documentation says: +% +% \begin{quotation} +% If one is going to document a set of macros with the \pk{[gm]doc} +% package one has to prepare a special driver file which produces +% the formatted document. This driver file has the following +% characteristics: \par\leftskip\CodeIndent +% \stanza +% +% \noindent|\documentclass[|\|]{|\|}|\par +% \noindent|\usepackage[|\|]{gmdoc}|\par +% \\par +% \noindent|\begin{document}|\par +% \\par +% \noindent|\end{document}|\par +% \end{quotation} +% +% +% \subdivision{The Main Input Commands} +% +% To typeset a~source file you may use the \TextUsage\DocInput\ +% macro that takes the (path and) name of the file \emph{with ^^B +% the extension} as the only argument, e.g., +% |\DocInput{mybrilliantpackage.sty}|. +% +% (Note that an \emph{installed} package or class file is findable to +% \TeX\ even if you don't specify the path.) +% +% If a~source file is written with rather \docfm\ than \gmdoc\ in +% mind, then the \TextUsage\OldDocInput\ command may be more +% appropriate (e.g., if you break the arguments of commands in the +% commentary in lines). It also takes the file (path and) name as the +% argument. +% +% When using |\OldDocInput|, you have to wrap all the code in +% \TextUsage*{macrocode} environments, which is not necessary when you +% use |\DocInput|. Moreover, with |\OldDocInput| the +% \env{macrocode(*)} environments require to be ended with +% |% \end{macrocode(*)}|. +% +% \stanza +% If you wish to document many files in one document, you are +% provided \TextUsage\DocInclude\ command, analogous to \LaTeX's +% |\include| and very likely to \pk{ltxdoc}'s command of the same +% name. In \gmdoc\ it has one mandatory argument that should be the +% file name \emph{without extension}, just like for |\include|. +% +% The file extensions supported by |\DocInclude| are \pk{.fdd}, +% \pk{.dtx}, \pk{.cls}, \pk{.sty}, \pk{.tex} and \pk{.fd}. The macro +% looks for +% one of those +% extensions in the order just given. If you need to document files +% of other extensions, please let me know and most probably we'll make +% it possible. +% +% |\DocInclude| has also an optional first argument that is intended +% to be the path of the included file with the levels separated by |/| +% (slash) and also ended with a~slash. The path given to |\DocInclude| as +% the first and optional argument will not appear in the headings nor +% in the footers. +% +% |\DocInclude| redefines \TextUsage\maketitle\ so +% that it makes a~chapter heading or, in the classes that don't +% support |\chapter|, a~part heading, in both cases with +% respective toc entries. The default assumption is that all the +% files have the same author(s) so there's no need to print them in +% the file heading. If you wish the authors names to be printed, you +% should write \TextUsage\PrintFilesAuthors\ in the preamble or before +% the relevant |\DocInclude|s. If you wish to undeclare printing the +% authors names, there is \TextUsage\SkipFilesAuthors\ declaration. +% +% Like in \pk{ltxdoc}, the name of an included file appears in the +% footer of each page with date and version info (if they are +% provided). +% +% The |\DocInclude|d files are numbered with the letters, the +% lowercase first, as in \pk{ltxdoc}. Such a~filemarker also precedes +% the index entries, if the (default) codeline index option is in force. +% +% As with |\include|, you may declare +% \TextUsage\includeonly|{|\|}| for +% the draft versions. +% +% \stanza +% If you wish to include the driver file into your documentation, you +% may write |\DocInput{\jobname.tex}|, but a~try of +% |\DocInclude{\jobname}| would result with input stack overflow +% caused by infinite |\input{|\|.aux}| recursion. +% But there's \TextUsage\SelfInclude\ at your service that creates and +% uses \pk{\.auxx} file instead of the usual +% \pk{\.aux}. Its effect is analogous to the |\DocInclude|'s, but +% \emph{the arguments it takes are totally different}: Since the +% filename is known, there's no need to state it. The extension is +% assumed to be \file{.tex}, but if it's different, you may state it in +% the first and optional argument. The second argument is mandatory and +% it's the stuff to be put at begin of file input, this one and no +% else (with \TextCommonIndex\AtBegInputOnce|\AtBegInputOnce| hook). +% For the example of usage see line \ref{SelfIncludeUsg} of +% chapter~\ref*{Driver}. +% +% \stanza +% +% At the default settings, the |\Doc/SelfInclude|d files constitute +% chapters if |\chapter| is known and parts otherwise. The +% |\maketitle|s of those files result in the respective headings. +% +% If you prefer more \pk{ltxdoc}ish look, in which the files always +% constitute the parts and those parts have a~part's title +% pages with the file name and the files' |\maketitle|s result in +% (article-like) titles not division headings, then you are provided +% the \TextUsage\ltxLookSetup\ declaration (allowed only in the +% preamble). However, even after this declaration the files will be +% included according to \gmdoc's rules not necessarily to the \docfm's +% ones (i.e., with minimal marking necessary at the price of active +% line ends (therefore not allowed between a~command and its argument +% nor inside an argument)). +% +% On the other hand, if you like the look offered by me but you have +% the files prepared for \docfm\ not for \gmdoc, then you +% should declare \TextUsage\olddocIncludes. Unlike the previous one, +% this may be used anywhere, because I~have the account of including both +% \docfm-like and \gmdoc-like files into one document. This +% declaration just changes the internal input command and doesn't +% change the sectioning settings. +% +% It seems possible that you wish to document the `old-doc' files +% first and the `new-doc' ones after, so the above declaration has its +% counterpart, \TextUsage\gmdocIncludes, that may be used anywhere, +% too. Before the respective |\DocInclude|(s), of course. +% +% Both these declarations OCSR. +% +% If you wish to document your files as with \pk{ltxdoc} \emph{and} +% as with \docfm, you should declare +% |\ltxLookSetup| in the preamble \emph{and} |\olddocIncludes|. +% +% \stanza +% Talking of analogies with \pk{ltxdoc}, if you like only the page +% layout provided by that class, there is the +% \TextUsage\ltxPageLayout\ declaration (allowed only in preamble) +% that only changes the margins and the text width (it's intended to +% be used with the default paper size). This declaration is +% contained in the |\ltxLookSetup| declaration. +% +% \stanza +% If you need to add something at the beginning of the input of file, +% there's the \TextUsage\AtBegInput\ declaration that takes one and +% mandatory argument which is the stuff to be added. This declaration +% is global. It may be used more than one time and the arguments of +% each occurrence of it add up and are put at the beginning of input +% of every subsequent files. +% +% Simili modo, for the end of input, there's the +% \TextUsage\AtEndInput\ declaration, also one-argument, global and +% cumulative. +% +% If you need to add something at the beginning of input of only one +% file, put before the respective input command an +% \TextUsage\AtBegInputOnce|{|\|}| +% declaration. It's also global which means that the groups do not +% limit its scope but it adds its argument only at the first input +% succeding it (the argument gets wrapped in a~macro that's |\relax|ed +% at the first use). |\AtBegInputOnce|s add up, too. +% +% \stanza +% One more input command is \TextUsage\IndexInput\ (the name and idea +% of effect comes from \docfm). It takes the same argument as +% |\DocInput|, the file's (path and) name with extension. (It +% \emph{has} |\DocInput| inside). It works properly if the input file +% doesn't contain explicit \ (|^^A| is OK). +% +% The effect of this command is typesetting of all the input file +% verbatim, with the code lines numbered and the CSs automatically +% indexed (\pk{gmdoc.sty} options are in force). +% +% +% \subdivision{Package Options} +% +% As many good packages, this also provides some options: +% \stanza +% +% Due to best \TeX\ documenting traditions the codelines will be +% numbered. But if the user doesn't wish that, \heshe\ may turn it off +% with the \TextUsage*{linesnotnum} option. +% +% However, if \heshe\ agrees to have the lines numbered, \heshe\ may wish +% to reset the counter of lines \himher self, e.g., when \heshe\ +% documents many source files in one document. Then \heshe\ may wish +% the line numbers to be reset with every |{section}|'s turn for +% instance. This is the r\^ole of the \TextUsage*{uresetlinecount} +% option, which seems to be a~bit obsolete however, since the +% \TextCommonIndex\DocInclude|\DocInclude| command takes care of +% a~proper reset. +% +% Talking of line numbering further, a~tradition seems to exist to +% number only the codelines and not to number the lines of +% commentary. That's the default behaviour of \pk{gmdoc} but, if +% someone wants the comment lines to be numbered too, \heshe\ is +% provided the \TextUsage*{countalllines} option. ^^A( +% {\LineNumFont 441}\,Then the narration acquires a~bit biblical look ;-), +% {\LineNumFont 442}\,as shown in this short example. This option is intended +% {\LineNumFont 443}\,for the draft versions and it is not perfect (as if anything +% {\LineNumFont 444}\,in this package was). As you see, the lines +% {\LineNumFont 445}\,are typeset continuously with the numbers printed. +% +% \stanza +% By default the \pk{makeidx} package is loaded and initialized and +% the CSs occurring in the code are automatically +% (hyper)indexed thanks to the \pk{hyperref} package. If the user +% doesn't wish to index anything, she should use the +% \TextUsage*{noindex} option. +% +% The index comes two possible ways: with the line numbers (if the +% lines are numbered) and that's the default, or with the page numbers, if +% the \TextUsage*{pageindex}\label{indexoptions} option is set. +% +% \stanza +% By default, \gmdoc\ excludes some 300 CSs from being indexed. +% They are the most common CSs, \LaTeX\ internal +% macros and \TeX\ primitives. To learn what CSs are +% excluded actually, see lines \ref{DIE1}--\ref{DIE2}. +% +% If you don't want all those exclusions, you may turn them off with +% the \TextUsage*{indexallmacros} option. +% +% If you have ambiguous feelings about whether to let the default +% exclusions or forbid them, see p.\,\pageref{IEIDeclarations} to +% feed this ambiguity with a~couple of declarations. +% +% \stanza +% In \docfm\ package there's a~default behaviour of putting marked +% macro's or environment's name to a~marginpar. In the standard +% classes it's allright but not all the classes support marginpars. +% That is the reason why this package enables marginparing when in +% standard classes, enables or disables it due to the respective option +% when with Marcin Woli\'nski's classes and in any case provides the +% options \TextUsage*{withmarginpar} and \TextUsage*{nomarginpar}. So, in +% non-standard classes the default behaviour is to disable marginpars. +% If the marginpars are enabled in \pk{gmdoc}, it will put marked +% control sequences and environments into marginpars (see +% \gmiflink[textUsage]{\cs{TextUsage} etc.}). These options do +% not affect common using marginpars, which depends on the +% documentclass. +% +% \stanza +% My suggestion is to make the spaces in the code visible except the +% leading ones and that's the default. But if you wish all the code +% spaces to be blank, I~give the option \TextUsage*{codespacesblank} +% reluctantly. Moreover, if you wish the code spaces to be blank only +% in some areas, then there's \TextUsage\CodeSpacesBlank\ declaration +% (OCSR). +% +% +% \subdivision{The Packages Required} +% +% \pk{gmdoc} requires (loads if they're not loaded yet) some other +% packages of mine, namely \pk{gmutils}, \pk{gmverb}, analogous to +% Frank Mittelbach's \pk{shortvrb}, and \pk{gmiflink} for conditional +% making of hyperlinks. It also requires \pk{hyperref}, +% \pk{multicol}, \pk{color} and \pk{makeidx}. +% +% The \pk{gmverb}\gmdmarginpar{\pk{gmverb}} package redefines the +% |\verb| command and the \env{verbatim} environment in such a~way that +% | |, |{| and |\| are breakable, the first with no `hyphen' and the +% other two with the comment char as a~hyphen, i.e., +% |{|\|}| breaks into +% |{%|\\ \|}| ^^A] bal. braces for Emacs +% and \|\mylittlemacro| breaks into \|%|\\ +% |\mylittlemacro|. +% +% As the standard \LaTeX\ one, my |\verb| issues an error when a~line +% end occures 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 +% \[\hbox{\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[Macros for Marking the Macros]{^^B +% \gmhypertarget{Macros for Marking the Macros}} +% +% 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\CodeDefine, \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 `|\...Define/Usage| commands unstarred. +% +% The two |\Code...| 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 +% \[ \hbox{|%\CodeDefine*{foo}|} \] +% right before the code line +% \[\hbox{|\newenvironment{foo}{%|}\]^^A] +% i.e., not separated by any code line. The starred versions of +% the |\Code...| commands are also intended to mark implicit +% definitions of macros, e.g., |\CodeDefine*\@foofalse| before +% the line +% \[\hbox{|\newif\if@foo|.}\] +% +% They both are |\outer|. +% +% The |\TextUsage| (one-argument) command is intended to mark usage of +% a~verbatim occurrence of a~\TeX\ object in the commentary. Unlike +% the two |\Code...|s, 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\CodeDefIndex\ 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 |\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} +% +% It's\label{IEIDeclarations} understandable\footnote{After reading ^^B( +% \docfm's documentation ;-)\,.} that you don't +% want some control sequences to be indexed in your documentation. The +% \docfm\ package gives a~brilliant solution: the +% \TextUsage\DoNotIndex\ declaration. So do I +% (although here, \TeX nically it's done another +% way). It OCSR. This declaration takes one +% argument consisting of a~list of control sequences not to be +% indexed. The items of this list may be separated with commas, as in +% \docfm , but it's not obligatory. The whole list should come in +% curly braces (except when it's one-element), e.g., +% \[\hbox{\verb+\DoNotIndex{\some@macros,\are* \too\auxiliary\?}+}\] +% (The spaces after the control sequences are ignored.) +% You may use as many |\DoNotIndex|es as you wish (about half as many as +% many CSs may be declared, because for each CS excluded from indexing +% a~special CS is declared that stores the ban sentence). +% Excluding the same CS more than once makes no problem. +% +% I~assume you wish most of \LaTeX\ macros, \TeX\ primitives etc.\ to +% be excluded from your index (as I~do). Therefore \pk{gmdoc} excludes +% some 300 CSs by default. If you don't like it, just set the +% |indexallmacros| package option. +% +% On the third hand, if you like the default exclusions in general but +% wish to undo just a~couple of them, you are given \TextUsage\DoIndex\ +% declaration (OCSR) that removes a~ban on all the CSs given in the +% argument, e.g., +% \[\hbox{\verb+\DoIndex{\par \@@par \endgraf}+}\] +% +% Moreover, you are provided the \TextUsage\DefaultIndexExclusions\ +% and \Describe\UndoDefaultIndexExclusions^^A +% \cs{Un\-do\-Def\-ault\-Ind\-ex\-Ex\-cl\-us\-ions} declarations that +% act according to their names. You may use them in any configuration +% with the |indexallmacros| option. Both of these declarations OCSR. +% +% +% \subdivision{The \ds\ Directives} +% +% \gmdoc\ typesets the \ds\ directives and it does it quite likely as +% \docfm, i.e., with math sans serif font. It does it automatically +% whether you use the traditional settings or the new. +% +% Advised by my \TeX\ Guru, I~didn't implement the module nesting +% recognition (MW told it's not that important.) +% +% So far \gmhypertarget{verbatim mode directive} is only +% half-handled. That is, a~line beginning with |%<<|\ will be +% typeset as a~\ds\ directive, but +% the closing line |%|\ will be not. It doesn't hard to +% implement, I~only receive some message it's really useful for +% someone. +% +%^^A If you use the \TextUsage*{macrocode} environment, you don't have to +%^^A add any CS to get \ds\ directive typeset properly: within +%^^A \env{macrocode} a~|<| sign in a~line commented out is read as +%^^A a~beginning of a~\ds\ directive, which means that \TeX\ looks +%^^A for the closing |>| or the very next |<| as the beginning of the +%^^A special directive |<<|\. In the +%^^A standard case of |<|\|>| \TeX\ typesets any further text +%^^A in its line as the code. +%^^A +%^^A If you want the \ds\ directives to be typeset without +%^^A \env{macrocode}, you shoud declare \TextUsage\docstrips\ to make +%^^A \TeX\ read the |<| in the comment layer as the beginning of +%^^A a~\ds\ directive. In |\docstrips|'s scope the |<| signs +%^^A occurring in math mode remain just inequality signs. +%^^A +%^^A If you wish only the first |<| met to start a~\ds\ directive +%^^A typesetting, then there's \TextUsage\docstrip\ declaration that +%^^A restores the previous meaning of |<| after the first using it as +%^^A a~\ds\ directive opener. +%^^A +%^^A Both |\docstrips| and |\docstrip| OCSR and, of course you may use +%^^A them as environments (which doesn't make much sense with the +%^^A latter, though). +%^^A +% +% \subdivision{The Changes History} +% +% The \docfm's documentation reads: +% \begin{quotation} +% To maintain a change history within the file, the |\changes| command may +% be placed amongst the description part of the changed code. It takes three +% arguments, thus: +% \[\hbox{|\changes{|\|}{|\|}{|\|}|}\] +% +% The changes may be used to produce an auxiliary file (\LaTeX's +% |\glossary| mechanism is used for this) which may be printed after +% suitable formatting. The |\changes| [command] encloses the \ in +% parentheses and appends the \ to form the printed entry in +% such a change history [\dots\ obsolete remark ommitted]. +% +% To cause the change information to be written out, include +% \TextUsage\RecordChanges\ in the driver['s preamble or just in the +% source file (\pk{gmdocc.cls} does it for you)]. To read in and print +% the sorted change history (in two +% columns), just put the \TextUsage\PrintChanges\ command as the last +% (commented-out, and thus executed during the documentation pass +% through the file) command in your package file [or in the driver]. +% Alternatively, this command may form one of the arguments of the +% |\StopEventually| command, although a change history is probably not +% required if only the description is being printed. The command +% assumes that MakeIndex or some other program has processed the +% \pk{.glo} file to generate a~sorted \pk{.gls} file. You need +% a~special MakeIndex style file; a suitable one is supplied with +% \docfm\ [and \gmdoc], called \iffalse\pk{gglo.ist}\fi^^A +% [\dots\ \textbf{\pk{gmglo.ist}} for \gmdoc]. The \TextUsage\GlossaryMin, +% \TextUsage\GlossaryPrologue\ and \TextUsage\GlossaryParms\ macros are +% analagous to the |\Index...| versions [see +% sec.~\gmiflink[IndexParams]{The Parameters} +% p.\,\pageref*{IndexParams}]. (The \LaTeX\ `glossary' +% mechanism is used for the change entries.) +% \end{quotation} +% +% In \gmdoc\ |\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{\twelveclub} +%\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 +% \[\hbox{|\ChangesStart{|\|}{|\|/|\|/|\|}|}\] +% declaration. +% +% If the \env{ChangesStartDate} is set to a~date contemporary to \TeX\ +% i.e., not earlier than September 1982\footnote{DEK in \textit{\TeX\ ^^B +% The Program} mentions that month as of \TeX\ Version 0 release.}, +% then a~note shall appear at the beginning of the changes history +% that informs the reader of ommitting the earlier changes entries. +% +% If the date stored in \env{ChangesStartDate} is earlier than \TeX, +% no notification of ommitting shall be printed. This is intended for +% a~rather tricky usage of the changes start date feature: you may +% establish two threads of the changes history: the one for the users, +% dated with four digit year, and the other for yourself only, dated +% with two or three digit year. If you declare +% \[\hbox{|\ChangesStart{|\|}{1000/00/00}|}\] +% or so, the changes entries dated with less-than-four digit year +% shall be ommitted and no notification shall be issued of that. +% +% \stanza +% +% While scanning the CSs in the code, \gmdoc\ counts them and prints +% the information about their number on the terminal and in +% \pk{.log}. Moreover, you may declare +% \TextUsage\CheckSum|{|\|}| before the code and \TeX\ will +% inform you whether the number stated by you is +% correct or not, and what it is. As you guess, it's not my original idea +% but I~took it from \docfm. +% +% There it is provided as a~tool for +% testing whether the file is corrupted. +% My \TeX\ Guru says it's a~bit old-fashioned nowadays but I~like the +% idea and use it to document the file's growth. For this purpose +% \gmdoc\ types out lines like +% \begin{verbatim} +%% \chschange{v0.98j}{2006/10/19}{4372} +%% \chschange{v0.98j}{06/10/19}{4372} +%\end{verbatim} +% and you may place them at the beginning of the source file. Such +% a~line results in setting the check sum to the number contained in +% the last pair of braces and in making a~`general' changes entry that +% states the check sum for version \ dated \ was \. +% +% \subdivision{The Parameters} +% +% The \pk{gmdoc} package provides some parameters specific to +% typesetting the \TeX\ code: +% +% \stanza +% \TextUsage\stanzaskip\ is a~vertical space inserted when a~blank +% (code) line is met. It's equal |0.75\medskipamount| by default +% (with the \emph{entire} |\medskipamount|'s stretch- and +% shrinkability). Subsequent blank code lines do not increase this +% space. +% +% At the points where narration begins a~new line after the code or an +% inline comment and where a~new code line begins after the narration +% (that is not an inline comment), a~\TextUsage\CodeTopsep\ glue is +% added. At the beginning and the end of a~\env{macro} or +% \env{environment} environment a~|\MacroTopsep| glue is added. By +% default, these two skips are set equal |\stanzaskip|. +% +% The |\stanzaskip|'s value is assigned also to the display skips and +% to |\topsep|. This is done with the \TextUsage\UniformSkips\ +% declaration executed by default. If you want to change some of those +% values, you should declare \TextUsage\NonUniformSkips\ in the +% preamble to discard the default declaration. (To be more precise, by +% default |\UniformSkips| is executed twice: when loading \gmdoc\ and +% again |\AtBeginDocument| to allow you to change |\stanzaskip| and +% have the other glues set due to it. |\NonUniformSkips| relaxes the +% |\UniformSkips|'s occurrence at |\begin{document}|.) +% +% If you want to add a~vertical space of |\CodeTopsep| (equal by +% default |\stanzaskip|), you are provided the \TextUsage\stanza\ +% command. Similarly, if you want to add a~vertical space of the +% |\MacroTopsep| amount (by default also equal |\stanzaskip|), you are +% given the \TextUsage\chunkskip\ command. They both act analogously +% to |\addvspace| i.e., don't add two consecutive glues but put the +% bigger of them. +% +% Since |\CodeTopsep| glue is inserted automatically at each +% transition from the code (or code with an inline comment) to the +% narration and reverse, it may happen that you want not to add such +% a~glue exceptionally. Then there's the \TextUsage\nostanza\ +% command. +% +% \stanza +% The \TeX\ code is indented with the \TextUsage\CodeIndent\ glue +% and a~leading space increases indentation of the line by its +% (space's) width. The default value of |\CodeIndent| is 1.5\,em. +% +% There's also a~parameter for the indent of the narration, +% \TextUsage\TextIndent, but you should use it only in emergency +% (otherwise what would be the margins for?). It's 0\,sp by default. +% +% \stanza +% By default, typesetting a~|\DocInput/Include|d file is ended with +% a~codeline containing the text `\EOFMark' given by the +% \TextUsage\EOFMark\ macro. If you don't like such an ending, you +% should end the source file with the \TextUsage\NoEOF\ macro in +% a~comment, i.e., +% \[\hbox{|%|\|\NoEOF|}\] +% This macro redefines |\EOFMark| and suppresses the End +% Of File token to close the input properly. It also has the +% |\endinput| effect so you may put some text you don't want to +% document after it. +% +% \stanza +% +% The crucial concept of \gmdoc\ is to use the line end character +% as a~verbatim group opener and the comment char, usually the |%|, as +% its delimiter. Therefore the `knowledge' what char starts +% a~commentary is for this package crucial and utterly +% important. The default assumption is that you use |%| as we +% all do. So, if you use another character, then you should declare it +% with \TextUsage\CodeDelim\ typing the desired char +% preceded by a~backslash, e.g., |\CodeDelim\&|\,. (As just +% mentioned implicitly, \possfil|\CodeDelim\%| is declared by +% deafult.) +% +% This declaration is always global so when- and wherever you change +% your mind you should express it with a~new |\CodeDelim| +% declaration. +% +% The plain (unstarred) version of |\CodeDelim| changes also the verb +% `hyphen', the char appearing at the verbatim line breaks that is. If +% you don't want to change the verb `hyphen', use |\CodeDelim*|. +% +% \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\^ole is to allow some special chars +% to appear in the marking commands' arguments (the commands described +% in section \gmiflink{Macros for Marking the Macros}). The default +% contents of this list is | | (the space) and |^| so you may mark the +% environments names and special sequences like |^^A| safely. This +% list is also extended with every char that is |\MakeShortVerb|ed. +% (I~don't see a~need of removing chars from this list, but if +% you do, please let me know.) +% +% \stanza +% The line numbers (if enabled) are typeset in the +% \TextUsage\LineNumFont\ declaration's scope, which +% is defined as |{\normalfont\tiny}| by default. Let us also remember, that for +% each counter there is a~|\the|\ macro available. The +% counter for the line numbers is called \TextUsage*{codelinenum} so +% the macro printing it is |\thecodelinenum|. By default we don't +% change its \LaTeX's definition which is equivalent +% |\arabic{codelinenum}|. +% +% +% Three more parameter macros, are \TextUsage\IndexPrefix, +% \TextUsage\EntryPrefix\ and \TextUsage\HLPrefix. All three are +% provided with the account of including multiple files in one +% document. +% They are equal (almost) |\@empty| by default. The first may store +% main level index entry of which all indexed macros and environments +% would be subentries, e.g., the name of the package. The third may or +% even should store a~text to distinguish equal codeline numbers of +% distinct source files. It may be the file name too, of course. The +% second macro is intended for another concept, namely the one from +% \pk{ltxdoc} class, to distinguish the codeline numbers from +% different files \emph{in the index} by the file marker. Anyway, if +% you document just one file per document, there's no need of +% redefining those macros, nor when you input multiple files with +% |\DocInclude|. +% +% \pk{gmdoc} automatically indexes the control sequences +% occurring in the code. Their index entries may be `common' or +% distinguished in two (more) ways. The concept is to distinguish the +% entries indicating the \emph{usage} of the CS and the entries +% indicating the \emph{definition} of the CS. +% +% The special formattings of `usage' and `def' index entries are +% determined by \TextUsage\UsgEntry\ and \TextUsage\DefEntry\ +% one-parameter macros (the parameter shall be substituted with the +% reference number) and by default are defined as |\textit| and +% |\underline| respectively (as in \docfm). +% +% There's one more parameter macro, \TextUsage\CommonEntryCmd\ that +% stores the name of the encapsulation for the `common' index +% entries (not special) i.e., a~word that'll become a~CS that will +% be put before an entry in the \file{.ind} file. By default it's defined +% as |{relax}| and a~nontrivial use of it you may see in line +% \ref{UsgHack} of the driver file of this documentation, where it +% makes all the index entries of the driver's code are formatted as `usage'. +% +% \stanza +% ^^A~Index Parameters +% \gmhypertarget[IndexParams]{The index} comes in a~\env{multicols} +% environment whose columns number is determined by the +% \TextUsage*{IndexColumns} counter set by default to~3. To save space, +% the index begins at the same page as the previous text provided +% there is at least \TextUsage\IndexMin\ of the page height free. By +% default, |\IndexMin|\equals\the\IndexMin. +% +% The text put at the beginning of the index is declared with +% a~one-argument \TextUsage\IndexPrologue. Its default text at current +% index option you may \gmiflink[DIPrologue]{admire} on page +% \pageref*{DIPrologue}.^^A +% \AtDIPrologue{\raisebox{4cm}[0sp][0sp]{\gmhypertarget[DIPrologue]}} +% Of course, +% you may write your own |\IndexPrologue{|\|}|, but if you like the default and want only to add +% something to it, you are provided \TextUsage\AtDIPrologue\ +% one-argument declaration that adds the stuff after the default +% text. For instance, I~used it to add a~label and hypertarget that is +% referred to two sentences earlier. +% +% By default the colour of the index entry hyperlinks is set black to +% let Adobe Reader work faster. If you don't want this, +% \Describe\IndexLinksBlack|\let\IndexLinksBlack\relax|. That leaves +% the index links colour alone and hides +% the text about black links from the default index prologue. +% +% Other index parameters are set with the \TextUsage\IndexParms\ macro +% defined in line \gmifref[IndexParms]{sixty-odd} of the code. If you +% want to change some of them, you don't have to use +% |\renewcommand*\IndexParms| and set all of the parameters: you may +% \Describe\gaddtomacro^^A +% |\gaddtomacro\IndexParms{|\|}|. +% (|\gaddtomacro| is an alias for \LaTeX's |\g@addto@macro| provided +% by \pk{gmutils}.) +% +% At the default \gmdoc\ settings the \file{.idx} file is prepared for +% the default settings of MakeIndex (no special style). Therefore the +% index control chars are as usual. But if you need to use other +% chars as MakeIndex controls, know that they are stored in the four +% macros: \TextUsage\actualchar, \TextUsage\quotechar, +% \TextUsage\levelchar\ and \TextUsage\encapchar\ whose meaning you +% infer from their names. Any redefinition of them \emph{should be ^^B +% done in the preamble} because the first usage of them takes place at +% |\begin{document}| and on it depends further tests telling \TeX\ +% what characters of a~scanned CS name it should quote before +% writing it to the \pk{.idx} file. +% +% \stanza +% Frank Mittelbach in \docfm\ provides the |\verbatimchar| macro to +% (re)define the |\verb|'s delimiter for the index entries of the +% scanned CS names etc. \gmdoc\ also uses \TextUsage\verbatimchar\ but +% defines it as |{&}|. Moreover, a~macro that wraps a~CS name in |\verb| +% checks whether the wrapped CS isn't |\&| and if it is, |$| is taken +% as the delimiter. So there's hardly chance that you'll need to +% redefine |\verbatimchar|. +% +% So strange delimiters are chosen deliberately to allow any `other' +% chars in the environments names. +% +% \stanza +% There's a~quadratus of commands taken from \docfm: +% \TextUsage\StopEventually, \TextUsage\Finale, +% \TextUsage\AlsoImplementation\ and \TextUsage\OnlyDescription\ that +% should be +% explained simultaneously (in a~polyphonic song +% e.g.). +% +% The |\OnlyDescription| and |\AlsoImplementation| +% declarations are intended to exclude or include the code part from +% the documentation. The point between the description and the +% implementation part should be marked with |\StopEventually{|\|}| and |\Finale| should be typed +% at the end of file. Then |\OnlyDescription| defines +% |\StopEventually| to expand to its argument followed by |\endinput| +% and |\AlsoImplementation| defines |\StopEventually| to do nothing +% but pass its argument to |\Finale|. +% +% +% \subdivision{The Narration Macros} +% +% To print the control sequences' names you have the \TextUsage\verb\ macro and +% its `shortverb' version whatever you define. But they won't 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}. +% +% 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\ and \TextUsage\subdivision\ so far, that by +% default are |\let| to be |\section| and |\subsection| if such +% commands are defined in the documentclass. (If not, |\division| and +% |\subdivision| are |\let| to be |\relax|.) +% +% \stanza +% One more kind of flexibility is to allow using \pk{mwcls} or the +% standard classes for the same file. There was a~trouble with the +% number and order of the optional arguments of the original +% \pk{mwcls}'s sectioning commands. +% +% It's resolved in \pk{gmutils} so you are free at this point, and +% even more free than in the standard classes: if you give +% a~sectioning command just one optional argument, it will be the +% title to toc and to the running head (that's standard in +% scls\footnote{See \pk{gmutils} for some subtle details.}). If you give +% \emph{two} optionals, the first will go to the running head and the +% other to toc. (In both cases the mandatory argument goes only to the +% page). +% +% \stanza +% If you wish the |\DocInclude|d files make other sectionings than the +% default, you may declare \TextUsage\SetFileDiv|{|\|}|. +% +% \stanza +% +% \pk{gmdoc.sty} provides also an environment \TextUsage*{gmlonely} +% to wrap some text you think you may want to skip some day. When +% that day comes, you write \TextUsage\skipgmlonely\ before the +% instances of \env{gmlonely} you want to skip. This declaration has +% an optional argument which is for a~text that'll appear in(stead of) the +% first \env{gmlonely}'s instance in every |\DocInput| or +% |\DocInclude|d file within |\skipgmlonely|'s scope. +% +% An example of use you may see in this documentation: the repeated +% passages about the installation and compiling the documentation are +% skipped in further chapters thanks to it. +% +% \stanza +% \gmdoc\ 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\eTeX\eTeX,\\ +% \Describe\pdfeTeX\pdfeTeX\\ +% \Describe\pdfTeX\pdfTeX\\ +% \Describe\XeTeX\XeTeX\ (the first |E| will be reversed if the +% \pk{graphics} package is loaded) and\\ +% \Describe\LaTeXpar\LaTeXpar.\par +% (The last logo is defined in \pk{gmutils}.) +% +% \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 and mandatory argument +% which is the contents of the marginpar. +% +% \stanza +% To make a~vertical space to separate some piece of text you are +% given two macros: \TextUsage\stanza\ and \TextUsage\chunkskip. The +% first adds |\stanzaskip| while the latter |\MacroTopsep|. Both of +% them take care of not cumulating the vspaces. +% +% +%\stanza +% The \TextUsage*{quotation} environment is redefined just to enclose +% its contents in double quotes. +% \stanza +% +% The \TextUsage\GetFileInfo|{|\|}| command +% defines \TextUsage\filedate, \Describe\fileversion\cs{fil\-e\-vers\-ion} and +% \TextUsage\fileinfo\ as the respective pieces of the info (the +% optional argument) provided +% by \cs{Pro\-vid\-es\-Class/Pack\-age/Fi\-le} declarations. The +% information of the file you process with \gmdoc\ +% is provided (and therefore getable) if the file is also loaded (or +% the |\Provide...| line occures in a~|\StraightEOL| scope). +% +% Since you may wish to process also files that you don't load, +% there are commands \TextUsage\ProvideFileInfo|{|\|}[|\|]| and +% \TextUsage\ProvideSelfInfo|[|\|]|. (\ should consist of: +% \|/|\|/|\| |\| |\.) +% +% A~macro for the standard note is provided, \TextUsage\filenote, that +% expands to ``This file has version number \ dated +% \.'' To place such a~note in the document's title (or heading, +% with |\DocInclude| at the default settings), there's +% \TextUsage\thfileinfo\ macro that puts |\fileinfo| in |\thanks|. +% +% \stanza +% Since |\noindent| didn't want to cooperate with my code and +% narration layers sometimes, I~provide \TextUsage\gmdnoindent\ that +% forces a~not indented paragraph if |\noindent| could not. +% +% \stanza +% If you declare the code delimiter other than |%| and then want |%| +% back, you may write \TextUsage\CDPerc\ instead of |\CodeDelim\%|. +% +% If you like |&| as the code delimiter (as I~did twice), you may write +% \TextUsage\CDAnd\ instead of |\CodeDelim\&|. +% +% +%^^A \stanza +%^^A For an example driver file see chapter \gmiflink{The Driver}. +% +% +% \subdivision{A~Queerness of \cs{label}} +% +% You should be loyally informed that |\label| in \gmdoc\ +% behaves slightly +% non-standard in the \cs{Doc\-In\-put/\:Inc\-lud\-e}d files: +% the automatic redefinitions of |\ref| at each code line +% are \emph{global} (since the code is typeset in groups and the +% |\ref|s will be out of those groups), so +% a~|\ref|erence in the narrative will point at the last code line not +% the last section, \emph{unlike} in the standard \LaTeX. +% +% +% \subdivision{\docfm-Compatibility} +% +% One of my goals while writing \gmdoc\ was to make compilation of +% \docfm-like files with \gmdoc\ possible. I~cannot guarantee the goal +% has been reached but I~\emph{did} compile \pk{doc.dtx} with not +% a~smallest change of that file (actually, there was a~tiny little buggie in +% line 3299 which I~fixed remotely with |\AfterMacrocode| tool written +% specially for that). So, +% if you wish to compile a~\docfm-like file with my humble package, +% just try. +% +% The \docfm\ commands most important in my opinion are supported by +% \gmdoc. Some commands, mostly the obsolete in my opinion, are not +% supported but give an info on the terminal and in \pk{.log}. +% +% I~assume that if one wishes to use \docfm's interface then \heshe\ +% won't use \gmdoc's options but just the default. (Some \gmdoc\ +% options may interfere with some \docfm\ commands, they may cancel +% them e.g.) +% +% \stanza +% The main input commands compatible with \docfm\ are +% \TextUsage\OldDocInput\ and \TextUsage\DocInclude, the latter +% however only in the \TextUsage\olddocIncludes\ declaration's scope. +% +% Within their scope/argument the \TextUsage*{macrocode} environments +% behave as in \docfm, i.e.\ they are a~kind of verbatim and require to be +% ended with |% \end{macrocode(*)}|. +% +% The default behaviour of \env{macrocode(*)} with the `new' input +% commands is different however. Remember at te `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 +%\[\hbox{|\alittlemacro %| change it to foo}\] +% (Note that `my' \env{macrocode} doesn't require +% the magical |% \end|.) +% +% If you are used to the traditional (\docfm's) \env{macrocode} and still wish to +% use \gmdoc\ new way, you have at least two options: there is the +% \TextUsage*{oldmc} environment analogous to the traditional (\docfm's) +% \env{macrocode} (it also has the starred version), that's the first +% option (I~needed the traditional behaviour once in this +% documentation, find out where \& why). The other is to write +% \TextUsage\VerbMacrocodes. That declaration (OCSR) redefines +% \env{macrocode} and \env{macrocode*} to behave the traditional way. +% (It's always executed by |\OldDocInput| and |\olddocIncludes|.) +% +% \stanza +% For a~more detailed discussion of what is \docfm-compatible and how, +% see the code section \gmiflink[doccompa]{\docfm-Compatibiliy}. +% +% \StopEventually{\NoEOF} +% +% +% \division{The Code} +% +%\iffalse For debug +\catcode`\^^C9\relax +% \fi +% \catcode`\^^C\active +% +% \changes[^^C]{v0.98g}{06/10/10}{recatcoded for debug: in the working +% pass it's made ignored and in the documenting pass it's made active} +% +% +% \DoIndex{\par \@@par} +% +% The basic idea of this package is to re|\catcode| |^^M| (the line +% end char) and |%| (or any other comment char) so that they start and +% finish typesetting of what's between them as the \TeX\ code i.e., +% verbatim and with the bells and whistles. +% +% The bells and whistles are (optional) numbering of the codelines, +% and automatic indexing the CSs, possibly with +% special format for the `def' and `usage' entries. +% +% As mentioned in the preface, this package aims at a~minimal markup +% of the working code. A~package author writes \hisher\ splendid code +% and adds a~brilliant comment in |%|ed lines and that's all. Of +% course, if \heshe\ wants tomake a~|\section| or |\emph|asise, +% \heshe\ has to type respective CSs. +% +% I~see the feature described above to be quite a~convenience, +% however it has some price. See section +% \gmiflink[afc]{Life Among Queer EOLs} for details, +% here I~state only that in my opinion the price is not very high. +% \stanza +% +% More detailedly, the idea is to make |^^M| (end of line char) active +% and to define it to check if the next char i.e., the beginnig of the +% next line is a~|%| and if so +% to gobble it and just continue usual typesetting or else to start +% a~verbatim scope. In fact, every such a~line end starts a~verbatim +% scope which is immediately closed, if the next line begins with +% (leading spaces and) the code delimiter. +% +% Further details are typographical parameters of verbatim scope and +% how to restore normal settings after such a~scope so that a~code +% line could be commented and still displayed, how to deal with +% leading spaces, how to allow breaking a~moving argument in two lines +% in the comment layer, how to index and marginpar macros etc. +% +% +%\subdivision{The Package Options} +% +% Maybe someone wants the code lines not to be numbered. +% \CodeDefIndex\if@linesnotnum +% \CodeDefIndex*\@linesnotnumtrue +% \CodeDefIndex*\@linesnotnumalse +\newif\if@linesnotnum +% \CodeDefine*{linesnotnum} +\DeclareOption{linesnotnum}{\@linesnotnumtrue} + +% And maybe he or she wishes to declare resetting the line counter +% along with some sectioning counter him/herself. +% \CodeDefIndex\if@uresetlinecount +% \CodeDefIndex*\@uresetlinecounttrue +% \CodeDefIndex*\@uresetlinecountfalse +\newif\if@uresetlinecount +% \CodeDefine*{uresetlinecount} +\DeclareOption{uresetlinecount}{\@uresetlinecounttrue} + +% And let the user be given a~possibility to count the comment +% lines. +% \CodeDefIndex\if@countalllines +\newif\if@countalllines +% \CodeDefine*{countalllines} +\DeclareOption{countalllines}{\@countalllinestrue} + +% Unlike in \docfm , indexing the macros is the default and the +% default reference is the code line number. +% \CodeDefIndex\if@noindex +% \CodeDefIndex*\@noindextrue +% \CodeDefIndex*\@noindexfalse +\newif\if@noindex +% \CodeDefine*{noindex} +\DeclareOption{noindex}{\@noindextrue} + +% \CodeDefIndex\if@pageindex +% \CodeDefIndex*\@pageindextrue +% \CodeDefIndex*\@pageindexfalse +\newif\if@pageindex +% \CodeDefine*{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}). +% \CodeDefIndex\if@indexallmacros +% \CodeDefIndex*\@indexallmacrostrue +% \CodeDefIndex*\@indexallmacrosfalse +\newif\if@indexallmacros +% \CodeDefine*{indexallmacros} +\DeclareOption{indexallmacros}{\@indexallmacrostrue} + +% Some document classes don't support marginpars or disable them by +% default (as my favourite Marcin Woli\'nski's classes). +% +% \CodeDefIndex\if@marginparsused +% \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.)} +% \CodeDefIndex*\@marginparsusedtrue +% \CodeDefIndex*\@marginparsusedfalse +\@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:\CodeDefine*{withmarginpar} +\DeclareOption{withmarginpar}{\@marginparsusedtrue} +%\CodeDefine*{nomarginpar} +\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). +% \CodeDefIndex\if@codespacesblank +\newif\if@codespacesblank +% \CodeDefine*{codespacesblank} +\DeclareOption{codespacesblank}{\@codespacesblanktrue} + + +\ProcessOptions + + +% \subdivision{The Dependencies and Preliminaries} +% +% We require another package of mine that provides some tricky macros +% analogous to the \LaTeX\ standard ones, such as |\newgif| and +% |\@ifnextcat|. +\RequirePackage{gmutils} + +% A~standard package for defining colours, +\RequirePackage{color} +% and a~colour definition for the hyperlinks not to be too bright +\definecolor{deepblue}{rgb}{0,0,.85} + +% And the standard package probably most important for \gmdoc: +% If the user doesn't load \pk{hyperref} with \hisher\ favourite +% options, we do, with \emph{ours}. If \heshe\ has +% done it, we change only the links' colour. +% +% \changes{v0.97}{06/09/04}{linkcolor made deep blue} +\@ifpackageloaded{hyperref}{\hypersetup{colorlinks=true, + linkcolor=deepblue, urlcolor=blue, filecolor=blue}}{% + \RequirePackage[colorlinks=true, linkcolor=deepblue, urlcolor=blue, + filecolor=blue, pdfstartview=FitH, pdfview=FitBH, + pdfpagemode=None]{hyperref}} + +% 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} + +\if@noindex + \AtBeginDocument{\gag@index}% for the latter macro see line + % \ref{gag@index}. +\else + \RequirePackage{makeidx}\makeindex +\fi + +% Now, a~crucial statement about the code delimiter in the input file. +% Providing a~special declaration for the assignment is intended for +% documenting the packages that play with |%|'s +% |\catcode|. Some macros for such plays are defined +% \gmiflink[CDAnd]{further}. +% +% The declaration comes in the starred and unstarred version. The +% unstarred version besides declaring the code delimiter declares +% the same char as the verb(atim) `hyphen'. The starred version +% doesn't change the verb 'hyphen'. That is intended for the special +% tricks e.g.\ for the \env{oldmc} environment. +% +% If you want to change the verb `hyphen', there is the +% |\VerbHyphen\|\ +% declaration provided by \pk{gmverb}. +% +% \changes{v0.98c}{06/9/8}{\cs{CodeDelim} renamed from a~rather confusing +% \cs{NewCommentChar}; also the internal \cs{code@delim} is renamed +% from as much confusing \cs{commentchar} and a~\cs{glet} for +% \cs{verb}s \cs{verbhyphen} is added; similarly +% \cs{[Un]CodeDelimAnd} renamed from \cs{[un]commentand}} +% +% \changes{v0.98m}{06/11/10}{\cs{CDAnd} and \cs{CDPerc} renamed from +% \cs{CodeDelimAnd} and \cs{UnCodeDelimAnd} and both those commands +% simplified to just declaring the code delimiter} +% +% \changes{v0.99a}{06/12/1}{split into the starred and unstarred +% versions} +% +% \CodeDefine\CodeDelim \CodeDefine\code@delim +\def\CodeDelim{\@ifstar{\Code@Delim}{\Code@Delim@St}} + +\def\Code@Delim#1{% + {\escapechar\m@ne + \expandafter\gdef\expandafter\code@delim\expandafter{\string#1}}} + +\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 occure 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| +% \CodeDefIndex\gmd@preverypar +\newtoks\gmd@preverypar + +% \CodeDefIndex\settexcodehangi +\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. +% \CodeDefIndex\@@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): +% \CodeDefine\TextIndent +\newlength\TextIndent +% I~assume it's originally equal |\leftskip|, i.e.\ |\z@|. And for +% the \TeX\ code: +\newlength\CodeIndent +%\label{CodeIndent} +% \CodeDefine\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 +% derivates for typesetting poetry. A~computer program code \emph{is} +% poetry. +% \CodeDefine\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 the \ae sthetical +% 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 other most important +% vertical spaces used in \gmdoc. I~think a~macro that gathers all +% these assignments may be handy. +% \CodeDefine\MacroTopsep +% \CodeDefine\CodeTopsep +% \CodeDefine\UniformSkips +\def\UniformSkips{%\label{UniformSkips} + % \CodeDefine\CodeTopsep \CodeDefine\MacroTopsep + \CodeTopsep=\stanzaskip + \MacroTopsep=\stanzaskip + \abovedisplayskip=\stanzaskip + %\nostanza + % \leftskip0sp \noindent |%\abovedisplayshortskip| + % remains untouched as it is 0.0\,pt plus 3.0\,pt by default.\par + % + % \nostanza + \belowdisplayskip=\stanzaskip + \belowdisplayshortskip=.5\stanzaskip% due to DEK's idea of making the + % short below display skip half of the normal. + \advance\belowdisplayshortskip by\smallskipamount + \advance\belowdisplayshortskip by-1\smallskipamount% We advance + % \nlpercent\cs{be\+low\+dis\+play\+short\+skip} forth and back to + % give it the \nlpercent\cs{small\+skip\+am\+ount}'s shrink- and + % stretchability components. + \topsep=\stanzaskip + \partopsep=\z@ +} +% We make it the default, +\UniformSkips +% \gmdnoindent but we allow you to change the benchmark glue +% i.e., |\stanzaskip| in the preamble and still have the other glues +% set due to it: we launch |\UniformSkips| again after the +% preamble. +\AtBeginDocument{\UniformSkips} + +% So, if you don't want them at all i.e., you don't want to set other +% glues due to |\stanzaskip|, you should use the following +% declaration. That shall discard the unwanted setting already placed +% in the |\begin{document}| hook. +% +% \CodeDefine\NonUniformSkips +\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. +% \CodeDefine\chunkskip +\newcommand*\chunkskip{% + \skip0=\MacroTopsep + \if@codeskipput\advance\skip0 by-\CodeTopsep\fi + \par\addvspace{\skip0}\@codeskipputgtrue} + +% And, for a~smaller part of text, +% \CodeDefine\stanza +\newcommand*\stanza{% + \skip0=\stanzaskip + \if@codeskipput\advance\skip0 by-\CodeTopsep\fi + \par\addvspace{\skip0}\@codeskipputgtrue} + +% Since the stanza skips are inserted automatically most often (cf.\ lines +% \ref{codeskip}, \ref{codeskip2}, \ref{codeskip3}, \ref{codeskip4}, +% \ref{codeskip5}), sometimes you may need to forbid them. +% \CodeDefine\nostanza +\newcommand*\nostanza{% + \@codeskipputgtrue\@afternarrgfalse\@aftercodegtrue}% In the `code +% to narration' case the first switch is enough but in the countercase +% `narration to code' both the second and third are necessary while +% the first is not. +% +% +% To count the lines where they have begun not before them +% \CodeDefine\if@newline \CodeDefine*\@newlinegtrue +% \CodeDefine*\@newlinegfalse +\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} |%<...|. +% \CodeDefine*\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. +% +% \CodeDefine\DocInput \CodeDefine\Doc@Input +% \changes{v0.98}{06/09/05}{\cs{@makeother\protect\bslash_} added} + +\newcommand*\DocInput{\bgroup\@makeother\_\Doc@Input} + +\begingroup\catcode`\^^M=\active% +\firstofone{\endgroup% + \newcommand*{\Doc@Input}[1]{\egroup\begingroup% + % \CodeDefIndex\gmd@inputname + \edef\gmd@inputname{#1}% we'll use it in some notifications. + % \CodeDefIndex\gmd@currentlabel@before + \let\gmd@currentlabel@before=\@currentlabel% we store it 'cause + % we'll do |\xdef|s of |\@currentlabel| to make proper references + % to the line numbers so we want to restore current + % |\@currentlabel| after our group. + % \CodeUsgIndex\clubpenalty \CodeUsgIndex\widowpenalty + \gmd@setclubpenalty% we wrapped the assignment of |\clubpenalty| + % in a~macro because we'll repeat it twice more. + \@clubpenalty\clubpenalty \widowpenalty=3333 % Most paragraphs of the code will be + % one-line most probably and many of the narration, too.\par + %\vskip-\stanzaskip + % \changes[\DocInput]{v0.95}{06/08/15}{\cs{club-} + % and \cs{widowpenalty} set both to 3333} + %\CodeUsgIndex\tolerance + \tolerance=1000 % as in \docfm. + % \CodeUsgIndex\CodeSpacesBlank + \if@codespacesblank\CodeSpacesBlank\fi% \label{cspb}The default is + % that the code spaces are visible but here this may be cancelled + % due to the \cs{co\+de\+spa\+ces\+blank} option. + \catcode`\^^M=\active% + % \CodeUsgIndex\code@delim + \expandafter\@makeother\code@delim% + % \CodeUsgIndex\gmd@resetlinecount + \gmd@resetlinecount% due to the option |uresetlinecount| + % we reset the linenumber counter or do nothing. + % \CodeUsgIndex\@beginputhook + \@beginputhook% my first use of it is to redefine |\maketitle| + % just at this point not globally. \CodeUsgIndex\everypar + \everypar=\expandafter{\expandafter\@codetonarrskip\the\everypar}% + % \CodeDefine*{^^M} + \let^^M=\gmd@textEOL% + % \CodeDefIndex\gmd@guardedinput + \edef\gmd@guardedinput{% + \noexpand\@@input #1\relax% it's true \TeX's + % |\input|. \CodeUsgIndex\EOFMark + \noexpand\EOFMark% to pretty finish the input, see + % line~\ref{eofMark}.\CodeUsgIndex\code@delim + \noexpand^^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|). + \expandafter\expandafter\expandafter^^M\gmd@guardedinput%\label{eeeEOL} + \par% + % \CodeUsgIndex\@endinputhook + \@endinputhook% It's a~hook to let postpone + % some stuff till the end of input. We use it e.g.\ for the + % \docfm-(not)likeliness notifications. + \glet\@currentlabel=\gmd@currentlabel@before% we restore + % value from before this group. In a~very special case this could + % cause unexpected behaviour of crossrefs, but anyway we acted + % globally and so acts \pk{hyperref}. + \endgroup% + }% end of |\Doc@Input|'s definition. +}% end of |\firstofone|'s argument. + +% So, having the main macro outlined, let's fill in the details. +% +% First, define the queer EOL. We define a~macro that |^^M| will be +% let to. |\gmd@textEOL| +% will be used also for checking the |%^^M| case (|\@ifnextchar| +% does |\ifx|). +% +% \CodeDefine\gmd@textEOL + +\def\gmd@textEOL{ % a~space just like in normal \TeX. We put it first to + % cooperate with \nlpercent|\^^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. + \expandafter\@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 + % \nlpercent|\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\|% 'cause |\ttverbatim| doesn't do that. + \MakePrivateLetters% see line \ref{MPL}.\par + \expandafter\@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. + \expandafter\@ifnextchar\expandafter{\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: +% \CodeDefine\AtEndInput \CodeDefine\@endinputhook +\def\AtEndInput{\g@addto@macro\@endinputhook} +\def\@endinputhook{} +%\label{@endinputhook} +% Simili modo +% \CodeDefine\AtBegInput \CodeDefine\@beginputhook +\def\AtBegInput{\g@addto@macro\@beginputhook} +\def\@beginputhook{} + +% And let's use it instantly to avoid a~disaster while reading in the +% table of contents. +% \CodeDefine\tableofcontents +% \CodeDefIndex\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\^ole of |\@ifQueerEOL|: +% +% \changes{v0.98a}{06/09/06}{\cs{tableofcontents}, \cs{PrintIndex} +% and \cs{PrintChanges} modified to work properly in the `queer line +% ends' environment.} +% \CodeDefine\@ifQueerEOL +% \changes{v0.98a}{06/09/06}{added} +\long\def\@ifQueerEOL#1#2{% + \ifnum\the\catcode`\^^M=\active \afterelsefi#1\else\afterfi#2\fi} + +% \CodeDefine\AtBegInputOnce 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. +% \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 CodeDefine*{hook@oncecnt} +%^^A CodeDefIndex*\c@hook@oncecnt +%^^A\newcounter{hook@oncecnt} +% \CodeDefine\gmd@ABIOnce +\@emptify\gmd@ABIOnce +\AtBegInput\gmd@ABIOnce + +\long\def\AtBegInputOnce#1{% +%^^A \stepcounter{hook@oncecnt}% +%^^A \expandafter\long\expandafter\edef% \CodeUsgIndex*{NeuroOncer} +%^^A \csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname{% +%^^A \noexpand\glet\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname\relax}% +%^^A \expandafter\addtomacro\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname{#1}% +%^^A \expandafter\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 +% \CodeDefine\EOFMark +\def\EOFMark{\} +% \label{eofMark}Other solutions did print the last code delimiter or +% would require managing a~special case for the macros typesetting +% \TeX\ code to suppress the last line's numbering etc. +% +% If you don't like it, see line \ref{NoEOF}. +% \stanza +% +% Due to the |codespacesblank| option in the line \ref{cspb} we launch +% the macro defined below to change the meaning of a~\pk{gmdoc}-kernel +% macro. +% \CodeDefIndex\gmd@DoTeXCodeSpace +\begin{obeyspaces}% +\gdef\gmd@DoTeXCodeSpace{% +\obeyspaces\let =\breakabletwelvespace}% +% \stanza +% \CodeDefine\CodeSpacesBlank +% \changes{v0.98a}{06/09/06}{a~kernel \cs{gmd@verbatimspace} renamed +% to \cs{gmd@texcodespace} and a~bug fixed.} +% \CodeUsgIndex\gmobeyspaces +% \CodeDefIndex\gmd@texcodespace +\gdef\CodeSpacesBlank{% +\let\gmd@DoTeXCodeSpace\gmobeyspaces% +\let\gmd@texcodespace=\ }% the latter |\let| is for the |\if...|s. +%\stanza +% \CodeDefine\CodeSpacesSmall +\gdef\CodeSpacesSmall{% +\def\gmd@DoTeXCodeSpace{% +\obeyspaces\def {\,\hskip\z@}}% +\def\gmd@texcodespace{\,\hskip\z@}}% +% +\end{obeyspaces} + +% How the continuing of the narration should look like? +% \CodeDefIndex\gmd@continuenarration +\def\gmd@continuenarration{% + \endgroup + \gmd@countnarrationline% see \gmiflink[countnarr]{below}. + \expandafter\@trimandstore\the\everypar\@trimandstore + \everypar=\expandafter{\expandafter\@codetonarrskip\the\everypar}% + \expandafter\gmd@checkifEOL\@gobble} +% Simple, isn't it? (We gobble the `other' code delimiter. Despite of +% |\egroup| it's \catother\ because it was touched by |\futurelet| +% contained in |\@ifnextchar| in line \ref{ifContNarr}. And in line +% \ref{ContNarr2} it's been read as \catother. That's why it +% works in spite of that |%| is of category `ignored'.) + +%\gmhypertarget[countnarr]{Whether} we count the narration lines +% depends on the option |countalllines| which is off by default. +% \CodeDefIndex\gmd@countnarrationline +\if@countalllines + \def\gmd@countnarrationline{% + \if@newline + \grefstepcounter{codelinenum}\@newlinegfalse% the + % |\grefstepcounter| macro, defined in \pk{gmverb}, is a~global + % version of |\refstepcounter|, observing the redefinition made + % to |\refstepcounter| by \pk{hyperref}. + \everypar=\expandafter{% + \expandafter\@codetonarrskip\the\gmd@preverypar}%^^A + % the \cs{hy\+p\+er\+lab\+el\+@\+li\+ne} macro puts + % a~hypertarget in a~|\raise| i.e., drives \TeX\ into the + % horizontal mode so |\everypar| shall be issued. Therefore we + % should restore it. + \hyperlabel@line + {\LineNumFont\thecodelinenum}\,\ignorespaces + \fi}% \CodeDefIndex\gmd@countnarrationline +\else + \@emptify\gmd@countnarrationline% +\fi + +% And typesetting the \TeX\ code? +\begingroup\catcode`\^^M=\active% +\firstofone{\endgroup% \CodeDefIndex\gmd@typesettexcode + \def\gmd@typesettexcode{% + \gmd@parfixclosingspace% it's to eat a~space closing the + % paragraph, see \gmiflink[closingspace]{below}. It contains + % |\par|. + % + % A~verbatim group has already been opened by \cs{ttverb\+at\+im} and + % additional |\catcode|. + \everypar={\@@settexcodehangi}% At first attempt we thought + % of giving the user a~|\toks| list to insert at the beginning of + % every code line, but what for? + % \CodeDefine*{^^M}^^A + \def^^M{% + \@newlinegtrue% to |\refstep| the counter in proper place. + \@dsdirgtrue% to handle the \ds\ directives. + \global\gmd@closingspacewd=\z@% \label{noclosingspace}we + % don't wish to eat a~closing space after a~codeline, 'cause + % there isn't any and a~negative rigid |\hskip| added to + % |\parfillskip| would produce a~blank line. + \ifhmode\par\@codeskipputgfalse\else% + \if@codeskipput% + \else\addvspace{\stanzaskip}\@codeskipputgtrue% + \fi% if we've just met a~blank (code) line, we insert + % a~|\stanzaskip| glue. + % \label{codeskip} + \fi% + \prevhmodegfalse% we want to know later that now we are in the + % vmode. + \@ifnextchar{\gmd@texcodespace}{% + \@dsdirgfalse\gmd@dolspaces}{\gmd@charbychar}% + }% end of |^^M|'s definition.\label{debug!2} + % \CodeDefIndex\gmd@texcodeEOL + \let\gmd@texcodeEOL=^^M% for further checks inside |\gmd@charbychar|. + \raggedright\leftskip=\CodeIndent% + \if@aftercode\gmd@nocodeskip1{iaC}\else\if@afternarr% + % ^^A~\def^^C{\showthe\hyphenpenalty\showthe\rightskip} + \if@codeskipput\else\gmd@codeskip1\@codeskipputgtrue\@aftercodegfalse\fi% + % \label{codeskip3} + \else\gmd@nocodeskip1{naN}\fi\fi% if now we are + % switching from the narration into the code, we insert a~proper + % vertical space. + \@aftercodegtrue\@afternarrgfalse% + \ifdim\gmd@ldspaceswd>\z@% and here the leading spaces. + \leavevmode\@dsdirgfalse% + \if@newline\grefstepcounter{codelinenum}\@newlinegfalse% + \fi% + \printlinenumber% if we don't want the lines to be numbered, + % the respective option \nlpercent|\let|s this CS to |\relax|. + \hyperlabel@line% + \mark@envir% index and/or marginize an environment if there is + % some to be done so, see line \ref{mark@envir}. + \hskip\gmd@ldspaceswd% + \advance\hangindent by\gmd@ldspaceswd% + \xdef\settexcodehangi{% + \noexpand\hangindent=\the\hangindent% and also set the + % hanging indent setting for the same line comment case. BTW., + % this |%| or rather lack of it costed me five hours of + % debugging and rewriting. Active lineends require extreme + % caution. + \noexpand\hangafter=1\space}%^^A~\noexpand\relax + \else% + \glet\settexcodehangi=\@@settexcodehangi%\\ + %|%| |\printlinenumber| here produced line numbers for blank lines + % which is what we don't want. + \fi% of |\ifdim| + \gmd@ldspaceswd=\z@% + \prevhmodegfalse% we have done |\par| so we are not in the + % hmode. + \@aftercodegtrue% we want to know later that now we are + % typesetting a~codeline. + \gmd@charbychar% we'll eat the code char by char to scan all the + % macros and thus to deal properly with the case |\%| in which the + % |%| will be scanned and won't + % launch closing of the verbatim group. + }% +}% end of |\gmd@typesettexcode|'s definitions's group's |\firstofone|. +% +% \stanza +% +% Now let's deal with the leading spaces once forever. We wish not to +% typeset | |s but to add the width of every leading space to the +% paragraph's indent and to the hanging indent, but only if there'll +% be any code character not being |%| in this line (e.g., the end of +% line). If there'll be only |%|, we want just to continue the comment +% or start a~new one. (We don't have to worry about whether we should +% |\par| or not.) +% \CodeDefIndex\gmd@spacewd +\newlength\gmd@spacewd% to store the width of a~(leading) +% | |\catother. +% \CodeDefIndex\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 +% |\breakabletwelvespace|. +% So let us |\let| for future: +% \CodeDefIndex\gmd@texcodespace +\let\gmd@texcodespace=\breakabletwelvespace +% And now let's try to deal with those spaces. +% \CodeDefIndex\gmd@dolspaces +\def\gmd@dolspaces{% + \ifx\gmd@texcodespace\@let@token + \@dsdirgfalse + \afterelsefi\settowidth{\gmd@spacewd}{\twelvespace}% + \gmd@ldspaceswd=\z@ + \gmd@eatlspace% + \else\afterfi% about this smart macro and other of its family see + % \pk{gmutils} sec.\,3. + \par\gmd@typesettexcode + \fi} + +% And now, the iterating inner macro that'll eat the leading spaces. +% \CodeDefIndex\gmd@eatlspace +\def\gmd@eatlspace#1{% + \ifx\gmd@texcodespace#1% + \advance\gmd@ldspaceswd by\gmd@spacewd% we don't + % |\advance| it |\global|ly 'cause the current group may be closed + % iff we meet |%| and then we'll won't indent the line anyway. + \afterelseiffifi\gmd@eatlspace + \else + \if\code@delim\noexpand#1% + \gmd@ldspaceswd=\z@ + \gmd@continuenarration#1%\label{ContNarr2} + \else \afterfifi\gmd@typesettexcode#1% + \fi + \fi}% + +% We want to know whether we were in hmode before reading current +% |\code@delim|. We'll need to switch the switch globally. +% +% \CodeDefine\ifprevhmode \CodeDefine*\prevhmodegtrue +% \CodeDefine*\prevhmodegfalse +\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. +% \CodeDefine*\gmd@charbychar +\newcommand*\gmd@charbychar[1]{% + \ifhmode\prevhmodegtrue + \else\prevhmodegfalse\fi + \if\code@delim\noexpand#1% + \afterelseiffifi\gmd@percenthack% to typeset |%| if a~comment + % continues the~codeline. + \endgroup% + \gmd@checkifEOLmixd% to see if next is |^^M| and then do |\par|. + \else% i.e., we've not met the code delimiter + \if\code@escape@char\noexpand#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. + \afterelsefifi\gmd@counttheline#1\scan@macro + \else + \afterfifi\gmd@EOLorcharbychar#1% + \fi + \fi} + +% One more inner macro because |^^M| in \TeX\ code wants to peek at the +% next char and possibly launch |\gmd@charbychar|. We deal with +% counting the lines thorougly. Increasing the counter is divided into +% cases and it's very low level in one case because |\refstepcounter| and +% |\stepcounter| added some stuff that caused blank lines, at +% least with \pk {hyperref} package loaded. +% \CodeDefIndex\gmd@EOLorcharbychar +\def\gmd@EOLorcharbychar#1{% + \ifx\gmd@texcodeEOL#1% + \if@newline + \if@countalllines\global\advance\c@codelinenum by\@ne + \@newlinegfalse\fi + \fi + \afterelsefi#1%\label{printhashone1}here we print |#1|. + \else% i.e., |#1| is \emph{not} a~(very active) line end, + \afterfi + \gmd@counttheline#1\gmd@charbychar% \label{printhashone2}or here + % we print |#1|. Here we would also possibly mark an environment + % but there's no need of it because declaring an environment to + % be marked requires a~bit of commentary and here we are after + % a~code |^^M| with no commentary. + \fi} + +% \CodeDefIndex\gmd@counttheline +\def\gmd@counttheline{% + \ifvmode + \if@newline + \grefstepcounter{codelinenum}\@newlinegfalse + \hyperlabel@line + \fi + \printlinenumber + \mark@envir + \else + \if@newline + \grefstepcounter{codelinenum}\@newlinegfalse + \hyperlabel@line + \fi + \fi} + +% If before reading current |%| char we were in horizontal mode, then +% we wish to print |%| (or another code delimiter). +% \CodeDefIndex\gmd@percenthack +\def\gmd@percenthack{% + \ifprevhmode\code@delim\aftergroup\space% We add a~space after |%|, + % 'cause I~think it looks better. It's done |\aftergroup| to make + % the spaces possible after the |%| not to be + % typeset. + \else\aftergroup\gmd@narrcheckifds@ne% remember that + % \cs{gmd\-@\-pre\-cent\-hack} is only called when we've the code + % delimiter and soon we'll close the verbatim group and right after + % |\endgroup| there waits |\gmd@checkifEOLmixd|. + \fi} + +\def\gmd@narrcheckifds@ne#1{%^^A\typeout{narr@ne if ds \on@line}% + \@dsdirgfalse\@ifnextchar<{% + \expandafter\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. +% \CodeDefIndex\gmd@checkifEOL +\def\gmd@checkifEOL{% + \gmd@countnarrationline + \everypar=\expandafter{\expandafter\@codetonarrskip% we add the + % macro that'll insert a~vertical space if we leave the code and + % enter the narration. + \the\gmd@preverypar}% + \@ifnextchar{\gmd@textEOL}{% + \@dsdirgfalse\par\ignorespaces}{\gmd@narrcheckifds}}% + +% We check if it's |%<|, a~\ds\ directive that is. +\def\gmd@narrcheckifds{%^^A\typeout{narr if ds \on@line}% + \@dsdirgfalse\@ifnextchar<{% + \expandafter\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. +% \CodeDefIndex\gmd@checkifEOLmixd +\def\gmd@checkifEOLmixd{% + \gmd@countnarrationline + \everypar=\expandafter{\expandafter\@codetonarrskip\the\gmd@preverypar}% + % + % \label{longlinethatshouldbebroken} + \@afternarrgfalse\@aftercodegtrue + \ifhmode\@codeskipputgfalse\fi + \@ifnextchar{\gmd@textEOL}{% + {\raggedright\gmd@endpe\par}% without |\raggedright| this |\par| + % would be justified which is not appropriate for a~long codeline + % that should be broken, e.g., \ref{longlinethatshouldbebroken}. + \prevhmodegfalse + \gmd@endpe\ignorespaces}{% + % If a~codeline ends with |%| + % (|prevhmode|${}=={}$True) first |\gmd@endpe| sets the parameters + % at the \TeX\ code values and |\par| closes a~paragraph and the + % latter |\gmd@endpe| sets the parameters at the narration values. + % In the other case both |\gmd@endpe|s do the same + % and |\par| between them does nothing. + % \CodeDefIndex\par + \def\par{% + \ifhmode% (I~added this |\ifhmode| as a~result of a~heavy + % debug.) +%^^A \typeout{par of 1766 in hmode \on@line}% + \@@par + \if@afternarr + \if@aftercode + \if@codeskipput\else\gmd@codeskip2\@aftercodegfalse\@codeskipputgtrue\fi + %\label{codeskip4} + \else\gmd@nocodeskip2{naC}% + \fi + \else\gmd@nocodeskip2{naN}% + \fi + \prevhmodegfalse\gmd@endpe% when taken out of |\ifhmode|, this + % line caused some codeline numbers were typeset with + % |\leftskip|${}=0$. + \everypar=\expandafter{% + \expandafter\@codetonarrskip\the\gmd@preverypar}% + \let\par\@@par% +%^^A else +%^^A \typeout{par of 1766 in NOT hmode \on@line}% + \fi}% + \gmd@endpe\ignorespaces}} + +% As we announced, we play with |\leftskip| inside the verbatim +% group and therefore we wish to restore normal |\leftskip| when back to +% normal text i.e.\ the commentary. But, if normal text starts in the +% same line as the code, then we still wish to indent such a~line. +% \CodeDefIndex\gmd@endpe +\def\gmd@endpe{% + \ifprevhmode + \settexcodehangi%\unskip ndent + \leftskip=\CodeIndent +%^^A \typeout{gmd@endpe in prevhmode \on@line}% + \else + \leftskip=\TextIndent + \hangindent=\z@ + \everypar=\expandafter{% + \expandafter\@codetonarrskip\the\gmd@preverypar}% +%^^A \typeout{gmd@endpe in not prevhmode \on@line}% + \fi} + +% +% +% \subdivision{Numbering (or Not) of the Lines} +% +% Maybe you want codelines to be numbered and maybe you want to +% reset the counter within sections. +\if@uresetlinecount% with |uresetlinecount| option\dots + \@relaxen\gmd@resetlinecount% \dots\ we turn + % resetting the counter by \cs{Doc\+In\+put} off\dots + \newcommand*\resetlinecountwith[1]{% + % \CodeDefIndex*\c@codelinenum + \newcounter{codelinenum}[#1]}% \dots\ and provide a~new + % declaration of the counter. +\else% With the option turned off\dots \CodeDefine*{DocInputsCount} + \newcounter{DocInputsCount}% \CodeDefine*{codelinenum} + \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}} + % \CodeDefine\gmd@resetlinecount + \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. +% \CodeDefIndex\printlinenumber +\newcommand*\printlinenumber{% + \leavevmode\llap{\rlap{\LineNumFont$\phantom{999}$\llap{\thecodelinenum}}% + \hskip\leftskip}} +% \CodeDefine\LineNumFont +\def\LineNumFont{\normalfont\tiny} + +\if@linesnotnum\@relaxen\printlinenumber\fi +% \CodeDefIndex\hyperlabel@line +\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. \CodeDefIndex\gmd@codeskip +\newcommand*\gmd@codeskip[1]{\@@par\addvspace\CodeTopsep\@codeskipputgtrue} +%\label{codeskip2} + +% Sometimes we add the |\CodeTopsep| vertical space in +% |\everypar|. When this happens, first we remove the |\parindent| +% empty box, but this doesn't reverse putting |\parskip| to the main +% vertical list. And if |\parskip| is put, |\addvspace| shall see it +% not the `true' last skip. \Describe*{@codeskipput}Therefore we need +% a~Boolean switch to keep the knowledge of putting similar vskip +% before |\parskip|. +% \CodeDefine\if@codeskipput \CodeDefIndex*\@codeskipputgtrue +% \CodeDefIndex*\@codeskipputgfalse \CodeDefIndex*{@codeskipput} +\newgif\if@codeskipput + +% The below is another relic of the heavy debug of the automatic +% vspacing. Let's give it the same removal clause as +% \gmiflink[relic parameter]{above}. +% \CodeDefIndex\gmd@nocodeskip +\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. +% \CodeDefine\if@aftercode \CodeDefine*\@aftercodegtrue +% \CodeDefine*\@aftercodegfalse +\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. +% \CodeDefine\if@afternarr \CodeDefine*\@afternarrgtrue +% \CodeDefine*\@afternarrgfalse +\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. +% \CodeDefine\@codetonarrskip +\long\def\@codetonarrskip{% + \if@codeskipput\else + \if@afternarr\gmd@nocodeskip4{iaN}\else + \if@aftercode +% We are at the beginning of |\everypar|, i.e., \TeX\ has just entered +% the hmode and put the |\parindent| box. Let's remove it then. + {\setbox0=\lastbox}% +% Now we can put the vertical space and state we are not `aftercode'. + \gmd@codeskip4\@codeskipputgtrue + %\label{codeskip5} + \leftskip\TextIndent% this line is a~patch against + % a~bug-or-feature that in certain cases the narration |\leftskip| + % is left equal the code leftskip. (It happens when there're + % subsequent code lines after an inline comment not ended with + % an explicit |\par|.) + \else\gmd@nocodeskip4{naC}% + \fi% + \fi + \fi\@aftercodegfalse} + +% But we play with |\everypar| for other reasons too, and while restoring it, +% we don't want to add the |\@codetonarrskip| macro infinitely many +% times. So let us define a~macro that'll check if |\everypar| begins +% with |\@codetonarrskip| and trim it if so. We'll use this macro with +% proper |\expandafter|ing in order to give it the contents of +% |\everypar|. The work should be done in two steps first of which +% will be checking whether |\everypar| is nonempty (we can't have two +% delimited parameters for a~macro: if we define a~two-parameter +% macro, the first is undelimited so it has to be nonempty; it costed +% me some one hour to understand it). +% \CodeDefine\@trimandstore +% \CodeDefIndex\@trimandstore@hash +\long\def\@trimandstore#1\@trimandstore{% + \def\@trimandstore@hash{#1}% + \ifx\@trimandstore@hash\@empty% we check if |#1| is + % nonempty. The |\if|\nlpercent*|\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\expandafter\@trimandstore@ne\the\everypar\@trimandstore + \fi} + +% \CodeDefIndex\@trimandstore@ne +\long\def\@trimandstore@ne#1#2\@trimandstore{%\label{@trimandstore} + \def\trimmed@everypar{#2}% + \ifx\@codetonarrskip#1% + \gmd@preverypar=\expandafter{\trimmed@everypar}% + \else + \gmd@preverypar=\expandafter{\the\everypar}% + \fi} +% We prefer not to repeat |#1| and |#2| within the |\if|s and we even +% define an auxiliary macro because |\everypar| may contain some +% |\if|s or |\fi|s. +% +% +% \subdivision[Life Among Queer EOLs]{Life Among Queer \gmhypertarget[afc]{EOLs}} +% +% When I~showed this package to my \TeX\ Guru he commended it and +% immediately pointed some disadvantages in the comparison with the +% \docfm\ package. +% +% One of them was an expected difficulty of breaking a~moving argument +% (e.g., of a~sectioning macro) in two lines. To work it around let's +% define a~line-end eater: +\catcode`\^^B=\active% note we re|\catcode| \ globally, for the +% entire document. +\bgroup\catcode`\^^M=\active% +\firstofone{\egroup% \CodeDefIndex\QueerCharTwo \CodeDefine*{^^B} + \def\QueerCharTwo{\long\def^^B##1^^M{\ignorespaces}}} + +\QueerCharTwo + +\AtBegInput{\@ifQueerEOL{\catcode`\^^B\active}{}\QueerCharTwo}% \label{QCh2} +% We repeat redefinition of \ at begin of the documenting +% input, because \pk{doc.dtx} suggests that some packages (namely +% \pk{inputenc}) may re|\catcode| such unusual characters. +% +% \changes{v0.98d}{06/9/11}{re\cs{catcode}ing and defining +% \cs{char1} and \cs{char2} added atto begin doc input} +% +% \stanza +% As you see the |^^B| active char is defined to gobble everything +% since itself till the end of line and the very end of line. This is +% intended for harmless continuing a~line. The price is affecting the +% line numbering when |countalllines| option is enabled. +% +% I~also liked the \docfm's idea of comment${}^2$ i.e., the +% possibility of marking some text so that it doesn't appear nor in the +% working version neither in the documentation, got by making +% |^^A| (i.e., \) a~comment char. +% +% However, in this package such a~trick would work another way: here +% the line ends are active, a~comment char would disable them and that +% would cause disasters. So let's do it an |\active| way. +\catcode`\^^A=\active% note we re|\catcode| \ globally, for the +% entire document. +\bgroup\catcode`\^^M=\active% +\firstofone{\egroup% \CodeDefIndex\QueerCharOne \CodeDefine*{^^A} + \def\QueerCharOne{\long\def^^A##1^^M{\ignorespaces^^M}}} + +\QueerCharOne + +\AtBegInput{\@ifQueerEOL{\catcode`\^^A\active}\QueerCharOne}% see note +% after line \ref{QCh2}. + + +% As I~suggested in the users' guide, |\StraightEOL| and |\QueerEOL| are +% intended to cooperate in harmony for the user's good. They take care +% not only of redefining the line end but also these little things +% related to it. +% +% One usefulness of |\StraightEOL| is allowing linebreaking of the +% command arguments. Another making possible executing some code lines +% during the documentation pass. +% +% \changes{v0.98b}{06/09/07}{\cs{QueerM} and \cs{StraightM} renamed +% to \cs{QueerEOL} and \cs{StraightEOL} and other (internal) macros +% ending with \cs[]{M}} +% \CodeDefine\StraightEOL +\def\StraightEOL{%\label{StraightEOL} + \catcode`\^^M=5\relax + \catcode`\^^A=14\relax + \catcode`\^^B=14\relax + \def\^^M{\ }} + +% \CodeDefine\QueerEOL +\def\QueerEOL{%\label{QueerEOL} + \catcode`\^^M=\active + \catcode`\^^A=\active + \catcode`\^^B=\active% I~only re|\catcode| \ and \ + % hoping no one but me is \emph{that} perverse to make them + % |\active| and (re)define. (Let me know if I'm wrong at this point.) + \let\^^M=\gmd@bslashEOL} + +% \iffalse +% They won't work in \verb+|verbatim|+ scopes but the clubs redefine +% the active lineend to be a~breakable (and visible) space, so +% breaking a~`clubbed' text in two lines will not cause a~disaster but +% you get e.g., |...^^B %...|. +% \fi + +% \gmhypertarget[closingspace]{To make} |^^M| behave more like a~`normal' +% lineend I~command it to add a~| |${}\subs{10}$ at first. It works +% but has one uwelcome feature: if the line has nearly |\textwidth|, +% this closing space may cause line breaking and setting a~blank line. +% To fix this I~|\advance| the |\parfillskip|: +% \CodeDefIndex\gmd@parfixclosingspace +\def\gmd@parfixclosingspace{{% + \advance\parfillskip by-\gmd@closingspacewd\par}} +% We'll put it in a~group surrounding |\par| but we need to check if +% this |\par| is executed after narration or after the code, +% i.e., whether the closing space was added or not. +% \CodeDefIndex\gmd@closingspacewd +% \CodeDefIndex\gmd@setclosingspacewd +\newskip\gmd@closingspacewd +\newcommand*\gmd@setclosingspacewd{% + \global\gmd@closingspacewd=\fontdimen2\font% + plus\fontdimen3\font minus\fontdimen4\font\relax} +% +% See also line \ref{noclosingspace} to see what we do in the codeline +% case when no closing space is added. + +% And one more detail: +\bgroup\catcode`\^^M=\active% +\firstofone{\egroup% \CodeDefIndex*{\^^M} + \def\^^M{\ \expandafter\ignorespaces^^M}} +% To make |\^^M| behave properly. If this definition was ommitted, it +% 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. +% \CodeDefIndex\gmd@bslashEOL +\let\gmd@bslashEOL=\^^M +% 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: +% \CodeDefIndex\@verbatim +\gaddtomacro\@verbatim{\leftskip=\CodeIndent} + +% And a~one more little definition to accomodate |\verb| and pals for the +% lines commented out. +% \CodeDefIndex\check@percent +\AtBegInput{\long\def\check@percent#1{% + \expandafter\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. +% \CodeDefine\AddtoPrivateOthers +\def\AddtoPrivateOthers#1{% + \expandafter\def\expandafter\doprivateothers\expandafter{% + \doprivateothers\do#1}}% + +% We also redefine an internal |\verb|'s macro |\gm@verb@eol| to put a~proper +% line end if a~line end char is met in a~short verbatim: we have to +% check if we are in `queer' or `straight' EOLs area. +\begingroup +\obeylines% \CodeDefIndex\gm@verb@eol +\AtBegInput{\def\gm@verb@eol{\obeylines% + \def^^M{\verb@egroup\@latex@error{% + \noexpand\verb ended by end of line}% + \@ifQueerEOL{\gmd@textEOL}{\@ehc}}}}% +\endgroup + +% \subdivision{Macros for Marking The Macros} +% +% A~great inspiration for this part was the \docfm\ package again. +% I~take some macros from it, and some tasks I~solve a~different way, +% e.g., the |\| (or another escapechar) is not active, because anyway +% all the chars of code are scanned one by one. And exclusions from +% indexing are supported not with a~list stored as |\toks| register +% but with separate control sequences for each excluded CS. +% +% \stanza +% +% The \docfm\ package shows a~very general approach to the indexing +% issue. It assumes using a~special MakeIndex style and doesn't use +% explicit MakeIndex controls but provides specific macros to hide +% them. But here in \pk{gmdoc} we prefer no special style for the +% index. + +% \CodeDefine\actualchar \CodeDefine\quotechar \CodeDefine\encapchar +% \CodeDefine\levelchar +% \changes[\actualchar]{v0.98e}{06/09/23}{a~bug fix: making the +% \cs[]{@} \protect\catother\space again} +\edef\actualchar{\string @} +\def\quotechar{"} +\edef\encapchar{\twelveclub} +\def\levelchar{!} +% 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}|. +% +% +% \CodeDefine\CodeEscapeChar \CodeDefine\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 +% the~|\|\ 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} + % \CodeDefine\MakePrivateLetters + \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. +% \CodeDefine\MakePrivateOthers +\def\MakePrivateOthers{\let\do=\@makeother \doprivateothers} +% This macro we use 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: +% \CodeDefine\doprivateothers +\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. +% \CodeDefine\scan@macro +\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\noexpand#1% + \quote@char#1% + \xdef\macro@iname{\maybe@quote#1}% global for symmetry with + % line \ref{x123}. + \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. + \afterelsefi\@ifnextcat{a}{\continue@macroscan}{\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{x123} + \quote@char#1% + \xdef\macro@iname{\maybe@quote\macro@iname}% + \xdef\macro@pname{\xiistring#1}%\label{stringing1} + \afterfi \finish@macroscan + \fi} +% This is the end\dots\ beautiful friend, the end\dots\ of +% |\scan@macro|'s |\def| the end\dots\ +% The |\xiistring| macro, provided by \pk{gmutils}, is used instead of +% original |\string| because we wish to get the space \catother. +% +% \stanza +% Now, let's explain some details, i.e., let's define them. We call +% the following macro having known |#1| to be \catletter. +% \CodeDefIndex\continue@macroscan +\def\continue@macroscan#1{% + \quote@char#1% + \xdef\macro@iname{\macro@iname \maybe@quote#1}% + \xdef\macro@pname{\macro@pname \string#1}%\label{stringing2} + \@ifnextcat{a}{\continue@macroscan}{\finish@macroscan}% +} +% The |\@ifnextcat| macro is defined analogously to |\@ifnextchar| but +% the test done by it is not |\ifx| but |\ifcat|. +% \CodeDefIndex\quote@char +\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{% + \@ifismember 9\of \indexcontrols\glet\maybe@quote\quotechar% + \else\g@emptify\maybe@quote% + \fi}% + }} + +% 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. +% \CodeDefine\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}} + % \CodeDefine\@ifismember + \long\def \@ifismember#1\of#2{% + \long\def\in@@##1#1##2\in@@{% + \if\noexpand^^A##2\noexpand^^A\afterelsefi\gmd@@iffalse + \else\afterfi\gmd@@iftrue + \fi}% + \expandafter\in@@#2#1\in@@}% + +% To hide the Booleans from \TeX\ in some contexts define +% \CodeDefine\gmd@@iftrue \CodeDefine\gmd@@iffalse +\def\gmd@@iftrue{\iftrue} +\def\gmd@@iffalse{\iffalse} +% A~try to |\let| instead of |\def| resulted with the `incomplete if' +% error: \TeX\ looks at the meanings not the names while counting +% |\if|s. + +% A~word of commentary. \docfm\ in another situation solves the +% problem of checking similar way, but a~little more complexely. On +% the other hand, \docfm 's solution is more general: here a~trouble +% may arise if the list begins with |^^A|. It seems little possible to +% me, though. Btw., this macro is used only for catching chars that are +% MakeIndex's controls so far. 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 thus the |\@ifismember| macro gets +% |\quote@char|'s |#1| `other'ed as the first argument. +% +% |\@ifismember| is defined to take two parameters separated by |\of|. +% In |\quote@char| the second argument for it is |\indexcontrols| +% defined as the (expanded) sequence of the MakeIndex controls. +% |\@ifismember| defines its inner macro |\in@@| to take two +% parameters separated by the first and the second |\@ifismember|'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. |\in@@| is put before +% a~string consisting of |\@ifismember|'s second and first parameters +% (in such a~reversed order) and |\in@@| itself. In such a~sequence it +% looks for something fitting its parameter pattern. |\in@@| is sure +% to find the parameters delimiter (|\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 |\in@@|. What |\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 |\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. + +% \CodeDefIndex\finish@macroscan +\newcommand*\finish@macroscan{%\par + % We have the macro'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% it's important that |\verbatimchar| comes before the macro's + % name: when it was reverse, the |\tt| CS turned this test true + % and left the |\verbatimchar| what resulted with `|\+tt|' + % typeset. Note that this test should turn true iff the scanned + % macro name shows to be the default |\verb|'s delimiter. In such + % a~case we give |\verb| another delimiter, namely |$|: + \def\im@firstpar{[$]}%^^A$ + \else\def\im@firstpar{}\fi + \expandafter \index@macro\im@firstpar\macro@iname\macro@pname + \maybe@marginpar\macro@pname + \macro@pname + \gmd@charbychar +} + +% 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. +% \CodeDefIndex\maybe@marginpar +\def\maybe@marginpar#1{% + %^^A\ifx#1\mname@tomarginpar + \@ifundefined{gmd/2marpar/#1}{}{% + \expandafter\Text@Marginize\expandafter{\bslash#1}% |\expandafter|s + % \possfil'cause the |\Text@Marginize| command applies |\string| to its + % argument. \nlpercent |\macro@pname|, which will be the only possible + % argument to + % \cs{may\+be\+@mar\+g\+in\+par}, + % contains the macro's name + % without the escapechar so we added it here. + % ^^A\gdef\mname@tomarginpar{} + \expandafter\g@relaxen\csname gmd/2marpar/#1\endcsname% we reset the switch. + }} + +% 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})} +% \CodeDefine\index@macro +\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\IndexRefCs{gmdindexpagecs{\HLPrefix}{\kind@fentry}{\EntryPrefix}}% + \else + \edef\IndexRefCs{gmdindexrefcs{\HLPrefix}{\kind@fentry}{\EntryPrefix}}% + \fi + \edef\@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\IndexRefCs}% + \expandafter\special@index\expandafter{\@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. + }} + +%\CodeDefine\un@defentryze \CodeDefine\un@usgentryze +\def\un@defentryze#1{% + \expandafter\g@relaxen\csname gmd/defentry/#1\endcsname + \g@relaxen\last@defmark}% we care to clear the last definition +% marker checked by |\changes|. +\def\un@usgentryze#1{% + \expandafter\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: +% \CodeDefine\if@pageinclindex \CodeDefine*\@pageinclindextrue +% \CodeDefine*\@pageinclindexfalse +\newif\if@pageinclindex + +% \CodeDefine\quoted@eschar +\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{|\|!}| for instance and it will work +% as main level index entry and |\def\HLPrefix{|\|}| +% 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. + \let\gmdindexpagecs=\gmdindexrefcs + \else +% \CodeDefIndex\gmdindexrefcs +% \CodeDefIndex\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 \CodeDefIndex\gmd@revprefix + \def\gmd@revprefix#1{% + \def\@tempa{#1}% + \ifx\@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 + % 'cause during the authomatic |\hypertarget|ing the lines are labeled + % |clnum.|\. 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. +% \CodeDefine\DefEntry \CodeDefine\UsgEntry +\def\DefEntry#1{\underline{#1}} +\def\UsgEntry#1{\textit{#1}} +% The third option will be just |\relax| by default: +% \CodeDefine\CommonEntryCmd +\def\CommonEntryCmd{relax} +% In line \ref{CECmd} it's |\edef|ed to allow an `unm\"oglich' +% 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 (|\SelfInclude|d) driver file to be `usage', see codeline +% \ref{UsgHack} of \file{gmdocDoc.tex}. + +% 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. +% +% But first let's make a~version of |\@ifstar| that would work with +% |*|\catletter. It's analogous to |\@ifstar|. +% \CodeDefine\@ifstarl +\bgroup\catcode`\*=11 % +\firstofone{\egroup + \def\@ifstarl#1{\@ifnextchar *{\@firstoftwo{#1}}}} + +% Now we are ready to define a~couple of commands. % The |*| versions of +% them are for marking environments and \emph{implicit} CSs. + +% \CodeDefine\CodeDefIndex +% \CodeDefine*\CodeDefIndex* +\outer\def\CodeDefIndex{\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}} +%\CodeDefIndex\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. + \global\@defentryze{#1}}} +% \label{stringamacro} + +% \CodeDefIndex\Code@DefIndexStar +\long\def\Code@DefIndexStar#1{% + \endgroup + \addto@estoindex{#1}% + \@defentryze{#1}} + +% \CodeDefine\gmd@justadot +\def\gmd@justadot{.} + +%\CodeDefine\@defentryze \CodeDefine\@usgentryze +\long\def\@defentryze#1{% + \expandafter\let\csname gmd/defentry/\string#1\endcsname\gmd@justadot% The + % \LaTeX\ |\@namedef| macro could not be used since it's not `long'. + % \CodeDefine\last@defmark + \xdef\last@defmark{\string#1}}% we |\string| the argument 'cause it's +% a~control sequence most probably. +\long\def\@usgentryze#1{% + \expandafter\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: +%\CodeDefine\CodeUsgIndex +%\CodeDefine*\CodeUsgIndex* +\outer\def\CodeUsgIndex{\begingroup + \MakePrivateLetters + \@ifstarl{\MakePrivateOthers\Code@UsgIndexStar}{\Code@UsgIndex}} +% The |*| possibility is for marking environments etc. +% \CodeDefIndex\Code@UsgIndex +\long\def\Code@UsgIndex#1{\endgroup{% + \escapechar\m@ne + \global\@usgentryze{#1}}} + +% \CodeDefIndex\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: +% \CodeDefine\CodeCommonIndex +% \CodeDefine\CodeCommonIndex* +\outer\def\CodeCommonIndex{\begingroup + \MakePrivateLetters + \@ifstarl{\MakePrivateOthers\Code@CommonIndexStar}{\Code@CommonIndex}} + +% \CodeDefIndex\Code@CommonIndex +\long\def\Code@CommonIndex#1{\endgroup} + +% \CodeDefIndex\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. +% \CodeDefine\text@indexmacro +\long\def\text@indexmacro#1{% + {\escapechar\m@ne \xdef\macro@pname{\xiistring#1}}% + \expandafter\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}. + \expandafter \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|. +% \CodeDefine\quote@mname +\def\quote@mname{% + \def\macro@iname{}% + \quote@charbychar} + +% \CodeDefIndex\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 \maybe@quote#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. +% \CodeDefine\TextUsgIndex +% \CodeDefine*\TextUsgIndex* +\def\TextUsgIndex{\begingroup + \MakePrivateLetters + \@ifstarl{\MakePrivateOthers\Text@UsgIndexStar}{\Text@UsgIndex}} + +% \CodeDefIndex\Text@UsgIndex +\long\def\Text@UsgIndex#1{% + \endgroup\@usgentryze#1% + \text@indexmacro#1} + +% \CodeDefIndex\Text@UsgIndexStar +\long\def\Text@UsgIndexStar#1{\endgroup\@usgentryze{#1}% + \text@indexenvir{#1}} + +% \CodeDefine\text@indexenvir +\long\def \text@indexenvir#1{% + \edef\macro@pname{\xiistring#1}% + \if\bslash\expandafter\@firstofmany\macro@pname\@@nil% if + % |\string|ed |#1| begins with a~backslash, we will gobble it + % to make MakeIndex not see it. + \edef\@tempa{\expandafter\@gobble\macro@pname}% + \@tempswatrue + \else + \let\@tempa\macro@pname + \@tempswafalse + \fi + \expandafter\quote@mname\@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 expansion 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}} + +% \CodeDefine\TextCommonIndex +% \CodeDefine*\TextCommonIndex* +\def\TextCommonIndex{\begingroup + \MakePrivateLetters + \@ifstarl{\MakePrivateOthers\Text@CommonIndexStar}{\Text@CommonIndex}} + +%\CodeDefIndex\Text@CommonIndex +\long\def\Text@CommonIndex#1{\endgroup + \text@indexmacro#1} + +% \CodeDefIndex\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: +% \CodeDefine\CodeMarginize +% \CodeDefine*\CodeMarginize* +\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. +% \CodeDefIndex\egCode@MarginizeMacro +\long\def\egCode@MarginizeMacro#1{\endgroup + \Code@MarginizeMacro#1} + +% \CodeDefIndex\Code@MarginizeMacro +\long\def\Code@MarginizeMacro#1{{\escapechar\m@ne + \expandafter\glet\csname gmd/2marpar/\string#1\endcsname\gmd@justadot +%^^A \xdef\mname@tomarginpar{\xiistring#1} + }} + +% \CodeDefIndex\egCode@MarginizeEnvir +\long\def\egCode@MarginizeEnvir#1{\endgroup + \Code@MarginizeEnvir{#1}} + +% \CodeDefIndex\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: +% \CodeDefine\mark@envir +\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 + \def\do##1{% the |\envirs@toindex| list contains |\string|ed + % macros or environments' names in braces and each preceded + % with |\do|. + \if\bslash\@firstofmany##1\@@nil% if + % |##1| begins with a~backslash, we will gobble it for + % MakeIndex not see it. + \edef\@tempa{\@gobble##1}% + \@tempswatrue + \else + \edef\@tempa{##1}\@tempswafalse + \fi + \expandafter\quote@mname\@tempa\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}}}% + \envirs@toindex + \g@emptify\envirs@toindex% + \fi} + +% 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. +% \CodeDefine\CodeDefine +% \CodeDefine*\CodeDefine* +\outer\def\CodeDefine{\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}} + +% \CodeDefine\CodeUsage +% \CodeDefine*\CodeUsage* +\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. +% \CodeDefIndex\Code@DefMacro +\long\def\Code@DefMacro#1{% + \Code@DefIndex#1% we use the internal macro; it'll close the group. + \Code@MarginizeMacro#1} + +% \CodeDefIndex\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. +% \CodeDefIndex\codeline@wrindex +\def\codeline@wrindex#1{\if@filesw + \immediate\write\@indexfile + {\string\indexentry{#1}% + {\HLPrefix\number\c@codelinenum}}\fi} + +% We initialize it due to the option (or lack of the option): +\AtBeginDocument{% + \if@pageindex + \let\special@index=\index + \else + % \CodeDefIndex\special@index + \let\special@index=\codeline@wrindex + % \label{codeline indexnumber declaration} + \fi}% postponed till |\begin{document}| with respect of \docfm-like +% declarations. + +% And in case we don't want to index: +% \CodeDefine\gag@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: +% \CodeDefIndex\@@index \CodeDefIndex\@@codeline@wrindex +\StoreMacros{\index\codeline@wrindex} +% \CodeDefine\ungag@index +\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. +% \CodeDefIndex\Code@DefEnvir +\long\def\Code@DefEnvir#1{% + \endgroup + \addto@estomarginpar{#1}% + \addto@estoindex{#1}% + \@defentryze{#1}} + +% \CodeDefIndex\Code@UsgEnvir +\long\def\Code@UsgEnvir#1{% + \endgroup + \addto@estomarginpar{#1}% + \addto@estoindex{#1}% + \@usgentryze{#1}} + +% \CodeDefIndex\addto@estomarginpar +\long\def\addto@estomarginpar#1{% + \edef\@tempa{\noexpand\do{\xiistring#1}}% we |\string| the argument to + % allow it to be a~control sequence. + \expandafter\addtomacro\expandafter\envirs@tomarginpar\expandafter{\@tempa}} + +% \CodeDefIndex\addto@estoindex +\long\def\addto@estoindex#1{% + \edef\@tempa{\noexpand\do{\xiistring#1}} + \expandafter\addtomacro\expandafter\envirs@toindex\expandafter{\@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. +% \CodeDefine\TextUsage +% \CodeDefine*\TextUsage* +\def\TextUsage{\begingroup + %\label{TextUsage} + \MakePrivateLetters + \@ifstarl{\MakePrivateOthers\Text@UsgEnvir}{\Text@UsgMacro}} + +% \CodeDefIndex\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} + +% \CodeDefIndex\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. +% \CodeDefine\TextMarginize +% \CodeDefine*\TextMarginize* +\def\TextMarginize{\begingroup + \MakePrivateLetters + \@ifstarl{\MakePrivateOthers\egText@Marginize}{\egText@Marginize}} + +% \CodeDefIndex\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. + % \CodeDefine\gmdmarginpar + \long\def\gmdmarginpar#1{% + \marginpar{\raggedleft\strut + \hskip0ptplus100ptminus100pt% + #1}}%\stanza + % +\else + \long\def\gmdmarginpar#1{}% +\fi + +% \CodeDefine\Text@Marginize +\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 count all lines 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 +% count only the codelines, 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. +% \CodeDefIndex\do@properindex +\def\do@properindex{%\label{do@properindex} + \if@countalllines\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 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} +%\CodeDefine*{macrocode*} +\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. +%\CodeDefine*{macrocode} +\newenvironment*{macrocode}{%\label{macrocode} + \if@codeskipput\else\par\addvspace\CodeTopsep\@codeskipputgtrue\fi + \CodeSpacesBlank\QueerEOL}%^^A\docstrips + {\par\addvspace\CodeTopsep\CodeEscapeChar\\} +% Note that at the end of both the above environments the |\|'s r\^ole +% 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\"oglich, +% 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. +% +%\CodeDefine*{oldmc} +%\CodeDefine*{oldmc*} +\let\oldmc\macrocode +\let\endoldmc\endmacrocode +\@namelet{oldmc*}{macrocode*} +\@namelet{endoldmc*}{endmacrocode*} + +% Now we arm \env{oldmc} and \env{olmc*} with the +% the macro looking for |% \end|\arg{envir name}. +\addtomacro\oldmc{\@oldmacrocode@launch}% +\expandafter\addtomacro\csname oldmc*\endcsname{% + \@oldmacrocode@launch} + +% \CodeDefIndex\@oldmacrocode@launch +\def\@oldmacrocode@launch{% + \emptify\gmd@textEOL% to disable it in |\gmd@docstripdirective| + % launched within the code. + \glet\stored@code@delim\code@delim + \@makeother\^^B\CodeDelim*\^^B% + \ttverbatim \gmd@DoTeXCodeSpace% + \@makeother\|% 'cause |\ttverbatim| doesn't do that. + \MakePrivateLetters% see line \ref{MPL}.\par + % ^^A \expandafter\@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 occure 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. + \expandafter\gmd@currenvxistar\@currenvir*\relax + \@oldmacrocode} + +\bgroup\catcode`*11 +\firstofone{\egroup + \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.) + +% \CodeDefine\@oldmacrocode +\bgroup +\catcode`[=1 \catcode`]=2 +\catcode`\{=\active \@makeother\} +\@makeother\^^B +\catcode`!=0 \catcode`\\=\active +% \CodeEscapeChar\! \CDAnd +!catcode`&=14 !catcode`*=11 +!catcode`!%=!active !obeyspaces& +!firstofone[!egroup& +&%\stanza +!def!@oldmacrocode[& +!bgroup!let =!relax&% to avoid writing |!noexpand | four times. +!xdef!oldmc@def[& +!def!noexpand!oldmc@end####1!noexpand% !noexpand\end& +!noexpand{!@currenvir}[& +####1^^B!noexpand!end[!@currenvir]!noexpand!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{% + \expandafter\CodeDelim\stored@code@delim + \gmd@mchook}% see line \ref{gmd@mchook} + + +% \CodeDefine\VerbMacrocodes +\def\VerbMacrocodes{% + \let\macrocode\oldmc + \@namelet{macrocode*}{oldmc*}} + + +% To handle \ds\ directives in the code (in the old macrocodes +% case that is). + +% \begin{oldmc} +\bgroup\catcode`\%\active +\firstofone{\egroup +\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 + % \nlpercent|\gmd@charbychar| token. +% ^^A \typeout{code if ds \on@line}% + \if@dsdir\@dsdirgfalse + \if\noexpand<\noexpand#2\afterelsefifi\gmd@docstripdirective + \else\afterfifi\twelvepercent#1#2% + \fi + \else\afterfi\twelvepercent#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. +% \CodeDefIndex*\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}% +% \CodeDefIndex*\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 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} occure \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} +% \CodeDefIndex*\endmacro* +\expandafter\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 |{|\|}|, to +% tell the whole truth). +% \CodeDefine\gmd@ifsingle +\def\gmd@ifsingle#1#2\@@nil{% + \def\@tempa{#2}% + \ifx\@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. +% \CodeDefine\gmd@ifonetoken +\def\gmd@ifonetoken#1#2#3{% + \def\@tempb{#3}% We hide |#3| from \TeX\ in case it's |\if...| or + % so. \nlpercent|\@tempa| is used in \nlpercent|\gmd@ifsingle|. + \gmd@ifsingle#3\@@nil + \afterelsefi\expandafter#1\@tempb% + \else + \edef\@tempa{\expandafter\string\@tempb}% + \afterfi\expandafter#2\expandafter{\@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. +% \CodeDefine\Hybrid@DefMacro \CodeDefine\Hybrid@DefEnvir +\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}} + +%\CodeDefine\Text@MarginizeNext +\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. +%\CodeDefine\gmd@evpaddonce +\long\def\gmd@evpaddonce#1{% + \stepnummacro\gmd@oncenum + \expandafter\long\expandafter\edef% \CodeUsgIndex*{NeuroOncer} + \csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname{% + \noexpand\g@relaxen + \csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname}% Why does it + % work despite it shouldn't? Because when the CS got with + % \nlpercent|\csname...\endcsname| is undefined, it's equivalent + % |\relax| and therefore unexpandable. That's why it passes + % \nlpercent|\edef| and is able to be assigned. + \expandafter\addtomacro\csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname{#1}% + \expandafter\addto@hook\expandafter\everypar\expandafter{% + \csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname}% +} + +\nummacro\gmd@oncenum% We store the number uniquifying the auxiliary +% macro in a~macro to save count registers (cf.\ \pk{gmutils} +% 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. +\expandafter\let\expandafter\environment\csname macro*\endcsname +\expandafter\let\expandafter\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\'nski.} +% +% \CodeDefine\DoNotIndex +% \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: 'cause 't was iside a~command. So I~put it back} +% \changes{v0.98d}{06/9/11}{Unmade \cs{global}} +\def\DoNotIndex{\bgroup\MakePrivateLetters\DoNot@Index} + +% \CodeDefIndex\DoNot@Index +\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. + \dont@index#1.} + +% \CodeDefIndex\dont@index +\long\def\dont@index#1{% + \def\@tempa{\noexpand#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\@tempa.% a~dot finishes expelling + \else + \if\@tempa,% The list this macro is put before may + % contain commas and that's O.K., we just continue the work. + \afterelsefifi\dont@index + \else% what is else shall off the Index be expelled. + {\escapechar\m@ne + \xdef\@tempa{\string#1}}% + \expandafter\let% + \csname gmd/iexcl/\@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 'cause I~suppose one will +% document not \LaTeX\ source but normal packages. +% +% \begin{CodeSpacesSmall} +% \DoNotIndex\DoNotIndex \CodeDefine\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|. + \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 'cause + % 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 + % 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: \nlpercent|\@topsep| \nlpercent|\@topsepadd|^^B + % \ \nlpercent|\abovedisplayskip| \nlpercent|\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 \in@@}% + \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 + % |%%\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} + +% 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 +% +% \CodeDefine\DoIndex +% \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: 'cause +% 't was iside a~command and I~put it back} +% \changes{v0.98d}{06/9/11}{Unmade \cs{global}} +\def\DoIndex{\bgroup\MakePrivateLetters\Do@Index} + +% \CodeDefIndex\Do@Index +\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 OCSR, but anyway let's provide the +% counterpart. It OCSR, too. +% +% \CodeDefine\UndoDefaultIndexExclusions +% \changes{v0.98d}{06/9/11}{Unmade \cs{global}} +\def\UndoDefaultIndexExclusions{% + \StoreMacro\DoNotIndex + % ^^A\dont@index + \let\DoNotIndex\DoIndex + % ^^A \let\dont@index=\do@index + \DefaultIndexExclusions + % ^^A \RestoreMacro\dont@index + \RestoreMacro\DoNotIndex} + +% +% +% \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} \CodeDefine\IndexPrologue +\long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack} +% \label{IndexPrologue} + +% \CodeDefine\indexdiv +% \changes{v0.98a}{06/09/06}{modified to contain the star so that +% it may be redefined for tests.} +\def\indexdiv{\@ifundefined{chapter}{\section*}{\chapter*}} +% \CodeDefine\index@prologue +\@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 +% \CodeDefine\AtDIPrologue +% \changes{v0.98c}{06/9/8}{added 'cause of need} +% \CodeDefIndex\gmd@dip@hook \CodeDefine\AtDIPrologue +\@emptify\gmd@dip@hook +\long\def\AtDIPrologue#1{\g@addto@macro\gmd@dip@hook{#1}} + +% 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} +% \CodeDefine\IndexMin +\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. +% \CodeDefine*{IndexColumns} +% \CodeDefIndex*{\c@IndexColumns} +\newcount\c@IndexColumns \c@IndexColumns = 3 +% \CodeDefine*{theindex} +\renewenvironment{theindex} + {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]% + \IndexLinksBlack + \IndexParms \let\item\@idxitem \ignorespaces}% + {\end{multicols}} + +%\CodeDefine\IndexLinksBlack +\def\IndexLinksBlack{\hypersetup{linkcolor=black}}% To make Adobe +% Reader work faster. + +% \CodeDefine\IndexParms +\@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. + }}{} + + % \CodeDefine\PrintIndex +\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} +% +% \StraightEOL +% \iffalse +% +% This passage is obsoleted on 2006/11/30. +% +% In the \gmdoc\ thinking, the \ds\ directives belong to the +% narration layer since they all begin with |%|. For now I~don't +% have a~more minimal idea than to define a~pair of macros the first of +% which would |\active|ate the |<| and the other, assigned to the +% active |<|, would do the work and re`other' the |<| back. +% +% We provide two versions of the seargant-activating macro: the first +% makes only the first subsequent seargant typeset a~\ds\ +% directive (and the previous meaning of the |<| will be restored, the +% latter doesn't restore the previous meaning of |<| after (by) the +% first occurrence and the latter obeys usual scoping rules while the +% scoping rules of the first (|\docstrip|) are more strict: the scope +% is delimited by the first occurrence of the subject~|<|. +% +% Let us remeber that, just as all the control sequences except +% |\relax|, you can use |\docstrips| as an environment, i.e., in the +% |\begin{docstrips}|\dots |\end{docstrips}| syntax. And, that +% \env{macrocode} environment declares it. +% \bgroup\catcode`\<=\active +% \firstofone{\egroup +% % \stanza +% % \CodeDefine\docstrip +% \newcommand*\docstrip{% +% \gmd@storesearg +% \catcode`\<=\active +% \gmd@setdocstrips +% \let\gmd@docstripshook=\gmd@restoresearg}% +% % \stanza +% % \CodeDefine\docstrips +% \newcommand*\docstrips{% +% \catcode`\<=\active +% \gmd@setdocstrips +% \@emptify\gmd@docstripshook}% +% % \stanza +% % \CodeDefIndex\gmd@setdocstrips +% \def\gmd@setdocstrips{% +% \def<{\ifmmode\sgtleftxii\else\afterfi\gmd@docstripdirective\fi}} +% %\stanza +% % \CodeDefIndex\gmd@storesearg +% \def\gmd@storesearg{% +% \edef\gmd@SeargantCat{\the\catcode`\<}% +% \ifnum\gmd@SeargantCat=\active +% \let\gmd@SeargantMng=<% +% \fi} + +% % \CodeDefIndex\gmd@restoresearg +% \def\gmd@restoresearg{% +% \catcode`\<=\gmd@SeargantCat\relax +% \ifnum\gmd@SeargantCat=\active +% \let<=\gmd@SeargantMng +% \fi}% +% % \stanza +% }% of |\active| |<|'s |\firstofone| +% +% \fi ^^A~of the obsoletion iffalse +% \QueerEOL + +% \CodeDefine\gmd@docstripdirective +{\@makeother\<\@makeother\> + \glet\sgtleftxii=< + +\gdef\gmd@docstripdirective{% + \begingroup\let\do=\@makeother + \do\*\do\/\do\+\do\-\do\,\do\&\do\|\do\!\do\(\do\)\do\>\do\<% ^^Ayes, we + % ^^A make \nlpercent|<|\catother\ since a~directive |<<|\ theoretically may occure. + \@ifnextchar{<}{% + \let\do=\@makeother \dospecials + \gmd@docstripverb} + {\gmd@docstripinner}}% + +\if1 1%^^A~as the other debugs, let them rest in peace alt least till +%^^A the v2.0. +\gdef\Debug@dstron{\ifnum\c@codelinenum>1178 \ifdtraceon\fi + \ifnum\c@codelinenum>1184 \ifdtraceoff\@emptify\Debug@dstron\fi}% +\else + \global\@emptify\Debug@dstron +\fi + + % \CodeDefIndex\gmd@docstripinner + \gdef\gmd@docstripinner#1>{% + \endgroup + \def\gmd@modulehashone{% + \Module{#1}\space + \@afternarrgfalse\@aftercodegtrue\@codeskipputgfalse}% + % ^^A \gmd@docstripshook + \gmd@textEOL\gmd@modulehashone\Debug@dstron} + % 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. + % \CodeDefIndex\gmd@docstripverb + \catcode`\^^M=\active% + \gdef\gmd@docstripverb<#1^^M{% + \endgroup% + \def\gmd@modulehashone{% + \ModuleVerb{#1}\@afternarrgfalse\@aftercodegtrue% + \@codeskipputgfalse}% + \gmd@docstripshook% + \gmd@textEOL\gmd@modulehashone^^M}% +} + +% (\*Verbatim ;-) from \docfm:) +% \CodeDefine\Module \CodeDefine\ModuleVerb +\providecommand*\Module[1]{{\mod@math@codes$\langle\mathsf{#1}\rangle$}} + +\providecommand*\ModuleVerb[1]{{\mod@math@codes$\langle\langle\mathsf{#1}$}} + +% \CodeDefIndex\mod@math@codes +\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 +% \ 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 \ 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. +% +% \CodeDefine\gmd@DefineChanges +% \CodeDefine\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}% + \renewcommand\changes[4][]{}} + +\def\MakeGlossaryControls{% + \def\actualchar{=}\def\quotechar{!}% + \def\levelchar{>}\edef\encapchar{\twelveclub}}%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. + +% \CodeDefine\changes@ +% \changes[\changes]{v0.97}{06/09/04}{The optional pseudo-argument +% added intended to be the macro-entry.} +\newcommand\changes@[4][\generalname]{% + \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 |\@tempb| scratch macro. + \@tempswatrue + \edef\@tempb{% it's a~bug fix: while typesetting traditional + % \file{.dtx}es, |\last@defmark| came out with |\| at the + % beginning (which resulted with |\\|\ in the change + % log) but while typesetting the `new' way, it occured + % without the bslash. So we gobble the bslash if it's + % present and two lines below we handle the exception of + % |\last@defmark|\equals|{\}| (what would happen if + % a~definition of |\\| was marked in new way \gmdoc ing).%^^A] + \if\bslash\last@defmark\else\last@defmark\fi}% + \ifx\last@defmark\bslash\let\@tempb\last@defmark\fi% +%^^A \typeout{last dm @tempb: \@tempb}% (debugging) + % ^^A~\expandafter\quote@mname\macro@pname\relax + \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\@tempb{\string#1}} + % ^^A~\expandafter\quote@mname\@tempb\relax + \fi + \protected@edef\@tempa{\noexpand\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 preceed + % it by |\generalname|. + \@tempb + \actualchar\bslash verb*% + \if\verbatimchar\@tempb$\else\verbatimchar\fi + \quotechar\bslash \@tempb + \if\verbatimchar\@tempb$\else\verbatimchar\fi + \else + \space\actualchar\generalname + \fi + :\levelchar#4\encapchar hyperpage}}% + \@tempa + \fi\endgroup\@esphack} + +% Let's initialize |\last@defmark| and |\GeneralName|. +\@relaxen\last@defmark +\@emptify\GeneralName +% 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 +% \ shape both to be easily compared and readable. +% \CodeDefine\c@ChangesStartDate +\newcount\c@ChangesStartDate + +% \CodeDefine\if@RecentChange +\def\if@RecentChange#1{% + \gmd@setChDate#1\@@nil\@tempcnta + \ifnum\@tempcnta>\c@ChangesStartDate} + +% \CodeDefIndex\gmd@setChDate +\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[]{\{\/\/\\}}. +% \CodeDefine\ChangesStart +% \changes{v0.98e}{06/09/23}{\cs{string}s added before the seargants +% in the message with account of \cs{docstrip(s)}} +\def\ChangesStart#1#2{% + \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\@tempa{% + \noexpand\g@addto@macro\noexpand\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.}}% + \@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 +% |\CodeDefine|]). 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} +% \CodeDefine\generalname +\def\generalname{General} + +% \CodeDefine\chschange +% \changes{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|. +% +% \CodeDefine\RecordChanges +% \changes{v0.98c}{06/09/08}{made self-\cs{relax}ing} +% \changes{v0.98e}{06/09/23}{made it defining \cs{changes}} +\def\RecordChanges{\makeglossary\gmd@DefineChanges + \@relaxen\RecordChanges} +% \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 +% \CodeDefIndex*\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} +% +% \CodeDefine*{theglossary} +% \CodeDefIndex*\theglossary +\newenvironment{theglossary}{% + \begin{multicols}\c@GlossaryColumns + [\glossary@prologue][\GlossaryMin]% + \GlossaryParms \let\item\@idxitem \ignorespaces}% + {\end{multicols}} + +% Here is the MakeIndex style definition: +% \index{gmglo.ist@\file{gmglo.ist}} +%^^A \begin{docstrips} +% +%<+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: +% \[\hbox{|makeindex -r -s gmglo.ist -o |\|.gls |\|.glo|}\] +% ^^B +% ^^B makeindex -r -s gmglo.ist -o .gls .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} +% +% \CodeDefine\GlossaryPrologue +\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.} +% \CodeDefine\glossary@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} +% \CodeDefine\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} \CodeDefine\PrintChanges +\def\PrintChanges{% to avoid a~disaster among queer EOLs: + \@ifQueerEOL + {\StraightEOL\@input@{\jobname.gls}\QueerEOL}% + {\@input@{\jobname.gls}}% + \g@emptify\PrintChanges} + +% % \iffalse +% % \begin{quotation} +% % The following definitions provide the |\pfill| command; if this is +% % specified in the index style file to MakeIndex as the delimiter to +% % appear after index items, then the intervening space before the +% % referenced page numbers will be filled with dots, with a little +% % white space interpolated at each end of the dots. If the line is +% % broken the dots will show up on both lines.\end{quotation} +% \def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill}% +% \def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil}% +% \def\pfill{\unskip~\dotfill\penalty500\strut\nobreak +% \dotfil~\ignorespaces}% +%% +%%\begin{verbatim} +%% +%%<+ist>delim_0 "\\pfill " +%%<+ist>delim_1 "\\pfill "2 +%%<+ist>delim_2 "\\pfill " +%%<*package> +%\end{verbatim} +% % skipped definitions of dotted fills\fi +% +% +% \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. +% \CodeDefine\check@sum \CodeDefine\CheckSum +\newcount\check@sum +\def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack} +% \CodeDefine*{CheckSum} \CodeDefIndex*\c@CheckSum +\newcounter{CheckSum} +% \label{checksum} +% \CodeDefIndex\step@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\^ole 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}. +% \CodeDefine\check@checksum +\def\check@checksum{\relax + \ifnum\check@sum=\z@ + \typeout{**********************************}% + \typeout{* The input file \gmd@inputname\space has no Checksum + stated.}% + \typeout{* The current checksum is \the\c@CheckSum.}% + \gmd@chschangeline% a~check sum changes history entry, see below. + \typeout{* (package gmdoc info.)} + \typeout{**********************************}% + \else + \ifnum\check@sum=\c@CheckSum + \typeout{*****+*+*+*+*+*+*+*+*+*+}% + \typeout{* The input file \gmd@inputname: Checksum passed.}% + \gmd@chschangeline + \typeout{* (package gmdoc info.)} + \typeout{*****+*+*+*+*+*+*+*+*+*+}% + \else + \typeout{********!*!*!*!*!*!*!*!*!*!*!*!}% + \typeout{*! The input file \gmd@inputname:} + \typeout{*! The CheckSum stated: \the\check@sum\space<> my + count: \the\c@CheckSum.} + \gmd@chschangeline + \typeout{*! (package gmdoc info.)} + \typeout{********!*!*!*!*!*!*!*!*!*!*!*!}% + \fi + \fi + \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. +% \CodeDefIndex\gmd@chschangeline +\def\gmd@chschangeline{% + \typeout{\twelvepercent\space\string\chschange{% + \fileversion}{\the\year/\the\month/\the\day}{\the\c@CheckSum}} + \typeout{\twelvepercent\space\string\chschange{\fileversion}{% + \expandafter\@gobbletwo\the\year/\the\month/\the\day}{%\relax + % with two di\-g\-it year in case you use |\ChangesStart|. + \the\c@CheckSum}}} + +% And here the meaning of such a~line is defined: +\newcommand*\chschange[3]{%\label{chschange} + \csname changes\endcsname{#1}{#2}{CheckSum #3}% |\csname...| 'cause + % \nlpercent\cs{cha\+n\+g\+es} is \nlpercent|\outer|. + \CheckSum{#3}} +% It will make a~`General' entry in the change history unless +% used in some |\CodeDefine|'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 +% \CodeDefine\ltxPageLayout +\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}} + +% %\iffalse +% \def\task#1#2{} +% % What is this for? Probably to turn an obsolete command off. Or maybe +% % a~TODO? +% % \fi + +%\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 \nlpercent|_| `other' in order to allow it in the filenames. + +% \CodeDefine\Doc@Include +\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 \nlpercent |/|). This is intended not to print + % the path in the page footers only the filename.\par + % \CodeUsage\HLPrefix \CodeDefine\EntryPrefix + \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 \nlpercent|\IndexPrologue|'s + % |\if|s. Therefore the + % definition is global. The latter is such for symmetry. + % \CodeDefine\GeneralName + \def\GeneralName{#2\actualchar\pk{#2} }% \label{GeneralName} for the + % changes'history main level entry. + \relax + %^^A\if@ltxDocInclude + \clearpage + % ^^A\fi + \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. + +% \CodeDefine\@docinclude +% \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.aux}\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\@tempb{#2}% + \@for \@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}% + \fi + \if@tempswa \let\@auxout\@partaux + \if@filesw + \immediate\openout\@partaux #2.aux\relax% Yes, only |#2|. It's to + % create and process the partial \pk{.aux} 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.) +% \CodeDefine\xdef@filekey +\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 +% \CodeDefIndex\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{|\|}| 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.} +% \CodeDefIndex\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}} + +%\CodeDefine\gmd@doIndexRelated +\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\CodeDefine\aalph \CodeDefine\@aalph +\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|. +% \CodeDefine\docincludeaux +\def\docincludeaux{% + % We set the things for including the files only once. + \global\@relaxen\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 + \@addtoreset{codelinenum}{\filedivname}% remember it has + % a~|\global| effect in fact. For each file we'll reset + % \env{codelinenum}. + \def\thefilediv{\aalph{\filedivname}}% The files will be numbered + % with letters, lowercase first. + \expandafter\let\csname the\filedivname\endcsname=\thefilediv% This + % li\-ne lets |\the|\ 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. + \expandafter\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 + \expandafter\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% If |\filediv| is higher than + % |\section| we don't change the two divisions (they are + % |\section| and |\subsection| 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 |\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. +% \CodeDefine\SetFileDiv +% \changes{v0.98c}{06/9/10}{added and a~bug fixed in \cs{docincludeaux}} +\def\SetFileDiv#1{% + \edef\filedivname{#1}% + \expandafter\let\expandafter\filediv\csname#1\endcsname} + +% \subdivision{\cs{SelfInclude}} +% +% I~needed to include the driver file into +% a~documentation so I~wrote +% a~macro in case I'll need it again or you'll need it. +% We define it immediately i.e., +% without the |\catcode|s trick because it uses |\jobname| inside so +% the filename will be all \catother\ anyway. +% \CodeDefine\SelfInclude +% \changes{v0.98a}{06/09/06}{added in response to the needs} +\newcommand*{\SelfInclude}[2][.tex]{% As you guess, the optional |#1| + % is the jobname's extension. The second parameter is \emph{not} for + % the filename (note \emph{it's known:} as |\jobname|!), but + % \emph{for the stuff to be put at begin input.} + \AtBegInputOnce{#2}% + \gdef\HLPrefix{\filesep}% + \gdef\EntryPrefix{\filesep}% we define two rather kernel parameters + % etc.\ as in \nlpercent|\DocInclude|. + \relax + %^^A\if@ltxDocInclude + \clearpage + % ^^A\fi + \docincludeaux + \edef\currentfile{\jobname#1}% + \let\fullcurrentfile\currentfile + \def\GeneralName{\jobname\actualchar\pk{\jobname} }% for the + % changes history main level entry. + \ifnum\@auxout=\@partaux + \@latexerr{\string\DocInclude\space cannot be nested}\@eha + \else + \if@filesw + \gmd@writemauxinpaux{\jobname.auxx}% ^^A + % this queer macro allows |_| in the file names. In this + % particular case |\string\jobname| would do, but anyway we + % provide a~more general solution. Note the \pk{.auxx} extension + % used instead of \pk{.aux}. This is done to avoid an infinite + % recurrence of \nlpercent|\input|s. + \fi + \@tempswatrue + \if@partsw \@tempswafalse\edef\@tempb{\jobname}% + \@for + \@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}% + \fi + \if@tempswa \let\@auxout\@partaux + \if@filesw + \immediate\openout\@partaux \jobname.auxx\relax + \immediate\write\@partaux{\relax} + \fi + % \begin{quotation}We need to save (and later + % restore)\dots\end{quotation} + \StoringAndRelaxingDo% provided by \pk{gmutils} + \gmd@doIndexRelated + \if@ltxDocInclude\part{\currentfile}% + \else\let\maketitle=\InclMaketitle + \fi + \if@ltxDocInclude\xdef@filekey\fi + \GetFileInfo{\currentfile}% it's my (GM) addition with the account + % of using file info in the included files' title etc. + \incl@DocInput{\fullcurrentfile}% originally just |\currentfile|, no + % difference in |\SelfInclude|. + \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 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% among others, causes the |\writes| to be executed which is + % crucial for proper toc-ing e.g. + %^^A\fi + \gmd@writeckpt{\jobname.x}% note the |.x| in the checkpoint + % used to distinguish this instance (input) of the driver file + % from its main instance. + \if@filesw \immediate\closeout\@partaux \fi + \else\@nameuse{cp@\jobname.x}% note |.x|: it's used for the same + % reason as above. + \fi + \let\@auxout\@mainaux + \fi}% end of |\SelfInclude|. + +% 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. +% +% \CodeDefine\ltxLookSetup +% \CodeDefIndex\if@ltxDocInclude \CodeDefIndex*\@ltxDocIncludetrue +% \CodeDefIndex*\@ltxDocIncludefalse +\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. +% +% \iffalse +% % \stanza +% % But it may be not a~usual situation to include the source files +% % as with \pk{ltxdoc} but with the \emph{new} |\DocInput| macro. So +% % let's |\def| +% % \CodeDefine\ltxMultidocOldSetup +% \newcommand*\ltxMultidocOldSetup{% +% \ltxMultidocSetup +% \let\incl@DocInput=\OldDocInput} +% +% \@onlypreamble\ltxMultidocOldSetup +% +% And, for the symmetry, if you prefer the look offered by +% me, but +% \fi + +% If you want to |\Doc/SelfInclude| \docfm-likes: +% \CodeDefine\olddocIncludes +\newcommand*\olddocIncludes{% + \let\incl@DocInput=\OldDocInput} + +% And, if you have set the previous and want to set it back: +% \CodeDefine\gmdocIncludes +\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. +% \CodeDefine\maketitle +\AtBegInput{% + \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 +% TUGboat), 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}. + % \CodeDefine\@maketitle + \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.) + % \CodeDefine\title \CodeDefine\author \CodeDefine\date + % \CodeDefine\thanks + \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}}% + }%\CodeDefIndex\and + \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. + % \CodeDefine\titlesetup + \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 + +% 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. +% +% \CodeDefine\InclMaketitle +% \changes{v0.98a}{06/09/05}{renamed from \cs{incl@maketitle} 'cause +% I~needed it in self-input hacks.} +\def\InclMaketitle{%\par\CodeDefIndex\and + {\def\and{, }% we make |\and| just a~comma. + {\let\thanks=\@gobble% for the toc version of the heading we + % discard |\thanks|.\tOnLine + \protected@xdef\incl@titletotoc{\@title\if@fshda\protect\space + (\@author)\fi}% we add the author iff the `files have + % different authors' \nlpercent(|@fshda|) + }% \CodeDefine\thanks + \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. + \expandafter\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. +% +% \CodeDefIndex\if@fshda +% \CodeDefIndex*\@fshdatrue +% \CodeDefIndex*\@fshdafalse +% \CodeDefine\PrintFilesAuthors +\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{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: +% \CodeDefine\IndexInput +% \changes{v0.98b}{06/09/07}{\cs{StoreMacro}ing and \cs{RestoreMacro}ing +% \cs{code@delim} added} +\def\IndexInput#1{% + \StoreMacro\code@delim + \CodeDelim*\^^A% + \DocInput{#1}\RestoreMacro\code@delim} +% How does it work? We assume in the input file is no explicit +% \. 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 +% +% \iffalse First I~tried to use \specialcomment{gmlonely} provided by +% the \pk{comment} package, but it caused errors.\fi +% +% 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. +% +% \CodeDefine*{gmlonely} +% \CodeDefine\skipgmlonely +\newenvironment{gmlonely}{\StraightEOL}{} + +\newcommand\skipgmlonely[1][]{% + \def\@tempa{%\CodeDefIndex\gmd@skipgmltext + \def\gmd@skipgmltext{\g@emptify\gmd@skipgmltext#1}}% + \@tempa + \expandafter\AtBegInput\expandafter{\@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|. +% +% \CodeDefine\catother +\bgroup\catcode`\_=8 % we ensure the standard |\catcode| of |_|. +\firstofone{\egroup + \newcommand*\catother{${}_{12}$}%\par +% Similarly, if we need to say some char is of category 13 (`active'), +% we'll write \catactive, got by |\catactive| +% \CodeDefine\catactive + \newcommand*\catactive{${}_{13}$}%\par +% and a~letter, \catletter +% \CodeDefine\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 +% \CodeDefine*{copyrnote} +\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 +% \CodeDefine*{quotation} +\renewenvironment{quotation}{\par``\ignorespaces}{\unskip''\par} +% \chunkskip +% For some mysterious reasons |\noindent| doesn't work with the first +% (narrative) paragraph after the code so let's work it around: +% \CodeDefine\gmdnoindent +\newcommand*\gmdnoindent{\leavevmode\hskip-\parindent} +% +% When a~verbatim text occurres 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. For this purpose provide +% \CodeDefine\nlpercent +\newcommand*\nlpercent{% + \@ifstar{\def\@tempa{{\tt\twelvepercent}}% + \@emptify\@tempb\nl@percent}% + {\@emptify\@tempa + \def\@tempb{\gmboxedspace}\nl@percent}} + +\newcommand*\gmboxedspace{\hbox{\normalfont{ }}} + +\newcommand*\nl@percent[1][]{% + \unskip + \discretionary{\@tempa}{{\tt\twelvepercent\gmboxedspace}}{\@tempb}% + \penalty10000\hskip0sp\relax} +% As you see, |\nlpercent| inserts 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. +% +% TODO: make the space flexible (most probably it requires using sth.\ +% else than |\discretionary|). +%\stanza +% +% An optional hyphen for CSs in the inline comment: +% \CodeDefine\+ +\@ifundefined{+}{}{\typeout{^^Jgmdoc.sty: redefining \bslash+.}} +\def\+{\discre{{\normalfont-}}{{\tt\twelvepercent\gmboxedspace}}{}} +% +% +% And finally, some logos: +% \begin{quotation} Here are a few definitions which can usefully be +% employed when documenting +% package files: now we can readily refer to \AmSTeX, \BibTeX\ and \SliTeX, as well +% as the usual \TeX\ and \LaTeX. There's even a \PlainTeX\ and +% a~\Web.\end{quotation} +% \CodeDefine\AmSTeX \CodeDefine\BibTeX \CodeDefine\SliTeX +% \CodeDefine\PlainTeX \CodeDefine\Web \CodeDefine\TeXbook +% \CodeDefine\eTeX \CodeDefine\pdfeTeX \CodeDefine\pdfTeX +% \CodeDefine\XeTeX \CodeDefine\ds +\@ifundefined{AmSTeX} + {\def\AmSTeX{\leavevmode\hbox{$\mathcal A\kern-.2em\lower.376ex% + \hbox{$\mathcal M$}\kern-.2em\mathcal S$-\TeX}}}{} + +\@ifundefined{BibTeX} + {\def\BibTeX{{\rmfamily B\kern-.05em% + \textsc{i\kern-.025em b}\kern-.08em% + \TeX}}}{} + +\@ifundefined{SliTeX} + {\def\SliTeX{{\rmfamily S\kern-.06emL\kern-.18em\raise.32ex\hbox + {\scshape i}\kern -.03em\TeX}}}{} + +\@ifundefined{PlainTeX}{\def\PlainTeX{\textsc{Plain}\kern2pt\TeX}}{} + +\@ifundefined{Web}{\def\Web{\textsc{Web}}}{} +% There's also the \LaTeXpar\ logo got with the |\LaTeXpar| macro +% provided by \pk{gmutils}. And here \TeXbook's logo: +\def\TeXbook{The \TeX book} + +\@ifundefined{eTeX}{\def\eTeX{$\varepsilon$\TeX}}{}% The \eTeX\ manual +% uses `$\varepsilon$-\TeX' but that would look strange in \pdfeTeX. + +\@ifundefined{pdfeTeX}{\def\pdfeTeX{pdf\eTeX}}{} + +\@ifundefined{pdfTeX}{\def\pdfTeX{pdf\TeX}}{} + +\@ifundefined{XeTeX}{\def\XeTeX{X\kern-.125em\relax + \@ifundefined{reflectbox}{% + \lower.5ex\hbox{E}\kern-.1667em\relax}{% + \lower.5ex\hbox{\reflectbox{E}}\kern-.1667em\relax}% + \TeX}}{}% As you see, if +% \TeX\ doesn't recognize \nlpercent\cs{re\+flect\+box} (\pk{graphics} +% isn't loaded), the first |E| will not be reversed. This version of +% the command is intended for non-\XeTeX\ usage. With \XeTeX, the +% reversed |E| you get as the Unicode Latin Letter Reversed E. + +\@ifundefined{ds}{\def\ds{DocStrip}}{} + +% Define |\filedate| and friends from info in the +% |\ProvidesPackage| etc.\ commands. +% \CodeDefine\GetFileInfo +\def\GetFileInfo#1{% + \def\filename{#1}% + \def\@tempb##1 ##2 ##3\relax##4\relax{% + \def\filedate{##1}% + \def\fileversion{##2}% + \def\fileinfo{##3}}% + \edef\@tempa{\csname ver@#1\endcsname}% + \expandafter\@tempb\@tempa\relax? ? \relax\relax} + +% Since we may documentally input files that we don't load, as \docfm\ +% e.g., let's define 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. +% \CodeDefine\ProvideFileInfo +% \changes{v0.98a}{06/09/06}{added} +\def\ProvideFileInfo#1{% + \begingroup + \catcode`\ 10 \catcode\endlinechar 10 % + \@makeother\/\@makeother\&% + \kernel@ifnextchar[{\gmd@providefii{#1}}{\gmd@providefii{#1}[]}%^^A] + } + + % \CodeDefIndex\gmd@providefii +\def\gmd@providefii#1[#2]{%\\ + % (we \emph{don't} write the file info to \pk{.log}) + \expandafter\xdef\csname ver@#1\endcsname{#2}% + \endgroup} + +% And a~self-reference abbreviation (intended for providing file info +% for the driver): +% \CodeDefine\ProvideSelfInfo +\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: +% \CodeDefine\filenote +\newcommand*\filenote{This file has version number \fileversion{} dated \filedate{}.} +% And exactly as |\thanks|: +% \CodeDefine\thfileinfo +\newcommand*\thfileinfo{\thanks\filenote} + + +% \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|. \CodeDefine\CDAnd +\newcommand*\CDAnd{\CodeDelim\&} +% \CodeDefine\CDPerc +\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. +\@ifdefinable\division{}% just to test (this \LaTeX\ check issues an +% error if the first argument is already defined). \CodeDefine\division +\@ifundefined{section}{% + \@relaxen\division}{% \CodeDefine\division + \let\division=\section} + +\@ifdefinable\subdivision{}% just to test (see above). \CodeDefine\subdivision +\@ifundefined{subsection}{% + \@relaxen\subdivision}{% \CodeDefine\subdivision + \let\subdivision=\subsection} +% The |\let|s are inside |\@ifundefined|s because I'm not sure +% whether you will typeset a~documentation with usual classes. Maybe +% too much care. +% +% +% \stanza +% To kill a~tiny little bug in \file{doc.dtx} (in line 3299 |\@tempb| and +% |\@tempc| are written plain not verbatim): +% \CodeDefIndex*{gmd@mc} \CodeDefine\AfterMacrocode +\newcounter{gmd@mc} + +\def\gmd@mchook{\stepcounter{gmd@mc}% \label{gmd@mchook} + \gmd@mcdiag + \csname gmd@mchook\the\c@gmd@mc\endcsname} + +\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 |\@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). +% \CodeDefine\gmd@mcdiag \CodeDefine\mcdiagOn \CodeDefine\mcdiagOff +\@emptify\gmd@mcdiag + +\def\mcdiagOn{\def\gmd@mcdiag{% + \typeout{^^J\bslash end{macrocode(*)} No.\the\c@gmd@mc + \space\on@line, cln.\the\c@codelinenum.}}} + +\def\mcdiagOff{\@emptify\gmd@mcdiag} +% +% +% \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: +% \CodeDefine\CharacterTable +% \CodeDefIndex\Character@Table +\def\CharacterTable{\begingroup + \@makeother\{\@makeother\}% + \Character@Table} + +\begingroup +\catcode`\<=1 \catcode`\>=2 % +\@makeother\{\@makeother\}% +\firstofone<\endgroup + \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>>> +% 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. +% +% \gmdmarginpar{kici kici} +% 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: +% \CodeDefine\DescribeMacro +\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. +% \CodeDefine\DescribeEnv +\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:\CodeDefine\Describe +\outer\def\Describe{% + \begingroup\MakePrivateLetters + \@ifstarl{\MakePrivateOthers\Describe@Env}{\Describe@Macro}} + +% The below two definitions are adjusted \*s of |\Text@UsgMacro| and +% |\Text@UsgEnvir|. +% \CodeDefIndex\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} + +% \CodeDefIndex\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 +% \CodeDefine\MacroIndent +\let\MacroIndent\CodeIndent +% And similarly the other skips: \CodeDefine\MacrocodeTopsep +\let\MacrocodeTopsep\CodeTopsep +% Note that \TextUsage\MacroTopsep\ is defined in \gmdoc\ and has +% the same r\^ole as in \docfm. + +\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: +% \CodeDefine\noeffect@info +\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| +% \CodeDefine\CodelineIndex +\let\CodelineIndex\@pageindexfalse +\@onlypreamble\CodelineIndex + +% \CodeDefine\PageIndex +\let\PageIndex\@pageindextrue +% \label{PageIndex} +\@onlypreamble\PageIndex + +% The next two declarations I~find useful and +% smart:\CodeDefine\DisableCrossrefs +\def\DisableCrossrefs{\@bsphack\gag@index\@esphack} + +% \CodeDefine\EnableCrossrefs +\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.\CodeDefine\AlsoImplementation +\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} \CodeDefine\OnlyDescription + +\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*{\<...>}|\<|\|>|. +% \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}: +% \CodeDefine\SpecialMainIndex +\let\SpecialMainIndex=\CodeDefIndex + +% \DoNotIndex\endcsname* +% \CodeDefine\SpecialMainEnvIndex +\def\SpecialMainEnvIndex{\csname CodeDefIndex\endcsname*}% we don't +% type |\CodeDefIndex| explicitly here 'cause it's |\outer|, remember? + +% \CodeDefine\SpecialIndex \CodeDefine\SpecialUsageIndex +% \CodeDefine\SpecialEnvIndex \CodeDefine\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 occures 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. +% +% \CodeDefine\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} +\def\verbatimchar{&} + +% 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.) +% \CodeDefine\*\changes{v0.98}{06/09/05}{made robust.} +\DeclareRobustCommand*\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} + + +% \TextUsage\IndexPrologue\ is defined in line +% \ref{IndexPrologue}. And other \docfm\ index commands too. + +% \CodeDefine\main \CodeDefine\usage +\@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. +% \CodeDefine*{StandardModuleDepth} +\newcounter{StandardModuleDepth} + +% \stanza +% For now let's just mark the macro for further development +% \CodeDefine*\DocstyleParms +\noeffect@info{DocstyleParms} + +% For possible further development or to notify the user once and +% forever: +% \CodeDefine\DontCheckModules \CodeDefine\CheckModules +\@emptify\DontCheckModules \noeffect@info{DontCheckModules} +\@emptify\CheckModules \noeffect@info{CheckModules} +% The \TextMarginize\Module|\Module| macro \emph{is} provided exactly +% as in \docfm. +% \CodeDefine\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} +% \CodeDefine\MakePercentIgnore \CodeDefine\MakePercentComment +\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}.} +%\CodeDefine\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{% + \AtBegInputOnce{\StraightEOL + \let\@MakeShortVerb=\old@MakeShortVerb + %\label{oldmkshvrrb}\CodeDefIndex\gmd@@macro + \let\gmd@@macro\macro + \def\macro{\let\gmd@ifonetoken\@secondoftwo\gmd@@macro}% (Of course, + % na\-\"\i{}\-ve + % \nlpercent|\exp...\let\exp...\macro\cs...\macro*\endcs...| caused + % an infinite loop since in the definition of \env{macro*} the + % |\macro| macro occures.) + \VerbMacrocodes}% + \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\'nski suggests to add the marginpar clauses for the +% 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{|\|}| 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 `EOL-straighten' them like +% |\tableofcontents|, I~suppose (cf.\ line \ref{straighttoc}). +% +% Some lines of non-printing stuff such as |\CodeDefine...| 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. +% +% My \TeX\ Guru remarked that |\jobname| expands to the main file name +% without extension iff that extension is \file{.tex}. Should +% I~replace |\jobname| with |\jobnamewoe| then? (The latter always +% expands to the file name without extension.) +% +% About the \ds\ \gmiflink{verbatim mode directive} see above. +% +% \end{bulletpars} +% +% \def\EOFMark{\} +% \division{(No) \EOFMark} If the user doesn't wish the +% documentation to be ended by \EOFMark, \heshe\ +% should 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}.}: +% +% \CodeDefine\NoEOF +% \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 EOL and the latter gobbles the stuff till the EOL to +% suppress possible \cs{endinput} when used in \cs{StopEventually}} + +\bgroup\catcode`\^^M\active \firstofone{\egroup% + \def\@NoEOF#1^^M{% + \@relaxen\EOFMark\expandafter\noexpand\endinput^^M}} + +\def\NoEOF{\QueerEOL\@NoEOF} + +% \label{NoEOF} As you probably see, |\NoEOF| has also the +% |\endinput| effect. + +\endinput +%^^A~\docstrip +% +%\PrintChanges \PrintIndex +% +% +%^^A~place for general changes: +% +% \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{CodeDefine} 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.} +% +% \Finale + +% (For my GNU Emacs:) +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "e:/LaTeX/TeXGuru/gmdoc/gmdocDoc" +%%% End: diff --git a/Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls b/Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls new file mode 100644 index 00000000000..a03d4c4aa43 --- /dev/null +++ b/Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls @@ -0,0 +1,307 @@ +% +% \GetFileInfo{gmdocc.cls} +% \title{The \pk{gmdocc} Class For \pk{gmdoc} Driver Files\thfileinfo} +% \author{Grzegorz `Natror' Murzynowski} +% \maketitle +% +% \begin{copyrnote} +% +%%Written by Grzegorz `Natror' Murzynowski, +%% natror at o2 dot pl +%% +%% \copyright\,2006 by Grzegorz `Natror' Murzynowski. +%% +%% This program is subject to the \LaTeX\ Project Public License. +%% See ^^A +%% \url{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html} ^^A +%% for the details of that license. +%% +%% LPPL status: "author-maintained".\par +%% +% +%\end{copyrnote} +% +% \RecordChanges +% \ChangesStart{v0.677}{1000/00/00} +% +% \chschange{v0.69}{06/10/1}{81} +% \chschange{v0.70}{06/10/10}{98} +% \chschange{v0.71}{06/10/21}{114} +% \chschange{v0.72}{06/11/14}{122} +% \chschange{v0.73}{06/12/1}{128} +% + +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{gmdocc} + [2006/12/01 v0.73 a class for gmdoc driver files (GM)] + +% +% \division{Intro} +%% +%% This file is a~part of \pk{gmdoc} bundle and provides a~document +%% class for the driver files documenting \LaTeXpar\ packages \&a.\ +%% with my \pk{gmdoc.sty} package. It's not necessary, of course: most +%% probably you may use another document class you like. +%% +%% By default this class loads \pk{mwart} class with a4paper (default) +%% option and \pk{lmodern} package with QX fontencoding. It loads also +%% my \pk{gmdoc} documenting package which loads some auxiliary +%% packages of mine and the standard ones. +%% +%% If the \pk{mwart} class is not found, the standard \pk{article} +%% class is loaded instead. Similarly, if the \pk{lmodern} is not +%% found, the standard Computer Modern font family is used in the +%% default font encoding. +%% +% +% \division{Usage} +% +% For the ideas and details of \pk{gmdoc}ing of the \LaTeXpar\ files +% see the \pk{gmdoc.sty} file's documentation (chapter \ref{gmd}). The +% r\^ole of the \pk{gmdocc} document class is rather auxiliary and +% exemplary. Most probably, you may use your favourite document class +% with the settings you wish. This class I~wrote to meet my needs of +% fine formatting, such as not numbered sections and sans serif demi +% bold headings. +% +% However, with the users other than myself in mind, I~added some +% conditional clauses that make this class works also if an \pk{mwcls} +% class or the \pk{lmodern} package are unknown. \dekmedskip +% +% Of rather many options supported by \pk{gmdoc.sty}, this class +% chooses my favourite, i.e., the default. An exception is made for +% the \TextUsage*{noindex} option, which is provided by this class and +% passed to \pk{gmdoc.sty}. This is intended for the case you don't +% want to make an index. +% +% Simili modo, the \TextUsage*{nochanges} option is provided to turn +% creating the change history off. +% +% Both of the above options turn the \emph{writing out to the files} +% off. They don't turn off |\PrintIndex| nor |\PrintChanges|. (Those +% two commands are no-ops by themselves if there's no \file{.ind} +% (n)or \file{.gls} file respectively.) +% \dekmedskip +% +% One more option is \TextUsage*{outeroff}. It's intended for +% compiling the documentation of macros defined with the |\outer| +% prefix. It |\relax|es this prefix so the `|\outer|' macros' names can +% appear in the arguments of other macros, which is necessary to +% pretty mark and index them. +% +% I~decided not to make discarding |\outer| the default because +% it seems that \LaTeX\ writers don't use it in general and +% \pk{gmdoc.sty} \emph{does} make some use of it. +% \dekmedskip +% +% This class provides also the \TextUsage*{debug} option. It turns the +% |\if@debug| Boolean switch True and loads the \pk{trace} package that +% was a~great help to me while debugging \pk{gmdoc.sty}. +% \dekmedskip +% +% The default base document class loaded by \pk{gmdocc.cls} is Marcin +% Woli\'nski's \pk{mwart}. If you have not installed it on your +% computer, the standard \pk{article} will be used. +% +% Moreover, if you like MW's classes (as I~do) and need |\chapter| +% (for multiple files' input e.g.), you may declare another \pk{mwcls} +% with the option homonimic with the class'es name: \TextUsage*{mwrep} +% for \pk{mwrep} and \TextUsage*{mwbk} for \pk{mwbk}. For the symmetry +% there's also \TextUsage*{mwart} option (equivalent to the default +% setting). +% +% The existence test is done for any MW class option as it is in the +% default case. +% +% \stanza +% The \TextUsage\EOFMark\ is in this class typesets like this (of +% course, you can redefine it as you wish):\par\EOFMark +% +% \StopEventually\NoEOF +% +% \division{The Code} + +% \CodeDefIndex\gmcc@baseclass +\def\gmcc@baseclass{mwart}% the default is Marcin Woli\'nski's class (\pk{mwcls}) +% analogous to \pk{article}. + +% Since you can choose the standard \pk{article} class, we'd better +% provide a~Boolean switch to keep the score of what was chosen. It's +% to avoid unused options if \pk{article} is chosen. +%\CodeDefIndex*{gmcc@mwcls} +\newif\ifgmcc@mwcls +\gmcc@mwclstrue +% \CodeDefine*{mwart} +\DeclareOption{mwart}{\def\gmcc@baseclass{mwart}}% The \pk{mwart} class may also +% be declared explicitly. +% \CodeDefine*{mwrep} +\DeclareOption{mwrep}{\def\gmcc@baseclass{mwrep}}% If you need +% chapters, this option chooses an MW's class that corresponds to +% \pk{report}, +% \CodeDefine*{mwbk} +\DeclareOption{mwbk}{\def\gmcc@baseclass{mwbk}}% and this MW's class +% corresponds to \pk{book}. +% \CodeDefine*{article} +\DeclareOption{article}{\gmcc@mwclsfalse}% you can also +% \emph{choose} \pk{article}. + + +% \CodeDefine*{outeroff} +\DeclareOption{outeroff}{\let\outer\relax}% This option allows +% |\outer|-prefixed macros to be \pk{gmdoc}-processed with all the +% bells and whistles. + +% \CodeDefine\if@debug +\newif\if@debug +% \CodeDefine*{debug} +\DeclareOption{debug}{\@debugtrue}% This option causes \pk{trace} to +% be loaded and the Boolean switch of this option may be used to hide +% some things needed only while debugging. + +% \CodeDefine*{noindex} +\DeclareOption{noindex}{% + \PassOptionsToPackage{\CurrentOption}{gmdoc}}% This +% option turns the writing outto \file{.idx} file off. + +% \CodeDefIndex\if@gmccnochanges +% \CodeDefIndex*\@gmccnochangestrue +% \CodeDefIndex*\@gmccnochangesfalse +\newif\if@gmccnochanges +% \CodeDefine*{nochanges} +\DeclareOption{nochanges}{\@gmccnochangestrue}% This option turns the +% writing outto \file{.glo} file off. + +% \CodeDefine*{gmeometric} +\def\gmTheGeometry{geometry} +\DeclareOption{gmeometric}{% + \IfFileExists{gmeometric.sty}{% + \def\gmTheGeometry{gmeometric}}{}}% It's an experimental option +% that causes the |\geometry| macro provided by \pk{geometry} package +% is not restricted to the preamble. This option causes the +% \pk{gmeometric} package is loaded (if available) that works the +% limitation around. + + +\ProcessOptions + +% \newif\ifSecondClass^^A~to assure \TeX knows ifSecondClass +% ^^A switch and therefore it counts the fis properly. +% \iffalse It's for cooperation with my another class. (Feature under +% construction.) +\@ifundefined{ifSecondClass}{% + \newif\ifSecondClass}{} +%\fi\fi + +%\iffalse +\ifSecondClass\else +%\fi\fi +\ifgmcc@mwcls + \IfFileExists{\gmcc@baseclass.cls}{}{\gmcc@mwclsfalse}% As + % announced, we do the ontological test to any \pk{mwcls}. +\fi +\ifgmcc@mwcls + \LoadClass[fleqn, oneside, noindentfirst, 11pt, withmarginpar, + sfheadings]{\gmcc@baseclass}% +\else + \LoadClass[fleqn, 11pt]{article}% Otherwise the standard \pk{article} is + % loaded. +\fi + +\AtBeginDocument{\mathindent=\CodeIndent} +% The |fleqn| option makes displayed formuals be flushed left and +% |\mathindent| is their indentation. Therefore we ensure it is always +% equal |\CodeIndent| just like |\leftskip| in \env{verbatim}. Thanks +% to that you may display single verbatim lines with |\[...\]|: +% \[\hbox{\verb+\[\hbox{|\verbatim\stuff|}\]+\,.}\] + +\IfFileExists{lmodern.sty}{% We also examine the ontological status of + % this package + \RequirePackage{lmodern}% and if it shows to be satisfactory (the + % package shows \emph{to be}), we load it and set the proper + % font encoding. + \RequirePackage[QX]{fontenc}% +}{} +%\iffalse\iffalse +\fi +% of ifSecondClass (a~feature under construction).\fi + +\RequirePackage[margin=2.7cm, left=4cm, + right=2.2cm]{\gmTheGeometry}% Now we set the +% page layout. + +\def\gmdoccMargins{% + \geometry{margin=2.7cm, left=4cm, right=2.2cm}} + +\if@debug% For debugging we load also the \pk{trace} package that was +% very helpful to me. + \RequirePackage{trace}% + \errorcontextlines=100 % And we set an error info parameter. +\fi + +%\CodeDefine\ifdtraceon +%\CodeDefine\ifdtraceoff +\newcommand*\ifdtraceon{\if@debug\afterfi\traceon\fi} +\newcommand*\ifdtraceoff{\if@debug\traceoff\fi} + +% We load the core package: +\RequirePackage{gmdoc} + +\@ifpackageloaded{lmodern}{% The Latin Modern font family provides + % a~light condensed typewriter font that seems to be the most + % suitable for the marginpar CS marking. + \def\marginpartt{\normalfont\fontseries{lc}\ttfamily}}% + + +% ^^A\setcounter{IndexColumns}{2} narrow columns do spare space and +% ^^A~look better +\raggedbottom + +\setcounter{secnumdepth}{0}% We wish only the parts and chapters to be +% numbered. + +\renewcommand*\thesection{\arabic{section}}% isn't it redundant at the +% above setting? + +\@ifnotmw{}{% + \@ifclassloaded{mwart}{% We set the indentation of Contents: + \SetTOCIndents{{}{\quad}{\quad}{\quad}{\quad}{\quad}{\quad}}}{% for \pk{mwart} + \SetTOCIndents{{}{\bf9.\enspace}{\quad}{\quad}{\quad}{\quad}{\quad}}}% and for the two other \pk{mwcls}s. + \pagestyle{outer}}% We set the page numbers to be printed in the + % outer and bottom corner of the page. + +\def\titlesetup{\bfseries\sffamily}% We set the title(s) to be +% boldface and sans serif. + +\if@gmccnochanges\let\RecordChanges\relax\fi% If the |nochanges| +% option is on, we discard writing outto the \file{.glo} file. + +\RecordChanges% We turn the writing the |\changes| outto the +% \file{.glo} file if not the above. + +% \CodeUsgIndex\dekclubs \CodeUsgIndex\smartunder +\dekclubs% We declare the club sign \verb+|+ to be a~shorthand for |\verb*| +\smartunder% and we declare the |_| char to behave as usual in the +% math mode and outside math to be just an uderscore. + +\exhyphenpenalty\hyphenpenalty% 'cause \pk{mwcls} set it |=10000| due +% to Polish customs. + +\RequirePackage{amssymb} +\def\EOFMark{\rightline{\ensuremath{\square}}} + + +\endinput +% \changes{v0.677}{06/9/23}{Added checkings if \pk{mwart.cls} and +% \pk{lmodern.sty} are available and more standard behaviour if they +% are not} +% +% \changes{v0.70}{06/10/10}{Added some options and Latin Modern Light +% Condensed to the marginpar CSs.} +% +% \Finale + +% (For my GNU Emacs:) +%%% Local Variables: +%%% mode: latex +%%% TeX-master: "e:/LaTeX/TeXGuru/gmdoc/gmdocDoc" +%%% End: -- cgit v1.2.3