You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@subversion.apache.org by Greg Hudson <gh...@MIT.EDU> on 2004/09/25 03:23:00 UTC
On the size of the command set
I've often opposed adding new commands because I think we should keep
the command set small. Here's a reason why:
Arch is all of the above.. EXCEPT easy to use. Here's the
"eye-opener" that Mr. Lord really needs to address:
% svn --help | grep '^ ' | wc -l
28
% tla help | grep ' : ' | wc -l
105
I'm sorry but just watching that scroll by is enough to make me
say "well, maybe I'll figure this out later". Which is what I do
every time I look at Arch.
(from http://developers.slashdot.org/comments.pl?sid=123076&cid=10344192)
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Benjamin Pflugmann <be...@pflugmann.de>.
On Sat 2004-10-02 at 14:00:15 -0400, Greg Hudson wrote:
[...]
> I think the threshold for a subcommand list is higher than it is for
> GUI menus, and I think we haven't reached that threshold yet.
Thanks. You brought up some good points. And while I'd still like some
grouping, I admit that I have understated the usefulness of a sorted
list. I'll bring it up again, when the list size doubled or so. :)
HTH,
Benjamin.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Michael Sweet <mi...@easysw.com>.
Julian Foad wrote:
> 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. :-)
So how about the following:
Subcommands by category:
Modifying: add, copy, delete, mkdir, move
Synchronizing: commit, merge, resolved, update
Inspecting: blame, cat, diff, info, list, log, status
Respository: checkout, export, import
Maintenance: cleanup, revert, switch
Properties: propdel, propedit, propget, proplist, propset
Available subcommands:
commands...
That would add only a few lines to the output but would provide a
quick guide to new users. In fact, if you changed the output for
the "svn" command (no arguments) to include the categories, e.g.:
Type 'svn help' for usage.
Type "svn help <subcommand>" for help on a specific subcommand.
Subcommands by category:
Modifying: add, copy, delete, mkdir, move
Synchronizing: commit, merge, resolved, update
Inspecting: blame, cat, diff, info, list, log, status
Respository: checkout, export, import
Maintenance: cleanup, revert, switch
Properties: propdel, propedit, propget, proplist, propset
That output is under a page and would instantly give users a place
to start.
Also, I scraped some of the output above from the rc3 svn client; I
don't know if it was fixed in 1.1.0 (will check later today) but
you use single and double quotes inconsistently ('svn help' and
"svn help <subcommand>").
--
______________________________________________________________________
Michael Sweet, Easy Software Products mike at easysw dot com
Printing Software for UNIX http://www.easysw.com
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Julian Foad <ju...@btopenworld.com>.
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
Re: On the size of the command set
Posted by Travis P <sv...@castle.fastmail.fm>.
On Oct 2, 2004, at 1:00 PM, Greg Hudson wrote:
> It would be like the Subversion book including two different
> reference cards with the same information organized in different
> ways--theoretically a win, but in practice, likely to confuse more
> people than it helps.
I think that both could be useful. Serving different contexts.
I happen to enjoy having both a table of contents (grouping by some
author-decided-upon-and-imposed criteria) and an index in many books.
Yes, the things grouped in books aren't exactly the same, but I think
the idea holds. And people are not confused by the idea. I've
actually had reference cards that worked as you proposed and found both
options very useful. (I'm specifically remembering a card for 65C816
assembly language mnemonics where they were grouped by function and
also alphabetically.)
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.
Greg's example where one knows several possibilities and needs to
isolate the one this particular resource uses is a good one that I
experience relatively often.
Since new users might benefit more from the categorized (TOC-style)
help, it seems reasonable that that would be a reasonable default and
that same screen would mention a '--sorted' help switch for sorted
(index-style) help which the more experienced user might want (don't
make the user do a 'svn help help' to discover the sorted option). I'd
most likely prefer the index and the thought of using the extra typing
for such an option seems unpleasant -- but I can easily enough make an
alias.
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. :-)
-Travis
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Greg Hudson <gh...@MIT.EDU>.
On Sat, 2004-10-02 at 13:41, Benjamin Pflugmann wrote:
> Let me elaborate: IMHO, sorting something alphabetically mainly helps
> with finding something you know by name (or at least have an idea of
> its name).[1] If you have no idea of the name, you have to scan all
> items similar to an unsorted list. Admittedly, with the advantage that
> sorted lists are a bit easier on the eye.
I may have guesses as to the name of the operation you want, based on my
intuition or my experience with other systems. I can look for those
guesses faster in a sorted list.
> If we disregard the last bit (and you agree with my description), we
> are basically down to an unsorted vs. categorized list. Now, as said,
> an unsorted list doesn't speed up your search at all, while a
> categorized one at least helps those which are led by the task they
> want to accomplish.
A categorized list is, to me, more intimidating. Instead of having one
block of a reasonable number of commands, which I can take in as a unit,
I have six or seven blocks of three to six commands each, which is much
harder to treat as a gestalt. If I don't know what category the
operation I want fits into (and I think there will always be a lot of
ambiguity), then I might be worse off than if I had an unsorted list,
because there is simply more verbiage to hunt through.
A simple list allows me to mentally form my own categories, while a
categorized list forces me to accept someone else's.
Obviously, at some point a simple list breaks down. GUI programs have
multiple menu bars because one menu bar with scores of commands would be
unwieldy. (But you'll note that users frequently have to traverse all
of the menu bars in order to find the command they want. Is changing
preferences an "Edit", an "Action", or a "Tool"?) I think the threshold
for a subcommand list is higher than it is for GUI menus, and I think we
haven't reached that threshold yet.
> Ah, and are you opposed to offer both variants (e.g. via "--grouped"
> switch)?
Yes, that would be overengineering. Very few people would find the
--grouped switch, and fewer would find the groupings to be intuitive for
them. It would be like the Subversion book including two different
reference cards with the same information organized in different
ways--theoretically a win, but in practice, likely to confuse more
people than it helps.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Benjamin Pflugmann <be...@pflugmann.de>.
Let me start this email with a disclaimer, because it got a bit long:
There is no need for an elaborate answer. A short pointer to where you
disagree would be sufficient. And then I either learned somethine new
or we can agree to disagree. I only wrote in so much detail, because I
wanted to make my reasoning open (and make it easy for others to point
out what they see different).
On Sat 2004-10-02 at 12:42:38 -0400, Greg Hudson wrote:
> On Sat, 2004-10-02 at 09:50, Benjamin Pflugmann wrote:
> > On Sat 2004-09-25 at 07:58:55 +0100, Max Bowsher wrote:
> > >
> > > Perhaps we should think about categorizing our svn help output, to help
> > > maintain it's readability as we increase the number of commands?
> >
> > Since I pondered about this independently, I thought I'd make a start.
> > The excerpt below is the the output of "svn help" (from the 1.0.1
> > client, but the help output shouldn't have changed too much) with some
> > grouping added by me.
>
> My gut reaction is that as long as our command set remains manageable, a
> simple sorted list is probably better than a categorized list.
Maybe I overlook the obvious, but what's the advantage of a sorted
list here? Would you also prefer an unsorted list to a categorized
one? If not, I don't see what you see in a sorted list and would love
a hit with a cluebat.
Let me elaborate: IMHO, sorting something alphabetically mainly helps
with finding something you know by name (or at least have an idea of
its name).[1] If you have no idea of the name, you have to scan all
items similar to an unsorted list. Admittedly, with the advantage that
sorted lists are a bit easier on the eye.
If we disregard the last bit (and you agree with my description), we
are basically down to an unsorted vs. categorized list. Now, as said,
an unsorted list doesn't speed up your search at all, while a
categorized one at least helps those which are led by the task they
want to accomplish.
And the latter is - which probably comes as no surprise - the way I
use "svn help" the most: Having a strong idea of what I want to
accomplish and scanning the list for possible candidates (e.g. I
regularly forget "svn info" in my box of inspection tools).
> Of course, formal usability testing is the only way to rigorously decide
> this question, and I assume we're not going to get that.
Well, maybe it's just me, but I don't see more use in a sorted than in
an unsorted list. And if others agree that to be true, then it
shouldn't hurt much, if the unsorted list happens to group items by
their functionality.
Ah, and are you opposed to offer both variants (e.g. via "--grouped"
switch)?
Bye,
Benjamin.
[1] Hm. I just realized that a sorted list is more useful than I said
above, if you know the name, but need a reminder on how to spell a
command (e.g. I imagine remembering "resolved" can be tricky). But
I don't think that use case should influence our entry point to
the "help system" too much.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Greg Hudson <gh...@MIT.EDU>.
On Sat, 2004-10-02 at 09:50, Benjamin Pflugmann wrote:
> On Sat 2004-09-25 at 07:58:55 +0100, Max Bowsher wrote:
> >
> > Perhaps we should think about categorizing our svn help output, to help
> > maintain it's readability as we increase the number of commands?
>
> Since I pondered about this independently, I thought I'd make a start.
> The excerpt below is the the output of "svn help" (from the 1.0.1
> client, but the help output shouldn't have changed too much) with some
> grouping added by me.
My gut reaction is that as long as our command set remains manageable, a
simple sorted list is probably better than a categorized list.
Of course, formal usability testing is the only way to rigorously decide
this question, and I assume we're not going to get that.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Benjamin Pflugmann <be...@pflugmann.de>.
On Sat 2004-09-25 at 07:58:55 +0100, Max Bowsher wrote:
>
> Perhaps we should think about categorizing our svn help output, to help
> maintain it's readability as we increase the number of commands?
Since I pondered about this independently, I thought I'd make a start.
The excerpt below is the the output of "svn help" (from the 1.0.1
client, but the help output shouldn't have changed too much) with some
grouping added by me. The names of the groups IMHO suck, so please pay
more intention to the grouping itself. Whether you think the groups
themselves resp. the items assigned to them make sense.
Note, that one could easily get rid of the "Mass operations" and/or
"Working-copy maintenance" groups by putting them into the "misc"
group, if they are not worth their own group.
We could add a redundant "most used"/"basics" group at the start,
which would contain something like: add, commit, diff, help, update,
log, status.
I'd also add a (very) short description to the commands (regardless of
grouped or sorted output).
Ah, and if we decide to put the help into groups, we should consider
if we want to add a "--sorted" switch to get the current, sorted
output. Indeed, we may want to give the new output only when
"--grouped" (sp?) is added, depending on compatibility rules: Though I
doubt that some other tool depends on the command line help output,
it's not unthinkable, especially if it just get passed through to a
GUI.
And now to the subject of discussion:
----------------------------------------------------------------------
usage: svn <subcommand> [options] [args]
Type "svn help <subcommand>" for help on a specific subcommand.
Subversion is a tool for version control.
Most subcommands take file and/or directory arguments, recursing
on the directories. If no arguments are supplied to such a
command, it will recurse on the current directory (inclusive) by
default.
Available subcommands:
Modifying:
add
copy (cp)
delete (del, remove, rm)
mkdir
move (mv, rename, ren)
Synchronizing:
commit (ci)
update (up)
merge
resolved
Inspecting:
blame (praise, annotate, ann)
cat
diff (di)
info
list (ls)
log
status (stat, st)
Mass operations:
checkout (co)
export
import
Working-copy maintenance:
switch (sw)
cleanup
revert
Handling Properties:
propdel (pdel, pd)
propedit (pedit, pe)
propget (pget, pg)
proplist (plist, pl)
propset (pset, ps)
Misc:
help (?, h)
For additional information, see http://subversion.tigris.org/
----------------------------------------------------------------------
Bye,
Benjamin.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
RE: Pure java subversion library
Posted by Alexander Kitaev <al...@tmate.org>.
Hello Garrett,
> It looks like the doTestDatedRevision stuff is still failing,
> as is setUp for AbstractRepositoryTest. Still can't manage
Could you please send me the console output generated by the tests? On my
linux box (running Gentoo) the main source of the problems was that file
timestamps are calcualted up to the seconds, not milliseconds, so comapring
files by timestamps only gave false positives. I've changed this code and
also got rid of File.rename(...) calls that doesn't work on Linux and all
the tests pass on my system now. If method setUp fails that actually means
that fixture repository was not created for some reason and it is no
surprise that all the tests will fail...
I do not have access to the MacOS, but of course would like to make javasvn
library work there as well, so, it will be very helpful if people will run
tests or, better, use the library :) in other then windows environments. To
run tests one have to:
1) check out sources from the repository
(http://80.188.80.120/svn/jsvn/trunk/)
2) modify javasvn-test/test.${OS}.properties file (test.mac.properties for
mac or test.unix.properties for unix)
3) run "ant test" in the root folder. Program will create ~/testRepo folder
where all test repositorires, working copies and log files will be created,
then it will start svnserve and apache2 on ports 3690 and 8080 by default.
Servers will be killed as soon as tests are finished.
4) collect console output and send the results to alex@tmate.org if there
are any problems.
Tests assumes that there are svn, svnserve and apache2 server a installed
and properties file defines their locations. On Linux I've used jdk 1.5.0,
svn 1.1.0 and apache 2.0.51 to run tests.
> to make the ra_dav tests work, but it's probably a local
> problem. I had to comment out a bunch of stuff in the
> httpd.conf template to get it to even start, so I probably
> removed something important.
This file is minimalistic configuration file for apache2 web server. It is
quite strange that you should comment anything in it to make apache work...
More details, like error messages will help to fix the problem.
> One other question... Is there any reason that your library
> deviates from the naming conventions used for the C version
> of Subversion. For example, you call working copies
> workspaces, which isn't exactly intuitive, considering that
> all the documentation about Subversion calls them working
> copies...
I will think about changing this name. However ISVNWorkspace interface
represents not a single working copy file but rather a whole checked out
project, that why I've named it "workspace". But may be ISVNWorkingCopy will
sound better. BTW, interface with similar capabilites in javahl library is
called SVNClientInterface.
> I also found the placing of the code to implement
> the two RA layers inside a package called 'io' not very
> intuitive, I/O is a rather nonspecific kind of name...
Here I have to disagree, I'm following the JDK naming in this case, where
the low-level IO classes are located in the java.(n)io package. In javasvn
library I'm using the same naming scheme, all the interfaces that abstracts
low-level communication are placed in the "org.tmatesoft.svn.core.io"
package, and their implementation (accordingly to eclipse guidelines) in the
"org.tmatesoft.svn.core.internal.io.svn" and
"org.tmatesoft.svn.core.internal.io.dav" packages.
> -----Original Message-----
> From: Garrett Rooney [mailto:rooneg@electricjellyfish.net]
> Sent: Wednesday, October 06, 2004 12:17 AM
> To: alex@tmate.org
> Cc: dev@subversion.tigris.org
> Subject: Re: Pure java subversion library
>
> Alexander Kitaev wrote:
> > Hello Garrett,
> >
> > All tests (svn,dav) for svn java library
> (http://tmate.org/svn/) pass
> > both on windows and linux, so I hope they will work on
> macOS as well,
> > so you may update library sources and give it a try.
>
> It looks like the doTestDatedRevision stuff is still failing,
> as is setUp for AbstractRepositoryTest. Still can't manage
> to make the ra_dav tests work, but it's probably a local
> problem. I had to comment out a bunch of stuff in the
> httpd.conf template to get it to even start, so I probably
> removed something important.
>
> Unfortunately I've exhausted my "play around with things"
> quota for today, so I don't know when I'll get back to this...
>
> One other question... Is there any reason that your library
> deviates from the naming conventions used for the C version
> of Subversion. For example, you call working copies
> workspaces, which isn't exactly intuitive, considering that
> all the documentation about Subversion calls them working
> copies... I also found the placing of the code to implement
> the two RA layers inside a package called 'io' not very
> intuitive, I/O is a rather nonspecific kind of name...
>
> -garrett
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
> For additional commands, e-mail: dev-help@subversion.tigris.org
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: Pure java subversion library
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
Alexander Kitaev wrote:
> Hello Garrett,
>
> All tests (svn,dav) for svn java library (http://tmate.org/svn/) pass both
> on windows and linux, so I hope they will work on macOS as well, so you may
> update library sources and give it a try.
It looks like the doTestDatedRevision stuff is still failing, as is
setUp for AbstractRepositoryTest. Still can't manage to make the ra_dav
tests work, but it's probably a local problem. I had to comment out a
bunch of stuff in the httpd.conf template to get it to even start, so I
probably removed something important.
Unfortunately I've exhausted my "play around with things" quota for
today, so I don't know when I'll get back to this...
One other question... Is there any reason that your library deviates
from the naming conventions used for the C version of Subversion. For
example, you call working copies workspaces, which isn't exactly
intuitive, considering that all the documentation about Subversion calls
them working copies... I also found the placing of the code to
implement the two RA layers inside a package called 'io' not very
intuitive, I/O is a rather nonspecific kind of name...
-garrett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
RE: Pure java subversion library
Posted by Alexander Kitaev <al...@tmate.org>.
Hello Garrett,
All tests (svn,dav) for svn java library (http://tmate.org/svn/) pass both
on windows and linux, so I hope they will work on macOS as well, so you may
update library sources and give it a try.
Alexander Kitaev.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Garrett Rooney <ro...@electricjellyfish.net>.
Max Bowsher wrote:
> Greg Hudson wrote:
>
>> I've often opposed adding new commands because I think we should keep
>> the command set small. Here's a reason why:
>>
>> Arch is all of the above.. EXCEPT easy to use. Here's the
>> "eye-opener" that Mr. Lord really needs to address:
>>
>> % svn --help | grep '^ ' | wc -l
>> 28
>>
>> % tla help | grep ' : ' | wc -l
>> 105
>>
>> I'm sorry but just watching that scroll by is enough to make me
>> say "well, maybe I'll figure this out later". Which is what I do
>> every time I look at Arch.
>
>
> True.
>
> We know we are going to need some more sooner or later though - for
> locking, and I think also we may need an analogue of 'cvs release -d'
> when we get non-recursive checkouts working.
>
> Perhaps we should think about categorizing our svn help output, to help
> maintain it's readability as we increase the number of commands?
I suspect we can get by with simply thinking good and hard before we add
commands at all. Yes, there are situations in the near future where we
will likely have to add one or two commands, and that's fine, we all
know that's going to happen at some point, we just need to always keep
in mind that a big part of Subversion's appeal is that it's easy to
learn, and when the command set gets too big we're in danger of losing
that advantage.
-garrett
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org
Re: On the size of the command set
Posted by Max Bowsher <ma...@ukf.net>.
Greg Hudson wrote:
> I've often opposed adding new commands because I think we should keep
> the command set small. Here's a reason why:
>
> Arch is all of the above.. EXCEPT easy to use. Here's the
> "eye-opener" that Mr. Lord really needs to address:
>
> % svn --help | grep '^ ' | wc -l
> 28
>
> % tla help | grep ' : ' | wc -l
> 105
>
> I'm sorry but just watching that scroll by is enough to make me
> say "well, maybe I'll figure this out later". Which is what I do
> every time I look at Arch.
True.
We know we are going to need some more sooner or later though - for locking,
and I think also we may need an analogue of 'cvs release -d' when we get
non-recursive checkouts working.
Perhaps we should think about categorizing our svn help output, to help
maintain it's readability as we increase the number of commands?
Max.
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@subversion.tigris.org
For additional commands, e-mail: dev-help@subversion.tigris.org