Re: On the size of the command set

Travis P wrote:
>
[...]
> In particular, learning a new system, a TOC often helps give a map of
> ideas that is useful and helps one find relevant similar information
> about a topic.
>
> When returning for reference, I think a (sorted) index is most useful.
[...]
> I'm thinking that TOC help by default might be the better approach for
> new users (I'm specifically contemplating specific new users for which I
> will be the live help resource, so I've a stake in the non-live help
> being as useful as possible. :-)

I think it would be overkill to have a way of selecting different output formats.

I agree that categorised (Table Of Contents style) help can be very useful. Indeed, on many occasions I have wished for categorised help output from programs like GNU 'ls' that have dozens of options. GNU 'diff' groups its help into functional categories with a blank line between each group, but gives no headings for the groups, so you can often spot an option similar to the one you want and then look near it, but it is still harder to find things than it need be.

If we were to categorise the subcommands in "svn help", that would, I believe, be a helpful incremental change, though really the number of commands at the moment is only just large enough to make it worthwhile.

However, it would be wrong to just do that and then stop without considering how this fits into the context of all the help we provide (including the book and the other command-line programs such as svnadmin). Some users would then treat "svn help" as on overview of the functional capabilities of Subversion, and so it would be rather unfriendly if under the heading "Inspecting" it didn't mention the separate program "svnversion", for instance. And the subcommands ought to be accompanied by brief descriptions, as Benjamin mentioned. And it would be rather a shame if, after seeing the subcommands nicely grouped, the switches for a particular subcommand were not also nicely grouped. (All of these are just my opinions, and arguable, of course.)

Note that the help text is not output by the software as a fixed block of text edited by hand, but as an automatically generated list of all the supported subcommands. Several command-line programs share this mechanism. The functions that do this would have to be changed. Of course they can be changed; I'm just making sure you're aware of this.

So there are several reasons why categorising the help output is not as trivial a matter as it perhaps first appears. If these concerns were addressed, I might support a patch for categorisation.

- Julian

---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Received on Sun Oct 3 13:27:29 2004