From: Alejandro Colomar <alx@kernel.org>
To: "G. Branden Robinson" <g.branden.robinson@gmail.com>
Cc: groff@gnu.org, linux-man@vger.kernel.org, bug-ncurses@gnu.org
Subject: Re: Proposed v2: revised man(7) synopsis macros
Date: Fri, 26 Apr 2024 11:32:06 +0200 [thread overview]
Message-ID: <Zit0nT-jhNPE9T2v@debian> (raw)
In-Reply-To: <20240426055958.3hzal6m4r7mgzhqj@illithid>
[-- 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 --]
next prev parent reply other threads:[~2024-04-26 9:32 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-26 5:59 Proposed v2: revised man(7) synopsis macros G. Branden Robinson
2024-04-26 9:32 ` Alejandro Colomar [this message]
2024-05-03 20:31 ` G. Branden Robinson
2024-05-05 12:41 ` Alejandro Colomar
2024-05-05 12:44 ` Alejandro Colomar
[not found] ` <20240505135453.4rxsqe3so7347mli@illithid>
[not found] ` <ZjeTilIR86sBYrtI@debian>
2024-05-05 14:28 ` Alejandro Colomar
2024-05-05 14:32 ` G. Branden Robinson
2024-05-05 14:45 ` Alejandro Colomar
2024-04-26 21:54 ` Lennart Jablonka
2024-04-26 22:31 ` Undeprecating man(7)'s `HP` macro? (was: Proposed v2: revised man(7) synopsis macros) G. Branden Robinson
2024-04-29 8:39 ` Proposed v2: revised man(7) synopsis macros G. Branden Robinson
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=Zit0nT-jhNPE9T2v@debian \
--to=alx@kernel.org \
--cc=bug-ncurses@gnu.org \
--cc=g.branden.robinson@gmail.com \
--cc=groff@gnu.org \
--cc=linux-man@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.