Re: [PATCH] git-fast-import(1): reorganise options

> On Sun, Jan 06, 2013 at 05:51:09AM -0800, Jonathan Nieder wrote:
> ...
>> 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

>> 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.

> 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

>> 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).