README (6461B)
1 An experiment in page makeup for troff output... 2 3 -mpm is a version of standard -ms that causes extra 4 information for vertical justification and figure 5 placement to be included in troff output. Commands that 6 have 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 18 Other 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 49 Usage is some variant of 50 51 ... | troff -mpm 52 53 /usr/lib/tmac/pm is the page-justifier itself; it is called automatically 54 by the -mpm macro package. If you are installing this yourself, you will 55 have to edit the 2nd line of tmac.pm to arrange that pm is called directly 56 from troff. 57 58 There are several lines in tmac.pm that say 59 .so /n/coma/usr/bwk/... 60 You should delete these; they are placeholders for some experiments. 61 62 If you use -mm, you are more or less out of luck, although we will be 63 happy 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 66 To compile pm, you need a C++ compiler, preferably release 2.0 or later. 67 Put the .c and .h files in a directory, and type 68 make 69 This process may well fail. The usual cause is that different systems 70 put function declarations in different header files, and C++ insists that 71 all functions be properly declared. You can almost always get through this 72 part by adding function declarations. The most likely offender is malloc; 73 a line like 74 extern char *malloc(int); 75 near the top of slug.c will solve this one. 76 77 78 Bugs, 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 103 If you want to roll your own, the following components are 104 included in pm's "command language". They are inserted in 105 the troff output in the form of "x X ..." commands, which 106 are created either by \X'...' or by the .X macro in -mpm. 107 Look at how they are used in /usr/lib/tmac/tmac.pm for examples. 108 109 110 BS n breakable stream n = min # lines that must appear on page 111 use: PP, LP, IP, ... 112 113 US unbreakable stream use: KS/KE, DS/DE, TS/TE, EQ/EN, PS/PE, etc. 114 115 BF 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 119 UF 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 123 PT page title use: user has absolute control between PT and END 124 no SP's or other pm commands inside are processed 125 126 BT bottom title use: user has absolute control between BT and END 127 128 END 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 132 NE n need break page if a VBOX of height n would not fit on page 133 use: .NE n 134 135 SP n space paddable space of n 136 use: .SP n 137 138 PARM NP v top of pm text at v 139 new page 140 141 PARM FO v bottom of pm text at v 142 footer length of text on page = FO-NP 143 144 PARM PL v physical page ends at v 145 page length default = FO + NP 146 147 PARM MF x tolerance to prevent padding 148 minimum fullness default = 0.9 149 150 PARM CT x tolerance for two-column operation 151 column tolerance default = 0.5 152 153 PARM DBG x debugging flag 154 155 TM str message .Tm words prints <pageno> <tab> <words> on stderr 156 157 MC n o multiple column n columns, offset o. 158 Only 1 and 2 columns will work. 159 160 CMD BP break page force page break 161 162 CMD FL flush force all queued figures out before any more 163 stream material is output 164 165 CMD FC freeze columns force out current two-column contents; 166 start a fresh one 167 168 Something like this will probably have to be added: 169 170 NC new column HARD! 171 172 Known botches in the existing implementation of pm: 173 174 If a footnote is split across two pages, any associated separator line 175 will not be copied. If there are multiple footnotes on one page, there 176 will be multiple separators too. -mpm's .FS macro does not provide a 177 separator. If you want a separator line, put it in explicitly with 178 a call to the .FA macro. 179 180 There are not enough settable parameters; in particular, the 181 way to control the height is a botch. 182 183 184 Historical note: There is a simpler version of pm and -mpm 185 called pj and -mpj that only does vertical justification of 186 pages that have already been laid out by conventional means. 187 This simpler version may be adequate, but it is no longer 188 supported and memory of how it works is growing dim.