/contrib/groff/tmac/groff_ms.man

   1'\" t
   2.ig
   3Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2005
   4  Free Software Foundation, Inc.
   5
   6Permission is granted to make and distribute verbatim copies of
   7this manual provided the copyright notice and this permission notice
   8are preserved on all copies.
   9
  10Permission is granted to copy and distribute modified versions of this
  11manual under the conditions for verbatim copying, provided that the
  12entire resulting derived work is distributed under the terms of a
  13permission notice identical to this one.
  14
  15Permission is granted to copy and distribute translations of this
  16manual into another language, under the above conditions for modified
  17versions, except that this permission notice may be included in
  18translations approved by the Free Software Foundation instead of in
  19the original English.
  20..
  21.
  22.do nr groff_ms_C \n[.C]
  23.cp 0
  24.
  25.TH GROFF_MS @MAN7EXT@ "@MDATE@" "Groff Version @VERSION@"
  26.
  27.
  28.
  29.SH NAME
  30.
  31groff_ms \- groff ms macros
  32.
  33.
  34.
  35.SH SYNOPSIS
  36.
  37.B groff
  38.B \-ms
  39[
  40.IR options .\|.\|.\&
  41]
  42[
  43.IR files .\|.\|.\&
  44]
  45.br
  46.B groff
  47.B \-m\ ms
  48[
  49.IR options .\|.\|.\&
  50]
  51[
  52.IR files .\|.\|.\&
  53]
  54.
  55.
  56.
  57.SH DESCRIPTION
  58.
  59This manual page describes the GNU version of the
  60.I ms
  61macros,
  62part of the
  63.I groff
  64typesetting system.
  65The
  66.I ms
  67macros are mostly compatible with the
  68documented behavior of the 4.3
  69.SM BSD
  70Unix
  71.I ms
  72macros (see
  73.I Differences from troff ms
  74below for details).
  75The
  76.I ms
  77macros are suitable for reports, letters, books, and
  78technical documentation.
  79.
  80.
  81.
  82.SH USAGE
  83.
  84The
  85.I ms
  86macro package expects files to have
  87a certain amount of structure.
  88The simplest documents can begin with a paragraph macro
  89and consist of text separated by paragraph macros
  90or even blank lines.
  91Longer documents have a structure as follows:
  92.
  93.TP
  94.B "Document type"
  95If you use the
  96.B RP
  97(report) macro at the beginning of the document,
  98.I groff
  99prints the cover page information on its own page;
 100otherwise it prints the information on the
 101first page with your document text immediately following.
 102Other document formats found in AT&T
 103.I troff
 104are specific to AT&T
 105or Berkeley, and are not supported in
 106.IR "groff ms" .
 107.
 108.TP
 109.B "Format and layout"
 110By setting number registers,
 111you can change your document's type (font and size),
 112margins, spacing, headers and footers, and footnotes.
 113See 
 114.I "Document control registers"
 115below for more details.
 116.
 117.TP
 118.B "Cover page"
 119A cover page consists of a title,
 120and optionally the author's name and institution,
 121an abstract, and the date.
 122See
 123.I "Cover page macros"
 124below for more details.
 125.
 126.TP
 127.B "Body"
 128Following the cover page is your document.
 129It consists of paragraphs, headings, and lists.
 130.
 131.TP
 132.B "Table of contents"
 133Longer documents usually include a table of contents,
 134which you can add by placing the
 135.B TC
 136macro at the end of your document.
 137.
 138.
 139.SS "Document control registers"
 140.
 141The following table lists the document control
 142number registers.
 143For the sake of consistency,
 144set registers related to margins at the beginning of your document,
 145or just after the
 146.B RP
 147macro.
 148.
 149.LP
 150.ne 12
 151.B Margin settings
 152.RS
 153.na
 154.TS
 155cb   s cb s s cb s cb s
 156afCW s l  s s l  s l  s.
 157Reg.	Definition	Effective	Default
 158_
 159PO	T{
 160Page offset (left margin)
 161T}	T{
 162next page
 163T}	1i
 164LL	T{
 165Line length
 166T}	next para.	6i
 167LT	T{
 168Header/footer length
 169T}	next para.	6i
 170HM	T{
 171Top (header) margin
 172T}	next page	1i
 173FM	T{
 174Bottom (footer) margin
 175T}	next page	1i
 176_
 177.TE
 178.RE
 179.
 180.LP
 181.ne 12
 182.B Text settings
 183.RS
 184.TS
 185cb   s cb s s cb s cb s
 186afCW s l  s s l  s l  s.
 187Reg.	Definition	Effective	Default
 188_
 189PS	T{
 190Point size
 191T}	next para.	10p
 192VS	T{
 193Line spacing (leading)
 194T}	next para.	12p
 195PSINCR	T{
 196Point size increment
 197for section headings of
 198increasing importance
 199T}	next heading	1p
 200GROWPS	T{
 201Heading level
 202beyond which PSINCR
 203is ignored
 204T}	next heading	0
 205_
 206.TE
 207.RE
 208.
 209.LP
 210.ne 11
 211.B Paragraph settings
 212.RS
 213.TS
 214cb cb s cb cb
 215afCW l s l l .
 216Reg.	Definition	Effective	Default
 217_
 218PI	T{
 219Initial indent
 220T}	next para.	5n
 221PD	T{
 222Space between paragraphs
 223T}	next para.	0.3v
 224QI	T{
 225Quoted paragraph indent
 226T}	next para.	5n
 227PORPHANS	T{
 228Number of initial lines
 229to be kept together
 230T}	next para.	1
 231HORPHANS	T{
 232Number of initial lines
 233to be kept with heading
 234T}	next heading	1
 235_
 236.TE
 237.RE
 238.
 239.LP
 240.ne 7
 241.B Footnote settings
 242.RS
 243.TS
 244cb cb cb cb
 245afCW l l l .
 246Reg.	Definition	Effective	Default
 247_
 248FL	Footnote length	next footnote	\[rs]n[LL]*5/6
 249FI	Footnote indent	next footnote	2n
 250FF	Footnote format	next footnote	0
 251FPS	Point size	next footnote	\[rs]n[PS]-2
 252FVS	Vert. spacing	next footnote	\[rs]n[FPS]+2
 253FPD	Para. spacing	next footnote	\[rs]n[PD]/2
 254_
 255.TE
 256.RE
 257.
 258.LP
 259.ne 6
 260.B Other settings
 261.RS
 262.TS
 263cb   s cb s s cb s cb s
 264afCW s l  s s l  s l  s.
 265Reg.	Definition	Effective	Default
 266_
 267MINGW	T{
 268Minimum width between columns
 269T}	next page	2n
 270_
 271.TE
 272.ad
 273.RE
 274.
 275.
 276.SS "Cover page macros"
 277.
 278Use the following macros to create a cover page for your document
 279in the order shown.
 280.
 281.TP
 282.B .RP [no]
 283Specifies the report format for your document.
 284The report format creates a separate cover page.
 285With no
 286.B RP
 287macro,
 288.I groff
 289prints a subset of the
 290cover page on page\~1 of your document.
 291.
 292.IP
 293If you use the optional
 294.B no
 295argument,
 296.I groff
 297prints a title page but
 298does not repeat any of the title page information
 299(title, author, abstract, etc.\&)
 300on page\~1 of the document.
 301.
 302.TP
 303.B .P1 
 304(P-one) Prints the header on page\~1.
 305The default is to suppress the header.
 306.
 307.TP
 308.BI ".DA [" xxx ]
 309(optional) Print the current date,
 310or the arguments to the macro if any,
 311on the title page (if specified)
 312and in the footers.
 313This is the default for
 314.IR nroff .
 315.
 316.TP
 317.BI ".ND [" xxx ]
 318(optional) Print the current date,
 319or the arguments to the macro if any,
 320on the title page (if specified)
 321but not in the footers.
 322This is the default for
 323.IR troff .
 324.
 325.TP
 326.B .TL
 327Specifies the document title.
 328.I Groff
 329collects text following the
 330.B TL
 331macro into the title, until reaching the author name or abstract.
 332.
 333.TP
 334.B .AU
 335Specifies the author's name.
 336You can specify multiple authors by using an
 337.B AU
 338macro for each author.
 339.
 340.TP
 341.B .AI
 342Specifies the author's institution.
 343You can specify multiple institutions.
 344.
 345.TP
 346.B .AB [no]
 347Begins the abstract.
 348The default is to print the word
 349.BR ABSTRACT ,
 350centered and in italics, above the text of the abstract.
 351The option
 352.B no
 353suppresses this heading.
 354.
 355.TP
 356.B .AE
 357End the abstract.
 358.
 359.
 360.SS Paragraphs
 361.
 362Use the
 363.B PP
 364macro to create indented paragraphs,
 365and the
 366.B LP
 367macro to create paragraphs with no initial indent.
 368.
 369.PP
 370The
 371.B QP
 372macro indents all text at both left and right margins.
 373The effect is identical to the HTML
 374.B <BLOCKQUOTE>
 375element.
 376The next paragraph or heading
 377returns margins to normal.
 378.
 379.PP
 380The
 381.B XP
 382macro produces an exdented paragraph.
 383The first line of the paragraph begins at
 384the left margin,
 385and subsequent lines are indented
 386(the opposite of
 387.BR PP ).
 388.
 389.PP
 390For each of the above paragraph types,
 391and also for any list entry introduced by the
 392.B IP
 393macro
 394(described later),
 395the document control register
 396.BR PORPHANS ,
 397sets the
 398.I minimum
 399number of lines which must be printed,
 400after the start of the paragraph,
 401and before any page break occurs.
 402If there is insufficient space remaining on the current page
 403to accommodate this number of lines,
 404then a page break is forced
 405.I before
 406the first line of the paragraph is printed.
 407.
 408.PP
 409Similarly,
 410when a section heading
 411(see subsection
 412.I Headings
 413below)
 414preceeds any of these paragraph types,
 415the
 416.B HORPHANS
 417document control register specifies the
 418.I minimum
 419number of lines of the paragraph
 420which must be kept on the same page as the heading.
 421If insufficient space remains on the current page
 422to accommodate the heading and this number of lines of paragraph text,
 423then a page break is forced
 424.I before
 425the heading is printed.
 426.
 427.
 428.SS Headings
 429.
 430Use headings to create a hierarchical structure
 431for your document.
 432By default,
 433the
 434.I ms
 435macros print headings in
 436.B bold
 437using the same font family and point size as the body text.
 438For output devices which support scalable fonts,
 439this behaviour may be modified,
 440by defining the document control registers,
 441.B GROWPS
 442and
 443.BR PSINCR .
 444.
 445.PP
 446The following heading macros are available:
 447.
 448.TP
 449.BI .NH\  xx
 450Numbered heading.
 451The argument
 452.I xx
 453is either a numeric argument to indicate the
 454level of the heading, or
 455.I S\ xx\ xx\ \c
 456".\|.\|."
 457to set the section number explicitly.
 458If you specify heading levels out of sequence,
 459such as invoking
 460.B ".NH\ 3"
 461after
 462.BR ".NH\ 1" ,
 463.I groff
 464prints a warning on standard error.
 465.
 466.IP
 467If the
 468.B GROWPS
 469register is set to a value
 470greater than the level of the heading,
 471then the point size of the heading will be increased by
 472.B PSINCR
 473units over the text size specified by the
 474.B PS
 475register,
 476for each level by which the heading level is less than
 477the value of
 478.BR GROWPS .
 479For example,
 480the sequence:
 481.
 482.RS
 483.ne 12
 484.nf
 485.IP
 486\&.nr PS 10
 487\&.nr GROWPS 3
 488\&.nr PSINCR 1.5p
 489\&.
 490\&.NH 1
 491Top Level Heading
 492\&.
 493\&.NH 2
 494Second Level Heading
 495\&.
 496\&.NH 3
 497Third Level Heading
 498.fi
 499.RE
 500.
 501.IP
 502will cause
 503.RI \*(lq 1.\ Top\ Level\ Heading \*(rq
 504to be printed in 13pt
 505.B bold
 506text, followed by
 507.RI \*(lq 1.1.\ Second\ Level\ Heading \*(rq
 508in 11.5pt
 509.B bold
 510text, while
 511.RI \*(lq 1.1.1.\ Third\ Level\ Heading \*(rq,
 512and all more deeply nested heading levels,
 513will remain in the 10pt
 514.B bold
 515text which is specified by the
 516.B PS
 517register.
 518.
 519.IP
 520Note that the value stored in
 521.B PSINCR
 522is interpreted in
 523.I groff
 524basic units;
 525the
 526.I p
 527scaling factor should be employed,
 528when assigning a value specified in points.
 529.
 530.IP
 531After invoking
 532.BR .NH ,
 533the assigned heading number is available in the strings
 534.B SN-DOT
 535(exactly as it appears in the formatted heading),
 536and
 537.B SN-NO-DOT
 538(with its final period omitted).
 539The string
 540.B SN
 541is also defined,
 542as an alias for
 543.BR SN-DOT ;
 544if preferred,
 545the user may redefine it as an alias for
 546.BR SN-NO-DOT ,
 547'ne 10
 548by including the initialisation:
 549.
 550.RS
 551.nf
 552.IP
 553\&.ds SN-NO-DOT
 554\&.als SN SN-NO-DOT
 555.fi
 556.RE
 557.
 558.IP
 559.I before
 560the first use of
 561.BR .NH ,
 562or simply:
 563.
 564.RS
 565.nf
 566.IP
 567\&.als SN SN-NO-DOT
 568.fi
 569.RE
 570.
 571.IP
 572.I after
 573the first use of
 574.BR .NH .
 575.
 576.TP
 577.BI .SH\ [ xx ]
 578Unnumbered subheading.
 579The use of the optional
 580.I xx
 581argument is a GNU extension,
 582which adjusts the point size of the unnumbered subheading
 583to match that of a numbered heading,
 584introduced using
 585.BI .NH\  xx
 586with the same value of
 587.IR xx .
 588For example,
 589given the same settings for
 590.BR PS ,
 591.B GROWPS
 592and
 593.BR PSINCR ,
 594as used in the preceeding
 595.B .NH
 596example,
 597the sequence:
 598.
 599.RS
 600.ne
 601.nf
 602.IP
 603\&.SH 2
 604An Unnumbered Subheading
 605.fi
 606.RE
 607.
 608.IP
 609will print
 610.RI \*(lq "An Unnumbered Subheading" \*(rq
 611in 11.5pt
 612.B bold
 613text.
 614.
 615.
 616.SS Highlighting
 617.
 618The
 619.I ms
 620macros provide a variety of methods to highlight
 621or emphasize text:
 622.
 623.TP
 624.B ".B [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
 625Sets its first argument in
 626.BR "bold type" .
 627If you specify a second argument,
 628.I groff
 629prints it in the previous font after
 630the bold text, with no intervening space
 631(this allows you to set punctuation after
 632the highlighted text without highlighting
 633the punctuation).
 634Similarly, it prints the third argument (if any)
 635in the previous font
 636.B before
 637the first argument.
 638For example,
 639.RS
 640.
 641.IP
 642\&.B foo ) (
 643.RE
 644.
 645.IP
 646prints
 647.RB ( foo ).
 648.
 649.IP
 650If you give this macro no arguments,
 651.I groff
 652prints all text following in bold until
 653the next highlighting, paragraph, or heading macro.
 654.
 655.TP
 656.B ".R [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
 657Sets its first argument in
 658roman (or regular) type.
 659It operates similarly to the
 660.B B
 661macro otherwise.
 662.
 663.TP
 664.B ".I [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
 665Sets its first argument in
 666.IR "italic type" .
 667It operates similarly to the
 668.B B
 669macro otherwise.
 670.
 671.TP
 672.B ".CW [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
 673Sets its first argument in a constant width face.
 674It operates similarly to the
 675.B B
 676macro otherwise.
 677.
 678.TP
 679.B ".BI [\fItxt\fP [\fIpost\fP [\fIpre\fP]]]"
 680Sets its first argument in bold italic type.
 681It operates similarly to the
 682.B B
 683macro otherwise.
 684.
 685.TP
 686.BI ".BX [" txt ]
 687Prints its argument and draws a box around it.
 688If you want to box a string that contains spaces,
 689use a digit-width space (\[rs]0).
 690.
 691.TP
 692.BI ".UL [" txt " [" post ]]
 693Prints its first argument with an underline.
 694If you specify a second argument,
 695.I groff
 696prints it in the previous font after
 697the underlined text, with no intervening space.
 698.
 699.TP
 700.B .LG
 701Prints all text following in larger type
 702(2\~points larger than the current point size) until
 703the next font size, highlighting, paragraph, or heading macro.
 704You can specify this macro multiple times
 705to enlarge the point size as needed.
 706.
 707.TP
 708.B .SM
 709Prints all text following in
 710smaller type
 711(2\~points smaller than the current point size) until
 712the next type size, highlighting, paragraph, or heading macro.
 713You can specify this macro multiple times
 714to reduce the point size as needed.
 715.
 716.TP
 717.B .NL
 718Prints all text following in
 719the normal point size
 720(that is, the value of the
 721.B PS
 722register).
 723.
 724.TP
 725.BI \[rs]*{ text \[rs]*}
 726Print the enclosed
 727.I text
 728as a superscript.
 729.
 730.
 731.SS Indents
 732.
 733You may need to indent sections of text.
 734A typical use for indents is to create nested lists and sublists.
 735.
 736.PP
 737Use the
 738.B RS
 739and
 740.B RE
 741macros to start and end a section of indented text, respectively.
 742The
 743.B PI
 744register controls the amount of indent.
 745.
 746.PP
 747You can nest indented sections as deeply as needed by
 748using multiple, nested pairs of
 749.B RS
 750and
 751.BR RE .
 752.
 753.
 754.SS Lists
 755.
 756The
 757.B IP
 758macro handles duties for all lists.
 759Its syntax is as follows:
 760.
 761.TP
 762.BI ".IP [" marker " [" width ]]
 763.
 764.IP
 765The
 766.I marker
 767is usually a bullet character
 768.B \[rs](bu
 769for unordered lists,
 770a number (or auto-incrementing number register) for numbered lists,
 771or a word or phrase for indented (glossary-style) lists.
 772.
 773.IP
 774The
 775.I width
 776specifies the indent for the body of each list item.
 777Once specified, the indent remains the same for all
 778list items in the document until specified again.
 779.\" -----
 780.br
 781.ne 15
 782.
 783.
 784.SS "Tab stops"
 785.
 786Use the
 787.B ta
 788request to set tab stops as needed.
 789Use the
 790.B TA
 791macro to reset tabs to the default (every 5n).
 792You can redefine the
 793.B TA
 794macro to create a different set of default tab stops.
 795.
 796.
 797.SS "Displays and keeps"
 798.
 799Use displays to show text-based examples or figures
 800(such as code listings).
 801Displays turn off filling, so lines of code can be
 802displayed as-is without inserting
 803.B br
 804requests in between each line.
 805Displays can be 
 806.I kept
 807on a single page, or allowed to break across pages.
 808The following table shows the display types available.
 809.RS
 810.ne 11
 811.na
 812.TS
 813cb   s s    s cbt s s
 814cb   s cb   s ^   s s
 815lfCW s lfCW s l   s s.
 816Display macro	Type of display
 817With keep	No keep
 818_
 819\&.DS L	\&.LD	Left-justified.
 820\&.DS I [\fIindent\fP]	\&.ID	T{
 821Indented (default indent in the \fBDI\fP register).
 822T}
 823\&.DS B	\&.BD	T{
 824Block-centered (left-justified, longest line centered).
 825T}
 826\&.DS C	\&.CD	Centered.
 827\&.DS R	\&.RD	Right-justified.
 828_
 829.TE
 830.RE
 831.ad
 832.
 833.LP
 834Use the
 835.B DE
 836macro to end any display type.
 837The macros
 838.B Ds
 839and
 840.B De
 841were formerly provided as aliases for
 842.B DS
 843and
 844.BR DE ,
 845respectively, but they have been removed, and should no longer be used.
 846X11 documents which actually use
 847.B Ds
 848and
 849.B De
 850always load a specific macro file from the X11 distribution (macros.t)
 851which provides proper definitions for the two macros.
 852.PP
 853To
 854.I keep
 855text together on a page,
 856such as
 857a paragraph that refers to a table (or list, or other item)
 858immediately following, use the
 859.B KS
 860and
 861.B KE
 862macros.
 863The
 864.B KS
 865macro begins a block of text to be kept on a single page,
 866and the
 867.B KE
 868macro ends the block.
 869.
 870.PP
 871You can specify a
 872.I "floating keep"
 873using the
 874.B KF
 875and
 876.B KE
 877macros.
 878If the keep cannot fit on the current page,
 879.I groff
 880holds the contents of the keep and allows text following
 881the keep (in the source file) to fill in the remainder of
 882the current page.
 883When the page breaks,
 884whether by an explicit
 885.B bp
 886request or by reaching the end of the page,
 887.I groff
 888prints the floating keep at the top of the new page.
 889This is useful for printing large graphics or tables
 890that do not need to appear exactly where specified.
 891.
 892.PP
 893The macros
 894.B B1
 895and
 896.B B2
 897can be used to enclose a text within a box;
 898.B .B1
 899begins the box, and
 900.B .B2
 901ends it.
 902Text in the box is automatically placed in a diversion
 903(keep).
 904.
 905.
 906.SS "Tables, figures, equations, and references"
 907.
 908The
 909.I -ms
 910macros support the standard
 911.I groff
 912preprocessors:
 913.IR tbl ,
 914.IR pic ,
 915.IR eqn ,
 916and
 917.IR refer .
 918Mark text meant for preprocessors by enclosing it
 919in pairs of tags as follows:
 920.
 921.TP
 922.BR ".TS [H]" " and " .TE
 923Denotes a table, to be processed by the
 924.I tbl
 925preprocessor.
 926The optional
 927.BR H "\~argument"
 928instructs
 929.I groff
 930to create a running header with the information
 931up to the
 932.B TH
 933macro.
 934.I Groff
 935prints the header at the beginning of the table;
 936if the table runs onto another page,
 937.I groff
 938prints the header on the next page as well.
 939.
 940.TP
 941.BR .PS " and " .PE
 942Denotes a graphic, to be processed by the
 943.I pic
 944preprocessor.
 945You can create a
 946.I pic
 947file by hand, using the
 948AT&T
 949.I pic
 950manual available on the Web as a reference,
 951or by using a graphics program such as
 952.IR xfig .
 953.
 954.TP
 955.BR ".EQ [\fI\,align\/\fP]" " and " .EN
 956Denotes an equation, to be processed by the
 957.I eqn
 958preprocessor.
 959The optional
 960.I align
 961argument can be
 962.BR C ,
 963.BR L ,
 964or\~\c
 965.B I
 966to center (the default), left-justify, or indent
 967the equation.
 968.
 969.TP
 970.BR .[ " and " .]
 971Denotes a reference, to be processed by the
 972.I refer
 973preprocessor.
 974The GNU
 975.IR @g@refer (@MAN1EXT@)
 976manual page provides a comprehensive reference
 977to the preprocessor and the format of the
 978bibliographic database.
 979.
 980.
 981.SS Footnotes
 982.
 983The
 984.I ms
 985macros provide a flexible footnote system.
 986You can specify a numbered footnote by using the
 987.B \[rs]**
 988escape, followed by the text of the footnote
 989enclosed by
 990.B FS
 991and
 992.B FE
 993macros.
 994.
 995.PP
 996You can specify symbolic footnotes
 997by placing the mark character (such as
 998.B \[rs](dg
 999for the dagger character) in the body text,
1000followed by the text of the footnote
1001enclosed by
1002.B FS\ \[rs](dg
1003and
1004.B FE
1005macros.
1006.
1007.PP
1008You can control how
1009.I groff
1010prints footnote numbers by changing the value of the
1011.B FF
1012register as follows:
1013.RS
1014.ne 7
1015.
1016.TP
10170
1018Prints the footnote number as a superscript; indents the footnote (default).
1019.
1020.TP
10211
1022Prints the number followed by a period (like\~1.\&)
1023and indents the footnote.
1024.
1025.TP
10262
1027Like\~1, without an indent.
1028.
1029.TP
10303
1031Like\~1, but prints the footnote number as a hanging paragraph.
1032.
1033.LP
1034.RE
1035You can use footnotes safely within keeps and displays,
1036but avoid using numbered footnotes within floating keeps.
1037You can set a second
1038.B \[rs]**
1039between a
1040.B \[rs]**
1041and its corresponding
1042.BR .FS ;
1043as long as each
1044.B .FS
1045occurs
1046.I after
1047the corresponding
1048.B \[rs]**
1049and the occurrences of
1050.B .FS
1051are in the same order as the corresponding occurrences of
1052.BR \[rs]** .
1053.
1054.
1055.SS "Headers and footers"
1056.
1057There are two ways to define headers and footers:
1058.
1059.IP \(bu 3n
1060Use the strings
1061.BR LH ,
1062.BR CH ,
1063and
1064.B RH
1065to set the left, center, and right headers; use
1066.BR LF ,
1067.BR CF ,
1068and
1069.B RF
1070to set the left, center, and right footers.
1071This works best for documents that do not distinguish
1072between odd and even pages.
1073.
1074.IP \(bu
1075Use the
1076.B OH
1077and
1078.B EH
1079macros to define headers for the odd and even pages; and
1080.B OF
1081and
1082.B EF
1083macros to define footers for the odd and even pages.
1084This is more flexible than defining the individual strings.
1085The syntax for these macros is as follows:
1086.RS
1087.
1088.IP
1089.B ".OH '\fIleft\fP'\fIcenter\fP'\fIright\fP'"
1090.RE
1091.
1092.IP
1093You can replace the quote (') marks with any character not
1094appearing in the header or footer text.
1095.
1096.
1097.SS Margins
1098.
1099You control margins using a set of number registers.
1100The following table lists the register names and defaults:
1101.RS
1102.ne 8
1103.na
1104.TS
1105cb   s cb s s cb s cb s
1106afCW s l  s s l  s l  s.
1107Reg.	Definition	Effective	Default
1108_
1109PO	T{
1110Page offset (left margin)
1111T}	next page	1i
1112LL	T{
1113Line length
1114T}	next para.	6i
1115LT	T{
1116Header/footer length
1117T}	next para.	6i
1118HM	T{
1119Top (header) margin
1120T}	next page	1i
1121FM	T{
1122Bottom (footer) margin
1123T}	next page	1i
1124_
1125.TE
1126.RE
1127.ad
1128.
1129.PP
1130Note that there is no right margin setting.
1131The combination of page offset and line length
1132provide the information necessary to
1133derive the right margin.
1134.
1135.
1136.SS "Multiple columns"
1137.
1138The
1139.I ms
1140macros can set text in as many columns as will reasonably
1141fit on the page.
1142The following macros are available.
1143All of them force a page break if a multi-column mode is already set.
1144However, if the current mode is single-column, starting a multi-column
1145mode does
1146.I not
1147force a page break.
1148.
1149.TP
1150.B .1C
1151Single-column mode.
1152.
1153.TP
1154.B .2C
1155Two-column mode.
1156.
1157.TP
1158.BI ".MC [" width " [" gutter ]]
1159Multi-column mode.
1160If you specify no arguments, it is equivalent to the
1161.B 2C
1162macro.
1163Otherwise,
1164.I width
1165is the width of each column and
1166.I gutter
1167is the space between columns.
1168The
1169.B MINGW
1170number register is the default gutter width.
1171.
1172.
1173.SS "Creating a table of contents"
1174.
1175Wrap text that you want to appear in the
1176table of contents in
1177.B XS
1178and
1179.B XE
1180macros.
1181Use the
1182.B TC
1183macro to print the table of contents at the end of the document,
1184resetting the page number to\~\c
1185.B i
1186(Roman numeral\~1).
1187.
1188.PP
1189You can manually create a table of contents
1190by specifying a page number as the first argument to
1191.BR XS .
1192Add subsequent entries using the
1193.B XA
1194macro.
1195For example:
1196.RS
1197.
1198.PP
1199.ne 8
1200.nf
1201\&.XS 1
1202Introduction
1203\&.XA 2
1204A Brief History of the Universe
1205\&.XA 729
1206Details of Galactic Formation
1207\&.\|.\|.
1208\&.XE
1209.fi
1210.RE  
1211.
1212.LP  
1213Use the
1214.B PX  
1215macro to print a manually-generated table of contents
1216without resetting the page number.
1217.
1218.PP
1219If you give the argument
1220.B no
1221to either
1222.B PX
1223or   
1224.BR TC ,
1225.I groff
1226suppresses printing the title
1227specified by the
1228.B \[rs]*[TOC]  
1229string.
1230.
1231.
1232.SS "Fractional point sizes"
1233.
1234Traditionally, the
1235.I ms
1236macros only support integer values for the document's font size and
1237vertical spacing.
1238To overcome this restriction, values larger than or equal to 1000 are taken
1239as fractional values, multiplied by 1000.
1240For example, `.nr\~PS\~10250' sets the font size to 10.25 points.
1241.
1242.LP
1243The following four registers accept fractional point sizes:
1244.BR PS ,
1245.BR VS ,
1246.BR FPS ,
1247and
1248.BR FVS .
1249.
1250.LP
1251Due to backwards compatibility, the value of
1252.B VS
1253must be smaller than 40000 (this is 40.0 points).
1254.
1255.
1256.
1257.SH "DIFFERENCES FROM troff ms"
1258.
1259The
1260.I "groff ms"
1261macros are a complete re-implementation,
1262using no original AT&T code.
1263Since they take advantage of the extended features in
1264.IR groff ,
1265they cannot be used with AT&T
1266.IR troff .
1267Other differences include:
1268.
1269.IP \(bu 3n
1270The internals of
1271.I "groff ms"
1272differ from the internals of Unix
1273.IR ms . 
1274Documents that depend upon implementation details of Unix
1275.I ms
1276may not format properly with
1277.IR "groff ms" .
1278.
1279.IP \(bu
1280The error-handling policy of
1281.I "groff ms"
1282is to detect and report errors,
1283rather than silently to ignore them.
1284.
1285.IP \(bu
1286Bell Labs localisms are not implemented.
1287.
1288.IP \(bu
1289Berkeley localisms, in particular the
1290.B TM
1291and
1292.B CT
1293macros,
1294are not implemented.
1295.
1296.IP \(bu
1297.I "Groff ms"
1298does not work in compatibility mode (e.g., with the
1299.B \-C
1300option).
1301.
1302.IP \(bu
1303There is no support for typewriter-like devices.
1304.
1305.IP \(bu
1306.I "Groff ms"
1307does not provide cut marks.
1308.
1309.IP \(bu
1310Multiple line spacing is not supported
1311(use a larger vertical spacing instead).
1312.
1313.IP \(bu
1314Some Unix
1315.I ms
1316documentation says that the
1317.B CW
1318and
1319.B GW
1320number registers can be used to control the column width and
1321gutter width, respectively.
1322These number registers are not used in
1323.IR "groff ms" .
1324.
1325.IP \(bu
1326Macros that cause a reset
1327(paragraphs, headings, etc.\&)
1328may change the indent.
1329Macros that change the indent do not increment or decrement
1330the indent, but rather set it absolutely.
1331This can cause problems for documents that define
1332additional macros of their own.
1333The solution is to use not the
1334.B in
1335request but instead the
1336.B RS
1337and
1338.B RE
1339macros.
1340.
1341.IP \(bu
1342The number register
1343.B GS
1344is set to\~1 by the
1345.I "groff ms"
1346macros,
1347but is not used by the Unix
1348.I ms
1349macros.
1350Documents that need to determine whether
1351they are being formatted with Unix
1352.I ms
1353or
1354.I "groff ms"
1355should use this number register.
1356.
1357.IP \(bu
1358To make
1359.I "groff ms"
1360use the default page offset (which also specifies the left margin),
1361the
1362.B PO
1363number register must stay undefined until the first
1364.B ms
1365macro is evaluated.
1366This implies that
1367.B PO
1368should not be used early in the document, unless it is changed also:
1369Remember that accessing an undefined register automatically defines it.
1370.br
1371.ne 23
1372.
1373.
1374.SS Strings
1375.
1376You can redefine the following strings to adapt the
1377.I "groff ms"
1378macros to languages other than English:
1379.TS
1380center;
1381cb cb
1382afCW l .
1383String	Default Value
1384_
1385REFERENCES	References
1386ABSTRACT	ABSTRACT
1387TOC	Table of Contents
1388MONTH1	January
1389MONTH2	February
1390MONTH3	March
1391MONTH4	April
1392MONTH5	May
1393MONTH6	June
1394MONTH7	July
1395MONTH8	August
1396MONTH9	September
1397MONTH10	October
1398MONTH11	November
1399MONTH12	December
1400_
1401.TE
1402.
1403.PP
1404The
1405.B \[rs]*-
1406string produces an em dash \[em] like this.
1407.
1408.PP
1409Use
1410.B \[rs]*Q
1411and
1412.B \[rs]*U
1413to get a left and right typographer's quote,
1414respectively, in
1415.I troff
1416(and plain quotes in
1417.IR nroff ).
1418
1419.
1420.
1421.SS Text Settings
1422.
1423The
1424.B FAM
1425string sets the default font family.
1426If this string is undefined at initialization,
1427it is set to Times.
1428.
1429.LP
1430The point size, vertical spacing, and inter-paragraph spacing for footnotes
1431are controlled by the number registers
1432.BR FPS ,
1433.BR FVS ,
1434and
1435.BR FPD ;
1436at initialization these are set to
1437.BR \[rs]n(PS-2 ,
1438.BR \[rs]n[FPS]+2 ,
1439and
1440.BR \[rs]n(PD/2 ,
1441respectively.
1442If any of these registers are defined before initialization,
1443the initialization macro does not change them.
1444.
1445.LP
1446The hyphenation flags (as set by the
1447.B hy
1448request) are set from the
1449.B HY
1450register;
1451the default is\~14.
1452.
1453.PP
1454Improved accent marks
1455(as originally defined in Berkeley's
1456.I ms
1457version)
1458are available by specifying the
1459.B AM
1460macro at the beginning of your document.
1461You can place an accent over most characters
1462by specifying the string defining the accent
1463directly after the character.
1464For example,
1465.B n\[rs]*~ 
1466produces an n with a tilde over it.
1467.
1468.
1469.
1470.SH "NAMING CONVENTIONS"
1471.
1472.
1473.LP
1474The following conventions are used for names of macros, strings and
1475number registers.
1476External names available to documents that use the
1477.I "groff ms"
1478macros contain only uppercase letters and digits.
1479.
1480.LP
1481Internally the macros are divided into modules;
1482naming conventions are as follows:
1483.
1484.IP \(bu 3n
1485Names used only within one module are of the form
1486.IB \%module * name\fR.
1487.
1488.IP \(bu
1489Names used outside the module in which they are defined are of the form
1490.IB \%module @ name\fR.
1491.
1492.IP \(bu
1493Names associated with a particular environment are of the form
1494.IB \%environment : name\fR;
1495these are used only within the
1496.B par
1497module.
1498.
1499.IP \(bu
1500.I name
1501does not have a module prefix.
1502.
1503.IP \(bu
1504Constructed names used to implement arrays are of the form
1505.IB \%array ! index\fR.
1506.
1507.PP
1508Thus the groff ms macros reserve the following names:
1509.
1510.IP \(bu 3n
1511Names containing the characters
1512.BR * ,
1513.BR @ ,
1514and\~\c
1515.BR : .
1516.
1517.IP \(bu
1518Names containing only uppercase letters and digits.
1519.
1520.
1521.
1522.SH FILES
1523.
1524.B @MACRODIR@/ms.tmac
1525(a wrapper file for
1526.BR s.tmac )
1527.br
1528.B @MACRODIR@/s.tmac
1529.
1530.
1531.
1532.SH "SEE ALSO"
1533.
1534.BR groff (@MAN1EXT@),
1535.BR @g@troff (@MAN1EXT@),
1536.BR @g@tbl (@MAN1EXT@),
1537.BR @g@pic (@MAN1EXT@),
1538.BR @g@eqn (@MAN1EXT@),
1539.BR @g@refer (@MAN1EXT@),
1540.I Groff: The GNU Implementation of troff
1541by Trent Fisher and Werner Lemberg.
1542.
1543.
1544.
1545.SH AUTHOR
1546.
1547Original manual page by James Clark
1548.IR "et al" ;
1549rewritten by Larry Kollar
1550(\fIlkollar@despammed.com\fR).
1551.
1552.cp \n[groff_ms_C]
1553.
1554.\" Local Variables:
1555.\" mode: nroff
1556.\" End: