[groff] 37/47: [docs]: Be more careful with control characters.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit cbbf97b88157283ee1b8d67d98bf15633b8d3921
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Tue Jan 11 19:25:01 2022 +1100

    [docs]: Be more careful with control characters.
    
    ...when they are word-initial in filled text lines.
    
    The idea is to prevent baffling surprises if a sentence is recast in a
    text editor, and a word beginning with a dot or neutral apostrophe is
    reflowed onto the beginning of the next input line--suddenly it is
    parsed as a control character.
    
    Fixes <https://savannah.gnu.org/bugs/?51312>.
    
    Some of these edits permit other solecisms to persist.  I'll fix them
    separately.
---
 ChangeLog                       | 19 +++++++++++++++++++
 contrib/hdtbl/groff_hdtbl.7.man |  4 ++--
 doc/automake.mom                | 19 ++++++++++---------
 doc/meintro.me.in               |  8 ++++----
 doc/meintro_fr.me.in            | 24 ++++++++++++------------
 doc/pic.ms                      | 21 +++++++++++----------
 doc/webpage.ms                  | 26 +++++++++++++-------------
 src/devices/gropdf/gropdf.1.man |  2 +-
 8 files changed, 72 insertions(+), 51 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index de27d6b1..43ff1576 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,22 @@
+2022-01-11  G. Branden Robinson <g.branden.robinson@gmail.com>
+
+       [docs]: Be more careful with control characters when they are
+       word-initial in filled text lines.  The idea is to prevent
+       baffling surprises if a sentence is recast in a text editor, and
+       a word beginning with a dot or neutral apostrophe is reflowed
+       onto the beginning of the next input line--suddenly it is parsed
+       as a control character.
+
+       * contrib/hdtbl/groff_hdtbl.7.man:
+       * doc/automake.mom:
+       * doc/meintro.me.in:
+       * doc/meintro_fr.me.in:
+       * doc/pic.ms:
+       * doc/webpage.ms:
+       * src/devices/gropdf/gropdf.1.man: Do it.
+
+       Fixes <https://savannah.gnu.org/bugs/?51312>.
+
 2022-01-11  G. Branden Robinson <g.branden.robinson@gmail.com>
 
        * doc/groff.texi (Font Description File Format):
diff --git a/contrib/hdtbl/groff_hdtbl.7.man b/contrib/hdtbl/groff_hdtbl.7.man
index 27d146c5..24a6ba45 100644
--- a/contrib/hdtbl/groff_hdtbl.7.man
+++ b/contrib/hdtbl/groff_hdtbl.7.man
@@ -1129,8 +1129,8 @@ Together with
 .CR \[oq]border=0\[cq]
 for proper formatting the value of
 .CR \[oq]csp\[cq]
-must be at least .05\~inches for single separator lines and .15\~inches
-for double separator lines.
+must be at least \&.05\~inches for single separator lines and
+\&.15\~inches for double separator lines.
 .
 .XDEFS hl=s t*hl
 .
diff --git a/doc/automake.mom b/doc/automake.mom
index 83963400..10e72fd6 100644
--- a/doc/automake.mom
+++ b/doc/automake.mom
@@ -245,7 +245,7 @@ to declare a program that should be built, and then list the
 sources of this program in a variable that starts with the name of
 your program and ends with \*[CODE]_SOURCES\*[CODE OFF]\&.  In the
 groff project we have only 1 top-level Makefile.am that includes
-several .am files.
+several \&.am files.
 .PP
 Take for example the build of grolbp, in src/devices/grolbp/grolbp.am. 
 The file starts with:
@@ -301,7 +301,7 @@ The path to the files are relative to the top-level 
directory.
 .ITEM
 The binaries are generated in the top-level build directory.
 .ITEM
-The .o files are generated in the directory where the source files
+The \&.o files are generated in the directory where the source files
 are located, or, in the case of an out-of-source build tree, in a
 directory that is the replication of the source tree directory.
 For example if you built groff in a `build' directory, lbp.o
@@ -357,9 +357,10 @@ gxditview_CPPFLAGS = $(AM_CPPFLAGS) $(X_CFLAGS) -Dlint \\
 .ILQ
 .PP
 The use of specific CPPFLAGS changes the name of the generated objects:
-the .o object files are prefixed with the name of the program.
-For example, the .o file corresponding to src/devices/xditview/device.c
-will be src/devices/xditview/gxditview-device.o.
+the \&.o object files are prefixed with the name of the program.
+For example, the \&.o file corresponding to
+src/devices/xditview/device.c will be
+src/devices/xditview/gxditview-device.o.
 .
 .HEADING 2 "Cleaning"
 .
@@ -514,7 +515,7 @@ based on the following paper from Peter Miller:
 .PP
 The idea is to have a single Makefile that contains all the rules.
 That is why we have only a single Makefile.am in the top-level
-directory which includes all the .am files that define rules
+directory which includes all the \&.am files that define rules
 to build the various programs.  The inclusion is done with the
 \*[CODE]include\*[CODE OFF] directive, not \*[CODE]SUBDIRS\*[CODE OFF]\&.
 Using 'include' is like copying the contents of the included
@@ -527,11 +528,11 @@ We first say in this top-level Makefile.am:
 bin_PROGAMS = 
 .CODE OFF
 .QUOTE OFF
-and then all the .am files that define a program to be built (e.g.
+and then all the \&.am files that define a program to be built (e.g.
 src/devices/grolbp/grolbp.am, src/roff/troff/troff.am, and so on)
 overload this variable, so that at the end, all the programs that
 should be built are listed in this \*[CODE]bin_PROGRAMS\*[CODE OFF]
-variable.  This is the reason why all the paths in the various .am
+variable.  This is the reason why all the paths in the various \&.am
 files are relative to the top-level directory: at the end we will
 have only one Makefile in the top-level directory of the build tree.
 .PP
@@ -717,7 +718,7 @@ There are no garantees on the order of execution of these 
local
 rules.  An example of local rule is the installation of GXditview.ad
 and GXditview-color.ad files in src/devices/xditview/xditview.am: if
 theses files are already installed, the old files are first saved.
-Also, the final file that is installed is stripped from its .ad
+Also, the final file that is installed is stripped from its \&.ad
 suffix.  Thus the usage of a custom rule rather than the definition
 of a \*[CODE]xxx_DATA\*[CODE OFF] variable:
 .FLEX
diff --git a/doc/meintro.me.in b/doc/meintro.me.in
index 1610feed..e7034c1c 100644
--- a/doc/meintro.me.in
+++ b/doc/meintro.me.in
@@ -1348,9 +1348,9 @@ This is the first point.
 This is the second point.
 Points are just regular paragraphs
 which are given sequence numbers automatically
-by the .np request.
+by the \&.np request.
 \&.pp
-This paragraph will reset numbering by .np.
+This paragraph will reset numbering by \&.np.
 \&.np
 For example,
 we have reverted to numbering from one now.
@@ -1362,9 +1362,9 @@ This is the first point.
 This is the second point.
 Points are just regular paragraphs
 which are given sequence numbers automatically
-by the .np request.
+by the \&.np request.
 .pp
-This paragraph will reset numbering by .np.
+This paragraph will reset numbering by \&.np.
 .np
 For example,
 we have reverted to numbering from one now.
diff --git a/doc/meintro_fr.me.in b/doc/meintro_fr.me.in
index 66fb2ddb..d8f7b2b8 100644
--- a/doc/meintro_fr.me.in
+++ b/doc/meintro_fr.me.in
@@ -159,8 +159,8 @@ Remplacez
 par le nom de votre fichier qui devra être en un mot.
 Le fichier devra être placé dans votre répertoire personnel,
 sinon remplacez foo par le chemin du fichier.
-À la place de .ps,
-vous pouvez mettre .pdf ou le format que vous désirez obtenir.
+À la place de \&.ps,
+vous pouvez mettre \&.pdf ou le format que vous désirez obtenir.
 Vous trouverez un description plus complète des options pour la commande
 \*G en tapant
 .b "man groff"
@@ -1361,9 +1361,9 @@ Ceci est le premier point.
 Ceci est le second point.
 Les "points" sont juste des paragraphes normaux
 auxquels on donne automatiquement un numéro
-à l'aide de la requête .np.
+à l'aide de la requête \&.np.
 \&.pp
-Ce paragraphe remet la numérotation par .np à 1.
+Ce paragraphe remet la numérotation par \&.np à 1.
 \&.np
 Là par exemple,
 nous avons recommencé la numérotation à 1.
@@ -1375,9 +1375,9 @@ Ceci est le premier point.
 Ceci est le second point.
 Les "points" sont juste des paragraphes normaux
 auxquels on donne automatiquement un numéro
-à l'aide de la requête .np.
+à l'aide de la requête \&.np.
 .pp
-Ce paragraphe remet la numérotation à 1 à cause de .pp.
+Ce paragraphe remet la numérotation à 1 à cause de \&.pp.
 .np
 Là par exemple,
 nous avons recommencé la numérotation à 1.
@@ -1606,7 +1606,7 @@ CONCLUSIONS
 .)b
 avec des espacements appropriés pour une thèse.
 L'en-tête aussi est déplacé en bas de page
-sur la première page d'un chapitre\** .
+sur la première page d'un chapitre\** \&.
 .(f
 \**Voir la première page de ce document
 .)f
@@ -1967,7 +1967,7 @@ des documents
 qui seront joliment imprimés
 sur un terminal normal,
 ou, si vous avez besoin d'un photocompositeur,
-en utilisant le programme de formatage \*T .
+en utilisant le programme de formatage \*T \&.
 .sh 2 "Polices"
 .pp
 Une
@@ -2056,7 +2056,7 @@ génère
 .)b
 Notez que les requêtes de pseudo-police
 ne mettent qu'un seul paramètre dans la pseudo-police;
-les requêtes de police ordinaire (.r, .i, .b, et .bi)
+les requêtes de police ordinaire (.r, \&.i, \&.b, et \&.bi)
 vont commencer à mettre
 tout le texte qui suit
 dans la police spéciale
@@ -2066,7 +2066,7 @@ si vous ne fournissez pas de paramètre précis\**.
 commencer une nouvelle ligne directement après la requête.
 La police spéciale sera maintenue jusqu'à la fin du paragraphe.
 .)f
-Si vous utilisez ces requêtes de pseudo-polices (.u, .bx)
+Si vous utilisez ces requêtes de pseudo-polices (.u, \&.bx)
 au milieu des lignes,
 elles ne devraient porter vraiment que sur un seul mot.
 Ceci à cause de la manière
@@ -2167,7 +2167,7 @@ avec la requête
 .)b
 ou en
 .q enlever
-en utilisant le signe - à la place de + .
+en utilisant le signe - à la place de + \&.
 .br
 L'
 .i "espacement vertical"\**
@@ -2186,7 +2186,7 @@ Avec
 .i temporaires !!!
 Pour revenir à la taille par défaut, tapez simplement
 .(b
-\& .sz
+\& \&.sz
 .)b
 Si vous voulez influencer systématiquement
 la taille des éléments de votre texte,
diff --git a/doc/pic.ms b/doc/pic.ms
index fc140db9..a6f22a45 100644
--- a/doc/pic.ms
+++ b/doc/pic.ms
@@ -1004,7 +1004,8 @@ The second arrow in Figure \*[SN]2 dropped downwards from 
the circle's
 attachment point for an
 object to be joined to the right.
 .PP
-The meaning of the command \fBmove to last circle .s\fP should be obvious.
+The meaning of the command \fBmove to last circle \&.s\fP should be
+obvious.
 In order to see how it generalizes, we'll need to go into detail on two
 important topics; locations and object names.
 .
@@ -1193,7 +1194,7 @@ compass(ellipse wid 1.5 ht 1);
 .LP
 these are the locations where eight compass rays from the geometric center
 would intersect the figure.
-So when we say \fBlast circle .s\fP we are referring to the south
+So when we say \fBlast circle \&.s\fP we are referring to the south
 compass point of the last circle drawn.
 The explanation of Figure 8-3's program is now complete.
 .PP
@@ -1257,7 +1258,7 @@ Positions may be added or subtracted to yield a new 
position (to be
 more precise, you can only add a position and an expression pair; the
 latter must be on the right side of the addition or subtraction sign).
 The result is the conventional vector sum or difference of coordinates.
-For example, \fBlast box .ne + (0.1, 0)\fP is a valid position.
+For example, \fBlast box \&.ne + (0.1, 0)\fP is a valid position.
 This example illustrates a common use, to define a position slightly
 offset from a named one (say, for captioning purposes).
 .NH 3
@@ -1436,9 +1437,9 @@ By default, the \fBchop\fR modifier shortens both ends of 
the line by
 \fBcirclerad\fR.
 By suffixing it with a number you can change the amount of chopping.
 .PP
-If you say \fBline .\|.\|.\& chop \fIr1\fP chop \fIr2\fP\fR with \fIr1\fP
-and \fIr2\fP both numbers, you can vary the amount of chopping at both
-ends.
+If you say \fBline \&.\|.\|.\& chop \fIr1\fP chop \fIr2\fP\fR with
+\fIr1\fP and \fIr2\fP both numbers, you can vary the amount of chopping
+at both ends.
 You can use this in combination with trigonometric functions to write
 code that deals with more complex intersections.
 .
@@ -1503,9 +1504,9 @@ compass([junction()]);
 .CE "1: A sample composite object"
 .LP
 To refer to one of the composite's attachment points, you can say
-(for example) \fBA .s\fP.
+(for example) \fBA \&.s\fP.
 For purposes of object naming, composites are a class.
-You could write \fBlast [] .s\fP as an equivalent reference, usable
+You could write \fBlast [] \&.s\fP as an equivalent reference, usable
 anywhere a location is needed.
 This construction is very important for putting together large,
 multi-part diagrams.
@@ -1926,7 +1927,7 @@ source up to the next \fB.PE\fP.
 In either of the last two \fBcopy\fP commands, GNU \fBgpic\fP permits a
 trailing `\fBuntil\fP \fIword\/\fP' clause to be added which terminates
 the copy when the first word matches the argument (the default
-behavior is therefore equivalent to \fBuntil .PE\fP).
+behavior is therefore equivalent to \fBuntil \&.PE\fP).
 .PP
 Accordingly, the command
 .RS
@@ -3218,7 +3219,7 @@ The macro may be called as
 .R
 .DE
 .LP
-The arguments (if any) are substituted for tokens $1, $2 .\|.\|.\& $n
+The arguments (if any) are substituted for tokens $1, $2 \&.\|.\|.\& $n
 appearing in the replacement text.
 To undefine a macro, say \fBundef\fP \fIname\fR, specifying the name to
 be undefined.
diff --git a/doc/webpage.ms b/doc/webpage.ms
index a4018566..26d5970e 100644
--- a/doc/webpage.ms
+++ b/doc/webpage.ms
@@ -342,10 +342,10 @@ option by default, unless a request similar to:
 .fi
 .in
 
-is invoked during input file processing; (`.if !\en[PHASE] ...\&' ensures
-that the effect of the `.tm' request is restricted to the document setup
-phase of processing, as pdfroff sets it to 1 or\~2 in the output phase,
-but leaves it unset in the setup phase).
+is invoked during input file processing; (`.if !\en[PHASE] \&...\&'
+ensures that the effect of the `.tm' request is restricted to the
+document setup phase of processing, as pdfroff sets it to 1 or\~2 in the
+output phase, but leaves it unset in the setup phase).
 
 The bundled `spdf.tmac' macro package, which implicitly activates
 `\-mpdfmark' for `ms' macro users, ensures that TOC relocation is
@@ -552,7 +552,7 @@ macro packages
 .ULS
 .LI
 A new macro `%U' has been added to the mdoc package to indicate a URL
-reference within an .Rs/.Re environment.
+reference within an \&.Rs/.Re environment.
 
 .LI
 Rudimentary support for the Japanese script has been added, most
@@ -609,7 +609,7 @@ equivalents to the \eX and \eY escapes, respectively.
 
 .LI
 A new read-only number register `.br' is available which is set to\~1
-if a macro is called as .foo and to\~0 if called as 'foo.
+if a macro is called as \&.foo and to\~0 if called as \&'foo.
 This allows reliable modification of requests.
 
 .in 2m
@@ -945,7 +945,7 @@ to handle normal groff number operations without risking 
overflow errors).
 .LI
 For \-ms, Eric S.\& Raymond contributed support for ancient Bell Labs
 localisms `.SC', `.UC', `.P1', and `.P2'.
-The latter three are enabled only after .SC is called.
+The latter three are enabled only after \&.SC is called.
 
 .LI
 A new string, `SN-STYLE', has been added to the ms macros, controlling
@@ -965,7 +965,7 @@ troff
 
 .ULS
 .LI
-Analogously to the .ft and \ef pair, two new requests `gcolor' and
+Analogously to the \&.ft and \ef pair, two new requests `gcolor' and
 `fcolor' (which pair with \em and \eM, respectively) have been added to
 set the glyph and background colours.
 
@@ -1574,13 +1574,13 @@ available:
 
 .in 2m
 .ft C
-\eD\[aq]Fr ...\&\[aq] \f[R](rgb)\f[]
+\eD\[aq]Fr \&...\&\[aq] \f[R](rgb)\f[]
 .br
-\eD\[aq]Fc ...\&\[aq] \f[R](cmy)\f[]
+\eD\[aq]Fc \&...\&\[aq] \f[R](cmy)\f[]
 .br
-\eD\[aq]Fg ...\&\[aq] \f[R](gray)\f[]
+\eD\[aq]Fg \&...\&\[aq] \f[R](gray)\f[]
 .br
-\eD\[aq]Fk ...\&\[aq] \f[R](cmyk)\f[]
+\eD\[aq]Fk \&...\&\[aq] \f[R](cmyk)\f[]
 .br
 \eD\[aq]Fd\[aq] \f[R](default color)\f[]
 .ft R
@@ -1968,7 +1968,7 @@ environment variable also.
 
 For defining color components as fractions between 0 and\~1, a new scaling
 indicator `f' has been defined: 1f\~=\~65536u.
-For testing whether a color is defined (with .if and .ie), a new
+For testing whether a color is defined (with \&.if and \&.ie), a new
 conditional operator `m' is available.
 
 More details can be found in the groff_diff.7 manual page and in
diff --git a/src/devices/gropdf/gropdf.1.man b/src/devices/gropdf/gropdf.1.man
index e2814824..27429f70 100644
--- a/src/devices/gropdf/gropdf.1.man
+++ b/src/devices/gropdf/gropdf.1.man
@@ -765,7 +765,7 @@ below, this text is ignored.
 .B \[rs]X\[aq]ps: exec %%%%ENDONCE\[aq]
 This terminates the block defined by %%%%BEGINONCE.
 This pair of commands
-is what implements the .BLOCKS Once/.BLOCKE commands in present.tmac.
+is what implements the \&.BLOCKS Once/.BLOCKE commands in present.tmac.
 .LP
 The
 .B mom