%
% \GetFileInfo{gmdoc.sty}
% \title{The \pk{gmdoc.sty} Package\thfileinfo}
% \author{Natror (Grzegorz Murzynowski)}
% \date{\today}
% \maketitle
% \label{gmd}
%% 
%% This is (a~documentation of) file \pk{gmdoc.sty},
%% intended to be used with \LaTeXe\ as a~package for
%% documenting \LaTeXpar\ files and to be documented with itself. 
%% \stanza
%% 
% \begin{copyrnote}
%
%% Written by Natror (Grzegorz Murzynowski),
%% natror at o2 dot pl
%%
%% \copyright\,2006, 2007, 2008 by Natror (Grzegorz Murzynowski).
%%
%% This program is subject to the \LaTeX\ Project Public License.
%% See \url{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html} ^^A
%% for the details of that license.
%%
%% \acro{LPPL} status: "author-maintained".\par
%%
%% Many thanks to my \TeX\ Guru Marcin Woli\nacute ski for his \TeX nical ^^A
%% support.
%
%\end{copyrnote}
%
% \ChangesStart{v0.98c}{1000/0/0}
%
% \chschange{v0.96}{2006/08/22}{2395}
% \chschange{v0.97}{06/09/04}{3636}
% \chschange{v0.98}{06/09/04}{3636}
% \chschange{v0.98a}{06/09/06}{4092}
% \chschange{v0.98b}{06/9/7}{4119}
% \chschange{v0.98c}{06/9/10}{4299}
% \chschange{v0.98d}{06/9/15}{4409}
% \chschange{v0.98e}{06/9/23}{4420}
% \chschange{v0.98f}{06/9/30}{4430}
% \chschange{v0.98g}{06/10/5}{4294}
% \chschange{v0.98i}{06/10/14}{4352}
% \chschange{v0.98j}{06/10/17}{4372}
% \chschange{v0.98k}{06/10/21}{4416}
% \chschange{v0.98l}{06/10/27}{4401}
% \chschange{v0.98m}{06/11/14}{4349}
% \chschange{v0.99}{06/11/29}{4462}
% \chschange{v0.99a}{2006/12/01}{4479}
% \chschange{v0.99b}{07/01/01}{4479}
% \chschange{v0.99c}{07/3/2}{4486}
% \chschange{v0.99c}{07/3/30}{4475}
% \chschange{v0.99d}{07/4/26}{4555}
% \chschange{v0.99e}{2007/4/29}{4574}
% \chschange{v0.99g}{2007/11/12}{5229}
% \chschange{v0.99i}{2008/8/3}{5247}
% \chschange{v0.99j}{2008/8/3}{5266}
% \chschange{v0.99k}{2008/8/4}{5261}
% \chschange{v0.99l}{2008/8/6}{5225}
% \chschange{v0.99m}{2008/8/9}{5356}
% \chschange{v0.99m}{2008/8/13}{5354}
% \chschange{v0.99n}{2008/8/22}{5409}
% \chschange{v0.99n}{2008/8/30}{5547}
% \chschange{v0.99p}{2008/10/4}{5607}
% \chschange{v0.99q}{2008/10/10}{5603}
% \chschange{v0.99r}{2008/11/22}{5607}
% \toCTAN{v0.99r}{2008/11/22}
%
%
\ifnum\catcode`\@=11 % Why this test here---will come out in chapter
% \gmiflink{The driver}. ^^A~( the very first line
% ^^A and about coming out already! ;-)
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{gmdoc}
         [2008/11/22 v0.99r a documenting package (GM)]
\fi
% 
%
%
% \CharacterTable {In my \TeX\ Guru's opinion the idea of
%   checking of the correctness of chars is a~bit obsolete
%   nowadays. Therefore I~define the \CharacterTable<#1>
%   macro to gobble its argument and to typeout a~request
%   for request.}
%
%
% \newcommand*\docfm{\pk{doc}}
% \newcommand*\gmdoc{\pk{gmdoc}}
%
% \tableofcontents
%
%
% \division{Readme}
%
%   This package is a~tool for documenting of \LaTeXpar\
%   packages, classes etc., i.e., the \file{.sty}, \file{.cls} files
%   etc. The author just writes the code and adds the commentary 
%   preceded with |%| sign (or another properly declared). No special
%   environments are necessary.
%
%   The package tends to be (optionally) compatible with the standard
%   \pk{doc.sty} package, 
%   i.e., the \file{.dtx} files are also compilable with \pk{gmdoc}
%   (they may need very little adjustment, in some rather special
%   cases).
%
%   The tools are integrated with \pk{hyperref}'s advantages such as
%   hyperlinking of index entries, contents entries and
%   cross-references.
%
%   The package also works with \XeTeX\ (switches automatically).
%
% \begin{gmlonely}
%   \subdivision{Installation} Unpack the \file{gmdoc-tds.zip} archive
%   (this is an archive conforming the \acro{TDS} standard, see
%   \file{CTAN/tds/tds.pdf})% in a~\file{texmf} directory
%   or put the \pk{gmdoc.sty}, \pk{gmdocc.cls} and \pk{gmoldcomm.sty}
%   somewhere in the \file{texmf/tex/latex} branch on your own.
%   (Creating a~\file{texmf/tex/latex/gm} directory may be
%   advisable if you consider using other packages written by me. And
%   you \emph{have} to use four of them to make \pk{gmdoc} work.)
%
%   You should also install \pk{gmverb.sty}, \pk{gmutils.sty} and
%   \pk{gmiflink.sty} (e.g., put them into the same \file{gm}
%   directory). These packages are available on \acro{CTAN} as separate
%   \file{.zip} archives also in \acro{TDS}-compliant \pk{zip}
%   archives.
%
%   Moreover, you should put the \file{gmglo.ist} file, a MakeIndex
%   style for the changes' history, into some \file{texmf/makeindex}
%   (sub)directory.
%
%   Then you should refresh your \TeX\ distribution's files' database
%   most probably.
% \end{gmlonely}
%
%
% \subdivision{Contents of the \pk{gmdoc.zip} archive}
%
% The distribution of the \pk{gmdoc} package consists of the
% following five files and a~\acro{TDS}-compliant archive.
% \begin{verse}
%   \pk{gmdoc.sty}\\
%   \pk{gmdocc.cls}\\
%   \pk{gmglo.ist}\\
%   \pk{README}\\
%   \pk{gmdoc.pdf}\\
%   \pk{gmdoc.tds.zip}
% \end{verse}
%
% 
% \begin{gmlonely}
%   \subdivision{Compiling of the documentation}
%
%   The last of the above files (the \pk{.pdf}, i.e., \emph{this ^^B
%     file}) is a~documentation compiled from the \pk{.sty} and
%   \pk{.cls} files by running \XeLaTeX\ on the \file{gmdoc.sty}
%   twice (|xelatex gmdoc.sty| in the directory you wish the
%   documentation to be in, you don't have copy the \file{.sty} file
%   there, \TeX\ will find it), then MakeIndex on the \file{gmdoc.idx} and
%   \file{gmdoc.glo} files, and then \XeLaTeX\ on \file{gmdoc.sty}
%   once more. (Using \LaTeX\ instead  of \XeLaTeX\ should do, too.)
%
%   MakeIndex shell commands:
%\begin{verbatim}
%makeindex -r gmdoc
%makeindex -r -s gmglo.ist -o gmdoc.gls gmdoc.glo
%\end{verbatim}
%   The |-r| switch is to forbid MakeIndex to make implicit ranges since
%   the (code line) numbers will be hyperlinks.
%
%   Compiling the documentation requires the packages:
%   \pk{gmdoc} (\pk{gmdoc.sty} and \pk{gmdocc.cls}), \pk{gmutils.sty},
%   \pk{gmverb.sty}, \pk{gmiflink.sty} and also some standard packages:
%   \pk{hyperref.sty}, \pk{xcolor.sty}, \pk{geometry.sty},
%   \pk{multicol.sty}, \pk{lmodern.sty}, \pk{fontenc.sty} that should
%   be installed on your computer by default.
%
%   If you had not installed the \pk{mwcls} classes (available on
%   \acro{CTAN} and present in \TeX\ Live e.g.), the result of your
%   compilation might differ a~bit from the \pk{.pdf} provided in this
%   \pk{.zip} archive in formatting: If you had not installed
%   \pk{mwcls}, the standard \pk{article.cls} class would be used.
% \end{gmlonely}
%
% \subdivision{Dependencies}
%
% The \pk{gmdoc} bundle depends on some other packages of mine:
% \begin{verse}
%   \pk{gmutils.sty},\\
%   \pk{gmverb.sty},\\
%   \pk{gmiflink.sty}\\
%   \pk{gmeometric} (for the driver of The \LaTeXe\ Source)\\
% \end{verse}
% and also on some standard packages:
% \begin{verse}
%   \pk{hyperref.sty},\\
%   \pk{color.sty},\\
%   \pk{geometry.sty},\\
%   \pk{multicol.sty},\\
%   \pk{lmodern.sty},\\
%   \pk{fontenc.sty}\\
% \end{verse}
% that should
%   be installed on your computer by default.
%
%^^A\traceon
% % \subdivision{Bonus: \file{base} drivers}
%^^A\traceoff 
% As a~bonus and example of \docfm-compatibility 
% there are driver files included
% (cf.\ Palestrina, \textit{Missa papae Marcelli} ;-):
%
% \begin{verse}
%   \pk{source2e_gmdoc.tex}\\
%   \pk{docstrip_gmdoc.tex}\\
%   \pk{doc_gmdoc.tex}
%
%   \pk{gmoldcomm.sty}\\
%   (\pk{gmsource2e.ist} is generated from \pk{source2e_gmdoc.tex})\\
% \end{verse}
%
% These drivers typeset the respective files from the
%\[\hbox{\file{…/texmf-dist/source/latex/base}}\]
% directory of the \TeX Live2007 distribution (they only read that
% directory).
%
% Probably you should redefine the |\BasePath| macro in them
% so that it points that directory on your computer.
%
%
%\division*{Introduction}
%
% There are very sophisticated and effective tools for documenting
% \LaTeX\ macro packages, namely the \pk{doc} package and the
% \pk{ltxdoc} class.
% Why did I~write another documenting package then? 
%
% I~like comfort and \pk{doc} is not comfortable enough for me. It
% requires special marking of the macro code to be properly typeset
% when documented. I~want \TeX\ to know `itself' where the code begins
% and ends, without additional marks. 
%
% That's the difference. One more difference, more important for the
% people for whom the \docfm's conventions are acceptable, is that
% \gmdoc\ makes use of \pk{hyperref} advantages and makes
% a~hyperlinking index and toc entries and the
% cross-references, too. (The \CSs in the code maybe in the future.) 
%
% The rest is striving to level the very high \pk{doc/ltxdoc}'s
% standard, such as (optional) numbering of the codelines and
% authomatic indexing the control sequences e.g.
%
% The \docfm\ package was and still is a~great inspiration for me and
% I~would like this humble package to be considered as a~sort of
% hommage to it\footnote{As Grieg's Piano Concerto is a~hommage to ^^B
%   the Schumann's.}. If I~mention copying some code or narrative but do
% not state the source explicitly, I~mean the \docfm\ package's
% documentation (I~have v2.1b dated 2004/02/09).
%
%
%
% \division{The user interface}
%
%
% \subdivision{Used terms}
%
% When I~write of a~\textbf{macro}, I~mean a~macro in \TeXbook's
% meaning, i.e., a~control sequence whose meaning is
% |\(e/g/x)def|ined. By a~\textbf{macro's parameter} I~mean each of
% |#|\<digit>s in its definition. When I~write about ^^A\)
% a~\textbf{macro's argument}, I~mean the value (list of tokens)
% subsituting the corresponding parameter of this macro. 
% (These understandings are according ^^A(
% to \TeXbook, I~hope: \TeX\ is a~religion of Book ;-)\,.)
%
% I'll use a~shorthand for `control sequence', \textbf{\CS}. 
%
% When I~talk of a~\textbf{declaration}, I~mean a~macro that expands
% to a~certain assignment, such as |\itshape| or
% |\@onlypreamble{|\<\CS>|}|.
%
% Talking of declarations, I'll use the \textbf{\acro{OCSR}} acronym as
% a~shorthand for 'observes/ing common \TeX\ scoping rules'.
%
% By a~\textbf{command} I~mean a~certain abstract visible to the end
% user as a~\CS but consisting possibly of more than one macro. I'll
% talk of a~\textbf{command's argument} also in
% the `sense\:-for\:-the\:-end\:-user', e.g., I'll talk of the
% |\verb| \emph{command's} argument although \emph{the macro}
% |\verb| has no |#|\<digit> in its definition.
%
% The \textbf{code} to be typeset verbatim (and with all the bells
% and whistles) is everything that's not commented out in the source
% file and what is not a~leading space(s).
% 
% The \textbf{commentary} or \textbf{narrative} is everything after
% the comment char till the end of a~line. The \textbf{comment char}
% is a~character the |\catcode| of which is 14 usually i.e., when the
% file works; if you don't play with
% the |\catcode|s, it's just the |%|. When the file is documented with
% \gmdoc, such a~char is re|\catcode|d and its r\ocircum le is else: it
% becomes the \textbf{code delimiter}.
%
% A~line containing any \TeX\ code (not commented out) will be called
% a~\textbf{codeline}. A~line that begins with (some leading spaces
% and) a~code delimiter will be called a~\textbf{comment line} or
% \textbf{narration line}. 
%
% The \textbf{user} of this package will also be addressed
% as \textbf{you}.\stanza
%
% Not to favour any particular gender (of the amazingly rich variety,
% I~mean, not of the vulgarly simplified two-element set), in this
% documentation I~use alternating pronouns of third person ^^A(
% (\TextUsage\heshe\ etc. commands provided by \pk{gmutils}), so let
% one be not surprised if `\heshe' sees `\himher self' altered in the
% same sentence :-)\,.
% 
%
% \subdivision{Preparing of the source file}
%
% When \LaTeXpar\ with \pk{gmdoc.sty} package loaded typesets the
% comment lines, the code delimiter is ommitted. If the comment
% continues a~codeline, the code delimiter is printed. It's done so
% because ending a~\TeX\ code line with a~|%| is just a~concatenation
% with the next line sometimes. Comments longer than one line are
% typeset continuously with the code delimiters ommitted.
%
% The user should just write \hisher\ splendid code and brilliant
% commentary. In the latter \heshe\ may use usual \LaTeXpar\ commands.
% The only requirement is, if an argument is divided in two lines, to
% end such a~dividing line with \TextUsage*{\^^M} (|\|\<line end>) or with
% \TextUsage*{^^B} sequence that'll enter the (active) \<char2> which
% shall gobble the line end.  ^^A~and the leading code delimiter of
%^^A % the next line---obsoleted by ^^A~making % ignored in the commentary.
%
% Moreover, if \heshe\ wants to add a~meta-comment i.e., a~text that
% doesn't appear in the code layer nor in the narrative, \heshe\ may
% use the \TextUsage*{^^A} sequence that'll be read by \TeX\ as
% \<char1>, which 
%  in \gmdoc\ is active and defined to gobble the stuff between itself
% and the line end. 
%
% Note that |^^A| behaves much like comment char
% although it's active in fact: it re|\catcode|s the special
% characters including |\|, |{| and |}|
% so you don't have to worry about unbalanced braces or \cs{if}s in
% its scope. But |^^B| doesn't re|\catcode| anything (it would be
% useless in an argument) so any text between |^^B| and line end has
% to be balanced.
% 
% However, it may be a~bit confusing
% for someone acquainted with the \docfm\ conventions. If you don't
% fancy the |^^B| special sequence, instead you may restore the
% standard meaning of the line end with the \TextUsage\StraightEOL\
% declaration which
% \acro{OCSR}. As almost all the control
% sequences, it may be used also as an environment, i.e.,
% |\begin{StraightEOL}|\ \dots\ |\end{StraightEOL}|. However, if for any
% reason you don't want to make an environment (a~group), there's
% a~|\StraightEOL|'s counterpart, the \TextUsage\QueerEOL\ declaration that
% restores again the 
% \StraightEOL
% queer\footnote{In my understanding
%   `queer' and `straight' are not the opposites excluding each
%   other but the counterparts that may cooperate in harmony for
%   people's good. And, as I~try to show with the \cs{QueerEOL} and
%   \cs{StraightEOL} declarations, `queer' may be very useful and
%   recommended while `straight' is the standard but not necessarily
%   normative. ^^A% (Remember also Alice's in the Wonderland exclamations
%   ^^A %   ``What a~queer day is today''.)
% }^^A
% \QueerEOL
% \gmdoc's meaning of the line end. It \acro{OCSR}, too.  One more point to use
% |\StraightEOL| is where you wish some code lines to be executed
% both while loading the file and during the documentation pass
% (it's analogous to \docfm's not embracing some code lines in
% a~\env{macrocode} environment).
%
% \stanza
%
% As in standard \TeX ing, one gets a~paragraph by a~blank line.
% Such a~line should be |%|ed of course. A~fully blank line is
% considered a~blank \emph{code line} and hence results in
% a~vertical space in the documentation. As in the environments for
% poetry known to me, subsequent blank lines do not increase such
% a~space.
%
% Then \heshe\ should prepare a~main document file,
% a~\textbf{driver} henceforth, to set all the
% required formattings such as |\documentclass|, paper size
% etc., and load this package with a~standard command
% i.e., |\usepackage{gmdoc}|, just as \docfm's documentation says:
%
% \begin{quotation}
%   If one is going to document a set of macros with the \pk{[gm]doc}
%   package one has to prepare a special driver file which produces
%   the formatted document. This driver file has the following
%   characteristics: \par\leftskip\CodeIndent
%   \stanza
%
%   \noindent|\documentclass[|\<options>|]{|\<document-class>|}|\par
%   \noindent|\usepackage[|\<options, probably none>|]{gmdoc}|\par
%   \<preamble>\par
%   \noindent|\begin{document}|\par
%     \<special input commands>\par
%     \noindent|\end{document}|\par
% \end{quotation}
%
%
% \subdivision{The main input commands}
%
% To typeset a~source file you may use the \TextUsage\DocInput\
% macro that takes the (path and) name of the file \emph{with ^^B
%   the extension} as the only argument, e.g.,
% |\DocInput{mybrilliantpackage.sty}|.
%
% (Note that an \emph{installed} package or class file is findable to
% \TeX\ even if you don't specify the path.)
%
% If a~source file is written with rather \docfm\ than \gmdoc\ in
% mind, then the \TextUsage\OldDocInput\ command may be more
% appropriate (e.g., if you break the arguments of commands in the
% commentary in lines). It also takes the file (path and) name as the
% argument. 
%
% When using |\OldDocInput|, you have to wrap all the code in
% \TextUsage*{macrocode} environments, which is not necessary when you
% use |\DocInput|. Moreover, with |\OldDocInput| the\
% \env{mac\-ro\-co\-de(*)} environments require to be ended with
% |%    \end{macrocode(*)}| as in \docfm. (With |\DocInput| you are
% not obliged to precede |\end{macrocode(*)}| with The
% Four Spaces.)
%
% \stanza
% If you wish to document many files in one document, you are
% provided \TextUsage\DocInclude\ command, analogous to \LaTeX's
% |\include| and very likely to \pk{ltxdoc}'s command of the same
% name. In \gmdoc\ it has one mandatory argument that should be the
% file name \emph{without extension}, just like for |\include|.
%
% The file extensions\label{docinclude:extensions} supported by
% |\DocInclude| are \pk{.fdd}, \pk{.dtx}, \pk{.cls}, \pk{.sty},
% \pk{.tex} and \pk{.fd}. The macro looks for one of those extensions
% in the order just given. If you need to document files of other
% extensions, please let me know and most probably we'll make it
% possible.
%
% |\DocInclude| has also an optional first argument that is intended
% to be the path of the included file with the levels separated by |/|
% (slash) and also ended with a~slash. The path given to |\DocInclude| as
% the first and optional argument will not appear in the headings nor
% in the footers. 
%
% |\DocInclude| redefines \TextUsage\maketitle\ so
% that it makes a~chapter heading or, in the classes that don't
% support |\chapter|, a~part heading, in both cases with
% respective toc entries. The default assumption is that all the
% files have the same author(s) so there's no need to print them in
% the file heading. If you wish the authors names to be printed, you
% should write \TextUsage\PrintFilesAuthors\ in the preamble or before
% the relevant |\DocInclude|s. If you wish to undeclare printing the
% authors names, there is \TextUsage\SkipFilesAuthors\ declaration.
%
% Like in \pk{ltxdoc}, the name of an included file appears in the
% footer of each page with date and version info (if they are
% provided).
%
% The |\DocInclude|d files are numbered with the letters, the
% lowercase first, as in \pk{ltxdoc}. Such a~filemarker also precedes
% the index entries, if the (default) codeline index option is in force.
%
% As with |\include|, you may declare
% \TextUsage\includeonly|{|\<filenames separated by commas>|}| for
% the draft versions.
%
% \stanza If you want to put the driver into the same \file{.sty} or
% \file{.cls} file (see chapter \ref{Driver} to see how), you may
% write |\DocInput{\jobname.sty}|, or |\DocInclude{\jobname.sty}|, but
% there's also a~shorthand for the latter \TextUsage\SelfInclude \
% that takes no arguments.
% By the way, to avoid an infinite recursive input of \file{.aux}
% files in the case of self-inclusion an \file{.auxx} file is used
% instead of (main) \file{.aux}. 
% \stanza
% 
% At the default settings, the |\Doc/SelfInclude|d files constitute
% chapters if |\chapter| is known and parts otherwise. The
% |\maketitle|s of those files result in the respective headings.
%
% If you prefer more \pk{ltxdoc}ish look, in which the files always
% constitute the parts and those parts have a~part's title
% pages with the file name and the files' |\maketitle|s result in
% (article-like) titles not division headings, then you are provided
% the \TextUsage\ltxLookSetup\ declaration (allowed only in the
% preamble). However, even after this declaration the files will be
% included according to \gmdoc's rules not necessarily to the \docfm's
% ones (i.e., with minimal marking necessary at the price of active
% line ends (therefore not allowed between a~command and its argument
% nor inside an argument)).
%
% On the other hand, if you like the look offered by me but you have
% the files prepared for \docfm\ not for \gmdoc, then you
% should declare \TextUsage\olddocIncludes. Unlike the previous one,
% this may be used anywhere, because I~have the account of including both
% \docfm-like and \gmdoc-like files into one document. This
% declaration just changes the internal input command and doesn't
% change the sectioning settings.
%
% It seems possible that you wish to document the `old-doc' files
% first and the `new-doc' ones after, so the above declaration has its
% counterpart, \TextUsage\gmdocIncludes, that may be used anywhere,
% too. Before the respective |\DocInclude|(s), of course.
%
% Both these declarations \acro{OCSR}.
%
% If you wish to document your files as with \pk{ltxdoc} \emph{and}
% as with \docfm, you should declare
% |\ltxLookSetup| in the preamble \emph{and} |\olddocIncludes|.
%
% \stanza
% Talking of analogies with \pk{ltxdoc}, if you like only the page
% layout provided by that class, there is the
% \TextUsage\ltxPageLayout\ declaration (allowed only in preamble)
% that only changes the margins and the text width (it's intended to
% be used with the default paper size). This declaration is
% contained in the |\ltxLookSetup| declaration.
%
% \stanza
% If you need to add something at the beginning of the input of file,
% there's the \TextUsage\AtBegInput\ declaration that takes one
% mandatory argument which is the stuff to be added. This declaration
% is global. It may be used more than one time and the arguments of
% each occurrence of it add up and are put at the beginning of input
% of every subsequent files. 
%
% Simili modo, for the end of input, there's the
% \TextUsage\AtEndInput\  declaration, also one-argument, global and
% cumulative.
%
% If you need to add something at the beginning of input of only one
% file, put before the respective input command an
% \TextUsage\AtBegInputOnce|{|\<the stuff to be added>|}|
% declaration. It's also global which means that the groups do not
% limit its scope but it adds its argument only at the first input
% succeding it (the argument gets wrapped in a~macro that's |\relax|ed 
% at the first use). |\AtBegInputOnce|s add up, too.
%
% \stanza
% One more input command is \TextUsage\IndexInput\ (the name and idea
% of effect comes from \docfm). It takes the same argument as
% |\DocInput|, the file's (path and) name with extension. (It
% \emph{has} |\DocInput| inside). It works properly if the input file
% doesn't contain explicit \<char1> (|^^A| is \acro{OK}). 
%
% The effect of this command is typesetting of all the input file
% verbatim, with the code lines numbered and the \CSs automatically
% indexed (\pk{gmdoc.sty} options are in force).
%
%
% \subdivision{Package options}
%
% As many good packages, this also provides some options:
% \stanza
%
% Due to best \TeX\ documenting traditions the codelines will be
% numbered. But if the user doesn't wish that, \heshe\ may turn it off
% with the \TextUsage*{linesnotnum} option.
%
% However, if \heshe\ agrees to have the lines numbered, \heshe\ may wish
% to reset the counter of lines \himher self, e.g., when \heshe\
% documents many source files in one document. Then \heshe\ may wish
% the line numbers to be reset with every |{section}|'s turn for
% instance. This is the r\ocircum le of the \TextUsage*{uresetlinecount}
% option, which seems to be a~bit obsolete however, since the
% \TextCommonIndex\DocInclude|\DocInclude| command takes care of
% a~proper reset.
%
% Talking of line numbering further, a~tradition seems to exist to
% number only the codelines and not to number the lines of
% commentary. That's the default behaviour of \pk{gmdoc} but, if
% someone wants the comment lines to be numbered too, which may be
% convenient for reference purposes, \heshe\ is
% provided the \TextUsage*{countalllines} option. This option switches
% things to use the \cs{inputlineno} primitive for codeline numbers so
% you get the numbers of the source file instead of number only of the
% codelines. Note however, that there are no hypertargets made to the
% narration lines and the value of \cs{ref} is the number of the most
% recent codeline. 
%
% Moreover, if \heshe\ wants to get the narration lines' number
% printed, there is the starred version of that option,
% \TextUsage*{countalllines*}. I~imagine someone may use it for
% debug. This option is not finished in details, it causes errors with
% \cs{addvspace} because it puts a~hyperlabel at every line.  When it
% is in force, all the index entries are referenced 
% with the line numbers and
%% ^^A(
% {\LineNumFont 441}\, the narration acquires a~bit biblical look ;-),
% {\LineNumFont 442}\,as shown in this short example. This option is intended
% {\LineNumFont 443}\,for the draft versions and it is not perfect (as if anything
% {\LineNumFont 444}\,in this package was). As you see, the lines 
% {\LineNumFont 445}\,are typeset continuously with the numbers printed.
%
% \stanza
% By default the \pk{makeidx} package is loaded and initialized and
% the \CSs occurring in the code are automatically
% (hyper)indexed thanks to the \pk{hyperref} package. If the user
% doesn't wish to index anything, she should use the
% \TextUsage*{noindex} option.
%
% The index comes two possible ways: with the line numbers (if the
% lines are numbered) and that's the default, or with the page numbers, if
% the \TextUsage*{pageindex}\label{indexoptions} option is set.
%
% The references in the change history are of the same: when index is
% line number, then the changes history too.
%
% \stanza
% By default, \gmdoc\ excludes some 300 \CSs from being indexed.
% They are the most common \CSs, \LaTeX\ internal
% macros and \TeX\ primitives. To learn what \CSs are
% excluded actually, see lines \ref{DIE1}--\ref{DIE2}.
%
% If you don't want all those exclusions, you may turn them off with
% the \TextUsage*{indexallmacros} option. 
%
% If you have ambiguous feelings about whether to let the default
% exclusions or forbid them, see p.\,\pageref{IEIDeclarations} to
% feed this ambiguity with a~couple of declarations.
%
% \stanza
% In \docfm\ package there's a~default behaviour of putting marked
% macro's or environment's name to a~marginpar. In the standard
% classes it's allright but not all the classes support marginpars.
% That is the reason why this package enables marginparing when in
% standard classes, enables or disables it due to the respective option
% when with Marcin Woli\nacute ski's classes and in any case provides the
% options \TextUsage*{withmarginpar} and \TextUsage*{nomarginpar}. So, in
% non-standard classes the default behaviour is to disable marginpars.
% If the marginpars are enabled in \pk{gmdoc}, it will put marked
% control sequences and environments into marginpars (see
% \gmiflink[textUsage]{\cs{TextUsage} etc.}). These options do
% not affect common using marginpars, which depends on the
% documentclass.
%
% \stanza
% My suggestion is to make the spaces in the code visible except the
% leading ones and that's the default. But if you wish all the code
% spaces to be blank, I~give the option \TextUsage*{codespacesblank}
% reluctantly. Moreover, if you wish the code spaces to be blank only
% in some areas, then there's \TextUsage\CodeSpacesBlank\ declaration
% (\acro{OCSR}).
%
% Another space formatting option is \TextUsage*{codespacesgrey}
% suggested by Will Robertson. It makes the spaces of code visible
% only not black but grey. The name of their colour is
% |visspacesgrey| and by default it's defined as |{gray}{.5}|, you
% can change it with \pk{xcolor}'s |\definecolor|. There is also an
% \acro{OCSR} declaration \TextUsage\CodeSpacesGrey.
%
% If for any reason you wish the code spaces blank in general and
% visible and grey in \env{verbatim*}s, use the declaration
% \TextUsage\VisSpacesGrey\ of the \pk{gmverb} package. If you like
% a~little tricks, you can also specify
% |codespacesgrey, codespacesblank| in \pk{gmdoc} options (in this
% order). 
%
% \subdivision{The packages required}
%
% \pk{gmdoc} requires (loads if they're not loaded yet) some other
% packages of mine, namely \pk{gmutils}, \pk{gmverb}, analogous to
% Frank Mittelbach's \pk{shortvrb}, and \pk{gmiflink} for conditional
% making of hyperlinks. It also requires \pk{hyperref},
% \pk{multicol}, \pk{color} and \pk{makeidx}. 
%
% The \pk{gmverb}\gmdmarginpar{\pk{gmverb}} package redefines the
% |\verb| command and the \env{verbatim} environment in such a~way that 
% | |, |{| and |\| are breakable, the first with no `hyphen' and the
%   other two with the comment char as a~hyphen, i.e.,
%   |{|\<subsequent text>|}| breaks into 
%     |{%|\\ \<subsequent text>|}| ^^A] bal. braces for Emacs
%       and \<text>|\mylittlemacro| breaks into \<text>|%|\\
%       |\mylittlemacro|.
%
% As the standard \LaTeX\ one, my |\verb| issues an error when a~line
% end occurs in its scope. But, if you'd like to allow line ends in
% short verbatims, there's the \TextUsage\verbeolOK\ declaration.  The
% plain |\verb| typesets spaces blank and |\verb*| makes them visible,
% as in the standard version(s).
%
% Moreover, \pk{gmverb} provides the \TextUsage\MakeShortVerb\
% declaration 
% that takes a~one-char control sequence as the only argument and
% turns the char used into a~short verbatim delimiter, e.g., after
% \[\verb+\MakeShortVerb*\|+\]
% (as you see, the declaration has the starred version, which is for
% visible spaces, and non-starred for blank spaces) to get
% |\mylittlemacro| you may type \verb+|\mylittlemacro|+ instead of
% |\verb+\mylittlemacro+|. Because the char used in the last example
% is my favourite and is used this way by DEK in \TeXbook's
% format, \pk{gmverb} provides a~macro \TextUsage\dekclubs\ that
% expands to the example displayed above.
%
% Be careful because such active chars may interfere with other
% things, e.g., the \verb+|+ with the vertical line marker in \env{tabular}s and
% with the \pk{tikz} package. If this happens, you can declare e.g.,
% \TextUsage\DeleteShortVerb\verb+\|+ and the previous meaning of the
% char used shall be restored.
%
% One more difference between \pk{gmverb} and \pk{shortvrb} is that
% the chars |\active|ated  by |\MakeShortVerb|, behave as if they were
% `other' in math mode, so you may type e.g., \verb+$k|n$+ to get
% $k|n$ etc.
% \stanza
%
% The \pk{gmutils}\gmdmarginpar{\pk{gmutils}} package provides a~couple of
% macros similar to some basic \LaTeXpar\ ones, rather strictly
% technical and (I~hope) tricky, such as |\afterfi|, |\ifnextcat|,
% |\addtomacro| etc. It's this package that provides the macros for
% formatting of names of macros and files, such as |\cs|, |\marg|, |\pk|
% etc.  \stanza
% 
% The \gmdoc\ package uses a~lot of hyperlinking possibilities
% provided by \pk{hyperref}\gmdmarginpar{\pk{hyperref}} which is therefore
% probably the most important package required. The recommended
% situation is that the user loads \pk{hyperref} package with \hisher\
% favourite options \emph{before} loading \pk{gmdoc}.
%
% If \heshe\ does not, \pk{gmdoc} shall load it with \emph{my}
% favourite options. 
%
% To avoid an error if a~(hyper)referenced label does not exist,
% \pk{gmdoc} uses the \pk{gmiflink}\gmdmarginpar{\pk{gmiflink}}
% package. It works e.g., in the index when the codeline numbers have
% been changed: then they are still typeset, only not as hyperlinks
% but as a~common text.
%
% \stanza
% To typeset the index and the change history in balanced columns
% \gmdoc\ uses the \gmdmarginpar{\pk{multicol}}\pk{multicol} package
% that seems to be standard these days.
%
% Also the \gmdmarginpar{\pk{color}}\pk{multicol} package, required to
% define the default colour of the hyperlinks, seems to be standard
% already, and \pk{makeidx}.
%
% \subdivision[Automatic marking of definitions]{^^B
%   \gmhypertarget{Automatic marking of definitions}}
% \gmdoc\ implements automatic detection of a~couple of
% definitions. By default it detects all occurrences of the following
% commands in the code:
%\begin{enumerate}^^B
%\item \label{def type}
% |\def|,
% |\newcount|,
% |\newdimen|,
% |\newskip|,
% |\newif|,
% |\newtoks|,
% |\newbox|,
% |\newread|,\\
% |\newwrite|,
% |\newlength|,
% |\newcommand(*)|,
% |\renewcommand(*)|,
% |\providecommand(*)|,
% |\DeclareRobustCommand(*)|,
% |\DeclareTextCommand(*)|,\\
% |\DeclareTextCommandDefault(*)|,
% |\DeclareDocumentCommand|,
%
% \item 
% |\newenvironment(*)|,
% |\renewenvironment(*)|,
% |\DeclareOption(*)|,
%^^A~ |%\DeclareDefining*\@namedef|
%
% \item \label{newctr}
% |\newcounter|,
%
% \xdef\gmdenumi{\arabic{enumi}}
% \end{enumerate}
%
% of the \pk{xkeyval} package:
% \begin{enumerate}\setcounter{enumi}{\gmdenumi}^^B
% \item\label{dk type} |\define@key|,
% |\define@boolkey|,
% |\define@choicekey|,
% |\DeclareOptionX|,
%
% \xdef\gmdenumi{\arabic{enumi}}
% \end{enumerate}
%
% and of the \pk{kvoptions} package:
% \begin{enumerate}\setcounter{enumi}{\gmdenumi}^^B
% \item \label{DSOption}
% |\DeclareStringOption|,
% |\DeclareBoolOption|,
% |\DeclareComplementaryOption|,\\
% |\DeclareVoidOption|.
% \end{enumerate}\par
%
% What does `detects' mean? It means that the main argument of
% detected command will be marked as defined at this point,
% i.e.\ thrown to a~margin note and indexed with a~`definition' entry.
% Moreover, for the definitions \ref*{newctr}--\ref*{DSOption} an
% alternate index entries will be created: of the \CSs uderlying those
% definitions, e.g. |\newcounter{foo}| in the
% code will result in indexing |foo| and |\c@foo|.
%
% If you want to add detection of a~defining command not listed above,
% use the \TextUsage\DeclareDefining\ declaration. It comes in two
% flavours: `saut\eacute' and with star. The `saut\eacute' version
% (without star and without an optional argument) declares a~defining
% command of the kind of |\def| and |\newcommand|: its main argument,
% whether wrapped in braces or not, is a~\CS. The starred version (without
% the optional argument) declares a~defining command of the kind of
% |\newenvironment| and |\DeclareOption|: whose main mandatory
% argument is text. Both versions provide an optional argument in
% which you can set the keys. 
%
% Probably the most important key is \TextUsage*{type}. Its default
% value is |cs| and that is set in the `saut\eacute' version. Another
% possible value is |text| and that is set in the starred version. You
% can also set three other types (any keyval setting of the type
% overrides the default and `starred' setting): |dk|, |dox| or |kvo|.
%
% |dk| stands for |\define@key| and is the type of \pk{xkeyval}
% definitions of keys (group \ref{dk type} commands). When detected,
% it scans furher code for an optional \arg[KVprefix], mandatory
% \arg{KVfamily} and mandatory \arg{key name}. The default \<KVprefix>
% is |KV|, as in \pk{xkeyval}.
%
% |dox| stands for |\DeclareOptionX| and launches scanning for an
% optional \arg[KVprefix], optional |<|\<KVfamily>|>| and mandatory
% \arg{option name}. Here the default \<KVprefix>
% is also |KV| and the default \<KVfamily> is the input file name. If
% you want to set another default family (e.g. if the code of
% \file{foo.sty} actually is in file \file{bar.dtx}), use
% \TextUsage\DeclareDOXHead\arg{KVfamily}. This declaration has an
% optional first argument that is the default \<KVprefix> for
% |\DeclareOptionX| definitions.
%
% |kvo| stands for the \pk{kvoptions} package by Heiko Oberdiek. This
% package provides a~handful of option defining commands (the group
% \ref{DSOption} commands). Detection of such a~command launches
% a~scan for mandatory \arg{option name} and alternate indexing of
% a~\CS |\|\<KVOfamily>|@|\<optionname>. The default \<KVOfamily> is
% the input file name. Again, if you want to set something else, you
% are given the \TextUsage\DeclareKVOFam\arg{KVOfamily} that sets the
% default family (and prefix: \<KVOfamily>|@|) for all the commands of
% group \ref{DSOption}.
%
% Next key recognized by |\DeclareDefining| is \TextUsage*{star}. It
% determines whether the starred version of a~defining command should
% be taken into account.  For example, |\newcommand| should be
% declared with |[star=true]| while |\def| with
% |[star=false]|.  You can also write just |[star]| instead of
% |[star=true]|. It's the default if the |star| key is omitted.
%
% There are also \TextUsage*{KVpref} and \TextUsage*{KVfam} keys if
% you want to redeclare the \pk{xkeyval} definitions with another
% default prefix and family.
% 
% For example, if you wish |\@namedef| to be detected (the original
% \LaTeX\ version), declare
% \[|\DeclareDefining*[star=false]\@namedef|\] or 
% \[|\DeclareDefining[type=text,star=false]\@namedef|\] (as stated
% above, |*| is equivalent |[type=text]|).
%
% On the other hand, if you want some of the commands listed above
% \emph{not} to be detected, write \TextUsage\HideDefining\<command>
% in the commentary. If both \<command> and \<command*> are detected,
% then both will be hidden. |\HideDefining| is always |\global|. Later
% you can resume detection of \<command> and \<command*> with
% \TextUsage\ResumeDefining\<command> which is always |\global|
% too. Moreover, if you wish to suspend automatic detection of the
% defining \<command> only once (the next occurrence), there is
% |\HideDefining*| which suspends detection of the next occurrence of
% \<command>. So, if you wish to `hide' |\providecommand*| once, write
% \[|\HideDefining*\providecommand*|\]
%
% If you wish to turn entire detection mechanism off, write
% \TextUsage\HideAllDefining\ in the narration layer. Then you can
% resume detection with \TextUsage\ResumeAllDefining. Both
% declarations are |\global|.
%
% The basic definition command, |\def|, seems to me a~bit
% ambiguous. Definitely \emph{not always} it defines important
% macros. But first of all, if you |\def| a~\CS excluded from indexing (see
% section \gmiflink{Index ex/inclusions}), it will not be marked even
% if detection of |\def| is on. But if the |\def|'s argument is not
% excluded from indexing and you still don't want it to be marked at
% this point, you can write |\HideDefining*\def| or \TextUsage\UnDef\
% for short.
%
% If you don't like |\def| to be detected more times, you may write
% |\HideDefining\def| of course, but there's a~shorthand for this:
% \TextUsage\HideDef\ which has the starred version
% \TextUsage\HideDef*\ equivalent |\UnDef|. To resume detection of
% |\def| you are provided also a~shorthand, \TextUsage\ResumeDef\ (but
% |\ResumeDefining\def| also works).
%
% If you define things not with easily detectable commands, you can
% mark them `manually', with the |\Define| declaration described in
% the next section.
%
%
%
% \subdivision[Manual marking of the macros and environments]{^^B
%   \gmhypertarget{Manual Marking of the Macros and Environments}}
%
% The concept (taken from \docfm ) is to index virtually all the
% control sequences occurring in the code. \gmdoc\ does that by
% default and needs no special command. (See below about exluding some
% macros from being indexed.)
%
% The next concept (also taken from \docfm) is to ditinguish some
% occurrences of some control sequences by putting such a~sequence
% into a~marginpar and by special formatting of its index entry. That
% is what I~call marking the macros. 
% \gmdoc\ provides also
% a~possibility of analogous marking for the environments' names and
% other sequences such as |^^A|.
%
% This package provides two kinds of special formatting of the
% index entries: `usage', with the reference number italic by default,
% and `def' (in \docfm\ called `main'), with the reference number
% roman (upright) and underlined by default. All the reference
% numbers, also those with no special formatting, are made hyperlinks
% to the page or the codeline according to the respective indexing
% option (see p.\,\pageref{indexoptions}).
%
% The macros and environments to be marked appear either in the code
% or in the commentary. But all the definitions appear in the code,
% I~suppose. Therefore the `def' marking macro is provided only for
% the code case. So we have\gmhypertarget[textUsage]{} the
% \TextUsage\Define, \TextUsage\CodeUsage\ and
% \TextUsage\TextUsage\ commands.
%
% All three take one argument and all three may be starred.  The
% non-starred versions are intended to take a~control sequence as the
% argument and the starred to take whatever (an
% environment name or a~|^^A|-like and also a~\CS).
%
% You don't have to bother whether |@| is a~letter while documenting
% because even if not, these commands do make it a~letter, or more
% precisely, they execute \TextUsage\MakePrivateLetters\ whatever 
% it does: At the default settings this command makes |*|
% a~letter, too, so a~starred version of a~command is a~proper argument
% to any of the three commands unstarred.
%
% The |\Define| and |\CodeUsage| commands, if unstarred, mark the next
% scanned occurrence of their argument in the code. (By `scanned
% occurrence' I~mean a~situation of the \CS having been scanned in the
% code which happens iff its name was preceded by the char declared as
% |\CodeEscapeChar|). The starred versions of those commands mark just
% the next codeline and don't make \TeX\ looks for the scanned
% occurrence of their argument (which would never happen if the
% argument is not a~\CS). Therefore, if you want to mark a~definition
% of an environment \env{foo}, you should put
% \[|%\Define*{foo}|\]
%  right before the code line
% \[|\newenvironment{foo}{%|\]^^A]
%     i.e., not separated by another code line. The starred versions of
%     the |\Code...| commands are also intended to mark implicit
%     definitions of macros, e.g.,  |\Define*\@foofalse| before
%     the line
% \[|\newif\if@foo|.\]
%
% They both are |\outer| to dicourage their use inside macros because
% they actually re|\catcode| before taking their arguments.
%
% The |\TextUsage| (one-argument) command is intended to mark usage of
% a~verbatim occurrence of a~\TeX\ object in the commentary. Unlike
%  |\CodeUsage| or |\Define|, it typesets its argument which means among others\ that
% the marginpar appears usually at the same line as the text you
% wanted to mark. This command also has the starred version primarily
% intended for the environments names, and secondarily for
% |^^A|-likes and \CSs, too. Currently, the most important difference
% is that the unstarred version executes |\MakePrivateLetters| while
% the starred does both |\MakePrivateLetters| and |\MakePrivateOthers|
% before reading the argument.
%
% If you consider the marginpars a~sort of sub(sub\dots)section
% marks, then you may wish to have a~command that makes a~marginpar of
% the desired \CS (or whatever) at the beginning of its description,
% which may be fairly far from the first occurrence of its
% object. Then you have the \TextUsage\Describe\ command which
% puts its argument in a~marginpar and indexes it as a~`usage' entry
% but doesn't print it in the text. It's |\outer|.
%
% All four commands  just described put their (|\string|ed) argument
% into a~marginpar (if the marginpars are enabled) and create an index
% entry (if indexing is enabled).
%
% But what if you want just to make a~marginpar with macro's or
% environment's name? Then you have \TextUsage\CodeMarginize\
% to declare what to put into a~marginpar in the \TeX\ code (it's
% |\outer|) and
% \TextUsage\TextMarginize\ to do so in the commentary. According to
% the spirit of this part of the interface, these commands also take one
% argument and have their starred versions for strings other than
% control sequences.
%
% The marginpars (if enabled) are `reverse' i.e., at the left margin, and
% their contents is flush right and typeset in a~font declared with
% \TextUsage\marginpartt. By default, this declaration is |\let| to
% |\tt| but it may be advisable to choose a~condensed font if there is
% any. Such a~choice is made by \pk{gmdocc.cls} if the Latin Modern
% fonts are available: in this case \pk{gmdocc.cls} uses Latin Modern
% Typewriter Light Condensed.
% 
% If you need to put something in a~marginpar without making it typewriter
% font, there's the \TextUsage\gmdmarginpar\ macro (that takes one
% and mandatory argument) that only flushes its contents right.
%
% \stanza
% On the other hand, if you don't want to put a~\CS (or another
% verbatim text) in a~marginpar but only to index it, then there are
% \TextUsage\DefIndex\ and \TextUsage\CodeUsgIndex\ to declare
% special formatting of an entry. The unstarred versions of these
% commands look for their argument's scanned occurrence in the code
% (the argument should be a~\CS), and the starred ones just take the
% next code line as the reference point. Both these commands are
% |\outer|.
%
% In the code all the control sequences (except the excluded ones, see
% below) are indexed by default so no explicit command is needed for
% that. But the environments and other special sequences are not and
% the two commands described above in their |*|ed versions contain the
% command for indexing their argument. But what if you wish to index
% a~not scanned stuff as a~usual entry? The \TextUsage\CodeCommonIndex*\
% comes in rescue, starred for the symmetry with the two previous commands
%  (without |*| it just gobbles
% it's argument---it's indexed automatically anyway). It's |\outer|.
%
% Similarly, to index a~\TeX\ object occurring verbatim in the narrative, you
% have \TextUsage\TextUsgIndex\ and \TextUsage\TextCommonIndex\
% commands with 
% their starless versions for a~\CS argument and the starred for all
% kinds of the argument.
%
% \stanza
% Moreover, as in \docfm, the \TextUsage*{macro} and 
% \TextUsage*{environment} environments are provided. Both take one
% argument that should be a~\CS for \env{macro} and `whatever' for
% \env{environment}. Both add the |\MacroTopsep| glue before and after
% their contents, and put their argument in a~marginpar at the first
% line of their contents (since it's done with |\strut|, you should
% not put any blank line (|%|ed or not) between
% |\begin{macro/environment}| and the first line of the
% contents). Then \env{macro} commands the first scanned occurrence of
% its argument to be indexed as `def' entry and \env{environment}
% commands \TeX\ to index the argument as if it occurred in the next
% code line (also as `def' entry).
%
% Since it's possible that you define a~\CS implicitly i.e., in such a~way that it
% cannot be scanned in the definition (with |\csname...\endcsname|
% e.g.) and wrapping such a~definition (and description) in an
% \env{environment} environment would look misguidedly ugly, there's
% the \env{macro*} environment which \TeX nically is just an alias for
% \env{environment}.
%
% (To be honest, if you give a~\env{macro} environment a~non-\CS
% argument, it will accept it and then it'll work as
% \env{evironment}.)
%
%
% \subdivision[Index ex/inclusions]{\gmhypertarget{Index ex/inclusions}}
%
% It's\label{IEIDeclarations} understandable\footnote{After reading ^^B(
%   \docfm's documentation ;-)\,.} that you don't
% want some control sequences to be indexed in your documentation. The
% \docfm\ package gives a~brilliant solution: the
% \TextUsage\DoNotIndex\ declaration. So do I
% (although here, \TeX nically it's done another
% way). It \acro{OCSR}. This declaration takes one
% argument consisting of a~list of control sequences not to be
% indexed. The items of this list may be separated with commas, as in
% \docfm , but it's not obligatory. The whole list should come in
% curly braces (except when it's one-element), e.g.,
% \[|\DoNotIndex{\some@macros,\are* \too\auxiliary\?}|\]
% (The spaces after the control sequences are ignored.)
% You may use as many |\DoNotIndex|es as you wish (about half as many as
% many \CSs may be declared, because for each \CS excluded from indexing
% a~special \CS is declared that stores the ban sentence).
%  Excluding the same \CS more than once makes no problem.
%
% I~assume you wish most of \LaTeX\ macros, \TeX\ primitives etc.\ to
% be excluded from your index (as I~do). Therefore \pk{gmdoc} excludes
% some 300 \CSs by default. If you don't like it, just set the
% |indexallmacros| package option.
%
% On the third hand, if you like the default exclusions in general but
% wish to undo just a~couple of them, you are given \TextUsage\DoIndex\
% declaration (\acro{OCSR}) that removes a~ban on all the \CSs given in the
% argument, e.g.,
% \[|\DoIndex{\par \@@par \endgraf}|\]
%
% Moreover, you are provided the \TextUsage\DefaultIndexExclusions\
% and \Describe\UndoDefaultIndexExclusions^^A
% \cs{Un\-do\-Def\-ault\-Ind\-ex\-Ex\-cl\-us\-ions} declarations that
% act according to their names. You may use them in any configuration
% with the |indexallmacros| option. Both of these declarations \acro{OCSR}.
%
%
% \subdivision{The \ds\ directives}
%
% \gmdoc\ typesets the \ds\ directives and it does it quite likely as
% \docfm, i.e., with math sans serif font. It does it automatically
% whether you use the traditional settings or the new.
%
% Advised by my \TeX\ Guru, I~didn't implement the module nesting
% recognition (MW told it's not that important.)
%
% So far \gmhypertarget{verbatim mode directive} is only
% half-handled. That is, a~line beginning with |%<||<|\<END-TAG> will be
% typeset as a~\ds\ directive, but ^^A~The magical directive divided
% ^^A due to the doctex mode who saw it and coloured all after with
% ^^A~salmon. 
% the closing line |%|\<END-TAG> will be not. It doesn't seem to be
% hard to implement, if I~only receive some message it's really useful
% for someone.
%
%^^A If you use the \TextUsage*{macrocode} environment, you don't have to
%^^A add any \CS to get \ds\ directive typeset properly: within
%^^A \env{macrocode} a~|<| sign in a~line commented out is read as
%^^A a~beginning of a~\ds\ directive, which means that \TeX\ looks
%^^A for the closing |>| or the very next |<| as the beginning of the
%^^A special directive |<<|\<any text till the end of line>.  In the
%^^A standard case of |<|\<directive>|>| \TeX\ typesets any further text
%^^A in its line as the code.
%^^A
%^^A If you want the \ds\ directives to be typeset without
%^^A \env{macrocode}, you shoud declare \TextUsage\docstrips\ to make
%^^A \TeX\ read the |<| in the comment layer as the beginning of
%^^A a~\ds\ directive. In |\docstrips|'s scope the |<| signs
%^^A occurring in math mode remain just inequality signs.
%^^A
%^^A If you wish only the first |<| met to start a~\ds\ directive
%^^A typesetting, then there's \TextUsage\docstrip\ declaration that
%^^A restores the previous meaning of |<| after the first using it as
%^^A a~\ds\ directive opener.
%^^A
%^^A Both |\docstrips| and |\docstrip| \acro{OCSR} and, of course you may use
%^^A them as environments (which doesn't make much sense with the
%^^A latter, though).
%^^A
%
% \subdivision{The changes history}
%
% The \docfm's documentation reads:
% \begin{quotation}
% To maintain a change history within the file, the |\changes| command may
% be placed amongst the description part of the changed code. It takes three
% arguments, thus:
% \[|\changes{|\<version>|}{|\<\acro{YYYY}/\acro{MM}/\acro{DD} date>|}{|\<text>|}|\]
%
% The changes may be used to produce an auxiliary file (\LaTeX's
% |\glossary| mechanism is used for this) which may be printed after
% suitable formatting. The |\changes| [command] encloses the \<date> in
% parentheses and appends the \<text> to form the printed entry in
% such a change history [\dots\ obsolete remark ommitted].
% 
% To cause the change information to be written out, include
% \TextUsage\RecordChanges\ in the driver['s preamble or just in the
% source file (\pk{gmdocc.cls} does it for you)]. To read in and print
% the sorted change history (in two 
% columns), just put the \TextUsage\PrintChanges\ command as the last
% (commented-out, and thus executed during the documentation pass
% through the file) command in your package file [or in the driver].
% Alternatively, this command may form one of the arguments of the
% |\StopEventually| command, although a change history is probably not
% required if only the description is being printed. The command
% assumes that MakeIndex or some other program has processed the
% \pk{.glo} file to generate a~sorted \pk{.gls} file. You need
% a~special MakeIndex style file; a suitable one is supplied with
% \docfm\ [and \gmdoc], called \iffalse\pk{gglo.ist}\fi^^A
% [\dots\ \textbf{\pk{gmglo.ist}} for \gmdoc]. The \TextUsage\GlossaryMin,
% \TextUsage\GlossaryPrologue\ and \TextUsage\GlossaryParms\ macros are
% analagous to the |\Index...| versions [see
% sec.~\gmiflink[IndexParams]{The parameters}
% p.\,\pageref*{IndexParams}]. (The \LaTeX\ `glossary' 
% mechanism is used for the change entries.)
% \end{quotation}
%
% In \gmdoc\ (unless you turn definitions detection off), you can put
% |\changes| after the line of definition of a~command to set the
% default argument of |\changes| to that command. For example,
%\begin{verbatim}
% \newcommand*\dodecaphonic{...}
% % \changes{v0.99e}{2007/04/29}{renamed from \cs{DodecaPhonic}}
%\end{verbatim}
% results with a~history (sub)entry:
% \deksmallskip
% v0.99e\par\hspace*{\parindent} (\dots)\par \hspace*{\parindent}
% \cs{dodecaphonic}: \par\hspace*{2\parindent} renamed from
% \cs{DodecaPhonic}, \textit{\arabic{page}}
% \deksmallskip
% 
% Such a~setting is in force till the next definition and 
% \emph{every} detected definition resets it.
%
% In \gmdoc\ |\changes| is |\outer|.
%
% \stanza
% As mentioned in the introduction, the glossary, the changes history
% that is, uses a~special MakeIndex style, \pk{gmglo.ist}. This style
% declares another set of the control chars but you don't have to
% worry: |\changes| takes care of setting them properly. To be
% precise, |\changes| executes \TextUsage\MakeGlossaryControls\ that
% is defined as
% \begin{verbatim}
%  \def\actualchar{=} \def\quotechar{!}%
%  \def\levelchar{>} \edef\encapchar{\xiiclub}
%\end{verbatim}
%
% Only if you
% want to add a~control character yourself in a~changes entry, to quote
% some char, that is (using level or encapsulation chars is not
% recommended since |\changes| uses them itself), use rather
% |\quotechar|.
%
% \stanza
% Before writing an entry to the \pk{.glo} file, |\changes|
% checks if the date (the second mandatory\equals the third argument)
% is later than the date stored in the counter
% \TextUsage*{ChangesStartDate}. You may set this counter with a
% \Describe\ChangesStart^^B
% \[|\ChangesStart{|\<version>|}{|\<year>|/|\<month>|/|\<day>|}|\]
% declaration.
%
% If the \env{ChangesStartDate} is set to a~date contemporary to \TeX\
% i.e., not earlier than September 1982\footnote{DEK in \textit{\TeX\ ^^B
% The Program} mentions that month as of \TeX\ Version 0 release.},
% then a~note shall appear at the beginning of the changes history
% that informs the reader of ommitting the earlier changes entries.
%
% If the date stored in \env{ChangesStartDate} is earlier than \TeX,
% no notification of ommitting shall be printed. This is intended for
% a~rather tricky usage of the changes start date feature: you may
% establish two threads of the changes history: the one for the users,
% dated with four digit year, and the other for yourself only, dated
% with two or three digit year. If you declare 
% \[|\ChangesStart{|\<version?>|}{1000/00/00}|\]
% or so, the changes entries dated with less-than-four digit year
% shall be ommitted and no notification shall be issued of that.
%
% \stanza
%
% While scanning the \CSs in the code, \gmdoc\ counts them and prints
% the information about their number on the terminal and in
% \pk{.log}. Moreover, you may declare
% \TextUsage\CheckSum|{|\<number>|}| before the code and \TeX\ will
% inform you whether the number stated by you is
% correct or not, and what it is. As you guess, it's not my original idea
% but I~took it from \docfm. 
%
% There it is provided as a~tool for
% testing whether the file is corrupted. 
% My \TeX\ Guru says it's a~bit old-fashioned nowadays but I~like the
% idea and use it to document the file's growth. For this purpose
% \gmdoc\ types out lines like
% \begin{verbatim}
%% \chschange{v0.98j}{2006/10/19}{4372}
%% \chschange{v0.98j}{06/10/19}{4372}
%\end{verbatim}
% and you may place them at the beginning of the source file. Such
% a~line results in setting the check sum to the number contained in
% the last pair of braces and in making a~`general' changes entry that
% states the check sum for version \<first brace> dated \<second ^^B
% brace> was \<third brace>.
%
% \stanza
% There is also \TextUsage\toCTAN\arg{version}\arg{date}, a~shorthand
% for 
% \[|\changes|\arg{version}\arg{date}|{put to \acro{CTAN} on |\<date>|}|\]
%
%
% \subdivision{The parameters}
%
% The \pk{gmdoc} package provides some parameters specific to
% typesetting the \TeX\ code:
%
% \stanza
% \TextUsage\stanzaskip\ is a~vertical space inserted when a~blank
% (code) line is met. It's equal |0.75\medskipamount| by default
% (with the \emph{entire} |\medskipamount|'s stretch- and
% shrinkability). Subsequent blank code lines do not increase this
% space.
%
% At the points where narration begins a~new line after the code or an
% inline comment and where a~new code line begins after the narration
% (that is not an inline comment), a~\TextUsage\CodeTopsep\ glue is
% added. At the beginning and the end of a~\env{macro} or
% \env{environment} environment a~|\MacroTopsep| glue is added. By
% default, these two skips are set equal |\stanzaskip|. 
%
% The |\stanzaskip|'s value is assigned also to the display skips and
% to |\topsep|. This is done with the \TextUsage\UniformSkips\
% declaration executed by default. If you want to change some of those
% values, you should declare \TextUsage\NonUniformSkips\ in the
% preamble to discard the default declaration. (To be more precise, by
% default |\UniformSkips| is executed twice: when loading \gmdoc\ and
% again |\AtBeginDocument| to allow you to change |\stanzaskip| and
% have the other glues set due to it. |\NonUniformSkips| relaxes the
% |\UniformSkips|'s occurrence at |\begin{document}|.)
%
% If you want to add a~vertical space of |\CodeTopsep| (equal by
% default |\stanzaskip|), you are provided the \TextUsage\stanza\
% command. Similarly, if you want to add a~vertical space of the
% |\MacroTopsep| amount (by default also equal |\stanzaskip|), you are
% given the \TextUsage\chunkskip\ command. They both act analogously
% to |\addvspace| i.e., don't add two consecutive glues but put the
% bigger of them.
%
% Since |\CodeTopsep| glue is inserted automatically at each
% transition from the code (or code with an inline comment) to the
% narration and reverse, it may happen that you want not to add such
% a~glue exceptionally. Then there's the \TextUsage\nostanza\
% command. You can use it before narration to remove the vskip before
% it or after narration to suppress the vskip after it.
%
% \stanza
% The \TeX\ code is indented with the \TextUsage\CodeIndent\ glue
% and a~leading space increases indentation of the line by its
% (space's) width. The default value of |\CodeIndent| is 1.5\,em.
%
% There's also a~parameter for the indent of the narration,
% \TextUsage\TextIndent, but you should use it only in emergency
% (otherwise what would be the margins for?). It's 0\,sp by default.
%
% \stanza
% By default, the end of a~|\DocInput| file is marked with
%
%`\EOFMark' 
%
% \noindent given by the
% \TextUsage\EOFMark\ macro.
%
% \stanza
% If you do use the \eTeX's primitive \TextUsage\everyeof, be sure
% the contents of it begins with |\relax| because it's the token that
% stops the main macro scanning the code.
% \stanza
%
% The crucial concept of \gmdoc\ is to use the line end character
% as a~verbatim group opener and the comment char, usually the |%|, as
% its delimiter. Therefore the `knowledge' what char starts
% a~commentary is for this package crucial and utterly
% important. The default assumption is that you use |%| as we
% all do. So, if you use another character, then you should declare it
% with \TextUsage\CodeDelim\ typing the desired char
% preceded by a~backslash, e.g., |\CodeDelim\&|\,. (As just
% mentioned implicitly, \possfil|\CodeDelim\%| is declared by
% deafult.) 
%
% This declaration is always global so when- and wherever you change
% your mind you should express it with a~new |\CodeDelim|
% declaration.
%
% The starred version of |\CodeDelim| changes also the verb
% `hyphen', the char appearing at the verbatim line breaks that is.
%
% \stanza
% Talking of special chars, the escape char, |\| by default, is also
% very important for this package as it marks control sequences and
% allows automatic indexing them for instance. Therefore, if you for
% any reason choose another than |\| character to be the escape char,
% you should tell \pk{gmdoc} about it with the
% \TextUsage\CodeEscapeChar\ declaration. As the previous one, this too
% takes its argument preceded by a~backslash,
% e.g., |\CodeEscapeChar\!|. (As you may deduct from the above,
% |\CodeEscapeChar\\| is declared by default.)
%
% The tradition is that in the packages |@| char is a~letter
% i.e., of catcode \catletter. Frank Mittelbach in \docfm\ takes into account
% a~possibility that a~user wishes some other chars to be letters,
% too, and therefore he (F.M.) provides the
% \TextUsage\MakePrivateLetters\ macro.  
% So do I~and like in \docfm, this macro makes |@| sign a~letter. It
%  also makes  |*| a~letter in order to cover the starred versions
% of commands.
%
% Analogously but for a~slightly different purpose, the
% \TextUsage\AddtoPrivateOthers\ macro is provided here. It adds its
% argument, which is supposed to be a~one-char \CS, to the
% |\doprivateothers| list, whose r\ocircum le is to allow some special chars
% to appear in the marking commands' arguments (the commands described
% in section \gmiflink{Macros for marking the macros}). The default
% contents of this list is | | (the space) and |^| so you may mark the
% environments names and special sequences like |^^A| safely. This
% list is also extended with every char that is |\MakeShortVerb|ed.
% (I~don't see a~need of removing chars from this list, but if
% you do, please let me know.)
%
% \stanza
% The line numbers (if enabled) are typeset in the
% \TextUsage\LineNumFont\ declaration's scope, which
% is defined as |{\normalfont\tiny}| by default. Let us also remember, that for
% each counter there is a~|\the|\<counter> macro available. The
% counter for the line numbers is called \TextUsage*{codelinenum} so
% the macro printing it is |\thecodelinenum|. By default we don't
% change its \LaTeX's definition which is equivalent
% |\arabic{codelinenum}|.
%
%
% Three more parameter macros, are \TextUsage\IndexPrefix,
% \TextUsage\EntryPrefix\ and \TextUsage\HLPrefix. All three are
% provided with the account of  including multiple files in one
% document. 
% They are equal (almost) |\@empty| by default. The first may store
% main level index entry of which all indexed macros and environments
% would be subentries, e.g., the name of the package. The third may or
% even should store a~text to distinguish equal codeline numbers of
% distinct source files. It may be the file name too, of course. The
% second macro is intended for another concept, namely the one from
% \pk{ltxdoc} class, to distinguish the codeline numbers from
% different files \emph{in the index} by the file marker. Anyway, if
% you document just one file per document, there's no need of
% redefining those macros, nor when you input multiple files with
% |\DocInclude|.
%
% \pk{gmdoc} automatically indexes the control sequences
% occurring in the code. Their index entries may be `common' or
% distinguished in two (more) ways. The concept is to distinguish the
% entries indicating the \emph{usage} of the \CS and the entries
% indicating the \emph{definition} of the \CS.
%
% The special formattings of `usage' and `def' index entries are
% determined by \Describe\UsgEntry\cs{Usg\-Ent\-ry} and \TextUsage\DefEntry\
% one-parameter macros (the parameter shall be substituted with the
% reference number) and by default are defined as |\textit| and
% |\underline| respectively (as in \docfm).
%
% There's one more parameter macro, \TextUsage\CommonEntryCmd\ that
% stores the name of the encapsulation for the `common' index entries
% (not special) i.e., a~word that'll become a~\CS that will be put
% before an entry in the \file{.ind} file. By default it's defined as
% |{relax}| and a~nontrivial use of it you may see in the source of
% chapter \ref*{Driver}, where
% |\def\CommonEntryCmd{UsgEntry}| makes all the index entries of the
% driver formatted as `usage'.
%
% \stanza
% ^^A~Index Parameters
% \gmhypertarget[IndexParams]{The index} comes in a~\env{multicols}
% environment whose columns number is determined by the
% \TextUsage*{IndexColumns} counter set by default to~3. To save space,
% the index begins at the same page as the previous text provided
% there is at least \TextUsage\IndexMin\ of the page height free. By
% default, |\IndexMin|\equals\the\IndexMin.
%
% The text put at the beginning of the index is declared with
% a~one-argument
% \Describe\IndexPrologue\cs{Ind\-ex\-Pro\-lo\-gue}. Its default text
% at current index option you may \gmiflink[DIPrologue]{admire} on
% page \pageref*{DIPrologue}.^^A
% \AtDIPrologue{\raisebox{4cm}[0sp][0sp]{\gmhypertarget[DIPrologue]}}
% Of course, you may write your own |\IndexPrologue{|\<brand new ^^B
% index prologue>|}|, but if you like the default and want only to add
% something to it, you are provided \TextUsage\AtDIPrologue\
% one-argument declaration that adds the stuff after the default
% text. For instance, I~used it to add a~label and hypertarget that is
% referred to two sentences earlier.
%
% By default the colour of the index entry hyperlinks is set black to
% let Adobe Reader work faster. If you don't want this,
% \Describe\IndexLinksBlack|\let\IndexLinksBlack\relax|. That leaves
% the index links colour alone and hides
% the text about black links from the default index prologue.
%
% Other index parameters are set with the \TextUsage\IndexParms\ macro
% defined in line \gmifref[IndexParms]{sixty-odd} of the code. If you
% want to change some of them, you don't have to use
% |\renewcommand*\IndexParms| and set all of the parameters: you may
% \Describe\gaddtomacro^^A
% |\gaddtomacro\IndexParms{|\<only the desired changes>|}|.
% (|\gaddtomacro| is an alias for \LaTeX's |\g@addto@macro| provided
% by \pk{gmutils}.)
%
% At the default \gmdoc\ settings the \file{.idx} file is prepared for
% the default settings of MakeIndex (no special style). Therefore the
% index control chars are as usual. But if you need to use other
% chars as MakeIndex controls, know that they are stored in the four
% macros: \TextUsage\actualchar, \TextUsage\quotechar,
% \TextUsage\levelchar\ and \TextUsage\encapchar\ whose meaning you
% infer from their names.  Any redefinition of them \emph{should be ^^B 
% done in the preamble} because the first usage of them takes place at
% |\begin{document}| and on it depends further tests telling \TeX\
%   what characters of a~scanned \CS name it should quote before
%   writing it to the \pk{.idx} file.
% 
% \stanza
% Frank Mittelbach in \docfm\ provides the |\verbatimchar| macro to
% (re)define the |\verb|'s delimiter for the index entries of the
% scanned \CS names etc. \gmdoc\ also uses \TextUsage\verbatimchar\ but
% defines it as |{&}|. Moreover, a~macro that wraps a~\CS name in |\verb|
% checks whether the wrapped \CS isn't |\&| and if it is, |$| is taken
% as the delimiter. So there's hardly chance that you'll need to
% redefine |\verbatimchar|.
%
% So strange delimiters are chosen deliberately to allow any `other'
% chars in the environments names.
%
% \stanza
% There's a~quadratus of commands taken from \docfm:
% \TextUsage\StopEventually, \TextUsage\Finale,\\
% \TextUsage\AlsoImplementation\ and \TextUsage\OnlyDescription\ that
% should be 
% explained simultaneously (in a~polyphonic song
% e.g.).
%
% The |\OnlyDescription| and |\AlsoImplementation|
% declarations are intended to  exclude or include the code part from
% the documentation. The point between the description and the
% implementation part should be marked with |\StopEventually{|\<the ^^B
% stuff to be executed anyway>|}| and |\Finale| should be typed
% at the end of file. Then |\OnlyDescription| defines
% |\StopEventually| to expand to its argument followed by |\endinput|
% and\\ |\AlsoImplementation| defines |\StopEventually| to do nothing
% but pass its argument to |\Finale|.
%
%
% \subdivision{The narration macros}
%
% To print the control sequences' names you have the \TextUsage\verb\ macro and
% its `shortverb' version whatever you define (see the \pk{gmverb}
% package). 
% 
% For short verbatim texts in the inline comments \pk{gmdoc} provides
% the \TextUsage\inverb\<charX>\dots\<charX> (the name stands for
% `inline verbatim') command that redefines the \pk{gmverb} breakables
% to break with |%| at the beginning of the
% lower line to avoid mistaking such a~broken verbatim commentary text
% for the code.
% 
% But nor |\verb(*)| neither |\inverb|  will work if
% you put them in an argument of another macro. For such a~situation,
% or if you just prefer, \gmdoc\ (\pk{gmutils}) provides a~robust command
% \TextUsage\cs, which takes one obligatory argument, the macro's name
% without the backslash, e.g., |\cs{mymacro}| produces
% \cs{mymacro}. I~take account of a~need of printing some other text
% verbatim, too, and therefore |\cs| has the first argument
% optional, which is the text to be typeset before the mandatory
% argument. It's the backslash by default, but if you wish to typeset
% something without the |\|, you may write {\verbeolOK |\cs[]{not
% a~macro}|}. Moreover, for typesetting the environments' names,
% \gmdoc\ (\pk{gmutils})
% provides the \TextUsage\env\ macro, that prints its argument
% verbatim and without a~backslash, e.g., |\env{an environment}|
% produces \env{an environment}.
%
% For usage in the inline comments there are \TextUsage\incs\ and
% \TextUsage\inenv\ commands that take analogous arguments and precede
% the typeset command and environment names with a~|%| if at the
% beginning of a~new line.
%
% And for line breaking at |\cs| and |\env| there is
% \TextUsage\nlpercent\ to ensure |%| if the line breaks at the
% beginning of a~|\cs| or |\env| and \TextUsage\+ to use inside their
% argument for a~discretionary hyphen that'll break to - at the end of
% the upper line and |%| at the beginning of the lower line. By
% default hyphenation of |\cs| and |\env| arguments is off, you can
% allow it only at |\-| or |\+|.
% 
% \stanza By default the multiline inline comments are typeset with
% a~hanging indent (that is constant relatively to the current
% indent of the code) and justified. Since vertical alignment is
% determined by the parameters as they are at the moment of \cs{par},
% no one can set the code line to be typeset ragged right (to break
% nicely if it's long) and the following inline comment to be
% justified. Moreover, because of the hanging indent the lines of
% multiline inline comments are relatively short, you may get lots of
% overfulls. Therefore there is a~Boolean switch \TextUsage*{ilrr}
% (\acro{OCSR}),
% whose name stands for `InLine RaggedRight' and the inline comments
% (and their codelines) are typeset justified in the scope of
% |\ilrrfalse| which is the default.
%  When you write |\ilrrtrue|, then all  inline comments in its scope
% (and their codelines) will be typeset ragged right
% (and still with the hanging indent). Moreover, you are provided
% \TextUsage\ilrr\ and \TextUsage\ilju\ commands that set |\ilrrtrue|
% and |\ilrrfalse| for the current inline comment only. Note you can
% use them  anywhere within such a~comment, as they set |\rightskip|
% basically. |\ilrr| and |\ilju| are no-ops in the standalone narration.
%
%
%
% \stanza
% To print packages' names sans serif there is a~\TextUsage\pk\
% one-argument command, and the \TextUsage\file\ command intended for
% the filenames. 
%
% Because we play a~lot with the |\catcode|s here and want to talk
% about it, there are \TextUsage\catletter, \TextUsage\catother\ and
% \TextUsage\catactive\ macros that print \catletter, \catother\ and
% \catactive\ respectively to concisely mark the most used char
% categories.
%
% I~wish my self-documenting code to be able to be typeset each
% package separately or several in one document. Therefore I~need some
% `flexible' sectioning commands and here they are:
% \TextUsage\division, \TextUsage\subdivision\ and
% \TextUsage\subsubdivision\ so far, that by default are |\let| to be
% |\section|, |\subsection| and |\subsubsection| respectively.
%
% \stanza
% One more kind of flexibility is to allow using \pk{mwcls} or the
% standard classes for the same file. There was a~trouble with the
% number and order of the optional arguments of the original
% \pk{mwcls}'s sectioning commands.
%
% It's resolved in \pk{gmutils} so you are free at this point, and
% even more free than in the standard classes: if you give
% a~sectioning command just one optional argument, it will be the
% title to toc and to the running head (that's standard in
% scls\footnote{See \pk{gmutils} for some subtle details.}). If you give
% \emph{two} optionals, the first will go to the running head and the
% other to toc. (In both cases the mandatory argument goes only to the
% page).
%
% \stanza
% If you wish the |\DocInclude|d files make other sectionings than the
% default, you may declare \TextUsage\SetFileDiv|{|\<sec name without ^^B
% backslash>|}|.
%
% \stanza
%
% \pk{gmdoc.sty} provides also an environment \TextUsage*{gmlonely}
% to wrap some text you think you may want to skip some day. When
% that day comes, you write \TextUsage\skipgmlonely\ before the
% instances of \env{gmlonely} you want to skip. This declaration has
% an optional argument which is for a~text that'll appear in(stead of) the
% first \env{gmlonely}'s instance in every |\DocInput| or
% |\DocInclude|d file within |\skipgmlonely|'s scope.
%
% An example of use you may see in this documentation: the repeated
% passages about the installation and compiling the documentation are
% skipped in further chapters thanks to it.
%
% \stanza
% \gmdoc\ (\pk{gmutils}, to be precise) provides some \TeX-related
% logos:\\ 
% \Describe\AmSTeX typesets \AmSTeX,\\
% \Describe\BibTeX\BibTeX,\\
% \Describe\SliTeX\SliTeX,\\
% \Describe\PlainTeX\PlainTeX,\\
% \Describe\Web\Web,\\
% \Describe\TeXbook\TeXbook,\par^^A~without par there raised error
% ^^A `too many unprocessed floats'.
% \noindent\Describe\TB\TB\par
% \noindent\Describe\eTeX\eTeX,\\
% \Describe\pdfeTeX\pdfeTeX\\
% \Describe\pdfTeX\pdfTeX\\
% \Describe\XeTeX\XeTeX\ (the first |E| will be reversed if the
% \pk{graphics} package is loaded or \XeTeX\ is at work) and\\
% \Describe\LaTeXpar\LaTeXpar.\par
%
% \noindent\Describe\ds\ds\ not quite a~logo, but still convenient.
%
% \stanza
% The \TextUsage*{copyrnote} environment is provided to format the
% copyright note flush left in |\obeylines|' scope.
%
% \stanza
%
% To put an arbitrary text into a~marginpar and have it flushed right
% just like the macros' names, you are provided the
% \TextUsage\gmdmarginpar\ macro that takes one mandatory argument
% which is the contents of the marginpar.
%
% \stanza
% To make a~vertical space to separate some piece of text you are
% given two macros: \TextUsage\stanza\ and \TextUsage\chunkskip. The
% first adds |\stanzaskip| while the latter |\MacroTopsep|. Both of
% them take care of not cumulating the vspaces.
%
%
%\stanza
% The \TextUsage*{quotation} environment is redefined just to enclose
% its contents in double quotes. 
%
% If you don't like it, just call
% |\RestoreEnvironment{quotation}| after loading \pk{gmdoc}.
% Note however that other environments using
% \env{quotation}, such as \env{abstract}, keep their shape.
%
% \stanza
%
% The \TextUsage\GetFileInfo|{|\<file name with extension>|}| command
% defines \TextUsage\filedate, \Describe\fileversion\cs{fil\-e\-vers\-ion} and
% \TextUsage\fileinfo\ as the respective pieces of the info (the
% optional argument) provided
% by \cs{Pro\-vid\-es\-Class/Pack\-age/Fi\-le} declarations. The
% information of the file you process with \gmdoc\
% is provided (and therefore getable) if the file is also loaded (or
% the |\Provide...| line occurs in a~|\StraightEOL| scope).
%
% If the input file doesn't contain |\Provides...| in the code layer, 
% there are commands \TextUsage\ProvideFileInfo|{|\<file name with ^^B
% extension>|}[|\<info>|]|. (\<info> should consist of:
% \<year>|/|\<month>|/|\<day>| |\<version number>| |\<a~short note>.)
%
% Since we may documentally input files that we don't load, \docfm\ in
% \pk{gmdoc} e.g., we provide a~declaration to be put (in the comment
% layer) before the line(s) containing |\Provides...|. The
% \TextUsage\FileInfo\ command takes the subsequent stuff till the
% closing |]| and subsequent line end, extracts from it the info and
% writes it to the \file{.aux} and rescans the stuff. We use an
% \eTeX\ primitive |\scantokens| for that purpose.
%
% A~macro for the standard note is provided, \TextUsage\filenote, that
% expands to ``This file has version number \<version number> dated
% \<date>.'' To place such a~note in the document's title (or heading,
% with |\DocInclude| at the default settings), there's
% \TextUsage\thfileinfo\ macro that puts |\fileinfo| in |\thanks|.
%
% \stanza
% Since |\noindent| didn't want to cooperate with my code and
% narration layers sometimes, I~provide \TextUsage\gmdnoindent\ that
% forces a~not indented paragraph if |\noindent| could not.
%
% \stanza
% If you declare the code delimiter other than |%| and then want |%|
% back, you may write \TextUsage\CDPerc\ instead of |\CodeDelim*\%|.
%
% If you like |&| as the code delimiter (as I~did twice), you may write
% \TextUsage\CDAnd\ instead of |\CodeDelim\&|.
%
% \stanza To get `\CS' which is `CS' in small caps (in |\acro| to be
% precise), you can write \TextUsage\CS. This macro is |\protected| so
% you can use it safely  in |\changes| e.g. Moreover, it checks
% whether the next token is a~letter and puts a~space if so so you
% don't have to bother about \verb*|\CS\ |.
% 
% \stanza
% To enumerate the list of command's arguments or macro's parameters
% there is the \TextUsage*{enumargs} environment which is a~version of
% \env{enumerate} with labels like |#7|.  You can use |\item| or, at
% your option, \TextUsage\mand\ which is just an alias for the
% former. For an optional arguments use \TextUsage\opt\ which wraps
% the item label in square brackets. Moreover, to align optional and
% mandatory arguments digit under digit, use
% the \TextUsage*{enumargs*} environment.
%
% Both environments take an optional argument which is the number of
% |#|s. It's 1 by default, but also can be 2 or 4 (other numbers will
% typeset numbers without a~|#|). Please feel free to notify me if you
% really need more hashes in that environment. 
%
% \stanza
% For an example driver file see chapter \gmiflink{The driver}.
%
%
% \subdivision{A~queerness of \cs{label}}
%
% You should be loyally informed that |\label| in \gmdoc\
% behaves slightly
% non-standard in the \cs{Doc\-In\-put/\:Inc\-lud\-e}d files:
% the automatic redefinitions of |\ref| at each code line
% are \emph{global} (since the code is typeset in groups and the
% |\ref|s will be out of those groups), so
% a~|\ref|erence in the narrative will point at the last code line not
% the last section, \emph{unlike} in the standard \LaTeX.
%
% 
% \subdivision{\docfm-compatibility}
% 
% One of my goals while writing \gmdoc\ was to make compilation of
% \docfm-like files with \gmdoc\ possible. I~cannot guarantee the goal
% has been reached but I~\emph{did} compile \pk{doc.dtx} with not
% a~smallest change of that file (actually, there was a~tiny little
% buggie in line 3299 which I~fixed remotely with
% \cs{AfterMacrocode} tool written specially for that). So, if
% you wish to compile a~\docfm-like file with my humble package, just
% try.
%
% \TextUsage\AfterMacrocode\arg{mc number}\arg{the stuff} defines
% control sequence \cs{gmd@mchook}\<mc number> with the meaning \<the\
% stuff> which is put at the end of \env{macrocode} and \env{oldmc}
% number \<mc number> (after the group).
%
% The \docfm\ commands most important in my opinion are supported by
% \gmdoc. Some commands, mostly the obsolete in my opinion, are not
% supported but give an info on the terminal and in \pk{.log}.
%
% I~assume that if one wishes to use \docfm's interface then \heshe\
% won't use \gmdoc's options but just the default. (Some \gmdoc\
% options may interfere with some \docfm\ commands, they may cancel
% them e.g.)
%
% \stanza
% The main input commands compatible with \docfm\ are
% \TextUsage\OldDocInput\ and \TextUsage\DocInclude, the latter
% however only in the \TextUsage\olddocIncludes\ declaration's scope.
%
% Within their scope/argument the \TextUsage*{macrocode} environments
% behave as in \docfm, i.e.\ they are a~kind of verbatim and require to be
% ended with |%    \end{macrocode(*)}|.
%
% The default behaviour of \env{macrocode(*)} with the `new' input
% commands is different however. Remember that in the `new' fashion the code
% and narration layers philosophy is in force and that is sustained
% within \env{macrocode(*)}. Which means basically that with `new'
% settings when you write
%\begin{verbatim}
%% \begin{macrocode}
%  \alittlemacro % change it to \blaargh
%%\end{macrocode}
%\end{verbatim}
% and |\blaargh|'s definition is |{foo}|, you'll get
%\[|\alittlemacro %| change it to foo\]
% (Note that `my' \env{macrocode} doesn't require 
% the magical \verb*|%    \end|.)
%
% If you are used to the traditional (\docfm's) \env{macrocode} and still wish to
% use \gmdoc\ new way, you have at least two options: there is the
% \TextUsage*{oldmc} environment analogous to the traditional (\docfm's)
% \env{macrocode} (it also has the starred version), that's the first
% option (I~needed the traditional behaviour once in this
% documentation, find out where \& why). The other is to write
% \TextUsage\OldMacrocodes. That declaration (\acro{OCSR}) redefines 
% \env{macrocode} and \env{macrocode*} to behave the traditional way.
% (It's always executed by |\OldDocInput| and |\olddocIncludes|.)
%
%
% \stanza
% For a~more detailed discussion of what is \docfm-compatible and how,
% see the code section \gmiflink[doccompa]{\docfm-compatibiliy}.
%
%^^A \docstrip
%<*package>

%  \division[The driver part]{\gmhypertarget{The driver} part}
%
% In case of a~single package, such as \pk{gmutils}, a~driver part of
% the package may look as follows and you put it before
% \cs{ProvidesPackage/Class}.
%
%\begin{verbatim}
%% \skiplines we skip the driver
%\ifnum\catcode`\@=12
%
%\documentclass[outeroff, pagella, fontspec=quiet]{gmdocc}
%\usepackage{eufrak}% for |\continuum| in the commentary.
%\twocoltoc
%\begin{document}
%
%\DocInput{\jobname.sty}
%\PrintChanges
%\thispagestyle{empty}
%\typeout{%
%  Produce change log with^^J%
%  makeindex -r -s gmglo.ist -o \jobname.gls \jobname.glo^^J
%  (gmglo.ist should be put into some texmf/makeindex directory.)^^J}
%\typeout{%
%  Produce index with^^J%
%  makeindex -r \jobname^^J}
%\afterfi{\end{document}}
%
%\fi% of driver pass
%%\endskiplines
%\end{verbatim}
% 
% The advantage of \TextUsage\skiplines…\TextUsage\endskiplines\ over
% |\iffalse…\fi| is that the latter has to contain balanced \cs{if}s
% and \cs{fi}s while the former hasn't because it sanitizes the
% stuff. More precisely, it uses the \cs{dospecials} list, so it
% sanitizes also the braces.
% 
% Moreover, when the |countalllines(*)| option is in force,
% |\skipfiles|…|\endskipfiles| keeps the score of skipped lines.
%
% \label{Driver}
% {\def\CommonEntryCmd{UsgEntry}%
%
% Note |%\iffalse| \dots\ |%\fi| in the code layer that protects the
% driver against being typeset.
%
% But \pk{gmdoc} is more baroque and we want to see the driver
% typeset---behold.

\ifnum\catcode`\@=12

% \CodeUsgIndex*{outeroff} \CodeUsgIndex*{mwrep}
\documentclass[countalllines, codespacesgrey, outeroff, debug, mwrep,
pagella, fontspec=quiet]{gmdocc} 

\twocoltoc
\title{The \pk{gmdoc} Package\\ i.e., \pk{gmdoc.sty} and
  \pk{gmdocc.cls}}
\author{Grzegorz `Natror' Murzynowski}
\date{\ifcase\month\relax\or January\or February\or March\or April\or May\or
  June\or July\or August\or September\or October\or November\or
  December\fi\ 2008}

%|%\includeonly{gmoldcomm}|
%^^A\includeonly{gmeometric,gmoldcomm}
\begin{document}

%\skiplines
\emptify\udigits % because orig. def. raises an error `\cs{@secondoftwo} has
                 % an extra \}'
%\endskiplines
\maketitle

\setcounter{page}{2}% \pk{hyperref} cries if it sees two pages
% numbered~1.
\tableofcontents
\DoIndex\maketitle

%^^A\AtBegInputOnce{\showthe\catcode`\^^B}
\SelfInclude
% \label{SelfIncludeUsg}
\DocInclude{gmdocc}

% For your convenience I~decided to add the documentations of the
% three auxiliary packages:
\skipgmlonely[\stanza The remarks about installation and compiling
  of the documentation are analogous to those in the chapter
  \pk{gmdoc.sty} and therefore ommitted.\stanza]
\DocInclude{gmutils} 
\DocInclude{gmiflink} 
\DocInclude{gmverb}
\DocInclude{gmeometric}
\DocInclude{gmoldcomm}
\typeout{%
  Produce change log with^^J%
  makeindex -r -s gmglo.ist -o \jobname.gls \jobname.glo^^J
  (gmglo.ist should be put into some texmf/makeindex directory.)^^J}
\PrintChanges
\typeout{%
  Produce index with^^J%
  makeindex -r \jobname^^J}
 \PrintIndex

\afterfi{%
\end{document}
% MakeIndex shell commands:
  makeindex -r gmdoc
  makeindex -r -s gmglo.ist -o gmdocDoc.gls gmdocDoc.glo
% (\pk{gmglo.ist} should be put into some \pk{texmf/makeindex}
% directory.) 

%^^A(
% And ``That's all, folks'' ;-)\,.

}\fi% of |\ifnum\catcode`\@=12|, of the driver that is.

% }^^A~of special \cs{CommonEntryCmd}'s definition.
%
% \StopEventually{\NoEOF}
%
%
% \division{The code}
%
% For debug
\catcode`\^^C=9\relax
% We set the |\catcode| of this char to \catactive\ in the comment
% layer. 
% \catcode`\^^C\active
%
% \changes[^^C]{v0.98g}{06/10/10}{recatcoded for debug: in the working
% pass it's made ignored and in the documenting pass it's made active}
%
%
% \DoIndex{\par \@@par}
% 
% The basic idea of this package is to re|\catcode| |^^M| (the line
% end char) and |%| (or any other comment char) so that they start and
% finish typesetting of what's between them as the \TeX\ code i.e.,
% verbatim and with the bells and whistles.
%
% The bells and whistles are (optional) numbering of the codelines,
% and automatic indexing the \CSs, possibly with
% special format for the `def' and `usage' entries.
%
% As mentioned in the preface, this package aims at a~minimal markup
% of the working code. A~package author writes \hisher\ splendid code
% and adds a~brilliant comment in |%|ed lines and that's all. Of
% course, if \heshe\ wants tomake a~|\section| or |\emph|asise,
% \heshe\ has to type respective \CSs.
%
% I~see the feature described above to be quite a~convenience,
% however it has some price. See section 
% \gmiflink[afc]{Life among queer \acro{EOL}s}  for details,
% here I~state only that in my opinion the price is not very high.
% \stanza
%
% More detailedly, the idea is to make |^^M| (end of line char) active
% and to define it to check if the next char i.e., the beginnig of the
% next line is a~|%| and if so
% to gobble it and just continue usual typesetting or else to start
% a~verbatim scope. In fact, every such a~line end starts a~verbatim
% scope which is immediately closed, if the next line begins with
% (leading spaces and) the code delimiter.
%
% Further details are typographical parameters of verbatim scope and
% how to restore normal settings after such a~scope so that a~code
% line could be commented and still displayed, how to deal with
% leading spaces, how to allow breaking a~moving argument in two lines
% in the comment layer, how to index and marginpar macros etc.
%
%
%\subdivision{The package options}
%
\RequirePackage{gmutils}[2008/08/30]% includes redefinition of
% \incs{newif} to make the switches \incs{protected}.
\RequirePackage{xkeyval}% we need key-vals later, but maybe we'll make
% the option key-val as well.
%
% Maybe someone wants the code lines not to be numbered.

\newif\if@linesnotnum

\DeclareOption{linesnotnum}{\@linesnotnumtrue}

% And maybe he or she wishes to declare resetting the line counter
% along with some sectioning counter  him/herself.

\newif\if@uresetlinecount

\DeclareOption{uresetlinecount}{\@uresetlinecounttrue}

% And let the user be given a~possibility to count the comment
% lines.

\newif\if@countalllines
\newif\if@printalllinenos

\DeclareOption{countalllines}{%
  \@countalllinestrue
  \@printalllinenosfalse}

\DeclareOption{countalllines*}{%
  \@countalllinestrue
  \@printalllinenostrue}


% Unlike in \docfm , indexing the macros is the default and the
% default reference is the code line number.

\newif\if@noindex

\DeclareOption{noindex}{\@noindextrue}


\newif\if@pageindex

\DeclareOption{pageindex}{\@pageindextrue}

% It would be a~great honour to me if someone would like to document
% \LaTeX\ source with this humble package but I~don't think it's
% really probable so let's make an option that'll switch index exclude
% list properly (see sec.\ \gmiflink{Index exclude list}).

\newif\if@indexallmacros

\DeclareOption{indexallmacros}{\@indexallmacrostrue}

% Some document classes don't support marginpars or disable them by
% default (as my favourite Marcin Woli\nacute ski's classes).
%
% \changes{v0.98e}{06/09/23}{wrapped in \cs{@ifundefined} (a~bug fix:
%   before the bare \cs{newif} falsified the \cs{if@marginparsused}
%   switch when it had been defined and set True by the \pk{mwart}
%   class.)}

\@ifundefined{if@marginparsused}{\newif\if@marginparsused}{}
% This switch is copied from \pk{mwbk.cls} for compatibility with
% it. Thanks to it loading an \pk{mwcls} with |[withmarginpar]| option
% shall switch marginpars on in this package, too. 
%
% To be compatible with the standard classes, let's |\let|:

\@ifclassloaded{article}{\@marginparsusedtrue}{}
%\label{mparclause1}

\@ifclassloaded{report}{\@marginparsusedtrue}{}

\@ifclassloaded{book}{\@marginparsusedtrue}{}
% \label{mparclause2} And if you don't use \pk{mwcls} nor standard
% classes, then you have the options:
\DeclareOption{withmarginpar}{\@marginparsusedtrue}

\DeclareOption{nomarginpar}{\@marginparsusedfalse}
% The order of the above conditional switches and options is significant.
% Thanks to it the options are available also in the
% standard classes and in \pk{mwcls}.
%
% \stanza
% To make the code spaces blank (they are visible by default except
% the leading ones).


\DeclareOption{codespacesblank}{%
  \AtEndOfPackage{% to allow \inverb|codespacesgrey, codespacesblank|
  \AtBeginDocument{\CodeSpacesBlank}}}


\DeclareOption{codespacesgrey}{%
  % \changes{v0.99l}{2008/08/06}{added due to Will Robertson's
  %  suggestion}
  \AtEndOfPackage{% to put the declaration into the begin-document
    % hook after definition of \incs{visiblespace}.
    \AtBeginDocument{\CodeSpacesGrey}}}

\ProcessOptions


% \subdivision{The dependencies and preliminaries}
%
% We require another package of mine that provides some tricky macros
% analogous to the \LaTeX\ standard ones, such as |\newgif| and
% |\@ifnextcat|. Since 2008/08/08 it also makes \cs{if…} switches
% \cs{protected} (redefines \cs{newif})
\RequirePackage{gmutils}[2008/08/08]

% A~standard package for defining colours,
\RequirePackage{xcolor}
% and a~colour definition for the hyperlinks not to be too bright
\definecolor{deepblue}{rgb}{0,0,.85}

% And the standard package probably most important for \gmdoc:
% If the user doesn't load \pk{hyperref} with \hisher\ favourite
% options, we do, with \emph{ours}. If \heshe\ has
% done it, we change only the links' colour.
% 
% \changes[hyperref]{v0.97}{06/09/04}{linkcolor made deep blue}
% \changes[hyperref]{v0.99g}{2007/10/30}{added bypass of encoding for loading
% \pk{url}}

%^^A\@ifXeTeX{\XeTeXdefaultencoding "cp1250"}{}

\@ifpackageloaded{hyperref}{\hypersetup{colorlinks=true,
    linkcolor=deepblue, urlcolor=blue, filecolor=blue}}{%
  \RequirePackage[colorlinks=true, linkcolor=deepblue, urlcolor=blue,
  filecolor=blue, pdfstartview=FitH, pdfview=FitBH,
%^^A  \@ifXeTeX{xetex,}{}
  pdfpagemode=UseNone]{hyperref}}

%^^A\@ifXeTeX{\XeTeXdefaultencoding "utf-8"}{}
% \changes[hyperref]{v0.99k}{2008/08/04}{removed some lines testing if
% \XeTeX\ colliding with \pk{tikz} and most probably obsolete} 

% Now a~little addition to \pk{hyperref}, a~conditional hyperlinking
% possibility with the |\gmhypertarget| and |\gmiflink| macros. It
% \emph{has} to be loaded \emph{after} \pk{hyperref}.
\RequirePackage{gmiflink}
% And a~slight redefinition of \env{verbatim}, |\verb(*)| and
% providing of |\MakeShortVerb(*)|.
\RequirePackage{gmverb}[2008/08/20]

\if@noindex
  \AtBeginDocument{\gag@index}% for the latter macro see line
  % \ref{gag@index}.
\else
   \RequirePackage{makeidx}\makeindex
\fi

% Now, a~crucial statement about the code delimiter in the input file.
% Providing a~special declaration for the assignment is intended for
% documenting the packages that play with |%|'s
% |\catcode|. Some macros for such plays are defined
% \gmiflink[CDAnd]{further}.
%
% The declaration comes in the starred and unstarred version. The
% unstarred version besides declaring the code delimiter declares
% the same char as the verb(atim) `hyphen'. The starred version
% doesn't change the verb 'hyphen'. That is intended for the special
% tricks e.g.\ for the \env{oldmc} environment.
%
% If you want to change the verb `hyphen', there is the
% |\VerbHyphen\|\<one char> 
% declaration provided by \pk{gmverb}.
% 
% \changes{v0.98c}{06/9/8}{\cs{CodeDelim} renamed from a~rather confusing
% \cs{NewCommentChar}; also the internal \cs{code@delim} is renamed
% from as much confusing \cs{commentchar} and a~\cs{glet} for
% \cs{verb}s \cs{verbhyphen} is added; similarly
% \cs{[Un]CodeDelimAnd} renamed from \cs{[un]commentand}}
%
% \changes{v0.98m}{06/11/10}{\cs{CDAnd} and \cs{CDPerc} renamed from
% \cs{CodeDelimAnd} and \cs{UnCodeDelimAnd} and both those commands
% simplified to just declaring the code delimiter}
%
% \changes{v0.99a}{06/12/1}{split into the starred and unstarred
% versions}
%
\def\CodeDelim{\@ifstar\Code@Delim@St\Code@Delim}

\def\Code@Delim#1{%
  {\escapechar\m@ne
    \@xa\gdef\@xa\code@delim\@xa{\string#1}}}
% (|\@xa| is |\expandafter|, see \pk{gmutils}.)\DoNotIndex\@xa

\def\Code@Delim@St#1{\Code@Delim{#1}\VerbHyphen{#1}}

% It is an invariant of \gmdoc ing that |\code@delim| stores the
% current code delimiter (of catcode 12).
%
% The |\code@delim| should be \catother\ so a~space is not allowed as
% a~code delimiter. I~don't think it \emph{really} to be a~limitation.
%
% And let's assume you do as we all do:
\CodeDelim*\%

% We'll play with |\everypar|, a~bit, and if you use such things as
% the |{itemize}| environment, an error would occur if we didn't
% store the previous value of |\everypar| and didn't restore it at
% return to the narration. So let's assign a~|\toks| list to store the
% original |\everypar|:

\newtoks\gmd@preverypar 

\newcommand*\settexcodehangi{%
  \hangindent=\verbatimhangindent \hangafter=\@ne}% we'll use
% it in the inline comment case. |\verbatimhangindent| is provided by the
% \pk{gmverb} package and\equals3\,em by default.
% \DefIndex\@@settexcodehangi
\@ifdefinable\@@settexcodehangi{\let\@@settexcodehangi=\settexcodehangi}
%^^A~\gmdeverycodeline{\@@settexcodehangi}

% We'll play a~bit with |\leftskip|, so let the user have a~parameter
% instead. For normal text (i.e.\ the comment):

\newlength\TextIndent
% I~assume it's originally equal to |\leftskip|, i.e.\ |\z@|. And for
% the \TeX\ code:
% \HideAllDefining
\newlength\CodeIndent
% \label{CodeIndent}
% \Define\CodeIndent
\CodeIndent=1,5em\relax
% And the vertical space to be inserted where there are blank lines in the
% source code:
\@ifundefined{stanzaskip}{\newlength\stanzaskip}{}
% I~use |\stanzaskip| in \pk{gmverse} package and
% derivatives for typesetting poetry. A~computer program code \emph{is}
% poetry.
% \Define\stanzaskip
\stanzaskip=\medskipamount
\advance\stanzaskip by-.25\medskipamount% to preserve the stretch- and
% shrinkability.\par
%
%\stanza
% A~vertical space between the commentary and the code seems
% to enhance readability so declare
\newskip\CodeTopsep
\newskip\MacroTopsep

% And let's set them.  For \ae sthetic
% minimality\StraightEOL\footnote{The terms `minimal' and `minimalist'
%   used in \gmdoc\ are among others\ inspired by the \emph{South Park}
%   cartoon's episode \emph{Mr.\ Hankey The~Christmas (\dots)}\/ in
%   which `Philip Glass, a~Minimalist New York composer' appears in
%   a~`non-denominational non-offensive Christmas play' ^^A(
%   ;-)\,. (Philip Glass composed the music to the \emph{Qatsi}
%   trilogy among others).}\QueerEOL\ let's unify them and the other most important
% vertical spaces used in \gmdoc. I~think a~macro that gathers all
% these assignments may be handy.  
% \ResumeAllDefining
% \Define\MacroTopsep 
% \Define\CodeTopsep
% \Define\UniformSkips
\def\UniformSkips{%\label{UniformSkips}
  % \Define\CodeTopsep \Define\MacroTopsep
  \CodeTopsep=\stanzaskip
  \MacroTopsep=\stanzaskip
  \abovedisplayskip=\stanzaskip
  %\nostanza \leftskip0sp \gmdnoindent 
  %  |%% \abovedisplayshortskip|
  % remains untouched as it is 0.0\,pt plus 3.0\,pt by default.
  % \nostanza
  \belowdisplayskip=\stanzaskip
  \belowdisplayshortskip=.5\stanzaskip% due to DEK's idea of making the
  % short below display skip half of the normal.
  \advance\belowdisplayshortskip by\smallskipamount
  \advance\belowdisplayshortskip by-1\smallskipamount% We advance
  % \incs{be\+low\+dis\+play\+short\+skip} forth and back to
  % give it the \nlpercent\cs{small\+skip\+am\+ount}'s shrink- and
  % stretchability components.
  \topsep=\stanzaskip
  \partopsep=\z@
}
% We make it the default,
\UniformSkips
% \gmdnoindent but we allow you to change the benchmark glue
% i.e., |\stanzaskip| in the preamble and still have the other glues
% set due to it: we launch |\UniformSkips| again after the
% preamble. 
\AtBeginDocument{\UniformSkips}

% So, if you don't want them at all i.e., you don't want to set other
% glues due to |\stanzaskip|, you should use the following
% declaration. That shall discard the unwanted setting already placed
% in the |\begin{document}| hook.
%
\newcommand*\NonUniformSkips{\@relaxen\UniformSkips}
% Why do we launch |\UniformSkips| twice then? The first time is
% to set all the \gmdoc-specific glues \emph{somehow}, which allows
% you to set not all of them, and the second
% time to set them due to a~possible change of |\stanzaskip|.
%
% \stanza
% And let's define a~macro to insert a~space
% for a~chunk of documentation, e.g., to mark the beginning of new
% macro's explanation and code.
\newcommand*\chunkskip{%
  \par\addvspace{%
  \glueexpr\MacroTopsep
  \if@codeskipput-\CodeTopsep\fi
  \relax
}\@codeskipputgtrue}

% And, for a~smaller part of text,
\pdef\stanza{%
  \par\addvspace{%
    \glueexpr\stanzaskip
    \if@codeskipput-\CodeTopsep\fi
    \relax}\@codeskipputgtrue}

% Since the stanza skips are inserted automatically most often (cf.\ lines
% \ref{codeskip}, \ref{codeskip2}, \ref{codeskip3}, \ref{codeskip4},
% \ref{codeskip5}), sometimes you may need to forbid them.
\newcommand*\nostanza{% \changes{v0.99n}{2008/08/21}{added adding
  % negative skip if in vmode and \cs{par}}
  \par
  \if@codeskipput\unless\if@nostanza\vskip-\CodeTopsep\relax\fi\fi
  \@codeskipputgtrue\@nostanzagtrue
  \@afternarrgfalse\@aftercodegtrue}% In the `code
% to narration' case the first switch is enough but in the countercase
% `narration to code' both the second and third are necessary while
% the first is not.
%
%\stanza
% To count the lines where they have begun not before them\nostanza
\newgif\if@newline
% |\newgif| is |\newif| with global effect i.e., it defines |\...gtrue|
% and |\...gfalse| switchers that switch respective Boolean switch
% \emph{globally}. See \pk{gmutils} package for details.
% \stanza
%
% To handle the \ds\ directives not \emph{any} |%<...|\,.
% \Define\if@dsdir
\newgif\if@dsdir
% This switch will be falsified at the first char of a~code line. (We
% need a~switch independent of the one indicationg whether the line
% has or has not been counted because of two reasons: 1.\ line
% numbering is optional, 2.\ counting the line falsifies that switch
% \emph{before} the first char.)
%
% \subdivision{The core}
%
% Now we define main |\input|ing command that'll change catcodes.
% The macros used by it are defined later.
% 

\newcommand*\DocInput{\bgroup\@makeother\_\Doc@Input}

\begingroup\catcode`\^^M=\active%
\firstofone{\endgroup%
  \newcommand*{\Doc@Input}[1]{\egroup\begingroup%
    % \changes{v0.98}{06/09/05}{\cs{@makeother\protect\bslash_} added}
    % \DefIndex\gmd@inputname
    \edef\gmd@inputname{#1}% we'll use it in some notifications.
    % \DefIndex\gmd@currentlabel@before
    \let\gmd@currentlabel@before=\@currentlabel% we store it because
    % we'll do |\xdef|s of |\@currentlabel| to make proper references
    % to the line numbers so we want to restore current
    % |\@currentlabel| after our group.\
    % \CodeUsgIndex\clubpenalty \CodeUsgIndex\widowpenalty
    \gmd@setclubpenalty% we wrapped the assignment of |\clubpenalty|
    % in a~macro because we'll repeat it twice more.
    \@clubpenalty\clubpenalty \widowpenalty=3333 % Most paragraphs of the code will be
    % one-line most probably and many of the narration, too.\par\
    % \changes[\DocInput]{v0.95}{06/08/15}{\cs{club-}
    % and \cs{widowpenalty} set both to 3333}
    %\CodeUsgIndex\tolerance
    \tolerance=1000 % as in \docfm.
    % ^^A    \catcode`\^^M=\active% redundant with line 2304
    % \CodeUsgIndex\code@delim
    \@xa\@makeother\csname\code@delim\endcsname%
    % \CodeUsgIndex\gmd@resetlinecount
    \gmd@resetlinecount% due to the option |uresetlinecount|
    % we reset the linenumber counter or do nothing.
    % \Define*{^^M}
    \QueerEOL% \changes{v0.99m}{2008/08/09}{there was
    % \cs{let}\hathat{M} but \cs{QueerEOL} is better: it also
    % redefines \cs{}\hathat M} It has to be before the
    % begin-input-hook to allow change by that hook.
    % \CodeUsgIndex\@beginputhook
    \@beginputhook% my first use of it is to redefine |\maketitle|
    % just at this point not globally. \CodeUsgIndex\everypar
    \everypar=\@xa{\@xa\@codetonarrskip\the\everypar}%
    % \Define\gmd@guardedinput
    \edef\gmd@guardedinput{%
      \@nx\@@input #1\relax% |\@nx| is
      % |\noexpand|, see \pk{gmutils}.\DoNotIndex\@nx
      % \incs{@@input} is the 
      % true \TeX's \incs{input}. \CodeUsgIndex\EOFMark
      \gmd@iihook% cf.\ line \ref{iihook}
      \@nx\EOFMark% to pretty finish the input, see
      % line~\ref{eofMark}.\CodeUsgIndex\code@delim
      \@nx\CodeDelim\@xa\@nx\csname\code@delim\endcsname% to
      % ensure the code delimiter is the same as at the beginning of
      % input. 
      % \changes[\DocInput]{v0.99c}{2007/03/02}{added ensuring the
      % code delimiter to be the same at the end as at the beginning}
      \@nx^^M\code@delim%
      % \label{guardians}
    }% we add guardians after
    % |\input|ing a~file; somehow an error occurred without them.
    \catcode`\%=9 % for \docfm -compatibility.\label{ignorePercent}
    \setcounter{CheckSum}{0}% we initialize the counter for the number
    % of the escape chars (the assignment is |\global|).
    \everyeof{\relax}% |\@nx| moved not to spoil input of toc e.g.
    \@xa\@xa\@xa^^M\gmd@guardedinput%\label{eeeEOL}
    \par%
    % \CodeUsgIndex\@endinputhook
    \@endinputhook% It's a~hook to let postpone
    % some stuff till the end of input. We use it e.g.\ for the
    % \docfm-(not)likeliness notifications.
    \glet\@currentlabel=\gmd@currentlabel@before% we restore
    % value from before this group. In a~very special case this could
    % cause unexpected behaviour of crossrefs, but anyway we acted
    % globally and so acts \pk{hyperref}.
    \endgroup%
  }% end of |\Doc@Input|'s definition.
}% end of |\firstofone|'s argument.

% So, having the main macro outlined, let's fill in the details.
%
% First, define the queer \acro{EOL}. We define a~macro that |^^M| will be
% let to. |\gmd@textEOL|
% will be used also for checking the |%^^M| case (|\@ifnextchar|
% does |\ifx|).
%

\pdef\gmd@textEOL{ % a~space just like in normal
  % \TeX. We put it first to  % cooperate with \inverb|\^^M|'s
  % |\expandafter\ignorespaces|. It's  % no  % problem since a~space
  % | |${}_{10}$ doesn't drive \TeX\ out of  % the vmode.
  \ifhmode\@afternarrgtrue\@codeskipputgfalse\fi% being in
  % the horizontal mode means we've just typeset some narration so we
  % turn the respective switches: the one bringing the message `we are
  % after narration' to True (|@afternarr|) and the `we have put the
  % code-narration glue' to False (|@codeskipput|). Since we are in
  % a~verbatim group and the information should be brought outside it,
  % we switch the switches globally (the letter |g| in both).
  \@newlinegtrue% to |\refstep| the lines' counter at the proper
  % point.
  \@dsdirgtrue% to handle the \ds\ directives.
  \@xa\@trimandstore\the\everypar\@trimandstore%we store the
  % previous value of |\everypar| register to restore it at
  % a~proper point. See line \ref{@trimandstore} for the details.
  \begingroup%^^A ##### maybe we prefer to restore the genuine |\par|
  % ^^A~before the group?
% ^^A      \let\gmd@narrpar\par% we store the possibly redefined |\par| to
% ^^A~typeset the previous narration appropriately.
% ^^A      \def\par{\gmd@narrpar\let\par\@@par}% the first |\par| will be
% ^^A~the one brought from the narration but then, 
  \gmd@setclubpenalty% Most paragraphs will be
  % one-line most probably. Since some sectioning commands may change
  % \incs{clubpenalty}, we set it again here and also after this
  % group.
  \aftergroup\gmd@setclubpenalty%
  \let\par\@@par% inside the verbatim group we wish |\par| to be genuine.
  % \CodeUsgIndex\ttverbatim
  \ttverbatim% it does |\tt| and makes specials
  % other or |\active|-and-breakable.
  \gmd@DoTeXCodeSpace%
  \@makeother\|% because |\ttverbatim| doesn't do that.
  \MakePrivateLetters% see line \ref{MPL}.\par
  \@xa\@makeother\code@delim% we are
  % almost sure the code comment char is among the chars having
  % been \catother ed already. For `almost' see the
  % \gmiflink[IndexInput]{\cs{IndexInput}} macro's definition.\par
  % So, we've opened a~verbatim group and want to peek at the next
  % character. If it's |%|, then we just continue narration, else we
  % process the leading spaces supposed there are any and, if after
  % them is a~|%|, we just continue the commentary as in the
  % previous case or else we typeset the \TeX\ code.
  \@xa\@ifnextchar\@xa{\code@delim}{%\label{ifContNarr}
    % \CodeUsgIndex\gmd@continuenarration
    \gmd@continuenarration}{% \CodeUsgIndex\gmd@dolspaces
    \gmd@dolspaces% it will launch |\gmd@typesettexcode|.
  }% end of |\@ifnextchar|'s else.
}% end of |\gmd@textEOL|'s definition.

\def\gmd@setclubpenalty{\clubpenalty=3333 }

% \stanza
% For convenient adding things to the begin- and endinput hooks:
\def\AtEndInput{\g@addto@macro\@endinputhook}
\def\@endinputhook{}
%\label{@endinputhook}
% Simili modo
\def\AtBegInput{\g@addto@macro\@beginputhook}
\def\@beginputhook{}

% For the index input hooking now declare a~macro, we define it
% another way at line \ref{iihook}.
\emptify\gmd@iihook

% And let's use it instantly to avoid a~disaster while reading in the
% table of contents.
% \DefIndex\gmd@@toc
\AtBegInput{\let\gmd@@toc\tableofcontents
  \def\tableofcontents{% \label{straighttoc}
    \@ifQueerEOL{\StraightEOL\gmd@@toc\QueerEOL}%
    {\gmd@@toc}}}

% As you'll learn from lines \ref{QueerEOL} and \ref{StraightEOL}, we
% use those two strange declarations to change and restore the very
% special meaning of the line end. Without such changes
% |\tableofcontents| would cause a~disaster (it did indeed). And to
% check the catcode of |^^M| is the r\ocircum le of |\@ifEOLactive|:
%
% \changes{v0.98a}{06/09/06}{\cs{tableofcontents}, \cs{PrintIndex}
% and \cs{PrintChanges} modified to work properly in the `queer line
% ends' environment.}

\long\def\@ifEOLactive#1#2{%
  \ifnum\catcode`\^^M=\active \afterfi{#1}\else\afterfi{#2}\fi}

\foone\obeylines{%
  \long\def\@ifQueerEOL#1#2{%% \changes{v0.98a}{06/09/06}{added}
    \@ifEOLactive{\ifx^^M\gmd@textEOL\afterfi{#1}\else\afterfi{#2}\fi}%
    {#2}}% of \cs{@ifQueerEOL}
}% of \cs{foone}

% The declaration below is useful if you
% wish to put sth.\ just in the nearest input/included file and no
% else: at the moment of putting the stuff it will erase it from the
% hook. You may declare several |\AtBegInputOnce|s, they add up.
%
%^^A Define*{hook@oncecnt}
%^^A CodeDefIndex*\c@hook@oncecnt
%^^A\newcounter{hook@oncecnt}
% \Define\gmd@ABIOnce
\@emptify\gmd@ABIOnce
\AtBegInput\gmd@ABIOnce

\long\def\AtBegInputOnce#1{%
% \changes{v0.98a}{06/09/05}{The counter \cs[]{hook@oncecnt} added
%   to number the self-destructing cs's (thence the hooks add up) and
%   the prefix changed to \cs[]{gmd/AtBI/NeuroOncer}}
% \changes{v0.98l}{06/10/26}{After the Tiger's suggestion, defining
%   a~unique macro for each use of \* substituted with just one macro in
%   the begin input hook and adding to this macro.}
%^^A  \stepcounter{hook@oncecnt}%
%^^A  \@xa\long\@xa\edef% \CodeUsgIndex*{NeuroOncer}
%^^A    \csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname{%
%^^A      \@nx\glet\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname\relax}%
%^^A  \@xa\addtomacro\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname{#1}%
%^^A  \@xa\AtBegInput\csname gmd/AtBI/NeuroOncer\the\c@hook@oncecnt\endcsname
  \gaddtomacro\gmd@ABIOnce{\g@emptify\gmd@ABIOnce#1}}

% Many tries of finishing the input cleanly led me to setting the
% guardians as in line \ref{guardians} and to

\def\EOFMark{\<eof>}
% \label{eofMark}Other solutions did print the last code delimiter or
% would require managing a~special case for the macros typesetting
% \TeX\ code to suppress the last line's numbering etc.
%
% If you don't like it, see line \ref{NoEOF}.
% \stanza
%
% Due to the |codespacesblank| option in the line \ref{cspb} we launch
% the macro defined below to change the meaning of a~\pk{gmdoc}-kernel
% macro.
% \DefIndex\gmd@DoTeXCodeSpace
\begin{obeyspaces}%
\gdef\CodeSpacesVisible{%
\def\gmd@DoTeXCodeSpace{%
\obeyspaces\let =\breakablevisspace}}%
% \stanza
% \Define\CodeSpacesBlank
% \changes{v0.98a}{06/09/06}{a~kernel \cs{gmd@verbatimspace} renamed
%   to \cs{gmd@texcodespace} and a~bug fixed.}
% \CodeUsgIndex\gmobeyspaces
% \DefIndex\gmd@texcodespace
\gdef\CodeSpacesBlank{%
\let\gmd@DoTeXCodeSpace\gmobeyspaces%
\let\gmd@texcodespace=\ }% the latter |\let| is for the |\if...|s.
%\stanza
% \Define\CodeSpacesSmall
\gdef\CodeSpacesSmall{%
\def\gmd@DoTeXCodeSpace{%
\obeyspaces\def {\,\hskip\z@}}%
\def\gmd@texcodespace{\,\hskip\z@}}%
%\stanza
\end{obeyspaces}

\def\CodeSpacesGrey{%
  % \changes{v0.99l}{2008/08/06}{added due to Will Robertson's
  %   suggestion}
  \CodeSpacesVisible
  \VisSpacesGrey% defined in \pk{gmverb}
}%

% Note that \cs{CodeSpacesVisible} doesn't revert \cs{CodeSpacesGrey}.


\CodeSpacesVisible


% How the continuing of the narration should look like?
\def\gmd@continuenarration{%
  \endgroup
  \gmd@cpnarrline% see \gmiflink[countnarr]{below}.
  \@xa\@trimandstore\the\everypar\@trimandstore
  \everypar=\@xa{\@xa\@codetonarrskip\the\everypar}%
  \@xa\gmd@checkifEOL\@gobble}
% Simple, isn't it? (We gobble the `other' code delimiter. Despite of
% |\egroup| it's \catother\ because it was touched by |\futurelet|
% contained in |\@ifnextchar| in line \ref{ifContNarr}. And in line
% \ref{ContNarr2} it's been read as \catother. That's why it
% works in spite of that |%| is of category `ignored'.)

\if@countalllines
%^^A   erased obsolete code is backed up in gmdoc.sty~5~.
%\gmhypertarget[countnarr]{If the} |countalllines| option is in force,
% we get the count of lines from the \cs{inputlineno} primitive. But
% if the option is |countalllines*|, we want to print the line number.
%^^A   \def\gmd@countnarrline{%
%^^A     \if@newline
%^^A       \gmd@countnarrline@
%^^A     \fi}% \DefIndex\gmd@countnarrline

  \def\gmd@countnarrline@{%
      \gmd@grefstep{codelinenum}\@newlinegfalse
      \everypar=\@xa{%
        \@xa\@codetonarrskip\the\gmd@preverypar}%^^A
      % the \cs{hy\+p\+er\+lab\+el\+@\+li\+ne} macro puts
      % a~hypertarget in a~|\raise| i.e., drives \TeX\ into the
      % horizontal mode so |\everypar| shall be issued. Therefore we
      % should restore it.
    }% of \cs{gmd@countnarrline@}

    \def\gmd@grefstep#1{% instead of diligent redefining all possible
      % commands and environments we just assign the current value of
      % the respective \TeX's primitive to the \env{codelinenum}
      % counter. Note we decrease it by $-1$ to get the proper value
      % for the next line. (Well, I~don't quite know why, but it
      % works.) %^^A~we'll step its value by 1 because it will be put
      % ^^Aat the beninning of the \emph{next} line.
      \ifnum\value{#1}<\inputlineno
        \csname c@#1\endcsname\numexpr\inputlineno-1\relax
        \ifvmode\leavevmode\fi% this line is added 2008/08/10 after an
        % ^^A( 
        % all-night debuggery ;-) that showed that at one point
        % \incs{gmd@grefstep} was called in vmode which caused adding
        % \incs{penalty 10000} to the main vertical list and thus
        % forbidding pagebreak during entire \inenv{oldmc}.
        \grefstepcounter{#1}%
      \fi}% We wrap stepping the counter in an \incs{ifnum} to avoid
    % repetition of the same ref-value (what would result in the
    % ``multiply defined labels'' warning).\par\
    % The
    % \cs{grefstepcounter} macro, defined in \pk{gmverb}, is
    % a~global
    % version of \cs{ref\-step\-count\-er}, observing the redefinition
    % made
    % to \incs{refstepcounter} by \pk{hyperref}.

    \if@printalllinenos% Note that checking this swich makes only
    % sense when |countalllines| is true.
      \def\gmd@cpnarrline{% count and print narration line
        \if@newline
          \gmd@countnarrline@
          \hyperlabel@line
          {\LineNumFont\thecodelinenum}\,\ignorespaces}%
        \fi}
      \else% not |printalllinenos|
        \emptify\gmd@cpnarrline
      \fi

\def\gmd@ctallsetup{% In the \inenv{oldmc} environments and with the
  % \incs{FileInfo} declaration (when % \inenv{countalllines} option
  % is in force) the  % code is gobbled as an argument of a~macro and
  % % then processed at one place (at the end of  % \inenv{oldmc}
  % % e.g.) so if we used  % \incs{inputlineno}, we would have got all
  % % the  % lines with the same number. But we only set the counter
  % % not \incs{refstep} it to avoid putting a~hypertarget.
  \setcounter{codelinenum}{\inputlineno}% it's global.
  \let\gmd@grefstep\hgrefstepcounter}
  
\else% not |countallines| (and therefore we won't print the narration
     % lines' numbers either)
  \@emptify\gmd@cpnarrline
  \let\gmd@grefstep\hgrefstepcounter% \label{let grefstep} if we don't
  % want to count all the  lines, we only \incs{ref}-increase the
  % counter in the code layer. 
  \emptify\gmd@ctallsetup
\fi% of |\if@countalllines|

\def\skiplines{\bgroup
  \let\do\@makeother \dospecials % not \incs{@sanitize} because the
  % latter doesn't recatcode braces and we want all to be quieten.\ilrr
%^^A  \catcode`\^^M\active what was it for? for countalllines, but
%^^A~there's no need of.
  \gmd@skiplines}

  \edef\gmu@tempa{%
    \long\def\@nx\gmd@skiplines##1\bslash endskiplines{\egroup}}
  \gmu@tempa


% And typesetting the \TeX\ code?
\foone\obeylines{% \DefIndex\gmd@typesettexcode
  \def\gmd@typesettexcode{%
    \gmd@parfixclosingspace% it's to eat a~space closing the
    % paragraph, see \gmiflink[closingspace]{below}. It contains
    % |\par|.
    %
    % ^^A\special{color push gray 0.2645}%
    % A~verbatim group has already been opened by \cs{ttverb\+at\+im} and
    % additional \cs{cat\-code}.
    \everypar={\@@settexcodehangi}% At first attempt we thought
    % of giving the user a~|\toks| list to insert at the beginning of
    % every code line, but what for?
    % \Define*{^^M}^^A
    \def^^M{% \TeX\ code \acro{EOL}
      \@newlinegtrue% to |\refstep| the counter in proper place.
      \@dsdirgtrue% to handle the \ds\ directives.
      \global\gmd@closingspacewd=\z@% \label{noclosingspace}we
      % don't wish to eat a~closing space after a~codeline, because
      % there isn't any and a~negative rigid |\hskip| added to
      % |\parfillskip| would produce a~blank line.
      \ifhmode\par\@codeskipputgfalse\else%
        \if@codeskipput%
        \else\addvspace{\stanzaskip}\@codeskipputgtrue%
        \fi% if we've just met a~blank (code) line, we insert
        % a~|\stanzaskip| glue.
        % \label{codeskip}
      \fi%
      \prevhmodegfalse% we want to know later that now we are in the
      % vmode. 
      % ^^A\special{color push gray 0.2666}%
      \@ifnextchar{\gmd@texcodespace}{%
        \@dsdirgfalse\gmd@dolspaces}{\gmd@charbychar}%
    }% end of |^^M|'s definition.\label{debug!2}
    % \DefIndex\gmd@texcodeEOL
    \let\gmd@texcodeEOL=^^M% for further checks inside |\gmd@charbychar|.
    \raggedright\leftskip=\CodeIndent%
    \if@aftercode%
      \gmd@nocodeskip1{iaC}%
    \else%
      \if@afternarr%
      % ^^A~\def^^C{\showthe\hyphenpenalty\showthe\rightskip}
        \if@codeskipput\else%
          \gmd@codeskip1\@aftercodegfalse%
        \fi% \label{codeskip3}
      \else\gmd@nocodeskip1{naN}%
      \fi%
    \fi% if now we are
    % switching from the narration into the code, we insert a~proper
    % vertical space.
    \@aftercodegtrue\@afternarrgfalse%
    %^^A\special{color push gray 0.2682}% before that penalty
    \ifdim\gmd@ldspaceswd>\z@% and here the leading spaces.
      \leavevmode\@dsdirgfalse%
      \if@newline\gmd@grefstep{codelinenum}\@newlinegfalse%
      \fi%
      \printlinenumber% if we don't want the lines to be numbered,
      % the respective option \incs{let}s this \CS to \incs{relax}.
      \hyperlabel@line%
      %^^A\special{color push gray 0.2689}% seems O.K.
      \mark@envir% index and/or marginize an environment if there is
      % some to be done so, see line \ref{mark@envir}.
      \hskip\gmd@ldspaceswd%
      \advance\hangindent by\gmd@ldspaceswd%
      \xdef\settexcodehangi{%
        \@nx\hangindent=\the\hangindent% and also set the
        % hanging indent setting for the same line comment case. \acro{BTW}.,
        % this |%| or rather lack of it costed me five hours of
        % debugging and rewriting. Active lineends require extreme
        % caution. 
        \@nx\hangafter=1\space}%^^A~\@nx\relax
    \else%
      \glet\settexcodehangi=\@@settexcodehangi%\\
      %|%| |\printlinenumber| here produced line numbers for blank lines
      % which is what we don't want.
    \fi% of |\ifdim|
    \gmd@ldspaceswd=\z@%
    \prevhmodegfalse% we have done |\par| so we are not in the
    % hmode.
    \@aftercodegtrue% we want to know later that now we are
    % typesetting a~codeline.
    \if@ilgroup\aftergroup\egroup\@ilgroupfalse\fi% when we are in the inline
    % comment group (for ragged right or justified), we want
    % to \label{inline.egroup.2}
    % close it. But if we did it
    % here, we would close the verbatim group for the code. But we set
    % the swich false not to repeat \inverb|\aftergroup\egroup|.
    % ^^A\special{color push gray 0.2712}% before that penalty
    \gmd@charbychar% we'll eat the code char by char to scan all the
    % macros and thus to deal properly with the case |\%| in which the
    % |%| will be scanned and won't
    % launch closing of the verbatim group.
  }% of |\gmd@typesettexcode|.
}% of |\foone\obeylines|.
%
% \stanza
%
% Now let's deal with the leading spaces once forever. We wish not to
% typeset | |s but to add the width of every leading space to the
% paragraph's indent and to the hanging indent, but only if there'll
% be any code character not being |%| in this line (e.g., the end of
% line). If there'll be only |%|, we want just to continue the comment
% or start a~new one. (We don't have to worry about whether we should
% |\par| or not.) 
% \DefIndex\gmd@spacewd
\newlength\gmd@spacewd% to store the width of a~(leading) 
% | |\catother.
% \DefIndex\gmd@ldspaceswd
\newlength\gmd@ldspaceswd% to store total length of gobbled leading
                          %spaces.

% It costed me some time to reach that in my verbatim scope a~space
% isn't \catother\ but \catactive, namely |\let| to
% |\breakablevisspace|.
% So let us |\let| for future:
% \Define\gmd@texcodespace
\let\gmd@texcodespace=\breakablevisspace
% And now let's try to deal with those spaces.

\def\gmd@dolspaces{%
  \ifx\gmd@texcodespace\@let@token
    \@dsdirgfalse
    \afterfi{\settowidth{\gmd@spacewd}{\visiblespace}%
    \gmd@ldspaceswd=\z@
    \gmd@eatlspace}%
  \else\afterfi{% about this smart macro and other of its family see
    % \pk{gmutils} sec.\,3.
    % ^^A \special{color push gray 0.2748}% debug of \penalty10000
    % ^^A~2008/08/10 was far
    % ^^A \ifnum\inputlineno>1016 \ifnum\inputlineno<1050 \show\par\fi\fi
    % ^^A~O.K.
    \if@afternarr\if@aftercode
        \ifilrr\bgroup \gmd@setilrr\fi
    \fi\fi
    \par% possibly after narration 
    \if@afternarr\if@aftercode
        \ifilrr\egroup\fi
    \fi\fi
    \gmd@typesettexcode}%
  \fi}

% And now, the iterating inner macro that'll eat the leading spaces.

\def\gmd@eatlspace#1{%
  \ifx\gmd@texcodespace#1%
    \advance\gmd@ldspaceswd by\gmd@spacewd% we don't
    % \incs{advance} it \incs{global}ly because the current group may be closed
    % iff we meet \inverb|%| and then we'll won't indent the line anyway.\ilrr
    \afteriffifi\gmd@eatlspace
  \else
    \if\code@delim\@nx#1%
      \gmd@ldspaceswd=\z@
      \afterfifi{\gmd@continuenarration#1}%\label{ContNarr2}
      % \changes{v0.99n}{2008/08/30}{\cs{afterfifi} added---a~bug fix}
    \else \afterfifi{\gmd@typesettexcode#1}%
    \fi
  \fi}%

% We want to know whether we were in hmode before reading current
% |\code@delim|. We'll need to switch the switch globally.
 
\newgif\ifprevhmode

% \addvspace\medskipamount
%
% And the main iterating inner macro which eats every single char of
% verbatim text to check the end. The case |\%| should be excluded
% and it is indeed.

\newcommand*\gmd@charbychar[1]{%
  \ifhmode\prevhmodegtrue
  \else\prevhmodegfalse
  % ^^A~\special{color push gray 0.2789}%
  \fi 
  \if\code@delim\@nx#1%
    \def\next{% occurs when next a~\cs{hskip4.875pt} is to be put
      % ^^A\special{color push gray 0.2791}% O.K.
      \gmd@percenthack% to typeset |%| if a~comment
    % continues the~codeline.
    \endgroup%
    \gmd@checkifEOLmixd}% to see if next is |^^M| and then do |\par|.
  \else% i.e., we've not met the code delimiter
    \ifx\relax#1\def\next{%
      % ^^A\special{color push gray 0.2798}%
      \endgroup}% special case of end of file thanks to |\everyeof|.
    \else
      \if\code@escape@char\@nx#1%
        \@dsdirgfalse% yes, just here not before the whole |\if| because
        % then we would discard checking for \ds\ directives doable by
        % the active |%| at the `old macrocode' setting.
        \def\next{%
%^^A \debug@special{2808}%
          \gmd@counttheline#1\scan@macro}%
      \else
        \def\next{%
%^^A \debug@special{2806}% before penalty 
          \gmd@EOLorcharbychar#1}%
      \fi
    \fi
  \fi\next}

\def\debug@special#1{%
  \ifhmode\special{color push gray 0.#1}%
  \else\special{color push gray 0.#1000}\fi}

% One more inner macro because |^^M| in \TeX\ code wants to peek at the
% next char and possibly launch |\gmd@charbychar|. We deal with
% counting the lines thorougly. Increasing the counter is divided into
% cases and it's very low level in one case because |\refstepcounter| and
% |\stepcounter| added some stuff that caused blank lines, at
% least with \pk {hyperref} package loaded.
\def\gmd@EOLorcharbychar#1{%
                             %^^A \debug@special{2829}%
  \ifx\gmd@texcodeEOL#1%
    \if@newline
    % ^^A\special{color push gray 0.281600}% no occurence
    % ^^A      \if@countalllines\global\advance\c@codelinenum by\@ne obsolete
    % ^^A\fi
      \@newlinegfalse
    \fi
    \afterfi{#1}%\label{printhashone1}here we print |#1|.
  \else% i.e., |#1| is \emph{not} a~(very active) line end,
    \afterfi
    {%^^A \debug@special{2839}% this occurs frequently
\gmd@counttheline#1\gmd@charbychar}% \label{printhashone2}or here
    % we print |#1|. Here we would also possibly mark an environment
    % but there's no need of it because declaring an environment to
    % be marked requires a~bit of commentary and here we are after
    % a~code |^^M| with no commentary.
 \fi}

\def\gmd@counttheline{%
  \ifvmode
    \if@newline
      \leavevmode
      %^^A \debug@special{2851}%
      \gmd@grefstep{codelinenum}\@newlinegfalse
      \hyperlabel@line
    \fi
    %^^A\debug@special{2853}% 
    \printlinenumber
    % ^^A\debug@special{2855}% 
    \mark@envir
  \else% not vmode
    \if@newline
    % ^^A\special{color push gray 0.2842}% didn't occur
      \gmd@grefstep{codelinenum}\@newlinegfalse
      \hyperlabel@line
    \fi
  \fi}

% If before reading current |%| char we were in horizontal mode, then
% we wish to print |%| (or another code delimiter).

\def\gmd@percenthack{%
  \ifprevhmode\code@delim\aftergroup~% We add a~space after |%|,
  % because I~think it looks better. It's done |\aftergroup| to make
  % the spaces possible after the |%| not to be
  % typeset.
  % \changes{v0.99n}{2008/08/21}{\cs{space} replaced with a~tilde to
  % forbid a~linebreak before an inline comment}
  \else\aftergroup\gmd@narrcheckifds@ne% remember that
  % \cs{gmd\-@\-pre\-cent\-hack} is only called when we've the code
  % delimiter and soon we'll close the verbatim group and right after
  % |\endgroup| there waits |\gmd@checkifEOLmixd|.
  \fi}

\def\gmd@narrcheckifds@ne#1{%^^A\typeout{narr@ne if ds \on@line}%
  \@dsdirgfalse\@ifnextchar<{%
    \@xa\gmd@docstripdirective\@gobble}{#1}}

% The macro below is used to look for the |%^^M| case to make
% a~commented blank line make a~new paragraph.
% Long searched and very simple at last.

\def\gmd@checkifEOL{%
  \gmd@cpnarrline
  \everypar=\@xa{\@xa\@codetonarrskip% we add the
    % macro that'll insert a~vertical space if we leave the code and
    % enter the narration.
    \the\gmd@preverypar}%
  \@ifnextchar{\gmd@textEOL}{%
  %^^A\@ifnextMac{%^^A}
    \@dsdirgfalse
    \par\ignorespaces}{%
    \gmd@narrcheckifds}}%

% We check if it's |%<|, a~\ds\ directive that is.
\def\gmd@narrcheckifds{%^^A\typeout{narr if ds \on@line}%
  \@dsdirgfalse\@ifnextchar<{%
    \@xa\gmd@docstripdirective\@gobble}{\ignorespaces}}
    

% In the `mixed' line case it should be a~bit more complex, though. On
% the other hand, there's no need to checking for \ds\ directives.

\def\gmd@checkifEOLmixd{%
  \gmd@cpnarrline
  \everypar=\@xa{\@xa\@codetonarrskip\the\gmd@preverypar}%
  % 
  % \label{longlinethatshouldbebroken}
  \@afternarrgfalse\@aftercodegtrue
  \ifhmode\@codeskipputgfalse\fi
  \@ifnextchar{\gmd@textEOL}{%
  %^^A\@ifnextMac{%^^A}
    {\raggedright\gmd@endpe\par}% without \incs{raggedright} this
    % \incs{par}
    % would be justified which is not appropriate for a~long codeline
    % that should be broken, e.g., \ref{longlinethatshouldbebroken}.
    \prevhmodegfalse
    \gmd@endpe\ignorespaces}{% 
    % If a~codeline ends with |%|
    % (|prevhmode|${}=={}$True) first |\gmd@endpe| sets the parameters
    % at the \TeX\ code values and |\par| closes a~paragraph and the
    % latter |\gmd@endpe| sets the parameters at the narration values.
    % In the other case both |\gmd@endpe|s do the same
    % and |\par| between them does nothing.
    % \DefIndex\par
    \def\par{% the narration \cs{par}.
      \ifhmode% (I~added this |\ifhmode| as a~result of a~heavy
      % debug.) 
        \if@afternarr\if@aftercode
            \unless\if@ilgroup\bgroup\@ilgrouptrue\fi
            \ifilrr\gmd@setilrr\fi
        \fi\fi
        \@@par
        \if@afternarr
          \if@aftercode
          \if@ilgroup\egroup\fi% \label{inline.egroup.1}if we are both after code
            % and after narration it means we are after an inline
            % comment. Then we probably end a~group opened in line
            % \ref{inline.bgroup} 
            \if@codeskipput\else\gmd@codeskip2\@aftercodegfalse\fi
            %\label{codeskip4}
          \else\gmd@nocodeskip2{naC}%
          \fi
        \else\gmd@nocodeskip2{naN}%
        \fi
        \prevhmodegfalse\gmd@endpe% when taken out of |\ifhmode|, this
        % line caused some codeline numbers were typeset with
        % |\leftskip|${}=0$.
        \everypar=\@xa{%
          \@xa\@codetonarrskip\the\gmd@preverypar}%
        \let\par\@@par%
      \fi}% of \cs{par}.
    \gmd@endpe\ignorespaces}}

% As we announced, we play with |\leftskip| inside the verbatim
% group and therefore we wish to restore normal |\leftskip| when back to
% normal text i.e.\ the commentary. But, if normal text starts in the
% same line as the code, then we still wish to indent such a~line.

\def\gmd@endpe{%
  \ifprevhmode
    \settexcodehangi%\unskip ndent
    \leftskip=\CodeIndent
%^^A    \typeout{gmd@endpe in prevhmode \on@line}%
  \else
    \leftskip=\TextIndent
    \hangindent=\z@
    \everypar=\@xa{%
      \@xa\@codetonarrskip\the\gmd@preverypar}%
%^^A    \typeout{gmd@endpe in not prevhmode \on@line}%
  \fi}


% Now a~special treatment for an inline comment:
\newif\ifilrr

\def\ilrr{%\changes{v0.99n}{2008/08/21}{added}
  \if@aftercode
    \unless\if@ilgroup\bgroup\@ilgrouptrue\fi% \label{inline.bgroup} If we are
    % `aftercode', then we are in an inline comment. Then we open
    % a~group to be able to declare e.g.\ \cs{raggedright} for that
    % comment only. This group is closed in line \ref{inline.egroup.1}
    % or \ref{inline.egroup.2}.
    \ilrrtrue
  \fi}

\newif\if@ilgroup

\def\gmd@setilrr{\rightskip0ptplus\textwidth}

\def\ilju{% when inline comments are ragged right in general but we
  % want just this one to be justified.
  \if@aftercode
    \unless\if@ilgroup\bgroup\@ilgrouptrue\fi
    \ilrrfalse
  \fi}

\def\verbcodecorr{%\changes{v0.99n}{2008/08/21}{added}
  % a~correction of vertical spaces between a~\env{verbatim} and
  % code. We put also a~\cs{par} to allow parindent in the next
  % commentary. 
  \vskip-\lastskip\vskip-4\CodeTopsep\vskip3\CodeTopsep\par}

%
%
% \subdivision{Numbering (or not) of the lines}
%
% Maybe you want codelines to be numbered and maybe you want to
% reset the counter within sections.
\if@uresetlinecount% with |uresetlinecount| option\dots
  \@relaxen\gmd@resetlinecount% \dots\  we turn
  % resetting the counter by \cs{Doc\+In\+put} off\dots
  \newcommand*\resetlinecountwith[1]{%
    \newcounter{codelinenum}[#1]}% \dots\ and provide a~new
  % declaration of the counter.
\else% With the option turned off\dots
  \newcounter{DocInputsCount}% 
  \newcounter{codelinenum}[DocInputsCount]% \dots\ we declare the
  % |\DocInput|s' number counter andthe codeline counter
  % to be reset with stepping of it.
  % \changes[\c@DocInputsCount]{v0.98c}{06/9/8}{added for fixing
  % duplication of \pk{hyperref} labels in the case of a~multiple
  % \cs{DocInput}}
  \newcommand*\gmd@resetlinecount{\stepcounter{DocInputsCount}}% \dots 
  % and let the |\DocInput| increment the |\DocInput|s number count
  % and thus reset the codeline count. It's for unique naming of the
  % \pk{hyperref} labels.
\fi

% Let's define printing the line number as we did in \pk{gmvb}
% package.
\newcommand*\printlinenumber{%
  \leavevmode\llap{\rlap{\LineNumFont$\phantom{999}$\llap{\thecodelinenum}}%
    \hskip\leftskip}}

\def\LineNumFont{\normalfont\tiny}

\if@linesnotnum\@relaxen\printlinenumber\fi

\newcommand*\hyperlabel@line{%
  \if@pageindex% It's good to be able to switch it any time not just
  % define it once according to the value of the switch set by the
  % option.
  \else
    \raisebox{2ex}[1ex][\z@]{\gmhypertarget[clnum.%
      \HLPrefix\arabic{codelinenum}]{}}%
  \fi}

%
% \subdivision{Spacing with \cs{everypar}}
%
% Last but not least, let's define the macro inserting a~vertical space
% between the code and the narration.  Its parameter is
% a~\gmhypertarget[relic parameter]{relic} of a~very heavy debug of
% the automatic vspacing mechanism. Let it remain at least until this
% package is 2.0 version.
\newcommand*\gmd@codeskip[1]{%
  \@@par\addvspace\CodeTopsep
  \@codeskipputgtrue\@nostanzagfalse}
%\label{codeskip2}

% Sometimes we add the |\CodeTopsep| vertical space in
% |\everypar|. When this happens, first we remove the |\parindent|
% empty box, but this doesn't reverse putting |\parskip| to the main
% vertical list. And if |\parskip| is put, |\addvspace| shall see it
% not the `true' last skip. \Describe*{@codeskipput}Therefore we need
% a~Boolean switch to keep the knowledge of putting similar vskip
% before |\parskip|.
% \Define\if@codeskipput
\newgif\if@codeskipput

% A~switch to control |\nostanza|s: \nostanza
\newgif\if@nostanza

% The below is another relic of the heavy debug of the automatic
% vspacing. Let's give it the same removal clause as 
% \gmiflink[relic parameter]{above}. 
\newcommand*\gmd@nocodeskip[2]{}

% And here is how the two relic macros looked like during the
% debug. As you see, they are disabled by a~false |\if| (look at it
% closely ;-).
\if1 1
  \renewcommand*\gmd@codeskip[1]{%
    \hbox{\rule{1cm}{3pt} #1!!!}}
  \renewcommand*\gmd@nocodeskip[2]{%
    \hbox{\rule{1cm}{0.5pt} #1: #2 }}
\fi

% We'll wish to execute |\gmd@codeskip| wherever a~codeline (possibly with
% an inline comment) is followed by a~homogenic comment line or
% reverse. Let us dedicate a~Boolean switch to this then.
% \Define\if@aftercode
\newgif\if@aftercode
% This switch will be set true in the moments when we are able to
% switch from the \TeX\ code into the narration and the below one when
% we are able to switch reversely.
% \Define\if@afternarr
\newgif\if@afternarr

% To insert vertical glue between the \TeX\ code and the narration
% we'll be playing with |\everypar|. More precisely, we'll add a~macro
% that the |\parindent| box shall move and the glue shall put. 
\def\@codetonarrskip{%
  \if@codeskipput\else
    \if@afternarr\gmd@nocodeskip4{iaN}\else
      \if@aftercode
        % We are at the beginning of |\everypar|, i.e., \TeX\ has just entered
        % the hmode and put the |\parindent| box. Let's remove it then.
        {\setbox0=\lastbox}%
        % Now we can put the vertical space and state we are not `aftercode'.
        \gmd@codeskip4%
        % \label{codeskip5}
      \else\gmd@nocodeskip4{naC}%
      \fi
    \fi
  \fi
  \leftskip\TextIndent% this line is a~patch against
  % a~bug-or-feature that in certain cases the narration |\leftskip|
  % is left equal the code leftskip. (It happens when there're
  % subsequent code lines after an inline comment not ended with
  % an explicit |\par|.) Before v0.99n it was just after line \ref{codeskip5}.
  \@aftercodegfalse\@nostanzagtrue
  % \changes{v0.99o}{2008/09/04}{a~bug fix: added \cs{@nostanzagtrue}}
}

% But we play with |\everypar| for other reasons too, and while restoring it,
% we don't want to add the |\@codetonarrskip| macro infinitely many
% times. So let us define a~macro that'll check if |\everypar| begins
% with |\@codetonarrskip| and trim it if so. We'll use this macro with
% proper |\expandafter|ing in order to give it the contents of
% |\everypar|. The work should be done in two steps first of which
% will be checking whether |\everypar| is nonempty (we can't have two
% delimited parameters for a~macro: if we define a~two-parameter
% macro, the first is undelimited so it has to be nonempty; it costed
% me some one hour to understand it).
\long\def\@trimandstore#1\@trimandstore{%
  \def\@trimandstore@hash{#1}%
  \ifx\@trimandstore@hash\@empty% we check if |#1| is
  % nonempty. The \incs{if} \inverb*|\relax#1\relax| trick is not
  % recommended here because using it we couldn't avoid expanding |#1|
  % if it'd be expandable.
    \gmd@preverypar={}%
  \else
    \afterfi{\@xa\@trimandstore@ne\the\everypar\@trimandstore}%
  \fi}

\long\def\@trimandstore@ne#1#2\@trimandstore{%\label{@trimandstore}
  \def\trimmed@everypar{#2}%
  \ifx\@codetonarrskip#1%
    \gmd@preverypar=\@xa{\trimmed@everypar}%
  \else
    \gmd@preverypar=\@xa{\the\everypar}%
  \fi}
% We prefer not to repeat |#1| and |#2| within the |\if|s and we even
% define an auxiliary macro because |\everypar| may contain some
% |\if|s or |\fi|s.
%
%
% \subdivision[Life among queer \acro{EOL}s]{Life among queer \gmhypertarget[afc]{\acro{EOL}s}}
%
% When I~showed this package to my \TeX\ Guru he commended it and
% immediately pointed some disadvantages in the comparison with the
% \docfm\ package.
%
% One of them was an expected difficulty of breaking a~moving argument
% (e.g., of a~sectioning macro) in two lines. To work it around let's
% define a~line-end eater:
\catcode`\^^B=\active% note we re|\catcode| \<char2> globally, for the
% entire document.
\foone{\obeylines}%% \Define*{^^B}
  {\def\QueerCharTwo{%
      \protected\def^^B##1^^M{%
        %^^A\@newlinegtrue\gmd@countnarrline
        \ifhmode\unskip\space\ignorespaces\fi}}% It shouldn't be \incs{ } not to
    % drive \TeX\ into hmode.
  }

\QueerCharTwo

\AtBegInput{\@ifEOLactive{\catcode`\^^B\active}{}\QueerCharTwo}% \label{QCh2}
% We repeat redefinition of \<char2> at begin of the documenting
% input, because \pk{doc.dtx} suggests that some packages (namely
% \pk{inputenc}) may re|\catcode| such unusual characters.
%
% \changes{v0.98d}{06/9/11}{re\cs{catcode}ing and defining
% \cs{char1} and \cs{char2} added atto begin doc input}
%
% \stanza
% As you see the |^^B| active char is defined to gobble everything
% since itself till the end of line and the very end of line. This is
% intended for harmless continuing a~line. The price is affecting the
% line numbering when |countalllines| option is enabled.
%
% I~also liked the \docfm's idea of comment${}^2$ i.e., the
% possibility of marking some text so that it doesn't appear nor in the
% working version neither in the documentation, got by making
% |^^A| (i.e., \<char1>) a~comment char. 
%
% However, in this package such a~trick would work another way: here
% the line ends are active, a~comment char would disable them and that
% would cause disasters. So let's do it an |\active| way.
\catcode`\^^A=\active% note we re|\catcode| \<char1> globally, for the
% entire document.
\foone\obeylines{%%\DefIndex\QueerCharOne \Define*{^^A}
  \def\QueerCharOne{%
    \def^^A{%^^A no need to write \incs{gmd@countnarrline} because
      % ^^A \inverb|^^M| will contain it if \inenv{countalllines} is in force.
      \bgroup\let\do\@makeother\dospecials\gmd@gobbleuntilM}}%
  \def\gmd@gobbleuntilM#1^^M{\egroup\ignorespaces^^M}%
}

\QueerCharOne

\AtBegInput{\@ifEOLactive{\catcode`\^^A\active}\QueerCharOne}% see note
% after line \ref{QCh2}.\ilrr


% As I~suggested in the users' guide, |\StraightEOL| and |\QueerEOL| are
% intended to cooperate in harmony for the user's good. They take care
% not only of redefining the line end but also these little things
% related to it.
%
% One usefulness of |\StraightEOL| is allowing linebreaking of the
% command arguments. Another---making possible executing some code lines
% during the documentation pass.
%
% \changes{v0.98b}{06/09/07}{\cs{QueerM} and \cs{StraightM} renamed
% to \cs{QueerEOL} and \cs{StraightEOL} and other (internal) macros
% ending with \cs[]{M}}
\def\StraightEOL{%\label{StraightEOL}
  \catcode`\^^M=5
  \catcode`\^^A=14
  \catcode`\^^B=14
  \def\^^M{\ }}

%^^A \unless\if@countalllines
%^^A   \let\StraightEOL\StraightEOLnocount
%^^A \fi
%^^A 


\foone\obeylines{%
  \def\QueerEOL{%\label{QueerEOL}
    \catcode`\^^M=\active%
    \let^^M\gmd@textEOL%
    \catcode`\^^A=\active%
    \catcode`\^^B=\active% I~only re|\catcode| \<char1> and \<char2>
    % hoping no one but me is \emph{that} perverse to make them
    % |\active| and (re)define. (Let me know if I'm wrong at this point.)
    \let\^^M=\gmd@bslashEOL}%
%^^A   % 
%^^A   \if@countalllines%
%^^A     \def\StraightEOL{%
%^^A       \catcode`\^^M=\active%
%^^A       \let^^M\gmd@notsostraightEOL%
%^^A       \catcode`\^^A=\active%
%^^A       \catcode`\^^B=\active% I~only re|\catcode| \<char1> and \<char2>
%^^A       % hoping no one but me is \emph{that} perverse to make them
%^^A       % |\active| and (re)define. (Let me know if I'm wrong at this point.)
%^^A       \let\^^M=\gmd@bslashEOL}%
%^^A     % 
%^^A   \fi%
}

%^^A % \skiplines
%^^A % They won't work in \verb+|verbatim|+ scopes but the clubs redefine
%^^A % the active lineend to be a~breakable (and visible) space, so
%^^A % breaking a~`clubbed' text in two lines will not cause a~disaster but
%^^A % you get e.g., |...^^B %...|.
%^^A % \endskiplines

% \gmhypertarget[closingspace]{To make} |^^M| behave more like a~`normal'
% lineend I~command it to add a~| |${}\subs{10}$ at first. It works
% but has one unwelcome feature: if the line has nearly |\textwidth|,
% this closing space may cause line breaking and setting a~blank line.
% To fix this I~|\advance| the |\parfillskip|:
\def\gmd@parfixclosingspace{{% 
    \advance\parfillskip by-\gmd@closingspacewd
    \if@aftercode\ifilrr \gmd@setilrr \fi\fi
    \par}% 
  \if@ilgroup\aftergroup\egroup\@ilgroupfalse\fi% we are in the
  % verbatim group so we 
  % close the inline comment group after it if the closing is not yet set.
}
% We'll put it in a~group surrounding |\par| but we need to check if
% this |\par| is executed after narration or after the code,
% i.e., whether the closing space was added or not.
\newskip\gmd@closingspacewd
\newcommand*\gmd@setclosingspacewd{%
  \global\gmd@closingspacewd=\fontdimen2\font%
    plus\fontdimen3\font minus\fontdimen4\font\relax}
%
% See also line \ref{noclosingspace} to see what we do in the codeline
% case when no closing space is added.

% And one more detail:
\foone\obeylines{%\DefIndex*{\^^M}
  \if 1 1%
    \protected\def\gmd@bslashEOL{\ \@xa\ignorespaces^^M}%
  }% of \cs{foone}. Note we interlace here \incs{if} with a~group.
\else%
  \protected\def\gmd@bslashEOL{%
    \ifhmode\unskip\fi\ \ignorespaces}
    %^^A~\if@countalllines\@newlinegtrue\gmd@cpnarrline\fi%
  \fi
% \changes{v0.99c}{2007/03/30}{a~bug fix: redefinition of it left
% solely to \cs{QueerEOL}} 
% \changes{v0.99m}{2008/08/09}{also \cs{StraightEOL} with
% \env{countalllines} package option lets \cs{}\hathat{M} to it}
%
% The |\QueerEOL| declaration will |\let| it to |\^^M| to make 
%  |\^^M| behave properly. If this definition was ommitted, |\^^M|
% would just expand to |\ | and thus not gobble the leading |%| of the
% next line leave alone typesetting the \TeX\ code.  I~type |\ | etc.
% instead of just |^^M| which adds a~space itself because I~take
% account of a~possibility of redefining the |\ | \CS by the user, just
% like in normal \TeX.


% We'll need it for restoring queer definitions for \docfm-compatibility.
%
%
% \subdivision{Adjustment of \env{verbatim} and \cs{verb}}
%
% To make \env{verbatim(*)} typeset its contents with the \TeX\ code's
% indentation: 
% \Define\@verbatim
\gaddtomacro\@verbatim{\leftskip=\CodeIndent}

% And a~one more little definition to accomodate |\verb| and pals for the
% lines commented out.
\AtBegInput{\long\def\check@percent#1{%
    \gmd@cpnarrline% to count the verbatim lines and possibly print
    % their numbers. This macro is used only by the verbatim end of line.
    \@xa\ifx\code@delim#1\else\afterfi{#1}\fi}}
% We also redefine \pk{gmverb}'s |\AddtoPrivateOthers| that has been
% provided just with \pk{gmdoc}'s need in mind.
\def\AddtoPrivateOthers#1{%
  \@xa\def\@xa\doprivateothers\@xa{%
    \doprivateothers\do#1}}%

%^^A \foone\obeylines{%
%^^A   \AtBegInput{%
%^^A     \prependtomacro{% first the stuff then the macro (see \pk{gmutils}).
%^^A       \def\obeylines{\def^^M{\par}\catcode`\^^M\active}}%
%^^A     \@verbatim}}

% We also redefine an internal |\verb|'s macro |\gm@verb@eol| to put a~proper
% line end if a~line end char is met in a~short verbatim: we have to
% check if we are in `queer' or `straight' \acro{EOL}s area.
\begingroup
\obeylines% \DefIndex\gm@verb@eol
\AtBegInput{\def\gm@verb@eol{\obeylines%
    \def^^M{\verb@egroup\@latex@error{%
        \@nx\verb ended by end of line}%
      \@ifEOLactive{^^M}{\@ehc}}}}%
\endgroup

% \subdivision{Macros for marking of the macros}
%
% A~great inspiration for this part was the \docfm\ package again.
% I~take some macros from it, and some tasks I~solve a~different way,
% e.g., the |\| (or another escapechar) is not active, because anyway
% all the chars of code are scanned one by one. And exclusions from
% indexing are supported not with a~list stored as |\toks| register
% but with separate control sequences for each excluded \CS.
%
% \stanza
%
% The \docfm\ package shows a~very general approach to the indexing
% issue. It assumes using a~special MakeIndex style and doesn't use
% explicit MakeIndex controls but provides specific macros to hide
% them. But here in \pk{gmdoc} we prefer no special style for the
% index. 

% \Define\actualchar \Define\quotechar \Define\encapchar 
% \Define\levelchar 
% \changes[\actualchar]{v0.98e}{06/09/23}{a~bug fix: making the
% \cs[]{@} \protect\catother\space again}
\edef\actualchar{\string @} 
\edef\quotechar{\string "}
\edef\encapchar{\xiiclub} 
\edef\levelchar{\string !}
% However, for the glossary, i.e., the change history, a~special style
% is required, e.g., \pk{gmglo.ist}, and the above macros are
% redefined by the |\changes| command due to \pk{gmglo.ist} and
% \pk{gglo.ist} settings.
%
% Moreover, if you insist on using a~special MakeIndex style, you may
% redefine the above four macros in the preamble. The |\edef|s that
% process them further are postponed till |\begin{document}|.
%
%
%   \Define\code@escape@char
\def\CodeEscapeChar#1{%
  \begingroup
  \escapechar\m@ne
  \xdef\code@escape@char{\string#1}%
  \endgroup}
% As you see, to make a~proper use of this macro you should give it
% a~|\|\<one char> \CS as an argument. It's an invariant assertion that
% |\code@escape@char| stores  `other' version of the code layer
% escape char.
% \CodeUsgIndex\CodeEscapeChar
\CodeEscapeChar\\

% As mentioned in \docfm, someone may have some chars \catletter ed.
\@ifundefined{MakePrivateLetters}{%\label{MPL}
  \def\MakePrivateLetters{\makeatletter\catcode`\*=11 }}{}
% A~tradition seems to exist to write about e.g., `command |\section| and
% command |\section*|' and such an uderstanding also of `macro' is
% noticeable in \docfm. Making the |*| a~letter solves the problem of
% scanning starred commands.
%
% \stanza
% And you may wish some special chars to be \catother.
\def\MakePrivateOthers{\let\do=\@makeother \doprivateothers}
% We use this macro to re|\catcode| the space for marking the
% environments' names and the caret for marking chars such as |^^M|, see
% line \ref{TextUsage}. So let's define the list:
\def\doprivateothers{\do\ \do\^}
% Two chars for the beginning, and also the |\MakeShortVerb| command
% shall this list enlarge with the char(s) declared.
% (There's no need to add the backslash to this list since all the
% relevant commands |\string| their argument whatever it is.)
%
% \changes{v0.98c}{06/9/9}{\cs{} removed from \cs{doprivateothers}
% list and \cs{string} added instead to commands that process the
% `environments' names;}

% Now the main macro indexing a~macro's name. It would be a~verbatim
% :-) copy of the \docfm 's one if I~didn't ommit some lines
% irrelevant with my approach.
\def\scan@macro#1{% we are sure to scan at least one token and
                  % therefore we define this macro as one-parameter.\par
% Unlike in \docfm , here we have the escape char \catother\ so we
% may just have it printed during main scan char by char, i.e., in the
% lines \ref{printhashone1} and \ref{printhashone2}.\par
% So, we step the checksum counter first,
  \step@checksum% \label{checksumUse}(see line \ref{checksum} for
  % details),\par
  % Then, unlike in \docfm , we do \emph{not} check if the scanning is
  % allowed, because here it's always allowed and required.\par
  % Of course, I~can imagine horrible perversities, but I~don't think
  % they should really be taken into account.  Giving the letter |a|
  % |\catcode| other than \catletter\ surely would be one of those
  % perversities. Therefore I~feel safe to take the character |a| as
  % a~benchmark letter.
  \ifcat a\@nx#1%
    \quote@char#1%
    \xdef\macro@iname{\gmd@maybequote#1}% global for symmetry with
    % line \ref{x474}.
    \xdef\macro@pname{\string#1}%\label{stringing0} we'll print entire
    % name of the macro later.\par
    % We |\string| it here and in the lines \ref{stringing1} and
    % \ref{stringing2} to be sure it is whole \catother\ for easy
    % testing for special indexentry formats, see line
    % \ref{pnametestDef} etc. Here we are sure the result of |\string|
    % is \catother\ since its argument is \catletter.
    \afterfi{\@ifnextcat{a}{\gmd@finishifstar#1}{\finish@macroscan}}%
  \else% |#1| is not a~letter, so we have just scanned a~one-char
  % \CS.\par 
  % Another reasonable |\catcode|s assumption seems to be that the
  % digits are \catother. Then we don't have to
  % type (|%|)|\expandafter\@gobble\string\a|. We do the |\uccode|
  % trick to be sure that the char we write as the macro's name is
  % \catother. 
    {\uccode`9=`#1%
      \uppercase{\xdef\macro@iname{9}}%\label{x474}
    }%
    \quote@char#1%
    \xdef\macro@iname{\gmd@maybequote\macro@iname}%
    \xdef\macro@pname{\xiistring#1}%\label{stringing1}
    \afterfi \finish@macroscan
  \fi}
% The |\xiistring| macro, provided by \pk{gmutils}, is used instead of
% original |\string| because we wish to get | |\catother (`other' space).
%
% \stanza
% Now, let's explain some details, i.e., let's define them. We call
% the following macro having known |#1| to be \catletter.
\def\continue@macroscan#1{%
  \quote@char#1%
  \xdef\macro@iname{\macro@iname \gmd@maybequote#1}%
  \xdef\macro@pname{\macro@pname \string#1}%\label{stringing2} we know
  % \inverb*|#1| to be \catletter, so
  % we don't need \incs{xiistring}.
  \@ifnextcat{a}{\gmd@finishifstar#1}{\finish@macroscan}%
}
% As you may guess, |\@ifnextcat| is defined analogously to |\@ifnextchar| but
% the test it does is |\ifcat| (not |\ifx|).  (Note it wouldn't
% work for an active char as the `pattern'.)
%\stanza
% We treat the star specially since in usual \LaTeX\ it should finish
% the scanning of a~\CS name---we want to avoid scanning
% |\command*argum| as one \CS.

\def\gmd@finishifstar#1{%
  \if*\@nx#1\afterfi\finish@macroscan% note we protect |#1| against
  % expansion. In \pk{gmdoc} verbatim scopes some chars are active
  % (e.g. \inverb|\|\,).
  \else\afterfi\continue@macroscan
  \fi}

% If someone \emph{really} uses |*| as a~letter please let me know.

\def\quote@char#1{{\uccode`9=`#1% at first I~took digit 1 for this
    % |\uccode|ing but then |#1| meant |#|\<\#1> in |\uppercase|'s
    % argument, of course.
    \uppercase{% \DefIndex\gmd@maybequote
      \gmd@ifinmeaning 9\of \indexcontrols
      {\glet\gmd@maybequote\quotechar}%
      {\g@emptify\gmd@maybequote}%
    }%
  }}

% And now let's take care of the MakeIndex control characters. We'll
% define a~list of them to check whether we should quote a~char or
% not. But we'll do it at |\begin{document}| to allow the user to use
% some special MakeIndex style and in such a~case to redefine the four
% MakeIndex controls' macros. We enrich this list with the backslash
% because sometimes MakeIndex didn't like it unquoted.
% \Define\indexcontrols
% \changes{v0.98d}{06/9/15}{relativized to the index control macros:
% previously the controls were given explicitly as the standard ones.}
\AtBeginDocument{\xdef\indexcontrols{%
    \bslash\levelchar\encapchar\actualchar\quotechar}}

\long\def \gmd@ifinmeaning#1\of#2#3#4{% explained in the text
  % paragraph below.  \changes{v0.99g}{2007/11/06}{made more elegant:
  % \cs{if} changed to \cs{ifx} made four parameters and not expanding
  % to an open \cs{iftrue/false}. Also renamed from \cs{@ifismember}}
  \long\def\gmd@in@@##1#1##2\gmd@in@@{%
    \ifx^^A##2^^A\afterfi{#4}%
    \else\afterfi{#3}%
    \fi}%
  \@xa\gmd@in@@#2#1\gmd@in@@}%


% This macro is used for catching chars that are
% MakeIndex's controls. How does it work?
%
% |\quote@char| sort of re|\catcode|s its argument through the
% |\uccode| trick: assigns the argument as the uppercase code of the
% digit 9 and does further work in the |\uppercase|'s scope so the
% digit 9 (a~benchmark `other') is substituted by |#1| but the
% |\catcode| remains so \cs{gmd\-@\-if\-in\-mean\-ing} gets |\quote@char|'s |#1|
% `other'ed as the first argument.
%
% The meaning of the |\gmd@ifinmeaning| parameters is as follows:
%\begin{enumargs}^^B
%\item the token(s) whose presence we check,
%\item the macro in whose meaning we search |#1| (the first token of
%  this argument is expanded one level with |\expandafter|),
%\item the `if found' stuff,
%\item the `if not found' stuff.
%\end{enumargs}
%
% In |\quote@char| the second argument for |\gmd@ifinmeaning| is
% |\indexcontrols| defined as the (expanded and `other') sequence of
% the MakeIndex controls.  |\gmd@ifinmeaning| defines its inner macro
% |\gmd@in@@| to take two parameters separated by the first and the
% second |\gmd@ifinmeaning|'s parameter, which are here the char
% investigated by |\quote@char| and the |\indexcontrols| list. The
% inner macro's parameter string is delimited by the macro itself, why
% not.  |\gmd@in@@| is put before a~string consisting of
% |\gmd@ifinmeaning|'s second and first parameters (in such a~reversed
% order) and |\gmd@in@@| itself. In such a~sequence it looks for
% something fitting its parameter pattern. |\gmd@in@@| is sure to find
% the parameters delimiter (|\gmd@in@@| itself) and the separator,
% |\ifismember|'s |#1| i.e., the investigated char, because they are
% just there. But the investigated char may be found not near the end,
% where we put it, but among the MakeIndex controls' list. Then the
% rest of this list and |\ifismember|'s |#1| put by us become the
% secong argument of |\gmd@in@@|. What |\gmd@in@@| does with its
% arguments, is just a~check whether the second one is empty. This may
% happen \emph{iff} the investigated char hasn't been found among the
% MakeIndex controls' list and then |\gmd@in@@| shall expand to
% |\iffalse|, otherwise it'll expand to |\iftrue|. (The |\after...|
% macros are employed not to (mis)match just got |\if...| with the
% test's |\fi|.)  ``(Deep breath.) You got that?'' If not, try
% \docfm's explanation of |\ifnot@excluded|, pp.\,36--37 of the v2.1b
% dated 2004/02/09 documentation, where a~similar construction is
% attributed to Michael Spivak.
%
% Since version 0.99g |\gmd@ifinmeaning| is used also in testing
% whether a~detector is already present in the carrier in the
% mechanism of automatic detection of definitions (line \ref{550}). 

\newif\ifgmd@glosscs% we use this switch to keep the information
% whether a~history entry is a~\CS or not.


\newcommand*\finish@macroscan{%\label{506}\par
  % First we check if the current \CS is not just being defined. The
  % switch may be set true in line \ref{519}
  \ifgmd@adef@cshook% if so, we throw  it into marginpar and index as
  % a~def entry\dots
  \@ifundefined{gmd/iexcl/\macro@pname}{% \dots\ if it's not excluded
    % from indexing. 
      \@xa\Code@MarginizeMacro\@xa{\macro@pname}%
      \@xa\@defentryze\@xa{\macro@pname}{1}}{}%% here we declare the kind of
    % index entry and define |\last@defmark| used by \cs{changes}
    \global\gmd@adef@cshookfalse% we falsify the hook that was set
    % true just for this \CS.
  \fi
  % We have the \CS's name for indexing in |\macro@iname| and
  % for print in |\macro@pname|. So we index it. We do it a~bit
  % countercrank way because we wish to use more general indexing
  % macro.
  \if\verbatimchar\macro@pname% \label{3039}it's important that |\verbatimchar|
  % comes before the macro's name: when it was reverse, the |\tt| \CS
  % turned this test true and left the |\verbatimchar| what resulted
  % with `|\+tt|' typeset. Note that this test should turn true iff
  % the scanned macro name shows to be the default
  % |\verb|'s delimiter. In such a~case we give
  % |\verb| another delimiter, namely |$|: ^^A$
    \def\im@firstpar{[$%^^A$
      ]}%
    \else\def\im@firstpar{}\fi
    \@xa \index@macro\im@firstpar\macro@iname\macro@pname
    % \label{3049}
    \maybe@marginpar\macro@pname
    \if\xiispace\macro@pname\relax\gmd@texcodespace
    \else\macro@pname
    \fi
    % \changes[\finish@macroscan]{v0.99n}{2008/09/30}{the case of
    % \cs{\vs}  taken care of} 
    \let\next\gmd@charbychar
    \gmd@detectors% \label{519} for automatic detection of
    % definitions. Defined and
    % explained in the next section. It redefines
    % |\next| if detects a~definition command and thus
    % sets the switch of line \ref{506} true.
    \next
    % \label{next 3690}
  }

% Now, the~macro that checks whether the just scanned macro should be
% put into a~marginpar: it checks the meaning of a~very special \CS:
% whose name consists of |gmd/2marpar/| and of the examined macro's
% name. 
\def\maybe@marginpar#1{%
  %^^A\ifx#1\mname@tomarginpar
  \@ifundefined{gmd/2marpar/#1}{}{%
    \@xa\Text@Marginize\@xa{\bslash#1}% |\expandafter|s
    % \possfil because the |\Text@Marginize| command applies |\string| to its
    % argument.  \incs{macro@pname}, which will be the only possible
    % argument to
    % \incs{may\+be\+@mar\+g\+in\+par},  
    % contains the macro's name 
    % without the escapechar so we added it here.
    % ^^A\gdef\mname@tomarginpar{}
    \@xa\g@relaxen\csname gmd/2marpar/#1\endcsname% we reset the switch.
  }}

% Since version 0.99g we introduce automatic detection of definitions,
% it will be implemented in the next section. The details of indexing
% \CSs are implemented in the section after it.
%
% \subdivision{Automatic detection of definitions}
%
% To begin with, let's introduce a~general declaration of a~defining
% command. \cs{Decl\-are\-Def\-in\-ing} comes in two flavours: `saut\eacute',
% and with star. The `saut\eacute' version without an optional
% argument declares a~defining command of the kind of |\def| and
% |\newcommand|: whether wrapped in braces or not, its main argument
% is a~\CS. The star version without the optional argument declares
% a~defining command of the kind of |\newenvironment| and
% |\DeclareOption|: whose main mandatory argument is text. Both
% versions provide an optional argument in which you can set the keys.
% Probably the most important key is |star|. It determines whether the
% starred version of a~defining command should be taken into account.
% For example, |\newcommand| should be declared with |[star=true]|
% while |\def| with |[star=false]|. You can also write just |[star]|
% instead of |[star=true]|. It's the default if the |star| key is
% omitted.
%
% Another key is |type|. Its possible values are the (backslashless)
% names of the defining commands, see below.
%
% We provide now more keys for the \pk{xkeyval}ish definitions:
% |KVpref| (the key prefix) and |KVfam| (the key family). If not set by
% the user, they are assigned the default values as in \pk{xkeyval}:
% |KVpref| letters |KV| and |KVfam| the input file name. The latter
% assignment is done only for the |\DeclareOptionX| defining command
% because in other \pk{xkeyval} definitions (|\define@(...)key|) the
% family is mandatory.
%
%\stanza
% Let's make a~version of |\@ifstar| that would work with
% |*|\catletter. It's analogous to |\@ifstar|.
\foone{\catcode`\*=11 }
  {\def\@ifstarl#1{\@ifnextchar *{\@firstoftwo{#1}}}}
%
% \subsubdivision{\cs{DeclareDefining} and the detectors}
%
% Note that the main argument of the next declaration should be a~\CS
% \emph{without star}, unless you wish to declare only the starred
% version of a~command. The effect of this command is always global.
\outer\def\DeclareDefining{\begingroup
  \MakePrivateLetters
  \@ifstarl
    {\gdef\gmd@adef@defaulttype{text}\Declare@Dfng}%
    {\gdef\gmd@adef@defaulttype{cs}\Declare@Dfng}%
}

% The keys except |star| depend of |\gmd@adef@currdef|, therefore we
% set them having known both arguments
\newcommand*\Declare@Dfng[2][]{%
  \endgroup
  \Declare@Dfng@inner{#1}{#2}%
  \ifgmd@adef@star% this swith may be set false in first
  % \incs{Declare@Dfng@inner} (it's the |star| key).
    \Declare@Dfng@inner{#1}{#2*}% The catcode of |*| doesn't matter since
    % it's in
    % \incs{csname\+…\+\bslash end\+cs\+na\+me}
    % everywhere.
  \fi}

% \Define\gmd@adef@currdef
\def\Declare@Dfng@inner#1#2{%
  \edef\gmd@resa{%
    \@nx\setkeys[gmd]{adef}{type=\gmd@adef@defaulttype}}%
  \gmd@resa
  {\escapechar\m@ne
    \xdef\gmd@adef@currdef{\string#2}%
    % ^^A~\typeout{@@@ gmd@adef@currdef:::\gmd@adef@currdef::::}%
  }% 
  \gmd@adef@setkeysdefault
  \setkeys[gmd]{adef}{#1}%
  \@xa\gmd@ifinmeaning
    \csname gmd@detect@\gmd@adef@currdef\endcsname
    % \label{550}  
    \of\gmd@detectors{}{% 
      \@xa\gaddtomacro\@xa\gmd@detectors\@xa{%
        \csname gmd@detect@\gmd@adef@currdef\endcsname}}% we add a~\CS\\
    % |%| |\gmd@detect@|\<def name> (a~\textbf{detector}) to the 
    % meaning of the \textbf{detectors' carrier}. And we define it to
    % detect the \inverb|#2| command.
  \@xa\xdef\csname gmd@detectname@\gmd@adef@currdef\endcsname{%
    \gmd@adef@currdef}%
  \edef\gmu@tempa{% this |\edef| is to expand |\gmd@adef@TYPE|.
    \global\@nx\@namedef{gmd@detect@\gmd@adef@currdef}{%
      \@nx\ifx
        \@xa\@nx\csname gmd@detectname@\gmd@adef@currdef\endcsname
        \@nx\macro@pname
        \@nx\n@melet{next}{gmd@adef@\gmd@adef@TYPE}%
        \@nx\n@melet{gmd@adef@currdef}{gmd@detectname@\gmd@adef@currdef}%
      \@nx\fi}}%
  \gmu@tempa
  \SMglobal\StoreMacro*{gmd@detect@\gmd@adef@currdef}% we store the \CS to
  % allow its temporary discarding later.
}


\def\gmd@adef@setkeysdefault{%
  \setkeys[gmd]{adef}{star,prefix,KVpref}}
% Note we don't set |KVfam|. We do not so because for
% |\define@key|-likes family is a~mandatory argument and for
% |\DeclareOptionX| the default family is set to the input file name
% in line \ref{defDOXfam}.

\define@boolkey[gmd]{adef}{star}[true]{}

% The |prefix@|\<command> keyvalue will be used to create additional
% index entry for detected definiendum (a~\textbf{definiendum} is the
% thing defined, e.g. in |\newenvironment{foo}| the env.\ \env{foo}).
% For instance, |\newcounter| is declared with |[prefix=\bslash c@]|
% in line \ref{newcounter} and therefore |\newcounter{foo}| occurring
% in the code will index both |foo| and |\c@foo| (as definition
% entries).  \UnDef
\define@key[gmd]{adef}{prefix}[]{%
  \edef\gmd@resa{%
    \def\@xa\@nx\csname gmd@adef@prefix@\gmd@adef@currdef \endcsname{%
      #1}}%
  \gmd@resa}
    

\def\gmd@KVprefdefault{KV}% in a~separate macro because we'll need
                            % it in \cs{ifx}.


% A~macro |\gmd@adef@KVprefixset@|\<command> if defined, will falsify
% an \cs{ifnum} test that will decide whether create additional index
% entry together with the tests for |prefix|\<command> and 
% \UnDef
\define@key[gmd]{adef}{KVpref}[\gmd@KVprefdefault]{%
  \edef\gmd@resa{#1}%
  \ifx\gmd@resa\gmd@KVprefdefault
  \else
    \@namedef{gmd@adef@KVprefixset@\gmd@adef@currdef}{1}%
    \gmd@adef@setKV% whenever the |KVpref|fix is set (not default), the
    % declared command is assumed to be \pk{keyval}ish.
  \fi
  \edef\gmd@resa{#1}% because |\gmd@adef@setKV| redefined it.
  \edef\gmd@resa{%
    \def\@xa\@nx\csname gmd@adef@KVpref@\gmd@adef@currdef\endcsname{%
      \ifx\gmd@resa\empty
      \else#1@\fi}}% as in \pk{xkeyval}, if the \acro{KV} prefix is not
  % empty, we add \inverb|@| to it.
  \gmd@resa}


% Analogously to |KVpref|, |KVfam| declared in |\DeclareDefining|
% will override the family scanned from the code and, in
% |\DeclareOptionX| case, the default family which is the input file
% name (only for the command being declared).
\define@key[gmd]{adef}{KVfam}[]{%
  \edef\gmd@resa{#1}%
  \@namedef{gmd@adef@KVfamset@\gmd@adef@currdef}{1}%
  \edef\gmd@resa{%
    \def\@xa\@nx\csname gmd@adef@KVfam@\gmd@adef@currdef\endcsname{%
      \ifx\gmd@resa\empty
      \else#1@\fi}}%
  \gmd@resa
  \gmd@adef@setKV}% whenever the |KVfam|ily is set, the declared command is
                  % assumed to be \pk{keyval}ish.


\define@choicekey[gmd]{adef}{type}
  [\gmd@adef@typevals\gmd@adef@typenr]
  {% the list of possible types of defining commands
    def,
    newcommand,
    cs,% equivalent to the two above, covers all the cases of defining
          % a~\CS, including the \PlainTeX\ \inverb|\new...| and
          % \LaTeX\ |\newlength|.
    newenvironment,
    text,% equivalent to the one above, covers all the commands defining
         % its first mandatory argument that should be text,
         % \inverb|\DeclareOption| e.g.
    define@key,% special case of more arguments important; covers the
    % \pk{xkeyval} defining commands.
    dk,% a~shorthand for the one above.
    DeclareOptionX,% another case of special arguments configuration,
    % covers the \pk{xkeyval} homonym.
    dox,% a~shorthand for the one above.
    kvo% one of option defining commands of the \pk{kvoptions} package
       % by Heiko Oberdiek (a~package available o~\acro{CTAN} in the
       % \pk{oberdiek} bundle).
  }
  {% In fact we collapse all the types just to four so far:
    \ifcase\gmd@adef@typenr% if |def|
      \gmd@adef@settype{cs}{0}%
    \or% when |newcommand|
      \gmd@adef@settype{cs}{0}%
    \or% when |cs|
      \gmd@adef@settype{cs}{0}%
    \or% when |newenvironment|
      \gmd@adef@settype{text}{0}%
    \or% when |text|
      \gmd@adef@settype{text}{0}%
    \or% when |define@key|
      \gmd@adef@settype{dk}{1}%
    \or% when |dk|
      \gmd@adef@settype{dk}{1}%
    \or% when |DeclareOptionX|
      \gmd@adef@settype{dox}{1}%
    \or% when |dox|
      \gmd@adef@settype{dox}{1}%
    \or% when |kvo|
      \gmd@adef@settype{text}{1}%% The \pk{kvoptions} option
      %% definitions take first mandatory
      % argument as the option name and they define a~\pk{keyval} key
      % whose macro's name begins with the prefix/family, either default or
      % explicitly declared. The \pk{kvoptions} prefix/family is
      % supported in \pk{gmdoc} with \inverb|[KVpref=, KVfam=|\<family>|]|.
    \fi}
  
\def\gmd@adef@settype#1#2{%
  \def\gmd@adef@TYPE{#1}%
  \ifnum1=#2 % now we define (or not) a~quasi-switch that fires for
             % the \pk{keyval}ish definition commands.
    \gmd@adef@setKV
  \fi}

\def\gmd@adef@setKV{%
  \edef\gmd@resa{%
    \def\@xa\@nx\csname gmd@adef@KV@\gmd@adef@currdef\endcsname{1}%
  }%
  \gmd@resa}


% We initialize the carrier of detectors:
\emptify\gmd@detectors


% The definiendum of a~command of the |cs| type is the next control
% sequence. Therefore we only need a~self-relaxing hook in
% |\finish@macroscan|. 
\newif\ifgmd@adef@cshook

\def\gmd@adef@cs{\global\gmd@adef@cshooktrue\gmd@charbychar}

% For other kinds of definitions we'll employ active chars of their
% arguments' opening braces, brackets and seargants. In \pk{gmdoc}
% code layer scopes the left brace is active so we only add a~hook to
% its meaning (see line \ref{gm@lbracehook} in \pk{gmverb}) and \ref and here
% we switch it according to the type of detected definition.

\def\gmd@adef@text{\gdef\gmd@lbracecase{1}\gmd@charbychar}

\foone{%
  \catcode`\[\active
  % ^^A>\]
  \catcode`\<\active}
{%\par
  % The detector of \pk{xkeyval} |\define@(...)key|:
  \def\gmd@adef@dk{%
    \let[\gmd@adef@scanKVpref
    \catcode`\[\active
    % ^^A\]]
    \gdef\gmd@lbracecase{2}%
    \gmd@adef@dfKVpref\gmd@KVprefdefault% We set the default value of
    % the \pk{xkeyval} prefix. Each time again because an assignment
    % in \inverb|\gmd@adef@dfKVpref| is global.\ilrr
    \gmd@adef@checklbracket}
  
  % The detector of \pk{xkeyval} |\DeclareOptionX|:
  \def\gmd@adef@dox{%
    \let[\gmd@adef@scanKVpref
    \let<\gmd@adef@scanDOXfam
    \catcode`[\active
    % ^^A]]
    \catcode`<\active
    \gdef\gmd@lbracecase{1}%
    \gmd@adef@dfKVpref\gmd@KVprefdefault% We set the default values of
                                % the \pk{xkeyval} prefix\dots
    \edef\gmd@adef@fam{\gmd@inputname}% \dots\ and family. 
    \gmd@adef@dofam
    % \label{defDOXfam}
    \gmd@adef@checkDOXopts}%
}

% The case when the right bracket is next to us is special because it
% is already touched by |\futurelet| (of \CSs scanning macro's
% \cs{@ifnextcat}), therefore we need a~`future' test. 
\def\gmd@adef@checklbracket{%
  \@ifnextchar[%^^A]
  \gmd@adef@scanKVpref\gmd@charbychar}% note that
%  the prefix scanning macro gobbles its first argument (undelimited)
%  which in this case is |[|.\ilrr
%^^A]

% After a~|\DeclareOptionX|-like defining command not only the prefix
% in square brackets may occur but also the family in
% seargants. Therefore we have to test presence of both of them.
\def\gmd@adef@checkDOXopts{%
  \@ifnextchar[\gmd@adef@scanKVpref%^^A]
  {\@ifnextchar<\gmd@adef@scanDOXfam\gmd@charbychar}}


%^^A[
\def\gmd@adef@scanKVpref#1#2]{%
  \gmd@adef@dfKVpref{#2}%
  [#2]\gmd@charbychar}


\def\gmd@adef@dfKVpref#1{%
  \ifnum1=0\csname gmd@adef@KVprefixset@\gmd@adef@currdef\endcsname
    \relax
  \else
    \edef\gmu@resa{%
    \gdef\@xa\@nx
    \csname gmd@adef@KVpref@\gmd@adef@currdef\endcsname{%
      \ifx\relax#1\relax
      \else#1@%
      \fi}}%
    \gmu@resa
  \fi}


\def\gmd@adef@scanDOXfam{%
  \ifnum12=\catcode`\>\relax
    \let\next\gmd@adef@scanfamoth
  \else
    \ifnum13=\catcode`\>\relax
      \let\next\gmd@adef@scanfamact
    \else
      \PackageError{gmdoc}{> neither `other' nor `active'! Make it
        `other' with \bslash AddtoPrivateOthers\bslash\>.}%
    \fi
  \fi
  \next}

\def\gmd@adef@scanfamoth#1>{%
    \edef\gmd@adef@fam{\@gobble#1}% there is always
    % \cs{gmd@charbychar} first.
    \gmd@adef@dofam
    <\gmd@adef@fam>%
  \gmd@charbychar}

\foone{\catcode`\>\active}
  {\def\gmd@adef@scanfamact#1>{%
      \edef\gmd@adef@fam{\@gobble#1}% there is always
      % \cs{gmd@charbychar} first.
      \gmd@adef@dofam
      <\gmd@adef@fam>%
      \gmd@charbychar}%
  }


% The hook of the left brace consists of \cs{ifcase} that logically
% consists of three subcases:
% \begin{itemize}^^B
% \item [0]---the default: do nothing in particular;
% \item [1]---the detected defining  command has one mandatory
% argument (is of the |text| type, including \pk{kvoptions} option definition);
% \item [2--3]---we are after detection of a~|\define@key|-like command
%   so we have to scan \emph{two} mandatory arguments (case 2 is for
%   the family, case 3 for the key name).
% \end{itemize}
%
%
\def\gm@lbracehook{%
  \ifcase\gmd@lbracecase\relax
  \or% when  1
    \afterfi{%
      \gdef\gmd@lbracecase{0}%
      \gmd@adef@scanname}%
  \or% when 2---the first mandatory argument of two (|\define@(...)key|)
    \afterfi{%
    \gdef\gmd@lbracecase{3}%
     \gmd@adef@scanDKfam}%
  \or% when 3---the second mandatory argument of two (the key name).
    \afterfi{%
      \gdef\gmd@lbracecase{0}%
      \gmd@adef@scanname}%
  \fi}

\def\gmd@lbracecase{0}% we initialize the hook caser.


% And we define the inner left brace macros:

\foone{\catcode`\[1 \catcode`\]2 \catcode`\}12 }
  [% Note that till line \ref{738} the square brackets are grouping
   % and the right brace is `other'. ^^A{
%\par Define the macro that reads and processes the |\define@key|
%family argument. It has the parameter delimited with `other' right
%brace. An active left brace that has launched this macro had been
%passed through iterating |\gmd@charbychar| that now stands next right
%to us.
  \def\gmd@adef@scanDKfam#1}[%^^A{
    \edef\gmd@adef@fam[\@gobble#1]% there is always
    % \cs{gmd@charbychar} first.
    \gmd@adef@dofam
    \gmd@adef@fam}%
  \gmd@charbychar]

  % ^^A{
  \def\gmd@adef@scanname#1}[%^^A{
    \@makeother\[%^^A\]
    \@makeother\<%
    % The scanned name begins with |\gmd@charbychar|, we have to be
    % careful.
    \gmd@adef@deftext[#1]%
    \@gobble#1}%
    \gmd@charbychar]
  ]


\def\gmd@adef@dofam{%
  \ifnum1=0\csname gmd@adef@KVfamset@\gmd@adef@currdef\endcsname
    \relax% a~family declared with |\DeclareDefining| overrides the
          % one currently scanned.
  \else
    \edef\gmu@resa{%
      \gdef\@xa\@nx
      \csname gmd@adef@KVfam@\gmd@adef@currdef\endcsname
      {\ifx\gmd@adef@fam\empty
        \else\gmd@adef@fam @%
        \fi}}%
    \gmu@resa
  \fi}

\def\gmd@adef@deftext#1{%
  \edef\macro@pname{\@gobble#1}% we gobble |\gmd@charbychar|, cf. above.
  \@xa\Text@Marginize\@xa{\macro@pname}%
  \gmd@adef@indextext
  \edef\gmd@adef@altindex{%
    \csname gmd@adef@prefix@\gmd@adef@currdef \endcsname}%
  %\hskip-\parindent and we add the \pk{xkeyval} header if we are in \pk{xkeyval}
  % definition. 
  \ifnum1=0\csname gmd@adef@KV@\gmd@adef@currdef \endcsname\relax% The\\ \CS
  % \inverb|\gmd@adef@KV@|\<def. command> is defined |{1}| (so \cs{ifnum}
  % gets |1=01\relax|---\hskip0sptrue) iff \<def. command> is a~\pk{keyval}
  % definition. In that case we check for the \inverb|KVpref|ix and
  % \inverb|KVfam|ily. (Otherwise |\gmd@adef@KV@|\<def. command> is undefined
  % so \cs{ifnum} gets |1=0\relax|---false.)\ilrr
    \edef\gmd@adef@altindex{%
      \gmd@adef@altindex
      \csname gmd@adef@KVpref@\gmd@adef@currdef \endcsname}%
    \edef\gmd@adef@altindex{%
      \gmd@adef@altindex
      \csname gmd@adef@KVfam@\gmd@adef@currdef \endcsname}%
  \fi
  \ifx\gmd@adef@altindex\empty
  \else% we make another index entry of the definiendum with prefix/KVheader.
    \edef\macro@pname{\gmd@adef@altindex\macro@pname}%
    \gmd@adef@indextext
  \fi}

\def\gmd@adef@indextext{%
  \@xa\@defentryze\@xa{\macro@pname}{0}% declare the definiendum has to
  % have a~definition entry and in the changes history should appear
  % without backslash.
  \gmd@doindexingtext% redefine |\do| to an indexing macro.
% \label{gmd@doindexingtext 2nd use}
  \@xa\do\@xa{\macro@pname}}

% \stanza

% So we have implemented automatic detection of definitions. Let's now
% introduce some.
%
% \subsubdivision{Default defining commands}

% Some commands are easy to declare as defining:
% \HideAllDefining
% \DeclareDefining\DeclareDefining

%^^A\DeclareDefining[type=dox, star=false]\def
\DeclareDefining[star=false]\def
\DeclareDefining[star=false]\pdef% it's a~\pk{gmutils}' shorthand for \inverb|\protected\def|.
\DeclareDefining[star=false]\provide% a~\pk{gmutils}' conditional \incs{def}.
\DeclareDefining[star=false]\pprovide% a~\pk{gmutils}' conditional \incs{pdef}.
%^^A\show\gmd@detectors

% \ResumeAllDefining But |\def| definitely \emph{not always} defines
% an important macro.  Sometimes it's just a~scratch assignment.
% Therefore we define the next declaration. It turns the next
% occurence of |\def| off (only the next one).

\def\UnDef{{% \changes{v0.99n}{2008/08/30}{a~bug fixed:
    % \cs{gmd@charbychar} appended to \cs{next}---without it
    % a~subsequent inline comment was typeset verbatim}
    % \UnDef
    \gmd@adef@selfrestore\def
  }}

\StoreMacro\UnDef% because the `hiding' commands relax it.

\def\HideDef{% \changes{v0.99n}{2008/08/30}{added the starred version
             % that calls \cs{UnDef}}
  \@ifstar\UnDef{\HideDefining\def\relaxen\UnDef}}

\def\ResumeDef{\ResumeDefining\def\RestoreMacro\UnDef}


% Note that I~\emph{don't} declare |\gdef|, |\edef| neither
% |\xdef|. In my opinion their use as `real' definition is very rare
% and then you may use |\Define| implemented later.
% \HideAllDefining \DeclareDefining\DeclareDefining
\DeclareDefining[star=false]\newcount
\DeclareDefining[star=false]\newdimen
\DeclareDefining[star=false]\newskip
\DeclareDefining[star=false]\newif
\DeclareDefining[star=false]\newtoks
\DeclareDefining[star=false]\newbox
\DeclareDefining[star=false]\newread
\DeclareDefining[star=false]\newwrite
\DeclareDefining[star=false]\newlength
\DeclareDefining[star=false]\DeclareDocumentCommand
% \changes{v0.99p}{2008/10/04}{added}


\DeclareDefining\newcommand
\DeclareDefining\renewcommand
\DeclareDefining\providecommand
\DeclareDefining\DeclareRobustCommand
\DeclareDefining\DeclareTextCommand
\DeclareDefining\DeclareTextCommandDefault

\DeclareDefining*\newenvironment
\DeclareDefining*\renewenvironment
\DeclareDefining*\DeclareOption
%|%\DeclareDefining*\@namedef|

% \HideDefining\DeclareDefining
% \DeclareDefining\bslash

\DeclareDefining*[prefix=\bslash c@]\newcounter% \label{newcounter}
% this prefix provides indexing also |\c@|\<counter>.

\DeclareDefining[type=dk, prefix=\bslash]\define@key
\DeclareDefining[type=dk, prefix=\bslash if]\define@boolkey% the
                                % alternate index entry will be
                                % \cs{if}\<KVpref>|@|\<KVfam>|@|\<key name>
\DeclareDefining[type=dk, prefix=\bslash]\define@choicekey

\DeclareDefining[type=dox, prefix=\bslash]\DeclareOptionX% the
% alternate index entry will be \cs{}\<KVpref>|@|\<KVfam>|@|\<option name>.
%
% For |\DeclareOptionX| the default KVfamily is the input file
% name. If the source file name differs from the name of the goal
% file (you \TeX\ a~\file{.dtx} not \file{.sty} e.g.), there is the
% next declaration. It takes one optional and one mandatory
% argument. The optional is the |KVpref|, the mandatory the |KVfam|.
% \Define\DeclareDOXHead
\newcommand*\DeclareDOXHead[2][\gmd@KVprefdefault]{%
  \csname DeclareDefining\endcsname
  [type=dox, prefix=\bslash, KVpref=#1, KVfam=#2]% \HideDefining\DeclareOptionX
  \DeclareOptionX
}

% An example:
%\skiplines
\iffalse
%\endskiplines
\DeclareOptionX[Berg]<Lulu>{EvelynLear}{}
% Check in the index for
% \inverb|EvelynLear| and \inverb|\Berg@Lulu@EvelynLear|.
% Now we set in the comment layer
% |\DeclareDOXHead[Webern]{Lieder}|\DeclareDOXHead[Webern]{Lieder} and
\DeclareOptionX<AntonW>{ChneOelze}
% The latter example shows also overriding the option header by
% declaring the default. By the way, both the example options are
% not declared in the code actually.
%\skiplines
\fi
%\endskiplines
%\stanza
% Now the Heiko Oberdiek's \pk{kvoptions} package option definitions:
\DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareStringOption
\DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareBoolOption
\DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareComplementaryOption
\DeclareDefining[type=kvo, prefix=\bslash, KVpref=]\DeclareVoidOption

% The \pk{kvoptions} option definitions allow setting the default
% family/prefix for all definitions forth so let's provide analogon:
\def\DeclareKVOFam#1{%
  \def\do##1{%
    \csname DeclareDefining\endcsname
    [type=kvo, prefix=\bslash, KVpref=, KVfam=#1]##1}%
  \do\DeclareStringOption
  \do\DeclareBoolOption
  \do\DeclareComplementaryOption
  \do\DeclareVoidOption
}

% \ResumeAllDefining^^A~ it cancels |\DD\DD| and |\DD\bslash| effect.
% As a~nice exercise I~recommend to think why this list of declarations
% had to be preceded (in the comment layer) with |\HideAllDefining|
% and for which declarations of the above
% |\DeclareDefining\DeclareDefining| did not work. (The answers are
% commented out in the source file.)
%^^A~ I~had to precede the list of |\DeclareDefining|s with
%^^A~ |\HideAllDefining| in the commentary because the detectors of
%^^A~ some commands expect certain configurations of arguments and of
%^^A~ course such arguments do \emph{not} occur when such a~defining
%^^A~ command is being declared. That caused errors. Another reason is
%^^A~ that if not hidden, the detectors fired at the declared definers
%^^A~ of \CSs and marked next |\DeclareDefining| as being defined.
%^^A
%^^A~ |\DD\DD| did not work for those three \pk{xkeyval} definers
%^^A~ declared with |\bslash| in the optional argument. To be precise, 
%^^A~ it \emph{did work} perfectly: marked |\bslash| as being defined.
%
% One remark more: if you define (in the code) a~new defining command
% (I~did: a~shorthand for |\DeclareOptionX[gmcc]<>|), declare it as
% defining (in the commentary) \emph{after} it is defined. Otherwise
% its first occurence shall fire the detector and mark next \CS or
% worse, shall make the detector expect some arguments that it won't
% find. 


% \subsubdivision{Suspending (`hiding') and resuming detection}
%
% Sometimes we want to suspend automatic detection of definitions. For
% |\def| we defined suspending and resuming declarations in the
% previous section. Now let's take care of detection more generally.
%
% \stanza
% The next command has no arguments and suspends entire detection of
% definitions. 
\def\HideAllDefining{%
  \ifnum0=0\csname gmd@adef@allstored\endcsname
    \SMglobal\StoreMacro\gmd@detectors
    \global\@namedef{gmd@adef@allstored}{1}%
  \fi
  \global\emptify\gmd@detectors}% we make the carrier |\empty| not |\relax| to
                         % be able to declare new defining command in
                         % the scope of |\HideAll...| 

% The |\ResumeAllDefining| command takes no arguments and restores the
% meaning of the detectors' carrier stored with |\HideAllDefining|
\def\ResumeAllDefining{%
  \ifnum1=0\csname gmd@adef@allstored\endcsname\relax
    \SMglobal\RestoreMacro\gmd@detectors
    \SMglobal\RestoreMacro\UnDef
    \global\@namedef{gmd@adef@allstored}{0}%
  \fi}

% Note that |\ResumeAllDefining| discards the effect of any
% |\DeclareDefining| that could have occured between
% |\HideAllDefining| and itself.
%
% \stanza
%
% The |\HideDefining| command takes one argument which should be
% a~defining command (always without star). |\HideDefining| suspends
% detection of this command (also of its starred version) until
% |\ResumeDefining| of the same command or |\ResumeAllDefining|.
\def\HideDefining{\begingroup
  % \changes{v0.99n}{2008/08/30}{Added the starred version that hides
  % the defining command only once}
  \MakePrivateLetters
  \@ifstarl\Hide@DfngOnce\Hide@Dfng}

\def\Hide@Dfng#1{%%\UnDef
  \escapechar\m@ne
  \gn@melet{gmd@detect@\string#1}{relax}%
  \gn@melet{gmd@detect@\string#1*}{relax}%
  \ifx\def#1\global\relaxen\UnDef\fi
  \endgroup}

\def\Hide@DfngOnce#1{%%\UnDef
  \gmd@adef@selfrestore#1%
  \endgroup}

\def\gmd@adef@selfrestore#1{%
  \escapechar\m@ne
  \@ifundefined{gmd@detect@\string#1}{%
    \SMglobal\@xa\StoreMacro
    \csname gmd@detect@\string#1\endcsname}{}%
  % ^^A\typeout{:::::::::::::::gmd@detect@\string#1:::::::::::::}%
  \global\@nameedef{gmd@detect@\string#1}{%
    \@nx\ifx\@xa\@nx\csname gmd@detectname@\string#1\endcsname
    \@nx\macro@pname
    \def\@nx\next{% this \incs{next} will be executed in line
      % % \ref{next 3690}.
      \SMglobal\RestoreMacro % they both are \incs{protected}.
      \@xa\@nx\csname gmd@detect@\string#1\endcsname
      \@nx\gmd@charbychar}%^^A we define
    % ^^A \inverb|\next| not restore the macro here just in case of
    % ^^A multiple declaration of |\def| (in that case there would
    % ^^A~be
    % ^^A multiple occurences of the macro to be restored in the
    % ^^A~carrier
    % ^^A \inverb|\gmd@detectors| and we wish
    % ^^A all of them not to fire this one time) That's probably too
    % ^^A much care since there's the test in line \ref{550}.
    \@nx\fi}% of \cs{@nameedef}.
}% of \cs{gmd@adef@selfrestore}.

% The |\ResumeDefining| command takes a~defining command as the
% argument and resumes its automatic detection. Note that it restores
% also the possibly undefined detectors of starred version of the
% argument but that is harmless I~suppose until we have millions of \CSs.
\def\ResumeDefining{\begingroup
  \MakePrivateLetters
  \gmd@ResumeDfng}

\def\gmd@ResumeDfng#1{%
  \escapechar\m@ne
  \SMglobal\RestoreMacro*{gmd@detect@\string#1}%
  \SMglobal\RestoreMacro*{gmd@detect@\string#1*}%
  \endgroup}


% \subdivision{Indexing of \CSs}
% The inner macro indexing macro. |#1| is the |\verb|'s delimiter;
% |#2| is assumed to be the macro's name with MakeIndex-control chars
% quoted. |#3| is a~macro storing the \catother\ macro's name, usually
% |\macro@pname|, built with |\string|ing every char in lines ^^A
% \ref{stringing0}, \ref{stringing1} and \ref{stringing2}. |#3| is
% used only to test if the entry should be specially formatted.
% \changes{v0.98}{06/09/05}{Indexing the codelines improved to sort
%   with account of the \cs{filesep} (\cs{HLPrefix})}
\newcommand*\index@macro[3][\verbatimchar]{{%
    \@ifundefined{gmd/iexcl/#3}%\label{iexcltest}
    {% |#3| is not excluded from index
      \@ifundefined{gmd/defentry/#3}% \label{pnametestDef} 
      {% |#3| is not def entry
        \@ifundefined{gmd/usgentry/#3}%\label{pnametestUsg}
        {% |#3| is not usg entry
          \edef\kind@fentry{\CommonEntryCmd}}%\label{CECmd}
        {% |#3| is usg entry
          \def\kind@fentry{UsgEntry}%
          \un@usgentryze{#3}}%\label{usgentryrs}
      }%
      {% |#3| is def entry
        \def\kind@fentry{DefEntry}%
        \un@defentryze{#3}%\label{defentryrs}
      }% of |gmd/defentry/| test's `else'
      \if@pageindex\@pageinclindexfalse\fi% should it be here or
      % there? Definitely here because we'll wish to switch the switch
      % with a~declaration.
      \if@pageinclindex
        \edef\gmu@tempa{gmdindexpagecs{\HLPrefix}{\kind@fentry}{\EntryPrefix}}%        
      \else
        \edef\gmu@tempa{gmdindexrefcs{\HLPrefix}{\kind@fentry}{\EntryPrefix}}%
      \fi
      \edef\gmu@tempa{\IndexPrefix#2\actualchar%
        \quotechar\bslash verb*#1\quoted@eschar#2#1% The last macro in
        % this line usually means the first two, but in some cases
        % it's redefined to be empty (when we use |\index@macro| to
        % index not a~\CS).
        \encapchar\gmu@tempa}% 
      \@xa\special@index\@xa{\gmu@tempa}% We give the
      % indexing macro the argument expanded so that \pk{hyperref} may
      % see the explicit encapchar in order not to add its own
      % encapsulation of \verb+|hyperpage+ when the (default)
      % |hyperindex=true|\TextCommonIndex*{hyperindex} option is in
      % force. (After this setting the |\edef|s in the above may be
      % changed to |\def|s.)
      % \changes[\index@macro]{v0.98f}{06/9/30}{explicit MakeIndex
      %   controls changed to corresponding macros. Therefore
      %   \cs[]{hyperindex} option of \pk{hyperref} didn't see the
      %   encapsulation and added its own. So I~expanded the
      %   argument of the very indexing macro}
    }{}% closing of |gmd/iexcl/| test.
    }}
  
  

\def\un@defentryze#1{%
  \@xa\g@relaxen\csname gmd/defentry/#1\endcsname
  \ifx\gmd@detectors\empty
    \g@relaxen\last@defmark
  \fi}% the last macro (assuming \cs{fi} is not a~macro :-)
  % is only used by \cs{changes}. If we are in the scope of automatic
  % detection of definitions, we want to be able not to use \inverb|\Define|
  % but write |\changes| after a~definition and get proper entry. Note
  % that in case of automatic detection of definitions
  % |\last@defmark|'s value keeps until the next definition.

\def\un@usgentryze#1{%
  \@xa\g@relaxen\csname gmd/usgentry/#1\endcsname}

\@emptify\EntryPrefix% this macro seems to be obsolete now
% (v0.98d).

% For the case of page-indexing a~macro in the commentary when
% codeline index option is on:
\newif\if@pageinclindex

\newcommand*\quoted@eschar{\quotechar\bslash}% we'll redefine it when
% indexing an environment.

% Let's initialize |\IndexPrefix|
\def\IndexPrefix{}
% The |\IndexPrefix| and |\HLPrefix| (`HyperLabel Prefix') macros are
% given with account of a~possibility of documenting several files
% in(to) one document.  In such case the user may for each file
% |\def\IndexPrefix{|\<package name>|!}| for instance and it will work
% as main level index entry and |\def\HLPrefix{|\<package name>|}|
% as a~prefix in hypertargets in the codelines. They are redefined by
% |\DocInclude| e.g.

\if@linesnotnum\@pageindextrue\fi
\AtBeginDocument{%
  \if@pageindex
    \def\gmdindexrefcs#1#2#3#4{\csname#2\endcsname{\hyperpage{#4}}}%^^A
    % in the page case we gobble the third argument that is supposed
    % to be the entry prefix.\ilrr
    \let\gmdindexpagecs=\gmdindexrefcs
  \else
% \DefIndex\gmdindexrefcs
% \DefIndex\gmdindexpagecs
    \def \gmdindexrefcs#1#2#3#4{\gmiflink[clnum.#4]{%
        \csname#2\endcsname{#4}}}%
    \def \gmdindexpagecs#1#2#3#4{\hyperlink{page.#4}{%
        \csname#2\endcsname{\gmd@revprefix{#3}#4}}}%
    % \stanza \DefIndex\gmd@revprefix
    \def\gmd@revprefix#1{%
      \def\gmu@tempa{#1}%
      \ifx\gmu@tempa\@empty p.\,\fi}

    \providecommand*\HLPrefix{}% it'll be the hypertargets names' prefix
    % in mul\-ti-docs. Moreover, it showed that if it was empty,
    % \pk{hyperref} saw duplicates of the hyper destinations, which
    % was perfectly understandable (|codelinenum.123| made by
    % |\refstepcounter| and |codelinenum.123| made by
    % |\gmhypertarget|). But since v0.98 it is not a~problem anymore
    % because during the automatic \inverb|\hypertarget|ing the
    % lines are labeled |clnum.|\<number>. When |\HLPrefix| was
    % defined as dot, MakeIndex rejected the entries as `illegal page
    % number'.  \changes[\HLPrefix]{v0.98a}{06/09/05}{again
    %   \cs{@empty}fied since \cs{hypertarget}ing the codelines names
    %   them \cs[]{clnum} (since v0.98).}
  \fi}
% The definition is postponed till |\begin{document}| because of the
%   |\PageIndex| declaration (added for \docfm-compatibility), see
%   line \ref{PageIndex}.
%
% I~design the index to contain hyperlinking numbers whether they are
% the line numbers or page numbers. In both cases the last parameter
% is the number, the one before the last is the name of a~formatting macro
% and in linenumber case the first parameter is a~prefix for proper
% reference in multi-doc.


% I~take account of three kinds of formatting the numbers: 1.~the
% `def' entry, 2.~a~`usage' entry, 3.~a~common entry. As in \docfm , let
% them be underlined, italic and upright respectively.
\def\DefEntry#1{\underline{#1}}
\def\UsgEntry#1{\textit{#1}}
% The third option will be just |\relax| by default:
\def\CommonEntryCmd{relax}
% In line \ref{CECmd} it's |\edef|ed to allow an `unm\oumlaut glich'
% situation that the user wants to have the common index entries
% specially formatted. I~use this to make \emph{all} the index entries
% of the  driver part to be `usage', see the source of chapter
% \ref*{Driver}. 


% Now let's |\def| the macros declaring a~\CS to be indexed
% special way. Each declaration puts the \catother ed name of the
% macro given it as the argument into proper macro to be |\ifx|ed in
% lines \ref{pnametestDef} and \ref{pnametestUsg} respectively.

% Now we are ready to define a~couple of commands. % The |*| versions of
% them are for marking environments and \emph{implicit} \CSs.

\outer\def\DefIndex{\begingroup
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Code@DefIndexStar}{\Code@DefIndex}}

% \changes{v0.98d}{06/9/11}{The macros indexing and marginizing
% macros (and other sequences) made \cs{long}}
%\DefIndex\Code@DefIndex
\long\def\Code@DefIndex#1{\endgroup{%
    \escapechar\m@ne% because we will compare the macro's name with
    % a~string without the backslash.
    \@defentryze{#1}{1}}}
% \label{stringamacro}

% \DefIndex\Code@DefIndexStar
\long\def\Code@DefIndexStar#1{%
  \endgroup
  \addto@estoindex{#1}%
  \@defentryze{#1}{0}}

\def\gmd@justadot{.}

\long\def\@defentryze#1#2{%
  \@xa\glet\csname gmd/defentry/\string#1\endcsname\gmd@justadot% The\\
  % \LaTeX\ \inverb|\@namedef| macro could not be used since it's not `long'.\ilrr
  % \Define\last@defmark
  \xdef\last@defmark{\string#1}% we |\string| the argument just in case it's
  % a~control sequence. But when it can be a~\CS, we |\@defentryze| in
  % a~scope of |\escapechar=-1|, so there will never be a~backslash at
  % the beginning of |\last@defmark|'s meaning (unless we
  % |\@defentryze| |\\|).
  \@xa\gdef\csname gmd/isaCS/\last@defmark\endcsname{#2}}% |#2| is
% either 0 or 1. It is the information whether this entry is a~\CS or
% not.

\long\def\@usgentryze#1{%
  \@xa\let\csname gmd/usgentry/\string#1\endcsname\gmd@justadot}

% Initialize |\envirs@toindex|
\@emptify\envirs@toindex

% Now we'll do the same for the `usage' entries:
\outer\def\CodeUsgIndex{\begingroup
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Code@UsgIndexStar}{\Code@UsgIndex}}
% The |*| possibility is for marking environments etc.
% \DefIndex\Code@UsgIndex
\long\def\Code@UsgIndex#1{\endgroup{%
    \escapechar\m@ne
    \global\@usgentryze{#1}}}

% \DefIndex\Code@UsgIndexStar
\long\def\Code@UsgIndexStar#1{%
  \endgroup
  \addto@estoindex{#1}%
  \@usgentryze{#1}}

% For the symmetry, if we want to mark a~control sequence or an
% environment's name to be indexed as a~`normal' entry, let's have:
\outer\def\CodeCommonIndex{\begingroup
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Code@CommonIndexStar}{\Code@CommonIndex}}

% \DefIndex\Code@CommonIndex
\long\def\Code@CommonIndex#1{\endgroup}

% \DefIndex\Code@CommonIndexStar
\long\def\Code@CommonIndexStar#1{%
  \endgroup\addto@estoindex{#1}}


% And now let's define commands to index the control sequences and
% environments occurring in the narrative.
\long\def\text@indexmacro#1{%
  {\escapechar\m@ne \xdef\macro@pname{\xiistring#1}}%
  \@xa\quote@mname\macro@pname\relax% we process the \CS's
  % name char by char and quote MakeIndex controls. |\relax| is the
  % iterating macro's stopper. The scanned \CS's quoted name shall be the
  % expansion of |\macro@iname|.
  \if\verbatimchar\macro@pname
    \def\im@firstpar{[$]}%^^A$
  \else\def\im@firstpar{}%
  \fi
  {\do@properindex% see line \ref{do@properindex}.
    \@xa \index@macro\im@firstpar\macro@iname\macro@pname}}

% The macro defined below (and the next one) are executed only before
% a~\catother\ macro's name i.e.\ a~nonempty sequence of \catother\
% character(s). This sequence is delimited (guarded) by |\relax|.
\def\quote@mname{%
  \def\macro@iname{}%
  \quote@charbychar}

% \DefIndex\quote@charbychar
\def\quote@charbychar#1{%
  \if\relax#1% finish quoting when you meet |\relax| or:
  \else
    \quote@char#1%
    \xdef\macro@iname{\macro@iname \gmd@maybequote#1}%
    \afterfi\quote@charbychar
  \fi}

% The next command will take one argument,
% which in plain version should be a~control sequence and in the
% starred version also a~sequence of chars allowed in environment names or
% made other by |\MakePrivateOthers| macro, taken in the curly braces.
\def\TextUsgIndex{\begingroup
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Text@UsgIndexStar}{\Text@UsgIndex}}

% \DefIndex\Text@UsgIndex
\long\def\Text@UsgIndex#1{%
  \endgroup\@usgentryze#1%
  \text@indexmacro#1}

% \DefIndex\Text@UsgIndexStar
\long\def\Text@UsgIndexStar#1{\endgroup\@usgentryze{#1}%
  \text@indexenvir{#1}}

\long\def \text@indexenvir#1{%
  \edef\macro@pname{\xiistring#1}%
  \if\bslash\@xa\@firstofmany\macro@pname\@@nil% if
  % |\string|ed |#1| begins with a~backslash, we will gobble it
  % to make MakeIndex not see it.
    \edef\gmu@tempa{\@xa\@gobble\macro@pname}%
    \@tempswatrue
  \else
    \let\gmu@tempa\macro@pname
    \@tempswafalse
  \fi
  \@xa\quote@mname\gmu@tempa\relax% \label{quote@mname comm}we 
  % process |\sting|ed |#1| char by char and quote MakeIndex
  % controls. |\relax| is the iterating macro's stopper. The quoted
  % |\string|ed |#1| shall be the meaning of |\macro@iname|.
  {\if@tempswa
    \def\quoted@eschar{\quotechar\bslash}%
    \else\@emptify\quoted@eschar\fi% we won't print any backslash before
    % an environment's name, but we will before a~\CS's name.
    \do@properindex% see line \ref{do@properindex}.
    \index@macro\macro@iname\macro@pname}}

\def\TextCommonIndex{\begingroup
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Text@CommonIndexStar}{\Text@CommonIndex}}

%\DefIndex\Text@CommonIndex
\long\def\Text@CommonIndex#1{\endgroup
  \text@indexmacro#1}

% \DefIndex\Text@CommonIndexStar
\long\def\Text@CommonIndexStar#1{\endgroup
  \text@indexenvir{#1}}

% As you see in the lines \ref{defentryrs} and \ref{usgentryrs}, the
% markers of special formatting are reset after first use.

% But we wish the \CSs not only to be indexed special way but also
% to be put in marginpars. So:
\outer\def\CodeMarginize{\begingroup
  \MakePrivateLetters
  \@ifstarl
    {\MakePrivateOthers\egCode@MarginizeEnvir}
    {\egCode@MarginizeMacro}}

% One more expansion level because we wish |\Code@MarginizeMacro| not
% to begin with |\endgroup| because in the subsequent macros it's used
% \emph{after} ending the re|\catcode|ing group.
% \DefIndex\egCode@MarginizeMacro
\long\def\egCode@MarginizeMacro#1{\endgroup
  \Code@MarginizeMacro#1}

% \DefIndex\Code@MarginizeMacro
\long\def\Code@MarginizeMacro#1{{\escapechar\m@ne
    \@xa\glet\csname gmd/2marpar/\string#1\endcsname\gmd@justadot
%^^A    \xdef\mname@tomarginpar{\xiistring#1}
  }}

% \DefIndex\egCode@MarginizeEnvir
\long\def\egCode@MarginizeEnvir#1{\endgroup
  \Code@MarginizeEnvir{#1}}

% \DefIndex\Code@MarginizeEnvir
\long\def\Code@MarginizeEnvir#1{\addto@estomarginpar{#1}}

% And a~macro really putting the environment's name in a~marginpar
% shall be trigged at the beginning of the nearest codeline.
%
% Here it is:
\def\mark@envir{%\label{mark@envir}
  \ifx\envirs@tomarginpar\@empty
  \else
    \let\do\Text@Marginize
    \envirs@tomarginpar%
    \g@emptify\envirs@tomarginpar%
  \fi
  \ifx\envirs@toindex\@empty
  \else
    \gmd@doindexingtext
    \envirs@toindex
    \g@emptify\envirs@toindex%
  \fi}

\def\gmd@doindexingtext{%
  \def\do##1{% the |\envirs@toindex| list contains |\string|ed
    % macros or environments' names in braces and each  preceded
    % with |\do|. We extract the definition because we use it also in
    % line \ref{gmd@doindexingtext 2nd use}. 
    \if\bslash\@firstofmany##1\@@nil% if
    % |##1| begins with a~backslash, we will gobble it for
    % MakeIndex not see it.
    \edef\gmd@resa{\@gobble##1}%
    \@tempswatrue
    \else
    \edef\gmd@resa{##1}\@tempswafalse
    \fi
    \@xa\quote@mname\gmd@resa\relax% see line
    % \ref{quote@mname comm} \& subs. for commentary.
    {\if@tempswa
      \def\quoted@eschar{\quotechar\bslash}%
      \else\@emptify\quoted@eschar\fi
      \index@macro\macro@iname{##1}}}%
}


% One very important thing: initialisation of the list macros:
\@emptify\envirs@tomarginpar
\@emptify\envirs@toindex


% For convenience we'll make the `private letters' first not to bother
% ourselves with |\makeatletter| for instance when we want mark some
% \CS. And |\MakePrivateOthers| for the environment and other string
% case.
\outer\def\Define{\begingroup
  \MakePrivateLetters
% We do |\MakePrivateLetters| before |\@ifstarl| in order to avoid
% a~situation that \TeX\ sees a~control sequence with improper name
% (another \CS than we wished)
% (because |\@ifstarl| establishes the |\catcode|s for the next token):
  \@ifstarl{\MakePrivateOthers\Code@DefEnvir}{\Code@DefMacro}}

\outer\def\CodeUsage{\begingroup
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Code@UsgEnvir}{\Code@UsgMacro}}

% And then we launch the macros that close the group and do the work. 
\long\def\Code@DefMacro#1{%
  \Code@DefIndex#1% we use the internal macro; it'll close the group.
  \Code@MarginizeMacro#1}

% \DefIndex\Code@UsgMacro
\long\def\Code@UsgMacro#1{%
  \Code@UsgIndex#1% here also the internal macro; it'll close the group
  \Code@MarginizeMacro#1}

% The next macro is taken verbatim ;-) from \docfm\ and the subsequent
% |\let|s, too.
% \DefIndex\codeline@wrindex
\def\codeline@wrindex#1{\if@filesw
  \immediate\write\@indexfile
  {\string\indexentry{#1}%
    {\HLPrefix\number\c@codelinenum}}\fi}



\def\codeline@glossary#1{% It doesn't need to establish a~group since
  % it is always called in a~group.
  \if@pageinclindex
    \edef\gmu@tempa{gmdindexpagecs{\HLPrefix}{relax}{\EntryPrefix}}%        
  \else
    \edef\gmu@tempa{gmdindexrefcs{\HLPrefix}{relax}{\EntryPrefix}}% \inverb|relax| stands for the formatting command. But we don't want to do anything special with the change history entries. \ilrr
  \fi
  \protected@edef\gmu@tempa{%
    \@nx\protected@write\@nx\@glossaryfile{}%
    {\string\glossaryentry{#1\encapchar\gmu@tempa}%
    {\HLPrefix\number\c@codelinenum}}}%
  \gmu@tempa
}

% \changes[\changes]{v0.99m}{2008/08/09}{changed to write the line
% number instead of page number by default and with
% \env{codelineindex} option which seems to be more reasonable
% especially with the \env{countalllines} option}

% We initialize it due to the option (or lack of the option):
\AtBeginDocument{%
  \if@pageindex
    \let\special@index=\index
    \let\gmd@glossary\glossary
  \else
  % \DefIndex\special@index
    \let\special@index=\codeline@wrindex
    \let\gmd@glossary\codeline@glossary
    % \label{codeline indexnumber declaration}
  \fi}% postponed till |\begin{document}| with respect of \docfm-like
% declarations.

% And in case we don't want to index:
\def\gag@index{\let\index=\@gobble
  %\label{gag@index}
  \let\codeline@wrindex=\@gobble}
% We'll use it in one more place or two. And we'll wish to be able to
% undo it so
% let's copy the original meanings:
% \DefIndex\@@index \DefIndex\@@codeline@wrindex
\StoreMacros{\index\codeline@wrindex}

\def\ungag@index{\RestoreMacros{\index\@@codeline@wrindex}}
  %\label{ungag@index}
  


% Our next task is to define macros that'll mark and index an
% environment or other string in the code. Because of lack of
% a~backslash, no environment's name is scanned so we have to proceed
% different way. But we wish the user to have symmetric tools, i.e.,
% the `def' or `usage' use of an environment should be declared before
% the line where the environment occurs. Note the slight difference
% between these and the commands to declare a~\CS marking: the latter
% do not require to be used \emph{immediately} before the line containig the
% \CS to be marked.  We separate indexing from marginizing to leave
% a~possibility of doing only one of those things.
% \DefIndex\Code@DefEnvir
\long\def\Code@DefEnvir#1{%
  \endgroup
  \addto@estomarginpar{#1}%
  \addto@estoindex{#1}%
  \@defentryze{#1}{0}}

% \DefIndex\Code@UsgEnvir
\long\def\Code@UsgEnvir#1{%
  \endgroup
  \addto@estomarginpar{#1}%
  \addto@estoindex{#1}%
  \@usgentryze{#1}}

% \DefIndex\addto@estomarginpar
\long\def\addto@estomarginpar#1{%
  \edef\gmu@tempa{\@nx\do{\xiistring#1}}% we |\string| the argument to
  % allow it to be a~control sequence.
  \@xa\addtomacro\@xa\envirs@tomarginpar\@xa{\gmu@tempa}}

% \DefIndex\addto@estoindex
\long\def\addto@estoindex#1{%
  \edef\gmu@tempa{\@nx\do{\xiistring#1}}
  \@xa\addtomacro\@xa\envirs@toindex\@xa{\gmu@tempa}}


% And now a~command to mark a~`usage' occurrence of a~\CS, environment
% or another string in the commentary. As the `code' commands this also
% has plain and starred version, first for \CSs appearing explicitly and the
% latter for the strings and \CSs appearing implicitly.
\def\TextUsage{\begingroup
  %\label{TextUsage}
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Text@UsgEnvir}{\Text@UsgMacro}}

% \DefIndex\Text@UsgMacro
\long\def\Text@UsgMacro#1{%
  \endgroup{\tt\xiistring#1}%
  \Text@Marginize#1%
  \begingroup\Code@UsgIndex#1% we declare the kind of formatting of the entry.
  \text@indexmacro#1}

% \DefIndex\Text@UsgEnvir
\long\def\Text@UsgEnvir#1{%
  \endgroup{\tt\xiistring#1}%
  \Text@Marginize{#1}%
  \@usgentryze{#1}% we declare the `usage' kind of formatting of the
  % entry and index the sequence |#1|.
  \text@indexenvir{#1}}

% We don't provide commands to mark a~macro's or environment's
% definition present within the narrative because we think there won't
% be any: one defines macros and environments in the code not in
% the commentary. 
\def\TextMarginize{\begingroup
  \MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\egText@Marginize}{\egText@Marginize}}

% \DefIndex\egText@Marginize
\long\def\egText@Marginize#1{\endgroup
  \Text@Marginize#1}

% We check whether the margin pars are enabled and proceed
% respectively in either case.
\if@marginparsused
  \reversemarginpar
  \marginparpush\z@
  \marginparwidth8pc\relax
  % ^^A  \settowidth{\marginparsep}{\ \ }%
  %
  % You may wish to put not only macros and environments to
  % a~marginpar. 
  \long\def\gmdmarginpar#1{%
    \marginpar{\raggedleft\strut
      \hskip0ptplus100ptminus100pt%
      #1}}%\stanza
  % 
\else
  \long\def\gmdmarginpar#1{}%
\fi

\long\def\Text@Marginize#1{%
  \gmdmarginpar{\marginpartt\xiistring#1}}
% Note that the above macro will just gobble its argument if the
% marginpars are disabled.^^A\NoEOF so far O.K.
%
% It may be advisable to choose a~condensed typewriter font for the
% marginpars, if there is any. (The Latin Modern font family provides
% a~light condensed typewriter font, it's set in \pk{gmdocc} class.)
\let\marginpartt\tt

% If we pront also the narration lines' numbers, then the index entries for \CSs and
% environments marked in the commentary should have codeline numbers
% not page numbers and that is |\let| in line 
% \ref{codeline indexnumber declaration}.  On the other hand, if we
% don't print narration lines' numbers, then a~macro or an environment marked in
% the commentary should have page number not codeline number. This we
% declare here, among others\ we add the letter |p| before the page number.
% \DefIndex\do@properindex
\def\do@properindex{%\label{do@properindex}
  \if@printalllinenos\else
    \@pageinclindextrue
    \let\special@index=\index
  \fi}

% \stanza
% In \docfm\ all the `working' \TeX\ code should be braced in(to) the
% \env{macrocode} environments. Here another solutions are taken so to
% be \docfm-compatible we only should
%  nearly-ignore \env{macrocode(*)}s
% with their Percent and The Four Spaces Preceding ;-)\,. I.e., to ensure
% the line ends are `queer'. And that the \ds\ directives will be
% typeset as the \ds\ directives. And that the usual code escape
% char will be restored at |\end{macrocode}|. And to add the vertical
% spaces.
%
% ^^A~\NoEOF so far \acro{OK}
% If you know \docfm\ conventions, note that \gmdoc\ \emph{does not}
% require |\end{macrocode}| to be preceded ^^A(  
% with any particular number of any char :-)\,.
% \changes{v0.98b}{06/09/07}{To \env{macrocode(*)} default
% definitions \cs{QueerEOL} added}

\newenvironment*{macrocode*}{%\label{macrocode*}
  \if@codeskipput\else\par\addvspace\CodeTopsep\@codeskipputgtrue\fi
  \QueerEOL}%^^A\docstrips
  {\par\addvspace\CodeTopsep\CodeEscapeChar\\}
  % Let's remind that the starred version makes | |
% visible, which is the default in \pk{gmdoc} outside
% \env{macrocode}.
%
% So we should make the spaces \emph{invisible} for the unstarred
% version.

\newenvironment*{macrocode}{%\label{macrocode}
  \if@codeskipput\else\par\addvspace\CodeTopsep\@codeskipputgtrue\fi
  \QueerEOL}% \changes{v0.99l}{2008/08/06}{removed \cs{CodeSpacesBlank}}
  {\par\addvspace\CodeTopsep\CodeEscapeChar\\}
% Note that at the end of both the above environments the |\|'s
% r\ocircum le
% as the code escape char is restored. This is crafted for the
% |\SpecialEscapechar| macro's compatibility: this macro influences
% only the first \env{macrocode} environment. The situation that the
% user wants some queer escape char in general and in a~particular
% \env{macrocode} yet another seems to me ``unm\oumlaut glich,
% Prinzessin''\footnote{Richard Strauss after Oscar Wilde, ^^B
% \textit{Salome}.}. 
%
% \stanza
% Since the first \file{.dtx} I~tried to compile after the first
% published version of \gmdoc\ uses a~lot of commented out code in
% \env{macrocode}s, it seems to me necessary to add a~possibility to
% typeset \env{macrocode}s as if they were a~kind of \env{verbatim},
% that is to leave the code layer and narration layer philosophy.
%
%\Define*{oldmc}
\let\oldmc\macrocode
\let\endoldmc\endmacrocode
%\Define*{oldmc*}
\n@melet{oldmc*}{macrocode*}
\n@melet{endoldmc*}{endmacrocode*}

% Now we arm \env{oldmc} and \env{olmc*} with
% the macro looking for |%   \end|\arg{envir name}.
\addtomacro\oldmc{\@oldmacrocode@launch}%
\@xa\addtomacro\csname oldmc*\endcsname{%
  \@oldmacrocode@launch}

% \DefIndex\@oldmacrocode@launch
\def\@oldmacrocode@launch{%
  \emptify\gmd@textEOL% to disable it in |\gmd@docstripdirective|
  % launched within the code.
  \gmd@ctallsetup
  \glet\stored@code@delim\code@delim
  \@makeother\^^B\CodeDelim\^^B%
  \ttverbatim \gmd@DoTeXCodeSpace%
  \@makeother\|% because |\ttverbatim| doesn't do that.
  \MakePrivateLetters% see line \ref{MPL}.\par
  % ^^A  \@xa\@makeother\code@delim
  \docstrips@percent \@makeother\>%
  % sine qua non of the automatic delimiting is replacing possible
  % |*|\catother in the environment's name with |*|\catletter.
  % Not to complicate assume |*| may occur at most once and only at
  % the end. We also assume the environment's name consists only of
  % character tokens whose catcodes (except of |*|) will be the same
  % in the verbatim text.
  \@xa\gmd@currenvxistar\@currenvir*\relax
  \@oldmacrocode}

\foone{\catcode`*11 }
{\def\gm@xistar{*}}

\def\gmd@currenvxistar#1*#2\relax{%
  \edef\@currenvir{#1\if*#2\gm@xistar\fi}}
% The trick is that |#2| may be either |*|\catother\ or empty. If it's
% |*|, the test is satisfied and |\if...\fi| expands to
% |\gm@xistar|. If |#2| is empty, the test is also satisfied since
% |\gm@xistar| expands to |*| but there's nothing to expand to. So, if
% the environment's name ends with |*|\catother, it'll be substituted
% with |*|\catletter or else nothing will be added. (Note that a~|*|
% not at the end of env.\ name would cause a~disaster.)

%^^A~ \Define\@oldmacrocode
\foone{%
\catcode`[=1 \catcode`]=2
\catcode`\{=\active \@makeother\}
\@makeother\^^B
\catcode`/=0 \catcode`\\=\active
\catcode`&=14 \catcode`*=11
\catcode`\%=\active \obeyspaces}& % \CodeEscapeChar\/ \CDAnd
[& here the \cs{foone}'s second pseudo-argument begins
&%\stanza
/def/@oldmacrocode[&
/bgroup/let =/relax&% to avoid writing |/@nx | four times.
/xdef/oldmc@def[&
/def/@nx/oldmc@end####1/@nx%    /@nx\end&
/@nx{/@currenvir}[&
####1^^B/@nx/end[/@currenvir]/@nx/gmd@oldmcfinis]]&
/egroup&% now |\oldmc@edef| is defined to have one parameter delimited
&% with |\end|\arg{current env.'s name}
/oldmc@def&
/oldmc@end]&% \CDPerc
]

\def\gmd@oldmcfinis{%
  \@xa\CodeDelim\stored@code@delim
  \gmd@mchook}% see line \ref{gmd@mchook}

\def\OldMacrocodes{%% \changes{v0.99m}{2008/08/10}{renamed from
  %% \cs{VerbMacrocodes}} 
  \let\macrocode\oldmc
  \n@melet{macrocode*}{oldmc*}}



% To handle \ds\ directives in the code (in the old macrocodes
% case that is).

%    \begin{oldmc}
\foone{\catcode`\%\active}
{\def\docstrips@percent{\catcode`\%\active
    \let%\gmd@codecheckifds}}
%    \end{oldmc}\

% The point is, the active |%| will be expanded when just after it is
% the |\gmd@charbychar| cs token and next is some char, the |^^B| code
% delimiter at least. So, if that char is |<|, we wish to launch
% \ds\ directive typesetting. (Thanks to |\ttverbatim| all the |<|
% are `other'.)
\def\gmd@codecheckifds#1#2{% note that |#1| is just to gobble
  % \inverb|\gmd@charbychar| token.
% ^^A  \typeout{code if ds \on@line}%
  \if@dsdir\@dsdirgfalse
    \if\@nx<\@nx#2\afterfifi\gmd@docstripdirective
    \else\afterfifi{\xiipercent#1#2}%
    \fi
  \else\afterfi{\xiipercent#1#2}%
  \fi}
%
% \begin{environment}{macro}
% Almost  the same we do with the \env{macro(*)} environments, stating
% only their argument to be processed as the `def' entry. Of course,
% we should re|\catcode| it first.
% \DefIndex*\macro
\newenvironment{macro}{%\label{macro}
  \@tempskipa=\MacroTopsep
  \if@codeskipput\advance\@tempskipa by-\CodeTopsep\fi
  \par\addvspace{\@tempskipa}\@codeskipputgtrue
  \begingroup\MakePrivateLetters\MakePrivateOthers% we make also the
  % `private others' to cover the case of other sequence in the
  % argument. (We'll use the |\macro| macro also in the environment
  % for describing and defining environments.)
  \gmd@ifonetoken\Hybrid@DefMacro\Hybrid@DefEnvir}%
% \DefIndex*\endmacro
  {\par\addvspace\MacroTopsep\@codeskipputgtrue}
  % It came out that the \docfm's author(s) give the \env{macro}
  % environment also starred versions of commands as argument. It's \acro{OK}
  % since (the default version of) |\MakePrivateLetters| makes |*|
  % a~letter and therefore such a~starred version is just one \CS.
  % However, in \pk{doc.dtx} occur \env{macro}s that mark
  % \emph{implicit} definitions i.e., such that the defined \CS is not
  % scanned in the subsequent code.
%
% \begin{macro*}{macro*}
% And for those who want to to use this environment
% for marking implicit definitions, define the star
% version:
\@namedef{macro*}{\let\gmd@ifonetoken\@secondoftwo\macro}
% \DefIndex*\endmacro*
\@xa\let\csname endmacro*\endcsname\endmacro
% Note that \env{macro} and \env{macro*} have the same effect for
% more-than-one-token arguments thanks to |\gmd@ifonetoken|'s meaning
% inside unstarred \env{macro} (it checks whether the argument is
% one-token and if it isn't, |\gmd@ifonetoken| switches execution to
% `other sequence' path).
%
% The two environments behave different only with a~one-token
% argument: \env{macro} postpones indexing it till the first scanned
% occurrence while \env{macro*} till the first code line met.
% \end{macro*}
% \end{environment}
%
% \stanza
% Now, let's complete the details.
% First define an |\if|-like macro  that turns true when the string
% given to it consists of just one token (or one |{|\<text>|}|, to
% tell the whole truth).
\def\gmd@ifsingle#1#2\@@nil{%
  \def\gmu@tempa{#2}%
  \ifx\gmu@tempa\@empty}
% Note it expands to an open |\if...| test (unbalanced with |\fi|) so it
% has to be used as all the |\if|s, with optional |\else| and
% obligatory |\fi|. And cannot be used in the possibly skipped
% branches of other |\if...|s (then it would result with `extra
% |\fi|/extra |\else|' errors). But the below usage is safe since both
% |\gmd@ifsingle| and its |\else| and |\fi| are hidden in a~macro
% (that will not be |\expandafter|ed).
%
% Note also that giving |\gmd@ifsingle| an |\if...| or so as the first
% token of the argument will not confuse \TeX\ since the first token 
% is just gobbled. The possibility of occurrence of  |\if...| or so as
% a~not-first token seems to be negligible.
\def\gmd@ifonetoken#1#2#3{%
  \def\gmu@tempb{#3}% We hide |#3| from \TeX\ in case it's |\if...| or
  % so. \inverb|\gmu@tempa| is used in \inverb|\gmd@ifsingle|. \ilrr
  \gmd@ifsingle#3\@@nil
    \afterfi{\@xa#1\gmu@tempb}%
  \else
    \edef\gmu@tempa{\@xa\string\gmu@tempb}%
    \afterfi{\@xa#2\@xa{\gmu@tempa}}%
  \fi}
% Now, define the mysterious |\Hybrid@DefMacro| and |\Hybrid@DefEnvir|
% macros. They mark their argument with a~certain subtlety: they put
% it in a~marginpar at the point where they are and postpone indexing
% it till the first scanned occurrence or just the first code line met.
\long\def\Hybrid@DefMacro#1{%
  \Code@DefIndex{#1}% this macro closes the group opened by |\macro|.
  \Text@MarginizeNext{#1}}

\long\def\Hybrid@DefEnvir#1{%
  \Code@DefIndexStar{#1}% this macro also closes the group begun by
  % |\macro|.
  \Text@MarginizeNext{#1}}

\long\def\Text@MarginizeNext#1{%
  \gmd@evpaddonce{\Text@Marginize{#1}\ignorespaces}}
%^^A~\strut from before Text@Marginize deleted as unnecessary in everypar.

% The following macro adds its argument to |\everypar| using an auxiliary
% macro to wrap the stuff in. The auxiliary macro has
% a~self-destructor built in so it |\relax|es itself after first use.
\long\def\gmd@evpaddonce#1{%
  \global\advance\gmd@oncenum\@ne
  \@xa\long\@xa\edef% \CodeUsgIndex*{NeuroOncer}
    \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname{%
      \@nx\g@relaxen
      \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname}% Why does it
    % work despite it shouldn't? Because when the \CS got with
    % \inverb|\csname...\endcsname| is undefined, it's equivalent
    % |\relax| and therefore unexpandable. That's why it passes
    % \inverb|\edef| and is able to be assigned.\ilrr
  \@xa\addtomacro\csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname{#1}%
  \@xa\addto@hook\@xa\everypar\@xa{%
    \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname}%
}

\newcount\gmd@oncenum
%^^A % We store the number uniquifying the auxiliary
%^^A % macro in a~macro to save count registers (cf.\ \pk{gmutils}
%^^A % sec.\ \gmiflink{To Save Precious Count Registers}).

% \begin{environment}{environment}
% Wrapping a~description and definition of an environment in
% a~\env{macro} environment would look inappropriate (`zgrzyta\l o by'
% in Polish) although there's no \TeX nical obstacle to do
% so. Therefore we define the \env{environment}, because of \ae^^B
% sthetic and psychological reasons.
\@xa\let\@xa\environment\csname macro*\endcsname
\@xa\let\@xa\endenvironment\csname endmacro*\endcsname
% \end{environment}
%


%\subdivision[Index exclude list]{\gmhypertarget{Index exclude list}}
% We want some \CSs not to be indexed, e.g., the \LaTeX\
% internals and \TeX\ primitives.
%
% \docfm\ takes |\index@excludelist| to be a~|\toks| register to store
% the list of expelled \CSs. Here we'll deal another way. For each \CS
% to be excluded we'll make (|\let|, to be precise) a~control sequence
% and then we'll be checking if it's undefined (|\ifx|-equivalent
% |\relax|).\footnote{This idea comes from Marcin Woli\nacute ski.}
%
\def\DoNotIndex{\bgroup\MakePrivateLetters\DoNot@Index}
% \changes{v0.97}{06/09/04}{\cs{MakePrivateLetters} added}
% \changes{v0.98}{06/09/05}{Removed since it had not worked. The
% macros in the argument should be separated with commas. I~understood
% why it didn't work: because 't was iside a~command. So I~put it back}
% \changes{v0.98d}{06/9/11}{Unmade \cs{global}}


\long\def\DoNot@Index#1{\egroup% we close the group,
  \let\gmd@iedir\gmd@justadot% we declare the direction of the cluding
  % to be \emph{ex}cluding. We act this way to be able to reverse the
  % exclusions easily later.\ilrr
  \dont@index#1.}

% \DefIndex\dont@index
\long\def\dont@index#1{%
  \def\gmu@tempa{\@nx#1}% My \TeX\ Guru's trick to deal with |\fi|
  % and such, i.e., to hide from \TeX\ when it is processing a~test's
  % branch without expanding.
  \if\gmu@tempa.% a~dot finishes expelling
  \else
    \if\gmu@tempa,% The list this macro is put before may
    % contain commas and that's O.K., we just continue the work.
      \afterfifi\dont@index
    \else% what is else shall off the Index be expelled.
      {\escapechar\m@ne
        \xdef\gmu@tempa{\string#1}}%
      \@xa\let%
      \csname gmd/iexcl/\gmu@tempa\endcsname=\gmd@iedir% In the default
      % case explained e.g.\ by the macro's name, the last macro's
      % meaning is such that the test in line \ref{iexcltest} will
      % turn false and the subject \CS shall not be indexed.
      % We |\let| not |\def| to spare \TeX's memory.
      \afterfifi\dont@index
    \fi
  \fi}

%^^A(
% Let's now give the exclude list copied \*verbatim ;-) from
% \pk{doc.dtx}. I~give it in the code layer because I~suppose one will
% document not \LaTeX\ source but normal packages.
% 
% \begin{CodeSpacesSmall}
% \DoNotIndex\DoNotIndex \Define\DefaultIndexExclusions
\DoNotIndex\{ \DoNotIndex\}% \label{DNIbraces}the index entries of
% these two \CSs would be rejected by MakeIndex anyway.

\begin{MakePrivateLetters}% Yes, |\DoNotIndex| does
  % |\MakePrivateLetters| on its own but No, it won't have any effect
  % if it's given in another macro's |\def|.
  % \HideAllDefining
  \gdef\DefaultIndexExclusions{%
    \DoNotIndex{\@ \@@par \@beginparpenalty \@empty}%\label{DIE1}
    \DoNotIndex{\@flushglue \@gobble \@input}%
    \DoNotIndex{\@makefnmark \@makeother \@maketitle}%
    \DoNotIndex{\@namedef \@ne \@spaces \@tempa}%
    \DoNotIndex{\@tempb \@tempswafalse \@tempswatrue}%
    \DoNotIndex{\@thanks \@thefnmark \@topnum}%
    \DoNotIndex{\@@ \@elt \@forloop \@fortmp \@gtempa \@totalleftmargin}%
    \DoNotIndex{\" \/ \@ifundefined \@nil \@verbatim \@vobeyspaces}%
    \DoNotIndex{\| \~ \  \active \advance \aftergroup \begingroup \bgroup}%
    \DoNotIndex{\mathcal \csname \def \documentstyle \dospecials \edef}%
    \DoNotIndex{\egroup}%
    \DoNotIndex{\else \endcsname \endgroup \endinput \endtrivlist}%
    \DoNotIndex{\expandafter \fi \fnsymbol \futurelet \gdef \global}%
    \DoNotIndex{\hbox \hss \if \if@inlabel \if@tempswa \if@twocolumn}%
    \DoNotIndex{\ifcase}%
    \DoNotIndex{\ifcat \iffalse \ifx \ignorespaces \index \input \item}%
    \DoNotIndex{\jobname \kern \leavevmode \leftskip \let \llap \lower}%
    \DoNotIndex{\m@ne \next \newpage \nobreak \noexpand \nonfrenchspacing}%
    \DoNotIndex{\obeylines \or \protect \raggedleft \rightskip \rm \sc}%
    \DoNotIndex{\setbox \setcounter \small \space \string \strut}%
    \DoNotIndex{\strutbox}%
    \DoNotIndex{\thefootnote \thispagestyle \topmargin \trivlist \tt}%
    \DoNotIndex{\twocolumn \typeout \vss \vtop \xdef \z@}%
    \DoNotIndex{\, \@bsphack \@esphack \@noligs \@vobeyspaces \@xverbatim}%
    \DoNotIndex{\` \catcode \end \escapechar \frenchspacing \glossary}%
    \DoNotIndex{\hangindent \hfil \hfill \hskip \hspace \ht \it \langle}%
    \DoNotIndex{\leaders \long \makelabel \marginpar \markboth \mathcode}%
    \DoNotIndex{\mathsurround \mbox}%\verb+% \newcount \newdimen \newskip+
    \DoNotIndex{\nopagebreak}%
    \DoNotIndex{\parfillskip \parindent \parskip \penalty \raise \rangle}%
    \DoNotIndex{\section \setlength \TeX \topsep \underline \unskip}%
    \DoNotIndex{\vskip \vspace \widetilde \\ \% \@date \@defpar}%
    \DoNotIndex{\[ \]}% see line \ref{DNIbraces}.
    \DoNotIndex{\count@ \ifnum \loop \today \uppercase \uccode}%
    \DoNotIndex{\baselineskip \begin \tw@}%
    \DoNotIndex{\a \b \c \d \e \f \g \h \i \j \k \l \m \n \o \p \q}%
    \DoNotIndex{\r \s \t \u \v \w \x \y \z \A \B \C \D \E \F \G \H}%
    \DoNotIndex{\I \J \K \L \M \N \O \P \Q \R \S \T \U \V \W \X \Y \Z}%
    \DoNotIndex{\1 \2 \3 \4 \5 \6 \7 \8 \9 \0}%
    \DoNotIndex{\! \# \$ \& \' \( \) \. \: \; \< \= \> \? \_}% |\+|
    % seems to be so rarely used that it may be advisable to index it.
    \DoNotIndex{\discretionary \immediate \makeatletter \makeatother}%
    \DoNotIndex{\meaning \newenvironment \par \relax \renewenvironment}%
    \DoNotIndex{\repeat \scriptsize \selectfont \the \undefined}%
    \DoNotIndex{\arabic \do \makeindex \null \number \show \write \@ehc}%
    \DoNotIndex{\@author \@ehc \@ifstar \@sanitize \@title}%
    \DoNotIndex{\if@minipage \if@restonecol \ifeof \ifmmode}%
    \DoNotIndex{\lccode %|%\newtoks|
      \onecolumn \openin \p@ \SelfDocumenting}%
    \DoNotIndex{\settowidth \@resetonecoltrue \@resetonecolfalse \bf}%
    \DoNotIndex{\clearpage \closein \lowercase \@inlabelfalse}%
    \DoNotIndex{\selectfont \mathcode \newmathalphabet \rmdefault}%
    \DoNotIndex{\bfdefault}%
    % From the above list I~removed some |\new...| declarations because
    % I~think it may be useful to see gathered the special |\new...|s of
    % each kind. For the same reason I~would not recommend excluding
    % from the index such declarations as |\AtBeginDocument|,
    % |\AtEndDocument|, |\AtEndOfPackage|, |\DeclareOption|,
    % |\DeclareRobustCommand| etc. But the
    % common definitions, such as |\new/providecommand| and
    % |\(e/g/x)def|s, as the most common, in my opinion excluded should
    % be.^^A\)
    % 
    % \stanza
    % And some my exclusions:
    \DoNotIndex{\@@input \@auxout \@currentlabel \@dblarg}%
    \DoNotIndex{\@ifdefinable \@ifnextchar \@ifpackageloaded}%
    \DoNotIndex{\@indexfile \@let@token \@sptoken \^}% the latter comes
    % from \CSs like |\^^M|, see sec. \ref{Tasks}.
    \DoNotIndex{\addto@hook \addvspace}%
    \DoNotIndex{\CurrentOption}%
    \DoNotIndex{\emph \empty \firstofone}%
    \DoNotIndex{\font \fontdimen \hangindent \hangafter}%
    \DoNotIndex{\hyperpage \hyperlink \hypertarget}%
    \DoNotIndex{\ifdim \ifhmode \iftrue \ifvmode \medskipamount}%
    \DoNotIndex{\message}%
    \DoNotIndex{\NeedsTeXFormat \newcommand \newif}%
    \DoNotIndex{\newlabel}%
    \DoNotIndex{\of}%
    % ^^A\PassOptionsToClass\PassOptionsToPackage
    \DoNotIndex{\phantom \ProcessOptions \protected@edef}%
    \DoNotIndex{\protected@xdef \protected@write}%
    \DoNotIndex{\ProvidesPackage \providecommand}%
    \DoNotIndex{\raggedright}%
    \DoNotIndex{\raisebox \refstepcounter \ref \rlap}% ^^A\RequirePackage
    \DoNotIndex{\reserved@a \reserved@b \reserved@c \reserved@d}%
    \DoNotIndex{\stepcounter \subsection \textit \textsf \thepage \tiny}%
    \DoNotIndex{\copyright \footnote \label \LaTeX}%
    % \changes[\DefaultIndexExclusions]{v0.98a}{06/09/06}{more
    % macros added to the `exclude list'}
    \DoNotIndex{\@eha \@endparenv \if@endpe \@endpefalse \@endpetrue}%
    \DoNotIndex{\@evenfoot \@oddfoot \@firstoftwo \@secondoftwo}%
    \DoNotIndex{\@for \@gobbletwo \@idxitem \@ifclassloaded}%
    \DoNotIndex{\@ignorefalse \@ignoretrue \if@ignore}%
    \DoNotIndex{\@input@ \@input}%
    \DoNotIndex{\@latex@error \@mainaux \@nameuse}%
    \DoNotIndex{\@nomath \@oddfoot}%|%\@onlypreamble| should be indexed
    % \acro{IMO}.
    \DoNotIndex{\@outerparskip \@partaux \@partlist \@plus}%
    \DoNotIndex{\@sverb \@sxverbatim}%
    \DoNotIndex{\@tempcnta \@tempcntb \@tempskipa \@tempskipb}%\\
    % I~think the layout parameters  even the kernel, should not be
    % excluded: \inverb|\@topsep| \inverb|\@topsepadd|^^B 
    % \ \inverb|\abovedisplayskip| \inverb|\clubpenalty| etc.
    \DoNotIndex{\@writeckpt}%
    \DoNotIndex{\bfseries \chapter \part \section \subsection}%
    \DoNotIndex{\subsubsection}%
    \DoNotIndex{\char \check@mathfonts \closeout}%
    \DoNotIndex{\fontsize \footnotemark \footnotetext \footnotesize}%
    \DoNotIndex{\g@addto@macro \hfilneg \Huge \huge}%
    \DoNotIndex{\hyphenchar \if@partsw \IfFileExists }%
    \DoNotIndex{\include \includeonly \indexspace}%
    \DoNotIndex{\itshape \language \LARGE \Large \large}%
    \DoNotIndex{\lastbox \lastskip \m@th \makeglossary}%
    \DoNotIndex{\maketitle \math@fontsfalse \math@fontstrue \mathsf}%
    \DoNotIndex{\MessageBreak \noindent \normalfont \normalsize}%
    \DoNotIndex{\on@line \openout \outer}%
    \DoNotIndex{\parbox \part \rmfamily \rule \sbox}%
    \DoNotIndex{\sf@size \sffamily \skip}%
    \DoNotIndex{\textsc \textup \toks@ \ttfamily \vbox}%
    % \changes[\DoNotIndex]{v0.97}{06/09/04}{Excluding some star-versions of
    %   commands}
    % \nostanza\noindent
    % |%% \DoNotIndex{\begin*}| maybe in the future, if the idea gets
    % popular\dots \nostanza
    \DoNotIndex{\hspace* \newcommand* \newenvironment* \providecommand*}%
    \DoNotIndex{\renewenvironment* \section* \chapter*}%\label{DIE2}
  }% of |\DefaultIndexExclusions|.\par
  % I~put all the expellings into a~macro because I~want them
  % to be optional.
\end{MakePrivateLetters}
% \end{CodeSpacesSmall} \ResumeAllDefining

% And we execute it due to the (lack of) counter-corresponding option:
\if@indexallmacros\else
  \DefaultIndexExclusions
\fi


% If we expelled so many \CSs, someone may like it in general but
% he/she may need one or two expelled to be indexed back. So
%
\def\DoIndex{\bgroup\MakePrivateLetters\Do@Index}
% \changes{v0.97}{06/09/04}{\cs{MakePrivateLetters} added.}
% \changes{v0.98}{06/09/05}{\cs{MakePrivateLetters} removed since it
% hadn't worked. I~understood why it didn't work: because
% 't was iside a~command and I~put it back}
% \changes{v0.98d}{06/9/11}{Unmade \cs{global}}

\long\def\Do@Index#1{\egroup\@relaxen\gmd@iedir\dont@index#1.}% note
% we only redefine an auxiliary \CS and launch also |\dont@index| inner
% macro.

% And if a~user wants here make default exclusions and there do not
% make them, \heshe\ may use the |\DefaultIndexExclusions| declaration
% \himher self. This declaration \acro{OCSR}, but anyway let's provide the
% counterpart. It \acro{OCSR}, too.
%
\def\UndoDefaultIndexExclusions{%
  \StoreMacro\DoNotIndex
  % ^^A\dont@index
  \let\DoNotIndex\DoIndex
  % ^^A  \let\dont@index=\do@index
  \DefaultIndexExclusions
  % ^^A  \RestoreMacro\dont@index
  \RestoreMacro\DoNotIndex}
% \changes{v0.98d}{06/9/11}{Unmade \cs{global}}

%
%
% \subdivision{Index parameters}
%
% \begin{quotation}The |\IndexPrologue| macro is used to place a short
% message into the document above the index. It is implemented by
% redefining |\index@prologue|, a macro which holds the default
% text. We'd better make it a |\long| macro to allow |\par| commands 
% in its argument.\end{quotation}
\long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack}
% \label{IndexPrologue}

\def\indexdiv{\@ifundefined{chapter}{\section*}{\chapter*}}
% \changes{v0.98a}{06/09/06}{modified to contain the star so that
% it may be redefined for tests.}

\@ifundefined{index@prologue} {\def\index@prologue{\indexdiv{Index}%
    \markboth{Index}{Index}%
    Numbers written in italic refer to the \if@pageindex pages \else
    code lines \fi where the
    corresponding entry is described; numbers underlined refer to the
    \if@pageindex\else code line of the \fi definition; numbers in
    roman refer to the \if@pageindex pages\else code lines \fi where
    the entry is used. 
    \if@pageindex\else 
      \ifx\HLPrefix\@empty 
        The numbers preceded with `p.' are page numbers.
      \else The numbers with no prefix are page numbers.
    \fi\fi
    \ifx\IndexLinksBlack\relax\else
      All the numbers are hyperlinks.
      % ^^A, they are made black just to let Adobe Reader work
      % ^^A~faster. 
    \fi
    \gmd@dip@hook% this hook is intended to let a~user add
    % something without redefining the entire prologue, see below.
  }}{}

% During the preparation of this package for publishing I~needed
% only to add something at the end of the default index prologue. So
% \DefIndex\gmd@dip@hook
\@emptify\gmd@dip@hook
\long\def\AtDIPrologue#1{\g@addto@macro\gmd@dip@hook{#1}}
% \changes{v0.98c}{06/9/8}{added because of need}

% The Author(s) of \docfm\ assume \pk{multicol} is known not to
% everybody. My assumption is the other so
\RequirePackage{multicol}

% \begin{quotation}If \pk{multicol} is in use, when the index is
%   started we compute 
%   the remaining space on the current page; if it is greater than
%   |\IndexMin|, the first part of the index will then be placed in the
%   available space. The number of columns set is controlled by the
%   counter |\c@IndexColumns| which can be changed with a
%   |\setcounter| declaration.\end{quotation}
\newdimen\IndexMin \IndexMin = 133pt\relax% originally it was set
% 80\,pt, but with my default prologue there's at least 4.7\,cm needed
% to place the prologue and some index entries on the same page.
\newcount\c@IndexColumns \c@IndexColumns = 3
\renewenvironment{theindex}
  {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]%
      \IndexLinksBlack
      \IndexParms \let\item\@idxitem \ignorespaces}%
    {\end{multicols}}

\def\IndexLinksBlack{\hypersetup{linkcolor=black}}% To make Adobe
% Reader work faster.

\@ifundefined{IndexParms}
  {\def\IndexParms{%
      % \label{IndexParms}
      \parindent \z@
      \columnsep 15pt
      \parskip 0pt plus 1pt
      \rightskip 15pt
      \mathsurround \z@
      \parfillskip=-15pt plus 1 fil % \docfm\ defines this parameter
      % rigid but that's because of the stretchable space (more
      % precisely, a~|\dotfill|) between the item and the entries. But
      % in \pk{gmdoc} we define no such special delimiters, so we add
      % an ifinite stretch.
      \small
      \def\@idxitem{\par\hangindent 30pt}%
      \def\subitem{\@idxitem\hspace*{15pt}}%
      \def\subsubitem{\@idxitem\hspace*{25pt}}%
      \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}%
      \ifx\EntryPrefix\@empty\else\raggedright\fi% long (actually,
      % a~quite \emph{short but nonempty} entry prefix) made space
      % stretches so terribly large in the justified paragraphs that
      % we should make |\raggedright| rather.
      \ifnum\c@IndexColumns>\tw@\raggedright\fi% the numbers in narrow
      % col\-umns look better when they are |\raggedright| in my opinion.
    }}{}

\def\PrintIndex{% we ensure the standard meaning of the line end
  % character not to cause a~disaster.
  \@ifQueerEOL{\StraightEOL\printindex\QueerEOL}%
  {\printindex}}

% Remember that if you want to change not all the parameters, you
% don't have to redefine the entire |\IndexParms| macro but you may
% use a~very nice \LaTeX\ command |\g@addto@macro| (it has |\global|
% effect, also with an apeless name (|\gaddtomacro|) provided by
% \pk{gmutils}. (It adds its second argument at the end of definition
% of its first argument provided the first argument is a~no-argument
% macro.) Moreover, \pk{gmutils} provides also 
% |\addtomacro| that has the same effect except it's not |\global|.
%
%
%
% \subdivision{The \ds\ directives}
%
%^^A  \StraightEOL
%^^A  \iffalse ^^A~ this passage is obsoleted
%^^A 
%^^A  This passage is obsoleted on 2006/11/30.
%^^A 
%^^A  In the \gmdoc\ thinking, the \ds\ directives belong to the
%^^A  narration layer since they all begin with |%|. For now I~don't
%^^A  have a~more minimal idea than to define a~pair of macros the first of
%^^A  which would |\active|ate the |<| and the other, assigned to the
%^^A  active |<|, would do the work and re`other' the |<| back.
%^^A 
%^^A  We provide two versions of the seargant-activating macro: the first
%^^A  makes only the first subsequent seargant typeset a~\ds\
%^^A  directive (and the previous meaning of the |<| will be restored, the
%^^A  latter doesn't restore the previous meaning of |<| after (by) the
%^^A  first occurrence and the latter obeys usual scoping rules while the
%^^A  scoping rules of the first (|\docstrip|) are more strict: the scope
%^^A  is delimited by the first occurrence of the subject~|<|.
%^^A 
%^^A  Let us remeber that, just as all the control sequences except
%^^A  |\relax|, you can use |\docstrips| as an environment, i.e., in the
%^^A  |\begin{docstrips}|\dots |\end{docstrips}| syntax. And, that
%^^A  \env{macrocode} environment declares it.
%^^A  \bgroup\catcode`\<=\active
%^^A  \firstofone{\egroup
%^^A    % \stanza
%^^A    \newcommand*\docstrip{%
%^^A      \gmd@storesearg
%^^A      \catcode`\<=\active
%^^A      \gmd@setdocstrips
%^^A      \let\gmd@docstripshook=\gmd@restoresearg}%
%^^A    % \stanza
%^^A    \newcommand*\docstrips{%
%^^A      \catcode`\<=\active
%^^A      \gmd@setdocstrips
%^^A      \@emptify\gmd@docstripshook}%
%^^A    % \stanza
%^^A    \def\gmd@setdocstrips{%
%^^A      \def<{\ifmmode\sgtleftxii\else\afterfi\gmd@docstripdirective\fi}}
%^^A    %\stanza
%^^A    \def\gmd@storesearg{%
%^^A      \edef\gmd@SeargantCat{\the\catcode`\<}%
%^^A      \ifnum\gmd@SeargantCat=\active
%^^A        \let\gmd@SeargantMng=<%
%^^A      \fi}
%^^A    % \stanza
%^^A    \def\gmd@restoresearg{%
%^^A      \catcode`\<=\gmd@SeargantCat\relax
%^^A      \ifnum\gmd@SeargantCat=\active
%^^A        \let<=\gmd@SeargantMng
%^^A      \fi}%
%^^A    % \stanza
%^^A  }% of |\active| |<|'s |\firstofone|
%^^A 
%^^A  \fi ^^A~of the obsoletion iffalse
%^^A  \QueerEOL

\foone{\@makeother\<\@makeother\>
  \glet\sgtleftxii=<}
{
  \def\gmd@docstripdirective{%
    \begingroup\let\do=\@makeother
    \do\*\do\/\do\+\do\-\do\,\do\&\do\|\do\!\do\(\do\)\do\>\do\<% ^^Ayes, we
    % ^^A make \inverb|<|\catother\ since a~directive |<<|\<any text till ^^B>>
    % ^^A~the end of line> theoretically may occur.
    \@ifnextchar{<}{%
      \let\do=\@makeother \dospecials
      \gmd@docstripverb}
    {\gmd@docstripinner}}%

  \def\gmd@docstripinner#1>{%
    \endgroup
    \def\gmd@modulehashone{%
      \Module{#1}\space
      \@afternarrgfalse\@aftercodegtrue\@codeskipputgfalse}%
    % ^^A    \gmd@docstripshook
    \gmd@textEOL\gmd@modulehashone}
  % A~word of explanation: first of all, we
  % close the group for changed |\catcode|s; the directive's text has its
  % |\catcode|s fixed. Then we put the directive's text wrapped with the
  % formatting macro into one macro in order to give just one token
  % the \gmdoc's \TeX\ code scanner. 
  % ^^A But before we launch the \TeX\ code
  % ^^A  scanning with all the b\&w, we virtually restore the meaning of
  % ^^A  further |<|s to let them start further \ds\ directives,
  % ^^A  and after this possible restore (if it \emph{actually} takes place
  % ^^A  depends on the declaration used: |\docstrip| or |\docstrips|) we
  % Then launch this big \TeX\ code scanning machinery by calling
  % |\gmd@textEOL| which is an alias for the `narrative' meaning of the
  % line end. This macro opens the verbatim group and launches the
  % char-by-char scanner. That is this scanner because of what we
  % encapsulated the directive's text with the formatting into one
  % macro: to let it pass the scanner. 
  % 
  % That's why in the `old' macrocodes case the active |%| closes the
  % group before launching |\gmd@docstripdirective|.
  % 
  % \stanza
  % The `verbatim' directive macro works very similarly.
}

\foone{\@makeother\<\@makeother\>
  \glet\sgtleftxii=<
  \catcode`\^^M=\active}%
{
  \def\gmd@docstripverb<#1^^M{%
    \endgroup%
    \def\gmd@modulehashone{%
      \ModuleVerb{#1}\@afternarrgfalse\@aftercodegtrue%
      \@codeskipputgfalse}%
    \gmd@docstripshook%
    \gmd@textEOL\gmd@modulehashone^^M}%
}

% (\*Verbatim ;-) from \docfm:)
\providecommand*\Module[1]{{\mod@math@codes$\langle\mathsf{#1}\rangle$}}

\providecommand*\ModuleVerb[1]{{\mod@math@codes$\langle\langle\mathsf{#1}$}}

\def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026 }

% \subdivision{The changes history}
% 
% The contents of this section was copied \*verbatim from the
% \docfm's documentation, with only smallest necessary changes. Then ^^A(( 
% my additions were added :-))\,.
%
% \begin{quotation}To provide a change history log, the |\changes|
% command has been
%   introduced.  This takes [one optional and] three [mandatory]
%   arguments, respectively, [the macro that'll become the entry's
%   second level,] the version 
%   number of the file, the date of the change, and some detail
%   regarding what change has been made [i.e., the description of the
%   change]. The [second] of these arguments 
%   is otherwise ignored, but the others are written out and may be
%   used to generate a history of changes, to be printed at the end of
%   the document. [\dots\ I~ommit an obsolete remark about then-older
%   MakeIndex's versions.]
% 
%   The output of the |\changes| command goes into the
%   \<Glossary_File> and therefore uses the normal |\glossaryentry|
%   commands. Thus MakeIndex or a~similar program can be used to
%   process the output into a sorted ``glossary''. The |\changes|
%   command commences by taking the usual measures to hide its
%   spacing, and then redefines |\protect| for use within the argument
%   of the generated |\indexentry| command.  We re-code nearly all
%   chars found in |\@sanitize| to letter since the use of special
%   package which make some characters active might upset the
%   |\changes| command when writing its entries to the file. However
%   we have to leave |%| as
%   comment and | | as \<space> otherwise chaos will happen. And, of
%   course the |\| should be available as escape character.\end{quotation}
%
% We put the definition inside a~macro that will be 
% executed by (the first use of) |\RecordChanges|. And we provide
% the default definition of |\changes| as a~macro just gobbling its
% arguments. We do this to provide no changes' writing out if
% |\RecordChanges| is not used.
%
% 
% \changes[\changes]{v0.98e}{06/09/23}{definition put into a~macro that shall
% launch it when \cs{RecordChanges} is executed and the default
% defining it as a~gobbling macro}
%
\def\gmd@DefineChanges{%
  \outer\long\def\changes{\@bsphack\begingroup\@sanitize
    \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
    \MakePrivateLetters \StraightEOL
    \MakeGlossaryControls
    \changes@}}

\newcommand\changes[4][]{\PackageWarningNoLine{gmdoc}{%
    ^^JThe \bslash changes command used \on@line
    ^^Jwith no \string\RecordChanges\space declared.
    ^^JI shall not warn you again about it}%
  %^^A\gmd@countlines{#4}%
  \renewcommand\changes[4][]{%^^A\gmd@countlines{#4}
  }}

\def\MakeGlossaryControls{%
  \edef\actualchar{\string=}\edef\quotechar{\string!}%
  \edef\levelchar{\string>}\edef\encapchar{\xiiclub}}%for the glossary the
  % `actual', the `quote' and the `level' chars are respectively |=|,
  % |!| and |>|, the `encap' char remains untouched. I~decided to
  % preserve the \docfm's settings for the compatibility.


\newcommand\changes@[4][\generalname]{%
% \changes[\changes]{v0.97}{06/09/04}{The optional pseudo-argument
%   added intended to be the macro-entry.}
  \if@RecentChange{#3}% if the date is later than the one stored in
  % \cs{c@Chang\+es\+Start\+Date},
    \@tempswafalse
    \ifx\generalname#1% then we check whether a~\CS-entry is given
    % in the optional first argument or is it unchanged.
      \ifx\last@defmark\relax\else% if no particular \CS is
      % specified in |#1|, we check whether |\last@defmark| contains
      % something and if so, we put it into |\gmu@tempb| scratch macro.
        \@tempswatrue
        \edef\gmu@tempb{% it's a~bug fix: while typesetting traditional
          % \file{.dtx}es, \inverb|\last@defmark| came out with \inverb|\| at the
          % beginning (which resulted with \inverb|\\|\<name> in the change
          % log) but while typesetting the `new' way, it occurred 
          % without the bslash. So we gobble the bslash if it's
          % present and two lines below we handle the exception of
          % \inverb|\last@defmark|\equals|{\}| (what would happen if 
          % a~definition of \inverb|\\| was marked in new way \gmdoc ing).%^^A]
          \if\bslash\last@defmark\else\last@defmark\fi}%
        \ifx\last@defmark\bslash\let\gmu@tempb\last@defmark\fi%
        \n@melet{gmd@glossCStest}{gmd/isaCS/\last@defmark}%
      \fi
    \else%the first argument isx not |\generalname| i.e.,
         %a~particular \CS is specified by it (if some day one
    % wishes to |\changes| |\generalname|, \heshe\ should type
    % |\changes[generalname]|\dots)
      \@tempswatrue
      {\escapechar\m@ne
        \xdef\gmu@tempb{\string#1}}%
      \if\bslash\@xa\@firstofmany\string#1\relax\@@nil% we check
      % whether \inverb|#1| is a~\CS\dots\ilrr
        \def\gmd@glossCStest{1}%\dots\ and tell the glossary if so.
      \fi
      % ^^A~\@xa\quote@mname\@tempb\relax
    \fi
    \@ifundefined{gmd@glossCStest}{\def\gmd@glossCStest{0}}{}%
    \protected@edef\gmu@tempa{\@nx\gmd@glossary{%
        \if\relax\GeneralName\relax\else
          \GeneralName% it's for the |\DocInclude| case to precede
          % every |\changes| of the same file with the file name, cf.\ line
          % \ref{GeneralName}.
        \fi
        #2\levelchar%
        \if@tempswa% If the macro |\last@defmark|
        % doesn't contain any \CS name (i.e., is empty) nor |#1|
        % specifies a~\CS, the current
        % changes entry was done at top-level.  In this case we precede
        % it by |\generalname|.
          \gmu@tempb
          \actualchar\bslash verb*%
          \if\verbatimchar\gmu@tempb$\else\verbatimchar\fi
          \if1\gmd@glossCStest\quotechar\bslash\fi \gmu@tempb
          \if\verbatimchar\gmu@tempb$\else\verbatimchar\fi       
        \else
          \space\actualchar\generalname
        \fi
        :\levelchar%^^A\gmd@deeolize{
        #4%^^A}
      }}%
    \gmu@tempa
    \grelaxen\gmd@glossCStest
  \fi% of |\if@recentchange|
  %^^A\gmd@countlines{#4}%
  \endgroup\@esphack}

% Let's initialize |\last@defmark| and |\GeneralName|.
\@relaxen\last@defmark
\@emptify\GeneralName

\def\ChangesGeneral{\grelaxen\last@defmark}% If automatic detection of
% definitions is on, the default entry of |\changes| is the meaning of
% |\last@defmark|, the last detected definiendum that is. The
% declaration defined here serves to start a~scope of `general'
% \cs{changes}' entries. 

\AtBegInput{\ChangesGeneral}

% Let's explain |\if@RecentChange|. We wish to check whether the
% change's date is later than date declared (if any limit date
% \emph{was} declared). First of all, let's establish a~counter to store
% the declared date. The untouched counters are equal 0 so if no date
% is declared there'll be no problem. The date will have the
% \<YYYYMMDD> shape both to be easily compared and readable.
\newcount\c@ChangesStartDate


\def\if@RecentChange#1{%
  \gmd@setChDate#1\@@nil\@tempcnta
  \ifnum\@tempcnta>\c@ChangesStartDate}

\def\gmd@setChDate#1/#2/#3\@@nil#4{% the last parameter will be a~|\count|
  % register.
  #4=#1\relax
  \multiply#4 by\@M
  \count8=#2\relax% I~know it's a~bit messy not to check whether the
  % |#4| |\count| is |\count8| but I~know this macro will only be used
  % with |\count0 | \nlpercent(\cs{@\+te\+m\+p\+cn\+ta}) and some
  % higher (not a~scratch) one.
  \multiply\count8 by100 %
  \advance#4 by\count8 \count8=\z@
  \advance#4 by#3\relax}

% Having the test defined, let's define the command setting the date
% counter. |#1| is to be the version and |#2| the date
% \cs[]{\{\<year>/\<month>/\<day>\}}. 

\def\ChangesStart#1#2{%
% \changes{v0.98e}{06/09/23}{\cs{string}s added before the seargants
% in the message with account of \cs{docstrip(s)}}
  \gmd@setChDate#2\@@nil\c@ChangesStartDate
  \typeout{^^JPackage gmdoc info: ^^JChanges' start date #1 memorized
    as \string<\the\c@ChangesStartDate\string> \on@line.^^J}
  \advance\c@ChangesStartDate\m@ne% we shall show the changes \emph{at ^^B
  % the specified day} and later.
  \ifnum\c@ChangesStartDate>19820900 %\unskip\StraightEOL\footnote{^^A
  % DEK writes in \textit{\TeX, The Program} of September 1982 as the
  % date of \TeX\ Version 0.}\QueerEOL\label{TeXVer0}
  % see \gmiflink[personalchanges]{below}.
    \edef\gmu@tempa{%
      \@nx\g@addto@macro\@nx\glossary@prologue{%
        The changes
        \if\relax\GeneralName\relax\else of \GeneralName\space\fi
        earlier than
        #1 \if\relax#1\relax #2\else(#2)\fi\space are not shown.}}%
    \gmu@tempa
  \fi}
% (Explanation to line \ref{TeXVer0}.)
% \gmhypertarget[personalchanges]{My} \TeX\ Guru has remarked that the
% change history tool should be used for documenting the changes that
% may be significant for the users not only for the author and talking
% of what may be significant to the user, no changes should be hidden
% since the first published version. However, the changes' start date
% may be used to provide hiding the author's `personal' notes: \heshe\
% should only date the `public' changes with the four digit year and
% the `personal' ones with two digit year and set
% |\ChangesStart{}{1000/0/0}| or so.
%
% In line \ref{TeXVer0} I~establish a~test value that corresponds to
% a~date earlier than any \TeX\ stuff and is not too small (early) to
% ensure that hiding the two digit year changes shall not be mentioned
% in the changes prologue.
% 
% \changes{v0.98d}{2006/9/15}{An entry to show the change history
% works: watch and admire. Some sixty \cs{changes} entries irrelevant
% for the users-other-than-myself are hidden due to the trick
% described on
% p.\protect\,\protect\pageref{personalchanges}.%
% \protect\StoreMacro\protect\hyperpage 
% \protect\def\protect\hyperpage#1{\protect\RestoreMacro\protect\hyperpage}%
% \protect\gobble}
% \stanza
% \begin{quotation}The entries [of a~given version number] are sorted
%   for convenience by the name of [the macro explicitly specified as
%   the first argument or] the most recently introduced macroname
%   (i.e., that in the most recent |\begin{macro}| command [or
%     |\Define|]). We therefore provide [|\last@defmark|] to
%     record that argument, and provide a default definition in case
%     |\changes| is used outside a \env{macro} environment. (This is a
%     wicked hack to get such entries at the beginning of the sorted
%     list! It works providing no macro names start with |!| or |"|.)
% 
% This macro holds the string placed before changes entries on
% top-level.\end{quotation} 
\def\generalname{General}

% \changes[\chschange]{v0.98a}{06/09/06}{added.}
%
% \stanza
% \begin{quotation}To cause the changes to be written (to a \pk{.glo})
% file, we define |\RecordChanges| 
%   to invoke \LaTeX's usual |\makeglossary| command.\end{quotation}
% 
% I~add to it also the |\write|ing definition of the |\changes| macro
% to ensure no changes are written out without |\RecordChanges|.
%
\def\RecordChanges{\makeglossary\gmd@DefineChanges
  \@relaxen\RecordChanges}
% \changes{v0.98c}{06/09/08}{made self-\cs{relax}ing}
% \changes{v0.98e}{06/09/23}{made it defining \cs{changes}}
% \begin{quotation}The remaining macros are all analogues of those used
%   for the \env{theindex} environment. 
% When the glossary is started we compute the space which remains at
% the bottom of the current page; if this is greater than |\GlossaryMin| then the
% first part of the glossary will be placed in the available space. The number of
% columns set [is] controlled by the counter |\c@GlossaryColumns| which can be
% changed with a |\setcounter| declaration.\end{quotation}
% \begin{CodeSpacesBlank}

\newdimen\GlossaryMin         \GlossaryMin       = 80pt
% \DefIndex*\c@GlossaryColumns
\newcount\c@GlossaryColumns   \c@GlossaryColumns = 2
% \end{CodeSpacesBlank}
%\begin{quotation}The environment \env{theglossary} is defined in the
%same manner as the \env{theindex} 
% environment.\end{quotation}
%
\newenvironment{theglossary}{%
% \changes{v0.99m}{2008/08/10}{added \cs{IndexLinksBlack}}
  \begin{multicols}\c@GlossaryColumns
    [\glossary@prologue][\GlossaryMin]%
    \GlossaryParms \IndexLinksBlack
    \let\item\@idxitem \ignorespaces}%
  {\end{multicols}}

% Here is the MakeIndex style definition:
% \index{gmglo.ist@\file{gmglo.ist}}
%^^A \begin{docstrips}
%</package>
%<+gmglo>preamble
%<+gmglo>"\n \\begin{theglossary} \n
%<+gmglo>\\makeatletter\n"
%<+gmglo>postamble
%<+gmglo>"\n\n \\end{theglossary}\n"
%<+gmglo>keyword "\\glossaryentry"
%<+gmglo>actual '='
%<+gmglo>quote '!'
%<+gmglo>level '>'
%<*package>
%^^A \end{docstrips}
% The MakeIndex shell command for the glossary should look as
% follows:
% \[|makeindex -r -s gmglo.ist -o |\<myfile>|.gls |\<myfile>|.glo|\]
% ^^B
% ^^B makeindex -r -s gmglo.ist -o <myfile>.gls <myfile>.glo 
% ^^B
% where |-r| commands MakeIndex not to make implicit page ranges,
% |-s| commands MakeIndex to use the style stated next not the
% default settings and the |-o| option with the subsequent filename
% defines the name of the output.
%
% \begin{quotation}The |\GlossaryPrologue| macro is used to place
%   a~short message above the glossary into the document. It is
%   implemented by redefining |\glossary@prologue|, a macro which
%   holds the default text. We better make it a long macro to allow
%   |\par| commands in its argument.\end{quotation}
%
\long\def\GlossaryPrologue#1{\@bsphack
  \def\glossary@prologue{#1}%
  \@esphack}
% \begin{quotation}Now we test whether the default is already defined
% by another package file. If not we define it.\end{quotation}
% \changes{v0.98a}{06/09/06}{a~bug fixed: \cs{filediv} replaced with
% \cs{indexdiv} in the default prologue.}
\@ifundefined{glossary@prologue}
  {\def\glossary@prologue{\indexdiv{{Change History}}%
      \markboth{{Change History}}{{Change History}}%
    }}{}
%\begin{quotation}Unless the user specifies otherwise, we set the
%change history using the same parameters as for the index.\end{quotation}
% \Define\GlossaryParms
\AtBeginDocument{%
  \@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms}{}}

%\begin{quotation}
%  To read in and print the sorted change history, just put the
%  |\PrintChanges| command as the last (commented-out, and thus
%  executed during the documentation pass through the file) command in
%  your package file. Alternatively, this command may form one of the
%  arguments of the |\StopEventually| command, although a change history
%  is probably not required if only the description is being printed.
%  The command assumes that MakeIndex or some other program has
%  processed the \pk{.glo} file to generate a sorted \pk{.gls}
%  file.\end{quotation} \Define\PrintChanges
\def\PrintChanges{% to avoid a~disaster among queer EOLs:
  \@ifQueerEOL
    {\StraightEOL\@input@{\jobname.gls}\QueerEOL}%
    {\@input@{\jobname.gls}}%
    \g@emptify\PrintChanges}

\pdef\toCTAN#1#2{%\ 
  % \begin{enumargs}
  % \item version number,
  % \item date \<year/month/day>.
  % \end{enumargs}
  % \changes{v0.99r}{2008/11/22}{added}
    \changes{#1}{#2}{put to \acro{CTAN} on #2}}


%
% \subdivision{The checksum}
%
%
% \docfm\ provides a~checksum mechanism that counts the backslashes 
% in the scanned code. Let's do almost the same.
%
% At the beginning of the source file you may put the |\CheckSum|
% macro with a~number (in one of \TeX's formats) as its argument and
% \TeX\ with \pk{gmdoc} shall count the number of the \emph{escape ^^B
%   chars} in the source file and tell you in the \file{.log} file (and
%   on the terminal)
% whether you have typed the right number. If you don't type |\CheckSum|,
% \TeX\ anyway will tell you how much it is.
\newcount\check@sum

\def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack}

\newcounter{CheckSum}
% \label{checksum}

\newcommand*\step@checksum{\stepcounter{CheckSum}}
% And we'll use it in the line \ref{checksumUse} (|\stepcounter| is
% |\global|). See also the |\chschange| declaration,
% l.\,\ref{chschange}.  
%
% However, the check sum mechanism in \gmdoc\ behaves slightly
% different than in \docfm\ which
% is nicely visible while \pk{gmdoc}ing \docfm: \docfm\ states its
% check sum to be 2171 and our count counts 2126. The mystery lies in
% the fact that \docfm's CheckSum mechanism counts the code's
% backslashes no matter what they mean and the \gmdoc's the escape
% chars so, among others, |\\| at the default settings increases \docfm's
% CheckSum by 2 while the \gmdoc's by 1. (There are 38 occurrences of |\\|
% in \pk{doc.dtx} \env{macrocode}s, I~counted
% myself.)\begin{StraightEOL}\footnote{My opinion is that nowadays
%     a~check sum 
%     is not necessary for checking the completness of a~file but
%     I~like it as a~marker of file development and this more than
%     that is its r\ocircum le in \gmdoc.}
% \end{StraightEOL}
%
%
% \begin{quotation}But |\Finale| will be called at the very end of a
%   file. This is exactly the point were we want to know if the file
%   is uncorrupted. Therefore we also call |\check@checksum| at this
%   point.\end{quotation}
% In \pk{gmdoc} we have the |\AtEndInput| hook.
\AtEndInput{\check@checksum}

% Based on the lines 723--741 of \pk{doc.dtx}.
\def\check@checksum{\relax
  \ifnum\check@sum=\z@
    \edef\gmu@tempa{% why \cs{edef}---see line \ref{wypis sumy}
      \@nx\typeout{**********************************^^J%
        * The input file \gmd@inputname\space has no Checksum
        stated.^^J%
        * The current checksum is \the\c@CheckSum.^^J%
        \gmd@chschangeline% a~check sum changes history entry, see below.
        * (package gmdoc info.)^^J%
        **********************************^^J}}
    \else
    \ifnum\check@sum=\c@CheckSum
      \edef\gmu@tempa{%
        \@nx\typeout{*****+*+*+*+*+*+*+*+*+*+^^J%
          * The input file \gmd@inputname: Checksum passed.^^J%
          \gmd@chschangeline
          * (package gmdoc info.)^^J%
          *****+*+*+*+*+*+*+*+*+*+^^J}}
    \else
      \edef\gmu@tempa{%
        \@nx\typeout{********!*!*!*!*!*!*!*!*!*!*!*!^^J%
          *! The input file \gmd@inputname:^^J%
          *! The CheckSum stated: \the\check@sum\space<> my
          count: \the\c@CheckSum.^^J%
          \gmd@chschangeline
          *! (package gmdoc info.)^^J%
          ********!*!*!*!*!*!*!*!*!*!*!*!^^J}}%
    \fi
  \fi
  \gmu@tempa
  \@xa\AtEndDocument\@xa{\gmu@tempa}%\label{wypis sumy} we print 
  % the checksum notification on the terminal immediately and at end
  % of \TeX ing not to have to scroll the output far nor search the log.
  \global\check@sum\z@}

% As I~mentioned above, I~use the check sum mechanism to mark the file
% growth. Therefore I~provide a~macro that produces a~line on the
% terminal to be put somewhere at the
% beginning of the source file's commentary for instance.
\def\gmd@chschangeline{%
  \xiipercent\space\string\chschange
  {\@ifundefined{fileversion}{v???}{\fileversion}}%
  {\the\year/\the\month/\the\day}%
  {\the\c@CheckSum}^^J%
  \xiipercent\space\string\chschange
  {\@ifundefined{fileversion}{v???}{\fileversion}}%
  {\@xa\@gobbletwo\the\year/\the\month/\the\day}%
  {%  with two di\-g\-it year in case you use |\ChangesStart|.
    \the\c@CheckSum}^^J}

% And here the meaning of such a~line is defined:
\newcommand*\chschange[3]{%\label{chschange}
  \csname changes\endcsname{#1}{#2}{CheckSum #3}% |\csname...| because
  % \nlpercent\cs{cha\+n\+g\+es} is \inverb|\outer|.
  \CheckSum{#3}}
% It will make a~`General' entry in the change history unless
% used in some |\Define|'s scope or inside a~\env{macro}
% environment. It's intended to be put 
% somewhere at the beginning of the documented file.
%
%
% \changes[\CheckSum]{v0.98a}{06/09/06}{`package gmdoc info'
% statement moved to the end of the checksum messages.}
% \changes[\CheckSum]{v0.98b}{06/09/07}{typing out the
% \cs{chschange} line added}

%
%
% \subdivision{Macros from \pk{ltxdoc}}
%
% I'm not sure whether this package still remains `minimal' but
% I~liked the macros provided by \pk{ltxdoc.cls} so much\dots
% \stanza
%
% The next page setup declaration is intended to be used
% with the \pk{article}'s default Letter paper size. But since 
\newcommand*\ltxPageLayout{%
%\begin{quotation}Increase the text width slightly so that width the standard fonts
% 72 columns of code may appear in a |macrocode| environment.\end{quotation}
% 
  \setlength{\textwidth}{355pt}%
% \begin{quotation}Increase the marginpar width slightly, for long
% command names. And increase the left margin by a similar
% amount.\end{quotation}
% To make these settings independent from the defaults (changed e.g.\
% in \pk{gmdocc.cls}) we replace the original |\addtolength|s with
% |\setlength|s.
%^^A  \addtolength\marginparwidth{30pt}%
%^^A  \addtolength\oddsidemargin{20pt}% 
%^^A  \addtolength\evensidemargin{20pt}
 \setlength\marginparwidth{95pt}%
 \setlength\oddsidemargin{82pt}%
 \setlength\evensidemargin{82pt}}

% %\skiplines
% \def\task#1#2{}
% % What is this for? Probably to turn an obsolete command off. Or maybe
% % a~\acro{TODO}?
% % \endskiplines

%\subdivision{\cs{DocInclude} and the \pk{ltxdoc}-like setup}
%
% Let's provide a~command for including
% multiple files into one document. In the \pk{ltxdoc} class such
% a~command is defined to include files as parts. But we prefer to
% include them as chapters in the classes that provide
% |\chapter|. We'll redefine |\maketitle| so that it make a~chapter or
% a~part heading \emph{unlike} in \pk{ltxdoc} where the file parts
% have their titlepages with only the filename and \pk{article}-like titles
% made by |\maketitle|.
%
% But we will also provide a~possibility of typesetting multiple files
% exactly like with the \pk{ltxdoc} class.
%
% \begin{macro}{\DocInclude}
%
%   So, define the |\DocInclude| command, that acts
%   \begin{quotation}more or less exactly the same as |\include|, but
%     uses |\DocInput| on a \pk{dtx} [or \pk{.fdd}] file, not |\input| on
%     a \pk{tex} file.\end{quotation}
%   Our version will accept also \pk{.sty}, \pk{.cls}, and \pk{.tex}
%   files.
%
% \changes{v0.98}{06/09/05}{\cs{@makeother\protect\bslash_} added}
\newcommand*\DocInclude{\bgroup\@makeother\_\Doc@Include}% First, we
% make \inverb|_| `other' in order to allow it in the filenames.

\newcommand*{\Doc@Include}[2][]{% originally it took just one
  % argument. Here we make it take two, first of which is intended to
  % be the path (with the closing \inverb |/|). This is intended not to print
  % the path in the page footers only the filename.\par
  % \CodeUsage\HLPrefix
  \egroup% having the arguments read, we close the group opened by the
  % previous macro for |_|\catother.
  \gdef\HLPrefix{\filesep}% 
  \gdef\EntryPrefix{\filesep}% we define two rather kernel parameters
  % to expand to the file marker. The first will bring the information
  % to one of the default \inverb|\IndexPrologue|'s
  % |\if|s. Therefore the 
  % definition is global. The latter is such for symmetry.
  \def\GeneralName{#2\actualchar\pk{#2} }% \label{GeneralName} for the
    % changes'history main level entry.
    % 
    % Now we check whether we try to include ourselves and if
    % so---we'll (create and) read an \file{.auxx} file instead of
    % (the main) \file{.aux} to avoid an infinite recursion of |\input|s.
    % 
    \edef\gmd@jobname{\jobname}%
    \edef\gmd@difilename{% we want the filename all `other', just as
      % in \inverb|\jobname|.
      \@xa\@xa\@xa\@gobble\@xa\string\csname#2\endcsname}%
    \ifx\gmd@jobname\gmd@difilename
      \def\gmd@auxext{auxx}%
    \else
      \def\gmd@auxext{aux}%
    \fi
  \relax
  %^^A\if@ltxDocInclude
  \clearpage
  % ^^A\fi
  \gmd@docincludeaux
  \def\currentfile{gmdoc-IncludeFileNotFound.000}%
  \let\fullcurrentfile\currentfile
  \IfFileExists{#1#2.fdd}{\edef\currentfile{#2.fdd}}{% it's not \pk{.fdd},
    \IfFileExists{#1#2.dtx}{\edef\currentfile{#2.dtx}}{% it's not \pk{.dtx}
      % either,
      \IfFileExists{#1#2.sty}{\edef\currentfile{#2.sty}}{% it's not
        % \pk{.sty},
        \IfFileExists{#1#2.cls}{\edef\currentfile{#2.cls}}{% it's
            % not \pk{.cls},
          \IfFileExists{#1#2.tex}{\edef\currentfile{#2.tex}}{% it's
            % not \pk{.tex},
            \IfFileExists{#1#2.fd}{\edef\currentfile{#2.fd}}{% so it
            % must be \pk{.fd} or error.
              \PackageError{gmdoc}{\string\DocInclude\space file
                #1#2.fdd/dtx/sty/cls/tex/fd not found.}}}}}}}%
  % \changes{v0.98j}{06/10/16}{\pk{.fdd} added in \cs{DocInclude}'s
  % search for the extension.}
  \edef\fullcurrentfile{#1\currentfile}%
  \ifnum\@auxout=\@partaux
    \@latexerr{\string\DocInclude\space cannot be nested}\@eha
  \else \@docinclude{#1}#2 \fi}% Why is |#2| delimited with | | not
% braced as we are used to, one may ask. 

% \changes[\DocInclude]{v0.97}{06/09/03}{\cs{@docinclude} gets 2 params
%   in order to \cs{includeonly} work as expected, with only the names
%   (w.o. the paths)}
\def\@docinclude#1#2 {% To match the macro's parameter string, is an
  % answer. But why is |\@docinclude| defined so? Originally, in
  % \pk{ltxdoc} it takes one argument and it's delimited with a~space
  % probably in resemblance to the true |\input| \nlpercent(|\@@input| in
  % \LaTeX). ^^A\if@ltxDocInclude
  \clearpage
  %^^A\fi
  \if@filesw \gmd@writemauxinpaux{#2.\gmd@auxext}\fi% this strange macro with
  % a~long name is another thing to allow |_| in the filenames (see
  % line \ref{gmd@writemauxinpaux}).
  \@tempswatrue
  \if@partsw \@tempswafalse\edef\gmu@tempb{#2}%
    \@for \gmu@tempa:=\@partlist\do{\ifx\gmu@tempa\gmu@tempb\@tempswatrue\fi}%
  \fi
  \if@tempswa \let\@auxout\@partaux 
    \if@filesw
      \immediate\openout\@partaux #2.\gmd@auxext\relax% Yes, only |#2|. It's to
      % create and process the partial \pk{.aux(x)} files always in the main
      % document's (driver's) directory.
      % \changes[\DocInclude]{v0.97}{06/09/04}{\protect\TeX forced to
      %   process the partial \pk{.aux}es in the main document directory}
      \immediate\write\@partaux{\relax}%
    \fi
    % \begin{quotation}We need to save (and later restore) various
    %   index-related commands which might be changed by the included
    %   file.\end{quotation}
    % \changes{v0.98a}{06/09/06}{\cs{MacroStoringDo} renamed (in
    %   \pk{gmutils}) to \cs{StoringAndRelaxingDo}, and
    %   \cs{MacroRestoringDo} to \cs{RestoringDo}.}
    \StoringAndRelaxingDo\gmd@doIndexRelated
    \if@ltxDocInclude\part{\currentfile}% In the \pk{ltxdoc}-like setup
    % we make a~part title page with only the filename and the file's
    % |\maketitle| will typeset an \pk{article}-like title.
    \else\let\maketitle=\InclMaketitle
    \fi% In the default setup we
    % redefine |\maketitle| to typeset a~common chapter or part heading.
    \if@ltxDocInclude\xdef@filekey\fi
    \GetFileInfo{\currentfile}% it's my (GM) addition with the account
    % of using file info in the included files' title/\:heading etc.
    \incl@DocInput{\fullcurrentfile}% originally just |\currentfile|.
    \if@ltxDocInclude\else\xdef@filekey\fi% in the default case we add
    % new file to the file key \emph{after} the input because in this
    % case it's the files own |\maketitle| what launches the
    % sectioning command that increases the counter.
    % \par And here is the moment to restore the index-related
    % commands.
    \RestoringDo\gmd@doIndexRelated
    % ^^A\if@ltxDocInclude
    \clearpage
    % ^^A\fi
    \gmd@writeckpt{#1#2}%
    \if@filesw \immediate\closeout\@partaux \fi
  \else\@nameuse{cp@#1#2}%
  \fi
  \let\@auxout\@mainaux}% end of |\@docinclude|.
% \end{macro}
%
% (Two is a~sufficient number of iterations to define a~macro for.)
\def\xdef@filekey{{\@relaxen\ttfamily% \label{LetTTFRelax}This
    % assignment is very trickly crafted: it makes \emph{all}
    % |\ttfamily|s present in the |\filekey|'s expansion unexpandable
    % not only the one added in this step.
    \xdef\filekey{\filekey, \thefilediv={\ttfamily\currentfile}}}}


% To allow |_| in the filenames we must assure |_| will be \catother\
% while reading the filename. Therefore define
% \DefIndex\gmd@writemauxinpaux
\def\gmd@writemauxinpaux#1{% \label{gmd@writemauxinpaux}
  % this name comes from `\emph{write} outto \emph main
  % \emph{\pk{.aux}} to \emph{in}put \emph partial
  % \emph{\pk{.aux}}'.\par 
  % We wrap |\@input{|\<partial \pk{.aux}>|}| in a~|_|\catother\
  % hacked scope. This hack is especially recommended here since the
  % \pk{.aux} file may contain a~non-|\global| stuff that should not
  % be localized by a~group that we would have to establish if we
  % didn't use the hack. (Hope you understand it. If not, notify me
  % and for now I'll only give a~hint: ``Look at it with the \TeX's
  % eyes''. More uses of this hack are to be seen in \pk{gmutils}
  % where they are a~bit more explained.)
  \immediate\write\@mainaux{%
    \bgroup\string\@makeother\string\_%
    \string\firstofone{\egroup
    \string\@input{#1}}}}

% We also slightly modify a~\LaTeX\ kernel macro |\@writeckpt| to
% allow |_| in the file name.
% \changes[\DocInclude]{v0.98a}{06/09/06}{\cs{@writeckpt} wrapped
% with \cs{firstofone} hack to allow \cs[]{_} in the file names.}
% \DefIndex\gmd@writeckpt
\def\gmd@writeckpt#1{%
  \immediate\write\@partaux{%
    \string\bgroup\string\@makeother\string\_%
    \string\firstofone\@charlb\string\egroup}
  \@writeckpt{#1}%
  \immediate\write\@partaux{\@charrb}}

\def\gmd@doIndexRelated{%
  \do\tableofcontents \do\makeindex \do\EnableCrossrefs
  \do\PrintIndex \do\printindex \do\RecordChanges \do\PrintChanges
  \do\theglossary \do\endtheglossary}


\@emptify\filesep
% The \pk{ltxdoc} class establishes a~special number format for
% multiple file documentation numbering needed to document the \LaTeX\
% sources. I~like it too, so
\def\aalph#1{\@aalph{\csname c@#1\endcsname}}
\def\@aalph#1{%
  \ifcase#1\or a\or b\or c\or d\or e\or f\or g\or h\or i\or
         j\or k\or l\or m\or n\or o\or p\or q\or r\or s\or
         t\or u\or v\or w\or x\or y\or z\or A\or B\or C\or
         D\or E\or F\or G\or H\or I\or J\or K\or L\or M\or
         N\or O\or P\or Q\or R\or S\or T\or U\or V\or W\or
         X\or Y\or Z\else\@ctrerr\fi}

% A~macro that initialises things for |\DocInclude|.
\def\gmd@docincludeaux{%
  % We set the things for including the files only once.
  \global\@relaxen\gmd@docincludeaux
  % By default, we will include multiple files into one document
  % as chapters in the classes that provide |\chapter| and as parts
  % elsewhere.
  \ifx\filediv\relax
    \ifx\filedivname\relax% (nor |\filediv| neither
    % |\filedivname| is defined by the user)
    % \changes[\filediv]{v0.98a}{06/09/06}{definition moved into
    % \cs{DocInclude} and let \cs{relax} by default ($\quotechar=$a~bug fix).}
      \@ifundefined{chapter}{%
        \SetFileDiv{part}}%\changes[\DocInclude]{v0.98f}{06/9/29}{\cs{filediv(name)}  
      % defined as \cs[]{(\protect\bslash)part} for the classes that
      % don't know \cs{chapter}} 
      {\SetFileDiv{chapter}}%
    \else% (|\filedivname| is defined by the user, |\filediv| is not)
      \SetFileDiv{\filedivname}% why not? Inside is |\edef| so it'll work.
    \fi
  \else% (|\filediv| is defined by the user
    \ifx\filedivname\relax% and |\filedivname| is not)
    %^^A~I~deleted a~six level test which one sectioning command
    %^^A~|\filedivname| isx. 
      \PackageError{gmdoc}{You've redefined \string\filediv\space
        without redefining \string\filedivname.}{Please redefine the
        two macros accordingly. You may use \string\SetFileDiv{name
          without bslash}.}%
    \fi
  \fi
  % \changes[\DocInclude]{v0.99m}{2008/08/09}{
  %   resetting of codeline number with every
  % \cs{filedivname} commented out because with the
  % \env{countalllines} option it caused that reset at \cs{maketitle}
  % after some lines of file}
  % ^^A  \@addtoreset{codelinenum}{\filedivname}% remember it has
  % ^^A~a~|\global| effect in fact. For each file we'll reset
  % ^^A~\env{codelinenum}.
  \def\thefilediv{\aalph{\filedivname}}% The files will be numbered
  % with letters, lowercase first.
  \@xa\let\csname the\filedivname\endcsname=\thefilediv% This
  % li\-ne lets |\the|\<chapter> etc.\ equal |\thefilediv|.
  \def\filesep{\thefilediv-}% File separator (identifier) for the index.
  \let\filekey=\@gobble
  \g@addto@macro\index@prologue{%
    \gdef\@oddfoot{\parbox{\textwidth}{\strut\footnotesize
        \raggedright{\bfseries File Key:} \filekey}}% The footer for
    % the pages of index.
    \glet\@evenfoot\@oddfoot}% \label{oneside}anyway, it's intended to
  % be oneside. 
  \g@addto@macro\glossary@prologue{%
    \gdef\@oddfoot{\strut Change History\hfill\thepage}% The footer
    % for the changes history.
    \glet\@evenfoot\@oddfoot}%
  % \changes[\DocInclude]{v0.98c}{06/9/10}{Change History footer
  % defined}
  \gdef\@oddfoot{% The footer of the file pages will be its name and,
    % if there is a~file info, also the date and version.
    \@xa\ifx\csname ver@\currentfile\endcsname\relax
      File \thefilediv: {\ttfamily\currentfile} %
    \else
      \GetFileInfo{\currentfile}%
      File \thefilediv: {\ttfamily\filename} %
      Date: \filedate\ %
      Version \fileversion
    \fi
    \hfill\thepage}%
  \glet\@evenfoot\@oddfoot% see line \ref{oneside}.
  % ^^A  \show\filedivname% for debug
  \@xa\def\csname\filedivname name\endcsname{File}% we
  % redefine the name of the proper division to `File'.
  \ifx\filediv\section
    \let\division=\subsection
    \let\subdivision=\subsubsection
    \let\subsubdivision=\paragraph
    % If |\filediv| is higher than
    % |\section| we don't change the three divisions (they are
    % |\section|, |\subsection| and |\subsubsection| by default).
    % |\section| seems to me the lowest reasonable sectioning command
    % for the file. If |\filediv| is lower you should rather rethink
    % the level of a~file in your documentation not redefine the two
    % divisions.
  \fi}% end of |\gmd@docincludeaux|.

% The |\filediv| and |\filedivname| macros should always be set
% together. Therefore provide a~macro that takes care of both at
% once. Its |#1| should be a~sectioning name without the backslash.
\def\SetFileDiv#1{%
  \edef\filedivname{#1}%
  \@xa\let\@xa\filediv\csname#1\endcsname}
% \changes{v0.98c}{06/9/10}{added and a~bug fixed in \cs{docincludeaux}}


\def\SelfInclude{\DocInclude{\jobname}}
% \changes{v0.98a}{06/09/06}{added in response to the needs of the
% first user, of me that is}
% \changes{v0.99l}{2008/08/05}{Made a~shorthand for
% \cs{Docinclude}\cs{jobname} instead of repeating 99\% of
% \cs{DocInclude}'s code}

% The \pk{ltxdoc} class makes some preparations for inputting multiple
% files. We are not sure if the user wishes to use \pk{ltxdoc}-like
% way of documenting (maybe \heshe\ will prefer what I~offer,
% \pk{gmdocc.cls} e.g.), so we put
% those preparations into a~declaration.
%
\newif\if@ltxDocInclude

\newcommand*\ltxLookSetup{%
  \SetFileDiv{part}%
  \ltxPageLayout
  \@ltxDocIncludetrue
}

\@onlypreamble\ltxLookSetup

% The default is that we |\DocInclude| the files due to the original
% \gmdoc\ input settings.
\let\incl@DocInput=\DocInput

\@emptify\currentfile% for the pages outside the
% |\DocInclude|'s scope. In force for all includes.
%
%^^A  \iffalse
%^^A  % \stanza
%^^A  % But it may be not a~usual situation to include the source files
%^^A  % as with \pk{ltxdoc} but with the \emph{new} |\DocInput| macro. So
%^^A  % let's |\def|
%^^A  % \Define\ltxMultidocOldSetup
%^^A  \newcommand*\ltxMultidocOldSetup{%
%^^A    \ltxMultidocSetup
%^^A    \let\incl@DocInput=\OldDocInput}
%^^A 
%^^A  \@onlypreamble\ltxMultidocOldSetup
%^^A 
%^^A  And, for the symmetry, if you prefer the look offered by
%^^A  me, but 
%^^A  \fi

% If you want to |\Doc/SelfInclude| \docfm-likes:
\newcommand*\olddocIncludes{%
  \let\incl@DocInput=\OldDocInput}

% And, if you have set the previous and want to set it back:
\newcommand*\gmdocIncludes{%
  \let\incl@DocInput=\DocInput
  \AtBegInput{\QueerEOL}}% to move back the |\StraightEOL| declaration put
% at begin input by |\olddocIncludes|.
%
%
% \subdivision{Redefinition of \cs{maketitle}}
%
% A~not-so-slight alteration of the \TextUsage\maketitle\ command in
% order it allow multiple titles in one document seems to me very
% clever. So let's copy again (\pk{ltxdoc.dtx} the lines 643--656):
%
% \begin{quotation}The macro to generate titles is easily altered in
% order that it can be used more than once (an article with many
% titles). In the original, diverse macros were concealed 
% after use with |\relax|. We must cancel anything that may have been
% put into |\@thanks|, etc., otherwise all titles will carry forward
% any earlier such setting!\end{quotation} 
% But here in \pk{gmdoc} we'll do it locally for (each) input 
% not to change the main title settings if there are any.
\AtBegInput{%^^A~ why provide not just \cs{def}?
  \providecommand*\maketitle{\par
    \begingroup \def \thefootnote {\fnsymbol {footnote}}%
    \setcounter {footnote}\z@
    \def\@makefnmark{\hbox to\z@{$\m@th^{\@thefnmark}$\hss}}%
    \long\def\@makefntext##1{\parindent 1em\noindent
      \hbox to1.8em{\hss$\m@th^{\@thefnmark}$}##1}%
    \if@twocolumn \twocolumn [\@maketitle ]%
    \else \newpage \global \@topnum \z@ \@maketitle \fi
% \begin{quotation}For special formatting requirements (such as in
% \acro{TUG}boat), we use pagestyle |titlepage| for this; this is later defined
% to be |plain|, unless already defined, as, for example, by
% \pk{ltugboat.sty}.\end{quotation}
    \thispagestyle{titlepage}\@thanks \endgroup 
%\begin{quotation}If the driver file
% documents many files, we don't want parts of a title of one to
% propagate to the next, so we have to cancel these:\end{quotation}
    \setcounter {footnote}\z@
    \gdef\@date{\today}\g@emptify\@thanks%
    \g@emptify\@author\g@emptify\@title%
  }%\par
  % \begin{quotation}When a number of articles are concatenated into
  % a~journal, for example, it is not usual for the title pages of
  % such documents to be formatted differently. Therefore, a class
  % such as \pk{ltugboat} can define this macro in advance. However,
  % if no such definition exists, we use pagestyle plain for title
  % pages.\end{quotation}
  \@ifundefined{ps@titlepage}{\let\ps@titlepage=\ps@plain}{}%
  % \par And let's provide |\@maketitle| just in case:  an error occurred
  % without it at \TeX ing with \pk{mwbk.cls} because this class with the
  % default options does not define |\@maketitle|. The below definitions
  % are taken from \pk{report.cls} and \pk{mwrep.cls}.
  \providecommand*\@maketitle{%
    \newpage\null \vskip 2em\relax%
    \begin{center}%
      \titlesetup
      \let \footnote \thanks
      {\LARGE \@title \par}%
      \vskip 1.5em%
      {\large \lineskip .5em%
        \begin{tabular}[t]{c}%
          \strut \@author
        \end{tabular}\par}%
      \vskip 1em%
      {\large \@date}%
    \end{center}%
    \par \vskip 1.5em\relax}%\par
  % We'd better restore the primary meanings of the macros making
  % a~title. (\LaTeXe\ source, File F: ltsect.dtx Date: 1996/12/20 Version
  % v1.0z, lines 3.5.7.9--12.14--17.)
  \providecommand*\title[1]{\gdef\@title{#1}}
  \providecommand*\author[1]{\gdef\@author{#1}}
  \providecommand*\date[1]{\gdef\@date{#1}}
  \providecommand*\thanks[1]{\footnotemark
    \protected@xdef\@thanks{\@thanks
      \protect\footnotetext[\the\c@footnote]{#1}}%
  }%
  \providecommand*\and{%| % \begin{tabular}|
    \end{tabular}%
    \hskip 1em \@plus.17fil%
    \begin{tabular}[t]{c}}%| % \end{tabular}|
    % And finally, let's initialize \cs{tit\+le\+set\+up} if it is not yet.
    \providecommand*\titlesetup{}%
}% end of |\AtBegInput|.
%
% \changes[\titlesetup]{v0.98c}{06/09/08}{\cs{provide}d \cs[]{\{\}}}
%
%
% The \pk{ltxdoc} class redefines the |\maketitle| command to allow
% multiple titles in one document. We'll do the same and something
% more: our |\Doc/SelfInclude| will turn the file's |\maketitle| into
% a~part or chapter heading. But, if hte |\ltxLookSetup| declaration
% is in force, |\Doc/SelfInclude| will make for an included file
% a~part's title page and an \pk{article}-like title.
%
% \stanza
% Let's initialize the file division macros.
\@relaxen\filediv
\@relaxen\filedivname
\@relaxen\thefilediv
% \changes[\thefilediv]{v0.99m}{2008/08/06}{let to \cs{relax} by
% default} 

% If we don't include files the \pk{ltxdoc}-like way, we wish to
% redefine |\maketitle| so that it typesets a~division's heading.
%

% Now, we redefine |\maketitle| and its relatives.
%
\def\InclMaketitle{%
  % \changes{v0.98a}{06/09/05}{renamed from \cs{incl@maketitle} because
  %   I~needed it in self-input hacks.}
  {\def\and{, }% we make |\and| just a~comma.
    {\let\thanks=\@gobble% for the toc version of the heading we
      % discard |\thanks|.
      \protected@xdef\incl@titletotoc{\@title\if@fshda\protect\space
        (\@author)\fi}% we add the author iff the `files have
      % different authors' \nlpercent(|@fshda|)
    }% 
    \def\thanks##1{\footnotemark
      \protected@xdef\@thanks{\@thanks% to keep the previous |\thanks|
        % if there were any.
        \protect\footnotetext[\the\c@footnote]{##1}}}% for some
    % mysterious reasons so defined |\thanks| do typeset the footnote
    % mark and text but they don't hyperlink it
    % properly. A~\pk{hyperref} bug?
    \@emptify\@thanks
    \protected@xdef\incl@filedivtitle{%
      [{\incl@titletotoc}]% braces to allow |[| and
      % |]| in the title to toc.
      {\protect\@title
        {\smallerr% this macro is provided by the \pk{gmutils}
          % package after the \pk{relsize} package.
          \if@fshda\\[0.15em]\protect\@author
            \if\relax\@date\relax\else, \fi
          \else
            \if\relax\@date\relax\else\\[0.15em]\fi
          \fi
          % The default is that all the included files have the same
          % author(s). In this case we won't print the author(s) in
          % the headings. Otherwise we wish to print them.  The
          % information which case are we in is brought by the
          % |\if@fshda| switch defined in line \ref{@fshda}.
% 
%  If we wish to print the author's name
% (|\if@fshda|), then we'll print the date after the author, separated
% with a~comma. If we don't print the author, there still may be
% a~date to be printed. In such a~case we break the line, too, and
% print the date with no comma.
          \protect\@date}}% end of |\incl@filedivtitle|'s brace (2nd
      % or 3rd argument).
    }% end of |\incl@filedivtitle|'s |\protected@xdef|.\par
    % We |\protect| all the title components to avoid expanding
    % |\footnotemark| hidden in |\thanks| during  |\protected@xdef|
    % (and to let it be executed during the typesetting, of course).
    }% end of the comma-|\and|'s group.
    \@xa\filediv\incl@filedivtitle
    \@thanks
    \g@relaxen\@author \g@relaxen\@title \g@relaxen\@date
    \g@emptify\@thanks
}% end of |\InclMaketitle|.

% What I~make the default, is an assumption that all the
% multi-documented files have the same author(s). 
% And with the account of the other possibility I~provide
% the below switch and declaration.


\newif\if@fshda
% \label{@fshda} (its name comes from \textit file\textit s
% \textit have \textit different \textit authors).

\newcommand*\PrintFilesAuthors{\@fshdatrue}
% And the counterpart, if you change your mind:
\newcommand*\SkipFilesAuthors{\@fshdafalse}


% \subdivision{The file's date and version information}


% Define |\filedate| and friends from info in the
% |\ProvidesPackage| etc.\ commands.
\def\GetFileInfo#1{%
  \def\filename{#1}%
  \def\gmu@tempb##1 ##2 ##3\relax##4\relax{%
    \def\filedate{##1}%
    \def\fileversion{##2}%
    \def\fileinfo{##3}}%
  \edef\gmu@tempa{\csname ver@#1\endcsname}%
  \@xa\gmu@tempb\gmu@tempa\relax? ? \relax\relax}

% Since we may documentally input files that we don't load, as \docfm\
% e.g., let's define a~declaration to be put (in the comment layer)
% before the line(s) containing |\Provides...|. The |\FileInfo|
% command takes the stuff till the closing |]| and subsequent line
% end, extracts from it the info and writes it to the \file{.aux} and
% rescans the stuff. \eTeX\ provides a~special primitive for that
% action but we remain strictly \TeX nical and do it with writing to
% a~file and inputting that file.

\newcommand*\FileInfo{%
  \bgroup
  \gmd@ctallsetup
  \bgroup% yes, we open two groups because we want to rescan tokens in
  % `usual' catcodes. We cannot put \incs{gmd@ctallsetup} into the
  % inner macro because when that will be executed, the
  % \incs{inputlineno} will be too large (the last not the first line).
  \let\do\@makeother
  \do\ \do\{\do\}\do\^^M\do\\%
  \gmd@fileinfo}
% \changes{v0.99d}{2007/04/26}{added}

\foone{%
  \catcode`!\z@
  \catcode`(\@ne
  \catcode`)\tw@
  \let\do\@makeother
  \do\ % we make space `other' to keep it for scanning the code where
  % it may be leading.
  \do\{\do\}\do\^^M\do\\}%\CodeEscapeChar\!
(%
!def!gmd@fileinfo#1Provides#2{#3}#4[#5]#6^^M%
(!egroup% we close the group of changed catcodes, the catcodes
% of the arguments are set. And we are still in the group for
% \incs{gmd@ctallsetup}. 
!gmd@writeFI(#2)(#3)(#5)%
!gmd@FIrescan(#1Provides#2{#3}#4[#5]#6)% this macro will close the group.
%\changes[\FileInfo]{v0.99m}{2008/08/09}{\cs{egroup} of the
% inner macro moved to the end to allow \cs{gmd@ctallsetup}. From the
% material passed to \cs{gmd@FIrescan} ending \hathat{M} stripped not
% to cause double labels.}
)% \CodeEscapeChar\\
)

\def\gmd@writeFI#1#2#3{%
  % ^^A  \typeout{@@@ write FI}\show\relax
  \immediate\write\@auxout{%
    \global\@nx\@namedef{%
      ver@#2.\if P\@firstofmany#1\@@nil sty\else cls\fi}{#3}}}

\foone\obeylines{%
  \def\gmd@FIrescan#1{%
 % \changes{v0.99l}{2008/08/06}{\cs{scantokens} used instead of
 %   \cs{write} and \cs{@@input} which simplified the macro}
 % ^^A  \newwrite\gmd@docrescanfile
 % ^^A  \immediate\openout\gmd@docrescanfile=\jobname.docrescan\relax
 {\newlinechar=`\^^M\scantokens{#1}}\egroup^^M}}


% And, for the case the input file doesn't contain |\Provides...|,
% a~macro for explicit providing the file 
% info. It's written in analogy to |\ProvidesFile|, \pk{source ^^B
% 2${}_\epsilon$}, file L v1.1g, l.\,102.

\def\ProvideFileInfo#1{%
  \begingroup
    \catcode`\ 10 \catcode\endlinechar 10 %
    \@makeother\/\@makeother\&%
    \kernel@ifnextchar[{\gmd@providefii{#1}}{\gmd@providefii{#1}[]}%^^A]
  }
% \changes{v0.98a}{06/09/06}{added}

  % \DefIndex\gmd@providefii
\def\gmd@providefii#1[#2]{%\\
  % (we \emph{don't} write the file info to \pk{.log})
  \@xa\xdef\csname ver@#1\endcsname{#2}%
  \endgroup}

% And a~self-reference abbreviation (intended for providing file info
% for the driver):
\def\ProvideSelfInfo{\ProvideFileInfo{\jobname.tex}}

% A~neat conventional statement used in \docfm's documentation e.g.,
% to be put in |\thanks| to the title or in a~footnote:
\newcommand*\filenote{This file has version number \fileversion{} dated \filedate{}.}
% And exactly as  |\thanks|:
\newcommand*\thfileinfo{\thanks\filenote}


%
%
% \subdivision{Miscellanea}
%
% The main inputting macro, |\DocInput| has been provided. But there's
% another one in \docfm\ and it looks very reasonably:
% \gmhypertarget[IndexInput]{\cs{IndexInput}}. Let's make analogous one
% here:
\foone{\obeylines}%
{%
  \def\IndexInput#1{% \changes{v0.98b}{06/09/07}{\cs{StoreMacro}ing
    %% and \cs{RestoreMacro}ing
    % \cs{code@delim} added}
    \StoreMacro\code@delim%
    \CodeDelim\^^Z%
    \def\gmd@iihook{% \label{iihook}this hook is |\edef|ed!
      \@nx^^M%
      \code@delim\relax\@nx\let\@nx\EOFMark\relax}%^^A\@nx^^M
    \DocInput{#1}\RestoreMacro\code@delim}%
}
% How does it work? We assume in the input file is no explicit 
% \<char1>. This char is chosen as the code delimiter and will be put
% at the end of input. So, entire file contents will be scanned char
% by char as the code.
% \stanza
%
% \skiplines First I~tried to use \specialcomment{gmlonely} provided by
% the \pk{comment} package, but it caused errors.\endskiplines
%
% The below environment I~designed to be able to skip some repeating
% texts while documenting several packages of mine into one
% document. At the default settings it's just a~|\StraightEOL| group
% and in the |\skipgmlonely| declaration's scope it gobbles its
% contents.
%
\newenvironment{gmlonely}{\StraightEOL}{}

\newcommand\skipgmlonely[1][]{%
  \def\gmu@tempa{%\DefIndex\gmd@skipgmltext
    \def\gmd@skipgmltext{%
      \g@emptify\gmd@skipgmltext
      % ^^A      \gmd@deeolize{
      #1%^^A}
    }}% not to count the lines of the substituting
  % text but only of the text omitted
  \gmu@tempa
  \@xa\AtBegInput\@xa{\gmu@tempa}%
  \renewenvironment{gmlonely}{%
    \StraightEOL
    \@fileswfalse% to forbid writing to \pk{.toc}, \pk{.idx} etc.
    \setbox0=\vbox\bgroup}{\egroup\gmd@skipgmltext}}

% Sometimes in the commentary of this package, so maybe also others,
% I~need to say some char is of category 12 (`other sign'). This I'll
% mark just as \catother\ got by |\catother|.
%

\foone{\catcode`\_=8 }% we ensure the standard |\catcode| of |_|.
{
  \newcommand*\catother{${}_{12}$}%\par
  % Similarly, if we need to say some char is of category 13 (`active'),
  % we'll write \catactive, got by |\catactive|
  \newcommand*\catactive{${}_{13}$}%\par
  % and a~letter, \catletter
  \newcommand*\catletter{${}_{11}$}%.
}
%
% For the copyright note first I~used just \env{verse} but it requires
% marking the line ends with |\\| and indents its contents while
% I~prefer the copyright note to be flushed left. So
\newenvironment*{copyrnote}{%
  \StraightEOL\everypar{\hangindent3em\relax\hangafter1 }%
  \par\addvspace\medskipamount\parindent\z@\obeylines}{%
  \@codeskipputgfalse\stanza}
%
% I~renew the \env{quotation} environment to make the fact of quoting
% visible. 
\StoreEnvironment{quotation}
\def\gmd@quotationname{quotation}
\renewenvironment{quotation}{%
  % \changes{v0.99j}{2008/08/03}{Improved behaviour of redefined
  %   \env{quotation} to be the original if used by another environment.}
  % The first non-me user complained that \env{abstract} comes out in
  % quotation marks. That is because \env{abstract} uses \env{quotation}
  % internally. So we first check whether the current environment is
  % \env{quotation} or something else.
  \ifx\@currenvir\gmd@quotationname
  \afterfi{\par``\ignorespaces}%
  \else\afterfi{\storedcsname{quotation}}%
  \fi}
{\ifx\@currenvir\gmd@quotationname
  \afterfi{\ifhmode\unskip\fi''\par}%
  \else\afterfi{\storedcsname{endquotation}}%
  \fi}

% \chunkskip
% For some mysterious reasons |\noindent| doesn't work with the first
% (narrative) paragraph after the code so let's work it around:
\def\gmdnoindent{%
  \ifvmode\leavevmode\hskip-\parindent\ignorespaces
  \fi}% \incs{ignorespaces} is added to eat a~space inserted% by
% \incs{gmd@textEOL}. Without  
% it it% also worked but it was a~bug: since% \incs{parindent} is
% a~dimen not% skip, \TeX\ looks forward and % expands macros to check
% whether% there is a~stretch or shrink part%% and therefore it
% gobbled the% \incs{gmd@textEOL}'s space.
%
% When a~verbatim text occurs in an inline comment, it's advisable to
% precede it with |%| if it begins a~not first line of such a~comment
% not to mistake it for a~part of code. Moreover, if such a~short verb
% breaks in its middle, it should break with the percent at the
% beginning of the new line. For this purpose provide 
\newcommand*\inverb{%
  % \changes{v0.99g}{2007/11/12}{added}
  \@ifstar{%
    \def\gmu@tempa{{\tt\xiipercent}}%
    \@emptify\gmu@tempb% here and in the paralell points of the other
    % case and \inverb|\nlpercent| I~considered an \inverb|\ifhmode|
    % test but it's not possible to be in vertical mode while in an
    % inline comment. If there happens vertical mode, the commentary
    % begins to be `outline' (main text).
    \gmd@inverb}%
  {\@emptify\gmu@tempa
    \def\gmu@tempb{\gmboxedspace}%
    \gmd@inverb}}

\newcommand*\gmboxedspace{\hbox{\normalfont{ }}}

\newcommand*\gmd@nlperc[1][]{% \changes{v0.99n}{2008/08/22}{% added
  % \cs{hbox}es in \cs{discretionary} to score \cs{hyphenpenalty} not
  % \cs{exhyphenpenalty}}
  \ifhmode\unskip\fi
  \discretionary{\hbox{\gmu@tempa}}% (pre-break).  I~always put
  % a~\incs{hbox} here to make this discretionary score the
  % \incs{hyphenpenalty} not \incs{exhyphenpenalty} (\TB\ p.~96) since
  % the latter may be 10,000 in Polish typesetting.
  {{\tt\xiipercent\gmboxedspace}}% (post-break)
  {\gmu@tempb}% (no-break).
  \penalty10000\hskip0sp\relax}

\newcommand*\gmd@inverb[1][]{%
  \gmd@nlperc
  \ifmmode\hbox\else\leavevmode\null\fi
  \bgroup
  \ttverbatim
  \def\breakablevisspace{%
    \discretionary{\visiblespace}{\xiipercent\gmboxedspace}{\visiblespace}}%
  \def\breakbslash{%
    \discretionary{}{\xiipercent\gmboxedspace\bslash}{\bslash}}%
  \def\breaklbrace{%
    \discretionary
      {\xiilbrace\verbhyphen}%
      {\xiipercent\gmboxedspace}%
      {\xiilbrace}}%
  \gm@verb@eol
  %^^A  \@ifstar {\@sverb@chbsl}
  %^^A~ {\gmobeyspaces\frenchspacing\@sverb@chbsl}
  \@sverb@chbsl% It's always with visible spaces.
}

\newcommand*\nlpercent{%
  \@ifstar{\def\gmu@tempa{{\tt\xiipercent}}%
    \@emptify\gmu@tempb
    \gmd@nlperc}%
  {\@emptify\gmu@tempa
    \def\gmu@tempb{\gmboxedspace}%
    \gmd@nlperc}}

\newcommand*\incs{% an inline \cs{cs}
  % \changes{v0.99m}{008/08/07}{added}
  \@ifstar{\def\gmu@tempa{{\tt\xiipercent}}%
    \@emptify\gmu@tempb
    \gmd@nlperc\cs}%
  {\@emptify\gmu@tempa
    \def\gmu@tempb{\gmboxedspace}%
    \gmd@nlperc\cs}}

\def\inenv{\incs[]}% an in-line \cs{env}



% As you see, |\inverb| and |\nlpercent| insert a~discretionary that
% breaks to |%|
% at the beginning of the lower line. Without the break it's a~space
% (alas at its natural width i.e., not flexible) or, with the starred
% version, nothing. The starred version puts |%| also at the end of
% the upper line. Then |\inverb| starts sth. like
% |\verb*| but the breakables of it break to |%| in the
% lower line.
%
% \acro{TODO}: make the space flexible (most probably it requires using sth.\
% else than |\discretionary|).
%\stanza
%
% An optional hyphen for \CSs in the inline comment:
\@ifundefined{+}{}{\typeout{^^Jgmdoc.sty: redefining \bslash+.}}
\def\+{\discre{{\normalfont-}}{{\tt\xiipercent\gmboxedspace}}{}}
%
%

\providecommand*\ds{DocStrip}

% A~shorthand for |\CS|:
\pdef\CS{% \changes{v0.99n}{2008/08/30}{added}
  \acro{CS}%
  \@ifnextcat a{ }{}}% we put a~space if the next token is
% \catletter. It's the next best thing to checking whether the \CS
% consisting of letters is followed by a~space.

\pdef\CSs{\CS{}es\@ifnextcat a{ }{}}% for pluralis.
% \changes{v0.99n}{2008/08/30}{added}
\pdef\CSes{\CS{}es\@ifnextcat a{ }{}}% for pluralis.
% \changes{v0.99n}{2008/08/30}{added}


% \gmhypertarget[CDAnd]{Finally,} a~couple of macros for documenting
% files playing with |%|'s
% catcode(s). Instead of |%| I~used |&|. They may be at the end
% because they're used in the commented thread i.e.\ after package's
% |\usepackage|.  
\newcommand*\CDAnd{\CodeDelim\&}

\newcommand*\CDPerc{\CodeDelim*\%}

% And for documenting in general:
%
% A~general sectioning command because I~foresee a~possibility of
% typesetting the same file once as independent document and another
% time as a~part of bigger whole.
% \Define\division
\let\division=\section

% \Define\subdivision
\let\subdivision=\subsection

% \Define\subsubdivision
\let\subsubdivision=\subsubsection
%
%
% \stanza
% To kill a~tiny little bug in \file{doc.dtx} (in line 3299 |\gmu@tempb| and
% |\gmu@tempc| are written plain not verbatim):
\newcounter{gmd@mc}

% Note it is after the \env{macrocode} group
\def\gmd@mchook{\stepcounter{gmd@mc}% \label{gmd@mchook}
  \gmd@mcdiag
  \ifcsname gmd@mchook\the\c@gmd@mc\endcsname
  \afterfi{\csname gmd@mchook\the\c@gmd@mc\endcsname}%
  \fi}

\long\def\AfterMacrocode#1#2{\@namedef{gmd@mchook#1}{#2}}
% What have I~done? I~declare a~new counter and employ it to count the
% \env{macrocode(*)}s (and \env{oldmc(*)}s too, in fact) and attach
% a~hook to (after) the end of every such environment. That lets us to
% put some stuff pretty far inside the compiled file (for the buggie
% in \file{doc.dtx}, to redefine |\gmu@tempb/c|).

% One more detail to expalin and define: the |\gmd@mcdiag| macro may
% be defined to type out a~diagnostic message (the
% \env{macrocode(*)}'s number, code line number and input line number).
\@emptify\gmd@mcdiag

\def\mcdiagOn{\def\gmd@mcdiag{%
    \typeout{^^J\bslash end{\@currenvir} No.\the\c@gmd@mc
    \space\on@line, cln.\the\c@codelinenum.}}}

\def\mcdiagOff{\@emptify\gmd@mcdiag}
%
% An environment to display the meaning of macro parameters: its
% items are automatically numbered as |#1|, |#2| etc.
\newenvironment*{enumargs}[1][1]%
% \changes{v0.99n}{2008/08/21}{developed for the case of inline
%   comment} 
% \changes{v0.99o}{2008/09/04}{added the optional argument which is
% the number of hashes (1 by default or 2 or 4)}
% \changes{v0.99p}{2008/10/4}{added optional arguments' handling}
{\if@aftercode\edef\gmu@tempa{\the\leftskip}%
  \edef\gmu@tempb{\the\hangindent}\fi
  \enumerate
  \if@aftercode
    \leftskip=\glueexpr\gmu@tempa+\gmu@tempb\relax
  \fi
  \@namedef{label\@enumctr}{%
    \env{\if@aftercode\code@delim\space\fi
      \gmd@ea@bwrap
      \#\ifcase#1\relax\or\or\#\or\or\#\#\#\fi
      \csname the\@enumctr\endcsname 
      \gmd@ea@ewrap}}%
  \let\mand\item
  \provide\gmd@ea@wraps{%
    \emptify\gmd@ea@ewrap
    \emptify\gmd@ea@bwrap}%
  \gmd@ea@wraps
  \def\opt{%
    \def\gmd@ea@bwrap{[}\def\gmd@ea@ewrap{]}%
  \item
    \gmd@ea@wraps}%
}
{\endenumerate}

% The starred version is intended for lists of arguments some of which
% are optional: to align them in line.
\newenvironment*{enumargs*}{%
  \def\gmd@ea@wraps{%
    \def\gmd@ea@bwrap{ }\def\gmd@ea@ewrap{ }}%
  \enumargs}{\endenumargs}

%
% \subdivision[\docfm-compatibility]{\gmhypertarget[doccompa]{\docfm-compatibility}}
%
% \gmhypertarget[doc-likeness]{My} \TeX\ Guru recommended me to write
% hyperlinking for \docfm. The suggestion came out when writing of
% \gmdoc\ was at such a~stage that I~thought it to be much easier to write
% a~couple of |\let|s to make \gmdoc\ able to typeset
% sources written for \docfm\ than to write a~new package that adds
% hyperlinking to \docfm. So\dots
%
% \stanza
% The \docfm\ package makes |%| an ignored char. Here the |%| delimits
% the code and therefore has to be `other'. But only the first one
% after the code. The others we may re|\catcode| to be ignored and we
% do it indeed in line \ref{ignorePercent}.
% \stanza
%
% At the very beginning of a~\docfm-prepared file we meet a~nice
% command \cs{Char\-act\-er\-Tab\-le}. My \TeX\ Guru says it's a~bit old
% fashioned these days so let's just make it notify the user:

\def\CharacterTable{\begingroup
  \@makeother\{\@makeother\}%
  \Character@Table}

\foone{%
  \catcode`\[=1 \catcode`\]=2 %
  \@makeother\{\@makeother\}}%
[
  \def\Character@Table#1{#2}[\endgroup
     \message[^^J^^J gmdoc.sty package:^^J
     ==== The input file contains the \bslash CharacterTable.^^J
     ==== If you really need to check the correctness of the chars,^^J
     ==== please notify the author of gmdoc.sty at the email address^^J
     ==== given in the legal notice in gmdoc.sty.^^J^^J]%
     %^^A~\gmd@countlines[#1]\gmd@countlines[#2]
  ]]
% Similarly as \docfm, \gmdoc\ provides \env{macrocode}, \env{macro}
% and \env{environment} environments. Unlike in \docfm,
% |\end{macrocode}| \emph{does not} require to be preceded with any
% particular number of spaces. Unlike in \docfm, it \emph{is not}
% a~kind of \env{verbatim}, however, which means the code and
% narration layers remains in force inside it which means that any
% text after the first |%| in a~line will be processed as narration
% (and its control sequences will be executed). For a~discussion of
% a~possible workaround see line \ref{AVerySpecialMacro}.
%
% \stanza
% Let us now look over other original \docfm's control sequences and
% let's `domesticate' them if they are not yet.
% 
% The \TextUsage\DescribeMacro\ and \TextUsage\DescribeEnv\ commands
% seem to correspond with my |\TextUsage| macro in its plain and starred
% version respectively except they don't typeset their arguments in the text
% i.e., they do two things of the three. So let's |\def| them to do these
% two things in this package, too:
\outer\def\DescribeMacro{%
  \begingroup\MakePrivateLetters
  \gmd@ifonetoken\Describe@Macro\Describe@Env}
% Note that if the argument to |\DescribeMacro| is not
% a~(possibly starred) control sequence, then as an environment's name
% shall it be processed \emph{except} the \cs{Mak\-ePriv\-at\-e\-Oth\-ers}
% re|\catcode|ing shall not be done to it.
\outer\def\DescribeEnv{%
  \begingroup\MakePrivateOthers\Describe@Env}

% Actually, I've used the |\Describe...| commands myself a~few times, so
% let's |\def| a~common command with a~starred
% version:
\outer\def\Describe{% It doesn't typeset its argument in the point of
  % occurrence. 
  \begingroup\MakePrivateLetters
  \@ifstarl{\MakePrivateOthers\Describe@Env}{\Describe@Macro}}

% The below two definitions are adjusted \*s of |\Text@UsgMacro| and
% |\Text@UsgEnvir|.
% \DefIndex\Describe@Macro
\long\def\Describe@Macro#1{%
  \endgroup
  \strut\Text@Marginize#1%
  \@usgentryze#1% we declare kind of formatting the entry
  \text@indexmacro#1\ignorespaces}

% \DefIndex\Describe@Env
\def\Describe@Env#1{%
  \endgroup
  \strut\Text@Marginize{#1}%
  \@usgentryze{#1}% we declare the `usage' kind of
  % formatting the entry and index the sequence |#1|.
  \text@indexenvir{#1}\ignorespaces}

% Note that here the environments' names are typeset in |\tt| font
% just like the macros', \emph{unlike} in \docfm.
%
% \stanza
% My understanding of `minimality' includes avoiding too much freedom
% as causing chaos not beauty. That's the philosophical and \ae^^B
% sthetic reason why I~don't provide \TextUsage\MacroFont. In
% my opinion there's a~noble tradition of typesetting the \TeX\ code
% in |\tt| font nad this tradition sustained should be. If one wants
% to change the tradition, let \himher\ redefine |\tt|, in \TeX\ it's
% no problem. I~suppose |\MacroFont| is not used explicitly, and that
% it's (re)defined at most, but just in case let's |\let|:

\let\MacroFont\tt

%
% \stanza
% We have provided \TextUsage\CodeIndent\ in line
% \ref{CodeIndent}. And it corresponds with \docfm's
% \Describe\MacroIndent\cs{Mac\-ro\-In\-dent} so
% \Define\MacroIndent
\let\MacroIndent\CodeIndent
% And similarly the other skips: \Define\MacrocodeTopsep
\let\MacrocodeTopsep\CodeTopsep
% Note that \TextUsage\MacroTopsep\ is defined in \gmdoc\ and has
% the same r\ocircum le as in \docfm.
% \Define\SpecialEscapechar
\let\SpecialEscapechar\CodeEscapeChar

% \TextUsage\theCodelineNo\ is not used in
% \pk{gmdoc}. Instead of it there is \TextUsage\LineNumFont\
% declaration and a~possibility to redefine |\thecodelinenum| as for
% all the counters. Here the |\LineNumFont| is used two different
% ways, to set the benchmark width for a~linenumber among others, so it's not
% appropriate to put two things into one macro. Thus let's give the
% user a~notice if \heshe\ defined this macro: 
%
% Because of possible localness of the definitions it seems to be
% better to add a~check at the end of each |\DocInput| or
% |\IndexInput|. 

\AtEndInput{\@ifundefined{theCodelineNo}{}{\PackageInfo{gmdoc}{The
      \string\theCodelineNo\space macro has no effect here, please use
      \string\LineNumFont\space for setting the font and/or
      \string\thecodelinenum\space to set the number format.}}}
% I~hope this lack will not cause big trouble.
%
% \stanza
% For further notifications let's define a~shorthand:
\def\noeffect@info#1{\@ifundefined{#1}{}{\PackageInfo{gmdoc}{^^J%
      The \bslash#1 macro is not supported by this package^^J
      and therefore has no effect but this notification.^^J
      If you think it should have, please contact the maintainer^^J
      indicated in the package's legal note.^^J}}}

% The four macros formatting the macro and environment names, namely
% \possfil\TextUsage\PrintDescribeMacro,
% \possfil\TextUsage\PrintMacroName,
% \possfil\TextUsage\PrintDescribeEnv\ and
% \possfil\TextUsage\PrintEnvName\  are not
% supported by \pk{gmdoc}. They seem to me to be too internal to take
% care of them. Note that in the name of (\ae sthetical) minimality
% and (my) convenience I~deprive you of easy knobs to set strange
% formats for verbatim bits: I~think they are not advisable.
%
% Let us just notify the user. 
\AtEndInput{%
  \noeffect@info{PrintDescribeMacro}%
  \noeffect@info{PrintMacroName}%
  \noeffect@info{PrintDescribeEnv}%
  \noeffect@info{PrintEnvName}}
  
% The \TextUsage\CodelineNumbered\ declaration of \docfm\ seems to be
% equivalent to our |noindex| option with the |linesnotnum| option set
% off so let's define it such a~way.
\def\CodelineNumbered{\AtBeginDocument{\gag@index}}
\@onlypreamble\CodelineNumbered
% Note that if the |linesnotnum| option is in force, this declaration
% shall not revert its effect. 
%
% I~assume that if one wishes to use \docfm's interface then \heshe'll
% not use \gmdoc's options but just the default.
%
% \stanza
% The |\CodelineIndex| and |\PageIndex| declarations
% correspond with  the \pk{gmdoc}'s default and the |pageindex| option
% respectively.
% Therefore let's |\let|
\let\CodelineIndex\@pageindexfalse
\@onlypreamble\CodelineIndex

\let\PageIndex\@pageindextrue
% \label{PageIndex}
\@onlypreamble\PageIndex

% The next two declarations I~find useful and
% smart:
\def\DisableCrossrefs{\@bsphack\gag@index\@esphack}

\def\EnableCrossrefs{\@bsphack\ungag@index
  \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack}
% The latter definition is made due to the footnote 6 on p.\,8 of the
% Frank Mittelbach's \docfm's documentation and both of them are
% copies of lines 302--304 of it modulo |\|(|un|)|gag@index|.
%
% \stanza
% The subsequent few lines I~copy almost verbatim ;-) from the lines
% 611--620.
\newcommand*\AlsoImplementation{\@bsphack%
  \long\def\StopEventually##1{\gdef\Finale{##1}}% we define
  % \cs{Fi\+n\+a\+le} just to expand to the argument of |\StopEventually| not
  % to to add anything to the end input hook because |\Finale| should
  % only be executed if entire document is typeset.\nostanza\par
  % 
  % \hangindent\verbatimhangindent \hangafter1\relax
  % \gmdnoindent \leftskip\CodeIndent
  % |%\init@checksum| is obsolete in
  % \pk{gmdoc} at this point: the \env{CheckSum} counter is reset just at
  % the beginning of (each of virtually numerous) input(s).
  % \nostanza\par
    \@esphack}

\AlsoImplementation

% \begin{quotation} When the user places an |\OnlyDescription|
%   declaration in the driver file the document should only be typeset
%   up to |\StopEventually|. We therefore have to redefine this
%   macro.\end{quotation}

\def\OnlyDescription{\@bsphack\long\def\StopEventually##1{%
    % \begin{quotation} In this case the argument of |\StopEventually|
    %   should be set and afterwards \TeX\ should stop reading from
    %   this file. Therefore we finish this macro with\end{quotation}
    ##1\endinput}\@esphack}

% \begin{quotation} If no |\StopEventually| command is given we
%   silently ignore a~|\Finale| issued.\end{quotation}

\@relaxen\Finale

% The \TextUsage\meta\ macro is so beautifully crafted in \docfm\ that
% I~couldn't resist copying it into \pk{gmutils}. It's also available
% in Knuthian (\TeXbook\ format's) disguise
% \Describe*{\<...>}|\<|\<the argument>|>|.
% \stanza
% The checksum mechanism is provided and developed for a~slightly
% different purpose.
% \stanza
% Most of \docfm's indexing commands have already been `almost
% defined' in \pk{gmdoc}:
\let\SpecialMainIndex=\DefIndex

% \DoNotIndex\endcsname*
\def\SpecialMainEnvIndex{\csname CodeDefIndex\endcsname*}% we don't
% type |\DefIndex| explicitly here because it's |\outer|, remember?

% \Define\SpecialIndex \Define\SpecialUsageIndex
% \Define\SpecialEnvIndex \Define\SortIndex
\let\SpecialIndex=\CodeCommonIndex

\let\SpecialUsageIndex=\TextUsgIndex

\def\SpecialEnvIndex{\csname TextUsgIndex\endcsname*}

\def\SortIndex#1#2{\index{#1\actualchar#2}}
% \begin{quotation}All these macros are usually used by other macros;
% you will need them only in an emergency.\end{quotation}
% 
% Therefore I~made the assumption(s) that `Main' indexing macros are
% used in my `Code' context and the 'Usage' ones in my `Text' context.
%
% \stanza
% Frank Mittelbach in \docfm\ provides the \TextUsage\verbatimchar\
% macro to (re)define the |\verb(*)|'s delimiter for the index
% entries. The \gmdoc\ package uses the same macro and its default definition
% is |{&}|. When you use \docfm\ you
% may have to redefine |\verbatimchar| if you use (and index) the |\+|
% control sequence. \pk{gmdoc} does a~check for the analogous situation
% (i.e., for processing |\&|) and
% if it occurs it takes |$| as the |\verb*|'s delimiter. So strange
% delimiters are chosen deliberately to allow any `other' chars in the
% environments' names. If this would cause problems, please
% notify me and we'll think of adjustments.
%
\def\verbatimchar{&}
% \changes{v0.98c}{06/9/10}{put into all indexing macros for the
% accordance of the `macro' and the `environment' index entries; the 
% \cs[]{\$} sign set as its alternative}

% One more a~very neat macro provided by \docfm. I~copy it
% verbatim and put into \pk{gmutils}, too. (|\DeclareRobustCommand|
% doesn't issue an error if its argument has been defined, it only
% informs about redefining.)
\pdef\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}}
% \changes{v0.98}{06/09/05}{made robust.}


% \TextUsage\IndexPrologue\ is defined in line
% \ref{IndexPrologue}. And other \docfm\ index commands too.

\@ifundefined{main}{}{\let\DefEntry=\main}

\@ifundefined{usage}{}{\let\UsgEntry=\usage}

% About how the \ds\ directives are supported by \pk{gmdoc},
% see section \gmiflink[docstrip]{The \ds\dots}.
% This support is not \emph{that} sophisticated as in \docfm, among others, it
% doesn't count the modules' nesting. Therefore if we dont want an
% error while \pk{gmdoc}umenting \docfm-prepared files, better let's
% define \docfm's counter for the modules' depths.
\newcounter{StandardModuleDepth}

% \stanza
% For now let's just mark the macro for further development
% \Define*\DocstyleParms
\noeffect@info{DocstyleParms}

% For possible further development or to notify the user once and
% forever:
% \Define\DontCheckModules \Define\CheckModules
\@emptify\DontCheckModules \noeffect@info{DontCheckModules}
\@emptify\CheckModules \noeffect@info{CheckModules}
% The \TextMarginize\Module|\Module| macro \emph{is} provided exactly
% as in \docfm.
% \Define\AltMacroFont
\@emptify\AltMacroFont \noeffect@info{AltMacroFont}

% \begin{quotation} And finally the most important bit: we change the
% |\catcode| of |%| so that it is ignored (which is how we are able to
% produce this \pk{doc}ument!). We provide two commands to do the
% actual switching.\end{quotation}
\def\MakePercentIgnore{\catcode`\%9\relax}
\def\MakePercentComment{\catcode`\%14\relax}
%
%
% \subdivision{\gmdoc ing \file{doc.dtx}}
%
% The author(s) of \docfm\ suggest(s): \begin{quotation}For examples
% of the use of most---if not all---of the features described above
% consult the \file{doc.dtx} source itself.\end{quotation}
% Therefore I~hope that after \file{doc.dtx} has been \gmdoc-ed, one
% can say \gmdoc\ is \docfm-compatible ``at most---if not at all''.
%
% \TeX ing the original \docfm\ with my humble\footnote{What ^^B(
% a~\emph{false} modesty! ;-)}  package was a~challenge and
% a~milestone experience in my \TeX\ life.
%
% \stanza
% One of minor errors was caused by my understanding of a~`shortverb'
% char: due to \pk{gmverb}, in the math mode an active `shortverb' char
% expands to itself's `other' version thanks to |\string| (It's done
% with \verb+|+ in mind). \docfm's
% concept is different, there a~`shortverb' char should in the math
% mode work as shortverb. So let it be as they wish: \pk{gmverb}
% provides |\OldMakeShortVerb| and the oldstyle input commands change
% the inner macros so that also |\MakeShortVerb| works as in \docfm
% (cf.\ line \ref{oldmkshvrrb}). 
%
% We also redefine the \env{macro} environment to make it mark the
% first code line as the point of defining of its argument, because
% \pk{doc.dtx} uses this environment also for implicit definitions.
%
% \changes[\OldMakeShortVerb]{v0.98a}{06/09/05}{and pals moved to
% \pk{gmverb}.} 
%\Define\OldDocInput
% \changes{v0.98}{06/09/05}{\cs{@makeother\protect\bslash_} added}
% \changes{v0.98a}{06/09/05}{\cs{AtBegInput} changed into
% \cs{AtBegInputOnce}.}
% \changes{v0.98b}{06/09/07}{enrichments of the \env{macrocode(*)}
% definitions moved to the default definitions of these envs.}
\def\OldDocInput{% \changes{v0.99g}{2007/11/11}{obsolete redefinition
  % of the \env{macro} environment removed}
  \AtBegInputOnce{\StraightEOL
    \let\@MakeShortVerb=\old@MakeShortVerb
    % \label{oldmkshvrrb}
    \OldMacrocodes}%
  \bgroup\@makeother\_% it's to allow |_| in the filenames. The next
  % macro will close the group.
  \Doc@Input}
% We don't swith the |@codeskipput| switch neither we check it because
% in `old' world there's nothing to switch this switch in the
% narration layer.
%
% \stanza
% I~had a~hot and wild \TeX\ all the night nad what a~bliss when
% the `Succesfully formated 67 page(s)' message appeared. 
% 
% My package needed fixing some bugs and adding some compatibility
% adjustments (listed in the previous section) and the original
% \pk{doc.dtx} source file needed a~few adjustments too because some
% crucial differences came out. I'd like to write a~word about them now.
%
% \stanza
% The first but not least is that the author(s) of \docfm\ give the
% \CS marking commands non-macro arguments sometimes, e.g.,
% |\DescribeMacro{StandardModuleDepth}|. Therefore we should launch
% the \emph{starred} versions of corresponding \gmdoc\ commands. This
% means the \docfm-like commands will not look for the \CS's occurrence
% in the code but will mark the first codeline met.
% \stanza
%
% Another crucial difference is that in \gmdoc\ the narrative and the
% code layers are separated with only the code delimiter and
% therefore may be much more mixed than in \docfm. among others, the \env{macro}
% environment is \emph{not} a~typical \env{verbatim} like: the texts
% commented out within \env{macrocode} are considered a~normal
% commentary i.e., not verbatim. Therefore some macros `commented out'
% to be shown verbatim as an example source must have been `additionally'
% verbatimized for \gmdoc\ with the shortverb chars e.g. You may also
% change the code delimiter for a~while, e.g., the line
% \CodeDelim\.
% \AVerySpecialMacro % delete the first % when.\unskip|..|\par\CDPerc
%
% \gmdnoindent\label{AVerySpecialMacro}
%  was got with
% \begin{verbatim}
%\CodeDelim\.
%% \AVerySpecialMacro % delete the first % when.\unskip|..|\CDPerc
%\end{verbatim}
%
% \leftskip0sp\relax
% One more difference is that my shortverb chars expand to their
% \catother\ versions in the math mode while in \docfm\ remain
% shortverb, so I~added a~declaration |\OldMakeShortVerb| etc.
%
% \stanza
% Moreover, it's \TeX ing \docfm\ what inspired adding the
% |\StraightEOL| and |\QueerEOL| declarations.
%
%
%
% \division{Polishing, development and bugs}
% 
% \begin*{bulletpars}
%   \everypar{$\bullet$ }
%   \label{Tasks}|\MakePrivateLetters| theoretically may interfere
%   with |\active|ating some chars to allow linebreaks. But making
%   a~space or an opening brace a~letter seems so perverse that we may
%   feel safe not to take account of such a~possibility.
%
%   When |countalllines*| option is enabled, the comment lines
%   that don't produce any printed output result with a~(blank) line too
%   because there's put a~hypertarget at the beginning of them. But for
%   now let's assume this option is for draft versions so hasn't be
%   perfect.
%   
%   Marcin Woli\nacute ski suggests to add the marginpar clauses for the
%   \acro{AMS} classes as we did for the standard ones in the lines
%   \ref{mparclause1}--\ref{mparclause2}. Most probably I~can do it on
%   request when I~only know the classes' names and their `marginpar
%   status'.
%
%   When the |countalllines*| option is in force, some |\list|
%   environments shall raise the `missing |\item|' error if you don't
%   put the first |\item| in the same line as
%   |\begin{|\<environment>|}| because the (comment-) line number is
%   printed.^^A~\end{} 
%
% I'm prone to make the control sequences hyperlinks to the(ir)
% `definition' occurrences. It doesn't seem to be a~big work compared
% with what has been done so far.
%     
% Is |\RecordChanges| really necessary these days? Shouldn't be the
% |\makeglossary| command rather executed by default?\footnote{It's ^^B
% understandable that ten years earlier writing things out to the files ^^B
% remarkably decelerated \TeX, but nowadays it does not in most ^^B
% cases. That's why \cs{makeindex} is launched by default in \gmdoc.}
%
% Do you use |\listoftables| and/or |\listoffigures| in your
% documentations? If so, I~should `\acro{EOL}-straighten' them like
% |\tableofcontents|, I~suppose (cf.\ line \ref{straighttoc}).
%
% Some lines of non-printing stuff such as |\Define...| and
% |\changes| connecting the narration with the code resulted with
% unexpected large vertical space. Adding a~fully blank line between
% the printed narration text and not printed stuff helped.
%
% Specifying |codespacesgrey, codespacesblank| results in typesetting
% all the spaces grey including the leading ones. 
%
%
% About the \ds\ \gmiflink{verbatim mode directive} see above.
%
% \end{bulletpars}
% \ \par\vspace*{-\baselineskip}
% 
% \def\EOFMark{\<eof>}
% \division{(No) \EOFMark} 
% 
%  Until version 0.99i
% a~file that is |\DocInput| had to be ended with a~comment line with
% an |\EOF| or |\NoEOF| \CS that
% suppressed the end-of-file character to make input end
% properly. Since version 0.99i however the proper ending of input is
% acheved with |\everyeof| and therefore |\EOF| and |\NoEOF| become
% a~bit obsolete. 
%
% If the user doesn't wish the documentation to be ended by
% `\EOFMark', \heshe\ should redefine the |\EOFMark| \CS or end
% the file with a~comment ending with |\NoEOF| macro defined
% below\footnote{Thanks to Bernd Raichle at Bacho\TeX\ 2006 ^^B Pearl
%   Session where he presented \cs{input}ing a~file inside ^^B
%   \cs{edef}.}:
%

\foone{\catcode`\^^M\active }{%
  \def\@NoEOF#1^^M{%
    \@relaxen\EOFMark\endinput}%
  \def\@EOF#1^^M{\endinput}}

\def\NoEOF{\QueerEOL\@NoEOF}
\def\EOF{\QueerEOL\@EOF}
% \changes{v0.98}{06/09/05}{extended to add it the \cs{endinput} effect}
% \changes{v0.98l}{06/10/27}{divided in two macros first of which
% makes queer \acro{EOL} and the latter gobbles the stuff till the \acro{EOL} to
% suppress possible \cs{endinput} when used in \cs{StopEventually}}
% \label{NoEOF} As you probably see, \cs{(No)EOF} have the `immediate'
% |\endinput| effect: the file ends even in the middle of a~line, the
% stuff after \cs{(No)EOF} will be gobbled unlike with a~bare
% |\endinput|.


\endinput
%^^A~\docstrip
%</package>
%\PrintChanges \PrintIndex 
%
%
%^^A~place for general changes:
% \ChangesGeneral
%
% \changes{v0.98a}{06/09/06}{\cs{AtBeginput}, \cs{AtEndinput},
% \cs{AtBeginputOnce} renamed to \cs{AtBegInput}, \cs{AtEndInput}
% \cs{AtBegInputOnce} respect.}
%
% \changes{v0.98c}{06/9/9}{making \cs{Define} and \cs{CodeUsage}
% markers to add up; bug fixes in indexing macros and change of
% concept of \cs{Code(Define$\quotechar|$Usage)*}: hence they serve not only for
% environments but also for implicit def/use of macros}
%
% \changes{v0.98d}{06/9/11}{mostly editing the narrative, marking
% special index entries etc.; queering \cs{char1} and \cs{char2}
% repeated \cs{AtBegInput}}
%
% \changes{v0.98e}{06/09/24}{Some macros moved to \pk{gmutils}:
% \cs{cs} and pals and one-chars with queer \cs{catcode}s}
%
% \changes{v0.98f}{06/09/27}{A~bug fixed: \cs{Code@MarginizeMacro} set
% to define a~\CS and the corresponding test set to check if it's
% undefined. In all three such definitions and resets after the use,
% \cs{def} is changed to \cs{(g)let}}
%
% \changes{v0.98g}{06/10/10}{among others, \cs{discretionary}s for breaking
% a~\CS to percent at the beginning of the lower line. Moreover, fixing
% a~bug/feature that leaves the code leftskip in the narration when an
% inline comment is followed by another codeline (w.o.\ explicit
% \cs{par}). And lots of finishing touches to the text. A~special font
% for the marginpar \CSs among others}
%
% \changes{v0.98l}{06/10/26}{in \cs{AtBegInputOnce} an auxiliary macro
% for each use substituted with one macro added at begin input. In
% \cs{gmd@evpaddonce} a~counter substituted with a~numeric
% macro. \cs{@ifQueerEOL} made polite i.e., a~two-argument not
% expanding to an open \cs{if...}}
%
% \changes{v0.99}{06/11/24}{\env{oldmc(*)} implemented that's
% (hope)fully  compatible with \docfm's \env{macrocode(*)}. Moreover,
% a~declaration letting \gmdoc's \env{macrocode} to \env{oldmc(*)}}
%
% \changes{v0.99a}{06/11/30}{The \ds\ directives implemented fully
% automatic (no more need of \cs{doctrip(s)} declarations). Moreover,
% some minor changes due to \TeX ing The Source.}
%
% \changes{v0.99b}{2007/01/01}{Thanks to the \cs{edverbs} declaration
% in the class, displayed shortverbs simplified; Emacs mode changed to
% doctex. Author's true name more exposed}
%
% \changes{v0.99c}{2007/03/02}{A~bug fixed in \cs{DocInput} and all
% \cs{expandafter}s changed to \cs{@xa} and \cs{noexpand}s to
% \cs{@nx}} 
%
% \changes{v0.99c}{2007/03/12}{The \TeX-related logos now are declared
% with \cs{DeclareLogo} provided in \pk{gmutils}}
%
% \changes{v0.99d}{2007/04/13}{\cs{afterfi} \& pals made two-argument}
%
% \changes{v0.99d}{2007/04/24}{\cs{@namelet} renamed to \cs{n@melet}
% to solve a~conflict with the \pk{beamer} class (in \pk{gmutils} at
% first)}
%
% \changes{v0.99e}{2007/04/29}{a~bug fixed in \cs{DocInput} and
% \cs{IndexInput}} 
%
% \changes{v0.99g}{2007/11/12}{The bundle goes \XeTeX. The
%   \TeX-related logos now are moved to \pk{gmutils}. \hathat{A}
%   becomes more comment-like thanks to re\cs{catcode}'ing. Automatic
%   detection of definitions implemented}
%
% \changes{v0.99h}{2007/11/16}{Fixed behaviour of sectioning commands
% (optional two heading skip check) of \pk{mwcls/gmutils} and
% respective macro added in \pk{gmdocc}. I~made a~\file{tds} archive}
% 
% \changes{v0.99i}{2008/08/03}{A~“feature not bug” fix: thanks to
% \cs{everyeof} the \cs{(No)EOF} is now not necessary at the end of
% \cs{DocInput} file.}
%
% \changes{v0.99m}{2008/08/08}{Counting of all lines developed (the
% \env{countalllines} package option), now it
% uses \cs{inputlineno}}
%
% \changes{v0.99n}{2008/08/24}{Inline comments' alignment developed}
%
% \Finale

% (For my GNU Emacs:)
%%% Local Variables: 
%%% mode: doctex
%%% End: