modelverse/techreport/general/vmargin.sty

%%----------------------------------------------------------------------
%% vmargin.sty
%
% LaTeX package which introduces paper sizes and provides macros for
% setting document margins.
% This package supersedes package vpage.
%
% This file can be made part of a format by typing \input vmargin.sty
% before dumping the format.
%
% Documentation & history after (last) \endinput.
%
% Still works with LaTeX 2.09.
% Supported = yes.
%
%
% Copyright (C) 1993, 1994, 1995, 1996, 1999 by:
%
% Volker Kuhlmann
% c/o University of Canterbury
% ELEC Dept
% Creyke Road
% Christchurch, New Zealand
% E-Mail: v.kuhlmann@elec.canterbury.ac.nz
%
% This program can be redistributed and/or modified under the terms
% of the LaTeX Project Public License, distributed from CTAN
% archives as macros/latex/base/lppl.txt; either
% version 1 of the License, or (at your option) any later version.
%
%%----------------------------------------------------------------------

%\def\filename{Vmargin}
\def\filename{vmargin}
\def\fileversion{V2.2}
\def\filedate{1999/06/01}

\@ifundefined{Vmargin}{}{\endinput}

\@ifundefined{documentclass}{
 \edef\Vmargin{Style `\filename', \fileversion, \filedate}
 \expandafter\everyjob\expandafter{\the\everyjob\typeout{\Vmargin}}
 \typeout{\Vmargin}
}{
 \NeedsTeXFormat{LaTeX2e}[1994/06/01]
 \ProvidesPackage{\filename}[\filedate]
 \edef\Vmargin{Package `\filename', \fileversion, <\filedate>}
 \expandafter\everyjob\expandafter{\the\everyjob\typeout{\Vmargin}}
 \typeout{\Vmargin}
}


% new lengths:	\PaperWidth, \PaperHeight
% new if:	\ifLandscape
%
\newdimen\PaperWidth
\newdimen\PaperHeight
%
\newif\ifLandscape


% \setpapersize
%
\def\setpapersize{\@ifnextchar[{\@@setps}{\@@setps[portrait]}}
\def\@@setps[#1]{%
  \@ifundefined{po@#1}{\@name@err{#1}}{\@nameuse{po@#1}}%
  \@@@setps}
\def\@@@setps#1{%
  \@ifundefined{paper@#1}{\@name@err{#1}}{}%
  \csname paper@#1\endcsname}
	% \usename{paper@#1} inside arg to \@ifundefined does not work
	% with papersize "custom".
\def\po@portrait{\Landscapefalse}
\def\po@landscape{\Landscapetrue}
\def\@po@{\ifLandscape\dimen0\PaperWidth
  \PaperWidth\PaperHeight\PaperHeight\dimen0\fi
  \@ifundefined{paperwidth}{}{\paperwidth\PaperWidth}%
  \@ifundefined{paperheight}{}{\paperheight\PaperHeight}}
\@ifundefined{PackageError}{
 \def\@name@err#1{%
   \typeout{*****> \string\setpapersize: illegal parameter: #1}}
}{
 \def\@name@err#1{\PackageError{\filename}%
 			{Paper size or orientation unknown: #1}{}}
}


% pre-defined paper/envelope sizes
%
% A0, A1, A2, ..., A9, B0, B1, ..., B9, C0, C1, ..., C9
% USletter, USlegal, USexecutive
% custom
%
\def\@defmetricpaper#1#2#3{%
  \begingroup
  \count0=0
  \def\w{\dimen1 }\def\h{\dimen2 }\def\s{\dimen3 }%
  \w#2\h#3
  \def\l{11}
  \loop
    \begingroup
    \def\t{\the\count0}
    \catcode`\t=11	% letter
    \expandafter\xdef\csname paper@#1\the\count0\endcsname{%
      \PaperWidth\the\w\PaperHeight\the\h\noexpand\@po@}
    \endgroup
    \s\w\w.5\h\h\s
  \ifnum\the\count0<9
    \advance\count0 by 1
  \repeat
  \endgroup
}
%
\@defmetricpaper{A}{840.9mm}{1189.2mm}
\@defmetricpaper{B}{1000mm}{1414mm}
\@defmetricpaper{C}{917mm}{1297mm}
%
\let\@defmetricpaper=\relax	% delete definition to save memory
%
\def\paper@USletter{\PaperWidth 8.5in \PaperHeight 11in \@po@}
\def\paper@USlegal{\PaperWidth 8.5in \PaperHeight 14in \@po@}
\def\paper@USexecutive{\PaperWidth 7.25in\PaperHeight 10.5in \@po@}
%
\def\paper@custom#1#2{\PaperWidth#1\PaperHeight#2\@po@}


% margin@offset
%
% Compensates for the +1in/+1in top/left corner
% by either reducing the margins or \hoffset, \voffset by 1in.
% This macro is only defined here if it is not already defined!
% (see documentation at the end)
%
\newif\if@shiftmargins
\@shiftmarginsfalse	% this MUST be default (pageframe.sty)
%
\@ifundefined{margin@offset}{
\def\margin@offset{
  \if@shiftmargins
	\oddsidemargin -1in\evensidemargin -1in\topmargin -1in
	\hoffset 0in\voffset 0in\relax
  \else
	\oddsidemargin 0in\evensidemargin 0in\topmargin 0in
	\hoffset -1in\voffset -1in\relax
  \fi
}}{}
%
\def\shiftmargins{\@shiftmarginstrue}


% Setting margins
%
% \setmargins{leftmargin}{topmargin}{textwidth}{textheight}% 
%    {headheight}{headsep}{footheight}{footskip}
%
\newcommand\setmargins[8]{%
	\margin@offset
	\advance\oddsidemargin	#1
	\advance\evensidemargin	\PaperWidth	% = paperwidth - left
	\advance\evensidemargin	-#1		%	- width
	\advance\evensidemargin	-#3
	\advance\topmargin	#2
	\textwidth	#3
	\textheight	#4
	\headheight	#5
	\headsep	#6
	\@ifundefined{footheight}{}{\footheight=#7}%
	\footskip	#8
	\chk@dimen{#1}{#2}{#3}{#4}%
}
%
% \setmarginsrb{leftmargin}{topmargin}{rightmargin}{bottommargin}% 
%    {headheight}{headsep}{footheight}{footskip}
%
\newcommand\setmarginsrb[8]{%
	\margin@offset
	\textwidth		\PaperWidth	% = paperwidth
	\advance\textwidth	-#1		%  - left - right
	\advance\textwidth	-#3
	\textheight		\PaperHeight	% = paperheight - top
	\advance\textheight	-#2		%  - headheight
	\advance\textheight	-#5		%  - headsep
	\advance\textheight	-#6		%  - footskip - bottom
	\advance\textheight	-#8
	\advance\textheight	-#4
	\advance\oddsidemargin	#1
	\advance\evensidemargin	\PaperWidth	% = paperwidth
	\advance\evensidemargin	-#1		%  - left - width
	\advance\evensidemargin	-\textwidth
	\advance\topmargin	#2
	\headheight	#5
	\headsep	#6
	\@ifundefined{footheight}{}{\footheight=#7}%
	\footskip	#8
	\chk@dimen{#1}{#2}{#3}{#4}%
}
%
% \setmargnohf{leftmargin}{topmargin}{textwidth}{textheight}
% headheight, headsep, footheight, footskip set to 0pt
\newcommand\setmargnohf[4]{%
	\setmargins{#1}{#2}{#3}{#4}\z@\z@\z@\z@
	\pagestyle{empty}}
%
% \setmargnohfrb{leftmargin}{topmargin}{rightmargin}{bottommargin}
% headheight, headsep, footheight, footskip set to 0pt
\newcommand\setmargnohfrb[4]{%
	\setmarginsrb{#1}{#2}{#3}{#4}\z@\z@\z@\z@
	\pagestyle{empty}}
%
% \setmarg{leftmargin}{topmargin}{textwidth}{textheight}
% headheight, headsep, footheight, footskip unchanged
\newcommand\setmarg[4]{%
	\setmargins{#1}{#2}{#3}{#4}%
	\headheight\headsep\footheight\footskip}
%
% \setmargrb{leftmargin}{topmargin}{rightmargin}{bottommargin}
% headheight, headsep, footheight, footskip unchanged
\newcommand\setmargrb[4]{%
	\setmarginsrb{#1}{#2}{#3}{#4}%
	\headheight\headsep\footheight\footskip}
%
% h-warning if [leftmarg + textwidth > paperwidth] resp.
%	    if [leftmarg + rightmarg > paperwidth].
% v-warning if [topmarg + textheight > paperheight] resp.
%	    if [topmarg + bottommarg > paperheight].
\def\chk@dimen#1#2#3#4{%
	\dimen0=	#1
	\advance\dimen0 by#3
	\advance\dimen0 -\PaperWidth
	\dimen1=	#2
	\advance\dimen1 by#4
	\advance\dimen1 \headheight
	\advance\dimen1 \headsep
	\advance\dimen1 \footskip
	\advance\dimen1 -\PaperHeight
	\chk@dimen@err
}
\@ifundefined{PackageError}{
 \def\chk@dimen@err{
	\ifnum\dimen0>\z@\typeout{vmargin Warning: Horizontal dimensions
	  exceed paper width by \the\dimen0}\fi
	\ifnum\dimen1>\z@\typeout{vmargin Warning: Vertical dimensions
	  exceed paper height by \the\dimen1}\fi
 }
}{
 \def\chk@dimen@err{
	\ifnum\dimen0>\z@\PackageError{\filename}{%
	  Horizontal dimensions exceed paper width by \the\dimen0}{}\fi
	\ifnum\dimen1>\z@\PackageError{\filename}{%
	  Vertical dimensions exceed paper height by \the\dimen1}{}\fi
 }
}


%
% DEFAULTS:
%
\setpapersize{A4}
\def\@hf@dflt{}
\@ifundefined{DeclareOption}{
}{
 \DeclareOption{shiftmargins}{\shiftmargins}
 \DeclareOption{portrait}{\Landscapefalse}
 \DeclareOption{landscape}{\Landscapetrue}
 \DeclareOption{nohf}{\def\@hf@dflt{y}}
 \DeclareOption*{\@@@setps{\CurrentOption}}
 \ProcessOptions\relax  % process options in order of declaration!
}
\if y\@hf@dflt
  \setmargnohfrb{35mm}{20mm}{25mm}{15mm}%
\else
  \setmarginsrb{35mm}{20mm}{25mm}{15mm}{12pt}{11mm}{0pt}{11mm}%
\fi


\endinput

%%----------------------------------------------------------------------

Page Size and Margins
=====================

These macros make it easy to set page margins for a chosen paper size.
Actual dimensions of the most common paper sizes are stored and need
not be remembered.

Two sided printing is supported, meaning that if on odd pages the left
margin is, say, 30mm and the right margin is 20mm, it will be vice
versa on even pages. This gives equal margins on the outer and equal
margins on the inner edge of the paper, as expected e.g. for a book.

vmargin is designed to be reasonably restricted in both memory usage
and processing time, so that the common task of setting margins is not
too distracting. If you are looking for something fancier try the
geometry package.

The basic procedure of using vmargin is to first set a paper size, and
then to set the margins. The margin setting functions depend on the
paper size. Setting the paper size and margins are two independent
operations, i.e. setting the paper size does not directly affect the
margins but will affect the next margin setting command.

The size of the paper can be set with 

	\setpapersize{<size>}

<size> can be A0, A1, ..., A9, B0, B1, ..., B9, C0, ..., C9, USletter,
USlegal, and USexecutive. The metric paper sizes are not stored but
calculated. \setpapersize by default sets the orientation to portrait.

Landscape format is selected by using the optional argument

	\setpapersize[landscape]{<size>}

which swaps the width and height dimensions of the paper.
\setpapersize[portrait]{<size>} is allowed but is the default.

If you have a size which is not pre-defined use

	\setpapersize{custom}{<width>}{<height>}

For <width> and <height> insert the respective dimensions of your
paper.

\setpapersize stores the actual dimensions of the paper in the length
variables

	\PaperWidth
	\PaperHeight

which can be used further, if desired.

	\ifLandscape

yields true if a landscape format is selected. Do not write to
\PaperWidth, \PaperHeight, or call \Landscapetrue or \Landscapefalse,
it will not work!!

The margins can be set with

	\setmargins{leftmargin}{topmargin}{textwidth}{textheight}%
  		   {headheight}{headsep}{footheight}{footskip}

or with

	\setmarginsrb{leftmargin}{topmargin}{rightmargin}{bottommargin}%
		     {headheight}{headsep}{footheight}{footskip}

In the latter case \textwidth and \textheight are calculated using the
width and height of the selected paper. The first four parameters of
the above two commands are used to set \oddsidemargin, \evensidemargin,
\textwidth, \topmargin, and \textheight.

	\setmargnohf, \setmargnohfrb

Provide a page with no header and footer. They work the same as
\setmargins, \setmarginsrb except that they only need the first 4
parameters. The last 4 parameters are set to 0pt. These 2 commands set
the pagestyle to empty (\pagestyle{empty}) as there is no space for
headers or footers.

	\setmarg, \setmargrb

are the same as \setmargnohf, \setmargnohfrb except that the last 4
parameters to \setmargins, \setmarginsrb are unchanged.

Example:

	A4 paper, left margin 30mm, top, right, and bottom margin 20mm
	each, no headers or footers:

	\setpapersize{A4}
	\setmarginsrb{30mm}{20mm}{20mm}{20mm}{0pt}{0mm}{0pt}{0mm}
	\pagestyle{empty}

The same settings would result with:

	\setpapersize{A4}
	\setmargnohfrb{30mm}{20mm}{20mm}{20mm}

For the default settings please see the part after "DEFAULTS:" (last
part before \endinput). 

The default top and left margins of TeX are +1in. \setmargXXX call

	\margin@offset

which initialises \hoffset, \voffset to -1in and \oddsidemargin,
\evensidemargin, \topmargin to 0in. \setmargXXX then add the given
dimensions to \topmargin, \oddsidemargin, \evensidemargin. In some
cases it might be desired to use \XXXmargin instead of \Xoffset for
compensation. This can be achieved by telling \margin@offset to
initialise \Xoffset to 0in and \XXXmargin to -1in. This is done by
%
	\shiftmargins.
%
If \margin@offset is already defined at the time vmargin is loaded it
is NOT redefined! Therefore if \margin@offset is defined before vmargin
is loaded the above mentioned compensation can be replaced by a
different mechanism. In any case \setmargXXX call \margin@offset and
then expect that \XXXmargin are set to useful values. \Xoffset are not
touched by \setmargXXX.  \margin@offset should be defined in a separate
file which is included BEFORE vmargin, i.e. appears in the list of
document-substyles of the \documentstyle command before vmargin.
%
Any better way of doing this? (grumble)

Example:  \documentstyle[...,margins,vmargin,...]{...} 
	  if \margin@offset is defined in a file called margins.sty.

LaTeX2e:  \documentclass[...]{...}
	  \usepackage{...,margins,vmargin,...}


LaTeX2e
-------

This package now uses some of the new LaTeX2e features for package
programming. It will still work with LaTeX 2.09 (in which case the new
features are not used, resp. are inaccessible).

LaTeX2e (unless in compatibility mode) does not know \footheight any
more. vmargin does not set this variable if it does not exist, and sets
it if it does. As \footheight was not used by LaTeX 2.09 all this has
little significance.

LaTeX2e now has the dimensions \paperwidth, \paperheight which hold the
size of the paper. \PaperWidth, \PaperHeight are copied into
\paperwidth, \paperheight if the latter exist. This makes vmargin work
correctly with anything that expects \paperwidth, \paperheight to be
set properly. The names \PaperWidth, \PaperHeight had been chosen in
the first place to avoid clashes with style files that also use these
names (namely pageframe.sty).

The following package options are available under LaTeX2e:

shiftmargins	same as \shiftmargins
portrait
landscape
A4, etc.	same as using \setpapersize[...]{...}
		Note: \setpapersize always sets the orientation to
		portrait unless landscape is given. Using \setpapersize
		after \usepackage causes package option landscape to be
		ignored.
nohf		do not make space for header and footer lines; this also
		sets the pagestyle to empty

All unknown options are treated as a paper size, if necessary
generating an error that the requested paper size is not defined.


Inclusion in TeX formats
------------------------

This file may be loaded in initex before dumping the format, by typing
	\makeatletter
	\input vmargin.sty
	\makeatother
Note: this produces a non-standard format.


Hints for using pageframe.sty
-----------------------------

vmargin.sty and pageframe.sty can be used together if the following
points are considered:

vmargin uses \hoffset and \voffset and writes negative values into it,
pageframe expects them to be zero to give a 1in space on the left and
the top where it prints additional information. Initially, set both to
0mm (in the pre-amble of your text) and adjust them later on.

pageframe needs to know the trimmed height of the paper (= the height
of the "page frame"). Unless the trimmed(!) size of the paper is
equivalent to one of the standard paper sizes (unlikely...) the size
should be specified with

	\setpapersize{custom}{<width>}{<height>}

The correct height of the trimmed page can then be given to pageframe
using

	\paperheight{\PaperHeight}

and the margins of the final product (inside the page frame) can be
specified using \setmargXXX.

Warning: if \setmargXXXrb is used the 3rd parameter (right margin) is
ignored. Instead, the dimension of the right margin has to be assigned
to \evensidemargin. This is because pageframe.sty re-defines the meaning
of \evensidemargin to be the right margin of your text, on all pages.

Remember: all these assignments and macro calls have to be in the
pre-amble of the document.


Bugs:
-----

I have not tested this with older versions of LaTeX2e because I don't
have any. If there are any problems pleease do let me know and I'll do
something about it.


To do:
------

* The way the metric paper sizes are stored takes up a lot of space. A
  metric size could be computed by \setpapersize.


SUMMARY:
========

new lengths:
  \PaperWidth
  \PaperHeight

new ifs:
  \ifLandscape

new macros:
  \setpapersize[<orientation>]{<size>}, 
  \setpapersize[<orientation>]{custom}{<width>}{<height>}
	<orientation> (optional) = landscape or portrait (default)
	<size> = A4, B5, ...
	<width>, <height> = actual dimensions of the paper
  \setmargins{leftmargin}{topmargin}{textwidth}{textheight}%
  	     {headheight}{headsep}{footheight}{footskip}
  \setmarginsrb{leftmargin}{topmargin}{rightmargin}{bottommargin}%
  	       {headheight}{headsep}{footheight}{footskip}
  \setmargnohf{leftmargin}{topmargin}{textwidth}{textheight}
  \setmargnohfrb{leftmargin}{topmargin}{rightmargin}{bottommargin}
  \setmarg{leftmargin}{topmargin}{textwidth}{textheight}
  \setmargrb{leftmargin}{topmargin}{rightmargin}{bottommargin}
%
  \margin@offset
  \shiftmargins

LaTeX2e package options:
  shiftmargins
  portrait
  landscape
  nohf
  all other options are treated as paper sizes


If you have any comments (positive or negative) please let me know!



HISTORY:
========

	.
	.		Created out of Vpage.sty.
	.
V1.7	  21 May 1994	Changed file header.
V1.72	  21 May 1994	Fixed bug in \setpapersize{custom}
V1.8	  28 May 94	Commented \chk@dimen; reduced load on TeX's
			parameter stack (changed \chk@dimen).
			Put a conditional around references 
			to \footheight.
V1.9	  22 Jun 94	Corrected spelling in comment.
V2.0      28 Jun 94     Added support for LaTeX2e \paperwidth,
			\paperheight.
V2.1	  20 Sep 94	\@defmetricpaper now defines \w, \h, \s locally.
			Thanks to branderhorst@fgg.eur.nl!
V2.12	  28 Mar 95	Fixed documentation for \setmargrb.
V2.13	  26 Jun 96	Fixed comment for \setmarginsrb.
V2.2	  31 May 99	Released under LPPL.
			Changed references to Vmargin to vmargin.
			LaTeX2e package options introduced.
%
%% EOF vmargin.sty
%%----------------------------------------------------------------------