Feedback please! More detailed documentation for Graphical Debugger

I have written a new reference doc for the graphical debugger with more detail and tailored a bit more to newer users (like myself) that don’t have a lot of the assumed background. I eventually want to replace the existing one.

Love any and all feedback including things folks think should be included or that I got wrong!

P.S. Love any information on how the Exceptions window works and I’ll include that as well.

2 Likes

Thanks Eric. I just read the entire post. I think it is pretty clear (but I’m not the good target audience). I found only one factual mistake: the command line editor is not (always) GNU readline based. In fact, the default one is based on BSD libedit for two reasons (1) license compatibility and (2). You can have multiple editline editors in the same process. This is used by the libssh package. You may consider adding this to the debugger facilities. This library allows using ssh to get a new thread with a Prolog toplevel to interact with the program. This is notably interesting for embedded Prolog systems or when Prolog runs as a daemon without console access.

Otherwise the only problem I found is the dark purple explanation text on the black background. Might be my eyes (which are bad) or my monitor calibration, but I can only read it with a bit of guessing :frowning:

That is quite an important tool as it allows debugging on errors whether or not they are caught. The way it works is as follows:

  • If an exception happens, Prolog calls a hook (prolog_exception_hook/4)
  • This hook matches the exception listed in the GUI top-to-bottom. If a row matches, the action depends on the two tick boxes.
  • The exact transaction is added as a new row. The rows may be reordered using the up/down buttons or deleted using the cross button. This can be used to trap on exactly the error you are interested in.

So, the normal behavior is to open this tool and select Trace always for error(_,_) and continue running. Normally using l (leap) to run in debug mode and get the best error context. If this is too slow or uses too much memory, n (nodebug) is also fine.

If errors happen that you are not interested in, make sure they are above the ones you are interested in and untick Trace always

Note that by default only error(,) exceptions are trapped. Other errors are collected and can be placed in the right order and ticked to trap them.

Oh, caught means there is a matching catch/3 higher up on the stack.

I’m sure you can explain it more clearly :slight_smile:

2 Likes

I actually got that from the existing docs :slight_smile: . Removed now.

I’ll add a note about this.

Here’s another try in green. Let me know if this doesn’t fix it:

OK, I’ll post when I get this section written up. Thanks!

2 Likes