path: root/macros/latex/contrib/notes/notes.dtx

% \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{}