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

[Alejandro Colomar <alx@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 1762 bytes --]

Hi Branden,

On Fri, Apr 26, 2024 at 12:59:58AM -0500, G. Branden Robinson wrote:
> Hi folks,
> 
> Difference from v1
> ==================
> Support reuse of previously computed indentation, to line up function
> arguments and similar across multiple synopses.  Requested by Alex
> Colomar.
> 
> Proposal
> ========
> 
> I have been dissatisfied with groff man(7)'s SY and YS macros for a long
> time.  My primary grievance is one that has frustrated its uptake by
> documenters of libraries: the macros are designed for synopsizing Unix
> commands, not C library functions.
> 
> After working on the ncurses man pages for a while it became clear to me
> how to modestly revise the way groff man(7)'s SY and YS macros work to
> serve both sets of authors better.
> 
> My proposal, as a diff to groff Git HEAD, is attached.

[...]

> Attachments:
> 
> * "git diff" of my working copy, also including updates to existing
>   groff man pages and to a regression test script, to reflect the new
>   `SY` and `YS` behavior.
> * Sample document exercising mandoc(1)'s incorrect handling of
>   `in` and `ti` requests.
> * An example document, renderable with groff Git HEAD, 1.23.0, 1.22.4,
>   and 1.22.3 (at least), illustrating use of these macros.  View it with
>   "nroff -man".
> 
> My questions:
> 
> A.  Does anyone object to me committing this change to groff's master
>     branch?  It will of course require a NEWS item, which I will write.

Acked-by: Alejandro Colomar <alx@kernel.org>

> B.  Does this look enticing enough to any documenters of C libraries for
>     you to adopt it?

This one at least.  :-)

> Regards,
> Branden

Have a lovely day!
Alex

-- 
<https://www.alejandro-colomar.es/>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]