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@xxxxxxxxxx> > > > > > > > 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@xxxxxxxxxxx> > > .\" Werner Lemberg <wl@xxxxxxx> > > .\" G. Branden Robinson <g.branden.robinson@xxxxxxxxx> > > .\" > > .\" 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:
signature.asc
Description: PGP signature
