From 4b3d1bc803a0fb6b5a3546bcebb5a5cb25f55951 Mon Sep 17 00:00:00 2001 From: Frank Mittelbach Date: Tue, 16 Nov 2021 13:11:25 +0100 Subject: [PATCH] =?UTF-8?q?Added=20^^X=20as=20an=20alternative=20comment?= =?UTF-8?q?=20char=20(as=20^^A=20often=20gives=20^=C3=84=20on=20keyboards)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- base/changes.txt | 8 ++--- base/doc.dtx | 76 ++++++++++++++++++++++++++------------------ base/doc/doc-doc.tex | 4 --- 3 files changed, 48 insertions(+), 40 deletions(-) delete mode 100644 base/doc/doc-doc.tex diff --git a/base/changes.txt b/base/changes.txt index 23a4042f7..55ef89207 100644 --- a/base/changes.txt +++ b/base/changes.txt @@ -6,11 +6,6 @@ completeness or accuracy and it contains some references to files that are not part of the distribution. ================================================================================ -================================================================================ -All changes above are only part of the development branch for the next release. -================================================================================ - - 2021-11-14 Frank Mittelbach * doc.dtx: Replaced doc.dtx with V3 version. @@ -26,6 +21,9 @@ All changes above are only part of the development branch for the next release. Added our default .cfg for extraction. Added option "nocfg" to bypass a system cfg. +================================================================================ +All changes above are only part of the development branch for the next release. +================================================================================ ######################### # 2021-11-15 Release diff --git a/base/doc.dtx b/base/doc.dtx index 1bc889795..ee48e779e 100644 --- a/base/doc.dtx +++ b/base/doc.dtx @@ -224,10 +224,10 @@ % %\NewDocElement[macrolike = false , % toplevel = false, -% idxtype = option , -% idxgroup = Package options , -% printtype = \textit{option} -% ]{Option}{option} +% idxtype = key , +% idxgroup = Package keys , +% printtype = \textit{key} +% ]{Key}{key} % % \renewcommand\code[1]{\mbox{$\ell$-#1}} % \renewcommand\main[1]{\underline{\mbox{$\ell$-#1}}} @@ -390,6 +390,8 @@ \usepackage[T1]{fontenc} \usepackage{xspace} +\OnlyDescription + \EnableCrossrefs %\DisableCrossrefs % Say \DisableCrossrefs if index is ready \CodelineIndex @@ -418,11 +420,11 @@ % \NewIn{v3} % Starting with version~3 the \DOC package now offers a small number % of package options to modify its overall behavior. These are: -% \DescribeOption[noprint]{multicol} -% \DescribeOption[noprint]{hyperref} -% \DescribeOption[noprint]{debugshow} -% \DescribeOption[noprint]{noindex} -% \DescribeOption[noprint]{noprint} +% \DescribeKey[noprint]{multicol} +% \DescribeKey[noprint]{hyperref} +% \DescribeKey[noprint]{debugshow} +% \DescribeKey[noprint]{noindex} +% \DescribeKey[noprint]{noprint} % \begin{description} % \item[\opt{hyperref}] Boolean (default \texttt{true}). Load the % \pkg{hyperref} package and make index references to code lines @@ -464,9 +466,17 @@ % \LaTeX{} commands except that the character `|%|' cannot be % used as a comment character. % \SortIndex{\string^\string^A}{\string\verb\verbatimchar -% \string^\string^A\verbatimchar \encapchar usage} To allow user -% comments, the |^^A| character is defined as a comment character -% later on. Such `metacomments' may be also be included simply by +% \string^\string^A\verbatimchar \encapchar usage}^^A +% \SortIndex{\string^\string^X}{\string\verb\verbatimchar +% \string^\string^X\verbatimchar \encapchar usage} +% To allow user +% comments, the characters |^^A| and |^^X| are both defined as a comment character +% later on.\footnote{In version 2 it was only +% \texttt{\string^\string^A}, but many keyboards combine +% \texttt{\string^} and \texttt{A} and automatically turn it into +% ``Ä''; so \texttt{\string^\string^X} was added as an +% alternative in version 3.} +% Such `metacomments' may be also be included simply by % surrounding them with |\iffalse| \ldots~|\fi|. % % All other parts of the file are called `definition parts'. They @@ -604,7 +614,7 @@ % argument in which you can specify \opt{noindex} or \opt{noprint} or % both to suppress indexing or printing for that particular % instance. If any such setting is made on the environment level it -% overwrite whatever default was given when the \DOC element was +% overwrites whatever default was given when the \DOC element was % defined or when the package was loaded. % % @@ -688,13 +698,13 @@ % |\NewDocElement{Env}{environment}| % though that's not quite what has been done, as we will see later. % -% \DescribeOption[noprint]{macrolike} -% \DescribeOption[noprint]{envlike} -% \DescribeOption[noprint]{toplevel} -% \DescribeOption[noprint]{notoplevel} -% \DescribeOption[noprint]{idxtype} -% \DescribeOption[noprint]{printtype} -% \DescribeOption[noprint]{idxgroup} +% \DescribeKey[noprint]{macrolike} +% \DescribeKey[noprint]{envlike} +% \DescribeKey[noprint]{toplevel} +% \DescribeKey[noprint]{notoplevel} +% \DescribeKey[noprint]{idxtype} +% \DescribeKey[noprint]{printtype} +% \DescribeKey[noprint]{idxgroup} % The \meta{options} are keyword/value and define further details on % how that \DOC element should behave. They are: % \begin{description} @@ -1390,14 +1400,14 @@ % ]{ObsoleteInterfaceMacro}{omacro} %\end{verbatim} % -% Another type of category are the package options: +% Another type of category are the package keys: %\begin{verbatim} %\NewDocElement[macrolike = false , % toplevel = false, -% idxtype = option , -% idxgroup = Package options , -% printtype = \textit{option} -% ]{Option}{option} +% idxtype = key , +% idxgroup = Package keys , +% printtype = \textit{key} +% ]{Key}{key} %\end{verbatim} % % Finally we have \TeX{} counters (with a backslash in front) and @@ -1871,27 +1881,31 @@ % footnote to the title. % % -% The first thing that we do next is to get ourselves a new comment -% sign. Because all sensible signs are already occupied, we will -% choose one that can only be entered indirectly: +% The first thing that we do next is to get ourselves two alternative comment +% signs. Because all sensible signs are already occupied, we will +% choose some that can only be entered indirectly: % {\DoNotIndex{\^}^^A avoid misinterpretation !!!!! VERIFY % \begin{macrocode} \catcode`\^^A=14 +\catcode`\^^X=14 % \end{macrocode} % We repeat this statement at the beginning of the document in case % the \texttt{inputenc} package is used disabling it again. % \changes{v2.0b}{1998/05/19}{Init docs private comment char at begin % of document again (pr2581)} % \begin{macrocode} -\AtBeginDocument{\catcode`\^^A=14\relax} +\AtBeginDocument{\catcode`\^^A=14\relax\catcode`\^^X=14\relax} % \end{macrocode} % \SortIndex{\string^\string^A}{\string\verb\verbatimchar % \string^\string^A\verbatimchar +% \encapchar main}^^A +% \SortIndex{\string^\string^X}{\string\verb\verbatimchar +% \string^\string^X\verbatimchar % \encapchar main} % } % % -% \subsection{Options supported by \DOC{}} +% \subsection{Keys supported by \DOC{}} % % For historical reasons this uses \pkg{kvoptions} but this will be % replaced by using \texttt{l3keys} at some point in the future. @@ -1931,7 +1945,7 @@ \DeclareBoolOption[false]{outer} % \end{macrocode} % -% \subsection{Processing the package options} +% \subsection{Processing the package keys} % % \begin{macrocode} \ProcessKeyvalOptions* diff --git a/base/doc/doc-doc.tex b/base/doc/doc-doc.tex deleted file mode 100644 index c0328048f..000000000 --- a/base/doc/doc-doc.tex +++ /dev/null @@ -1,4 +0,0 @@ -% this will typeset only documentation but not the code - -\AtBeginDocument{\OnlyDescription} -\input{doc.dtx}