groff
[Top][All Lists]
Advanced

[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: Tue, 14 Feb 2023 00:08:36 -0700
User-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.7.2

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



reply via email to

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