From 32514addcd2b369a74cb384f0274598e5574ce21 Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Tue, 12 Aug 2008 00:00:12 +0000
Subject: gmdoc update (11aug08)

git-svn-id: svn://tug.org/texlive/trunk@10266 c570f23f-e606-0410-a88d-b1316a301751
---
 Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty | 846 ++++++++++++++++------------
 1 file changed, 485 insertions(+), 361 deletions(-)

(limited to 'Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty')

diff --git a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty
index 00351067f45..2532d3e7608 100644
--- a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty
+++ b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty
@@ -16,13 +16,13 @@
 %% Written by Natror (Grzegorz Murzynowski),
 %% natror at o2 dot pl
 %%
-%% \copyright\,2006, 2007 by Natror (Grzegorz Murzynowski).
+%% \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.
 %%
-%% LPPL status: "author-maintained".\par
+%% \acro{LPPL} status: "author-maintained".\par
 %%
 %% Many thanks to my \TeX\ Guru Marcin Woli\nacute ski for his \TeX nical ^^A
 %% support.
@@ -54,15 +54,20 @@
 % \chschange{v0.99d}{07/4/26}{4555}
 % \chschange{v0.99e}{2007/4/29}{4574}
 % \chschange{v0.99g}{2007/11/12}{5229}
-%
-% 
-%^^A \docstrip
-%<package>
-
+% \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.99l}{2008/8/6}{5233}
+%
+\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}
-         [2007/11/12 v0.99h a documenting package (GM)]
-
+         [2008/08/06 v0.99l a documenting package (GM)]
+\fi
+% 
 %
 %
 % \CharacterTable {In my \TeX\ Guru's opinion the idea of
@@ -103,18 +108,19 @@
 %   (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.)
+%   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 CTAN as separate
+%   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}
+%   style for the changes' history, into some \file{texmf/makeindex}
 %   (sub)directory.
 %
 %   Then you should refresh your \TeX\ distribution's files' database
@@ -125,14 +131,13 @@
 % \subdivision{Contents of the \pk{gmdoc.zip} Archive}
 %
 % The distribution of the \pk{gmdoc} package consists of the
-% following six files and a~\acro{TDS}-compliant archive.
+% following five files and a~\acro{TDS}-compliant archive.
 % \begin{verse}
 %   \pk{gmdoc.sty}\\
 %   \pk{gmdocc.cls}\\
 %   \pk{gmglo.ist}\\
 %   \pk{README}\\
-%   \pk{gmdocDoc.tex}\\
-%   \pk{gmdocDoc.pdf}\\
+%   \pk{gmdoc.pdf}\\
 %   \pk{gmdoc.tds.zip}
 % \end{verse}
 %
@@ -140,17 +145,19 @@
 % \begin{gmlonely}
 %   \subdivision{Compiling the Documentation}
 %
-%   The last of the above files (the \pk{.pdf}, i.e., \emph{this
+%   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{gmdocDoc.tex}
-%   twice, then MakeIndex on the \file{gmdocDoc.idx} and
-%   \file{gmdocDoc.glo} files, and then \XeLaTeX\ on \file{gmdocDoc.tex}
+%   \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 gmdocDoc
-%makeindex -r -s gmglo.ist -o gmdocDoc.gls gmdocDoc.glo
+%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.
@@ -158,12 +165,12 @@
 %   Compiling the documentation requires the packages:
 %   \pk{gmdoc} (\pk{gmdoc.sty} and \pk{gmdocc.cls}), \pk{gmutils.sty},
 %   \pk{gmverb.sty}, \pk{gmiflink.sty} and also some standard packages:
-%   \pk{hyperref.sty}, \pk{color.sty}, \pk{geometry.sty},
+%   \pk{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
-%   CTAN and present in \TeX\ Live e.g.), the result of your
+%   \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.
@@ -190,9 +197,9 @@
 % 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} ;-):
@@ -231,7 +238,7 @@
 % 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.) 
+% cross-references, too. (The \acro{CS}s 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
@@ -260,17 +267,17 @@
 % (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}. 
+% I'll use a~shorthand for `control sequence', \textbf{\acro{CS}}. 
 %
 % When I~talk of a~\textbf{declaration}, I~mean a~macro that expands
 % to a~certain assignment, such as |\itshape| or
-% |\@onlypreamble{|\<CS>|}|.
+% |\@onlypreamble{|\<\acro{CS}>|}|.
 %
-% Talking of declarations, I'll use the \textbf{OCSR} acronym as
+% 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
+% user as a~\acro{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}
@@ -341,7 +348,7 @@
 % fancy the |^^B| special sequence, instead you may restore the
 % standard meaning of the line end with the \TextUsage\StraightEOL\
 % declaration which
-% OCSR. As almost all the control
+% \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
@@ -358,7 +365,7 @@
 %   ^^A %   ``What a~queer day is today''.)
 % }^^A
 % \QueerEOL
-% \gmdoc's meaning of the line end. It OCSR, too.  One more point to use
+% \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
@@ -426,13 +433,12 @@
 % name. In \gmdoc\ it has one mandatory argument that should be the
 % file name \emph{without extension}, just like for |\include|.
 %
-% The file extensions supported by |\DocInclude| are \pk{.fdd},
-% \pk{.dtx}, \pk{.cls}, \pk{.sty}, \pk{.tex} and \pk{.fd}. The macro
-% looks for 
-% one of those 
-% extensions in the order just given. If you need to document files
-% of other extensions, please let me know and most probably we'll make
-% it possible.
+% 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 |/|
@@ -462,23 +468,14 @@
 % \TextUsage\includeonly|{|\<filenames separated by commas>|}| for
 % the draft versions.
 %
-% \stanza
-% If you wish to include the driver file into your documentation, you
-% may write |\DocInput{\jobname.tex}|, but a~try of
-% |\DocInclude{\jobname}| would result with input stack overflow
-% caused by infinite |\input{|\<jobname>|.aux}| recursion.
-% But there's \TextUsage\SelfInclude\ at your service that creates and
-% uses \pk{\<jobname>.auxx} file instead of the usual
-% \pk{\<jobname>.aux}. Its effect is analogous to the |\DocInclude|'s, but
-% \emph{the arguments it takes are totally different}: Since the
-% filename is known, there's no need to state it. The extension is
-% assumed to be \file{.tex}, but if it's different, you may state it in
-% the first and optional argument. The second argument is mandatory and
-% it's the stuff to be put at begin of file input, this one and no
-% else (with \TextCommonIndex\AtBegInputOnce|\AtBegInputOnce| hook).
-% For the example of usage see line \ref{SelfIncludeUsg} of
-% chapter~\ref*{Driver}.
-% 
+% \stanza 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
@@ -509,7 +506,7 @@
 % counterpart, \TextUsage\gmdocIncludes, that may be used anywhere,
 % too. Before the respective |\DocInclude|(s), of course.
 %
-% Both these declarations OCSR.
+% Both these declarations \acro{OCSR}.
 %
 % If you wish to document your files as with \pk{ltxdoc} \emph{and}
 % as with \docfm, you should declare
@@ -548,10 +545,10 @@
 % 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 OK). 
+% 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
+% verbatim, with the code lines numbered and the \acro{CS}s automatically
 % indexed (\pk{gmdoc.sty} options are in force).
 %
 %
@@ -586,7 +583,7 @@
 %
 % \stanza
 % By default the \pk{makeidx} package is loaded and initialized and
-% the CSs occurring in the code are automatically
+% the \acro{CS}s 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.
@@ -596,9 +593,9 @@
 % the \TextUsage*{pageindex}\label{indexoptions} option is set.
 %
 % \stanza
-% By default, \gmdoc\ excludes some 300 CSs from being indexed.
-% They are the most common CSs, \LaTeX\ internal
-% macros and \TeX\ primitives. To learn what CSs are
+% By default, \gmdoc\ excludes some 300 \acro{CS}s from being indexed.
+% They are the most common \acro{CS}s, \LaTeX\ internal
+% macros and \TeX\ primitives. To learn what \acro{CS}s are
 % excluded actually, see lines \ref{DIE1}--\ref{DIE2}.
 %
 % If you don't want all those exclusions, you may turn them off with
@@ -629,8 +626,14 @@
 % spaces to be blank, I~give the option \TextUsage*{codespacesblank}
 % reluctantly. Moreover, if you wish the code spaces to be blank only
 % in some areas, then there's \TextUsage\CodeSpacesBlank\ declaration
-% (OCSR).
+% (\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
+% |codespacesgrey| 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.
 %
 % \subdivision{The Packages Required}
 %
@@ -770,7 +773,7 @@
 % 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
+% alternate index entries will be created: of the \acro{CS}s uderlying those
 % definitions, e.g. |\newcounter{foo}| in the
 % code will result in indexing |foo| and |\c@foo|.
 %
@@ -779,7 +782,7 @@
 % 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
+% whether wrapped in braces or not, is a~\acro{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
@@ -811,7 +814,7 @@
 % 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
+% a~\acro{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
@@ -846,7 +849,7 @@
 %
 % The basic definition command, |\def|, seems to me a~bit
 % controversial. Definitely \emph{not always} it defines important
-% macros. But first of all, if you |\def| a~CS excluded from indexing (see
+% macros. But first of all, if you |\def| a~\acro{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
@@ -900,7 +903,7 @@
 % 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).
+% environment name or a~|^^A|-like and also a~\acro{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
@@ -911,12 +914,12 @@
 %
 % 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
+% occurrence' I~mean a~situation of the \acro{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
+% argument is not a~\acro{CS}). Therefore, if you want to mark a~definition
 % of an environment \env{foo}, you should put
 % \[|%\Define*{foo}|\]
 %  right before the code line
@@ -936,14 +939,14 @@
 % 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
+% |^^A|-likes and \acro{CS}s, 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,
+% the desired \acro{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
@@ -975,12 +978,12 @@
 % 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
+% On the other hand, if you don't want to put a~\acro{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
+% (the argument should be a~\acro{CS}), and the starred ones just take the
 % next code line as the reference point. Both these commands are
 % |\outer|.
 %
@@ -997,13 +1000,13 @@
 % 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
+% their starless versions for a~\acro{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
+% argument that should be a~\acro{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
@@ -1014,14 +1017,14 @@
 % 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
+% Since it's possible that you define a~\acro{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
+% (To be honest, if you give a~\env{macro} environment a~non-\acro{CS}
 % argument, it will accept it and then it'll work as
 % \env{evironment}.)
 %
@@ -1034,7 +1037,7 @@
 % \docfm\ package gives a~brilliant solution: the
 % \TextUsage\DoNotIndex\ declaration. So do I
 % (although here, \TeX nically it's done another
-% way). It OCSR. This declaration takes one
+% 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
@@ -1042,18 +1045,18 @@
 % \[|\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.
+% many \acro{CS}s may be declared, because for each \acro{CS} excluded from indexing
+% a~special \acro{CS} is declared that stores the ban sentence).
+%  Excluding the same \acro{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
+% some 300 \acro{CS}s by default. If you don't like it, just set the
 % |indexallmacros| package option.
 %
 % On the third hand, if you like the default exclusions in general but
 % wish to undo just a~couple of them, you are given \TextUsage\DoIndex\
-% declaration (OCSR) that removes a~ban on all the CSs given in the
+% declaration (\acro{OCSR}) that removes a~ban on all the \acro{CS}s given in the
 % argument, e.g.,
 % \[|\DoIndex{\par \@@par \endgraf}|\]
 %
@@ -1061,7 +1064,7 @@
 % and \Describe\UndoDefaultIndexExclusions^^A
 % \cs{Un\-do\-Def\-ault\-Ind\-ex\-Ex\-cl\-us\-ions} declarations that
 % act according to their names. You may use them in any configuration
-% with the |indexallmacros| option. Both of these declarations OCSR.
+% with the |indexallmacros| option. Both of these declarations \acro{OCSR}.
 %
 %
 % \subdivision{The \ds\ Directives}
@@ -1083,7 +1086,7 @@
 % 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 add any \acro{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
@@ -1102,7 +1105,7 @@
 %^^A restores the previous meaning of |<| after the first using it as
 %^^A a~\ds\ directive opener.
 %^^A
-%^^A Both |\docstrips| and |\docstrip| OCSR and, of course you may use
+%^^A 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
@@ -1114,7 +1117,7 @@
 % 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>|}{|\<YYYY/MM/DD date>|}{|\<text>|}|\]
+% \[|\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
@@ -1208,7 +1211,7 @@
 %
 % \stanza
 %
-% While scanning the CSs in the code, \gmdoc\ counts them and prints
+% While scanning the \acro{CS}s 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
@@ -1284,17 +1287,17 @@
 % (otherwise what would be the margins for?). It's 0\,sp by default.
 %
 % \stanza
-% By default, typesetting a~|\DocInput/Include|d file is ended with
-% a~codeline containing the text `\EOFMark' given by the
-% \TextUsage\EOFMark\ macro. If you don't like such an ending, you
-% should end the source file with the \TextUsage\NoEOF\ macro in
-% a~comment, i.e.,
-% \[|%|\<some text, why not>|\NoEOF|\]
-%   This macro redefines |\EOFMark| and suppresses the End
-% Of File token to close the input properly. It also has the
-% |\endinput| effect so you may put some text you don't want to 
-% document after it.
+% 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
@@ -1337,7 +1340,7 @@
 %
 % 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
+% argument, which is supposed to be a~one-char \acro{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
@@ -1377,8 +1380,8 @@
 % \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.
+% entries indicating the \emph{usage} of the \acro{CS} and the entries
+% indicating the \emph{definition} of the \acro{CS}.
 %
 % The special formattings of `usage' and `def' index entries are
 % determined by \TextUsage\UsgEntry\ and \TextUsage\DefEntry\
@@ -1387,12 +1390,13 @@
 % |\underline| respectively (as in \docfm).
 %
 % There's one more parameter macro, \TextUsage\CommonEntryCmd\ that
-% stores the name of the encapsulation for the `common' index
-% entries (not special) i.e., a~word that'll become a~CS that will 
-% be put before an entry in the \file{.ind} file. By default it's defined
-% as |{relax}| and a~nontrivial use of it you may see in line
-% \ref{UsgHack} of the driver file of this documentation, where it
-% makes all the index entries of the driver's code are formatted as `usage'.
+% stores the name of the encapsulation for the `common' index entries
+% (not special) i.e., a~word that'll become a~\acro{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
@@ -1440,15 +1444,15 @@
 % 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
+%   what characters of a~scanned \acro{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
+% scanned \acro{CS} names etc. \gmdoc\ also uses \TextUsage\verbatimchar\ but
+% defines it as |{&}|. Moreover, a~macro that wraps a~\acro{CS} name in |\verb|
+% checks whether the wrapped \acro{CS} isn't |\&| and if it is, |$| is taken
 % as the delimiter. So there's hardly chance that you'll need to
 % redefine |\verbatimchar|.
 %
@@ -1603,7 +1607,13 @@
 %
 %\stanza
 % The \TextUsage*{quotation} environment is redefined just to enclose
-% its contents in double quotes.
+% 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
@@ -1617,10 +1627,17 @@
 %
 % If the input file doesn't contain |\Provides...| in the code layer, 
 % there are commands \TextUsage\ProvideFileInfo|{|\<file name with ^^B
-% extension>|}[|\<info>|]| and
-% \TextUsage\ProvideSelfInfo|[|\<info>|]|. (\<info> should consist of:
+% 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,
@@ -1640,8 +1657,8 @@
 % \TextUsage\CDAnd\ instead of |\CodeDelim\&|.
 %
 % 
-%^^A \stanza
-%^^A For an example driver file see chapter \gmiflink{The Driver}.
+% \stanza
+% For an example driver file see chapter \gmiflink{The Driver}.
 %
 %
 % \subdivision{A~Queerness of \cs{label}}
@@ -1706,7 +1723,7 @@
 % \env{macrocode} (it also has the starred version), that's the first
 % option (I~needed the traditional behaviour once in this
 % documentation, find out where \& why). The other is to write
-% \TextUsage\VerbMacrocodes. That declaration (OCSR) redefines 
+% \TextUsage\VerbMacrocodes. That declaration (\acro{OCSR}) redefines 
 % \env{macrocode} and \env{macrocode*} to behave the traditional way.
 % (It's always executed by |\OldDocInput| and |\olddocIncludes|.)
 %
@@ -1714,6 +1731,116 @@
 % 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}
+%% \iffalse we skip the driver
+%\ifnum\catcode`\@=12
+%
+%\documentclass[outeroff,pagella]{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
+%%\fi
+%\end{verbatim}
+% 
+%
+% \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[outeroff,debug,mwrep,pagella]{gmdocc}
+%^^A~ \OnlyDescription
+%^^A~ \usepackage{graphics}
+%^^A~ \usepackage{eufrak}% specially for |\continuum| of \pk{gmutils}
+%^^A~ \usepackage{fontenc}% for Polish and French diacritics.
+\twocoltoc
+\title{The \pk{gmdoc} Package\\ i.e., \pk{gmdoc.sty} and
+  \pk{gmdocc.cls}}
+\author{Grzegorz `Natror' Murzynowski}
+\date{August 2008}
+\begin{document}
+
+%\iffalse
+\emptify\udigits % because orig. def. raises an error `\cs{@secondoftwo} has
+                 % an extra \}'
+%\fi
+\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}
 %
 %
@@ -1737,18 +1864,18 @@
 % verbatim and with the bells and whistles.
 %
 % The bells and whistles are (optional) numbering of the codelines,
-% and automatic indexing the CSs, possibly with
+% and automatic indexing the \acro{CS}s, 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.
+% \heshe\ has to type respective \acro{CS}s.
 %
 % I~see the feature described above to be quite a~convenience,
 % however it has some price. See section 
-% \gmiflink[afc]{Life Among Queer EOLs}  for details,
+% \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
 %
@@ -1835,7 +1962,7 @@
 
 \@ifclassloaded{book}{\@marginparsusedtrue}{}
 % \label{mparclause2} And if you don't use \pk{mwcls} nor standard
-% classes, then you have the options:\Define*{withmarginpar}
+% classes, then you have the options:
 \DeclareOption{withmarginpar}{\@marginparsusedtrue}
 
 \DeclareOption{nomarginpar}{\@marginparsusedfalse}
@@ -1847,9 +1974,17 @@
 % To make the code spaces blank (they are visible by default except
 % the leading ones).
 
-\newif\if@codespacesblank
 
-\DeclareOption{codespacesblank}{\@codespacesblanktrue}
+\DeclareOption{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 \inverb|\visiblespace|.
+    \AtBeginDocument{\CodeSpacesGrey}}}
 
 \ProcessOptions
 
@@ -1859,10 +1994,10 @@
 % We require another package of mine that provides some tricky macros
 % analogous to the \LaTeX\ standard ones, such as |\newgif| and
 % |\@ifnextcat|.
-\RequirePackage{gmutils}[2007/11/09]
+\RequirePackage{gmutils}[2008/08/03]
 
 % A~standard package for defining colours,
-\RequirePackage{color}
+\RequirePackage{xcolor}
 % and a~colour definition for the hyperlinks not to be too bright
 \definecolor{deepblue}{rgb}{0,0,.85}
 
@@ -1875,14 +2010,18 @@
 % \changes[hyperref]{v0.99g}{2007/10/30}{added bypass of encoding for loading
 % \pk{url}}
 
-\@ifXeTeX{\XeTeXdefaultencoding "cp1250"}{}
+%^^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,
-  \@ifXeTeX{xetex,}{}
+%^^A  \@ifXeTeX{xetex,}{}
   pdfpagemode=UseNone]{hyperref}}
-\@ifXeTeX{\XeTeXdefaultencoding "utf-8"}{}
+
+%^^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
@@ -2115,10 +2254,6 @@
     % and \cs{widowpenalty} set both to 3333}
     %\CodeUsgIndex\tolerance
     \tolerance=1000 % as in \docfm.
-    % \CodeUsgIndex\CodeSpacesBlank
-    \if@codespacesblank\CodeSpacesBlank\fi% \label{cspb}The default is
-    % that the code spaces are visible but here this may be cancelled
-    % due to the \cs{co\+de\+spa\+ces\+blank} option.
     \catcode`\^^M=\active%
     % \CodeUsgIndex\code@delim
     \@xa\@makeother\csname\code@delim\endcsname%
@@ -2152,6 +2287,7 @@
     \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
@@ -2168,7 +2304,7 @@
 
 % So, having the main macro outlined, let's fill in the details.
 %
-% First, define the queer EOL. We define a~macro that |^^M| will be
+% 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|).
@@ -2303,8 +2439,9 @@
 % macro.
 % \DefIndex\gmd@DoTeXCodeSpace
 \begin{obeyspaces}%
-\gdef\gmd@DoTeXCodeSpace{%
-\obeyspaces\let =\breakablexiispace}%
+\gdef\CodeSpacesVisible{%
+\def\gmd@DoTeXCodeSpace{%
+\obeyspaces\let =\breakablevisspace}}%
 % \stanza
 % \Define\CodeSpacesBlank
 % \changes{v0.98a}{06/09/06}{a~kernel \cs{gmd@verbatimspace} renamed
@@ -2320,9 +2457,31 @@
 \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}
+  \providecolor{codespacesgrey}{gray}{0.5}%
+  \CodeSpacesVisible%
+  \gmd@preambleABD{%
+    \unless\ifdefined\gmd@visspace
+      \let\gmd@visspace\visiblespace
+    \fi
+    \def\visiblespace{%
+      \hbox{\textcolor{codespacesgrey}\gmd@visspace}}%
+  }}%
+
+% Note that \cs{CodeSpacesVisible} doesn't revert \cs{CodeSpacesGrey}.
+
+\let\gmd@preambleABD\AtBeginDocument
+\AtBeginDocument{\let\gmd@preambleABD\firstofone}
+
+
+\CodeSpacesVisible
+
+
 % How the continuing of the narration should look like?
 \def\gmd@continuenarration{%
   \endgroup
@@ -2407,7 +2566,7 @@
       \if@newline\grefstepcounter{codelinenum}\@newlinegfalse%
       \fi%
       \printlinenumber% if we don't want the lines to be numbered,
-      % the respective option \inverb|\let|s this CS to |\relax|.
+      % the respective option \inverb|\let|s this \acro{CS} to |\relax|.
       \hyperlabel@line%
       \mark@envir% index and/or marginize an environment if there is
       % some to be done so, see line \ref{mark@envir}.
@@ -2415,7 +2574,7 @@
       \advance\hangindent by\gmd@ldspaceswd%
       \xdef\settexcodehangi{%
         \@nx\hangindent=\the\hangindent% and also set the
-        % hanging indent setting for the same line comment case. BTW.,
+        % 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. 
@@ -2455,16 +2614,16 @@
 
 % It costed me some time to reach that in my verbatim scope a~space
 % isn't \catother\ but \catactive, namely |\let| to
-% |\breakablexiispace|.
+% |\breakablevisspace|.
 % So let us |\let| for future:
 % \Define\gmd@texcodespace
-\let\gmd@texcodespace=\breakablexiispace
+\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}{\xiispace}%
+    \afterfi{\settowidth{\gmd@spacewd}{\visiblespace}%
     \gmd@ldspaceswd=\z@
     \gmd@eatlspace}%
   \else\afterfi{% about this smart macro and other of its family see
@@ -2503,20 +2662,23 @@
   \ifhmode\prevhmodegtrue
   \else\prevhmodegfalse\fi 
   \if\code@delim\@nx#1%
-    \afteriffifi{\gmd@percenthack% to typeset |%| if a~comment
+    \def\next{\gmd@percenthack% to typeset |%| if a~comment
     % continues the~codeline.
     \endgroup%
     \gmd@checkifEOLmixd}% to see if next is |^^M| and then do |\par|.
   \else% i.e., we've not met the code delimiter
-    \if\code@escape@char\@nx#1%
-      \@dsdirgfalse% yes, just here not before the whole |\if| because
-      % then we would discard checking for \ds\ directives doable by
-      % the active |%| at the `old macrocode' setting.
-      \afterfifi{\gmd@counttheline#1\scan@macro}%
+    \ifx\relax#1\def\next{\endgroup}% special case of end of file thanks to |\everyeof|.
     \else
-      \afterfifi{\gmd@EOLorcharbychar#1}%
+      \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{\gmd@counttheline#1\scan@macro}%
+      \else
+        \def\next{\gmd@EOLorcharbychar#1}%
+      \fi
     \fi
-  \fi}
+  \fi\next}
 
 % One more inner macro because |^^M| in \TeX\ code wants to peek at the
 % next char and possibly launch |\gmd@charbychar|. We deal with
@@ -2805,7 +2967,7 @@
 % |\if|s or |\fi|s.
 %
 %
-% \subdivision[Life Among Queer EOLs]{Life Among Queer \gmhypertarget[afc]{EOLs}}
+% \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
@@ -2924,7 +3086,7 @@
 % 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
+% account of a~possibility of redefining the |\ | \acro{CS} by the user, just
 % like in normal \TeX.
 
 
@@ -2950,7 +3112,7 @@
 
 % We also redefine an internal |\verb|'s macro |\gm@verb@eol| to put a~proper
 % line end if a~line end char is met in a~short verbatim: we have to
-% check if we are in `queer' or `straight' EOLs area.
+% check if we are in `queer' or `straight' \acro{EOL}s area.
 \begingroup
 \obeylines% \DefIndex\gm@verb@eol
 \AtBegInput{\def\gm@verb@eol{\obeylines%
@@ -2966,7 +3128,7 @@
 % 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.
+% but with separate control sequences for each excluded \acro{CS}.
 %
 % \stanza
 %
@@ -3001,7 +3163,7 @@
   \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
+% a~|\|\<one char> \acro{CS} as an argument. It's an invariant assertion that
 % |\code@escape@char| stores  `other' version of the code layer
 % escape char.
 % \CodeUsgIndex\CodeEscapeChar
@@ -3062,7 +3224,7 @@
     % 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 
+  % \acro{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|
@@ -3095,8 +3257,8 @@
 % 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.
+% the scanning of a~\acro{CS} name---we want to avoid scanning
+% |\command*argum| as one \acro{CS}.
 
 \def\gmd@finishifstar#1{%
   \if*\@nx#1\afterfi\finish@macroscan% note we protect |#1| against
@@ -3198,10 +3360,10 @@
 % 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.
+% whether a~history entry is a~\acro{CS} or not.
 
 \newcommand*\finish@macroscan{%\label{506}\par
-  % First we check if the current CS is not just being defined. The
+  % First we check if the current \acro{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
@@ -3211,14 +3373,14 @@
       \@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.
+    % true just for this \acro{CS}.
   \fi
-  % We have the CS's name for indexing in |\macro@iname| and
+  % We have the \acro{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
+  % comes before the macro's name: when it was reverse, the |\tt| \acro{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
@@ -3240,7 +3402,7 @@
 }
 
 % 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:
+% put into a~marginpar: it checks the meaning of a~very special \acro{CS}:
 % whose name consists of |gmd/2marpar/| and of the examined macro's
 % name. 
 \def\maybe@marginpar#1{%
@@ -3259,7 +3421,7 @@
 
 % 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.
+% \acro{CS}s are implemented in the section after it.
 %
 % \subdivision{Automatic detection of definitions}
 %
@@ -3268,7 +3430,7 @@
 % 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
+% is a~\acro{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.
@@ -3298,7 +3460,7 @@
 %
 % \subsubdivision{\cs{DeclareDefining} and the detectors}
 %
-% Note that the main argument of the next declaration should be a~CS
+% Note that the main argument of the next declaration should be a~\acro{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
@@ -3335,8 +3497,8 @@
     % \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 
+        \csname gmd@detect@\gmd@adef@currdef\endcsname}}% we add a~\acro{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{%
@@ -3350,7 +3512,7 @@
         \@nx\n@melet{gmd@adef@currdef}{gmd@detectname@\gmd@adef@currdef}%
       \@nx\fi}}%
   \@tempa
-  \SMglobal\StoreMacro*{gmd@detect@\gmd@adef@currdef}% we store the CS to
+  \SMglobal\StoreMacro*{gmd@detect@\gmd@adef@currdef}% we store the \acro{CS} to
   % allow its temporary discarding later.
 }
 
@@ -3398,7 +3560,7 @@
   \edef\gmd@resa{%
     \def\@xa\@nx\csname gmd@adef@KVpref@\gmd@adef@currdef\endcsname{%
       \ifx\gmd@resa\empty
-      \else#1@\fi}}% as in \pk{xkeyval}, if the KV prefix is not
+      \else#1@\fi}}% as in \pk{xkeyval}, if the \acro{KV} prefix is not
   % empty, we add \inverb|@| to it.
   \gmd@resa}
 
@@ -3425,7 +3587,7 @@
     def,
     newcommand,
     cs,% equivalent to the two above, covers all the cases of defining
-          % a~CS, including the \PlainTeX\ \inverb|\new...| and
+          % a~\acro{CS}, including the \PlainTeX\ \inverb|\new...| and
           % \LaTeX\ |\newlength|.
     newenvironment,
     text,% equivalent to the one above, covers all the commands defining
@@ -3438,7 +3600,7 @@
     % covers the \pk{xkeyval} homonym.
     dox,% a~shorthand for the one above.
     kvo% one of option defining commands of the \pk{kvoptions} package
-       % by Heiko Oberdiek (a~package available o~CTAN in the
+       % 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:
@@ -3535,7 +3697,7 @@
 }
 
 % The case when the right bracket is next to us is special because it
-% is already touched by |\futurelet| (of CSs scanning macro's
+% is already touched by |\futurelet| (of \acro{CS}s scanning macro's
 % \cs{@ifnextcat}), therefore we need a~`future' test. 
 \def\gmd@adef@checklbracket{%
   \@ifnextchar[{\gmd@adef@scanKVpref}\gmd@charbychar}% note that
@@ -3710,17 +3872,6 @@
 % \label{gmd@doindexingtext 2nd use}
   \@xa\do\@xa{\macro@pname}}
 
-
-%^^A %\iffalse if we decided to manage \verbatimchar
-%^^A \iffalse
-%^^A   \if\verbatimchar\macro@pname% cf. lines \ref{3039}--\ref{3049}
-%^^A     \def\im@firstpar{[$]}%^^A$
-%^^A   \else\def\im@firstpar{}%
-%^^A   \fi
-%^^A   \@xa \index@macro\im@firstpar\macro@iname\macro@pname
-%^^A \fi
-%^^A %\fi
-%^^A %
 % \stanza
 
 % So we have implemented automatic detection of definitions. Let's now
@@ -3870,7 +4021,7 @@
 % 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
+% its first occurence shall fire the detector and mark next \acro{CS} or
 % worse, shall make the detector expect some arguments that it won't
 % find. 
 
@@ -3927,7 +4078,7 @@
 % 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.
+% argument but that is harmless I~suppose until we have millions of \acro{CS}s.
 \def\ResumeDefining{\begingroup
   \MakePrivateLetters
   \gmd@ResumeDfng}
@@ -3939,7 +4090,7 @@
   \endgroup}
 
 
-% \subdivision{Indexing of CSs}
+% \subdivision{Indexing of \acro{CS}s}
 % 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
@@ -3976,7 +4127,7 @@
         \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).
+        % index not a~\acro{CS}).
         \encapchar\IndexRefCs}% 
       \@xa\special@index\@xa{\@tempa}% We give the
       % indexing macro the argument expanded so that \pk{hyperref} may
@@ -4081,16 +4232,17 @@
 % 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 (|\SelfInclude|d) driver file to be `usage', see codeline
-% \ref{UsgHack} of \file{gmdocDoc.tex}.
+% 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
+% Now let's |\def| the macros declaring a~\acro{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.
+% them are for marking environments and \emph{implicit} \acro{CS}s.
 
 \outer\def\DefIndex{\begingroup
   \MakePrivateLetters
@@ -4118,12 +4270,12 @@
   % \LaTeX\ \inverb|\@namedef| macro could not be used since it's not `long'.
   % \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~control sequence. But when it can be a~\acro{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
+% either 0 or 1. It is the information whether this entry is a~\acro{CS} or
 % not.
 
 \long\def\@usgentryze#1{%
@@ -4166,9 +4318,9 @@
 % 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
+  \@xa\quote@mname\macro@pname\relax% we process the \acro{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
+  % iterating macro's stopper. The scanned \acro{CS}'s quoted name shall be the
   % expansion of |\macro@iname|.
   \if\verbatimchar\macro@pname
     \def\im@firstpar{[$]}%^^A$
@@ -4228,7 +4380,7 @@
   {\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.
+    % an environment's name, but we will before a~\acro{CS}'s name.
     \do@properindex% see line \ref{do@properindex}.
     \index@macro\macro@iname\macro@pname}}
 
@@ -4247,7 +4399,7 @@
 % 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
+% But we wish the \acro{CS}s not only to be indexed special way but also
 % to be put in marginpars. So:
 \outer\def\CodeMarginize{\begingroup
   \MakePrivateLetters
@@ -4322,13 +4474,13 @@
 
 % 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
+% \acro{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)
+% (another \acro{CS} than we wished)
 % (because |\@ifstarl| establishes the |\catcode|s for the next token):
   \@ifstarl{\MakePrivateOthers\Code@DefEnvir}{\Code@DefMacro}}
 
@@ -4386,9 +4538,9 @@
 % 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
+% between these and the commands to declare a~\acro{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
+% \acro{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{%
@@ -4416,10 +4568,10 @@
   \@xa\addtomacro\@xa\envirs@toindex\@xa{\@tempa}}
 
 
-% And now a~command to mark a~`usage' occurrence of a~CS, environment
+% And now a~command to mark a~`usage' occurrence of a~\acro{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.
+% has plain and starred version, first for \acro{CS}s appearing explicitly and the
+% latter for the strings and \acro{CS}s appearing implicitly.
 \def\TextUsage{\begingroup
   %\label{TextUsage}
   \MakePrivateLetters
@@ -4481,7 +4633,7 @@
 % a~light condensed typewriter font, it's set in \pk{gmdocc} class.)
 \let\marginpartt\tt
 
-% If we count all lines then the index entries for CSs and
+% If we count all lines then the index entries for \acro{CS}s 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
@@ -4506,7 +4658,7 @@
 % char will be restored at |\end{macrocode}|. And to add the vertical
 % spaces.
 %
-% ^^A~\NoEOF so far OK
+% ^^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 :-)\,.
@@ -4526,7 +4678,7 @@
 
 \newenvironment*{macrocode}{%\label{macrocode}
   \if@codeskipput\else\par\addvspace\CodeTopsep\@codeskipputgtrue\fi
-  \CodeSpacesBlank\QueerEOL}%^^A\docstrips
+  \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
@@ -4628,10 +4780,9 @@
 % case that is).
 
 %    \begin{oldmc}
-\bgroup\catcode`\%\active
-\firstofone{\egroup
-\def\docstrips@percent{\catcode`\%\active
-  \let%\gmd@codecheckifds}}
+\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
@@ -4666,11 +4817,11 @@
 % \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 OK
+  % 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.
+  % a~letter and therefore such a~starred version is just one \acro{CS}.
   % However, in \pk{doc.dtx} occur \env{macro}s that mark
-  % \emph{implicit} definitions i.e., such that the defined CS is not
+  % \emph{implicit} definitions i.e., such that the defined \acro{CS} is not
   % scanned in the subsequent code.
 %
 % \begin{macro*}{macro*}
@@ -4747,7 +4898,7 @@
     \csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname{%
       \@nx\g@relaxen
       \csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname}% Why does it
-    % work despite it shouldn't? Because when the CS got with
+    % work despite it shouldn't? Because when the \acro{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.
@@ -4773,11 +4924,11 @@
 
 
 %\subdivision[Index Exclude List]{\gmhypertarget{Index Exclude List}}
-% We want some CSs not to be indexed, e.g., the \LaTeX\
+% We want some \acro{CS}s 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
+% the list of expelled \acro{CS}s. Here we'll deal another way. For each \acro{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.}
@@ -4813,7 +4964,7 @@
       \csname gmd/iexcl/\@tempa\endcsname=\gmd@iedir% In the default
       % case explained e.g.\ by the macro's name, the last macro's
       % meaning is such that the test in line \ref{iexcltest} will
-      % turn false and the subject CS shall not be indexed.
+      % turn false and the subject \acro{CS} shall not be indexed.
       % We |\let| not |\def| to spare \TeX's memory.
       \afterfifi\dont@index
     \fi
@@ -4827,7 +4978,7 @@
 % \begin{CodeSpacesSmall}
 % \DoNotIndex\DoNotIndex \Define\DefaultIndexExclusions
 \DoNotIndex\{ \DoNotIndex\}% \label{DNIbraces}the index entries of
-% these two CSs would be rejected by MakeIndex anyway.
+% these two \acro{CS}s would be rejected by MakeIndex anyway.
 
 \begin{MakePrivateLetters}% Yes, |\DoNotIndex| does
   % |\MakePrivateLetters| on its own but No, it won't have any effect
@@ -4902,7 +5053,7 @@
     \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}.
+    % from \acro{CS}s like |\^^M|, see sec. \ref{Tasks}.
     \DoNotIndex{\addto@hook \addvspace}%
     \DoNotIndex{\CurrentOption}%
     \DoNotIndex{\emph \empty \firstofone}%
@@ -4931,7 +5082,7 @@
     \DoNotIndex{\@input@ \@input}%
     \DoNotIndex{\@latex@error \@mainaux \@nameuse}%
     \DoNotIndex{\@nomath \@oddfoot}%|%\@onlypreamble| should be indexed
-    % IMO.
+    % \acro{IMO}.
     \DoNotIndex{\@outerparskip \@partaux \@partlist \@plus}%
     \DoNotIndex{\@sverb \@sxverbatim}%
     \DoNotIndex{\@tempcnta \@tempcntb \@tempskipa \@tempskipb}%\\
@@ -4973,7 +5124,7 @@
 \fi
 
 
-% If we expelled so many CSs, someone may like it in general but
+% If we expelled so many \acro{CS}s, 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}
@@ -4984,13 +5135,13 @@
 % \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
+% we only redefine an auxiliary \acro{CS} and launch also |\dont@index| inner
 % macro.
 
 % And if a~user wants here make default exclusions and there do not
 % make them, \heshe\ may use the |\DefaultIndexExclusions| declaration
-% \himher self. This declaration OCSR, but anyway let's provide the
-% counterpart. It OCSR, too.
+% \himher self. This declaration \acro{OCSR}, but anyway let's provide the
+% counterpart. It \acro{OCSR}, too.
 %
 \def\UndoDefaultIndexExclusions{%
   \StoreMacro\DoNotIndex
@@ -5305,9 +5456,9 @@
   \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
+    \ifx\generalname#1% then we check whether a~\acro{CS}-entry is given
     % in the optional first argument or is it unchanged.
-      \ifx\last@defmark\relax\else% if no particular CS is
+      \ifx\last@defmark\relax\else% if no particular \acro{CS} is
       % specified in |#1|, we check whether |\last@defmark| contains
       % something and if so, we put it into |\@tempb| scratch macro.
         \@tempswatrue
@@ -5324,14 +5475,14 @@
         \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
+         %a~particular \acro{CS} is specified by it (if some day one
     % wishes to |\changes| |\generalname|, \heshe\ should type
     % |\changes[generalname]|\dots)
       \@tempswatrue
       {\escapechar\m@ne
         \xdef\@tempb{\string#1}}%
       \if\bslash\@xa\@firstofmany\string#1\relax\@@nil% we check
-      % whether |#1| is a~CS\dots
+      % whether |#1| is a~\acro{CS}\dots
         \def\gmd@glossCStest{1}%\dots\ and tell the glossary if so.
       \fi
       % ^^A~\@xa\quote@mname\@tempb\relax
@@ -5345,8 +5496,8 @@
         \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
+        % doesn't contain any \acro{CS} name (i.e., is empty) nor |#1|
+        % specifies a~\acro{CS}, the current
         % changes entry was done at top-level.  In this case we precede
         % it by |\generalname|.
           \@tempb
@@ -5670,8 +5821,8 @@
 % beginning of the source file's commentary for instance.
 \def\gmd@chschangeline{%
   \typeout{\xiipercent\space\string\chschange{%
-      \fileversion}{\the\year/\the\month/\the\day}{\the\c@CheckSum}}
-  \typeout{\xiipercent\space\string\chschange{\fileversion}{%
+      \csname fileversion\endcsname}{\the\year/\the\month/\the\day}{\the\c@CheckSum}}
+  \typeout{\xiipercent\space\string\chschange{\csname fileversion\endcsname}{%
       \@xa\@gobbletwo\the\year/\the\month/\the\day}{%\relax
       %  with two di\-g\-it year in case you use |\ChangesStart|.
       \the\c@CheckSum}}}
@@ -5723,7 +5874,7 @@
 % %\iffalse
 % \def\task#1#2{}
 % % What is this for? Probably to turn an obsolete command off. Or maybe
-% % a~TODO?
+% % a~\acro{TODO}?
 % % \fi
 
 %\subdivision{\cs{DocInclude} and the \pk{ltxdoc}-Like Setup}
@@ -5768,11 +5919,25 @@
   % 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
-  \docincludeaux
+  \gmd@docincludeaux
   \def\currentfile{gmdoc-IncludeFileNotFound.000}%
   \let\fullcurrentfile\currentfile
   \IfFileExists{#1#2.fdd}{\edef\currentfile{#2.fdd}}{% it's not \pk{.fdd},
@@ -5806,7 +5971,7 @@
   % \LaTeX). ^^A\if@ltxDocInclude
   \clearpage
   %^^A\fi
-  \if@filesw \gmd@writemauxinpaux{#2.aux}\fi% this strange macro with
+  \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
@@ -5815,8 +5980,8 @@
   \fi
   \if@tempswa \let\@auxout\@partaux 
     \if@filesw
-      \immediate\openout\@partaux #2.aux\relax% Yes, only |#2|. It's to
-      % create and process the partial \pk{.aux} files always in the main
+      \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}
@@ -5916,9 +6081,9 @@
          X\or Y\or Z\else\@ctrerr\fi}
 
 % A~macro that initialises things for |\DocInclude|.
-\def\docincludeaux{%
+\def\gmd@docincludeaux{%
   % We set the things for including the files only once.
-  \global\@relaxen\docincludeaux
+  \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.
@@ -5992,7 +6157,7 @@
     % for the file. If |\filediv| is lower you should rather rethink
     % the level of a~file in your documentation not redefine the two
     % divisions.
-  \fi}% end of |\docincludeaux|.
+  \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
@@ -6002,85 +6167,13 @@
   \@xa\let\@xa\filediv\csname#1\endcsname}
 % \changes{v0.98c}{06/9/10}{added and a~bug fixed in \cs{docincludeaux}}
 
-% \subdivision{\cs{SelfInclude}}
-%
-% I~needed to include the driver file into
-% a~documentation so I~wrote
-% a~macro in case I'll need it again or you'll need it.
-% We define it immediately i.e.,
-% without the |\catcode|s trick because it uses |\jobname| inside so
-% the filename will be all \catother\ anyway.
-\newcommand*{\SelfInclude}[2][.tex]{% As you guess, the optional |#1|
-  % is the jobname's extension. The second parameter is \emph{not} for
-  % the filename (note \emph{it's known:} as |\jobname|!), but
-  % \emph{for the stuff to be put at begin input.}
-  % \changes{v0.98a}{06/09/06}{added in response to the needs}
-  \AtBegInputOnce{#2}%
-  \gdef\HLPrefix{\filesep}%
-  \gdef\EntryPrefix{\filesep}% we define two rather kernel parameters
-  % etc.\ as in \inverb|\DocInclude|.
-  \relax
-  %^^A\if@ltxDocInclude
-  \clearpage
-  % ^^A\fi
-  \docincludeaux
-  \edef\currentfile{\jobname#1}%
-  \let\fullcurrentfile\currentfile
-  \def\GeneralName{\jobname\actualchar\pk{\jobname} }% for the
-  % changes history main level entry.
-  \ifnum\@auxout=\@partaux
-    \@latexerr{\string\DocInclude\space cannot be nested}\@eha
-  \else
-    \if@filesw
-      \gmd@writemauxinpaux{\jobname.auxx}% ^^A
-      % this queer macro allows |_| in the file names. In this
-      % particular case |\string\jobname| would do, but anyway we
-      % provide a~more general solution. Note the \pk{.auxx} extension
-      % used instead of \pk{.aux}. This is done to avoid an infinite
-      % recurrence of \inverb|\input|s.
-    \fi
-    \@tempswatrue
-    \if@partsw \@tempswafalse\edef\@tempb{\jobname}%
-      \@for
-      \@tempa:=\@partlist\do{\ifx\@tempa\@tempb\@tempswatrue\fi}%
-    \fi
-    \if@tempswa \let\@auxout\@partaux
-      \if@filesw
-        \immediate\openout\@partaux \jobname.auxx\relax
-        \immediate\write\@partaux{\relax}
-      \fi
-      % \begin{quotation}We need to save (and later
-      %   restore)\dots\end{quotation} 
-      \StoringAndRelaxingDo% provided by \pk{gmutils}
-      \gmd@doIndexRelated
-      \if@ltxDocInclude\part{\currentfile}%
-      \else\let\maketitle=\InclMaketitle
-      \fi
-      \if@ltxDocInclude\xdef@filekey\fi
-      \GetFileInfo{\currentfile}% it's my (GM) addition with the account
-      % of using file info in the included files' title etc.
-      \incl@DocInput{\fullcurrentfile}% originally just |\currentfile|, no
-      % difference in |\SelfInclude|.
-      \if@ltxDocInclude\else\xdef@filekey\fi% in 
-      % the default case we add new file to the file key \emph{after} the
-      % input because in this case it's files own |\maketitle| what
-      % launches the sectioning command that increases the counter.
-      % \par And here is the moment to restore the index-related commands.
-      \RestoringDo
-      \gmd@doIndexRelated
-      %^^A\if@ltxDocInclude
-      \clearpage% among others, causes the |\writes| to be executed which is
-      % crucial for proper toc-ing e.g.
-      %^^A\fi
-      \gmd@writeckpt{\jobname.x}% note the |.x| in the checkpoint
-      % used to distinguish this instance (input) of the driver file
-      % from its main instance.
-      \if@filesw \immediate\closeout\@partaux \fi
-    \else\@nameuse{cp@\jobname.x}% note |.x|: it's used for the same
-    % reason as above. 
-    \fi
-    \let\@auxout\@mainaux
-  \fi}% end of |\SelfInclude|.
+
+\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
@@ -6156,7 +6249,7 @@
     \if@twocolumn \twocolumn [\@maketitle ]%
     \else \newpage \global \@topnum \z@ \@maketitle \fi
 % \begin{quotation}For special formatting requirements (such as in
-% TUGboat), we use pagestyle |titlepage| for this; this is later defined
+% \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 
@@ -6352,15 +6445,11 @@
       ver@#2.\if P\@firstofmany#1\@@nil sty\else cls\fi}{#3}}}
 
 \def\gmd@docrescan#1{%
-  \newwrite\gmd@docrescanfile
-  \immediate\openout\gmd@docrescanfile=\jobname.docrescan\relax
-  {\newlinechar=`\^^M%
-    \immediate\write\gmd@docrescanfile{%
-      \xiipercent#1\xiipercent\@nx\NoEOF}%
-  }%
-  \immediate\closeout\gmd@docrescanfile
-  \@@input\jobname.docrescan 
-}
+% \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}}}
 
 
 % And, for the case the input file doesn't contain |\Provides...|,
@@ -6464,8 +6553,25 @@
   \@codeskipputgfalse\stanza}
 %
 % I~renew the \env{quotation} environment to make the fact of quoting
-% visible
-\renewenvironment{quotation}{\par``\ignorespaces}{\unskip''\par}
+% 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{\unskip''\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:
@@ -6502,8 +6608,8 @@
   \ifmmode\hbox\else\leavevmode\null\fi
   \bgroup
   \ttverbatim
-  \def\breakablexiispace{%
-    \discretionary{\xiispace}{\xiipercent\gmboxedspace}{\xiispace}}%
+  \def\breakablevisspace{%
+    \discretionary{\visiblespace}{\xiipercent\gmboxedspace}{\visiblespace}}%
   \def\breakbslash{%
     \discretionary{}{\xiipercent\gmboxedspace\bslash}{\bslash}}%
   \def\breaklbrace{%
@@ -6512,8 +6618,8 @@
       {\xiipercent\gmboxedspace}%
       {\xiilbrace}}%
   \gm@verb@eol
-  % ^^A  \@ifstar {\@sverb@chbsl}
-  % ^^A~ {\gmobeyspaces\frenchspacing\@sverb@chbsl}
+  %^^A  \@ifstar {\@sverb@chbsl}
+  %^^A~ {\gmobeyspaces\frenchspacing\@sverb@chbsl}
   \@sverb@chbsl% It's always with visible spaces.
 }
 
@@ -6534,11 +6640,11 @@
 % |\verb*| but the breakables of it break to |%| in the
 % lower line.
 %
-% TODO: make the space flexible (most probably it requires using sth.\
+% \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:
+% An optional hyphen for \acro{CS}s in the inline comment:
 \@ifundefined{+}{}{\typeout{^^Jgmdoc.sty: redefining \bslash+.}}
 \def\+{\discre{{\normalfont-}}{{\tt\xiipercent\gmboxedspace}}{}}
 %
@@ -6995,10 +7101,10 @@
 %
 % \stanza
 % The first but not least is that the author(s) of \docfm\ give the
-% CS marking commands non-macro arguments sometimes, e.g.,
+% \acro{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
+% means the \docfm-like commands will not look for the \acro{CS}'s occurrence
 % in the code but will mark the first codeline met.
 % \stanza
 %
@@ -7048,7 +7154,7 @@
 %   perfect.
 %   
 %   Marcin Woli\nacute ski suggests to add the marginpar clauses for the
-%   AMS classes as we did for the standard ones in the lines
+%   \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'.
@@ -7070,7 +7176,7 @@
 % cases. That's why \cs{makeindex} is launched by default in \gmdoc.}
 %
 % Do you use |\listoftables| and/or |\listoffigures| in your
-% documentations? If so, I~should `EOL-straighten' them like
+% 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
@@ -7089,25 +7195,39 @@
 % \ \par\vspace*{-\baselineskip}
 % 
 % \def\EOFMark{\<eof>}
-% \division{(No) \EOFMark} If the user doesn't wish the
-% documentation to be ended by \EOFMark, \heshe\
-% should end the file with a~comment ending with |\NoEOF| macro
-% defined below\footnote{Thanks to Bernd Raichle at Bacho\TeX\ 2006 ^^B
-%   Pearl Session where he presented \cs{input}ing a~file inside ^^B
+% \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| \acro{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| \acro{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}.}:
 %
 
-\bgroup\catcode`\^^M\active \firstofone{\egroup%
+\foone{\catcode`\^^M\active }{%
   \def\@NoEOF#1^^M{%
-    \@relaxen\EOFMark\@xa\@nx\endinput^^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 EOL and the latter gobbles the stuff till the EOL to
+% 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, |\NoEOF| has also the
-% |\endinput| effect. 
+% \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
@@ -7136,16 +7256,16 @@
 % \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
+% to define a~\acro{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~\acro{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}
+% for the marginpar \acro{CS}s 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
@@ -7190,11 +7310,15 @@
 % (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.}
+%
+%
 %
 % \Finale
 
 % (For my GNU Emacs:)
 %%% Local Variables: 
 %%% mode: doctex
-%%% TeX-master: "../../../../LaTeX/TeXGuru/gmdoc/gmdocDoc.tex"
 %%% End: 
-- 
cgit v1.2.3

