fix for #531

base/changes.txt

@@ -6,11 +6,17 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2021-12-12  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
+
+	* doc.dtx (subsection[Dealing with the change history]):
+	Implement option recordchangedates to show dates  in the change log
+	if that option is used (gh/531).
+
 2021-12-11  Frank Mittelbach  <Frank.Mittelbach@latex-project.org>
 
 	* ltdirchk.dtx (section{Initialization}):
 	Add comment lines into latex.ltx to indicate temp definitions that
-	are later overwritten (gh/725)
+	are later overwritten (gh/725).
 
 2021-12-10  David Carlisle  <David.Carlisle@latex-project.org>
 

base/doc.dtx

@@ -48,7 +48,7 @@
 %<+beta>\ProvidesPackage{doc-v3beta}
 %</package>
 %<+shortvrb>\ProvidesPackage{shortvrb}
-%<+package|shortvrb>  [2022/06/01 v3.0f
+%<+package|shortvrb>  [2022/06/01 v3.0g
 %<+package|shortvrb>   Standard LaTeX documentation package V3 (FMi)]
 %\catcode`\<=12
 %
@@ -60,7 +60,7 @@
 %
 %
 %% Package `doc' to use with LaTeX 2e
-%% Copyright (C) 1989-2020 Frank Mittelbach, all rights reserved.
+%% Copyright (C) 1989-2022 Frank Mittelbach, all rights reserved.
 %
 %
 % Version:     Date:     Changes:
@@ -384,6 +384,7 @@
  %\DisableCrossrefs     % Say \DisableCrossrefs if index is ready
 \CodelineIndex
 \RecordChanges          % Gather update information
+\SetupDoc{reportchangedates}
  %\OnlyDescription      % comment out for implementation details
 \setlength\hfuzz{15pt}  % don't show so many
 \hbadness=7000          % over- and underfull box warnings
@@ -415,6 +416,7 @@
 % \DescribeOption[noprint]{debugshow}
 % \DescribeOption[noprint]{noindex}
 % \DescribeOption[noprint]{noprint}
+% \DescribeOption[noprint]{reportchangedates}
 % \begin{description}
 % \item[\opt{hyperref}, \opt{nohyperref}] Boolean (default \texttt{true}). Load the
 %    \pkg{hyperref} package and make index references to code lines
@@ -430,14 +432,17 @@
 %    various tracing information at the terminal and in the transcript
 %    file. In particular show which elements are indexed.
 %
-% \item[\opt{noindex}] Boolean (default \texttt{false}). If set all
+% \item[\opt{noindex}] Boolean (default \texttt{false}). If set, all
 %    automatic indexing is suppressed. This option can also be used on
 %    individual elements as described below.
 %
-% \item[\opt{noprint}] Boolean (default \texttt{false}). If set then
+% \item[\opt{noprint}] Boolean (default \texttt{false}). If set, then
 %    printing of element names in the margin will be suppressed. This
 %    option can also be used on individual elements as described
 %    below.
+% \item[\opt{reportchangedates}] Boolean (default \texttt{false}). If
+%    set, then change entries list the date after the version number in
+%    the change log.
 % \end{description}
 %
 % \DescribeInterfaceMacro{\SetupDoc} Instead of providing options to the \DOC
@@ -1912,13 +1917,14 @@
 %    \end{macrocode}
 % Some keys are available as options for use in \cs{usepackage} some are
 % for the generated item \api's:
-% \fmi{cleanup documentation (and code)}
+% \fmi{cleanup documentation (and code once the new key interface is there)}
 %    \begin{macrocode}
 \newif \ifdoc@noprint
 \newif \ifdoc@noindex
 \newif \ifdoc@hyperref \doc@hyperreftrue
 \newif \ifdoc@multicol \doc@multicoltrue
 \newif \ifdoc@debugshow
+\newif \ifdoc@reportchangedates
 \keys_define:nn {doc}
   {
     noprint  .choice:,
@@ -1949,6 +1955,10 @@
     debugshow / true  .code:n = { \legacy_if_set_true:n  { doc@debugshow } },
     debugshow / false .code:n = { \legacy_if_set_false:n { doc@debugshow } },
     debugshow  .default:n = { true },
+    reportchangedates  .choice:,
+    reportchangedates / true  .code:n = { \legacy_if_set_true:n  { doc@reportchangedates } },
+    reportchangedates / false .code:n = { \legacy_if_set_false:n { doc@reportchangedates } },
+    reportchangedates  .default:n = { true },
   }
 %    \end{macrocode}
 % This one is for \cs{usepackage} and \cs{NewDocElement}:
@@ -4430,7 +4440,15 @@
    \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore
    \changes@}
 \def\changes@#1#2#3{%
-  \protected@edef\@tempa{\noexpand\glossary{#1\levelchar
+  \protected@edef\@tempa{\noexpand\glossary{#1%
+%    \end{macrocode}
+%    If asked for we also show the date of in the change log (after
+%    the version).
+% \changes{v3.0g}{2022/06/01}{Show change dates if asked for (gh/531)}
+%    \begin{macrocode}
+                   \ifdoc@reportchangedates
+                     \space -- #2\fi
+                   \levelchar
 %    \end{macrocode}
 % \changes{v1.9u}{1995/08/06}{Use value of \cs{saved@macroname} to
 %          find out about change entries at outer level}

base/doc/ltnews35.tex

@@ -230,6 +230,22 @@ \subsection{\pkg{doc} upgraded to version~3}
 solution is to load the package as follows:
 \verb/\usepackage{doc}[=v2]/
 
+\subsection{\pkg{doc} can now show dates in change log}
+
+Up to now the change log was always sorted by version numbers
+(ignoring the date that was given in the \cs{changes} command).  It
+can now be sorted by both version and date if you specify the option
+\option{reportchangedates} on package level and in that case the
+changes are displayed with
+\begin{quote}
+  \meta{version} -- \meta{date}
+\end{quote}
+as the heading (instead of just \meta{version}), when using
+\cs{PrintChanges}.
+%
+\githubissue{gh/531}
+
+
 
 \subsection{Lua\TeX\ callback improvements}