CLI: improve docs w.r.t. aliases, add examples to 'tahoe put' and 'tahoe get' help output. Addresses part of #431

docs/CLI.txt

@@ -75,9 +75,6 @@ start using their changes.
 
 == Virtual Drive Manipulation ==
 
-[NOTE: This is a work-in-progress: none of this actually works yet].
-
-
 These commands let you exmaine a Tahoe virtual drive, providing basic
 list/upload/download/delete/rename/mkdir functionality. They can be used as
 primitives by other scripts. Most of these commands are fairly thin wrappers
@@ -91,9 +88,8 @@ a node on some other host, just create ~/.tahoe/ and copy that node's webapi
 URL into this file, and the CLI commands will contact that node instead of a
 local one.
 
-These commands also use ~/.tahoe/private/root_dir.cap to figure out which
-directory they ought to use a starting point. This is explained in more
-detail below.
+These commands also use a table of "aliases" to figure out which directory
+they ought to use a starting point. This is explained in more detail below.
 
 === Root Directories ===
 
@@ -115,24 +111,31 @@ directory, but instead each user's personal filesystem has a root that they
 use as a starting point for all their operations.
 
 In fact, each tahoe node remembers a list of starting points, named
-"aliases", in a file named ~/.tahoe/private/aliases . These are short strings
-that stand for a directory read- or write- cap. The default starting point
-uses an alias named "tahoe:", and for backwards compatibility can be stored
-in a file named ~/.tahoe/private/root_dir.cap .
+"aliases", in a file named ~/.tahoe/private/aliases . These aliases are short
+strings that stand in for a directory read- or write- cap. The default
+starting point uses an alias named "tahoe:".
 
-The Tahoe CLI commands use the same filename syntax as scp and rsync, an
+For backwards compatibility with Tahoe-1.0, if the "tahoe": alias is not
+found in ~/.tahoe/private/aliases, the CLI will use the contents of
+~/.tahoe/private/root_dir.cap instead. Tahoe-1.0 had only a single starting
+point, and stored it in this root_dir.cap file, so Tahoe-1.1 will use it if
+necessary. However, once you've set a "tahoe:" alias with "tahoe set-alias",
+that will override anything in the old root_dir.cap file.
+
+The Tahoe CLI commands use the same filename syntax as scp and rsync: an
 optional "alias:" prefix, followed by the pathname or filename. Many commands
 have arguments which supply a default tahoe: alias if you don't provide one
 yourself, but it is always safe to supply the alias. Some commands (like
 "tahoe cp") use the lack of an alias to mean that you want to refer to a
-local file, instead of something from the tahoe virtual filesystem. Another
-way to indicate this is to start the pathname with a dot, slash, or tilde.
+local file, instead of something from the tahoe virtual filesystem. [TODO]
+Another way to indicate this is to start the pathname with a dot, slash, or
+tilde.
 
 When you're dealing with your own personal filesystem, the "tahoe:" alias is
-all you need. But when you want to refer to something that isn't yet in your
-virtual drive, you need to refer to it by its URI. The way to do that is to
-add an alias to it, with the "tahoe add-alias" command. Once you've added an
-alias, you can use that alias as a prefix to the other commands.
+all you need. But when you want to refer to something that isn't yet attached
+to your virtual drive, you need to refer to it by its URI. The way to do that
+is to add an alias to it, with the "tahoe add-alias" command. Once you've
+added an alias, you can use that alias as a prefix to the other commands.
 
 The best way to get started with Tahoe is to create a node, start it, then
 use the following command to create a new directory and set it as your

src/allmydata/scripts/cli.py

@@ -11,8 +11,8 @@ class VDriveOptions(BaseOptions, usage.Options):
          "Look here to find out which Tahoe node should be used for all "
          "operations. The directory should either contain a full Tahoe node, "
          "or a file named node.url which points to some other Tahoe node. "
-         "It should also contain a file named root_dir.cap which contains "
-         "the root dirnode URI that should be used."
+         "It should also contain a file named private/aliases which contains "
+         "the mapping from alias name to root dirnode URI."
          ],
         ["node-url", "u", None,
          "URL of the tahoe node to use, a URL like \"http://127.0.0.1:8123\". "
@@ -91,6 +91,17 @@ class GetOptions(VDriveOptions):
     local filesystem. If LOCAL_FILE is omitted or '-', the contents of the file
     will be written to stdout."""
 
+    def getUsage(self, width=None):
+        t = VDriveOptions.getUsage(self, width)
+        t += """
+Examples:
+ % tahoe get FOO |less            # write to stdout
+ % tahoe get tahoe:FOO |less      # same
+ % tahoe get FOO bar              # write to local file
+ % tahoe get tahoe:FOO bar        # same
+"""
+        return t
+
 class PutOptions(VDriveOptions):
     optFlags = [
         ("mutable", "m", "Create a mutable file instead of an immutable one."),
@@ -119,8 +130,21 @@ class PutOptions(VDriveOptions):
         return "%s put LOCAL_FILE VDRIVE_FILE" % (os.path.basename(sys.argv[0]),)
 
     longdesc = """Put a file into the virtual drive (copying the file's
-    contents from the local filesystem). LOCAL_FILE is required to be a
-    local file (it can't be stdin)."""
+    contents from the local filesystem). If LOCAL_FILE is missing or '-',
+    data will be copied from stdin. VDRIVE_FILE is assumed to start with
+    tahoe: unless otherwise specified."""
+
+    def getUsage(self, width=None):
+        t = VDriveOptions.getUsage(self, width)
+        t += """
+Examples:
+ % cat FILE > tahoe put           # create unlinked file from stdin
+ % cat FILE > tahoe put FOO       # create tahoe:FOO from stdin
+ % cat FILE > tahoe put tahoe:FOO # same
+ % tahoe put bar FOO              # copy local 'bar' to tahoe:FOO
+ % tahoe put bar tahoe:FOO        # same
+"""
+        return t
 
 class CpOptions(VDriveOptions):
     optFlags = [