From: Junio C Hamano <gitster@pobox.com>
Date: Tue, 26 Mar 2024 20:20:16 GMT
Subject: Re: [PATCH 4/4] doc: git-clone: apply new documentation guidelines
Message-ID: <xmqq8r24agov.fsf@gitster.g>
In-Reply-To: <CAN0heSoSNxuoObvO_xtu1fXb+XYH+gBvVOWfJVBkpXouR0cmWQ@mail.gmail.com>

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

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