Plan for guile-debugging integration

[Neil Jerram]

Hi all,

I'm going to start merging my guile-debugging work into Guile CVS
(HEAD), and thought it would be good to say briefly how I plan to do
this.

guile-debugging consists of some Scheme code, some Elisp code, and
some documentation, so the points of interest are really just where
the code should go, how the documentation will be integrated, and what
testing there will be.

1. Scheme code

The Scheme files fall into two categories: those which implement new
debugging infrastructure (steps.scm, trace.scm, traps.scm, trc.scm,
breakpoints.scm) and those which implement the Emacs interface
(gds-client.scm, gds-server.scm).

By default I'd add these under (ice-9) - but perhaps we should
consider something else?  Please let me know if you have ideas.

2. Elisp code

These files (gds-scheme.el, gds-server.el, gds.el) implement the Emacs
interface.  Guile CVS already has an "emacs" subdir, so I think it
makes sense to add these here.

3. Documentation

This is the interesting part, in my view.  As part of this merge I
want to achieve three things.

- Complete the documentation of existing debugging infrastructure:
  stacks, frames, (ice-9 debug) and the command line debugger.

- Merge the documentation of new debugging stuff and of the Emacs
  interface from guile-debugging into the Guile reference manual.

- Remedy the lack of basic documentation on using the Guile REPL.

I should also say that I plan to document my Guile/Emacs interface as
the "official" or recommended one.  If you are concerned about that,
please let me know asap.

Proposed doc changes in more detail...

* New "Using Guile interactively" node, under "Programming in Scheme"

Basic intro to using the REPL; readline; value history; what happens
when an error is hit; backtrace; command line debugger (== existing
"Interactive Debugger" node + "Additional Commands" from
guile-debugging.texi).

* New "Using Guile in Emacs" node, under "Programming in Scheme"

Everything about the "GDS" Guile/Emacs interface.  (From the "GDS"
node in guile-debugging.texi.)

* Changes to the "Debugging Features" node

"Debug Last Error" and "Interactive Debugger" move to underneath the
"Using Guile interactively" node.

"Intro to Breakpoints" stays here but is renamed "Breakpoints".
"Tracing" stays here.  The details under these nodes are updated to
reflect latest guile-debugging.

New "Examples" node, == the "Example" node in guile-debugging.texi.

* Changes to the "Debugging Infrastructure", under "API Reference".

Incorporate reference material from the "Traps", "Breakpoints" and
Appendix A nodes in guile-debugging.texi.

Complete existing documentation on stacks and frames.

Make sure overall structure is coherent.

4. Testing

I can add debugging infrastructure tests using our usual test
framework, so I'll do that.

I don't know how to regressibly test any of the Emacs interface stuff
though.  Please let me know if you have ideas.

5. Anything else?

If there are other facets of the integration that I have overlooked,
please feel free to point them out.

Regards,
     Neil