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