The notes.sty package for marking special sections in a document with icons

Duncan Webb^{∗}

2002/10/29

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 L^{A}TEXpage numbering problem.

1 Introduction

The notes package displays a block of italic text in a frame and placed in the margin is an icon.

importantnote Currently there are three environments defined importantnote, warningnote

warningnote and 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.

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.

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.

∗email: duncan@dwebb.ch

2 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
 \usepackage{notes}
 ...
 \begin{importantnote}
 This is how an important note is shown
 \end{importantnote}

and the result is:

This is how an important note is shown

Here is an example of an warning note.

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.

3 To Do

There are a number of things that need to be done, possibly others that I’ve not yet thought about.

Use the .aux mechanism, this may be more reliable and allow cleaner code.

4 The Package

1 ⟨∗package⟩

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.

 2 \newskip\noteskipamount \noteskipamount=6pt plus 4pt minus 0pt
 3 \newdimen\textwidth     \textwidth=\hsize
 4 \newdimen\marparsep     \marparsep=4pt
 5 \newdimen\rulewd        \rulewd=0.4pt
 6 \newdimen\ruleht        \ruleht=0.4pt
 7 \newdimen\iconwd        \iconwd=0.8cm

 8 \newdimen\iconht        \iconht=0.8cm
 9 \newdimen\textwd        \textwd=.8\textwidth
10 \newdimen\vframegap     \vframegap=3pt
11 \newdimen\hframegap     \hframegap=6pt

debug The debug option set the debug flag, which numbers each of the icons and write in the log debug information.

12 \newif\if@debug@
13 \DeclareOption{debug}{%
14 \global\@debug@true
15 }%

frames The frames option sets the frame flag, which prints frames around the icon and the text.

16 \newif\if@frames@
17 \DeclareOption{frames}{%
18 \global\@frames@true
19 }%
20 \ProcessOptions*

Here are some dimensions that are calculated during the processing of the note. notecnt keeps a count of the notes.

21 \newcounter{notecnt}
22 \setcounter{notecnt}{0}
23 \newdimen\containerwd
24 \newdimen\textframeht
25 \newdimen\iconframeht
26 \newdimen\containerht
27 \newdimen\notesmargin
28 \newdimen\dbgrulewd \dbgrulewd=0pt
29 \newdimen\dbgruleht \dbgruleht=0pt
30 \if@frames@
31 \dbgrulewd=0.01pt \dbgruleht=0.01pt
32 \fi
33 \def\noteskip{\vskip\noteskipamount}

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 not set and dbgrulewd, dbgruleht when the debug flag is set.

34 \def\boxdbg#1{\hbox{%
35 \vrule width \dbgrulewd\vbox{%
36  \hrule height \dbgruleht%
37  \hbox{#1}\hrule height \dbgruleht%
38 }%
39 \vrule width \dbgrulewd}%

40 }

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.

41 \def\buildtextframe#1{%
42 \vbox{%

43  \hrule height \ruleht%
44  \hbox{%
45  \vrule width \rulewd\kern\vframegap%
46  \vbox{\kern\hframegap#1\kern\hframegap}%
47  \kern\vframegap\vrule width \rulewd%
48  }%
49  \hrule height \ruleht%
50 }%

51 }

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.

52 \def\buildiconbox#1{
53 \if@debug@
54  \raisebox{0pt}[0pt][0pt]{\makebox[0pt][c]{\tiny\thenotecnt}}%
55 \fi
56 \vbox{%
57  \hsize \iconwd \noindent \hbox to \iconwd{%
58  \hfil\resizebox*{\iconwd}{\iconht}{\includegraphics{#1}}\hfil%
59  }%
60 }%

61 }

buildiconframe the buildiconframe command puts its argument is a vbox of iconht.

62 \def\buildiconframe#1{%
63 \vbox to \iconht{\vfil\hbox{\buildiconbox{#1}}\vfil}%
64 }%

calccontainerht The calccontainerht command determines the greater height of the icon or the text. It returns the maximum of the two dimensions passed.

65 \def\calccontainerht#1#2{
66 \ifnum #1 > #2 #1 \else #2 \fi

67 }

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

68 \def\buildvcontainer#1#2{%
69 \boxdbg{\vbox to #1{\vfil#2\vfil}}

70 }

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

71 \def\buildcontainer#1#2{%
72 \if@twoside
73  \ifodd\count0
74  \hbox to \containerwd{%
75  \hskip\notesmargin\hfil#1\hfil\hskip\marparsep#2%

77  \else
78  \hbox to \containerwd{
79  #2\hskip\marparsep\hfil#1\hfil\hskip\notesmargin%

80 }

81  \fi
82 \else %single sided
83  \hbox to \containerwd{%
84  #2\hskip\marparsep\hfil#1\hfil\hskip\notesmargin%

85 }

86 \fi

87 }

buildnotes Now we start the complicated bit! It is not really complicated but because \ifodd\count0 is not always correct in L^{A}TEXit 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. L^{A}TEXupdates the page when a vertical skip is sent to the page.

First some boxes and dimensions are defined.

88 \newbox\iconframe
89 \newbox\textframe
90 \newbox\iconcontainer
91 \newbox\textcontainer
92 \newbox\container
93 \newbox\notesbox
94 \newdimen\pageleft
95 \newdimen\notesboxht

The height of the text frame and the icon frame are calculated. From these dimensions the height of the note is calculated. Six dbgrulehts are added because there are three boxes drawn when the frame flag is set.

L^{A}TEXdoes 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.

96 \def\buildnotes#1#2{%
97 \stepcounter{notecnt}
98 \if@debug@
99  \typeout{NOTE \thenotecnt \space started}
100 \fi
101 \setbox\textframe=\buildtextframe{#1}
102 \setbox\iconframe=\buildiconframe{#2}
103 \containerht=\calccontainerht{\ht\iconframe}{\ht\textframe}
104 % check the page remaining
105 \notesboxht=\containerht
106 \advance\notesboxht by \dbgruleht
107 \advance\notesboxht by \dbgruleht
108 \advance\notesboxht by \dbgruleht
109 \advance\notesboxht by \dbgruleht

110 \advance\notesboxht by \dbgruleht
111 \advance\notesboxht by \dbgruleht
112 \noteskip % this forces the pagetotal to be updated
113 \pageleft=\pagegoal
114 \advance\pageleft by -\pagetotal
115 \advance\pageleft by -\noteskipamount %
116 \advance\pageleft by -\notesboxht
117 \advance\pageleft by -\noteskipamount %
118 \advance\pageleft by \pageshrink % I'm not sure about this
119 % increase the space left on the page by a magic number.
120 \advance\pageleft by 0.87083pt
121 \if@debug@
122  \typeout{pageleft(0)=\the\pageleft}
123  \typeout{wd textframe=\the\wd\textframe}
124  \typeout{wd iconframe=\the\wd\iconframe}
125 \fi
126 \setbox\textcontainer=\buildvcontainer{\containerht}{\box\textframe}
127 \setbox\iconcontainer=\buildvcontainer{\containerht}{\box\iconframe}
128 \notesmargin=\marparsep
129 \advance\notesmargin by \wd\iconcontainer
130 % calc the container width
131 \containerwd=\textwidth
132 \containerwd=355pt % \textwidth can be strange
133 \advance\containerwd by \notesmargin
134 \advance\containerwd by \notesmargin
135 \if@debug@
136  \typeout{notesboxht=\the\notesboxht}
137  \typeout{containerht=\the\containerht}
138  \typeout{containerwd=\the\containerwd}
139  \typeout{pageshrink(1)=\the\pageshrink}
140  \typeout{pagetotal(1)=\the\pagetotal}
141  \typeout{pageleft(1)=\the\pageleft}
142  \typeout{textframeht=\the\textframeht}
143  \typeout{iconframeht=\the\iconframeht}
144  \typeout{wd iconcontainer=\the\wd\iconcontainer}
145 \fi
146 % if there is insufficient space left eject the page
147 \ifnum \pageleft < 0 \eject \fi
148 % build the container box
149 \setbox\container=\vbox{%
150  \buildcontainer{\boxdbg{\copy\textcontainer}}{%
151  \boxdbg{\copy\iconcontainer}%

152 }% 153 }

154 \setbox\notesbox=\boxdbg{\copy\container}
155 \notesboxht=\ht\notesbox
156 \if@debug@\typeout{notesboxht=\the\notesboxht}\fi
157 % build the container box
158 \moveleft \notesmargin\copy\notesbox\noteskip
159 % check the page remaining
160 \pageleft=\pagegoal
161 \advance\pageleft by -\pagetotal
162 \advance\pageleft by -\notesboxht
163 \if@debug@

164  \typeout{pagetotal(2)=\the\pagetotal}
165  \typeout{pageleft(2)=\the\pageleft}
166  \typeout{NOTE \thenotecnt \space finished}
167 \fi

168 }

169 \newbox\notebox

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.

170 \newenvironment{importantnote}%

171 {%

172 \begingroup%
173 \setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%

174 }{

175 \egroup
176 \egroup
177 \buildnotes{\box\notebox}{hand}
178 \endgroup%

179 }

warningnote The warningnote enviroment is defined here; the warn image is used for this environment.

180 \newenvironment{warningnote}%

181 {%

182 \begingroup%
183 \setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%

184 }{

185 \egroup
186 \egroup
187 \buildnotes{\box\notebox}{warn}
188 \endgroup%

189 }

informationnote The informationnote enviroment is defined here; the info image is used for this environment.

190 \newenvironment{informationnote}%

191 {%

192 \begingroup%
193 \setbox\notebox=\vbox\bgroup\hsize\textwd\noindent\bgroup\it%

194 }{

195 \egroup
196 \egroup
197 \buildnotes{\box\notebox}{info}
198 \endgroup%

199 }

200 ⟨/package⟩

Index

Numbers written in italic refer to the page where the corresponding entry is described; numbers underlined refer to the code line of the definition; numbers in roman refer to the code lines where the entry is used.

Symbols

\@debug@true . . . . . . 14
\@frames@true . . . . . 18

B

\boxdbg …. 34, \underline{34},

69, 150, 151, 154

\buildcontainer . .

. . . . . 71, \underline{71}, 150

\buildiconbox 52, \underline{52}, 63
\buildiconframe . .

. . . . . 62, \underline{62}, 102

\buildnotes . . . . \underline{88},

96, 177, 187, 197

\buildtextframe . .

. . . . . 41, \underline{41}, 101

\buildvcontainer .

. . 68, \underline{68}, 126, 127

C

\calccontainerht .

. . . . . 65, \underline{65}, 103

\container 92, 149, 154
\containerht 26, 103,

105, 126, 127, 137

\containerwd . . . . .

… 23, 74, 78, 83, 131–134, 138

D

\dbgruleht . . . . 29,

31, 36, 37, 106–111 \dbgrulewd 28, 31, 35, 39 \debug . . . . . . . . . . . \underline{12}

E

environments:

importantnote . . 1

   informationnote 1
   warningnote . . . . 1

F

\frames . . . . . . . . . . \underline{16}

H

\hframegap . . . . 11, 46

I

\iconcontainer . 90,

127, 129, 144, 151

\iconframe . . . . 88,

102, 103, 124, 127

\iconframeht . . 25, 143

\iconht . . . . . 8, 58, 63 \iconwd . . . . . 7, 57, 58

\if@debug@ 12, 53, 98,

121, 135, 156, 163

\if@frames@ . . . . 16, 30
\if@twoside . . . . . . . 72
\importantnote . . . \underline{170}
importantnote (envi-

ronment) …. 1

\includegraphics . . 58
\informationnote . \underline{190}
informationnote (en-

vironment) … 1

M

\marparsep . . . . . .

. 4, 75, 79, 84, 128

N

\notebox . . . . . . . .

169, 173, 177, 183, 187, 193, 197

\notesbox . . . . . . .

. 93, 154, 155, 158

                         \notesboxht . . . . 95,

105–111, 116, 136, 155, 156, 162

\noteskip . 33, 112, 158

                         \noteskipamount . .

… 2, 33, 115, 117

                         \notesmargin . . . 27,

75, 79, 84, 128, 129, 133, 134, 158

P

                         \pageleft . . . . . . .

. 94, 113–118, 120, 122, 141, 147, 160–162, 165

R \ruleht . . . . . 6, 43, 49 \rulewd . . . . . 5, 45, 47

T

                         \textcontainer . . .

…. 91, 126, 150

                         \textframe . . . . 89,

101, 103, 123, 126

                         \textframeht . . 24, 142

\textwd 9, 173, 183, 193 \textwidth 3, 9, 131, 132

                         \thenotecnt . 54, 99, 166

V

                         \vframegap . 10, 45, 47

W

                         \warningnote . . . . . \underline{180}
                         warningnote (environ-

ment) . . . . . . . 1