[ms]: Fix content nits in documentation.

* Explicitly tell the reader how to end section heading text.
* Describe the handling of display distance in more detail.

3 files changed, 31 insertions, 14 deletions

diff --git a/doc/groff.texi b/doc/groff.texi
index 819bcf17b..414e40bc9 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -3340,7 +3340,9 @@ Use headings to create a sequential or hierarchical structure for your
 document.  The @file{ms} macros print headings in @strong{bold} using
 the same font family and, by default, type size as the body text.
 Headings are available with and without automatic numbering.  Text on
-input lines following the macro call becomes the heading's title.
+input lines following the macro call becomes the heading's title.  Call
+a paragraphing macro to end the heading text and start the section's
+content.
 
 @DefmacList {NH, [@Var{depth}], ms}
 @DefmacListEnd {NH, @t{S} @Var{heading-depth-index} @dots{}, ms}
@@ -3916,13 +3918,14 @@ End any display.
 @endDefmac
 
 The distance stored in the @code{DD} register is inserted before and
-after each pair of display macros, replacing any adjacent
-inter-paragraph distance; this is a Berkeley extension.  The @code{DI}
-register is a GNU extension; its value is an indentation applied to
-displays created with @samp{.DS} and @samp{.ID} without arguments, to
-@samp{.DS I} without an indentation argument, and to indented equations
-set with @samp{.EQ}.  Changes to either register take effect at the next
-display boundary.
+after each pair of display macros; this is a Berkeley extension.  In
+@code{groff} @file{ms}, this distance replaces any adjacent
+inter-paragraph distance or subsequent spacing prior to a section
+heading.  The @code{DI} register is a GNU extension; its value is an
+indentation applied to displays created with @samp{.DS} and @samp{.ID}
+without arguments, to @samp{.DS I} without an indentation argument, and
+to indented equations set with @samp{.EQ}.  Changes to either register
+take effect at the next display boundary.
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 2f267676b..c8ec38411 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -36,8 +36,8 @@
 .nr TC-MARGIN \w'00' \" expect 2-digit page numbers at most
 .ie t .nr PI 3.5n
 .el   .nr PI 4n
-.ND April 2023
-.EH '%''April 2023'
+.ND May 2023
+.EH '%''May 2023'
 .EF ''''
 .OH 'Using \f[I]groff\f[] with the \f[I]ms\f[] macros''%'
 .OF ''''
@@ -1211,6 +1211,9 @@ Headings are available with and without automatic numbering.
 Text on input lines following the macro call becomes the heading's
 title.
 .
+Call a paragraphing macro to end the heading text and start the
+section's content.
+.
 .
 .TS
 box;
@@ -2394,10 +2397,14 @@ cf(CR) s | lx .
 .PP
 The distance stored in
 .CW \[rs]n[DD]
-is inserted before and after each pair of display macros,
-replacing any adjacent inter-paragraph distance;
+is inserted before and after each pair of display macros;
 this is a Berkeley extension.
 .
+In
+.I "groff ms" ,
+this distance replaces any adjacent inter-paragraph distance
+or subsequent spacing prior to a section heading.
+.
 The
 .CW DI
 register is a GNU extension;
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 1aa22b994..07832ddaf 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -834,6 +834,9 @@ Headings are available with and without automatic numbering.
 Text on input lines following the macro call becomes the heading's
 title.
 .
+Call a paragraphing macro to end the heading text and start the
+section's content.
+.
 .
 .TP
 .BR .NH \~[\c
@@ -1439,10 +1442,14 @@ End any display.
 .P
 The distance stored in
 .B \[rs]n[DD]
-is inserted before and after each pair of display macros,
-replacing any adjacent inter-paragraph distance;
+is inserted before and after each pair of display macros;
 this is a Berkeley extension.
 .
+In
+.IR "groff ms" ,
+this distance replaces any adjacent inter-paragraph distance
+or subsequent spacing prior to a section heading.
+.
 The
 .B DI
 register is a GNU extension;