* tmac/groff_ms.man, doc/groff.texinfo: Synchronize.

* tmac/groff_ms.man: Document `PO' better.

* NEWS: Document grotty changes.

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  <wl@gnu.org>
+
+	* tmac/groff_ms.man, doc/groff.texinfo: Synchronize.
+
+2005-09-04  Jörgen Grahn <jgrahn@algonet.se>
+
+	* tmac/groff_ms.man: Document `PO' better.
+
+2005-09-03  Werner LEMBERG  <wl@gnu.org>
+
+	* NEWS: Document grotty changes.
+
 2005-09-01  Keith Marshall  <keith.d.marshall@ntlworld.com>
 
 	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  <wl@gnu.org>
+2005-08-29  Werner LEMBERG  <wl@gnu.org>
 
 	* 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  <wl@gnu.org>
+2004-05-14  Werner LEMBERG  <wl@gnu.org>
 
 	* 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  <wl@gnu.org>
+2004-05-13  Werner LEMBERG  <wl@gnu.org>
 
 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{<BLOCKQUOTE>} element.
+Sets a paragraph that is indented at both left and right margins.  The
+effect is identical to the @acronym{HTML} @code{<BLOCKQUOTE>} 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 Æ ligature.
 
 @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.