README
1An experiment in page makeup for troff output...
2
3-mpm is a version of standard -ms that causes extra
4information for vertical justification and figure
5placement to be included in troff output. Commands that
6have been augmented to provide paddable space are
7
8 .SH and .NH
9 .PP and .LP no space if \n(PD is 0; normally .nr PD 0.3v; leave at least 1u
10 .IP and .QP also
11 .EQ and .EN
12 .TS and .TE no space if \n(TS is 0; normally .nr TS 0.5v
13 .PS and .PE
14 .P1 and .P2 display programs in CW font
15 .DS and .DE
16 .QS and .QE
17
18Other commands, registers, strings, etc.:
19
20 .SP n explicit paddable space, just like .sp n.
21 generally you should ALWAYS use .SP instead of .sp.
22 if you need exactly a given vertical space, you can say
23 .SP 3i exactly
24 this space won't be padded.
25 .Tm words prints "words" and the output page number on stderr
26 sorry about the spelling; -ms pre-empted .TM
27 .NE n like .ne. note: does not cause a break
28
29 Others may be added as the need arises.
30
31 .nr FO n Set the page length. This value is the bottom of
32 the text on the page; a bottom title may lie below.
33 default is 10i (== 10 inches).
34 %o, %e are strings containing odd and even page titles
35 %# is the current page number (often useless)
36 .PT is a macro invoked at the top of each "page";
37 it will normally use %e, %o and %#. There is also
38 a .BT for page bottoms if desired.
39 .BP force a page break
40 .FL force all waiting figures out before any more running text
41 .1C, .2C multiple columns; number registers CW and GW set
42 the column and gutter width if you don't like the default.
43 absent a .FC command, all two-column contents collect
44 together on the page
45 .FC freeze current two-column contents and start afresh.
46 necessary if you want to switch between 1 and 2 column
47 text and keep the relative order among them.
48
49Usage is some variant of
50
51 ... | troff -mpm
52
53/usr/lib/tmac/pm is the page-justifier itself; it is called automatically
54by the -mpm macro package. If you are installing this yourself, you will
55have to edit the 2nd line of tmac.pm to arrange that pm is called directly
56from troff.
57
58There are several lines in tmac.pm that say
59 .so /n/coma/usr/bwk/...
60You should delete these; they are placeholders for some experiments.
61
62If you use -mm, you are more or less out of luck, although we will be
63happy to provide a crude and incomplete program that purports to convert
64-mm to -ms. It may suggest what you need but it won't do the job.
65
66To compile pm, you need a C++ compiler, preferably release 2.0 or later.
67Put the .c and .h files in a directory, and type
68 make
69This process may well fail. The usual cause is that different systems
70put function declarations in different header files, and C++ insists that
71all functions be properly declared. You can almost always get through this
72part by adding function declarations. The most likely offender is malloc;
73a line like
74 extern char *malloc(int);
75near the top of slug.c will solve this one.
76
77
78Bugs, etc.:
79
80 not all -ms commands have been decorated; in particular,
81 the rich variety of document types (TM, CSTR, etc.,) is not
82 really supported.
83
84 there are problems with funny first pages and troff input
85 that moves back up the page.
86
87 multiple columns: only .2C is available. The program does not check
88 whether something is wide or narrow: user has responsibility to mark
89 which with .1C or .2C.
90
91 headings are a bit tricky if you want things like
92 running titles that include the current section title.
93 normally a two-pass procedure using .Tm is needed.
94
95 It's a pain to force a blank vertical space of specified height.
96 Try this:
97 .de x
98 \v'\\$1'\0\h'-\w'\0'u'\c
99 ..
100 .x 2.5i
101
102
103If you want to roll your own, the following components are
104included in pm's "command language". They are inserted in
105the troff output in the form of "x X ..." commands, which
106are created either by \X'...' or by the .X macro in -mpm.
107Look at how they are used in /usr/lib/tmac/tmac.pm for examples.
108
109
110BS n breakable stream n = min # lines that must appear on page
111 use: PP, LP, IP, ...
112
113US unbreakable stream use: KS/KE, DS/DE, TS/TE, EQ/EN, PS/PE, etc.
114
115BF v breakable float v = preferred vertical location of box center
116 use: FS/FE
117 use two successive BF's to give two preferences
118
119UF v unbreakable float v = preferred vertical location of box center
120 use: KF/KE
121 use two successive UF's to give two preferences
122
123PT page title use: user has absolute control between PT and END
124 no SP's or other pm commands inside are processed
125
126BT bottom title use: user has absolute control between BT and END
127
128END end end a US, BF, UF, PT, or BT
129 all constructs nest, but a float within another float
130 or a US block will not float within or outside the block
131
132NE n need break page if a VBOX of height n would not fit on page
133 use: .NE n
134
135SP n space paddable space of n
136 use: .SP n
137
138PARM NP v top of pm text at v
139 new page
140
141PARM FO v bottom of pm text at v
142 footer length of text on page = FO-NP
143
144PARM PL v physical page ends at v
145 page length default = FO + NP
146
147PARM MF x tolerance to prevent padding
148 minimum fullness default = 0.9
149
150PARM CT x tolerance for two-column operation
151 column tolerance default = 0.5
152
153PARM DBG x debugging flag
154
155TM str message .Tm words prints <pageno> <tab> <words> on stderr
156
157MC n o multiple column n columns, offset o.
158 Only 1 and 2 columns will work.
159
160CMD BP break page force page break
161
162CMD FL flush force all queued figures out before any more
163 stream material is output
164
165CMD FC freeze columns force out current two-column contents;
166 start a fresh one
167
168Something like this will probably have to be added:
169
170NC new column HARD!
171
172Known botches in the existing implementation of pm:
173
174If a footnote is split across two pages, any associated separator line
175will not be copied. If there are multiple footnotes on one page, there
176will be multiple separators too. -mpm's .FS macro does not provide a
177separator. If you want a separator line, put it in explicitly with
178a call to the .FA macro.
179
180There are not enough settable parameters; in particular, the
181way to control the height is a botch.
182
183
184Historical note: There is a simpler version of pm and -mpm
185called pj and -mpj that only does vertical justification of
186pages that have already been laid out by conventional means.
187This simpler version may be adequate, but it is no longer
188supported and memory of how it works is growing dim.
189