Re: Proposed v2: revised man(7) synopsis macros

[Alejandro Colomar]

Hi Branden,

On Fri, May 03, 2024 at 03:31:26PM -0500, G. Branden Robinson wrote:
> At 2024-04-26T11:32:06+0200, Alejandro Colomar wrote:
> > > 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>
> > 
> > > 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 <esr@thyrsus.com>
> .\"            Werner Lemberg <wl@gnu.org>
> .\"            G. Branden Robinson <g.branden.robinson@gmail.com>
> .\"
> .\" 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:

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

> Regards,
> Branden


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

signature.asc
Description: PGP signature