Re: [PATCH v4 0/3] doc: introducing synopsis para

From: Junio C Hamano <gitster@pobox.com>
Date: Sep 13, 2024, 18:15 UTC
Message-ID: <xmqqo74rxvw0.fsf@gitster.g>
In-Reply-To: <pull.1766.v4.git.1725573126.gitgitgadget@gmail.com>

"Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:

Show 10 quoted lines

> In the continuation of the simplification of manpage editing, the synopsis
> processing that was developed for synopsis paragraph style is also applied
> to all inline backquoted texts.
>
> Refining the magic regexp took more time than expected, but this one should
> really enhance writers'experience. I had to fight a bit more with
> asciidoctor, due to discrepancies between version 2.0 on my laptop and the
> 1.5.6 used by Github actions.
>
> The git-init and git-clone manpages are converted to this new system.

The fact that such a "magic" processing will hide the gory details from those whose primary interest is to describe the commands and their options cuts both ways. While I can understand that purists would find it ugly, as `backticks` is now much more than a mark-up that means "this text is typeset in monospace", it is a very welcome thing for developers around here, who just want to write their document in a way even whose source is readable without having to worry about suh gory details. Maybe this gets popular enough after other projects notice what you did to AsciiDoctor, love it, adopt it, and eventually it feeds back to improve AsciiDoctor proper ;-).

So, unless there are objections and people want to discuss it further, I'll mark the topic for 'next' soonish.

Thanks.