Add command-option section...

Also make a pass over docs

Author: rocky

docs/entry-exit.rst

@@ -255,7 +255,7 @@ and call the debugger on signal *USR1*:
           signal.signal(signal.SIGUSR1, signal_handler)
           # Go about your business...
 
-However, if you have entered the debugger either by running intially or
+However, if you have entered the debugger either by running initially or
 previously via a debug() call, trepan has already set up such default
 handlers for many of the popular signals, like *SIGINT*. To see what
 *trepan3k* has installed use the ``info signals`` command:
@@ -272,7 +272,7 @@ handlers for many of the popular signals, like *SIGINT*. To see what
         SIGSYS        Yes     Yes     No      No      Bad system call
         ...
 
-Commonly occuring signals like *CHILD* and unmaskable signals like
+Commonly occurring signals like *CHILD* and unmaskable signals like
 *KILL* are not intercepted.
 
 Set up an exception handler allow remote connections
@@ -372,7 +372,7 @@ example it might look like this:
       $
 
 
-By default, the file `$HOME/.config/trepanpy/profile/profile.py` is
-loaded, and that a file exists `trepan3k` starts up. To change this
+By default, the file ``$HOME/.config/trepan3k/profile/profile.py`` is
+loaded, and that a file exists ``trepan3k`` starts up. To change this
 default behavior and *not* have the default profile loaded, use the
-option `-n`, or `--nx` in the `trepan3k` invocation.
+option ``-n``, or ``--nx`` in the ``trepan3k`` invocation.

docs/index.rst

@@ -26,6 +26,7 @@ An Emacs interface is available via realgud_.
 
    features
    install
+   options
    entry-exit
    syntax
    commands

docs/manpages/Makefile

@@ -3,77 +3,86 @@
 trepan3k (Python3 debugger)
 ###########################
 
-Synopsis
---------
+Trepan3k Synopsis
+-----------------
 
 **trepan3k** [ *debugger-options* ] [ \-- ] [ *python-script* [ *script-options* ...]]
 
 
-Description
------------
+Trepan3k Description
+---------------------
 
 Run the Python3 trepan debugger from the outset.
 
 
-Options
--------
+Trepan3k Options
+----------------
+
+:\--version:
+   show program's version number and exit
 
 :-h, \--help:
    Show the help message and exit
 
-:-x, \--trace:
+:-X, \--trace:
    Show lines before executing them.
 
 :-F, \--fntrace:
    Show functions before executing them.
 
 :\--basename:
-   Filenames strip off basename, (e.g. for regression tests)
+   Show file path basenames, e.g. for regression tests.
 
 :\--client:
-   Connect to an existing debugger process started with the `--server` option
+   Connect to an existing debugger process started with the --server option. See also options -H and -P.
 
 :-x *FILE*, \--command\= *FILE*:
-   Execute commands from *FILE*
+   Execute commands from *FILE*.
 
 :\--cd= *DIR*:
-   Change current directory to *DIR*
+   Change current directory to *DIR*.
 
-:\-confirm:
-   Confirm potentially dangerous operations
+:\--confirm:
+   Confirm potentially dangerous operations.
+
+:\--no-confirm:
+   Do not confirm potentially dangerous operations.
 
 :\--dbg_trepan:
-   Debug the debugger
+   Allow debugging the debugger.
 
 :\--different:
-   Consecutive stops should have different positions
+   Consecutive debugger stops should have different positions.
+
+:\--edit-mode=EDIT_MODE:
+   Set debugger-input edit mode, either "emacs" or "vi".
 
 :-e *EXECUTE-CMDS*, \--exec= *EXECUTE-CMDS*:
    list of debugger commands to execute. Separate the commands with `;;`
 
 :\--highlight={light|dark|plain}:
-   Use syntax and terminal highlight output. "plain" is no highlight
+   Use syntax and terminal highlight output. "plain" is no highlight.
 
 :\--private:
-   Don't register this as a global debugger
+   Don't register this as a global debugger.
 
 :\--post-mortem:
-   Enter debugger on an uncaught (fatal) exception
+   Enter debugger on an uncaught (fatal) exception.
 
 :-n, \--nx:
-   Don't execute commands found in any initialization files
+   Don't execute commands found in any initialization files.
 
 :-o *FILE*, \--output= *FILE*:
-   Write debugger's output (stdout) to *FILE*
+   Write debugger's output (stdout) to *FILE*.
 
 :-p *PORT*,\ --port= *PORT*:
    Use TCP port number *NUMBER* for out-of-process connections.
 
 :--server:
-   Out-of-process server connection mode
+   Out-of-process server connection mode.
 
 :--sigcheck:
-   Set to watch for signal handler changes
+   Set to watch for signal handler changes.
 
 :-t *TARGET*, \--target= *TARGET*:
    Specify a target to connect to. Arguments should be of form, *protocol*:*address*
@@ -82,7 +91,7 @@ Options
    Called from inside ipython
 
 :\--:
-   Use this to separate debugger options from any options your Python script has
+   Use this to separate debugger options from any options your Python script has.
 
 
 See also

docs/manpages/trepan3k.rst

@@ -0,0 +1,151 @@
+Command-line Options
+====================
+
+The abbreviated forms are shown below with ``-`` and long forms are shown
+with  ``--``  to  reflect  how  they  are  shown  in  ``--help``.  However, ``trepan3k``,
+and ``trepan3kc`` recognizes all of the following conventions for most options:
+
+* ``--`` *option* ``=`` *value*
+* ``--`` *option* *value*
+* ``-`` *option* ``=`` *value*
+* ``-`` *option* *value*
+* ``--`` *o* ``=`` *value*
+* ``--`` *o* *value*
+* ``-`` *o* ``=`` *value*
+* ``-`` *o* *value*
+
+``trepan3k``
+------------
+
+``trepan3k`` invokes the debugger. Unless options ``--client`` or
+``--server`` is used, the debugger runs entirely in the debugged process.
+
+Although you can enter this debugger without a program to be debugged,
+if there is a filename argument given, it indicates the program that
+will be run under the debugger.
+
+
+``--version``
+   Show trepan3k's version number and exit.
+
+``-h``, ``--help``
+   Show a help message which includes these options and exit.
+
+``-X``, ``--trace``
+  Show lines before executing them. This option also sets ``--batch``.
+
+``-F``, ``--fntrace``
+  Show functions before executing them.
+
+``--basename``
+  In reporting filename, show only the basename. This is useful, for example,
+  in regression tests
+
+``--client``
+  Connect to an existing debugger process started with the ``--server`` option. See also options ``H`` and ``P``
+
+``-x`` *debugger-command-path*, ``--command=`` *debugger-command-path*
+  Execute commands from *debugger-command-path*.
+
+``--cd=`` *directory-path*
+  Change current directory to *directory-path*.
+
+``--confirm``
+  Confirm potentially dangerous operations.
+
+``--no-confirm``
+  Do not confirm potentially dangerous operations.
+
+``--dbg_trepan``
+  Allow debugging the debugger.
+
+``--different``
+  Consecutive debugger stops should have different positions.
+
+``--edit-mode=`` { ``emacs`` | ``vi`` }
+  Set debugger-input edit mode, either "emacs" or "vi", used by GNU readline, lineedit, or toolkit-prompt.
+
+``-e`` *debugger-command-string*, ``--exec=`` *debugger-command-string*
+  List of debugger commands to execute. Separate the commands with ``;;``
+
+``-H`` *IP-or-hostname*, ``--host=`` *IP-or-hostname*
+  Connect to *IP* or hostname. Only valid if ``--client`` option is given.
+
+``--highlight=``{``light`` | ``dark``| ``plain``}
+  Use syntax and terminal highlight output. The value ``plain`` indicates no highlighting
+
+``--private``
+  Don't register this as a global debugger
+
+``--main``
+  First stop should be in ``__main__``
+
+``--no-main``
+  First stop should not be in ``__main__``.
+
+``--post-mortem``
+  Enter debugger on an uncaught (fatal) exception
+
+``--no-post-mortem``
+  Don't enter debugger on an uncaught (fatal) exception
+
+
+``-n``, ``--nx``
+  Don't execute commands found in any initialization files.
+
+``-o`` *path*, ``--output=`` *path*
+   Write debugger's output (stdout) to FILE
+
+``-P`` *port-number*, ``--port=`` *port-number*
+  Use TCP port number *port-number* for out-of-process connections.
+
+``--server``
+   Out-of-process server connection mode
+
+``--style=`` *pygments-style*
+Set output to pygments style; "none" uses 8-color rather than 256-color terminal
+
+``--sigcheck``
+  Set to watch for signal handler changes
+
+``-t`` *target*, ``--target=`` *target*
+  Specify a target to connect to. Arguments should be of form, 'protocol address'.
+
+`--from_ipython`` Called from inside ipython
+
+``--annotate=`` *annotate-number*
+  Use annotations to work inside GNU Emacs.
+
+``--prompt-toolkit``
+  Try using the Python prompt_toolkit module.
+
+``--no-prompt-toolkit``
+   Do not use prompt_toolkit
+
+``--``
+   Use this to separate debugger options from any options your Python script has.
+
+
+
+``trepan3kc``
+-------------
+
+``trepan3kc`` can be used to connect to an out-of-process or remote process which is in remote-debug TCP/IP mode.
+
+Most of the options below are the same as in the ``trepan3k`` counterpart when the ``--client`` option is given.
+
+
+``--version``
+   Show trepan3k's version number and exit.
+
+``-h``, ``--help``
+   Show a help message which includes these options and exit.
+
+``-H`` *IP-or-hostname*, ``--host=`` *IP-or-hostname*
+  Connect to *IP* or hostname. Only valid if ``--client`` option is given.
+
+``-P`` *port-number*, ``--port=`` *port-number*
+  Use TCP port number *port-number* for out-of-process connections.
+
+``--pid=`` *pid*
+  Use process-id *pid* to get FIFO names for out-of-process connections.

docs/options.rst

@@ -4,8 +4,8 @@
 Syntax for Address Ranges
 =========================
 
-Address ranges are used in the `disassemble` command. It is like a
-range but we allow addresses. An add
+Address ranges are used in the :ref:`disassemble <disassemble>` command. It is like a
+range, but we allow addresses.
 
 An address range is in one of the following forms:
 
@@ -16,15 +16,17 @@ An address range is in one of the following forms:
     , last         # ending line only
 
 
-A *location* is described elsewhere. *first* and *last* can also be
-linespecs but they also may be a number or address (bytecode
-offset). And finally *last* can be an (line number) offset.
+See :ref:` location <location>` for a full description of a location.
+
+*first* and *last* can also be line specifications (:ref:`linespec
+<linespec>`), but they also may be a number or address
+(bytecode offset). And finally *last* can be an (line number) offset.
 
 A number is just a decimal number. An offset is a number prefaced with "+" and
 indicates the number to increment the line number found in *first*.
 
-Examples
---------
+Address-Range Examples
+----------------------
 
 ::
 
@@ -35,4 +37,4 @@ Examples
 
 .. seealso::
 
- :ref:`help syntax location <syntax_location>`
+ :ref:`location <syntax_location>`, :ref:`linespec <linespec>`

docs/syntax/arange.rst

@@ -5,13 +5,13 @@ Debugger Command Syntax
 
 Command names and arguments are separated with spaces like POSIX shell
 syntax. Parenthesis around the arguments and commas between them are
-not used. If the first non-blank character of a line starts with `#`,
+not used. If the first non-blank character of a line starts with ``#``,
 the command is ignored.
 
-Commands are split at whereever `;;` appears. This process disregards
+Commands are split at wherever ``;;`` appears. This process disregards
 any quotes or other symbols that have meaning in Python. The strings
 after the leading command string are put back on a command queue, and
-there should be white space around ';;'.
+there should be white space around ``;;``.
 
 Within a single command, tokens are then white-space split. Again,
 this process disregards quotes or symbols that have meaning in Python.
@@ -38,7 +38,7 @@ are dispatched to that command.
 
 4. If after all of the above, we still don't find a command, the line
 may be evaluated as a Python statement in the current context of the
-program at the point it is stoppped. However this is done only if
+program at the point it is stopped. However, this is done only if
 "auto evaluation" is on.  It is on by default.
 
 If :ref:`auto eval <set_autoeval>` is not set on, or if running the