188 lines
6.3 KiB
Text
188 lines
6.3 KiB
Text
An experiment in page makeup for troff output...
|
|
|
|
-mpm is a version of standard -ms that causes extra
|
|
information for vertical justification and figure
|
|
placement to be included in troff output. Commands that
|
|
have been augmented to provide paddable space are
|
|
|
|
.SH and .NH
|
|
.PP and .LP no space if \n(PD is 0; normally .nr PD 0.3v; leave at least 1u
|
|
.IP and .QP also
|
|
.EQ and .EN
|
|
.TS and .TE no space if \n(TS is 0; normally .nr TS 0.5v
|
|
.PS and .PE
|
|
.P1 and .P2 display programs in CW font
|
|
.DS and .DE
|
|
.QS and .QE
|
|
|
|
Other commands, registers, strings, etc.:
|
|
|
|
.SP n explicit paddable space, just like .sp n.
|
|
generally you should ALWAYS use .SP instead of .sp.
|
|
if you need exactly a given vertical space, you can say
|
|
.SP 3i exactly
|
|
this space won't be padded.
|
|
.Tm words prints "words" and the output page number on stderr
|
|
sorry about the spelling; -ms pre-empted .TM
|
|
.NE n like .ne. note: does not cause a break
|
|
|
|
Others may be added as the need arises.
|
|
|
|
.nr FO n Set the page length. This value is the bottom of
|
|
the text on the page; a bottom title may lie below.
|
|
default is 10i (== 10 inches).
|
|
%o, %e are strings containing odd and even page titles
|
|
%# is the current page number (often useless)
|
|
.PT is a macro invoked at the top of each "page";
|
|
it will normally use %e, %o and %#. There is also
|
|
a .BT for page bottoms if desired.
|
|
.BP force a page break
|
|
.FL force all waiting figures out before any more running text
|
|
.1C, .2C multiple columns; number registers CW and GW set
|
|
the column and gutter width if you don't like the default.
|
|
absent a .FC command, all two-column contents collect
|
|
together on the page
|
|
.FC freeze current two-column contents and start afresh.
|
|
necessary if you want to switch between 1 and 2 column
|
|
text and keep the relative order among them.
|
|
|
|
Usage is some variant of
|
|
|
|
... | troff -mpm
|
|
|
|
/usr/lib/tmac/pm is the page-justifier itself; it is called automatically
|
|
by the -mpm macro package. If you are installing this yourself, you will
|
|
have to edit the 2nd line of tmac.pm to arrange that pm is called directly
|
|
from troff.
|
|
|
|
There are several lines in tmac.pm that say
|
|
.so /n/coma/usr/bwk/...
|
|
You should delete these; they are placeholders for some experiments.
|
|
|
|
If you use -mm, you are more or less out of luck, although we will be
|
|
happy to provide a crude and incomplete program that purports to convert
|
|
-mm to -ms. It may suggest what you need but it won't do the job.
|
|
|
|
To compile pm, you need a C++ compiler, preferably release 2.0 or later.
|
|
Put the .c and .h files in a directory, and type
|
|
make
|
|
This process may well fail. The usual cause is that different systems
|
|
put function declarations in different header files, and C++ insists that
|
|
all functions be properly declared. You can almost always get through this
|
|
part by adding function declarations. The most likely offender is malloc;
|
|
a line like
|
|
extern char *malloc(int);
|
|
near the top of slug.c will solve this one.
|
|
|
|
|
|
Bugs, etc.:
|
|
|
|
not all -ms commands have been decorated; in particular,
|
|
the rich variety of document types (TM, CSTR, etc.,) is not
|
|
really supported.
|
|
|
|
there are problems with funny first pages and troff input
|
|
that moves back up the page.
|
|
|
|
multiple columns: only .2C is available. The program does not check
|
|
whether something is wide or narrow: user has responsibility to mark
|
|
which with .1C or .2C.
|
|
|
|
headings are a bit tricky if you want things like
|
|
running titles that include the current section title.
|
|
normally a two-pass procedure using .Tm is needed.
|
|
|
|
It's a pain to force a blank vertical space of specified height.
|
|
Try this:
|
|
.de x
|
|
\v'\\$1'\0\h'-\w'\0'u'\c
|
|
..
|
|
.x 2.5i
|
|
|
|
|
|
If you want to roll your own, the following components are
|
|
included in pm's "command language". They are inserted in
|
|
the troff output in the form of "x X ..." commands, which
|
|
are created either by \X'...' or by the .X macro in -mpm.
|
|
Look at how they are used in /usr/lib/tmac/tmac.pm for examples.
|
|
|
|
|
|
BS n breakable stream n = min # lines that must appear on page
|
|
use: PP, LP, IP, ...
|
|
|
|
US unbreakable stream use: KS/KE, DS/DE, TS/TE, EQ/EN, PS/PE, etc.
|
|
|
|
BF v breakable float v = preferred vertical location of box center
|
|
use: FS/FE
|
|
use two successive BF's to give two preferences
|
|
|
|
UF v unbreakable float v = preferred vertical location of box center
|
|
use: KF/KE
|
|
use two successive UF's to give two preferences
|
|
|
|
PT page title use: user has absolute control between PT and END
|
|
no SP's or other pm commands inside are processed
|
|
|
|
BT bottom title use: user has absolute control between BT and END
|
|
|
|
END end end a US, BF, UF, PT, or BT
|
|
all constructs nest, but a float within another float
|
|
or a US block will not float within or outside the block
|
|
|
|
NE n need break page if a VBOX of height n would not fit on page
|
|
use: .NE n
|
|
|
|
SP n space paddable space of n
|
|
use: .SP n
|
|
|
|
PARM NP v top of pm text at v
|
|
new page
|
|
|
|
PARM FO v bottom of pm text at v
|
|
footer length of text on page = FO-NP
|
|
|
|
PARM PL v physical page ends at v
|
|
page length default = FO + NP
|
|
|
|
PARM MF x tolerance to prevent padding
|
|
minimum fullness default = 0.9
|
|
|
|
PARM CT x tolerance for two-column operation
|
|
column tolerance default = 0.5
|
|
|
|
PARM DBG x debugging flag
|
|
|
|
TM str message .Tm words prints <pageno> <tab> <words> on stderr
|
|
|
|
MC n o multiple column n columns, offset o.
|
|
Only 1 and 2 columns will work.
|
|
|
|
CMD BP break page force page break
|
|
|
|
CMD FL flush force all queued figures out before any more
|
|
stream material is output
|
|
|
|
CMD FC freeze columns force out current two-column contents;
|
|
start a fresh one
|
|
|
|
Something like this will probably have to be added:
|
|
|
|
NC new column HARD!
|
|
|
|
Known botches in the existing implementation of pm:
|
|
|
|
If a footnote is split across two pages, any associated separator line
|
|
will not be copied. If there are multiple footnotes on one page, there
|
|
will be multiple separators too. -mpm's .FS macro does not provide a
|
|
separator. If you want a separator line, put it in explicitly with
|
|
a call to the .FA macro.
|
|
|
|
There are not enough settable parameters; in particular, the
|
|
way to control the height is a botch.
|
|
|
|
|
|
Historical note: There is a simpler version of pm and -mpm
|
|
called pj and -mpj that only does vertical justification of
|
|
pages that have already been laid out by conventional means.
|
|
This simpler version may be adequate, but it is no longer
|
|
supported and memory of how it works is growing dim.
|