[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[groff] 04/17: [ms]: Improve "basic information" documentation.
From: |
G. Branden Robinson |
Subject: |
[groff] 04/17: [ms]: Improve "basic information" documentation. |
Date: |
Sat, 23 Jul 2022 12:40:44 -0400 (EDT) |
gbranden pushed a commit to branch master
in repository groff.
commit 3f0b41f088b6fb68867403a7d69f62480c11632e
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jul 17 06:25:33 2022 -0500
[ms]: Improve "basic information" documentation.
* More consistently use italics to introduce terminology.
* Explain what a macro call is.
* Explain what registers and strings store.
* Recast discussion of \& to scoop up its application to '.
* Fix markup nit, setting prose semicolon in Times, not Courier.
* Resync our Texinfo manual with recent ms.ms edits.
* Clarify a comment.
---
doc/groff.texi | 43 +++++++++++++++++++++----------------------
doc/ms.ms | 45 +++++++++++++++++++++++++++++++--------------
2 files changed, 52 insertions(+), 36 deletions(-)
diff --git a/doc/groff.texi b/doc/groff.texi
index 112e0b2f..fd322ab1 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -2479,9 +2479,10 @@ longer works intended for printing and possible
publication.
@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.
+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 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
@@ -2514,10 +2515,9 @@ denied than admitted.
@endCartoucheExample
@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.
+@code{groff}'s @dfn{registers} and @dfn{strings}, which store numbers
+and text, respectively. Measurements in @code{groff} are expressed with
+a suffix called a @dfn{scaling unit}.
@table @code
@item i
@@ -2543,10 +2543,10 @@ 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.
+request. @dfn{Requests} are like macro calls; they go on lines by
+themselves and start with the @dfn{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.
@@ -2555,10 +2555,10 @@ macro package.
@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
+example of an @dfn{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
@@ -2585,18 +2585,17 @@ Interpolate glyph of special character named @var{char}.
non-printing, zero-width dummy character
@item \~
-Move horizontally by the current font's space width (``non-breaking
-space'').
+Insert an unbreakble space that is adjustable like a normal 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.
+Prefix any words that start with a dot @samp{.} or neutral apostrophe
+@samp{'} with @code{\&} if they are at the beginning of an input line
+(or might become that way in editing) to prevent them from being
+interpreted as macro calls or requests. Suffix @samp{.}, @samp{?}, and
+@samp{!} with @code{\&} when needed to cancel end-of-sentence detection.
@CartoucheExample
After the criticality accident, Dr.\&
diff --git a/doc/ms.ms b/doc/ms.ms
index b670ece8..b0737b4d 100644
--- a/doc/ms.ms
+++ b/doc/ms.ms
@@ -7,8 +7,8 @@
. \" Redefine CW to use bold instead for a visible font change.
. als CW B
.\}
-.\" This document doesn't require the minus sign but we do want a copy-
-.\" and-pastable hyphen-minus.
+.\" This document doesn't require the minus sign (in Times) but we do
+.\" want a copy- and-pastable hyphen-minus.
.char \- \N'45'
.\" A very limited output device might not have a dagger glyph.
.fchar \[dg] *
@@ -140,6 +140,11 @@ be advised that
needs one of its macros called at the beginning of a document so that it
can initialize.
.
+A
+.I macro
+is a formatting instruction to
+.I ms.
+.
Put a macro call on a line by itself.
.
Use
@@ -208,8 +213,12 @@ denied than admitted.
.LP
.I ms
exposes many aspects of document layout to user control via
-.I groff
-registers and strings.
+.I groff 's
+.I registers
+and
+.I strings,
+which store numbers and text,
+respectively.
.
Measurements in
.I groff
@@ -241,8 +250,10 @@ and strings with the
.CW ds
request.
.
-Requests are like macro calls;
-they go on lines by themselves and start with the control character,
+.I Requests
+are like macro calls;
+they go on lines by themselves and start with the
+.I "control character,"
a dot
.CW . ). (
.
@@ -269,7 +280,8 @@ we see that
.CW \[rs]"
begins a comment.
.
-This is an example of an escape sequence,
+This is an example of an
+.I "escape sequence,"
the other kind of formatting instruction.
.
Escape sequences can appear anywhere.
@@ -304,7 +316,7 @@ Interpolate contents of string
T}
\[rs]*\f[I]s T{
abbreviation of
-.CW \[rs]*[\f[I]s\f[]];
+.CW \[rs]*[\f[I]s\f[]] ;
the name
.I s
must be only one character
@@ -325,18 +337,23 @@ T}
.
.
.PP
-.CW \[rs]&
-has two important uses:
-put it before a word starting with a dot
+Prefix any words that start with a dot
.CW .\& ) (
-if that word is at the beginning of an input line
+or neutral apostrophe
+.CW \[aq] ) (
+with
+.CW \[rs]&
+if they are 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
+to prevent the them from being interpreted as macro calls or requests.
+.
+Suffix
.CW . ,
.CW ? ,
and
.CW !\&
+with
+.CW \[rs]&
when needed to cancel end-of-sentence detection.
.
.
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [groff] 04/17: [ms]: Improve "basic information" documentation.,
G. Branden Robinson <=