From 5d35798dc0ca224df75f912f020c70024e1a1169 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 24 Oct 2010 23:45:49 +0000 Subject: gmdoc (24oct10) git-svn-id: svn://tug.org/texlive/trunk@20182 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/gmdoc/README | 242 +- .../doc/latex/gmdoc/basedrivers/doc_gmdoc.tex | 117 +- .../doc/latex/gmdoc/basedrivers/docstrip_gmdoc.tex | 84 +- .../doc/latex/gmdoc/basedrivers/source2e_gmdoc.tex | 24 +- Master/texmf-dist/doc/latex/gmdoc/gmdoc.pdf | Bin 5006687 -> 3006329 bytes Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty | 5229 ++------------------ Master/texmf-dist/tex/latex/gmdoc/gmdocc.cls | 397 +- 7 files changed, 896 insertions(+), 5197 deletions(-) (limited to 'Master/texmf-dist') diff --git a/Master/texmf-dist/doc/latex/gmdoc/README b/Master/texmf-dist/doc/latex/gmdoc/README index a2e161e1375..e3e2b56904e 100644 --- a/Master/texmf-dist/doc/latex/gmdoc/README +++ b/Master/texmf-dist/doc/latex/gmdoc/README @@ -1,121 +1,121 @@ -The gmdoc.zip package -is a work of Grzegorz Murzynowski, - - - -1. Copyright 2006, 2007, 2008, 2009, 2010 by Grzegorz `Natror' Murzynowski - -This program is subject to the LaTeX Project Public License. -See http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html -for the details of that license. - - -2. Introduction - -This package provides a tool for documenting of (La)TeX -packages, classes etc., i.e., the .sty, .cls -etc. The author just writes the code and adds the commentary -preceded with % sign (or another sign properly declared). No special -environments are necessary. - -The package tends to be compatible with the standard doc.sty -package, i.e., the .dtx files are also compilable with -gmdoc (they may need very little adjustment, in some rather -special cases). - -The tools are integrated with hyperref.sty's advantages such as -hyperlinking of index entries, of contents entries and -of cross-references. - - -3. Installation - -Unpack the gmdoc-tds.zip archive in a texmf directory or put the -gmdoc.sty, gmdocc.cls and gmoldcomm.sty somewhere in the -texmf/tex/latex branch on your own and also the gmiflink.sty, -gmverb.sty and gmiflink.sty files (available on CTAN in separate -packages). (Creating a /texmf/tex/latex/gm directory may be advisable -if you consider using other packages written by me.) - -Moreover, you should put the gmglo.ist file, a MakeIndex style for the -changes' history, into some texmf/makeindex directory. - -Then you should refresh your TeX distribution's files' -database most probably. - - -4. Contents - -The distribution of this package consists of the following five files. - -gmdoc.sty -gmdocc.cls -gmglo.ist -README -gmdoc.pdf -gmdoc-tds.zip - -5. Documentation - -The last of the above files (the .pdf) is a documentation compiled -from the .sty file by running LaTeX on the gmdocDoc.tex file twice: -xelatex gmdoc.sty - in the directory you wish the documentation to be in, -you don't have copy the .sty file there---TeX will find it, -then MakeIndex on the gmdoc.idx and gmdoc.glo files, and then LaTeX -on gmdocDoc.tex twice again. - -MakeIndex shell commands: - makeindex -r gmdocDoc - makeindex -r -s gmglo.ist -o gmdocDoc.gls gmdocDoc.glo -The -r switch is to forbid MakeIndex make implicit ranges since the -(code line) numbers will be hyperlinks. -The -s switch makes MakeIndex use the style file instead of the -default settings and the -o switch declares the not-default name of -the output file - -Compiling of the documentation requires the packages gmdoc.sty (with -the gmdocc.cls class), gmiflink.sty, gmverb.sty, gmutils.sty and also -some standard packages: hyperref.sty, xcolor.sty, geometry.sty, -multicol.sty, lmodern.sty, fontenc.sty that should be installed on -your computer by default. - -The gmglo.ist file, a MakeIndex style for the changes' history, is -provided on CTAN in the gmdoc .zip archive and should -be put into some texmf/makeindex directory. - -If you have not installed the mwcls classes (available on CTAN and -present in TeX Lives e.g.), the result of your compilation may differ -a bit from the .pdf provided in this .zip archive in formattings: If -you have not installed mwcls, the standard article.cls will be -used. - - -DEPENDS ON (only non-standard files listed): - -gmiflink.sty -gmutils.sty -gmverb.sty -gmglo.ist - -*if you typeset The LaTeX 2e Source - -BONUS: Base drivers - -As a bonus and example of doc-compatibility -there are driver files included -(cf. Palestrina, Missa papae Marcelli ;-): - -source2e_gmdoc.tex -docstrip_gmdoc.tex -doc_gmdoc.tex - -(gmsource2e.ist is generated from source2e_gmdoc.tex) -gmoldcomm.sty - -These drivers typeset the respective files from the -.../texmf-dist/source/latex/base -directory of TeXLive2005 distribution. -Probably you should redefine the \BasePath macro in them -so that it points that directory on your computer. - +The gmdoc.zip package +is a work of Grzegorz Murzynowski, + + + +1. Copyright 2006, 2007, 2008, 2009, 2010 by Grzegorz `Natror' Murzynowski + +This program is subject to the LaTeX Project Public License. +See http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html +for the details of that license. + + +2. Introduction + +This package provides a tool for documenting of (La)TeX +packages, classes etc., i.e., the .sty, .cls +etc. The author just writes the code and adds the commentary +preceded with % sign (or another sign properly declared). No special +environments are necessary. + +The package tends to be compatible with the standard doc.sty +package, i.e., the .dtx files are also compilable with +gmdoc (they may need very little adjustment, in some rather +special cases). + +The tools are integrated with hyperref.sty's advantages such as +hyperlinking of index entries, of contents entries and +of cross-references. + + +3. Installation + +Unpack the gmdoc-tds.zip archive in a texmf directory or put the +gmdoc.sty, gmdocc.cls and gmoldcomm.sty somewhere in the +texmf/tex/latex branch on your own and also the gmiflink.sty, +gmverb.sty and gmiflink.sty files (available on CTAN in separate +packages). (Creating a /texmf/tex/latex/gm directory may be advisable +if you consider using other packages written by me.) + +Moreover, you should put the gmglo.ist file, a MakeIndex style for the +changes' history, into some texmf/makeindex directory. + +Then you should refresh your TeX distribution's files' +database most probably. + + +4. Contents + +The distribution of this package consists of the following five files. + +gmdoc.sty +gmdocc.cls +gmglo.ist +README +gmdoc.pdf +gmdoc-tds.zip + +5. Documentation + +The last of the above files (the .pdf) is a documentation compiled +from the .sty file by running LaTeX on the gmdocDoc.tex file twice: +xelatex gmdoc.sty + in the directory you wish the documentation to be in, +you don't have copy the .sty file there---TeX will find it, +then MakeIndex on the gmdoc.idx and gmdoc.glo files, and then LaTeX +on gmdocDoc.tex twice again. + +MakeIndex shell commands: + makeindex -r gmdocDoc + makeindex -r -s gmglo.ist -o gmdocDoc.gls gmdocDoc.glo +The -r switch is to forbid MakeIndex make implicit ranges since the +(code line) numbers will be hyperlinks. +The -s switch makes MakeIndex use the style file instead of the +default settings and the -o switch declares the not-default name of +the output file + +Compiling of the documentation requires the packages gmdoc.sty (with +the gmdocc.cls class), gmiflink.sty, gmverb.sty, gmutils.sty and also +some standard packages: hyperref.sty, xcolor.sty, geometry.sty, +multicol.sty, lmodern.sty, fontenc.sty that should be installed on +your computer by default. + +The gmglo.ist file, a MakeIndex style for the changes' history, is +provided on CTAN in the gmdoc .zip archive and should +be put into some texmf/makeindex directory. + +If you have not installed the mwcls classes (available on CTAN and +present in TeX Lives e.g.), the result of your compilation may differ +a bit from the .pdf provided in this .zip archive in formattings: If +you have not installed mwcls, the standard article.cls will be +used. + + +DEPENDS ON (only non-standard files listed): + +gmiflink.sty +gmutils.sty +gmverb.sty +gmglo.ist + +*if you typeset The LaTeX 2e Source + +BONUS: Base drivers + +As a bonus and example of doc-compatibility +there are driver files included +(cf. Palestrina, Missa papae Marcelli ;-): + +source2e_gmdoc.tex +docstrip_gmdoc.tex +doc_gmdoc.tex + +(gmsource2e.ist is generated from source2e_gmdoc.tex) +gmoldcomm.sty + +These drivers typeset the respective files from the +.../texmf-dist/source/latex/base +directory of TeXLive2005 distribution. +Probably you should redefine the \BasePath macro in them +so that it points that directory on your computer. + diff --git a/Master/texmf-dist/doc/latex/gmdoc/basedrivers/doc_gmdoc.tex b/Master/texmf-dist/doc/latex/gmdoc/basedrivers/doc_gmdoc.tex index 1a0b8906a9f..ac83c0917e8 100644 --- a/Master/texmf-dist/doc/latex/gmdoc/basedrivers/doc_gmdoc.tex +++ b/Master/texmf-dist/doc/latex/gmdoc/basedrivers/doc_gmdoc.tex @@ -1,14 +1,67 @@ +%% +% \skiplines +%<*master> +%% \iffalse ^^A we skip the debug setting +\IfFileExists{\string~/bin/gen_and_xela}{\errorcontextlines=1000 }{} +%% \fi +%% ^^A $Id: TheUltimateMaster.gmd,v 0.250 2010/10/24 14:42:35 natror Exp natror $ +% \endskiplines +% +%% \BundleInfoFromName{doc_gmdoc} +%% \title{\doc_gmdocTitle } +%% \author{Grzegorz Murzynowski} +%% \maketitle +%% +%% \let\ty\emph \let\df\dekfracc +%% +%% \begin{copyrnote} +%% +%% +%% Copyright ©\, +%% by Grzegorz ‘Natror’ Murzynowski +%% natror (at) o2 (dot) pl +%% +%% This program is subject to the \LaTeX\ Project Public License. +%% See ^^A +%% \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 +%% +%% +%% +%% +%% +%% For the documentation please refer to the file(s) +%% \file{doc_gmdoc.{gmd,pdf}}. +%% +%% \end{copyrnote} +%% +% +% +% \skiplines +% +% \endskiplines +% +% +%% +%% +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{doc_gmdoc} + [2010/09/25 v0.993 (GM)] + + +%% \PassOptionsToPackage{hyperindex=false}{hyperref}% Because FM writes some almost -% explicit indexing commands where he uses `encapsulating' i.e., -% a~command to encapsulate the page number, which would interfere with -% \pk{hyperref}'s default \verb+|hyperpage+. -\documentclass[outeroff,minion]{gmdocc} +\documentclass[countalllines, +codespacesblank, outeroff, pagella, cronos, cursor, +fontspec=quiet]{gmdocc} \usepackage{array} -\def\BasePath{/mnt/middle/TeXLive2005/texmf-dist/source/latex/base/}% Of course, -% you should change it to the respective path on your computer. +\VisSpacesGrey +\def\BasePath{/home/natror/texmf/source/latex/base/}% Of course, \ltxLookSetup \gmdoccMargins @@ -21,33 +74,38 @@ \makeatletter +\edef\gmd@wykrzykniki{\xiihash\space\xiihash\space} +\edef\gmd@wykrzykniki{\gmd@wykrzykniki\gmd@wykrzykniki} +\edef\gmd@wykrzykniki{\gmd@wykrzykniki\gmd@wykrzykniki} +\edef\gmd@wykrzykniki{\gmd@wykrzykniki\gmd@wykrzykniki} + \author{Frank Mittelbach \and David Carlisle} \title{The \pk{doc} and \pk{shortvrb} Packages\\ and\\ the \pk{ltxdoc} Class} -\date{Typeset with the \pk{gmdoc} package by Natror\\\today} +\date{Typeset with the \pk{gmdoc} package by Natror\\\today} +\errorcontextlines=1000 +\fooatletter{% + \typeout{@@@@@ \meaning\@begindocumenthook}} \begin{document} \smartunder -\maketitle +\typeout{@@@@ in document} +\maketitle +\typeout{@@@@ after title} \addtocontents{toc}{% to discard |\begin{multicols}{2}| of one % included document. (Table of contents is declared twocolumn with % |\twocoltoc| above.) \let\protect\begin\protect\@gobbletwo - \protect\StoreMacro\protect\end - \def\protect\end{\protect\RestoreMacro\protect\end\protect\@gobble}% + \protect\Store@Macro\protect\end + \def\protect\end{\protect\Restore@Macro\protect\end\protect\@gobble}% }% Because one document has a~\env{multicols} twocolumn table of -% contents and the other has usual one column, this will put entire -% toc in(to) \env{multicols}. - \tableofcontents -%^^A TODO Old comments i.e. authomatic verbatimization of all the cs's -%^^A met in the comment layer. \makeatletter \AfterMacrocode{161}{% it's for a~tiny little typo in line 3299: They @@ -63,7 +121,6 @@ % \label{explicit fileinfo} \let\GetFileInfo\relax \addtomacro\IndexParms{\arraybackslash}}% because |\IndexParms| use -% |\raggedright| and FM executes |\IndexParms| inside a~\env{tabular}. \DocInclude[\BasePath]{doc} @@ -71,7 +128,7 @@ \chschange{v2.0u}{2006/10/20}{410}% \let\CheckSum\gobble \def\filedate{1999/08/08} \def\fileversion{v2.0u}% see line - % \ref{explicit fileinfo}. + % \ref{explicit fileinfo}. \let\GetFileInfo\relax % The rest of this |\AtBegInputOnce|'s contents is necessary since % DC wrote it not commented out, which with \pk{doc} results with @@ -79,7 +136,7 @@ % with \pk{gmdoc} it puts this stuff in the code layer that'll be % only printed verbatim. \providecommand\dst{\expandafter{\normalfont\scshape docstrip}} - \title{The file \texttt{ltxdoc.dtx} for use with + \title{The file \texttt{ltxdoc.dtx} for use with \LaTeXe.\thanks{This file has version number \fileversion, dated \filedate.}\\[2pt] It contains the code for \texttt{ltxdoc.cls}} @@ -91,39 +148,39 @@ \gmdocIncludes -\SelfInclude{% +\AtBegInputOnce{% \title{\pk{doc_by_gmdoc.tex} The Driver\thanks{As mentioned in the title, I~typeset these package and class with the \pk{gmdoc} package, for which are they a~great inspiration and the base. The typesetting needed only a~few tricks, so here i~give the -%^^A( code of the `driver': a~snake eats its tail ;-) .}} \author{Grzegorz `Natror' Murzynowski}% \date{\today}% \maketitle} +\SelfInclude \typeout{% Produce change log with^^J% - makeindex -r -s gmglo.ist -o \jobnamewoe.gls \jobnamewoe.glo^^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 \jobnamewoe^^J} + makeindex -r \jobname^^J} \PrintIndex \end{document} -% MakeIndex shell commands: makeindex -r doc_gmdoc makeindex -r -s gmglo.ist -o doc_gmdoc.gls doc_gmdoc.glo -% \NoEOF -% \_ {\bf bf: \_} {\bfseries bfseries \_} - -%%% Local Variables: -%%% mode: latex -%%% TeX-master: t -%%% End: \ No newline at end of file +%%% (For my GNU Emacs:) +%%% Local Variables: +%%% mode: doctex +%%% coding: utf-8 +%%% End: +\endinput +%% +%% End of file `doc_gmdoc.tex'. diff --git a/Master/texmf-dist/doc/latex/gmdoc/basedrivers/docstrip_gmdoc.tex b/Master/texmf-dist/doc/latex/gmdoc/basedrivers/docstrip_gmdoc.tex index 6a724ef87fc..9f7d8cddbdf 100644 --- a/Master/texmf-dist/doc/latex/gmdoc/basedrivers/docstrip_gmdoc.tex +++ b/Master/texmf-dist/doc/latex/gmdoc/basedrivers/docstrip_gmdoc.tex @@ -1,17 +1,65 @@ +%% +% \skiplines +%<*master> +%% \iffalse ^^A we skip the debug setting +\IfFileExists{\string~/bin/gen_and_xela}{\errorcontextlines=1000 }{} +%% \fi +%% ^^A $Id: TheUltimateMaster.gmd,v 0.250 2010/10/24 14:42:35 natror Exp natror $ +% \endskiplines % -% A~driver file to typeset \pk{dostrip.dtx} with the \pk{gmdoc} -% package. +%% \BundleInfoFromName{docstrip_gmdoc} +%% \title{\docstrip_gmdocTitle } +%% \author{Grzegorz Murzynowski} +%% \maketitle +%% +%% \let\ty\emph \let\df\dekfracc +%% +%% \begin{copyrnote} +%% +%% +%% Copyright ©\, +%% by Grzegorz ‘Natror’ Murzynowski +%% natror (at) o2 (dot) pl +%% +%% This program is subject to the \LaTeX\ Project Public License. +%% See ^^A +%% \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 +%% +%% +%% +%% +%% +%% For the documentation please refer to the file(s) +%% \file{docstrip_gmdoc.{gmd,pdf}}. +%% +%% \end{copyrnote} +%% % -% GM 2006/12/1 % +% \skiplines +% +% \endskiplines +% +% +%% +%% +\NeedsTeXFormat{LaTeX2e} +\ProvidesClass{docstrip_gmdoc} + [2010/09/25 v0.993 (GM)] + + +%% -\PassOptionsToPackage{indexallmacros}{gmdoc} +\PassOptionsToPackage{countalllines,codespacesgrey,indexallmacros}{gmdoc} -\if1 1 - \documentclass[debug]{gmdocc}% +\if11 + \documentclass[debug, pagella, fontspec=quiet]{gmdocc}% \mcdiagOn \else - \documentclass[minion]{gmdocc}% + \documentclass[pagella]{gmdocc}% \fi \ltxLookSetup @@ -20,8 +68,6 @@ \DeleteShortVerb\| \OldMakeShortVerb*\|% To define shortverb \verb+|+ such that it -% remains shortverb in math mode (by default I~define it to be $\vert$ in -% math mode. \relaxen\ds \emptify\EOFMark @@ -43,23 +89,31 @@ \begin{document} -\def\BasePath{/mnt/middle/TeXLive2005/texmf-dist/source/latex/base/} -%^^A \tableofcontents +\def\BasePath{/home/natror/texmf/source/latex/base/} \addtomacro\endabstract{\aftergroup\tableofcontents} \AtBegInputOnce{\date{Printed \today\\ with \pk{gmdoc} package by Natror}\let\date\gobble \let\renewenvironment\gobbletwo}% the only renewed env.\ in % \file{docstrip.dtx} is \env{theglossary}. I~prefer it to be twocolumn. + \OldDocInput{\BasePath docstrip.dtx} \typeout{% ^^JProduce change log with^^J% - makeindex -r -s gmglo.ist -o \jobnamewoe.gls \jobnamewoe.glo^^J} + makeindex -r -s gmglo.ist -o \jobname.gls \jobname.glo^^J} \typeout{% ^^JProduce index with^^J% - makeindex -r \jobnamewoe.idx^^J} - + makeindex -r \jobname.idx^^J} + \end{document} -%\NoEOF + +%%% (For my GNU Emacs:) +%%% Local Variables: +%%% mode: doctex +%%% coding: utf-8 +%%% End: +\endinput +%% +%% End of file `docstrip_gmdoc.tex'. diff --git a/Master/texmf-dist/doc/latex/gmdoc/basedrivers/source2e_gmdoc.tex b/Master/texmf-dist/doc/latex/gmdoc/basedrivers/source2e_gmdoc.tex index cdfcd7b0626..bbe5e70afd2 100644 --- a/Master/texmf-dist/doc/latex/gmdoc/basedrivers/source2e_gmdoc.tex +++ b/Master/texmf-dist/doc/latex/gmdoc/basedrivers/source2e_gmdoc.tex @@ -105,13 +105,16 @@ page_precedence "rnaA" \end{filecontents} -\PassOptionsToPackage{indexallmacros}{gmdoc} +\PassOptionsToPackage{codespacesgrey, indexallmacros}{gmdoc} -\if1 1 - \documentclass[debug,minion]{gmdocc}% +\if11 + \documentclass[debug, minion, cronos, cursor, fontspec=quiet]{gmdocc}% + + % ^^A[FakeBold=2, FakeStretch=0.87]{Nimbus Mono L} \mcdiagOn + \else - \documentclass[sysfonts]{gmdocc}% + \documentclass[fontspec=quiet]{gmdocc}% \fi \foone{\catcode`_=12 } @@ -213,6 +216,9 @@ page_precedence "rnaA" %^^A \else\typeout{****** \cs{"} with argument }\show#1\fi }}{}} +\foone{\makeatletter\catcode`\#=12 }{% + \def\gmd@wykrzykniki{# # # # # # # # #}} + \begin{document} @@ -228,7 +234,7 @@ page_precedence "rnaA" Rainer Sch\"opf} -\def\BasePath{/mnt/middle/TeXLive2005/texmf-dist/source/latex/base/} +\def\BasePath{/home/natror/texmf/source/latex/base/} % This command will be used to input the patch file @@ -273,7 +279,11 @@ page_precedence "rnaA" \pagenumbering{roman} \thispagestyle{empty} + +%^^A\traceon \maketitle +\relax +%^^A \traceoff \emptify\maketitle \tableofcontents @@ -414,7 +424,7 @@ page_precedence "rnaA" \typeout{% ^^JProduce change log with^^J% - makeindex -r -s gmglo.ist -o \jobnamewoe.gls \jobnamewoe.glo^^J} + makeindex -r -s gmglo.ist -o \jobname.gls \jobname.glo^^J} {%^^A\def\.{\cs{.}}% 'cause there's |\cs {\.}| in change log on l.4314 % The next step of debug of \file{ltmiscen.dtx}'s @@ -438,7 +448,7 @@ page_precedence "rnaA" \typeout{% ^^JProduce index with^^J% - makeindex -r -s gmsource2e.ist \jobnamewoe.idx^^J} + makeindex -r -s gmsource2e.ist \jobname.idx^^J} % ``Makeindex needs a symbol between the parts of composite page numbers % but we dont want one, so:''---I~skip that. diff --git a/Master/texmf-dist/doc/latex/gmdoc/gmdoc.pdf b/Master/texmf-dist/doc/latex/gmdoc/gmdoc.pdf index dfbce2bf55c..1220b4db075 100644 Binary files a/Master/texmf-dist/doc/latex/gmdoc/gmdoc.pdf and b/Master/texmf-dist/doc/latex/gmdoc/gmdoc.pdf differ diff --git a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty index fad28ae1538..90e416a0fa7 100644 --- a/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty +++ b/Master/texmf-dist/tex/latex/gmdoc/gmdoc.sty @@ -1,1988 +1,52 @@ -% -% \GetFileInfo{gmdoc.sty} -% \title{The \pk{gmdoc.sty} Package\thfileinfo} -% \author{Natror (Grzegorz Murzynowski)} -% \date{\fakeonum[0.6]\today} -% \maketitle -% \label{gmd} %% -%% This is (a~documentation of) file \pk{gmdoc.sty}, -%% intended to be used with \LaTeXe\ as a~package for -%% documenting \LaTeXpar\ files and to be documented with itself. -%% \stanza +%% \iffalse ^^A we skip the debug setting +\IfFileExists{\string~/bin/gen_and_xela}{\errorcontextlines=1000 }{} +%% \fi +%% ^^A $Id: TheUltimateMaster.gmd,v 0.250 2010/10/24 14:42:35 natror Exp natror $ +%% This is file “gmdoc.sty” generated with the DocStrip utility. +%% +%% +%% The original source files were: %% -% \begin{copyrnote} -% -%% Written by Natror (Grzegorz Murzynowski), -%% natror at o2 dot pl +%% gmdoc/gmdoc.gmd (with options: `doc') %% -%% \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.\rrthis +%% Copyright © 2006, 2007, 2008, 2009, 2010 +%% by Grzegorz ‘Natror’ Murzynowski +%% natror (at) o2 (dot) pl +%% +%% This program is subject to the LaTeX Project Public License. +%% See http://www.ctan.org/tex-archive/help/Catalogue/licenses.lppl.html +%% for the details of that license. %% -%% \acro{LPPL} status: "author-maintained".\par +%% LPPL status: "author-maintained". %% -%% Many thanks to my \TeX\ Guru Marcin Woli\nacute ski for his \TeX nical ^^A -%% support. -% -%\end{copyrnote} -% -% \ChangesStart{v0.98c}{1000/0/0} -% -% \chschange{v0.96}{2006/08/22}{2395} -% \chschange{v0.97}{06/09/04}{3636} -% \chschange{v0.98}{06/09/04}{3636} -% \chschange{v0.98a}{06/09/06}{4092} -% \chschange{v0.98b}{06/9/7}{4119} -% \chschange{v0.98c}{06/9/10}{4299} -% \chschange{v0.98d}{06/9/15}{4409} -% \chschange{v0.98e}{06/9/23}{4420} -% \chschange{v0.98f}{06/9/30}{4430} -% \chschange{v0.98g}{06/10/5}{4294} -% \chschange{v0.98i}{06/10/14}{4352} -% \chschange{v0.98j}{06/10/17}{4372} -% \chschange{v0.98k}{06/10/21}{4416} -% \chschange{v0.98l}{06/10/27}{4401} -% \chschange{v0.98m}{06/11/14}{4349} -% \chschange{v0.99}{06/11/29}{4462} -% \chschange{v0.99a}{2006/12/01}{4479} -% \chschange{v0.99b}{07/01/01}{4479} -% \chschange{v0.99c}{07/3/2}{4486} -% \chschange{v0.99c}{07/3/30}{4475} -% \chschange{v0.99d}{07/4/26}{4555} -% \chschange{v0.99e}{2007/4/29}{4574} -% \chschange{v0.99g}{2007/11/12}{5229} -% \chschange{v0.99i}{2008/8/3}{5247} -% \chschange{v0.99j}{2008/8/3}{5266} -% \chschange{v0.99k}{2008/8/4}{5261} -% \chschange{v0.99l}{2008/8/6}{5225} -% \chschange{v0.99m}{2008/8/9}{5356} -% \chschange{v0.99m}{2008/8/13}{5354} -% \chschange{v0.99n}{2008/8/22}{5409} -% \chschange{v0.99n}{2008/8/30}{5547} -% \chschange{v0.99p}{2008/10/4}{5607} -% \chschange{v0.99q}{2008/10/10}{5603} -% \chschange{v0.99r}{2008/11/22}{5607} -% \toCTAN{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 -% \gmiflink{The driver}. ^^A~( the very first line -% ^^A and about coming out already! ;-) +%% +%% +%% For the documentation please refer to the file(s) +%% gmdoc.{gmd,pdf}. +%% +%% \NeedsTeXFormat{LaTeX2e} -\ProvidesPackage{gmdoc} - [2010/03/01 v0.991 a documenting package (GM)] -\fi -% -% -% -% \CharacterTable {In my \TeX\ Guru's opinion the idea of -% checking of the correctness of chars is a~bit obsolete -% nowadays. Therefore I~define the \CharacterTable<#1> -% macro to gobble its argument and to typeout a~request -% for request.} -% -% -% \newcommand*\docfm{\pk{doc}} -% \newcommand*\gmdoc{\pk{gmdoc}} -% -% \tableofcontents -% -% -% \division{Readme} -% -% This package is a~tool for documenting of \LaTeXpar\ -% packages, classes etc., i.e., the \file{.sty}, \file{.cls} files -% etc. The author just writes the code and adds the commentary -% preceded with |%| sign (or another properly declared). No special -% environments are necessary. -% -% The package tends to be (optionally) compatible with the standard -% \pk{doc.sty} package, -% i.e., the \file{.dtx} files are also compilable with \pk{gmdoc} -% (they may need a~tiny adjustment in some special -% cases). -% -% The tools are integrated with \pk{hyperref}'s advantages such as -% hyperlinking of index entries, contents entries and -% cross-references. -% -% The package also works with \XeTeX\ (switches automatically). -% -% \begin{gmlonely} -% \subdivision{Installation} Unpack the \file{gmdoc-tds.zip} archive -% (this is an archive conforming the \acro{TDS} standard, see -% \file{CTAN/tds/tds.pdf})% in a~\file{texmf} directory -% or put the \pk{gmdoc.sty}, \pk{gmdocc.cls} and \pk{gmoldcomm.sty} -% somewhere in the \file{texmf/tex/latex} branch on your own. -% (Creating a~\file{texmf/tex/latex/gm} directory may be -% advisable if you consider using other packages written by me. And -% you \emph{have} to use four of them to make \pk{gmdoc} work.) -% -% You should also install \pk{gmverb.sty}, \pk{gmutils.sty} and -% \pk{gmiflink.sty} (e.g., put them into the same \file{gm} -% directory). These packages are available on \acro{CTAN} as separate -% \file{.zip} archives also in \acro{TDS}-compliant \pk{zip} -% archives. -% -% Moreover, you should put the \file{gmglo.ist} file, a MakeIndex -% style for the changes' history, into some \file{texmf/makeindex} -% (sub)directory. -% -% Then you should refresh your \TeX\ distribution's files' database -% most probably. -% \end{gmlonely} -% -% -% \subdivision{Contents of the \pk{gmdoc.zip} archive} -% -% The distribution of the \pk{gmdoc} package consists of the -% following five files and a~\acro{TDS}-compliant archive. -% \begin{verse} -% \pk{gmdoc.sty}\\ -% \pk{gmdocc.cls}\\ -% \pk{gmglo.ist}\\ -% \pk{README}\\ -% \pk{gmdoc.pdf}\\ -% \pk{gmdoc.tds.zip} -% \end{verse} -% -% -% \begin{gmlonely} -% \subdivision{Compiling of the documentation} -% -% The last of the above files (the \pk{.pdf}, i.e., \emph{this ^^B -% file}) is a~documentation compiled from the \pk{.sty} and -% \pk{.cls} files by running \XeLaTeX\ on the \file{gmdoc.sty} -% twice (|xelatex gmdoc.sty| in the directory you wish the -% documentation to be in, you don't have copy the \file{.sty} file -% there, \TeX\ will find it), then MakeIndex on the \file{gmdoc.idx} and -% \file{gmdoc.glo} files, and then \XeLaTeX\ on \file{gmdoc.sty} -% once more. (Using \LaTeX\ instead of \XeLaTeX\ should do, too.) -% -% MakeIndex shell commands: -%\begin{verbatim} -%makeindex -r gmdoc -%makeindex -r -s gmglo.ist -o gmdoc.gls gmdoc.glo -%\end{verbatim} -% The |-r| switch is to forbid MakeIndex to make implicit ranges since -% the (code line) numbers will be hyperlinks. -% -% Compiling the documentation requires the packages: -% \pk{gmdoc} (\pk{gmdoc.sty} and \pk{gmdocc.cls}), \pk{gmutils.sty}, -% \pk{gmverb.sty}, \pk{gmiflink.sty} and also some standard packages: -% \pk{hyperref.sty}, \pk{xcolor.sty}, \pk{geometry.sty}, -% \pk{multicol.sty}, \pk{lmodern.sty}, \pk{fontenc.sty} that should -% be installed on your computer by default. -% -% If you had not installed the \pk{mwcls} classes (available on -% \acro{CTAN} and present in \TeX\ Live e.g.), the result of your -% compilation might differ a~bit from the \pk{.pdf} provided in this -% \pk{.zip} archive in formatting: If you had not installed -% \pk{mwcls}, the standard \pk{article.cls} class would be used. -% \end{gmlonely} -% -% \subdivision{Dependencies} -% -% The \pk{gmdoc} bundle depends on some other packages of mine: -% \begin{verse} -% \pk{gmutils.sty},\\ -% \pk{gmverb.sty},\\ -% \pk{gmiflink.sty} -%^^A% \pk{gmeometric} (for the driver of The \LaTeXe\ Source)\\ -% \end{verse} -% and also on some standard packages: -% \begin{verse} -% \pk{hyperref.sty},\\ -% \pk{color.sty},\\ -% \pk{geometry.sty},\\ -% \pk{multicol.sty},\\ -% \pk{lmodern.sty},\\ -% \pk{fontenc.sty}\\ -% \end{verse} -% that should -% be installed on your computer by default. -% -% % \subdivision{Bonus: \file{base} drivers} -% As a~bonus and example of \docfm-compatibility -% there are driver files included -% (cf.\ Palestrina, \textit{Missa papae Marcelli} ;-): -% -% \begin{verse} -% \pk{source2e_gmdoc.tex}\\ -% \pk{docstrip_gmdoc.tex}\\ -% \pk{doc_gmdoc.tex} -% -% \pk{gmoldcomm.sty}\\ -% (\pk{gmsource2e.ist} is generated from \pk{source2e_gmdoc.tex})\\ -% \end{verse} -% -% These drivers typeset the respective files from the -%\[\hbox{\file{…/texmf-dist/source/latex/base}}\] -% directory of the \TeX Live2007 distribution (they only read that -% directory). -% -% Probably you should redefine the |\BasePath| macro in them -% so that it points that directory on your computer. -% -% -%\division*{Introduction} -% -% There are very sophisticated and effective tools for documenting -% \LaTeX\ macro packages, namely the \pk{doc} package and the -% \pk{ltxdoc} class. -% Why did I~write another documenting package then? -% -% I~like comfort and \pk{doc} is not comfortable enough for me. It -% requires special marking of the macro code to be properly typeset -% when documented. I~want \TeX\ to know `itself' where the code begins -% and ends, without additional marks. -% -% That's the difference. One more difference, more important for the -% people for whom the \docfm's conventions are acceptable, is that -% \gmdoc\ makes use of \pk{hyperref} advantages and makes -% a~hyperlinking index and toc entries and the -% cross-references, too. (The \CSs in the code maybe in the future.) -% -% The rest is striving to level the very high \pk{doc/ltxdoc}'s -% standard, such as (optional) numbering of the codelines and -% 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 -% 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). -% -% -% -% \division{The user interface} -% -% -% \subdivision{Used terms} -% -% When I~write of a~\textbf{macro}, I~mean a~macro in \TeXbook's -% meaning, i.e., a~control sequence whose meaning is -% |\›[e⁄|g⁄|x›]def|ined. By a~\textbf{macro's parameter} I~mean each of -% |#|\s in its definition. When I~write about ^^A\) -% a~\textbf{macro's argument}, I~mean the value (list of tokens) -% substituting the corresponding parameter of this macro. -% (These understandings are according ^^A( -% to \TeXbook, I~hope: \TeX\ is a~religion of Book ;-)\,.) -% -% I'll use a~shorthand for `control sequence', \textbf{\CS}. -% -% When I~talk of a~\textbf{declaration}, I~mean a~macro that expands -% to a~certain assignment, such as |\itshape| or -% |\@onlypreamble{⁄<⁄CS>}|. -% -% Talking of declarations, I'll use the \textbf{\acro{OCSR}} acronym as -% a~shorthand for 'observes/ing common \TeX\ scoping rules'. -% -% By a~\textbf{command} I~mean a~certain abstract visible to the end -% user as a~\CS but consisting possibly of more than one macro. I'll -% talk of a~\textbf{command's argument} also in -% the `sense\:-for\:-the\:-end\:-user', e.g., I'll talk of the -% |\verb| \emph{command's} argument although \emph{the macro} -% |\verb| has no |#|\ in its definition. -% -% The \textbf{code} to be typeset verbatim (and with all the bells -% and whistles) is everything that's not commented out in the source -% file and what is not a~leading space(s). -% -% The \textbf{commentary} or \textbf{narrative} is everything after -% the comment char till the end of a~line. The \textbf{comment char} -% is a~character the |\catcode| of which is 14 usually i.e., when the -% file works; if you don't play with -% the |\catcode|s, it's just the |%|. When the file is documented with -% \gmdoc, such a~char is re|\catcode|d and its r\ocircum le is else: it -% becomes the \textbf{code delimiter}. -% -% A~line containing any \TeX\ code (not commented out) will be called -% a~\textbf{codeline}. A~line that begins with (some leading spaces -% and) a~code delimiter will be called a~\textbf{comment line} or -% \textbf{narration line}. -% -% The \textbf{user} of this package will also be addressed -% as \textbf{you}.\stanza -% -% Not to favour any particular gender (of the amazingly rich variety, -% I~mean, not of the vulgarly simplified two-element set), in this -% documentation I~use alternating pronouns of third person ^^A( -% (\TextUsage\heshe\ etc. commands provided by \pk{gmutils}), so let -% one be not surprised if `\heshe' sees `\himher self' altered in the -% same sentence :-)\,. -% -% -% \subdivision{Preparing of the source file} -% -% When \LaTeXpar\ with \pk{gmdoc.sty} package loaded typesets the -% comment lines, the code delimiter is 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 omitted. -% -% The user should just write \hisher\ splendid code and brilliant -% commentary. In the latter \heshe\ may use usual \LaTeXpar\ commands. -% The only requirement is, if an argument is divided in two lines, to -% end such a~dividing line with \TextUsage*{\^^M} (|\|\) or with -% \TextUsage*{^^B} sequence that'll enter the (active) \ which -% shall gobble the line end. ^^A~and the leading code delimiter of -%^^A % the next line---obsoleted by ^^A~making % ignored in the commentary. -% -% 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 -% \, which -% in \gmdoc\ is active and defined to gobble the stuff between itself -% and the line end. -% -% Note that |^^A| behaves much like comment char -% although it's active in fact: it re|\catcode|s the special -% characters including |\|, |{| and |}| -% so you don't have to worry about unbalanced braces or \cs{if}s in -% its scope. But |^^B| doesn't re|\catcode| anything (which would be -% useless in an argument) so any text between |^^B| and line end has -% to be balanced. -% -% However, it may be a~bit confusing -% for someone acquainted with the \docfm\ conventions. If you don't -% fancy the |^^B| special sequence, instead you may restore the -% standard meaning of the line end with the \TextUsage\StraightEOL\ -% declaration which -% \acro{OCSR}. As almost all the control -% sequences, it may be used also as an environment, i.e., -% |\begin{StraightEOL}|\ \dots\ |\end{StraightEOL}|. However, if for any -% reason you don't want to make an environment (a~group), there's -% a~|\StraightEOL|'s counterpart, the \TextUsage\QueerEOL\ declaration that -% restores again the -% 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 -% \cs{StraightEOL} declarations, `queer' may be very useful and -% recommended while `straight' is the standard but not necessarily -% normative. ^^A% (Remember also Alice's in the Wonderland exclamations -% ^^A % ``What a~queer day is today''.) -% } ^^A -% \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. -% Such a~line should be |%|ed of course. A~fully blank line is -% considered a~blank \emph{code line} and hence results in -% a~vertical space in the documentation. As in the environments for -% poetry known to me, subsequent blank lines do not increase such -% a~space. -% -% Then \heshe\ should prepare a~main document file, -% a~\textbf{driver} henceforth, to set all the -% required formattings such as |\documentclass|, paper size -% etc., and load this package with a~standard command -% i.e., |\usepackage{gmdoc}|, just as \docfm's documentation says: -% -% \begin{quotation} -% If one is going to document a set of macros with the \pk{[gm]doc} -% package one has to prepare a special driver file which produces -% the formatted document. This driver file has the following -% characteristics: \par\leftskip\CodeIndent -% \stanza -% -% \noindent|\documentclass[|\|]{|\|}|\par -% \noindent|\usepackage[|\|]{gmdoc}|\par -% \\par -% \noindent|\begin{document}|\par -% \\par -% \noindent|\end{document}|\par -% \end{quotation} -% -% -% \subdivision{The main input commands} -% -% To typeset a~source file you may use the \TextUsage\DocInput\ -% macro that takes the (path and) name of the file \emph{with ^^B -% the extension} as the only argument, e.g., -% |\DocInput{mybrilliantpackage.sty}|\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.) -% -% If a~source file is written with rather \docfm\ than \gmdoc\ in -% mind, then the \TextUsage\OldDocInput\ command may be more -% appropriate (e.g., if you break the arguments of commands in the -% commentary in lines). It also takes the file (path and) name as the -% argument. -% -% When using |\OldDocInput|, you have to wrap all the code in -% \TextUsage*{macrocode} environments, which is not necessary when you -% use |\DocInput|. Moreover, with |\OldDocInput| the\ -% \env{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 -% If you wish to document many files in one document, you are -% provided \TextUsage\DocInclude\ command, analogous to \LaTeX's -% |\include| and very likely to \pk{ltxdoc}'s command of the same -% name. In \gmdoc\ it has one mandatory argument that should be the -% file name \emph{without extension}, just like for |\include|. -% -% The file extensions\label{docinclude:extensions} supported by -% |\DocInclude| are \pk{.fdd}, \pk{.dtx}, \pk{.cls}, \pk{.sty}, -% \pk{.tex} and \pk{.fd}. The macro looks for one of those extensions -% in the order just given. If you need to document files of other -% extensions, please let me know and most probably we'll make it -% possible. -% -% |\DocInclude| has also an optional first argument that is intended -% to be the path of the included file with the levels separated by |/| -% (slash) and also ended with a~slash. The path given to |\DocInclude| as -% the first and optional argument will not appear in the headings nor -% in the footers. -% -% |\DocInclude| redefines \TextUsage\maketitle\ so that it makes -% a~chapter heading or, in the classes that don't support |\chapter|, -% a~part heading, in both cases with respective toc entries. The -% default assumption is that all the files have the same author(s) so -% there's no need to print them in the file heading. If you wish the -% authors names to be printed, you should write -% \TextUsage\PrintFilesAuthors\ in the preamble or before the relevant -% |\DocInclude|s. If you wish to undeclare printing the authors names, -% there is \TextUsage*[\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~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 -% 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}|, 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⁄|Self›)Include|d files constitute -% chapters if |\chapter| is known and parts otherwise. The -% |\maketitle|s of those files result in the respective headings. -% -% If you prefer more \pk{ltxdoc}ish look, in which the files always -% constitute the parts and those parts have a~part's title -% pages with the file name and the files' |\maketitle|s result in -% (article-like) titles not division headings, then you are provided -% the \TextUsage\ltxLookSetup\ declaration (allowed only in the -% preamble). However, even after this declaration the files will be -% included according to \gmdoc's rules not necessarily to the \docfm's -% ones (i.e., with minimal marking necessary at the price of active -% line ends (therefore not allowed between a~command and its argument -% nor inside an argument)). -% -% On the other hand, if you like the look offered by me but you have -% the files prepared for \docfm\ not for \gmdoc, then you -% should declare \TextUsage\olddocIncludes. Unlike the previous one, -% this may be used anywhere, because I~have the account of including both -% \docfm-like and \gmdoc-like files into one document. This -% declaration just changes the internal input command and doesn't -% change the sectioning settings. -% -% It seems possible that you wish to document the `old-doc' files -% first and the `new-doc' ones after, so the above declaration has its -% counterpart, \TextUsage\gmdocIncludes, that may be used anywhere, -% too. Before the respective |\DocInclude|(s), of course. -% -% Both these declarations \acro{OCSR}. -% -% If you wish to document your files as with \pk{ltxdoc} \emph{and} -% as with \docfm, you should declare -% |\ltxLookSetup| in the preamble \emph{and} |\olddocIncludes|. -% -% \stanza -% Talking of analogies with \pk{ltxdoc}, if you like only the page -% layout provided by that class, there is the -% \TextUsage\ltxPageLayout\ declaration (allowed only in preamble) -% that only changes the margins and the text width (it's intended to -% be used with the default paper size). This declaration is -% contained in the |\ltxLookSetup| declaration. -% -% \stanza -% If you need to add something at the beginning of the input of file, -% there's the \TextUsage\AtBegInput\ declaration that takes one -% mandatory argument which is the stuff to be added. This declaration -% is global. It may be used more than one time and the arguments of -% each occurrence of it add up and are put at the beginning of input -% of every subsequent files. -% -% Simili modo, for the end of input, there's the -% \TextUsage\AtEndInput\ declaration, also one-argument, global and -% cumulative. -% -% If you need to add something at the beginning of input of only one -% file, put before the respective input command an -% \TextUsage\AtBegInputOnce|{|\|}| -% 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 -% succeeding it (the argument gets wrapped in a~macro that's |\relax|ed -% at the first use). |\AtBegInputOnce|s add up, too. -% -% \stanza -% One more input command is \TextUsage\IndexInput\ (the name and idea -% of effect comes from \docfm). It takes the same argument as -% |\DocInput|, the file's (path and) name with extension. (It -% \emph{has} |\DocInput| inside). It works properly if the input file -% doesn't contain explicit \ (|^^A| is \acro{OK}). -% -% The effect of this command is typesetting of all the input file -% verbatim, with the code lines numbered and the \CSs automatically -% indexed (\pk{gmdoc.sty} options are in force). -% -% -% \subdivision{Package options} -% -% As many good packages, this also provides some options: -% \stanza -% -% Due to best \TeX\ documenting traditions the codelines will be -% numbered. But if the user doesn't wish that, \heshe\ may turn it off -% with the \TextUsage*{linesnotnum} option. -% -% However, if \heshe\ agrees to have the lines numbered, \heshe\ may wish -% to reset the counter of lines \himher self, e.g., when \heshe\ -% documents many source files in one document. Then \heshe\ may wish -% the line numbers to be reset with every |{section}|'s turn for -% instance. This is the r\ocircum le of the \TextUsage*{uresetlinecount} -% option, which seems to be a~bit obsolete however, since the -% \TextCommonIndex\DocInclude|\DocInclude| command takes care of -% a~proper reset. -% -% Talking of line numbering further, a~tradition seems to exist to -% number only the codelines and not to number the lines of -% commentary. That's the default behaviour of \pk{gmdoc} but, if -% someone wants the comment lines to be numbered too, which may be -% convenient for reference purposes, \heshe\ is -% provided the \TextUsage*{countalllines} option. This option switches -% things to use the \cs{inputlineno} primitive for codeline numbers so -% you get the numbers of the source file instead of number only of the -% codelines. Note however, that there are no hypertargets made to the -% narration lines and the value of \cs{ref} is the number of the most -% recent codeline. -% -% Moreover, if \heshe\ wants to get the narration lines' number -% printed, there is the starred version of that option, -% \TextUsage*{countalllines*}. I~imagine someone may use it for -% debug. This option is not finished in details, it causes errors with -% \cs{addvspace} because it puts a~hyperlabel at every line. When it -% is in force, all the index entries are referenced -% with the line numbers and +\ProvidesClass{gmdoc} + [2010/09/25 v0.993 a documenting package (GM)] + + +%% %% ^^A( -% {\LineNumFont 441}\, the narration acquires a~bit biblical look ;-), -% {\LineNumFont 442}\,as shown in this short example. This option is intended -% {\LineNumFont 443}\,for the draft versions and it is not perfect (as if anything -% {\LineNumFont 444}\,in this package was). As you see, the lines -% {\LineNumFont 445}\,are typeset continuously with the numbers printed. -% -% \stanza -% By default the \pk{makeidx} package is loaded and 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 -% \TextUsage*{noindex} option. -% -% The index comes two possible ways: with the line numbers (if the -% lines are numbered) and that's the default, or with the page numbers, if -% the \TextUsage*{pageindex}\label{indexoptions} option is set. -% -% The references in the change history are of the same: when index is -% line number, then the changes history too. -% -% \stanza -% By default, \gmdoc\ excludes some 300 \CSs from being indexed. -% They are the most common \CSs, \LaTeX\ internal -% macros and \TeX\ primitives. To learn what \CSs are -% excluded actually, see lines \ref{DIE1}--\ref{DIE2}. -% -% If you don't want all those exclusions, you may turn them off with -% the \TextUsage*{indexallmacros} option. -% -% If you have ambiguous feelings about whether to let the default -% exclusions or forbid them, see p.\,\pageref{IEIDeclarations} to -% feed this ambiguity with a~couple of declarations. -% -% \stanza -% In \docfm\ package there's a~default behaviour of putting marked -% macro's or environment's name to a~marginpar. In the standard -% classes it's 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 -% non-standard classes the default behaviour is to disable marginpars. -% If the marginpars are enabled in \pk{gmdoc}, it will put marked -% control sequences and environments into marginpars (see -% \gmiflink[textUsage]{\cs{TextUsage} etc.}). These options do -% not affect common using marginpars, which depends on the -% document class. -% -% \stanza -% My suggestion is to make the spaces in the code visible except the -% leading ones and that's the default. But if you wish all the code -% spaces to be blank, I~give the option \TextUsage*{codespacesblank} -% reluctantly. Moreover, if you wish the code spaces to be blank only -% in some areas, then there's \TextUsage\CodeSpacesBlank\ declaration -% (\acro{OCSR}). -% -% Another space formatting option is \TextUsage*{codespacesgrey} -% suggested by Will Robertson. It makes the spaces of code visible -% only not black but grey. The name of their colour is -% |visspacesgrey| and by default it's defined as |{gray}{.5}|, you -% can change it with \pk{xcolor}'s |\definecolor|. There is also an -% \acro{OCSR} declaration \TextUsage\CodeSpacesGrey. -% -% If for any reason you wish the code spaces blank in general and -% visible and grey in \env{verbatim*}s, use the declaration -% \TextUsage\VisSpacesGrey\ of the \pk{gmverb} package. If you like -% little tricks, you can also specify -% |codespacesgrey, codespacesblank| in \pk{gmdoc} options (in this -% order). -% -% \subdivision{The packages required} -% -% \pk{gmdoc} requires (loads if they're not loaded yet) some other -% packages of mine, namely \pk{gmutils}, \pk{gmverb}, analogous to -% Frank Mittelbach's \pk{shortvrb}, and \pk{gmiflink} for conditional -% making of hyperlinks. It also requires \pk{hyperref}, -% \pk{multicol}, \pk{color} and \pk{makeidx}. -% -% The \pk{gmverb}\gmdmarginpar{\pk{gmverb}} package redefines the -% |\verb| command and the \env{verbatim} environment in such a~way that -% | |, |{| and |\| are breakable, the first with no `hyphen' and the -% other two with the comment char as a~hyphen, i.e., -% |{|\|}| breaks into -% |{%|\\ \|}| ^^A] bal. braces for Emacs -% 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 -% plain |\verb| typesets spaces blank and |\verb*| makes them visible, -% as in the standard version(s). -% -% Moreover, \pk{gmverb} provides the \TextUsage\MakeShortVerb\ -% declaration -% that takes a~one-char control sequence as the only argument and -% turns the char used into a~short verbatim delimiter, e.g., after -% \[\verb+\MakeShortVerb*\|+\] -% (as you see, the declaration has the starred version, which is for -% visible spaces, and non-starred for blank spaces) to get -% |\mylittlemacro| you may type \verb+|\mylittlemacro|+ instead of -% |\verb+\mylittlemacro+|. Because the char used in the last example -% is my favourite and is used this way by DEK in \TeXbook's -% format, \pk{gmverb} provides a~macro \TextUsage\dekclubs\ that -% expands to the example displayed above. -% -% Be careful because such active chars may interfere with other -% things, e.g., the \verb+|+ with the vertical line marker in \env{tabular}s and -% with the \pk{tikz} package. If this happens, you can declare e.g., -% \TextUsage\DeleteShortVerb\verb+\|+ and the previous meaning of the -% char used shall be restored. -% -% One more difference between \pk{gmverb} and \pk{shortvrb} is that -% the chars |\active|ated by |\MakeShortVerb|, behave as if they were -% `other' in math mode, so you may type e.g., \verb+$k|n$+ to get -% $k|n$ etc. -% \stanza -% -% The \pk{gmutils}\gmdmarginpar{\pk{gmutils}} package provides a~couple of -% macros similar to some basic \LaTeXpar\ ones, rather strictly -% technical and (I~hope) tricky, such as |\afterfi|, |\ifnextcat|, -% |\addtomacro| etc. It's this package that provides the macros for -% formatting of names of macros and files, such as |\cs|, |\marg|, |\pk| -% etc. 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 -% probably the most important package required. The recommended -% situation is that the user loads \pk{hyperref} package with \hisher\ -% favourite options \emph{before} loading \pk{gmdoc}. -% -% If \heshe\ does not, \pk{gmdoc} shall load it with \emph{my} -% favourite options. -% -% To avoid an error if a~(hyper)referenced label does not exist, -% \pk{gmdoc} uses the \pk{gmiflink}\gmdmarginpar{\pk{gmiflink}} -% package. It works e.g., in the index when the codeline numbers have -% been changed: then they are still typeset, only not as hyperlinks -% but as a~common text. -% -% \stanza -% To typeset the index and the change history in balanced columns -% \gmdoc\ uses the \gmdmarginpar{\pk{multicol}}\pk{multicol} package -% that seems to be standard these days. -% -% Also the \gmdmarginpar{\pk{color}}\pk{multicol} package, required to -% define the default colour of the hyperlinks, seems to be standard -% already, and \pk{makeidx}. -% -% \subdivision[Automatic marking of definitions]{^^B -% \gmhypertarget{Automatic marking of definitions}} -% \gmdoc\ implements automatic detection of a~couple of -% definitions. By default it detects all occurrences of the following -% commands in the code: -%\begin{enumerate}^^B -%\item \label{def type} -% |\def|, -% |\newcount|, -% |\newdimen|, -% |\newskip|, -% |\newif|, -% |\newtoks|, -% |\newbox|, -% |\newread|,\\ -% |\newwrite|, -% |\newlength|, -% |\newcommand›[*›]|, -% |\renewcommand›[*›]|, -% |\providecommand›[*›]|, -% |\DeclareRobustCommand›[*›]|, -% |\DeclareTextCommand›[*›]|,\\ -% |\DeclareTextCommandDefault›[*›]|, -% |\DeclareDocumentCommand|, -% |\Decl⁄-are⁄-Com⁄-mand|\rrthis -% -% \item -% |\newenvironment›[*›]|, -% |\renewenvironment›[*›]|, -% |\DeclareOption|, -%^^A~ |%\DeclareDefining*\@namedef| -% -% \item \label{newctr} -% |\newcounter|, -% -% \xdef\gmdenumi{\arabic{enumi}} -% \end{enumerate} -% -% of the \pk{xkeyval} package: -% \begin{enumerate}\setcounter{enumi}{\gmdenumi}^^B -% \item\label{dk type} |\define@key|, -% |\define@boolkey|, -% |\define@choicekey|, -% |\DeclareOptionX|, -% -% \xdef\gmdenumi{\arabic{enumi}} -% \end{enumerate} -% -% and of the \pk{kvoptions} package: -% \begin{enumerate}\setcounter{enumi}{\gmdenumi}^^B -% \item \label{DSOption} -% |\DeclareStringOption|, -% |\DeclareBoolOption|, -% |\DeclareComplementaryOption|,\\ -% |\DeclareVoidOption|.\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 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, -% use the \TextUsage\DeclareDefining\ declaration. It comes in two -% flavours: `saut\eacute' and with star. The `saut\eacute' version -% (without star and without an optional argument) declares a~defining -% command of the kind of |\def| and |\newcommand|: its main argument, -% whether wrapped in braces or not, is a~\CS. The starred version (without -% the optional argument) declares a~defining command of the kind of -% |\newenvironment| and |\DeclareOption|: whose main mandatory -% argument is text. Both versions provide an optional argument in -% which you can set the keys. -% -% Probably the most important key is \TextUsage*{type}. Its default -% value is |cs| and that is set in the `saut\eacute' version. Another -% possible value is |text| and that is set in the starred version. You -% can also set three other types (any keyval setting of the type -% overrides the default and `starred' setting): |dk|, |dox| or |kvo|. -% -% |dk| stands for |\define@key| and is the type of \pk{xkeyval} -% definitions of keys (group \ref{dk type} commands). When detected, -% it scans 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[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 -% \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 -% |\DeclareOptionX| definitions. -% -% |kvo| stands for the \pk{kvoptions} package by Heiko Oberdiek. This -% package provides a~handful of option defining commands (the group -% \ref{DSOption} commands). Detection of such a~command launches -% a~scan for mandatory \arg{option name} and alternate indexing of -% a~\CS |\|\|@|\