%
% $Id: quick-intro.tex,v 1.7 1993/10/08 07:16:42 pk Exp $
%

%
% psd -- a portable debugger, version 1.1
%
% Quick intro to psd.
%
% $Log: quick-intro.tex,v $
% Revision 1.7  1993/10/08  07:16:42  pk
% Typo fixes. Documented psd-mode-hook.
%
% Revision 1.6  1993/10/07  10:36:52  pk
% Removed style option mya4.
%
% Revision 1.5  1993/09/27  11:13:53  pk
% Documented setting breakpoints by name.
%
% Revision 1.4  1993/09/24  07:57:35  pk
% Changed version number to 1.1.
%
% Revision 1.3  1993/09/23  10:49:13  pk
% Documented clearing of breakpoints.
%
% Revision 1.2  1993/05/18  11:37:19  pk
% Typo fix.
%
%

\documentstyle{article}
\begin{document}
\bibliographystyle{plain}
\newcommand{\scheme}[1]{{\tt #1}}

\author{Pertti Kellom\"aki, {\tt pk@cs.tut.fi}\\ 
\small Tampere University of Technology \\
\small Software Systems Lab \\
\small Finland}
\title{Psd for the Impatient \\ \small for version 1.1}
\maketitle

\section{Introduction}
\label{sec:intro}

This is a quick introduction to psd, the Portabe Scheme Debugger.  It
assumes, that psd is already installed in your system. It also assumes
that you are using GNU Emacs, because psd needs it for displaying
source code.

\section{How to Debug a Procedure?}

Write your Scheme program as usual.  Start up an inferior Scheme
session with the command {\tt M-x run-scheme}. If the mode line of the
{\tt *scheme*} buffer says ``Inferior Scheme Psd: run'', then psd is
already ready for use. If not, you will need to give the command {\tt
M-x psd-mode} in the Scheme buffer.  To debug a procedure:

\begin{enumerate}
\item
Move the cursor on top of the procedure you want to debug.

\item
Type {\tt C-u ESC C-x}.
The procedure has now been instrumented, and you can place breakpoints
within it.

\item
Put a breakpoint inside the procedure. Move the cursor to the line
where you want to stop the execution and give the command {\tt C-x
SPC}. You can also set breakpoints by giving the name of a procedure
where you want a breakpoint. Use the command {\tt C-c b} for that.

\item
Run your program. When execution reaches a line with a breakpoint, the
debugger is invoked and you can examine and change variable bindings
etc.

\item
Once you have located and fixed the bug, simply load the corrected
definition. 
\end{enumerate}

\section{Debugger Commands}

These are commands that you can give when the program has been stopped
to a breakpoint, and the prompt says \verb|psd>|.

\begin{description}
\item[val {\it sym}] 
  gives the value of {\it sym} in the current scope.

\item[set!\ {\it sym} {\it val}] 
  sets the value of {\it sym} to {\it val} in the current scope.

\item[c]
  clears all breakpoints on current line

\item[g]
  continues evaluation until the next breakpoint

\item[w]
  shows the current context as file name and a list of procedure names. For
  example, if the context is {\tt "/tmp/killme.scm:(encode
  encode-symbol)"}, it  means, that the you are in file {\tt
  /tmp/killme.scm}, inside a procedure called {\tt encode-symbol}, which
  is inside the procedure {\tt encode}.

\item[s] 
  steps one step in the evaluation process. Each time an expression is
  about to be evaluated, psd displays it and
  waits for a command. When an expression has been evaluated, psd
  displays the result and waits for a command.

\item[n] 
  continues evaluation until evaluation reaches a different line

\item[r {\it expr}] 
  evaluates {\it expr} and returns its value as the return value of the
  current expression

\end{description}

A list is taken to be a procedure call that is to be evaluated. All
the essential procedures in R4RS are visible to the evaluator. Any
other command displays a list of available commands.

If the debugger does not seem to be doing the right things, try the
Emacs command {\tt M-x psd-reset}, which will clear all the breakpoints
and reset the runtime system.

\section{Command Summary}

This is a short list of the available commands. The Emacs commands are:

\bigskip
\begin{tabular}{ll}
\tt C-c b	&	psd-break\cr
\tt C-c d       &       psd-debug-file \cr
\tt C-c e       &       scheme-or-psd-send-definition \cr
\tt C-c C-e     &       scheme-or-psd-send-definition-and-go \cr
\tt C-x SPC     &       psd-set-breakpoint \cr
\tt ESC C-x     &       scheme-or-psd-send-definition \cr
\tt M-x psd-reset &     clear all breakpoints and reset the psd runtime \cr
\end{tabular}
\bigskip

\noindent
The debugger commands are:

\bigskip
\begin{tabular}{ll}
\tt val {\it sym}       &   give the value of {\it sym} \cr
\tt set! {\it sym val}  &   set the value of {\it sym} to {\it val} \cr
\tt c             &   remove breakpoints on this line \cr
\tt g             &   run until the next breakpoint \cr
\tt w             &   give the current context \cr
\tt s             &   step one step in the evaluation process \cr
\tt n             &   run until evaluation reaches another line \cr
\tt r {\it expr}        &   return {\it expr} as the value of current expression \cr
\end{tabular}

\bigskip
\noindent
A list is taken to be a procedure call to be evaluated. It can also be
a {\tt set!}\ form.


\section{Useful Things for Your {\tt .emacs}}

If you want psd to be loaded automagically
when you start up a Scheme session, put the expression
\begin{verbatim}
  (setq inferior-scheme-mode-hook 
        (cons '(lambda () (psd-mode 1))
              inferior-scheme-mode-hook))
\end{verbatim}
in your {\tt .emacs} file, or with Emacs 19, put instead
\begin{verbatim}
  (add-hook 'inferior-scheme-mode-hook 
            (function (lambda () (psd-mode 1))))
\end{verbatim}

There is also a hook variable {\tt psd-mode-hook} that you can use for
customizing psd mode, for example to change key bindings.

\end{document}