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

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)

>> 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.
>>
>> newlib/libc/time/strftime.c: split chew table of conversion format
>> specifiers as man/tbl/groff can not handle large tables on all output
>> devices/file formats

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.

>> newlib/libc/Makefile.inc: sed fix strftime.3 tbl/groff format issues:
>> remove multiple "^l l$" tbl line formats at tops of tables;
>> change remaining "^l l\.$" tbl line formats at tops of tables so second
>> column is lx and extends to margin;
>> remove "^.PP$" breaks before each format description as it misaligns
>> text below format specifier;
>> remove blank line between adjacent tables
>>
>> Brian Inglis (2):
>>    newlib/libc/time/strftime.c: split chew table of conversion format
>>      specifiers
>>    newlib/libc/Makefile.inc: sed fix strftime.3 tbl/groff format issues
>>
>>   newlib/libc/time/strftime.c | 3 ++-
>>   newlib/libc/Makefile.inc    | 1 +
>>   2 files changed, 3 insertions(+), 1 deletion(-)
>>