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

[Brian Inglis]

[Sorry - answered to patches not newlib!]
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