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

From: Junio C Hamano <gitster@pobox.com>
Date: Mar 26, 2024, 20:20 UTC
Message-ID: <xmqq8r24agov.fsf@gitster.g>
In-Reply-To: <CAN0heSoSNxuoObvO_xtu1fXb+XYH+gBvVOWfJVBkpXouR0cmWQ@mail.gmail.com>

Martin Ågren <martin.agren@gmail.com> writes:

Show 28 quoted lines

>> +`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>_
>> +         [_<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.

Show 8 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.