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

[Alejandro Colomar]

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.

> > -  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?!
> 
> Because it's a bug.  Oops.

:-)

> > I would suggest never [hyphenate] anything between SY/YS.
> 
> I agree, and that was my intention.  (There are always _breaks_; they're
> just supposed to take place at spaces, or where you put in explicit
> hyphens.)
> 
> > Or do you want me to use \% where appropriate?
> 
> This will work but should not often be necessary.
> 
> > It's a bit of work that I'd prefer to avoid.
> 
> Yes, and I'd prefer not having to often tell people they have to do it.
> 
> [later]
> 
> > Oh, and removing the argument to YS fixes this.  :|
> 
> Yes.  I had a badly structured conditional.
> 
> Here's a patch.  I'll add a regression test for this since I managed to
> screw it up on something I called "done".

Thanks!

> 
> $ git diff tmac/an-ext.tmac
> diff --git a/tmac/an-ext.tmac b/tmac/an-ext.tmac
> index 361b4097a..e7f48876d 100644
> --- a/tmac/an-ext.tmac
> +++ b/tmac/an-ext.tmac
> @@ -101,11 +101,11 @@ .de YS
>  .  in \\n(mIu
>  .  ad \\n(mA
>  .  hy \\n(mH
> +.  nr mS 0
>  .
>  .  if !\\n(.$ \{\
>  .    rr mA
>  .    rr mI
> -.    nr mS 0
>  .    rr mT
>  .  \}
>  ..
> 
> `mS` just means "are we in a synopsis?"  Here's a pending change in my
> working copy, not yet pushed, that gets even more fastidious.
> 
> commit 89a889b889e1fdc74c7907c737653ec2e1b05885
> Author:     G. Branden Robinson <g.branden.robinson@gmail.com>
> AuthorDate: Sat May 4 14:24:01 2024 -0500
> Commit:     G. Branden Robinson <g.branden.robinson@gmail.com>
> CommitDate: Sat May 4 14:25:59 2024 -0500
> 
>     [man]: Reset more state in `TH` macro.
> 
>     * tmac/an.tmac (TH): Reset `mE` and `mS` registers from "an-ext.tmac" to
>       zero upon beginning a new document.
> 
>     The reduces potential misrendering when batch formatting multiple
>     documents in the event one of them leaves a synopsis or example "hanging
>     open" without closing it with a `YS` or `EE` call.  (These are unlikely
>     failure modes for pages that end civilly with a "See Also" section.)
> [...]
> diff --git a/tmac/an.tmac b/tmac/an.tmac
> index 3f6a295e9..e17ba1758 100644
> --- a/tmac/an.tmac
> +++ b/tmac/an.tmac
> @@ -302,6 +302,10 @@ .de1 TH
>  .  ad \\*[AD]
>  .  ll \\n[LL]u
>  .
> +.  \" Reset any lingering state from extensions in an-ext.tmac.
> +.  nr mE 0
> +.  nr mS 0
> +.
>  .  \" We've seen no tbl(1) tables yet in this document.
>  .  rr TW
>  .  nr an-was-tbl-failure-reported 0
> 
> Regards,
> Branden

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