From 4c968838fd7d9b3eeca1b928eeb82352a28c47b8 Mon Sep 17 00:00:00 2001 From: Werner LEMBERG Date: Sun, 4 Sep 2005 09:41:37 +0000 Subject: [PATCH] * tmac/groff_ms.man, doc/groff.texinfo: Synchronize. * tmac/groff_ms.man: Document `PO' better. * NEWS: Document grotty changes. --- ChangeLog | 18 +- NEWS | 5 + doc/groff.texinfo | 1026 +++++++++++++++++++++++++++++------------------------ tmac/groff_ms.man | 55 ++- 4 files changed, 627 insertions(+), 477 deletions(-) diff --git a/ChangeLog b/ChangeLog index a4626637..acd9d435 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,15 @@ +2005-09-04 Werner LEMBERG + + * tmac/groff_ms.man, doc/groff.texinfo: Synchronize. + +2005-09-04 Jörgen Grahn + + * tmac/groff_ms.man: Document `PO' better. + +2005-09-03 Werner LEMBERG + + * NEWS: Document grotty changes. + 2005-09-01 Keith Marshall Backward compatibility support for `man' program. @@ -14,7 +26,7 @@ * tmac/groff_mdoc.man: Go into more details how the `AUTHORS' section should look like. -2005-08-29 Werner Lemberg +2005-08-29 Werner LEMBERG * tmac/groff_mdoc.man: The month's name in a call to .Dd shouldn't be abbreviated. @@ -1911,7 +1923,7 @@ * arch/misc/Makefile.sub (shdeps.sed): Don't use `$<' in explicit rule. -2005-05-14 Werner LEMBERG +2004-05-14 Werner LEMBERG * REVISION: Set to 2. @@ -1924,7 +1936,7 @@ * src/libs/libgroff/tmpname.cpp: Don't include stdint.h but inttypes.h conditionally. -2003-05-13 Werner LEMBERG +2004-05-13 Werner LEMBERG Version 1.19.1 released ======================= diff --git a/NEWS b/NEWS index 2e3f08ee..0272def4 100644 --- a/NEWS +++ b/NEWS @@ -65,6 +65,11 @@ o New command line option `-s' to set the base point size. o New command line option `-S' to set the split level while generating multiple files. + +Grotty +------ + +o Experimental support for zero-width and double-width characters. Gxditview --------- diff --git a/doc/groff.texinfo b/doc/groff.texinfo index e4d90b6f..a23993ea 100644 --- a/doc/groff.texinfo +++ b/doc/groff.texinfo @@ -372,22 +372,26 @@ Software Foundation raise funds for GNU development.'' @end macro -@c We need special parentheses and brackets: +@c We need special parentheses, brackets, and braces: @c @c . Real parentheses in @deffn produce an error while compiling with @c TeX. @c . Real brackets use the wrong font in @deffn, overriding @t{}. @c +@c . @{ and @} fail with info if used in a macro. +@c @c Since macros aren't expanded in @deffn during -E, the following @c definitions are for non-TeX only. @c -@c This is true for texinfo 4.0. +@c This is true for texinfo 4.0 and above. @iftex @set Lparenmacro @lparen @set Rparenmacro @rparen @set Lbrackmacro @lbrack @set Rbrackmacro @rbrack +@set Lbracemacro @{ +@set Rbracemacro @} @end iftex @ifnottex @@ -395,6 +399,8 @@ Software Foundation raise funds for GNU development.'' @set Rparenmacro ) @set Lbrackmacro [ @set Rbrackmacro ] +@set Lbracemacro @{ +@set Rbracemacro @} @end ifnottex @macro Lparen{} @@ -409,6 +415,12 @@ Software Foundation raise funds for GNU development.'' @macro Rbrack{} @value{Rbrackmacro} @end macro +@macro Lbrace{} +@value{Lbracemacro} +@end macro +@macro Rbrace{} +@value{Rbracemacro} +@end macro @c This suppresses the word `Appendix' in the appendix headers. @@ -480,6 +492,29 @@ Software Foundation raise funds for GNU development.'' @end ifinfo @ifhtml +@menu +* Introduction:: +* Invoking groff:: +* Tutorial for Macro Users:: +* Macro Packages:: +* gtroff Reference:: +* Preprocessors:: +* Output Devices:: +* File formats:: +* Installation:: +* Copying This Manual:: +* Request Index:: +* Escape Index:: +* Operator Index:: +* Register Index:: +* Macro Index:: +* String Index:: +* Glyph Name Index:: +* Font File Keyword Index:: +* Program and File Index:: +* Concept Index:: +@end menu + @node Top, Introduction, (dir), (dir) @top GNU troff @@ -2148,8 +2183,8 @@ restrictions, 2@tie{} to not hyphenate the last word on a page, values are additive; the default is@tie{}14. @item -rIN=@var{length} -Set the body text indent to @var{length}. -If not specified, the indent defaults to 7@dmn{n} +Set the body text indentation to @var{length}. +If not specified, the indentation defaults to 7@dmn{n} (7@tie{}characters) in nroff mode and 7.2@dmn{n} otherwise. For nroff, this value should always be an integer multiple of unit @samp{n} to get consistent indentation. @@ -2186,8 +2221,8 @@ Use @var{xx} (which can be 10, 11, or@tie{}12@dmn{pt}) as the base document font size instead of the default value of@tie{}10@dmn{pt}. @item -rSN=@var{length} -Set the indent for sub-subheadings to @var{length}. -If not specified, the indent defaults to 3@dmn{n}. +Set the indentation for sub-subheadings to @var{length}. +If not specified, the indentation defaults to 3@dmn{n}. @item -rX@var{nnn} After page @var{nnn}, number pages as @var{nnn}a, @var{nnn}b, @@ -2746,12 +2781,10 @@ at the command line). @section @file{ms} @cindex @code{ms} macros -The @file{-ms} -macros are suitable for reports, letters, books, -user manuals, and so forth. -The package provides macros for cover pages, section headings, -paragraphs, lists, footnotes, pagination, -and a table of contents. +The @file{-ms} macros are suitable for reports, letters, books, user +manuals, and so forth. The package provides macros for cover pages, +section headings, paragraphs, lists, footnotes, pagination, and a +table of contents. @menu * ms Intro:: @@ -2761,6 +2794,7 @@ and a table of contents. * ms Body Text:: * ms Page Layout:: * Differences from AT&T ms:: +* Naming Conventions:: @end menu @c --------------------------------------------------------------------- @@ -2768,19 +2802,16 @@ and a table of contents. @node ms Intro, General ms Structure, ms, ms @subsection Introduction to @file{ms} -The original @file{-ms} macros were included with -@acronym{AT&T} @code{troff} as well as the -@file{man} macros. -While the @file{man} package is intended for brief documents -that can be read on-line as well as printed, the @file{ms} -macros are suitable for longer documents that are meant to be -printed rather than read on-line. +The original @file{-ms} macros were included with @acronym{AT&T} +@code{troff} as well as the @file{man} macros. While the @file{man} +package is intended for brief documents that can be read on-line as +well as printed, the @file{ms} macros are suitable for longer +documents that are meant to be printed rather than read on-line. -The @file{ms} macro package included with @code{groff} -is a complete, bottom-up re-implementation. -Several macros (specific to @acronym{AT&T} -or Berkeley) are not included, while several new commands are. -@xref{Differences from AT&T ms}, for more information. +The @file{ms} macro package included with @code{groff} is a complete, +bottom-up re-implementation. Several macros (specific to +@acronym{AT&T} or Berkeley) are not included, while several new +commands are. @xref{Differences from AT&T ms}, for more information. @c --------------------------------------------------------------------- @@ -2788,64 +2819,51 @@ or Berkeley) are not included, while several new commands are. @subsection General structure of an @file{ms} document @cindex @code{ms} macros, general structure -The @file{ms} macro package expects a certain amount of structure, -but not as much as packages such as @file{man} or @file{mdoc}. +The @file{ms} macro package expects a certain amount of structure, but +not as much as packages such as @file{man} or @file{mdoc}. -The simplest documents can begin with a paragraph macro -(such as @code{LP} or @code{PP}), -and consist of text separated by paragraph macros -or even blank lines. -Longer documents have a structure as follows: +The simplest documents can begin with a paragraph macro (such as +@code{LP} or @code{PP}), and consist of text separated by paragraph +macros or even blank lines. Longer documents have a structure as +follows: @table @strong @item Document type -If you invoke the @code{RP} -(report) macro on the first line of the document, -@code{groff} prints the cover page information on its own page; -otherwise it prints the information on the -first page with your document text immediately following. -Other document formats found in @acronym{AT&T} @code{troff} -are specific to @acronym{AT&T} or Berkeley, and are not supported in -@code{groff}. +If you invoke the @code{RP} (report) macro on the first line of the +document, @code{groff} prints the cover page information on its own +page; otherwise it prints the information on the first page with your +document text immediately following. Other document formats found in +@acronym{AT&T} @code{troff} are specific to @acronym{AT&T} or +Berkeley, and are not supported in @code{groff}. @item Format and layout -By setting number registers, -you can change your document's type (font and size), -margins, spacing, headers and footers, and footnotes. +By setting number registers, you can change your document's type (font +and size), margins, spacing, headers and footers, and footnotes. @xref{ms Document Control Registers}, for more details. @item Cover page A cover page consists of a title, the author's name and institution, -an abstract, and the date. -@footnote{Actually, only the title is required.} -@xref{ms Cover Page Macros}, for more details. +an abstract, and the date.@footnote{Actually, only the title is +required.} @xref{ms Cover Page Macros}, for more details. @item Body -Following the cover page is your document. -You can use the @file{ms} -macros to write reports, letters, books, and so forth. -The package is designed for structured documents, -consisting of paragraphs interspersed with headings -and augmented by lists, footnotes, tables, and other -common constructs. -@xref{ms Body Text}, for more details. +Following the cover page is your document. You can use the @file{ms} +macros to write reports, letters, books, and so forth. The package is +designed for structured documents, consisting of paragraphs +interspersed with headings and augmented by lists, footnotes, tables, +and other common constructs. @xref{ms Body Text}, for more details. @item Table of contents -Longer documents usually include a table of contents, -which you can invoke by placing the -@code{TC} -macro at the end of your document. -The @file{ms} -macros have minimal indexing facilities, consisting of the -@code{IX} macro, which prints an entry on standard error. +Longer documents usually include a table of contents, which you can +invoke by placing the @code{TC} macro at the end of your document. +The @file{ms} macros have minimal indexing facilities, consisting of +the @code{IX} macro, which prints an entry on standard error. Printing the table of contents at the end is necessary since -@code{groff} is a single-pass text formatter, -thus it cannot determine the page number of each section -until that section has actually been set and printed. -Since @file{ms} output is intended for hardcopy, -you can manually relocate the pages containing -the table of contents between the cover page and the -body text after printing. +@code{groff} is a single-pass text formatter, thus it cannot determine +the page number of each section until that section has actually been +set and printed. Since @file{ms} output is intended for hardcopy, you +can manually relocate the pages containing the table of contents +between the cover page and the body text after printing. @end table @c --------------------------------------------------------------------- @@ -2854,21 +2872,19 @@ body text after printing. @subsection Document control registers @cindex @code{ms} macros, document control registers -The following is a list of document control number registers. -For the sake of consistency, -set registers related to margins at the beginning of your document, -or just after the @code{RP} macro. -You can set other registers later in your document, -but you should keep them together at the beginning -to make them easy to find and edit as necessary. +The following is a list of document control number registers. For the +sake of consistency, set registers related to margins at the beginning +of your document, or just after the @code{RP} macro. You can set +other registers later in your document, but you should keep them +together at the beginning to make them easy to find and edit as +necessary. @unnumberedsubsubsec Margin Settings @Defmpreg {PO, ms} -Defines the page offset (i.e.@: the left margin). -There is no explicit right margin setting; the combination of -the @code{PO} and @code{LL} registers implicitly define the -right margin width. +Defines the page offset (i.e., the left margin). There is no explicit +right margin setting; the combination of the @code{PO} and @code{LL} +registers implicitly define the right margin width. Effective: next page. @@ -2876,7 +2892,7 @@ Default value: 1@dmn{i}. @endDefmpreg @Defmpreg {LL, ms} -Defines the line length (i.e.@: the width of the body text). +Defines the line length (i.e., the width of the body text). Effective: next paragraph. @@ -2884,8 +2900,8 @@ Default: 6@dmn{i}. @endDefmpreg @Defmpreg {LT, ms} -Defines the title length (i.e.@: the header and footer width). -This is usually the same as @code{LL}, but not necessarily. +Defines the title length (i.e., the header and footer width). This +is usually the same as @code{LL}, but not necessarily. Effective: next paragraph. @@ -2911,9 +2927,10 @@ Default: 1@dmn{i}. @unnumberedsubsubsec Text Settings @Defmpreg {PS, ms} -Defines the point size of the body text. If the value is larger than or -equal to 1000, divide it by 1000 to get a fractional point size. For -example, @samp{.nr PS 10250} sets the document's point size to 10.25@dmn{p}. +Defines the point size of the body text. If the value is larger than +or equal to 1000, divide it by 1000 to get a fractional point size. +For example, @samp{.nr PS 10250} sets the document's point size to +10.25@dmn{p}. Effective: next paragraph. @@ -2921,10 +2938,10 @@ Default: 10@dmn{p}. @endDefmpreg @Defmpreg {VS, ms} -Defines the space between lines (line height plus leading). If the value -is larger than or equal to 1000, divide it by 1000 to get a fractional point -size. Due to backwards compatibility, @code{VS} must be smaller than -40000 (this is 40.0@dmn{p}). +Defines the space between lines (line height plus leading). If the +value is larger than or equal to 1000, divide it by 1000 to get a +fractional point size. Due to backwards compatibility, @code{VS} must +be smaller than 40000 (this is 40.0@dmn{p}). Effective: next paragraph. @@ -2933,10 +2950,11 @@ Default: 12@dmn{p}. @Defmpreg {PSINCR, ms} Defines an increment in point size, which will be applied to section -headings at nesting levels below the value specified in @code{GROWPS}. The -value of @code{PSINCR} should be specified in points, with the @dmn{p} -scaling factor, and may include a fractional component; for example, -@w{@samp{.nr PSINCR 1.5p}} sets a point size increment of 1.5@dmn{p}. +headings at nesting levels below the value specified in @code{GROWPS}. +The value of @code{PSINCR} should be specified in points, with the +@dmn{p} scaling factor, and may include a fractional component; for +example, @w{@samp{.nr PSINCR 1.5p}} sets a point size increment of +1.5@dmn{p}. Effective: next section heading. @@ -2945,11 +2963,12 @@ Default: 1@dmn{p}. @Defmpreg {GROWPS, ms} Defines the heading level below which the point size increment set by -@code{PSINCR} becomes effective. Section headings at and above the level -specified by @code{GROWPS} will be printed at the point size set by @code{PS}; -for each level below the value of @code{GROWPS}, the point size will be -increased in steps equal to the value of @code{PSINCR}. Setting @code{GROWPS} -to any value less than@tie{}2 disables the incremental heading size feature. +@code{PSINCR} becomes effective. Section headings at and above the +level specified by @code{GROWPS} will be printed at the point size set +by @code{PS}; for each level below the value of @code{GROWPS}, the +point size will be increased in steps equal to the value of +@code{PSINCR}. Setting @code{GROWPS} to any value less than@tie{}2 +disables the incremental heading size feature. Effective: next section heading. @@ -2957,9 +2976,9 @@ Default: 0. @endDefmpreg @Defmpreg {HY, ms} -Defines the hyphenation level. @code{HY} sets safely the value of the -low-level @code{.hy} register. Setting the value of @code{HY} to 0 is -equivalent to using the @code{.nh} request. +Defines the hyphenation level. @code{HY} sets safely the value of the +low-level @code{hy} register. Setting the value of @code{HY} +to@tie{}0 is equivalent to using the @code{nh} request. Effective: next paragraph. @@ -2977,7 +2996,7 @@ Default: as defined in the output device. @unnumberedsubsubsec Paragraph Settings @Defmpreg {PI, ms} -Defines the initial indent of a @code{.PP} paragraph. +Defines the initial indentation of a (@code{PP} macro) paragraph. Effective: next paragraph. @@ -2993,7 +3012,8 @@ Default: 0.3@dmn{v}. @endDefmpreg @Defmpreg {QI, ms} -Defines the indent on both sides of a quoted (@code{.QP}) paragraph. +Defines the indentation on both sides of a quoted (@code{QP} macro) +paragraph. Effective: next paragraph. @@ -3001,11 +3021,12 @@ Default: 5@dmn{n}. @endDefmpreg @Defmpreg {PORPHANS, ms} -Defines the minimum number of initial lines of any paragraph which should -be kept together, to avoid orphan 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 @code{PORPHANS} lines before an automatic page break, -then the page break will be forced, before the start of the paragraph. +Defines the minimum number of initial lines of any paragraph which +should be kept together, to avoid orphan 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 @code{PORPHANS} lines +before an automatic page break, then the page break will be forced, +before the start of the paragraph. Effective: next paragraph. @@ -3013,12 +3034,13 @@ Default: 1. @endDefmpreg @Defmpreg {HORPHANS, ms} -Defines the minimum number of lines of the following paragraph which should -be kept together with any section heading introduced by the @code{NH} or -@code{SH} macros. If a section heading is placed close to the bottom of a -page, and there is insufficient space to accommodate both the heading and -at least @code{HORPHANS} lines of the following paragraph, before an -automatic page break, then the page break will be forced before the heading. +Defines the minimum number of lines of the following paragraph which +should be kept together with any section heading introduced by the +@code{NH} or @code{SH} macros. If a section heading is placed close +to the bottom of a page, and there is insufficient space to +accommodate both the heading and at least @code{HORPHANS} lines of the +following paragraph, before an automatic page break, then the page +break will be forced before the heading. Effective: next paragraph. @@ -3036,7 +3058,7 @@ Default: @math{@code{@\n[LL]} * 5 / 6}. @endDefmpreg @Defmpreg {FI, ms} -Defines the footnote indent. +Defines the footnote indentation. Effective: next footnote. @@ -3047,17 +3069,18 @@ Default: 2@dmn{n}. The footnote format: @table @code @item 0 -Prints the footnote number as a superscript; indents the footnote (default). +Print the footnote number as a superscript; indent the footnote +(default). @item 1 -Prints the number followed by a period (like 1.) -and indents the footnote. +Print the number followed by a period (like 1.@:) and indent the +footnote. @item 2 -Like 1, without an indent. +Like 1, without an indentation. @item 3 -Like 1, but prints the footnote number as a hanging paragraph. +Like 1, but print the footnote number as a hanging paragraph. @end table Effective: next footnote. @@ -3066,8 +3089,8 @@ Default: 0. @endDefmpreg @Defmpreg {FPS, ms} -Defines the footnote point size. If the value is larger than or equal to -1000, divide it by 1000 to get a fractional point size. +Defines the footnote point size. If the value is larger than or equal +to 1000, divide it by 1000 to get a fractional point size. Effective: next footnote. @@ -3075,8 +3098,8 @@ Default: @math{@code{@\n[PS]} - 2}. @endDefmpreg @Defmpreg {FVS, ms} -Defines the footnote vertical spacing. If the value is larger than or equal -to 1000, divide it by 1000 to get a fractional point size. +Defines the footnote vertical spacing. If the value is larger than or +equal to 1000, divide it by 1000 to get a fractional point size. Effective: next footnote. @@ -3108,45 +3131,47 @@ Default: 2@dmn{n}. @cindex @code{ms} macros, cover page @cindex cover page macros, [@code{ms}] -Use the following macros to create a cover page for your document -in the order shown. +Use the following macros to create a cover page for your document in +the order shown. @Defmac {RP, [@code{no}], ms} -Specifies the report format for your document. -The report format creates a separate cover page. -The default action (no @code{.RP} -macro) is to print a subset of the -cover page on page 1 of your document. - -If you use the word @code{no} as an optional argument, -@code{groff} prints a title page but -does not repeat any of the title page information -(title, author, abstract, etc.) -on page 1 of the document. +Specifies the report format for your document. The report format +creates a separate cover page. The default action (no @code{RP} +macro) is to print a subset of the cover page on page@tie{}1 of your +document. + +If you use the word @code{no} as an optional argument, @code{groff} +prints a title page but does not repeat any of the title page +information (title, author, abstract, etc.@:) on page@tie{}1 of the +document. +@endDefmac + +@Defmac {P1, , ms} +(P-one) Prints the header on page@tie{}1. The default is to suppress +the header. @endDefmac @Defmac {DA, [@dots{}], ms} -(optional) Print the current date, or the arguments to the macro if any, -on the title page (if specified) and in the footers. -This is the default for @code{nroff}. +(optional) Prints the current date, or the arguments to the macro if +any, on the title page (if specified) and in the footers. This is the +default for @code{nroff}. @endDefmac @Defmac {ND, [@dots{}], ms} -(optional) Print the current date, or the arguments to the macro if any, -on the title page (if specified) but not in the footers. -This is the default for @code{troff}. +(optional) Prints the current date, or the arguments to the macro if +any, on the title page (if specified) but not in the footers. This is +the default for @code{troff}. @endDefmac @Defmac {TL, , ms} -Specifies the document title. -@code{groff} collects text following the @code{.TL} -macro into the title, until reaching the author name or abstract. +Specifies the document title. @code{groff} collects text following +the @code{TL} macro into the title, until reaching the author name or +abstract. @endDefmac @Defmac {AU, , ms} -Specifies the author's name, which appears on the -line (or lines) immediately following. -You can specify multiple authors as follows: +Specifies the author's name, which appears on the line (or lines) +immediately following. You can specify multiple authors as follows: @Example .AU @@ -3163,20 +3188,19 @@ Monolithic Corporation @endDefmac @Defmac {AI, , ms} -Specifies the author's institution. -You can specify multiple institutions in the same way -that you specify multiple authors. +Specifies the author's institution. You can specify multiple +institutions in the same way that you specify multiple authors. @endDefmac @Defmac {AB, [@code{no}], ms} -Begins the abstract. -The default is to print the word @acronym{ABSTRACT}, -centered and in italics, above the text of the abstract. -The word @code{no} as an optional argument suppresses this heading. +Begins the abstract. The default is to print the word +@acronym{ABSTRACT}, centered and in italics, above the text of the +abstract. The word @code{no} as an optional argument suppresses this +heading. @endDefmac @Defmac {AE, , ms} -End the abstract. +Ends the abstract. @endDefmac The following is example mark-up for a title page. @@ -3221,15 +3245,15 @@ user demand. @subsection Body text @cindex @code{ms} macros, body text -This section describes macros used to mark up the body of your document. -Examples include paragraphs, sections, and other groups. +This section describes macros used to mark up the body of your +document. Examples include paragraphs, sections, and other groups. @menu * Paragraphs in ms:: * Headings in ms:: * Highlighting in ms:: * Lists in ms:: -* Indents in ms:: +* Indentation values in ms:: * Tabstops in ms:: * ms Displays and Keeps:: * ms Insertions:: @@ -3245,23 +3269,19 @@ Examples include paragraphs, sections, and other groups. The following paragraph types are available. -@Defmac {PP, , ms} -Sets a paragraph with an initial indent. -@endDefmac - -@Defmac {LP, , ms} -Sets a paragraph with no initial indent. +@DefmacList {PP, , ms} +@DefmacListEnd {LP, , ms} +Sets a paragraph with an initial indentation. @endDefmac @Defmac {QP, , ms} -Sets a paragraph that is indented at both left and right margins. -The effect is identical to the @acronym{HTML} @code{
} element. +Sets a paragraph that is indented at both left and right margins. The +effect is identical to the @acronym{HTML} @code{
} element. The next paragraph or heading returns margins to normal. @endDefmac @Defmac {XP, , ms} -Sets a paragraph whose lines are indented, -except for the first line. +Sets a paragraph whose lines are indented, except for the first line. This is a Berkeley extension. @endDefmac @@ -3312,21 +3332,20 @@ printing of orphan lines at the bottom of any page. @cindex @code{ms} macros, headings Use headings to create a hierarchical structure for your document. -The @file{ms} macros print headings in @strong{bold}, -using the same font family and point size as the body text. +The @file{ms} macros print headings in @strong{bold}, using the same +font family and point size as the body text. The following describes the heading macros: @DefmacList {NH, @Var{curr-level}, ms} @DefmacListEnd {NH, @t{S} @Var{level0} @dots{}, ms} -Numbered heading. -The argument is either a numeric argument to indicate the -level of the heading, or the letter@tie{}@code{S} followed by numeric -arguments to set the heading level explicitly. +Numbered heading. The argument is either a numeric argument to +indicate the level of the heading, or the letter@tie{}@code{S} +followed by numeric arguments to set the heading level explicitly. If you specify heading levels out of sequence, such as invoking -@samp{.NH 3} after @samp{.NH 1}, @code{groff} -prints a warning on standard error. +@samp{.NH 3} after @samp{.NH 1}, @code{groff} prints a warning on +standard error. @endDefmac @DefstrList {SN, ms} @@ -3358,12 +3377,12 @@ omitted). The string @code{SN} is also defined, as an alias for @Defmac {SH, [@Var{match-level}], ms} Unnumbered subheading. -The optional @code{match-level} argument is a GNU extension. It is a +The optional @var{match-level} argument is a GNU extension. It is a number indicating the level of the heading, in a manner analogous to -the @code{curr-level} argument to @code{.NH}. Its purpose is to match +the @var{curr-level} argument to @code{.NH}. Its purpose is to match the point size, at which the heading is printed, to the size of a -numbered heading at the same level, when the @code{GROWPS}/@code{PSINCR} -heading size adjustment mechanism is in effect. +numbered heading at the same level, when the @code{GROWPS} and +@code{PSINCR} heading size adjustment mechanism is in effect. @xref{ms Document Control Registers}. @endDefmac @@ -3378,18 +3397,16 @@ page. @subsubsection Highlighting @cindex @code{ms} macros, highlighting -The @file{ms} macros provide a variety of methods to highlight -or emphasize text: +The @file{ms} macros provide a variety of methods to highlight or +emphasize text: @Defmac {B, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} -Sets its first argument in @strong{bold type}. -If you specify a second argument, @code{groff} prints it in the -previous font after the bold text, with no intervening space -(this allows you to set punctuation after the highlighted text -without highlighting the punctuation). -Similarly, it prints the third argument (if any) in the previous -font @strong{before} the first argument. -For example, +Sets its first argument in @strong{bold type}. If you specify a +second argument, @code{groff} prints it in the previous font after the +bold text, with no intervening space (this allows you to set +punctuation after the highlighted text without highlighting the +punctuation). Similarly, it prints the third argument (if any) in the +previous font @strong{before} the first argument. For example, @Example .B foo ) ( @@ -3397,83 +3414,85 @@ For example, prints (@strong{foo}). -If you give this macro no arguments, @code{groff} -prints all text following in bold until -the next highlighting, paragraph, or heading macro. +If you give this macro no arguments, @code{groff} prints all text +following in bold until the next highlighting, paragraph, or heading +macro. @endDefmac @Defmac {R, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} -Sets its first argument in roman (or regular) type. -It operates similarly to the @code{B}@tie{}macro otherwise. +Sets its first argument in roman (or regular) type. It operates +similarly to the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {I, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} -Sets its first argument in @emph{italic type}. -It operates similarly to the @code{B}@tie{}macro otherwise. +Sets its first argument in @emph{italic type}. It operates similarly +to the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {CW, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} -Sets its first argument in a @code{constant width face}. -It operates similarly to the @code{B}@tie{}macro otherwise. +Sets its first argument in a @code{constant width face}. It operates +similarly to the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {BI, [@Var{txt} [@Var{post} [@Var{pre}]]], ms} -Sets its first argument in bold italic type. -It operates similarly to the @code{B}@tie{}macro otherwise. +Sets its first argument in bold italic type. It operates similarly to +the @code{B}@tie{}macro otherwise. @endDefmac @Defmac {BX, [@Var{txt}], ms} -Prints its argument and draws a box around it. -If you want to box a string that contains spaces, -use a digit-width space (@code{\0}). +Prints its argument and draws a box around it. If you want to box a +string that contains spaces, use a digit-width space (@code{\0}). @endDefmac @Defmac {UL, [@Var{txt} [@Var{post}]], ms} -Prints its first argument with an underline. -If you specify a second argument, @code{groff} -prints it in the previous font after -the underlined text, with no intervening space. +Prints its first argument with an underline. If you specify a second +argument, @code{groff} prints it in the previous font after the +underlined text, with no intervening space. @endDefmac @Defmac {LG, , ms} -Prints all text following in larger type -(two points larger than the current point size) until -the next font size, highlighting, paragraph, or heading macro. -You can specify this macro multiple times -to enlarge the point size as needed. +Prints all text following in larger type (two points larger than the +current point size) until the next font size, highlighting, paragraph, +or heading macro. You can specify this macro multiple times to +enlarge the point size as needed. @endDefmac @Defmac {SM, , ms} -Prints all text following in smaller type -(two points smaller than the current point size) until -the next type size, highlighting, paragraph, or heading macro. -You can specify this macro multiple times -to reduce the point size as needed. +Prints all text following in smaller type (two points smaller than the +current point size) until the next type size, highlighting, paragraph, +or heading macro. You can specify this macro multiple times to reduce +the point size as needed. @endDefmac @Defmac {NL, , ms} -Prints all text following in the normal point size -(that is, the value of the @code{PS} register). +Prints all text following in the normal point size (that is, the value +of the @code{PS} register). @endDefmac +@DefstrList {@Lbrace{}, ms} +@DefstrListEnd {@Rbrace{}, ms} +Text enclosed with @code{\*@{} and @code{\*@}} is printed as a +superscript. +@endDefstr + @c --------------------------------------------------------------------- -@node Lists in ms, Indents in ms, Highlighting in ms, ms Body Text +@node Lists in ms, Indentation values in ms, Highlighting in ms, ms Body Text @subsubsection Lists @cindex @code{ms} macros, lists -The @code{.IP} macro handles duties for all lists. +The @code{IP} macro handles duties for all lists. @Defmac {IP, [@Var{marker} [@Var{width}]], ms} -The @var{marker} is usually a bullet glyph (@code{\[bu]}) -for unordered lists, a number (or auto-incrementing number -register) for numbered lists, or a word or phrase for indented -(glossary-style) lists. +The @var{marker} is usually a bullet glyph (@code{\[bu]}) for +unordered lists, a number (or auto-incrementing number register) for +numbered lists, or a word or phrase for indented (glossary-style) +lists. -The @var{width} specifies the indent for the body of each list item; -its default unit is @samp{n}. -Once specified, the indent remains the same for all -list items in the document until specified again. +The @var{width} specifies the indentation for the body of each list +item; its default unit is @samp{n}. Once specified, the indentation +remains the same for all list items in the document until specified +again. The @code{PORPHANS} register (@pxref{ms Document Control Registers}) operates in conjunction with the @code{IP} macro, to inhibit the @@ -3506,8 +3525,6 @@ o guns o money @endExample -@sp 1 - The following is an example of a numbered list. @cindex example markup, numbered list [@code{ms}] @cindex numbered list, example markup [@code{ms}] @@ -3535,10 +3552,8 @@ A numbered list: 3. money @endExample -Note the use of the auto-incrementing number -register in this example. +Note the use of the auto-incrementing number register in this example. -@sp 1 The following is an example of a glossary-style list. @cindex example markup, glossary-style list [@code{ms}] @cindex glossary-style list, example markup [@code{ms}] @@ -3569,16 +3584,15 @@ money Gotta pay for those lawyers and guns! @endExample -In the last example, the @code{IP} macro places the definition -on the same line as the term if it has enough space; otherwise, -it breaks to the next line and starts the definition below the -term. -This may or may not be the effect you want, especially if some -of the definitions break and some do not. -The following examples show two possible ways to force a break. +In the last example, the @code{IP} macro places the definition on the +same line as the term if it has enough space; otherwise, it breaks to +the next line and starts the definition below the term. This may or +may not be the effect you want, especially if some of the definitions +break and some do not. The following examples show two possible ways +to force a break. -The first workaround uses the @code{br} -request to force a break after printing the term or label. +The first workaround uses the @code{br} request to force a break after +printing the term or label. @Example @cartouche @@ -3593,12 +3607,10 @@ Gotta pay for those lawyers and guns! @end cartouche @endExample -@sp 1 The second workaround uses the @code{\p} escape to force the break. -Note the space following the escape; this is important. -If you omit the space, @code{groff} prints the first word on -the same line as the term or label (if it fits) @strong{then} -breaks the line. +Note the space following the escape; this is important. If you omit +the space, @code{groff} prints the first word on the same line as the +term or label (if it fits) @strong{then} breaks the line. @Example @cartouche @@ -3612,9 +3624,8 @@ Gotta pay for those lawyers and guns! @end cartouche @endExample -@sp 1 To set nested lists, use the @code{RS} and @code{RE} macros. -@xref{Indents in ms}, for more information. +@xref{Indentation values in ms}, for more information. @cindex @code{ms} macros, nested lists @cindex nested lists [@code{ms}] @@ -3653,39 +3664,35 @@ o Guns @c --------------------------------------------------------------------- -@node Indents in ms, Tabstops in ms, Lists in ms, ms Body Text -@subsubsection Indents +@node Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text +@subsubsection Indentation values -In many situations, -you may need to indent a section of text -while still wrapping and filling. -@xref{Lists in ms}, -for an example of nested lists. +In many situations, you may need to indentation a section of text +while still wrapping and filling. @xref{Lists in ms}, for an example +of nested lists. @DefmacList {RS, , ms} @DefmacListEnd {RE, , ms} -These macros begin and end an indented section. -The @code{PI} register controls the amount of indent, -allowing the indented text to line up under hanging -and indented paragraphs. +These macros begin and end an indented section. The @code{PI} +register controls the amount of indentation, allowing the indented +text to line up under hanging and indented paragraphs. @endDefmac -@xref{ms Displays and Keeps}, -for macros to indent and turn off filling. +@xref{ms Displays and Keeps}, for macros to indentation and turn off +filling. @c --------------------------------------------------------------------- -@node Tabstops in ms, ms Displays and Keeps, Indents in ms, ms Body Text +@node Tabstops in ms, ms Displays and Keeps, Indentation values in ms, ms Body Text @subsubsection Tab Stops -Use the @code{ta} request to define tab stops as needed. -@xref{Tabs and Fields}. +Use the @code{ta} request to define tab stops as needed. @xref{Tabs +and Fields}. @Defmac{TA, , ms} Use this macro to reset the tab stops to the default for @file{ms} -(every 5n). -You can redefine the @code{TA} macro to create a different set -of default tab stops. +(every 5n). You can redefine the @code{TA} macro to create a +different set of default tab stops. @endDefmac @c --------------------------------------------------------------------- @@ -3697,119 +3704,107 @@ of default tab stops. @cindex keeps [@code{ms}] @cindex displays [@code{ms}] -Use displays to show text-based examples or figures -(such as code listings). +Use displays to show text-based examples or figures (such as code +listings). -Displays turn off filling, so lines of code are displayed -as-is without inserting @code{br} requests in between each line. -Displays can be @dfn{kept} on a single page, or allowed -to break across pages. +Displays turn off filling, so lines of code are displayed as-is +without inserting @code{br} requests in between each line. Displays +can be @dfn{kept} on a single page, or allowed to break across pages. @DefmacList {DS, @t{L}, ms} @DefmacItem {LD, , ms} @DefmacListEnd {DE, , ms} -Left-justified display. -The @samp{.DS L} call generates a page break, if necessary, -to keep the entire display on one page. -The @code{LD} macro allows the display to break across pages. -The @code{DE} macro ends the display. +Left-justified display. The @samp{.DS L} call generates a page break, +if necessary, to keep the entire display on one page. The @code{LD} +macro allows the display to break across pages. The @code{DE} macro +ends the display. @endDefmac @DefmacList {DS, @t{I}, ms} @DefmacItem {ID, , ms} @DefmacListEnd {DE, , ms} -Indents the display as defined by the @code{DI} register. -The @samp{.DS I} call generates a page break, if necessary, -to keep the entire display on one page. -The @code{ID} macro allows the display to break across pages. -The @code{DE} macro ends the display. +Indents the display as defined by the @code{DI} register. The +@samp{.DS I} call generates a page break, if necessary, to keep the +entire display on one page. The @code{ID} macro allows the display to +break across pages. The @code{DE} macro ends the display. @endDefmac @DefmacList {DS, @t{B}, ms} @DefmacItem {BD, , ms} @DefmacListEnd {DE, , ms} Sets a block-centered display: the entire display is left-justified, -but indented so that the longest line in the display is centered -on the page. -The @samp{.DS B} call generates a page break, if necessary, -to keep the entire display on one page. -The @code{BD} macro allows the display to break across pages. -The @code{DE} macro ends the display. +but indented so that the longest line in the display is centered on +the page. The @samp{.DS B} call generates a page break, if necessary, +to keep the entire display on one page. The @code{BD} macro allows +the display to break across pages. The @code{DE} macro ends the +display. @endDefmac @DefmacList {DS, @t{C}, ms} @DefmacItem {CD, , ms} @DefmacListEnd {DE, , ms} -Sets a centered display: each line in the display is centered. -The @samp{.DS C} call generates a page break, if necessary, -to keep the entire display on one page. -The @code{CD} macro allows the display to break across pages. -The @code{DE} macro ends the display. +Sets a centered display: each line in the display is centered. The +@samp{.DS C} call generates a page break, if necessary, to keep the +entire display on one page. The @code{CD} macro allows the display to +break across pages. The @code{DE} macro ends the display. @endDefmac @DefmacList {DS, @t{R}, ms} @DefmacItem {RD, , ms} @DefmacListEnd {DE, , ms} -Right-justifies each line in the display. -The @samp{.DS R} call generates a page break, if necessary, -to keep the entire display on one page. -The @code{RD} macro allows the display to break across pages. -The @code{DE} macro ends the display. +Right-justifies each line in the display. The @samp{.DS R} call +generates a page break, if necessary, to keep the entire display on +one page. The @code{RD} macro allows the display to break across +pages. The @code{DE} macro ends the display. @endDefmac @DefmacList {Ds, , ms} @DefmacListEnd {De, , ms} -These two macros were formerly provided as aliases for -@code{DS} and @code{DE}, respectively. -They have been removed, and should no longer be used. -The original implementations of @code{DS} and @code{DE} -are retained, and should be used instead. -X11 documents which actually use @code{Ds} and @code{De} always load a -specific macro file from the X11 distribution (@file{macros.t}) which -provides proper definitions for the two macros. +These two macros were formerly provided as aliases for @code{DS} and +@code{DE}, respectively. They have been removed, and should no longer +be used. The original implementations of @code{DS} and @code{DE} are +retained, and should be used instead. X11 documents which actually +use @code{Ds} and @code{De} always load a specific macro file from the +X11 distribution (@file{macros.t}) which provides proper definitions +for the two macros. @endDefmac -@sp 1 On occasion, you may want to @dfn{keep} other text together on a page. -For example, you may want to keep two paragraphs together, or -a paragraph that refers to a table (or list, or other item) -immediately following. -The @file{ms} macros provide the @code{KS} and @code{KE} +For example, you may want to keep two paragraphs together, or a +paragraph that refers to a table (or list, or other item) immediately +following. The @file{ms} macros provide the @code{KS} and @code{KE} macros for this purpose. @DefmacList {KS, , ms} @DefmacListEnd {KE, , ms} -The @code{KS} macro begins a block of text to be kept on a -single page, and the @code{KE} macro ends the block. +The @code{KS} macro begins a block of text to be kept on a single +page, and the @code{KE} macro ends the block. @endDefmac @DefmacList {KF, , ms} @DefmacListEnd {KE, , ms} -Specifies a @dfn{floating keep}; -if the keep cannot fit on the current page, @code{groff} -holds the contents of the keep and allows text following -the keep (in the source file) to fill in the remainder of -the current page. -When the page breaks, whether by an explicit @code{bp} -request or by reaching the end of the page, @code{groff} -prints the floating keep at the top of the new page. -This is useful for printing large graphics or tables -that do not need to appear exactly where specified. +Specifies a @dfn{floating keep}; if the keep cannot fit on the current +page, @code{groff} holds the contents of the keep and allows text +following the keep (in the source file) to fill in the remainder of +the current page. When the page breaks, whether by an explicit +@code{bp} request or by reaching the end of the page, @code{groff} +prints the floating keep at the top of the new page. This is useful +for printing large graphics or tables that do not need to appear +exactly where specified. @endDefmac -You can also use the @code{ne} request to force a page break if -there is not enough vertical space remaining on the page. +You can also use the @code{ne} request to force a page break if there +is not enough vertical space remaining on the page. -@sp 1 -Use the following macros to draw a box around a section of -text (such as a display). +Use the following macros to draw a box around a section of text (such +as a display). @DefmacList {B1, , ms} @DefmacListEnd {B2, , ms} -Marks the beginning and ending of text that is to have a -box drawn around it. -The @code{B1} macro begins the box; the @code{B2} macro ends it. -Text in the box is automatically placed in a diversion (keep). +Marks the beginning and ending of text that is to have a box drawn +around it. The @code{B1} macro begins the box; the @code{B2} macro +ends it. Text in the box is automatically placed in a diversion +(keep). @endDefmac @c --------------------------------------------------------------------- @@ -3825,8 +3820,7 @@ Text in the box is automatically placed in a diversion (keep). @cindex equations [@code{ms}] @cindex references [@code{ms}] -The @file{ms} macros support the standard -@code{groff} preprocessors: +The @file{ms} macros support the standard @code{groff} preprocessors: @code{tbl}, @code{pic}, @code{eqn}, and @code{refer}. @pindex tbl @pindex pic @@ -3837,21 +3831,20 @@ in pairs of tags as follows. @DefmacList {TS, [@code{H}], ms} @DefmacListEnd {TE, , ms} -Denotes a table, to be processed by the @code{tbl} preprocessor. -The optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} -to create a running header with the information -up to the @code{TH} macro. -@code{groff} prints the header at the beginning of the -table; if the table runs onto another page, @code{groff} -prints the header on the next page as well. +Denotes a table, to be processed by the @code{tbl} preprocessor. The +optional argument@tie{}@code{H} to @code{TS} instructs @code{groff} to +create a running header with the information up to the @code{TH} +macro. @code{groff} prints the header at the beginning of the table; +if the table runs onto another page, @code{groff} prints the header on +the next page as well. @endDefmac @DefmacList {PS, , ms} @DefmacListEnd {PE, , ms} Denotes a graphic, to be processed by the @code{pic} preprocessor. You can create a @code{pic} file by hand, using the @acronym{AT&T} -@code{pic} manual available on the Web as a reference, or by using -a graphics program such as @code{xfig}. +@code{pic} manual available on the Web as a reference, or by using a +graphics program such as @code{xfig}. @endDefmac @DefmacList {EQ, [@Var{align}], ms} @@ -3881,8 +3874,8 @@ database. @cindex example markup, multi-page table [@code{ms}] @cindex multi-page table, example markup [@code{ms}] -The following is an example of how to set up a -table that may print across two or more pages. +The following is an example of how to set up a table that may print +across two or more pages. @Example @cartouche @@ -3907,9 +3900,9 @@ l | l . @cindex @code{ms} macros, footnotes @cindex footnotes [@code{ms}] -The @file{ms} macro package has a flexible footnote system. -You can specify either numbered footnotes or symbolic footnotes -(that is, using a marker such as a dagger symbol). +The @file{ms} macro package has a flexible footnote system. You can +specify either numbered footnotes or symbolic footnotes (that is, +using a marker such as a dagger symbol). @Defstr {*, ms} Specifies the location of a numbered footnote marker in the text. @@ -3917,19 +3910,27 @@ Specifies the location of a numbered footnote marker in the text. @DefmacList {FS, , ms} @DefmacListEnd {FE, , ms} -Specifies the text of the footnote. -The default action is to create a numbered footnote; -you can create a symbolic footnote by specifying -a @dfn{mark} glyph -(such as @code{\[dg]} for the dagger glyph) -in the body text and as an argument to the @code{FS} macro, -followed by the text of the footnote -and the @code{FE} macro. +Specifies the text of the footnote. The default action is to create a +numbered footnote; you can create a symbolic footnote by specifying a +@dfn{mark} glyph (such as @code{\[dg]} for the dagger glyph) in the +body text and as an argument to the @code{FS} macro, followed by the +text of the footnote and the @code{FE} macro. @endDefmac -You can control how @code{groff} -prints footnote numbers by changing the value of the -@code{FF} register. @xref{ms Document Control Registers}. +You can control how @code{groff} prints footnote numbers by changing +the value of the @code{FF} register. @xref{ms Document Control +Registers}. + +@cindex footnotes, and keeps [@code{ms}] +@cindex keeps, and footnotes [@code{ms}] +@cindex footnotes, and displays [@code{ms}] +@cindex displays, and footnotes [@code{ms}] +Footnotes can be safely used within keeps and displays, but you should +avoid using numbered footnotes within floating keeps. You can set a +second @code{\**} marker between a @code{\**} and its corresponding +@code{.FS} entry; as long as each @code{FS} macro occurs @emph{after} +the corresponding @code{\**} and the occurrences of @code{.FS} are in +the same order as the corresponding occurrences of @code{\**}. @c --------------------------------------------------------------------- @@ -3938,14 +3939,12 @@ prints footnote numbers by changing the value of the @cindex @code{ms} macros, page layout @cindex page layout [@code{ms}] -The default output from the @file{ms} -macros provides a minimalist page layout: -it prints a single column, with the page number centered at the top -of each page. -It prints no footers. +The default output from the @file{ms} macros provides a minimalist +page layout: it prints a single column, with the page number centered +at the top of each page. It prints no footers. -You can change the layout by setting -the proper number registers and strings. +You can change the layout by setting the proper number registers and +strings. @menu * ms Headers and Footers:: @@ -3964,8 +3963,8 @@ the proper number registers and strings. @cindex headers [@code{ms}] @cindex footers [@code{ms}] -For documents that do not distinguish between odd and even pages, -set the following strings: +For documents that do not distinguish between odd and even pages, set +the following strings: @DefstrList {LH, ms} @DefstrItem {CH, ms} @@ -3979,17 +3978,17 @@ Sets the left, center, and right headers. Sets the left, center, and right footers. @endDefstr -@sp 1 -For documents that need different information printed in the -even and odd pages, use the following macros: +For documents that need different information printed in the even and +odd pages, use the following macros: @DefmacList {OH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} @DefmacItem {EH, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} @DefmacItem {OF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} @DefmacListEnd {EF, @t{'}@Var{left}@t{'}@Var{center}@t{'}@Var{right}@t{'}, ms} -The @code{OH} and @code{EH} macros define headers for the odd and even pages; -the @code{OF} and @code{EF} macros define footers for the odd and even pages. -This is more flexible than defining the individual strings. +The @code{OH} and @code{EH} macros define headers for the odd and even +pages; the @code{OF} and @code{EF} macros define footers for the odd +and even pages. This is more flexible than defining the individual +strings. You can replace the quote (@code{'}) marks with any character not appearing in the header or footer text. @@ -4001,8 +4000,8 @@ appearing in the header or footer text. @subsubsection Margins @cindex @code{ms} macros, margins -You control margins using a set of number registers. -@xref{ms Document Control Registers}, for details. +You control margins using a set of number registers. @xref{ms +Document Control Registers}, for details. @c --------------------------------------------------------------------- @@ -4012,11 +4011,10 @@ You control margins using a set of number registers. @cindex multiple columns [@code{ms}] The @file{ms} macros can set text in as many columns as will -reasonably fit on the page. -The following macros are available; -all of them force a page break if a multi-column mode is already set. +reasonably fit on the page. The following macros are available; all +of them force a page break if a multi-column mode is already set. However, if the current mode is single-column, starting a multi-column -mode does @strong{not} force a page break. +mode does @emph{not} force a page break. @Defmac {1C, , ms} Single-column mode. @@ -4027,12 +4025,10 @@ Two-column mode. @endDefmac @Defmac {MC, [@Var{width} [@Var{gutter}]], ms} -Multi-column mode. -If you specify no arguments, it is equivalent to the -@code{2C} macro. -Otherwise, @var{width} is the width of each column and -@var{gutter} is the space between columns. -The @code{MINGW} number register controls the default gutter width. +Multi-column mode. If you specify no arguments, it is equivalent to +the @code{2C} macro. Otherwise, @var{width} is the width of each +column and @var{gutter} is the space between columns. The +@code{MINGW} number register controls the default gutter width. @endDefmac @c --------------------------------------------------------------------- @@ -4042,22 +4038,19 @@ The @code{MINGW} number register controls the default gutter width. @cindex @code{ms} macros, creating table of contents @cindex table of contents, creating [@code{ms}] -The facilities in the @file{ms} macro package for creating -a table of contents are semi-automated at best. -Assuming that you want the table of contents to consist of -the document's headings, you need to repeat those headings -wrapped in @code{XS} and @code{XE} macros. +The facilities in the @file{ms} macro package for creating a table of +contents are semi-automated at best. Assuming that you want the table +of contents to consist of the document's headings, you need to repeat +those headings wrapped in @code{XS} and @code{XE} macros. @DefmacList {XS, [@Var{page}], ms} @DefmacItem {XA, [@Var{page}], ms} @DefmacListEnd {XE, , ms} -These macros define a table of contents -or an individual entry in the table of contents, -depending on their use. -The macros are very simple; they cannot indent a heading based on its level. -The easiest way to work around this is to add tabs -to the table of contents string. -The following is an example: +These macros define a table of contents or an individual entry in the +table of contents, depending on their use. The macros are very +simple; they cannot indent a heading based on its level. The easiest +way to work around this is to add tabs to the table of contents +string. The following is an example: @Example @cartouche @@ -4079,12 +4072,11 @@ Methodology @end cartouche @endExample -You can manually create a table of contents -by beginning with the @code{XS} macro for the first entry, -specifying the page number for that entry as the argument to @code{XS}. -Add subsequent entries using the @code{XA} macro, -specifying the page number for that entry as the argument to @code{XA}. -The following is an example: +You can manually create a table of contents by beginning with the +@code{XS} macro for the first entry, specifying the page number for +that entry as the argument to @code{XS}. Add subsequent entries using +the @code{XA} macro, specifying the page number for that entry as the +argument to @code{XA}. The following is an example: @Example @cartouche @@ -4101,34 +4093,32 @@ Details of Galactic Formation @endDefmac @Defmac {TC, [@code{no}], ms} -Prints the table of contents on a new page, -setting the page number to@tie{}@strong{i} (Roman numeral one). -You should usually place this macro at the end of the -file, since @code{groff} is a single-pass formatter and -can only print what has been collected up to the point -that the @code{TC} macro appears. - -The optional argument @code{no} suppresses printing -the title specified by the string register @code{TOC}. +Prints the table of contents on a new page, setting the page number +to@tie{}@strong{i} (Roman lowercase numeral one). You should usually +place this macro at the end of the file, since @code{groff} is a +single-pass formatter and can only print what has been collected up to +the point that the @code{TC} macro appears. + +The optional argument @code{no} suppresses printing the title +specified by the string register @code{TOC}. @endDefmac @Defmac{PX, [@code{no}], ms} -Prints the table of contents on a new page, -using the current page numbering sequence. -Use this macro to print a manually-generated table of contents -at the beginning of your document. +Prints the table of contents on a new page, using the current page +numbering sequence. Use this macro to print a manually-generated +table of contents at the beginning of your document. -The optional argument @code{no} suppresses printing -the title specified by the string register @code{TOC}. +The optional argument @code{no} suppresses printing the title +specified by the string register @code{TOC}. @endDefmac -The @cite{Groff and Friends HOWTO} -includes a @code{sed} script that automatically inserts -@code{XS} and @code{XE} macro entries after each heading in a document. +The @cite{Groff and Friends HOWTO} includes a @code{sed} script that +automatically inserts @code{XS} and @code{XE} macro entries after each +heading in a document. -Altering the @code{NH} macro to automatically build the table -of contents is perhaps initially more difficult, but would save -a great deal of time in the long run if you use @file{ms} regularly. +Altering the @code{NH} macro to automatically build the table of +contents is perhaps initially more difficult, but would save a great +deal of time in the long run if you use @file{ms} regularly. @c --------------------------------------------------------------------- @@ -4141,19 +4131,18 @@ a great deal of time in the long run if you use @file{ms} regularly. @cindex special characters [@code{ms}] @cindex strings [@code{ms}] -The @file{ms} macros provide the following predefined strings. -You can change the string definitions to help in creating -documents in languages other than English. +The @file{ms} macros provide the following predefined strings. You +can change the string definitions to help in creating documents in +languages other than English. @Defstr {REFERENCES, ms} -Contains the string printed at the beginning of the -references (bibliography) page. -The default is @samp{References}. +Contains the string printed at the beginning of the references +(bibliography) page. The default is @samp{References}. @endDefstr @Defstr {ABSTRACT, ms} -Contains the string printed at the beginning of the abstract. -The default is @samp{ABSTRACT}. +Contains the string printed at the beginning of the abstract. The +default is @samp{ABSTRACT}. @endDefstr @Defstr {TOC, ms} @@ -4172,37 +4161,40 @@ Contains the string printed at the beginning of the table of contents. @DefstrItem {MONTH10, ms} @DefstrItem {MONTH11, ms} @DefstrListEnd {MONTH12, ms} -Prints the full name of the month in dates. -The default is @samp{January}, @samp{February}, etc. +Prints the full name of the month in dates. The default is +@samp{January}, @samp{February}, etc. @endDefstr The following special characters are available@footnote{For an -explanation what special characters are see @ref{Special Characters}.}: +explanation what special characters are see @ref{Special +Characters}.}: @Defstr {-, ms} Prints an em dash. @endDefstr -@DefstrList {*Q, ms} -@DefstrListEnd {*U, ms} -Prints typographer's quotes in troff, -plain quotes in nroff. -@code{*Q} is the left quote and @code{*U} is the right quote. +@DefstrList {Q, ms} +@DefstrListEnd {U, ms} +Prints typographer's quotes in troff, and plain quotes in nroff. +@code{\*Q} is the left quote and @code{\*U} is the right quote. @endDefstr Improved accent marks are available in the @file{ms} macros. @Defmac {AM, , ms} -Specify this macro at the beginning of your document -to enable extended accent marks and special characters. -This is a Berkeley extension. +Specify this macro at the beginning of your document to enable +extended accent marks and special characters. This is a Berkeley +extension. -To use the accent marks, place them @strong{after} -the character being accented. +To use the accent marks, place them @strong{after} the character being +accented. + +Note that groff's native support for accents is superior to the +following definitions. @endDefmac -The following accent marks are available -after invoking the @code{AM} macro: +The following accent marks are available after invoking the @code{AM} +macro: @Defstr {\', ms} Acute accent. @@ -4250,8 +4242,8 @@ Underdot. Ring above. @endDefstr -The following are standalone characters -available after invoking the @code{AM} macro: +The following are standalone characters available after invoking the +@code{AM} macro: @Defstr {?, ms} Upside-down question mark. @@ -4299,14 +4291,69 @@ Uppercase @c --------------------------------------------------------------------- -@node Differences from AT&T ms, , ms Page Layout, ms +@node Differences from AT&T ms, Naming Conventions, ms Page Layout, ms @subsection Differences from @acronym{AT&T} @file{ms} @cindex @code{ms} macros, differences from @acronym{AT&T} @cindex @acronym{AT&T} @code{troff}, @code{ms} macro package differences -This section lists the (minor) differences between the -@code{groff -ms} macros and @acronym{AT&T} -@code{troff -ms} macros. +This section lists the (minor) differences between the @code{groff +-ms} macros and @acronym{AT&T} @code{troff -ms} macros. + +@itemize @bullet +@item +The internals of @code{groff -ms} differ from the internals of +@acronym{AT&T} @code{troff -ms}. Documents that depend upon +implementation details of @acronym{AT&T} @code{troff -ms} may not +format properly with @code{groff -ms}. + +@item +The general error-handling policy of @code{groff -ms} is to detect and +report errors, rather than silently to ignore them. + +@item +@code{groff -ms} does not work in compatibility mode (this is, with +the @option{-C} option). + +@item +There is no special support for typewriter-like devices. + +@item +@code{groff -ms} does not provide cut marks. + +@item +Multiple line spacing is not supported. Use a larger vertical spacing +instead. + +@item +Some @acronym{UNIX} @code{ms} documentation says that the @code{CW} +and @code{GW} number registers can be used to control the column width +and gutter width, respectively. These number registers are not used in +@code{groff -ms}. + +@item +Macros that cause a reset (paragraphs, headings, etc.@:) may change +the indentation. Macros that change the indentation do not increment +or decrement the indentation, but rather set it absolutely. This can +cause problems for documents that define additional macros of their +own. The solution is to use not the @code{in} request but instead the +@code{RS} and @code{RE} macros. + +@item +To make @code{groff -ms} use the default page offset (which also +specifies the left margin), the @code{PO} register must stay undefined +until the first @file{-ms} macro is evaluated. This implies that +@code{PO} should not be used early in the document, unless it is +changed also: Remember that accessing an undefined register +automatically defines it. +@end itemize + +@Defmpreg {GS, ms} +This number register is set to@tie{}1 by the @code{groff -ms} macros, +but it is not used by the @code{AT&T} @code{troff -ms} macros. +Documents that need to determine whether they are being formatted with +@code{AT&T} @code{troff -ms} or @code{groff -ms} should use this +number register. +@endDefmpreg @menu * Missing ms Macros:: @@ -4318,9 +4365,8 @@ This section lists the (minor) differences between the @node Missing ms Macros, Additional ms Macros, Differences from AT&T ms, Differences from AT&T ms @subsubsection @code{troff} macros not appearing in @code{groff} -Macros missing from @code{groff -ms} -are cover page macros specific to Bell Labs. -The macros known to be missing are: +Macros missing from @code{groff -ms} are cover page macros specific to +Bell Labs and Berkeley. The macros known to be missing are: @table @code @item .TM @@ -4381,7 +4427,6 @@ You can write a script to capture and process an index generated in this manner. @endDefmac -@sp 1 The following additional number registers appear in @code{groff -ms}: @@ -4392,11 +4437,57 @@ place of the @code{GW} register that was documented but apparently not implemented in @acronym{AT&T} @code{troff}. @endDefmpreg -@sp 1 Several new string registers are available as well. You can change these to handle (for example) the local language. @xref{ms Strings and Special Characters}, for details. +@c --------------------------------------------------------------------- + +@node Naming Conventions, , Differences from AT&T ms, ms +@subsection Naming Conventions +@cindex @code{ms} macros, naming conventions +@cindex naming conventions, @code{ms} macros + +The following conventions are used for names of macros, strings and +number registers. External names available to documents that use the +@code{groff -ms} macros contain only uppercase letters and digits. + +Internally the macros are divided into modules; naming conventions are +as follows: + +@itemize @bullet +@item +Names used only within one module are of the form +@var{module}@code{*}@var{name}. + +@item +Names used outside the module in which they are defined are of the +form @var{module}@code{@@}@var{name}. + +@item +Names associated with a particular environment are of the form +@var{environment}@code{:}@var{name}; these are used only within the +@code{par} module. + +@item +@var{name} does not have a module prefix. + +@item +Constructed names used to implement arrays are of the form +@var{array}@code{!}@var{index}. +@end itemize + +Thus the groff ms macros reserve the following names: + +@itemize @bullet +@item +Names containing the characters @code{*}, @code{@@}, +and@tie{}@code{:}. + +@item +Names containing only uppercase letters and digits. +@end itemize + @c ===================================================================== @@ -7988,8 +8079,9 @@ If a negative indentation value is specified (which is not allowed), @code{gtroff} emits a warning of type @samp{range} and sets the indentation to zero. -The effect of @code{in} is delayed until a partially collected line (if -it exists) is output. A temporary indent value is reset to zero also. +The effect of @code{in} is delayed until a partially collected line +(if it exists) is output. A temporary indentation value is reset to +zero also. The current indentation (as set by @code{in}) can be found in the read-only number register @samp{.i}. @@ -12340,7 +12432,7 @@ The number of lines still to center, or to right-justify, or to underline (with or without underlined spaces); they are set to zero. @item -The status whether a temporary indent is active. +The status whether a temporary indentation is active. @item Input traps and its associated data. diff --git a/tmac/groff_ms.man b/tmac/groff_ms.man index ec57657a..258670fb 100644 --- a/tmac/groff_ms.man +++ b/tmac/groff_ms.man @@ -1,6 +1,7 @@ '\" t .ig -Copyright (C) 1989-1995, 2001, 2002, 2003, 2004 Free Software Foundation, Inc. +Copyright (C) 1989-1995, 2001, 2002, 2003, 2004, 2005 + Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -888,6 +889,19 @@ prints the floating keep at the top of the new page. This is useful for printing large graphics or tables that do not need to appear exactly where specified. . +.PP +The macros +.B B1 +and +.B B2 +can be used to enclose a text within a box; +.B .B1 +begins the box, and +.B .B2 +ends it. +Text in the box is automatically placed in a diversion +(keep). +. . .SS "Tables, figures, equations, and references" . @@ -1281,7 +1295,7 @@ are not implemented. . .IP \(bu .I "Groff ms" -does not work in compatibility mode (e.g.\& with the +does not work in compatibility mode (e.g., with the .B \-C option). . @@ -1304,12 +1318,13 @@ documentation says that the and .B GW number registers can be used to control the column width and -gutter width respectively. -These number registers are not used in groff ms. +gutter width, respectively. +These number registers are not used in +.IR "groff ms" . . .IP \(bu Macros that cause a reset -(paragraphs, headings, etc.) +(paragraphs, headings, etc.\&) may change the indent. Macros that change the indent do not increment or decrement the indent, but rather set it absolutely. @@ -1338,6 +1353,20 @@ they are being formatted with Unix or .I "groff ms" should use this number register. +. +.IP \(bu +To make +.I "groff ms" +use the default page offset (which also specifies the left margin), +the +.B PO +number register must stay undefined until the first +.B ms +macro is evaluated. +This implies that +.B PO +should not be used early in the document, unless it is changed also: +Remember that accessing an undefined register automatically defines it. .br .ne 23 . @@ -1376,6 +1405,18 @@ The .B \[rs]*- string produces an em dash \[em] like this. . +.PP +Use +.B \[rs]*Q +and +.B \[rs]*U +to get a left and right typographer's quote, +respectively, in +.I troff +(and plain quotes in +.IR nroff ). + +. . .SS Text Settings . @@ -1396,7 +1437,7 @@ at initialization these are set to .BR \[rs]n(PS-2 , .BR \[rs]n[FPS]+2 , and -.B \[rs]n(PD/2 +.BR \[rs]n(PD/2 , respectively. If any of these registers are defined before initialization, the initialization macro does not change them. @@ -1450,7 +1491,7 @@ Names used outside the module in which they are defined are of the form . .IP \(bu Names associated with a particular environment are of the form -.IB \%environment : name; +.IB \%environment : name\fR; these are used only within the .B par module. -- 2.11.4.GIT