diff options
Diffstat (limited to 'macros/latex/contrib/skdoc/skdoc.dtx')
-rw-r--r-- | macros/latex/contrib/skdoc/skdoc.dtx | 117 |
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} }% |