Debian Codegraph @

texmf-dist/source/latex/errata/errata.dtx

raw
1 % \iffalse meta-comment
2 % A Package for recording errata
3 % Copyright (c) 2006 Michael Kohlhase, all rights reserved
4 %
5 % This file is distributed under the terms of the LaTeX Project Public
6 % License from CTAN archives in directory macros/latex/base/lppl.txt.
7 % Either version 1.0 or, at your option, any later version.
8 %
9 % The development version of this file can be found at
10 % $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/errata/errata.dtx $
11 % \fi
12 %
13 % \iffalse
14 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
15 %<package>\ProvidesPackage{errata}[2006/11/121v0.3 Errata Management]
16 %
17 %<*driver>
18 \documentclass[twoside]{ltxdoc}
19 \DoNotIndex{\def,\long,\edef,\xdef,\gdef,\let,\global}
20 \DoNotIndex{\begin,\AtEndDocument,\newcommand,\newcounter,\stepcounter}
21 \DoNotIndex{\immediate,\openout,\closeout,\message,\typeout}
22 \DoNotIndex{\section,\scshape,\arabic}
23
24 \EnableCrossrefs
25 %\CodelineIndex
26 %\OnlyDescription
27 \RecordChanges
28 \usepackage{textcomp,url,float,a4wide}
29 \usepackage[show]{ed}
30 \usepackage[show]{errata}
31 \usepackage[fancyhdr,today,draft]{svninfo}
32 \pagestyle{fancyplain}\fancyhead[RE,LO]{\leftmark}\fancyhead[LE,RO]{\thepage}
33 \floatstyle{boxed}
34 \newfloat{exfig}{thp}{lop}
35 \floatname{exfig}{Example}
36 \begin{document}
37 \svnInfo $Id: errata.dtx 13983 2007-11-04 14:34:39Z kohlhase $
38 \svnKeyword $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/errata/errata.dtx $
39 \DocInput{errata.dtx}
40 \end{document}
41 %</driver>
42 % \fi
43 %
44 %\CheckSum{191}
45 %
46 % \changes{v0.1}{2006/07/18}{First Version with Documentation}
47 % \changes{v0.2}{2006/08/01}{More Documentation and Keywords Management}
48 % \changes{v0.3}{2006/11/21}{adding type Keyword}
49 %
50 % \GetFileInfo{errata.sty}
51 %
52 % \MakeShortVerb{\|}
53 % \title{Recording Errata in {\LaTeX} Documents\thanks{Version {\fileversion} (last revised
54 % {\filedate})}}
55 % \author{Michael Kohlhase\\
56 % Computer Science, Jacobs University, Bremen, Germany\\
57 % \url{http://kwarc.info/kohlhase}}
58 % \maketitle
59 %
60 % \begin{abstract}
61 % This package provides a simple infrastructure for recording errata in {\LaTeX}
62 % documents. This allows to maintain an updated version of the document (with all errors
63 % corrected) and automatically generate an errata document highlighting the difference
64 % to the published version.
65 % \end{abstract}
66 %
67 % \section{Introduction}\label{sec:intro}
68 %
69 % The life-cycle of a document does not end with its publication. After that, errors will
70 % be discovered, and have to be managed. The best way to do this is by marking errata in
71 % the text and generating the errata document from that.\ednote{describe some more}
72 %
73 % \section{The User Interface}\label{sec:user-interface}
74 %
75 % The |errata| package can be called with a variety of package options.
76 % \DescribeMacro{hide} The |show| and |hide| options govern the general visibility of the
77 % errata markup. If |hide| is specified (the default, if no option is given), then errata
78 % markup is totally invisible in the formatted document. \DescribeMacro{margins/foots}
79 % The |margins| and |foots| options give finer control. If the |margins| (|foots|) option
80 % is not given, then margin decorations (explanatory footnotes) are not generated.
81 % \DescribeMacro{hide} the |hide| option is equivalent to |margins| and |foots|.
82 %
83 % \DescribeMacro{record} If the |record| option is specified, then errata are written to a
84 % special file \meta{jobname}|-errata.tex| so that they can be included in an errata
85 % document (see Section~\ref{sec:generating}).
86 %
87 % There are two kinds of errata, short ones or extended ones. We will go into them in the
88 % next two subsections. All the errata macros take optional KeyVal arguments that specify
89 % the metadata for the errata. \DescribeMacro{date=}We can specify the date when the
90 % erratum was found, with the |date| key and\DescribeMacro{reported-by=} the person that
91 % reported the erratum with with the |reported-by| key. Consider for instance the metadata
92 % for the erratum in Example~\ref{fig:extended-erratum}; The date format follows the ISO
93 % 8601 norm: it is of the form \meta{YYYY}|-|\meta{MM}|-|\meta{DD}, where \meta{YYYY} is
94 % the 4-digit year, \meta{MM} the 2-digit month, and {\meta{DD}} the two-digit day of the
95 % month. The format of the |reported-by| field is free\footnote{Remember to encasulate the
96 % value in curly braces if the name contains a comma}. \DescribeMacro{id=}We can specify
97 % an identifier for the erratum using the |id| key, so that we can refer back to it
98 % later. \DescribeMacro{type=}Finally, we can use the |type| key to specify the type
99 % (e.g. ``clarification'') of an erratum.
100 %
101 % \subsection{Short Errata}
102 %
103 % Short errata can be recorded by the marking up the editing operations needed for the
104 % corrections. The following example in Example~\ref{fig:short-errata} shows all editing
105 % operations, which we will detail now:
106 %
107 % \begin{exfig}
108 % \begin{verbatim}
109 % Here we have \erratumAdd{forgotten word}{three} errata
110 % in one \erratumDelete{superfluous phrase}{darned} long
111 % \erratumReplace{translated}{Zeile}{line}
112 % \end{verbatim}
113 % \caption{Some short errata}\label{fig:short-errata}
114 % \end{exfig}
115 %
116 % \DescribeMacro{\erratumAdd} |\erratumAdd| marks up a correction by adding some text. The
117 % first argument holds the explanation of the intended correctionand the second one the
118 % new text.
119 %
120 % \DescribeMacro{\erratumDelete} |\erratumDelete| does the same for a correction by
121 % deleting some text; here the second argument holds the deleted text. While the
122 % |\erratumAdd| will copy the contents of the second argument to the result document,
123 % |\erratumDelete| does not.
124 %
125 % \DescribeMacro{\erratumReplace}
126 % |\erratumReplace{[|\meta{keys}|]|\meta{desc}|}{|\meta{old}|}{|\meta{new}|}| replaces
127 % {\meta{old}} with {\meta{new}} in the result document.
128 %
129 % All of these macros mark the location of the errata in the margin and document the
130 % changes in footnote-like structures. For instance, the text fragment above would be
131 % rendered as
132 % \begin{quote}
133 % Here we have \erratumAdd{forgotten word}{three} errata
134 % in one \erratumDelete{superfluous phrase}{darned} long
135 % \erratumReplace{translated}{Zeile}{line}
136 % \end{quote}
137 %
138 % \subsection{Extended Errata}
139 %
140 % \DescribeEnv{erratum} Extended errata group multiple editing operations into a coherent
141 % group via the |erratum| environment. The first argument of this environment is an
142 % explanation as for the short errata above. The |erratum| environment provides local
143 % versions of the editing markup macros, which behave like those, but lack the first
144 % (explanation) argument, which is already given in the environment that contains them.
145 %
146 % \begin{exfig}
147 % \begin{verbatim}
148 % \begin{erratum}[date=2006-07-19,reported-by=Michael Kohlhase]{old should be new}
149 % this is a test of a long erratum
150 % \begin{enumerate}
151 % \item We can replace \eReplace{oldtext}{newtext}
152 % \item and \eAdd{new text}
153 % \item and finally delete old text\eDelete{alltogether}
154 % \end{enumerate}
155 % \end{erratum}
156 % \end{verbatim}
157 % \caption{An extended erratum with local correction markers}\label{fig:extended-erratum}
158 % \end{exfig}
159 %
160 % This text fragment would be rendered as
161 % \begin{quote}
162 % \begin{erratum}[reported-by=Michael Kohlhase,date=2006-11-21]{old should be new}
163 % this is a test of a long erratum
164 % \begin{enumerate}
165 % \item We can replace \eReplace{oldtext}{newtext}
166 % \item and \eAdd{new text}
167 % \item and finally delete old text\eDelete{alltogether}
168 % \end{enumerate}
169 % \end{erratum}
170 % \end{quote}
171 %
172 % The |erratum| environment should also be used in situations where the error occurs in an
173 % environment, where normal {\TeX/\LaTeX} processing is suspended, e.g. a |verbatim|
174 % environment. In this case, we can use it to attach correction information via the
175 % environment, but do not use the local change documentations.\ednote{what do we do in
176 % floats? document}
177 %
178 % \subsection{Generating Statistics and Errata Documents}\label{sec:generating}
179 %
180 % \DescribeMacro{\erratamessage} Putting the macro |\erratamessage| just before the
181 % |\end||{document}| will generate a message with cardinality information for the errata
182 % into the log file.
183 %
184 % \DescribeMacro{\erratumItem} Errata can be marked up using the |\erratumItem| macro in
185 % the the\DescribeEnv{errata} |errata| environment. The |\erratumItem| takes two
186 % arguments, the first is a reference to where the erratum occurred, and the second one
187 % the explanation.
188 %
189 % \DescribeMacro{\printerrata} The |\printerrata| command allows to print the errata for
190 % another document. This command is useful when generating errata documents for published
191 % works. Say we have a book with a driver file |thebook.tex|, into which we have
192 % incorporated errata markup using the infrastructure detailed above. Then we have a new
193 % document called e.g. |theerrata.tex| which has the form given in
194 % Figure~\ref{fig:sample-errata-document}. Note that we have used |\printerrata{thebook}|
195 % to include the errata notices generated from |thebook.tex|.
196 % \begin{exfig}
197 % \begin{verbatim}
198 % \documentclass{article}
199 % \usepackage[hide]{errata}
200 % \title{Errata for The Book}
201 % \begin{document}
202 % \maketitle
203 % \begin{abstract} This document tracks the errata in The Book. \end{abstract}
204 % \section{Introduction}
205 % ... The errata of The Book are tracked in this document, whose newest version can be
206 % found at \url{.../berrata.pdf}. A version of The Book that contains all errata
207 % corrections (and markup of what changed) can be found at \url{.../book.pdf}.
208 %
209 % In the following we will tabulate the errata in document order. Their location will be
210 % referenced by the section they appear in rather than the page number, since we do not
211 % expect the former to change in the errata correction process.
212 %
213 % \section{The Errata in The Book}
214 % \printerrata{thebook}
215 % \end{document}
216 % \end{verbatim}
217 % \caption{A Sample Errata Document}\label{fig:sample-errata-document}
218 % \end{exfig}
219 %
220 % In the errata document in Figure~\ref{fig:sample-errata-document} we postulate that we
221 % keep an updated version of The Book online\footnote{And indeed it is good practice to do
222 % so if the copyright agreement with the publisher allows this.} using the
223 % infrastructure provide by the |errata| package. \DescribeMacro{\printerrata} In the
224 % updated version of |thebook.tex|, it can be useful to tabulate the errata as well,
225 % e.g. in a section in the appendix. This can be done by the |\PrintErrata| command. Note
226 % that this command needs to close the errata file |thebook-errata.tex| therefore we need
227 % a |\newpage| to clear the queue of waiting |\writes| before |thebook-errata.tex| can be
228 % loaded (otherwise we may be missing the errata from the last page).
229 %
230 % \StopEventually{\newpage\PrintChanges\newpage\section{The Errata of this Document}\printerrata{errata}\ednotemessage}
231 %
232 % \newpage
233 % \section{The Implementation}
234 %
235 % The implementation is rather standard. We first set up the options for the package. The
236 % main switches are |\ifmargins| and |\iffoots|, which govern the visibility of the
237 % annotations in the margins and the footnotes.
238 % \begin{macrocode}
239 %<*package>
240 \newif\ifmargins\marginsfalse
241 \newif\iffoots\footsfalse
242 \newif\ifrecord\recordfalse
243 % \end{macrocode}
244 % the next step is to declare the package options, they just set the switches accordingly.
245 % \begin{macrocode}
246 \DeclareOption{show}{\marginstrue\footstrue}
247 \DeclareOption{hide}{}
248 \DeclareOption{margins}{\marginstrue}
249 \DeclareOption{foots}{\footstrue}
250 \DeclareOption{record}{\recordtrue}
251 \ProcessOptions
252 % \end{macrocode}
253 % This ends the package setup code, so we can come to the implementation of the
254 % functionality of the package.
255 %
256 % We first make sure that the |Keyval| package is loaded.
257 % \begin{macrocode}
258 %<*package>
259 \RequirePackage{keyval}[1997/11/10]
260 % \end{macrocode}
261 % and then define the actions that are undertaken when the keys are encountered. Here
262 % this is very simple, we just define an internal macro with the value, so that we can use
263 % it later.
264 % \begin{macrocode}
265 \define@key{erratum}{id}{\def\erratum@id{#1}}
266 \define@key{erratum}{type}{\def\erratum@type{#1}}
267 \define@key{erratum}{date}{\def\erratum@date{#1}}
268 \define@key{erratum}{reported-by}{\def\erratum@reported-by{#1}}
269 % \end{macrocode}
270 %
271 % \subsection{Recording Errata}
272 %
273 % The next step is to set up two counters for the errata.
274 % \begin{macrocode}
275 \newcounter{erratum}
276 \newcounter{erratum@note}[erratum]
277 % \end{macrocode}
278 %
279 % If the |record| option is specified, we open a file for writing out the errata.
280 % \begin{macrocode}
281 \ifrecord\newwrite\errata@file
282 \immediate\openout\errata@file=\jobname-errata.tex
283 \AtEndDocument{\closeout\errata@file}\fi
284 % \end{macrocode}
285 % \begin{macro}{\record@erratum}
286 % The |\record@erratum| macro just writes its argument to the errata file together with
287 % referencing information
288 % \begin{macrocode}
289 \def\ErratumRef{\@ifundefined{thechapter}{}{\arabic{chapter}.}%
290 \@ifundefined{thesection}{}{\ifnum\value{section}>0{}\arabic{section}\fi}%
291 \@ifundefined{thesubsection}{}{\ifnum\value{subsection}>0.\arabic{subsection}\fi}%
292 \@ifundefined{thesubsubsection}{}{\ifnum\value{subsubsection}>0.\arabic{subsubsection}\fi}}
293 \def\record@erratum#1{\ifrecord\protected@write\errata@file{}%
294 {\string\erratumItem{\ErratumRef}{#1}}\fi}
295 % \end{macrocode}
296 % \end{macro}
297 %
298 % \begin{macro}{\erratumItem}
299 % For the errata themselves we use the following macro, which treats them as items in a
300 % |description| environment\ednote{would be better to number errata and treat them like
301 % glossary entries: 1. explanation ....... 3.4}
302 % \begin{macrocode}
303 \def\erratumItem#1#2{\item[#1] #2}
304 % \end{macrocode}
305 % \end{macro}
306 %
307 % \begin{macro}{\printerrata}
308 % \begin{macro}{\PrintErrata}
309 % The |\printerrata| inputs the errata file for the path given in its argument. Its
310 % variant |\PrintErrata| macro closes the errata file if necessary and calls
311 % |\printerrata| for its own errata.
312 % \begin{macrocode}
313 \def\printerrata#1{\IfFileExists{#1-errata.tex}{\begin{errata}\input{#1-errata}\end{errata}}{}}
314 \def\PrintErrata{\ifrecord\immediate\closeout\errata@file\fi\printerrata\jobname}
315 % \end{macrocode}
316 % \end{macro}
317 % \end{macro}
318 %
319 % \begin{environment}{errata}
320 % The |errata| environment wraps the errata items. Currently, this is just a
321 % |description| environment.
322 % \begin{macrocode}
323 \newenvironment{errata}{\begin{description}}{\end{description}}
324 % \end{macrocode}
325 % \end{environment}
326 %
327 % \subsection{Short Errata}
328 %\ednote{these could do with a bit of code refactoring}
329 % \begin{macro}{\erratumAdd}
330 % \begin{macrocode}
331 \newcommand{\erratumAdd}[3][]% keyvals, explanation, new
332 {\setkeys{erratum}{#1}\stepcounter{erratum}\record@erratum{#2}%
333 \marginpar{Err(\arabic{erratum})}\immediate\typeout{Erratum!}%
334 [#3]$_a^{\arabic{erratum}}$%
335 \footnotetext[\value{erratum}]{{\scshape{Erratum!}}%
336 \@ifundefined{erratum@type}{}{(\erratum@type)} #2 (added text)}}
337 % \end{macrocode}
338 % \end{macro}
339 %
340 % \begin{macro}{\erratumDelete}
341 % \begin{macrocode}
342 \newcommand{\erratumDelete}[3][]% keyvals, explanation, old
343 {\setkeys{erratum}{#1}\stepcounter{erratum}\record@erratum{#2}%
344 \marginpar{Err(\arabic{erratum})}\immediate\typeout{Erratum!}%
345 []$_d^{\arabic{erratum}}$%
346 \footnotetext[\value{erratum}]{{\scshape{Erratum!}}%
347 \@ifundefined{erratum@type}{}{(\erratum@type)} #2 (deleted ``#3'')}}
348 % \end{macrocode}
349 % \end{macro}
350 %
351 % \begin{macro}{\erratumReplace}
352 % \begin{macrocode}
353 \newcommand{\erratumReplace}[4][]% keyvals, explanation, old, new
354 {\setkeys{erratum}{#1}\stepcounter{erratum}\record@erratum{#2}%
355 \marginpar{Err(\arabic{erratum})}\immediate\typeout{Erratum!}%
356 [#4]$_r^{\arabic{erratum}}$%
357 \footnotetext[\value{erratum}]{{\scshape{Erratum!}}%
358 \@ifundefined{erratum@type}{}{(\erratum@type)} #2 (original text was: ``#3'')}}
359 % \end{macrocode}
360 % \end{macro}
361 %
362 % \subsection{Extended Errata}
363 %
364 % \begin{environment}{erratum}
365 % The |erratum| environment is for extended errata. It steps the counters, marks the
366 % margins (if desired) and sets up local macros
367 % \begin{macrocode}
368 \newenvironment{erratum}[2][]% keys, explanation
369 {\setkeys{erratum}{#1}\stepcounter{erratum}
370 \edef\new@number{\theerratum}\message{Erratum \new@number!}
371 \iffoots\footnotetext[\value{erratum}]{{\scshape{Erratum}%
372 \@ifundefined{erratum@type}{}{(\erratum@type)}: #2}}\marginpar{BErr(\new@number)}\fi
373 \record@erratum{#2}
374 % \end{macrocode}
375 % \begin{macro}{\eAdd}
376 % This macro just passes through the argument, and delemits it, so that the extent
377 % of the insertion can be seen.
378 % \begin{macrocode}
379 \def\eAdd##1{[##1]$_a$}%
380 % \end{macrocode}
381 % \end{macro}
382 % \begin{macro}{\eDelete}
383 % This macro just passes through the argument, and explains what was deleted in a
384 % footnote.
385 % \begin{macrocode}
386 \def\eDelete##1{\erratum@mark[]$_d^{\@thefnmark}$\@footnotetext{deleted: ##1}}%
387 % \end{macrocode}
388 % \begin{macro}{\eReplace}
389 % This macro just passes through the second argument, delemits it and marks the
390 % replacement in a footnote.
391 % \begin{macrocode}
392 \def\eReplace##1##2{\erratum@mark[##2]$_r^{\@thefnmark}$\@footnotetext{was: ##1}}}%
393 % \end{macrocode}
394 % \end{macro}
395 % The end part of the |erratum| environement is almost trivial, it only marks the margin
396 % with the end mark.
397 % \begin{macrocode}
398 {\ifmargins\marginpar{EErr(\new@number)}\fi}
399 % \end{macrocode}
400 % \end{macro}
401 % \end{environment}
402 %
403 % \begin{macro}{\erratum@mark}
404 % This macro is used by the local macros of the |erratum| environment, it sets the
405 % footnote label by redefining the {\LaTeX}-internal |\@thefnmark| macro appropriately.
406 % \begin{macrocode}
407 \def\erratum@mark{\stepcounter{erratum@note}{}
408 \def\@thefnmark{\arabic{erratum}:\arabic{erratum@note}}}
409 % \end{macrocode}
410 % \end{macro}
411 %
412 % \subsection{Generating Statistics}
413 %
414 % \begin{macro}{\ednotemessage}
415 % The |\ednotemessage| makes use of the counter |ednote| and generates a message.
416 % \begin{macrocode}
417 \def\ednotemessage{\ifnum\value{erratum}>0\typeout{}%
418 \typeout{This document contains \arabic{erratum} Errata; see \jobname-errata.tex!}%
419 \typeout{}\fi}
420 %</package>
421 % \end{macrocode}
422 % \end{macro}
423 % \PrintErrata
424 % \Finale
425 \endinput
426
427
428 % LocalWords: dtx keyval tex thechapter thesection thesubsection BErr EErr
429 % LocalWords: thesubsubsection