summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ed/ed.dtx
blob: 918756b1c36f038ead88e76522614cab82ec096d (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
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
% \iffalse meta-comment
% Editorial Notes for LaTeX
% Copyright (c) 2009 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/forCTAN/ed/ed.dtx $
% \fi
% 
% \iffalse
%<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
%<package>\ProvidesPackage{ed}[2012/01/29 v1.8 Editorial Notes]
%
%<*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,a4wide}
\usepackage[show]{ed}
\usepackage[eso-foot,today,draft]{svninfo}
\usepackage{hyperref}
%\makeindex
\begin{document}
\svnInfo $Id: ed.dtx 23125 2012-01-29 12:15:08Z kohlhase $
\svnKeyword $HeadURL: https://svn.kwarc.info/repos/kwarc/doc/macros/forCTAN/ed/ed.dtx $
\DocInput{ed.dtx}
\end{document}
%</driver>
% \fi
% 
%\CheckSum{409}
% 
% \changes{v1.0}{2005/06/23}{First Version with Documentation}
% \changes{v1.1}{2005/10/03}{Added capitalized variants}
% \changes{v1.2}{2007/05/10}{adding todo environment}
% \changes{v1.3}{2007/10/03}{rationalizing todo environment}
% \changes{v1.4}{2007/11/12}{localization}
% \changes{v1.5}{2008/06/08}{todolist now uses enumerate}
% \changes{v1.6}{2009/06/18}{nomargins option}
% \changes{v1.6}{2009/06/24}{deprecated issue for edissue to get around name clashes.}
% \changes{v1.6}{2009/10/29}{made ednotemessage automatic}
% \changes{v1.7}{2011/01/16}{adding final/draft options}
% \changes{v1.8}{2012/01/29}{adding \texttt{edstub} environment}
% 
% \GetFileInfo{ed.sty}
% 
% \MakeShortVerb{\|}
% \title{Editorial Notes for {\LaTeX}\thanks{Version {\fileversion} (last revised
%        {\filedate})}} 
%    \author{Michael Kohlhase\\
%            Computer Science, Jacobs University\\
%            \url{http://kwarc.info/kohlhase}}
% \maketitle
%
% \begin{abstract}
%   This package defines a couple of editorial notes that simplify collaboration on a
%   {\LaTeX} text. These allow authors to annotate status information in the source. In
%   draft mode, the annotations are shown for communication, and in publication mode these
%   are suppressed.
% \end{abstract}
%
% \tableofcontents\newpage
%
% \section{Introduction}\label{sec:intro}
%
% When collaborating on a document with multiple authors, communication about the status
% of a given passage and intentions about what to do with it, indications about issues
% still need to be resolved, and directives to other authors, e.g. calling for help, or
% passing the baton, etc.  make up much of the overhead involved in collaboration. In
% particular, many of the necessary communicative acts are centered around specific points
% or passages in the document at hand. Therefore it is natural to embed the communicative
% acts in the document source itself. The simplest version of this is to special markers
% like ``(*** remember to rework this before publication ***)'', where the markers
% ``(***'' and ``***)'' serve as a visual aid and target for search and navigation tools
% in the editor. Of course this is dangerous, and we have all seen published texts with
% such markers still present.
%
% The {\LaTeX} package described in here systematizes the idea and provides more conspicuous
% visual markers (as footnotes and margin notes) and a way of making all all of these
% private markers and comments invisible for publication or outside communication.
%
% \section{The User Interface}\label{sec:user-interface}
%
% \subsection{Package Options}
%
% As usual in {\LaTeX}, the package is loaded by |\usepackage[|\meta{options}|]{ed}|,
% where |[|\meta{options}|]| is optional and gives a comma separated list of options.  The
% |ed| package takes the options \DescribeMacro{show}|show| and
% \DescribeMacro{hide}|hide|, where |hide| is the default case, so that |\usepackage{ed}|,
% is equivalent to |\usepackage[hide]{ed}|. If the |show| option is given, then the
% editorial notes are presented as special annotations to the document, otherwise they are
% completely invisible --- if you take care about spaces in the source code. For instance
% |text|\textvisiblespace|\ednote{|\ldots|}|\textvisiblespace|text| will fool {\TeX}'s
% whitespace-collapsing algorithm and bring it to output two spaces in the document
% instead of just one as expected |text\ednote{|\ldots|}|\textvisiblespace|text| should be
% used instead!  This |hide| option useful for preparing ``clean'' version for outside
% consumption without losing the management metadata. In some situations the |\marginpar|
% decorations generated by editorial notes are disallowed, for these situations the |ed|
% package has the \DescribeMacro{nomargins}|nomargins| option that disables them.
% 
% As many classes support the \DescribeMacro{draft}|draft| and
% \DescribeMacro{final}|final| options and pass them on to all loaded packages that will
% take them, the |ed| package supports them as aliases for |show| and |hide|.
%
% \subsection{Annotation Macros}
% 
% \DescribeMacro{\ednote} The main user macro of this package is |\ednote|. It is used say
% what you have done or what should still be done at a given point in the document.
% |ed.sty| formats it like a footnote, but with a margin note that marks the place in the
% text, where the note is located. Otherwise, in the presence of multiple |\ednote|s in a
% page it may be difficult to find the referenced locations\ednote{this is an example of
%   an ednote}.  Editorial notes are numbered and marked in the margin for easy
% recognition.  |\ednote| also takes an optional argument that is an identifier. This
% allows to cross-reference ednotes in each other.
%
% \DescribeMacro{\edissue} The |\edissue| macro\edissue{The control sequence\textbf{issue}
%   conflicts with many other macro packages, maybe we should rename it to
%   \textbf{edissue}.} is a variant of |\ednote| for issues that still have to be
% discussed among the authors. For issues the labeling and cross-referencing in the
% optional argument is especially useful. Note that the \DescribeMacro{\issue}|\issue|
% macro which earlier versions of the |ed| package provided is deprecated in favor of
% |\edissue|. The old |\issue| macro is only provided for backwards compatibility if it is
% not defined by other packages. For this to work, the |ed| package should be loaded late
% in the preamble.
%
% \DescribeMacro{\tweak} The |\tweak| macro\tweak{this is an example of an tweak} is a
% variant of |\ednote| for marking places where we have tweaked something (apart from the
% standard way we usually use).
%
% \DescribeEnv{todo} The |todo| environment is an environment that can be used to mark up
% writing tasks. These are inserted into the text in a different font, so that they are
% conspicuous as a foreign part, and take an argument for a comment.
%
% \DescribeEnv{todolist} The |todolist| is a variant of the |todo| environment which is a
% is an itemized list.
%
% The following is an example, generated form the the input 
% |\begin{todolist}{an example todolist}| \ldots |\item| \ldots |\end{todolist}|.
% \begin{todolist}{an example todolist}
%   \item lots of good examples
%   \item a general chapter about best practices
% \end{todolist}
%
% \DescribeEnv{newpart}\DescribeEnv{oldpart} the |newpart| environment can be used to mark
% up changed text blocks.  |\beg||in{newpart}| takes an argument that is interpreted as a
% comment and is treated like an |\ednote| comment.  The |oldpart| environment is similar
% to |newpart| but is used for old parts of text copied from another document that still
% need to be changed in a document. They displayed in gray, so that they can be identified
% better.
%
% The annotation macros have capitalized variants (|\Ednote|, |\edIssue|, |\Tweak|,
% |Todo|, |Newpart|, |Oldpart|) that do not make location marks in the margin. This is
% convenient in situations (e.g. inside boxes or minipages) that allow footnotes, but no
% margin notes.
%
% \subsection{Stubs and External Files}
%
% In some collaborative editing situations not all participants are willing to write
% {\LaTeX}, but insist on developing their proposal parts in some other word procesing
% software. The |ed| class offers the \DescribeEnv{edstub}|edstub| environment:
%
% |\begin{edstub}[|\meta{exp}|]{|\meta{file}|}| marks the content of the environment as
%   provisional (e.g. by turning it blue) and lists an external file (\meta{file}) as the
%   original. Here, \meta{exp} is an optional reformulation of the default desription
%   ``The following blue text''. The following stub
%
% \begin{edstub}{stub.doc}
% here are some provisional ideas
% \end{edstub}
%
% is generated by
%
% \begin{verbatim}
% \begin{edstub}{stub.doc}
% here are some provisional ideas
% \end{edstub}
% \end{verbatim}
%
% For hyperlinking \meta{file} the \DescribeMacro{edstubURI}|edstubURI| can be used to set
% a URI: After setting |\edstubURI{|\meta{URI}|}| with a non-empty URI, \meta{file} is
% hyperlinked to \meta{URI}|/|\meta{file}. If \meta{file} is in the same directory as the
% current document, use |\edstubURI{.}|.
%
%   \subsection{Generating Statistics and Explanations}
%
% \DescribeMacro{\ednotemessage} Up to version 1.6, the |ed| package had an explicit macro
% |\ednotemessage| that put just before the |\end||{document}| will generates a message
% with cardinality information for the ednotes into the log file. This macro is now
% deprecated, since the message is now automatically generated. 
%
% \DescribeMacro{\edexplanation} The |\edexplanation| macro generates an explanation of the
% best practices into the document. So that if you introduce collaboration partners to the
% |ed| package, you can give them an explanation ``in-place''. 
%
% \subsection{Configuration}
%
% \DescribeMacro{\ednoteshape} The font shape of editorial annotations is governed by the
% parameter |\ednoteshape| the default is sans serif, specialize it to say italic by
% |\def\ednoteshape{\it}|. The labels in the margins can be tweaked (e.g. for
% localization:) by setting the (internal) macros |\ednote@label|, |\tweak@label|,
% |\edissue@label|, |\b@todo@label|, |\e@todo@label|. 
%
% \subsection{Best Practices}
%
% In a situation with multiple authors, we it is advisable to use the |\ednote| in the
% following form: |\ednote{author: some explanatory text}| to specify the originator of the
% note.
%
% \StopEventually{\newpage\PrintChanges}\newpage
%
% \section{The Implementation} 
%
% The implementation is rather standard. We first set up the options for the package.
%
% \subsection{Package Options}
%
% The main switch is |\showednotes|, which governs the visibility of the annotations.
%    \begin{macrocode}
%<*package>
\newif\ifshowednotes\showednotesfalse
\newif\ifmargins\marginstrue
%    \end{macrocode}
%    the next step is to declare the package options, they just set |\showednotes| switch
%    accordingly.
%    \begin{macrocode}
\DeclareOption{show}{\showednotestrue\message{ed.sty: showing ednotes}}
\DeclareOption{hide}{\showednotesfalse\message{ed.sty: hiding ednotes}}
\DeclareOption{draft}{\showednotestrue\message{ed.sty: showing ednotes}}
\DeclareOption{final}{\showednotesfalse\message{ed.sty: hiding ednotes}}
\DeclareOption{nomargins}{\marginsfalse}
\ProcessOptions
%    \end{macrocode}
% The next step is to load the |verbatim| or |paralist| packages, so that we can either
% comment out the or use the |compactenum| environment for todo lists.
%    \begin{macrocode}
\ifshowednotes
\RequirePackage{paralist}
\RequirePackage{xcolor}
\else
\RequirePackage{verbatim}
\fi
%    \end{macrocode}
%    This ends the package setup code, so we can come to the implementation of the
%    functionality of the package. 
%
% \subsection{Annotation Macros}
%
% \begin{macro}{\ednoteshape}
%    We start with the configuration part, predefining
%    |\epdnoteshape| to be sans serif. 
%    \begin{macrocode}
\newcommand\ednoteshape{\sffamily}
%    \end{macrocode}
% \end{macro}
% 
%    The next step is to set up a counter for the editorial annotations
%    \begin{macrocode}
\newcounter{ednote}
%    \end{macrocode}
%
% \begin{macro}{\ed@foot}
%    The internal macro |\ed@foot| is used to actually make the annotations, it is used 
%    by the interface macros to give the annotations. It takes three arguments: A comment
%    text that goes into the footnote, a type descriptor, and an identifiers.
%    \begin{macrocode}
\newcommand\ed@foot[3]% text, type, label
{\def\@test{#3}\footnotetext[\arabic{ednote}]%
{{\scshape{#2}\if\@test\@empty\else\label{ed:#3}[{#3}]\fi:} \ednoteshape #1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ed@footnote}
%  extends the |\ed@foot| to a complete footnote
%    \begin{macrocode}
\newcommand\ed@footnote[3]{\footnotemark[\arabic{ednote}]\ed@foot{#1}{#2}{#3}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ed@margin}
%    The internal macro |\ed@margin| makes a |\marginpar| annotation if allowed. 
%    \begin{macrocode}
\newcommand\ed@margin[1]{\ifmargins\marginpar{#1}\fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\Ed@note}
%    Another internal macro |\Ed@note| adds label management to |\ed@foot|
%    \begin{macrocode}
\newcommand\Ed@note[3]% text, type, label
{\addtocounter{ednote}{1}\message{#2!}%
\ifshowednotes\ed@footnote{#1}{#2}{#3}\fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ed@note}
%    |\ed@note| is a variant of |\Ed@note| that also makes an identifying mark in the
%    margin. 
%    \begin{macrocode}
\newcommand\ed@note[4]% text, type, label, margin
{\Ed@note{#1}{#2}{#3}\ifshowednotes\ed@margin{#4:\arabic{ednote}}\fi}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ednotelabel}
%    \begin{macrocode}
\newcommand\ednote@label{EdNote}
\newcommand\ednote@margin{EdN}
\newcommand\ednotelabel[1]{\def\ednote@label{#1}}
\newcommand\ednotemargin[1]{\def\ednote@margin{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ednote}
%    with the |\Ed@note| and |\ed@note| macros it is very simple to get the desired
%    functionality of |\Ednote| and |\ednote|: 
%    \begin{macrocode}
\newcommand{\Ednote}[2][]{\Ed@note{#2}\ednote@label{#1}}
\newcommand{\ednote}[2][]{\ed@note{#2}\ednote@label{#1}\ednote@margin}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tweaklabel}
%    \begin{macrocode}
\newcommand\tweaklabel[1]{\def\tweak@label{#1}}
\newcommand\tweak@label{Tweak}
\newcommand\tweakmargin[1]{\def\tweak@margin{#1}}
\newcommand\tweak@margin{Tw}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\tweak}
%   and of course for |\tweak|:
%    \begin{macrocode}
\newcommand{\tweak}[2][]{\ed@note{#2}\tweak@label{#1}\tweak@margin}
\newcommand{\Tweak}[2][]{\Ed@note{#2}\tweak@label{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\edissuelabel}
%    \begin{macrocode}
\newcommand\edissue@label{Issue}
\newcommand\edissuelabel[1]{\def\edissue@label{#1}}
\newcommand\edissue@margin{Is}
\newcommand\edissuemargin[1]{\def\edissue@margin{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\edissue}
%    \begin{macrocode}
\providecommand{\issue}[2][]{\ed@note{#2}\edissue@label{#1}\edissue@margin}
\providecommand{\Issue}[2][]{\Ed@note{#2}\edissue@label{#1}}
\newcommand{\edissue}[2][]{\ed@note{#2}\edissue@label{#1}\edissue@margin}
\newcommand{\edIssue}[2][]{\Ed@note{#2}\edissue@label{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{environment}{Ed@part}
%    For the text status environments |Newpart| and |Oldpart| we also set up an internal
%    macro that does the work. 
%    \begin{macrocode}
\newenvironment{Ed@part}[3]% text, mess, start
{\addtocounter{ednote}{1}\edef\new@number{\theednote}\message{#2!\new@number}
\ifshowednotes\ed@foot{#1}{#2}{}\fi}
{}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{ed@part}
%    and one that makes the marginpars.
%    \begin{macrocode}
\def\ed@part#1#2#3#4% text, mess, start, margin
{\Ed@part{#1}{#2}{#3}\ifshowednotes\ed@margin{#4:\new@number}\fi}
\def\ended@part#1{\endEd@part\ifshowednotes\ed@margin{#1:\new@number}\fi}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{newpartlabels}
%    \begin{macrocode}
\newcommand\b@newpart@label{BegNP}\newcommand\e@newpart@label{EndNP}
\newcommand\b@newpart@margin{BNP}\newcommand\e@newpart@margin{ENP}
\newcommand\newpartmargins[2]{\def\b@newpart@margin{#1}\def\e@newpart@margin{#2}}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{newpart}
%    We instantiate it for the |newpart| environment
%    \begin{macrocode}
\newenvironment{Newpart}[1]{\Ed@part{#1}{New Part}\b@newpart@label}{\endEd@part}
\newenvironment{newpart}[1]{\ed@part{#1}{New Part}\b@newpart@label\b@newpart@margin}{\ended@part\e@newpart@margin}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{oldpartlabels}
%    \begin{macrocode}
\newcommand\oldpartlabels[2]{\def\b@oldpart@label{#1}\def\e@oldpart@label{#2}}
\newcommand\oldpartmargins[2]{\def\b@oldpart@margin{#1}\def\e@oldpart@margin{#2}}
\newcommand\b@oldpart@label{BegOP}\newcommand\e@oldpart@label{EndOP}
\newcommand\b@oldpart@margin{BOP}\newcommand\e@oldpart@margin{EOP}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{oldpart}
%    and of course for the |oldpart| environment
%    \begin{macrocode}
\newenvironment{Oldpart}[1]%
{\Ed@part{#1}{Old Part}\b@oldpart@label\ifshowednotes\color{gray}\fi}
{\endEd@part}
\newenvironment{oldpart}[1]%
{\ed@part{#1}{Old Part}\b@oldpart@label\b@oldpart@margin\ifshowednotes\color{gray}\fi}
{\ended@part\e@oldpart@margin}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{todolabel}
%    \begin{macrocode}
\newcommand\todolabels[2]{\def\b@todo@label{#1}\def\e@todo@label{#2}}
\newcommand\todomargins[2]{\def\b@todo@margin{#1}\def\e@todo@margin{#2}}
\newcommand\b@todo@label{ToDo}\newcommand\e@todo@label{Done}
\newcommand\b@todo@margin{ToDo}\newcommand\e@todo@margin{Done}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{todo}
%   How we define the |todo| environment depends on the |\showednotes| switch (or the
%   package option). If we hide annotations, |todo| is set to |comment| from the
%   |comment| package, otherwise the body is set in sans serif font for emphasis.
%    \begin{macrocode}
\newenvironment{Todo}[1]%
{\Ed@part{#1}{To Do}\b@todo@label\ifshowednotes\bgroup\ednoteshape\else\comment\fi}
{\endEd@part\e@todo@label\ifshowednotes\egroup\else\endcomment\fi}
\newenvironment{todo}[1]%
{\ed@part{#1}{To Do}\b@todo@label\b@todo@margin\ifshowednotes\bgroup\ednoteshape\else\comment\fi}
{\ended@part\e@todo@margin\ifshowednotes\egroup\else\endcomment\fi}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{todolist}
%    How we define the |todolist| environment depends on the |\showednotes| switch (or the
%    package option). If we hide annotations, |todolist| is set to |comment| from the
%    |comment| package, otherwise it is set to an itemize. 
%    \begin{macrocode}
\newenvironment{Todolist}[1]{% the comment
\ifshowednotes\message{todolist!}{{\ednoteshape To Do: #1}}\bgroup\ednoteshape\begin{compactenum}%
\else\comment%
\fi}
{\ifshowednotes\end{compactenum}\egroup\else\endcomment\fi}
\newenvironment{todolist}[1]{\ifshowednotes\ed@margin{{\ednoteshape ToDo}}\Todolist{#1}\fi}
{\endTodolist}
%    \end{macrocode}
% \end{environment}
%
% \begin{environment}{musings}
%    \begin{macrocode}
\newenvironment{musings}{\ifshowednotes\color{blue}\fi}{}
%    \end{macrocode}
% \end{environment}
%
% \begin{macro}{\edstubURI}
%    \begin{macrocode}
\def\ed@stubURI{}
\newcommand\edstuURI[1]{\gdef\ed@stubURI{#1}}
%    \end{macrocode}
% \end{macro}
% 
% \subsection{Stubs and External Files}
%
% \begin{environment}{edstub}
%    \begin{macrocode}
\newif\ifhref\hreffalse
\AtBeginDocument{\@ifpackageloaded{hyperref}{\hreftrue}{\hreffalse}}
\newenvironment{edstub}[2][]
{\def\@test{#1}\begin{center}\huge\color{red}
\ifx\@test\@empty The following blue text \else #1 \fi is only a provisional stub\\\Large 
the Office document 
\ifx\ed@stubURI\@empty{#2}\else\ifhref\href{\ed@stubURI}{#2}\else{#2}\fi\fi\ 
contains more text\\which will be merged for the final document
  \end{center}\color{blue}}
{}
%    \end{macrocode}
% \end{environment}
% 
% 
% \subsection{Generating Statistics and Explanations}
%
% \begin{macro}{\ednotemessage}
%    The |\@ednotemessage| makes use of the counter |ednote| and generates a message. 
%    \begin{macrocode}
\newcommand\@ednotemessage{\ifnum\value{ednote}>0\typeout{}%
\typeout{There are still \arabic{ednote} EdNotes, New/Oldparts, and Issues to resolve!}%
\typeout{}\fi}
%    \end{macrocode}
% we output it automtatically at the end of the log file. 
%    \begin{macrocode}
\AtEndDocument{\@ednotemessage}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\ednotemessage}
%    The old |\ednotemessage| is now deprecated
%    \begin{macrocode}
\newcommand\ednotemessage{\PackageWarning{ed}{The `\ednotemessage' macro is obsolete, the message
  is generated automatically now.}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\edexplanation}
%    The |\edexplanation| macro makes use of the |todolist| environment. 
%    \begin{macrocode}
\newcommand\edexplanation{\todolist{we will use the ednote system to communicate}
\item use the {\tt{\char92ednote\char123author: some explanatory text\char125}}
  like a footnote to say what you have done or what should still be
  done\ednote{MiKo: this is an example of an ednote}. Ednotes are numbered and
  marked in the margin for easy recognition.
\item use the {\tt{\char92issue\char123author: explanation of the
      issue\char125}} variant of ednote for issues\issue{this is an example of
    an issue} that still have to be discussed.
\item finally, the {\tt{todolist}} environment is a list environment that can be
  used to mark up todo lists. This explanation is an example of a todo list, it
  is inserted into the text in a different font.
\item the {\tt{newpart}} environment can be used to mark up changed text blocks.
  {\tt{\char92begin\char123newpart\char125}} takes an argument that is
  interpreted as a comment and is treated like an {\tt{\char92ednote}} comment.
\item the {\tt{oldpart}} environment is similar to {\tt{newpart}} but is used
  for old parts of text copied from another document that still need to be
  changed in a document.
\item putting the macro {\tt{\char92ednotemessage}} just before the
  {\tt{char92end\char123document\char125}} will generate a message with
  cardinality information for the ednotes into the log file.
\item all of these text decorations and meta-annotations are only inserted into
  the text, if the {\tt{show}} package option in the {\tt{\char92 usepackage}}
  directive in the preamble of the document is set: {\tt{\char92
      usepackage[show]\char123ed\char125}} will show the decorations, while
  {\tt{\char92 usepackage\char123ed\char125}} will not. This is useful for
  preparing ``clean'' version for outside consumption without loosing the
  management metadata.
\endtodolist}
%</package>
%    \end{macrocode}
% \end{macro}
% \Finale
\endinput

% LocalWords:  LPPL dtx ednote ednotes todolist newpart oldpart serif todo ToDo
% LocalWords:  EdNote BegNP EndNP BegOP EndOP EdNotes MiKo ednotemessage textbf
% LocalWords:  usepackage kohlhase HeadURL iffalse nomargins edissue maketitle
% LocalWords:  fileversion textvisiblespace textvisiblespace marginpar newif
% LocalWords:  DescribeEnv edexplanation edexplanation ednoteshape showednotes
% LocalWords:  ifshowednotes showednotesfalse ifmargins marginstrue compactenum
% LocalWords:  showednotestrue marginsfalse xcolor epdnoteshape sffamily endnew
% LocalWords:  newcounter footnotetext scshape addtocounter footnotemark bgroup
% LocalWords:  ednotelabel tweaklabel edissuelabel providecommand theednote
% LocalWords:  newpartlabels newenvironment oldpartlabels todolabel egroup
% LocalWords:  endcomment endtodo endtodolist ifnum typeout Oldparts
% LocalWords:  automtatically