Re: groff 1.22.4 mandb 2.11.2 man -H tbl not rendered

[G. Branden Robinson]

[redirecting to groff@gnu; bug-groff is mainly a reflector for the
Savannah ticket tracker for groff]

Hi Brian,

At 2023-02-11T18:17:49-0700, Brian Inglis wrote:
> Hi folks,
> 
> Running Cygwin groff 1.22.4 mandb 2.11.2 man -H tbl is not rendered from
> newlib strftime.3 man page (truncated after .TE, 44 redundant occurrences of
> "l l" removed before "l l.", other lines commented out in .3 file attached,
> as is generated HTML, and docbook source: see below).

Ah.  DocBook source.  I'll give you the bad news first: a high-quality
converter of DocBook documents to man(7) is not known to the groff
community.

I un-commented the following lines to reduce the number of warnings I
saw.

.ie \n(.g .ds Aq \(aq
.el       .ds Aq '

> This man page tbl extract is interesting, as it needs at least the .TH
> directive plus the .TS/.../.TE lines to generate the tty man page,

Yes.  I got the following diagnostics from groff Git HEAD.

$ ./build/test-groff -ww -t -man -Thtml \
    ~/Downloads/newlib-strftime-tbl.3>strf.html
/home/branden/Downloads/newlib-strftime-tbl.3:49: error: boxed table does not 
fit on page 1; use .TS H/.TH with a supporting macro package
troff: error: suppression limit registers span more than a page; grohtml-info 
for image 1 will be wrong

(The second diagnostic can be ignored for our purposes.)

You (well, the DocBook-related tool) needs to construct the table with
".TS H" instead of plain ".TS".  This is a hard requirement for
multi-page tables that are boxed or for which column heading repetition
is desired.

The only reason the table renders anyway on the terminal is because the
groff man(7) package has a feature that grows the page length in an
unbounded[1] way.  This is termed "continuous rendering" in the
groff_man(7) man page.  If you turn this feature off with the "-rcR=0"
option to the formatter...

$ ./build/test-groff -ww -t -rcR=0 -man -Tascii \
    ~/Downloads/newlib-strftime-tbl.3 | less -R

...you will get the same problem.  I got it for PostScript, too, so I
expect this document's problem to afflict every output device except
terminals, and those as well if continuous rendering is not used.

> whereas tables from other man pages can be extracted and still render
> on both tty and HTML.

I suspect that this is because they, perhaps accidentally, manage to
follow the rules about composing large tables.

> If you can point me to something in the tbl content that is
> problematic and/or how to fix it, given the below, then I could work
> my way back down the chain to fix the root cause, or determine it is a
> groff/man bug, possibly fixed in the pending release, I would greatly
> appreciate the pointer.

I do not observe any bugs with groff/man/tbl for this page with groff
Git HEAD.  (Some significant bugs in tbl have been fixed since groff
1.22.4,[3] but at a glance I don't see any implicated by this input.)

I will note that the table is composed with one hand tied behind its
back, so to speak, by using text blocks in the right-hand column but not
the "x" column modifier in that column to permit it to expand until the
table fills the available line length.  Unfortunately that is not enough
to repair this table's interaction with the HTML output device, but it
is nevertheless a tbl(1) feature that any converter to *roff/man/tbl
output should exercise when warranted.

Long story short, the line:

l l.

could become

l lx.

profitably.

The forced call of paragraphing macros at the start of every text block
is also unidiomatic, and, given that it puts a blank line at the top of
the table cell, ugly as well.

> [The man page source comes from docbook comments embedded in the
> source:

Er, uh, looking at it, are you sure this is DocBook?

Compare

https://en.wikipedia.org/wiki/DocBook#Sample_document

with
> https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/time/strftime.c

  18 /*
  19 FUNCTION
  20 <<strftime>>, <<strftime_l>>---convert date and time to a formatted string
  21
  22 INDEX
  23         strftime
  24
  25 INDEX
  26         strftime_l
  27
  28 SYNOPSIS
  29         #include <time.h>
  30         size_t strftime(char *restrict <[s]>, size_t <[maxsize]>,

...this really does not look like DocBook to me.  (Admittedly I haven't
looked at DocBook in well over a decade.)  Perhaps it is some other
plain text markup format that has sworn to supplant all others.[2]
ReST?  Sphinx?

On the bright side, if it isn't DocBook, there is a less notorious
legacy of failure in producing *roff/man/tbl output from it.  So maybe
the problems _can_ be fixed.

I'm afraid using ".TS H" for large boxed tables is a non-negotiable
item simply due to the way the *roff systems format pages.  (Details
available upon request.)  On the bright side, if a table has column
headings, using ".TS H" even on a table with few enough rows to fit a
single page is harmless.  But on the gripping hand, this is not done in
man(7) pages because of the name collision between tbl's understanding
of '.TH' (marking the end of column headings) and man(7)'s (start a new
man page document).  This collision could be worked around, but I've
seldom seen demand for multi-page tables in man pages expressed.

This table lacks column headings altogether, however, so my prescription
would be to drop the "allbox" region option.  It is a cosmetic feature
and not required in most tables.

Indeed, if I add the "x" column modifier, drop "allbox", and kill the
".PP" calls inside all the text blocks, the content formats pleasantly
enough on PostScript.  The blank lines between table rows can be
recovered with a quick bit of Vim to emplace blank table rows after each
text block.  I'm attaching a specimen.

But really at this point I have to wonder why the translation tool
doesn't format input like this using tagged paragraphs.  This is the
`TP` macro, documented in groff_man(7).

> via makedocbook python script which generates xml (attached),

I think maybe something is generating DocBook or DocBook-XML _from_ this
<<nesty bracket>> markup as the initial stage.

> then docbook generates html, man pages, PDFs, texinfo, and the latter
> generate libc info.]

Personally, I lack confidence in DocBook to occupy this central role in
document format interconversion.  Others on the groff list may want to
share their experiences.

Regards,
Branden

[1] technically not unbounded; to 2^31-1 basic units
[2] https://xkcd.com/927/
[3] 
https://savannah.gnu.org/bugs/index.php?go_report=Apply&group=groff&func=&set=custom&msort=0&report_id=225&advsrch=0&bug_id=&summary=&submitted_by=0&resolution_id=0&assigned_to=0&bug_group_id=0&status_id=3&severity=0&category_id=109&plan_release_id=103&history_search=0&history_field=0&history_event=modified&history_date_dayfd=12&history_date_monthfd=2&history_date_yearfd=2023&chunksz=50&spamscore=5&boxoptionwanted=1#options

(I wish Savannah didn't have such ridiculous query URLs; most of these
parameters recapitulate defaults.)

newlib-strftime-tbl-gbr.3
Description: Text document

signature.asc
Description: PGP signature