{"thread":{"id":"47183","subject":"aesthetic standard for synopsis line of man pages?","startedAt":"2017-11-12T20:48:40Z","lastAt":"2017-11-12T20:48:40Z","messageCount":1,"participants":["Robert P. J. Day"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"332363","messageId":"alpine.LFD.2.21.1711121537440.7324@localhost.localdomain","threadId":"47183","inReplyTo":null,"subject":"aesthetic standard for synopsis line of man pages?","fromName":"Robert P. J. Day","fromEmail":"rpjday@crashcourse.ca","sentAt":"2017-11-12T20:48:10Z","receivedAt":"2017-11-12T20:48:40Z","isPatch":false,"sender":{"key":"rpjday@crashcourse.ca","avatar":"https://avatars.githubusercontent.com/u/226084077?v=4"},"body":"\n  yet more aesthetic nitpickery ... was just perusing the man pages of\nboth \"git clean\" and \"git rm\", and noticed some striking\ninconsistency.\n\n  from \"man git-clean\":\n\n  SYNOPSIS\n       git clean [-d] [-f] [-i] [-n] [-q] [-e <pattern>] [-x | -X] [--] <path>...\n\nnote how, in that sypnosis, even those options that are represented by\nboth a short form option (-f) and a corresponding long form (--force)\nuse only the short form in the synopsis, i'm assuming for brevity,\nwhich makes perfect sense.\n\n  \"man git-rm\" is a different beast entirely, with a hodge podge of\nshort forms and long forms with no apparent pattern:\n\n  SYNOPSIS\n       git rm [-f | --force] [-n] [-r] [--cached] [--ignore-unmatch] [--quiet] [--] <file>...\n\n  ... snip ...\n\n  OPTIONS\n\n       -f, --force\n           Override the up-to-date check.\n\n       -n, --dry-run\n           Don’t actually remove any file(s). Instead, just show if\n           they exist in the index and would otherwise be removed by\n           the command.\n\n       -r\n           Allow recursive removal when a leading directory name is\n           given.\n\n       --\n           This option can be used to separate command-line options\n           from the list of files, (useful when filenames might be\n           mistaken for command-line options).\n\n       --cached\n           Use this option to unstage and remove paths only from the\n           index. Working tree files, whether modified or not, will\n           be left alone.\n\n       --ignore-unmatch\n           Exit with a zero status even if no files matched.\n\n       -q, --quiet\n           git rm normally outputs one line (in the form of an rm\n           command) for each file removed. This option suppresses\n           that output.\n\n\n  the strangeness above?\n\n1) the synopsis itself lists the alternatives \"[-f | --force]\", which\nseems unnecessary, as both forms are listed under OPTIONS\n\n2) this is followed by *only* the short form (-n) of --dry-run, so\nthat's inconsistent\n\n3) the SYNOPSIS weirdly includes *only* the long form (--quiet) rather\nthan the short form (-q)\n\n4) is it standard to explain the \"--\" separator in a man page? i\ndon't recall seeing that in any other man page, but maybe i wasn't\npaying attention. it seems unnecessary.\n\n  in short, \"man git-clean\" seems reasonable, while \"man git-rm\"\nappears somewhat disorganized.\n\nrday\n\n-- \n\n========================================================================\nRobert P. J. Day                                 Ottawa, Ontario, CANADA\n                        http://crashcourse.ca\n\nTwitter:                                       http://twitter.com/rpjday\nLinkedIn:                               http://ca.linkedin.com/in/rpjday\n========================================================================"}]}