Re: [PATCH] doc: git-clone fix discrepancy between asciidoc and asciidoctor

From: Junio C Hamano <gitster@pobox.com>
Date: Jul 20, 2024, 23:23 UTC
Message-ID: <xmqq1q3nhcl2.fsf@gitster.g>
In-Reply-To: <xmqq8qxvhcy5.fsf@gitster.g>

Junio C Hamano <gitster@pobox.com> writes:

Show 16 quoted lines

> The reondered result _might_ be easier to read than pre-2.45 version
> of documentation, but I somehow find the updated SYNOPSIS section
> almost impossible to work with in the source form.  And the need for
> these otherwise no-op {empty} makes it even less pleasant to work
> with.
>
> I wonder if there is a magic incantation that says "everything
> should be typeset in monospace in this block, unless ..." so that we
> can lose all these `back quotes`?  And then the part that follows
> "unless ..." would say how we mark up the <placeholder> part which
> is the only thing exempt from "everything is in monospace" default.
>
> Thanks for a quick response.
>
>>  Documentation/git-clone.txt | 6 +++---
>>  1 file changed, 3 insertions(+), 3 deletions(-)

Ah, another and *more* important thing.

The original series that added the new mark-up to "clone" and "init" updated them as examples to illustrate the rules added by c42ea604 (doc: rework CodingGuidelines with new formatting rules, 2024-03-29) to Documentation/CodingGuidelines. I _dislike_ the idea that we have to sprinkle otherwise no-op {empty} all over the place, if we were to update the SYNOPSIS part of all other commands consistently, but if that is what it takes, we _should_ document that they need to do so (and no, we should not assume that those who document the commands _know_ why asciidoctor wants to eat the [string] there and we should not expect them to insert {empty} without being told).

Thanks.

Show 20 quoted lines

>>
>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
>> index 5de18de2ab8..8e925db7e9c 100644
>> --- a/Documentation/git-clone.txt
>> +++ b/Documentation/git-clone.txt
>> @@ -13,9 +13,9 @@ SYNOPSIS
>>  	  [`-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++[++=++__<pathspec>__]] [`--`[`no-`]`shallow-submodules`]
>> -	  [`--`[`no-`]`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]`reject-shallow`]
>> +	  [`--depth` _<depth>_] [`--`[`no-`]{empty}`single-branch`] [`--no-tags`]
>> +	  [++--recurse-submodules++[++=++__<pathspec>__]] [++--++[++no-++]{empty}++shallow-submodules++]
>> +	  [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` _<n>_] [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`]
>>  	  [++--filter=++__<filter-spec>__] [`--also-filter-submodules`]] [`--`] _<repository>_
>>  	  [_<directory>_]
>>  
>>
>> base-commit: a7dae3bdc8b516d36f630b12bb01e853a667e0d9