Return to pm.ms CVS log

Up to [Research Unix] / researchv10dc / vol2 / pm

Annotation of researchv10dc/vol2/pm/pm.ms, revision 1.1

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.