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

[Alejandro Colomar]

Hi Branden,

On Sun, May 05, 2024 at 04:11:21PM +0200, Alejandro Colomar wrote:
> On Sun, May 05, 2024 at 08:54:53AM -0500, G. Branden Robinson wrote:
> > Hi Alex,
> 
> Hi Branden,
> 
> > At 2024-05-05T14:41:44+0200, Alejandro Colomar wrote:
> > > 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.
> > 
> > Thanks for giving it some field testing.  groff's own man pages aren't
> > the best test bed because I've revised nearly all of them so extensively
> > that they don't do things I wouldn't anticipate.
> > 
> > > -  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.
> > 
> > Yes.  You could still use the `br` request to force a break here.  `SY`
> > and `YS` should not interfere.  groff and mandoc do discourage the use
> > of *roff requests, but in frankness no one will ever be able to get away
> > with not supporting `br`.  And at least its semantics are very obvious
> > and easy to implement in just about any text formatting system.
> 
> Hmmm, I hadn't considered .br.  That changes things.
> 
> > >    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).
> > 
> > Awww.  Too bad.  I think a lot of aspiring page authors would look
> > there, because the function is so familiar, and they might wonder how to
> > do the variadic thing.
> 
> With .br I think I retire my previous statement.  I'll test it when I
> finish some other stuff I'm working on.

Done.  I like it very much.  It works just like it should.  :-)
In case you want to check my pages for testing your code, here they are:

<https://git.kernel.org/pub/scm/libs/liba2i/liba2i.git/tree/man/man3/a2i.3?h=main>
<https://git.kernel.org/pub/scm/libs/liba2i/liba2i.git/tree/man/man3/str2i.3?h=main>

While I don't care for liba2i.git too much, it would be interesting if
these enhancements could be backported to Debian stable, which would
allow using them earlier in the Linux man-pages.

Have a lovely day!
Alex

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