Added ^^X as an alternative comment char (as ^^A often gives ^Ä on ke…

…yboards)

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  <Frank.Mittelbach@latex-project.org>
 
 	* 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

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*