command:help: add `repo` and `server` topics.

1 files changed, 60 insertions, 1 deletions

diff --git a/libbe/command/help.py b/libbe/command/help.py
index 869a35a..e655105 100644
--- a/libbe/command/help.py
+++ b/libbe/command/help.py
@@ -24,7 +24,66 @@ import libbe
 import libbe.command
 import libbe.command.util
 
-TOPICS = {}
+
+TOPICS = {
+    'repo': """A BE repository containing child bugdirs
+
+BE repositories are stored in an abstract `Storage` instance, which
+may or may not be versioned.  If you're using BE to track bugs in your
+local software, you'll probably be using an on-disk storage based on
+the VCS you use to version the storage.  See `be help init` for
+details about automatic VCS-detection.
+
+While most users will be using local storage, BE also supports remote
+storage servers.  This allows projects to publish their local
+repository in a way that's directly accessible to remote users.  The
+remote users can then use a local BE client to interact with the
+remote repository, without having to create a local copy of the
+repository.  The remote server will be running something like:
+
+    $ be serve-storage --host 123.123.123.123 --port 54321
+
+And the local client can run:
+
+    $ be --repo http://123.123.123.123:54321 list
+
+or whichever command they like.        
+
+Because the storage server serves repositories at the `Storage` level,
+it can be inefficient.  For example, `be list` will have to transfer
+the data for all the bugs in a repository over the wire.  The storage
+server can also be harder to lock down, because users with write
+access can potentially store data that cannot be parsed by BE.  For a
+more efficient server, see `be serve-commands`.
+""",
+##
+    'server': """A server for remote BE command execution
+
+The usual way for a user to interact with a BE bug tracker for a
+particular project is to clone the project repository.  They can then
+use their local BE client to browse the repository and make changes,
+before pushing their changes back upstream.  For the average user
+seeking to file a bug or comment, this can be too much work.  One way
+to simplify the process is to use a storage server (see `be help
+repo`), but this is not always ideal.  A more robust approach is to
+use a command server.
+
+The remote server will be running something like:
+
+    $ be serve-commands --host 123.123.123.123 --port 54321
+
+And the local client can run:
+
+    $ be --server http://123.123.123.123:54321 list
+
+or whichever command they like.  The command line arguments are parsed
+locally, and then POSTed to the command server, where the command is
+executed.  The output of the command is returned to the client for
+display.  This requires much less traffic over the wire than running
+the same command via a storage server.
+""",
+        }
+
 
 class Help (libbe.command.Command):
     """Print help for given command or topic