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

[Denton Liu <liu.denton@gmail.com>]

On Mon, Aug 19, 2019 at 01:09:04PM -0400, Eric Sunshine wrote:
> On Sun, Aug 18, 2019 at 10:37 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.
> >
> > 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 camelcase.
> 
> I can't figure out if you typeset "camelcase" like that intentionally,
> as opposed to "camelCase" or "camel case" or "camel-case".

I thought that was how it's spelled but a quick Google search proves me
wrong.

> 
> > Signed-off-by: Denton Liu <liu.denton@gmail.com>
> > ---
> > diff --git a/Documentation/git-format-patch.txt b/Documentation/git-format-patch.txt
> >  --to=<email>::
> >         Add a `To:` header to the email headers. This is in addition
> > -       to any configured headers, and may be used multiple times.
> > +       to any configured headers, and may be used multiple times. The
> > +       emails given will be used along with any emails given by
> > +       `format.to` configurations.
> 
> Hmph. This seems redundant. The description already says "This is in
> addition to...", so a new sentence saying "...used along with..." is
> just parroting what was already stated.
> 
> >         The negated form `--no-to` discards all `To:` headers added so
> >         far (from config or command line).
> > @@ -314,7 +318,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 equal to "auto", a base commit
> > +       is automatically chosen.
> 
> "is equal to" is unnecessarily technical-sounding. How about:
> 
>     If <commit> is "auto", ...