https://github.com/Trepan-Debuggers/bashdb/pull/49

Add a more expansive debugger call example

docs/entry-exit.rst

@@ -6,9 +6,9 @@ Entering the Zsh Debugger
 
 
 Invoking the Debugger Initially
-====================================
+===============================
 
-The simplest way to debug your program is to run `zshdb`. Give
+The simplest way to debug your program is to run ``zshdb``. Give
 the name of your program and its options and any debugger options:
 
 .. code:: console
@@ -35,7 +35,7 @@ the name of your program and its options and any debugger options:
 
         $ zshdb /etc/profile
 
-For help on `zshdb` or options, use the ``--help`` option.
+For help on ``zshdb`` or options, use the ``--help`` option.
 
 .. code:: console
 
@@ -52,35 +52,46 @@ For help on `zshdb` 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 ``zshdb``.
 
-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
-`zshdb/dbg-trace.sh` from where wherever it appears on your filesystem.
+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
+``zshdb/dbg-trace.sh`` from where wherever it appears on your filesystem.
 This needs to be done only once.
 
-After that you call `_Dbg_debugger`.
+After that you call ``_Dbg_debugger``.
 
 Here is an Example:
 
 .. code:: console
 
-    source path-to-zshdb/zshdb/dbg-trace.sh
-    # work, work, work.
-    # ... some zsh 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
-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.
+Until the first call to ``_Dbg_debugger``, there is no debugger overhead.
 
-Note that `_Dbg_debugger` causes the statement *after* the call to be stopped at.
+Note that ``_Dbg_debugger`` causes the statement *after* the call to be stopped.