From: Eric Sunshine <sunshine@sunshineco.com>
Date: Fri, 29 Mar 2024 18:42:28 GMT
Subject: Re: [PATCH v2 1/5] doc: rework CodingGuidelines with new formatting rules
Message-ID: <CAPig+cSzqUcTfnHBFTQWxjMbUZQBKahpD7eafmL=QvUDYtXTpw@mail.gmail.com>
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.