Re: [PATCH 0/9] Doc git log

["Jean-Noël AVILA" <jn.avila@free.fr>]

On Wednesday, 18 June 2025 23:35:51 CEST Junio C Hamano wrote:
> "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