Re: [PATCH 0/9] Doc git log

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Jul 6, 2025, 15:27 UTC
Message-ID: <7824165.EvYhyI6sBW@cayenne>
In-Reply-To: <xmqq4iwcenrc.fsf@gitster.g>

On Wednesday, 18 June 2025 23:35:51 CEST Junio C Hamano wrote:

Show 10 quoted lines

> "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com> writes:
> > This series converts the man page of git log to the synopsis format style.
> > Git log is the second largest manpage after git config, which makes the
> > changes quite large.
> 
> ;-)
> 
> Other than the "add % to literal" in [5/9], which I couldn't figure
> out if it truly belongs to "doc: git-log: convert rev list options
> to new doc format", everything looked pretty reasonable.

TBH, I'm not entirely satisfied with this patch, because it reintroduces complicated format marks everywhere instead of pushing this complexity into the formatting logic. The problem is coming again that we have some signs which are used for the synopsis syntax but can appear as "keywords". First there was the three dot notation, now it's the parenthesis. Coming up with basic regexps that can handle the context difference to tell apart their grammatical meaning is increasing difficult, if not impossible.

For git-scm.com, with asciidoctor, an extension managing the synopsis style using a parser combinator was introduced to alleviate the difficulty of the task.

The problem is that, as far as I can tell, asciidoc.py does not propose such extensions in a programmable way. If anybody can direct me to an example of using a parser combinator in asciidoc.py, that would be great. For the moment, this patch is the best proposition.

Thanks

JN