[darcs-users] UI rfc: keyword-based help/documentation?

[Eric Kow]

Hi all,

In the Darcs UI, we've made some recent efforts at being a little bit more
informative about what's going on and what you can do.

Unfortunately, this makes the UI a lot chattier, which I think is probably
more annoying than helpful.

One proposal might be to introduce a keyword-based online help mechanism,
but I'm not sure how sensible this is, and I don't really have a clear idea
on how this fits into the rest of our documentation, or how we can use this
consistently.

Here's one example use: If you darcs get /tmp/blah (some missing directory),
this is what Darcs currently says and here's what a keyword help mechanism
would provide.

Original
--------
% darcs get /tmp/blah
darcs failed:  Not a repository: /tmp/blah (/tmp/blah/_darcs/inventory does not exist)

HINT: Do you have the right URI for the repository?

      If so, check with the repository owner to see if the following files
      are readable:

        1. _darcs/format    - might not exist; that's OK
        2. _darcs/inventory - should exist if #1 is missing
        3. _darcs/hashed_inventory - should exist if #2 is missing

Keyword-based Help
------------------
% dist/build/darcs/darcs get /tmp/blah

darcs failed:  Not a repository: /tmp/blah (/tmp/blah/_darcs/inventory does not exist)

Do you have the right URI or path? For details, `darcs help not-a-repo`

Comments?
---------
Things to consider:

1. When should we use this mechanism?  My rough idea is when Darcs has a
   lot to tell you.  Some thoughts would be the "bad cache" warnings from
   our 2010 GSoC, and also maybe the set-default hints.  Another area that
   could benefit from this is darcs send, which suffers from potentially
   un/misconfigured mail servers...

2. How does this relate to our documentation?  How do we avoid duplication?
   Do we start documenting all of darcs in the form of darcs help keywords?

3. How to do we control keyword growth?

4. What are our alternatives?

Thanks!

PS. http://bugs.darcs.net/patch583

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
For a faster response, try +44 (0)1273 64 2905 or
xmpp:kowey at jabber.fr (Jabber or Google Talk only)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20110508/a26c0b75/attachment.asc>