path: root/Master/texmf-dist/source/latex/errata/errata.dtx

% \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