[groff] 03/06: doc/ms.ms: Update example style.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit a4f00b67316c8319d176622ceb34db0cb6e350ea
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Feb 22 16:03:10 2021 +1100

    doc/ms.ms: Update example style.
    
    * Improve typesetting of ellipses.
    * Use two empty requests where vertical space is expected.
    * Set input examples using tbl tables instead of boxed displays; this
      way, only the tables of ms language description go all the way to both
      margins, whereas examples are inset.
    * Use recommended input style in code examples, except for groff's empty
      request convention, which takes a lot of vertical space.
    * Use a longer input length of 64 columns in examples to use vertical
      space more economically.
    * (Introduction) Introduce convention of using a right-arrow glyph to
      indicate an input tab character.
    * (Highlighting) Say "ms" instead of "-ms".
    * Stop putting ".TS H" tables inside keeps; it is unreliable, leading to
      ugliness when box options are used and the table spreads across
      pages.  Thanks to Tadziu Hoffman for help troubleshooting this.
    * Rewrap input lines.
---
 doc/ms.ms | 178 +++++++++++++++++++++++++++++++++++++++-----------------------
 1 file changed, 113 insertions(+), 65 deletions(-)

diff --git a/doc/ms.ms b/doc/ms.ms
index 0e6dae3..34995fb 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -125,6 +125,11 @@ ms\c
 for more information.
 .
 .
+.PP
+In this document,
+a right arrow (\[->]) is used to indicate a tab character in the input.
+.
+.
 .NH 2
 Basic information
 .XS
@@ -507,7 +512,7 @@ Martha Buck
 \&.AI
 Monolithic Corporation
 .R
-\&...
+\&.\|.\|.
 .DE
 T}
 _
@@ -533,42 +538,49 @@ T}
 _
 \&.AE  End the abstract.
 .TE
+.
+.
 .KS
 .LP
-The following is example mark-up for a title page.
-.B1
-.DS B
+The following is example markup for a title page.
+.
+.
+.\" Wrap lines in the code example below at 64 columns.
+.TS
+box center;
+l.
+T{
+.nf
 .CW
 \&.RP
 \&.TL
-The Inevitability of Code Bloat
-in Commercial and Free Software
+The Inevitability of Code Bloat in Commercial and Free Software
 \&.AU
 J. Random Luser
 \&.AI
 University of West Bumblefuzz
 \&.AB
-This report examines the long-term growth
-of the code bases in two large, popular software
-packages; the free Emacs and the commercial
-Microsoft Word.
-While differences appear in the type or order
-of features added, due to the different
-methodologies used, the results are the same
-in the end.
+This report examines the long-term growth of the code bases in
+two large,
+popular software packages;
+the free Emacs and the commercial Microsoft Word.
+While differences appear in the type or order of features added,
+due to the different methodologies used,
+the results are the same in the end.
 \&.PP
-The free software approach is shown to be
-superior in that while free software can
-become as bloated as commercial offerings,
-free software tends to have fewer serious
-bugs and the added features are in line with
-user demand.
+The free software approach is shown to be superior in that while
+free software can become as bloated as commercial offerings,
+free software tends to have fewer serious bugs and the added
+features are in line with user demand.
 \&.AE
 .R
-\&... the rest of the paper follows ...
-.DE
-.B2
+\&.\|.\|.\|the rest of the paper follows\|.\|.\|.
+.fi
+T}
+.TE
 .KE
+.
+.
 .\" ------------------------
 .bp
 .NH 1
@@ -604,34 +616,44 @@ The effect is identical to the
 element.
 The next paragraph or heading
 returns margins to normal.
+.
+.
 .KS
 .PP
 The following markup uses all three paragraph macros.
-.B1
-.DS B
+.
+.
+.\" Wrap lines in the code example below at 64 columns.
+.TS
+box center;
+l.
+T{
+.nf
 .CW
 \&.NH 2
 Cases used in the study
 \&.LP
-The following software and versions were
-considered for this report.
+The following software and versions were considered for this
+report.
 \&.PP
-For commercial software, we chose
+For commercial software,
+we chose
 \&.B "Microsoft Word for Windows" ,
-starting with version 1.0 through the
-current version (Word 2000).
+starting with version 1.0 through the current version
+(Word 2000).
 \&.PP
-For free software, we chose
+For free software,
+we chose
 \&.B Emacs ,
-from its first appearance as a standalone
-editor through the current version (v20).
+from its first appearance as a standalone editor through the
+current version (v20).
 \&.QP
 Franklin's Law applied to software:
-software expands to outgrow both
-RAM and disk space over time.
+software expands to outgrow both RAM and disk space over time.
 .R
-.DE
-.B2
+.fi
+T}
+.TE
 .KE
 .
 .
@@ -910,11 +932,15 @@ Highlighting
 .XS
        Highlighting
 .XE
+.
+.
 .LP
 The
-.I -ms
-macros provide a variety of methods to highlight
-or emphasize text:
+.I ms
+macros provide a variety of methods to highlight or emphasize text.
+.KE
+.
+.
 .TS H
 box;
 lb lb
@@ -1067,7 +1093,8 @@ the value of the
 register).
 T}
 .TE
-.KE
+.
+.
 .NH 2
 Lists
 .XS
@@ -1098,7 +1125,6 @@ Once specified, the indent remains the same for all
 list items in the document until specified again.
 .
 .
-.KS
 .PP
 The following are examples of each type of list.
 .
@@ -1175,7 +1201,6 @@ preferably large-caliber.
 Gotta pay for those lawyers and guns!
 T}
 .TE
-.KE
 .
 .
 .PP
@@ -1562,28 +1587,39 @@ An example multi-page table
 .XS
                An example multi-page table
 .XE
+.
+.
 .LP
-The following is an example of how to set up a
-table that may print across two or more pages.
-.B1
-.DS I
+The following is an example of how to set up a table that may print
+across two or more pages.
+.
+.
+.TS
+box center;
+l .
+T{
+.nf
 .CW
 \&.TS H
 allbox expand;
 cb | cb .
-Text      \&...of heading...
+Part\[->]Description
 _
 \&.TH
 \&.T&
 l | l .
+GH-1978\[->]Fribulating gonkulator
 .R
-\&... the rest of the table follows...
+\&.\|.\|.\|the rest of the table follows\|.\|.\|.
 .CW
 \&.TE
 .R
-.DE
-.B2
+.fi
+T}
+.TE
 .KE
+.
+.
 .NH 2
 Footnotes
 .XS
@@ -1833,16 +1869,25 @@ repeat those headings wrapped in
 and
 .CW .XE
 macros.
+.
+.
 .PP
-In addition, the
-.CW .XS
-macro does not know to 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:
-.B1
-.DS I
+In addition,
+the
+.CW XS
+macro does not know to 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.
+.
+.
+.TS
+box center;
+l .
+T{
+.nf
 .CW
 \&.NH 1
 Introduction
@@ -1850,17 +1895,20 @@ Introduction
 Introduction
 \&.XE
 .R
-\&...
+\&.\|.\|.
 .CW
 \&.NH 2
 Methodology
 \&.XS
-       Methodology
+\[->]Methodology
 \&.XE
 .R
-\&...
-.DE
-.B2
+\&.\|.\|.
+.fi
+T}
+.TE
+.
+.
 .LP
 The
 .I "Groff and Friends HOWTO"