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

[Ingo Schwarze]

Update of bug #62841 (project groff):

                Severity:              3 - Normal => 4 - Important          
              Item Group:     Rendering/Cosmetics => Feature change         

    _______________________________________________________

Follow-up 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.


    _______________________________________________________

Reply to this item at:

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

_______________________________________________
Message sent via Savannah
https://savannah.gnu.org/