bugGNU roff - Bugs: bug #51328, [man pages] prevent unintended...

 
 

bug #51328: [man pages] prevent unintended inter-sentence space

Submitter:  Bjarni Ingi Gislason <bjarniig>
Submitted:  Tue 27 Jun 2017 07:11:30 PM UTC
   
 
Category:  General Severity:  2 - Minor
Item Group:  Lint Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Fri 17 Jun 2022 04:51:08 AM UTC, comment #4: 

I've fixed this independently with a variety of commits over the past few years.  Here's a sample.


commit fd04c52f8093fd3fadf1bee54d4016bf89244b5a
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Jun 15 06:04:56 2022 -0500

    chem(1): Fix markup nits.

    Use idiomatic input style, placing newlines after sentences and commas.
    Also put an empty request between sentences.

commit c66e7ce030ce764cb02a0267a49e147e15adebfd
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Wed Jun 15 01:41:09 2022 -0500

    [man pages]: Fix markup nit.

    Add `\&` after a dot followed by multiple spaces in displayed examples,
    to keep the rendering consistent even if the reader changes the
    supplemental inter-sentence space amount.

commit 2d8c81931640e263653a4ff3b377cabfdb530ce9
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Mar 31 06:45:53 2022 +1100

    roff(7): Fix style and markup nits.

    * Add `\&` after sentence-ending candidate punctuation when discussing
      this very feature.
    * Wrap long input line.

commit 79afd29a346f97c687fadb1878e66471803955b3
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Oct 31 21:07:06 2021 +1100

    tbl(1): Do some spot cleaning.

    Content:
    * Start standardizing the term "(table) region" as that material between
      ".TS" and the first subsequent ".TE".
    * Start standardizing the term "(table) description".  (A table region
      consists of one (or more, separated by .T&) table description(s)).
    * Add parenthetical paragraph aiding the reader who knows just enough
      *roff to start making unwarranted assumptions (as I once did, and
      probably will continue to do).  Try to clarify the fact that ".TS",
      ".T&", ".TE" are input tokens to tbl, but macro calls to troff.
    * When introducing the term "decimal separator", note that it is
      configurable, in hopes of justifying the sesquipedalian terminology.
    * Speak of "alignment", not "justification".
    * Advise when tbl(1) generates *roff code to produce warning messages.
      (There are other cases not yet noted.)
    * Prefer "table entries" to "data items".
    * Instead of talking about "whitespace", identify specific input
      characters.
    * Remove discussion of "column separator lines" (not allowing '_', '-',
      or '='); I couldn't figure out what was meant.

    Style:
    * Recast to use more formal and idiomatic English.
    * Stop ending sentences with colons.
    * Speak consistently of "GNU extensions", not "GNU tbl only".  Other
      implementations might adopt GNU extensions.
    * Say "AT&T", not "Unix", tbl.  There are many Unices and not all
      shipped AT&T troff (or not exclusively).
    * Use "\[em]", not " \[en] ", to "break" (interrupt) a sentence.
    * Turn some sentence fragments into parentheticals.
    * Add space after commas in table format specifiers used as paragraph
      tags.

    Markup:
    * Break input lines after commas.
    * Break input lines before and after multi-word parentheticals.
    * Use two empty requests where vertical space is expected.
    * Protect non-sentential dots from end-of-sentence detection.

commit aceac1232e2ed33d87b4fbd8fbba319d4d48681d
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sun Nov 8 11:09:58 2020 +1100

    refer(1): Avoid inter-sentence spacing after dot.


Also see:


commit c33c23a10b314393d43fd4d41306729b36ba92fa
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Tue Jun 14 19:39:00 2022 -0500

    doc/webpage.ms: Fix markup nit.

    Use `\&` after '.' and multiple spaces in unfilled example of groff
    source.  It is a better stylistic practice since additional
    inter-sentence space is applied even when filling is disabled.

commit cb1b89620ff5b0b509831a3b8ecf4f1916d34567
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Thu Dec 16 08:20:58 2021 +1100

    doc/meref.me.in: Fix feature summary table nits.

    ...observed while revising groff_me(7).

    * Remove junk comment line (I de-documented \SP in favor of \~).
    * Add non-printing input break `\&` between non-sentence ending period
      and space.
    * Be more consistent: we say "(pre/post) space", not "spacing" when
      referring to registers containing vertical distances to be inserted by
      the package adjacent to various constructs.  I try to reserve the term
      "spacing" for baseline separation (registers `$V` and `$v`).
    * Recast descriptions of `lp` and `pp` to distinguish them better.


G. Branden Robinson <gbranden>
Group administrator
Wed 15 Jun 2022 03:12:59 PM UTC, comment #3: 


comment #2:

> Wait, nope, I'm wrong about tbl(1).
>
> comment #1:
> > 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 part "or populated with inter-sentence space" needs to go, or tbl(1) needs to be fixed to honor this claim.


This issue is being pursued in bug #61909.

G. Branden Robinson <gbranden>
Group administrator
Mon 24 Jan 2022 02:45:02 PM UTC, comment #2: 

Wait, nope, I'm wrong about tbl(1).

comment #1:

> 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 part "or populated with inter-sentence space" needs to go, or tbl(1) needs to be fixed to honor this claim.  I guess I'll go see what Heirloom and Unix V7 tbl do.


$ cat EXPERIMENTS/tbl-iss.roff
.ss 12 120
.TS
L.
Foo.  Bar.
.TE
$ tgu -t EXPERIMENTS/tbl-iss.roff | cat -s
Foo.           Bar.


G. Branden Robinson <gbranden>
Group administrator
Mon 24 Jan 2022 02:40:13 PM UTC, 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?

G. Branden Robinson <gbranden>
Group administrator
Tue 27 Jun 2017 07:11:30 PM UTC, original submission:  


("Indicator" is an "end-of-sentence character" (.!?)).

The space between sentences in "roff" is two spaces.
Better is to begin each sentence on a new line to avoid different
writers' conventions.

  References:

  1) man-pages(7) from package "man-pages" or
"www.kernel.org/doc/man-pages" section 7 or
"man7.org/linux/man-pages/man7/man-pages.7.html":

"New sentences should be started on new lines.
This makes it easier to see the effect of patches,
which often operate at the level of individual sentences."

  2) groff_diff(7) in package "groff":

"In GNU troff, as in UNIX troff, you should always follow a sentence
with either a newline or two spaces."

  3) "info groff":

  Search for the word "sentence" in the output to get more hints about input
conventions.

  The patch is in the attachment.

Bjarni Ingi Gislason <bjarniig>

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

Attach Files:
   
   
Comment:
   

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by gbranden (Posted a comment)
  • -email is unavailable- added by bgarrigues (Updated the item)
  • -email is unavailable- added by bjarniig (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

    Only logged-in users can vote.

     

    Follow 12 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-06-17 gbranden Item GroupDocumentation Lint
        StatusNeed Info Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0
        Summary[PATCH] [man pages] prevent unintended inter-sentence space [man pages] prevent unintended inter-sentence space
    2022-01-24 gbranden CategoryNone General
        StatusNone Need Info
        Assigned toNone gbranden
        Summary[Patch] Manuals: Adjust space between sentences or protect the indicator [PATCH] [man pages] prevent unintended inter-sentence space
    2017-09-01 bgarrigues Severity3 - Normal 2 - Minor
        Item GroupNone Documentation
    2017-06-27 bjarniig Attached File- Added 0001-Adjust-space-after-end-of-sentences-or-protect-indicat.txt.gz, #41057

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code