bugGNU roff - Bugs: bug #62841, [man] stop forcing vertical space...

 
 

bug #62841: [man] stop forcing vertical space before tbl(1) tables

Submitter:  G. Branden Robinson <gbranden>
Submitted:  Sat 30 Jul 2022 04:47:23 PM UTC
   
 
Category:  Macro man Severity:  4 - Important
Item Group:  Feature change Status:  Fixed
Privacy:  Public Assigned to:  gbranden
Open/Closed:  Closed Planned Release:  1.23.0
* Mandatory Fields

Add a New Comment Rich Markup
   

Sun 28 Aug 2022 10:05:55 AM UTC, comment #3: 
Ingo Schwarze <schwarze>
Group Member
Sun 28 Aug 2022 08:06:31 AM UTC, comment #2: 

This is an incompatible change, changing the output for large numbers of existing manual pages.  So in addition to asking "Does this change make writing new pages simpler and more flexible and more consistent?", which gbranden@ answers affirmatively below (and i agree with him so far), another reasonable question to ask is "Does it typically improve or degrade the rendering of existing real-world manual pages?"

As a random sample, i took the manual pages in the OpenBSD base system and individually looked at each one in turn.  Here are the results (i stopped after about one third of X11 because a clear pattern is emerging; all non-X11 pages were inspected though):

now looks better because it expects tbl to directly follow preceding text:
  XAllocSizeHints(3) XAllocStandardColormap(3) XChangeKeyboardControl(3)
  XConfigureWindow(3) XCreateWindow(3) XGetVisualInfo(3)

now looks better because of existing .sp before .TS:
  curs_getch(3)
  bitmap(1) editres(1)
  GLwDrawingArea(3) GLwMDrawingArea(3)
  XkbActionCtrls(3) XkbAllocCompatMap(3) XkbBell(3) XkbAllocControls(3)

now looks worse because of missing .PP:
  captoinfo(1) infocmp(1)
  curs_inch(3)
  xterm(1) Yserver(1)
  XkbAllocClientMap(3)

inconsistent use within the same page, parts better, parts worse:
  xedit(1)
  XAllocWMHints(3) XCreateGC(3)

now looks worse because of explicit trailing .sp 2v:
  tbl)7)

output unchanged:
  llvm-objcopy(1)
  curs_addch(3) curs_attr(3) curs_mouse(3) curses(3) form(3) menu(3)
  phantasia(6)
  mkhybrid(8)
  xcalc(1)
  XDrawArc(3) XGetWindowAttributes(3) XQueryColor(3)

irrelevant, uses very bad formatting in the first place:
  terminfo(5)

To summarize, existing usage is wildly inconsistent among real-world pages.  There is a significant minority of pages that look worse after this change, but that cannot really be called a regression because there are similar, and possibly larger, numbers that look better.

To express the same conclusion in a different way, it appears very few manual page authors understood how spacing before .TS was supposed to work, which implies that changing the rules mid-game and simplifying them makes sense.  The benefit of simplicity and consistency in the rules clearly outweighs the occasional formatting degradation, which is besides easy to fix by adding .PP before .TS in the pages in question.

I'll follow with mandoc(1).

I did change the "Item Group" from "Cosmetics" to "Feature Change" though because it is a man(7) API change.  It changes the semantics off the .TS macro, it changes how authors have to use .TS in manual pages, and it needs to be announced as a feature change that is imposed without providing backward compatibility.  (And i don't think backward compatibility would be feasible.)

I also changed the "Severity" from "Normal" to "Important": if we have to tell users that they need to change their finger memory, that is important.

Ingo Schwarze <schwarze>
Group Member
Sun 31 Jul 2022 12:44:01 AM UTC, comment #1: 


commit 7ec36dc9b9618fac504bb0920a2d2bcfed4eedf4 (HEAD -> master, origin/master, origin/HEAD)
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
Date:   Sat Jul 30 18:44:03 2022 -0500

    [man]: Stop adding vertical space before tables.

    * tmac/an.tmac (TS): Stop inserting space before tables.  Unlike ms(7),
      man(7) has no concept of "displays" and thus none of "display
      distance".  It is up to the page author to use paragraphing macros
      around tables if vertical space is desired.  And not up to us to
      impose it.

    Fixes <https://savannah.gnu.org/bugs/?62841>.


G. Branden Robinson <gbranden>
Group administrator
Sat 30 Jul 2022 04:47:23 PM UTC, original submission:  

I'm slowly picking the spacing bugs out of tbl, particularly in nroff mode.

It's getting to the point where we can undo what I assume was a workaround for rendering problems 20 years ago.

The following commits seem relevant.


commit 7ef622e18f30f74b20d1dfa71c5e3174b7feecec
Author: Werner LEMBERG <wl@gnu.org>
Date:   Wed Jan 16 22:58:46 2002 +0000

    * tmac/an-old.tmac (TS): Force break, inserting some vertical space.

diff --git a/tmac/an-old.tmac b/tmac/an-old.tmac
index 4920c9150..0e064e9c4 100644
--- a/tmac/an-old.tmac
+++ b/tmac/an-old.tmac
@@ -493,6 +493,7 @@
 .\" table support
 .
 .de1 TS
+.  sp \\n[PD]u
 .  if n \{\
 .    nr an-pl \\n[.p]
 .    pl \\n[nl]u

commit 777e2d262862621966c18d685a000cc88f432bc6
Author: Werner LEMBERG <wl@gnu.org>
Date:   Sat Jan 26 07:52:05 2002 +0000

    * tmac/groff_ms.man: Typographical improvements.

    * doc/groff.texinfo: Updated version and copyright.
    * src/devices/grops/grops.man: Updated.

    * tmac/groff_tmac.man: Fix `ig' macro.

    * tmac/an-old.tmac (ne): Redefine `ne' request to be a no-op in
    nroff mode.
    Use `.ne' unconditionally everywhere.
    (TS): Only insert some vertical space.  Doing a page break is no
    longer necessary due to the redefinition of the `ne' request.

    * src/libs/libdriver/input.cc (parse_D_command): Don't emit a
    warning for unknown subcommands but parse and pass them to the
    device driver.

[snip]
iff --git a/tmac/an-old.tmac b/tmac/an-old.tmac
index 0e064e9c4..b9e3da83d 100644
--- a/tmac/an-old.tmac
+++ b/tmac/an-old.tmac
[snip]
@@ -494,12 +499,6 @@
 .
 .de1 TS
 .  sp \\n[PD]u
-.  if n \{\
-.    nr an-pl \\n[.p]
-.    pl \\n[nl]u
-.    bp
-.    pl \\n[an-pl]u
-.  \}
 ..
 .
 .de1 TE


These look to me like efforts to wrestle the continuous-rendering beast into submission, which I can attest is a hell of a challenge.

I think we have room to express a simpler rule now.

If you want your table to be preceded by vertical space, use a paragraphing macro.[1]

If you don't want your table to be preceded by vertical space, don't precede it with a paragraphing macro.

A fix that makes it unnecessary to follow a boxed table with a paragraphing macro just to avoid overprinting the table's bottom border in nroff mode is pending.  See bug #49390.

So tables in man pages will shortly be better behaved.

[1] If you start a (sub)section with a table, that won't work, but it's not supposed to.  Good style may suggest that you should discuss the table before presenting it, in any case.

G. Branden Robinson <gbranden>
Group administrator

 

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

Attach Files:
   
   
Comment:
   

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by schwarze (Posted a comment)
  • -email is unavailable- added by gbranden (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 5 latest changes.

    Date Changed by Updated Field Previous Value => Replaced by
    2022-08-28 schwarze Severity3 - Normal 4 - Important
        Item GroupRendering/Cosmetics Feature change
    2022-07-31 gbranden StatusIn Progress Fixed
        Open/ClosedOpen Closed
        Planned ReleaseNone 1.23.0

    Back to the top

    Powered by Savane 3.13-758e.
    Corresponding source code