From 556dfa7ef108ed2946da8b8f32106f881d064ce9 Mon Sep 17 00:00:00 2001 From: Karl Berry Date: Sun, 19 May 2019 21:26:20 +0000 Subject: rgltxdoc (19may19) git-svn-id: svn://tug.org/texlive/trunk@51166 c570f23f-e606-0410-a88d-b1316a301751 --- Master/texmf-dist/doc/latex/rgltxdoc/rgltxdoc.pdf | Bin 150853 -> 163440 bytes .../texmf-dist/source/latex/rgltxdoc/rgltxdoc.dtx | 140 +++++++++++++++++---- Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty | 61 +++++++-- 3 files changed, 171 insertions(+), 30 deletions(-) (limited to 'Master') diff --git a/Master/texmf-dist/doc/latex/rgltxdoc/rgltxdoc.pdf b/Master/texmf-dist/doc/latex/rgltxdoc/rgltxdoc.pdf index 4086db5524a..cdd3ec2761f 100644 Binary files a/Master/texmf-dist/doc/latex/rgltxdoc/rgltxdoc.pdf and b/Master/texmf-dist/doc/latex/rgltxdoc/rgltxdoc.pdf differ 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 % ------------------------------------------------------- -% +% % 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 @@ %\NeedsTeXFormat{LaTeX2e}[1999/12/01] %\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] % % %<*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 % %\fi diff --git a/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty b/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty index d750caa078d..df61ef9f4ff 100644 --- a/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty +++ b/Master/texmf-dist/tex/latex/rgltxdoc/rgltxdoc.sty @@ -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@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{, }} + {}} +\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}} \RequirePackage{pbox} \newcommand\rgltxdoc@Desc{\medskip\par\noindent\rgltxdoc@DescRec} \newcommand\rgltxdoc@DescRec[4]{% @@ -84,9 +120,8 @@ {\rgltxdoc@DescRec@i{#1}{#2}{#3}{#4}}% {\rgltxdoc@DescRec@i{#1}{#2}{#3}{#4}[]}} \def\rgltxdoc@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@inmargin{\ttfamily #1{#6}}% + {\ifstrempty{#7}{\quad}{}}% #2{#7}\relax \ifstrempty{#5}% {#3{#6}}% @@ -94,6 +129,10 @@ \ifnumgreater{#4}{1}% {\\\rgltxdoc@DescRec{#1}{#2}{#3}{#4-1}}% {\ifstrempty{#7}{}{\smallskip\par\noindent}\ignorespaces}} +\newcommand\rgltxdoc@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@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@curlbltype@i\cref@currentlabel\@nil}} \def\rgltxdoc@curlbltype@i[#1][#2][#3]#4\@nil{#1} \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}}% -- cgit v1.2.3