Re: [PATCH v2 2/4] Doc: add more detail for git-format-patch

From: Denton Liu <liu.denton@gmail.com>
Date: Aug 20, 2019, 07:07 UTC
Message-ID: <20190820070740.GA29407@archbookpro.localdomain>
In-Reply-To: <CAPig+cTL3rtPuMQiFfZPcAX7T=v8fVSOL07ULDbXUuG+GD_jzQ@mail.gmail.com>

On Mon, Aug 19, 2019 at 10:44:03PM -0400, Eric Sunshine wrote:

Show 27 quoted lines

> On Mon, Aug 19, 2019 at 7:53 PM Denton Liu <liu.denton@gmail.com> wrote:
> > In git-format-patch.txt, we were missing some key user information.
> > First of all, using the `--to` and `--cc` options don't override
> > `format.to` and `format.cc` variables, respectively. They add on to each
> > other. Document this.
> 
> This entire paragraph can go away since v2 dropped this change.
> 
> > In addition, document the special value of `--base=auto`.
> >
> > Next, while we're at it, surround option arguments with <>.
> >
> > Finally, document the `format.outputDirectory` config and change
> > `format.coverletter` to use camel case.
> >
> > Signed-off-by: Denton Liu <liu.denton@gmail.com>
> > ---
> > diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> > @@ -314,7 +314,8 @@ you can use `--suffix=-patch` to get `0001-description-of-my-change-patch`.
> >  --base=<commit>::
> >         Record the base tree information to identify the state the
> >         patch series applies to.  See the BASE TREE INFORMATION section
> > -       below for details.
> > +       below for details. If <commit> is "auto", a base commit is
> > +       automatically chosen.
> 
> Should <commit> be encased in backquotes in the paragraph body?

In this page, it seems like the other instances of <commit> (or most other <text> for that matter) aren't wrapped in backquotes. From checking out the rest of Git's documentation, it seems like it's a mixed bag whether to do this or not.

I'm going to leave it as is and hopefully someone who cares enough will make the docs more stylistically uniform.