diff options
author | Karl Berry <karl@freefriends.org> | 2018-12-29 22:50:33 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2018-12-29 22:50:33 +0000 |
commit | 8bf197469266dba0e4307bfa90d6320130f4b2d8 (patch) | |
tree | 62aa18601b3bbd7b7529f914c95165e488bf8767 /Master/texmf-dist | |
parent | 120c0c49c7474dd161886fd979a0126398043d3d (diff) |
changelog (29dec18)
git-svn-id: svn://tug.org/texlive/trunk@49529 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist')
-rw-r--r-- | Master/texmf-dist/doc/latex/changelog/changelog.pdf | bin | 260697 -> 267778 bytes | |||
-rw-r--r-- | Master/texmf-dist/doc/latex/changelog/changelog.tex | 166 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/changelog/changelog-doc.sty | 39 | ||||
-rw-r--r-- | Master/texmf-dist/tex/latex/changelog/changelog.sty | 162 |
4 files changed, 224 insertions, 143 deletions
diff --git a/Master/texmf-dist/doc/latex/changelog/changelog.pdf b/Master/texmf-dist/doc/latex/changelog/changelog.pdf Binary files differindex d5187c65e46..ab2efe1c24d 100644 --- a/Master/texmf-dist/doc/latex/changelog/changelog.pdf +++ b/Master/texmf-dist/doc/latex/changelog/changelog.pdf diff --git a/Master/texmf-dist/doc/latex/changelog/changelog.tex b/Master/texmf-dist/doc/latex/changelog/changelog.tex index 71ee96584ec..6408ef3b968 100644 --- a/Master/texmf-dist/doc/latex/changelog/changelog.tex +++ b/Master/texmf-dist/doc/latex/changelog/changelog.tex @@ -1,9 +1,9 @@ \documentclass{ltxdoc} +\errorcontextlines=10 \usepackage{changelog-doc} \author{Rebecca Turner\thanks{Brandeis University; \email{rebeccaturner@brandeis.edu}}} \title{The \cl\ Package} -\date{2018-11-06} - +\date{2018-10-29} \begin{document} \maketitle @@ -12,7 +12,7 @@ for typesetting changelogs in \LaTeX. \cl\ defines a \env{changelog} environment to make changelogs simple and intuitive. - For rationale, read \https{keepachangelog.com}. + For rationale, read \keepachangelog. \end{abstract} \noterepo{9999years/latex-changelog} @@ -21,12 +21,44 @@ \vfill \pagebreak +\section{I don't want to read this documentation} + +Perfectly understandable. \cl\ comes in a ``simple'' flavor: + +\begin{mdframed} +\begin{lstsample}{}{} +% \begin{changelog}[author=Rebecca Turner, simple, sectioncmd=\section*] +% \begin{version}[v=1.0.0, date=2018-12-28] +% \item Cool features +% \item Bug fixes +% \end{version} +% \shortversion{v=0.1.0, date=2018-10-25, changes=Initial beta} +% \end{changelog} +\end{lstsample} +\end{mdframed} + +And a more organized variant based on \keepachangelog: + +\begin{mdframed} +\begin{lstsample}{}{} +% \begin{changelog}[author=Rebecca Turner, sectioncmd=\section*] +% \begin{version}[v=1.0.0, date=2018-12-28] +% \added +% \item Cool features +% \fixed +% \item Bug fixes +% \end{version} +% \shortversion{v=0.1.0, date=2018-10-25, changes=Initial beta} +% \end{changelog} +\end{lstsample} +\end{mdframed} + \section{Intro} \subsection{Why?} Read \href{https://olivierlacan.com/}{Olivier Lacan}'s lovely site -\https{keepachangelog.com}. To excerpt: +\keepachangelog. To excerpt: \begin{adjustwidth}{1in}{1in} \subsubsection{What is a changelog?} @@ -131,6 +163,10 @@ of the other solutions here.}} yanked & Indicates that the release was revoked due to a ``serious bug or security issue''; prints a visible notice next to the version number \\ + simple & Indicates this version isn't split up into + \cs{added}, \cs{changed}, etc.\ categories; if this + option is given, a \env{version} environment acts + like a plain \env{itemize} \\ \end{Optionlist} \end{adjustwidth} \end{table} @@ -151,22 +187,37 @@ table~\ref{opt:version}, the following options are available for The \cl\ package defines several ``helper commands,'' which are colorized if the \option{color} package option has been given. See -section~\ref{sec:colors} for more information. These commands include a -trailing space; |\added a cool feature| will print with a space between -``Added'' and ''a cool feature''. - -\begin{macro}{\added}Prints an \cs{item} beginning with ``Added''\end{macro} -\begin{macro}{\changed}Prints an \cs{item} beginning with ``Changed''\end{macro} -\begin{macro}{\deprecated}Prints an \cs{item} beginning with ``Deprecated''\end{macro} -\begin{macro}{\removed}Prints an \cs{item} beginning with ``Removed''\end{macro} -\begin{macro}{\fixed}Prints an \cs{item} beginning with ``Fixed''\end{macro} -\begin{macro}{\security}Prints an \cs{item} beginning with ``Security''\end{macro} +section~\ref{sec:colors} for more information. These commands introduce a +\textit{set} of changes within the version. There must be at least one +\cs{item} between one of these commands and the end of the \env{version} +environment. + +\begin{macro}{\added}Introduces a list of \cs{item}s that represent added + features\end{macro} +\begin{macro}{\changed}Introduces a list of \cs{item}s that represent + changed features\end{macro} +\begin{macro}{\deprecated}Introduces a list of \cs{item}s that represent + deprecated features\end{macro} +\begin{macro}{\removed}Introduces a list of \cs{item}s that represent + features which have been removed\end{macro} +\begin{macro}{\fixed}Introduces a list of \cs{item}s that represent bug + fixes\end{macro} +\begin{macro}{\security}Introduces a list of \cs{item}s that represent + security-fixes and closed security holes\end{macro} \subsection{Customization} -The \env{changelog} environment wraps \env{description}, and the -\env{version} environment wraps \env{itemize}. One could customize these in -depth with \ctan{enumitem}. +The \env{changelog} environment wraps \env{changelogdescription} (which is +defined by default to be just the \env{description} environment), and the +\env{version} environment wraps \env{changelogitemize}. One could customize +these in depth with \ctan{enumitem}, as in: + +\begin{latexcode} +\usepackage{enumitem} +\renewenvironment{changelogitemize} + {\begin{itemize}[label=---]} + {\end{itemize}} +\end{latexcode} \begin{macro}{\changelogyanked} Prints the ``revoked release'' notice: \changelogyanked. See: @@ -205,82 +256,21 @@ you'll likely do fine with just e.g.\ \cs{colorlet}|{ChangelogAdded}{magenta}|. color & Makes output more colorful; this is probably not that useful \end{Optionlist} -\begin{changelog}[author=Rebecca Turner, - sectioncmd=\subsection, - title=Example changelog] -\begin{version} - \added Really cool features -\end{version} - -\begin{version}[date=2019-01-23] - \item A version with only a date -\end{version} - -\begin{version}[v=1.1.0] - \item A version with no date -\end{version} - -\begin{version}[v=1.0.1, yanked] - \item A version with a terrible bug -\end{version} - -\begin{version}[v=1.0.0, date=2018-10-26] - \added a cool feature - \changed some \textsc{api} detail - \deprecated something that was a bad idea in the first place - \removed something that was deprecated 3 versions ago - \fixed a bug that would delete files instead of saving them - \security improved with addition of buffer bound checks - \item A change that doesn't fit into any other category -\end{version} -\shortversion{v=0.1.0, date=2018-10-19, - changes=Initial beta.} -\end{changelog} - -Which is produced with: - -\begin{latexcode} -\usepackage[color]{changelog} -%... -\begin{changelog}[author=Rebecca Turner, - sectioncmd=\subsection, - title=Example changelog] -\begin{version} - \added Really cool features -\end{version} - -\begin{version}[date=2019-01-23] - \item A version with only a date -\end{version} - -\begin{version}[v=1.1.0] - \item A version with no date -\end{version} - -\begin{version}[v=1.0.1, yanked] - \item A version with a terrible bug -\end{version} - -\begin{version}[v=1.0.0, date=2018-10-26] - \added a cool feature - \changed some \textsc{api} detail - \deprecated something that was a bad idea in the first place - \removed something that was deprecated 3 versions ago - \fixed a bug that would delete files instead of saving them - \security improved with addition of buffer bound checks - \item A change that doesn't fit into any other category -\end{version} -\shortversion{v=0.1.0, date=2018-10-19, - changes=Initial beta.} -\end{changelog} -\end{latexcode} - \section{Changelog} This is this package's actual changelog --- not an example! \begin{changelog}[author=Rebecca Turner, section=false] -\shortversion{v=0.3.0, date=2018-11-06, changes=Added proper dependencies} +\begin{version}[v=1.0.0, date=2018-12-28] +\added + \item The ``simple'' option for changelogs which aren't split up + into sections of added, changed, removed, etc.\ features +\changed + \item Instead of commands like \cs{added} introducing an item, they + introduce a list of items; this is what \keepachangelog\ + actually intended; previous implementations were incorrect to + display an ``Added'' (or whatever) marker next to each item. +\end{version} \shortversion{v=0.2.1, date=2018-10-26, changes=Documented \option{yanked} option} \shortversion{v=0.2.0, date=2018-10-26, changes=First stable release} diff --git a/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty b/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty index a097f718017..c839f386342 100644 --- a/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty +++ b/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty @@ -1,4 +1,5 @@ \usepackage{hypdoc} +\PassOptionsToPackage{writefile}{listings} \usepackage[ loadHyperref=false, createIndexEntries=false @@ -7,10 +8,12 @@ \PageIndex \EnableCrossrefs +\usepackage{lstdoc} \usepackage{textcomp} % needed for listings \usepackage{xparse} \usepackage{xkeyval} \usepackage{changepage} +\usepackage{mdframed} \usepackage[color]{changelog} @@ -18,7 +21,6 @@ \newcommand{\email}[1]{\href{mailto:#1}{\texttt{#1}}} \newcommand{\https}[1]{\href{https://#1}{\texttt{#1}}} -\newcommand{\cl}{\ctan{changelog}} \newcommand{\todo}[1]{\begin{itemize}\item[\textbf{To-do:}] #1 \end{itemize}} \newcommand{\note}[1]{\begin{itemize}\item[\textbf{Note:}] #1 \end{itemize}} \newcommand{\ctan}[1]{\href{https://ctan.org/pkg/#1}{\package{#1}}} @@ -29,6 +31,9 @@ \newcommand{\noterepo}[1]{\note{Browse the sources, contribute, or complain at \\ \https{github.com/#1}}} +\newcommand{\cl}{\ctan{changelog}} +\newcommand{\keepachangelog}{\https{keepachangelog.com}} + % definition copied from doc package \DescribeMacro \lstnewenvironment{latexfile}[1] {\lstset{style=lstDemoStyleLaTeXCode}% @@ -50,3 +55,35 @@ } } {\end{itemize}} + +\newif\ifsidebyside@first +\newcommand{\sidebyside@maybehfill}{% + \ifsidebyside@first + \hfill + \sidebyside@firstfalse + \fi +} +\newenvironment{sidebyside}{% + + \lstnewenvironment{code}[1][]{% + \lstset{style=lstDemoStyleLaTeXCode, + basicstyle=\ttfamily\small, + frame=single, + linewidth=0.45\linewidth, + ##1}% + } + {% + \sidebyside@maybehfill + }% + \newenvironment{example}{% + \begin{mdframed}[userdefinedwidth=0.45\linewidth] + } + {% + \end{mdframed}\sidebyside@maybehfill + }% + \sidebyside@firsttrue + \medskip + \noindent + } + {% + } diff --git a/Master/texmf-dist/tex/latex/changelog/changelog.sty b/Master/texmf-dist/tex/latex/changelog/changelog.sty index 79830d82a7e..53e7299bb90 100644 --- a/Master/texmf-dist/tex/latex/changelog/changelog.sty +++ b/Master/texmf-dist/tex/latex/changelog/changelog.sty @@ -1,14 +1,10 @@ -\ProvidesPackage{changelog}[2018-11-06 0.3.0 Typesetting changelogs] +\ProvidesPackage{changelog}[2018-12-28 1.0.0 Typesetting changelogs] % Description: Provides the changelog environment for typesetting changelogs % License: GPL-3.0 % Homepage: https://github.com/9999years/latex-changelog % https://ctan.org/pkg/changelog % Maintainer: Rebecca Turner <637275@gmail.com> -\RequirePackage{xparse} -\RequirePackage{xkeyval} -\RequirePackage{kvoptions} - \newif\ifchangelog@color\changelog@colorfalse \DeclareOption{color}{\changelog@colortrue} \ProcessOptions @@ -22,75 +18,133 @@ \colorlet{ChangelogRemoved} {red} \colorlet{ChangelogFixed} {cyan} \colorlet{ChangelogSecurity} {magenta} + \colorlet{ChangelogMiscellaneous}{.} - \newcommand{\@addversionshorthands}{ + \newcommand{\changelog@yanked@pre}{\color{ChangelogSecurity}} + % parameter = item type (Added, Changed, etc.) + \newcommand{\changelog@item@preitem}[1]{\color{Changelog#1}} + \newcommand{\changelog@item@postitem}{\hspace{0pt}} +\else + \newcommand{\changelog@yanked@pre}{} + \newcommand{\changelog@item@preitem}[1]{} + \newcommand{\changelog@item@postitem}{} +\fi - \newcommand{\added }{\item{\textcolor{ChangelogAdded} {\textbf{Added}} }} - \newcommand{\changed }{\item{\textcolor{ChangelogChanged} {\textbf{Changed}} }} - \newcommand{\deprecated}{\item{\textcolor{ChangelogDeprecated}{\textbf{Deprecated}} }} - \newcommand{\removed }{\item{\textcolor{ChangelogRemoved} {\textbf{Removed}} }} - \newcommand{\fixed }{\item{\textcolor{ChangelogFixed} {\textbf{Fixed}} }} - \newcommand{\security }{\item{\textcolor{ChangelogSecurity} {\textbf{Security}} }} +\newif\ifchangelog@versionfirst +\newcommand{\changelog@item@pre}{% + \ifchangelog@versionfirst + \changelog@versionfirstfalse + \else + \end{changelogitemize} + \fi +} - } +\newcommand{\changelog@item}[1]{% + \noindent + \changelog@item@pre + {\changelog@item@preitem{#1}\textbf{#1}}\changelog@item@postitem + \begin{changelogitemize}% +} - \newcommand{\changelogyanked}{{\color{ChangelogSecurity}\fbox{\textbf{YANKED}}}} -\else - \newcommand{\@addversionshorthands}{ - \newcommand{\added} {\item Added\ } - \newcommand{\changed} {\item Changed\ } - \newcommand{\deprecated}{\item Deprecated\ } - \newcommand{\removed} {\item Removed\ } - \newcommand{\fixed} {\item Fixed\ } - \newcommand{\security} {\item Security\ } - } - \newcommand{\changelogyanked}{\fbox{\textbf{YANKED}}} -\fi +\newcommand{\changelogyanked}{{\changelog@yanked@pre\fbox{\textbf{YANKED}}}} + +\newcommand{\changelog@sectioncmds}{ + \newcommand{\added} {\changelog@item{Added}} + \newcommand{\changed} {\changelog@item{Changed}} + \newcommand{\deprecated}{\changelog@item{Deprecated}} + \newcommand{\removed} {\changelog@item{Removed}} + \newcommand{\fixed} {\changelog@item{Fixed}} + \newcommand{\security} {\changelog@item{Security}} + \newcommand{\misc} {\changelog@item{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@cmdkeys{changelog}{sectioncmd, title, label} \define@boolkey{changelog}{section}[true]{} \presetkeys{changelog}{sectioncmd=\section, title=Changelog, label=sec:changelog, section}{} -\NewDocumentEnvironment{changelog}{o} - {\IfValueT{#1}{\setkeys{changelog, version}{#1}}% +\newenvironment{changelogdescription} + {\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} + \expandafter\label{\cmdKV@changelog@label}% \fi +} + +\newcommand{\changelog@shortversion@definedate}{% + \@ifundefined{cmdKV@version@version}{ + \@ifundefined{cmdKV@version@date}{ + \newcommand{\cmdKV@version@version}{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}{\end{changelogitemize}} + +\NewDocumentEnvironment{changelog}{o} + {\IfValueT{#1}{\setkeys{changelog, version}{#1}}% + \changelog@section@maybe %\today % version environment; wraps a list \NewDocumentEnvironment{version}{ O{} } - {\shortversion{##1}% - \begin{itemize} - \@addversionshorthands - } - {\end{itemize}}% + {\setkeys{version}{##1}% + \@shortversion + \changelog@version@pre} + {\changelog@version@post}% - % short version; "like" a 1-bullet list - \NewDocumentCommand{\shortversion}{m}{{% - \setkeys{version}{##1}% - \@ifundefined{cmdKV@version@version}{ - \@ifundefined{cmdKV@version@date}{ - \newcommand{\cmdKV@version@version}{Unreleased} - \let\cmdKV@version@date\today - }{% - \let\cmdKV@version@version\cmdKV@version@date - \let\cmdKV@version@date\undefined - }% - }{}% - \item[\cmdKV@version@version - \ifKV@version@yanked\ \changelogyanked\fi] - \@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)}% + % doesn't set keys so this can share code with the version + % environment + \NewDocumentCommand{\@shortversion}{}{{% + \changelog@shortversion@definedate + \item[\changelog@shortversion@item] + \changelog@shortversion@authordate \@ifundefined{cmdKV@version@changes}{}{ --- \cmdKV@version@changes} }} - \begin{description}} - {\end{description}} + + % short version; "like" a 1-bullet list + % extra braces keep command definitions local + \NewDocumentCommand{\shortversion}{m}{{ + \setkeys{version}{##1}% + \@shortversion + }} + \begin{changelogdescription}} + {\end{changelogdescription}} |