Debian Codegraph @

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

raw
1 % \iffalse meta-comment
2 % Editorial Notes for LaTeX
3 % Copyright (c) 2009 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/forCTAN/ed/ed.dtx $
11 % \fi
12 %
13 % \iffalse
14 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
15 %<package>\ProvidesPackage{ed}[2012/01/29 v1.8 Editorial Notes]
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 \EnableCrossrefs
24 %\CodelineIndex
25 %\OnlyDescription
26 \RecordChanges
27 \usepackage{textcomp,url,a4wide}
28 \usepackage[show]{ed}
29 \usepackage[eso-foot,today,draft]{svninfo}
30 \usepackage{hyperref}
31 %\makeindex
32 \begin{document}
33 \svnInfo $Id: ed.dtx 23125 2012-01-29 12:15:08Z kohlhase $
34 \svnKeyword $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/forCTAN/ed/ed.dtx $
35 \DocInput{ed.dtx}
36 \end{document}
37 %</driver>
38 % \fi
39 %
40 %\CheckSum{409}
41 %
42 % \changes{v1.0}{2005/06/23}{First Version with Documentation}
43 % \changes{v1.1}{2005/10/03}{Added capitalized variants}
44 % \changes{v1.2}{2007/05/10}{adding todo environment}
45 % \changes{v1.3}{2007/10/03}{rationalizing todo environment}
46 % \changes{v1.4}{2007/11/12}{localization}
47 % \changes{v1.5}{2008/06/08}{todolist now uses enumerate}
48 % \changes{v1.6}{2009/06/18}{nomargins option}
49 % \changes{v1.6}{2009/06/24}{deprecated issue for edissue to get around name clashes.}
50 % \changes{v1.6}{2009/10/29}{made ednotemessage automatic}
51 % \changes{v1.7}{2011/01/16}{adding final/draft options}
52 % \changes{v1.8}{2012/01/29}{adding \texttt{edstub} environment}
53 %
54 % \GetFileInfo{ed.sty}
55 %
56 % \MakeShortVerb{\|}
57 % \title{Editorial Notes for {\LaTeX}\thanks{Version {\fileversion} (last revised
58 % {\filedate})}}
59 % \author{Michael Kohlhase\\
60 % Computer Science, Jacobs University\\
61 % \url{http://kwarc.info/kohlhase}}
62 % \maketitle
63 %
64 % \begin{abstract}
65 % This package defines a couple of editorial notes that simplify collaboration on a
66 % {\LaTeX} text. These allow authors to annotate status information in the source. In
67 % draft mode, the annotations are shown for communication, and in publication mode these
68 % are suppressed.
69 % \end{abstract}
70 %
71 % \tableofcontents\newpage
72 %
73 % \section{Introduction}\label{sec:intro}
74 %
75 % When collaborating on a document with multiple authors, communication about the status
76 % of a given passage and intentions about what to do with it, indications about issues
77 % still need to be resolved, and directives to other authors, e.g. calling for help, or
78 % passing the baton, etc. make up much of the overhead involved in collaboration. In
79 % particular, many of the necessary communicative acts are centered around specific points
80 % or passages in the document at hand. Therefore it is natural to embed the communicative
81 % acts in the document source itself. The simplest version of this is to special markers
82 % like ``(*** remember to rework this before publication ***)'', where the markers
83 % ``(***'' and ``***)'' serve as a visual aid and target for search and navigation tools
84 % in the editor. Of course this is dangerous, and we have all seen published texts with
85 % such markers still present.
86 %
87 % The {\LaTeX} package described in here systematizes the idea and provides more conspicuous
88 % visual markers (as footnotes and margin notes) and a way of making all all of these
89 % private markers and comments invisible for publication or outside communication.
90 %
91 % \section{The User Interface}\label{sec:user-interface}
92 %
93 % \subsection{Package Options}
94 %
95 % As usual in {\LaTeX}, the package is loaded by |\usepackage[|\meta{options}|]{ed}|,
96 % where |[|\meta{options}|]| is optional and gives a comma separated list of options. The
97 % |ed| package takes the options \DescribeMacro{show}|show| and
98 % \DescribeMacro{hide}|hide|, where |hide| is the default case, so that |\usepackage{ed}|,
99 % is equivalent to |\usepackage[hide]{ed}|. If the |show| option is given, then the
100 % editorial notes are presented as special annotations to the document, otherwise they are
101 % completely invisible --- if you take care about spaces in the source code. For instance
102 % |text|\textvisiblespace|\ednote{|\ldots|}|\textvisiblespace|text| will fool {\TeX}'s
103 % whitespace-collapsing algorithm and bring it to output two spaces in the document
104 % instead of just one as expected |text\ednote{|\ldots|}|\textvisiblespace|text| should be
105 % used instead! This |hide| option useful for preparing ``clean'' version for outside
106 % consumption without losing the management metadata. In some situations the |\marginpar|
107 % decorations generated by editorial notes are disallowed, for these situations the |ed|
108 % package has the \DescribeMacro{nomargins}|nomargins| option that disables them.
109 %
110 % As many classes support the \DescribeMacro{draft}|draft| and
111 % \DescribeMacro{final}|final| options and pass them on to all loaded packages that will
112 % take them, the |ed| package supports them as aliases for |show| and |hide|.
113 %
114 % \subsection{Annotation Macros}
115 %
116 % \DescribeMacro{\ednote} The main user macro of this package is |\ednote|. It is used say
117 % what you have done or what should still be done at a given point in the document.
118 % |ed.sty| formats it like a footnote, but with a margin note that marks the place in the
119 % text, where the note is located. Otherwise, in the presence of multiple |\ednote|s in a
120 % page it may be difficult to find the referenced locations\ednote{this is an example of
121 % an ednote}. Editorial notes are numbered and marked in the margin for easy
122 % recognition. |\ednote| also takes an optional argument that is an identifier. This
123 % allows to cross-reference ednotes in each other.
124 %
125 % \DescribeMacro{\edissue} The |\edissue| macro\edissue{The control sequence\textbf{issue}
126 % conflicts with many other macro packages, maybe we should rename it to
127 % \textbf{edissue}.} is a variant of |\ednote| for issues that still have to be
128 % discussed among the authors. For issues the labeling and cross-referencing in the
129 % optional argument is especially useful. Note that the \DescribeMacro{\issue}|\issue|
130 % macro which earlier versions of the |ed| package provided is deprecated in favor of
131 % |\edissue|. The old |\issue| macro is only provided for backwards compatibility if it is
132 % not defined by other packages. For this to work, the |ed| package should be loaded late
133 % in the preamble.
134 %
135 % \DescribeMacro{\tweak} The |\tweak| macro\tweak{this is an example of an tweak} is a
136 % variant of |\ednote| for marking places where we have tweaked something (apart from the
137 % standard way we usually use).
138 %
139 % \DescribeEnv{todo} The |todo| environment is an environment that can be used to mark up
140 % writing tasks. These are inserted into the text in a different font, so that they are
141 % conspicuous as a foreign part, and take an argument for a comment.
142 %
143 % \DescribeEnv{todolist} The |todolist| is a variant of the |todo| environment which is a
144 % is an itemized list.
145 %
146 % The following is an example, generated form the the input
147 % |\begin{todolist}{an example todolist}| \ldots |\item| \ldots |\end{todolist}|.
148 % \begin{todolist}{an example todolist}
149 % \item lots of good examples
150 % \item a general chapter about best practices
151 % \end{todolist}
152 %
153 % \DescribeEnv{newpart}\DescribeEnv{oldpart} the |newpart| environment can be used to mark
154 % up changed text blocks. |\beg||in{newpart}| takes an argument that is interpreted as a
155 % comment and is treated like an |\ednote| comment. The |oldpart| environment is similar
156 % to |newpart| but is used for old parts of text copied from another document that still
157 % need to be changed in a document. They displayed in gray, so that they can be identified
158 % better.
159 %
160 % The annotation macros have capitalized variants (|\Ednote|, |\edIssue|, |\Tweak|,
161 % |Todo|, |Newpart|, |Oldpart|) that do not make location marks in the margin. This is
162 % convenient in situations (e.g. inside boxes or minipages) that allow footnotes, but no
163 % margin notes.
164 %
165 % \subsection{Stubs and External Files}
166 %
167 % In some collaborative editing situations not all participants are willing to write
168 % {\LaTeX}, but insist on developing their proposal parts in some other word procesing
169 % software. The |ed| class offers the \DescribeEnv{edstub}|edstub| environment:
170 %
171 % |\begin{edstub}[|\meta{exp}|]{|\meta{file}|}| marks the content of the environment as
172 % provisional (e.g. by turning it blue) and lists an external file (\meta{file}) as the
173 % original. Here, \meta{exp} is an optional reformulation of the default desription
174 % ``The following blue text''. The following stub
175 %
176 % \begin{edstub}{stub.doc}
177 % here are some provisional ideas
178 % \end{edstub}
179 %
180 % is generated by
181 %
182 % \begin{verbatim}
183 % \begin{edstub}{stub.doc}
184 % here are some provisional ideas
185 % \end{edstub}
186 % \end{verbatim}
187 %
188 % For hyperlinking \meta{file} the \DescribeMacro{edstubURI}|edstubURI| can be used to set
189 % a URI: After setting |\edstubURI{|\meta{URI}|}| with a non-empty URI, \meta{file} is
190 % hyperlinked to \meta{URI}|/|\meta{file}. If \meta{file} is in the same directory as the
191 % current document, use |\edstubURI{.}|.
192 %
193 % \subsection{Generating Statistics and Explanations}
194 %
195 % \DescribeMacro{\ednotemessage} Up to version 1.6, the |ed| package had an explicit macro
196 % |\ednotemessage| that put just before the |\end||{document}| will generates a message
197 % with cardinality information for the ednotes into the log file. This macro is now
198 % deprecated, since the message is now automatically generated.
199 %
200 % \DescribeMacro{\edexplanation} The |\edexplanation| macro generates an explanation of the
201 % best practices into the document. So that if you introduce collaboration partners to the
202 % |ed| package, you can give them an explanation ``in-place''.
203 %
204 % \subsection{Configuration}
205 %
206 % \DescribeMacro{\ednoteshape} The font shape of editorial annotations is governed by the
207 % parameter |\ednoteshape| the default is sans serif, specialize it to say italic by
208 % |\def\ednoteshape{\it}|. The labels in the margins can be tweaked (e.g. for
209 % localization:) by setting the (internal) macros |\ednote@label|, |\tweak@label|,
210 % |\edissue@label|, |\b@todo@label|, |\e@todo@label|.
211 %
212 % \subsection{Best Practices}
213 %
214 % In a situation with multiple authors, we it is advisable to use the |\ednote| in the
215 % following form: |\ednote{author: some explanatory text}| to specify the originator of the
216 % note.
217 %
218 % \StopEventually{\newpage\PrintChanges}\newpage
219 %
220 % \section{The Implementation}
221 %
222 % The implementation is rather standard. We first set up the options for the package.
223 %
224 % \subsection{Package Options}
225 %
226 % The main switch is |\showednotes|, which governs the visibility of the annotations.
227 % \begin{macrocode}
228 %<*package>
229 \newif\ifshowednotes\showednotesfalse
230 \newif\ifmargins\marginstrue
231 % \end{macrocode}
232 % the next step is to declare the package options, they just set |\showednotes| switch
233 % accordingly.
234 % \begin{macrocode}
235 \DeclareOption{show}{\showednotestrue\message{ed.sty: showing ednotes}}
236 \DeclareOption{hide}{\showednotesfalse\message{ed.sty: hiding ednotes}}
237 \DeclareOption{draft}{\showednotestrue\message{ed.sty: showing ednotes}}
238 \DeclareOption{final}{\showednotesfalse\message{ed.sty: hiding ednotes}}
239 \DeclareOption{nomargins}{\marginsfalse}
240 \ProcessOptions
241 % \end{macrocode}
242 % The next step is to load the |verbatim| or |paralist| packages, so that we can either
243 % comment out the or use the |compactenum| environment for todo lists.
244 % \begin{macrocode}
245 \ifshowednotes
246 \RequirePackage{paralist}
247 \RequirePackage{xcolor}
248 \else
249 \RequirePackage{verbatim}
250 \fi
251 % \end{macrocode}
252 % This ends the package setup code, so we can come to the implementation of the
253 % functionality of the package.
254 %
255 % \subsection{Annotation Macros}
256 %
257 % \begin{macro}{\ednoteshape}
258 % We start with the configuration part, predefining
259 % |\epdnoteshape| to be sans serif.
260 % \begin{macrocode}
261 \newcommand\ednoteshape{\sffamily}
262 % \end{macrocode}
263 % \end{macro}
264 %
265 % The next step is to set up a counter for the editorial annotations
266 % \begin{macrocode}
267 \newcounter{ednote}
268 % \end{macrocode}
269 %
270 % \begin{macro}{\ed@foot}
271 % The internal macro |\ed@foot| is used to actually make the annotations, it is used
272 % by the interface macros to give the annotations. It takes three arguments: A comment
273 % text that goes into the footnote, a type descriptor, and an identifiers.
274 % \begin{macrocode}
275 \newcommand\ed@foot[3]% text, type, label
276 {\def\@test{#3}\footnotetext[\arabic{ednote}]%
277 {{\scshape{#2}\if\@test\@empty\else\label{ed:#3}[{#3}]\fi:} \ednoteshape #1}}
278 % \end{macrocode}
279 % \end{macro}
280 %
281 % \begin{macro}{\ed@footnote}
282 % extends the |\ed@foot| to a complete footnote
283 % \begin{macrocode}
284 \newcommand\ed@footnote[3]{\footnotemark[\arabic{ednote}]\ed@foot{#1}{#2}{#3}}
285 % \end{macrocode}
286 % \end{macro}
287 %
288 % \begin{macro}{\ed@margin}
289 % The internal macro |\ed@margin| makes a |\marginpar| annotation if allowed.
290 % \begin{macrocode}
291 \newcommand\ed@margin[1]{\ifmargins\marginpar{#1}\fi}
292 % \end{macrocode}
293 % \end{macro}
294 %
295 % \begin{macro}{\Ed@note}
296 % Another internal macro |\Ed@note| adds label management to |\ed@foot|
297 % \begin{macrocode}
298 \newcommand\Ed@note[3]% text, type, label
299 {\addtocounter{ednote}{1}\message{#2!}%
300 \ifshowednotes\ed@footnote{#1}{#2}{#3}\fi}
301 % \end{macrocode}
302 % \end{macro}
303 %
304 % \begin{macro}{\ed@note}
305 % |\ed@note| is a variant of |\Ed@note| that also makes an identifying mark in the
306 % margin.
307 % \begin{macrocode}
308 \newcommand\ed@note[4]% text, type, label, margin
309 {\Ed@note{#1}{#2}{#3}\ifshowednotes\ed@margin{#4:\arabic{ednote}}\fi}
310 % \end{macrocode}
311 % \end{macro}
312 %
313 % \begin{macro}{\ednotelabel}
314 % \begin{macrocode}
315 \newcommand\ednote@label{EdNote}
316 \newcommand\ednote@margin{EdN}
317 \newcommand\ednotelabel[1]{\def\ednote@label{#1}}
318 \newcommand\ednotemargin[1]{\def\ednote@margin{#1}}
319 % \end{macrocode}
320 % \end{macro}
321 %
322 % \begin{macro}{\ednote}
323 % with the |\Ed@note| and |\ed@note| macros it is very simple to get the desired
324 % functionality of |\Ednote| and |\ednote|:
325 % \begin{macrocode}
326 \newcommand{\Ednote}[2][]{\Ed@note{#2}\ednote@label{#1}}
327 \newcommand{\ednote}[2][]{\ed@note{#2}\ednote@label{#1}\ednote@margin}
328 % \end{macrocode}
329 % \end{macro}
330 %
331 % \begin{macro}{\tweaklabel}
332 % \begin{macrocode}
333 \newcommand\tweaklabel[1]{\def\tweak@label{#1}}
334 \newcommand\tweak@label{Tweak}
335 \newcommand\tweakmargin[1]{\def\tweak@margin{#1}}
336 \newcommand\tweak@margin{Tw}
337 % \end{macrocode}
338 % \end{macro}
339 %
340 % \begin{macro}{\tweak}
341 % and of course for |\tweak|:
342 % \begin{macrocode}
343 \newcommand{\tweak}[2][]{\ed@note{#2}\tweak@label{#1}\tweak@margin}
344 \newcommand{\Tweak}[2][]{\Ed@note{#2}\tweak@label{#1}}
345 % \end{macrocode}
346 % \end{macro}
347 %
348 % \begin{macro}{\edissuelabel}
349 % \begin{macrocode}
350 \newcommand\edissue@label{Issue}
351 \newcommand\edissuelabel[1]{\def\edissue@label{#1}}
352 \newcommand\edissue@margin{Is}
353 \newcommand\edissuemargin[1]{\def\edissue@margin{#1}}
354 % \end{macrocode}
355 % \end{macro}
356 %
357 % \begin{macro}{\edissue}
358 % \begin{macrocode}
359 \providecommand{\issue}[2][]{\ed@note{#2}\edissue@label{#1}\edissue@margin}
360 \providecommand{\Issue}[2][]{\Ed@note{#2}\edissue@label{#1}}
361 \newcommand{\edissue}[2][]{\ed@note{#2}\edissue@label{#1}\edissue@margin}
362 \newcommand{\edIssue}[2][]{\Ed@note{#2}\edissue@label{#1}}
363 % \end{macrocode}
364 % \end{macro}
365 %
366 % \begin{environment}{Ed@part}
367 % For the text status environments |Newpart| and |Oldpart| we also set up an internal
368 % macro that does the work.
369 % \begin{macrocode}
370 \newenvironment{Ed@part}[3]% text, mess, start
371 {\addtocounter{ednote}{1}\edef\new@number{\theednote}\message{#2!\new@number}
372 \ifshowednotes\ed@foot{#1}{#2}{}\fi}
373 {}
374 % \end{macrocode}
375 % \end{environment}
376 %
377 % \begin{environment}{ed@part}
378 % and one that makes the marginpars.
379 % \begin{macrocode}
380 \def\ed@part#1#2#3#4% text, mess, start, margin
381 {\Ed@part{#1}{#2}{#3}\ifshowednotes\ed@margin{#4:\new@number}\fi}
382 \def\ended@part#1{\endEd@part\ifshowednotes\ed@margin{#1:\new@number}\fi}
383 % \end{macrocode}
384 % \end{environment}
385 %
386 % \begin{environment}{newpartlabels}
387 % \begin{macrocode}
388 \newcommand\b@newpart@label{BegNP}\newcommand\e@newpart@label{EndNP}
389 \newcommand\b@newpart@margin{BNP}\newcommand\e@newpart@margin{ENP}
390 \newcommand\newpartmargins[2]{\def\b@newpart@margin{#1}\def\e@newpart@margin{#2}}
391 % \end{macrocode}
392 % \end{environment}
393 %
394 % \begin{environment}{newpart}
395 % We instantiate it for the |newpart| environment
396 % \begin{macrocode}
397 \newenvironment{Newpart}[1]{\Ed@part{#1}{New Part}\b@newpart@label}{\endEd@part}
398 \newenvironment{newpart}[1]{\ed@part{#1}{New Part}\b@newpart@label\b@newpart@margin}{\ended@part\e@newpart@margin}
399 % \end{macrocode}
400 % \end{environment}
401 %
402 % \begin{environment}{oldpartlabels}
403 % \begin{macrocode}
404 \newcommand\oldpartlabels[2]{\def\b@oldpart@label{#1}\def\e@oldpart@label{#2}}
405 \newcommand\oldpartmargins[2]{\def\b@oldpart@margin{#1}\def\e@oldpart@margin{#2}}
406 \newcommand\b@oldpart@label{BegOP}\newcommand\e@oldpart@label{EndOP}
407 \newcommand\b@oldpart@margin{BOP}\newcommand\e@oldpart@margin{EOP}
408 % \end{macrocode}
409 % \end{environment}
410 %
411 % \begin{environment}{oldpart}
412 % and of course for the |oldpart| environment
413 % \begin{macrocode}
414 \newenvironment{Oldpart}[1]%
415 {\Ed@part{#1}{Old Part}\b@oldpart@label\ifshowednotes\color{gray}\fi}
416 {\endEd@part}
417 \newenvironment{oldpart}[1]%
418 {\ed@part{#1}{Old Part}\b@oldpart@label\b@oldpart@margin\ifshowednotes\color{gray}\fi}
419 {\ended@part\e@oldpart@margin}
420 % \end{macrocode}
421 % \end{environment}
422 %
423 % \begin{environment}{todolabel}
424 % \begin{macrocode}
425 \newcommand\todolabels[2]{\def\b@todo@label{#1}\def\e@todo@label{#2}}
426 \newcommand\todomargins[2]{\def\b@todo@margin{#1}\def\e@todo@margin{#2}}
427 \newcommand\b@todo@label{ToDo}\newcommand\e@todo@label{Done}
428 \newcommand\b@todo@margin{ToDo}\newcommand\e@todo@margin{Done}
429 % \end{macrocode}
430 % \end{environment}
431 %
432 % \begin{environment}{todo}
433 % How we define the |todo| environment depends on the |\showednotes| switch (or the
434 % package option). If we hide annotations, |todo| is set to |comment| from the
435 % |comment| package, otherwise the body is set in sans serif font for emphasis.
436 % \begin{macrocode}
437 \newenvironment{Todo}[1]%
438 {\Ed@part{#1}{To Do}\b@todo@label\ifshowednotes\bgroup\ednoteshape\else\comment\fi}
439 {\endEd@part\e@todo@label\ifshowednotes\egroup\else\endcomment\fi}
440 \newenvironment{todo}[1]%
441 {\ed@part{#1}{To Do}\b@todo@label\b@todo@margin\ifshowednotes\bgroup\ednoteshape\else\comment\fi}
442 {\ended@part\e@todo@margin\ifshowednotes\egroup\else\endcomment\fi}
443 % \end{macrocode}
444 % \end{environment}
445 %
446 % \begin{environment}{todolist}
447 % How we define the |todolist| environment depends on the |\showednotes| switch (or the
448 % package option). If we hide annotations, |todolist| is set to |comment| from the
449 % |comment| package, otherwise it is set to an itemize.
450 % \begin{macrocode}
451 \newenvironment{Todolist}[1]{% the comment
452 \ifshowednotes\message{todolist!}{{\ednoteshape To Do: #1}}\bgroup\ednoteshape\begin{compactenum}%
453 \else\comment%
454 \fi}
455 {\ifshowednotes\end{compactenum}\egroup\else\endcomment\fi}
456 \newenvironment{todolist}[1]{\ifshowednotes\ed@margin{{\ednoteshape ToDo}}\Todolist{#1}\fi}
457 {\endTodolist}
458 % \end{macrocode}
459 % \end{environment}
460 %
461 % \begin{environment}{musings}
462 % \begin{macrocode}
463 \newenvironment{musings}{\ifshowednotes\color{blue}\fi}{}
464 % \end{macrocode}
465 % \end{environment}
466 %
467 % \begin{macro}{\edstubURI}
468 % \begin{macrocode}
469 \def\ed@stubURI{}
470 \newcommand\edstuURI[1]{\gdef\ed@stubURI{#1}}
471 % \end{macrocode}
472 % \end{macro}
473 %
474 % \subsection{Stubs and External Files}
475 %
476 % \begin{environment}{edstub}
477 % \begin{macrocode}
478 \newif\ifhref\hreffalse
479 \AtBeginDocument{\@ifpackageloaded{hyperref}{\hreftrue}{\hreffalse}}
480 \newenvironment{edstub}[2][]
481 {\def\@test{#1}\begin{center}\huge\color{red}
482 \ifx\@test\@empty The following blue text \else #1 \fi is only a provisional stub\\\Large
483 the Office document
484 \ifx\ed@stubURI\@empty{#2}\else\ifhref\href{\ed@stubURI}{#2}\else{#2}\fi\fi\
485 contains more text\\which will be merged for the final document
486 \end{center}\color{blue}}
487 {}
488 % \end{macrocode}
489 % \end{environment}
490 %
491 %
492 % \subsection{Generating Statistics and Explanations}
493 %
494 % \begin{macro}{\ednotemessage}
495 % The |\@ednotemessage| makes use of the counter |ednote| and generates a message.
496 % \begin{macrocode}
497 \newcommand\@ednotemessage{\ifnum\value{ednote}>0\typeout{}%
498 \typeout{There are still \arabic{ednote} EdNotes, New/Oldparts, and Issues to resolve!}%
499 \typeout{}\fi}
500 % \end{macrocode}
501 % we output it automtatically at the end of the log file.
502 % \begin{macrocode}
503 \AtEndDocument{\@ednotemessage}
504 % \end{macrocode}
505 % \end{macro}
506 %
507 % \begin{macro}{\ednotemessage}
508 % The old |\ednotemessage| is now deprecated
509 % \begin{macrocode}
510 \newcommand\ednotemessage{\PackageWarning{ed}{The `\ednotemessage' macro is obsolete, the message
511 is generated automatically now.}}
512 % \end{macrocode}
513 % \end{macro}
514 %
515 % \begin{macro}{\edexplanation}
516 % The |\edexplanation| macro makes use of the |todolist| environment.
517 % \begin{macrocode}
518 \newcommand\edexplanation{\todolist{we will use the ednote system to communicate}
519 \item use the {\tt{\char92ednote\char123author: some explanatory text\char125}}
520 like a footnote to say what you have done or what should still be
521 done\ednote{MiKo: this is an example of an ednote}. Ednotes are numbered and
522 marked in the margin for easy recognition.
523 \item use the {\tt{\char92issue\char123author: explanation of the
524 issue\char125}} variant of ednote for issues\issue{this is an example of
525 an issue} that still have to be discussed.
526 \item finally, the {\tt{todolist}} environment is a list environment that can be
527 used to mark up todo lists. This explanation is an example of a todo list, it
528 is inserted into the text in a different font.
529 \item the {\tt{newpart}} environment can be used to mark up changed text blocks.
530 {\tt{\char92begin\char123newpart\char125}} takes an argument that is
531 interpreted as a comment and is treated like an {\tt{\char92ednote}} comment.
532 \item the {\tt{oldpart}} environment is similar to {\tt{newpart}} but is used
533 for old parts of text copied from another document that still need to be
534 changed in a document.
535 \item putting the macro {\tt{\char92ednotemessage}} just before the
536 {\tt{char92end\char123document\char125}} will generate a message with
537 cardinality information for the ednotes into the log file.
538 \item all of these text decorations and meta-annotations are only inserted into
539 the text, if the {\tt{show}} package option in the {\tt{\char92 usepackage}}
540 directive in the preamble of the document is set: {\tt{\char92
541 usepackage[show]\char123ed\char125}} will show the decorations, while
542 {\tt{\char92 usepackage\char123ed\char125}} will not. This is useful for
543 preparing ``clean'' version for outside consumption without loosing the
544 management metadata.
545 \endtodolist}
546 %</package>
547 % \end{macrocode}
548 % \end{macro}
549 % \Finale
550 \endinput
551
552 % LocalWords: LPPL dtx ednote ednotes todolist newpart oldpart serif todo ToDo
553 % LocalWords: EdNote BegNP EndNP BegOP EndOP EdNotes MiKo ednotemessage textbf
554 % LocalWords: usepackage kohlhase HeadURL iffalse nomargins edissue maketitle
555 % LocalWords: fileversion textvisiblespace textvisiblespace marginpar newif
556 % LocalWords: DescribeEnv edexplanation edexplanation ednoteshape showednotes
557 % LocalWords: ifshowednotes showednotesfalse ifmargins marginstrue compactenum
558 % LocalWords: showednotestrue marginsfalse xcolor epdnoteshape sffamily endnew
559 % LocalWords: newcounter footnotetext scshape addtocounter footnotemark bgroup
560 % LocalWords: ednotelabel tweaklabel edissuelabel providecommand theednote
561 % LocalWords: newpartlabels newenvironment oldpartlabels todolabel egroup
562 % LocalWords: endcomment endtodo endtodolist ifnum typeout Oldparts
563 % LocalWords: automtatically