From c843903259250c00059a3c92804694d87e4987cc Mon Sep 17 00:00:00 2001 From: rocky Date: Mon, 11 Nov 2024 15:10:47 -0500 Subject: [PATCH] tweak option descriptions more --- docs/index.rst | 1 - docs/manpages.rst | 8 -------- docs/manpages/trepan3k.rst | 41 +++++++++++++++++++++++--------------- docs/options.rst | 24 ++++++++++++---------- trepan/options.py | 4 ++-- 5 files changed, 41 insertions(+), 37 deletions(-) delete mode 100644 docs/manpages.rst diff --git a/docs/index.rst b/docs/index.rst index 48f15fbc..7ac9154f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -30,7 +30,6 @@ An Emacs interface is available via realgud_. entry-exit syntax commands - manpages Indices and tables ================== diff --git a/docs/manpages.rst b/docs/manpages.rst deleted file mode 100644 index f72261ca..00000000 --- a/docs/manpages.rst +++ /dev/null @@ -1,8 +0,0 @@ -Manual Pages -************ - -.. toctree:: - :maxdepth: 1 - - manpages/trepan3k - manpages/trepan3kc diff --git a/docs/manpages/trepan3k.rst b/docs/manpages/trepan3k.rst index a88c1253..45a7b9b7 100644 --- a/docs/manpages/trepan3k.rst +++ b/docs/manpages/trepan3k.rst @@ -34,13 +34,13 @@ Trepan3k Options Show file path basenames, e.g. for regression tests. :\--client: - Connect to an existing debugger process started with the --server option. See also options -H and -P. + 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*. +:-x *FILE*, \--command\= *debugger-command-path*: + Execute commands from *debugger-command-path*. -:\--cd= *DIR*: - Change current directory to *DIR*. +:\--cd= *directory-path*: + Change current directory to *directory-path*. :\--confirm: Confirm potentially dangerous operations. @@ -54,11 +54,11 @@ Trepan3k Options :\--different: Consecutive debugger stops should have different positions. -:\--edit-mode=EDIT_MODE: +:\--edit-mode={emacs|vi}: 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 `;;` +:\-e *debugger-commands-string*, \--exec\= *debugger-commands-string*: + list of debugger commands to execute. Separate the commands with `;;`. :\--highlight={light|dark|plain}: Use syntax and terminal highlight output. "plain" is no highlight. @@ -72,23 +72,32 @@ Trepan3k Options :-n, \--nx: Don't execute commands found in any initialization files. -:-o *FILE*, \--output= *FILE*: - Write debugger's output (stdout) to *FILE*. +:-o *path*, \--output= *path*: + Write debugger's output (stdout) to *path*. -:-p *PORT*,\ --port= *PORT*: - Use TCP port number *NUMBER* for out-of-process connections. +:-p *port-number*,\ --port= *port-number*: + Use TCP/IP port number *port-number* for out-of-process connections. :--server: - Out-of-process server connection mode. + Out-of-process or "headless" server-connection mode. :--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* +:-t *target*, \--target= *target*: + Specify a target to connect to. Arguments should be of form, *protocol*:*address*. :\--from_ipython: - Called from inside 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. diff --git a/docs/options.rst b/docs/options.rst index 856ddfc8..99ad49ac 100644 --- a/docs/options.rst +++ b/docs/options.rst @@ -63,10 +63,13 @@ will be run under the debugger. 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. + Set debugger-input edit mode, either "emacs" or "vi", used by GNU + readline, lineedit, or toolkit-prompt. The default is + "emacs". Inside the debugger, you can toggle the edit mode using ESC + CTRL-j (same as you would in ``gdb``). -``-e`` *debugger-command-string*, ``--exec=`` *debugger-command-string* - List of debugger commands to execute. Separate the commands with ``;;`` +``-e`` *debugger-commands-string*, ``--exec=`` *debugger-commands-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. @@ -97,21 +100,21 @@ will be run under the debugger. Write debugger's output (stdout) to FILE ``-P`` *port-number*, ``--port=`` *port-number* - Use TCP port number *port-number* for out-of-process connections. + Use TCP/IP port number *port-number* for out-of-process connections. ``--server`` - Out-of-process server connection mode + Out-of-process or "headless" 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 + Set to watch for signal handler changes. ``-t`` *target*, ``--target=`` *target* - Specify a target to connect to. Arguments should be of form, 'protocol address'. + Specify a target to connect to. Arguments should be of form, *protocol*:*address*. -`--from_ipython`` Called from inside ipython +`--from_ipython`` Called from inside ipython. ``--annotate=`` *annotate-number* Use annotations to work inside GNU Emacs. @@ -120,10 +123,11 @@ Set output to pygments style; "none" uses 8-color rather than 256-color terminal Try using the Python prompt_toolkit module. ``--no-prompt-toolkit`` - Do not use prompt_toolkit + Do not use prompt_toolkit. ``--`` - 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 to be debugged has. diff --git a/trepan/options.py b/trepan/options.py index d556034d..c0d9d0aa 100644 --- a/trepan/options.py +++ b/trepan/options.py @@ -270,7 +270,7 @@ def process_options(pkg_version: str, sys_argv: str, option_list=None): "--server", dest="server", action="store_true", - help="Out-of-process server connection mode.", + help='Out-of-process or "headless" server-connection mode.', ) optparser.add_option( @@ -340,7 +340,7 @@ def process_options(pkg_version: str, sys_argv: str, option_list=None): dest="use_prompt_toolkit", action="store_false", default=True, - help="Do not use prompt_toolkit", + help="Do not use prompt_toolkit.", ) # Set up to stop on the first non-option because that's the name