git/list[1] front-page[2] threads[3] people[4] search[5] about
 

RE: [RFC] Documentation: --options in man-pages synopsys

From
LDLoyall, David <david.loyall@nebraska.gov>
Date
Oct 8, 2013, 14:03 UTC
Message-ID
<FCEE4469EE8B234199968ECA9B0661E230EC61C0@STNEEX10MB01.stone.ne.gov>
In-Reply-To
<CA+gfSn-o7cH3a-KWx_iggNc4-rYzQysbTj7OGdaggutLu-X-BA@mail.gmail.com>
As a unix user I'd expect the SYNOPSIS section at the top of the man page to include all options that the command accepts.  Mutually exclusive options are expected to be in the form [-q | --progress | --all-progress], such is already done.
I believe that you'd be safe in following http://pubs.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap12.html unless the git-* family of commands and documentation deviate from it in a way that I am not aware of.

Hope this helps, --Dave

Show 31 quoted lines
> -----Original Message-----
> From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On
> Behalf Of Dmitry Ivankov
> Sent: Tuesday, October 08, 2013 7:07 AM
> To: Git List
> Subject: [RFC] Documentation: --options in man-pages synopsys
> 
> Hi,
> 
> I've noticed that man git-pack-objects describes cmdline as following
> 
> SYNOPSYS
> 'git pack-objects' [-q | --progress | --all-progress] [--all-progress-implied] [--
> no-reuse-delta] [--delta-base-offset] [--non-empty] [--local] [--incremental]
> [--window=<n>] [--depth=<n>] [--revs [--unpacked | --all]] [--stdout | base-
> name] [--keep-true-parents] < object-list
> 
> while OPTIONS sections has even more options, --no-reuse-objects for
> instance.
> 
> Should it be dealt with and how?
> - add smth like ... at the tail of options in synopsys to indicate that there are
> more options
> - add all the [--options] to synopsys
> - drop all the [--options] as they all are optional
> - pick only the most common/important ones like -q --progress, per
> command or per command classes (hard to maintain and/or verify?)
> --
> To unsubscribe from this list: send the line "unsubscribe git" in the body of a
> message to majordomo@vger.kernel.org More majordomo info at
> http://vger.kernel.org/majordomo-info.html
Previous: Dmitry IvankovNext: Philip Oakley
Message 2 of 4 in “[RFC] Documentation: --options in man-pages synopsys”
  1. Dmitry IvankovOct 8, 2013
  2. Loyall, DavidOct 8, 2013
  3. Philip OakleyOct 9, 2013
  4. Jeff KingOct 10, 2013

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.