Re: [PATCH v3 0/2] newlib/libc/time/strftime: fix multi-page table format issues

Re: [PATCH v3 0/2] newlib/libc/time/strftime: fix multi-page table format issues

[Brian Inglis]

On 2023-02-22 13:10, Jon Turney wrote:
> On 21/02/2023 09:15, Corinna Vinschen wrote:
>> Jon,
>> I'd like your GTG on the patchset before merging it.

> Sorry, I don't think this patchset is good as is.

>> On Feb 20 21:17, Brian Inglis wrote:
>>> Discussion about why newlib man generation by docbook2man is
>>> incompatible with how man is incompatible with groff/tbl/grohtml:
>>>     https://lists.gnu.org/archive/html/bug-groff/2023-02/msg00118.html
>>> There does not appear to be good way to deal in docbook2man processing
>>> with generation of tables > "page" size, or that may not adversely affect
>>> other [newlib] doc man page tables, as the problem occurs solely on the
>>> strftime.3 man page!

> So, this seems to be saying that "strftime manpage misrenders under some 
> circumstances", but I even after re-reading several times, I have no clear sense 
> what that circumstance is exactly: generating html output? with current version 
> of groff? a future one?
> (Your answer should be a single sentence)

Current groff tbl pre-/processing generates table images for non-tty 
"devices"/file formats where tables > "page" size disappear if it is not handled 
appropriately, but the proper solution for tbl preprocessor output from groff 
can not be used, as there is a conflict between man requiring macro .TH and tbl 
needing command .TH to be passed thru to fix the problem - can't be done!

>>> The imminent groff/tbl release fixes a number of tbl issues, so may
>>> affect man pages with tables differently.
>>> The following groff/grohtml release plans to change grohtml, from
>>> generating tables as PNG graphics, which don't work reliably on some
>>> "devices"/file formats, and are not searchable, to generating tables in
>>> searchable text form on all "devices"/file formats, and fix other
>>> related issues, so may also affect man pages with tables differently.
>>> So for the current release, localize the changes to the man page chew
>>> input embedded in the strftime.c source comments, and the generated
>>> strftime.3 man page table formatting.
>>> Be prepared to tweak formatting if doc generation needs it, and
>>> eventually eliminate custom processing.

> I'm not sure "make it look worse in the typical case (someone looking at it in a 
> terminal with 'man strftime') to make it look better in the atypical case (?)" 
> is a good trade-off.

We could mess up other tables in other man pages if we tried to change 
makedocbook/docbook2man processing to try to split "long" tables as that depends 
on the length of the descriptive text column entries in lines and pages, which 
depends on the "device"/file format!

It seems easier, given the future changes above with unknown impacts, to handle 
the strftime long man page table rendering by splitting the (chew) table about 
the middle +/-%Ox, which fixes the table length > page length issue, then 
correcting the generated man page markup, which fixes the non-tty table 
rendering issue.
We could also do all the work just on the generated man page markup, but that 
seems even "hack"ier to me, than the current proposal.

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