diff options
author | Norbert Preining <norbert@preining.info> | 2023-02-18 03:01:32 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2023-02-18 03:01:32 +0000 |
commit | 4ff14bd6227f033e0d226f68a153f4a8c6458d16 (patch) | |
tree | 7ec4972c299f416960bd8426facbb245545d05e7 /macros/latex/contrib/changelog | |
parent | cb7cbc1f98cedde266389c64619b6dbfaec14f87 (diff) |
CTAN sync 202302180301
Diffstat (limited to 'macros/latex/contrib/changelog')
-rw-r--r-- | macros/latex/contrib/changelog/README.md | 14 | ||||
-rw-r--r-- | macros/latex/contrib/changelog/changelog.pdf | bin | 46523 -> 54725 bytes | |||
-rw-r--r-- | macros/latex/contrib/changelog/changelog.sty | 386 | ||||
-rw-r--r-- | macros/latex/contrib/changelog/changelog.tex | 55 | ||||
-rw-r--r-- | macros/latex/contrib/changelog/example.pdf | bin | 16679 -> 17624 bytes | |||
-rw-r--r-- | macros/latex/contrib/changelog/example.tex | 11 |
6 files changed, 312 insertions, 154 deletions
diff --git a/macros/latex/contrib/changelog/README.md b/macros/latex/contrib/changelog/README.md index 93e7c2834e..ab16196d1e 100644 --- a/macros/latex/contrib/changelog/README.md +++ b/macros/latex/contrib/changelog/README.md @@ -19,5 +19,19 @@ screenshot.png | Sample screenshot README.md | This file LICENSE.txt | LPPL v1.3c +## Development + +Sources for this package are [available on GitHub.][github] +This package is built with the [Nix][nix] package manager. + +- Build a release directory with rendered PDFs: + `nix build .#changelog` +- Build a release tarball: + `nix build .#changelog-tar`, or just `nix build` +- Enter a development shell with `latexmk` and fonts available: + `nix develop` + [keepachangelog.com]: https://keepachangelog.com/ [changelog]: https://ctan.org/pkg/changelog +[github]: https://github.com/9999years/latex-changelog +[nix]: https://zero-to-nix.com/ diff --git a/macros/latex/contrib/changelog/changelog.pdf b/macros/latex/contrib/changelog/changelog.pdf Binary files differindex 800b2ac365..c80cec01db 100644 --- a/macros/latex/contrib/changelog/changelog.pdf +++ b/macros/latex/contrib/changelog/changelog.pdf diff --git a/macros/latex/contrib/changelog/changelog.sty b/macros/latex/contrib/changelog/changelog.sty index 6c329e9a18..4c95edd805 100644 --- a/macros/latex/contrib/changelog/changelog.sty +++ b/macros/latex/contrib/changelog/changelog.sty @@ -1,4 +1,5 @@ -\ProvidesPackage{changelog}[2020/08/26 2.4.0 Typesetting changelogs] +\RequirePackage{expl3} +\ProvidesExplPackage{changelog}{2023/02/16}{2.5.0}{Typesetting changelogs} % Description: Provides the changelog environment for typesetting changelogs % License: LPPL 1.3c % Homepage: https://github.com/9999years/latex-changelog @@ -19,8 +20,6 @@ % % This work consists of the files changelog.sty and changelog.tex. -\RequirePackage{xparse} -\RequirePackage{xkeyval} \RequirePackage{translations} % See https://github.com/olivierlacan/keep-a-changelog/issues/195 @@ -95,148 +94,247 @@ \DeclareTranslation{Japanese}{changelog-Unreleased}{未公開} \DeclareTranslation{Japanese}{changelog-Yanked}{緊急変更} -\newif\ifchangelog@versionfirst -\newcommand{\changelog@item}[1]{% - \noindent - \ifchangelog@versionfirst - \changelog@versionfirstfalse - \else - \end{changelogitemize} - \fi - \textbf{#1}% - \begin{changelogitemize}% -} - -\newcommand{\changelogyanked}{\fbox{\textbf{\GetTranslation{changelog-Yanked}}}} - -\newcommand{\changelog@sectioncmds}{ - \newcommand{\added} {\changelog@item{\GetTranslation{changelog-Added}}} - \newcommand{\changed} {\changelog@item{\GetTranslation{changelog-Changed}}} - \newcommand{\deprecated}{\changelog@item{\GetTranslation{changelog-Deprecated}}} - \newcommand{\removed} {\changelog@item{\GetTranslation{changelog-Removed}}} - \newcommand{\fixed} {\changelog@item{\GetTranslation{changelog-Fixed}}} - \newcommand{\security} {\changelog@item{\GetTranslation{changelog-Security}}} - \newcommand{\misc} {\changelog@item{\GetTranslation{changelog-Miscellaneous}}} -} - -\define@cmdkeys{version}{author, version, date, changes} -\define@key{version}{v}{\def\cmdKV@version@version{#1}} -\define@boolkey{version}{yanked}[true]{} -\define@boolkey{version}{simple}[true]{} -\define@boolkey{version}{short}[true]{} - -\define@cmdkeys{changelog}{sectioncmd, title, label} -\define@boolkey{changelog}{section}[true]{} -\presetkeys{changelog}{sectioncmd=\section, title=\GetTranslation{changelog}, - label=sec:changelog, section}{} +\msg_new:nnnn { changelog } { missing_section } + { + Something's~wrong~in~version~environment;~perhaps~a~missing~ + \protect\added,~\protect\changed,~\protect\deprecated,~ + \protect\removed,~\protect\fixed,~\protect\security,~ + or~\protect\misc? + } + { + A~version~environment~needs~to~introduce~its~ + \protect\item-ized~lists~with~one~of~the~provided~section~commands;~ + maybe~you~meant~to~use~the~[simple]~option? + } + +\msg_new:nnnn { changelog } { missing_version } + { + No~versions~listed~in~changelog~environment~body. + } + { + A~changelog~environment~must~have~at~least~one~version~environment~or~ + \protect\shortversion~command~in~it. + } + +\bool_new:N \g__changelog_version_first_bool +\cs_set:Npn \changelog__item:n #1 + { + \noindent + \bool_if:NTF \g__changelog_version_first_bool + { + \bool_gset_false:N \g__changelog_version_first_bool + } + { + \end{changelogitemize} + } + \textbf{#1} + \begin{changelogitemize} + } + +\cs_set:Npn \changelogremark #1 + { + \fbox{\textbf{#1}} + } + +\cs_set:Npn \changelogyanked + { + \changelogremark{\GetTranslation{changelog-Yanked}} + } + +\tl_new:N \g__changelog_extra_section_cmds +\cs_set:Npn \changelog__define_section_cmds + { + \cs_set:Npn \added {\changelog__item:n{\GetTranslation{changelog-Added}}} + \cs_set:Npn \changed {\changelog__item:n{\GetTranslation{changelog-Changed}}} + \cs_set:Npn \deprecated {\changelog__item:n{\GetTranslation{changelog-Deprecated}}} + \cs_set:Npn \removed {\changelog__item:n{\GetTranslation{changelog-Removed}}} + \cs_set:Npn \fixed {\changelog__item:n{\GetTranslation{changelog-Fixed}}} + \cs_set:Npn \security {\changelog__item:n{\GetTranslation{changelog-Security}}} + \cs_set:Npn \misc {\changelog__item:n{\GetTranslation{changelog-Miscellaneous}}} + \tl_use:N \g__changelog_extra_section_cmds + } + +\NewDocumentCommand{\newchangelogsection}{m m} + { + \tl_gput_right:Nn \g__changelog_extra_section_cmds + { + \cs_set:Npn #1 + { + \changelog__item:n { #2 } + } + } + } + +\keys_define:nn { changelog_version } + { + author .tl_set:N = \g__changelog_author_tl , + v .tl_set:N = \g__changelog_version_tl , + version .tl_set:N = \g__changelog_version_tl , + date .tl_set:N = \g__changelog_date_tl , + changes .tl_set:N = \g__changelog_changes_tl , + yanked .bool_set:N = \g__changelog_yanked_bool , + simple .bool_set:N = \g__changelog_simple_bool , + short .bool_set:N = \g__changelog_short_bool , + remark .tl_set:N = \g__changelog_remark_tl , + remarks .clist_set:N = \g__changelog_remarks_clist , + } + +\keys_define:nn { changelog_changelog } + { + sectioncmd .tl_set:N = \g__changelog_sectioncmd_tl , + sectioncmd .initial:n = \section , + title .tl_set:N = \g__changelog_title_tl , + title .initial:n = \GetTranslation{changelog} , + label .tl_set:N = \g__changelog_label_tl , + label .initial:n = sec:changelog , + section .bool_gset:N = \g__changelog_section_bool , + section .initial:n = true , + } + +\keys_define:nn { } { changelog_changelog .inherit:n = changelog_version } \newenvironment{changelogdescription} - {\begin{description}} - {\end{description}} + {\begin{description}} + {\end{description}} \newenvironment{changelogitemize} - {\begin{itemize}} - {\end{itemize}} - -\newcommand{\changelog@section@maybe}{% - \ifKV@changelog@section - \expandafter\cmdKV@changelog@sectioncmd{\cmdKV@changelog@title}% - \expandafter\label{\cmdKV@changelog@label}% - \fi -} - -\newcommand{\changelog@shortversion@definedate}{% - \@ifundefined{cmdKV@version@version}{ - \@ifundefined{cmdKV@version@date}{ - \newcommand{\cmdKV@version@version}{\GetTranslation{changelog-Unreleased}} - \let\cmdKV@version@date\today - }{% - \let\cmdKV@version@version\cmdKV@version@date - \let\cmdKV@version@date\undefined - }% - }{}% -} - -\newcommand{\changelog@yanked@maybe} - {\ifKV@version@yanked\ \changelogyanked\fi} - -\newcommand{\changelog@shortversion@item} - {\cmdKV@version@version - \changelog@yanked@maybe} - - -\newcommand{\changelog@shortversion@authordate}{% - \@ifundefined{cmdKV@version@author}{}{\cmdKV@version@author} - \@ifundefined{cmdKV@version@date}{% - % if both undefined, add a linebreak - \@ifundefined{cmdKV@version@author}{\hspace{0pt}}{}% - }{(\cmdKV@version@date)}% -} - -\newcommand{\changelog@version@pre}{% - \par - \changelog@versionfirsttrue - \changelog@sectioncmds - \ifKV@version@simple - \begin{changelogitemize} - \fi -} -\newcommand{\changelog@version@post}{% - \ifchangelog@versionfirst - \ifKV@version@simple - \else - \PackageError{changelog}{Something's wrong in version environment; - perhaps a missing \protect\added, \protect\changed, - \protect\deprecated, \protect\removed, \protect\fixed, - \protect\security, or \protect\misc}{A version environment needs to - introduce its \protect\item-ized lists with one of the provided - section commands; maybe you meant to use the [simple] option?} - \fi - \fi - \end{changelogitemize}% -} - -\newif\ifchangelog@hadversion + {\begin{itemize}} + {\end{itemize}} + +\cs_set:Npn \changelog__section_maybe + { + \bool_if:NTF \g__changelog_section_bool + { + \exp_after:wN \g__changelog_sectioncmd_tl { \g__changelog_title_tl } + \exp_after:wN \label { \g__changelog_label_tl } + } + {} + } + +\cs_set:Npn \changelog__short_version_define_date + { + \tl_if_empty:NT \g__changelog_version_tl + { + \tl_if_empty:NTF \g__changelog_date_tl + { + \tl_set:Nn \g__changelog_version_tl { \GetTranslation{changelog-Unreleased} } + \tl_set:Nn \g__changelog_date_tl { \today } + } + { + \tl_set_eq:NN \g__changelog_version_tl \g__changelog_date_tl + } + } + } + +\cs_set:Npn \changelog__short_version_item + { + \tl_use:N \g__changelog_version_tl + \bool_if:NT \g__changelog_yanked_bool + { + \ \changelogyanked + } + \tl_if_empty:NF \g__changelog_remark_tl + { + \ \changelogremark{\tl_use:N \g__changelog_remark_tl} + } + \clist_if_empty:NF \g__changelog_remarks_clist + { + \clist_map_variable:NNn \g__changelog_remarks_clist \l__changelog_remark_tl + { + \ \changelogremark{\tl_use:N \l__changelog_remark_tl} + } + } + } + +\cs_set:Npn \changelog__short_version_author_date + { + \tl_use:N \g__changelog_author_tl + \tl_if_empty:NF \g__changelog_date_tl + { + \tl_if_empty:NF \g__changelog_author_tl + { ~ } + (\tl_use:N \g__changelog_date_tl) + } + } + +\cs_set:Npn \changelog__version_pre + { + \par + \bool_gset_true:N \g__changelog_version_first_bool + \changelog__define_section_cmds + \bool_if:NT \g__changelog_simple_bool + { + \begin{changelogitemize} + } + } + +\cs_set:Npn \changelog__version_post + { + \bool_if:NT \g__changelog_version_first_bool + { + \bool_if:NF \g__changelog_simple_bool + { + \msg_error:nn { changelog } { missing_section } + } + } + \end{changelogitemize} + } + +\bool_new:N \g__changelog_seen_version_bool \NewDocumentEnvironment{changelog}{o} - {\global\changelog@hadversionfalse - \IfValueT{#1}{\setkeys{changelog, version}{#1}}% - \changelog@section@maybe - %\today - % version environment; wraps a list - \NewDocumentEnvironment{version}{ O{} }% - {\setkeys{version}{##1}% - \@shortversion - \ifKV@version@short - \else - \changelog@version@pre - \fi} - {\ifKV@version@short - \else - \changelog@version@post - \fi}% - - % doesn't set keys so this can share code with the version - % environment - \NewDocumentCommand{\@shortversion}{}{% - \changelog@shortversion@definedate - \global\changelog@hadversiontrue - \item[\changelog@shortversion@item]% - \changelog@shortversion@authordate - \ifKV@version@short - \ --- - \@ifundefined{cmdKV@version@changes}{}{\cmdKV@version@changes}% - \fi - }% - - % short version; "like" a 1-bullet list - % extra braces keep command definitions local - \NewDocumentCommand{\shortversion}{m}{{% - \setkeys{version}{##1, short}% - \@shortversion - }}% - \begin{changelogdescription}} - {\ifchangelog@hadversion - \else - \PackageError{changelog}{No versions in changelog environment body}{A - changelog environment must have at least one version or shortversion in - it.}% - \fi\end{changelogdescription}} + { + \bool_gset_false:N \g__changelog_seen_version_bool + \IfValueT{#1}{\keys_set:nn{changelog_changelog}{#1}} + \changelog__section_maybe + + % Define the version environment, which wraps an `itemize`-style list. + \NewDocumentEnvironment{version}{ O{} } + { + \keys_set:nn { changelog_version } { ##1 } + \changelog__short_version + + \bool_if:NF \g__changelog_short_bool + { + \changelog__version_pre + } + } + { + \bool_if:NF \g__changelog_short_bool + { + \changelog__version_post + } + } + + % doesn't set keys so this can share code with the version + % environment + \cs_set:Npn \changelog__short_version + { + \changelog__short_version_define_date + \bool_gset_true:N \g__changelog_seen_version_bool + + \item[\changelog__short_version_item] + \changelog__short_version_author_date + + \bool_if:NT \g__changelog_short_bool + { + \ ---\ \tl_use:N \g__changelog_changes_tl + } + } + + % A short version; "like a 1-bullet list. + \NewDocumentCommand{\shortversion}{m} + % The extra braces here keep the keys we set local. + {{ + \keys_set:nn{changelog_version}{##1, short} + \changelog__short_version + }} + + \begin{changelogdescription} + } + { + \bool_if:NF \g__changelog_seen_version_bool + { + \msg_error:nn { changelog } { missing_version } + } + + \end{changelogdescription} + } diff --git a/macros/latex/contrib/changelog/changelog.tex b/macros/latex/contrib/changelog/changelog.tex index 3e5611dd5d..f4d0706350 100644 --- a/macros/latex/contrib/changelog/changelog.tex +++ b/macros/latex/contrib/changelog/changelog.tex @@ -17,14 +17,7 @@ } \makeatother -\setmainfont{Charter}[ - Path = /nix/store/8ylkcs5xw8b3glvgp5l66md6hvxdk098-charter-200512/share/fonts/opentype/, - Extension = .otf, - UprightFont = * Regular, - ItalicFont = * Italic, - BoldFont = * Bold, - BoldItalicFont = * Bold Italic, -] +\setmainfont{Charter} \usepackage{FiraSans} \usepackage{FiraMono} \lstset{basewidth=0.6em} @@ -35,9 +28,9 @@ \begin{description}} {\end{description}} -\author{Rebecca Turner\thanks{Brandeis University; \email{rbt@sent.as}}} +\author{Rebecca Turner\thanks{\email{rbt@sent.as}}} \title{The \cl\ Package} -\date{2020/08/26 2.4.0} +\date{2.5.0 (2023/02/16)} \begin{document} \maketitle @@ -159,6 +152,7 @@ versions have the same author. What to \cs{label} the section? \end{keys} +\pagebreak \begin{desc} |\begin{version}[<options>]...\end{version}| \end{desc} @@ -192,6 +186,10 @@ of the other solutions here.}} \key{yanked}[\bool][false] Indicates that the release was revoked due to a ``serious bug or security issue''; prints a visible notice next to the version number + \key{remark}[\m{remark}] + Adds a remark in the style of the |yanked| key. + \key{remarks}[\m{comma-separated list of remarks}] + Adds multiple remarks in the style of the |yanked| key. \key{simple}[\bool][false] Indicates this version isn't split up into \cs{added}, \cs{changed}, etc.\ categories; if this option is given, a |version| environment acts @@ -235,6 +233,21 @@ the \option{simple} option! \begin{desc}|\security|\end{desc}Introduces a list of \cs{item}s that represent security-fixes and closed security holes +\begin{desc}|\newchangelogsection{<command>}{<description>}|\end{desc} + Creates a new command like \cs{added}, \cs{changed}, etc., that can be + used in the |version| environment. + +\begin{LTXexample} +\newchangelogsection + {\critical}{Critical} +\begin{changelog}[section=false] + \begin{version}[v=1.0.0, date=2023-02-16] + \critical + \item Features! + \end{version} +\end{changelog} +\end{LTXexample} + \subsection{Customization} The |changelog| environment wraps |changelogdescription| (which is @@ -257,6 +270,12 @@ Prints the ``revoked release'' notice: \href{https://keepachangelog.com/en/1.0.0/#yanked}{yanked releases on \texttt{keepachangelog.com}}. +\begin{desc} +|\changelogremark{<remark>}| +\end{desc} +Prints a ``remark.'' This is used to implement |\changelogyanked| and the +|remark| and |remarks| keys of the |version| environment. + \section{Translations} Want to use \cl\ in a non-English document? Great! \cl\ comes with @@ -327,6 +346,22 @@ an email} and I'll incorporate the translation into \cl's next release! This is this package's actual changelog --- not an example! \begin{changelog}[author=Rebecca Turner <\email{rbt@sent.as}>, section=false] +\begin{version}[v=2.5.0, date=2023-02-16] +\added + \item Added the \cs{newchangelogsection} command to support custom + sections. + \item Added the |remark| and |remarks| keys to support custom remarks (like + ``YANKED'') on versions. + \item Added the |\changelogremark| command, which renders the ``YANKED'' + remark and other custom remarks. +\end{version} +\begin{version}[v=2.4.1, date=2023-02-14] +\changed + \item Converted the |changelog.sty| implementation to use the \ctan{expl3} + package. \ctan{expl3} provides a reasonable and well-defined programming + environment. I believe \ctan{expl3} is the future of programming in + \LaTeX, despite its verbosity. +\end{version} \begin{version}[v=2.4.0, date=2020-09-02, author={cmplstofB <\https{github.com/cmplstofB}>}] \added diff --git a/macros/latex/contrib/changelog/example.pdf b/macros/latex/contrib/changelog/example.pdf Binary files differindex 6cb7383b02..110ae72c38 100644 --- a/macros/latex/contrib/changelog/example.pdf +++ b/macros/latex/contrib/changelog/example.pdf diff --git a/macros/latex/contrib/changelog/example.tex b/macros/latex/contrib/changelog/example.tex index ad2272c5b8..9db61a2ea7 100644 --- a/macros/latex/contrib/changelog/example.tex +++ b/macros/latex/contrib/changelog/example.tex @@ -1,10 +1,13 @@ \documentclass{article} \usepackage{changelog} +\newchangelogsection{\critical}{Critical} \begin{document} \begin{changelog}[author=Rebecca Turner, sectioncmd=\subsection, title=Example changelog] \begin{version} +\critical + \item A critical new feature \added \item Really cool features \end{version} @@ -17,6 +20,14 @@ \item A version with no date \end{version} +\begin{version}[v=1.0.3, remark=Remark, simple] + \item A version with a remark. +\end{version} + +\begin{version}[v=1.0.2, remarks={Remark 1, Remark 2}, simple] + \item A version with multiple remarks. +\end{version} + \begin{version}[v=1.0.1, yanked, simple] \item A version with a terrible bug \end{version} |