Comments and a couple of test cases

diff --git a/ucwmac.tex b/ucwmac.tex
index 3bb1091146d7f71806812b0b67e52ddec8b003d1..881c6dbce2943508f74b724d0f03b6458df21c3b 100644 (file)
--- a/ucwmac.tex
+++ b/ucwmac.tex
@@ -1,7 +1,13 @@
+% The UCW Macro Collection (a successor of mjmac.tex)
+% Written by Martin Mares <mj@ucw.cz> in 2010 and placed into public domain
+% -------------------------------------------------------------------------
+
+%%% Prolog %%%
+
 % We'll use internal macros of plain TeX
 \catcode`@=11
 
-%%% PDF output switch %%%
+%%% PDF output detection %%%
 
 \newif\ifpdf
 \pdffalse
@@ -13,6 +19,7 @@
 
 %%% Page size and margins %%%
 
+% If you modify these registers, call \setuppage afterwards
 \newdimen\pagewidth
 \newdimen\pageheight
 \newdimen\leftmargin
@@ -38,13 +45,15 @@
        \fi
 }
 
+% Set multiple margins to the same value
 \def\sethmargins#1{\leftmargin=#1\relax\rightmargin=#1\relax\evenpageshift=0pt\relax}
 \def\setvmargins#1{\topmargin=#1\relax\bottommargin=#1\relax}
 \def\setmargins#1{\sethmargins{#1}\setvmargins{#1}}
 
+% Define inner/outer margin instead of left/right
 \def\setinneroutermargin#1#2{\sethmargins{#1}{#2}\evenpageshift=\rightmargin\advance\evenpageshift by -\leftmargin}
 
-\def\defpaper#1#2#3{\expandafter\def\csname paper-#1\endcsname{\pagewidth=#2\pageheight=#3\setuppage}}
+% Use a predefined paper format, calls \setuppage automagically
 \def\setpaper#1{%
        \expandafter\let\expandafter\currentpaper\csname paper-#1\endcsname
        \ifx\currentpaper\relax
@@ -53,6 +62,7 @@
        \currentpaper
 }
 
+% Switch to landscape orientation, calls \setuppage automagically
 \def\landscape{%
        \dimen0=\pageheight
        \pageheight=\pagewidth
@@ -60,6 +70,8 @@
        \setuppage
 }
 
+% Common paper sizes
+\def\defpaper#1#2#3{\expandafter\def\csname paper-#1\endcsname{\pagewidth=#2\pageheight=#3\setuppage}}
 \defpaper{a3}{297truemm}{420truemm}
 \defpaper{a4}{210truemm}{297truemm}
 \defpaper{a5}{148truemm}{210truemm}
@@ -67,6 +79,7 @@
 \defpaper{letter}{8.5truein}{11truein}
 \defpaper{legal}{8.5truein}{14truein}
 
+% Default page parameters
 \setmargins{1truein}
 \setpaper{a4}
 
@@ -102,13 +115,17 @@
 \newbox\commonunderlays
 \newbox\commonoverlays
 
-% Adding to {over,under}-lays
+% In addition to the normal page contents, you can define page overlays
+% and underlays, which are zero-size vboxes positioned absolutely in the
+% front / in the back of the normal material. Also, there are global
+% versions of both which are not reset after every page.
 \def\addlay#1#2{\setbox#1=\vbox{\ifvbox#1\box#1\fi\smashedvbox{#2}}}
 \def\pageunderlay{\addlay\pageunderlays}
 \def\pageoverlay{\addlay\pageoverlays}
 \def\commonunderlay{\addlay\commonoverlays}
 \def\commonoverlay{\addlay\commonoverlays}
 
+% Our variation on \plainoutput, which manages inner/outer margins and overlays
 \output{\ucwoutput}
 \def\ucwoutput{\wigglepage\shipout\vbox{%
        \makeheadline
@@ -123,7 +140,7 @@
 
 \def\wigglepage{\ifodd\pageno\else\advance\hoffset by \evenpageshift\fi}
 
-%%% Cleanup %%%
+%%% Epilog %%%
 
 % Let's hide all internal macros
 \catcode`@=12