Go over documentation... (#49)

Add a more expansive explicit debugger call example.

doc/bashdb.texi

@@ -68,7 +68,7 @@ This is the @value{EDITION} Edition, @value{UPDATED},
 of @cite{Debugging with BASHDB: the @sc{gnu} Source-Level Debugger}
 for BASH
 
-Copyright (C) 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011
+Copyright (C) 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2011, 2024
 Rocky Bernstein for the Free Software Foundation.
 
 Permission is granted to copy, distribute and/or modify this document
@@ -838,6 +838,76 @@ script.
 Options for the @emph{bashdb} front-end are shown in the
 following list.
 
+@node Calling the debugger from inside a running bash script
+@subsection Calling the debugger from inside a shell script
+
+Running bash scripts when the debugger has been started can slow down
+your program. In most programs this is not a big problem. However, in
+large bash script this slowdown can be very noticable. Autogenerated
+@code{configure} script fall in to this category.
+
+Instead of invoking @code{bashdb} from the outset, or have having
+@code{bash} the same, you can instead modify your program to make a
+call to the debugger at a point inside your program.
+
+This way, your code runs full speed, and the debugger is not even
+present, until the point where you wan to start debuggingere.
+
+Here is how you do this. Consider this script adapted from @code{/etc/profile}
+on Ubuntu GNU/Linux systems:
+
+@smallexample
+@cartouche
+# /etc/profile: system-wide .profile file for the Bourne shell (sh(1))
+# and Bourne compatible shells (bash(1), ksh(1), ash(1), ...).
+
+if [ "$PS1" ]; then
+  # 15 lines omitted
+fi
+
+if [ -d /etc/profile.d ]; then
+  for i in /etc/profile.d/*.sh; do
+    if [ -r $i ]; then
+      if [[ $i == "/etc/profile.d/bash_completion.sh"; then
+        # Load in debugger
+        . /usr/share/bashdb/bashdb-trace -q
+        # Call debugger
+        _Dbg_debugger
+      fi
+      . $i
+    fi
+  done
+  unset i
+fi
+@end cartouche
+@end smallexample
+
+The lines:
+
+@smallexample
+@cartouche
+        # Load in debugger
+        . /usr/share/bashdb/bashdb-trace -q
+        # Call debugger
+        _Dbg_debugger
+      . $i
+@end cartouche
+@end smallexample
+
+Have been added. The line @code{. /usr/share/bashdb/bashdb-trace -q}
+pulls in the debugger code using bash's ``source'' command. After
+that, an explicit call to the debbugger is made. Here, it is done to
+be able to debug the bash completion code in
+@code{/etc/profile.d/bash_completion.sh} if that exists in the
+filesystem.
+
+The file name @code{/usr/share/bashdb/bashdb-trace} may need to be
+adjusted based on the location @code{bashdb} was installed. Here, it
+was installed in @code{/usr/share/bashdb}.
+
+Again, there is no overhead or knowledge of the debugger before the
+source command.
+
 @menu
 * Options for the bashdb script::   Options you can pass in starting bashdb
 @end menu

docs/commands/running/continue.rst

@@ -2,7 +2,7 @@
 .. _continue:
 
 Continue Program Execution (``continue``)
----------------------------------------
+------------------------------------------
 
 **continue** [ *loc* | **-*** ]
 

docs/commands/set/different.rst

@@ -2,7 +2,7 @@
 .. _set_different:
 
 Consecutive Stops on Different File/Line Positions) (``set different``)
----------------------------------------------------------------------
+-----------------------------------------------------------------------
 
 **set different** [ **on** | **off** ]
 

docs/entry-exit.rst

@@ -1,12 +1,12 @@
 Entering the Bash Debugger
-****************************
+**************************
 
 .. toctree::
 .. contents::
 
 
 Invoking the Debugger Initially
-====================================
+===============================
 
 The simplest way to debug your program is to run ``bashdb``. Give
 the name of your program and its options and any debugger options:
@@ -52,31 +52,46 @@ For help on `bashdb` or options, use the ``--help`` option.
 
 
 Calling the debugger from your program
-===========================================
+======================================
+
+Sometimes it is not possible to invoke the program you want debugged
+from the ``bashdb`` or from ``bash --debugger``.
 
-Sometimes it is not feasible to invoke the program from the debugger.
 Although the debugger tries to set things up to make it look like your
-program is called, sometimes the differences matter. Also, the debugger
-adds overhead and slows down your program.
+program is called, sometimes the differences matter. Also, once the debugger
+is loaded this can slows in parts that you do not want to debug.
 
-Another possibility is adding statements into your program to call
-the debugger at the spot in the program you want. To do this, you source
-``bashdb/dbg-trace.sh`` from where wherever it appears on your filesystem.
-This needs to be done only once.
+So instead, you can add statements into your program to call the
+debugger at the spot in the program you want. To do this, you source
+``bashdb/dbg-trace.sh`` from where wherever it appears on your
+filesystem.  This needs to be done only once.
 
 After that, you call ``_Dbg_debugger``.
 
-Here is an example:
+Consider the example of the previous section, but you to debug
+``/etc/profile.d/bash_completion.sh`` and skip over the other default
+profile scripts at high speed. Here is how you might do this:
 
 .. code:: console
 
-    source path-to-bashdb/bashdb/dbg-trace.sh
-    # work, work, work.
-    # ... some bash code
-
-    _Dbg_debugger
-    # start debugging here
+        if [ "${PS1-}" ]; then
+          # 15 lines omitted
+        fi
 
+        if [ -d /etc/profile.d ]; then
+          for i in /etc/profile.d/*.sh; do
+            if [ -r $i ]; then
+              if [[ $i == "/etc/profile.d/bash_completion.sh"; then
+                # Load in debugger
+                . /usr/share/bashdb/bashdb-trace -q
+                # Call debugger
+                _Dbg_debugger
+              fi
+              . $i
+           fi
+          done
+         unset i
+        fi
 
 Since `_Dbg_debugger``is a function call, it can be nested inside some 
 conditional statement allowing one to be precise about the

docs/manpage.rst

@@ -4,7 +4,7 @@
 .. contents::
 
 bashdb command
-#############
+##############
 
 Synopsis
 --------