[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug #51328] [PATCH] [man pages] prevent unintended inter-sentence space
|
From: |
G. Branden Robinson |
|
Subject: |
[bug #51328] [PATCH] [man pages] prevent unintended inter-sentence space |
|
Date: |
Mon, 24 Jan 2022 09:40:13 -0500 (EST) |
Update of bug #51328 (project groff):
Category: None => General
Status: None => Need Info
Assigned to: None => gbranden
Summary: [Patch] Manuals: Adjust space between sentences or
protect the indicator => [PATCH] [man pages] prevent unintended inter-sentence
space
_______________________________________________________
Follow-up Comment #1:
contrib/mm/groff_mm.7.man | 2 +-
contrib/mom/groff_mom.7.man | 2 +-
man/groff.7.man | 4 ++--
man/groff_char.7.man | 18 +++++++++---------
man/groff_diff.7.man | 2 +-
src/devices/grops/grops.1.man | 2 +-
tmac/groff_man.7.man | 4 ++--
tmac/groff_mdoc.7.man | 2 +-
tmac/groff_www.7.man | 5 +++--
9 files changed, 21 insertions(+), 20 deletions(-)
Most (6) of these have become invalidated over the years by unrelated rewrites
to the pages.
There are 3 exceptions.
diff --git a/contrib/mm/groff_mm.7.man b/contrib/mm/groff_mm.7.man
index 0b46d9381..202b98011 100644
--- a/contrib/mm/groff_mm.7.man
+++ b/contrib/mm/groff_mm.7.man
@@ -4066,7 +4066,7 @@ Format of figure, table, exhibit, and equation titles.
.TS
tab(@);
l l.
-0@\[dq]. \[dq]
+0@\[dq].\& \[dq]
1@\[dq] - \[dq]
.TE
.RE
The foregoing is unnecessary because the table entry is not in a text block.
> Ordinarily, a table entry is typeset rigidly. It is not filled,
> broken, hyphenated, adjusted, or populated with inter-sentence
> space.
(tbl(1), from groff Git HEAD)
The foregoing diff chunk is consequently invalid. However...
diff --git a/tmac/groff_www.7.man b/tmac/groff_www.7.man
index 829da51a7..08cc1399f 100644
--- a/tmac/groff_www.7.man
+++ b/tmac/groff_www.7.man
@@ -580,7 +580,7 @@ macro is defined as
.IP
.EX
\&.de BGIMG
-\&. HTML <body background=\[rs]\[rs]$1>
+\&.\& HTML <body background=\[rs]\[rs]$1>
\&..
.EE
.RE
This is a legitimate catch; the man(7) EX/EE macros disable filling, but
disabling filling does not disable the supplementation of a line with
inter-sentence space. The only way to do that is to shut it off with the
second argument to the 'ss' request (inappropriate in a man page) or to use
the non-printing input break escape sequence, as you've shown.
Six _groff_ man pages have this problem.
$ git grep -l '^\\&[.!?] ' *.man*
contrib/hdtbl/groff_hdtbl.7.man
man/groff.7.man
man/groff_char.7.man
man/groff_diff.7.man
src/preproc/eqn/eqn.1.man
tmac/groff_www.7.man
Every single one of them appears to be an example of _roff_ input.
We could tack a non-printing input break on after each of them, but I fear
offering such advice to man page writers--for one thing, it will visually
unalign the output in the source, which might make it harder to verify for
correctness, especially if indentation is being used (which is necessarily is
in these cases).
Consider the groff_char(7) case.
.RS
.EX
\&.\e" Make a pile centered vertically 0.5em above the baseline.
\&.\e" The first argument is placed at the top.
\&.\e" The pile is returned in string \[aq]pile\[aq].
\&.eo
\&.de pile\-make
\&. nr pile\-wd 0
\&. nr pile\-ht 0
\&. ds pile\-args
\&.
\&. nr pile\-# \en[.$]
\&. while \en[pile\-#] \e{\e
\&. nr pile\-wd (\en[pile\-wd] >? \ew\[aq]\e$[\en[pile\-#]]\[aq])
\&. nr pile\-ht +(\en[rst] \- \en[rsb])
\&. as pile\-args \ev\[aq]\en[rsb]u\[aq]\e"
\&. as pile\-args \eZ\[aq]\e$[\en[pile\-#]]\[aq]\e"
\&. as pile\-args \ev\[aq]\-\en[rst]u\[aq]\e"
\&. nr pile\-# \-1
\&. \e}
\&.
\&. ds pile \ev\[aq](\-0.5m + (\en[pile\-ht]u / 2u))\[aq]\e"
\&. as pile \e*[pile\-args]\e"
\&. as pile \ev\[aq]((\en[pile\-ht]u / 2u) + 0.5m)\[aq]\e"
\&. as pile \eh\[aq]\en[pile\-wd]u\[aq]\e"
\&..
\&.ec
.EE
.RE
Asking users to add a \& after every '.' followed by a space is possible, but
I would expect it to provoke grumbles.
A better solution might be to extend the semantics of the man(7) EX macro to
disable inter-sentence space and of EE to restore it. (They can save the
value of the .sss register to do this independently of how a localization
package set it. That register is a GNU extension, so I guess people who
eschew GNU can go ahead and add the '\&'s.)
Turning to our last example, groff_mdoc(7)...
diff --git a/tmac/groff_mdoc.7.man b/tmac/groff_mdoc.7.man
index c16bde5cc..db0a83aed 100644
--- a/tmac/groff_mdoc.7.man
+++ b/tmac/groff_mdoc.7.man
@@ -3169,7 +3169,7 @@ and enclosure macros: Test the value of a variable.
.Bd -literal -offset indent
\&.It Xo
\&.Ic .ifndef
-\&.Oo \e&! Oc Ns Ar variable Oo
+\&.Oo \e&!\& Oc Ns Ar variable Oo
\&.Ar operator variable ...
\&.Oc Xc
.Ed
This turns out to be a similar issue. That the display begun with 'Bd' does
not, in groff mdoc(7), imply that it is not filled. (To see this, edit the
groff_mdoc(7) page without your patch in place and put '.ss 12 120' somewhere
before the above lines. The inter-sentence space will leap out at you.)
I reckon we should see what mandoc(1) wants to do about this. It's easy
enough to handle, but which 'Bd' option should get these semantics?
_______________________________________________________
Reply to this item at:
<https://savannah.gnu.org/bugs/?51328>
_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/
- [bug #51328] [PATCH] [man pages] prevent unintended inter-sentence space,
G. Branden Robinson <=