Junio C Hamano <gitster@xxxxxxxxx> writes:
> 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.
>>
>> 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
