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.robin...@gmail.com>
> AuthorDate: Sat May 4 14:24:01 2024 -0500
> Commit: G. Branden Robinson <g.branden.robin...@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
