Re: [PATCH v2] doc: Add missing "-n" (dry-run) option to reflog man page

From: Robert P. J. Day <rpjday@crashcourse.ca>
Date: Nov 22, 2017, 07:59 UTC
Message-ID: <alpine.LFD.2.21.1711220249020.31052@localhost.localdomain>
In-Reply-To: <xmqqh8tnvvom.fsf@gitster.mtv.corp.google.com>

On Wed, 22 Nov 2017, Junio C Hamano wrote:

Show 16 quoted lines

> "Robert P. J. Day" <rpjday@crashcourse.ca> writes:
>
> > While the "git reflog" man page supports both "--dry-run" and "-n" for
> > a dry run, the man page mentions only the former, not the latter.
> >
> > Signed-off-by: Robert P. J. Day <rpjday@crashcourse.ca>
> >
> > ---
>
> I have a suspicion that this was deliberately omitted in order to
> keep the lines in the description short and concise.  Just adding
> 5-columns may appear not to hurt too much, but these things tend to
> accumulate, so...
>
> Queued, so that I won't lose sight of it, but won't merge unless
> somebody else strongly feels about it.

  i appreciate the need for brevity, but this just takes us back to,
is there a standard for man pages, given how they bounce around all
over the place?

  i tossed in that missing "-n" option for "man git-reflog" since it
was the *only* option missing from the SYNOPSIS, and it didn't mess up
the aesthetics. but there are other examples that clearly aren't worth
the trouble:

  $ man git-clean
  SYNOPSIS
    git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...

where *only* the short forms are used in the SYNOPSIS.

  and, finally, there are examples that mix and match, like:

  $ man git-commit
  SYNOPSIS
    git commit [-a | --interactive | --patch] ...

which uses "-a" instead of "--all", but "--patch" instead of "-p". i'm fine if someone says, "there is no standard," but if there is, then the docs should follow them.

  thoughts?

rday

-- 
========================================================================
Robert P. J. Day                                 Ottawa, Ontario, CANADA
                        http://crashcourse.ca

Twitter:                                       http://twitter.com/rpjday
LinkedIn:                               http://ca.linkedin.com/in/rpjday
========================================================================