gbranden pushed a commit to branch master
in repository groff.
commit 15259c48a5399ab6cbb1a58c97c91df06f5981ea
Author: G. Branden Robinson <g.branden.robin...@gmail.com>
AuthorDate: Tue Jul 8 16:39:57 2025 -0500
doc/*: Revise introduction to the ms package.
---
doc/groff.texi.in | 105 +++++++++++++++++++++++++++++++++++++++---------------
doc/ms.ms | 52 +++++++++++++++------------
2 files changed, 107 insertions(+), 50 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index 3b87a5b90..f7388ba29 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -2589,12 +2589,28 @@ documentation.
@section @file{ms}
@cindex @file{ms} macro package
-The @file{ms} (``manuscript'') package is suitable for the preparation
-of letters, memoranda, reports, and books. These @code{groff}
+Use the
+@file{ms}
+(``manuscript'')
+package to compose
+letters,
+memoranda,
+reports,
+and books.
+These
+@code{groff}
macros feature cover page and table of contents generation,
-automatically numbered headings, several paragraph styles, a variety of
-text styling options, footnotes, and multi-column page layouts.
-@file{ms} supports the @command{tbl}, @command{eqn}, @command{pic}, and
+automatically numbered headings,
+several paragraph styles,
+a variety of text styling options,
+footnotes,
+and multi-column page layouts.
+@file{ms}
+supports the
+@command{tbl},
+@command{eqn},
+@command{pic},
+and
@command{refer}
preprocessors for inclusion of tables,
mathematical equations,
@@ -2630,10 +2646,25 @@ The @file{ms} macros are the oldest surviving package
for @code{roff}
systems.@footnote{While manual @emph{pages} are older, early ones used
macros supplanted by the @file{man} package of Seventh Edition Unix
(1979). @file{ms} shipped with Sixth Edition (1975) and was documented
-by Mike Lesk in a Bell Labs 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.
+by Mike Lesk in a Bell Labs internal memorandum.}
+Whereas
+@file{man}
+suits brief references,
+@file{ms}
+can handle long or complex works
+intended for printing and possible publication.
+
+Macro,
+register,
+and string descriptions frequently mention each other;
+most references are to macros.
+Where a register or string is referenced,
+we annotate its type.
+@file{ms}'s
+identifiers use only capital letters,
+numerals,
+and
+@samp{-}.
@menu
* ms basic information::
@@ -2644,26 +2675,44 @@ publication.
@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 start, know that
-@file{ms} needs one of its macros called at the beginning of a document
-so that it can initialize. A @dfn{macro} is a formatting instruction to
-@file{ms}. Put a macro call on a line by itself. Use @samp{.PP} if you
-want your paragraph's first line 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
-punctuation, 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}
+Prepare an
+@file{ms}
+document
+with your preferred text editor.
+Call an
+@file{ms}
+macro early in the document to initialize the package.
+A
+@dfn{macro}
+is a formatting instruction to
+@file{ms}.
+Put a macro call on a line by itself with a dot before its name.
+Use
+@samp{.PP}
+if you want your paragraph's first line indented,
+or
+@samp{.LP}
+if you don't.
+Then type text
+normally.
+It is a good practice to start each sentence on a new line,
+or to put two spaces after sentence-ending punctuation,
+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 subsection.
+
+Format the document with the
+@command{groff}
+command.
+@command{nroff}
can be useful for previewing.
@Example
-$ editor radical.ms # vim, emacs, @dots{}
+$ editor radical.ms # vim, emacs, nano, @dots{}
$ nroff -ww -z -ms radical.ms # check for errors
$ nroff -ms radical.ms | less -R
$ groff -T ps -ms radical.ms > radical.ps
@@ -2682,7 +2731,7 @@ denied than admitted.
@arrow{}That's what Dijkstra said, anyway.
@endExample
-@need 750
+@need 1000
@file{ms} exposes many aspects of document layout to user control via
@code{groff}'s @dfn{registers} and @dfn{strings}, which store numbers
and text, respectively. Measurements in @code{groff} are expressed with
@@ -2708,7 +2757,7 @@ vees; current vertical spacing
ems; width of an ``M'' in the current font
@item n
-ens; one-half em
+ens; one-half em (same as @code{m} on terminals)
@end table
Set registers with the @code{nr} request and strings with the @code{ds}
diff --git a/doc/ms.ms b/doc/ms.ms
index 7b88c922d..21b434a4d 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -61,9 +61,9 @@ G.\& Branden Robinson
.AI
g.branden.robin...@gmail.com
.AB no
-The
+Use the
.I ms
-(\[lq]manuscript\[rq]) package is suitable for the composition of
+(\[lq]manuscript\[rq]) package to compose
letters,
memoranda,
reports,
@@ -129,18 +129,31 @@ shipped with Sixth Edition (1975) and was documented by
Mike Lesk in a
Bell Labs internal memorandum.
.FE
.
-While the
+Whereas
.I man
-package was designed for brief reference documents,
-the
+suits brief references,
.I ms
-macros are also suitable for longer works intended for printing and
-possible publication.
+can handle long or complex works
+intended for printing and possible publication.
.
.
.PP
In this document,
-a right arrow (\[->]) is used to indicate a tab character in the input.
+a right arrow (\[->]) indicates a tab character in the input.
+.
+Macro,
+register,
+and string descriptions frequently mention each other;
+most references are to macros.
+.
+Where a register or string is referenced,
+we annotate its type.
+.
+.I ms 's
+identifiers use only capital letters,
+numerals,
+and
+.CW \- \[rq]. \[lq]
.
.
.KS
@@ -152,22 +165,20 @@ Basic information
.
.
.LP
+Prepare an
.I ms
-documents are plain text files;
-prepare them with your preferred text editor.
+document with your preferred text editor.
.
-If you're in a hurry to start,
-know that
+Call an
.I ms
-needs one of its macros called at the beginning of a document so that it
-can initialize.
+macro early in the document to initialize the package.
.
A
.I macro
is a formatting instruction to
.I ms.
.
-Put a macro call on a line by itself.
+Put a macro call on a line by itself with a dot before its name.
.
Use
.CW PP
@@ -175,12 +186,8 @@ if you want your paragraph's first line indented,
or
.CW LP
if you don't.
-.KE
.
-.
-.PP
-After that,
-start typing normally.
+Then type text normally.
.
It is a good practice to start each sentence on a new line,
or to put two spaces after sentence-ending punctuation,
@@ -192,6 +199,7 @@ and you can indent with tabs.
.
When you need one of the features mentioned earlier,
return to this manual.
+.KE
.
.
.PP
@@ -207,7 +215,7 @@ can be useful for previewing.
.TS
box center;
Lf(CR)1 Lf(CB).
-$ editor radical.ms \f[TI]# vim, emacs, .\|.\|.
+$ editor radical.ms \f[TI]# vim, emacs, nano, .\|.\|.
$ nroff -ww -z -ms radical.ms \f[TI]# check for errors
$ nroff \-ms radical.ms | less \-R
$ groff \-T pdf \-ms radical.ms > radical.pdf
@@ -263,7 +271,7 @@ p point (1/72\[sd])
P pica (1/6\[sd])
v \[lq]vee\[rq]; current vertical spacing
m \[lq]em\[rq]; width of an \[lq]M\[rq] in the current font
-n \[lq]en\[rq]; one-half em
+n \[lq]en\[rq]; one-half em (same as \f[CR]m\f[] on terminals)
.TE
.
.
_______________________________________________
groff-commit mailing list
groff-commit@gnu.org
https://lists.gnu.org/mailman/listinfo/groff-commit
