dvips: Config file paper sizes
4.2 Configuration file paper size command
=========================================
The '@' command in a configuration file sets the paper size defaults and
options. The first '@' command defines the default paper size. It has
three possible parameters:
@ [NAME [HSIZE VSIZE]]
If '@' is specified on a line by itself, with no parameters, it
instructs Dvips to discard all previous paper size information (possibly
from another configuration file).
If three parameters are given, with the first parameter being a name
and the second and third being a dimension (as in '8.5in' or '3.2cc',
just like in the 'papersize' special), then the option is interpreted as
starting a new paper size description, where NAME is the name and HSIZE
and VSIZE define the horizontal and vertical size of the sheet of paper,
respectively. For example:
@ letterSize 8.5in 11in
If both HSIZE and VSIZE are zero (you must still specify units!) then
any page size will match. If the '@' character is immediately followed
by a '+' sign, then the remainder of the line (after skipping any
leading blanks) is treated as PostScript code to send to the printer,
presumably to select that particular paper size:
@ letter 8.5in 11in
@+ %%BeginPaperSize: Letter
@+ letter
@+ %%EndPaperSize
After all that, if the first character of the line is an exclamation
point, then the line is put in the initial comments section of the final
output file; else, it is put in the setup section of the output file.
For example:
@ legal 8.5in 14in
@+ ! %%DocumentPaperSizes: Legal
@+ %%BeginPaperSize: Legal
@+ legal
@+ %%EndPaperSize
When Dvips has a paper format name given on the command line, it
looks for a match by the NAME; when it has a 'papersize' special, it
looks for a match by dimensions. The best match found (from the paper
size information in the configuration file) is used. The dimensions
must match within 5bp.
If nothing matches, a warning is printed and the first paper size
with zero dimensions is used; this should be the 'unknown' paper size
definition mentioned below, resulting in the actual dimensions being
used.
Landscape mode for all paper sizes is automatically supported.
If your printer has a command to set a special paper size, then give
dimensions of '0in 0in'; the PostScript code that sets the paper size
can refer to the dimensions the user requested as 'hsize' and 'vsize';
these will be macros defined in the PostScript that return the requested
size in default PostScript units. Also, some printers want
'BeginPaperSize' comments and paper size setting commands; others (such
as the NeXT) want 'PaperSize' comments and they will handle setting the
paper size. So paper size entries should typically specify both.
When using a paper size that is not already defined in 'config.ps',
you probably want to say '-t unknown' on the command line; the 'unknown'
paper size definition in 'config.ps' has the requisite PostScript
incantation to set the PostScript page size, as just described.
If you want no paper size information in the output at all, use
'-t nopaper'. This is useful with multi-page output that will be
processed further. If you just have a single page document, you can use
'-E' to get pure EPSF output.
The Perl 5 script 'contrib/configs/mkdvipspapers' in the distribution
directory may help in determining appropriate paper size definitions.
Notwithstanding the above, the default 'letter' and 'a4' paper size
definitions in 'config.ps' execute the 'setpagedevice' operator if it
exists (it was defined in PostScript Level 2), or the 'letter' or 'a4'
operator if they exist (they are nonstandard and thus perhaps cause
failures on certain (unknown) printers). Not executing any page size
definition at all confuses PostScript conversion programs such as
'ps2pdf', so we want to execute one if we can.
The 'letterSize' and 'A4Size' paper size definitions are now synonyms
for 'letter' and 'a4'.