diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/changelog/changelog.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/changelog/changelog.tex | 292 |
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} |