[groff] 14/14: [docs]: Sync up ms .RS/.RE descriptions.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 9ea1c77d62edc96eef12bab91a4bab57a750c67d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Fri Feb 19 10:17:43 2021 +1100

    [docs]: Sync up ms .RS/.RE descriptions.
    
    * doc/groff.texi: Rename node from "Indentation values in ms" to
      "Indented regions in ms".  Recast descriptions of .RS and .RE to note
      the breadth of their effect.  Fix grammar errors.  Tweak example.
    * doc/ms.ms (Indented regions): Add section.  Sync with Texinfo.
    * tmac/groff_ms.7.man: Rename subsection from "Indents" to "Indented
      regions".  Sync with ms.ms, omitting example.
---
 doc/groff.texi      | 64 ++++++++++++++++++++++-------------------
 doc/ms.ms           | 83 +++++++++++++++++++++++++++++++++++++----------------
 tmac/groff_ms.7.man | 37 +++++++++++++-----------
 3 files changed, 113 insertions(+), 71 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index deeb09f..1d91cf5 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3030,8 +3030,8 @@ Examples include paragraphs, sections, and other groups.
 * Headings in ms::
 * Highlighting in ms::
 * Lists in ms::
-* Indentation values in ms::
-* Tabstops in ms::
+* Indented regions in ms::
+* Tab stops in ms::
 * ms Displays and Keeps::
 * ms Insertions::
 * Example multi-page table::
@@ -3348,7 +3348,7 @@ Text enclosed with @code{\*<} and @code{\*>} is printed 
as a subscript.
 
 @c ---------------------------------------------------------------------
 
-@node Lists in ms, Indentation values in ms, Highlighting in ms, ms Body Text
+@node Lists in ms, Indented regions in ms, Highlighting in ms, ms Body Text
 @subsubsection Lists
 @cindex @code{ms} macros, lists
 
@@ -3490,13 +3490,28 @@ Two or more attorneys.
 Gotta pay for those lawyers and guns!
 @endCartoucheExample
 
-To set nested lists, use the @code{RS} and @code{RE} macros.
-@xref{Indentation values in ms}.
+@c ---------------------------------------------------------------------
+
+@node Indented regions in ms, Tab stops in ms, Lists in ms, ms Body Text
+@subsubsection Indented regions
+
+You may need to indent a section of text while still wrapping and
+filling.
+
+@Defmac {RS, , ms}
+Begin a region indented by the amount of the @code{PI} register,
+affecting the placement of headings, paragraphs, and displays.
+@endDefmac
+
+@Defmac {RE, , ms}
+End the most recent indented region.
+@endDefmac
 
+You can use @code{RS}/@code{RE} regions to line up text under hanging
+and indented paragraphs.
 @cindex @code{ms} macros, nested lists
 @cindex nested lists [@code{ms}]
-
-For example:
+For example, you may wish to nest lists; the input
 
 @CartoucheExample
 .IP \[bu] 2
@@ -3506,6 +3521,7 @@ Lawyers:
 Dewey,
 .IP \[bu]
 Cheatham,
+and
 .IP \[bu]
 and Howe.
 .RE
@@ -3513,43 +3529,31 @@ and Howe.
 Guns
 @endCartoucheExample
 
-Produces:
+@noindent
+produces
 
 @Example
 @bullet{} Lawyers:
 
   @bullet{}  Dewey,
 
-  @bullet{}  Cheatham,
+  @bullet{}  Cheatham, and
 
-  @bullet{}  and Howe.
+  @bullet{}  Howe.
 
 @bullet{} Guns
 @endExample
 
-@c ---------------------------------------------------------------------
-
-@node Indentation values in ms, Tabstops in ms, Lists in ms, ms Body Text
-@subsubsection Indentation values
-
-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}
-@DefmacListEndx {RE, , ms}
-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
+@noindent
+as output.
 
-@xref{ms Displays and Keeps}, for macros to indentation and turn off
-filling.
+@xref{ms Displays and Keeps}, for macros to indent regions with filling
+disabled.
 
 @c ---------------------------------------------------------------------
 
-@node Tabstops in ms, ms Displays and Keeps, Indentation values in ms, ms Body 
Text
-@subsubsection Tab Stops
+@node Tab stops in ms, ms Displays and Keeps, Indented regions in ms, ms Body 
Text
+@subsubsection Tab stops
 
 Use the @code{ta} request to define tab stops as needed.  @xref{Tabs and
 Fields}.
@@ -3562,7 +3566,7 @@ set of default tab stops.
 
 @c ---------------------------------------------------------------------
 
-@node ms Displays and Keeps, ms Insertions, Tabstops in ms, ms Body Text
+@node ms Displays and Keeps, ms Insertions, Tab stops in ms, ms Body Text
 @subsubsection Displays and keeps
 @cindex @code{ms} macros, displays
 @cindex @code{ms} macros, keeps
diff --git a/doc/ms.ms b/doc/ms.ms
index 5f41556..e99db7f 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -1259,54 +1259,89 @@ If you omit the space,
 prints the first word on the same line as the term or label (if it fits)
 .B then
 breaks the line.
+.
+.
+.NH 2
+Indented regions
+.XS
+       Indented regions
+.XE
+.
+.
+.LP
+You may need to indent a section of text while still wrapping and
+filling.
+.
+.
+.TS
+box;
+cb cb
+lfCR lx .
+Macro  Description
+_
+\&.RS  T{
+Begin a region indented by
+.CW \[rs]n[PI] ,
+affecting the placement of headings,
+paragraphs,
+and displays.
+T}
+\&.RE  T{
+End the most recent indented region.
+T}
+.TE
+.
+.
 .PP
-To set nested lists, use the
-.CW .RS
-and 
+You can use
+.CW .RS /
 .CW .RE
-macros.
-These macros begin and end a section indented to line
-up with the body of an
-.CW .IP
-macro.
-For example:
+regions to line up text under hanging and indented paragraphs.
+.
+For example,
+you may wish to nest lists.
+.
 .TS
 box center;
-a a .
+l l .
 T{
 .nf
 .CW
-\&.IP \\(bu 2
+\&.IP \\[bu] 2
 Lawyers:
 \&.RS
-\&.IP \\(bu
+\&.IP \\[bu]
 Dewey,
-\&.IP \\(bu
+\&.IP \\[bu]
 Cheatham,
-\&.IP \\(bu
-and Howe.
+and
+\&.IP \\[bu]
+Howe.
 \&.RE
-\&.IP \\(bu
+\&.IP \\[bu]
 Guns
 .R
-\&...
+\&.\|.\|.
 .fi
 T}     T{
-.IP \(bu 2
+.IP \[bu] 2
 Lawyers:
 .RS
-.IP \(bu
+.IP \[bu]
 Dewey,
-.IP \(bu
+.IP \[bu]
 Cheatham,
-.IP \(bu
-and Howe.
+and
+.IP \[bu]
+Howe.
 .RE
-.IP \(bu
+.IP \[bu]
 Guns
-\&...
+\&.\|.\|.
 T}
 .TE
+.
+.
 .NH 2
 Displays and keeps
 .XS
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 0235b5a..cd85d6e 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -796,32 +796,35 @@ document until specified again.
 .
 .
 .\" ====================================================================
-.SS Indents
+.SS "Indented regions"
 .\" ====================================================================
 .
-You may need to indent sections of text.
+You may need to indent a section of text while still wrapping and
+filling.
 .
-A typical use for indents is to create nested lists and sublists.
 .
+.TP
+.B .RS
+Begin a region indented by
+.BR \[rs]n[PI] ,
+affecting the placement of headings,
+paragraphs,
+and displays.
 .
-.PP
-Use the
-.B RS
-and
-.B RE
-macros to start and end a section of indented text, respectively.
 .
-The
-.B PI
-register controls the amount of indent.
+.TP
+.B .RE
+End the most recent indented region.
 .
 .
 .PP
-You can nest indented sections as deeply as needed by using multiple,
-nested pairs of
-.B RS
-and
-.BR RE .
+You can use
+.BR .RS /
+.B .RE
+regions to line up text under hanging and indented paragraphs.
+.
+For example,
+you may wish to nest lists.
 .
 .
 .\" ====================================================================