[PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[Brian Inglis]

Brian Inglis (2):
  newlib/libc/time/strftime.c: split table of conversion
    specifiers to fix man, tbl, groff multi-page table issues
  newlib/libc/Makefile.inc: sed fix strftime.3 table format
    man, tbl, groff multi-page issues

 newlib/libc/time/strftime.c | 3 ++-
 newlib/libc/Makefile.inc    | 1 +
 2 files changed, 3 insertions(+), 1 deletion(-)

--
2.39.0

[PATCH 1/2] newlib/libc/time/strftime.c: split table of conversion specifiers to fix man, tbl, groff multi-page table issues

[Brian Inglis]

---
 newlib/libc/time/strftime.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/newlib/libc/time/strftime.c b/newlib/libc/time/strftime.c
index 56f227c5f3b8..c4532b4ceada 100644
--- a/newlib/libc/time/strftime.c
+++ b/newlib/libc/time/strftime.c
@@ -153,7 +153,8 @@ A newline character (`<<\n>>').
 o %O<<x>>
 In some locales, the O modifier selects alternative digit characters
 for certain modifiers <<x>>.  In newlib, it is ignored, and treated as %<<x>>.
-
+o-
+o+
 o %p
 Either `<<AM>>' or `<<PM>>' as appropriate, or the corresponding strings for
 the current locale. [tm_hour]
-- 
2.39.0

[PATCH 2/2] newlib/libc/Makefile.inc: sed fix strftime.3 table format man, tbl, groff multi-page issues

[Brian Inglis]

---
 newlib/libc/Makefile.inc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/newlib/libc/Makefile.inc b/newlib/libc/Makefile.inc
index d07eed7641ec..2aafb8c530e3 100644
--- a/newlib/libc/Makefile.inc
+++ b/newlib/libc/Makefile.inc
@@ -30,6 +30,7 @@ man: %C%_man.stamp
 
 %C%_install-man: %C%_man.stamp
 	$(MKDIR_P) $(DESTDIR)$(mandir)/man3
+	sed -i -e '/^\.TS$/,/^\.TE$/{/^\.PP$\|^l\sl$/d;/^l\sl\.$/s,\.,x&,};/^\.TE$/,/^\.TS$/{/^\.sp\s1$/d}' -- %D%/strftime.3
 	$(INSTALL_DATA) %D%/*.3 $(DESTDIR)$(mandir)/man3/
 install-man: %C%_install-man
 
-- 
2.39.0

[PATCH v2 2/2] newlib/libc/Makefile.inc: sed fix strftime.3 table format man, tbl, groff multi-page issues

[Brian Inglis]

double "$"s in make lines
---
 newlib/libc/Makefile.inc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/newlib/libc/Makefile.inc b/newlib/libc/Makefile.inc
index d07eed7641ec..248d3051fa87 100644
--- a/newlib/libc/Makefile.inc
+++ b/newlib/libc/Makefile.inc
@@ -30,6 +30,7 @@ man: %C%_man.stamp
 
 %C%_install-man: %C%_man.stamp
 	$(MKDIR_P) $(DESTDIR)$(mandir)/man3
+	sed -i -e '/^\.TS$$/,/^\.TE$$/{/^\.PP$$\|^l\sl$$/d;/^l\sl\.$$/s,\.,x&,};/^\.TE$$/,/^\.TS$$/{/^\.sp\s1$$/d}' -- %D%/strftime.3
 	$(INSTALL_DATA) %D%/*.3 $(DESTDIR)$(mandir)/man3/
 install-man: %C%_install-man
 
-- 
2.39.0

Re: [PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[Corinna Vinschen]

Hi Brian,

On Feb 17 13:49, Brian Inglis wrote:
> Brian Inglis (2):
>   newlib/libc/time/strftime.c: split table of conversion
>     specifiers to fix man, tbl, groff multi-page table issues
>   newlib/libc/Makefile.inc: sed fix strftime.3 table format
>     man, tbl, groff multi-page issues
> 
>  newlib/libc/time/strftime.c | 3 ++-
>  newlib/libc/Makefile.inc    | 1 +
>  2 files changed, 3 insertions(+), 1 deletion(-)
> 
> --
> 2.39.0

Would you mind terribly to add more text to the commit messages?
explaining the problem, and its fix?  Just the subject line is quite
terse.

For patch 1, why adding the split and what's the desired effect.  For
patch 2, what problem is the sed call fixing and what is the sed
expression doing?


Thanks,
Corinna

Re: [PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[Brian Inglis]

On 2023-02-20 02:45, Corinna Vinschen wrote:
> Hi Brian,
> 
> On Feb 17 13:49, Brian Inglis wrote:
>> Brian Inglis (2):
>>    newlib/libc/time/strftime.c: split table of conversion
>>      specifiers to fix man, tbl, groff multi-page table issues
>>    newlib/libc/Makefile.inc: sed fix strftime.3 table format
>>      man, tbl, groff multi-page issues
>>
>>   newlib/libc/time/strftime.c | 3 ++-
>>   newlib/libc/Makefile.inc    | 1 +
>>   2 files changed, 3 insertions(+), 1 deletion(-)
>>
>> --
>> 2.39.0
> 
> Would you mind terribly to add more text to the commit messages?
> explaining the problem, and its fix?  Just the subject line is quite
> terse.
> 
> For patch 1, why adding the split and what's the desired effect.  For
> patch 2, what problem is the sed call fixing and what is the sed
> expression doing?

Thanks Corinna, You're right - will redo all v3.

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

Re: [PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[Jon Turney]

On 20/02/2023 20:25, Brian Inglis wrote:
> On 2023-02-20 02:45, Corinna Vinschen wrote:
>> Hi Brian,
>>
>> On Feb 17 13:49, Brian Inglis wrote:
>>> Brian Inglis (2):
>>>    newlib/libc/time/strftime.c: split table of conversion
>>>      specifiers to fix man, tbl, groff multi-page table issues
>>>    newlib/libc/Makefile.inc: sed fix strftime.3 table format
>>>      man, tbl, groff multi-page issues
>>>
>>>   newlib/libc/time/strftime.c | 3 ++-
>>>   newlib/libc/Makefile.inc    | 1 +
>>>   2 files changed, 3 insertions(+), 1 deletion(-)
>>>
>>> -- 
>>> 2.39.0
>>
>> Would you mind terribly to add more text to the commit messages?
>> explaining the problem, and its fix?  Just the subject line is quite
>> terse.
>>
>> For patch 1, why adding the split and what's the desired effect.  For
>> patch 2, what problem is the sed call fixing and what is the sed
>> expression doing?
> 
> Thanks Corinna, You're right - will redo all v3.

You should also describe why this must be fixed in this ad-hoc fasion, 
rather than in the chew markup or makedocbook.

Re: [PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[Brian Inglis]

On 2023-02-20 15:03, Jon Turney wrote:
> On 20/02/2023 20:25, Brian Inglis wrote:
>> On 2023-02-20 02:45, Corinna Vinschen wrote:
>>> Hi Brian,
>>>
>>> On Feb 17 13:49, Brian Inglis wrote:
>>>> Brian Inglis (2):
>>>>    newlib/libc/time/strftime.c: split table of conversion
>>>>      specifiers to fix man, tbl, groff multi-page table issues
>>>>    newlib/libc/Makefile.inc: sed fix strftime.3 table format
>>>>      man, tbl, groff multi-page issues
>>>>
>>>>   newlib/libc/time/strftime.c | 3 ++-
>>>>   newlib/libc/Makefile.inc    | 1 +
>>>>   2 files changed, 3 insertions(+), 1 deletion(-)
>>>>
>>>> -- 
>>>> 2.39.0
>>>
>>> Would you mind terribly to add more text to the commit messages?
>>> explaining the problem, and its fix?  Just the subject line is quite
>>> terse.
>>>
>>> For patch 1, why adding the split and what's the desired effect.  For
>>> patch 2, what problem is the sed call fixing and what is the sed
>>> expression doing?
>>
>> Thanks Corinna, You're right - will redo all v3.
> 
> You should also describe why this must be fixed in this ad-hoc fasion, rather 
> than in the chew markup or makedocbook.

I'll also ref the discussion with Branden, following comments from linux-man,
the 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

I dug and could not find a good point to alter generation of tables > page size 
that may not adversely affect other [newlib] doc man page tables, where the 
problem occurs solely on that strftime.3 man page!

Also the imminent groff/tbl/grohtml release fixes a number of tbl issues, so may 
affect man pages with tables differently.

The following release plans to change grohtml, from generating tables as PNG 
graphics, which don't work on some output "devices"/file formats, and are not 
searchable, to generating tables in searchable text form on the target 
"devices"/file formats, so will also affect man pages with tables differently, 
and fix other related issues.

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

Re: [PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[Jon Turney]

On 20/02/2023 23:20, Brian Inglis wrote:
> On 2023-02-20 15:03, Jon Turney wrote:
>> On 20/02/2023 20:25, Brian Inglis wrote:
>>> On 2023-02-20 02:45, Corinna Vinschen wrote:
>>>> Hi Brian,
>>>>
>>>> On Feb 17 13:49, Brian Inglis wrote:
>>>>> Brian Inglis (2):
>>>>>    newlib/libc/time/strftime.c: split table of conversion
>>>>>      specifiers to fix man, tbl, groff multi-page table issues
>>>>>    newlib/libc/Makefile.inc: sed fix strftime.3 table format
>>>>>      man, tbl, groff multi-page issues
>>>>>
>>>>>   newlib/libc/time/strftime.c | 3 ++-
>>>>>   newlib/libc/Makefile.inc    | 1 +
>>>>>   2 files changed, 3 insertions(+), 1 deletion(-)
>>>>>
>>>>> -- 
>>>>> 2.39.0
>>>>
>>>> Would you mind terribly to add more text to the commit messages?
>>>> explaining the problem, and its fix?  Just the subject line is quite
>>>> terse.
>>>>
>>>> For patch 1, why adding the split and what's the desired effect.  For
>>>> patch 2, what problem is the sed call fixing and what is the sed
>>>> expression doing?
>>>
>>> Thanks Corinna, You're right - will redo all v3.
>>
>> You should also describe why this must be fixed in this ad-hoc fasion, 
>> rather than in the chew markup or makedocbook.
> 
> I'll also ref the discussion with Branden, following comments from 
> linux-man,
> the 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

Thanks, interesting reading.

> via makedocbook python script which generates xml (attached), then
> docbook generates html, man pages, PDFs, texinfo, and the latter
> generate libc info.]

This statement of yours is incorrect:

The embedded documentation is processed ('chewed') by makedoc into 
texinfo, from which html, info and PDFs are generated.

The embedded documentation is also processed by makedocbook into docbook 
from which manpages are generated.

Whatever you think of docbook as a pivot format for generating the 
manpages, texinfo is much worse.

In theory you could use makedocbook as a starting point for directly 
outputting groff manpages, if that's the only way to generate manpages 
of the quality desired.

> I dug and could not find a good point to alter generation of tables > 
> page size that may not adversely affect other [newlib] doc man page 
> tables, where the problem occurs solely on that strftime.3 man page!

These seem like generic problem in the docbook2man XSLT, which should be 
fixed there.

Re: [PATCH 0/2] newlib/libc/time/strftime: table format fix man, tbl, groff multi-page table issues

[Brian Inglis]

On 2023-02-22 13:10, Jon Turney wrote:
> On 20/02/2023 23:20, Brian Inglis wrote:
>> On 2023-02-20 15:03, Jon Turney wrote:
>>> On 20/02/2023 20:25, Brian Inglis wrote:
>>>> On 2023-02-20 02:45, Corinna Vinschen wrote:
>>>>> Hi Brian,
>>>>>
>>>>> On Feb 17 13:49, Brian Inglis wrote:
>>>>>> Brian Inglis (2):
>>>>>>    newlib/libc/time/strftime.c: split table of conversion
>>>>>>      specifiers to fix man, tbl, groff multi-page table issues
>>>>>>    newlib/libc/Makefile.inc: sed fix strftime.3 table format
>>>>>>      man, tbl, groff multi-page issues
>>>>>>
>>>>>>   newlib/libc/time/strftime.c | 3 ++-
>>>>>>   newlib/libc/Makefile.inc    | 1 +
>>>>>>   2 files changed, 3 insertions(+), 1 deletion(-)
>>>>>>
>>>>>> -- 
>>>>>> 2.39.0
>>>>>
>>>>> Would you mind terribly to add more text to the commit messages?
>>>>> explaining the problem, and its fix?  Just the subject line is quite
>>>>> terse.
>>>>>
>>>>> For patch 1, why adding the split and what's the desired effect.  For
>>>>> patch 2, what problem is the sed call fixing and what is the sed
>>>>> expression doing?
>>>>
>>>> Thanks Corinna, You're right - will redo all v3.
>>>
>>> You should also describe why this must be fixed in this ad-hoc fasion, rather 
>>> than in the chew markup or makedocbook.
>>
>> I'll also ref the discussion with Branden, following comments from linux-man,
>> the 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
> 
> Thanks, interesting reading.
> 
>> via makedocbook python script which generates xml (attached), then
>> docbook generates html, man pages, PDFs, texinfo, and the latter
>> generate libc info.]
> 
> This statement of yours is incorrect:
> 
> The embedded documentation is processed ('chewed') by makedoc into texinfo, from 
> which html, info and PDFs are generated.
> 
> The embedded documentation is also processed by makedocbook into docbook from 
> which manpages are generated.

I realized I switched them due to similar names and possibly ToD or coffee lack.

> Whatever you think of docbook as a pivot format for generating the manpages, 
> texinfo is much worse.

Not my opinion - I don't mind GMLs or roffs - BTDT.

> In theory you could use makedocbook as a starting point for directly outputting 
> groff manpages, if that's the only way to generate manpages of the quality desired.
> 
>> I dug and could not find a good point to alter generation of tables > page 
>> size that may not adversely affect other [newlib] doc man page tables, where 
>> the problem occurs solely on that strftime.3 man page!
> 
> These seem like generic problem in the docbook2man XSLT, which should be fixed 
> there.

The problem is man -> tbl -> groff - see other reply.
It may be fixed in groff v + 2.

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

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

[Brian Inglis]

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!

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

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

--
2.39.0

[PATCH v3 1/2] newlib/libc/time/strftime.c: split chew table of conversion format specifiers

[Brian Inglis]

split chew table of conversion format specifiers as man/tbl/groff can
not handle large tables on all output devices/file formats

---
 newlib/libc/time/strftime.c | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/newlib/libc/time/strftime.c b/newlib/libc/time/strftime.c
index 56f227c5f3b8..c4532b4ceada 100644
--- a/newlib/libc/time/strftime.c
+++ b/newlib/libc/time/strftime.c
@@ -153,7 +153,8 @@ A newline character (`<<\n>>').
 o %O<<x>>
 In some locales, the O modifier selects alternative digit characters
 for certain modifiers <<x>>.  In newlib, it is ignored, and treated as %<<x>>.
-
+o-
+o+
 o %p
 Either `<<AM>>' or `<<PM>>' as appropriate, or the corresponding strings for
 the current locale. [tm_hour]
-- 
2.39.0

[PATCH v3 2/2] newlib/libc/Makefile.inc: sed fix strftime.3 tbl/groff format issues

[Brian Inglis]

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

---
 newlib/libc/Makefile.inc | 1 +
 1 file changed, 1 insertion(+)

diff --git a/newlib/libc/Makefile.inc b/newlib/libc/Makefile.inc
index d07eed7641ec..248d3051fa87 100644
--- a/newlib/libc/Makefile.inc
+++ b/newlib/libc/Makefile.inc
@@ -30,6 +30,7 @@ man: %C%_man.stamp
 
 %C%_install-man: %C%_man.stamp
 	$(MKDIR_P) $(DESTDIR)$(mandir)/man3
+	sed -i -e '/^\.TS$$/,/^\.TE$$/{/^\.PP$$\|^l\sl$$/d;/^l\sl\.$$/s,\.,x&,};/^\.TE$$/,/^\.TS$$/{/^\.sp\s1$$/d}' -- %D%/strftime.3
 	$(INSTALL_DATA) %D%/*.3 $(DESTDIR)$(mandir)/man3/
 install-man: %C%_install-man
 
-- 
2.39.0

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

[Corinna Vinschen]

Jon,

I'd like your GTG on the patchset before merging it.


Thanks,
Corinna

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!
> 
> 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
> 
> 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(-)
> 
> --
> 2.39.0

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

[Jon Turney]

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

Re: [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

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

[Brian Inglis]

On 2023-02-21 02:15, Corinna Vinschen wrote:
> I'd like your GTG on the patchset before merging it.

Hi folks,

The spark for this was comments on the ML about using BROWSER=cygstart man -H to 
render pages in the browser, finding that other pages with tables work okay on 
all devices/encodings/file formats, except strftime, which is an area of 
interest to me, renders its table only on tty devices/encodings/file formats. 
Following up on the groff list, found out that other -T devices/file formats 
also fail to render that page's table, where others are okay, due to known 
conflicts and deficiencies in man/tbl/groff processing of long tables > page size.

Please let me know if you want more docs, comments, code, etc. to progress this.

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