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

[G. Branden Robinson]

Hi Alex,

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.

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

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

$ 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

signature.asc
Description: PGP signature