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:
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.
Attachment:
signature.asc
Description: PGP signature
