diff options
Diffstat (limited to 'upstream/opensuse-tumbleweed/man7/groff_ms.7')
| -rw-r--r-- | upstream/opensuse-tumbleweed/man7/groff_ms.7 | 2906 |
1 files changed, 2906 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man7/groff_ms.7 b/upstream/opensuse-tumbleweed/man7/groff_ms.7 new file mode 100644 index 00000000..d7b89773 --- /dev/null +++ b/upstream/opensuse-tumbleweed/man7/groff_ms.7 @@ -0,0 +1,2906 @@ +'\" t +.TH groff_ms 7 "4 October 2023" "groff 1.23.0" +.SH Name +groff_ms \- GNU +.I roff +manuscript macro package for formatting documents +. +. +.\" ==================================================================== +.\" Legal Terms +.\" ==================================================================== +.\" +.\" Copyright (C) 1989-2023 Free Software Foundation, Inc. +.\" +.\" Permission is granted to make and distribute verbatim copies of this +.\" manual provided the copyright notice and this permission notice are +.\" preserved on all copies. +.\" +.\" Permission is granted to copy and distribute modified versions of +.\" this manual under the conditions for verbatim copying, provided that +.\" the entire resulting derived work is distributed under the terms of +.\" a permission notice identical to this one. +.\" +.\" Permission is granted to copy and distribute translations of this +.\" manual into another language, under the above conditions for +.\" modified versions, except that this permission notice may be +.\" included in translations approved by the Free Software Foundation +.\" instead of in the original English. +. +. +.\" Save and disable compatibility mode (for, e.g., Solaris 10/11). +.do nr *groff_groff_ms_7_man_C \n[.cp] +.cp 0 +. +.\" Define fallback for groff 1.23's MR macro if the system lacks it. +.nr do-fallback 0 +.if !\n(.f .nr do-fallback 1 \" mandoc +.if \n(.g .if !d MR .nr do-fallback 1 \" older groff +.if !\n(.g .nr do-fallback 1 \" non-groff *roff +.if \n[do-fallback] \{\ +. de MR +. ie \\n(.$=1 \ +. I \%\\$1 +. el \ +. IR \%\\$1 (\\$2)\\$3 +. . +.\} +.rr do-fallback +. +. +.\" ==================================================================== +.SH Synopsis +.\" ==================================================================== +. +.SY "groff \-m\%s" +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +. +.SY "groff \-m m\%s" +.RI [ option\~ .\|.\|.\&] +.RI [ file\~ .\|.\|.] +.YS +. +. +.\" ==================================================================== +.SH Description +.\" ==================================================================== +. +The GNU implementation of the +.I ms +macro package is part of the +.I groff +document formatting system. +. +The +.I ms +package is suitable for the composition of +letters, +memoranda, +reports, +and books. +. +. +.LP +These +.I groff +macros support cover page and table of contents generation, +automatically numbered headings, +several paragraph styles, +a variety of text styling options, +footnotes, +and multi-column page layouts. +. +.I ms +supports the +.MR \%tbl 1 , +.MR \%eqn 1 , +.MR \%pic 1 , +and +.MR \%refer 1 +preprocessors for inclusion of tables, +mathematical equations, +diagrams, +and standardized bibliographic citations. +. +. +.LP +This implementation is mostly compatible with the documented interface +and behavior of AT&T Unix Version\~7 +.IR ms . +. +Many extensions from 4.2BSD (Berkeley) +.\" Few changes were made in 4.3, Reno, Tahoe, or 4.4. +and Tenth Edition Research Unix have been recreated. +. +. +.\" ==================================================================== +.SH Usage +.\" ==================================================================== +. +The +.I ms +macro package expects a certain amount of structure: +a well-formed document contains at least one paragraphing or heading +macro call. +. +.\" This sentence is unique to the man page because we omit the "Basic +.\" information" section from ms.ms. +To compose a simple document from scratch, +begin it by calling +.B .LP +or +.BR .PP . +. +Longer documents have a structure as follows. +. +. +.TP +.B Document type +Calling the +.B RP +macro at the beginning of your document puts the document description +(see below) +on a cover page. +. +Otherwise, +.I ms +places this information +on the first page, +followed immediately by the body text. +. +Some document types found in other +.I ms +implementations are specific to AT&T or Berkeley, +and are not supported in +.IR "groff ms" . +. +. +.TP +.B "Format and layout" +By setting registers and strings, +you can configure your document's typeface, +margins, +spacing, +headers and footers, +and footnote arrangement. +. +See subsection \[lq]Document control settings\[rq] below. +. +. +.TP +.B Document description +A document description consists of any of: +a title, +one or more authors' names and affiliated institutions, +an abstract, +and a date or other identifier. +. +See subsection \[lq]Document description macros\[rq] below. +. +. +.TP +.B Body text +The main matter of your document follows its description +(if any). +. +.I ms +supports highly structured text consisting of paragraphs interspersed +with multi-level headings +(chapters, +sections, +subsections, +and so forth) +and augmented by lists, +footnotes, +tables, +diagrams, +and similar material. +. +The preponderance of subsections below covers these matters. +. +. +.TP +.B "Table of contents" +Macros enable the collection of entries for a table of contents +(or index) +as the material they discuss appears in the document. +. +You then call a macro to emit the table of contents at the end of +your document. +. +The table of contents must necessarily follow the rest of the text since +GNU +.I troff \" GNU +is a single-pass formatter; +it thus cannot determine the page number of a division of the text until +it has been set and output. +. +Since +.I ms +output was designed for the production of hard copy, +the traditional procedure was to manually relocate the pages containing +the table of contents between the cover page and the body text. +. +Today, +page resequencing is more often done in the digital domain. +. +An index works similarly, +but because it typically needs to be sorted after collection, +its preparation requires separate processing. +. +. +.\" ==================================================================== +.SS "Document control settings" +.\" ==================================================================== +. +The following tables list the document control registers, +strings, +and special characters. +. +For any parameter whose default is unsatisfactory, +define it before calling any +.I ms +macro other than +.BR RP . +. +. +.LP +.ne 7v +.TS +cb s s s +cb cb cb cb +lf(CR) lx l lf(CR). +Margin settings +Parameter Definition Effective Default +_ +\[rs]n[PO] Page offset (left margin) next page 1i (0) +\[rs]n[LL] Line length next paragraph 6.5i (65n) +\[rs]n[LT] Title line length next paragraph 6.5i (65n) +\[rs]n[HM] Top (header) margin next page 1i +\[rs]n[FM] Bottom (footer) margin next page 1i +_ +.TE +. +. +.LP +.ne 8v +.TS +cb s s s +cb cb cb cb +lf(CR) lx l lf(CR). +Titles (headers, footers) +Parameter Definition Effective Default +_ +\[rs]*[LH] Left header text next header \f[I]empty +\[rs]*[CH] Center header text next header \-\[rs]n[%]\- +\[rs]*[RH] Right header text next header \f[I]empty +\[rs]*[LF] Left footer text next footer \f[I]empty +\[rs]*[CF] Center footer text next footer \f[I]empty +\[rs]*[RF] Right footer text next footer \f[I]empty +_ +.TE +. +. +.LP +.ne 6v +.TS +cb s s s +cb cb cb cb +lf(CR) lx l lf(CR). +Text settings +Parameter Definition Effective Default +_ +\[rs]n[PS] Point size next paragraph 10p +\[rs]n[VS] Vertical spacing (leading) next paragraph 12p +\[rs]n[HY] Hyphenation mode next paragraph 6 +\[rs]*[FAM] Font family next paragraph T +_ +.TE +. +. +.LP +.ne 6v +.TS +cb s s s +cb cb cb cb +lf(CR)2 lx l lf(CR). +Paragraph settings +Parameter Definition Effective Default +_ +\[rs]n[PI] Indentation next paragraph 5n +\[rs]n[PD] Paragraph distance (spacing) next paragraph 0.3v\ + \f[R](\f[]1v\f[R]) +\[rs]n[QI] Quotation indentation next paragraph 5n +\[rs]n[PORPHANS] # of initial lines kept next paragraph 1 +_ +.TE +. +. +.ne 10v \" Keep table and subsequent paragraph together. +.LP +.TS +cb s s s +cb cb cb cb +lf(CR) lx l lf(CR). +Heading settings +Parameter Definition Effective Default +_ +\[rs]n[PSINCR] Point size increment next heading 1p +\[rs]n[GROWPS] Size increase depth limit next heading 0 +\[rs]n[HORPHANS] # of following lines kept next heading 1 +\[rs]*[SN\-STYLE] Numbering style (alias) next heading \[rs]*[SN\-DOT] +_ +.TE +. +. +.LP +.B \[rs]*[SN\-STYLE] +can alternatively be made an alias of +.B \[rs]*[SN\-NO\-DOT] +with the +.B als +request. +. +. +.LP +.ne 8v +.TS +cb s s s +cb cb cb cb +lf(CR) lx l lf(CR). +Footnote settings +Parameter Definition Effective Default +_ +\[rs]n[FI] Indentation next footnote 2n +\[rs]n[FF] Format next footnote 0 +\[rs]n[FPS] Point size next footnote \[rs]n[PS]\-2p +\[rs]n[FVS] Vertical spacing (leading) next footnote \[rs]n[FPS]+2p +\[rs]n[FPD] Paragraph distance (spacing) next footnote \[rs]n[PD]/2 +\[rs]*[FR] Line length ratio \f[I]special 11/12 +_ +.TE +. +. +.LP +.ne 4v +.TS +cb s s s +cb cb cb cb +lf(CR) lx l lf(CR). +Display settings +Parameter Definition Effective Default +_ +\[rs]n[DD] Display distance (spacing) \f[I]special 0.5v\ + \f[R](\f[]1v\f[R]) +\[rs]n[DI] Display indentation \f[I]special 0.5i +_ +.TE +. +. +.LP +.ne 3v +.TS +cb s s s +cb cb cb cb +lf(CR) lx l lf(CR). +Other settings +Parameter Definition Effective Default +_ +\[rs]n[MINGW] Minimum gutter width next page 2n +\[rs]n[TC\-MARGIN] TOC page number margin width \ +next \f[B]PX\f[] call \[rs]w\[aq]000\[aq] +\[rs][TC\-LEADER] TOC leader character next \f[B]PX\f[] call\ + .\[rs]h\[aq]1m\[aq] +_ +.TE +. +. +.LP +For entries marked +.RI \[lq] special \[rq] +in the \[lq]Effective\[rq] column, +see the discussion in the applicable section below. +. +The +.BR PO , +.BR LL , +and +.B LT +register defaults vary by output device and paper format; +the values shown are for typesetters using U.S.\& letter paper, +and then terminals. +. +See section \[lq]Paper format\[rq] of +.MR groff 1 . +. +The +.B PD +and +.B DD +registers use the larger value if the vertical motion quantum of the +output device is too coarse for the smaller one; +usually, +this is the case only for output to terminals and emulators thereof. +. +The \[lq]gutter\[rq] affected by +.B \[rs]n[MINGW] +is the gap between columns in multiple-column page arrangements. +. +The +.B TC\-MARGIN +register and +.B TC\-LEADER +special character affect the formatting of tables of contents assembled +by the +.BR XS , +.BR XA , +and +.B XE +macros. +. +. +.\" ==================================================================== +.SS "Document description macros" +.\" ==================================================================== +. +Define information describing the document by calling the macros below +in the order shown; +.B .DA +or +.B .ND +can be called to set the document date +(or other identifier) +at any time before (a) the abstract, +if present, +or (b) its information is required in a header or footer. +. +Use of these macros is optional, +except that +.B .TL +is mandatory if any of +.BR .RP , +.BR .AU , +.BR .AI , +or +.B .AB +is called, +and +.B .AE +is mandatory if +.B .AB +is called. +. +. +.TP +.BR .RP\~ [ no\-repeat\-info ]\~[ no\-renumber ] +Use the \[lq]report\[rq] +(AT&T: \[lq]released paper\[rq]) +format for your document, +creating a separate cover page. +. +The default arrangement is to place most of the document description +(title, +author names and institutions, +and abstract, +but not the date) +at the top of the first page. +. +If the optional +.B no\-\:\%repeat\-\:\%info +argument is given, +.I ms +produces a cover page but does not repeat any of its information on +subsequently +(but see the +.B DA +macro below regarding the date). +. +Normally, +.B .RP +sets the page number following the cover page to\~1. +. +Specifying the optional +.B no\-\:\%renumber +argument suppresses this alteration. +. +Optional arguments can occur in any order. +. +.RB \[lq] no \[rq] +is recognized as a synonym of +.B no\-\:\%repeat\-\:\%info +for AT&T compatibility. +. +. +.TP +.B .TL +Specify the document title. +. +.I ms +collects text on input lines following this call into the title until +reaching +.BR .AU , +.BR .AB , +or a heading or paragraphing macro call. +. +. +.TP +.B .AU +Specify an author's name. +. +.I ms +collects text on input lines following this call into the author's name +until reaching +.BR .AI , +.BR .AB , +another +.BR .AU , +or a heading or paragraphing macro call. +. +Call it repeatedly to specify multiple authors. +. +. +.TP +.B .AI +Specify the preceding author's institution. +. +An +.B .AU +call is usefully followed by at most one +.B .AI +call; +if there are more, +the last +.B .AI +call controls. +. +.I ms +collects text on input lines following this call into the author's +institution until reaching +.BR .AU , +.BR .AB , +or a heading or paragraphing macro call. +. +. +.TP +.BR .DA \~[\c +.IR x \~.\|.\|.] +Typeset the current date, +or any +.RI arguments\~ x , +in the center footer, +and, +if +.B .RP +is also called, +left-aligned at the end of the document description on the cover page. +. +. +.TP +.BR .ND \~[\c +.IR x \~.\|.\|.] +Typeset the current date, +or any +.RI arguments\~ x , +if +.B .RP +is also called, +left-aligned at the end of the document description on the cover page. +. +This is +.IR "groff ms" 's +default. +. +. +.TP +.BR ".AB " [ no ] +Begin the abstract. +. +.I ms +collects text on input lines following this call into the abstract until +reaching an +.B .AE +call. +. +By default, +.I ms +places the word \[lq]ABSTRACT\[rq] centered and in italics above the +text of the abstract. +. +The optional argument +.RB \[lq] no \[rq] +suppresses this heading. +. +. +.TP +.B .AE +End the abstract. +. +. +.\" ==================================================================== +.SS "Text settings" +.\" ==================================================================== +. +The +.B FAM +string, +a GNU extension, +sets the font family for body text; +the default is +.RB \[lq] T \[rq]. +. +The +.B PS +and +.B VS +registers set the type size and vertical spacing +(distance between text baselines), +respectively. +. +The font family and type size are ignored on terminal devices. +. +Setting these parameters before the first call of a heading, +paragraphing, +or (non-date) document description macro also applies them to headers, +footers, +and +(for +.BR FAM ) +footnotes. +. +. +.br +.ne 2v +.P +The +.B HY +register defines the automatic hyphenation mode used with the +.B hy +request. +. +Setting +.B \[rs]n[HY] +.RB to\~ 0 +is equivalent to using the +.B nh +request. +. +This is a Tenth Edition Research Unix extension. +. +. +.\" ==================================================================== +.SS "Typographical symbols" +.\" ==================================================================== +. +.I ms +provides a few strings to obtain typographical symbols not easily +entered with the keyboard. +. +These and many others are available as special character escape +sequences\[em]see +.MR groff_char 7 . +. +. +.TP +.B \[rs]*[\-] +Interpolate an em dash. +. +. +.TP +.B \[rs]*[Q] +.TQ +.B \[rs]*[U] +Interpolate typographer's quotation marks where available, +and neutral double quotes otherwise. +. +.B \[rs]*[Q] +is the left quote and +.B \[rs]*[U] +the right. +. +. +.\" ==================================================================== +.SS Paragraphs +.\" ==================================================================== +. +Paragraphing macros +.IR break , +or terminate, +any pending output line so that a new paragraph can begin. +. +Several paragraph types are available, +differing in how indentation +applies to them: +to left, +right, +or both margins; +to the first output line of the paragraph, +all output lines, +or all but the first. +. +All paragraphing macro calls cause the insertion of vertical space in +the amount stored in the +.B PD +register, +except at page or column breaks, +or adjacent to displays. +. +. +.PP +The +.B PORPHANS +register defines the minimum number of initial lines of any paragraph +that must be kept together to avoid isolated lines at the bottom of a +page. +. +If a new paragraph is started close to the bottom of a page, +and there is insufficient space to accommodate +.B \[rs]n[PORPHANS] +lines before an automatic page break, +then a page break is forced before the start of the paragraph. +. +This is a GNU extension. +. +. +.TP +.B .LP +Set a paragraph without any (additional) indentation. +. +. +.TP +.B .PP +Set a paragraph with a first-line left indentation in the amount stored +in the +.B PI +register. +. +. +.TP +.BR .IP \~[\c +.IR marker \~[ width ]] +Set a paragraph with a left indentation. +. +The optional +.I marker +is not indented and is empty by default. +. +.I width +overrides the indentation amount in +.BR \[rs]n[PI] ; +its default unit is +.RB \[lq] n \[rq]. +. +Once specified, +.I width +applies to further +.B .IP +calls until specified again or a heading or different paragraphing macro +is called. +. +. +.TP +.B .QP +Set a paragraph indented from both left and right margins by +.BR \[rs]n[QI] . +. +. +.TP +.B .QS +.TQ +.B .QE +Begin +.RB ( QS ) +and end +.RB ( QE ) +a region where each paragraph is indented from both margins by +.BR \[rs]n[QI] . +. +The text between +.B .QS +and +.B .QE +can be structured further by use of other paragraphing macros. +. +. +.TP +.B .XP +Set an \[lq]exdented\[rq] paragraph\[em]one with a left indentation of +.B \[rs]n[PI] +on every line +.I except +the first +(also known as a hanging indent). +. +This is a Berkeley extension. +. +. +.\" ==================================================================== +.SS Headings +.\" ==================================================================== +. +Use headings to create a hierarchical structure for your document. +. +The +.I ms +macros print headings in +.B bold +using the same font family and, +by default, +type size as the body text. +. +Headings are available with and without automatic numbering. +. +Text on input lines following the macro call becomes the heading's +title. +. +Call a paragraphing macro to end the heading text and start the +section's content. +. +. +.TP +.BR .NH \~[\c +.IR depth ] +Set an automatically numbered heading. +. +.I ms +produces a numbered heading in the form +.IR a . b . c .\|.\|., +to any level desired, +with the numbering of each depth increasing automatically and being +reset to zero when a more significant depth is increased. +. +.RB \[lq] 1 \[rq]\~is +the most significant or coarsest division of the document. +. +Only non-zero values are output. +. +If +.I depth +is omitted, +it is taken to be +.BR 1 . +. +If you specify +.I depth +such that an ascending gap occurs relative to the previous +.B NH +call\[em]that is, +you \[lq]skip a depth\[rq], +as by +.RB \[lq] ".NH\~1" \[rq] +and then +.RB \[lq] ".NH\~3" \[rq], +.I groff ms +emits a warning on the standard error stream. +. +. +.TP +.BI ".NH S\~" heading-depth-index\~\c +\&.\|.\|. +Alternatively, +you can give +.B NH +a first argument +.RB of\~\[lq] S \[rq], +followed by integers to number the heading depths explicitly. +. +Further automatic numbering, +if used, +resumes using the specified indices as their predecessors. +. +.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper... +This feature is a Berkeley extension. +. +. +.P +After +.B .NH +is called, +the assigned number is made available in the strings +.B SN\-DOT +(as it appears in a printed heading with default formatting, +followed by a terminating period) +and +.B SN\-NO\-DOT +(with the terminating period omitted). +. +These are GNU extensions. +. +. +.P +You can control the style used to print numbered headings by defining an +appropriate alias for the string +.BR SN\-STYLE . +. +By default, +.B \[rs]*[SN\-STYLE] +is aliased to +.BR \[rs]*[SN\-DOT] . +. +If you prefer to omit the terminating period from numbers appearing in +numbered headings, +you may alias it to +.BR \[rs]*[SN\-NO\-DOT] . +. +Any such change in numbering style becomes effective from the next use +of +.B .NH +following redefinition of the alias for +.BR \[rs]*[SN\-STYLE] . +. +The formatted number of the current heading is available in +.B \[rs]*[SN] +(a feature first documented by Berkeley); +this string facilitates its inclusion in, +for example, +table captions, +equation labels, +and +.BR .XS / .XA / .XE +table of contents entries. +. +. +.TP +.BR .SH \~[\c +.IR depth ] +Set an unnumbered heading. +. +The optional +.I depth +argument is a GNU extension indicating the heading depth corresponding +to the +.I depth +argument of +.BR .NH . +. +It matches the type size at which the heading is set to that of a +numbered heading at the same depth when the +.B \[rs]n[GROWPS] +and +.B \[rs]n[PSINCR] +heading size adjustment mechanism is in effect. +. +. +.P +The +.B PSINCR +register defines an increment in type size to be applied to a heading at +a lesser depth than that specified in +.BR \[rs]n[GROWPS] . +. +The value of +.B \[rs]n[PSINCR] +should be specified in points with the +.RB \[lq] p \[rq] +scaling unit and may include a fractional component. +. +. +.P +The +.B GROWPS +register defines the heading depth above which the type size increment +set by +.B \[rs]n[PSINCR] +becomes effective. +. +For each heading depth less than the value of +.BR \[rs]n[GROWPS] , +the type size is increased by +.BR \[rs]n[PSINCR] . +. +Setting +.B \[rs]n[GROWPS] +to a value less than\~2 disables the incremental heading size feature. +. +. +.P +In other words, +if the value of +.B GROWPS +register is greater than the +.I depth +argument to a +.B .NH +or +.B .SH +call, +the type size of a heading produced by these macros increases by +.B \[rs]n[PSINCR] +units over +.B \[rs]n[PS] +multiplied by the difference of +.B \[rs]n[GROWPS] +and +.IR depth . +. +. +.P +The +.B \[rs]n[HORPHANS] +register operates in conjunction with the +.B NH +and +.B SH +macros to inhibit the printing of isolated headings at the bottom of a +page; +it specifies the minimum number of lines of the subsequent paragraph +that must be kept on the same page as the heading. +. +If insufficient space remains on the current page to accommodate the +heading and this number of lines of paragraph text, +a page break is forced before the heading is printed. +. +Any display macro call or +.IR tbl , +.IR pic , +or +.I eqn +region between the heading and the subsequent paragraph suppresses this +grouping. +. +. +.\" ==================================================================== +.SS "Typeface and decoration" +.\" ==================================================================== +. +. +.P +The +.I ms +macros provide a variety of ways to style text. +. +Attend closely to the ordering of arguments labeled +.I pre +and +.I post, +which is not intuitive. +. +Support for +.I pre +arguments is a GNU extension. +. +. +.TP +.BR .B \~[\c +.IR text \~[ post \~[ pre ]]] +Style +.I text +in bold, +followed by +.I post +in the previous font style without intervening space, +and preceded by +.I pre +similarly. +. +Without arguments, +.I ms +styles subsequent text in bold +until the next +paragraphing, +heading, +or no-argument typeface macro call. +. +. +.TP +.BR .R \~[\c +.IR text \~[ post \~[ pre ]]] +As +.BR .B , +but use the roman style +(upright text of normal weight) +instead of bold. +. +Argument recognition is a GNU extension. +. +. +.TP +.BR .I \~[\c +.IR text \~[ post \~[ pre ]]] +As +.BR .B , +but use an italic or oblique style instead of bold. +. +. +.TP +.BR .BI \~[\c +.IR text \~[ post \~[ pre ]]] +As +.BR .B , +but use a bold italic or bold oblique style instead of upright bold. +. +This is a Tenth Edition Research Unix extension. +.\" possibly 9th, but definitely not Berkeley +. +. +.TP +.BR .CW \~[\c +.IR text \~[ post \~[ pre ]]] +As +.BR .B , +but use a constant-width (monospaced) roman typeface instead of bold. +. +This is a Tenth Edition Research Unix extension. +.\" possibly 9th, but definitely not Berkeley +. +. +.TP +.BR .BX \~[\c +.IR text ] +Typeset +.I text +and draw a box around it. +. +On terminal devices, +reverse video is used instead. +. +If you want +.I text +to contain space, +use unbreakable space or horizontal motion escape sequences +.RB ( \[rs]\[ti] , +.BI \[rs] space\c +, +.BR \[rs]\[ha] , +.BR \[rs]| , +.BR \[rs]0 , +or +.BR \[rs]h ). +. +. +.TP +.BR .UL \~[\c +.IR text \~[ post ]] +Typeset +.I text +with an underline. +. +.I post, +if present, +is set after +.I text +with no intervening space. +. +. +.TP +.B .LG +Set subsequent text in larger type +(2\~points larger than the current size) +until the next +type size, +paragraphing, +or heading macro call. +. +You can specify this macro multiple times to enlarge the type size as +needed. +. +. +.TP +.B .SM +Set subsequent text in smaller type +(2\~points smaller than the current size) +until the next +type size, +paragraphing, +or heading macro call. +. +You can specify this macro multiple times to reduce the type size as +needed. +. +. +.TP +.B .NL +Set subsequent text at the normal type size +.RB ( \[rs]n[PS] ). +. +. +.P +When +.I pre +is used, +a hyphenation control escape sequence +.B \[rs]% +that would ordinarily start +.I text +must start +.I pre +instead. +. +. +.P +.I groff ms +also offers strings to begin and end super- and subscripting. +. +These are GNU extensions. +. +. +.TP +.B \[rs]*{ +.TQ +.B \[rs]*} +Begin and end superscripting, +respectively. +. +. +.TP +.B \[rs]*< +.TQ +.B \[rs]*> +Begin and end subscripting, +respectively. +. +. +.\" ==================================================================== +.SS "Indented regions" +.\" ==================================================================== +. +You may need to indent a region of text while otherwise formatting it +normally. +. +Indented regions can be nested. +. +. +.TP +.B .RS +Begin a region where headings, +paragraphs, +and displays are indented (further) by +.BR \[rs]n[PI] . +. +. +.TP +.B .RE +End the (next) most recent indented region. +. +. +.\" ==================================================================== +.SS "Keeps, boxed keeps, and displays" +.\" ==================================================================== +. +On occasion, +you may want to +.I keep +several lines of text, +or a region of a document, +together on a single page, +preventing an automatic page break within certain boundaries. +. +This can cause a page break to occur earlier than it normally would. +. +. +.P +You can alternatively specify a +.I floating keep: +if a keep cannot fit on the current page, +.I ms +holds its contents and allows text following the keep +(in the source document) +to fill in the remainder of the current page. +. +When the page breaks, +whether by reaching the end or +.B bp +request, +.I ms +puts the floating keep at the beginning of the next page. +. +. +.TP +.B .KS +Begin a keep. +. +. +.TP +.B .KF +Begin a floating keep. +. +. +.TP +.B .KE +End (floating) keep. +. +. +.P +As an alternative to the keep mechanism, +the +.B ne +request forces a page break if there is not at least the amount of +vertical space specified in its argument remaining on the page. +. +. +.PP +A +.I boxed keep +has a frame drawn around it. +. +. +.TP +.B .B1 +Begin a keep with a box drawn around it. +. +. +.TP +.B .B2 +End boxed keep. +. +. +.P +Boxed keep macros cause breaks; +if you need to box a word or phrase within a line, +see the +.B BX +macro in section \[lq]Highlighting\[rq] above. +. +Box lines are drawn as close as possible to the text they enclose so +that they are usable within paragraphs. +. +If you wish to place one or more paragraphs in a boxed keep, +you may improve their appearance by calling +.B .B1 +after the first paragraphing macro, +and by adding a small amount of vertical space before calling +.BR .B2 . +. +. +.br +.ne 2v +.P +If you want a boxed keep to float, +you will need to enclose the +.B .B1 +and +.B .B2 +calls within a pair of +.B .KF +and +.B .KE +calls. +. +. +.P +.I Displays +turn off filling; +lines of verse or program code are shown with their lines broken as in +the source document without requiring +.B br +requests between lines. +. +Displays can be kept on a single page or allowed to break across pages. +. +The +.B DS +macro begins a kept display of the layout specified in its first +argument; +non-kept displays are begun with dedicated macros corresponding to their +layout. +. +. +.TP +.B .DS L +.TQ +.B .LD +Begin +.RB ( DS ": kept)" +left-aligned display. +. +. +.TP +.BR .DS \~\c +.RB [ I \~\c +.RI [ indent ]] +.TQ +.BR .ID \~\c +.RI [ indent ] +Begin +.RB ( DS ": kept)" +display indented by +.I indent +if specified, +.B \[rs]n[DI] +otherwise. +. +. +.TP +.B .DS B +.TQ +.B .BD +Begin +.RB ( DS ": kept)" +block display: +the entire display is left-aligned, +but indented such that the longest line in the display is centered on +the page. +. +. +.TP +.B .DS C +.TQ +.B .CD +Begin +.RB ( DS ": kept)" +centered display: +each line in the display is centered. +. +. +.TP +.B .DS R +.TQ +.B .RD +Begin +.RB ( DS ": kept)" +right-aligned display. +. +This is a GNU extension. +. +. +.TP +.B .DE +End any display. +. +. +.P +The distance stored in +.B \[rs]n[DD] +is inserted before and after each pair of display macros; +this is a Berkeley extension. +. +In +.IR "groff ms" , +this distance replaces any adjacent inter-paragraph distance +or subsequent spacing prior to a section heading. +. +The +.B DI +register is a GNU extension; +its value is an indentation applied to displays created with +.B .DS +and +.B .ID +without arguments, +to +.RB \[lq] .DS\~I \[rq] +without an indentation argument, +and to equations set with +.RB \[lq] .EQ\~I \[rq]. +. +Changes to either register take effect at the next display boundary. +. +. +.\" ==================================================================== +.SS "Tables, figures, equations, and references" +.\" ==================================================================== +. +The +.I ms +package is often used with the +.IR \%tbl , +.IR \%pic , +.IR \%eqn , +and +.I \%refer +preprocessors. +. +The +.B \[rs]n[DD] +distance is also applied to regions of the document preprocessed with +.IR \%eqn , +.IR \%pic , +and +.IR \%tbl . +. +Mark text meant for preprocessors by enclosing it in pairs of tokens as +follows, +with nothing between the dot and the macro name. +. +The preprocessors match these tokens only at the start of an input line. +. +. +.TP +.BR .TS " [" H "] +.TQ +.B .TE +Demarcate a table to be processed by the +.I tbl +preprocessor. +. +The optional +.BR H "\~argument" +instructs +.I ms +to repeat table rows +(often column headings) +at the top of each new page the table spans, +if applicable; +calling the +.B TH +macro marks the end of such rows. +. +.MR \%tbl 1 +provides a comprehensive reference to the preprocessor and offers +examples of its use. +. +. +.TP +.B .PS +.TQ +.B .PE +.TQ +.B .PF +.B .PS +begins a picture to be processed by the +.I pic +preprocessor; +either of +.B .PE +or +.B .PF +ends it, +the latter with \[lq]flyback\[rq] to the vertical position at its top. +. +. +.TP +.BR .EQ \~[\c +.IR align \~[\c] +.IR label ]] +.TQ +.B .EN +Demarcate an equation to be processed by the +.I eqn +preprocessor. +. +The equation is centered by default; +.I align +can be +.BR C , +.BR L , +.RB or\~ I +to (explicitly) center, +left-align, +or indent it by +.BR \[rs]n[DI] , +respectively. +. +If specified, +.I label +is set right-aligned. +. +. +.TP +.B .[ +.TQ +.B .] +Demarcate a bibliographic citation to be processed by the +.I refer +preprocessor. +. +.MR \%refer 1 +provides a comprehensive reference to the preprocessor and the format of +its bibliographic database. +. +. +.P +When +.I \%refer +emits collected references +(as might be done on a \[lq]Works Cited\[rq] page), +it interpolates the string +.B \[rs]*[REFERENCES] +as an unnumbered heading +.RB ( .SH ). +. +. +.br +.ne 2v +.P +Attempting to place a multi-page table inside a keep can lead to +unpleasant results, +particularly if the +.I tbl \" generic +.RB \[lq] allbox \[rq] +option is used. +. +. +.\" ==================================================================== +.SS Footnotes +.\" ==================================================================== +. +A footnote is typically anchored to a place in the text with a +.I marker, +which is a small integer, +a symbol, +or arbitrary user-specified text. +. +. +.TP +.B \[rs]** +Place an +.I automatic number, +an automatically generated numeric footnote marker, +in the text. +. +Each time this string is interpolated, +the number it produces increments by one. +. +Automatic numbers start at 1. +. +This is a Berkeley extension. +. +. +.P +Enclose the footnote text in +.B FS +and +.B FE +macro calls to set it at the nearest available \[lq]foot\[rq], +or bottom, +of a text column or page. +. +. +.TP +.BR .FS \~[\c +.IR marker ] +Begin a footnote. +. +The +.B .FS\-MARK +hook +(see below) +is called with any supplied +.I marker +argument, +which is then also placed at the beginning of the footnote text. +. +If +.I marker +is omitted, +the next pending automatic number enqueued by interpolation of the +.B * +string is used, +and if none exists, +nothing is prefixed. +. +. +.TP +.B .FE +End footnote text. +. +. +.P +.I groff ms +provides a hook macro, +.BR FS\-MARK , +for user-determined operations to be performed when the +.B FS +macro is called. +. +It is passed the same arguments as +.B .FS +itself. +. +By default, +this macro has an empty definition. +. +.B .FS\-MARK +is a GNU extension. +. +. +.P +Footnote text is formatted as paragraphs are, +using analogous parameters. +. +The registers +.BR FI , +.BR FPD , +.BR FPS , +and +.B FVS +correspond to +.BR PI , +.BR PD , +.BR PS , +and +.BR VS , +respectively; +.BR FPD , +.BR FPS , +and +.B FVS +are GNU extensions. +. +. +.P +The +.B FF +register controls the formatting of automatically numbered footnote +paragraphs, +and those for which +.B .FS +is given a +.I marker +argument, +at the bottom of a column or page as follows. +. +. +.RS +.TP +0 +Set an automatic number, +or a specified +.B FS +.I marker +argument, +as a superscript +(on typesetter devices) +or surrounded by square brackets +(on terminals). +. +The footnote paragraph is indented as with +.B .PP +if there is an +.B .FS +argument or an automatic number, +and as with +.B .LP +otherwise. +. +This is the default. +. +. +.TP +1 +As +.BR 0 , +but set the marker as regular text, +and follow an automatic number with a period. +. +. +.TP +2 +As +.BR 1 , +but without indentation +(like +.BR .LP ). +. +. +.TP +3 +As +.BR 1 , +but set the footnote paragraph with the marker hanging +(like +.BR .IP ). +.RE +. +. +.\" ==================================================================== +.SS "Language and localization" +.\" ==================================================================== +. +.I groff ms +provides several strings that you can customize for your own purposes, +or redefine to adapt the macro package to languages other than English. +. +It is already localized for +.\" cs, de, fr, it, sv +Czech, +German, +French, +Italian, +and +Swedish. +. +Load the desired localization macro package after +.IR ms ; +see +.MR groff_tmac 5 . +. +. +.P +.RS +.TS +cb cb +lf(CR) lf(CR). +String Default +_ +\[rs]*[REFERENCES] References +\[rs]*[ABSTRACT] \[rs]f[I]ABSTRACT\[rs]f[] +\[rs]*[TOC] Table of Contents +\[rs]*[MONTH1] January +\[rs]*[MONTH2] February +\[rs]*[MONTH3] March +\[rs]*[MONTH4] April +\[rs]*[MONTH5] May +\[rs]*[MONTH6] June +\[rs]*[MONTH7] July +\[rs]*[MONTH8] August +\[rs]*[MONTH9] September +\[rs]*[MONTH10] October +\[rs]*[MONTH11] November +\[rs]*[MONTH12] December +_ +.TE +.RE +. +The default for +.B ABSTRACT +includes font selection escape sequences to set the word in italics. +. +. +.\" ==================================================================== +.SS "Headers and footers" +.\" ==================================================================== +. +There are multiple ways to produce headers and footers. +. +One is to define the strings +.BR LH , +.BR CH , +and +.B RH +to set the left, +center, +and right headers, +respectively; +and +.BR LF , +.BR CF , +and +.B RF +to set the left, +center, +and right footers. +. +This approach suffices for documents that do not distinguish odd- and +even-numbered pages. +. +. +.P +Another method is to call macros that set headers or footers for odd- or +even-numbered pages. +. +Each such macro takes a delimited argument separating the left, +center, +and right header or footer texts from each other. +. +You can replace the neutral apostrophes (\[aq]) shown below with any +character not appearing in the header or footer text. +. +These macros are Berkeley extensions. +. +. +.br +.ne 5v +.TP +.BR .OH \~\[aq]\c +.IR left \[aq] center \[aq] right \[aq] +.TQ +.BR .OF \~\[aq]\c +.IR left \[aq] center \[aq] right \[aq] +.TQ +.BR .EH \~\[aq]\c +.IR left \[aq] center \[aq] right \[aq] +.TQ +.BR .EF \~\[aq]\c +.IR left \[aq] center \[aq] right \[aq] +The +.B OH +and +.B EH +macros define headers for odd- (recto) and even-numbered (verso) pages, +respectively; +the +.B OF +and +.B EF +macros define footers for them. +. +. +.P +With either method, +a percent sign +.B % +in header or footer text is replaced by the current page number. +. +By default, +.I ms +places no header on a page numbered \[lq]1\[rq] +(regardless of its number format). +. +. +.TP +.B .P1 +Typeset the header even on page\~1. +. +To be effective, +this macro must be called before the header trap is sprung on any page +numbered \[lq]1\[rq]. +. +This is a Berkeley extension. +. +. +.P +For even greater flexibility, +.I ms +permits redefinition of the macros called when the page header and +footer traps are sprung. +. +.B PT +(\[lq]page trap\[rq]) +is called by +.I ms +when the header is to be written, +and +.B BT +(\[lq]bottom trap\[rq]) +when the footer is to be. +. +The +.I groff +page location trap that +.I ms +sets up to format the header also calls the +(normally undefined) +.B HD +macro after +.BR .PT ; +you can define +.B .HD +if you need additional processing after setting the header. +. +.\" Although undocumented in Tuthill's 4.2BSD ms.diffs paper... +The +.B HD +hook is a Berkeley extension. +. +Any such macros you (re)define must implement any desired specialization +for odd-, +even-, +or first numbered pages. +. +. +.\" ==================================================================== +.SS "Tab stops" +.\" ==================================================================== +. +Use the +.B ta +request to set tab stops as needed. +. +. +.TP +.B .TA +Reset the tab stops to the +.I ms +default +(every 5 ens). +. +Redefine this macro to create a different set of default tab stops. +. +. +.\" ==================================================================== +.SS Margins +.\" ==================================================================== +. +Control margins using the registers summarized in the \[lq]Margins\[rq] +portion of the table in section \[lq]Document control settings\[rq] +above. +. +There is no setting for the right margin; +the combination of page offset +.B \[rs]n[PO] +and line length +.B \[rs]n[LL] +determines it. +. +. +.\" ==================================================================== +.SS "Multiple columns" +.\" ==================================================================== +. +.I ms +can set text in as many columns as reasonably fit on the page. +. +The following macros force a page break if a multi-column layout is +active when they are called. +. +.B \[rs]n[MINGW] +is the default minimum gutter width; +it is a GNU extension. +. +When multiple columns are in use, +keeps +and the +.B \%HORPHANS +and +.B \%PORPHANS +registers +work with respect to column breaks instead of page breaks. +. +. +.TP +.B .1C +Arrange page text in a single column +(the default). +. +. +.TP +.B .2C +Arrange page text in two columns. +. +. +.TP +.BR .MC \~[\c +.IR column-width " [" gutter-width ]] +Arrange page text in multiple columns. +. +If you specify no arguments, +it is equivalent to the +.B 2C +macro. +. +Otherwise, +.I column-width +is the width of each column and +.I gutter-width +is the minimum distance between columns. +. +. +.\" ==================================================================== +.SS "Creating a table of contents" +.\" ==================================================================== +. +Define an entry to appear in the table of contents by bracketing its +text between calls to the +.B XS +and +.B XE +macros. +. +A typical application is to call them immediately after +.B NH +or +.B SH +and repeat the heading text within them. +. +The +.B XA +macro, +used within +.BR .XS / .XE +pairs, +supplements an entry\[em]for instance, +when it requires multiple output lines, +whether because a heading is too long to fit or because style dictates +that page numbers not be repeated. +. +You may wish to indent the text thus wrapped to correspond to its +heading depth; +this can be done in the entry text by prefixing it with tabs or +horizontal motion escape sequences, +or by providing a second argument to the +.B XA +macro. +. +.B .XS +and +.B .XA +automatically associate the page number where they are called with the +text following them, +but they accept arguments to override this behavior. +. +At the end of the document, +call +.B TC +or +.B PX +to emit the table of contents; +.B .TC +resets the page number +.RB to\~ i +(Roman numeral one), +and then calls +.BR PX . +. +All of these macros are Berkeley extensions. +. +. +.TP +.BR .XS \~[\c +.IR page-number ] +.TQ +.BR .XA \~[\c +.IR page-number \~[ indentation ]] +.TQ +.B .XE +Begin, +supplement, +and end a table of contents entry. +. +Each entry is associated with +.I page-number +(otherwise the current page number); +a +.I page-number +of +.RB \[lq] no \[rq] +prevents a leader and page number from being emitted for that entry. +. +Use of +.B .XA +within +.BR .XS / .XE +is optional; +it can be repeated. +. +If +.I indentation +is present, +a supplemental entry is indented by that amount; +ens are assumed if no unit is indicated. +. +Text on input lines between +.B .XS +and +.B .XE +is stored for later recall by +.BR .PX . +. +. +.TP +.BR .PX \~[ no ] +Switch to single-column layout. +. +Unless +.RB \[lq] no \[rq] +is specified, +center and interpolate +.B \[rs]*[TOC] +in bold and two points larger than the body text. +. +Emit the table of contents entries. +. +. +.TP +.BR .TC \~[ no ] +Set the page number to\~1, +the page number format to lowercase Roman numerals, +and call +.B PX +(with a +.RB \[lq] no \[rq] +argument, +if present). +. +. +.P +The remaining features in this subsection are GNU extensions. +. +.I groff ms +obviates the need to repeat heading text after +.B .XS +calls. +. +Call +.B .XN +and +.B .XH +after +.B .NH +and +.BR .SH , +respectively. +. +Text to be appended to the formatted section heading, +but not to appear in the table of contents entry, +can follow these calls. +. +. +.TP +.BI .XN\~ heading-text +Format +.I heading-text +and create a corresponding table of contents entry; +the indentation is computed from the +.I depth +argument of the preceding +.B NH +call. +. +. +.TP +.BI .XH\~ "depth heading-text" +As +.BR .XN , +but use +.I depth +to determine the indentation. +. +. +.P +.I groff ms +encourages customization of table of contents entry production. +. +(Re-)define any of the following macros as desired. +. +. +.TP +.BI \%.XN\-REPLACEMENT\~ heading-text +.TQ +.BI \%.XH\-REPLACEMENT\~ "depth heading-text" +These hook macros implement +.B .XN +and +.BR .XH , +and call +.B \%XN\-INIT +and +.BR \%XH\-INIT , +respectively, +then call +.B \%XH\-UPDATE\-TOC +with the arguments given them. +. +. +.TP +.B \%.XH\-INIT +.TQ +.B \%.XN\-INIT +These hook macros do nothing by default. +. +. +.TP +.BI \%.XH\-UPDATE\-TOC\~ "depth heading-text" +Bracket +.I heading-text +with +.B XS +and +.B XE +calls, +indenting it by 2 ens per level of +.I depth +beyond the first. +. +. +.P +You can customize the style of the leader that bridges each table of +contents entry with its page number; +define the +.B TC\-LEADER +special character by using the +.B char +request. +. +A typical leader combines the dot glyph +.RB \[lq] .\& \[rq] +with a horizontal motion escape sequence to spread the dots. +. +The width of the page number field is stored in the +.B TC\-MARGIN +register. +. +. +.\" ==================================================================== +.SH "Differences from AT&T \f[I]ms\f[]" +.\" ==================================================================== +. +The +.I groff ms +macros are an independent reimplementation, +using no AT&T code. +. +Since they take advantage of the extended features of +.IR groff , +they cannot be used with AT&T +.IR troff . +. +.I groff ms +supports features described above as Berkeley and Tenth Edition Research +Unix extensions, +and adds several of its own. +. +. +.IP \[bu] 3n +The internals of +.I groff ms +differ from the internals of AT&T +.IR ms . +. +Documents that depend upon implementation details of AT&T +.I ms +may not format properly with +.IR "groff ms" . +. +Such details include macros whose function was not documented in the +AT&T +.I ms +manual +(\[lq]Typing Documents on the UNIX System: Using the \-ms Macros with +Troff and Nroff\[rq], +M.\& E.\& Lesk, +Bell Laboratories, +1978). +.\" TODO: Use refer(1)? +.\" XXX: We support RT anyway; maybe we should stop? +. +. +.IP \[bu] +The error-handling policy of +.I groff ms +is to detect and report errors, +rather than to ignore them silently. +. +. +.IP \[bu] +Tenth Edition \" possibly 9th +Research Unix supported +.BR P1 / P2 +macros to bracket code examples; +.I groff ms +does not. +. +. +.IP \[bu] +.I groff ms +does not work in GNU +.IR troff 's \" GNU +AT&T compatibility mode. +. +If loaded when that mode is enabled, +it aborts processing with a diagnostic message. +. +. +.IP \[bu] +Multiple line spacing is not supported. +. +Use a larger vertical spacing instead. +. +. +.IP \[bu] +.I groff ms +uses the same header and footer defaults in both +.I nroff +and +.I troff +modes +as AT&T +.I ms +does in +.I troff +mode; +AT&T's default in +.I nroff +mode is to put the date, +in U.S.\& traditional format +(e.g., +\[lq]January 1, 2021\[rq]), +in the center footer +(the +.B CF +string). +. +. +.IP \[bu] +Many +.I groff ms +macros, +including those for paragraphs, +headings, +and displays, +cause a reset of paragraph rendering parameters, +and may change the indentation; +they do so not by incrementing or decrementing it, +but by setting it absolutely. +. +This can cause problems for documents that define additional macros of +their own that try to manipulate indentation. +. +Use +.B .RS +and +.B .RE +instead of the +.B in +request. +. +. +.IP \[bu] +AT&T +.I ms +interpreted the values of the registers +.B PS +and +.B VS +in points, +and did not support the use of scaling units with them. +. +.I groff ms +interprets values of the registers +.BR PS , +.BR VS , +.BR FPS , +and +.BR FVS , +equal to or larger than\~1,000 +(one thousand) +as decimal fractions multiplied by\~1,000. +. +(Register values are converted to and stored as basic +units. +. +See \[lq]Measurements\[rq] in the +.I groff +Texinfo manual or in +.MR groff 7 ). +. +This threshold makes use of a scaling unit with these parameters +practical for high-resolution devices while preserving backward +compatibility. +. +It also permits expression of non-integral type sizes. +. +For example, +.RB \[lq] "groff \-rPS=10.5p" \[rq] +at the shell prompt is equivalent to placing +.RB \[lq] ".nr PS 10.5p" \[rq] +at the beginning of the document. +. +. +.IP \[bu] +AT&T +.IR ms 's +.B AU +macro supported arguments used with some document types; +.I groff ms +does not. +. +. +.IP \[bu] +Right-aligned displays are available. +. +The AT&T +.I ms +manual observes that \[lq]it is tempting to assume that +.RB \[lq] ".DS R" \[rq] +will right adjust lines, +but it doesn't work\[rq]. +. +In +.IR "groff ms" , +it does. +. +. +.IP \[bu] +To make +.I groff ms +use the default page offset +(which also specifies the left margin), +the +.B PO +register must stay undefined until the first +.I ms +macro is called. +. +This implies that +.B \[rs]n[PO] +should not be used early in the document, +unless it is changed also: +accessing an undefined register automatically defines it. +. +. +.IP \[bu] +.I groff ms +supports the +.B PN +register, +but it is not necessary; +you can access the page number via the usual +.B % +register and invoke the +.B af +request to assign a different format to it if desired. +. +(If you redefine the +.I ms +.B PT +macro \" I wouldn't mention that, but Lesk 1978 encourages doing so. :-/ +and desire special treatment of certain page numbers\[em]like +.RB \[lq] 1 \[rq]\[em]you +may need to handle a non-Arabic page number format, +as +.IR "groff ms" 's +.B .PT +does; +see the macro package source. +. +.I groff ms +aliases the +.B PN +register to +.BR % .) +. +. +.IP \[bu] +The AT&T +.I ms +manual documents registers +.B CW +and +.B GW +as setting the default column width and \[lq]intercolumn gap\[rq], +respectively, +and which applied when +.B .MC +was called with fewer than two arguments. +. +.I groff ms +instead treats +.B .MC +without arguments as synonymous with +.BR .2C ; +there is thus no occasion for a default column width register. +. +Further, +the +.B MINGW +register +and the second argument to +.B .MC +specify a +.I minimum +space between columns, +not the fixed gutter width of AT&T +.IR ms . +. +. +.IP \[bu] +The AT&T +.I ms +manual did not document the +.B QI +register; +Berkeley and +.I "groff ms" +do. +. +. +.IP \[bu] +The register +.B GS +is set to\~1 by the +.I groff ms +macros, +but is not used by the AT&T +.I ms +package. +. +Documents that need to determine whether they are being formatted with +.I groff ms +or another implementation should test this register. +. +. +.\" ==================================================================== +.SS "Unix Version\~7 macros not implemented by \f[I]groff ms\f[]" +.\" ==================================================================== +. +Several macros described in the Unix Version\~7 +.I ms +documentation are unimplemented by +.I groff ms +because they are specific to the requirements of documents produced +internally by Bell Laboratories, +some of which also require a glyph for the Bell System logo that +.I groff +does not support. +. +These macros implemented several document type formats +(\c +.BR EG , \" engineer's notes +.BR IM , \" internal memorandum +.BR MF , \" memorandum for file +.BR MR , \" memorandum for record +.BR TM , \" technical memorandum +.BR TR ), \" technical report +were meaningful only in conjunction with the use of certain document +types +(\c +.BR AT , \" attachments +.BR CS , \" cover sheet info for `TM` documents +.BR CT , \" copies to +.BR OK , \" "other keywords" for `TM` documents +.BR SG ), \" signatures for `TM` documents +stored the postal addresses of Bell Labs sites +(\c +.BR HO , \" Holmdel +.BR IH , \" Naperville +.BR MH , \" Murray Hill +.BR PY , \" Piscataway +.BR WH ), \" Whippany +or lacked a stable definition over time +(\c +.BR UX ). \" Unix; on 1st use, add footnote identifying trademark owner +. +. +.\" ==================================================================== +.SH "Legacy features" +.\" ==================================================================== +. +.I "groff ms" +retains some legacy features solely to support formatting of historical +documents; +contemporary ones should not use them because they can render poorly. +. +See +.MR groff_char 7 +instead. +. +. +.\" ==================================================================== +.SS "AT&T \f[I]ms\f[] accent mark strings" +.\" ==================================================================== +. +AT&T +.I ms +defined +accent mark strings as follows. +. +. +.P +.TS +Cb Lb +Lf(CR) L. +String Description +_ +\[rs]*[\[aq]] Apply acute accent to subsequent glyph. +\[rs]*[\[ga]] Apply grave accent to subsequent glyph. +\[rs]*[:] Apply dieresis (umlaut) to subsequent glyph. +\[rs]*[\[ha]] Apply circumflex accent to subsequent glyph. +\[rs]*[\[ti]] Apply tilde accent to subsequent glyph. +\[rs]*[C] Apply caron to subsequent glyph. +.\" \*v was an undocumented (in Lesk 1978-11-13) synonym for \*C. +\[rs]*[,] Apply cedilla to subsequent glyph. +.TE +. +. +.\" ==================================================================== +.SS "Berkeley \f[I]ms\f[] accent mark and glyph strings" +.\" ==================================================================== +. +Berkeley +.I ms +offered an +.B AM +macro; +calling it redefined the AT&T accent mark strings +(except for +.BR \[rs]*C ), +applied them to the +.I preceding +glyph, +and defined additional strings, +some for spacing glyphs. +. +. +.TP +.B .AM +Enable alternative accent mark and glyph-producing strings. +. +. +.P +.TS +Cb Lb +Lf(CR) L. +String Description +_ +\[rs]*[\[aq]] Apply acute accent to preceding glyph. +\[rs]*[\[ga]] Apply grave accent to preceding glyph. +\[rs]*[:] Apply dieresis (umlaut) to preceding glyph. +\[rs]*[\[ha]] Apply circumflex accent to preceding glyph. +\[rs]*[\[ti]] Apply tilde accent to preceding glyph. +\[rs]*[,] Apply cedilla to preceding glyph. +\[rs]*[/] Apply stroke (slash) to preceding glyph. +\[rs]*[v] Apply caron to preceding glyph. +\[rs]*[_] Apply macron to preceding glyph. +\[rs]*[.] Apply underdot to preceding glyph. +\[rs]*[o] Apply ring accent to preceding glyph. +_ +\[rs]*[?] Interpolate inverted question mark. +\[rs]*[!] Interpolate inverted exclamation mark. +\[rs]*[8] Interpolate small letter sharp s. +\[rs]*[q] Interpolate small letter o with hook accent (ogonek). +\[rs]*[3] Interpolate small letter yogh. +\[rs]*[d-] Interpolate small letter eth. +\[rs]*[D-] Interpolate capital letter eth. +\[rs]*[th] Interpolate small letter thorn. +\[rs]*[TH] Interpolate capital letter thorn. +\[rs]*[ae] Interpolate small ae ligature. +\[rs]*[AE] Interpolate capital ae ligature. +\[rs]*[oe] Interpolate small oe ligature. +\[rs]*[OE] Interpolate capital oe ligature. +.TE +. +. +.\" ==================================================================== +.SH "Naming conventions" +.\" ==================================================================== +. +The following conventions are used for names of macros, +strings, +and registers. +. +External names available to documents that use the +.I groff ms +macros contain only uppercase letters and digits. +. +. +.LP +Internally, +the macros are divided into modules. +. +Conventions for identifier names are as follows. +. +.IP \[bu] 3n +Names used only within one module are of the form +.IB \%module * name\c +\&. +. +.IP \[bu] +Names used outside the module in which they are defined are of the form +.IB \%module @ name\c +\&. +. +.IP \[bu] +Names associated with a particular environment are of the form +.IB \%environment : name\c +\&; +these are used only within the +.B par +module. +. +.IP \[bu] +.I name +does not have a module prefix. +. +.IP \[bu] +Constructed names used to implement arrays are of the form +.IB \%array ! index\c +\&. +. +. +.PP +Thus the +.I groff ms +macros reserve the following names: +. +.IP \[bu] 3n +Names containing the characters +.BR * , +.BR @ , +and\~\c +.BR : . +. +.IP \[bu] +Names containing only uppercase letters and digits. +. +. +.\" ==================================================================== +.SH Files +.\" ==================================================================== +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:\%s\:.tmac +implements the package. +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/refer\-ms.tmac +implements +.MR \%refer 1 +support for +.IR ms . +. +. +.TP +.I /usr/\:\%share/\:\%groff/\:\%1.23.0/\:\%tmac/\:ms\:.tmac +is a wrapper enabling the package to be loaded with +.RB \[lq] "groff \-m ms" \[rq]. +. +. +. +.\" ==================================================================== +.SH Authors +.\" ==================================================================== +. +The GNU version of the +.I ms +macro package was written by James Clark and contributors. +. +This document was written by Clark, +.MT lkollar@\:despammed\:.com +Larry Kollar +.ME , +and +.MT g.branden\:.robinson@\:gmail\:.com +G.\& Branden Robinson +.ME . +. +. +.br +.ne 8v +.\" ==================================================================== +.SH "See also" +.\" ==================================================================== +. +A manual is available in source and rendered form. +. +On your system, +it may be compressed and/or available in additional formats. +. +. +.TP +.I /usr/\:\%share/\:\%doc/\:\%packages/\:\%groff/\:ms\:.ms +.TQ +.I /usr/\:\%share/\:\%doc/\:\%packages/\:\%groff/\:ms\:.ps +\[lq]Using +.I groff +with the +.I ms +Macro Package\[rq]; +Larry Kollar and \%G.\~Branden Robinson. +. +. +.br +.ne 5v +.TP +.I /usr/\:\%share/\:\%doc/\:\%packages/\:\%groff/\:\%msboxes\:.ms +.TQ +.I /usr/\:\%share/\:\%doc/\:\%packages/\:\%groff/\:\%msboxes\:.pdf +\[lq]Using PDF boxes with +.I groff +and the +.I ms +macros\[rq]; +Deri James. +. +.B \%BOXSTART +and +.B \%BOXSTOP +macros are available via the +.I sboxes +extension package, +enabling colored, +bordered boxes when the +.B pdf +output device is used. +. +. +.PP +.IR "Groff: The GNU Implementation of troff" , +by Trent A.\& Fisher and Werner Lemberg, +is the primary +.I groff +manual. +. +You can browse it interactively with \[lq]info groff\[rq]. +. +. +.PP +.MR groff 1 , +.MR \%troff 1 , +.MR \%tbl 1 , +.MR \%pic 1 , +.MR \%eqn 1 , +.MR \%refer 1 +. +. +.\" Restore compatibility mode (for, e.g., Solaris 10/11). +.cp \n[*groff_groff_ms_7_man_C] +.do rr *groff_groff_ms_7_man_C +. +. +.\" Local Variables: +.\" fill-column: 72 +.\" mode: nroff +.\" End: +.\" vim: set filetype=groff textwidth=72: |