Re: [PATCH 4/4] doc: git-clone: apply new documentation guidelines

From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Mar 26, 2024, 20:49 UTC
Message-ID: <3285532.aeNJFYEL58@cayenne>
In-Reply-To: <xmqq8r24agov.fsf@gitster.g>

On Tuesday, 26 March 2024 21:20:16 CET Junio C Hamano wrote:

> Martin Ågren <martin.agren@gmail.com> writes:
> 
> >> +`git clone` [`--template=`{empty}__<template-directory>__]
> >> +         [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`--

mirror`]

> >> +         [`-o` _<name>_] [`-b` _<name>_] [`-u` _<upload-pack>_] [`--

reference` _<repository>_]

> >> +         [`--dissociate`] [`--separate-git-dir` _<git-dir>_]
> >> +         [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-

tags`]

> >> +         [`--recurse-submodules`[`=`{empty}__<pathspec>__]] [`--`[`no-

`]`shallow-submodules`]

> >> +         [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`]

[`--`[`no-`]`reject-shallow`]

> >> +         [`--filter=`{empty}__<filter-spec>__] [`--also-filter-

submodules`]] [`--`] _<repository>_

Show 23 quoted lines

> >> +         [_<directory>_]
> >
> > Don't ask me why, but I need this on top (whitespace-damaged)
> >
> > -         [`--depth` _<depth>_] [`--`[`no-`]`single-branch`] [`--no-tags`]
> > -         [`--recurse-submodules`[`=`{empty}__<pathspec>__]]
> > [`--`[`no-`]`shallow-submodules`]
> > -         [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_]
> > [`--sparse`] [`--`[`no-`]`reject-shallow`]
> > +         [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`]
> > [`--no-tags`]
> > +         [`--recurse-submodules`[`=`{empty}__<pathspec>__]]
> > [`--`[`no-`]{empty}`shallow-submodules`]
> > +         [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_]
> > [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
> >
> > i.e., some sprinkling of "{empty}", to keep each of these "[--[no-]"
> > from simply disappearing. This is with Asciidoctor 1.5.5, which is
> > admittedly starting to get old, but still ok as per our INSTALL
> > document.
> 
> The original from Jean-Noël was already bad enough with all these
> {empty}, but now this is even worse.

I must concede this does not help make these parts readable in the source. The point that Martin raised is the worst for me: if the processing of this workaround is depend on the version of Asciidoc[tor], the way of writing this formatting for stuck parts in a compatible way must be clearly defined (and made understandable).

Show 21 quoted lines

> 
> >> ---bare::
> >> +`--bare`::
> >>         Make a 'bare' Git repository.  That is, instead of
> >>         creating _<directory>_ and placing the administrative
> >> -       files in `<directory>/.git`, make the _<directory>_
> >> +       files in _<directory>_`/.git`, make the _<directory>_
> >
> > This should be __<directory>__{empty}`/.git`
> 
> The worst part is that I am not sure if there is a pattern easily
> understandable by document writers to help them decide where to
> sprinkle these {empty} mark-ups.  Of course, they are visually very
> distracting and made our documentation that used to be perfectly
> readable in the source form to something much less pleasant to read.
> 
> Can we make both the rendered output nicer while keeping the source
> still readable and easy to maintain?
> 
> Thanks.
>

I came up with this trickery because of the use of "legacy" Asciidoc format, which does not understand unconstrained formatting (doubling the signs, so that they don't care about word boundary). With the new format, we would simply write:

__<directory>__``/.git`` ``--filter=``__<filter-spec>__

Without having to pay attention to the surrounding characters.

For now, we are stuck with the compatibility with the existing tools. I will try an propose something else. Would preprocessing be accepted?