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

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 4957 bytes --]

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

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]