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

From: Martin Ågren <martin.agren@gmail.com>
Date: Mar 26, 2024, 20:03 UTC
Message-ID: <CAN0heSoSNxuoObvO_xtu1fXb+XYH+gBvVOWfJVBkpXouR0cmWQ@mail.gmail.com>
In-Reply-To: <5ae83d3f799e9ab84d5233f77cb91715415ae167.1711318740.git.gitgitgadget@gmail.com>

Thanks for working on this. This renders really nicely.

On Sun, 24 Mar 2024 at 23:20, Jean-Noël Avila via GitGitGadget <gitgitgadget@gmail.com> wrote:

Show 30 quoted lines

>
> From: =?UTF-8?q?Jean-No=C3=ABl=20Avila?= <jn.avila@free.fr>
>
> Heavily apply literal and placeholder markup everywhere.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
>  Documentation/config/clone.txt |  23 +++++--
>  Documentation/git-clone.txt    | 120 ++++++++++++++++-----------------
>  Documentation/urls.txt         |  22 +++---
>  3 files changed, 88 insertions(+), 77 deletions(-)
>
> diff --git a/Documentation/config/clone.txt b/Documentation/config/clone.txt
> index d037b57f729..0e0a8a1ae4a 100644
> --- a/Documentation/config/clone.txt
> +++ b/Documentation/config/clone.txt
> @@ -1,13 +1,22 @@
> -clone.defaultRemoteName::
> +`clone.defaultRemoteName`::
>         The name of the remote to create when cloning a repository.  Defaults to
> -       `origin`, and can be overridden by passing the `--origin` command-line
> +       `origin`.
> +ifdef::git-clone[]
> +       It can be overridden by passing the `--origin` command-line
> +       option.
> +endif::[]
> +ifndef::git-clone[]
> +       It can be overridden by passing the `--origin` command-line
>         option to linkgit:git-clone[1].
> +endif::[]

There's a bit more going on here than the commit message claims. FWIW, I think these changes are good, even if maybe a bit surprising.

Show 18 quoted lines

> -'git clone' [--template=<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[=<pathspec>]] [--[no-]shallow-submodules]
> -         [--[no-]remote-submodules] [--jobs <n>] [--sparse] [--[no-]reject-shallow]
> -         [--filter=<filter> [--also-filter-submodules]] [--] <repository>
> -         [<directory>]
> +`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.

Show 6 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`

Thanks. Apart from the small mistake and the misrendering of "[--[no-]", this looks really nice to me, both HTML and manpage. The source .txt files do get a bit messier, especially with the {empty} trickery, but ok. (I haven't been paying attention. Maybe this has been discussed before, and TBH I haven't even dug -- I don't mean to start another round of discussion.)

Martin