Re: Debugger output: where to look for its explanation?

[Nicolas Richard]

Marcin Borkowski <mbork@wmi.amu.edu.pl> writes:

> Hi all,
>
> so I got this as a *Backtrace*:
>
> --8<---------------cut here---------------start------------->8---
> Debugger entered--Lisp error: (scan-error "Containing expression ends 
> prematurely" 2959 2959)
>   scan-sexps(2980 -3)
>   forward-sexp(-3)
>   backward-sexp(3)
>   (let ((beg-string (nth 8 (syntax-ppss))) (current-line 
> (line-number-at-pos))) (goto-char beg-string) (backward-sexp 3) (if (and 
> (member (symbol-at-point) symbols-with-docstrings) (looking-back "^(")) 
> (progn (goto-char beg-string) (forward-sexp) (or (> (line-number-at-pos) 
> current-line) (is-current-line-comment-only-p)))))
>   (if (and (eq major-mode (quote emacs-lisp-mode)) (nth 3 (syntax-ppss))) 
> (let ((beg-string (nth 8 (syntax-ppss))) (current-line (line-number-at-pos))) 
> (goto-char beg-string) (backward-sexp 3) (if (and (member (symbol-at-point) 
> symbols-with-docstrings) (looking-back "^(")) (progn (goto-char beg-string) 
> (forward-sexp) (or (> (line-number-at-pos) current-line) 
> (is-current-line-comment-only-p))))))
>   (save-excursion (skip-syntax-forward "\"-") (if (and (eq major-mode (quote 
> emacs-lisp-mode)) (nth 3 (syntax-ppss))) (let ((beg-string (nth 8 
> (syntax-ppss))) (current-line (line-number-at-pos))) (goto-char beg-string) 
> (backward-sexp 3) (if (and (member (symbol-at-point) symbols-with-docstrings) 
> (looking-back "^(")) (progn (goto-char beg-string) (forward-sexp) (or (> 
> (line-number-at-pos) current-line) (is-current-line-comment-only-p)))))))
>   is-current-line-docstring-p()
>   eval((is-current-line-docstring-p) nil)
>   eval-expression((is-current-line-docstring-p) nil)
>   funcall-interactively(eval-expression (is-current-line-docstring-p) nil)
>   call-interactively(eval-expression nil nil)
>   command-execute(eval-expression)
> --8<---------------cut here---------------end--------------->8---

The following descriptions is from my experience, not from the source,
but I'm fairly confident it is right (modulo me not being able to
express myself correctly) :

- The first line is a special one: it shows you which error
  was thrown. Look into the source code, it happens in scan_lists (a C
  function) :

  xsignal3 (Qscan_error, build_string ("Containing expression ends
  prematurely"), make_number (last_good), make_number (from));

  This also tells you the meaning of the numbers.

- Each line below that one is "something" that was evaluated by emacs,
  with the latest at the top (second line). A line that begins with a
  symbol means a function call, and if it begins with an opening paren
  it's evaluation of a form.

- Most lines are of the "function call" kind when you run byte-compiled
  code. When the code was evalled from the source file, you get to see
  more of the "evaluated form" kind (they represent the steps
  between function calls).

- In each "function call" kind, you see the name of the function and the
  value of its arguments.

- In the "evaluated form" kind of line, you can see precisely which form
  was called, which allows you to follow the execution path. E.g. above
  is-current-line-docstring-p, you see a (save-excursion ...) form which
  corresponds to the definition of that function. The line above that
  one is an (if ...), precisely the one that's in the save-excursion.
  etc.
  
Btw that buffer is more than just a backtrace : you're in a debugger
where you can e.g. eval things in the context (with `e'). See C-h m as
usual.

HTH,

Nicolas.