First batch of doc cleanups (#21)

* First batch of doc cleanups

* zsh{,db} -> bash{,db} and other doc fixes

* zsh{,db} -> bash{,db} and other doc fixes

* Gratuituous change to get readthe docs to reread?

Author: rocky

.readthedocs.yaml

@@ -0,0 +1,36 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#   install:
+#     - requirements: docs/requirements.txt
+#

README.md

@@ -1,6 +1,6 @@
 [![Build Status Circle](https://circleci.com/gh/rocky/bashdb.svg?&style=shield)](https://circleci.com/gh/rocky/bashdb)
 
-[![Packaging status](https://repology.org/badge/vertical-allrepos/zshdb.svg)](https://repology.org/project/zshdb/versions)
+[![Packaging status](https://repology.org/badge/vertical-allrepos/bashdb.svg)](https://repology.org/project/bashdb/versions)
 
 Here, we have a debugger for Bash 5.2 and higher.
 

command/break.sh

@@ -34,7 +34,7 @@ See also:
 "tbreak" and "continue"'
 
 _Dbg_help_add tbreak \
-'**tbreak* [*loc-spec*]
+'**tbreak** [ *location* ] [**if** *condition*]
 
 Set a one-time breakpoint at *loc-spec*.
 

command/condition.sh

@@ -1,7 +1,7 @@
 # -*- shell-script -*-
 # condition.sh - gdb-like "condition" debugger command
 #
-#   Copyright (C) 2002-2006, 2008, 2009, 2011, 2016, 2019
+#   Copyright (C) 2002-2006, 2008, 2009, 2011, 2016, 2019, 2024
 #   Rocky Bernstein rocky@gnu.org
 #
 #   This program is free software; you can redistribute it and/or
@@ -24,7 +24,7 @@ _Dbg_help_add condition \
 
 Break only if *bash-cond* is true in breakpoint number *bp_number*.
 
-*bp_number* is an integer and *cond* is an zsh expression to be evaluated whenever
+*bp_number* is an integer and *cond* is an bash expression to be evaluated whenever
 breakpoint *bp_number* is reached.
 
 Examples:

command/next.sh

@@ -24,14 +24,17 @@
 # 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.
+
+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 <rocky@gnu.org>
+#   Copyright (C) 2010, 2011, 2017, 2024
+#   Rocky Bernstein <rocky@gnu.org>
 #
 #   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 rocky@gnu.org
 #
 #   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/.gitignore

@@ -0,0 +1,3 @@
+*~
+/.python-version
+/_build

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    = bashdb
+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 bash 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>`