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

[Brian Inglis]

On 2023-02-12 18:48, G. Branden Robinson wrote:
> [redirecting to groff@gnu; bug-groff is mainly a reflector for the
> Savannah ticket tracker for groff]
> At 2023-02-11T18:17:49-0700, Brian Inglis wrote:
> > 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.

Thanks very much Branden,
These comments really help.
I have hacked around between the original and your suggested approach to find 
something that will work for now.
I will highlight tables need to be less than a page.

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

Agreed.

> > [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
> ...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.

It is docbook xml - see the previously attached xml and that in the attached 
archive.

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

No options here - would have to redo the whole flow with available tools.
Wanted to replace all images with webp compressed for speed on mobiles but 
somewhere in the chain did not yet support those and stated they would never!

I worked from your gbr suffix page, playing around with the test suffix, not 
getting far with html output anyway, and decided the only solution was to split 
the table, see suffixes -split (and -new for complete doc), which render 
properly in html and utf8, but groff still complains: run attached script for 
giggles.

From the source code, it looks like the comment list delimiters are o+/o- (and 
o\s for list items), so adding a couple of those lines about where %Ox is in the 
table, should give us a split table that renders completely on all devices, of 
docbook cooperates.  ;^>

I will ask the Cygwin groff package maintainer to give us a test preview, once 
you release, so we can check newlib, Cygwin, and any related doc flows.

--
Take care. Thanks, Brian Inglis                 Calgary, Alberta, Canada

La perfection est atteinte                      Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter     not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer        but when there is no more to cut
                        -- Antoine de Saint-Exupéry

newlib-strftime.tar.xz
Description: Binary data