summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/errata/errata.dtx
blob: df0dac7e871281e40b234102530e419c923c6ce3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
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