texlive[51166] Master/texmf-dist: rgltxdoc (19may19)

commits+karl at tug.org commits+karl at tug.org
Sun May 19 23:26:20 CEST 2019


Revision: 51166
          http://tug.org/svn/texlive?view=revision&revision=51166
Author:   karl
Date:     2019-05-19 23:26:20 +0200 (Sun, 19 May 2019)
Log Message:
-----------
rgltxdoc (19may19)

Modified Paths:
--------------
    trunk/Master/texmf-dist/doc/latex/rgltxdoc/rgltxdoc.pdf
    trunk/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx
    trunk/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty

Modified: trunk/Master/texmf-dist/doc/latex/rgltxdoc/rgltxdoc.pdf
===================================================================
(Binary files differ)

Modified: trunk/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx
===================================================================
--- trunk/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx	2019-05-19 21:26:07 UTC (rev 51165)
+++ trunk/Master/texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx	2019-05-19 21:26:20 UTC (rev 51166)
@@ -2,7 +2,7 @@
 %
 % Copyright (C) 2018-2019 by Richard Grewe <r-g+tex at 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,8 +303,8 @@
 % \end{KeyValTable}
 % A usage example for |\NewNiceDescription| can be found in the
 % implementation below.
-% 
 %
+%
 % \paragraph{Implementation}
 %
 % \begin{macro}{\NewNiceDescription}
@@ -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 at opt{default}{\cmdrgltxdoc at DescOpt@def}%
+     \rgltxdoc at opt{initially}{\cmdrgltxdoc at DescOpt@init}}%
+   \parbox[t]{\linewidth-\wd\z@}{%
+     \raggedright\cmdrgltxdoc at DescOpt@vals}%
+   \box\z@\endgroup}
+  {\SpecialOtherIndex{option-key}{option-keys}}
+\usepackage{xkeyval,calc}
+\define at key[rgltxdoc]{DescOpt}{vals}{%
+  \def\cmdrgltxdoc at DescOpt@vals{}\let\rgltxdoc@@sep\@empty%
+  \def\do##1{%
+    \protected at eappto\cmdrgltxdoc at DescOpt@vals{\rgltxdoc@@sep\texttt{##1}}%
+    \def\rgltxdoc@@sep{, }}%
+  \docsvlist{#1}}
+\define at cmdkey[rgltxdoc]{DescOpt}{init}{}
+\define at cmdkey[rgltxdoc]{DescOpt}{def}{}
+\newcommand\rgltxdoc at 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|.
+% 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
+\newcommand*\SpecialOtherIndex[3]{%
+  \@bsphack
+  \begingroup
+    \HD at target
+    \let\HDorg at encapchar\encapchar
+    \edef\encapchar usage{%
+      \HDorg at encapchar hdclindex{\the\c at HD@hypercount}{usage}%
+    }%
+    \rgltxdoc at nohyp@SpecialOtherIndex{#1}{#2}{#3}%
+  \endgroup
+  \@esphack}
+\newcommand\rgltxdoc at 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 at 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,7 +486,20 @@
 %    \end{macrocode}
 % \end{macro}
 %
+% \begin{macro}{\rgltxdoc at inmargin}
+% The |\rgltxdoc at 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 at inmargin[2]{%
+  \leavevmode\null\hbox to\z@{\hss%
+    \pbox[t]{3\marginparwidth}{#1}%
+    #2}}
+%    \end{macrocode}
+% \end{macro}
 %
+%
 % \subsection{Arguments, Keys, and Values}
 %
 % Longer descriptions of macro/environment arguments as well as of keys
@@ -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 at 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 at 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 at 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 at 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

Modified: trunk/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty	2019-05-19 21:26:07 UTC (rev 51165)
+++ trunk/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty	2019-05-19 21:26:20 UTC (rev 51166)
@@ -20,7 +20,7 @@
 %% 
 \NeedsTeXFormat{LaTeX2e}[1999/12/01]
 \ProvidesPackage{rgltxdoc}
-    [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]
 \RequirePackage{ifluatex}
 \RequirePackage{etoolbox}
 \ifbool{luatex}{
@@ -29,7 +29,8 @@
   \setmainlanguage[variant=american]{english}
 }{
   \RequirePackage[utf8]{inputenc}
-  \RequirePackage[english]{babel}
+  \@ifpackageloaded{babel}{}
+    {\RequirePackage[english]{babel}}
 }
 \RequirePackage[a4paper,twoside=false]{geometry}
 \RequirePackage[DIV=9,BCOR=2.25cm]{typearea}
@@ -47,9 +48,9 @@
   \DeclareFontShape{T1}{lmtt}{m}{it}{<->sub*lmtt/m/sl}{}
 }
 \RequirePackage{microtype}
-\RequirePackage{csquotes}
+\RequirePackage[autostyle=true]{csquotes}
 \MakeOuterQuote{"}
-\RequirePackage{enumitem}
+\RequirePackage[inline]{enumitem}
 \RequirePackage[columns=2]{idxlayout}
 \RequirePackage{varioref}
 \RequirePackage{hypdoc}
@@ -72,11 +73,46 @@
   {#1}{\SpecialEnvIndex}
 \NewNiceDescription{Counter}{#1}{#1}
                    {\SpecialOtherIndex{counter}{counters}}
-\newcommand\SpecialOtherIndex[3]{\@bsphack
+\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 at opt{default}{\cmdrgltxdoc at DescOpt@def}%
+     \rgltxdoc at opt{initially}{\cmdrgltxdoc at DescOpt@init}}%
+   \parbox[t]{\linewidth-\wd\z@}{%
+     \raggedright\cmdrgltxdoc at DescOpt@vals}%
+   \box\z@\endgroup}
+  {\SpecialOtherIndex{option-key}{option-keys}}
+\usepackage{xkeyval,calc}
+\define at key[rgltxdoc]{DescOpt}{vals}{%
+  \def\cmdrgltxdoc at DescOpt@vals{}\let\rgltxdoc@@sep\@empty%
+  \def\do##1{%
+    \protected at eappto\cmdrgltxdoc at DescOpt@vals{\rgltxdoc@@sep\texttt{##1}}%
+    \def\rgltxdoc@@sep{, }}%
+  \docsvlist{#1}}
+\define at cmdkey[rgltxdoc]{DescOpt}{init}{}
+\define at cmdkey[rgltxdoc]{DescOpt}{def}{}
+\newcommand\rgltxdoc at opt[2]{\ifdef{#2}
+  {\rgltxdoc@@sep\textsl{#1: }\texttt{#2}%
+   \def\rgltxdoc@@sep{, }}
+  {}}
+\newcommand*\SpecialOtherIndex[3]{%
+  \@bsphack
+  \begingroup
+    \HD at target
+    \let\HDorg at encapchar\encapchar
+    \edef\encapchar usage{%
+      \HDorg at encapchar hdclindex{\the\c at HD@hypercount}{usage}%
+    }%
+    \rgltxdoc at nohyp@SpecialOtherIndex{#1}{#2}{#3}%
+  \endgroup
+  \@esphack}
+\newcommand\rgltxdoc at 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}}
 \RequirePackage{pbox}
 \newcommand\rgltxdoc at Desc{\medskip\par\noindent\rgltxdoc at DescRec}
 \newcommand\rgltxdoc at DescRec[4]{%
@@ -84,9 +120,8 @@
     {\rgltxdoc at DescRec@i{#1}{#2}{#3}{#4}}%
     {\rgltxdoc at DescRec@i{#1}{#2}{#3}{#4}[]}}
 \def\rgltxdoc at DescRec@i#1#2#3#4[#5]#6#7{%
-  \leavevmode\null\hbox to\z@{\hss%
-    \pbox[t]{3\marginparwidth}{\ttfamily #1{#6}}%
-    \ifstrempty{#7}{\quad}{}}%
+  \rgltxdoc at inmargin{\ttfamily #1{#6}}%
+    {\ifstrempty{#7}{\quad}{}}%
   #2{#7}\relax
   \ifstrempty{#5}%
     {#3{#6}}%
@@ -94,6 +129,10 @@
   \ifnumgreater{#4}{1}%
     {\\\rgltxdoc at DescRec{#1}{#2}{#3}{#4-1}}%
     {\ifstrempty{#7}{}{\smallskip\par\noindent}\ignorespaces}}
+\newcommand\rgltxdoc at inmargin[2]{%
+  \leavevmode\null\hbox to\z@{\hss%
+    \pbox[t]{3\marginparwidth}{#1}%
+    #2}}
 \RequirePackage{keyvaltable}
 \kvtSet{headbg=black!10,rowbg=white..black!5}
 \NewKeyValTable{KeyDesc}{%
@@ -114,6 +153,9 @@
   \IfFileExists{#1.sty}
     {\textsf{#1}}
     {\rgltxdoc at err{Package `#1' not found. Spelling?}}}
+\newcommand\pkgnames{%
+  \def\do##1{\pkgname{##1}\def\do####1{, \pkgname{####1}}}%
+  \docsvlist}
 \newcommand\cmarg[1]{\mbox{\texttt{\string{#1\string}}}}
 \newcommand\coarg[1]{\mbox{\texttt{[#1]}}}
 \RequirePackage{hologo}
@@ -148,6 +190,7 @@
     {\expandafter\rgltxdoc at curlbltype@i\cref at currentlabel\@nil}}
 \def\rgltxdoc at curlbltype@i[#1][#2][#3]#4\@nil{#1}
 \newcommand\rgltxdoc at SaveSecs{%
+  \def\addcontentsline##1##2##3{}%
   \@for\SC:=chapter,section,subsection,subsubsection\do{%
     \@ifundefined{c@\SC}{}
       {\csedef{rgltx@@ctr@\SC}{\the\value{\SC}}%



More information about the tex-live-commits mailing list