Re: [PATCH] MyFirstContribution: render literal *

From: Linus Arver <linusa@google.com>
Date: Apr 5, 2023, 05:39 UTC
Message-ID: <owlyzg7mubui.fsf@fine.c.googlers.com>
In-Reply-To: <CAMP44s15E0xJwXv8qGp8FqQvB_KaxS2TXenNZNH_VzvXpXv4Hw@mail.gmail.com>

Hello Felipe!

Felipe Contreras <felipe.contreras@gmail.com> writes:

> Small nit: with this change we would lose the quotes, which are
> helpful, I would rather do "`foo`".

I see that the doc currently does not quote backticked areas, so this would be introducing a new style. I think such a change should belong in a separate patch.

That being said, personally I think having the quotes around the backticks makes things harder to read, especially for users directly reading from the raw *.txt file.

> And for what it's worth I would revamp the whole section, something like  
> this:

Show 7 quoted lines

> --- a/Documentation/MyFirstContribution.txt
> +++ b/Documentation/MyFirstContribution.txt
> @@ -1136,18 +1136,18 @@ information on how to handle comments from  
> reviewers.
>   We'll reuse our `psuh` topic branch for v2. Before we make any changes,  
> we'll
>   mark the tip of our v1 branch for easy reference:

Show 6 quoted lines

> -----
> +....
>   $ git checkout psuh
>   $ git branch psuh-v1
> -----
> +....

While I see the four dots (....) being used to denote regions in other files like SubmittingPatches, they are not used at all in MyFirstContribution.txt. So I am not sure why we would want to change this.