git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* aesthetic standard for synopsis line of man pages?
@ 2017-11-12 20:48 Robert P. J. Day
  0 siblings, 0 replies; only message in thread
From: Robert P. J. Day @ 2017-11-12 20:48 UTC (permalink / raw)
  To: Git Mailing list

[-- Attachment #1: Type: text/plain, Size: 2765 bytes --]


  yet more aesthetic nitpickery ... was just perusing the man pages of
both "git clean" and "git rm", and noticed some striking
inconsistency.

  from "man git-clean":

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

note how, in that sypnosis, even those options that are represented by
both a short form option (-f) and a corresponding long form (--force)
use only the short form in the synopsis, i'm assuming for brevity,
which makes perfect sense.

  "man git-rm" is a different beast entirely, with a hodge podge of
short forms and long forms with no apparent pattern:

  SYNOPSIS
       git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>...

  ... snip ...

  OPTIONS

       -f, --force
           Override the up-to-date check.

       -n, --dry-run
           Don’t actually remove any file(s). Instead, just show if
           they exist in the index and would otherwise be removed by
           the command.

       -r
           Allow recursive removal when a leading directory name is
           given.

       --
           This option can be used to separate command-line options
           from the list of files, (useful when filenames might be
           mistaken for command-line options).

       --cached
           Use this option to unstage and remove paths only from the
           index. Working tree files, whether modified or not, will
           be left alone.

       --ignore-unmatch
           Exit with a zero status even if no files matched.

       -q, --quiet
           git rm normally outputs one line (in the form of an rm
           command) for each file removed. This option suppresses
           that output.


  the strangeness above?

1) the synopsis itself lists the alternatives "[-f | --force]", which
seems unnecessary, as both forms are listed under OPTIONS

2) this is followed by *only* the short form (-n) of --dry-run, so
that's inconsistent

3) the SYNOPSIS weirdly includes *only* the long form (--quiet) rather
than the short form (-q)

4) is it standard to explain the "--" separator in a man page? i
don't recall seeing that in any other man page, but maybe i wasn't
paying attention. it seems unnecessary.

  in short, "man git-clean" seems reasonable, while "man git-rm"
appears somewhat disorganized.

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] only message in thread

only message in thread, other threads:[~2017-11-12 20:48 UTC | newest]

Thread overview: (only message) (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2017-11-12 20:48 aesthetic standard for synopsis line of man pages? Robert P. J. Day

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git