On Wed, 22 Nov 2017, Junio C Hamano wrote:
> "Robert P. J. Day" <rpjday@xxxxxxxxxxxxxx> 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@xxxxxxxxxxxxxx>
> >
> > ---
>
> 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
========================================================================
