diff options
author | G. Branden Robinson <g.branden.robinson@gmail.com> | 2022-01-11 19:25:01 +1100 |
---|---|---|
committer | G. Branden Robinson <g.branden.robinson@gmail.com> | 2022-01-11 21:57:46 +1100 |
commit | cbbf97b88157283ee1b8d67d98bf15633b8d3921 (patch) | |
tree | 7c4695f3157357093871b0f06a5b6f6c605e8564 | |
parent | f051deabe9dfe2c36e24e42791444972053c0e4e (diff) | |
download | groff-git-cbbf97b88157283ee1b8d67d98bf15633b8d3921.tar.gz |
[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.
-rw-r--r-- | ChangeLog | 19 | ||||
-rw-r--r-- | contrib/hdtbl/groff_hdtbl.7.man | 4 | ||||
-rw-r--r-- | doc/automake.mom | 19 | ||||
-rw-r--r-- | doc/meintro.me.in | 8 | ||||
-rw-r--r-- | doc/meintro_fr.me.in | 24 | ||||
-rw-r--r-- | doc/pic.ms | 21 | ||||
-rw-r--r-- | doc/webpage.ms | 26 | ||||
-rw-r--r-- | src/devices/gropdf/gropdf.1.man | 2 |
8 files changed, 72 insertions, 51 deletions
@@ -1,5 +1,24 @@ 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): * man/groff_font.5.man (Font description file format): Document restriction of kerning adjustment to glyph pairs from within a diff --git a/contrib/hdtbl/groff_hdtbl.7.man b/contrib/hdtbl/groff_hdtbl.7.man index 27d146c50..24a6ba452 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 839634008..10e72fd6a 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 1610feed6..e7034c1c7 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 66fb2ddb6..d8f7b2b8f 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 fc140db93..a6f22a453 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 a40185663..26d5970e4 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 e2814824e..27429f70f 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 |