Go over documentation...

Add a more expansive explicit debugger call example.

Author: rocky

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,35 +52,58 @@ 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 then is to 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.
+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
+        if [ "${PS1-}" ]; then
+          # 15 lines omitted
+        fi
 
-    _Dbg_debugger
-    # start debugging here
+        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`` a function call, it can be nested inside some sort of
+Since ``_Dbg_debugger`` is a function call, it can be nested inside some sort of
 conditional statement allowing one to be very precise about the
 conditions you want to debug under. And until first call to ``_Dbg_debugger``,
 there is no debugger overhead.
 
 Note that ``_Dbg_debugger`` causes the statement *after* the call to be stopped at.
+
+The file name ``/usr/share/bashdb/bashdb-trace`` may need to be
+adjusted based on the location ``bashdb`` was installed. Here, on
+my Ubuntu GNU/Linux system it was installed in ``/usr/share/bashdb``.
+
+Again, there is no overhead or knowledge of the debugger before the
+first source command to ``bashdb-trace``.

docs/manpage.rst

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