[darcs-users] query manifest --directories default

[Max Battcher]

Bit of a more general follow-up...  I think it might be useful in
trying to create some sort of policy for choosing thoughtful command
names...  I'm not sure how useful such a thing is, and I'm not a user
interface expert by any means, but I am hoping I might have enough of
a spark of passion here that it could be useful to darcs long term.

On 7/17/07, Eric Y. Kow <eric.kow at gmail.com> wrote:
> I'm not sure how I feel about list.  I'm slightly nervous about it being
> too 'similar' to the other commands (sorry, very vague), or it being too
> specific to things that can be listed.

I think specific in this case trumps vague.  I think that ``query``
has always felt like a odds-n-ends bag of miscellanea.  Can anyone
describe what ``query`` is actually for other than as a place to put
other "information" commands?  ``query`` in this case is pretty
useless semantically as a name and doesn't offer much in the way of
how to use darcs.  (In addition to being a 5 letter word with the ugly
'qu' at the beginning.)  As a word, 'query' sounds needlessly academic
in an otherwise "humane" command list.

What I think ``list`` has to offer over ``query`` is a
paradigm/strategy that is intuitively semantic.  By pushing for ``list
some-noun`` as a strategy it yields a simple goal-oriented approach to
darcs, and tells us just from the English language usage a lot about
what we might expect list to do and what might might expect to find as
noun-subcommands to it.  From a new user perspective:

I want to get some "thing" from darcs.  ``darcs list`` gives me lists
of "darcs things".  Does ``darcs list`` have the thing I'm looking
for?

I think that super-commands should have a modus operandi, a paradigm,
because we are asking the user (even if it is ourselves) to add the
additional level of indirection to their thinking and that level of
indirection should be as helpful as possible.  Rhetorical questions:
What do you expect to be sub-commands of ``query``?  ``list``?  If you
need to do some specific action how do you know to look under
``query``?  ``list``?  Suppose other super-commands existed and I gave
you the name of a query sub-command how would you know to find it
under query?  Instead, if I gave you a noun related to darcs, wouldn't
you immediately wonder if is "listable"?

So, Eric, you become correct in that if we open the flood gates for
some duplication where the set of goal-oriented "list a darcs thing"
intersects with existing commands.  Obviously that is something to
consider, but I don't think duplication is necessarily evil; instead I
think the duplication we see arise becomes our friend...

What's the difference between a ``darcs list patches`` and a ``darcs
changes``?  I think the better question becomes what's the mindset
that might cause someone to use one over the other.  If I'm new to
darcs and I'm told by a friend to see if I have the "Foo x in bar"
patch from 3 weeks ago, there is a necessary mental leap that the noun
``changes`` at the top level implies that it "shows patches", whereas
``list patches`` sounds just about obvious what it does and how...
Admittedly a trivial example as ``changes`` is one of the first
commands that people learn, but the illustration I think is useful
enough.

A better example is probably something like ``list patch-content``.
The goal: give me the dpatch (or contents) of a given patch without me
having to scavenge in _darcs/patches/.  ``list patch-content`` is
inferable from the goal.  ``darcs annotate`` isn't necessarily.  In
fact, I wouldn't know ``annotate`` did that if I hadn't asked on
darcs-users some time ago.  ``darcs annotate --help`` could enlighten
someone that it did that, but not ``darcs help``.  With just the goal
in mind, iterating through ``darcs help``, would you think to give
``darcs annotate --help`` a try?

But "duplicating" that functionality might not necessarily mean that
annotate's ability to do the same thing should vanish.  A newbie may
easily discover the nested list command and a darcs veteran may take
the time to learn that ``darcs ann --match='hash ...'`` does the same
thing and does it with less typing.  ``darcs list patch-content
--help`` could even say that.  Same goes for terse unix-style
top-level aliases and discoverable sub-commands: one can be found when
searching for a need and the other can be learned over time when
aiming for "efficiency".

Does all of this make sense?  I think that English-language semantics
play a large part in how easy to use a CLI program is, and there are
many good reasons to make even "sub-command buckets" have some meaning
and to keep that meaning in mind as you evolve the command "language"
that the program speaks.

-- 
--Max Battcher--
http://www.worldmaker.net/