* pedantry: is there a standard for what should be in the SYNOPSIS?
@ 2017-11-21 14:49 Robert P. J. Day
2017-11-21 17:54 ` Jonathan Nieder
0 siblings, 1 reply; 3+ messages in thread
From: Robert P. J. Day @ 2017-11-21 14:49 UTC (permalink / raw)
To: Git Mailing list
following up on an earlier question of mine, is there a standard for
what options should be listed in either the SYNOPSIS or the
DESCRIPTION sections of a man page? i ask since i'm seeing some
definite inconsistency.
in addition to the patch i submitted earlier, here are some other
examples.
"man git-clone", the SYNOPSIS says nothing about options "--verbose"
or "-v", even though "git clone" supports those options and they're
mentioned further down that man page.
on that same man page, there are a number of options that have two
supported forms (eg., "-l" and "--local"), but the SYNOPSIS shows only
the short form, while many other man pages show both (for another
example of this, see "man git-clean", which shows only the short
forms).
also, regarding what seems to be a standard for some options, it
seems that many commands support both options "--verbose" and "-v" to
mean verbose operation (as long as "-v" isn't reserved for some other
option for that command, which occasionally happens). in cases where
"-v" is not being used, is there a reason to not just add it as an
equivalent to "--verbose"?
the same thing could be said with respect to "-n" (as long as it's
available) always being the short form of "--dry-run". and so on, and
so on.
oh, and i'm still wondering why some commands feel the need to
explain the function of "--", when that's the sort of thing that more
properly belongs in "man gitcli".
thoughts?
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: pedantry: is there a standard for what should be in the SYNOPSIS?
2017-11-21 14:49 pedantry: is there a standard for what should be in the SYNOPSIS? Robert P. J. Day
@ 2017-11-21 17:54 ` Jonathan Nieder
2017-11-21 21:16 ` Robert P. J. Day
0 siblings, 1 reply; 3+ messages in thread
From: Jonathan Nieder @ 2017-11-21 17:54 UTC (permalink / raw)
To: Robert P. J. Day; +Cc: Git Mailing list
Hi,
Robert P. J. Day wrote:
> following up on an earlier question of mine, is there a standard for
> what options should be listed in either the SYNOPSIS or the
> DESCRIPTION sections of a man page? i ask since i'm seeing some
> definite inconsistency.
No standard. Seems worth starting a discussion on what you'd like the
standard to be.
Jonathan
^ permalink raw reply [flat|nested] 3+ messages in thread
* Re: pedantry: is there a standard for what should be in the SYNOPSIS?
2017-11-21 17:54 ` Jonathan Nieder
@ 2017-11-21 21:16 ` Robert P. J. Day
0 siblings, 0 replies; 3+ messages in thread
From: Robert P. J. Day @ 2017-11-21 21:16 UTC (permalink / raw)
To: Jonathan Nieder; +Cc: Git Mailing list
On Tue, 21 Nov 2017, Jonathan Nieder wrote:
> Hi,
>
> Robert P. J. Day wrote:
>
> > following up on an earlier question of mine, is there a standard
> > for what options should be listed in either the SYNOPSIS or the
> > DESCRIPTION sections of a man page? i ask since i'm seeing some
> > definite inconsistency.
>
> No standard. Seems worth starting a discussion on what you'd like
> the standard to be.
so i'm in charge? awesome. you won't regret it. :-)
rday
--
========================================================================
Robert P. J. Day Ottawa, Ontario, CANADA
http://crashcourse.ca
Twitter: http://twitter.com/rpjday
LinkedIn: http://ca.linkedin.com/in/rpjday
========================================================================
^ permalink raw reply [flat|nested] 3+ messages in thread
end of thread, other threads:[~2017-11-21 21:18 UTC | newest]
Thread overview: 3+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-11-21 14:49 pedantry: is there a standard for what should be in the SYNOPSIS? Robert P. J. Day
2017-11-21 17:54 ` Jonathan Nieder
2017-11-21 21:16 ` Robert P. J. Day
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).