texlive[49529] Master/texmf-dist: changelog (29dec18)
commits+karl at tug.org
commits+karl at tug.org
Sat Dec 29 23:50:33 CET 2018
Revision: 49529
http://tug.org/svn/texlive?view=revision&revision=49529
Author: karl
Date: 2018-12-29 23:50:33 +0100 (Sat, 29 Dec 2018)
Log Message:
-----------
changelog (29dec18)
Modified Paths:
--------------
trunk/Master/texmf-dist/doc/latex/changelog/changelog.pdf
trunk/Master/texmf-dist/doc/latex/changelog/changelog.tex
trunk/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty
trunk/Master/texmf-dist/tex/latex/changelog/changelog.sty
Modified: trunk/Master/texmf-dist/doc/latex/changelog/changelog.pdf
===================================================================
(Binary files differ)
Modified: trunk/Master/texmf-dist/doc/latex/changelog/changelog.tex
===================================================================
--- trunk/Master/texmf-dist/doc/latex/changelog/changelog.tex 2018-12-29 22:50:15 UTC (rev 49528)
+++ trunk/Master/texmf-dist/doc/latex/changelog/changelog.tex 2018-12-29 22:50:33 UTC (rev 49529)
@@ -1,9 +1,9 @@
\documentclass{ltxdoc}
+\errorcontextlines=10
\usepackage{changelog-doc}
\author{Rebecca Turner\thanks{Brandeis University; \email{rebeccaturner at 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 @@
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,23 +187,38 @@
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''.
+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}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}
+\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:
\href{https://keepachangelog.com/en/1.0.0/#yanked}{yanked releases on
@@ -205,82 +256,21 @@
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}
Modified: trunk/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty 2018-12-29 22:50:15 UTC (rev 49528)
+++ trunk/Master/texmf-dist/tex/latex/changelog/changelog-doc.sty 2018-12-29 22:50:33 UTC (rev 49529)
@@ -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 at first
+\newcommand{\sidebyside at maybehfill}{%
+ \ifsidebyside at first
+ \hfill
+ \sidebyside at firstfalse
+ \fi
+}
+\newenvironment{sidebyside}{%
+
+ \lstnewenvironment{code}[1][]{%
+ \lstset{style=lstDemoStyleLaTeXCode,
+ basicstyle=\ttfamily\small,
+ frame=single,
+ linewidth=0.45\linewidth,
+ ##1}%
+ }
+ {%
+ \sidebyside at maybehfill
+ }%
+ \newenvironment{example}{%
+ \begin{mdframed}[userdefinedwidth=0.45\linewidth]
+ }
+ {%
+ \end{mdframed}\sidebyside at maybehfill
+ }%
+ \sidebyside at firsttrue
+ \medskip
+ \noindent
+ }
+ {%
+ }
Modified: trunk/Master/texmf-dist/tex/latex/changelog/changelog.sty
===================================================================
--- trunk/Master/texmf-dist/tex/latex/changelog/changelog.sty 2018-12-29 22:50:15 UTC (rev 49528)
+++ trunk/Master/texmf-dist/tex/latex/changelog/changelog.sty 2018-12-29 22:50:33 UTC (rev 49529)
@@ -1,4 +1,4 @@
-\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
@@ -5,10 +5,6 @@
% https://ctan.org/pkg/changelog
% Maintainer: Rebecca Turner <637275 at gmail.com>
-\RequirePackage{xparse}
-\RequirePackage{xkeyval}
-\RequirePackage{kvoptions}
-
\newif\ifchangelog at color\changelog at colorfalse
\DeclareOption{color}{\changelog at colortrue}
\ProcessOptions
@@ -22,34 +18,50 @@
\colorlet{ChangelogRemoved} {red}
\colorlet{ChangelogFixed} {cyan}
\colorlet{ChangelogSecurity} {magenta}
+ \colorlet{ChangelogMiscellaneous}{.}
- \newcommand{\@addversionshorthands}{
+ \newcommand{\changelog at yanked@pre}{\color{ChangelogSecurity}}
+ % parameter = item type (Added, Changed, etc.)
+ \newcommand{\changelog at item@preitem}[1]{\color{Changelog#1}}
+ \newcommand{\changelog at item@postitem}{\hspace{0pt}}
+\else
+ \newcommand{\changelog at yanked@pre}{}
+ \newcommand{\changelog at item@preitem}[1]{}
+ \newcommand{\changelog at 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 at versionfirst
+\newcommand{\changelog at item@pre}{%
+ \ifchangelog at versionfirst
+ \changelog at versionfirstfalse
+ \else
+ \end{changelogitemize}
+ \fi
+}
- }
+\newcommand{\changelog at item}[1]{%
+ \noindent
+ \changelog at item@pre
+ {\changelog at item@preitem{#1}\textbf{#1}}\changelog at 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 at yanked@pre\fbox{\textbf{YANKED}}}}
+\newcommand{\changelog at sectioncmds}{
+ \newcommand{\added} {\changelog at item{Added}}
+ \newcommand{\changed} {\changelog at item{Changed}}
+ \newcommand{\deprecated}{\changelog at item{Deprecated}}
+ \newcommand{\removed} {\changelog at item{Removed}}
+ \newcommand{\fixed} {\changelog at item{Fixed}}
+ \newcommand{\security} {\changelog at item{Security}}
+ \newcommand{\misc} {\changelog at item{Miscellaneous}}
+}
+
\define at cmdkeys{version}{author, version, date, changes}
\define at key{version}{v}{\def\cmdKV at version@version{#1}}
\define at boolkey{version}{yanked}[true]{}
+\define at boolkey{version}{simple}[true]{}
\define at cmdkeys{changelog}{sectioncmd, title, label}
\define at boolkey{changelog}{section}[true]{}
@@ -56,41 +68,83 @@
\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 at section@maybe}{%
\ifKV at changelog@section
\expandafter\cmdKV at changelog@sectioncmd{\cmdKV at changelog@title}%
- \expandafter\label{\cmdKV at changelog@label}
+ \expandafter\label{\cmdKV at changelog@label}%
\fi
+}
+
+\newcommand{\changelog at shortversion@definedate}{%
+ \@ifundefined{cmdKV at version@version}{
+ \@ifundefined{cmdKV at version@date}{
+ \newcommand{\cmdKV at version@version}{Unreleased}
+ \let\cmdKV at version@date\today
+ }{%
+ \let\cmdKV at version@version\cmdKV at version@date
+ \let\cmdKV at version@date\undefined
+ }%
+ }{}%
+}
+
+\newcommand{\changelog at yanked@maybe}
+ {\ifKV at version@yanked\ \changelogyanked\fi}
+
+\newcommand{\changelog at shortversion@item}
+ {\cmdKV at version@version
+ \changelog at yanked@maybe}
+
+
+\newcommand{\changelog at shortversion@authordate}{%
+ \@ifundefined{cmdKV at version@author}{}{\cmdKV at version@author}
+ \@ifundefined{cmdKV at version@date}{%
+ % if both undefined, add a linebreak
+ \@ifundefined{cmdKV at version@author}{\hspace{0pt}}{}%
+ }{(\cmdKV at version@date)}%
+}
+
+\newcommand{\changelog at version@pre}{%
+ \par
+ \changelog at versionfirsttrue
+ \changelog at sectioncmds
+ \ifKV at version@simple
+ \begin{changelogitemize}
+ \fi
+}
+\newcommand{\changelog at version@post}{\end{changelogitemize}}
+
+\NewDocumentEnvironment{changelog}{o}
+ {\IfValueT{#1}{\setkeys{changelog, version}{#1}}%
+ \changelog at section@maybe
%\today
% version environment; wraps a list
\NewDocumentEnvironment{version}{ O{} }
- {\shortversion{##1}%
- \begin{itemize}
- \@addversionshorthands
- }
- {\end{itemize}}%
+ {\setkeys{version}{##1}%
+ \@shortversion
+ \changelog at version@pre}
+ {\changelog at version@post}%
+ % doesn't set keys so this can share code with the version
+ % environment
+ \NewDocumentCommand{\@shortversion}{}{{%
+ \changelog at shortversion@definedate
+ \item[\changelog at shortversion@item]
+ \changelog at shortversion@authordate
+ \@ifundefined{cmdKV at version@changes}{}{ --- \cmdKV at version@changes}
+ }}
+
% short version; "like" a 1-bullet list
- \NewDocumentCommand{\shortversion}{m}{{%
+ % extra braces keep command definitions local
+ \NewDocumentCommand{\shortversion}{m}{{
\setkeys{version}{##1}%
- \@ifundefined{cmdKV at version@version}{
- \@ifundefined{cmdKV at version@date}{
- \newcommand{\cmdKV at version@version}{Unreleased}
- \let\cmdKV at version@date\today
- }{%
- \let\cmdKV at version@version\cmdKV at version@date
- \let\cmdKV at version@date\undefined
- }%
- }{}%
- \item[\cmdKV at version@version
- \ifKV at version@yanked\ \changelogyanked\fi]
- \@ifundefined{cmdKV at version@author}{}{\cmdKV at version@author}
- \@ifundefined{cmdKV at version@date}{%
- % if both undefined, add a linebreak
- \@ifundefined{cmdKV at version@author}{\hspace{0pt}}{}%
- }{(\cmdKV at version@date)}%
- \@ifundefined{cmdKV at version@changes}{}{ --- \cmdKV at version@changes}
- }}
- \begin{description}}
- {\end{description}}
+ \@shortversion
+ }}
+ \begin{changelogdescription}}
+ {\end{changelogdescription}}
More information about the tex-live-commits
mailing list