--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/man/lispref/compile.texi	Mon Aug 13 08:45:50 2007 +0200
@@ -0,0 +1,811 @@
+@c -*-texinfo-*-
+@c This is part of the XEmacs Lisp Reference Manual.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. 
+@c See the file lispref.texi for copying conditions.
+@setfilename ../../info/compile.info
+@node Byte Compilation, Debugging, Loading, Top
+@chapter Byte Compilation
+@cindex byte-code
+@cindex compilation
+
+  XEmacs Lisp has a @dfn{compiler} that translates functions written
+in Lisp into a special representation called @dfn{byte-code} that can be
+executed more efficiently.  The compiler replaces Lisp function
+definitions with byte-code.  When a byte-coded function is called, its
+definition is evaluated by the @dfn{byte-code interpreter}.
+
+  Because the byte-compiled code is evaluated by the byte-code
+interpreter, instead of being executed directly by the machine's
+hardware (as true compiled code is), byte-code is completely
+transportable from machine to machine without recompilation.  It is not,
+however, as fast as true compiled code.
+
+  In general, any version of Emacs can run byte-compiled code produced
+by recent earlier versions of Emacs, but the reverse is not true.  In
+particular, if you compile a program with Emacs 19.29, the compiled
+code does not run in earlier versions.
+@iftex
+@xref{Docs and Compilation}.
+@end iftex
+Files compiled in versions before 19.29 may not work in 19.29 if they
+contain character constants with modifier bits, because the bits were
+renumbered in Emacs 19.29.
+
+  @xref{Compilation Errors}, for how to investigate errors occurring in
+byte compilation.
+
+@menu
+* Speed of Byte-Code::          An example of speedup from byte compilation.
+* Compilation Functions::       Byte compilation functions.
+* Docs and Compilation::        Dynamic loading of documentation strings.
+* Dynamic Loading::             Dynamic loading of individual functions.
+* Eval During Compile::  	Code to be evaluated when you compile.
+* Compiled-Function Objects::	The data type used for byte-compiled functions.
+* Disassembly::                 Disassembling byte-code; how to read byte-code.
+@end menu
+
+@node Speed of Byte-Code
+@section Performance of Byte-Compiled Code
+
+  A byte-compiled function is not as efficient as a primitive function
+written in C, but runs much faster than the version written in Lisp.
+Here is an example:
+
+@example
+@group
+(defun silly-loop (n)
+  "Return time before and after N iterations of a loop."
+  (let ((t1 (current-time-string)))
+    (while (> (setq n (1- n)) 
+              0))
+    (list t1 (current-time-string))))
+@result{} silly-loop
+@end group
+
+@group
+(silly-loop 100000)
+@result{} ("Fri Mar 18 17:25:57 1994"
+    "Fri Mar 18 17:26:28 1994")  ; @r{31 seconds}
+@end group
+
+@group
+(byte-compile 'silly-loop)
+@result{} @r{[Compiled code not shown]}
+@end group
+
+@group
+(silly-loop 100000)
+@result{} ("Fri Mar 18 17:26:52 1994"
+    "Fri Mar 18 17:26:58 1994")  ; @r{6 seconds}
+@end group
+@end example
+
+  In this example, the interpreted code required 31 seconds to run,
+whereas the byte-compiled code required 6 seconds.  These results are
+representative, but actual results will vary greatly.
+
+@node Compilation Functions
+@comment  node-name,  next,  previous,  up
+@section The Compilation Functions
+@cindex compilation functions
+
+  You can byte-compile an individual function or macro definition with
+the @code{byte-compile} function.  You can compile a whole file with
+@code{byte-compile-file}, or several files with
+@code{byte-recompile-directory} or @code{batch-byte-compile}.
+
+  When you run the byte compiler, you may get warnings in a buffer
+called @samp{*Compile-Log*}.  These report things in your program that
+suggest a problem but are not necessarily erroneous.
+
+@cindex macro compilation
+  Be careful when byte-compiling code that uses macros.  Macro calls are
+expanded when they are compiled, so the macros must already be defined
+for proper compilation.  For more details, see @ref{Compiling Macros}.
+
+  Normally, compiling a file does not evaluate the file's contents or
+load the file.  But it does execute any @code{require} calls at top
+level in the file.  One way to ensure that necessary macro definitions
+are available during compilation is to require the file that defines
+them (@pxref{Named Features}).  To avoid loading the macro definition files
+when someone @emph{runs} the compiled program, write
+@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
+During Compile}).
+
+@defun byte-compile symbol
+This function byte-compiles the function definition of @var{symbol},
+replacing the previous definition with the compiled one.  The function
+definition of @var{symbol} must be the actual code for the function;
+i.e., the compiler does not follow indirection to another symbol.
+@code{byte-compile} returns the new, compiled definition of
+@var{symbol}.
+
+  If @var{symbol}'s definition is a compiled-function object,
+@code{byte-compile} does nothing and returns @code{nil}.  Lisp records
+only one function definition for any symbol, and if that is already
+compiled, non-compiled code is not available anywhere.  So there is no
+way to ``compile the same definition again.''
+
+@example
+@group
+(defun factorial (integer)
+  "Compute factorial of INTEGER."
+  (if (= 1 integer) 1
+    (* integer (factorial (1- integer)))))
+@result{} factorial
+@end group
+
+@group
+(byte-compile 'factorial)
+     @result{}
+#<byte-code (integer)
+ "ÁU«‚Á‡ÂS!_‡"
+ [integer 1 factorial]
+ 3 "Compute factorial of INTEGER.">
+@end group
+@end example
+
+@noindent
+The result is a compiled-function object.  The string it contains is
+the actual byte-code; each character in it is an instruction or an
+operand of an instruction.  The vector contains all the constants,
+variable names and function names used by the function, except for
+certain primitives that are coded as special instructions.
+@end defun
+
+@deffn Command compile-defun &optional arg
+This command reads the defun containing point, compiles it, and
+evaluates the result.  If you use this on a defun that is actually a
+function definition, the effect is to install a compiled version of that
+function.
+
+@c XEmacs feature
+If @var{arg} is non-@code{nil}, the result is inserted in the current
+buffer after the form; otherwise, it is printed in the minibuffer.
+@end deffn
+
+@deffn Command byte-compile-file filename &optional load
+This function compiles a file of Lisp code named @var{filename} into
+a file of byte-code.  The output file's name is made by appending
+@samp{c} to the end of @var{filename}.
+
+@c XEmacs feature
+  If @code{load} is non-@code{nil}, the file is loaded after having been
+compiled.
+
+Compilation works by reading the input file one form at a time.  If it
+is a definition of a function or macro, the compiled function or macro
+definition is written out.  Other forms are batched together, then each
+batch is compiled, and written so that its compiled code will be
+executed when the file is read.  All comments are discarded when the
+input file is read.
+
+This command returns @code{t}.  When called interactively, it prompts
+for the file name.
+
+@example
+@group
+% ls -l push*
+-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
+@end group
+
+@group
+(byte-compile-file "~/emacs/push.el")
+     @result{} t
+@end group
+
+@group
+% ls -l push*
+-rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
+-rw-rw-rw-  1 lewis     638 Oct  8 20:25 push.elc
+@end group
+@end example
+@end deffn
+
+@c flag is not optional in FSF Emacs
+@deffn Command byte-recompile-directory directory &optional flag
+@cindex library compilation
+This function recompiles every @samp{.el} file in @var{directory} that
+needs recompilation.  A file needs recompilation if a @samp{.elc} file
+exists but is older than the @samp{.el} file.
+
+When a @samp{.el} file has no corresponding @samp{.elc} file, then
+@var{flag} says what to do.  If it is @code{nil}, these files are
+ignored.  If it is non-@code{nil}, the user is asked whether to compile
+each such file.
+
+The returned value of this command is unpredictable.
+@end deffn
+
+@defun batch-byte-compile
+This function runs @code{byte-compile-file} on files specified on the
+command line.  This function must be used only in a batch execution of
+Emacs, as it kills Emacs on completion.  An error in one file does not
+prevent processing of subsequent files.  (The file that gets the error
+will not, of course, produce any compiled code.)
+
+@example
+% emacs -batch -f batch-byte-compile *.el
+@end example
+@end defun
+
+@c XEmacs feature
+@defun batch-byte-recompile-directory
+  This function is similar to @code{batch-byte-compile} but runs the
+command @code{byte-recompile-directory} on the files remaining on the
+command line.
+@end defun
+
+@c XEmacs feature
+@defvar byte-recompile-directory-ignore-errors-p
+  If non-@code{nil}, this specifies that @code{byte-recompile-directory}
+will continue compiling even when an error occurs in a file.  This is
+normally @code{nil}, but is bound to @code{t} by
+@code{batch-byte-recompile-directory}.
+@end defvar
+
+@defun byte-code code-string data-vector max-stack
+@cindex byte-code interpreter
+This function actually interprets byte-code.  A byte-compiled function
+is actually defined with a body that calls @code{byte-code}.  Don't call
+this function yourself.  Only the byte compiler knows how to generate
+valid calls to this function.
+
+In newer Emacs versions (19 and up), byte-code is usually executed as
+part of a compiled-function object, and only rarely due to an explicit
+call to @code{byte-code}.
+@end defun
+
+@node Docs and Compilation
+@section Documentation Strings and Compilation
+@cindex dynamic loading of documentation
+
+  Functions and variables loaded from a byte-compiled file access their
+documentation strings dynamically from the file whenever needed.  This
+saves space within Emacs, and makes loading faster because the
+documentation strings themselves need not be processed while loading the
+file.  Actual access to the documentation strings becomes slower as a
+result, but normally not enough to bother users.
+
+  Dynamic access to documentation strings does have drawbacks:
+
+@itemize @bullet
+@item
+If you delete or move the compiled file after loading it, Emacs can no
+longer access the documentation strings for the functions and variables
+in the file.
+
+@item
+If you alter the compiled file (such as by compiling a new version),
+then further access to documentation strings in this file will give
+nonsense results.
+@end itemize
+
+  If your site installs Emacs following the usual procedures, these
+problems will never normally occur.  Installing a new version uses a new
+directory with a different name; as long as the old version remains
+installed, its files will remain unmodified in the places where they are
+expected to be.
+
+  However, if you have built Emacs yourself and use it from the
+directory where you built it, you will experience this problem
+occasionally if you edit and recompile Lisp files.  When it happens, you
+can cure the problem by reloading the file after recompiling it.
+
+  Byte-compiled files made with Emacs 19.29 will not load into older
+versions because the older versions don't support this feature.  You can
+turn off this feature by setting @code{byte-compile-dynamic-docstrings}
+to @code{nil}.  Once this is done, you can compile files that will load
+into older Emacs versions.  You can do this globally, or for one source
+file by specifying a file-local binding for the variable.  Here's one
+way to do that:
+
+@example
+-*-byte-compile-dynamic-docstrings: nil;-*-
+@end example
+
+@defvar byte-compile-dynamic-docstrings
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic loading of documentation strings.
+@end defvar
+
+@cindex @samp{#@@@var{count}}
+@cindex @samp{#$}
+  The dynamic documentation string feature writes compiled files that
+use a special Lisp reader construct, @samp{#@@@var{count}}.  This
+construct skips the next @var{count} characters.  It also uses the
+@samp{#$} construct, which stands for ``the name of this file, as a
+string.''  It is best not to use these constructs in Lisp source files.
+
+@node Dynamic Loading
+@section Dynamic Loading of Individual Functions
+
+@cindex dynamic loading of functions
+@cindex lazy loading
+  When you compile a file, you can optionally enable the @dfn{dynamic
+function loading} feature (also known as @dfn{lazy loading}).  With
+dynamic function loading, loading the file doesn't fully read the
+function definitions in the file.  Instead, each function definition
+contains a place-holder which refers to the file.  The first time each
+function is called, it reads the full definition from the file, to
+replace the place-holder.
+
+  The advantage of dynamic function loading is that loading the file
+becomes much faster.  This is a good thing for a file which contains
+many separate commands, provided that using one of them does not imply
+you will soon (or ever) use the rest.  A specialized mode which provides
+many keyboard commands often has that usage pattern: a user may invoke
+the mode, but use only a few of the commands it provides.
+
+  The dynamic loading feature has certain disadvantages:
+
+@itemize @bullet
+@item
+If you delete or move the compiled file after loading it, Emacs can no
+longer load the remaining function definitions not already loaded.
+
+@item
+If you alter the compiled file (such as by compiling a new version),
+then trying to load any function not already loaded will get nonsense
+results.
+@end itemize
+
+  If you compile a new version of the file, the best thing to do is
+immediately load the new compiled file.  That will prevent any future
+problems.
+
+  The byte compiler uses the dynamic function loading feature if the
+variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
+time.  Do not set this variable globally, since dynamic loading is
+desirable only for certain files.  Instead, enable the feature for
+specific source files with file-local variable bindings, like this:
+
+@example
+-*-byte-compile-dynamic: t;-*-
+@end example
+
+@defvar byte-compile-dynamic
+If this is non-@code{nil}, the byte compiler generates compiled files
+that are set up for dynamic function loading.
+@end defvar
+
+@defun fetch-bytecode function
+This immediately finishes loading the definition of @var{function} from
+its byte-compiled file, if it is not fully loaded already.  The argument
+@var{function} may be a compiled-function object or a function name.
+@end defun
+
+@node Eval During Compile
+@section Evaluation During Compilation
+
+  These features permit you to write code to be evaluated during
+compilation of a program.
+
+@defspec eval-and-compile body
+This form marks @var{body} to be evaluated both when you compile the
+containing code and when you run it (whether compiled or not).
+
+You can get a similar result by putting @var{body} in a separate file
+and referring to that file with @code{require}.  Using @code{require} is
+preferable if there is a substantial amount of code to be executed in
+this way.
+@end defspec
+
+@defspec eval-when-compile body
+This form marks @var{body} to be evaluated at compile time and not when
+the compiled program is loaded.  The result of evaluation by the
+compiler becomes a constant which appears in the compiled program.  When
+the program is interpreted, not compiled at all, @var{body} is evaluated
+normally.
+
+At top level, this is analogous to the Common Lisp idiom
+@code{(eval-when (compile eval) @dots{})}.  Elsewhere, the Common Lisp
+@samp{#.} reader macro (but not when interpreting) is closer to what
+@code{eval-when-compile} does.
+@end defspec
+
+@node Compiled-Function Objects
+@section Compiled-Function Objects
+@cindex compiled function
+@cindex byte-code function
+
+  Byte-compiled functions have a special data type: they are
+@dfn{compiled-function objects}.
+
+  A compiled-function object is a bit like a vector; however, the
+evaluator handles this data type specially when it appears as a function
+to be called.  The printed representation for a compiled-function
+object normally begins with @samp{#<compiled-function} and ends with
+@samp{>}.  However, if the variable @code{print-readably} is
+non-@code{nil}, the object is printed beginning with @samp{#[} and
+ending with @samp{]}.  This representation can be read directly
+by the Lisp reader, and is used in byte-compiled files (those ending
+in @samp{.elc}).
+
+  In Emacs version 18, there was no compiled-function object data type;
+compiled functions used the function @code{byte-code} to run the byte
+code.
+
+  A compiled-function object has a number of different elements.
+They are:
+
+@table @var
+@item arglist
+The list of argument symbols.
+
+@item instructions
+The string containing the byte-code instructions.
+
+@item constants
+The vector of Lisp objects referenced by the byte code.  These include
+symbols used as function names and variable names.
+
+@item stacksize
+The maximum stack size this function needs.
+
+@item doc-string
+The documentation string (if any); otherwise, @code{nil}.  The value may
+be a number or a list, in case the documentation string is stored in a
+file.  Use the function @code{documentation} to get the real
+documentation string (@pxref{Accessing Documentation}).
+
+@item interactive
+The interactive spec (if any).  This can be a string or a Lisp
+expression.  It is @code{nil} for a function that isn't interactive.
+
+@item domain
+The domain (if any).  This is only meaningful if I18N3 (message-translation)
+support was compiled into XEmacs.  This is a string defining which
+domain to find the translation for the documentation string and
+interactive prompt.  @xref{Domain Specification}.
+@end table
+
+Here's an example of a compiled-function object, in printed
+representation.  It is the definition of the command
+@code{backward-sexp}.
+
+@example
+#<compiled-function
+  (&optional arg)
+  "¬‚ÁÂ[!‡"
+  [arg 1 forward-sexp]
+  2
+  579173
+  "_p">
+@end example
+
+  The primitive way to create a compiled-function object is with
+@code{make-byte-code}:
+
+@defun make-byte-code &rest elements
+This function constructs and returns a compiled-function object
+with @var{elements} as its elements.
+
+@emph{NOTE:} Unlike all other Emacs-lisp functions, calling this with
+five arguments is @emph{not} the same as calling it with six arguments,
+the last of which is @code{nil}.  If the @var{interactive} arg is
+specified as @code{nil}, then that means that this function was defined
+with @code{(interactive)}.  If the arg is not specified, then that means
+the function is not interactive.  This is terrible behavior which is
+retained for compatibility with old @samp{.elc} files which expected
+these semantics.
+@end defun
+
+  You should not try to come up with the elements for a compiled-function
+object yourself, because if they are inconsistent, XEmacs may crash
+when you call the function.  Always leave it to the byte compiler to
+create these objects; it makes the elements consistent (we hope).
+
+  The following primitives are provided for accessing the elements of
+a compiled-function object.
+
+@defun compiled-function-arglist function
+This function returns the argument list of compiled-function object
+@var{function}.
+@end defun
+
+@defun compiled-function-instructions function
+This function returns a string describing the byte-code instructions
+of compiled-function object @var{function}.
+@end defun
+
+@defun compiled-function-constants function
+This function returns the vector of Lisp objects referenced by
+compiled-function object @var{function}.
+@end defun
+
+@defun compiled-function-stack-size function
+This function returns the maximum stack size needed by compiled-function
+object @var{function}.
+@end defun
+
+@defun compiled-function-doc-string function
+This function returns the doc string of compiled-function object
+@var{function}, if available.
+@end defun
+
+@defun compiled-function-interactive function
+This function returns the interactive spec of compiled-function object
+@var{function}, if any.  The return value is @code{nil} or a two-element
+list, the first element of which is the symbol @code{interactive} and
+the second element is the interactive spec (a string or Lisp form).
+@end defun
+
+@defun compiled-function-domain function
+This function returns the domain of compiled-function object
+@var{function}, if any.  The result will be a string or @code{nil}.
+@xref{Domain Specification}.
+@end defun
+
+@node Disassembly
+@section Disassembled Byte-Code
+@cindex disassembled byte-code
+
+  People do not write byte-code; that job is left to the byte compiler.
+But we provide a disassembler to satisfy a cat-like curiosity.  The
+disassembler converts the byte-compiled code into humanly readable
+form.
+
+  The byte-code interpreter is implemented as a simple stack machine.
+It pushes values onto a stack of its own, then pops them off to use them
+in calculations whose results are themselves pushed back on the stack.
+When a byte-code function returns, it pops a value off the stack and
+returns it as the value of the function.
+
+  In addition to the stack, byte-code functions can use, bind, and set
+ordinary Lisp variables, by transferring values between variables and
+the stack.
+
+@deffn Command disassemble object &optional stream
+This function prints the disassembled code for @var{object}.  If
+@var{stream} is supplied, then output goes there.  Otherwise, the
+disassembled code is printed to the stream @code{standard-output}.  The
+argument @var{object} can be a function name or a lambda expression.
+
+As a special exception, if this function is used interactively,
+it outputs to a buffer named @samp{*Disassemble*}.
+@end deffn
+
+  Here are two examples of using the @code{disassemble} function.  We
+have added explanatory comments to help you relate the byte-code to the
+Lisp source; these do not appear in the output of @code{disassemble}.
+These examples show unoptimized byte-code.  Nowadays byte-code is
+usually optimized, but we did not want to rewrite these examples, since
+they still serve their purpose.
+
+@example
+@group
+(defun factorial (integer)
+  "Compute factorial of an integer."
+  (if (= 1 integer) 1
+    (* integer (factorial (1- integer)))))
+     @result{} factorial
+@end group
+
+@group
+(factorial 4)
+     @result{} 24
+@end group
+
+@group
+(disassemble 'factorial)
+     @print{} byte-code for factorial:
+ doc: Compute factorial of an integer.
+ args: (integer)
+@end group
+
+@group
+0   constant 1              ; @r{Push 1 onto stack.}
+
+1   varref   integer        ; @r{Get value of @code{integer}} 
+                            ;   @r{from the environment}
+                            ;   @r{and push the value}
+                            ;   @r{onto the stack.}
+@end group
+
+@group
+2   eqlsign                 ; @r{Pop top two values off stack,}
+                            ;   @r{compare them,}
+                            ;   @r{and push result onto stack.}
+@end group
+
+@group
+3   goto-if-nil 10          ; @r{Pop and test top of stack;}
+                            ;   @r{if @code{nil}, go to 10,}
+                            ;   @r{else continue.}
+@end group
+
+@group
+6   constant 1              ; @r{Push 1 onto top of stack.}
+
+7   goto     17             ; @r{Go to 17 (in this case, 1 will be}
+                            ;   @r{returned by the function).}
+@end group
+
+@group
+10  constant *              ; @r{Push symbol @code{*} onto stack.}
+
+11  varref   integer        ; @r{Push value of @code{integer} onto stack.}
+@end group
+
+@group
+12  constant factorial      ; @r{Push @code{factorial} onto stack.}
+
+13  varref   integer        ; @r{Push value of @code{integer} onto stack.}
+
+14  sub1                    ; @r{Pop @code{integer}, decrement value,}
+                            ;   @r{push new value onto stack.}
+@end group
+
+@group
+                            ; @r{Stack now contains:}
+                            ;   @minus{} @r{decremented value of @code{integer}}
+                            ;   @minus{} @r{@code{factorial}} 
+                            ;   @minus{} @r{value of @code{integer}}
+                            ;   @minus{} @r{@code{*}}
+@end group
+
+@group
+15  call     1              ; @r{Call function @code{factorial} using}
+                            ;   @r{the first (i.e., the top) element}
+                            ;   @r{of the stack as the argument;}
+                            ;   @r{push returned value onto stack.}
+@end group
+
+@group
+                            ; @r{Stack now contains:}
+                            ;   @minus{} @r{result of recursive}
+                            ;        @r{call to @code{factorial}}
+                            ;   @minus{} @r{value of @code{integer}}
+                            ;   @minus{} @r{@code{*}}
+@end group
+
+@group
+16  call     2              ; @r{Using the first two}
+                            ;   @r{(i.e., the top two)}
+                            ;   @r{elements of the stack}
+                            ;   @r{as arguments,}
+                            ;   @r{call the function @code{*},}
+                            ;   @r{pushing the result onto the stack.}
+@end group
+
+@group
+17  return                  ; @r{Return the top element}
+                            ;   @r{of the stack.}
+     @result{} nil
+@end group
+@end example
+
+The @code{silly-loop} function is somewhat more complex:
+
+@example
+@group
+(defun silly-loop (n)
+  "Return time before and after N iterations of a loop."
+  (let ((t1 (current-time-string)))
+    (while (> (setq n (1- n)) 
+              0))
+    (list t1 (current-time-string))))
+     @result{} silly-loop
+@end group
+
+@group
+(disassemble 'silly-loop)
+     @print{} byte-code for silly-loop:
+ doc: Return time before and after N iterations of a loop.
+ args: (n)
+
+0   constant current-time-string  ; @r{Push}
+                                  ;   @r{@code{current-time-string}}
+                                  ;   @r{onto top of stack.}
+@end group
+
+@group
+1   call     0              ; @r{Call @code{current-time-string}}
+                            ;   @r{ with no argument,}
+                            ;   @r{ pushing result onto stack.}
+@end group
+
+@group
+2   varbind  t1             ; @r{Pop stack and bind @code{t1}}
+                            ;   @r{to popped value.}
+@end group
+
+@group
+3   varref   n              ; @r{Get value of @code{n} from}
+                            ;   @r{the environment and push}
+                            ;   @r{the value onto the stack.}
+@end group
+
+@group
+4   sub1                    ; @r{Subtract 1 from top of stack.}
+@end group
+
+@group
+5   dup                     ; @r{Duplicate the top of the stack;}
+                            ;   @r{i.e., copy the top of}
+                            ;   @r{the stack and push the}
+                            ;   @r{copy onto the stack.}
+@end group
+
+@group
+6   varset   n              ; @r{Pop the top of the stack,}
+                            ;   @r{and bind @code{n} to the value.}
+
+                            ; @r{In effect, the sequence @code{dup varset}}
+                            ;   @r{copies the top of the stack}
+                            ;   @r{into the value of @code{n}}
+                            ;   @r{without popping it.}
+@end group
+
+@group
+7   constant 0              ; @r{Push 0 onto stack.}
+@end group
+
+@group
+8   gtr                     ; @r{Pop top two values off stack,}
+                            ;   @r{test if @var{n} is greater than 0}
+                            ;   @r{and push result onto stack.}
+@end group
+
+@group
+9   goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
+                            ;   @r{(this exits the while loop).}
+                            ;   @r{else pop top of stack}
+                            ;   @r{and continue}
+@end group
+
+@group
+12  constant nil            ; @r{Push @code{nil} onto stack}
+                            ;   @r{(this is the body of the loop).}
+@end group
+
+@group
+13  discard                 ; @r{Discard result of the body}
+                            ;   @r{of the loop (a while loop}
+                            ;   @r{is always evaluated for}
+                            ;   @r{its side effects).}
+@end group
+
+@group
+14  goto     3              ; @r{Jump back to beginning}
+                            ;   @r{of while loop.}
+@end group
+
+@group
+17  discard                 ; @r{Discard result of while loop}
+                            ;   @r{by popping top of stack.}
+                            ;   @r{This result is the value @code{nil} that}
+                            ;   @r{was not popped by the goto at 9.}
+@end group
+
+@group
+18  varref   t1             ; @r{Push value of @code{t1} onto stack.}
+@end group
+
+@group
+19  constant current-time-string  ; @r{Push} 
+                                  ;   @r{@code{current-time-string}}
+                                  ;   @r{onto top of stack.}
+@end group
+
+@group
+20  call     0              ; @r{Call @code{current-time-string} again.}
+@end group
+
+@group
+21  list2                   ; @r{Pop top two elements off stack,}
+                            ;   @r{create a list of them,}
+                            ;   @r{and push list onto stack.}
+@end group
+
+@group
+22  unbind   1              ; @r{Unbind @code{t1} in local environment.}
+
+23  return                  ; @r{Return value of the top of stack.}
+
+     @result{} nil
+@end group
+@end example
+
+