Re: [PATCH] git-fast-import(1): reorganise options
John Keeping writes: > 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 Sounds sensible and I like the direction in which this discussion is progressing. >> 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'll leave it to others to decide which individual options would fall into that catch-all category, but the idea you outlined above sounds sensible overall. > 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 Again, sounds sensible. >> 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). I tend to agree with Jonathan that verbosity options are less important ones than the ones that affect how things work. Thanks. -- 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
Re: [PATCH] git-fast-import(1): reorganise options
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
Re: [PATCH] git-fast-import(1): reorganise options
John Keeping wrote: > How about this? Ah, our patches crossed. > I left the "Semantics of execution" options with the general options > since I couldn't think of a sensible heading Neat trick. :) [...] > -- <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. 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. 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 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. Generally I think this is a better starting point for future work than the patch I sent. Thanks for writing it. Jonathan -- 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
