summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/notes/notes.dtx
blob: fceebf14bea2705eb0d4630779b019c0b915f75d (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
% \iffalse
%%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\ProvidesPackage{notes}
%<package>[2002/10/29 v1.0.1 (Duncan Webb)]
%<package>\RequirePackage{graphics}
%
%<*driver>
\documentclass{ltxdoc}
%\usepackage[debug,frames]{notes}
\usepackage{notes}
\usepackage{pifont}
\usepackage{calc}
\providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
\GetFileInfo{notes.sty}
\begin{document}
\changes{v1.0.0}{15 Jan 2002}{Initial version}
\changes{v1.0.1}{29 Oct 2002}{Corrections for CTAN}
\title{The \texttt{notes.sty} package for marking special sections
 in a document with icons}
 \author{Duncan Webb\thanks{email: duncan@dwebb.ch}}
\date{\filedate}
 \maketitle
 \DocInput{notes.dtx}
\end{document}
%</driver>
% \fi
%
% \DoNotIndex{\the,\advance,\box,\CurrentOption,\DeclareOption,\def}
% \DoNotIndex{\else,\fi,\hrule,\hspace,\newdimen,\newif,\copy}
% \DoNotIndex{\ifnum,\loop,\MessageBreak,\newcount,\divide,\eject}
% \DoNotIndex{\count,\ifx,\ifodd,\hfil,\hsize,\global,\bgroup,\egroup}
% \DoNotIndex{\PackageWarning,\ProcessOptions,\relax,\repeat,\ht,\wd}
% \DoNotIndex{\color,\textcolor,\colorbox,\begin,\end,\endinput}
% \DoNotIndex{\framebox,Rest,\huge,\line,\linethickness,\makebox}
% \DoNotIndex{\multiput,\newsavebox,\parbox,\protect,\put,\RequirePackage}
% \DoNotIndex{\savebox,\thinlines,\thicklines,\usebox,\setlength}
% \DoNotIndex{\pagefilllstretch,\pagefillstretch,\pagefilstretch}
% \DoNotIndex{\it,\tiny,\kern,\raisebox,\typeout}
% \DoNotIndex{\hbox,\hfil,\hskip,\hrule,\vbox,\vfil,\vskip,\vrule}
% \DoNotIndex{\@empty,\begingroup,\endgroup,\kern,\moveleft,\noindent}
% \DoNotIndex{\newbox,\newcommand,\newcounter,\newenvironment,\newskip}
% \DoNotIndex{\pagegoal,\pageshrink,\pagetotal,\resizebox}
% \DoNotIndex{\setbox,\setcounter,\stepcounter,\space}
%
% \begin{abstract}
% This package provides environments to highlight significant portions of
% text within a document by putting the text in a box and adding an icon
% in the margin. It has been designed specifically for double sided printing
% catering for the \LaTeX page numbering problem.
% \end{abstract}
%
% \section{Introduction}
%
% The notes package displays a block of italic text in a frame and placed in
% the margin is an icon.
%
% Currently there are three environments defined \DescribeEnv{importantnote}
% |importantnote|, \DescribeEnv{warningnote}|warningnote| and
% \DescribeEnv{informationnote}|informationnote|.
%
% Included with the package there are three icons and some \LyX{} include files.
% The icons are provided as Xfig diagrams. A make file will generate the style
% sheet, this documentation and other graphic formats. The other formats 
% include encapsulated postscript, portable document format
% and portable network graphics. The |.eps| files are used when the document is
% printed, the |.pdf| files are used when the document is converted to pdf and
% the |.png| files are used when the document is converted to HTML.
% \begin{informationnote}
% It may be necessary to remove the |.png| files before a document is converted
% to pdf because in this format they look dreadful; they are best suited 
% for HTML pages.
% \end{informationnote}
%
% The \LyX{} files should be placed in your |~/.lyx| directory so that they 
% are then available from \LyX{}.
%
% It is quite simple to change the icons or to add new note environments. 
% To change the icons, either use your own and rename the files to the 
% appropriate name.
%
% To add a new enviroment just copy an existing one and change its name. 
% Then you can change the icon name or the font.
%
% \section{Usage}
%
% In the document preamble include the |usepackage[...]{notes}|. Generally, no
% options need to be specified.
%
% To begin a note we use the one of the three environments, such as 
% |importantnote|
%
% \begin{verbatim}
% \usepackage{notes}
% ...
% \begin{importantnote}
% This is how an important note is shown
% \end{importantnote}
% \end{verbatim}
%
% and the result is:
%
% \begin{importantnote}
% This is how an important note is shown
% \end{importantnote}
%
% Here is an example of an warning note.
%
% \begin{warningnote}
% This is an example of a warning note.
%
% There is no limitation on the amount of text in the box, it can be a single
% line or several lines. However, it is not recommended to have a page full of
% text as this is not the purpose of the package.
% \end{warningnote}
%
% \section{To Do}
% There are a number of things that need to be done, possibly others that 
% I've not yet thought about.
%
% \newcounter{local}\renewcommand{\labelenumi}
%  {\setcounter{local}{171+\value{enumi}}\ding{\value{local}}}
% \begin{enumerate}
% \item Use the \texttt{.aux} mechanism, this may be more reliable and allow
% cleaner code.
% \end{enumerate}
%
% \section{The Package}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% Definable settings are listed below. |noteskipamount| is some glue that is
% printed before and after the note. |textwidth| is the length of the printable
% area. |marginparsep| is the amount of space between the icon and the main body
% of the text. |rulewd| and |ruleht| are the thickness of the frame arount the
% notes box. |textwd| is the amount of space that text in the note uses up.
% |vframegap| and |hframegap| are the gaps between the text and its frame.
%
%    \begin{macrocode}
\newskip\noteskipamount \noteskipamount=6pt plus 4pt minus 0pt
\newdimen\textwidth     \textwidth=\hsize
\newdimen\marparsep     \marparsep=4pt
\newdimen\rulewd        \rulewd=0.4pt
\newdimen\ruleht        \ruleht=0.4pt
\newdimen\iconwd        \iconwd=0.8cm
\newdimen\iconht        \iconht=0.8cm
\newdimen\textwd        \textwd=.8\textwidth
\newdimen\vframegap     \vframegap=3pt
\newdimen\hframegap     \hframegap=6pt
%    \end{macrocode}
%
% \begin{macro}{debug}
% The |debug| option set the debug flag, which numbers each of the icons and
% write in the log debug information.
%
%    \begin{macrocode}
\newif\if@debug@
\DeclareOption{debug}{%
  \global\@debug@true
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{frames}
% The |frames| option sets the frame flag, which prints frames around the icon
% and the text.
%
%    \begin{macrocode}
\newif\if@frames@
\DeclareOption{frames}{%
  \global\@frames@true
}%
\ProcessOptions*
%    \end{macrocode}
% \end{macro}
%
% Here are some dimensions that are calculated during the processing of
% the note. |notecnt| keeps a count of the notes.
%
%    \begin{macrocode}
\newcounter{notecnt}
\setcounter{notecnt}{0}
\newdimen\containerwd
\newdimen\textframeht
\newdimen\iconframeht
\newdimen\containerht
\newdimen\notesmargin
\newdimen\dbgrulewd \dbgrulewd=0pt
\newdimen\dbgruleht \dbgruleht=0pt
\if@frames@
  \dbgrulewd=0.01pt \dbgruleht=0.01pt
\fi
\def\noteskip{\vskip\noteskipamount}
%    \end{macrocode}
%
% \begin{macro}{boxdbg}
% The |boxdbg| command puts a frame around the argument if the debug flag is 
% set. The mechanism is to define a width for the line, which is 0pt when the 
% debug flag is \emph{not} set and |dbgrulewd|, |dbgruleht| when the debug 
% flag is set.
%
%    \begin{macrocode}
\def\boxdbg#1{\hbox{%
  \vrule width \dbgrulewd\vbox{%
    \hrule height \dbgruleht%
    \hbox{#1}\hrule height \dbgruleht%
  }%
  \vrule width \dbgrulewd}%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{buildtextframe}
% The |buildtextframe| command creates a frame around the argument. Space is 
% placed around the items, the vertical space is defined by |vframegap| and 
% the horizonal space is defined by the |hframegap|.
%
%    \begin{macrocode}
\def\buildtextframe#1{%
  \vbox{%
    \hrule height \ruleht%
    \hbox{%
      \vrule width \rulewd\kern\vframegap%
      \vbox{\kern\hframegap#1\kern\hframegap}%
      \kern\vframegap\vrule width \rulewd%
    }%
    \hrule height \ruleht%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{buildiconbox}
% The |buildiconbox| command creates an box around the icon, the icon is placed
% in a rectanglar box of |iconwd| by |iconht|. The default box is a 1cm sqaure.
% When the debug flag is set the note number is written at the bottom left of 
% the icon.
%
%    \begin{macrocode}
\def\buildiconbox#1{
  \if@debug@
    \raisebox{0pt}[0pt][0pt]{\makebox[0pt][c]{\tiny\thenotecnt}}%
  \fi
  \vbox{%
    \hsize \iconwd \noindent \hbox to \iconwd{%
      \hfil\resizebox*{\iconwd}{\iconht}{\includegraphics{#1}}\hfil%
    }%
  }%
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{buildiconframe}
% the |buildiconframe| command puts its argument is a vbox of |iconht|.
%
%    \begin{macrocode}
\def\buildiconframe#1{%
  \vbox to \iconht{\vfil\hbox{\buildiconbox{#1}}\vfil}%
}%
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{calccontainerht}
% The |calccontainerht| command determines the greater height of the icon
% or the text. It returns the maximum of the two dimensions passed.
%
%    \begin{macrocode}
\def\calccontainerht#1#2{
  \ifnum #1 > #2 #1 \else #2 \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{buildvcontainer}
% The |buildvcontainer| command creates an vbox to contain both the icon and the
% text boxes.  \#1 is the container height, \#2 is the box to be contained
%
%    \begin{macrocode}
\def\buildvcontainer#1#2{%
  \boxdbg{\vbox to #1{\vfil#2\vfil}}
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{buildcontainer}
% The |buildcontainer| command creates a hbox of the icon and the text box.
% In a double sided document the icon is placed on the right hand side for
% odd pages numbers and the left hand side for even page numbers. In a single
% sided document the icon is placed in the left hand side margin.
% \#1 is the text container, \#2 is the icon container
%
%    \begin{macrocode}
\def\buildcontainer#1#2{%
  \if@twoside
    \ifodd\count0
      \hbox to \containerwd{%
        \hskip\notesmargin\hfil#1\hfil\hskip\marparsep#2%
      }
    \else
      \hbox to \containerwd{
        #2\hskip\marparsep\hfil#1\hfil\hskip\notesmargin%
      }
    \fi
  \else %single sided
    \hbox to \containerwd{%
      #2\hskip\marparsep\hfil#1\hfil\hskip\notesmargin%
    }
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{buildnotes}
% Now we start the complicated bit! It is not really complicated but because
% |\ifodd\count0| is not always correct in \LaTeX it means that the amount of
% vertical space that the note takes up and the amount space left on the page
% must be calculated before the note is written to the page. \LaTeX updates
% the page when a vertical skip is sent to the page.
%
% First some boxes and dimensions are defined.
%
%    \begin{macrocode}
\newbox\iconframe
\newbox\textframe
\newbox\iconcontainer
\newbox\textcontainer
\newbox\container
\newbox\notesbox
\newdimen\pageleft
\newdimen\notesboxht
%    \end{macrocode}
%
% The height of the text frame and the icon frame are calculated. From these
% dimensions the height of the note is calculated. Six |dbgruleht|s are added
% because there are three boxes drawn when the frame flag is set.
%
% \LaTeX does not update the page total, the |noteskip| command flushes the
% value. The |pageleft| dimension is initially set to the |pagegoal| dimension
% (the total space on the page) and then it reduced by |pagetotal|
% (the space used by the text).
% |pageleft| is then reduced by the |noteskipamount|,
% |notesboxht|, |noteskipamount|. Finally a magic number is added to the amount
% left. I've no idea where this magic number comes from, but it was found by
% seeing that the amount of space left on the page was not zero. Trial and lots
% of errors discovered that this was a constant. \#1 is the text, \#2 is the 
% icon.
%
%    \begin{macrocode}
\def\buildnotes#1#2{%
  \stepcounter{notecnt}
  \if@debug@
    \typeout{NOTE \thenotecnt \space started}
  \fi
  \setbox\textframe=\buildtextframe{#1}
  \setbox\iconframe=\buildiconframe{#2}
  \containerht=\calccontainerht{\ht\iconframe}{\ht\textframe}
  % check the page remaining
  \notesboxht=\containerht
  \advance\notesboxht by \dbgruleht
  \advance\notesboxht by \dbgruleht
  \advance\notesboxht by \dbgruleht
  \advance\notesboxht by \dbgruleht
  \advance\notesboxht by \dbgruleht
  \advance\notesboxht by \dbgruleht
  \noteskip % this forces the pagetotal to be updated
  \pageleft=\pagegoal
  \advance\pageleft by -\pagetotal
  \advance\pageleft by -\noteskipamount %
  \advance\pageleft by -\notesboxht
  \advance\pageleft by -\noteskipamount %
  \advance\pageleft by \pageshrink % I'm not sure about this
  % increase the space left on the page by a magic number.
  \advance\pageleft by 0.87083pt
  \if@debug@
    \typeout{pageleft(0)=\the\pageleft}
    \typeout{wd textframe=\the\wd\textframe}
    \typeout{wd iconframe=\the\wd\iconframe}
  \fi
  \setbox\textcontainer=\buildvcontainer{\containerht}{\box\textframe}
  \setbox\iconcontainer=\buildvcontainer{\containerht}{\box\iconframe}
  \notesmargin=\marparsep
  \advance\notesmargin by \wd\iconcontainer
  % calc the container width
  \containerwd=\textwidth
  \containerwd=355pt % \textwidth can be strange
  \advance\containerwd by \notesmargin
  \advance\containerwd by \notesmargin
  \if@debug@
    \typeout{notesboxht=\the\notesboxht}
    \typeout{containerht=\the\containerht}
    \typeout{containerwd=\the\containerwd}
    \typeout{pageshrink(1)=\the\pageshrink}
    \typeout{pagetotal(1)=\the\pagetotal}
    \typeout{pageleft(1)=\the\pageleft}
    \typeout{textframeht=\the\textframeht}
    \typeout{iconframeht=\the\iconframeht}
    \typeout{wd iconcontainer=\the\wd\iconcontainer}
  \fi
  % if there is insufficient space left eject the page
  \ifnum \pageleft < 0 \eject \fi
  % build the container box
  \setbox\container=\vbox{%
    \buildcontainer{\boxdbg{\copy\textcontainer}}{%
      \boxdbg{\copy\iconcontainer}%
    }%
  }
  \setbox\notesbox=\boxdbg{\copy\container}
  \notesboxht=\ht\notesbox
  \if@debug@\typeout{notesboxht=\the\notesboxht}\fi
  % build the container box
  \moveleft \notesmargin\copy\notesbox\noteskip
  % check the page remaining
  \pageleft=\pagegoal
  \advance\pageleft by -\pagetotal
  \advance\pageleft by -\notesboxht
  \if@debug@
    \typeout{pagetotal(2)=\the\pagetotal}
    \typeout{pageleft(2)=\the\pageleft}
    \typeout{NOTE \thenotecnt \space finished}
  \fi
}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
\newbox\notebox
%    \end{macrocode}
%
% \begin{macro}{importantnote}
% The |importantnode| enviroment is defined here. A vbox is placed around the
% text, which is formatted to |textwd|. The |hand| icon is passed with the vbox
% to the |buildnotes| command.
%
%    \begin{macrocode}
\newenvironment{importantnote}%
{%
\begingroup%
\setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%
}{
\egroup
\egroup
\buildnotes{\box\notebox}{hand}
\endgroup%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{warningnote}
% The |warningnote| enviroment is defined here; the |warn| image is used for 
% this environment.
%
%    \begin{macrocode}
\newenvironment{warningnote}%
{%
\begingroup%
\setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%
}{
\egroup
\egroup
\buildnotes{\box\notebox}{warn}
\endgroup%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{informationnote}
% The |informationnote| enviroment is defined here; the |info| image is used for
% this environment.
%
%    \begin{macrocode}
\newenvironment{informationnote}%
{%
\begingroup%
\setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%
}{
\egroup
\egroup
\buildnotes{\box\notebox}{info}
\endgroup%
}
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
% \pagebreak
% \Finale{}