Debian Codegraph @

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

raw
1 % \iffalse
2 %%
3 %<package>\NeedsTeXFormat{LaTeX2e}
4 %<package>\ProvidesPackage{notes}
5 %<package>[2002/10/29 v1.0.1 (Duncan Webb)]
6 %<package>\RequirePackage{graphics}
7 %
8 %<*driver>
9 \documentclass{ltxdoc}
10 %\usepackage[debug,frames]{notes}
11 \usepackage{notes}
12 \usepackage{pifont}
13 \usepackage{calc}
14 \providecommand{\LyX}{L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
15 \GetFileInfo{notes.sty}
16 \begin{document}
17 \changes{v1.0.0}{15 Jan 2002}{Initial version}
18 \changes{v1.0.1}{29 Oct 2002}{Corrections for CTAN}
19 \title{The \texttt{notes.sty} package for marking special sections
20 in a document with icons}
21 \author{Duncan Webb\thanks{email: [email protected]}}
22 \date{\filedate}
23 \maketitle
24 \DocInput{notes.dtx}
25 \end{document}
26 %</driver>
27 % \fi
28 %
29 % \DoNotIndex{\the,\advance,\box,\CurrentOption,\DeclareOption,\def}
30 % \DoNotIndex{\else,\fi,\hrule,\hspace,\newdimen,\newif,\copy}
31 % \DoNotIndex{\ifnum,\loop,\MessageBreak,\newcount,\divide,\eject}
32 % \DoNotIndex{\count,\ifx,\ifodd,\hfil,\hsize,\global,\bgroup,\egroup}
33 % \DoNotIndex{\PackageWarning,\ProcessOptions,\relax,\repeat,\ht,\wd}
34 % \DoNotIndex{\color,\textcolor,\colorbox,\begin,\end,\endinput}
35 % \DoNotIndex{\framebox,Rest,\huge,\line,\linethickness,\makebox}
36 % \DoNotIndex{\multiput,\newsavebox,\parbox,\protect,\put,\RequirePackage}
37 % \DoNotIndex{\savebox,\thinlines,\thicklines,\usebox,\setlength}
38 % \DoNotIndex{\pagefilllstretch,\pagefillstretch,\pagefilstretch}
39 % \DoNotIndex{\it,\tiny,\kern,\raisebox,\typeout}
40 % \DoNotIndex{\hbox,\hfil,\hskip,\hrule,\vbox,\vfil,\vskip,\vrule}
41 % \DoNotIndex{\@empty,\begingroup,\endgroup,\kern,\moveleft,\noindent}
42 % \DoNotIndex{\newbox,\newcommand,\newcounter,\newenvironment,\newskip}
43 % \DoNotIndex{\pagegoal,\pageshrink,\pagetotal,\resizebox}
44 % \DoNotIndex{\setbox,\setcounter,\stepcounter,\space}
45 %
46 % \begin{abstract}
47 % This package provides environments to highlight significant portions of
48 % text within a document by putting the text in a box and adding an icon
49 % in the margin. It has been designed specifically for double sided printing
50 % catering for the \LaTeX page numbering problem.
51 % \end{abstract}
52 %
53 % \section{Introduction}
54 %
55 % The notes package displays a block of italic text in a frame and placed in
56 % the margin is an icon.
57 %
58 % Currently there are three environments defined \DescribeEnv{importantnote}
59 % |importantnote|, \DescribeEnv{warningnote}|warningnote| and
60 % \DescribeEnv{informationnote}|informationnote|.
61 %
62 % Included with the package there are three icons and some \LyX{} include files.
63 % The icons are provided as Xfig diagrams. A make file will generate the style
64 % sheet, this documentation and other graphic formats. The other formats
65 % include encapsulated postscript, portable document format
66 % and portable network graphics. The |.eps| files are used when the document is
67 % printed, the |.pdf| files are used when the document is converted to pdf and
68 % the |.png| files are used when the document is converted to HTML.
69 % \begin{informationnote}
70 % It may be necessary to remove the |.png| files before a document is converted
71 % to pdf because in this format they look dreadful; they are best suited
72 % for HTML pages.
73 % \end{informationnote}
74 %
75 % The \LyX{} files should be placed in your |~/.lyx| directory so that they
76 % are then available from \LyX{}.
77 %
78 % It is quite simple to change the icons or to add new note environments.
79 % To change the icons, either use your own and rename the files to the
80 % appropriate name.
81 %
82 % To add a new enviroment just copy an existing one and change its name.
83 % Then you can change the icon name or the font.
84 %
85 % \section{Usage}
86 %
87 % In the document preamble include the |usepackage[...]{notes}|. Generally, no
88 % options need to be specified.
89 %
90 % To begin a note we use the one of the three environments, such as
91 % |importantnote|
92 %
93 % \begin{verbatim}
94 % \usepackage{notes}
95 % ...
96 % \begin{importantnote}
97 % This is how an important note is shown
98 % \end{importantnote}
99 % \end{verbatim}
100 %
101 % and the result is:
102 %
103 % \begin{importantnote}
104 % This is how an important note is shown
105 % \end{importantnote}
106 %
107 % Here is an example of an warning note.
108 %
109 % \begin{warningnote}
110 % This is an example of a warning note.
111 %
112 % There is no limitation on the amount of text in the box, it can be a single
113 % line or several lines. However, it is not recommended to have a page full of
114 % text as this is not the purpose of the package.
115 % \end{warningnote}
116 %
117 % \section{To Do}
118 % There are a number of things that need to be done, possibly others that
119 % I've not yet thought about.
120 %
121 % \newcounter{local}\renewcommand{\labelenumi}
122 % {\setcounter{local}{171+\value{enumi}}\ding{\value{local}}}
123 % \begin{enumerate}
124 % \item Use the \texttt{.aux} mechanism, this may be more reliable and allow
125 % cleaner code.
126 % \end{enumerate}
127 %
128 % \section{The Package}
129 %
130 % \begin{macrocode}
131 %<*package>
132 % \end{macrocode}
133 %
134 % Definable settings are listed below. |noteskipamount| is some glue that is
135 % printed before and after the note. |textwidth| is the length of the printable
136 % area. |marginparsep| is the amount of space between the icon and the main body
137 % of the text. |rulewd| and |ruleht| are the thickness of the frame arount the
138 % notes box. |textwd| is the amount of space that text in the note uses up.
139 % |vframegap| and |hframegap| are the gaps between the text and its frame.
140 %
141 % \begin{macrocode}
142 \newskip\noteskipamount \noteskipamount=6pt plus 4pt minus 0pt
143 \newdimen\textwidth \textwidth=\hsize
144 \newdimen\marparsep \marparsep=4pt
145 \newdimen\rulewd \rulewd=0.4pt
146 \newdimen\ruleht \ruleht=0.4pt
147 \newdimen\iconwd \iconwd=0.8cm
148 \newdimen\iconht \iconht=0.8cm
149 \newdimen\textwd \textwd=.8\textwidth
150 \newdimen\vframegap \vframegap=3pt
151 \newdimen\hframegap \hframegap=6pt
152 % \end{macrocode}
153 %
154 % \begin{macro}{debug}
155 % The |debug| option set the debug flag, which numbers each of the icons and
156 % write in the log debug information.
157 %
158 % \begin{macrocode}
159 \newif\if@debug@
160 \DeclareOption{debug}{%
161 \global\@debug@true
162 }%
163 % \end{macrocode}
164 % \end{macro}
165 %
166 % \begin{macro}{frames}
167 % The |frames| option sets the frame flag, which prints frames around the icon
168 % and the text.
169 %
170 % \begin{macrocode}
171 \newif\if@frames@
172 \DeclareOption{frames}{%
173 \global\@frames@true
174 }%
175 \ProcessOptions*
176 % \end{macrocode}
177 % \end{macro}
178 %
179 % Here are some dimensions that are calculated during the processing of
180 % the note. |notecnt| keeps a count of the notes.
181 %
182 % \begin{macrocode}
183 \newcounter{notecnt}
184 \setcounter{notecnt}{0}
185 \newdimen\containerwd
186 \newdimen\textframeht
187 \newdimen\iconframeht
188 \newdimen\containerht
189 \newdimen\notesmargin
190 \newdimen\dbgrulewd \dbgrulewd=0pt
191 \newdimen\dbgruleht \dbgruleht=0pt
192 \if@frames@
193 \dbgrulewd=0.01pt \dbgruleht=0.01pt
194 \fi
195 \def\noteskip{\vskip\noteskipamount}
196 % \end{macrocode}
197 %
198 % \begin{macro}{boxdbg}
199 % The |boxdbg| command puts a frame around the argument if the debug flag is
200 % set. The mechanism is to define a width for the line, which is 0pt when the
201 % debug flag is \emph{not} set and |dbgrulewd|, |dbgruleht| when the debug
202 % flag is set.
203 %
204 % \begin{macrocode}
205 \def\boxdbg#1{\hbox{%
206 \vrule width \dbgrulewd\vbox{%
207 \hrule height \dbgruleht%
208 \hbox{#1}\hrule height \dbgruleht%
209 }%
210 \vrule width \dbgrulewd}%
211 }
212 % \end{macrocode}
213 % \end{macro}
214 %
215 % \begin{macro}{buildtextframe}
216 % The |buildtextframe| command creates a frame around the argument. Space is
217 % placed around the items, the vertical space is defined by |vframegap| and
218 % the horizonal space is defined by the |hframegap|.
219 %
220 % \begin{macrocode}
221 \def\buildtextframe#1{%
222 \vbox{%
223 \hrule height \ruleht%
224 \hbox{%
225 \vrule width \rulewd\kern\vframegap%
226 \vbox{\kern\hframegap#1\kern\hframegap}%
227 \kern\vframegap\vrule width \rulewd%
228 }%
229 \hrule height \ruleht%
230 }%
231 }
232 % \end{macrocode}
233 % \end{macro}
234 %
235 % \begin{macro}{buildiconbox}
236 % The |buildiconbox| command creates an box around the icon, the icon is placed
237 % in a rectanglar box of |iconwd| by |iconht|. The default box is a 1cm sqaure.
238 % When the debug flag is set the note number is written at the bottom left of
239 % the icon.
240 %
241 % \begin{macrocode}
242 \def\buildiconbox#1{
243 \if@debug@
244 \raisebox{0pt}[0pt][0pt]{\makebox[0pt][c]{\tiny\thenotecnt}}%
245 \fi
246 \vbox{%
247 \hsize \iconwd \noindent \hbox to \iconwd{%
248 \hfil\resizebox*{\iconwd}{\iconht}{\includegraphics{#1}}\hfil%
249 }%
250 }%
251 }
252 % \end{macrocode}
253 % \end{macro}
254 %
255 % \begin{macro}{buildiconframe}
256 % the |buildiconframe| command puts its argument is a vbox of |iconht|.
257 %
258 % \begin{macrocode}
259 \def\buildiconframe#1{%
260 \vbox to \iconht{\vfil\hbox{\buildiconbox{#1}}\vfil}%
261 }%
262 % \end{macrocode}
263 % \end{macro}
264 %
265 % \begin{macro}{calccontainerht}
266 % The |calccontainerht| command determines the greater height of the icon
267 % or the text. It returns the maximum of the two dimensions passed.
268 %
269 % \begin{macrocode}
270 \def\calccontainerht#1#2{
271 \ifnum #1 > #2 #1 \else #2 \fi
272 }
273 % \end{macrocode}
274 % \end{macro}
275 %
276 % \begin{macro}{buildvcontainer}
277 % The |buildvcontainer| command creates an vbox to contain both the icon and the
278 % text boxes. \#1 is the container height, \#2 is the box to be contained
279 %
280 % \begin{macrocode}
281 \def\buildvcontainer#1#2{%
282 \boxdbg{\vbox to #1{\vfil#2\vfil}}
283 }
284 % \end{macrocode}
285 % \end{macro}
286 %
287 % \begin{macro}{buildcontainer}
288 % The |buildcontainer| command creates a hbox of the icon and the text box.
289 % In a double sided document the icon is placed on the right hand side for
290 % odd pages numbers and the left hand side for even page numbers. In a single
291 % sided document the icon is placed in the left hand side margin.
292 % \#1 is the text container, \#2 is the icon container
293 %
294 % \begin{macrocode}
295 \def\buildcontainer#1#2{%
296 \if@twoside
297 \ifodd\count0
298 \hbox to \containerwd{%
299 \hskip\notesmargin\hfil#1\hfil\hskip\marparsep#2%
300 }
301 \else
302 \hbox to \containerwd{
303 #2\hskip\marparsep\hfil#1\hfil\hskip\notesmargin%
304 }
305 \fi
306 \else %single sided
307 \hbox to \containerwd{%
308 #2\hskip\marparsep\hfil#1\hfil\hskip\notesmargin%
309 }
310 \fi
311 }
312 % \end{macrocode}
313 % \end{macro}
314 %
315 % \begin{macro}{buildnotes}
316 % Now we start the complicated bit! It is not really complicated but because
317 % |\ifodd\count0| is not always correct in \LaTeX it means that the amount of
318 % vertical space that the note takes up and the amount space left on the page
319 % must be calculated before the note is written to the page. \LaTeX updates
320 % the page when a vertical skip is sent to the page.
321 %
322 % First some boxes and dimensions are defined.
323 %
324 % \begin{macrocode}
325 \newbox\iconframe
326 \newbox\textframe
327 \newbox\iconcontainer
328 \newbox\textcontainer
329 \newbox\container
330 \newbox\notesbox
331 \newdimen\pageleft
332 \newdimen\notesboxht
333 % \end{macrocode}
334 %
335 % The height of the text frame and the icon frame are calculated. From these
336 % dimensions the height of the note is calculated. Six |dbgruleht|s are added
337 % because there are three boxes drawn when the frame flag is set.
338 %
339 % \LaTeX does not update the page total, the |noteskip| command flushes the
340 % value. The |pageleft| dimension is initially set to the |pagegoal| dimension
341 % (the total space on the page) and then it reduced by |pagetotal|
342 % (the space used by the text).
343 % |pageleft| is then reduced by the |noteskipamount|,
344 % |notesboxht|, |noteskipamount|. Finally a magic number is added to the amount
345 % left. I've no idea where this magic number comes from, but it was found by
346 % seeing that the amount of space left on the page was not zero. Trial and lots
347 % of errors discovered that this was a constant. \#1 is the text, \#2 is the
348 % icon.
349 %
350 % \begin{macrocode}
351 \def\buildnotes#1#2{%
352 \stepcounter{notecnt}
353 \if@debug@
354 \typeout{NOTE \thenotecnt \space started}
355 \fi
356 \setbox\textframe=\buildtextframe{#1}
357 \setbox\iconframe=\buildiconframe{#2}
358 \containerht=\calccontainerht{\ht\iconframe}{\ht\textframe}
359 % check the page remaining
360 \notesboxht=\containerht
361 \advance\notesboxht by \dbgruleht
362 \advance\notesboxht by \dbgruleht
363 \advance\notesboxht by \dbgruleht
364 \advance\notesboxht by \dbgruleht
365 \advance\notesboxht by \dbgruleht
366 \advance\notesboxht by \dbgruleht
367 \noteskip % this forces the pagetotal to be updated
368 \pageleft=\pagegoal
369 \advance\pageleft by -\pagetotal
370 \advance\pageleft by -\noteskipamount %
371 \advance\pageleft by -\notesboxht
372 \advance\pageleft by -\noteskipamount %
373 \advance\pageleft by \pageshrink % I'm not sure about this
374 % increase the space left on the page by a magic number.
375 \advance\pageleft by 0.87083pt
376 \if@debug@
377 \typeout{pageleft(0)=\the\pageleft}
378 \typeout{wd textframe=\the\wd\textframe}
379 \typeout{wd iconframe=\the\wd\iconframe}
380 \fi
381 \setbox\textcontainer=\buildvcontainer{\containerht}{\box\textframe}
382 \setbox\iconcontainer=\buildvcontainer{\containerht}{\box\iconframe}
383 \notesmargin=\marparsep
384 \advance\notesmargin by \wd\iconcontainer
385 % calc the container width
386 \containerwd=\textwidth
387 \containerwd=355pt % \textwidth can be strange
388 \advance\containerwd by \notesmargin
389 \advance\containerwd by \notesmargin
390 \if@debug@
391 \typeout{notesboxht=\the\notesboxht}
392 \typeout{containerht=\the\containerht}
393 \typeout{containerwd=\the\containerwd}
394 \typeout{pageshrink(1)=\the\pageshrink}
395 \typeout{pagetotal(1)=\the\pagetotal}
396 \typeout{pageleft(1)=\the\pageleft}
397 \typeout{textframeht=\the\textframeht}
398 \typeout{iconframeht=\the\iconframeht}
399 \typeout{wd iconcontainer=\the\wd\iconcontainer}
400 \fi
401 % if there is insufficient space left eject the page
402 \ifnum \pageleft < 0 \eject \fi
403 % build the container box
404 \setbox\container=\vbox{%
405 \buildcontainer{\boxdbg{\copy\textcontainer}}{%
406 \boxdbg{\copy\iconcontainer}%
407 }%
408 }
409 \setbox\notesbox=\boxdbg{\copy\container}
410 \notesboxht=\ht\notesbox
411 \if@debug@\typeout{notesboxht=\the\notesboxht}\fi
412 % build the container box
413 \moveleft \notesmargin\copy\notesbox\noteskip
414 % check the page remaining
415 \pageleft=\pagegoal
416 \advance\pageleft by -\pagetotal
417 \advance\pageleft by -\notesboxht
418 \if@debug@
419 \typeout{pagetotal(2)=\the\pagetotal}
420 \typeout{pageleft(2)=\the\pageleft}
421 \typeout{NOTE \thenotecnt \space finished}
422 \fi
423 }
424 % \end{macrocode}
425 % \end{macro}
426 %
427 % \begin{macrocode}
428 \newbox\notebox
429 % \end{macrocode}
430 %
431 % \begin{macro}{importantnote}
432 % The |importantnode| enviroment is defined here. A vbox is placed around the
433 % text, which is formatted to |textwd|. The |hand| icon is passed with the vbox
434 % to the |buildnotes| command.
435 %
436 % \begin{macrocode}
437 \newenvironment{importantnote}%
438 {%
439 \begingroup%
440 \setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%
441 }{
442 \egroup
443 \egroup
444 \buildnotes{\box\notebox}{hand}
445 \endgroup%
446 }
447 % \end{macrocode}
448 % \end{macro}
449 % \begin{macro}{warningnote}
450 % The |warningnote| enviroment is defined here; the |warn| image is used for
451 % this environment.
452 %
453 % \begin{macrocode}
454 \newenvironment{warningnote}%
455 {%
456 \begingroup%
457 \setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%
458 }{
459 \egroup
460 \egroup
461 \buildnotes{\box\notebox}{warn}
462 \endgroup%
463 }
464 % \end{macrocode}
465 % \end{macro}
466 % \begin{macro}{informationnote}
467 % The |informationnote| enviroment is defined here; the |info| image is used for
468 % this environment.
469 %
470 % \begin{macrocode}
471 \newenvironment{informationnote}%
472 {%
473 \begingroup%
474 \setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%
475 }{
476 \egroup
477 \egroup
478 \buildnotes{\box\notebox}{info}
479 \endgroup%
480 }
481 % \end{macrocode}
482 % \end{macro}
483 %
484 % \begin{macrocode}
485 %</package>
486 % \end{macrocode}
487 % \pagebreak
488 % \Finale{}