From 89642d23f7bfe9d9b2fbebbc446f7c957da993af Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sat, 6 Mar 2010 01:07:57 +0000 Subject: gmdoc 0.991 (5mar10) git-svn-id: svn://tug.org/texlive/trunk@17338 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty | 1917 +++++++++++++++++--------- Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls | 269 +++- 2 files changed, 1462 insertions(+), 724 deletions(-) (limited to 'Master/texmf-dist/tex/latex/gmdoc') diff --git a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty index 8cfdcd0628e..fad28ae1538 100644 --- a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty +++ b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty @@ -2,7 +2,7 @@ % \GetFileInfo{gmdoc.sty} % \title{The \pk{gmdoc.sty} Package\thfileinfo} % \author{Natror (Grzegorz Murzynowski)} -% \date{\today} +% \date{\fakeonum[0.6]\today} % \maketitle % \label{gmd} %% @@ -10,17 +10,17 @@ %% intended to be used with \LaTeXe\ as a~package for %% documenting \LaTeXpar\ files and to be documented with itself. %% \stanza -%% +%% % \begin{copyrnote} % %% Written by Natror (Grzegorz Murzynowski), %% natror at o2 dot pl %% -%% \copyright\,2006, 2007, 2008 by Natror (Grzegorz Murzynowski). -%% +%% \copyright\,2006, 2007, 2008, 2009, 2010 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. +%% See \url{http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html} ^^A +%% for the details of that license.\rrthis %% %% \acro{LPPL} status: "author-maintained".\par %% @@ -65,7 +65,20 @@ % \chschange{v0.99p}{2008/10/4}{5607} % \chschange{v0.99q}{2008/10/10}{5603} % \chschange{v0.99r}{2008/11/22}{5607} -% \toCTAN{v0.99r}{2008/11/22} +% \toCTAN{2008/11/22 v0.99r} +% \chschange{v0.99s}{2008/12/15}{5974} +% [\env{enumargs} handling the +% argument types of \cmd\DeclareCommand; handling +% \cmd\verbatimspecials, including writing them to index; introduction +% of \cmd\narrativett\ including \cmd\ampulexdef\ of \pk{gmverb} +% internals] +% \chschange{v0.991}{2010/3/2}{6134} +% [compatibilising the \env{enumargs} environment with +% \cmd\DeclareCommand of \pk{gmutils} v.0.991; abandoning +% \pk{gmeometric}] +% \toCTAN{2010/03/04 v0.991} +% +% % % \ifnum\catcode`\@=11 % Why this test here---will come out in chapter @@ -73,7 +86,7 @@ % ^^A and about coming out already! ;-) \NeedsTeXFormat{LaTeX2e} \ProvidesPackage{gmdoc} - [2008/11/22 v0.99r a documenting package (GM)] + [2010/03/01 v0.991 a documenting package (GM)] \fi % % @@ -102,7 +115,7 @@ % The package tends to be (optionally) compatible with the standard % \pk{doc.sty} package, % i.e., the \file{.dtx} files are also compilable with \pk{gmdoc} -% (they may need very little adjustment, in some rather special +% (they may need a~tiny adjustment in some special % cases). % % The tools are integrated with \pk{hyperref}'s advantages such as @@ -190,8 +203,8 @@ % \begin{verse} % \pk{gmutils.sty},\\ % \pk{gmverb.sty},\\ -% \pk{gmiflink.sty}\\ -% \pk{gmeometric} (for the driver of The \LaTeXe\ Source)\\ +% \pk{gmiflink.sty} +%^^A% \pk{gmeometric} (for the driver of The \LaTeXe\ Source)\\ % \end{verse} % and also on some standard packages: % \begin{verse} @@ -205,9 +218,7 @@ % 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} ;-): @@ -250,11 +261,11 @@ % % The rest is striving to level the very high \pk{doc/ltxdoc}'s % standard, such as (optional) numbering of the codelines and -% authomatic indexing the control sequences e.g. +% automatic indexing the control sequences e.g. % % The \docfm\ package was and still is a~great inspiration for me and % I~would like this humble package to be considered as a~sort of -% hommage to it\footnote{As Grieg's Piano Concerto is a~hommage to ^^B +% homage to it\footnote{As Grieg's Piano Concerto is a~homage to ^^B % the Schumann's.}. If I~mention copying some code or narrative but do % not state the source explicitly, I~mean the \docfm\ package's % documentation (I~have v2.1b dated 2004/02/09). @@ -268,10 +279,10 @@ % % When I~write of a~\textbf{macro}, I~mean a~macro in \TeXbook's % meaning, i.e., a~control sequence whose meaning is -% |\(e/g/x)def|ined. By a~\textbf{macro's parameter} I~mean each of +% |\›[e⁄|g⁄|x›]def|ined. By a~\textbf{macro's parameter} I~mean each of % |#|\s in its definition. When I~write about ^^A\) % a~\textbf{macro's argument}, I~mean the value (list of tokens) -% subsituting the corresponding parameter of this macro. +% substituting the corresponding parameter of this macro. % (These understandings are according ^^A( % to \TeXbook, I~hope: \TeX\ is a~religion of Book ;-)\,.) % @@ -279,7 +290,7 @@ % % When I~talk of a~\textbf{declaration}, I~mean a~macro that expands % to a~certain assignment, such as |\itshape| or -% |\@onlypreamble{|\<\CS>|}|. +% |\@onlypreamble{⁄<⁄CS>}|. % % Talking of declarations, I'll use the \textbf{\acro{OCSR}} acronym as % a~shorthand for 'observes/ing common \TeX\ scoping rules'. @@ -322,11 +333,11 @@ % \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 +% comment lines, the code delimiter is omitted. If the comment % continues a~codeline, the code delimiter is printed. It's done so % because ending a~\TeX\ code line with a~|%| is just a~concatenation % with the next line sometimes. Comments longer than one line are -% typeset continuously with the code delimiters ommitted. +% typeset continuously with the code delimiters omitted. % % The user should just write \hisher\ splendid code and brilliant % commentary. In the latter \heshe\ may use usual \LaTeXpar\ commands. @@ -336,6 +347,15 @@ % shall gobble the line end. ^^A~and the leading code delimiter of %^^A % the next line---obsoleted by ^^A~making % ignored in the commentary. % +% But there is also a~\pk{gmdoc} version of |\footnote| provided that +% sets the catcodes so that you don't bother about |^^B| in the +% argument, \TextUsage\qfootnote that takes the same argument(s) as +% the standard |\footnote| and for emphasis there is +% \TextUsage*[\qemph]{\qemph}\arg{text to emphasise}. Both of them +% work also in the ‘straight’ \acro{EOL}s' scope so you don't +% bother. The \TextUsage\arg\ \pk{gmutils}' command also works without +% |^^B|. +% % Moreover, if \heshe\ wants to add a~meta-comment i.e., a~text that % doesn't appear in the code layer nor in the narrative, \heshe\ may % use the \TextUsage*{^^A} sequence that'll be read by \TeX\ as @@ -347,7 +367,7 @@ % although it's active in fact: it re|\catcode|s the special % characters including |\|, |{| and |}| % so you don't have to worry about unbalanced braces or \cs{if}s in -% its scope. But |^^B| doesn't re|\catcode| anything (it would be +% its scope. But |^^B| doesn't re|\catcode| anything (which would be % useless in an argument) so any text between |^^B| and line end has % to be balanced. % @@ -362,8 +382,7 @@ % reason you don't want to make an environment (a~group), there's % a~|\StraightEOL|'s counterpart, the \TextUsage\QueerEOL\ declaration that % restores again the -% \StraightEOL -% queer\footnote{In my understanding +% queer\qfootnote{In my understanding % `queer' and `straight' are not the opposites excluding each % other but the counterparts that may cooperate in harmony for % people's good. And, as I~try to show with the \cs{QueerEOL} and @@ -371,14 +390,19 @@ % recommended while `straight' is the standard but not necessarily % normative. ^^A% (Remember also Alice's in the Wonderland exclamations % ^^A % ``What a~queer day is today''.) -% }^^A -% \QueerEOL +% } ^^A % \gmdoc's meaning of the line end. It \acro{OCSR}, too. One more point to use % |\StraightEOL| is where you wish some code lines to be executed % both while loading the file and during the documentation pass % (it's analogous to \docfm's not embracing some code lines in % a~\env{macrocode} environment). % +% ^^A % The \pk{gmdoc}'s ‘queer’ line ends may be surprising at first. For +% ^^A % example they should not occur in the arguments to the commands +% ^^A % because they cause errors then. To suppress the ‘queer’ and active +% ^^A % line end in the arguments of commands you should end a~line with +% ^^A % \TextUsage*{^^B} which will gobble the line end safely. +% % \stanza % % As in standard \TeX ing, one gets a~paragraph by a~blank line. @@ -401,7 +425,7 @@ % characteristics: \par\leftskip\CodeIndent % \stanza % -% \noindent|\documentclass[|\|]{|\|}|\par +% \noindent|\documentclass[|\|]{|\|}|\par % \noindent|\usepackage[|\|]{gmdoc}|\par % \\par % \noindent|\begin{document}|\par @@ -415,7 +439,9 @@ % To typeset a~source file you may use the \TextUsage\DocInput\ % macro that takes the (path and) name of the file \emph{with ^^B % the extension} as the only argument, e.g., -% |\DocInput{mybrilliantpackage.sty}|. +% |\DocInput{mybrilliantpackage.sty}|\qfootnote{I~use the ‘broken bar’ +% character as a~hyphen in verbatim texts and hyperlinks. If you +% dont't like it, see \cmd\verbDiscretionaryHyphen\ in \pk{gmverb}.}. % % (Note that an \emph{installed} package or class file is findable to % \TeX\ even if you don't specify the path.) @@ -429,9 +455,9 @@ % When using |\OldDocInput|, you have to wrap all the code in % \TextUsage*{macrocode} environments, which is not necessary when you % use |\DocInput|. Moreover, with |\OldDocInput| the\ -% \env{mac\-ro\-co\-de(*)} environments require to be ended with -% |% \end{macrocode(*)}| as in \docfm. (With |\DocInput| you are -% not obliged to precede |\end{macrocode(*)}| with The +% \env{macrocode›[*›]} environments require to be ended with +% \[|% \end{macrocode›[*›]}|\] as in \docfm. (With |\DocInput| you are +% not obliged to precede |\end{macrocode›[*›]}| with The % Four Spaces.) % % \stanza @@ -454,39 +480,44 @@ % the first and optional argument will not appear in the headings nor % in the footers. % -% |\DocInclude| redefines \TextUsage\maketitle\ so -% that it makes a~chapter heading or, in the classes that don't -% support |\chapter|, a~part heading, in both cases with -% respective toc entries. The default assumption is that all the -% files have the same author(s) so there's no need to print them in -% the file heading. If you wish the authors names to be printed, you -% should write \TextUsage\PrintFilesAuthors\ in the preamble or before -% the relevant |\DocInclude|s. If you wish to undeclare printing the -% authors names, there is \TextUsage\SkipFilesAuthors\ declaration. +% |\DocInclude| redefines \TextUsage\maketitle\ so that it makes +% a~chapter heading or, in the classes that don't support |\chapter|, +% a~part heading, in both cases with respective toc entries. The +% default assumption is that all the files have the same author(s) so +% there's no need to print them in the file heading. If you wish the +% authors names to be printed, you should write +% \TextUsage\PrintFilesAuthors\ in the preamble or before the relevant +% |\DocInclude|s. If you wish to undeclare printing the authors names, +% there is \TextUsage*[\Skip⁄-Fil⁄-es⁄-Auth⁄-ors]{\SkipFilesAuthors} +% declaration. % % Like in \pk{ltxdoc}, the name of an included file appears in the % footer of each page with date and version info (if they are % provided). % % The |\DocInclude|d files are numbered with the letters, the -% lowercase first, as in \pk{ltxdoc}. Such a~filemarker also precedes +% lowercase first, as in \pk{ltxdoc}. Such a~file-marker also precedes % the index entries, if the (default) codeline index option is in force. % % As with |\include|, you may declare -% \TextUsage\includeonly|{|\|}| for +% \TextUsage\includeonly|{⁄}| for % the draft versions. % % \stanza If you want to put the driver into the same \file{.sty} or % \file{.cls} file (see chapter \ref{Driver} to see how), you may -% write |\DocInput{\jobname.sty}|, or |\DocInclude{\jobname.sty}|, but +% write |\DocInput{\jobname.sty}|, or |\DocInclude{\jobname}|, 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}. +% +% By the way, to say \TeX\ to (self)include only the current file, +% most probably you should say |\includeonly{\jobname}| not +% |\includeonly{myfile}| because of the catcodes. % \stanza % -% At the default settings, the |\Doc/SelfInclude|d files constitute +% At the default settings, the |\›(Doc⁄|Self›)Include|d files constitute % chapters if |\chapter| is known and parts otherwise. The % |\maketitle|s of those files result in the respective headings. % @@ -545,7 +576,7 @@ % \TextUsage\AtBegInputOnce|{|\|}| % declaration. It's also global which means that the groups do not % limit its scope but it adds its argument only at the first input -% succeding it (the argument gets wrapped in a~macro that's |\relax|ed +% succeeding it (the argument gets wrapped in a~macro that's |\relax|ed % at the first use). |\AtBegInputOnce|s add up, too. % % \stanza @@ -605,7 +636,7 @@ % {\LineNumFont 445}\,are typeset continuously with the numbers printed. % % \stanza -% By default the \pk{makeidx} package is loaded and initialized and +% By default the \pk{makeidx} package is loaded and initialised and % the \CSs occurring in the code are automatically % (hyper)indexed thanks to the \pk{hyperref} package. If the user % doesn't wish to index anything, she should use the @@ -634,8 +665,8 @@ % \stanza % In \docfm\ package there's a~default behaviour of putting marked % macro's or environment's name to a~marginpar. In the standard -% classes it's allright but not all the classes support marginpars. -% That is the reason why this package enables marginparing when in +% classes it's alright but not all the classes support marginpars. +% That is the reason why this package enables marginpar-ing when in % standard classes, enables or disables it due to the respective option % when with Marcin Woli\nacute ski's classes and in any case provides the % options \TextUsage*{withmarginpar} and \TextUsage*{nomarginpar}. So, in @@ -644,7 +675,7 @@ % control sequences and environments into marginpars (see % \gmiflink[textUsage]{\cs{TextUsage} etc.}). These options do % not affect common using marginpars, which depends on the -% documentclass. +% document class. % % \stanza % My suggestion is to make the spaces in the code visible except the @@ -664,7 +695,7 @@ % If for any reason you wish the code spaces blank in general and % visible and grey in \env{verbatim*}s, use the declaration % \TextUsage\VisSpacesGrey\ of the \pk{gmverb} package. If you like -% a~little tricks, you can also specify +% little tricks, you can also specify % |codespacesgrey, codespacesblank| in \pk{gmdoc} options (in this % order). % @@ -685,6 +716,15 @@ % and \|\mylittlemacro| breaks into \|%|\\ % |\mylittlemacro|. % +% This package provides the \TextUsage\verbatimspecials\ declaration +% that is used in \pk{gmdocc.cls} as {\noverbatimspecials +% \[|\verbatimspecials⁄«»[¿]|\] to set |⁄| (fractional slash) to the +% escape char, |«| and |»| to group begin and end respectively and +% |¿| to math shift in verbatims (also the short ones). Note +% however that this declaration \qemph{has no effect on the code +% layer}. } +% +% % As the standard \LaTeX\ one, my |\verb| issues an error when a~line % end occurs in its scope. But, if you'd like to allow line ends in % short verbatims, there's the \TextUsage\verbeolOK\ declaration. The @@ -721,7 +761,10 @@ % technical and (I~hope) tricky, such as |\afterfi|, |\ifnextcat|, % |\addtomacro| etc. It's this package that provides the macros for % formatting of names of macros and files, such as |\cs|, |\marg|, |\pk| -% etc. \stanza +% etc. Moreover, it provides a~powerful tool for defining commands +% with weird optional and Knuthian arguments, |\DeclareCommand|, +% inspired by ancient (pre-expl3) \pk{xparse}'s +% |\DeclareDocumentCommand|.\stanza % % The \gmdoc\ package uses a~lot of hyperlinking possibilities % provided by \pk{hyperref}\gmdmarginpar{\pk{hyperref}} which is therefore @@ -764,18 +807,19 @@ % |\newread|,\\ % |\newwrite|, % |\newlength|, -% |\newcommand(*)|, -% |\renewcommand(*)|, -% |\providecommand(*)|, -% |\DeclareRobustCommand(*)|, -% |\DeclareTextCommand(*)|,\\ -% |\DeclareTextCommandDefault(*)|, +% |\newcommand›[*›]|, +% |\renewcommand›[*›]|, +% |\providecommand›[*›]|, +% |\DeclareRobustCommand›[*›]|, +% |\DeclareTextCommand›[*›]|,\\ +% |\DeclareTextCommandDefault›[*›]|, % |\DeclareDocumentCommand|, +% |\Decl⁄-are⁄-Com⁄-mand|\rrthis % % \item -% |\newenvironment(*)|, -% |\renewenvironment(*)|, -% |\DeclareOption(*)|, +% |\newenvironment›[*›]|, +% |\renewenvironment›[*›]|, +% |\DeclareOption|, %^^A~ |%\DeclareDefining*\@namedef| % % \item \label{newctr} @@ -800,15 +844,15 @@ % |\DeclareStringOption|, % |\DeclareBoolOption|, % |\DeclareComplementaryOption|,\\ -% |\DeclareVoidOption|. +% |\DeclareVoidOption|.\rrthis % \end{enumerate}\par % % What does `detects' mean? It means that the main argument of % detected command will be marked as defined at this point, % i.e.\ thrown to a~margin note and indexed with a~`definition' entry. % Moreover, for the definitions \ref*{newctr}--\ref*{DSOption} an -% alternate index entries will be created: of the \CSs uderlying those -% definitions, e.g. |\newcounter{foo}| in the +% alternate index entries will be created: of the \CSs underlying those +% definitions, e.g.\ |\newcounter{foo}| in the % code will result in indexing |foo| and |\c@foo|. % % If you want to add detection of a~defining command not listed above, @@ -830,15 +874,15 @@ % % |dk| stands for |\define@key| and is the type of \pk{xkeyval} % definitions of keys (group \ref{dk type} commands). When detected, -% it scans furher code for an optional \arg[KVprefix], mandatory +% it scans further code for an optional \arg[KVprefix], mandatory % \arg{KVfamily} and mandatory \arg{key name}. The default \ % is |KV|, as in \pk{xkeyval}. % % |dox| stands for |\DeclareOptionX| and launches scanning for an -% optional \arg[KVprefix], optional |<|\|>| and mandatory +% optional \arg[KV\-pre\-fix], optional |<|\|>| and mandatory % \arg{option name}. Here the default \ % is also |KV| and the default \ is the input file name. If -% you want to set another default family (e.g. if the code of +% you want to set another default family (e.g.\ if the code of % \file{foo.sty} actually is in file \file{bar.dtx}), use % \TextUsage\DeclareDOXHead\arg{KVfamily}. This declaration has an % optional first argument that is the default \ for @@ -848,16 +892,22 @@ % 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 |\|\|@|\. The default \ is +% a~\CS |\|\|@|\