Re: [Gnu-arch-users] tla help

[Patrick Mauritz]

Am Samstag, 25. September 2004 01:16 schrieb Zenaan Harkness:
> Firstlyl, "full featured" version control systems generally have a few
> commands to deal with (examples I'm aware of: bk, tla, aegis).
just been writing a bit on this already..

tla help results in 120 unique lines, of which 18 are headers, newlines, 
underlines etc. (changes and file-diffs appear twice in non-|uniq output).

102 commands (incl. a bunch of aliases) - that's a lot.. how about providing a 
small help text, explaining the common commands, and a hint to a more 
extensive list (eg. via tla help --full, or even something hierarchical, like 
"tla help revisions")?

I'll just list some commands that I think aren't necessary in the base help:
- my-id, my-default-archive (you won't know what they do without a tutorial 
anyway, and you won't need them all the time either)
- whereis-archive (at least unless it's faster and more convenient to type the 
archive name instead of printing the whole list via 'archives' and do a 
visual grep)
- tree-root (mostly useful for scripts, or if you use configurations)
- id (never used - is this really used by an individual?)
- add-id, delete-id, move-id, explicit-default (alternatively their aliases)
- all revision library commands (like my-id)
- (apply-)changeset (or their aliases)
- make-(category|branch|version) (archive-setup?)
- "archive commands" except [ar]browse and maybe archive-fixup
- log-versions, add-log-version, remove-log-version, logs, cat-log
- "local cache commands" and "revision library commands" and "misc. scripting 
support" (these are nice for tuning, but for that, help texts won't be 
enough)

tla uses separate commands for similar operations instead of parameters, and 
has more operators than cvs in the first place, so tla help will be longer, 
but 185 lines (with 60 empty lines) is _slightly_ excessive.

================================== example ==================================
tla command [options]
  * quick help [to be replaced when using a given help category]
  get        : construct a project tree for a revision
  changes    : report about local changes in a project tree
  commit     : archive a changeset-based revision
  replay     : apply revision changesets to a project tree
  update     : update a project tree to reflect recent archived changes
  star-merge : merge mutually merged branches
  ...

  help : more extensive command list, see below for categories to be given as
    options. tla automatically completes to the shortest match.

  help categories: all, user, tree, inventory, patchset, archivetransaction,
    archive, patchlog, multiproject, branches, cache, revisionlibrary,
    scripting

Use tla command -h for help on `command', or tla command -H for detailed help
extensive documentation is available at (url|path)
================================== example ==================================

you can add 5 more commands to the quick help and still make it fit on a 80x25 
terminal. the path in the last line can be changed by distributors/packagers 
to a local copy of tutorial and documentation.


patrick mauritz