On Sun, May 05, 2024 at 02:41:44PM +0200, Alejandro Colomar wrote:

Hi Branden,

On Fri, May 03, 2024 at 03:31:26PM -0500, G. Branden Robinson wrote:

quoted

At 2024-04-26T11:32:06+0200, Alejandro Colomar wrote:

quoted

quoted

My questions:

A.  Does anyone object to me committing this change to groff's
    master branch?  It will of course require a NEWS item, which I
    will write.

Acked-by: Alejandro Colomar <alx@kernel.org>

quoted

B.  Does this look enticing enough to any documenters of C libraries
    for you to adopt it?

This one at least.  :-)

I've pushed this.

$ head -n 9 tmac/an-ext.tmac
.\" groff extension macros for man(7) package
.\"
.\" Copyright (C) 2007-2024 Free Software Foundation, Inc.
.\"
.\" Written by Eric S. Raymond [off-list ref]
.\"            Werner Lemberg [off-list ref]
.\"            G. Branden Robinson [off-list ref]
.\"
.\" You may freely use, modify and/or distribute this file.

Share and enjoy!

Thanks!

I'm trying it already in liba2i, since it's a project that I don't
expect to use until 1.24.0 is out.

Here's some feedback:

-  Hardcoded line widths have an interesting feature: the author decides
   the breaking point, which is interesting to highlight differences
   between similar functions.  See for example printf(3):

     int printf(const char *restrict format, ...);
     int fprintf(FILE *restrict stream,
                 const char *restrict format, ...);
     int dprintf(int fd,
                 const char *restrict format, ...);
     int sprintf(char *restrict str,
                 const char *restrict format, ...);
     int snprintf(char str[restrict .size], size_t size,
                 const char *restrict format, ...);

   As you can see, the breaking point clearly shows the differences
   between all of those, and leaves the common part in a separate line.

   Still, this is not the common case, and most pages would benefit of
   this SY.  I'm just mentioning here to note that old hard-coded BI
   still has its place in some pages.  I will probably never use SY in
   printf(3).

-  I found an inconsistent break point:

   Type‐generic macros
     int a2i(TYPE, TYPE *restrict n, const char *s,
             char **_Nullable restrict endp, int base, TYPE min, TYPE max);

     int a2s(TYPE, TYPE *restrict n, const char *s, char **_Nullable re‐
             strict endp, int base, TYPE min, TYPE max);
     int a2u(TYPE, TYPE *restrict n, const char *s, char **_Nullable re‐
             strict endp, int base, TYPE min, TYPE max);

   Why is 'restrict' hyphenated in two cases, but not in the first one?!
   The source is:

Oh, and removing the argument to YS fixes this.  :|

alx@debian:~/tmp/groff/SY$ cat restrict.3 
.TH a s d f
.SH Name
restrict \- gets broken
.SH Type-generic macros
.B int
.SY a2i (
.B TYPE,
.BI TYPE\~*restrict\~ n ,
.BI const\~char\~* s ,
.BI char\~**_Nullable\~restrict\~ endp ,
.BI int\~ base ,
.BI TYPE\~ min ,
.BI TYPE\~ max );
.YS .
.P
.B int
.SY a2s (
.B TYPE,
.BI TYPE\~*restrict\~ n ,
.BI const\~char\~* s ,
.BI char\~**_Nullable\~restrict\~ endp ,
.BI int\~ base ,
.BI TYPE\~ min ,
.BI TYPE\~ max );
.YS .
.B int
.SY a2u (
.B TYPE,
.BI TYPE\~*restrict\~ n ,
.BI const\~char\~* s ,
.BI char\~**_Nullable\~restrict\~ endp ,
.BI int\~ base ,
.BI TYPE\~ min ,
.BI TYPE\~ max );
.YS
alx@debian:~/tmp/groff/SY$ man ./restrict.3 | cat
a(s)                                                                       a(s)

Name
     restrict - gets broken

Type‐generic macros
     int a2i(TYPE, TYPE *restrict n, const char *s,
             char **_Nullable restrict endp, int base, TYPE min, TYPE max);

     int a2s(TYPE, TYPE *restrict n, const char *s, char **_Nullable re‐
             strict endp, int base, TYPE min, TYPE max);
     int a2u(TYPE, TYPE *restrict n, const char *s, char **_Nullable re‐
             strict endp, int base, TYPE min, TYPE max);

f                                      d                                   a(s)


I would suggest never breaking anything between SY/YS.  Or do you want
me to use \% where appropriate?  It's a bit of work that I'd prefer to
avoid.

Have a lovely day!
Alex

quoted

Regards,
Branden

-- 
<https://www.alejandro-colomar.es/>
A client is hiring kernel driver, mm, and/or crypto developers;
contact me if interested.

-- 
<https://www.alejandro-colomar.es/>
A client is hiring kernel driver, mm, and/or crypto developers;
contact me if interested.