Re: [PATCH v2 1/5] doc: rework CodingGuidelines with new formatting rules

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Mar 29, 2024, 18:42 UTC
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:

Show 12 quoted lines

> 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.