[groff] 14/30: [ms]: Expand "basic information" documentation.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 62dd6d79d2993d7c8a885de7c4e49ed1cc7f8fc6
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jun 14 03:45:44 2022 -0500

    [ms]: Expand "basic information" documentation.
    
    ...to better serve as a "crash course" tutorial introduction.
---
 doc/groff.texi | 141 +++++++++++++++++++++++++++++++++++-----
 doc/ms.ms      | 199 +++++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 311 insertions(+), 29 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index c346c484..742f4ced 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2467,21 +2467,41 @@ internal memorandum.}  While the @file{man} package was 
designed for
 brief reference documents, the @file{ms} macros are also suitable for
 longer works intended for printing and possible publication.
 
-The @file{ms} macro package included with @code{groff} is an independent
-reimplementation.  Some macros specific to @acronym{AT&T} or Berkeley
-@file{ms} are not included, while several features have been added; see
-@ref{Differences from AT&T ms}.
-
-If you're in a hurry to get started, you need only know that @file{ms}
-needs one of its macros called at the beginning of a document so that it
-can initialize.  A paragraphing macro like @code{PP} (if you want your
-paragraph to have a first-line indent) or @code{LP} (if you don't)
-suffices.
-
-After that, start typing normally.  You can separate paragraphs with
-further paragraphing macros, or with blank lines, and you can indent
-with tabs.  When you need one of the features mentioned earlier
-(@pxref{ms}), return to this manual.
+@menu
+* ms basic information::
+@end menu
+
+@c ---------------------------------------------------------------------
+
+@node ms basic information, ms Document Structure, ms Introduction, ms 
Introduction
+@subsubsection Basic information
+
+@file{ms} documents are plain text files; prepare them with your
+preferred text editor.  If you're in a hurry to get started, be advised
+that @file{ms} needs one of its macros called at the beginning of a
+document so that it can initialize.  Put a macro call on a line by
+itself.  Use @samp{.PP} if you want your paragraph's first line to be
+indented, or @samp{.LP} if you don't.
+
+After that, start typing normally.  It is a good practice to start each
+sentence on a new line, or to put two spaces after sentence-ending
+puncutation, so that the formatter knows where the sentence boundaries
+are.  You can separate paragraphs with further paragraphing macros, or
+with blank lines, and you can indent with tabs.  When you need one of
+the features mentioned earlier (@pxref{ms}), return to this part of the
+manual.
+
+Format the document with the @command{groff} command.  @command{nroff}
+can be useful for previewing.
+
+@CartoucheExample
+$ vi radical.ms
+$ nroff -ms radical.ms | less -R
+$ groff -ms radical.ms > radical.ps
+$ see radical.ps
+@endCartoucheExample
+
+Our @file{radical.ms} document might look like this.
 
 @CartoucheExample
 .LP
@@ -2493,7 +2513,96 @@ denied than admitted.
 @arrow{}That's what Dijkstra said, anyway.
 @endCartoucheExample
 
-We have used an arrow @arrow{} in the above to indicate a tab character.
+@file{ms} exposes many aspects of document layout to user control via
+@code{groff} registers and strings.  Most registers have a default unit
+of measurement.  Specifying a unit explicitly does not cause problems,
+and can avoid them in complex situations.  The following table
+summarizes typical units.
+
+@table @code
+@item i
+inches
+
+@item c
+centimeters
+
+@item p
+points (1/72 inch)
+
+@item P
+picas (1/6 inch)
+
+@item v
+vees; height of a line using the current font
+
+@item n
+ens; width of an ``n'' using the current font
+
+@item m
+ems; width of an ``M'' using the current font
+@end table
+
+Set registers with the @code{nr} request and strings with the @code{ds}
+request.  Requests are like macro calls; they go on lines by themselves
+and start with the control character, a dot (@code{.}).  The difference
+is that they directly instruct the formatter program, rather than the
+macro package.
+
+@CartoucheExample
+.nr PS 10.5p \" Use 10.5-point type.
+.ds FAM P    \" Use Palatino font family.
+@endCartoucheExample
+
+@noindent
+In the foregoing, we see that @code{\"} begins a comment.  This is an
+example of an escape sequence, the other kind of formatting instruction.
+Escape sequences can appear anywhere.  They begin with the escape
+character (@code{\}) and are followed by at least one more character.
+@file{ms} documents
+@c like this one
+tend to use only a few of @code{groff}'s many requests and escape
+sequences; see @ref{Request Index} and @ref{Escape Sequence Index} or
+the @cite{groff@r{(7)}} man page for complete lists.
+
+@table @code
+@item \"
+Begin comment; ignore remainder of line.
+
+@item \n[@var{reg}]
+Interpolate value of register @var{reg}.
+
+@item \*[@var{str}]
+Interpolate contents of string @var{str}.
+
+@item \*@var{s}
+abbreviation of @code{\*[@var{s}]}; the name @var{s} must be only one
+character
+
+@item \[@var{char}]
+Interpolate glyph of special character named @var{char}.
+
+@item \&
+non-printing, zero-width dummy character
+
+@item \~
+Move horizontally by the current font's space width (``non-breaking
+space'').
+
+@item \|
+Move horizontally by one-sixth em (``thin space'').
+@end table
+
+@code{\&} has two important uses: put it before a word starting with a
+dot @samp{.} if that word is at the beginning of an input line (or might
+become that way in editing) to prevent the dot from being interpreted as
+the control character, and after @samp{.}, @samp{?}, and @samp{!}, when
+needed to cancel end-of-sentence detection.
+
+@CartoucheExample
+After the criticality accident, Dr.\&
+Wallace said my exposure had been
+\&.5 to \&.6 Sv of neutrons.
+@endCartoucheExample
 
 @c ---------------------------------------------------------------------
 
diff --git a/doc/ms.ms b/doc/ms.ms
index 86d9e969..228e2748 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -122,6 +122,7 @@ In this document,
 a right arrow (\[->]) is used to indicate a tab character in the input.
 .
 .
+.KS
 .NH 2
 Basic information
 .XS
@@ -131,25 +132,97 @@ Basic information
 .
 .LP
 .I ms
+documents are plain text files;
+prepare them with your preferred text editor.
+.
+If you're in a hurry to get started,
+be advised that
+.I ms
+needs one of its macros called at the beginning of a document so that it
+can initialize.
+.
+Put a macro call on a line by itself.
+.
+Use
+.CW .PP
+if you want your paragraph's first line to be indented,
+or
+.CW .LP
+if you don't.
+.KE
+.
+.
+.PP
+After that,
+start typing normally.
+.
+It is a good practice to start each sentence on a new line,
+or to put two spaces after sentence-ending puncutation,
+so that the formatter knows where the sentence boundaries are.
+.
+You can separate paragraphs with further paragraphing macro calls,
+or with blank lines,
+and you can indent with tabs.
+.
+When you need one of the features mentioned earlier,
+return to this manual.
+.
+.
+.PP
+Format the document with the
+.I groff (1)
+command.
+.
+.I nroff (1)
+can be useful for previewing.
+.
+.
+.TS
+box center;
+lf(CB).
+\f[CR]$\f[] vi radical.ms
+\f[CR]$\f[] nroff \-ms radical.ms | less \-R
+\f[CR]$\f[] groff \-ms radical.ms > radical.ps
+\f[CR]$\f[] see radical.ps
+.TE
+.
+.
+.PP
+Our
+.CW radical.ms
+document might look like this.
+.
+.
+.TS
+box center;
+Lf(CR).
+\&.LP
+Radical novelties are so disturbing that they tend to be
+suppressed or ignored, to the extent that even the
+possibility of their existence in general is more often
+denied than admitted.
+.sp
+\[->]That\[aq]s what Dijkstra said, anyway.
+.TE
+.
+.
+.LP
+.I ms
 exposes many aspects of document layout to user control via
 .I groff
 registers and strings.
 .
-Most
-.I registers
-have a default unit of measurement.
-.
-Specifying a unit explicitly does not cause problems,
-and can avoid them in complex situations.
-.
-The following table summarizes typical units.
+Measurements in
+.I groff
+are expressed with a suffix called a
+.I "scaling unit."
 .
 .
 .TS
 box center;
 cb cb
 cf(CR) l .
-Unit   Description
+Scaling unit   Description
 _
 i      inches (\[sd])
 c      centimeters
@@ -163,18 +236,118 @@ m        \[lq]ems\[rq]; width of an \[lq]M\[rq] using 
the current font
 .
 .PP
 Set registers with the
-.CW .nr
+.CW nr
 request
 and strings with the
-.CW .ds
+.CW ds
 request.
 .
+Requests are like macro calls;
+they go on lines by themselves and start with the control character,
+a dot
+.CW . ). (
+.
+The difference is that they directly instruct the formatter program,
+rather than the macro package.
+.
+It is wise to specify a scaling unit when setting any register that
+represents a length,
+size,
+or distance.
+.
+.
+.TS
+box center;
+lf(CR).
+\&.nr PS 10.5p \[rs]" Use 10.5\-point type.
+\&.ds FAM P    \[rs]" Use Palatino font family.
+.TE
+.
+.
+.LP
+In the foregoing,
+we see that
+.CW \[rs]"
+begins a comment.
+.
+This is an example of an escape sequence,
+the other kind of formatting instruction.
+.
+Escape sequences can appear anywhere.
+.
+They begin with the escape character
+.CW \[rs] ) (
+and are followed by at least one more character.
+.
+.I ms
+documents like this one tend to use only a few of
+.I groff 's
+many requests and escape sequences;
+see the
+.I groff (7)
+man page for complete lists.
+.
+.
+.TS
+box center;
+Cb Cb
+Lf(CR) Lx .
+Escape sequence        Description
+_
+\[rs]" Begin comment; ignore remainder of line.
+\[rs]n[\f[I]reg\f[]]   T{
+Interpolate value of register
+.I reg .
+T}
+\[rs]*[\f[I]str\f[]]   T{
+Interpolate contents of string
+.I str .
+T}
+\[rs]*\f[I]s   T{
+abbreviation of
+.CW \[rs]*[\f[I]s\f[]];
+the name
+.I s
+must be only one character
+T}
+\[rs][\f[I]char\f[]]   T{
+Interpolate glyph of special character named
+.I char .
+T}
+\[rs]& non-printing, zero-width dummy character
+\[rs]\[ti]     T{
+Move horizontally by the current font's space width
+(\[lq]non-breaking space\[rq]).
+T}
+\[rs]| T{
+Move horizontally by one-sixth em
+(\[lq]thin space\[rq]).
+T}
+.TE
+.
+.
+.PP
+.CW \[rs]&
+has two important uses:
+put it before a word starting with a dot
+.CW .\& ) (
+if that word is at the beginning of an input line
+(or might become that way in editing)
+to prevent the dot from being interpreted as the control character,
+and after
+.CW . ,
+.CW ? ,
+and
+.CW !\&
+when needed to cancel end-of-sentence detection.
+.
 .
 .TS
 box center;
 lf(CR).
-\&.nr PS 12 \[rs]" Use 12-point type.
-\&.ds FAM P \[rs]" Use Palatino font family.
+After the criticality accident, Dr.\[rs]&
+Wallace said my exposure had been
+\[rs]&.5 to \[rs]&.6 Sv of neutrons.
 .TE
 .
 .