summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/errata/errata.dtx
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/latex/contrib/errata/errata.dtx
Initial commit
Diffstat (limited to 'macros/latex/contrib/errata/errata.dtx')
-rw-r--r--macros/latex/contrib/errata/errata.dtx429
1 files changed, 429 insertions, 0 deletions
diff --git a/macros/latex/contrib/errata/errata.dtx b/macros/latex/contrib/errata/errata.dtx
new file mode 100644
index 0000000000..df0dac7e87
--- /dev/null
+++ b/macros/latex/contrib/errata/errata.dtx
@@ -0,0 +1,429 @@
+% \iffalse meta-comment
+% A Package for recording errata
+% Copyright (c) 2006 Michael Kohlhase, all rights reserved
+%
+% This file is distributed under the terms of the LaTeX Project Public
+% License from CTAN archives in directory macros/latex/base/lppl.txt.
+% Either version 1.0 or, at your option, any later version.
+%
+% The development version of this file can be found at
+% $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/errata/errata.dtx $
+% \fi
+%
+% \iffalse
+%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
+%<package>\ProvidesPackage{errata}[2006/11/121v0.3 Errata Management]
+%
+%<*driver>
+\documentclass[twoside]{ltxdoc}
+\DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
+\DoNotIndex{\begin,\AtEndDocument,\newcommand,\newcounter,\stepcounter}
+\DoNotIndex{\immediate,\openout,\closeout,\message,\typeout}
+\DoNotIndex{\section,\scshape,\arabic}
+
+\EnableCrossrefs
+%\CodelineIndex
+%\OnlyDescription
+\RecordChanges
+\usepackage{textcomp,url,float,a4wide}
+\usepackage[show]{ed}
+\usepackage[show]{errata}
+\usepackage[fancyhdr,today,draft]{svninfo}
+\pagestyle{fancyplain}\fancyhead[RE,LO]{\leftmark}\fancyhead[LE,RO]{\thepage}
+\floatstyle{boxed}
+\newfloat{exfig}{thp}{lop}
+\floatname{exfig}{Example}
+\begin{document}
+\svnInfo $Id: errata.dtx 13983 2007-11-04 14:34:39Z kohlhase $
+\svnKeyword $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/errata/errata.dtx $
+\DocInput{errata.dtx}
+\end{document}
+%</driver>
+% \fi
+%
+%\CheckSum{191}
+%
+% \changes{v0.1}{2006/07/18}{First Version with Documentation}
+% \changes{v0.2}{2006/08/01}{More Documentation and Keywords Management}
+% \changes{v0.3}{2006/11/21}{adding type Keyword}
+%
+% \GetFileInfo{errata.sty}
+%
+% \MakeShortVerb{\|}
+% \title{Recording Errata in {\LaTeX} Documents\thanks{Version {\fileversion} (last revised
+% {\filedate})}}
+% \author{Michael Kohlhase\\
+% Computer Science, Jacobs University, Bremen, Germany\\
+% \url{http://kwarc.info/kohlhase}}
+% \maketitle
+%
+% \begin{abstract}
+% This package provides a simple infrastructure for recording errata in {\LaTeX}
+% documents. This allows to maintain an updated version of the document (with all errors
+% corrected) and automatically generate an errata document highlighting the difference
+% to the published version.
+% \end{abstract}
+%
+% \section{Introduction}\label{sec:intro}
+%
+% The life-cycle of a document does not end with its publication. After that, errors will
+% be discovered, and have to be managed. The best way to do this is by marking errata in
+% the text and generating the errata document from that.\ednote{describe some more}
+%
+% \section{The User Interface}\label{sec:user-interface}
+%
+% The |errata| package can be called with a variety of package options.
+% \DescribeMacro{hide} The |show| and |hide| options govern the general visibility of the
+% errata markup. If |hide| is specified (the default, if no option is given), then errata
+% markup is totally invisible in the formatted document. \DescribeMacro{margins/foots}
+% The |margins| and |foots| options give finer control. If the |margins| (|foots|) option
+% is not given, then margin decorations (explanatory footnotes) are not generated.
+% \DescribeMacro{hide} the |hide| option is equivalent to |margins| and |foots|.
+%
+% \DescribeMacro{record} If the |record| option is specified, then errata are written to a
+% special file \meta{jobname}|-errata.tex| so that they can be included in an errata
+% document (see Section~\ref{sec:generating}).
+%
+% There are two kinds of errata, short ones or extended ones. We will go into them in the
+% next two subsections. All the errata macros take optional KeyVal arguments that specify
+% the metadata for the errata. \DescribeMacro{date=}We can specify the date when the
+% erratum was found, with the |date| key and\DescribeMacro{reported-by=} the person that
+% reported the erratum with with the |reported-by| key. Consider for instance the metadata
+% for the erratum in Example~\ref{fig:extended-erratum}; The date format follows the ISO
+% 8601 norm: it is of the form \meta{YYYY}|-|\meta{MM}|-|\meta{DD}, where \meta{YYYY} is
+% the 4-digit year, \meta{MM} the 2-digit month, and {\meta{DD}} the two-digit day of the
+% month. The format of the |reported-by| field is free\footnote{Remember to encasulate the
+% value in curly braces if the name contains a comma}. \DescribeMacro{id=}We can specify
+% an identifier for the erratum using the |id| key, so that we can refer back to it
+% later. \DescribeMacro{type=}Finally, we can use the |type| key to specify the type
+% (e.g. ``clarification'') of an erratum.
+%
+% \subsection{Short Errata}
+%
+% Short errata can be recorded by the marking up the editing operations needed for the
+% corrections. The following example in Example~\ref{fig:short-errata} shows all editing
+% operations, which we will detail now:
+%
+% \begin{exfig}
+% \begin{verbatim}
+% Here we have \erratumAdd{forgotten word}{three} errata
+% in one \erratumDelete{superfluous phrase}{darned} long
+% \erratumReplace{translated}{Zeile}{line}
+% \end{verbatim}
+% \caption{Some short errata}\label{fig:short-errata}
+% \end{exfig}
+%
+% \DescribeMacro{\erratumAdd} |\erratumAdd| marks up a correction by adding some text. The
+% first argument holds the explanation of the intended correctionand the second one the
+% new text.
+%
+% \DescribeMacro{\erratumDelete} |\erratumDelete| does the same for a correction by
+% deleting some text; here the second argument holds the deleted text. While the
+% |\erratumAdd| will copy the contents of the second argument to the result document,
+% |\erratumDelete| does not.
+%
+% \DescribeMacro{\erratumReplace}
+% |\erratumReplace{[|\meta{keys}|]|\meta{desc}|}{|\meta{old}|}{|\meta{new}|}| replaces
+% {\meta{old}} with {\meta{new}} in the result document.
+%
+% All of these macros mark the location of the errata in the margin and document the
+% changes in footnote-like structures. For instance, the text fragment above would be
+% rendered as
+% \begin{quote}
+% Here we have \erratumAdd{forgotten word}{three} errata
+% in one \erratumDelete{superfluous phrase}{darned} long
+% \erratumReplace{translated}{Zeile}{line}
+% \end{quote}
+%
+% \subsection{Extended Errata}
+%
+% \DescribeEnv{erratum} Extended errata group multiple editing operations into a coherent
+% group via the |erratum| environment. The first argument of this environment is an
+% explanation as for the short errata above. The |erratum| environment provides local
+% versions of the editing markup macros, which behave like those, but lack the first
+% (explanation) argument, which is already given in the environment that contains them.
+%
+% \begin{exfig}
+% \begin{verbatim}
+% \begin{erratum}[date=2006-07-19,reported-by=Michael Kohlhase]{old should be new}
+% this is a test of a long erratum
+% \begin{enumerate}
+% \item We can replace \eReplace{oldtext}{newtext}
+% \item and \eAdd{new text}
+% \item and finally delete old text\eDelete{alltogether}
+% \end{enumerate}
+% \end{erratum}
+% \end{verbatim}
+% \caption{An extended erratum with local correction markers}\label{fig:extended-erratum}
+% \end{exfig}
+%
+% This text fragment would be rendered as
+% \begin{quote}
+% \begin{erratum}[reported-by=Michael Kohlhase,date=2006-11-21]{old should be new}
+% this is a test of a long erratum
+% \begin{enumerate}
+% \item We can replace \eReplace{oldtext}{newtext}
+% \item and \eAdd{new text}
+% \item and finally delete old text\eDelete{alltogether}
+% \end{enumerate}
+% \end{erratum}
+% \end{quote}
+%
+% The |erratum| environment should also be used in situations where the error occurs in an
+% environment, where normal {\TeX/\LaTeX} processing is suspended, e.g. a |verbatim|
+% environment. In this case, we can use it to attach correction information via the
+% environment, but do not use the local change documentations.\ednote{what do we do in
+% floats? document}
+%
+% \subsection{Generating Statistics and Errata Documents}\label{sec:generating}
+%
+% \DescribeMacro{\erratamessage} Putting the macro |\erratamessage| just before the
+% |\end||{document}| will generate a message with cardinality information for the errata
+% into the log file.
+%
+% \DescribeMacro{\erratumItem} Errata can be marked up using the |\erratumItem| macro in
+% the the\DescribeEnv{errata} |errata| environment. The |\erratumItem| takes two
+% arguments, the first is a reference to where the erratum occurred, and the second one
+% the explanation.
+%
+% \DescribeMacro{\printerrata} The |\printerrata| command allows to print the errata for
+% another document. This command is useful when generating errata documents for published
+% works. Say we have a book with a driver file |thebook.tex|, into which we have
+% incorporated errata markup using the infrastructure detailed above. Then we have a new
+% document called e.g. |theerrata.tex| which has the form given in
+% Figure~\ref{fig:sample-errata-document}. Note that we have used |\printerrata{thebook}|
+% to include the errata notices generated from |thebook.tex|.
+% \begin{exfig}
+% \begin{verbatim}
+% \documentclass{article}
+% \usepackage[hide]{errata}
+% \title{Errata for The Book}
+% \begin{document}
+% \maketitle
+% \begin{abstract} This document tracks the errata in The Book. \end{abstract}
+% \section{Introduction}
+% ... The errata of The Book are tracked in this document, whose newest version can be
+% found at \url{.../berrata.pdf}. A version of The Book that contains all errata
+% corrections (and markup of what changed) can be found at \url{.../book.pdf}.
+%
+% In the following we will tabulate the errata in document order. Their location will be
+% referenced by the section they appear in rather than the page number, since we do not
+% expect the former to change in the errata correction process.
+%
+% \section{The Errata in The Book}
+% \printerrata{thebook}
+% \end{document}
+% \end{verbatim}
+% \caption{A Sample Errata Document}\label{fig:sample-errata-document}
+% \end{exfig}
+%
+% In the errata document in Figure~\ref{fig:sample-errata-document} we postulate that we
+% keep an updated version of The Book online\footnote{And indeed it is good practice to do
+% so if the copyright agreement with the publisher allows this.} using the
+% infrastructure provide by the |errata| package. \DescribeMacro{\printerrata} In the
+% updated version of |thebook.tex|, it can be useful to tabulate the errata as well,
+% e.g. in a section in the appendix. This can be done by the |\PrintErrata| command. Note
+% that this command needs to close the errata file |thebook-errata.tex| therefore we need
+% a |\newpage| to clear the queue of waiting |\writes| before |thebook-errata.tex| can be
+% loaded (otherwise we may be missing the errata from the last page).
+%
+% \StopEventually{\newpage\PrintChanges\newpage\section{The Errata of this Document}\printerrata{errata}\ednotemessage}
+%
+% \newpage
+% \section{The Implementation}
+%
+% The implementation is rather standard. We first set up the options for the package. The
+% main switches are |\ifmargins| and |\iffoots|, which govern the visibility of the
+% annotations in the margins and the footnotes.
+% \begin{macrocode}
+%<*package>
+\newif\ifmargins\marginsfalse
+\newif\iffoots\footsfalse
+\newif\ifrecord\recordfalse
+% \end{macrocode}
+% the next step is to declare the package options, they just set the switches accordingly.
+% \begin{macrocode}
+\DeclareOption{show}{\marginstrue\footstrue}
+\DeclareOption{hide}{}
+\DeclareOption{margins}{\marginstrue}
+\DeclareOption{foots}{\footstrue}
+\DeclareOption{record}{\recordtrue}
+\ProcessOptions
+% \end{macrocode}
+% This ends the package setup code, so we can come to the implementation of the
+% functionality of the package.
+%
+% We first make sure that the |Keyval| package is loaded.
+% \begin{macrocode}
+%<*package>
+\RequirePackage{keyval}[1997/11/10]
+% \end{macrocode}
+% and then define the actions that are undertaken when the keys are encountered. Here
+% this is very simple, we just define an internal macro with the value, so that we can use
+% it later.
+% \begin{macrocode}
+\define@key{erratum}{id}{\def\erratum@id{#1}}
+\define@key{erratum}{type}{\def\erratum@type{#1}}
+\define@key{erratum}{date}{\def\erratum@date{#1}}
+\define@key{erratum}{reported-by}{\def\erratum@reported-by{#1}}
+% \end{macrocode}
+%
+% \subsection{Recording Errata}
+%
+% The next step is to set up two counters for the errata.
+% \begin{macrocode}
+\newcounter{erratum}
+\newcounter{erratum@note}[erratum]
+% \end{macrocode}
+%
+% If the |record| option is specified, we open a file for writing out the errata.
+% \begin{macrocode}
+\ifrecord\newwrite\errata@file
+\immediate\openout\errata@file=\jobname-errata.tex
+\AtEndDocument{\closeout\errata@file}\fi
+% \end{macrocode}
+% \begin{macro}{\record@erratum}
+% The |\record@erratum| macro just writes its argument to the errata file together with
+% referencing information
+% \begin{macrocode}
+\def\ErratumRef{\@ifundefined{thechapter}{}{\arabic{chapter}.}%
+\@ifundefined{thesection}{}{\ifnum\value{section}>0{}\arabic{section}\fi}%
+\@ifundefined{thesubsection}{}{\ifnum\value{subsection}>0.\arabic{subsection}\fi}%
+\@ifundefined{thesubsubsection}{}{\ifnum\value{subsubsection}>0.\arabic{subsubsection}\fi}}
+\def\record@erratum#1{\ifrecord\protected@write\errata@file{}%
+{\string\erratumItem{\ErratumRef}{#1}}\fi}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\erratumItem}
+% For the errata themselves we use the following macro, which treats them as items in a
+% |description| environment\ednote{would be better to number errata and treat them like
+% glossary entries: 1. explanation ....... 3.4}
+% \begin{macrocode}
+\def\erratumItem#1#2{\item[#1] #2}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\printerrata}
+% \begin{macro}{\PrintErrata}
+% The |\printerrata| inputs the errata file for the path given in its argument. Its
+% variant |\PrintErrata| macro closes the errata file if necessary and calls
+% |\printerrata| for its own errata.
+% \begin{macrocode}
+\def\printerrata#1{\IfFileExists{#1-errata.tex}{\begin{errata}\input{#1-errata}\end{errata}}{}}
+\def\PrintErrata{\ifrecord\immediate\closeout\errata@file\fi\printerrata\jobname}
+% \end{macrocode}
+% \end{macro}
+% \end{macro}
+%
+% \begin{environment}{errata}
+% The |errata| environment wraps the errata items. Currently, this is just a
+% |description| environment.
+% \begin{macrocode}
+\newenvironment{errata}{\begin{description}}{\end{description}}
+% \end{macrocode}
+% \end{environment}
+%
+% \subsection{Short Errata}
+%\ednote{these could do with a bit of code refactoring}
+% \begin{macro}{\erratumAdd}
+% \begin{macrocode}
+\newcommand{\erratumAdd}[3][]% keyvals, explanation, new
+{\setkeys{erratum}{#1}\stepcounter{erratum}\record@erratum{#2}%
+\marginpar{Err(\arabic{erratum})}\immediate\typeout{Erratum!}%
+[#3]$_a^{\arabic{erratum}}$%
+\footnotetext[\value{erratum}]{{\scshape{Erratum!}}%
+\@ifundefined{erratum@type}{}{(\erratum@type)} #2 (added text)}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\erratumDelete}
+% \begin{macrocode}
+\newcommand{\erratumDelete}[3][]% keyvals, explanation, old
+{\setkeys{erratum}{#1}\stepcounter{erratum}\record@erratum{#2}%
+\marginpar{Err(\arabic{erratum})}\immediate\typeout{Erratum!}%
+[]$_d^{\arabic{erratum}}$%
+\footnotetext[\value{erratum}]{{\scshape{Erratum!}}%
+\@ifundefined{erratum@type}{}{(\erratum@type)} #2 (deleted ``#3'')}}
+% \end{macrocode}
+% \end{macro}
+%
+% \begin{macro}{\erratumReplace}
+% \begin{macrocode}
+\newcommand{\erratumReplace}[4][]% keyvals, explanation, old, new
+{\setkeys{erratum}{#1}\stepcounter{erratum}\record@erratum{#2}%
+\marginpar{Err(\arabic{erratum})}\immediate\typeout{Erratum!}%
+[#4]$_r^{\arabic{erratum}}$%
+\footnotetext[\value{erratum}]{{\scshape{Erratum!}}%
+\@ifundefined{erratum@type}{}{(\erratum@type)} #2 (original text was: ``#3'')}}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Extended Errata}
+%
+% \begin{environment}{erratum}
+% The |erratum| environment is for extended errata. It steps the counters, marks the
+% margins (if desired) and sets up local macros
+% \begin{macrocode}
+\newenvironment{erratum}[2][]% keys, explanation
+{\setkeys{erratum}{#1}\stepcounter{erratum}
+\edef\new@number{\theerratum}\message{Erratum \new@number!}
+\iffoots\footnotetext[\value{erratum}]{{\scshape{Erratum}%
+\@ifundefined{erratum@type}{}{(\erratum@type)}: #2}}\marginpar{BErr(\new@number)}\fi
+\record@erratum{#2}
+% \end{macrocode}
+% \begin{macro}{\eAdd}
+% This macro just passes through the argument, and delemits it, so that the extent
+% of the insertion can be seen.
+% \begin{macrocode}
+\def\eAdd##1{[##1]$_a$}%
+% \end{macrocode}
+% \end{macro}
+% \begin{macro}{\eDelete}
+% This macro just passes through the argument, and explains what was deleted in a
+% footnote.
+% \begin{macrocode}
+\def\eDelete##1{\erratum@mark[]$_d^{\@thefnmark}$\@footnotetext{deleted: ##1}}%
+% \end{macrocode}
+% \begin{macro}{\eReplace}
+% This macro just passes through the second argument, delemits it and marks the
+% replacement in a footnote.
+% \begin{macrocode}
+\def\eReplace##1##2{\erratum@mark[##2]$_r^{\@thefnmark}$\@footnotetext{was: ##1}}}%
+% \end{macrocode}
+% \end{macro}
+% The end part of the |erratum| environement is almost trivial, it only marks the margin
+% with the end mark.
+% \begin{macrocode}
+{\ifmargins\marginpar{EErr(\new@number)}\fi}
+% \end{macrocode}
+% \end{macro}
+% \end{environment}
+%
+% \begin{macro}{\erratum@mark}
+% This macro is used by the local macros of the |erratum| environment, it sets the
+% footnote label by redefining the {\LaTeX}-internal |\@thefnmark| macro appropriately.
+% \begin{macrocode}
+\def\erratum@mark{\stepcounter{erratum@note}{}
+\def\@thefnmark{\arabic{erratum}:\arabic{erratum@note}}}
+% \end{macrocode}
+% \end{macro}
+%
+% \subsection{Generating Statistics}
+%
+% \begin{macro}{\ednotemessage}
+% The |\ednotemessage| makes use of the counter |ednote| and generates a message.
+% \begin{macrocode}
+\def\ednotemessage{\ifnum\value{erratum}>0\typeout{}%
+\typeout{This document contains \arabic{erratum} Errata; see \jobname-errata.tex!}%
+\typeout{}\fi}
+%</package>
+% \end{macrocode}
+% \end{macro}
+% \PrintErrata
+% \Finale
+\endinput
+
+
+% LocalWords: dtx keyval tex thechapter thesection thesubsection BErr EErr
+% LocalWords: thesubsubsection