rgltxdoc (19may19)

git-svn-id: svn://tug.org/texlive/trunk@51166 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 119 insertions, 21 deletions

diff --git a/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx b/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx
index d09758dae1a..1f5f87603de 100644
--- a/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx
+++ b/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx
@@ -2,7 +2,7 @@
 %
 % Copyright (C) 2018-2019 by Richard Grewe <r-g+tex@posteo.net>
 % -------------------------------------------------------
-% 
+%
 % This file may be distributed and/or modified under the
 % conditions of the LaTeX Project Public License, either version 1.2
 % of this license or (at your option) any later version.
@@ -10,7 +10,7 @@
 %
 %    http://www.latex-project.org/lppl.txt
 %
-% and version 1.2 or later is part of all distributions of LaTeX 
+% and version 1.2 or later is part of all distributions of LaTeX
 % version 1999/12/01 or later.
 %
 % \fi
@@ -22,7 +22,7 @@
 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
 %<package>\ProvidesPackage{rgltxdoc}
 %<*package>
-    [2019/01/05 v1 Common documentation code used for Richard Grewe's packages]
+    [2019/05/04 v1.2 Common documentation code used for Richard Grewe's packages]
 %</package>
 %
 %<*driver>
@@ -105,8 +105,11 @@
 %
 % \section{Documentation Input}
 %
-% The documentation is expected to be written in UTF-8 and in US-english
-% language.
+% The documentation is expected to be written in UTF-8 and in US-English
+% language. If \pkgname{babel} is already loaded, it will not be loaded
+% again, though. This is to support packages that use other languages
+% than English in examples and load \pkgname{babel} accordingly.
+% \changes{v1.1}{2019/01/12}{load babel only if not yet loaded}
 %    \begin{macrocode}
 \ifbool{luatex}{
   \RequirePackage[utf8]{luainputenc}
@@ -114,7 +117,8 @@
   \setmainlanguage[variant=american]{english}
 }{
   \RequirePackage[utf8]{inputenc}
-  \RequirePackage[english]{babel}
+  \@ifpackageloaded{babel}{}
+    {\RequirePackage[english]{babel}}
 }
 %    \end{macrocode}
 %
@@ -172,7 +176,7 @@
 % We simplify quoting names through the \pkgname{csquotes} package and
 % register |"| to produce double opening/closing quotation marks.
 %    \begin{macrocode}
-\RequirePackage{csquotes}
+\RequirePackage[autostyle=true]{csquotes}
 \MakeOuterQuote{"}
 %    \end{macrocode}
 %
@@ -184,7 +188,7 @@
 % in documentation and visually improve the index through a two-column
 % layout.
 %    \begin{macrocode}
-\RequirePackage{enumitem}
+\RequirePackage[inline]{enumitem}
 \RequirePackage[columns=2]{idxlayout}
 %    \end{macrocode}
 %
@@ -260,11 +264,21 @@
 % \vref{sec:KeysValues:impl}.
 %
 % \NiceDescribeMacros{2}
-%   {\NiceDescribeCounte}{\oarg{idx}\marg{counter}\marg{qualifiers}}
+%   {\NiceDescribeCounter}{\oarg{idx}\marg{counter}\marg{qualifiers}}
 %   {\NiceDescribeCounters}{\marg{n}\oarg{idx$_1$}\marg{ctr$_1$}\marg{qual$_1$}\ldots\oarg{idx$_n$}\marg{ctr$_n$}\marg{qual$_n$}}
 % These macros are analogous to the above macros, but aimed for
 % documenting \hologo{LaTeX} counters.
 %
+% \NiceDescribeMacros{2}
+%   {\NiceDescribeKey}{\oarg{idx}\marg{keyname}\marg{keyconfig}}
+%   {\NiceDescribeKeys}{\marg{n}\oarg{idx$_1$}\marg{name$_1$}\marg{cfg$_1$}\ldots\oarg{idx$_n$}\marg{name$_n$}\marg{cfg$_n$}}
+% These macros are for documenting option keys, for instances of
+% packages \pkgname{xkeyval} or \pkgname{pgfkeys}.
+% The \meta{keyconfig} is a key-value list in which the keys "vals",
+% "init", and "def" can be used to specify the range of
+% expected/permitted values, the initial (preset) value, and the default
+% (if the key is provided without a value).
+%
 % \NiceDescribeMacro{\NewNiceDescription}{\marg{type}\marg{efmt}\marg{afmt}\marg{icmd}}
 % This macro is used internally for defining the above macros and can be
 % used for defining new types of entity descriptions. The following
@@ -289,7 +303,7 @@
 % \end{KeyValTable}
 % A usage example for |\NewNiceDescription| can be found in the
 % implementation below.
-% 
+%
 %
 % \paragraph{Implementation}
 %
@@ -350,17 +364,67 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+% \begin{macro}{\NiceDescribeKey}
+% \begin{macro}{\NiceDescribeKeys}
+% Option-key names are formatted as is. Arguments are split into the range
+% of values (|vals|), the initial value (|init|), and the default value
+% (|def| -- the value used when only the key but no value is specified
+% to the key). These three can be set as keys.  The index entry is
+% produced through |\SpecialOtherIndex| (see its documentation below).
+% \changes{v1.2}{2019/05/04}{macros added}
+%    \begin{macrocode}
+\NewNiceDescription{Key}{#1\,\textrm{=}\,\null}
+  {\begingroup
+   \newcommand\vmeta[1]{{\normalfont\meta{##1}}}%
+   \setkeys[rgltxdoc]{DescOpt}{#1}%
+   \setbox\z@\hbox{\qquad\let\rgltxdoc@@sep\@empty
+     \rgltxdoc@opt{default}{\cmdrgltxdoc@DescOpt@def}%
+     \rgltxdoc@opt{initially}{\cmdrgltxdoc@DescOpt@init}}%
+   \parbox[t]{\linewidth-\wd\z@}{%
+     \raggedright\cmdrgltxdoc@DescOpt@vals}%
+   \box\z@\endgroup}
+  {\SpecialOtherIndex{option-key}{option-keys}}
+\usepackage{xkeyval,calc}
+\define@key[rgltxdoc]{DescOpt}{vals}{%
+  \def\cmdrgltxdoc@DescOpt@vals{}\let\rgltxdoc@@sep\@empty%
+  \def\do##1{%
+    \protected@eappto\cmdrgltxdoc@DescOpt@vals{\rgltxdoc@@sep\texttt{##1}}%
+    \def\rgltxdoc@@sep{, }}%
+  \docsvlist{#1}}
+\define@cmdkey[rgltxdoc]{DescOpt}{init}{}
+\define@cmdkey[rgltxdoc]{DescOpt}{def}{}
+\newcommand\rgltxdoc@opt[2]{\ifdef{#2}
+  {\rgltxdoc@@sep\textsl{#1: }\texttt{#2}%
+   \def\rgltxdoc@@sep{, }}
+  {}}
+%    \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
 % \begin{macro}{\SpecialOtherIndex}
 % The |\SpecialOtherIndex|\marg{type}\marg{types}\marg{name} macro
 % adds an index entry of the given \meta{type} (with plural form
 % \meta{types}) and given \meta{name}.
-% The macro is a straightforward generalization of |\SpecialEnvIndex|.
-%    \begin{macrocode}
-\newcommand\SpecialOtherIndex[3]{\@bsphack
+% The macro is a straightforward generalization of |\SpecialEnvIndex|
+% (both from \pkgname{hypdoc} and from \pkgname{doc}).
+% \changes{v1.2}{2019/05/04}{enabled \pkgname{hypdoc} support}
+%    \begin{macrocode}
+\newcommand*\SpecialOtherIndex[3]{%
+  \@bsphack
+  \begingroup
+    \HD@target
+    \let\HDorg@encapchar\encapchar
+    \edef\encapchar usage{%
+      \HDorg@encapchar hdclindex{\the\c@HD@hypercount}{usage}%
+    }%
+    \rgltxdoc@nohyp@SpecialOtherIndex{#1}{#2}{#3}%
+  \endgroup
+  \@esphack}
+\newcommand\rgltxdoc@nohyp@SpecialOtherIndex[3]{%
   \index{#3\actualchar{\protect\ttfamily#3}
     (#1)\encapchar usage}%
   \index{#2:\levelchar#3\actualchar
-    {\protect\ttfamily#3}\encapchar usage}\@esphack}
+    {\protect\ttfamily#3}\encapchar usage}}
 %    \end{macrocode}
 % \end{macro}
 %
@@ -393,13 +457,12 @@
 % The following code creates the "margin" text (more precisely, a box to
 % the left of the text) and the \meta{args} next to it.
 %    \begin{macrocode}
-  \leavevmode\null\hbox to\z@{\hss%
-    \pbox[t]{3\marginparwidth}{\ttfamily #1{#6}}%
+  \rgltxdoc@inmargin{\ttfamily #1{#6}}%
 %    \end{macrocode}
 % If there is no \meta{args}, then the margin part is moved towards the
 % left by a |\quad|.
 %    \begin{macrocode}
-    \ifstrempty{#7}{\quad}{}}%
+    {\ifstrempty{#7}{\quad}{}}%
   #2{#7}\relax
 %    \end{macrocode}
 % Next, the index entries are created, through the comma-separated
@@ -423,6 +486,19 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\rgltxdoc@inmargin}
+% The |\rgltxdoc@inmargin|\marg{text}\marg{spacing} macro puts
+% \meta{text} into the margin of a newly started paragraph and uses
+% \meta{spacing} to put additional horizontal spacing between
+% \meta{text} and the left side of the paragraph.
+%    \begin{macrocode}
+\newcommand\rgltxdoc@inmargin[2]{%
+  \leavevmode\null\hbox to\z@{\hss%
+    \pbox[t]{3\marginparwidth}{#1}%
+    #2}}
+%    \end{macrocode}
+% \end{macro}
+%
 %
 % \subsection{Arguments, Keys, and Values}
 %
@@ -439,12 +515,12 @@
 % \NiceDescribeEnv{KeyValTable}{\cmarg{ValDesc}}
 % This table is used for describing special values (constants). It has
 % two columns, |val| and |desc|, with their obvious meaning.
-% 
+%
 % \NiceDescribeEnv{KeyValTable}{\cmarg{ArgDesc}}
 % This table is used for describing arguments of macros and environments
 % in a structured fashion. It has two columns, |arg| and |desc|.
-% Examples of this kind of table can be found in \cref{sec:MacrosEnvs}. 
-% 
+% Examples of this kind of table can be found in \cref{sec:MacrosEnvs}.
+%
 % \paragraph{Implementation}\label{sec:KeysValues:impl}
 %
 % The \pkgname{keyvaltable} package is used for creating the tables that
@@ -484,7 +560,7 @@
 % \end{macro}
 %
 % \begin{macro}{\pkgname}
-% The |\pkgname|\meta{package-name} macro typesets package names in a
+% The |\pkgname|\marg{package-name} macro typesets package names in a
 % uniform font (sans-serif). Moreover, the package checks whether the
 % package actually exists, in order to identify embarrassing typos in
 % the package name.
@@ -495,6 +571,16 @@
     {\rgltxdoc@err{Package `#1' not found. Spelling?}}}
 %    \end{macrocode}
 % \end{macro}
+% \begin{macro}{\pkgnames}
+% The |\pkgnames|\marg{package-names} macro typesets a comma-separated
+% list of package names.
+% \changes{v1.2}{2019/05/04}{macro added}
+%    \begin{macrocode}
+\newcommand\pkgnames{%
+  \def\do##1{\pkgname{##1}\def\do####1{, \pkgname{####1}}}%
+  \docsvlist}
+%    \end{macrocode}
+% \end{macro}
 %
 % \begin{macro}{\cmarg}
 % \begin{macro}{\coarg}
@@ -626,8 +712,12 @@
 % |\rgltxdoc@RestoreSecs| macro restores the values of the section
 % counters. This allows one to use sectioning commands in code examples
 % without interfering with the section numbering in the documentation.
+% The |\rgltxdoc@SaveSecs| macro additionally disables the TOC macro,
+% such that example sections do not appear in the documentation's TOC.
+% \changes{v1.2}{2019/05/04}{disabled contents lines}
 %    \begin{macrocode}
 \newcommand\rgltxdoc@SaveSecs{%
+  \def\addcontentsline##1##2##3{}%
   \@for\SC:=chapter,section,subsection,subsubsection\do{%
     \@ifundefined{c@\SC}{}
       {\csedef{rgltx@@ctr@\SC}{\the\value{\SC}}%
@@ -658,6 +748,14 @@
 %    \end{macrocode}
 % \end{macro}
 % \end{macro}
+%
+% \section{Future Work}
+%
+% \begin{itemize}
+% \item Add keys, as listed in |KeyDesc| tables to the index
+%   automatically.
+% \end{itemize}
+%
 %\iffalse
 %</package>
 %\fi