diff options
Diffstat (limited to 'Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty')
| -rw-r--r-- | Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty | 814 |
1 files changed, 498 insertions, 316 deletions
diff --git a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty index be0dbaefe66..819157962f4 100644 --- a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty +++ b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty @@ -60,13 +60,16 @@ % \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} +% % \ifnum\catcode`\@=11 % Why this test here---will come out in chapter -% \gmiflink{The Driver}. ^^A~( the very first line +% \gmiflink{The driver}. ^^A~( the very first line % ^^A and about coming out already! ;-) \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{gmdoc} - [2008/08/06 v0.99m a documenting package (GM)] + [2008/08/30 v0.99n a documenting package (GM)] \fi % % @@ -129,7 +132,7 @@ % \end{gmlonely} % % -% \subdivision{Contents of the \pk{gmdoc.zip} Archive} +% \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. @@ -144,7 +147,7 @@ % % % \begin{gmlonely} -% \subdivision{Compiling the Documentation} +% \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 @@ -199,7 +202,7 @@ % be installed on your computer by default. % %^^A\traceon -% % \subdivision{Bonus: \file{base} Drivers} +% % \subdivision{Bonus: \file{base} drivers} %^^A\traceoff % As a~bonus and example of \docfm-compatibility % there are driver files included @@ -239,7 +242,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 \acro{CS}s in the code maybe in the future.) +% 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 @@ -254,10 +257,10 @@ % % % -% \division{The User Interface} +% \division{The user interface} % % -% \subdivision{Used Terms} +% \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 @@ -268,17 +271,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{\acro{CS}}. +% 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{|\<\acro{CS}>|}|. +% |\@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~\acro{CS} but consisting possibly of more than one macro. I'll +% 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} @@ -312,7 +315,7 @@ % same sentence :-)\,. % % -% \subdivision{Preparing the Source File} +% \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 @@ -403,7 +406,7 @@ % \end{quotation} % % -% \subdivision{The Main Input Commands} +% \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 @@ -549,11 +552,11 @@ % 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 \acro{CS}s automatically +% verbatim, with the code lines numbered and the \CSs automatically % indexed (\pk{gmdoc.sty} options are in force). % % -% \subdivision{Package Options} +% \subdivision{Package options} % % As many good packages, this also provides some options: % \stanza @@ -599,7 +602,7 @@ % % \stanza % By default the \pk{makeidx} package is loaded and initialized and -% the \acro{CS}s occurring in the code are automatically +% 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. @@ -612,9 +615,9 @@ % line number, then the changes history too. % % \stanza -% 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 +% 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 @@ -661,7 +664,7 @@ % |codespacesgrey, codespacesblank| in \pk{gmdoc} options (in this % order). % -% \subdivision{The Packages Required} +% \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 @@ -799,7 +802,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 \acro{CS}s uderlying those +% 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|. % @@ -808,7 +811,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~\acro{CS}. The starred version (without +% 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 @@ -840,7 +843,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~\acro{CS} |\|\<KVOfamily>|@|\<optionname>. The default \<KVOfamily> is +% 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 @@ -865,29 +868,36 @@ % % 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. Later -% you can resume detection of it with -% \TextUsage\ResumeDefining\<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. +% resume detection with \TextUsage\ResumeAllDefining. Both +% declarations are |\global|. % % 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~\acro{CS} excluded from indexing (see -% section \gmiflink{Index Ex/Inclusions}), it will not be marked even +% 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, in the commentary before this |\def| write -% \TextUsage\UnDef. That will turn off the detection just for this one -% occurrence of |\def|. +% 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. To resume detection of |\def| you are provided -% also a~shorthand, \TextUsage\ResumeDef\ (but |\ResumeDefining\def| -% also works). +% \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 @@ -895,8 +905,8 @@ % % % -% \subdivision[Manual Marking the Macros and Environments]{^^B -% \gmhypertarget{Manual Marking the Macros and Environments}} +% \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 @@ -929,7 +939,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~\acro{CS}). +% 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 @@ -940,12 +950,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 \acro{CS} having been scanned in the +% 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~\acro{CS}). Therefore, if you want to mark a~definition +% 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 @@ -965,14 +975,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 \acro{CS}s, too. Currently, the most important difference +% |^^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 \acro{CS} (or whatever) at the beginning of its description, +% 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 @@ -1004,12 +1014,12 @@ % and mandatory argument) that only flushes its contents right. % % \stanza -% On the other hand, if you don't want to put a~\acro{CS} (or another +% 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~\acro{CS}), and the starred ones just take the +% (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|. % @@ -1026,13 +1036,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~\acro{CS} argument and the starred for all +% 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~\acro{CS} for \env{macro} and `whatever' for +% 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 @@ -1043,19 +1053,19 @@ % 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~\acro{CS} implicitly i.e., in such a~way that it +% 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-\acro{CS} +% (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}} +% \subdivision[Index ex/inclusions]{\gmhypertarget{Index ex/inclusions}} % % It's\label{IEIDeclarations} understandable\footnote{After reading ^^B( % \docfm's documentation ;-)\,.} that you don't @@ -1071,18 +1081,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 \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. +% 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 \acro{CS}s by default. If you don't like it, just set the +% 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 \acro{CS}s given in the +% declaration (\acro{OCSR}) that removes a~ban on all the \CSs given in the % argument, e.g., % \[|\DoIndex{\par \@@par \endgraf}|\] % @@ -1093,7 +1103,7 @@ % with the |indexallmacros| option. Both of these declarations \acro{OCSR}. % % -% \subdivision{The \ds\ Directives} +% \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 @@ -1112,7 +1122,7 @@ % for someone. % %^^A If you use the \TextUsage*{macrocode} environment, you don't have to -%^^A add any \acro{CS} to get \ds\ directive typeset properly: within +%^^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 @@ -1136,7 +1146,7 @@ %^^A latter, though). %^^A % -% \subdivision{The Changes History} +% \subdivision{The changes history} % % The \docfm's documentation reads: % \begin{quotation} @@ -1168,7 +1178,7 @@ % [\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} +% sec.~\gmiflink[IndexParams]{The parameters} % p.\,\pageref*{IndexParams}]. (The \LaTeX\ `glossary' % mechanism is used for the change entries.) % \end{quotation} @@ -1237,7 +1247,7 @@ % % \stanza % -% While scanning the \acro{CS}s in the code, \gmdoc\ counts them and prints +% 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 @@ -1260,7 +1270,7 @@ % states the check sum for version \<first brace> dated \<second ^^B % brace> was \<third brace>. % -% \subdivision{The Parameters} +% \subdivision{The parameters} % % The \pk{gmdoc} package provides some parameters specific to % typesetting the \TeX\ code: @@ -1301,7 +1311,8 @@ % 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. +% 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 @@ -1366,10 +1377,10 @@ % % 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 \acro{CS}, to the +% 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 +% 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. @@ -1406,18 +1417,18 @@ % \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 \acro{CS} and the entries -% indicating the \emph{definition} of the \acro{CS}. +% entries indicating the \emph{usage} of the \CS and the entries +% indicating the \emph{definition} of the \CS. % % The special formattings of `usage' and `def' index entries are -% determined by \TextUsage\UsgEntry\ and \TextUsage\DefEntry\ +% 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~\acro{CS} that will be put +% (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 @@ -1434,13 +1445,13 @@ % default, |\IndexMin|\equals\the\IndexMin. % % The text put at the beginning of the index is declared with -% a~one-argument \TextUsage\IndexPrologue. Its default text at current -% index option you may \gmiflink[DIPrologue]{admire} on page -% \pageref*{DIPrologue}.^^A +% 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 index ^^B -% prologue>|}|, but if you like the default and want only to add +% 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 @@ -1470,15 +1481,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 \acro{CS} name it should quote before +% 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 \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 +% 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|. % @@ -1504,7 +1515,7 @@ % but pass its argument to |\Finale|. % % -% \subdivision{The Narration Macros} +% \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} @@ -1533,7 +1544,7 @@ % verbatim and without a~backslash, e.g., |\env{an environment}| % produces \env{an environment}. % -% For usage in the in-line comments there are \TextUsage\incs\ and +% 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. @@ -1545,6 +1556,29 @@ % 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\ @@ -1687,12 +1721,17 @@ % 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 -% For an example driver file see chapter \gmiflink{The Driver}. +% For an example driver file see chapter \gmiflink{The driver}. % % -% \subdivision{A~Queerness of \cs{label}} +% \subdivision{A~queerness of \cs{label}} % % You should be loyally informed that |\label| in \gmdoc\ % behaves slightly @@ -1704,7 +1743,7 @@ % the last section, \emph{unlike} in the standard \LaTeX. % % -% \subdivision{\docfm-Compatibility} +% \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 @@ -1765,12 +1804,12 @@ % % \stanza % For a~more detailed discussion of what is \docfm-compatible and how, -% see the code section \gmiflink[doccompa]{\docfm-Compatibiliy}. +% see the code section \gmiflink[doccompa]{\docfm-compatibiliy}. % %^^A \docstrip %<*package> -% \division[The Driver Part]{\gmhypertarget{The Driver} Part} +% \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 @@ -1780,7 +1819,7 @@ %% \skiplines we skip the driver %\ifnum\catcode`\@=12 % -%\documentclass[outeroff,pagella]{gmdocc} +%\documentclass[outeroff, pagella, fontspec=quiet]{gmdocc} %\usepackage{eufrak}% for |\continuum| in the commentary. %\twocoltoc %\begin{document} @@ -1823,11 +1862,8 @@ % \CodeUsgIndex*{outeroff} \CodeUsgIndex*{mwrep} \documentclass[countalllines, codespacesgrey, 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. +pagella, fontspec=quiet]{gmdocc} + \twocoltoc \title{The \pk{gmdoc} Package\\ i.e., \pk{gmdoc.sty} and \pk{gmdocc.cls}} @@ -1892,7 +1928,7 @@ pagella]{gmdocc} % \StopEventually{\NoEOF} % % -% \division{The Code} +% \division{The code} % % For debug \catcode`\^^C=9\relax @@ -1912,18 +1948,18 @@ pagella]{gmdocc} % verbatim and with the bells and whistles. % % The bells and whistles are (optional) numbering of the codelines, -% and automatic indexing the \acro{CS}s, possibly with +% 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 \acro{CS}s. +% \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, +% \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 % @@ -1942,10 +1978,10 @@ pagella]{gmdocc} % in the comment layer, how to index and marginpar macros etc. % % -%\subdivision{The Package Options} +%\subdivision{The package options} % -\RequirePackage{gmutils}% includes redefinition of \incs{newif} to make -% the switches \incs{protected} +\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. % @@ -1992,7 +2028,7 @@ pagella]{gmdocc} % 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}). +% list properly (see sec.\ \gmiflink{Index exclude list}). \newif\if@indexallmacros @@ -2048,7 +2084,7 @@ pagella]{gmdocc} \ProcessOptions -% \subdivision{The Dependencies and Preliminaries} +% \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 @@ -2089,7 +2125,7 @@ pagella]{gmdocc} \RequirePackage{gmiflink} % And a~slight redefinition of \env{verbatim}, |\verb(*)| and % providing of |\MakeShortVerb(*)|. -\RequirePackage{gmverb}[2007/11/09] +\RequirePackage{gmverb}[2008/08/20] \if@noindex \AtBeginDocument{\gag@index}% for the latter macro see line @@ -2127,7 +2163,6 @@ pagella]{gmdocc} % \changes{v0.99a}{06/12/1}{split into the starred and unstarred % versions} % -% \Define\code@delim \def\CodeDelim{\@ifstar\Code@Delim@St\Code@Delim} \def\Code@Delim#1{% @@ -2197,7 +2232,7 @@ pagella]{gmdocc} % 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 +% 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 @@ -2209,10 +2244,9 @@ pagella]{gmdocc} \CodeTopsep=\stanzaskip \MacroTopsep=\stanzaskip \abovedisplayskip=\stanzaskip - %\nostanza - % \leftskip0sp \noindent |%\abovedisplayshortskip| - % remains untouched as it is 0.0\,pt plus 3.0\,pt by default.\par - % + %\nostanza \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 @@ -2262,21 +2296,25 @@ pagella]{gmdocc} % Since the stanza skips are inserted automatically most often (cf.\ lines % \ref{codeskip}, \ref{codeskip2}, \ref{codeskip3}, \ref{codeskip4}, % \ref{codeskip5}), sometimes you may need to forbid them. -\newcommand*\nostanza{% - \@codeskipputgtrue\@afternarrgfalse\@aftercodegtrue}% In the `code +\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. % -% -% To count the lines where they have begun not before them +%\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} |%<...|. +% 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 @@ -2285,7 +2323,7 @@ pagella]{gmdocc} % numbering is optional, 2.\ counting the line falsifies that switch % \emph{before} the first char.) % -% \subdivision{The Core} +% \subdivision{The core} % % Now we define main |\input|ing command that'll change catcodes. % The macros used by it are defined later. @@ -2372,10 +2410,10 @@ pagella]{gmdocc} % does |\ifx|). % -\protected\def\gmd@textEOL{ % a~space just like in normal \TeX. We put it first to - % cooperate with \inverb|\^^M|'s |\expandafter\ignorespaces|. It's no - % problem since a~space | |${}_{10}$ doesn't drive \TeX\ out of - % the vmode. +\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 @@ -2595,9 +2633,9 @@ pagella]{gmdocc} % repetition of the same ref-value (what would result in the % ``multiply defined labels'' warning).\par\ % The - % \incs{grefstepcounter} macro, defined in \pk{gmverb}, is + % \cs{grefstepcounter} macro, defined in \pk{gmverb}, is % a~global - % version of \incs{refstepcounter}, observing the redefinition + % version of \cs{ref\-step\-count\-er}, observing the redefinition % made % to \incs{refstepcounter} by \pk{hyperref}. @@ -2634,8 +2672,9 @@ pagella]{gmdocc} \def\skiplines{\bgroup \let\do\@makeother \dospecials % not \incs{@sanitize} because the - % latter doesn't recatcode braces and we want all to be quieten. - \catcode`\^^M\active + % 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{% @@ -2652,7 +2691,7 @@ pagella]{gmdocc} % % ^^A\special{color push gray 0.2645}% % A~verbatim group has already been opened by \cs{ttverb\+at\+im} and - % additional |\catcode|. + % 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? @@ -2680,11 +2719,17 @@ pagella]{gmdocc} % \DefIndex\gmd@texcodeEOL \let\gmd@texcodeEOL=^^M% for further checks inside |\gmd@charbychar|. \raggedright\leftskip=\CodeIndent% - \if@aftercode\gmd@nocodeskip1{iaC}\else\if@afternarr% - % ^^A~\def^^C{\showthe\hyphenpenalty\showthe\rightskip} - \if@codeskipput\else\gmd@codeskip1\@codeskipputgtrue\@aftercodegfalse\fi% - % \label{codeskip3} - \else\gmd@nocodeskip1{naN}\fi\fi% if now we are + \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% @@ -2694,7 +2739,7 @@ pagella]{gmdocc} \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 \acro{CS} to \incs{relax}. + % 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 @@ -2718,13 +2763,19 @@ pagella]{gmdocc} % hmode. \@aftercodegtrue% we want to know later that now we are % typesetting a~codeline. - %^^A\special{color push gray 0.2712}% before that penalty + \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. - }% -}% end of |\gmd@typesettexcode|'s definitions's group's |\firstofone|. + }% of |\gmd@typesettexcode|. +}% of |\foone\obeylines|. % % \stanza % @@ -2758,10 +2809,17 @@ pagella]{gmdocc} \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 O.K. - \par + % ^^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} @@ -2770,13 +2828,14 @@ pagella]{gmdocc} \def\gmd@eatlspace#1{% \ifx\gmd@texcodespace#1% \advance\gmd@ldspaceswd by\gmd@spacewd% we don't - % |\advance| it |\global|ly because the current group may be closed - % iff we meet |%| and then we'll won't indent the line anyway. + % \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@ - \gmd@continuenarration#1%\label{ContNarr2} + \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}% @@ -2878,10 +2937,12 @@ pagella]{gmdocc} % we wish to print |%| (or another code delimiter). \def\gmd@percenthack{% - \ifprevhmode\code@delim\aftergroup\space% We add a~space after |%|, + \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 @@ -2903,7 +2964,10 @@ pagella]{gmdocc} % enter the narration. \the\gmd@preverypar}% \@ifnextchar{\gmd@textEOL}{% - \@dsdirgfalse\par\ignorespaces}{\gmd@narrcheckifds}}% + %^^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}% @@ -2922,7 +2986,9 @@ pagella]{gmdocc} \@afternarrgfalse\@aftercodegtrue \ifhmode\@codeskipputgfalse\fi \@ifnextchar{\gmd@textEOL}{% - {\raggedright\gmd@endpe\par}% without |\raggedright| this |\par| + %^^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 @@ -2934,14 +3000,21 @@ pagella]{gmdocc} % In the other case both |\gmd@endpe|s do the same % and |\par| between them does nothing. % \DefIndex\par - \def\par{% + \def\par{% the narration \cs{par}. \ifhmode% (I~added this |\ifhmode| as a~result of a~heavy % debug.) -%^^A \typeout{par of 1766 in hmode \on@line}% + \if@afternarr\if@aftercode + \unless\if@ilgroup\bgroup\@ilgrouptrue\fi + \ifilrr\gmd@setilrr\fi + \fi\fi \@@par \if@afternarr \if@aftercode - \if@codeskipput\else\gmd@codeskip2\@aftercodegfalse\@codeskipputgtrue\fi + \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 @@ -2953,9 +3026,7 @@ pagella]{gmdocc} \everypar=\@xa{% \@xa\@codetonarrskip\the\gmd@preverypar}% \let\par\@@par% -%^^A else -%^^A \typeout{par of 1766 in NOT hmode \on@line}% - \fi}% + \fi}% of \cs{par}. \gmd@endpe\ignorespaces}} % As we announced, we play with |\leftskip| inside the verbatim @@ -2976,9 +3047,40 @@ pagella]{gmdocc} %^^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} +% \subdivision{Numbering (or not) of the lines} % % Maybe you want codelines to be numbered and maybe you want to % reset the counter within sections. @@ -3029,7 +3131,9 @@ pagella]{gmdocc} % 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} +\newcommand*\gmd@codeskip[1]{% + \@@par\addvspace\CodeTopsep + \@codeskipputgtrue\@nostanzagfalse} %\label{codeskip2} % Sometimes we add the |\CodeTopsep| vertical space in @@ -3042,6 +3146,9 @@ pagella]{gmdocc} % \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}. @@ -3071,25 +3178,27 @@ pagella]{gmdocc} % To insert vertical glue between the \TeX\ code and the narration % we'll be playing with |\everypar|. More precisely, we'll add a~macro % that the |\parindent| box shall move and the glue shall put. -\long\def\@codetonarrskip{% +\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. + % We are at the beginning of |\everypar|, i.e., \TeX\ has just entered + % the hmode and put the |\parindent| box. Let's remove it then. {\setbox0=\lastbox}% -% Now we can put the vertical space and state we are not `aftercode'. - \gmd@codeskip4\@codeskipputgtrue - %\label{codeskip5} - \leftskip\TextIndent% this line is a~patch against - % a~bug-or-feature that in certain cases the narration |\leftskip| - % is left equal the code leftskip. (It happens when there're - % subsequent code lines after an inline comment not ended with - % an explicit |\par|.) - \else\gmd@nocodeskip4{naC}% - \fi% + % Now we can put the vertical space and state we are not `aftercode'. + \gmd@codeskip4% + % \label{codeskip5} + \else\gmd@nocodeskip4{naC}% + \fi \fi - \fi\@aftercodegfalse} + \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 +} % But we play with |\everypar| for other reasons too, and while restoring it, % we don't want to add the |\@codetonarrskip| macro infinitely many @@ -3124,7 +3233,7 @@ pagella]{gmdocc} % |\if|s or |\fi|s. % % -% \subdivision[Life Among Queer \acro{EOL}s]{Life Among Queer \gmhypertarget[afc]{\acro{EOL}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 @@ -3180,7 +3289,7 @@ pagella]{gmdocc} \QueerCharOne \AtBegInput{\@ifEOLactive{\catcode`\^^A\active}\QueerCharOne}% see note -% after line \ref{QCh2}. +% after line \ref{QCh2}.\ilrr % As I~suggested in the users' guide, |\StraightEOL| and |\QueerEOL| are @@ -3239,11 +3348,17 @@ pagella]{gmdocc} % \gmhypertarget[closingspace]{To make} |^^M| behave more like a~`normal' % lineend I~command it to add a~| |${}\subs{10}$ at first. It works -% but has one uwelcome feature: if the line has nearly |\textwidth|, +% 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\par}} +\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. @@ -3275,7 +3390,7 @@ pagella]{gmdocc} % 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 |\ | \acro{CS} by the user, just +% account of a~possibility of redefining the |\ | \CS by the user, just % like in normal \TeX. @@ -3318,14 +3433,14 @@ pagella]{gmdocc} \@ifEOLactive{^^M}{\@ehc}}}}% \endgroup -% \subdivision{Macros for Marking The Macros} +% \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 \acro{CS}. +% but with separate control sequences for each excluded \CS. % % \stanza % @@ -3360,7 +3475,7 @@ pagella]{gmdocc} \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> \acro{CS} as an argument. It's an invariant assertion that +% 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 @@ -3421,7 +3536,7 @@ pagella]{gmdocc} % 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 - % \acro{CS}.\par + % \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| @@ -3454,8 +3569,8 @@ pagella]{gmdocc} % 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~\acro{CS} name---we want to avoid scanning -% |\command*argum| as one \acro{CS}. +% 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 @@ -3498,13 +3613,6 @@ pagella]{gmdocc} \fi}% \@xa\gmd@in@@#2#1\gmd@in@@}% -%^^A % To hide the Booleans from \TeX\ in some contexts define -%^^A \def\gmd@@iftrue{\iftrue} -%^^A \def\gmd@@iffalse{\iffalse} -%^^A \def\gmd@@fi{\fi} -%^^A % A~try to |\let| instead of |\def| resulted with the `incomplete if' -%^^A % error: \TeX\ looks at the meanings not the names while counting -%^^A % |\if|s. % This macro is used for catching chars that are % MakeIndex's controls. How does it work? @@ -3513,7 +3621,7 @@ pagella]{gmdocc} % |\uccode| trick: assigns the argument as the uppercase code of the % digit 9 and does further work in the |\uppercase|'s scope so the % digit 9 (a~benchmark `other') is substituted by |#1| but the -% |\catcode| remains so |\gmd@ifinmeaning| gets |\quote@char|'s |#1| +% |\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: @@ -3557,10 +3665,10 @@ pagella]{gmdocc} % 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~\acro{CS} or not. +% whether a~history entry is a~\CS or not. \newcommand*\finish@macroscan{%\label{506}\par - % First we check if the current \acro{CS} is not just being defined. The + % 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 @@ -3570,36 +3678,42 @@ pagella]{gmdocc} \@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 \acro{CS}. + % true just for this \CS. \fi - % We have the \acro{CS}'s name for indexing in |\macro@iname| and + % 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| \acro{CS} + % comes before the macro's name: when it was reverse, the |\tt| \CS % turned this test true and left the |\verbatimchar| what resulted % with `|\+tt|' typeset. Note that this test should turn true iff % the scanned macro name shows to be the default % |\verb|'s delimiter. In such a~case we give - % |\verb| another delimiter, namely |$|: - \def\im@firstpar{[$]}%^^A$ - \else\def\im@firstpar{}\fi - \@xa \index@macro\im@firstpar\macro@iname\macro@pname - % \label{3049} - \maybe@marginpar\macro@pname - \macro@pname - \let\next\gmd@charbychar - \gmd@detectors% \label{519} for automatic detection of - % definitions. Defined and - % explained in the next section. It redefines - % |\next| if detects a~definition command amd thus - % sets the switch of line \ref{506} true. - \next -} + % |\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 \acro{CS}: +% 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{% @@ -3618,16 +3732,16 @@ pagella]{gmdocc} % Since version 0.99g we introduce automatic detection of definitions, % it will be implemented in the next section. The details of indexing -% \acro{CS}s are implemented in the section after it. +% \CSs are implemented in the section after it. % % \subdivision{Automatic detection of definitions} % % To begin with, let's introduce a~general declaration of a~defining -% command. |\DeclareDefining| comes in two flavours: `saut\eacute', +% 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~\acro{CS}. The star version without the optional argument declares +% 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. @@ -3657,7 +3771,7 @@ pagella]{gmdocc} % % \subsubdivision{\cs{DeclareDefining} and the detectors} % -% Note that the main argument of the next declaration should be a~\acro{CS} +% 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 @@ -3687,6 +3801,7 @@ pagella]{gmdocc} \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}% @@ -3695,7 +3810,7 @@ pagella]{gmdocc} % \label{550} \of\gmd@detectors{}{% \@xa\gaddtomacro\@xa\gmd@detectors\@xa{% - \csname gmd@detect@\gmd@adef@currdef\endcsname}}% we add a~\acro{CS}\\ + \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. @@ -3710,7 +3825,7 @@ pagella]{gmdocc} \@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 \acro{CS} to + \SMglobal\StoreMacro*{gmd@detect@\gmd@adef@currdef}% we store the \CS to % allow its temporary discarding later. } @@ -3785,7 +3900,7 @@ pagella]{gmdocc} def, newcommand, cs,% equivalent to the two above, covers all the cases of defining - % a~\acro{CS}, including the \PlainTeX\ \inverb|\new...| and + % a~\CS, including the \PlainTeX\ \inverb|\new...| and % \LaTeX\ |\newlength|. newenvironment, text,% equivalent to the one above, covers all the commands defining @@ -3875,7 +3990,7 @@ pagella]{gmdocc} \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. + % in \inverb|\gmd@adef@dfKVpref| is global.\ilrr \gmd@adef@checklbracket} % The detector of \pk{xkeyval} |\DeclareOptionX|: @@ -3895,12 +4010,12 @@ pagella]{gmdocc} } % The case when the right bracket is next to us is special because it -% is already touched by |\futurelet| (of \acro{CS}s scanning macro's +% is already touched by |\futurelet| (of \CSs scanning macro's % \cs{@ifnextcat}), therefore we need a~`future' test. \def\gmd@adef@checklbracket{% \@ifnextchar[{\gmd@adef@scanKVpref}\gmd@charbychar}% note that % the prefix scanning macro gobbles its first argument (undelimited) -% which in this case is |[|. +% which in this case is |[|.\ilrr %^^A]]} % After a~|\DeclareOptionX|-like defining command not only the prefix @@ -4043,12 +4158,12 @@ pagella]{gmdocc} \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 + \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.) + % so \cs{ifnum} gets |1=0\relax|---false.)\ilrr \edef\gmd@adef@altindex{% \gmd@adef@altindex \csname gmd@adef@KVpref@\gmd@adef@currdef \endcsname}% @@ -4083,6 +4198,9 @@ pagella]{gmdocc} %^^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 @@ -4090,22 +4208,18 @@ pagella]{gmdocc} % Therefore we define the next declaration. It turns the next % occurence of |\def| off (only the next one). -\def\UnDef{% - \gdef\gmd@detect@def{% - \ifx\gmd@detectname@def\macro@pname - \def\next{\SMglobal\RestoreMacro\gmd@detect@def}% ^^A we define - % ^^A \inverb|\next| not restore the macro here just in case of - % ^^A multiple declaration of |\def| (in that case there would be - % ^^A multiple occurences of the macro to be restored in the carrier - % ^^A \inverb|\gmd@detectors| and we wish - % ^^A all of them not to fire this one time) That's probably too - % ^^A much care since there's the test in line \ref{550}. - \fi}% - } +\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{\HideDefining\def\relaxen\UnDef} +\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} @@ -4210,7 +4324,7 @@ pagella]{gmdocc} %^^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~ 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, @@ -4219,7 +4333,7 @@ pagella]{gmdocc} % 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 \acro{CS} or +% 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. @@ -4262,8 +4376,10 @@ pagella]{gmdocc} % 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 - \Hide@Dfng} + \@ifstarl\Hide@DfngOnce\Hide@Dfng} \def\Hide@Dfng#1{%%\UnDef \escapechar\m@ne @@ -4272,11 +4388,39 @@ pagella]{gmdocc} \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 \acro{CS}s. +% argument but that is harmless I~suppose until we have millions of \CSs. \def\ResumeDefining{\begingroup \MakePrivateLetters \gmd@ResumeDfng} @@ -4288,7 +4432,7 @@ pagella]{gmdocc} \endgroup} -% \subdivision{Indexing of \acro{CS}s} +% \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 @@ -4325,7 +4469,7 @@ pagella]{gmdocc} \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~\acro{CS}). + % 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 @@ -4383,7 +4527,7 @@ pagella]{gmdocc} \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. + % to be the entry prefix.\ilrr \let\gmdindexpagecs=\gmdindexrefcs \else % \DefIndex\gmdindexrefcs @@ -4435,13 +4579,13 @@ pagella]{gmdocc} % \ref*{Driver}. -% Now let's |\def| the macros declaring a~\acro{CS} to be indexed +% 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} \acro{CS}s. +% them are for marking environments and \emph{implicit} \CSs. \outer\def\DefIndex{\begingroup \MakePrivateLetters @@ -4466,15 +4610,15 @@ pagella]{gmdocc} \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'. + % \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~\acro{CS}, we |\@defentryze| in + % 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~\acro{CS} or +% either 0 or 1. It is the information whether this entry is a~\CS or % not. \long\def\@usgentryze#1{% @@ -4517,9 +4661,9 @@ pagella]{gmdocc} % 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 \acro{CS}'s + \@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 \acro{CS}'s quoted name shall be 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$ @@ -4579,7 +4723,7 @@ pagella]{gmdocc} {\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~\acro{CS}'s name. + % 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}} @@ -4598,7 +4742,7 @@ pagella]{gmdocc} % 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 \acro{CS}s not only to be indexed special way but also +% 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 @@ -4673,13 +4817,13 @@ pagella]{gmdocc} % For convenience we'll make the `private letters' first not to bother % ourselves with |\makeatletter| for instance when we want mark some -% \acro{CS}. And |\MakePrivateOthers| for the environment and other string +% \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 \acro{CS} than we wished) +% (another \CS than we wished) % (because |\@ifstarl| establishes the |\catcode|s for the next token): \@ifstarl{\MakePrivateOthers\Code@DefEnvir}{\Code@DefMacro}} @@ -4712,7 +4856,7 @@ pagella]{gmdocc} \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. + \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{}% @@ -4760,9 +4904,9 @@ pagella]{gmdocc} % 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~\acro{CS} marking: the latter +% 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 -% \acro{CS} to be marked. We separate indexing from marginizing to leave +% \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{% @@ -4790,10 +4934,10 @@ pagella]{gmdocc} \@xa\addtomacro\@xa\envirs@toindex\@xa{\gmu@tempa}} -% And now a~command to mark a~`usage' occurrence of a~\acro{CS}, environment +% 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 \acro{CS}s appearing explicitly and the -% latter for the strings and \acro{CS}s appearing implicitly. +% 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 @@ -4855,7 +4999,7 @@ pagella]{gmdocc} % 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 \acro{CS}s and +% 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 @@ -5042,9 +5186,9 @@ pagella]{gmdocc} % 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 \acro{CS}. + % 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 \acro{CS} is not + % \emph{implicit} definitions i.e., such that the defined \CS is not % scanned in the subsequent code. % % \begin{macro*}{macro*} @@ -5088,7 +5232,7 @@ pagella]{gmdocc} % 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|. + % so. \inverb|\gmu@tempa| is used in \inverb|\gmd@ifsingle|. \ilrr \gmd@ifsingle#3\@@nil \afterfi{\@xa#1\gmu@tempb}% \else @@ -5116,23 +5260,24 @@ pagella]{gmdocc} % 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{% - \stepnummacro\gmd@oncenum + \global\advance\gmd@oncenum\@ne \@xa\long\@xa\edef% \CodeUsgIndex*{NeuroOncer} - \csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname{% + \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname{% \@nx\g@relaxen - \csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname}% Why does it - % work despite it shouldn't? Because when the \acro{CS} got with + \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. - \@xa\addtomacro\csname gmd/evp/NeuroOncer\gmd@oncenum\endcsname{#1}% + % \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\gmd@oncenum\endcsname}% + \csname gmd/evp/NeuroOncer\the\gmd@oncenum\endcsname}% } -\nummacro\gmd@oncenum% We store the number uniquifying the auxiliary -% macro in a~macro to save count registers (cf.\ \pk{gmutils} -% sec.\ \gmiflink{To Save Precious Count Registers}). +\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 @@ -5146,12 +5291,12 @@ pagella]{gmdocc} % -%\subdivision[Index Exclude List]{\gmhypertarget{Index Exclude List}} -% We want some \acro{CS}s not to be indexed, e.g., the \LaTeX\ +%\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 \acro{CS}s. Here we'll deal another way. For each \acro{CS} +% 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.} @@ -5167,7 +5312,7 @@ pagella]{gmdocc} \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. + % exclusions easily later.\ilrr \dont@index#1.} % \DefIndex\dont@index @@ -5187,7 +5332,7 @@ pagella]{gmdocc} \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 \acro{CS} shall not be indexed. + % turn false and the subject \CS shall not be indexed. % We |\let| not |\def| to spare \TeX's memory. \afterfifi\dont@index \fi @@ -5201,7 +5346,7 @@ pagella]{gmdocc} % \begin{CodeSpacesSmall} % \DoNotIndex\DoNotIndex \Define\DefaultIndexExclusions \DoNotIndex\{ \DoNotIndex\}% \label{DNIbraces}the index entries of -% these two \acro{CS}s would be rejected by MakeIndex anyway. +% 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 @@ -5276,7 +5421,7 @@ pagella]{gmdocc} \DoNotIndex{\@@input \@auxout \@currentlabel \@dblarg}% \DoNotIndex{\@ifdefinable \@ifnextchar \@ifpackageloaded}% \DoNotIndex{\@indexfile \@let@token \@sptoken \^}% the latter comes - % from \acro{CS}s like |\^^M|, see sec. \ref{Tasks}. + % from \CSs like |\^^M|, see sec. \ref{Tasks}. \DoNotIndex{\addto@hook \addvspace}% \DoNotIndex{\CurrentOption}% \DoNotIndex{\emph \empty \firstofone}% @@ -5330,8 +5475,8 @@ pagella]{gmdocc} \DoNotIndex{\textsc \textup \toks@ \ttfamily \vbox}% % \changes[\DoNotIndex]{v0.97}{06/09/04}{Excluding some star-versions of % commands} - % \nostanza - % |%%\DoNotIndex{\begin*}| maybe in the future, if the idea gets + % \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} @@ -5347,7 +5492,7 @@ pagella]{gmdocc} \fi -% If we expelled so many \acro{CS}s, someone may like it in general but +% 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} @@ -5358,7 +5503,7 @@ pagella]{gmdocc} % \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 \acro{CS} and launch also |\dont@index| inner +% 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 @@ -5378,7 +5523,7 @@ pagella]{gmdocc} % % -% \subdivision{Index Parameters} +% \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 @@ -5487,7 +5632,7 @@ pagella]{gmdocc} % % % -% \subdivision{The \ds\ Directives} +% \subdivision{The \ds\ directives} % %^^A \StraightEOL %^^A \iffalse ^^A~ this passage is obsoleted @@ -5610,7 +5755,7 @@ pagella]{gmdocc} \def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026 } -% \subdivision{The Changes History} +% \subdivision{The changes history} % % The contents of this section was copied \*verbatim from the % \docfm's documentation, with only smallest necessary changes. Then ^^A(( @@ -5683,33 +5828,33 @@ pagella]{gmdocc} \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~\acro{CS}-entry is given + \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 \acro{CS} is + \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, |\last@defmark| came out with |\| at the - % beginning (which resulted with |\\|\<name> in the change + % \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 - % |\last@defmark|\equals|{\}| (what would happen if - % a~definition of |\\| was marked in new way \gmdoc ing).%^^A] + % \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 \acro{CS} is specified by it (if some day one + %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 |#1| is a~\acro{CS}\dots + % 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 @@ -5723,8 +5868,8 @@ pagella]{gmdocc} \fi #2\levelchar% \if@tempswa% If the macro |\last@defmark| - % doesn't contain any \acro{CS} name (i.e., is empty) nor |#1| - % specifies a~\acro{CS}, the current + % 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 @@ -5970,7 +6115,7 @@ pagella]{gmdocc} %^^A%%\end{verbatim} %^^A%% % skipped definitions of dotted fills\fi % -% \subdivision{The Checksum} +% \subdivision{The checksum} % % % \docfm\ provides a~checksum mechanism that counts the backslashes @@ -6061,11 +6206,11 @@ pagella]{gmdocc} % beginning of the source file's commentary for instance. \def\gmd@chschangeline{% \xiipercent\space\string\chschange - {\csname fileversion\endcsname}% + {\@ifundefined{fileversion}{v???}{\fileversion}}% {\the\year/\the\month/\the\day}% {\the\c@CheckSum}^^J% \xiipercent\space\string\chschange - {\csname fileversion\endcsname}% + {\@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} @@ -6120,7 +6265,7 @@ pagella]{gmdocc} % % a~\acro{TODO}? % % \endskiplines -%\subdivision{\cs{DocInclude} and the \pk{ltxdoc}-Like Setup} +%\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 @@ -6581,7 +6726,7 @@ pagella]{gmdocc} % 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|.\tOnLine + % 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|) @@ -6644,7 +6789,7 @@ pagella]{gmdocc} \newcommand*\SkipFilesAuthors{\@fshdafalse} -% \subdivision{The File's Date and Version Information} +% \subdivision{The file's date and version information} % Define |\filedate| and friends from info in the @@ -6844,7 +6989,14 @@ pagella]{gmdocc} % \chunkskip % For some mysterious reasons |\noindent| doesn't work with the first % (narrative) paragraph after the code so let's work it around: -\newcommand*\gmdnoindent{\leavevmode\hskip-\parindent} +\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 @@ -6867,9 +7019,16 @@ pagella]{gmdocc} \newcommand*\gmboxedspace{\hbox{\normalfont{ }}} -\newcommand*\gmd@nlperc[1][]{% +\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{\gmu@tempa}{{\tt\xiipercent\gmboxedspace}}{\gmu@tempb}% + \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][]{% @@ -6926,13 +7085,26 @@ pagella]{gmdocc} % else than |\discretionary|). %\stanza % -% An optional hyphen for \acro{CS}s in the inline comment: +% An optional hyphen for \CSs in the inline comment: \@ifundefined{+}{}{\typeout{^^Jgmdoc.sty: redefining \bslash+.}} \def\+{\discre{{\normalfont-}}{{\tt\xiipercent\gmboxedspace}}{}} % % -\@ifundefined{ds}{\def\ds{DocStrip}}{} +\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 @@ -6991,14 +7163,22 @@ pagella]{gmdocc} % An environment to display the meaning of macro parameters: its % items are automatically numbered as |#1|, |#2| etc. \newenvironment*{enumargs} - {\enumerate - \@namedef{label\@enumctr}{% - \cs[]{\#\csname the\@enumctr\endcsname }}} - {\endenumerate} +% \changes{v0.99n}{2008/08/21}{developed for the case of inline +% comment} +{\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}{% + \cs[]{\if@aftercode\code@delim\space\fi + \#\csname the\@enumctr\endcsname }}} +{\endenumerate} % -% \subdivision[\docfm-Compatibility]{\gmhypertarget[doccompa]{\docfm-Compatibility}} +% \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 @@ -7281,7 +7461,7 @@ pagella]{gmdocc} % verbatim and put into \pk{gmutils}, too. (|\DeclareRobustCommand| % doesn't issue an error if its argument has been defined, it only % informs about redefining.) -\DeclareRobustCommand*\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} +\pdef\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} % \changes{v0.98}{06/09/05}{made robust.} @@ -7382,10 +7562,10 @@ pagella]{gmdocc} % % \stanza % The first but not least is that the author(s) of \docfm\ give the -% \acro{CS} marking commands non-macro arguments sometimes, e.g., +% \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 \acro{CS}'s occurrence +% means the \docfm-like commands will not look for the \CS's occurrence % in the code but will mark the first codeline met. % \stanza % @@ -7419,7 +7599,7 @@ pagella]{gmdocc} % % % -% \division{Polishing, Development and Bugs} +% \division{Polishing, development and bugs} % % \begin*{bulletpars} % \everypar{$\bullet$ } @@ -7479,14 +7659,14 @@ pagella]{gmdocc} % % 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 +% 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| \acro{CS} or end +% `\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 @@ -7536,16 +7716,16 @@ pagella]{gmdocc} % \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~\acro{CS} and the corresponding test set to check if it's +% 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~\acro{CS} to percent at the beginning of the lower line. Moreover, fixing +% 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 \acro{CS}s among others} +% 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 @@ -7598,6 +7778,8 @@ pagella]{gmdocc} % \env{countalllines} package option), now it % uses \cs{inputlineno}} % +% \changes{v0.99n}{2008/08/24}{Inline comments' alignment developed} +% % \Finale % (For my GNU Emacs:) |