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

[Ingo Schwarze]

Hello Alejandro,

Alejandro Colomar wrote on Wed, Jun 04, 2025 at 05:58:54PM +0200:

> +.P
> +.SY int\~dl_iterate_phdr(
> +.BI typeof(int\~(struct\~dl_phdr_info\~* info ,\~size_t\~ size ,
> +.BI \~\~\~\~\~\~\~\~\~\~\~\~void\~* data ))
> +.br
> +.BI \~\~\~\~* callback ,
> +.br
> +.BI void\~* data );
> +.YS

> which I'm relatively pleased with.

I find it hard to understand how anyone could possibly be pleased
with the above code.  It certainly feels disgusting to me.

The code uses a high-level macro which is supposed to be semantic.
In spite of that, the code is littered with a large numbers of purely
presentational low-level roff(7) constructions, which demonstrates
that .SY is utterly unfit for its supposed job.

 * .P is not used in its semantical function here (there is no
   paragraph of text), but abused as a presentational hack
   to insert vertical spacing, similar to the .sp request,
   which means that .SY fails at adequately controlling
   vertical spacing.
 * Manual indentation with explicit space escape sequences
   is not only extremely ugly, but whether it works as intended
   is also output-device-dependent.
 * And then we have the low-level .br requests.  Again, certainly
   not the worst requests to sneak into a manual page, but in
   the middle of a semantic macro?  Yikes.

Yours,
  Ingo