docs/frontends/CLI.rst: changes to formatting (mainly putting commands and filenames in monospace), and to command syntax to reflect that DIRCAP/... is accepted. Clarify the syntax of 'tahoe put' and other minor corrections. Tahoe -> Tahoe-LAFS.

docs/frontends/CLI.rst

@@ -1,6 +1,6 @@
-======================
+===========================
-The Tahoe CLI commands
+The Tahoe-LAFS CLI commands
-======================
+===========================
 
 1.  `Overview`_
 2.  `CLI Command Overview`_
@@ -18,20 +18,21 @@ The Tahoe CLI commands
 Overview
 ========
 
-Tahoe provides a single executable named "``tahoe``", which can be used to
+Tahoe-LAFS provides a single executable named "``tahoe``", which can be used to
 create and manage client/server nodes, manipulate the filesystem, and perform
 several debugging/maintenance tasks.
 
 This executable lives in the source tree at "``bin/tahoe``". Once you've done a
-build (by running "make"), ``bin/tahoe`` can be run in-place: if it discovers
+build (by running "``make``" or "``python setup.py build``"), ``bin/tahoe`` can
-that it is being run from within a Tahoe source tree, it will modify sys.path
+be run in-place: if it discovers that it is being run from within a Tahoe-LAFS
-as necessary to use all the source code and dependent libraries contained in
+source tree, it will modify ``sys.path`` as necessary to use all the source code
-that tree.
+and dependent libraries contained in that tree.
 
-If you've installed Tahoe (using "``make install``", or by installing a binary
+If you've installed Tahoe-LAFS (using "``make install``" or
-package), then the tahoe executable will be available somewhere else, perhaps
+"``python setup.py install``", or by installing a binary package), then the
-in ``/usr/bin/tahoe``. In this case, it will use your platform's normal
+``tahoe`` executable will be available somewhere else, perhaps in
-PYTHONPATH search paths to find the tahoe code and other libraries.
+``/usr/bin/tahoe``. In this case, it will use your platform's normal
+PYTHONPATH search path to find the Tahoe-LAFS code and other libraries.
 
 
 CLI Command Overview
@@ -47,7 +48,7 @@ To get a list of all commands, just run "``tahoe``" with no additional
 arguments. "``tahoe --help``" might also provide something useful.
 
 Running "``tahoe --version``" will display a list of version strings, starting
-with the "allmydata" module (which contains the majority of the Tahoe
+with the "allmydata" module (which contains the majority of the Tahoe-LAFS
 functionality) and including versions for a number of dependent libraries,
 like Twisted, Foolscap, pycryptopp, and zfec.
 
@@ -60,34 +61,35 @@ creates a new directory and populates it with files that will allow the
 "``tahoe start``" command to use it later on. This command creates nodes that
 have client functionality (upload/download files), web API services
 (controlled by the 'webport' file), and storage services (unless
-"--no-storage" is specified).
+``--no-storage`` is specified).
 
-NODEDIR defaults to ~/.tahoe/ , and newly-created nodes default to
+NODEDIR defaults to ``~/.tahoe/`` , and newly-created nodes default to
 publishing a web server on port 3456 (limited to the loopback interface, at
 127.0.0.1, to restrict access to other programs on the same host). All of the
-other "``tahoe``" subcommands use corresponding defaults.
+other "``tahoe``" subcommands use corresponding defaults (with the exception
+that "``tahoe run``" defaults to running a node in the current directory).
 
 "``tahoe create-client [NODEDIR]``" creates a node with no storage service.
 That is, it behaves like "``tahoe create-node --no-storage [NODEDIR]``".
-(This is a change from versions prior to 1.6.0.)
+(This is a change from versions prior to v1.6.0.)
 
 "``tahoe create-introducer [NODEDIR]``" is used to create the Introducer node.
 This node provides introduction services and nothing else. When started, this
-node will produce an introducer.furl, which should be published to all
+node will produce an ``introducer.furl`` file, which should be published to all
 clients.
 
 "``tahoe create-key-generator [NODEDIR]``" is used to create a special
 "key-generation" service, which allows a client to offload their RSA key
 generation to a separate process. Since RSA key generation takes several
 seconds, and must be done each time a directory is created, moving it to a
-separate process allows the first process (perhaps a busy wapi server) to
+separate process allows the first process (perhaps a busy webapi server) to
 continue servicing other requests. The key generator exports a FURL that can
 be copied into a node to enable this functionality.
 
 "``tahoe run [NODEDIR]``" will start a previously-created node in the foreground.
 
-"``tahoe start [NODEDIR]``" will launch a previously-created node. It will launch
+"``tahoe start [NODEDIR]``" will launch a previously-created node. It will
-the node into the background, using the standard Twisted "twistd"
+launch the node into the background, using the standard Twisted "``twistd``"
 daemon-launching tool. On some platforms (including Windows) this command is
 unable to run a daemon in the background; in that case it behaves in the
 same way as "``tahoe run``".
@@ -102,23 +104,23 @@ start using their changes.
 Filesystem Manipulation
 =======================
 
-These commands let you exmaine a Tahoe filesystem, providing basic
+These commands let you exmaine a Tahoe-LAFS filesystem, 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
-around wapi calls.
+around webapi calls, which are described in `<webapi.rst>`_.
 
-By default, all filesystem-manipulation commands look in ~/.tahoe/ to figure
+By default, all filesystem-manipulation commands look in ``~/.tahoe/`` to figure
-out which Tahoe node they should use. When the CLI command uses wapi calls,
+out which Tahoe-LAFS node they should use. When the CLI command makes webapi
-it will use ~/.tahoe/node.url for this purpose: a running Tahoe node that
+calls, it will use ``~/.tahoe/node.url`` for this purpose: a running Tahoe-LAFS
-provides a wapi port will write its URL into this file. If you want to use
+node that provides a webapi port will write its URL into this file. If you want
-a node on some other host, just create ~/.tahoe/ and copy that node's wapi
+to use a node on some other host, just create ``~/.tahoe/`` and copy that node's
-URL into this file, and the CLI commands will contact that node instead of a
+webapi URL into this file, and the CLI commands will contact that node instead
-local one.
+of a local one.
 
 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.
 
-As of Tahoe v1.7 (v1.7.1 on Windows), passing non-ASCII characters to the
+As of Tahoe-LAFS v1.7 (v1.7.1 on Windows), passing non-ASCII characters to the
 CLI should work. On Unix, the command-line arguments are assumed to use the
 character encoding specified by the current locale.
 
@@ -135,50 +137,52 @@ together into a directed graph.
 
 To use this collection of files and directories, you need to choose a
 starting point: some specific directory that we will refer to as a
-"starting directory".  For a given starting directory, the "``ls
+"starting directory".  For a given starting directory, the
-[STARTING_DIR]:``" command would list the contents of this directory,
+"``ls [STARTING_DIR]``" command would list the contents of this directory,
-the "``ls [STARTING_DIR]:dir1``" command would look inside this directory
+the "``ls [STARTING_DIR]/dir1``" command would look inside this directory
-for a child named "dir1" and list its contents, "``ls
+for a child named "dir1" and list its contents,
-[STARTING_DIR]:dir1/subdir2``" would look two levels deep, etc.
+"``ls [STARTING_DIR]/dir1/subdir2``" would look two levels deep, etc.
 
 Note that there is no real global "root" directory, but instead each
 starting directory provides a different, possibly overlapping
 perspective on the graph of files and directories.
 
-Each tahoe node remembers a list of starting points, named "aliases",
+Each Tahoe-LAFS node remembers a list of starting points, called "aliases",
-in a file named ~/.tahoe/private/aliases . These aliases are short UTF-8
+which are short Unicode strings that stand in for a directory read- or
-encoded strings that stand in for a directory read- or write- cap. If
+write- cap. They are stored (encoded as UTF-8) in the file
-you use the command line "``ls``" without any "[STARTING_DIR]:" argument,
+``NODEDIR/private/aliases`` .  If you use the command line "``tahoe ls``"
-then it will use the default alias, which is "tahoe", therefore "``tahoe
+without any "[STARTING_DIR]" argument, then it will use the default alias,
-ls``" has the same effect as "``tahoe ls tahoe:``".  The same goes for the
+which is ``tahoe:``, therefore "``tahoe ls``" has the same effect as
-other commands which can reasonably use a default alias: get, put,
+"``tahoe ls tahoe:``".  The same goes for the other commands that can
-mkdir, mv, and rm.
+reasonably use a default alias: ``get``, ``put``, ``mkdir``, ``mv``, and
+``rm``.
 
-For backwards compatibility with Tahoe-1.0, if the "tahoe": alias is not
+For backwards compatibility with Tahoe-LAFS v1.0, if the ``tahoe:`` alias
-found in ~/.tahoe/private/aliases, the CLI will use the contents of
+is not found in ``~/.tahoe/private/aliases``, the CLI will use the contents
-~/.tahoe/private/root_dir.cap instead. Tahoe-1.0 had only a single starting
+of ``~/.tahoe/private/root_dir.cap`` instead. Tahoe-LAFS v1.0 had only a
-point, and stored it in this root_dir.cap file, so Tahoe-1.1 will use it if
+single starting point, and stored it in this ``root_dir.cap`` file, so v1.1
-necessary. However, once you've set a "tahoe:" alias with "``tahoe set-alias``",
+and later will use it if necessary. However, once you've set a ``tahoe:``
-that will override anything in the old root_dir.cap file.
+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
+The Tahoe-LAFS CLI commands use the same path syntax as ``scp`` and
--- an optional "alias:" prefix, followed by the pathname or filename.
+``rsync`` -- an optional ``ALIAS:`` prefix, followed by the pathname or
-Some commands (like "tahoe cp") use the lack of an alias to mean that
+filename. Some commands (like "``tahoe cp``") use the lack of an alias to
-you want to refer to a local file, instead of something from the tahoe
+mean that you want to refer to a local file, instead of something from the
-virtual filesystem. [TODO] Another way to indicate this is to start
+Tahoe-LAFS filesystem. [TODO] Another way to indicate this is to start
 the pathname with a dot, slash, or tilde.
 
-When you're dealing a single starting directory, the "tahoe:" alias is
+When you're dealing a single starting directory, the ``tahoe:`` alias is
 all you need. But when you want to refer to something that isn't yet
 attached to the graph rooted at that starting directory, you need to
 refer to it by its capability. The way to do that is either to use its
 capability directory as an argument on the command line, or to add an
-alias to it, with the "tahoe add-alias" command. Once you've added an
+alias to it, with the "``tahoe add-alias``" command. Once you've added an
 alias, you can use that alias as an argument to commands.
 
-The best way to get started with Tahoe is to create a node, start it, then
+The best way to get started with Tahoe-LAFS is to create a node, start it,
-use the following command to create a new directory and set it as your
+then use the following command to create a new directory and set it as your
-"tahoe:" alias::
+``tahoe:`` alias::
 
  tahoe create-alias tahoe
 
@@ -189,21 +193,21 @@ you've just created.
 SECURITY NOTE: For users of shared systems
 ``````````````````````````````````````````
 
-Another way to achieve the same effect as the above "tahoe create-alias"
+Another way to achieve the same effect as the above "``tahoe create-alias``"
 command is::
 
  tahoe add-alias tahoe `tahoe mkdir`
 
 However, command-line arguments are visible to other users (through the
-'ps' command, or the Windows Process Explorer tool), so if you are using a
+``ps`` command or ``/proc`` filesystem, or the Windows Process Explorer tool),
-tahoe node on a shared host, your login neighbors will be able to see (and
+so if you are using a Tahoe-LAFS node on a shared host, your login neighbors
-capture) any directory caps that you set up with the "``tahoe add-alias``"
+will be able to see (and capture) any directory caps that you set up with the
-command.
+"``tahoe add-alias``" command.
 
 The "``tahoe create-alias``" command avoids this problem by creating a new
 directory and putting the cap into your aliases file for you. Alternatively,
-you can edit the NODEDIR/private/aliases file directly, by adding a line like
+you can edit the ``NODEDIR/private/aliases`` file directly, by adding a line
-this::
+like this::
 
  fun: URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
 
@@ -211,69 +215,65 @@ By entering the dircap through the editor, the command-line arguments are
 bypassed, and other users will not be able to see them. Once you've added the
 alias, no other secrets are passed through the command line, so this
 vulnerability becomes less significant: they can still see your filenames and
-other arguments you type there, but not the caps that Tahoe uses to permit
+other arguments you type there, but not the caps that Tahoe-LAFS uses to permit
 access to your files and directories.
 
 
 Command Syntax Summary
 ----------------------
 
-tahoe add-alias alias cap
+``tahoe add-alias ALIAS DIRCAP``
 
-tahoe create-alias alias
+``tahoe create-alias ALIAS``
 
-tahoe list-aliases
+``tahoe list-aliases``
 
-tahoe mkdir
+``tahoe mkdir``
 
-tahoe mkdir [alias:]path
+``tahoe mkdir PATH``
 
-tahoe ls [alias:][path]
+``tahoe ls [PATH]``
 
-tahoe webopen [alias:][path]
+``tahoe webopen [PATH]``
 
-tahoe put [--mutable] [localfrom:-]
+``tahoe put [--mutable] [FROMLOCAL|-]``
 
-tahoe put [--mutable] [localfrom:-] [alias:]to
+``tahoe put [--mutable] FROMLOCAL|- TOPATH``
 
-tahoe put [--mutable] [localfrom:-] [alias:]subdir/to
+``tahoe put [FROMLOCAL|-] mutable-file-writecap``
 
-tahoe put [--mutable] [localfrom:-] dircap:to
+``tahoe get FROMPATH [TOLOCAL|-]``
 
-tahoe put [--mutable] [localfrom:-] dircap:./subdir/to
+``tahoe cp [-r] FROMPATH TOPATH``
 
-tahoe put [localfrom:-] mutable-file-writecap
+``tahoe rm PATH``
 
-tahoe get [alias:]from [localto:-]
+``tahoe mv FROMPATH TOPATH``
 
-tahoe cp [-r] [alias:]frompath [alias:]topath
+``tahoe ln FROMPATH TOPATH``
 
-tahoe rm [alias:]what
+``tahoe backup FROMLOCAL TOPATH``
 
-tahoe mv [alias:]from [alias:]to
+In these summaries, ``PATH``, ``TOPATH`` or ``FROMPATH`` can be one of::
 
-tahoe ln [alias:]from [alias:]to
+ * ``[SUBDIRS/]FILENAME`` for a path relative to the default ``tahoe:`` alias;
+ * ``ALIAS:[SUBDIRS/]FILENAME`` for a path relative to another alias;
+ * ``DIRCAP/[SUBDIRS/]FILENAME`` or ``DIRCAP:./[SUBDIRS/]FILENAME`` for a path relative to a directory cap.
 
-tahoe backup localfrom [alias:]to
 
 Command Examples
 ----------------
 
-``tahoe mkdir``
+``tahoe add-alias ALIAS DIRCAP``
-
- This creates a new empty unlinked directory, and prints its write-cap to
- stdout. The new directory is not attached to anything else.
-
-``tahoe add-alias fun DIRCAP``
 
  An example would be::
 
   tahoe add-alias fun URI:DIR2:ovjy4yhylqlfoqg2vcze36dhde:4d4f47qko2xm5g7osgo2yyidi5m4muyo2vjjy53q4vjju2u55mfa
 
- This creates an alias "fun:" and configures it to use the given directory
+ This creates an alias ``fun:`` and configures it to use the given directory
- cap. Once this is done, "tahoe ls fun:" will list the contents of this
+ cap. Once this is done, "``tahoe ls fun:``" will list the contents of this
- directory. Use "tahoe add-alias tahoe DIRCAP" to set the contents of the
+ directory. Use "``tahoe add-alias tahoe DIRCAP``" to set the contents of the
- default "tahoe:" alias.
+ default ``tahoe:`` alias.
 
 ``tahoe create-alias fun``
 
@@ -283,12 +283,17 @@ Command Examples
 
  This displays a table of all configured aliases.
 
+``tahoe mkdir``
+
+ This creates a new empty unlinked directory, and prints its write-cap to
+ stdout. The new directory is not attached to anything else.
+
 ``tahoe mkdir subdir``
 
 ``tahoe mkdir /subdir``
 
- This both create a new empty directory and attaches it to your root with the
+ This creates a new empty directory and attaches it below the root directory
- name "subdir".
+ of the default ``tahoe:`` alias with the name "``subdir``".
 
 ``tahoe ls``
 
@@ -298,7 +303,7 @@ Command Examples
 
 ``tahoe ls tahoe:/``
 
- All four list the root directory of your personal virtual filesystem.
+ All four list the root directory of the default ``tahoe:`` alias.
 
 ``tahoe ls subdir``
 
@@ -314,8 +319,9 @@ Command Examples
 
  This uses the python 'webbrowser' module to cause a local web browser to
  open to the web page for the given directory. This page offers interfaces to
- add, dowlonad, rename, and delete files in the directory. If not given an
+ add, download, rename, and delete files in the directory. If no alias or
- alias or path, opens "tahoe:", the root dir of the default alias.
+ path is given, this command opens the root directory of the default
+ ``tahoe:`` alias.
 
 ``tahoe put file.txt``
 
@@ -340,8 +346,8 @@ Command Examples
 
 ``tahoe put file.txt tahoe:uploaded.txt``
 
- These upload the local file and add it to your root with the name
+ These upload the local file and add it to your ``tahoe:`` root with the name
- "uploaded.txt"
+ "``uploaded.txt``".
 
 ``tahoe put file.txt subdir/foo.txt``
 
@@ -349,24 +355,27 @@ Command Examples
 
 ``tahoe put file.txt tahoe:subdir/foo.txt``
 
+``tahoe put file.txt DIRCAP/foo.txt``
+or
 ``tahoe put file.txt DIRCAP:./foo.txt``
 
+``tahoe put file.txt DIRCAP/subdir/foo.txt``
+or
 ``tahoe put file.txt DIRCAP:./subdir/foo.txt``
 
  These upload the named file and attach them to a subdirectory of the given
- root directory, under the name "foo.txt". Note that to use a directory
+ root directory, under the name "``foo.txt``". When a directory write-cap is
- write-cap instead of an alias, you must use ":./" as a separator, rather
+ given, you can use either ``/`` or ``:./`` to separate it from the following
- than ":", to help the CLI parser figure out where the dircap ends. When the
+ path. When the source file is named "``-``", the contents are taken from stdin.
- source file is named "-", the contents are taken from stdin.
 
 ``tahoe put file.txt --mutable``
 
- Create a new mutable file, fill it with the contents of file.txt, and print
+ Create a new mutable file, fill it with the contents of ``file.txt``, and
- the new write-cap to stdout.
+ print the new write-cap to stdout.
 
 ``tahoe put file.txt MUTABLE-FILE-WRITECAP``
 
- Replace the contents of the given mutable file with the contents of file.txt
+ Replace the contents of the given mutable file with the contents of ``file.txt``
  and prints the same write-cap to stdout.
 
 ``tahoe cp file.txt tahoe:uploaded.txt``
@@ -377,8 +386,8 @@ Command Examples
 
 ``tahoe cp ./file.txt tahoe:``
 
- These upload the local file and add it to your root with the name
+ These upload the local file and add it to your ``tahoe:`` root with the name
- "uploaded.txt".
+ "``uploaded.txt``".
 
 ``tahoe cp tahoe:uploaded.txt downloaded.txt``
 
@@ -388,25 +397,25 @@ Command Examples
 
 ``tahoe cp tahoe:uploaded.txt ~/downloaded.txt``
 
- This downloads the named file from your tahoe root, and puts the result on
+ This downloads the named file from your ``tahoe:`` root, and puts the result on
  your local filesystem.
 
 ``tahoe cp tahoe:uploaded.txt fun:stuff.txt``
 
- This copies a file from your tahoe root to a different virtual directory,
+ This copies a file from your ``tahoe:`` root to a different directory, set up
- set up earlier with "tahoe add-alias fun DIRCAP".
+ earlier with "``tahoe add-alias fun DIRCAP``" or "``tahoe create-alias fun``".
 
 ``tahoe rm uploaded.txt``
 
 ``tahoe rm tahoe:uploaded.txt``
 
- This deletes a file from your tahoe root.
+ This deletes a file from your ``tahoe:`` root.
 
 ``tahoe mv uploaded.txt renamed.txt``
 
 ``tahoe mv tahoe:uploaded.txt tahoe:renamed.txt``
 
- These rename a file within your tahoe root directory.
+ These rename a file within your ``tahoe:`` root directory.
 
 ``tahoe mv uploaded.txt fun:``
 
@@ -414,17 +423,18 @@ Command Examples
 
 ``tahoe mv tahoe:uploaded.txt fun:uploaded.txt``
 
- These move a file from your tahoe root directory to the virtual directory
+ These move a file from your ``tahoe:`` root directory to the directory
- set up earlier with "tahoe add-alias fun DIRCAP"
+ set up earlier with "``tahoe add-alias fun DIRCAP``" or
+ "``tahoe create-alias fun``".
 
 ``tahoe backup ~ work:backups``
 
  This command performs a full versioned backup of every file and directory
- underneath your "~" home directory, placing an immutable timestamped
+ underneath your "``~``" home directory, placing an immutable timestamped
- snapshot in e.g. work:backups/Archives/2009-02-06_04:00:05Z/ (note that the
+ snapshot in e.g. ``work:backups/Archives/2009-02-06_04:00:05Z/`` (note that
- timestamp is in UTC, hence the "Z" suffix), and a link to the latest
+ the timestamp is in UTC, hence the "Z" suffix), and a link to the latest
  snapshot in work:backups/Latest/ . This command uses a small SQLite database
- known as the "backupdb", stored in ~/.tahoe/private/backupdb.sqlite, to
+ known as the "backupdb", stored in ``~/.tahoe/private/backupdb.sqlite``, to
  remember which local files have been backed up already, and will avoid
  uploading files that have already been backed up. It compares timestamps and
  filesizes when making this comparison. It also re-uses existing directories
@@ -432,27 +442,27 @@ Command Examples
  number of directories created.
 
  If you reconfigure your client node to switch to a different grid, you
- should delete the stale backupdb.sqlite file, to force "tahoe backup" to
+ should delete the stale backupdb.sqlite file, to force "``tahoe backup``"
- upload all files to the new grid.
+ to upload all files to the new grid.
 
 ``tahoe backup --exclude=*~ ~ work:backups``
 
  Same as above, but this time the backup process will ignore any
- filename that will end with '~'. '--exclude' will accept any standard
+ filename that will end with '~'. ``--exclude`` will accept any standard
- unix shell-style wildcards, have a look at
+ Unix shell-style wildcards, as implemented by the
- http://docs.python.org/library/fnmatch.html for a more detailed
+ `Python fnmatch module <http://docs.python.org/library/fnmatch.html>`_.
- reference.  You may give multiple '--exclude' options.  Please pay
+ You may give multiple ``--exclude`` options.  Please pay attention that
- attention that the pattern will be matched against any level of the
+ the pattern will be matched against any level of the directory tree;
- directory tree, it's still impossible to specify absolute path exclusions.
+ it's still impossible to specify absolute path exclusions.
 
 ``tahoe backup --exclude-from=/path/to/filename ~ work:backups``
 
- '--exclude-from' is similar to '--exclude', but reads exclusion
+ ``--exclude-from`` is similar to ``--exclude``, but reads exclusion
- patterns from '/path/to/filename', one per line.
+ patterns from ``/path/to/filename``, one per line.
 
 ``tahoe backup --exclude-vcs ~ work:backups``
 
- This command will ignore any known file or directory that's used by
+ This command will ignore any file or directory name known to be used by
  version control systems to store metadata. The excluded names are:
 
   * CVS
@@ -491,16 +501,16 @@ Storage Grid Maintenance
  and directory that can be reached from that point. It then emits one line to
  stdout for each object it encounters.
 
- The default behavior is to print the access cap string (like URI:CHK:.. or
+ The default behavior is to print the access cap string (like ``URI:CHK:..``
- URI:DIR2:..), followed by a space, followed by the full path name.
+ or ``URI:DIR2:..``), followed by a space, followed by the full path name.
 
- If --storage-index is added, each line will instead contain the object's
+ If ``--storage-index`` is added, each line will instead contain the object's
  storage index. This (string) value is useful to determine which share files
- (on the server) are associated with this directory tree. The --verify-cap
+ (on the server) are associated with this directory tree. The ``--verify-cap``
- and --repair-cap options are similar, but emit a verify-cap and repair-cap,
+ and ``--repair-cap`` options are similar, but emit a verify-cap and repair-cap,
- respectively. If --raw is provided instead, the output will be a
+ respectively. If ``--raw`` is provided instead, the output will be a
  JSON-encoded dictionary that includes keys for pathnames, storage index
- strings, and cap strings. The last line of the --raw output will be a JSON
+ strings, and cap strings. The last line of the ``--raw`` output will be a JSON
  encoded deep-stats dictionary.
 
 ``tahoe stats tahoe:``
@@ -513,7 +523,7 @@ Storage Grid Maintenance
 Debugging
 =========
 
-For a list of all debugging commands, use "tahoe debug".
+For a list of all debugging commands, use "``tahoe debug``".
 
 "``tahoe debug find-shares STORAGEINDEX NODEDIRS..``" will look through one or
 more storage nodes for the share files that are providing storage for the
@@ -527,22 +537,21 @@ concatenate these reports from all storage hosts and use it to look for
 anomalies.
 
 "``tahoe debug dump-share SHAREFILE``" will take the name of a single share file
-(as found by "tahoe find-shares") and print a summary of its contents to
+(as found by "``tahoe find-shares``") and print a summary of its contents to
 stdout. This includes a list of leases, summaries of the hash tree, and
 information from the UEB (URI Extension Block). For mutable file shares, it
 will describe which version (seqnum and root-hash) is being stored in this
 share.
 
-"``tahoe debug dump-cap CAP``" will take a URI (a file read-cap, or a directory
+"``tahoe debug dump-cap CAP``" will take any Tahoe-LAFS URI and unpack it
-read- or write- cap) and unpack it into separate pieces. The most useful
+into separate pieces. The most useful aspect of this command is to reveal the
-aspect of this command is to reveal the storage index for any given URI. This
+storage index for any given URI. This can be used to locate the share files
-can be used to locate the share files that are holding the encoded+encrypted
+that are holding the encoded+encrypted data for this file.
-data for this file.
 
-"``tahoe debug repl``" will launch an interactive python interpreter in which
+"``tahoe debug repl``" will launch an interactive Python interpreter in which
-the Tahoe packages and modules are available on sys.path (e.g. by using 'import
+the Tahoe-LAFS packages and modules are available on ``sys.path`` (e.g. by using
-allmydata'). This is most useful from a source tree: it simply sets the
+'``import allmydata``'). This is most useful from a source tree: it simply sets
-PYTHONPATH correctly and runs the 'python' executable.
+the PYTHONPATH correctly and runs the Python executable.
 
 "``tahoe debug corrupt-share SHAREFILE``" will flip a bit in the given
 sharefile. This can be used to test the client-side verification/repair code.