[latex3-commits] [git/LaTeX3-latex3-latex2e] doc-v3beta: minor cleanup and section for ltnews35 (47160ec7)

[Frank Mittelbach]

Repository : https://github.com/latex3/latex2e
On branch  : doc-v3beta
Link       : https://github.com/latex3/latex2e/commit/47160ec70f52ee6a025d2b916c7f39166dcc65c6

>---------------------------------------------------------------

commit 47160ec70f52ee6a025d2b916c7f39166dcc65c6
Author: Frank Mittelbach <frank.mittelbach at latex-project.org>
Date:   Thu Nov 25 17:09:30 2021 +0100

    minor cleanup and section for ltnews35


>---------------------------------------------------------------

47160ec70f52ee6a025d2b916c7f39166dcc65c6
 base/doc.dtx          | 39 ++++++++++++++++++++-------------------
 base/doc/ltnews35.tex | 41 ++++++++++++++++++++++++++++++++++-------
 2 files changed, 54 insertions(+), 26 deletions(-)

diff --git a/base/doc.dtx b/base/doc.dtx
index 66688261..927e1470 100644
--- a/base/doc.dtx
+++ b/base/doc.dtx
@@ -5534,7 +5534,11 @@
 %    default), then we load the \pkg{hypdoc} package. That package
 %    currently expects some commands from \DOC version~2 being
 %    defined, so we first need to provide some dummy definitions for
-%    them
+%    them.
+%
+%    Midterm all this code in \pkg{hypdoc} should be directly included
+%    in \DOC. For now, while they are separate we have to do this
+%    juggling.
 %    \begin{macrocode}
 \ifdoc at hyperref
   \let\PrintDescribeMacro \@empty
@@ -5547,7 +5551,14 @@
 %    Annoying to code around issue \#22
 %    \begin{macrocode}
   \expandafter\let\expandafter\doc at eoph@@k\csname doc.sty-h@@k\endcsname
-  \RequirePackage{hypdoc}
+%    \end{macrocode}
+%    We load the package with the option it knows about. This way if
+%    it is later loaded again we don't get option clashes. The
+%    alternative is to delay the loading until \verb=\begin{document}=
+%    but that means we also have to delay a lot of other code so this
+%    is the simpler solution.
+%    \begin{macrocode}
+  \RequirePackage[numbers]{hypdoc}
   \expandafter\let\csname doc.sty-h@@k\endcsname\doc at eoph@@k
 %    \end{macrocode}
 %    After \pkg{hypdoc} got loaded we need to undefine those macros
@@ -5567,16 +5578,6 @@
   \def\doc at handleencap#1{\encapchar hdclindex{\the\c at HD@hypercount}{#1}}
 %    \end{macrocode}
 %    If that package is not loaded these helpers do little to nothing.
-%
-%    \pkg{hypdoc} sets up support for \cs{autoindex} defined by the
-%    amsmath documentation class, but it forgot to add it to the
-%    commands to disable in pdfstrings, as a result the amsmath
-%    documentation blew up when hyperref got added (and a package was
-%    mentioned in a title). So we do that here for now.
-%  \fmi{fix in the right place}
-%    \begin{macrocode}
-\pdfstringdefDisableCommands{\let\autoindex\@gobble }
-%    \end{macrocode}
 %    \begin{macrocode}
 \else
   \let\doc at providetarget\@empty
@@ -5590,12 +5591,10 @@
   \def\hdpindex   #1{\ifx\@nil#1\@nil\else\csname #1\expandafter\endcsname\fi}
 \fi
 %    \end{macrocode}
-
-
-
-
-
-
+%
+%
+%
+%
 %
 % \section{Integrating the \DOX package code}
 %
@@ -5621,7 +5620,9 @@
 %    for each
 %    \begin{macrocode}
 \ExplSyntaxOn
-
+%    \end{macrocode}
+%
+%    \begin{macrocode}
 \long\def\@doc at env#1#2#3{
 %    \end{macrocode}
 %    The |\endgroup| here closes the scanning of names (using special catcodes.
diff --git a/base/doc/ltnews35.tex b/base/doc/ltnews35.tex
index 0a297fa5..bf911e32 100644
--- a/base/doc/ltnews35.tex
+++ b/base/doc/ltnews35.tex
@@ -153,9 +153,35 @@
 
 \subsection{\pkg{doc} upgraded to version~3}
 
-\emph{document}
-
-
+After roughly three decades the \pkg{doc} package gets a cautious
+uplift, as already announced at the TUG conference 2019\Dash changes
+to \pkg{doc} are obviously always done in a leisurely manner.
+
+Given that most documentation is nowadays viewed on screen,
+\pkg{hyperref} support is added and by default enabled (suppress it
+with option \option{nohyperref}) so the internal cross-reference are
+properly resolved including those from the index back into the
+document.
+
+Furthermore, \pkg{doc} has now a general mechanism to define
+additional \enquote{doc} elements besides the two \texttt{Macro} and
+\texttt{Env} it did know in the past. This enables better
+documentation because you can now clearly mark different types of
+objects instead of simply calling them all \enquote{macros}.
+If desired, they can be collected together under a heading
+in the index so that you have a section just with your document
+interface commands, or with all parameters, or \ldots
+
+The code borrows ideas from Didier Verna's \pkg{dox} package (although
+the document level interface is different) and it makes use of Heiko
+Oberdiek's \pkg{hypdoc} package, which at some point in the future
+will be completely integrated, given that its whole purpose it to
+patch \pkg{doc}'s internal commands to make them \pkg{hyperref}-aware.
+
+All changes are expected to be upward compatible, but if you run into
+issues with older documentation using \pkg{doc} a simple and quick
+solution is to load the package as follows:
+\verb/\usepackage{doc}[=v2]/
 
 
 \subsection{Lua\TeX\ callback improvements}
@@ -166,10 +192,11 @@ The previous type \texttt{list} resulted in incorrect parameters when multiple
 handlers were set, therefore this only makes an existing restriction more
 explicit.
 
-Additionally the return value \texttt{true} for \texttt{list} callbacks is now
-handled internally and no longer passed on to the engine. This simplifies the
-handling of these callbacks and makes it easier to provide consistent
-interfaces for user defined \texttt{list} callbacks.
+Additionally the return value \texttt{true} for \texttt{list}
+callbacks is now handled internally and no longer passed on to the
+engine. This simplifies the handling of these callbacks and makes it
+easier to provide consistent interfaces for user defined \texttt{list}
+callbacks.
 
 \subsection{???}
 %