From: Jean-Noël AVILA <jn.avila@free.fr>
Date: Sat, 30 Mar 2024 17:36:57 GMT
Subject: Re: [PATCH v2 1/5] doc: rework CodingGuidelines with new formatting rules
Message-ID: <12414787.O9o76ZdvQC@cayenne>
In-Reply-To: <CAPig+cSzqUcTfnHBFTQWxjMbUZQBKahpD7eafmL=QvUDYtXTpw@mail.gmail.com>

On Friday, 29 March 2024 19:42:28 CET Eric Sunshine wrote:
> 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.
> 

A few examples don't hurt. Anyway, if I have to reroll a v3, I'll remove 
_<template-directory>_ which would be better located in the next paragraph.