From: John Keeping <john@keeping.me.uk>
To: Jonathan Nieder <jrnieder@gmail.com>
Cc: Junio C Hamano <gitster@pobox.com>,
"Eric S. Raymond" <esr@thyrsus.com>,
git@vger.kernel.org, David Michael Barr <b@rr-dav.id.au>,
Pete Wyckoff <pw@padd.com>, Thomas Rast <trast@student.ethz.ch>
Subject: Re: [PATCH] git-fast-import(1): reorganise options
Date: Sun, 6 Jan 2013 14:28:25 +0000 [thread overview]
Message-ID: <20130106142825.GH6440@serenity.lan> (raw)
In-Reply-To: <20130106135109.GF22081@elie.Belkin>
On Sun, Jan 06, 2013 at 05:51:09AM -0800, Jonathan Nieder wrote:
> John Keeping wrote:
>> I left the "Semantics of execution" options with the general options
>> since I couldn't think of a sensible heading
>
> Neat trick. :)
I took inspiration from git-pull(1), which has a few general options
followed by several "Options related to..." sections.
> [...]
> > -- <8 --
> > The options in git-fast-import(1) are not currently arranged in a
> > logical order, which has caused the '--done' options to be documented
> > twice (commit 3266de10).
> >
> > Rearrange them into logical groups under subheadings.
>
> Nice description.
>
> > While doing this, fix the duplicate '--done' documentation by taking the
> > best bits of each. Also combine the descriptions of '--relative-marks'
> > and '--no-relative-marks' since they make more sense together.
>
> I'd prefer to keep those as separate patches, if that's manageable.
I'll send a series of three patches if the discussion below seems
reasonable:
[1/3] remove duplicate '--done'
[2/3] combine --[no-]relative-marks
[3/3] reorganize options
> The organization you propose is:
>
> OPTIONS
> -------
> --quiet
> --stats
> --force
> --cat-blob-fd
> --export-pack-edges
>
> Options related to the input stream
> ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> --date-format
> --done
>
> Options related to marks
> ~~~~~~~~~~~~~~~~~~~~~~~~
> --export-marks
> --import-marks
> --import-marks-if-exists
> --relative-marks
> --no-relative-marks
>
> Options for tuning
> ~~~~~~~~~~~~~~~~~~
> --active-branches
> --big-file-threshold
> --depth
> --max-pack-size
>
> These headings are less cryptic than the ones I proposed, which is a
> nice thing.
>
> My only nitpicks:
>
> I'd worry that the catch-all toplevel category would grow larger
> and larger with time, since it's the obvious place to put any new
> option.
I agree that that's a concern, perhaps '--cat-blob-fd' should be
combined with '--date-format' and '--done' into a section called
"Options for frontends" or similar?
And maybe '--export-pack-edges' can move to the performance/compression
tuning section? I expect the interested audience would be the same.
That only leaves three options in that section, which seems more
reasonable.
> Part of what I tried to do with the proposed categorization was to
> separate options that change the semantics of the import (which one
> uses with "feature" when they are specified in the fast-import stream
> since ignoring them results in a broken import) from options that only
> change superficial aspects of the interface or the details of how the
> resulting packfiles representing the same objects get written.
>
> The phrasing of the name of the category "Options related to the input
> stream" is too broad. All options relate to the input stream, since
> consuming an input stream and acting on it is all fast-import does.
> Something more specific than "related to" and a mention of "syntax"
> could make it clearer --- how about something like "Input Syntax
> Features"?
>
> Likewise, lots of functionality is _related_ to marks, but the marks
> options are the options that specify marks files. I don't know a good
> way to say that --- maybe "Location of Marks Files"?
>
> "Options for Tuning" could also be made more specific --- e.g.,
> "Performance and Compression Tuning".
I realise it's personal taste, but I like the subheadings of the form
"Options (for|related to) ...", so maybe:
Options for input stream features
Options related to marks files
Options for performance and compression tuning
Note that I chose sentence case instead of title case to be consistent
with git-pull(1).
> I like how you put important options like --force on top. Perhaps
> the less important --quiet and --stats could be split off from that
> into a subsection like "Verbosity" to make them stand out even more.
I quite like having the verbosity options near the top since those are
the ones that are most likely to be of interest to a user, whereas the
rest are likely to be prescribed by the frontend (or only really useful
to frontend authors).
John
next prev parent reply other threads:[~2013-01-06 14:29 UTC|newest]
Thread overview: 14+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-01-05 16:44 [PATCH] Alphabetize the fast-import options, following a suggestion on the list Eric S. Raymond
2013-01-05 23:11 ` Jonathan Nieder
2013-01-06 5:13 ` Eric S. Raymond
2013-01-06 7:12 ` Junio C Hamano
2013-01-06 13:29 ` [PATCH] git-fast-import(1): reorganise options John Keeping
2013-01-06 13:51 ` Jonathan Nieder
2013-01-06 14:28 ` John Keeping [this message]
2013-01-06 23:10 ` Junio C Hamano
2013-01-09 19:43 ` [PATCH v2 0/2] Reorganise options in git-fast-import(1) John Keeping
2013-01-09 19:44 ` [PATCH v2 1/2] git-fast-import(1): combine documentation of --[no-]relative-marks John Keeping
2013-01-09 21:42 ` Jonathan Nieder
2013-01-09 19:45 ` [PATCH v2 2/2] git-fast-import(1): reorganise options John Keeping
2013-01-09 22:21 ` Junio C Hamano
2013-01-06 13:34 ` [PATCH/RFC] fast-import doc: split OPTIONS into subsections Jonathan Nieder
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20130106142825.GH6440@serenity.lan \
--to=john@keeping.me.uk \
--cc=b@rr-dav.id.au \
--cc=esr@thyrsus.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jrnieder@gmail.com \
--cc=pw@padd.com \
--cc=trast@student.ethz.ch \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
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 read-only IMAP folder(s) and NNTP newsgroup(s).