First batch of doc cleanups

command/next.sh

@@ -24,14 +24,19 @@
 # but the command is different.
 
 _Dbg_help_add next \
-"**next** [*count*]
+"**next** [ **+** | **-** ] [ *count* ]
 
-Single step an statement skipping functions. This is sometimes called
+Step one statement ignoring steps into function calls at this level. This is sometimes called
 'step over' or 'step through'.
 
-If *count* is given, stepping occurs that many times before
-stopping. Otherwise *count* is one. *count* an be an arithmetic
-expression.
+With an integer argument, perform ``next`` that many times. However if
+an exception occurs at this level, or we *return*, *yield* or the
+thread changes, we stop regardless of count.
+
+A suffix of ``+`` on the command or an alias to the command forces to
+move to another line, while a suffix of ``-`` does the opposite and
+disables the requiring a move to a new line. If no suffix is given,
+the debugger setting 'different-line' determines this behavior.
 
 Functions and source'd files are not traced. This is in contrast to
 **step**.

command/skip.sh

@@ -1,7 +1,8 @@
 # -*- shell-script -*-
 # gdb-like "skip" (step over) commmand.
 #
-#   Copyright (C) 2010, 2011, 2017 Rocky Bernstein <[email protected]>
+#   Copyright (C) 2010, 2011, 2017, 2024
+#   Rocky Bernstein <[email protected]>
 #
 #   This program is free software; you can redistribute it and/or
 #   modify it under the terms of the GNU General Public License as
@@ -45,7 +46,7 @@ See http://lists.gnu.org/archive/html/bug-bash/2017-04/msg00004.html
 See also:
 ---------
 
-**next** and **step**.
+**next**, **step**, and **continue**.
 "
 
 _Dbg_do_skip() {

command/step.sh

@@ -1,7 +1,7 @@
 # -*- shell-script -*-
 # step.sh - Debugger step ("step into") commmand.
 #
-#   Copyright (C) 2006, 2008, 2009, 2010, 2015
+#   Copyright (C) 2006, 2008, 2009, 2010, 2015,
 #   2024 Rocky Bernstein [email protected]
 #
 #   This program is free software; you can redistribute it and/or
@@ -27,10 +27,9 @@
 typeset -i _Dbg_set_different=0
 
 _Dbg_help_add step \
-"**step** [*count*]
-
-Single step an statement. This is sometimes called 'step into'.
+"**step** [ **+** | **-** [ *count* ]]
 
+Single step a statement. This is sometimes called 'step into'.
 
 If *count* is given, stepping occurs that many times before
 stopping. Otherwise *count* is one. *count* an be an arithmetic
@@ -44,12 +43,19 @@ into.
 
 If suffix \"-\" is added, the different line aspect of \"step+\" does not occur.
 
-With no suffix is given, the behavior is dicted by the setting of **set force**.
+With no suffix is given, the behavior is dictated by the setting of **set different**.
+
+Examples:
+---------
+
+    step        # step 1
+    step 1      # same as above
+    step 5/5+0  # same as above
 
 See also:
 ---------
 
-**next**, **skip**, and **set force**." 1
+**next**, **skip**, **continue**, and **set different**." 1
 
 
 # Step command

docs/Makefile

@@ -0,0 +1,26 @@
+# Minimal makefile for Sphinx documentation
+# We use "remake" target comments
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = zshdb
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put "help" first so that "make" without argument is like "make help".
+#: Give sphinx build help
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help docs all
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%:
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+#: build HTML documentation; Set $O can be for $SPHINXOPTS
+all docs: Makefile
+	$(MAKE) html

docs/commands.rst

@@ -0,0 +1,19 @@
+Command Reference
+*****************
+
+Following *gdb*, we classify commands into categories. Note though
+that some commands, like `quit`, and `restart`, are in different categories
+and some categories are new, like `set`, `show`, and `info`.
+
+.. toctree::
+   :maxdepth: 1
+
+   commands/breakpoints
+   commands/data
+   commands/files
+   commands/info
+   commands/running
+   commands/set
+   commands/stack
+   commands/show
+   commands/support

docs/commands/Makefile

@@ -0,0 +1,9 @@
+# Whatever it is you want to do, it should be handled by the
+# by the main (parent) Makefile. So reissue make from there.
+.PHONY: html
+
+html:
+	$(MAKE) -C .. $@
+
+%: html
+	$(MAKE) -C .. $@

docs/commands/breakpoints.rst

@@ -0,0 +1,56 @@
+Breakpoints
+===========
+
+Making the program stop at certain points
+
+A *breakpoint* can make your program stop at that point. You can set
+breakpoints with the break command and its variants. You can specify
+the place where your program should stop by file and line number or by
+function name.
+
+The debugger assigns a number to each breakpoint when you create it;
+these numbers are successive integers starting with 1. In many of the
+commands for controlling various features of breakpoints you use this
+number. Each breakpoint may be enabled or disabled; if disabled, it
+has no effect on your program until you enable it again.
+
+The debugger allows you to set any number of breakpoints at the same
+place in your program. There is nothing unusual about this because
+different breakpoints can have different conditions associated with
+them.
+
+The simplest sort of breakpoint breaks every time your program reaches
+a specified place. You can also specify a condition for a
+breakpoint. A condition is just a Boolean expression in your
+programming language. A breakpoint with a condition evaluates the
+expression each time your program reaches it, and your program stops
+only if the condition is true.
+
+This is the converse of using assertions for program validation; in
+that situation, you want to stop when the assertion is violated-that
+is, when the condition is false.
+
+Break conditions can have side effects, and may even call functions in
+your program. This can be useful, for example, to activate functions
+that log program progress, or to use your own print functions to
+format special data structures. The effects are completely predictable
+unless there is another enabled breakpoint at the same address. (In
+that case, pydb might see the other breakpoint first and stop your
+program without checking the condition of this one.) Note that
+breakpoint commands are usually more convenient and flexible than
+break conditions for the purpose of performing side effects when a
+breakpoint is reached.
+
+Break conditions can be specified when a breakpoint is set, by adding
+a comma in the arguments to the break command. They can also be
+changed at any time with the :ref:`condition <condition>` command.
+
+.. toctree::
+   :maxdepth: 1
+
+   breakpoints/break
+   breakpoints/condition
+   breakpoints/delete
+   breakpoints/disable
+   breakpoints/enable
+   breakpoints/tbreak

docs/commands/breakpoints/Makefile

@@ -0,0 +1,9 @@
+# Whatever it is you want to do, it should be handled by the
+# by the main (parent) Makefile. So reissue make from there.
+.PHONY: html
+
+html:
+	$(MAKE) -C ../.. $@
+
+%: html
+	$(MAKE) -C ../.. $@

docs/commands/breakpoints/break.rst

@@ -0,0 +1,27 @@
+.. index:: break
+.. _break:
+
+Set a Breakpoint (break)
+------------------------
+
+**break** [*loc-spec*]
+
+Set a breakpoint at loc-spec.
+
+If no location specification is given, use the current line.
+
+Multiple breakpoints at one place are permitted, and useful if conditional.
+
+Examples:
++++++++++
+
+::
+
+   break              # Break where we are current stopped at
+   break 10           # Break on line 10 of the file we are
+                      # currently stopped at
+   break /etc/profile:10   # Break on line 45 of os.path
+
+.. seealso::
+
+   :ref:`tbreak <tbreak>`, :ref:`condition <condition>`, :ref:`delete <delete>`, :ref:`disable <disable>` and :ref:`continue <continue>`.

docs/commands/breakpoints/condition.rst

@@ -0,0 +1,24 @@
+.. index:: condition
+.. _condition:
+
+Add Condition to a Breakpoint (condition)
+-----------------------------------------
+
+**condition** *bp_number* *condition*
+
+*bp_number* is a breakpoint number. *condition* is a zsh expression
+which must evaluate to *True* before the breakpoint is honored.  If
+*condition* is absent, any existing condition is removed; i.e., the
+breakpoint is made unconditional.
+
+Examples:
++++++++++
+
+::
+
+   condition 5 x > 10  # Breakpoint 5 now has condition x > 10
+   condition 5         # Remove above condition
+
+.. seealso::
+
+   :ref:`break <break>`, :ref:`tbreak <tbreak>`.

docs/commands/breakpoints/delete.rst

@@ -0,0 +1,13 @@
+.. index:: delete
+.. _delete:
+
+Remove Breakpoints (delete)
+---------------------------
+
+**delete** [*bpnumber* [*bpnumber*...]]
+
+Delete some breakpoints.
+
+Arguments are breakpoint numbers with spaces in between.  To delete
+all breakpoints, give no argument.  Without
+arguments, clear all breaks (but first ask confirmation).

docs/commands/breakpoints/disable.rst

@@ -0,0 +1,14 @@
+.. index:: disable
+.. _disable:
+
+Disable breakpoints (disable)
+-----------------------------
+
+**disable** *bpnumber* [*bpnumber* ...]
+
+Disables the breakpoints given as a space separated list of breakpoint
+numbers. See also `info break` to get a list.
+
+.. seealso::
+
+   :ref:`enable <enable>`

docs/commands/breakpoints/enable.rst

@@ -0,0 +1,14 @@
+.. index:: enable
+.. _enable:
+
+Enable Breakpoints (enable)
+---------------------------
+
+**enable** *bpnumber* [*bpnumber* ...]
+
+Enables the breakpoints given as a space separated list of breakpoint
+numbers. See also `info break` to get a list.
+
+.. seealso::
+
+   :ref:`disable <disable>`, :ref:`tbreak <tbreak>`

docs/commands/breakpoints/tbreak.rst

@@ -0,0 +1,33 @@
+.. index:: tbreak
+.. _tbreak:
+
+Set a Temporary Breakpoint (tbreak)
+-----------------------------------
+
+**tbreak** [ *location* ] [**if** *condition*]
+
+With a line number argument, set a break there in the current file.
+With a function name, set a break at first executable line of that
+function.  Without argument, set a breakpoint at current location.  If
+a second argument is `if`, subequent arguments given an expression
+which must evaluate to true before the breakpoint is honored.
+
+The location line number may be prefixed with a filename or module
+name and a colon. Files is searched for using *sys.path*, and the `.py`
+suffix may be omitted in the file name.
+
+Examples:
++++++++++
+
+::
+
+   tbreak     # Break where we are current stopped at
+   tbreak 10  # Break on line 10 of the file we are currently stopped at
+   tbreak os.path.join # Break in function os.path.join
+   tbreak os.path:45   # Break on line 45 of os.path
+   tbreak myfile.py:45 # Break on line 45 of myfile.py
+   tbreak myfile:45    # Same as above.
+
+.. seealso::
+
+   :ref:`break <break>`, :ref:`condition <condition>`, :ref:`delete <delete>`.

docs/commands/data.rst

@@ -0,0 +1,13 @@
+Data
+====
+
+Examining data.
+
+.. toctree::
+   :maxdepth: 1
+
+   data/display
+   data/eval
+   data/examine
+   data/load
+   data/undisplay

docs/commands/data/display.rst

@@ -0,0 +1,24 @@
+.. index:: display
+.. _display:
+
+Set a Display Expression (`display`)
+------------------------------------
+
+**display** [ *format* ] *expression*
+
+Print value of expression *expression* each time the program stops.
+*format* may be used before *expression* and may be one of `/c` for
+char, `/x` for hex, `/o` for octal, `/f` for float or `/s` for string.
+
+For now, display expressions are only evaluated when in the same
+code as the frame that was in effect when the display expression
+was set.  This is a departure from gdb and we may allow for more
+flexibility in the future to specify whether this should be the
+case or not.
+
+With no argument, evaluate and display all currently requested
+auto-display expressions.
+
+.. seealso::
+
+   :ref:`undisplay <undisplay>` to cancel display requests previously made.