From: Eric Sunshine <sunshine@sunshineco.com>
To: "Jean-Noël Avila via GitGitGadget" <gitgitgadget@gmail.com>
Cc: git@vger.kernel.org, "Martin Ågren" <martin.agren@gmail.com>,
"Jeff King" <peff@peff.net>, "Jean-Noël Avila" <jn.avila@free.fr>
Subject: Re: [PATCH v2 1/5] doc: rework CodingGuidelines with new formatting rules
Date: Fri, 29 Mar 2024 14:42:28 -0400 [thread overview]
Message-ID: <CAPig+cSzqUcTfnHBFTQWxjMbUZQBKahpD7eafmL=QvUDYtXTpw@mail.gmail.com> (raw)
In-Reply-To: <8a25ab1c3b61ebea9942fe106d4e0547a81743a4.1711711181.git.gitgitgadget@gmail.com>
On Fri, Mar 29, 2024 at 7:19 AM Jean-Noël Avila via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> Literal and placeholder formatting is more heavily enforced, with some
> asciidoc magic. Basically, the markup is preserved everywhere.
>
> Signed-off-by: Jean-Noël Avila <jn.avila@free.fr>
> ---
> diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
> @@ -682,68 +682,118 @@ Writing Documentation:
> If a placeholder has multiple words, they are separated by dashes:
> - <new-branch-name>
> - --template=<template-directory>
> + _<new-branch-name>_
> + _<template-directory>_
Having two separate examples made sense in the original because it was
illustrating a standalone placeholder versus a placeholder coupled
with some literal text ("--template="). However, in the revised hunk,
there is no reason to use both "_<new-branch-name>_" and
"_<template-directory>_" as examples; the reader does not learn
anything new from the second example which couldn't be learned from
the first. As such, I'd drop the latter example.
next prev parent reply other threads:[~2024-03-29 18:42 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
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 [this message]
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='CAPig+cSzqUcTfnHBFTQWxjMbUZQBKahpD7eafmL=QvUDYtXTpw@mail.gmail.com' \
--to=sunshine@sunshineco.com \
--cc=git@vger.kernel.org \
--cc=gitgitgadget@gmail.com \
--cc=jn.avila@free.fr \
--cc=martin.agren@gmail.com \
--cc=peff@peff.net \
/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).