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