improved description and man page

documenting well ahead of implementation now

1 files changed, 46 insertions, 18 deletions

diff --git a/debug-me.1 b/debug-me.1
index ee12326..6b332aa 100644
--- a/debug-me.1
+++ b/debug-me.1
@@ -5,48 +5,76 @@ debug-me \- secure remote debugging
 .SH SYNOPSIS
 .B debug-me [options]
 .SH DESCRIPTION
-.I debug-me
-`debug-me` lets a developer access your computer remotely, to debug a problem,
-avoiding a tedious back-and-forth by email. When you start `debug-me`, it
-starts a shell, and generates an URL which you can give to the developer
-(or developers) to connect them to the session.
+Debugging a problem over email is slow, tedious, and hard. The developer
+needs to see the your problem to understand it. Debug-me aims to make
+debugging fast, fun, and easy, by letting the developer access your
+computer remotely, so they can immediately see and interact with the
+problem. Making your problem their problem gets it fixed fast.
 .PP
-It's not normally a good idea to let someone run commands in a shell on
-your computer. To make this as safe as possible, debug-me uses the
-GPG web of trust. Everything the developer sends to debug-me is signed
-with their GPG key, in a way that produces a GPG signed proof of what the
-developer saw, and what they did in the debug-me session.
-If the developer does something Evil, you have the neccessary proof
-to adjust their reputation.
+A debug-me session is logged and signed with the developer's Gnupg 
+key, producing a chain of evidence of what they saw and what they did. 
+So the developer's good reputation is leveraged to make debug-me secure.
 .PP
-.SH OPTIONS
+When you start debug-me without any options, it will connect to a debug-me
+server, and print out an url that you can give to the developer to get
+them connected to you. Then debug-me will show you their Gnupg key and who
+has signed it. If the developer has a good reputation, you can proceed
+to let them type into your console in a debug-me session. Once the
+session is done, the debug-me server will email you the signed
+evidence of what the developer did in the session.
 .PP
+It's a good idea to watch the debug-me session. The developer should be
+running their buggy program in different ways, perhaps running a debugger,
+or looking at configuration files. They should *not* be looking at your
+personal files without asking you first in the debug-me chat window.
+They should not be downloading or installing other software. If you see
+them do anything you don't expect, press Control-S immediately, which
+will prevent them from doing anything else. You can also press
+Control-Backslash to immediately end the debug-me session.
+.PP
+If the developer did do something bad, you'd have proof that they cannot
+be trusted, which you can share with the world. Knowing that is the case
+will keep most developers honest.
+.SH USER OPTIONS
 .IP "-- cmd opts"
 Normally debug-me will run your login shell. To run some other command,
 pass the command and any options after "--".
-.PP
 .IP "--gpg-opt=option"
 debug-me runs gpg to verify the GPG key of a developer. To pass options to
 gpg, use --gpg-opt with the option to pass. For example:
 --gpg-opt=--keyserver=pgpkeys.mit.edu
 This can be done multiple times.
+.IP "--control"
+debug-me uses a separate window from the one displaying the debug-me
+session to control the session. This control window is where debug-me will
+show you the Gnupg keys of developers who connect and let you decide if
+they should access the session. You can also chat with the developer
+in the control window during the session.
+.IP
+Normally, the control window will be opened when debug-me starts,
+by running a terminal emulator (xterm or gnome-terminal, etc).
+If debug-me is not being run in a graphical environment, that won't work,
+and you'll need to open another shell and run "debug-me --control" to see it.
+.SH DEVELOPER OPTIONS
 .IP "--debug url"
 Connect to a debug-me session on the specified url. The developer runs
 debug-me with this option to see and interact with the user's bug.
+.IP "--watch url"
+Connect to a debug-me session on the specified url and display what
+happens in the session. Your keystrokes will not be sent to the session.
+.SH LOG FILE OPTIONS
 .IP "--download url"
 Download a debug-me log file from the specified url. Note that if the
 debug-me session is still in progress, this will continue downloading
-until the session ends. The proof chain in the log file is verified
+until the session ends. The signature chain in the log file is verified
 as it is downloaded, but developer gpg signatures are not verified.
 .IP "--replay logfile"
 Replay a debug-me log file with realistic pauses.
-.IP "--watch url"
-Connect to a debug-me session on the specified url and display what
-happens in the session. Your keystrokes will not be sent to the session.
 .IP "--graphviz logfile"
 Uses graphviz to generate a visualization of a debug-me log file.
 .IP "--show-hashes"
 Include hashes in the graphviz visualization.
+.SH SERVER OPTIONS
 .IP "--server logdir"
 Run a debug-me server, logging to the specified directory.
 .IP "--port N"