{ "mode": "man", "parameter": "groff_ms", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/groff_ms/7/json", "generated": "2026-10-09T17:03:39Z", "sections": { "Name": { "content": "groffms - GNU roff manuscript macro package for formatting documents\n", "subsections": [] }, "Synopsis": { "content": "groff -ms [option ...] [file ...]\ngroff -m ms [option ...] [file ...]\n", "subsections": [] }, "Description": { "content": "The GNU implementation of the ms macro package is part of the groff document formatting sys‐\ntem. The ms package is suitable for the composition of letters, memoranda, reports, and\nbooks.\n\nThese groff macros support cover page and table of contents generation, automatically num‐\nbered headings, several paragraph styles, a variety of text styling options, footnotes, and\nmulti-column page layouts. ms supports the tbl(1), eqn(1), pic(1), and refer(1) preproces‐\nsors for inclusion of tables, mathematical equations, diagrams, and standardized biblio‐\ngraphic citations.\n\nThis implementation is mostly compatible with the documented interface and behavior of AT&T\nUnix Version 7 ms. Many extensions from 4.2BSD (Berkeley) and Tenth Edition Research Unix\nhave been recreated.\n", "subsections": [] }, "Usage": { "content": "The ms macro package expects a certain amount of structure: a well-formed document contains\nat least one paragraphing or heading macro call. To compose a simple document from scratch,\nbegin it by calling .LP or .PP. Longer documents have a structure as follows.\n", "subsections": [ { "name": "Document type", "content": "Calling the RP macro at the beginning of your document puts the document description\n(see below) on a cover page. Otherwise, ms places this information on the first page,\nfollowed immediately by the body text. Some document types found in other ms imple‐\nmentations are specific to AT&T or Berkeley, and are not supported in groff ms.\n" }, { "name": "Format and layout", "content": "By setting registers and strings, you can configure your document's typeface, margins,\nspacing, headers and footers, and footnote arrangement. See subsection “Document con‐\ntrol settings” below.\n" }, { "name": "Document description", "content": "A document description consists of any of: a title, one or more authors' names and af‐\nfiliated institutions, an abstract, and a date or other identifier. See subsection\n“Document description macros” below.\n" }, { "name": "Body text", "content": "The main matter of your document follows its description (if any). ms supports highly\nstructured text consisting of paragraphs interspersed with multi-level headings (chap‐\nters, sections, subsections, and so forth) and augmented by lists, footnotes, tables,\ndiagrams, and similar material. The preponderance of subsections below covers these\nmatters.\n" }, { "name": "Table of contents", "content": "Macros enable the collection of entries for a table of contents (or index) as the ma‐\nterial they discuss appears in the document. You then call a macro to emit the table\nof contents at the end of your document. The table of contents must necessarily fol‐\nlow the rest of the text since GNU troff is a single-pass formatter; it thus cannot\ndetermine the page number of a division of the text until it has been set and output.\nSince ms output was designed for the production of hard copy, the traditional proce‐\ndure was to manually relocate the pages containing the table of contents between the\ncover page and the body text. Today, page resequencing is more often done in the dig‐\nital domain. An index works similarly, but because it typically needs to be sorted\nafter collection, its preparation requires separate processing.\n" }, { "name": "Document control settings", "content": "The following tables list the document control registers, strings, and special characters.\nFor any parameter whose default is unsatisfactory, define it before calling any ms macro\nother than RP.\n\nMargin settings" }, { "name": "Parameter Definition Effective Default", "content": "──────────────────────────────────────────────────────────────────────────────────────────────\n\\n[PO] Page offset (left margin) next page 1i (0)\n\\n[LL] Line length next paragraph 6.5i (65n)\n\\n[LT] Title line length next paragraph 6.5i (65n)\n\\n[HM] Top (header) margin next page 1i\n\\n[FM] Bottom (footer) margin next page 1i\n──────────────────────────────────────────────────────────────────────────────────────────────\n\nTitles (headers, footers)" }, { "name": "Parameter Definition Effective Default", "content": "──────────────────────────────────────────────────────────────────────────────────────────────\n\\*[LH] Left header text next header empty\n\\*[CH] Center header text next header -\\n[%]-\n\\*[RH] Right header text next header empty\n\\*[LF] Left footer text next footer empty\n\\*[CF] Center footer text next footer empty\n\\*[RF] Right footer text next footer empty\n──────────────────────────────────────────────────────────────────────────────────────────────\n\nText settings" }, { "name": "Parameter Definition Effective Default", "content": "──────────────────────────────────────────────────────────────────────────────────────────────\n\\n[PS] Point size next paragraph 10p\n\\n[VS] Vertical spacing (leading) next paragraph 12p\n\\n[HY] Hyphenation mode next paragraph 6\n\\*[FAM] Font family next paragraph T\n──────────────────────────────────────────────────────────────────────────────────────────────\n\nParagraph settings" }, { "name": "Parameter Definition Effective Default", "content": "──────────────────────────────────────────────────────────────────────────────────────────────\n\\n[PI] Indentation next paragraph 5n\n\\n[PD] Paragraph distance (spacing) next paragraph 0.3v (1v)\n\\n[QI] Quotation indentation next paragraph 5n\n\\n[PORPHANS] # of initial lines kept next paragraph 1\n──────────────────────────────────────────────────────────────────────────────────────────────\n\nHeading settings" }, { "name": "Parameter Definition Effective Default", "content": "──────────────────────────────────────────────────────────────────────────────────────────────\n\\n[PSINCR] Point size increment next heading 1p\n\\n[GROWPS] Size increase depth limit next heading 0\n\\n[HORPHANS] # of following lines kept next heading 1\n\\*[SN-STYLE] Numbering style (alias) next heading \\*[SN-DOT]\n──────────────────────────────────────────────────────────────────────────────────────────────\n\n\\*[SN-STYLE] can alternatively be made an alias of \\*[SN-NO-DOT] with the als request.\n\nFootnote settings" }, { "name": "Parameter Definition Effective Default", "content": "──────────────────────────────────────────────────────────────────────────────────────────────\n\\n[FI] Indentation next footnote 2n\n\\n[FF] Format next footnote 0\n\\n[FPS] Point size next footnote \\n[PS]-2p\n\\n[FVS] Vertical spacing (leading) next footnote \\n[FPS]+2p\n\\n[FPD] Paragraph distance (spacing) next footnote \\n[PD]/2\n\\*[FR] Line length ratio special 11/12\n──────────────────────────────────────────────────────────────────────────────────────────────\n\nDisplay settings" }, { "name": "Parameter Definition Effective Default", "content": "──────────────────────────────────────────────────────────────────────────────────────────────\n\\n[DD] Display distance (spacing) special 0.5v (1v)\n\\n[DI] Display indentation special 0.5i\n──────────────────────────────────────────────────────────────────────────────────────────────\n\nOther settings\nParameter Definition Effective Default\n──────────────────────────────────────────────────────────────────────────────────────────────\n\\n[MINGW] Minimum gutter width next page 2n\n\\n[TC-MARGIN] TOC page number margin width next PX call \\w'000'\n\\[TC-LEADER] TOC leader character next PX call .\\h'1m'\n──────────────────────────────────────────────────────────────────────────────────────────────\n\nFor entries marked “special” in the “Effective” column, see the discussion in the applicable\nsection below. The PO, LL, and LT register defaults vary by output device and paper format;\nthe values shown are for typesetters using U.S. letter paper, and then terminals. See sec‐\ntion “Paper format” of groff(1). The PD and DD registers use the larger value if the verti‐\ncal motion quantum of the output device is too coarse for the smaller one; usually, this is\nthe case only for output to terminals and emulators thereof. The “gutter” affected by\n\\n[MINGW] is the gap between columns in multiple-column page arrangements. The TC-MARGIN\nregister and TC-LEADER special character affect the formatting of tables of contents assem‐\nbled by the XS, XA, and XE macros.\n" }, { "name": "Document description macros", "content": "Define information describing the document by calling the macros below in the order shown;\n.DA or .ND can be called to set the document date (or other identifier) at any time before\n(a) the abstract, if present, or (b) its information is required in a header or footer. Use\nof these macros is optional, except that .TL is mandatory if any of .RP, .AU, .AI, or .AB is\ncalled, and .AE is mandatory if .AB is called.\n\n.RP [no-repeat-info] [no-renumber]\nUse the “report” (AT&T: “released paper”) format for your document, creating a sepa‐\nrate cover page. The default arrangement is to place most of the document description\n(title, author names and institutions, and abstract, but not the date) at the top of\nthe first page. If the optional no-repeat-info argument is given, ms produces a cover\npage but does not repeat any of its information on subsequently (but see the DA macro\nbelow regarding the date). Normally, .RP sets the page number following the cover\npage to 1. Specifying the optional no-renumber argument suppresses this alteration.\nOptional arguments can occur in any order. “no” is recognized as a synonym of no-\nrepeat-info for AT&T compatibility.\n\n.TL Specify the document title. ms collects text on input lines following this call into\nthe title until reaching .AU, .AB, or a heading or paragraphing macro call.\n\n.AU Specify an author's name. ms collects text on input lines following this call into\nthe author's name until reaching .AI, .AB, another .AU, or a heading or paragraphing\nmacro call. Call it repeatedly to specify multiple authors.\n\n.AI Specify the preceding author's institution. An .AU call is usefully followed by at\nmost one .AI call; if there are more, the last .AI call controls. ms collects text on\ninput lines following this call into the author's institution until reaching .AU, .AB,\nor a heading or paragraphing macro call.\n\n.DA [x ...]\nTypeset the current date, or any arguments x, in the center footer, and, if .RP is\nalso called, left-aligned at the end of the document description on the cover page.\n\n.ND [x ...]\nTypeset the current date, or any arguments x, if .RP is also called, left-aligned at\nthe end of the document description on the cover page. This is groff ms's default.\n\n.AB [no]\nBegin the abstract. ms collects text on input lines following this call into the ab‐\nstract until reaching an .AE call. By default, ms places the word “ABSTRACT” centered\nand in italics above the text of the abstract. The optional argument “no” suppresses\nthis heading.\n\n.AE End the abstract.\n" }, { "name": "Text settings", "content": "The FAM string, a GNU extension, sets the font family for body text; the default is “T”. The\nPS and VS registers set the type size and vertical spacing (distance between text baselines),\nrespectively. The font family and type size are ignored on terminal devices. Setting these\nparameters before the first call of a heading, paragraphing, or (non-date) document descrip‐\ntion macro also applies them to headers, footers, and (for FAM) footnotes.\n\nThe HY register defines the automatic hyphenation mode used with the hy request. Setting\n\\n[HY] to 0 is equivalent to using the nh request. This is a Tenth Edition Research Unix ex‐\ntension.\n" }, { "name": "Typographical symbols", "content": "ms provides a few strings to obtain typographical symbols not easily entered with the key‐\nboard. These and many others are available as special character escape sequences—see\ngroffchar(7).\n\n\\*[-] Interpolate an em dash.\n\n\\*[Q]\n\\*[U] Interpolate typographer's quotation marks where available, and neutral double quotes\notherwise. \\*[Q] is the left quote and \\*[U] the right.\n" }, { "name": "Paragraphs", "content": "Paragraphing macros break, or terminate, any pending output line so that a new paragraph can\nbegin. Several paragraph types are available, differing in how indentation applies to them:\nto left, right, or both margins; to the first output line of the paragraph, all output lines,\nor all but the first. All paragraphing macro calls cause the insertion of vertical space in\nthe amount stored in the PD register, except at page or column breaks, or adjacent to dis‐\nplays.\n\nThe PORPHANS register defines the minimum number of initial lines of any paragraph that must\nbe kept together to avoid isolated lines at the bottom of a page. If a new paragraph is\nstarted close to the bottom of a page, and there is insufficient space to accommodate \\n[POR‐\nPHANS] lines before an automatic page break, then a page break is forced before the start of\nthe paragraph. This is a GNU extension.\n\n.LP Set a paragraph without any (additional) indentation.\n\n.PP Set a paragraph with a first-line left indentation in the amount stored in the PI reg‐\nister.\n\n.IP [marker [width]]\nSet a paragraph with a left indentation. The optional marker is not indented and is\nempty by default. width overrides the indentation amount in \\n[PI]; its default unit\nis “n”. Once specified, width applies to further .IP calls until specified again or a\nheading or different paragraphing macro is called.\n\n.QP Set a paragraph indented from both left and right margins by \\n[QI].\n" }, { "name": ".QS", "content": ".QE Begin (QS) and end (QE) a region where each paragraph is indented from both margins by\n\\n[QI]. The text between .QS and .QE can be structured further by use of other para‐\ngraphing macros.\n\n.XP Set an “exdented” paragraph—one with a left indentation of \\n[PI] on every line except\nthe first (also known as a hanging indent). This is a Berkeley extension.\n" }, { "name": "Headings", "content": "Use headings to create a hierarchical structure for your document. The ms macros print head‐\nings in bold using the same font family and, by default, type size as the body text. Head‐\nings are available with and without automatic numbering. Text on input lines following the\nmacro call becomes the heading's title. Call a paragraphing macro to end the heading text\nand start the section's content.\n\n.NH [depth]\nSet an automatically numbered heading. ms produces a numbered heading in the form\na.b.c..., to any level desired, with the numbering of each depth increasing automati‐\ncally and being reset to zero when a more significant depth is increased. “1” is the\nmost significant or coarsest division of the document. Only non-zero values are out‐\nput. If depth is omitted, it is taken to be 1. If you specify depth such that an as‐\ncending gap occurs relative to the previous NH call—that is, you “skip a depth”, as by\n“.NH 1” and then “.NH 3”, groff ms emits a warning on the standard error stream.\n\n.NH S heading-depth-index ...\nAlternatively, you can give NH a first argument of “S”, followed by integers to number\nthe heading depths explicitly. Further automatic numbering, if used, resumes using\nthe specified indices as their predecessors. This feature is a Berkeley extension.\n\nAfter .NH is called, the assigned number is made available in the strings SN-DOT (as it ap‐\npears in a printed heading with default formatting, followed by a terminating period) and\nSN-NO-DOT (with the terminating period omitted). These are GNU extensions.\n\nYou can control the style used to print numbered headings by defining an appropriate alias\nfor the string SN-STYLE. By default, \\*[SN-STYLE] is aliased to \\*[SN-DOT]. If you prefer\nto omit the terminating period from numbers appearing in numbered headings, you may alias it\nto \\*[SN-NO-DOT]. Any such change in numbering style becomes effective from the next use of\n.NH following redefinition of the alias for \\*[SN-STYLE]. The formatted number of the cur‐\nrent heading is available in \\*[SN] (a feature first documented by Berkeley); this string fa‐\ncilitates its inclusion in, for example, table captions, equation labels, and .XS/.XA/.XE ta‐\nble of contents entries.\n\n.SH [depth]\nSet an unnumbered heading. The optional depth argument is a GNU extension indicating\nthe heading depth corresponding to the depth argument of .NH. It matches the type\nsize at which the heading is set to that of a numbered heading at the same depth when\nthe \\n[GROWPS] and \\n[PSINCR] heading size adjustment mechanism is in effect.\n\nThe PSINCR register defines an increment in type size to be applied to a heading at a lesser\ndepth than that specified in \\n[GROWPS]. The value of \\n[PSINCR] should be specified in\npoints with the “p” scaling unit and may include a fractional component.\n\nThe GROWPS register defines the heading depth above which the type size increment set by\n\\n[PSINCR] becomes effective. For each heading depth less than the value of \\n[GROWPS], the\ntype size is increased by \\n[PSINCR]. Setting \\n[GROWPS] to a value less than 2 disables the\nincremental heading size feature.\n\nIn other words, if the value of GROWPS register is greater than the depth argument to a .NH\nor .SH call, the type size of a heading produced by these macros increases by \\n[PSINCR]\nunits over \\n[PS] multiplied by the difference of \\n[GROWPS] and depth.\n\nThe \\n[HORPHANS] register operates in conjunction with the NH and SH macros to inhibit the\nprinting of isolated headings at the bottom of a page; it specifies the minimum number of\nlines of the subsequent paragraph that must be kept on the same page as the heading. If in‐\nsufficient space remains on the current page to accommodate the heading and this number of\nlines of paragraph text, a page break is forced before the heading is printed. Any display\nmacro call or tbl, pic, or eqn region between the heading and the subsequent paragraph sup‐\npresses this grouping.\n" }, { "name": "Typeface and decoration", "content": "The ms macros provide a variety of ways to style text. Attend closely to the ordering of ar‐\nguments labeled pre and post, which is not intuitive. Support for pre arguments is a GNU ex‐\ntension.\n\n.B [text [post [pre]]]\nStyle text in bold, followed by post in the previous font style without intervening\nspace, and preceded by pre similarly. Without arguments, ms styles subsequent text in\nbold until the next paragraphing, heading, or no-argument typeface macro call.\n\n.R [text [post [pre]]]\nAs .B, but use the roman style (upright text of normal weight) instead of bold. Argu‐\nment recognition is a GNU extension.\n\n.I [text [post [pre]]]\nAs .B, but use an italic or oblique style instead of bold.\n\n.BI [text [post [pre]]]\nAs .B, but use a bold italic or bold oblique style instead of upright bold. This is a\nTenth Edition Research Unix extension.\n\n.CW [text [post [pre]]]\nAs .B, but use a constant-width (monospaced) roman typeface instead of bold. This is\na Tenth Edition Research Unix extension.\n\n.BX [text]\nTypeset text and draw a box around it. On terminal devices, reverse video is used in‐\nstead. If you want text to contain space, use unbreakable space or horizontal motion\nescape sequences (\\~, \\space, \\^, \\|, \\0, or \\h).\n\n.UL [text [post]]\nTypeset text with an underline. post, if present, is set after text with no interven‐\ning space.\n\n.LG Set subsequent text in larger type (2 points larger than the current size) until the\nnext type size, paragraphing, or heading macro call. You can specify this macro mul‐\ntiple times to enlarge the type size as needed.\n\n.SM Set subsequent text in smaller type (2 points smaller than the current size) until the\nnext type size, paragraphing, or heading macro call. You can specify this macro mul‐\ntiple times to reduce the type size as needed.\n\n.NL Set subsequent text at the normal type size (\\n[PS]).\n\nWhen pre is used, a hyphenation control escape sequence \\% that would ordinarily start text\nmust start pre instead.\n\ngroff ms also offers strings to begin and end super- and subscripting. These are GNU exten‐\nsions.\n\n\\*{\n\\*} Begin and end superscripting, respectively.\n\n\\*<\n\\*> Begin and end subscripting, respectively.\n" }, { "name": "Indented regions", "content": "You may need to indent a region of text while otherwise formatting it normally. Indented re‐\ngions can be nested.\n\n.RS Begin a region where headings, paragraphs, and displays are indented (further) by\n\\n[PI].\n\n.RE End the (next) most recent indented region.\n" }, { "name": "Keeps, boxed keeps, and displays", "content": "On occasion, you may want to keep several lines of text, or a region of a document, together\non a single page, preventing an automatic page break within certain boundaries. This can\ncause a page break to occur earlier than it normally would.\n\nYou can alternatively specify a floating keep: if a keep cannot fit on the current page, ms\nholds its contents and allows text following the keep (in the source document) to fill in the\nremainder of the current page. When the page breaks, whether by reaching the end or bp re‐\nquest, ms puts the floating keep at the beginning of the next page.\n\n.KS Begin a keep.\n\n.KF Begin a floating keep.\n\n.KE End (floating) keep.\n\nAs an alternative to the keep mechanism, the ne request forces a page break if there is not\nat least the amount of vertical space specified in its argument remaining on the page.\n\nA boxed keep has a frame drawn around it.\n\n.B1 Begin a keep with a box drawn around it.\n\n.B2 End boxed keep.\n\nBoxed keep macros cause breaks; if you need to box a word or phrase within a line, see the BX\nmacro in section “Highlighting” above. Box lines are drawn as close as possible to the text\nthey enclose so that they are usable within paragraphs. If you wish to place one or more\nparagraphs in a boxed keep, you may improve their appearance by calling .B1 after the first\nparagraphing macro, and by adding a small amount of vertical space before calling .B2.\n\nIf you want a boxed keep to float, you will need to enclose the .B1 and .B2 calls within a\npair of .KF and .KE calls.\n\nDisplays turn off filling; lines of verse or program code are shown with their lines broken\nas in the source document without requiring br requests between lines. Displays can be kept\non a single page or allowed to break across pages. The DS macro begins a kept display of the\nlayout specified in its first argument; non-kept displays are begun with dedicated macros\ncorresponding to their layout.\n" }, { "name": ".DS L", "content": ".LD Begin (DS: kept) left-aligned display.\n\n.DS [I [indent]]\n.ID [indent]\nBegin (DS: kept) display indented by indent if specified, \\n[DI] otherwise.\n" }, { "name": ".DS B", "content": ".BD Begin (DS: kept) block display: the entire display is left-aligned, but indented such\nthat the longest line in the display is centered on the page.\n" }, { "name": ".DS C", "content": ".CD Begin (DS: kept) centered display: each line in the display is centered.\n" }, { "name": ".DS R", "content": ".RD Begin (DS: kept) right-aligned display. This is a GNU extension.\n\n.DE End any display.\n\nThe distance stored in \\n[DD] is inserted before and after each pair of display macros; this\nis a Berkeley extension. In groff ms, this distance replaces any adjacent inter-paragraph\ndistance or subsequent spacing prior to a section heading. The DI register is a GNU exten‐\nsion; its value is an indentation applied to displays created with .DS and .ID without argu‐\nments, to “.DS I” without an indentation argument, and to equations set with “.EQ I”.\nChanges to either register take effect at the next display boundary.\n" }, { "name": "Tables, figures, equations, and references", "content": "The ms package is often used with the tbl, pic, eqn, and refer preprocessors. The \\n[DD]\ndistance is also applied to regions of the document preprocessed with eqn, pic, and tbl.\nMark text meant for preprocessors by enclosing it in pairs of tokens as follows, with nothing\nbetween the dot and the macro name. The preprocessors match these tokens only at the start\nof an input line.\n\n.TS [H]\n.TE Demarcate a table to be processed by the tbl preprocessor. The optional H argument\ninstructs ms to repeat table rows (often column headings) at the top of each new page\nthe table spans, if applicable; calling the TH macro marks the end of such rows.\ntbl(1) provides a comprehensive reference to the preprocessor and offers examples of\nits use.\n" }, { "name": ".PS", "content": "" }, { "name": ".PE", "content": ".PF .PS begins a picture to be processed by the pic preprocessor; either of .PE or .PF\nends it, the latter with “flyback” to the vertical position at its top.\n\n.EQ [align [label]]\n.EN Demarcate an equation to be processed by the eqn preprocessor. The equation is cen‐\ntered by default; align can be C, L, or I to (explicitly) center, left-align, or in‐\ndent it by \\n[DI], respectively. If specified, label is set right-aligned.\n\n.[\n.] Demarcate a bibliographic citation to be processed by the refer preprocessor.\nrefer(1) provides a comprehensive reference to the preprocessor and the format of its\nbibliographic database.\n\nWhen refer emits collected references (as might be done on a “Works Cited” page), it interpo‐\nlates the string \\*[REFERENCES] as an unnumbered heading (.SH).\n\nAttempting to place a multi-page table inside a keep can lead to unpleasant results, particu‐\nlarly if the tbl “allbox” option is used.\n" }, { "name": "Footnotes", "content": "A footnote is typically anchored to a place in the text with a marker, which is a small inte‐\nger, a symbol, or arbitrary user-specified text.\n\n\\ Place an automatic number, an automatically generated numeric footnote marker, in the\ntext. Each time this string is interpolated, the number it produces increments by\none. Automatic numbers start at 1. This is a Berkeley extension.\n\nEnclose the footnote text in FS and FE macro calls to set it at the nearest available “foot”,\nor bottom, of a text column or page.\n\n.FS [marker]\nBegin a footnote. The .FS-MARK hook (see below) is called with any supplied marker\nargument, which is then also placed at the beginning of the footnote text. If marker\nis omitted, the next pending automatic number enqueued by interpolation of the *\nstring is used, and if none exists, nothing is prefixed.\n\n.FE End footnote text.\n\ngroff ms provides a hook macro, FS-MARK, for user-determined operations to be performed when\nthe FS macro is called. It is passed the same arguments as .FS itself. By default, this\nmacro has an empty definition. .FS-MARK is a GNU extension.\n\nFootnote text is formatted as paragraphs are, using analogous parameters. The registers FI,\nFPD, FPS, and FVS correspond to PI, PD, PS, and VS, respectively; FPD, FPS, and FVS are GNU\nextensions.\n\nThe FF register controls the formatting of automatically numbered footnote paragraphs, and\nthose for which .FS is given a marker argument, at the bottom of a column or page as follows.\n\n0 Set an automatic number, or a specified FS marker argument, as a superscript\n(on typesetter devices) or surrounded by square brackets (on terminals). The\nfootnote paragraph is indented as with .PP if there is an .FS argument or an\nautomatic number, and as with .LP otherwise. This is the default.\n\n1 As 0, but set the marker as regular text, and follow an automatic number with a\nperiod.\n\n2 As 1, but without indentation (like .LP).\n\n3 As 1, but set the footnote paragraph with the marker hanging (like .IP).\n" }, { "name": "Language and localization", "content": "groff ms provides several strings that you can customize for your own purposes, or redefine\nto adapt the macro package to languages other than English. It is already localized for\nCzech, German, French, Italian, and Swedish. Load the desired localization macro package af‐\nter ms; see grofftmac(5).\n\nString Default\n───────────────────────────────────\n\\*[REFERENCES] References\n\\*[ABSTRACT] \\f[I]ABSTRACT\\f[]\n\\*[TOC] Table of Contents\n\\*[MONTH1] January\n\\*[MONTH2] February\n\\*[MONTH3] March\n\\*[MONTH4] April\n\\*[MONTH5] May\n\\*[MONTH6] June\n\\*[MONTH7] July\n\\*[MONTH8] August\n\\*[MONTH9] September\n\\*[MONTH10] October\n\\*[MONTH11] November\n\\*[MONTH12] December\n───────────────────────────────────\nThe default for ABSTRACT includes font selection escape sequences to set the word in italics.\n" }, { "name": "Headers and footers", "content": "There are multiple ways to produce headers and footers. One is to define the strings LH, CH,\nand RH to set the left, center, and right headers, respectively; and LF, CF, and RF to set\nthe left, center, and right footers. This approach suffices for documents that do not dis‐\ntinguish odd- and even-numbered pages.\n\nAnother method is to call macros that set headers or footers for odd- or even-numbered pages.\nEach such macro takes a delimited argument separating the left, center, and right header or\nfooter texts from each other. You can replace the neutral apostrophes (') shown below with\nany character not appearing in the header or footer text. These macros are Berkeley exten‐\nsions.\n\n.OH 'left'center'right'\n.OF 'left'center'right'\n.EH 'left'center'right'\n.EF 'left'center'right'\nThe OH and EH macros define headers for odd- (recto) and even-numbered (verso) pages,\nrespectively; the OF and EF macros define footers for them.\n\nWith either method, a percent sign % in header or footer text is replaced by the current page\nnumber. By default, ms places no header on a page numbered “1” (regardless of its number\nformat).\n\n.P1 Typeset the header even on page 1. To be effective, this macro must be called before\nthe header trap is sprung on any page numbered “1”. This is a Berkeley extension.\n\nFor even greater flexibility, ms permits redefinition of the macros called when the page\nheader and footer traps are sprung. PT (“page trap”) is called by ms when the header is to\nbe written, and BT (“bottom trap”) when the footer is to be. The groff page location trap\nthat ms sets up to format the header also calls the (normally undefined) HD macro after .PT;\nyou can define .HD if you need additional processing after setting the header. The HD hook\nis a Berkeley extension. Any such macros you (re)define must implement any desired special‐\nization for odd-, even-, or first numbered pages.\n" }, { "name": "Tab stops", "content": "Use the ta request to set tab stops as needed.\n\n.TA Reset the tab stops to the ms default (every 5 ens). Redefine this macro to create a\ndifferent set of default tab stops.\n" }, { "name": "Margins", "content": "Control margins using the registers summarized in the “Margins” portion of the table in sec‐\ntion “Document control settings” above. There is no setting for the right margin; the combi‐\nnation of page offset \\n[PO] and line length \\n[LL] determines it.\n" }, { "name": "Multiple columns", "content": "ms can set text in as many columns as reasonably fit on the page. The following macros force\na page break if a multi-column layout is active when they are called. \\n[MINGW] is the de‐\nfault minimum gutter width; it is a GNU extension. When multiple columns are in use, keeps\nand the HORPHANS and PORPHANS registers work with respect to column breaks instead of page\nbreaks.\n\n.1C Arrange page text in a single column (the default).\n\n.2C Arrange page text in two columns.\n\n.MC [column-width [gutter-width]]\nArrange page text in multiple columns. If you specify no arguments, it is equivalent\nto the 2C macro. Otherwise, column-width is the width of each column and gutter-width\nis the minimum distance between columns.\n" }, { "name": "Creating a table of contents", "content": "Define an entry to appear in the table of contents by bracketing its text between calls to\nthe XS and XE macros. A typical application is to call them immediately after NH or SH and\nrepeat the heading text within them. The XA macro, used within .XS/.XE pairs, supplements an\nentry—for instance, when it requires multiple output lines, whether because a heading is too\nlong to fit or because style dictates that page numbers not be repeated. You may wish to in‐\ndent the text thus wrapped to correspond to its heading depth; this can be done in the entry\ntext by prefixing it with tabs or horizontal motion escape sequences, or by providing a sec‐\nond argument to the XA macro. .XS and .XA automatically associate the page number where they\nare called with the text following them, but they accept arguments to override this behavior.\nAt the end of the document, call TC or PX to emit the table of contents; .TC resets the page\nnumber to i (Roman numeral one), and then calls PX. All of these macros are Berkeley exten‐\nsions.\n\n.XS [page-number]\n.XA [page-number [indentation]]\n.XE Begin, supplement, and end a table of contents entry. Each entry is associated with\npage-number (otherwise the current page number); a page-number of “no” prevents a\nleader and page number from being emitted for that entry. Use of .XA within .XS/.XE\nis optional; it can be repeated. If indentation is present, a supplemental entry is\nindented by that amount; ens are assumed if no unit is indicated. Text on input lines\nbetween .XS and .XE is stored for later recall by .PX.\n\n.PX [no]\nSwitch to single-column layout. Unless “no” is specified, center and interpolate\n\\*[TOC] in bold and two points larger than the body text. Emit the table of contents\nentries.\n\n.TC [no]\nSet the page number to 1, the page number format to lowercase Roman numerals, and call\nPX (with a “no” argument, if present).\n\nThe remaining features in this subsection are GNU extensions. groff ms obviates the need to\nrepeat heading text after .XS calls. Call .XN and .XH after .NH and .SH, respectively. Text\nto be appended to the formatted section heading, but not to appear in the table of contents\nentry, can follow these calls.\n\n.XN heading-text\nFormat heading-text and create a corresponding table of contents entry; the indenta‐\ntion is computed from the depth argument of the preceding NH call.\n\n.XH depth heading-text\nAs .XN, but use depth to determine the indentation.\n\ngroff ms encourages customization of table of contents entry production. (Re-)define any of\nthe following macros as desired.\n\n.XN-REPLACEMENT heading-text\n.XH-REPLACEMENT depth heading-text\nThese hook macros implement .XN and .XH, and call XN-INIT and XH-INIT, respectively,\nthen call XH-UPDATE-TOC with the arguments given them.\n" }, { "name": ".XH-INIT", "content": "" }, { "name": ".XN-INIT", "content": "These hook macros do nothing by default.\n\n.XH-UPDATE-TOC depth heading-text\nBracket heading-text with XS and XE calls, indenting it by 2 ens per level of depth\nbeyond the first.\n\nYou can customize the style of the leader that bridges each table of contents entry with its\npage number; define the TC-LEADER special character by using the char request. A typical\nleader combines the dot glyph “.” with a horizontal motion escape sequence to spread the\ndots. The width of the page number field is stored in the TC-MARGIN register.\n\nDifferences from AT&T ms\nThe groff ms macros are an independent reimplementation, using no AT&T code. Since they take\nadvantage of the extended features of groff, they cannot be used with AT&T troff. groff ms\nsupports features described above as Berkeley and Tenth Edition Research Unix extensions, and\nadds several of its own.\n\n• The internals of groff ms differ from the internals of AT&T ms. Documents that depend\nupon implementation details of AT&T ms may not format properly with groff ms. Such de‐\ntails include macros whose function was not documented in the AT&T ms manual (“Typing Doc‐\numents on the UNIX System: Using the -ms Macros with Troff and Nroff”, M. E. Lesk, Bell\nLaboratories, 1978).\n\n• The error-handling policy of groff ms is to detect and report errors, rather than to ig‐\nnore them silently.\n\n• Tenth Edition Research Unix supported P1/P2 macros to bracket code examples; groff ms does\nnot.\n\n• groff ms does not work in GNU troff's AT&T compatibility mode. If loaded when that mode\nis enabled, it aborts processing with a diagnostic message.\n\n• Multiple line spacing is not supported. Use a larger vertical spacing instead.\n\n• groff ms uses the same header and footer defaults in both nroff and troff modes as AT&T ms\ndoes in troff mode; AT&T's default in nroff mode is to put the date, in U.S. traditional\nformat (e.g., “January 1, 2021”), in the center footer (the CF string).\n\n• Many groff ms macros, including those for paragraphs, headings, and displays, cause a re‐\nset of paragraph rendering parameters, and may change the indentation; they do so not by\nincrementing or decrementing it, but by setting it absolutely. This can cause problems\nfor documents that define additional macros of their own that try to manipulate indenta‐\ntion. Use .RS and .RE instead of the in request.\n\n• AT&T ms interpreted the values of the registers PS and VS in points, and did not support\nthe use of scaling units with them. groff ms interprets values of the registers PS, VS,\nFPS, and FVS, equal to or larger than 1,000 (one thousand) as decimal fractions multiplied\nby 1,000. (Register values are converted to and stored as basic units. See “Measure‐\nments” in the groff Texinfo manual or in groff(7)). This threshold makes use of a scaling\nunit with these parameters practical for high-resolution devices while preserving backward\ncompatibility. It also permits expression of non-integral type sizes. For example,\n“groff -rPS=10.5p” at the shell prompt is equivalent to placing “.nr PS 10.5p” at the be‐\nginning of the document.\n\n• AT&T ms's AU macro supported arguments used with some document types; groff ms does not.\n\n• Right-aligned displays are available. The AT&T ms manual observes that “it is tempting to\nassume that “.DS R” will right adjust lines, but it doesn't work”. In groff ms, it does.\n\n• To make groff ms use the default page offset (which also specifies the left margin), the\nPO register must stay undefined until the first ms macro is called. This implies that\n\\n[PO] should not be used early in the document, unless it is changed also: accessing an\nundefined register automatically defines it.\n\n• groff ms supports the PN register, but it is not necessary; you can access the page number\nvia the usual % register and invoke the af request to assign a different format to it if\ndesired. (If you redefine the ms PT macro and desire special treatment of certain page\nnumbers—like “1”—you may need to handle a non-Arabic page number format, as groff ms's .PT\ndoes; see the macro package source. groff ms aliases the PN register to %.)\n\n• The AT&T ms manual documents registers CW and GW as setting the default column width and\n“intercolumn gap”, respectively, and which applied when .MC was called with fewer than two\narguments. groff ms instead treats .MC without arguments as synonymous with .2C; there is\nthus no occasion for a default column width register. Further, the MINGW register and the\nsecond argument to .MC specify a minimum space between columns, not the fixed gutter width\nof AT&T ms.\n\n• The AT&T ms manual did not document the QI register; Berkeley and groff ms do.\n\n• The register GS is set to 1 by the groff ms macros, but is not used by the AT&T ms pack‐\nage. Documents that need to determine whether they are being formatted with groff ms or\nanother implementation should test this register.\n" }, { "name": "Unix Version 7 macros not implemented by _groff_ ms", "content": "Several macros described in the Unix Version 7 ms documentation are unimplemented by groff ms\nbecause they are specific to the requirements of documents produced internally by Bell Labo‐\nratories, some of which also require a glyph for the Bell System logo that groff does not\nsupport. These macros implemented several document type formats (EG, IM, MF, MR, TM, TR),\nwere meaningful only in conjunction with the use of certain document types (AT, CS, CT, OK,\nSG), stored the postal addresses of Bell Labs sites (HO, IH, MH, PY, WH), or lacked a stable\ndefinition over time (UX).\n" } ] }, "Legacy features": { "content": "groff ms retains some legacy features solely to support formatting of historical documents;\ncontemporary ones should not use them because they can render poorly. See groffchar(7) in‐\nstead.\n", "subsections": [ { "name": "AT&T _ms_ accent mark strings", "content": "AT&T ms defined accent mark strings as follows.\n" }, { "name": "String Description", "content": "──────────────────────────────────────────────────────\n\\*['] Apply acute accent to subsequent glyph.\n\\*[`] Apply grave accent to subsequent glyph.\n\\*[:] Apply dieresis (umlaut) to subsequent glyph.\n\\*[^] Apply circumflex accent to subsequent glyph.\n\\*[~] Apply tilde accent to subsequent glyph.\n\\*[C] Apply caron to subsequent glyph.\n\\*[,] Apply cedilla to subsequent glyph.\n" }, { "name": "Berkeley _ms_ accent mark and glyph strings", "content": "Berkeley ms offered an AM macro; calling it redefined the AT&T accent mark strings (except\nfor \\*C), applied them to the preceding glyph, and defined additional strings, some for spac‐\ning glyphs.\n\n.AM Enable alternative accent mark and glyph-producing strings.\n" }, { "name": "String Description", "content": "───────────────────────────────────────────────────────────────\n\\*['] Apply acute accent to preceding glyph.\n\\*[`] Apply grave accent to preceding glyph.\n\\*[:] Apply dieresis (umlaut) to preceding glyph.\n\\*[^] Apply circumflex accent to preceding glyph.\n\\*[~] Apply tilde accent to preceding glyph.\n\\*[,] Apply cedilla to preceding glyph.\n\\*[/] Apply stroke (slash) to preceding glyph.\n\\*[v] Apply caron to preceding glyph.\n\\*[] Apply macron to preceding glyph.\n\\*[.] Apply underdot to preceding glyph.\n\\*[o] Apply ring accent to preceding glyph.\n───────────────────────────────────────────────────────────────\n\\*[?] Interpolate inverted question mark.\n\\*[!] Interpolate inverted exclamation mark.\n\\*[8] Interpolate small letter sharp s.\n\\*[q] Interpolate small letter o with hook accent (ogonek).\n\\*[3] Interpolate small letter yogh.\n\\*[d-] Interpolate small letter eth.\n\\*[D-] Interpolate capital letter eth.\n\\*[th] Interpolate small letter thorn.\n\\*[TH] Interpolate capital letter thorn.\n\\*[ae] Interpolate small ae ligature.\n\\*[AE] Interpolate capital ae ligature.\n\\*[oe] Interpolate small oe ligature.\n\\*[OE] Interpolate capital oe ligature.\n" } ] }, "Naming conventions": { "content": "The following conventions are used for names of macros, strings, and registers. External\nnames available to documents that use the groff ms macros contain only uppercase letters and\ndigits.\n\nInternally, the macros are divided into modules. Conventions for identifier names are as\nfollows.\n\n• Names used only within one module are of the form module*name.\n\n• Names used outside the module in which they are defined are of the form module@name.\n\n• Names associated with a particular environment are of the form environment:name; these are\nused only within the par module.\n\n• name does not have a module prefix.\n\n• Constructed names used to implement arrays are of the form array!index.\n\nThus the groff ms macros reserve the following names:\n\n• Names containing the characters *, @, and :.\n\n• Names containing only uppercase letters and digits.\n", "subsections": [] }, "Files": { "content": "/usr/share/groff/1.23.0/tmac/s.tmac\nimplements the package.\n\n/usr/share/groff/1.23.0/tmac/refer-ms.tmac\nimplements refer(1) support for ms.\n\n/usr/share/groff/1.23.0/tmac/ms.tmac\nis a wrapper enabling the package to be loaded with “groff -m ms”.\n", "subsections": [] }, "Authors": { "content": "The GNU version of the ms macro package was written by James Clark and contributors. This\ndocument was written by Clark, Larry Kollar, and G. Branden Robinson.\n\nSee also\nA manual is available in source and rendered form. On your system, it may be compressed\nand/or available in additional formats.\n\n/usr/share/doc/groff-base/ms.ms\n/usr/share/doc/groff-base/ms.ps\n“Using groff with the ms Macro Package”; Larry Kollar and G. Branden Robinson.\n\n/usr/share/doc/groff-base/msboxes.ms\n/usr/share/doc/groff-base/msboxes.pdf\n“Using PDF boxes with groff and the ms macros”; Deri James. BOXSTART and BOXSTOP\nmacros are available via the sboxes extension package, enabling colored, bordered\nboxes when the pdf output device is used.\n\nGroff: The GNU Implementation of troff, by Trent A. Fisher and Werner Lemberg, is the primary\ngroff manual. You can browse it interactively with “info groff”.\n\ngroff(1), troff(1), tbl(1), pic(1), eqn(1), refer(1)\n\ngroff 1.23.0 31 March 2024 groffms(7)", "subsections": [] } }, "flags": [], "examples": [], "see_also": [] }