[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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

From: Brian Inglis
Subject: Re: groff 1.22.4 mandb 2.11.2 man -H tbl not rendered
Date: Mon, 13 Feb 2023 16:41:42 -0700
User-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.7.2

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
I un-commented the following lines to reduce the number of warnings I
.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 \
/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 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.
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
Er, uh, looking at it, are you sure this is DocBook?
...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

Attachment: newlib-strftime.tar.xz
Description: Binary data

reply via email to

[Prev in Thread] Current Thread [Next in Thread]