more work on api-procedures.texi

* doc/ref/api-procedures.texi (Compiled Procedures): Stub out these docs
  some more, taking some commented-out docs from vm.texi.

* doc/ref/vm.texi: Move docs ^.

diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi
index fd3a8d1..75c0a72 100644 (file)
--- a/doc/ref/api-procedures.texi
+++ b/doc/ref/api-procedures.texi
@@ -145,7 +145,86 @@ to being, though procedures can be compiled at runtime as well.
 @xref{Read/Load/Eval/Compile}, for more information on runtime
 compilation.
 
-here document things from (system vm program)
+Compiled procedures, also known as @dfn{programs}, respond all
+procedures that operate on procedures. In addition, there are a few
+more accessors for low-level details on programs. Most people won't
+need these, but it's good to have them documented.
+
+You'll have to include the appropriate module first, though:
+
+@example
+(use-modules (system vm program))
+@end example
+
+@deffn {Scheme Procedure} program-bytecode program
+@deffnx {C Function} scm_program_bytecode (program)
+Returns the object code associated with this program.
+@end deffn
+
+@deffn {Scheme Procedure} program-arity program
+@deffnx {C Function} scm_program_arity (program)
+Returns a representation of the ``arity'' of a program.
+@end deffn
+
+@deffn {Scheme Procedure} arity:nargs arity
+@deffnx {Scheme Procedure} arity:nrest arity
+@deffnx {Scheme Procedure} arity:nlocs arity
+@deffnx {Scheme Procedure} arity:nexts arity
+Accessors for arity objects, as returned by @code{program-arity}.
+
+@code{nargs} is the number of arguments to the procedure, and
+@code{nrest} will be non-zero if the last argument is a rest argument.
+
+The other two accessors determine the number of local and external
+(heap-allocated) variables that this procedure will need to have
+allocated.
+@end deffn
+
+@deffn {Scheme Procedure} program-bindings program
+@deffnx {Scheme Procedure} make-binding name extp index start end
+@deffnx {Scheme Procedure} binding:name binding
+@deffnx {Scheme Procedure} binding:extp binding
+@deffnx {Scheme Procedure} binding:index binding
+@deffnx {Scheme Procedure} binding:start binding
+@deffnx {Scheme Procedure} binding:end binding
+Bindings annotations for programs, along with their accessors.
+
+Bindings declare names and liveness extents for block-local variables.
+The best way to see what these are is to play around with them at a
+REPL. The only tricky bit is that @var{extp} is a boolean, declaring
+whether the binding is heap-allocated or not. @xref{VM Concepts}, for
+more information.
+
+Note that bindings information are stored in a program as part of its
+metadata thunk, so including them in the generated object code does
+not impose a runtime performance penalty.
+@end deffn
+
+@deffn {Scheme Procedure} program-sources program
+@deffnx {Scheme Procedure} source:addr source
+@deffnx {Scheme Procedure} source:line source
+@deffnx {Scheme Procedure} source:column source
+@deffnx {Scheme Procedure} source:file source
+Source location annotations for programs, along with their accessors.
+
+Blah...
+@end deffn
+
+@deffn {Scheme Procedure} program-properties program
+@deffnx {Scheme Procedure} program-property program
+@deffnx {Scheme Procedure} program-documentation program
+@deffnx {Scheme Procedure} program-name program
+@deffnx {Scheme Procedure} program-external program
+@deffnx {Scheme Procedure} program-external-set! program
+@deffnx {Scheme Procedure} program-meta program
+@deffnx {Scheme Procedure} program-bytecode program
+@deffnx {Scheme Procedure} program-bytecode program
+@deffnx {Scheme Procedure} program? program
+@deffnx {Scheme Procedure} program-objects program
+@deffnx {Scheme Procedure} program-module program
+@deffnx {Scheme Procedure} program-base program
+Undocumented...
+@end deffn
 
 @node Optional Arguments
 @subsection Optional Arguments

diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi
index 1075ae7..5048edb 100644 (file)
--- a/doc/ref/vm.texi
+++ b/doc/ref/vm.texi
@@ -335,34 +335,6 @@ name to that variable, so it just marks it as being a ``closure
 variable''. Finally we see the reference to @code{b}, then a tail call
 (@code{goto/args}) with three arguments.
 
-@c @example
-@c (use-modules (system vm program))
-@c @end example
-
-@c @deffn {Scheme Procedure} program-bytecode program
-@c @deffnx {C Function} scm_program_bytecode (program)
-@c Returns the object code associated with this program.
-@c @end deffn
-
-@c @deffn {Scheme Procedure} program-arity program
-@c @deffnx {C Function} scm_program_arity (program)
-@c Returns a representation of the ``arity'' of a program.
-@c @end deffn
-
-@c @deffn {Scheme Procedure} arity:nargs arity
-@c @deffnx {Scheme Procedure} arity:nrest arity
-@c @deffnx {Scheme Procedure} arity:nlocs arity
-@c @deffnx {Scheme Procedure} arity:nexts arity
-@c Accessors for arity objects, as returned by @code{program-arity}.
-
-@c @code{nargs} is the number of arguments to the procedure, and
-@c @code{nrest} will be non-zero if the last argument is a rest argument.
-
-@c The other two accessors determine the number of local and external
-@c (heap-allocated) variables that this procedure will need to have
-@c allocated.
-@c @end deffn
-
 @node Instruction Set
 @subsection Instruction Set