summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/skdoc/skdoc.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/skdoc/skdoc.dtx')
-rw-r--r--macros/latex/contrib/skdoc/skdoc.dtx117
1 files changed, 62 insertions, 55 deletions
diff --git a/macros/latex/contrib/skdoc/skdoc.dtx b/macros/latex/contrib/skdoc/skdoc.dtx
index d780344712..739be62048 100644
--- a/macros/latex/contrib/skdoc/skdoc.dtx
+++ b/macros/latex/contrib/skdoc/skdoc.dtx
@@ -1,7 +1,7 @@
% \iffalse
%% skdoc documentation class
%%
-%% Copyright (C) 2012-2020 by Simon Sigurdhsson <sigurdhsson@gmail.com>
+%% Copyright (C) 2012-2025 by Simon Sigurdhsson <sigurdhsson@gmail.com>
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public License, either version 1.3
@@ -73,7 +73,7 @@
%</driver>
%<class>\ProvidesExplClass{skdoc}
%<*class>
- {2020/11/16}{1.5d}{skdoc documentation class}
+ {2025/01/08}{1.5e}{skdoc documentation class}
%</class>
%
%<*driver>
@@ -132,7 +132,7 @@
% {}{\small\pagemark}
% \pagestyle{skdoc-class}
%
-% \version{1.5d}
+% \version{1.5e}
% \changes{1.0}{Initial version}
% \changes{1.1}{Added support for syntax highlighting using \pkg{minted}}
% \changes{1.1a}{Deprecate the use of \pkg{bibtex} in favour of \pkg{biblatex}}
@@ -148,6 +148,7 @@
% \changes{1.5b}{Track \pkg{expl3} changes (thanks to Phelype Oleinik). Replace \pkg{opensans} option \opt{osfigures} with \opt{oldstyle} (\#40)}
% \changes{1.5c}{Replace \pkg{scrpage} package with \pkg{scrlayer-scrpage} (thanks to Daniel Wunderlich)}
% \changes{1.5d}{Use compatibiltiy levels for \pkg{scrartcl} (\#44)}
+% \changes{1.5e}{Fix incompatibilities with \pkg{glossaries} (\#47). Use \pkg{minted2} instead of \pkg{minted}}
% \iffalse
%%% Don't forget to update the version number and release date of
%%% the package declaration on line 76!
@@ -221,8 +222,8 @@
% \label{ssec:option:highlight}
% The \opt{highlight} option enables or disabled syntax highlighting
% of the implementation code. Highlighting is performed using
-% \pkg{minted}, and falls back to no highlighting if there is no
-% \cs{write18} access, if \pkg{minted} is unavailable or if the
+% \pkg{minted2}, and falls back to no highlighting if there is no
+% \cs{write18} access, if \pkg{minted2} is unavailable or if the
% \texttt{pygmentize} binary can't be found.
% \Notice{On non-unix platforms, the test for \texttt{pygmentize}
% will likely fail. Therefore, syntax highlighting is not supported
@@ -471,7 +472,7 @@
%
% Since the \env{example} environment is based on the same mechanisms
% as \env{MacroCode}, (mostly) the same typesetting properties apply.
-% In particular, the code will be highlighted if \pkg{minted} is
+% In particular, the code will be highlighted if \pkg{minted2} is
% available. \Notice{Since the backend utilizes \cs{verbatim}, the
% usual caveats apply. In particular, leaving whitespace before
% \cs{end}\marg{example} will result in an extra newline at the end
@@ -679,7 +680,7 @@
% sensitivity to whitespace, for instance). As detailed by the
% description of the \opt{highlight} option (on page
% \pageref{ssec:option:highlight}), the environment will highlight
-% the code using \pkg{minted} if possible. Multiple \meta{key}s are
+% the code using \pkg{minted2} if possible. Multiple \meta{key}s are
% allowed, and the code will be written to all corresponding files.
%
% \subsubsection{Hiding the implementation}
@@ -827,7 +828,7 @@
% Set up some booleans used throughout the code.
% \begin{macro}{\g__skdoc_use_minted_bool}
% The \texttt{use_minted} boolean keeps track of wether we're using
-% \pkg{minted} or not. The default value is \emph{false}.
+% \pkg{minted2} or not. The default value is \emph{false}.
% \begin{macrocode}
\bool_new:N\g__skdoc_use_minted_bool
\bool_gset_false:N\g__skdoc_use_minted_bool
@@ -925,10 +926,10 @@
% \end{macrocode}
%
% \subsection{Special case: syntax highlighting}
-% We support syntax highlighting through \pkg{minted}, but only if
+% We support syntax highlighting through \pkg{minted2}, but only if
% we're running with unrestricted \cs{write18} access \emph{and}
% there exists a suitable executable (\texttt{pygmentize}). Since
-% \pkg{minted} bails out without \cs{write18} access, we have to test
+% \pkg{minted2} bails out without \cs{write18} access, we have to test
% that before even loading it.
%
% \subsubsection{A simple \cs{write18} test}
@@ -1017,7 +1018,7 @@
% \end{macro*}
%
% Using the macros defined above, we can test for both \cs{write18}
-% and \texttt{pygmentize}, loading \pkg{minted} and setting a flag
+% and \texttt{pygmentize}, loading \pkg{minted2} and setting a flag
% if both exist. If the option \opt{highlight} was supplied and set
% to \texttt{false}, we do nothing.
% \begin{macrocode}
@@ -1027,17 +1028,17 @@
\__skdoc_if_pygmentize:TF{
\bool_gset_true:N\g__skdoc_use_minted_bool
% \end{macrocode}
-% Since \pkg{minted} (through \pkg{fancyvrb}) loads \pkg{lineno}, and something
+% Since \pkg{minted2} (through \pkg{fancyvrb}) loads \pkg{lineno}, and something
% above already defines \cs{c@linenumber}, we have to resort to a bit of a hack
-% before we actually load \pkg{minted}.
+% before we actually load \pkg{minted2}.
% \begin{macrocode}
\cs_undefine:N\c@linenumber
\cs_undefine:N\cl@linenumber
\cs_undefine:N\p@linenumber
\cs_undefine:N\thelinenumber
- \RequirePackage{minted}
+ \RequirePackage{minted2}
% \end{macrocode}
-% Now that we have \pkg{minted}, we redefine the style of the line
+% Now that we have \pkg{minted2}, we redefine the style of the line
% numbers to match what we have further down for the non-highlighted
% mode.
% \begin{macrocode}
@@ -1216,7 +1217,7 @@
\def\PYZlb{[}
\def\PYZrb{]}
% \end{macrocode}
-% If there's no \texttt{pygmentize}, no \cs{write18} or no \pkg{minted},
+% If there's no \texttt{pygmentize}, no \cs{write18} or no \pkg{minted2},
% we display a warning message and proceed without highlighting.
% \begin{macrocode}
}{
@@ -1321,7 +1322,7 @@
\__skdoc_if_print_code:T{
\bool_if:NTF\g__skdoc_use_minted_bool{
% \end{macrocode}
-% If we're using \pkg{minted}, we set a few options ans open the
+% If we're using \pkg{minted2}, we set a few options ans open the
% output file.
% \begin{macrocode}
\bool_if:NF\g__skdoc_in_example_bool{
@@ -1341,7 +1342,7 @@
}
\bool_if:NF\g__skdoc_in_example_bool{
% \end{macrocode}
-% In all non-example code, \pkg{minted} or not, we output a small
+% In all non-example code, \pkg{minted2} or not, we output a small
% marker showing what file we are writing to.
% \begin{macrocode}
\marginnote{
@@ -1372,7 +1373,7 @@
\bool_if:NTF\g__skdoc_use_minted_bool{
% \end{macrocode}
% ...but if we're using minted, \enquote{a lot more} consists of also
-% writing the line to the file used by \pkg{minted}.
+% writing the line to the file used by \pkg{minted2}.
% \begin{macrocode}
\iow_now:Nx\minted@code{\the\verbatim@line}%
}{
@@ -1440,15 +1441,15 @@
\__skdoc_if_print_code:T{
\bool_if:NTF\g__skdoc_use_minted_bool{
% \end{macrocode}
-% If we're using \pkg{minted}, we still have to actually print the code.
+% If we're using \pkg{minted2}, we still have to actually print the code.
% We begin with closing the output file.
% \begin{macrocode}
\iow_close:N\minted@code%
% \end{macrocode}
-% A few spacing fixes are applied. Since \pkg{minted} uses
+% A few spacing fixes are applied. Since \pkg{minted2} uses
% \pkg{fancyvrb}, these negative \cs{vspace}s are derived from the
% \pkg{fancyvrb} documentation \parencite[pp.~46--47]{Rahtz10}. What
-% we want to do is to offset the spacing produced by \pkg{minted}, so
+% we want to do is to offset the spacing produced by \pkg{minted2}, so
% that we are in control.
% \begin{macrocode}
\bool_if:NF\g__skdoc_in_example_bool{
@@ -1457,7 +1458,7 @@
\vspace*{-\parskip}
}
% \end{macrocode}
-% Now, the internal \pkg{minted} macro \cs{minted@pygmentize} is called
+% Now, the internal \pkg{minted2} macro \cs{minted@pygmentize} is called
% to highlight and typeset the code, and the temporary file is removed.
% \begin{macrocode}
\minted@pygmentize{latex}%
@@ -1469,7 +1470,7 @@
\vspace*{-\partopsep}
}{
% \end{macrocode}
-% If we aren't using \pkg{minted}, we hack spaces with \cs{@esphack}
+% If we aren't using \pkg{minted2}, we hack spaces with \cs{@esphack}
% instead.
% \begin{macrocode}
\bool_if:NF\g__skdoc_in_example_bool{\@esphack}%
@@ -1976,7 +1977,7 @@
% \end{macrocode}
% The code coffin is now filled, after clearing it. It'll get filled
% with the contents of the verbatim environment, typeset like other
-% \env{MacroCode} environments in the document (\emph{i.e.} \pkg{minted}
+% \env{MacroCode} environments in the document (\emph{i.e.} \pkg{minted2}
% if possible).
% \begin{macrocode}
\coffin_clear:N\l__skdoc_example_code_coffin
@@ -2610,7 +2611,7 @@
% our own \pkg{glossaries} style.
% \begin{macrocode}
\newglossarystyle{docindex}{
- \glossarystyle{indexgroup}
+ \setglossarystyle{indexgroup}
\renewcommand*{\glspostdescription}{\unskip\leaders\hbox to 2.9mm{\hss.}\hfill\strut}
\renewenvironment{theglossary}{
\bool_gset_true:N\g__skdoc_no_index_bool
@@ -2622,10 +2623,7 @@
\end{multicols}
\bool_gset_false:N\g__skdoc_no_index_bool
}
- \renewcommand*{\glossaryentryfield}[5]{
- \item\glsentryitem{##1}\glstarget{##1}{##2}
- \ifx\relax##4\relax\else\space(##4)\fi
- ##3\glspostdescription\space ##5}
+ \renewcommand*{\glstreenamefmt}[1]{##1}
\renewcommand*{\glsgroupheading}[1]{
\IfStrEq{##1}{default}{
\item{\descfont\glssymbolsgroupname}
@@ -2753,6 +2751,8 @@
% \changes{1.4a}{Unconditionally add version \enquote{parent} to
% circumvent strange behaviour by \pkg{glossaries}. Also, gobble
% page numbers for similar reasons}
+% \changes{1.5e}{Added an extra intermediate layer of macros
+% (\cs{@changes}) to force expansion of \cs{skdoc@macroname@stylized}}
% \begin{macrocode}
\DeclareDocumentCommand\changes{mm}{%
\@bsphack
@@ -2763,35 +2763,40 @@
nonumberlist=true
}
\ifx\skdoc@macroname@key\@empty
- \newglossaryentry{#1-general}{
- type=changes,
- description={\generalname{}:~#2},
- parent={#1},
- sort={0},
- nonumberlist=true
- }
- \glsadd[types=changes,format=@gobble]{#1-general}
+ \exp_args:Ne\@changes{\generalname}{!general}{#1}{#2}
\else
- \newglossaryentry{#1-\skdoc@macroname@key}{
- type=changes,
- description={\skdoc@macroname@stylized{}:~#2},
- parent={#1},
- sort={\skdoc@macroname@key},
- nonumberlist=true
- }
- \glsadd[types=changes,format=@gobble]{#1-\skdoc@macroname@key}
+ \exp_args:Nee\@changes{\skdoc@macroname@stylized}{\skdoc@macroname@key}{#1}{#2}
\fi
\@esphack
}
% \end{macrocode}
% \end{macro}
+% \begin{macro}{\@changes}[2]
+% {A prefix prepended to the change log message}
+% {An internal key used for sorting changes within each version}
+% {The version in which the changes were made}
+% {A short description of the changes}
+% \begin{macrocode}
+\DeclareDocumentCommand\@changes{mmmm}{%
+ \newglossaryentry{#3-#2}{
+ type=changes,
+ name={#1},
+ description={#4},
+ parent={#3},
+ sort={#2},
+ nonumberlist=true
+ }
+ \glsadd[types=changes,format=@gobble]{#3-#2}
+}
+% \end{macrocode}
+% \end{macro}
%
% \subsubsection{Displaying the changelog}
% Displaying the changelog is equally simple. We begin by defining
% our own \pkg{glossaries} style.
% \begin{macrocode}
\newglossarystyle{changelog}{
- \glossarystyle{altlist}
+ \setglossarystyle{altlist}
\renewenvironment{theglossary}{
\bool_gset_true:N\g__skdoc_no_index_bool
\begin{multicols}{2}\begin{description}
@@ -2799,15 +2804,16 @@
\end{description}\end{multicols}
\bool_gset_false:N\g__skdoc_no_index_bool
}
- \renewcommand*{\glossaryentryfield}[5]{
+ \renewcommand*{\glossentry}[2]{
\par\vspace{5\p@}\relax
- \item[\glsentryitem{##1}\glstarget{##1}{##2}]
- \mbox{}\par\nobreak\@afterheading
+ \item[\glsentryitem{##1}\glstarget{##1}{\glossentryname{##1}}]
+ \mbox{}\par\nobreak\@afterheading
}
- \renewcommand{\glossarysubentryfield}[6]{%
+ \renewcommand*{\subglossentry}[3]{
\par\hspace*{\itemindent}
- \glssubentryitem{##2}%
- \glstarget{##2}{\strut}##4\glspostdescription\space ##6
+ \glssubentryitem{##2}\glstarget{##2}{\strut}%
+ \glossentryname{##2}:~\glossentrydesc{##2}%
+ \glspostdescription\space ##3
}
}
% \end{macrocode}
@@ -2939,7 +2945,7 @@
}%
\IfNoValueTF{#1}{}{\keys_set:nn{skdoc@package}{#1}}%
\def\@package{#2}%
- \title{The~\textbf{\pkg*{\@package}}~package}%
+ \title{The~\textbf{\textsf{\@package}}~package}%
}
% \end{macrocode}
% \end{macro}
@@ -2999,6 +3005,7 @@
\DeclareDocumentCommand\thepkg{}{\thepackage}
% \end{macrocode}
% \end{macro}
+% \changes{1.5e}{Always expand \cs{@title} when setting metadata}
% Additionally we define \cs{skdocpdfsettings}, which is also used
% by \cs{maketitle}, to include PDF metadata if the documentation
% is being compiled using \hologo{pdfLaTeX}.
@@ -3007,7 +3014,7 @@
\def\skdocpdfsettings{%
\hypersetup{%
pdfauthor = {\@author\space<\@plainemail>},
- pdftitle = {\@title},
+ pdftitle = {\text_purify:n{\@title}},
pdfsubject = {Documentation~of~LaTeX~package~\@package},
pdfkeywords = {\@package,~LaTeX,~TeX}
}%