summaryrefslogtreecommitdiff
path: root/Master
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-12-29 22:50:33 +0000
committerKarl Berry <karl@freefriends.org>2018-12-29 22:50:33 +0000
commit8bf197469266dba0e4307bfa90d6320130f4b2d8 (patch)
tree62aa18601b3bbd7b7529f914c95165e488bf8767 /Master
parent120c0c49c7474dd161886fd979a0126398043d3d (diff)
changelog (29dec18)
git-svn-id: svn://tug.org/texlive/trunk@49529 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master')
-rw-r--r--Master/texmf-dist/doc/latex/changelog/changelog.pdfbin260697 -> 267778 bytes
-rw-r--r--Master/texmf-dist/doc/latex/changelog/changelog.tex166
-rw-r--r--Master/texmf-dist/tex/latex/changelog/changelog-doc.sty39
-rw-r--r--Master/texmf-dist/tex/latex/changelog/changelog.sty162
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
index d5187c65e46..ab2efe1c24d 100644
--- a/Master/texmf-dist/doc/latex/changelog/changelog.pdf
+++ b/Master/texmf-dist/doc/latex/changelog/changelog.pdf
Binary files differ
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}}