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

[Brian Inglis]

On 2023-02-13 22:10, G. Branden Robinson wrote:
> At 2023-02-13T16:41:42-0700, Brian Inglis wrote:
> > On 2023-02-12 18:48, G. Branden Robinson wrote:
> > > At 2023-02-11T18:17:49-0700, Brian Inglis wrote:
> > 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.
>
> Great!  I'm glad you've found a local optimum that isn't too painful. :)
>
> > I will highlight tables need to be less than a page.
>
> I'm curious to know how people in the ultimate source format (you said
> something about comments embedded in source code) are supposed to judge
> this.  That said, the list of format conversions supported by newlib's
> strftime() is so lengthy that it would take quite an optimist to not
> expect it to overrun any conventional paper format.
>
> I don't want to make any promises, but we might be able to implement a
> fairly cheap fix for this problem in grohtml early in the groff 1.24
> development cycle.
>
> Essentially, I want a "maxint" register and since "page length" is
> conceptually an odd fit for HTML anyway, I'd very much like to
> try out setting the page length on groff's "html" output device to the
> value of that maxint register.
>
> https://savannah.gnu.org/bugs/index.php?63587
>
> > It is docbook xml - see the previously attached xml and that in the
> > attached archive.
>
> Yes, the strftime.xml file looks like the DocBook I remember.  But...
>
> https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/libc/time/strftime.c#l18
>
> ...does not.  I have a vague unease that information could be getting
> captured there, at the ultimate source level ("the preferred form for
> making changes to the work", as the GNU GPL puts it), that isn't being
> done, making the generated DocBook less expressive and therefore
> transformed more poorly into *roff/man/tbl.
>
> Do you have a name for the inline documentation format with these double
> angle brackets?  It isn't Doxygen or a literate programming markup
> format I'm familiar with.  I can't even say for sure if I've seen it
> before.

The newlib docs call it texinfo, but the HOWTO documents reality:

https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/HOWTO

that it's a mix of embedded *chew* and texinfo "documented" somewhat in:

https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/doc/makedoc.c

written by Mr.Cygnus Steve Chamberlain, which produces texinfo def output and:

https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/doc/makedocbook.py

which works like makedoc to produce DocBook xml;

and all the texinfo output is used to integrate generated and non-functional doc 
source xml files into docs:

https://sourceware.org/git/?p=newlib-cygwin.git;a=blob;f=newlib/doc/chapter-texi2docbook.py

and each format is used to produce doc formats comparable to GNU manual formats, 
using their doc toolchains.

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

> Right...the DocBook that is the "source" for generating *roff et al. is
> itself an intermediate format. When I say "source" I typically mean
> "the format you opened in your text editor to work on".

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

Some? GNU packages use gtk-doc which also produces DocBook and converts those to 
Latex with dblatex then via the TeXlive hydra to consumable formats, as well as 
TeXinfo.

> > 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.
>
> Yes, I still get the format-time warning from tbl about the multi-page
> boxed table, and, when formatting for HTML, the screeching from grohtml
> about the suppression limit registers.
>
> (It took me a long time, but I finally learned what that diagnostic
> means, and I am uncertain that we really need to be throwing it.)
>
> But the real fix for several forms of grief would be this:
>
> https://savannah.gnu.org/bugs/index.php?60052

That would be nice

> > 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, if docbook cooperates. ;^>
>
> I'll take your word for it; the syntax you're quoting is utterly
> unfamiliar to me.  I assume it is the unnamed double-angle-bracket
> language I referred to above.

There are also source DocBook xml files used to generate non-functional man 
pages, more common for Cygwin emulation docs: I got annoyed with discrepancies 
between Linux and Cygwin proc(5) and updated the latter in xml! ;^p
So I can understand why asciidoc, chew, doxygen, gtk-doc, javadoc, markdown, 
perldoc, TexInfo were created: to avoid writing DocBook xml; but like roff... 
shows, human docs are complex to specify and produce.

> > 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.
>
> Thank you very much!  I'm afraid I don't know who the Cygwin package
> maintainer for groff even is at present.  It would be good to be
> introduced.  It can be benefit to keep topological distances low.  :)

I use Repology.org:

        https://repology.org/project/groff/versions

also Cygwin source packages document their maintainer:

        https://cygwin.com/packages/summary/groff-src.html

and he is also the primary perl package maintainer.

> Incidentally, I advised groff's maintainer, Bertrand Garrigues, that I
> am ready for RC3 or final release at his discretion.

It will be nice to see all the cleanup done over the pandemic released.

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