From: "Martin Ågren" <martin.agren@gmail.com>
To: "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, "Jean-Noël Avila" <jn.avila@free.fr>
Subject: Re: [PATCH 4/4] doc: git-clone: apply new documentation guidelines
Date: Tue, 26 Mar 2024 21:03:25 +0100 [thread overview]
Message-ID: <CAN0heSoSNxuoObvO_xtu1fXb+XYH+gBvVOWfJVBkpXouR0cmWQ@mail.gmail.com> (raw)
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:
>
> 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.
> -'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.
> ---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
next prev parent reply other threads:[~2024-03-26 20:03 UTC|newest]
Thread overview: 21+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-03-24 22:18 [PATCH 0/4] Doc new guidelines Jean-Noël Avila via GitGitGadget
2024-03-24 22:18 ` [PATCH 1/4] doc: rework CodingGuidelines with new formatting rules Jean-Noël Avila via GitGitGadget
2024-03-24 22:18 ` [PATCH 2/4] doc: allow literal and emphasis format in doc vs help tests Jean-Noël Avila via GitGitGadget
2024-03-28 10:06 ` Jeff King
2024-03-28 10:21 ` Eric Sunshine
2024-03-24 22:18 ` [PATCH 3/4] doc: git-init: apply new documentation formatting guidelines Jean-Noël Avila via GitGitGadget
2024-03-26 20:18 ` Martin Ågren
2024-03-26 20:26 ` Jean-Noël AVILA
2024-03-24 22:18 ` [PATCH 4/4] doc: git-clone: apply new documentation guidelines Jean-Noël Avila via GitGitGadget
2024-03-26 20:03 ` Martin Ågren [this message]
2024-03-26 20:20 ` Junio C Hamano
2024-03-26 20:49 ` Jean-Noël AVILA
2024-03-26 20:59 ` Junio C Hamano
2024-03-29 11:19 ` [PATCH v2 0/5] Doc new guidelines Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 1/5] doc: rework CodingGuidelines with new formatting rules Jean-Noël Avila via GitGitGadget
2024-03-29 18:42 ` Eric Sunshine
2024-03-30 17:36 ` Jean-Noël AVILA
2024-03-29 11:19 ` [PATCH v2 2/5] doc: allow literal and emphasis format in doc vs help tests Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 3/5] doc: git-init: apply new documentation formatting guidelines Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 4/5] doc: git-clone: " Jean-Noël Avila via GitGitGadget
2024-03-29 11:19 ` [PATCH v2 5/5] doc: git-clone: do not autoreference the manpage in itself Jean-Noël Avila via GitGitGadget
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=CAN0heSoSNxuoObvO_xtu1fXb+XYH+gBvVOWfJVBkpXouR0cmWQ@mail.gmail.com \
--to=martin.agren@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=jn.avila@free.fr \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).