diff options
| author | Karl Berry <karl@freefriends.org> | 2008-08-12 00:00:12 +0000 |
|---|---|---|
| committer | Karl Berry <karl@freefriends.org> | 2008-08-12 00:00:12 +0000 |
| commit | 32514addcd2b369a74cb384f0274598e5574ce21 (patch) | |
| tree | 85dc5545c7bfd89ab620f5a3c7da57bb0d896913 /Master/texmf-dist/tex/latex/gmdoc | |
| parent | 6e415c97f0911faa1cda349f351adf41d775958a (diff) | |
gmdoc update (11aug08)
git-svn-id: svn://tug.org/texlive/trunk@10266 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/tex/latex/gmdoc')
| -rw-r--r-- | Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty | 846 | ||||
| -rw-r--r-- | Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls | 54 |
2 files changed, 519 insertions, 381 deletions
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: diff --git a/Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls b/Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls index c1dd06eb6aa..59ccceecc28 100644 --- a/Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls +++ b/Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls @@ -33,10 +33,11 @@ % \chschange{v0.76}{2007/11/13}{257} % \chschange{v0.77}{2007/11/16}{262} % \chschange{v0.78}{2007/11/19}{267} +% \chschange{v0.79}{2008/8/3}{271} \NeedsTeXFormat{LaTeX2e} \ProvidesClass{gmdocc} - [2007/11/19 v0.78 a class for gmdoc driver files (GM)] + [2008/08/03 v0.79 a class for gmdoc driver files (GM)] % % \division{Intro} @@ -239,14 +240,18 @@ % will be turned true in line \ref{ofstrue} \AtBeginDocument{% \@ifXeTeX{% - % ^^A \def\f@encoding{U}\selectfont - \setromanfont[Mapping=tex-text]{#1}% + \defaultfontfeatures{Numbers={OldStyle,Proportional}}% + \setmainfont[Mapping=tex-text]{#1}% + \setsansfont[Mapping=tex-text, Scale=MatchLowercase]{Latin Modern Sans}% + \setmonofont[Scale=MatchLowercase]{Latin Modern Mono}% \let\sl\it \let\textsl\textit }{}}% } \gm@DOX{minion}{\gmcc@setfont{Minion Pro}} -\gm@DOX{pagella}{\gmcc@setfont{TeX Gyre Pagella}} +\gm@DOX{pagella}{\gmcc@setfont{TeX Gyre Pagella}% + \def\gmcc@PAGELLA{1}% +} @@ -256,6 +261,9 @@ \gm@EOX{mptt=0}% We default to set the marginpar typewriter font to % OpenType LMTT LC. +% \HideDefining\DeclareOptionX +\DeclareOptionX*{\PassOptionsToPackage{\CurrentOption}{gmdoc}} + \ProcessOptionsX[gmcc]<> @@ -290,7 +298,7 @@ \fi % of ifSecondClass'es \cs{else} (a~feature under construction).\fi -\RequirePackage{gmutils}% earlier to provide |\@ifXeTeX|. +\RequirePackage{gmutils}[2008/08/03]% earlier to provide |\@ifXeTeX|. \ifgmcc@mwcls\afterfi\ParanoidPostsec\fi @@ -324,15 +332,16 @@ \def\ocircum {\^o}% \def\oumlaut {\"o}% \def\uumlaut {\"u}% -\else% this case hapens only with \XeTeX. +\else% this case happens only with \XeTeX. \let\do\relaxen \do\Finv\do\Game\do\beth\do\gimel\do\daleth% these five caused the - % `already defined' error. + % `already defined' error. + \let\@zf@euenctrue\zf@euencfalse \XeTeXthree - %^^A \setromanfont{LMRoman12}% Regular +%^^A \setromanfont{LMRoman12}% Regular %^^A \setsansfont{LMSans10}% Regular %^^A \setmonofont{LMTypewriter10}% Regular - \let\fontencoding\@gobble +%^^A \let\fontencoding\@gobble \def\agrave {\char"00E0 }% \def\cacute {\char"0107 }% Note the space to be sure the number % ends here. @@ -377,16 +386,18 @@ % suitable for the marginpar CS marking. \def\marginpartt{\normalfont\fontseries{lc}\ttfamily}}{}% \else - \IfFileExists{/media/BleuDeParis/texmf/tex/xelatex/crop.cfg}% - {\def\mpttversion{1}}{}% my system doesn't see LMTT LC, so on my - % computer I~have to tell \XeTeX explicitly where the font is. - \ifcase\mpttversion - \font\marginpartt= lmtypewriter10-lightcondensed.otf at 10.95pt - \or% (when =1, on my computer that is) - \font\marginpartt= % - [/home/natror/.fonts/lmtypewriter10-lightcondensed.otf] at 10.95pt - \else % other values allow you to define |\marginpartt| yourself. - \fi +%^^A \IfFileExists{/media/BleuDeParis/texmf/tex/xelatex/crop.cfg}% +%^^A {\def\mpttversion{1}}{}% my system doesn't see LMTT LC, so on my +%^^A % computer I~have to tell \XeTeX explicitly where the font is. +%^^A \ifcase\mpttversion +%^^A \font\marginpartt= lmtypewriter10-lightcondensed.otf at 10.95pt +%^^A \or% (when =1, on my computer that is) +%^^A \font\marginpartt= % +%^^A lmtypewriter10-lightcondensed.otf at 10.95pt +%^^A [/home/natror/.fonts/lmtypewriter10-lightcondensed.otf] at 10.95pt +%^^A \else % other values allow you to define |\marginpartt| yourself. +%^^A \fi + \def\marginpartt{\fontspec{LMTypewriter10 LightCondensed}}% %^^A~ \iffontchar \marginpartt 32 \show\relax \else \show\par\fi %^^A~ %^^A~ LMTypewriter10-LightCondensed.pfb at 10.95pt @@ -398,6 +409,9 @@ %^^A~ /home/natror/.fonts/lmtypewriter10-lightcondensed.otf \fi +\ifnum1=0\csname gmcc@PAGELLA\endcsname\relax + \RequirePackage{pxfonts,tgpagella,qpxmath}% +\fi % ^^A\setcounter{IndexColumns}{2} narrow columns do spare space and % ^^A~look better @@ -437,7 +451,7 @@ \exhyphenpenalty\hyphenpenalty% 'cause \pk{mwcls} set it |=10000| due % to Polish customs. -\VerbT1% to ensure T1 font encoding in verbatims (in code). +%^^A\VerbT1% to ensure T1 font encoding in verbatims (in code). \RequirePackage{amssymb} \def\EOFMark{\rightline{\ensuremath{\square}}} |