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
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Reply via email to