summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/changelog/changelog.tex
diff options
context:
space:
mode:
authorKarl Berry <karl@freefriends.org>2018-10-28 21:06:14 +0000
committerKarl Berry <karl@freefriends.org>2018-10-28 21:06:14 +0000
commit4d1fe1c455eecb0f6d8c7039a842e7e370b6d09d (patch)
tree2f5cb5162fbe4d973c34c95d500018764ef8f6c2 /Master/texmf-dist/doc/latex/changelog/changelog.tex
parent8331a2748eb053e4c45a82481aa41ef22c44fb42 (diff)
changelog (28oct18)
git-svn-id: svn://tug.org/texlive/trunk@49012 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/changelog/changelog.tex')
-rw-r--r--Master/texmf-dist/doc/latex/changelog/changelog.tex292
1 files changed, 292 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/changelog/changelog.tex b/Master/texmf-dist/doc/latex/changelog/changelog.tex
new file mode 100644
index 00000000000..c9dc5639d00
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/changelog/changelog.tex
@@ -0,0 +1,292 @@
+\documentclass{ltxdoc}
+\usepackage{changelog-doc}
+\author{Rebecca Turner\thanks{Brandeis University; \email{rebeccaturner@brandeis.edu}}}
+\title{The \cl\ Package}
+\date{2018-10-26}
+
+\begin{document}
+\maketitle
+
+\begin{abstract}
+ Changelogs are important. Unfortunately, there are few facilities
+ for typesetting changelogs in \LaTeX. \cl\ defines a \env{changelog}
+ environment to make changelogs simple and intuitive.
+
+ For rationale, read \https{keepachangelog.com}.
+\end{abstract}
+
+\noterepo{9999years/latex-changelog}
+
+\tableofcontents
+\vfill
+\pagebreak
+
+\section{Intro}
+
+\subsection{Why?}
+
+Read \href{https://olivierlacan.com/}{Olivier Lacan}'s lovely site
+\https{keepachangelog.com}. To excerpt:
+
+\begin{adjustwidth}{1in}{1in}
+ \subsubsection{What is a changelog?}
+ A changelog is a file which contains a curated, chronologically
+ ordered list of notable changes for each version of a project.
+
+ \subsubsection{Why keep a changelog?}
+ To make it easier for users and contributors to see precisely what
+ notable changes have been made between each release (or version) of
+ the project.
+
+ \subsubsection{Who needs a changelog?}
+ People do. Whether consumers or developers, the end users of
+ software are human beings who care about what's in the software.
+ When the software changes, people want to know why and how.
+\end{adjustwidth}
+
+\subsection{The competition}
+
+It's always good to know the competition. Unfortunately, there isn't much
+here. Know of another package with similar functionality? Drop me a line or
+open a pull request!
+
+\begin{ctandescription}
+ \pkg{vhistory} provides a decent-looking changelog. However, it's
+ designed for short changes and provides a less-than-elegant
+ interface. Additionally, it's based on the \ctan{ltxtable}
+ package, meaning it makes restrictions on the contents of
+ version information and writes the table to a file.
+
+ \pkg{holtxdoc} has a decent changelog feature (via
+ Oberdiek's \env{History} and \env{Version} environments),
+ but \ctan{holtxdoc} ``contains some private macros and setup
+ for my needs. Thus do not use it.'' In addition, Oberdiek's
+ changelogs don't support multiple authors.
+
+ \pkg{gitlog} is an interesting idea, but \ctan{gitlog} ``is a
+ proof-of-concept release to allow users an early
+ evaluation\dots''
+
+ Also,
+ \href{https://keepachangelog.com/en/1.0.0/}{friends don't
+ let friends dump git logs into changelogs}.
+\end{ctandescription}
+
+\section{The \env{changelog} environment}
+
+\begin{macro}{changelog}\oarg{options}\AfterLastParam Wraps
+\env{description} while providing the \env{version} environment and the
+\cs{shortversion} command. In addition to the options shown in
+table~\ref{opt:changelog}, \meta{options} may contain any of the options for
+\env{version} (see figure~\ref{opt:version}) as a form of ``partial
+application''; this may be useful if, for example, most of your versions
+have the same author.
+
+\begin{table}[h]
+ \centering
+ \caption{Options for the \env{changelog} environment}
+ \label{opt:changelog}
+ \begin{adjustwidth}{1in}{1in}
+ \begin{Optionlist}
+ section & Insert a \cs{section} before the changelog?
+ Default: true \\
+ sectioncmd & Which sectioning command to use? Default:
+ \cs{section} \\
+ title & What to title the changelog section? Default:
+ \texttt{Changelog} \\
+ label & What to \cs{label} the section? Default:
+ \texttt{sec:changelog} \\
+ \end{Optionlist}
+ \end{adjustwidth}
+\end{table}
+\end{macro}
+
+\begin{macro}{version}\oarg{options}\AfterLastParam
+Gives a single version; wraps \env{itemize}.
+
+If the \option{date} option is absent, the date isn't printed.
+
+If the \option{v}/\option{version} option is absent, the date is used in its
+place.
+
+If both \option{version} and \option{date} are absent, the version is shown
+as \texttt{Unreleased} and \cs{today} is used for the date. \cs{today} isn't
+ideal (which is to say, not
+\href{https://en.wikipedia.org/wiki/ISO_8601}{\textsc{iso} 8601} compliant)
+but it's well-known and easy to redefine.\footnote{Try the \ctan{datetime2}
+package or
+\href{https://tex.stackexchange.com/questions/152392/date-format-yyyy-mm-dd}{any
+of the other solutions here.}}
+
+\begin{table}[h]
+ \centering
+ \caption{Options for the \env{version} environment}%
+ \label{opt:version}
+ \begin{adjustwidth}{1in}{1in}
+ \begin{Optionlist}
+ version & The version string for this version \\
+ v & An alias for \option{version} \\
+ author & The author(s) of this version \\
+ date & The date of this version's release \\
+ yanked & Indicates that the release was revoked due to a
+ ``serious bug or security issue''; prints a visible
+ notice next to the version number \\
+ \end{Optionlist}
+ \end{adjustwidth}
+\end{table}
+
+\end{macro}
+
+\begin{macro}{\shortversion}\marg{options}\AfterLastParam
+A short, one-line version. In addition to the options specified in
+table~\ref{opt:version}, the following options are available for
+\cs{shortversion}:
+
+ \begin{Optionlist}
+ changes & The changes to display for this version \\
+ \end{Optionlist}
+\end{macro}
+
+\subsection{Helper commands}
+
+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}
+
+\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}.
+
+\begin{macro}{\changelogyanked} Prints the ``revoked release'' notice:
+\changelogyanked. See:
+\href{https://keepachangelog.com/en/1.0.0/#yanked}{yanked releases on
+\texttt{keepachangelog.com}}.
+
+\end{macro}
+
+\subsection{Colors}%
+\label{sec:colors}
+
+Colored output is supported by \ctan{xcolor}, which defines several named
+colors (as seen in figure~\ref{fig:colors}); these colors may be redefined
+as needed. While the \ctan{xcolor} documentation goes into great detail,
+you'll likely do fine with just e.g.\ \cs{colorlet}|{ChangelogAdded}{magenta}|.
+
+\begin{figure}[h]
+ \centering
+ \begin{adjustwidth}{1in}{1in}
+ \begin{colorlist}
+ \item{ChangelogAdded}
+ \item{ChangelogChanged}
+ \item{ChangelogDeprecated}
+ \item{ChangelogRemoved}
+ \item{ChangelogFixed}
+ \item{ChangelogSecurity}
+ \end{colorlist}
+ \end{adjustwidth}
+ \caption{Colors provided by the \cl\ package}
+ \label{fig:colors}
+\end{figure}
+
+\subsubsection{Package options}
+
+\begin{Optionlist}
+ 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.2.1, date=2018-10-26, changes=Documented \option{yanked}
+ option}
+\shortversion{v=0.2.0, date=2018-10-26, changes=First stable release}
+\shortversion{v=0.1.0, date=2018-10-25, changes=Initial beta}
+\end{changelog}
+
+\PrintIndex
+\listoftables
+
+\end{document}