![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to pm.ms CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [Research Unix] / researchv10dc / vol2 / pm|
Return to pm.ms CVS log | Up to [Research Unix] / researchv10dc / vol2 / pm |
1.1 root 1: .so ../ADM/mac
2: .XX pm 21 "The \f(CW\-mpm\fP Macro Package"
3: .Tm typesetting g
4: .TL
5: The \&\f(CB\-mpm\fP Macro Package
6: .AU
7: Brian W. Kernighan
8: Christopher J. Van Wyk
9: .AI
10: .MH
11: .AB
12: The
13: .CW -mpm
14: macro package is an alternative to the standard
15: .CW -ms
16: macros|reference(latest msmacros) that is designed to produce better page makeup than
17: .CW -ms
18: does.
19: It includes most of the
20: .CW -ms
21: macros, while doing vertical justification and automatic figure placement,
22: and avoiding widows.
23: .AE
24: .2C
25: .NH
26: Executive Summary
27: .EQ
28: delim $$
29: .EN
30: .PP
31: Any document in generic
32: .CW -ms
33: format (not a
34: .CW .TM
35: or a
36: .CW .TR ,
37: for example) is formatted by
38: .P1
39: ... | troff -ms
40: .P2
41: Just by changing this command (and not the document) to
42: .P1
43: ... | troff -mpm
44: .P2
45: the
46: .CW -mpm
47: macro package, which defines most of the same macros as
48: .CW -ms ,
49: automatically invokes a
50: .I troff
51: postprocessor
52: .CW /usr/lib/tmac/pm ) (
53: that produces vertically justified pages
54: according to makeup rules that control figure placement
55: and prevent the creation of widow lines in text.
56: The general approach and algorithms of
57: .I pm
58: are described in |reference(page makeup).
59: .NH
60: Macros
61: .PP
62: The following macros are different from or not part of
63: .CW -ms .
64: Vertical distances denoted by
65: .I n
66: have default value
67: .CW 1v ,
68: i.e., one line.
69: .IP " \f(CW.SP\fP \f2n\fP"
70: .br
71: Add paddable space of height $n$.
72: The key word here is ``paddable'':
73: this space may expand or be removed to aid vertical justification.
74: Spaces produced by
75: .CW .sp
76: (instead of
77: .CW .SP )
78: may or may not appear in the output.
79: .IP " \f(CW.SP\fP \f2n\fP \f(CWexactly\fP"
80: .br
81: Add unpaddable space of height $n$.
82: This space cannot be removed.
83: .IP " \f(CW.KF\fP \f2m\fP"
84: .br
85: Text through a subsequent
86: .CW .KE
87: line defines a ``floating keep,''
88: whose center will be placed as close as possible to
89: vertical position $m$ on the page.
90: If $m$ is omitted,
91: the keep will appear at the top or bottom of a page.
92: The macro recognizes
93: .CW top
94: and
95: .CW bottom
96: as values for $m$.
97: .IP " \f(CW.FL\fP"
98: .br
99: Flush out all queued keeps before producing any more running text
100: (useful when a section or chapter ends).
101: .IP " \f(CW.BP\fP"
102: .br
103: Force a page break.
104: The
105: .I troff
106: command
107: .CW .bp
108: will not cause a page break.
109: .IP " \f(CW.NE\fP \f2n\fP"
110: .br
111: Start a new page if a chunk of output $n$ high would not fit here on the page.
112: .CW .NE
113: does not cause a break.
114: .IP " \f(CW.P1\fP, \f(CW.P2\fP, \f(CW.P3\fP"
115: .br
116: .CW .P1
117: begins a program display (Courier font);
118: .CW .P2
119: ends it;
120: .CW .P3
121: inserts an optional break point in a program display.
122: .IP " \f(CW.Tm\fP \f2any text\fP"
123: .br
124: On the standard error output, print
125: the current page number, a tab, and
126: .I "any text" .
127: The spelling is unusual because
128: .CW -ms
129: pre-empted
130: .CW .TM .
131: .IP " \f(CW.X\fP \f2any text\fP"
132: .br
133: Present
134: .I "any text
135: to the page-makeup program
136: as part of the sequence
137: .CW x
138: .CW X
139: .I "any text
140: (an output-device-dependent line in
141: .I troff
142: output).
143: This is equivalent to the
144: .I troff
145: command
146: .CW \eX'\f2any\ text\fP' .
147: .NH
148: Two-Column Operation
149: .PP
150: The page-makeup program maintains two ``regions''
151: on each page of output\(emone for single-column text
152: that is the full width of the page,
153: and one for two-column text that is about half the width of the page.
154: This convention makes it easy to insert single-column
155: figures into two-column text.
156: If one wishes to alternate single- and two-column output on a page
157: (as some journals alternate two-column text with single-column equations),
158: it is possible to ``freeze'' the contents of the current two-column region,
159: add the result to the single-column region,
160: and start with a fresh two-column region.
161: .PP
162: The following commands are related to two-column operation:
163: .IP " \f(CW.1C\fP
164: .br
165: Subsequent text up to the next
166: .CW .2C
167: command should be added to the single-column region.
168: .IP " \f(CW.2C\fP
169: .br
170: Subsequent text up to the next
171: .CW .1C
172: command should be added to the two-column region.
173: .LP
174: Note that it is the user's responsibility to label text with
175: .CW .1C
176: or
177: .CW .2C ;
178: the page-makeup program does not check whether the text widths make sense.
179: .IP " \f(CW.FC\fP"
180: .br
181: Freeze the current two-column region and start a new (empty) one.
182: .NH
183: Some Useful Number Registers and Strings
184: .PP
185: Table 1 shows some number registers that users may wish to set.
186: The value of register
187: .CW \en(PD
188: should be at least 1u to make vertical justification possible.
189: The value of register
190: .CW \en(TS
191: should be zero for side-by-side tables.
192: .1C
193: .KF
194: .nr PS 9
195: .nr VS 11
196: .ps 9
197: .vs 11
198: .TS
199: center, box;
200: cfI lfI lfI lfI
201: afCW a lfCWw(2i) a.
202: Register Default Used By Purpose
203: =
204: \f(CWPS\f1 10p point size
205: \f(CWVS\f1 12p vertical spacing
206: \f(CWLL\f1 6i line length
207: \f(CWLT\f1 \f(CW\en(LL\f1 title length
208: \f(CWFL\f1 \f(CW\en(LL\f1 footnote length
209: \f(CWCW\f1 7\(mu\f(CW\en(LL\f1/15 column width for two-column output
210: \f(CWGW\f1 \f(CW\en(LL\f1/15 gutter width for two-column output
211: _
212: HM 1i .PT header margin
213: FM 1i .BT footer margin
214: FO 10i vertical position of bottom margin
215: _
216: PO 1i page offset from left margin
217: PI 5n .PP paragraph indent
218: QI 5n .QP,.QS/.QE quotation indent
219: _
220: PD .3v .PP,.LP,.IP,.QP,.QS/.QE inter-paragraph vertical space
221: TS .5v .TS/.TE vertical space around tables
222: Kf .5v .KF/.KE vertical space around fixed keeps
223: Ks .5v .DS/.DE,.IS/.IE,.KS/.KE vertical space around floating keeps
224: _
225: dP 1p .P1/.P2 point-size decrease in programs
226: dT 8 .P1/.P2 spaces per tab stop in programs
227: dV 2p .P1/.P2 vertical-spacing decrease in programs
228: DV .5v .P1/.P2 vertical space around program displays
229: .TE
230: .ce 1
231: .B "Table 1
232: .nr PS 10
233: .nr VS 12
234: .ps 10
235: .vs 12
236: .KE
237: .2C
238: .PP
239: The vertical spacings shown in Table 1 are all paddable.
240: The macros shown in Table 2 produce vertical spacing that
241: cannot be adjusted by the user.
242: .KF bottom
243: .nr PS 9
244: .nr VS 11
245: .ps 9
246: .vs 11
247: .TS
248: center, box;
249: lfI lfI
250: afCW a.
251: Macro Vertical Spacing
252: =
253: \&.EQ .5v
254: \&.EN .5v
255: \&.NH 1v
256: \&.PS .35v
257: \&.PE .65v
258: \&.SH 1v
259: .TE
260: .ce 1
261: .B "Table 2
262: .nr PS 10
263: .nr VS 12
264: .ps 10
265: .vs 12
266: .KE
267: .PP
268: Table 3 shows strings used to produce page headers.
269: The value of
270: .CW \en(%#
271: at most points in the input is unrelated to the number of the page
272: on which that point will appear in the output.
273: .1C
274: .KF
275: .nr PS 9
276: .nr VS 11
277: .ps 9
278: .vs 11
279: .TS
280: center, box;
281: cfI cfI lfI
282: afCW lfCW a.
283: String Used by Purpose
284: =
285: %# .PT\fR,\fP .BT page number
286: %e .PT header for even-numbered pages
287: %o .PT header for odd-numbered pages
288: %E .BT footer for even-numbered pages
289: %O .BT footer for odd-numbered pages
290: .TE
291: .ce 1
292: .B "Table 3
293: .nr PS 10
294: .nr VS 12
295: .ps 10
296: .vs 12
297: .KE
298: .2C
299: .NH
300: Features
301: .PP
302: Warnings appear as comments in the standard output,
303: preceded by
304: .CW "MESSAGE TO USER:" '' ``
305: Common warnings concern pages that were not justified
306: because they were too empty and
307: keeps that had to be split because they were too large.
308: Users can set the
309: .CW WARN
310: parameter to see warnings on the standard error output;
311: see Section 6.
312: .PP
313: The
314: .CW -mpm
315: macro package does not support completely the rich variety of document types
316: (TM, CSTR, etc.,) that
317: .CW -ms
318: does, and does not provide obsolete styles like Engineer's Notes at all.
319: .PP
320: The interaction between
321: .I troff
322: and the page-makeup program produces strange results when
323: .I troff
324: input spaces up the page past paddable space.
325: (See the comment about
326: .CW \en(TS
327: in Section 4.)
328: .CW -mpm
329: issues a warning about ``an embedded SP.''
330: .PP
331: More generally, the ``flyback'' commands in
332: .I pic
333: and
334: .I ideal
335: .CW .PF "" (
336: and
337: .CW .IF ,
338: respectively) do not work with
339: .CW -mpm .
340: One can usually place narrow figures beside narrow text or other narrow figures
341: by setting the pieces in two columns and using the
342: .CW .FC
343: command.
344: .PP
345: The
346: .CW .FS
347: macro in
348: .CW -mpm
349: does not provide a line to separate footnotes from running text.
350: There are two reasons:
351: (1) if multiple footnotes appeared on a page,
352: each would have a separating line;
353: (2) if a footnote split across two pages,
354: no separator line would be provided
355: for the second part of the footnote.
356: Users can add footnote separating lines explicitly by calling the
357: .CW .FA
358: macro.
359: .PP
360: The implementation of multiple columns is incomplete:
361: .CW -mpm
362: provides only
363: .CW .2C .
364: .PP
365: Users who find that the page-makeup program stretches
366: their pages too much can experiment with adjusting the
367: minimum fullness and column tolerance parameters
368: described in Section 6.
369: .PP
370: Headings are a bit tricky if you want things like
371: running titles that include the current section title.
372: Normally you will need a two-pass procedure using
373: .CW .Tm
374: output.
375: On the bright side,
376: this procedure will produce correct headings,
377: where the standard one-pass procedure of resetting headers
378: in the
379: .CW .SH
380: macro can produce incorrect headers on odd-numbered pages.
381: .NH
382: Rolling Your Own
383: .PP
384: If you want to create your own macros that control
385: .I pm ,
386: Table 4 shows the components of
387: .I pm 's
388: ``command language.'' They are inserted into
389: the
390: .I troff
391: output in the form of
392: .CW "x X ..." '' ``
393: commands, created either by
394: .CW \eX'...'
395: or by the
396: .CW .X
397: macro in
398: .CW -mpm .
399: .CW /usr/lib/tmac/tmac.pm
400: contains examples of use.
401: .1C
402: .KF
403: .nr PS 9
404: .nr VS 11
405: .ps 9
406: .vs 11
407: .TS
408: center, box;
409: lfI lfI lfI lfI
410: lfCW l lw(2.75i) lfCWw(.55i).
411: Command Name Description Used by
412: =
413: SP $n$ space T{
414: Paddable space of $n$
415: T} .SP
416: BS $n$ breakable stream T{
417: $n ~=$ minimum number of lines from the stream that must appear on page
418: T} T{
419: \&.PP,.LP,
420: \&.IP,.QP
421: T}
422: US unbreakable stream T{
423: An \f(CWEND\fP-terminated item that cannot float or be broken
424: T} T{
425: \&.DS,\&.EQ,\&.IS,
426: \&.KS,\&.TS,\&.PS
427: T}
428: BF $v$ breakable float T{
429: An \f(CWEND\fP-terminated item that can float or be broken;
430: $v$ = preferred vertical location of box center;
431: two successive commands give two preferences
432: T} .FS
433: UF $v$ unbreakable float T{
434: An \f(CWEND\fP-terminated item that can float but cannot be broken;
435: $v$ = preferred vertical location of box center;
436: two successive commands give two preferences
437: T} .KF
438: PT page title T{
439: User has absolute control between PT and END;
440: no SP's or other
441: .I pm
442: commands inside are processed.
443: T} .PT
444: BT bottom title T{
445: User has absolute control between BT and END, as for PT.
446: T} .BT
447: END end T{
448: End a US, BF, UF, PT, or BT.
449: All constructs nest, but a float within another float
450: or US will not float within or outside the block.
451: T} T{
452: \&.DE,\&.EN,\&.FE,
453: \&.IE,\&.KE,\&.TE,
454: \&.PE
455: T}
456: TM $str$ message T{
457: Print the page number, a tab, and $str$ on standard error output.
458: T} .Tm
459: COORD $str$ output coordinates T{
460: Print $str$ with current page number and output $x$ and $y$ coordinates.
461: T}
462: NE $n$ need T{
463: Break page if a VBOX of height $n$ would not fit on page
464: T} .NE,.SH,.NH
465: MC $n$ $o$ multiple column T{
466: $n$ columns, $i$th offset from first by $o(i-1)$.
467: Only 1 and 2 columns work.
468: T} .1C,.2C
469: CMD FC freeze columns T{
470: Force out current two-column contents;
471: start a fresh one.
472: T} .FC
473: CMD FL flush T{
474: Force all queued figures out before any more
475: stream material is output.
476: T} .FL
477: CMD BP break page T{
478: Force page break.
479: T} .BP
480: PARM NP $v$ new page T{
481: Top of
482: .I pm
483: text at vertical position $v$.
484: T}
485: PARM FO $v$ footer T{
486: Bottom of
487: .I pm
488: text at vertical position $v$;
489: length of text on page = FO\ \-\ NP.
490: T}
491: PARM PL $v$ page length T{
492: Physical page ends at $v$;
493: default = FO + NP.
494: T}
495: PARM MF $x$ minimum fullness T{
496: Tolerance to prevent padding;
497: default = 90.
498: A page that is less than $x$% full will not be padded.
499: T}
500: PARM CT $x$ column tolerance T{
501: Tolerance for two-column operation;
502: default = 50.
503: Values larger than 50% will generally cause more text
504: to be included in the first column.
505: T}
506: PARM WARN $x$ warning flag T{
507: Print warnings on standard error output if $x != 0$.
508: T}
509: .TE
510: .ce 1
511: .B "Table 4
512: .nr PS 10
513: .nr VS 12
514: .ps 10
515: .vs 12
516: .KE
517: .2C
518: .NH
519: References
520: .LP
521: |reference_placement
522: .ig
523: ``Page Makeup by Postprocessing Text Formatter Output,''
524: Brian W. Kernighan and Christopher J. Van Wyk,
525: .I "Computing Systems,
526: $bold "2"$, 2, Spring 1989, pp 103-132.
527: ..
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.