klisp

an open source interpreter for the Kernel Programming Language.
git clone http://git.hanabi.in/repos/klisp.git
Log | Files | Refs | README
commit 534684f548d62afad16bdedc32e70562efcbf730
parent d92f9144bab42b51cb266bc06931de67d92cb412
Author: Andres Navarro <canavarro82@gmail.com>
Date:   Wed, 25 May 2011 22:07:53 -0300

Added some content to the manual (intro)

Diffstat:

Amanual/html/A-Sample-Applicative-Description.html | 79+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Acknowledgements.html | 51+++++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Caveats.html | 57+++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Conventions.html | 51+++++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Error-Messages.html | 50++++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Evaluation-Notation.html | 55+++++++++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Format-of-Descriptions.html | 47+++++++++++++++++++++++++++++++++++++++++++++++


Mmanual/html/Introduction.html | 48+++++++++++++++++++++++++++++++++---------------


Amanual/html/Kernel-History.html | 64++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Printing-Notation.html | 49+++++++++++++++++++++++++++++++++++++++++++++++++


Amanual/html/Some-Terms.html | 50++++++++++++++++++++++++++++++++++++++++++++++++++


Mmanual/klisp.info | 260++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++---


Mmanual/src/intro.texi | 266+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++--


Mmanual/src/klisp.texi | 8++++----


14 files changed, 1103 insertions(+), 32 deletions(-)

diff --git a/manual/html/A-Sample-Applicative-Description.html b/manual/html/A-Sample-Applicative-Description.html
@@ -0,0 +1,79 @@
+<html lang="en">
+<head>
+<title>A Sample Applicative Description - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Format-of-Descriptions.html#Format-of-Descriptions" title="Format of Descriptions">
+<link rel="prev" href="Format-of-Descriptions.html#Format-of-Descriptions" title="Format of Descriptions">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="A-Sample-Applicative-Description"></a>
+<p>
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Format-of-Descriptions.html#Format-of-Descriptions">Format of Descriptions</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Format-of-Descriptions.html#Format-of-Descriptions">Format of Descriptions</a>
+<hr>
+</div>
+
+<h5 class="subsubsection">1.3.5.1 A Sample Applicative Description</h5>
+
+<p><a name="index-applicative-descriptions-8"></a><a name="index-operative-descriptions-9"></a><a name="index-object-descriptions-10"></a>
+  In an applicative description, the name of the applicative being described
+appears first. It is followed on the same line by a list of arguments. 
+The names used for the arguments are also used in the body of the
+description.
+
+   <p>Here is a description of an imaginary applicative <code>foo</code>:
+
+<div class="defun">
+&mdash; Applicative: <b>(</b><var>foo integer1 integer2 . rest</var>)<var><a name="index-g_t_0028-11"></a></var><br>
+<blockquote><p>  The applicative <code>foo</code> subtracts <var>integer1</var> from <var>integer2</var>,
+then adds all the rest of the arguments to the result.
+
+     <pre class="example">          (foo 1 5 3 9)
+               &rArr; 16
+</pre>
+        <p>More generally,
+
+     <pre class="example">          (foo <var>w</var> <var>x</var> <var>y</var>...)
+          ==
+          (+ (- <var>x</var> <var>w</var>) <var>y</var>...)
+</pre>
+        </blockquote></div>
+
+   <p>Any parameter whose name contains the name of a type (e.g.,
+<var>integer</var>, <var>integer1</var> or <var>continuation</var>) is expected to be of that
+type. A plural of a type (such as <var>numbers</var>) often means a list of
+objects of that type. Parameters named <var>object</var> may be of any
+type. 
+<!-- TODO add xref types of objects -->
+(XXX Types of Lisp Object XXX, for a list of Kernel object types.) 
+Parameters with other sorts of names are
+discussed specifically in the description of the combiner. In some
+sections, features common to parameters of several combiners are
+described at the beginning.
+
+<!-- TODO xref to ptree -->
+<!-- TODO clean this up a little -->
+   <p>Operative descriptions have the same format, but the word
+`Applicative' is  replaced by `Operative', and `Argument' is replaced
+by `Operand'. Also Operatives always have an environment parameter
+(that can be #ignore or a symbol).
+
+   </body></html>
+
diff --git a/manual/html/Acknowledgements.html b/manual/html/Acknowledgements.html
@@ -0,0 +1,51 @@
+<html lang="en">
+<head>
+<title>Acknowledgements - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Introduction.html#Introduction" title="Introduction">
+<link rel="prev" href="Conventions.html#Conventions" title="Conventions">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Acknowledgements"></a>
+<p>
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Conventions.html#Conventions">Conventions</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introduction</a>
+<hr>
+</div>
+
+<h3 class="section">1.4 Acknowledgements</h3>
+
+<p>This manual was written by Andres Navarro.
+
+   <p>The structure and some text for this introductory section were
+borrowed from the Elisp Manual by the Free Sofware Foundation. This
+manual also borrows freely from both the Kernel Report and the Scheme
+Reports.
+
+<!-- appendices -->
+<!-- TODO -->
+<!-- @include index.texi -->
+<!-- Print the tables of contents -->
+<!-- FOR some reason this ends up in the last node instead of the general... -->
+<!-- TODO @summarycontents -->
+<!-- TODO @contents -->
+<!-- That's all -->
+</body></html>
+
diff --git a/manual/html/Caveats.html b/manual/html/Caveats.html
@@ -0,0 +1,57 @@
+<html lang="en">
+<head>
+<title>Caveats - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Introduction.html#Introduction" title="Introduction">
+<link rel="prev" href="Introduction.html#Introduction" title="Introduction">
+<link rel="next" href="Kernel-History.html#Kernel-History" title="Kernel History">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Caveats"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Kernel-History.html#Kernel-History">Kernel History</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Introduction.html#Introduction">Introduction</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introduction</a>
+<hr>
+</div>
+
+<h3 class="section">1.1 Caveats</h3>
+
+<p>This is the first draft of this manual. It will be incomplete for
+some time. It will also evolve, together with klisp and the Kernel
+Programming Language, both of which, right now, are in a quite fluid
+state.
+
+<!-- this is below, in history -->
+   <p>The main reference on Kernel is the preliminary report:
+<cite>Revised(-1) Report on the Kernel Programming Language</cite>. Some
+sections of the report are still incomplete, so both klisp and this
+manual will use specifications from other languages in these sections,
+trying to follow the Kernel spirit. These instances will be documented
+throughout the manual.
+
+   <p>Please mail comments and corrections to
+<a href="mailto:canavarro82@gmail.com">canavarro82@gmail.com</a>.
+
+<p class="noindent">
+<pre class="display">      &ndash;Andres Navarro
+</pre>
+   </body></html>
+
diff --git a/manual/html/Conventions.html b/manual/html/Conventions.html
@@ -0,0 +1,51 @@
+<html lang="en">
+<head>
+<title>Conventions - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Introduction.html#Introduction" title="Introduction">
+<link rel="prev" href="Kernel-History.html#Kernel-History" title="Kernel History">
+<link rel="next" href="Acknowledgements.html#Acknowledgements" title="Acknowledgements">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Conventions"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Acknowledgements.html#Acknowledgements">Acknowledgements</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Kernel-History.html#Kernel-History">Kernel History</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introduction</a>
+<hr>
+</div>
+
+<h3 class="section">1.3 Conventions</h3>
+
+<p>This section explains the notational conventions that are used in this
+manual. You may want to skip this section and refer back to it later.
+
+<ul class="menu">
+<li><a accesskey="1" href="Some-Terms.html#Some-Terms">Some Terms</a>:                Explanation of terms we use in this manual. 
+<!-- TODO add sections for booleans, parameter trees, list structures, -->
+<!-- naming conventions, etc. -->
+<li><a accesskey="2" href="Evaluation-Notation.html#Evaluation-Notation">Evaluation Notation</a>:       The format we use for examples of evaluation. 
+<li><a accesskey="3" href="Printing-Notation.html#Printing-Notation">Printing Notation</a>:         The format we use for examples that print output. 
+<li><a accesskey="4" href="Error-Messages.html#Error-Messages">Error Messages</a>:            The format we use for examples of errors. 
+<li><a accesskey="5" href="Format-of-Descriptions.html#Format-of-Descriptions">Format of Descriptions</a>:    Notation for describing functions, variables, etc. 
+</ul>
+
+   </body></html>
+
diff --git a/manual/html/Error-Messages.html b/manual/html/Error-Messages.html
@@ -0,0 +1,50 @@
+<html lang="en">
+<head>
+<title>Error Messages - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Conventions.html#Conventions" title="Conventions">
+<link rel="prev" href="Printing-Notation.html#Printing-Notation" title="Printing Notation">
+<link rel="next" href="Format-of-Descriptions.html#Format-of-Descriptions" title="Format of Descriptions">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Error-Messages"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Format-of-Descriptions.html#Format-of-Descriptions">Format of Descriptions</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Printing-Notation.html#Printing-Notation">Printing Notation</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventions</a>
+<hr>
+</div>
+
+<h4 class="subsection">1.3.4 Error Messages</h4>
+
+<p><a name="index-error-message-notation-6"></a>
+  Some examples cause errors to be signaled. The report doesn't
+specify what objects are passed to the error continuation, but in
+klisp, objects passed to the error continuation are encapsulated error
+objects that have at least a message and possibly some additional
+objects and context informations (such as source code location). In
+the examples, the error message is shown on a line starting with
+&lsquo;<samp><span class="samp">error--&gt;</span></samp>&rsquo;.
+
+<pre class="example">     (+ 23 #t)
+     error--&gt; Wrong type argument: (expected number) (#t)
+</pre>
+   </body></html>
+
diff --git a/manual/html/Evaluation-Notation.html b/manual/html/Evaluation-Notation.html
@@ -0,0 +1,55 @@
+<html lang="en">
+<head>
+<title>Evaluation Notation - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Conventions.html#Conventions" title="Conventions">
+<link rel="prev" href="Some-Terms.html#Some-Terms" title="Some Terms">
+<link rel="next" href="Printing-Notation.html#Printing-Notation" title="Printing Notation">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Evaluation-Notation"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Printing-Notation.html#Printing-Notation">Printing Notation</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Some-Terms.html#Some-Terms">Some Terms</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventions</a>
+<hr>
+</div>
+
+<h4 class="subsection">1.3.2 Evaluation Notation</h4>
+
+<p><a name="index-evaluation-notation-3"></a><a name="index-documentation-notation-4"></a>
+  When you evaluate a piece of Kernel code, it produces a result. In the
+examples in this manual, this is indicated with &lsquo;<samp><span class="samp">&rArr;</span></samp>&rsquo;:
+
+<pre class="example">     (car (cons 1 2))
+          &rArr; 1
+</pre>
+   <p class="noindent">You can read this as &ldquo;<code>(car (cons 1 2))</code> evaluates to 1&rdquo;.
+
+   <p>The semantics of a language feature are sometimes clarified, or even
+defined, in its entry by specifying that two expressions are
+equivalent. This is notated with &lsquo;<samp><span class="samp">==</span></samp>&rsquo;. For example, the
+semantics of applicative list* can be defined by following
+equivalences:
+<pre class="example">     (list* arg1) == arg1
+     (list* arg1 . more-args) == (cons arg1 (list* . more-args))
+</pre>
+   </body></html>
+
diff --git a/manual/html/Format-of-Descriptions.html b/manual/html/Format-of-Descriptions.html
@@ -0,0 +1,47 @@
+<html lang="en">
+<head>
+<title>Format of Descriptions - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Conventions.html#Conventions" title="Conventions">
+<link rel="prev" href="Error-Messages.html#Error-Messages" title="Error Messages">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Format-of-Descriptions"></a>
+<p>
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Error-Messages.html#Error-Messages">Error Messages</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventions</a>
+<hr>
+</div>
+
+<h4 class="subsection">1.3.5 Format of Descriptions</h4>
+
+<p><a name="index-description-format-7"></a>
+  Applicatives, operatives, and other objects are described in this manual
+in a uniform format. The first line of a description contains the
+name of the item followed by its operands or arguments, if any. 
+The description follows on succeeding lines, sometimes with examples.
+
+<ul class="menu">
+<li><a accesskey="1" href="A-Sample-Applicative-Description.html#A-Sample-Applicative-Description">A Sample Applicative Description</a>
+<!-- TODO add operative and/or variable like root-continuation -->
+</ul>
+
+   </body></html>
+
diff --git a/manual/html/Introduction.html b/manual/html/Introduction.html
@@ -35,23 +35,42 @@ Up:&nbsp;<a rel="up" accesskey="u" href="index.html#Top">Top</a>
 
 <p>klisp is an open source interpreter for the Kernel Programming
 Language. It aims at being comprehensive and robust as specified in
-the "Revised(-1) Report on the Kernel Programming Language", but
+the <cite>Revised(-1) Report on the Kernel Programming Language</cite>, but
 that probably won't happen for some time. It is written in C99 under
 the MIT license. It draws heavily from the Lua interpreter source
 code &amp; file structure. It uses the IMath library for arbitrary sized
 integers and rationals.
 
-   <p>Kernel is a conservative, Scheme-like dialect of Lisp in which
-everything is a first-class object. It was created by John N. Shutt. 
-You can read all about it at http://web.cs.wpi.edu/~jshutt/kernel.html
+   <p>The Kernel programming language is a statically scoped and properly
+tail-recursive dialect of Lisp, descended from Scheme. It is designed
+to be simpler and more general than Scheme, with an exceptionally
+clear, simple, and versatile semantics, only one way to form compound
+expressions, and no inessential restrictions on the power of that one
+compound form. Imperative, functional, and message-passing programming
+styles (to name a few) may be conveniently expressed in Kernel.
+
+   <p>An important property of Kernel is that all manipulable entities in
+Kernel are first-class objects. In particular, Kernel has no
+second-class combiners; instead, the roles of special forms and macros
+are subsumed by operatives, which are first-class, statically scoped
+combiners that act directly on their unevaluated operands. Kernel
+also has a second type of combiners, applicatives, which act on their
+evalu- ated arguments. Applicatives are roughly equivalent to Scheme
+procedures. However, an applicative is nothing more than a wrapper to
+induce operand evaluation, around an underlying operative (or, in
+principle, around another applicative, though that isn’t usually
+done); applicatives themselves are mere facilitators to computation.
+
+   <p>You can read more about Kernel at
+<a href="http://web.cs.wpi.edu/~jshutt/kernel.html">http://web.cs.wpi.edu/~jshutt/kernel.html</a>.
 
    <p>klisp is freely available for both academic and commercial purposes. 
 See LICENSE for details. it can be downloaded at
-http://www.bitbucket.org/AndresNavarro/klisp
+<a href="http://www.bitbucket.org/AndresNavarro/klisp">http://www.bitbucket.org/AndresNavarro/klisp</a>
 
    <p>klisp is developed by Andres Navarro, a Computer Science
 undergraduate at Buenos Aires University (UBA). You can reach him at
-&lt;canavarro82@gmail.com&gt;.
+<a href="mailto:canavarro82@gmail.com">canavarro82@gmail.com</a>.
 
    <p>This manual describes klisp version 0.1, presuming some familiarity
 with the Lisp family of languages in general, and with the Kernel
@@ -62,13 +81,12 @@ implemented functionality.
 
    <p>This is edition 0.1.
 
-<!-- appendices -->
-<!-- TODO -->
-<!-- @include index.texi -->
-<!-- Print the tables of contents -->
-<!-- FOR some reason this ends up in the last node instead of the general... -->
-<!-- TODO @summarycontents -->
-<!-- TODO @contents -->
-<!-- That's all -->
-</body></html>
+<ul class="menu">
+<li><a accesskey="1" href="Caveats.html#Caveats">Caveats</a>:                 Flaws and a request for help. 
+<li><a accesskey="2" href="Kernel-History.html#Kernel-History">Kernel History</a>:          Kernel is descended from Scheme. 
+<li><a accesskey="3" href="Conventions.html#Conventions">Conventions</a>:             How the manual is formatted. 
+<li><a accesskey="4" href="Acknowledgements.html#Acknowledgements">Acknowledgements</a>:        Contributions to this manual. 
+</ul>
+
+   </body></html>
 
diff --git a/manual/html/Kernel-History.html b/manual/html/Kernel-History.html
@@ -0,0 +1,64 @@
+<html lang="en">
+<head>
+<title>Kernel History - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Introduction.html#Introduction" title="Introduction">
+<link rel="prev" href="Caveats.html#Caveats" title="Caveats">
+<link rel="next" href="Conventions.html#Conventions" title="Conventions">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Kernel-History"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Conventions.html#Conventions">Conventions</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Caveats.html#Caveats">Caveats</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Introduction.html#Introduction">Introduction</a>
+<hr>
+</div>
+
+<h3 class="section">1.2 Kernel History</h3>
+
+<p><a name="index-Kernel-history-1"></a>
+  The Kernel Programming Language is a work in progress. It is being
+developed by John N. Shutt, Ph.D, who created it while studying at the
+Worcester Polytechnic Institute (I think about 2002, or so... ASK). It
+is descended from scheme, with the idea that all objects should be
+first class values. In particular, Kernel replaces macros with
+operatives (kinda like statically scoped fexprs and fsubrs) and has
+first class environments. Kernel also has the notion of encapsulated
+objects which limits the ammount of information an implementation can
+share with a Kernel program (e.g. There is no way in Kernel to get the
+parents or a complete list of bindings of an environment object).
+
+<!-- this is repeated above, in caveats -->
+   <p>The main reference on Kernel is the preliminary report:
+<cite>Revised(-1) Report on the Kernel Programming Language</cite>. Some
+sections of the report are still incomplete, so both klisp and this
+manual will use specifications from other languages in these sections,
+trying to follow the Kernel spirit. These instances will be documented
+throughout the manual.
+
+   <p>You can read all about Kernel at John's homepage at WPI
+<a href="http://www.cs.wpi.edu/~jshutt/">http://www.cs.wpi.edu/~jshutt/</a>, including the preliminary report
+on the language and his doctoral dissertation which gives a
+theorethical frame for fexprs. You can contact him at
+<a href="mailto:jshutt@cs.wpi.edu">jshutt@cs.wpi.edu</a>.
+
+   </body></html>
+
diff --git a/manual/html/Printing-Notation.html b/manual/html/Printing-Notation.html
@@ -0,0 +1,49 @@
+<html lang="en">
+<head>
+<title>Printing Notation - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Conventions.html#Conventions" title="Conventions">
+<link rel="prev" href="Evaluation-Notation.html#Evaluation-Notation" title="Evaluation Notation">
+<link rel="next" href="Error-Messages.html#Error-Messages" title="Error Messages">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Printing-Notation"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Error-Messages.html#Error-Messages">Error Messages</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Evaluation-Notation.html#Evaluation-Notation">Evaluation Notation</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventions</a>
+<hr>
+</div>
+
+<h4 class="subsection">1.3.3 Printing Notation</h4>
+
+<p><a name="index-printing-notation-5"></a>
+  Many of the examples in this manual print text when they are
+evaluated. In examples that print text, the printed text is indicated with
+&lsquo;<samp><span class="samp">-|</span></samp>&rsquo;. The value returned by evaluating the form (here
+<code>#t</code>) follows on a separate line.
+
+<pre class="example">     ($sequence (write 1) (write 2) #t)
+          -| 1
+          -| 2
+          &rArr; #t
+</pre>
+   </body></html>
+
diff --git a/manual/html/Some-Terms.html b/manual/html/Some-Terms.html
@@ -0,0 +1,50 @@
+<html lang="en">
+<head>
+<title>Some Terms - klisp Reference Manual</title>
+<meta http-equiv="Content-Type" content="text/html">
+<meta name="description" content="klisp Reference Manual">
+<meta name="generator" content="makeinfo 4.13">
+<link title="Top" rel="start" href="index.html#Top">
+<link rel="up" href="Conventions.html#Conventions" title="Conventions">
+<link rel="prev" href="Conventions.html#Conventions" title="Conventions">
+<link rel="next" href="Evaluation-Notation.html#Evaluation-Notation" title="Evaluation Notation">
+<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
+<meta http-equiv="Content-Style-Type" content="text/css">
+<style type="text/css"><!--
+  pre.display { font-family:inherit }
+  pre.format  { font-family:inherit }
+  pre.smalldisplay { font-family:inherit; font-size:smaller }
+  pre.smallformat  { font-family:inherit; font-size:smaller }
+  pre.smallexample { font-size:smaller }
+  pre.smalllisp    { font-size:smaller }
+  span.sc    { font-variant:small-caps }
+  span.roman { font-family:serif; font-weight:normal; } 
+  span.sansserif { font-family:sans-serif; font-weight:normal; } 
+--></style>
+</head>
+<body>
+<div class="node">
+<a name="Some-Terms"></a>
+<p>
+Next:&nbsp;<a rel="next" accesskey="n" href="Evaluation-Notation.html#Evaluation-Notation">Evaluation Notation</a>,
+Previous:&nbsp;<a rel="previous" accesskey="p" href="Conventions.html#Conventions">Conventions</a>,
+Up:&nbsp;<a rel="up" accesskey="u" href="Conventions.html#Conventions">Conventions</a>
+<hr>
+</div>
+
+<h4 class="subsection">1.3.1 Some Terms</h4>
+
+<p>Throughout this manual, the phrases &ldquo;the Kernel reader&rdquo; and &ldquo;the Kernel
+printer&rdquo; are used to refer to those routines in Lisp that convert
+textual representations of Kernel objects into actual objects, and
+<!-- TODO xref to printed representations -->
+vice versa. XXX Printed Representation XXX, for more details. You, the
+person reading this manual, are assumed to be &ldquo;the programmer&rdquo; or
+&ldquo;the user&rdquo;.
+
+   <p><a name="index-fonts-2"></a>  Examples of Kernel code appear in this font or form: <code>(list 1 2
+3)</code>. Names that represent arguments or metasyntactic variables appear
+in this font or form: <var>first-number</var>.
+
+   </body></html>
+
diff --git a/manual/klisp.info b/manual/klisp.info
@@ -8,7 +8,7 @@ version 0.1.
 
    Copyright (C) 2011 Andres Navarro
 
-   Permission is granted to make and distribute this manual, in whole
+   Permission is granted to copy and distribute this manual, in whole
 or in part.
 
 
@@ -19,7 +19,7 @@ corresponding to klisp version 0.1.
 
    Copyright (C) 2011 Andres Navarro
 
-   Permission is granted to make and distribute this manual, in whole
+   Permission is granted to copy and distribute this manual, in whole
 or in part.
 
 * Menu:
@@ -75,19 +75,38 @@ File: klisp,  Node: Introduction,  Next: (dir),  Prev: License,  Up: Top
 
 klisp is an open source interpreter for the Kernel Programming
 Language. It aims at being comprehensive and robust as specified in
-the "Revised(-1) Report on the Kernel Programming Language", but that
+the `Revised(-1) Report on the Kernel Programming Language', but that
 probably won't happen for some time. It is written in C99 under the
 MIT license. It draws heavily from the Lua interpreter source code &
 file structure. It uses the IMath library for arbitrary sized
 integers and rationals.
 
-   Kernel is a conservative, Scheme-like dialect of Lisp in which
-everything is a first-class object. It was created by John N. Shutt.
-You can read all about it at http://web.cs.wpi.edu/~jshutt/kernel.html
+   The Kernel programming language is a statically scoped and properly
+tail-recursive dialect of Lisp, descended from Scheme. It is designed
+to be simpler and more general than Scheme, with an exceptionally
+clear, simple, and versatile semantics, only one way to form compound
+expressions, and no inessential restrictions on the power of that one
+compound form. Imperative, functional, and message-passing programming
+styles (to name a few) may be conveniently expressed in Kernel.
+
+   An important property of Kernel is that all manipulable entities in
+Kernel are first-class objects. In particular, Kernel has no
+second-class combiners; instead, the roles of special forms and macros
+are subsumed by operatives, which are first-class, statically scoped
+combiners that act directly on their unevaluated operands. Kernel
+also has a second type of combiners, applicatives, which act on their
+evalu- ated arguments. Applicatives are roughly equivalent to Scheme
+procedures. However, an applicative is nothing more than a wrapper to
+induce operand evaluation, around an underlying operative (or, in
+principle, around another applicative, though that isn’t usually
+done); applicatives themselves are mere facilitators to computation.
+
+   You can read more about Kernel at
+`http://web.cs.wpi.edu/~jshutt/kernel.html'.
 
    klisp is freely available for both academic and commercial
 purposes.  See LICENSE for details. it can be downloaded at
-http://www.bitbucket.org/AndresNavarro/klisp
+`http://www.bitbucket.org/AndresNavarro/klisp'
 
    klisp is developed by Andres Navarro, a Computer Science
 undergraduate at Buenos Aires University (UBA). You can reach him at
@@ -102,11 +121,238 @@ implemented functionality.
 
    This is edition 0.1.
 
+* Menu:
+
+* Caveats::                Flaws and a request for help.
+* Kernel History::         Kernel is descended from Scheme.
+* Conventions::            How the manual is formatted.
+* Acknowledgements::       Contributions to this manual.
+
+
+File: klisp,  Node: Caveats,  Next: Kernel History,  Prev: Introduction,  Up: Introduction
+
+1.1 Caveats
+===========
+
+This is the first draft of this manual. It will be incomplete for
+some time. It will also evolve, together with klisp and the Kernel
+Programming Language, both of which, right now, are in a quite fluid
+state.
+
+   The main reference on Kernel is the preliminary report:
+`Revised(-1) Report on the Kernel Programming Language'. Some
+sections of the report are still incomplete, so both klisp and this
+manual will use specifications from other languages in these sections,
+trying to follow the Kernel spirit. These instances will be documented
+throughout the manual.
+
+   Please mail comments and corrections to <canavarro82@gmail.com>.
+
+
+      -Andres Navarro
+
+
+File: klisp,  Node: Kernel History,  Next: Conventions,  Prev: Caveats,  Up: Introduction
+
+1.2 Kernel History
+==================
+
+The Kernel Programming Language is a work in progress. It is being
+developed by John N. Shutt, Ph.D, who created it while studying at the
+Worcester Polytechnic Institute (I think about 2002, or so... ASK). It
+is descended from scheme, with the idea that all objects should be
+first class values. In particular, Kernel replaces macros with
+operatives (kinda like statically scoped fexprs and fsubrs) and has
+first class environments. Kernel also has the notion of encapsulated
+objects which limits the ammount of information an implementation can
+share with a Kernel program (e.g. There is no way in Kernel to get the
+parents or a complete list of bindings of an environment object).
+
+   The main reference on Kernel is the preliminary report:
+`Revised(-1) Report on the Kernel Programming Language'. Some
+sections of the report are still incomplete, so both klisp and this
+manual will use specifications from other languages in these sections,
+trying to follow the Kernel spirit. These instances will be documented
+throughout the manual.
+
+   You can read all about Kernel at John's homepage at WPI
+`http://www.cs.wpi.edu/~jshutt/', including the preliminary report on
+the language and his doctoral dissertation which gives a theorethical
+frame for fexprs. You can contact him at <jshutt@cs.wpi.edu>.
+
+
+File: klisp,  Node: Conventions,  Next: Acknowledgements,  Prev: Kernel History,  Up: Introduction
+
+1.3 Conventions
+===============
+
+This section explains the notational conventions that are used in this
+manual. You may want to skip this section and refer back to it later.
+
+* Menu:
+
+* Some Terms::               Explanation of terms we use in this manual.
+* Evaluation Notation::      The format we use for examples of evaluation.
+* Printing Notation::        The format we use for examples that print output.
+* Error Messages::           The format we use for examples of errors.
+* Format of Descriptions::   Notation for describing functions, variables, etc.
+
+
+File: klisp,  Node: Some Terms,  Next: Evaluation Notation,  Prev: Conventions,  Up: Conventions
+
+1.3.1 Some Terms
+----------------
+
+Throughout this manual, the phrases "the Kernel reader" and "the
+Kernel printer" are used to refer to those routines in Lisp that
+convert textual representations of Kernel objects into actual
+objects, and vice versa. XXX Printed Representation XXX, for more
+details. You, the person reading this manual, are assumed to be "the
+programmer" or "the user".
+
+   Examples of Kernel code appear in this font or form: `(list 1 2
+3)'. Names that represent arguments or metasyntactic variables appear
+in this font or form: FIRST-NUMBER.
+
+
+File: klisp,  Node: Evaluation Notation,  Next: Printing Notation,  Prev: Some Terms,  Up: Conventions
+
+1.3.2 Evaluation Notation
+-------------------------
+
+When you evaluate a piece of Kernel code, it produces a result. In the
+examples in this manual, this is indicated with `=>':
+
+     (car (cons 1 2))
+          => 1
+
+You can read this as "`(car (cons 1 2))' evaluates to 1".
+
+   The semantics of a language feature are sometimes clarified, or
+even defined, in its entry by specifying that two expressions are
+equivalent. This is notated with `=='. For example, the semantics of
+applicative list* can be defined by following equivalences:
+     (list* arg1) == arg1
+     (list* arg1 . more-args) == (cons arg1 (list* . more-args))
+
+
+File: klisp,  Node: Printing Notation,  Next: Error Messages,  Prev: Evaluation Notation,  Up: Conventions
+
+1.3.3 Printing Notation
+-----------------------
+
+Many of the examples in this manual print text when they are
+evaluated. In examples that print text, the printed text is indicated
+with `-|'. The value returned by evaluating the form (here `#t')
+follows on a separate line.
+
+     ($sequence (write 1) (write 2) #t)
+          -| 1
+          -| 2
+          => #t
+
+
+File: klisp,  Node: Error Messages,  Next: Format of Descriptions,  Prev: Printing Notation,  Up: Conventions
+
+1.3.4 Error Messages
+--------------------
+
+Some examples cause errors to be signaled. The report doesn't specify
+what objects are passed to the error continuation, but in klisp,
+objects passed to the error continuation are encapsulated error
+objects that have at least a message and possibly some additional
+objects and context informations (such as source code location). In
+the examples, the error message is shown on a line starting with
+`error-->'.
+
+     (+ 23 #t)
+     error--> Wrong type argument: (expected number) (#t)
+
+
+File: klisp,  Node: Format of Descriptions,  Prev: Error Messages,  Up: Conventions
+
+1.3.5 Format of Descriptions
+----------------------------
+
+Applicatives, operatives, and other objects are described in this
+manual in a uniform format. The first line of a description contains
+the name of the item followed by its operands or arguments, if any.
+The category--operative, applicative, or whatever--appears at the
+beginning of the line.  The description follows on succeeding lines,
+sometimes with examples.
+
+* Menu:
+
+* A Sample Applicative Description::
+
+
+File: klisp,  Node: A Sample Applicative Description,  Prev: Format of Descriptions,  Up: Format of Descriptions
+
+1.3.5.1 A Sample Applicative Description
+........................................
+
+In an applicative description, the name of the applicative being
+described appears first. It is followed on the same line by a list of
+arguments.  The names used for the arguments are also used in the
+body of the description.
+
+   Here is a description of an imaginary applicative `foo':
+
+ -- Applicative: (foo integer1 integer2 . rest)
+     The applicative `foo' subtracts INTEGER1 from INTEGER2, then
+     adds all the rest of the arguments to the result.
+
+          (foo 1 5 3 9)
+               => 16
+
+     More generally,
+
+          (foo W X Y...)
+          ==
+          (+ (- X W) Y...)
+
+   Any parameter whose name contains the name of a type (e.g.,
+INTEGER, INTEGER1 or CONTINUATION) is expected to be of that type. A
+plural of a type (such as NUMBERS) often means a list of objects of
+that type. Parameters named OBJECT may be of any type.  (XXX Types of
+Lisp Object XXX, for a list of Kernel object types.)  Parameters with
+other sorts of names are discussed specifically in the description of
+the combiner. In some sections, features common to parameters of
+several combiners are described at the beginning.
+
+   Operative descriptions have the same format, but the word
+`Applicative' is  replaced by `Operative', and `Argument' is replaced
+by `Operand'. Also Operatives always have an environment parameter
+(that can be #ignore or a symbol).
+
+
+File: klisp,  Node: Acknowledgements,  Prev: Conventions,  Up: Introduction
+
+1.4 Acknowledgements
+====================
+
+This manual was written by Andres Navarro.
+
+   The structure and some text for this introductory section were
+borrowed from the Elisp Manual by the Free Sofware Foundation. This
+manual also borrows freely from both the Kernel Report and the Scheme
+Reports.
+
 
 
 Tag Table:
 Node: Top334
 Node: License775
 Node: Introduction2442
+Node: Caveats5244
+Node: Kernel History6021
+Node: Conventions7454
+Node: Some Terms8119
+Node: Evaluation Notation8783
+Node: Printing Notation9519
+Node: Error Messages9990
+Node: Format of Descriptions10631
+Node: A Sample Applicative Description11188
+Node: Acknowledgements12739
 
 End Tag Table
diff --git a/manual/src/intro.texi b/manual/src/intro.texi
@@ -47,23 +47,42 @@ THE SOFTWARE.
 
   klisp is an open source interpreter for the Kernel Programming
 Language. It aims at being comprehensive and robust as specified in
-the "Revised(-1) Report on the Kernel Programming Language", but
+the @cite{Revised(-1) Report on the Kernel Programming Language}, but
 that probably won't happen for some time. It is written in C99 under
 the MIT license. It draws heavily from the Lua interpreter source
 code & file structure. It uses the IMath library for arbitrary sized
 integers and rationals.
 
-  Kernel is a conservative, Scheme-like dialect of Lisp in which
-everything is a first-class object. It was created by John N. Shutt.
-You can read all about it at http://web.cs.wpi.edu/~jshutt/kernel.html
+  The Kernel programming language is a statically scoped and properly
+tail-recursive dialect of Lisp, descended from Scheme. It is designed
+to be simpler and more general than Scheme, with an exceptionally
+clear, simple, and versatile semantics, only one way to form compound
+expressions, and no inessential restrictions on the power of that one
+compound form. Imperative, functional, and message-passing programming
+styles (to name a few) may be conveniently expressed in Kernel.
+
+  An important property of Kernel is that all manipulable entities in
+Kernel are first-class objects. In particular, Kernel has no
+second-class combiners; instead, the roles of special forms and macros
+are subsumed by operatives, which are first-class, statically scoped
+combiners that act directly on their unevaluated operands. Kernel
+also has a second type of combiners, applicatives, which act on their
+evalu- ated arguments. Applicatives are roughly equivalent to Scheme
+procedures. However, an applicative is nothing more than a wrapper to
+induce operand evaluation, around an underlying operative (or, in
+principle, around another applicative, though that isn’t usually
+done); applicatives themselves are mere facilitators to computation.
+
+  You can read more about Kernel at
+@url{http://web.cs.wpi.edu/~jshutt/kernel.html}.
 
   klisp is freely available for both academic and commercial purposes.
 See LICENSE for details. it can be downloaded at 
-http://www.bitbucket.org/AndresNavarro/klisp
+@url{http://www.bitbucket.org/AndresNavarro/klisp}
 
   klisp is developed by Andres Navarro, a Computer Science
 undergraduate at Buenos Aires University (UBA). You can reach him at
-<canavarro82@@gmail.com>.
+@email{canavarro82@@gmail.com}.
 
   This manual describes klisp version 0.1, presuming some familiarity
 with the Lisp family of languages in general, and with the Kernel 
@@ -73,3 +92,238 @@ rationale is provided for any feature, only a description of the
 implemented functionality. 
 
   This is edition 0.1.
+
+@menu
+* Caveats::                Flaws and a request for help.
+* Kernel History::         Kernel is descended from Scheme.
+* Conventions::            How the manual is formatted.
+* Acknowledgements::       Contributions to this manual.
+@end menu
+
+@node Caveats, Kernel History, Introduction, Introduction
+@section Caveats
+
+  This is the first draft of this manual. It will be incomplete for
+some time. It will also evolve, together with klisp and the Kernel
+Programming Language, both of which, right now, are in a quite fluid
+state.
+
+@c this is below, in history
+  The main reference on Kernel is the preliminary report: 
+@cite{Revised(-1) Report on the Kernel Programming Language}. Some
+sections of the report are still incomplete, so both klisp and this
+manual will use specifications from other languages in these sections,
+trying to follow the Kernel spirit. These instances will be documented
+throughout the manual.
+
+Please mail comments and corrections to
+@email{canavarro82@@gmail.com}.
+
+@noindent
+@display
+ --Andres Navarro
+@end display
+
+@node Kernel History, Conventions, Caveats, Introduction
+@section Kernel History
+@cindex Kernel history
+
+  The Kernel Programming Language is a work in progress. It is being
+developed by John N. Shutt, Ph.D, who created it while studying at the
+Worcester Polytechnic Institute (I think about 2002, or so... ASK). It
+is descended from scheme, with the idea that all objects should be
+first class values. In particular, Kernel replaces macros with
+operatives (kinda like statically scoped fexprs and fsubrs) and has
+first class environments. Kernel also has the notion of encapsulated
+objects which limits the ammount of information an implementation can
+share with a Kernel program (e.g. There is no way in Kernel to get the
+parents or a complete list of bindings of an environment object). 
+
+@c this is repeated above, in caveats
+  The main reference on Kernel is the preliminary report: 
+@cite{Revised(-1) Report on the Kernel Programming Language}. Some
+sections of the report are still incomplete, so both klisp and this
+manual will use specifications from other languages in these sections,
+trying to follow the Kernel spirit. These instances will be documented
+throughout the manual.
+
+  You can read all about Kernel at John's homepage at WPI 
+@url{http://www.cs.wpi.edu/~jshutt/}, including the preliminary report
+on the language and his doctoral dissertation which gives a
+theorethical frame for fexprs. You can contact him at
+@email{jshutt@@cs.wpi.edu}.
+
+@node Conventions, Acknowledgements, Kernel History, Introduction
+@section Conventions
+
+  This section explains the notational conventions that are used in this
+manual. You may want to skip this section and refer back to it later.
+
+@menu
+* Some Terms::               Explanation of terms we use in this manual.
+@c TODO add sections for booleans, parameter trees, list structures,
+@c naming conventions, etc.
+* Evaluation Notation::      The format we use for examples of evaluation.
+* Printing Notation::        The format we use for examples that print output.
+* Error Messages::           The format we use for examples of errors.
+* Format of Descriptions::   Notation for describing functions, variables, etc.
+@end menu
+
+@node Some Terms, Evaluation Notation, Conventions, Conventions
+@subsection Some Terms
+
+  Throughout this manual, the phrases ``the Kernel reader'' and ``the Kernel
+printer'' are used to refer to those routines in Lisp that convert
+textual representations of Kernel objects into actual objects, and
+@c TODO xref to printed representations
+vice versa. XXX Printed Representation XXX, for more details. You, the
+person reading this manual, are assumed to be ``the programmer'' or
+``the user''.
+
+@cindex fonts
+  Examples of Kernel code appear in this font or form: @code{(list 1 2
+3)}. Names that represent arguments or metasyntactic variables appear
+in this font or form: @var{first-number}.
+
+@node Evaluation Notation, Printing Notation, Some Terms, Conventions
+@subsection Evaluation Notation
+@cindex evaluation notation
+@cindex documentation notation
+
+  When you evaluate a piece of Kernel code, it produces a result. In the
+examples in this manual, this is indicated with @samp{@result{}}:
+
+@example
+(car (cons 1 2))
+     @result{} 1
+@end example
+
+@noindent
+You can read this as ``@code{(car (cons 1 2))} evaluates to 1''.
+
+  The semantics of a language feature are sometimes clarified, or even
+defined, in its entry by specifying that two expressions are
+equivalent. This is notated with @samp{@equiv{}}. For example, the 
+semantics of applicative list* can be defined by following
+equivalences:
+@example
+(list* arg1) @equiv{} arg1
+(list* arg1 . more-args) @equiv{} (cons arg1 (list* . more-args))
+@end example
+
+@node Printing Notation, Error Messages, Evaluation Notation, Conventions
+@subsection Printing Notation
+@cindex printing notation
+
+  Many of the examples in this manual print text when they are
+evaluated. In examples that print text, the printed text is indicated with
+@samp{@print{}}. The value returned by evaluating the form (here
+@code{#t}) follows on a separate line.
+
+@group
+@example
+($sequence (write 1) (write 2) #t)
+     @print{} 1
+     @print{} 2
+     @result{} #t
+@end example
+@end group
+
+@node Error Messages, Format of Descriptions, Printing Notation, Conventions
+@subsection Error Messages
+@cindex error message notation
+
+  Some examples cause errors to be signaled. The report doesn't
+specify what objects are passed to the error continuation, but in
+klisp, objects passed to the error continuation are encapsulated error
+objects that have at least a message and possibly some additional
+objects and context informations (such as source code location). In
+the examples, the error message is shown on a line starting with
+@samp{@error{}}.
+
+@example
+(+ 23 #t)
+@error{} Wrong type argument: (expected number) (#t)
+@end example
+
+@node Format of Descriptions,  , Error Messages, Conventions
+@subsection Format of Descriptions
+@cindex description format
+
+  Applicatives, operatives, and other objects are described in this manual
+in a uniform format. The first line of a description contains the
+name of the item followed by its operands or arguments, if any.
+@ifinfo
+The category---operative, applicative, or whatever---appears at the
+beginning of the line.
+@end ifinfo
+@iftex
+The category---operative, applicative, or whatever---is printed next to the
+right margin.
+@end iftex
+The description follows on succeeding lines, sometimes with examples.
+
+@menu
+* A Sample Applicative Description::       
+@c TODO add operative and/or variable like root-continuation
+@end menu
+
+@node A Sample Applicative Description, , Format of Descriptions, Format of Descriptions
+@subsubsection A Sample Applicative Description
+@cindex applicative descriptions
+@cindex operative descriptions
+@cindex object descriptions
+
+  In an applicative description, the name of the applicative being described
+appears first. It is followed on the same line by a list of arguments.
+The names used for the arguments are also used in the body of the
+description.
+
+  Here is a description of an imaginary applicative @code{foo}:
+
+@deffn Applicative (foo integer1 integer2 . rest)
+  The applicative @code{foo} subtracts @var{integer1} from @var{integer2},
+then adds all the rest of the arguments to the result. 
+
+@example
+(foo 1 5 3 9)
+     @result{} 16
+@end example
+
+More generally,
+
+@example
+(foo @var{w} @var{x} @var{y}@dots{})
+@equiv{}
+(+ (- @var{x} @var{w}) @var{y}@dots{})
+@end example
+@end deffn
+
+  Any parameter whose name contains the name of a type (e.g.,
+@var{integer}, @var{integer1} or @var{continuation}) is expected to be of that
+type. A plural of a type (such as @var{numbers}) often means a list of
+objects of that type. Parameters named @var{object} may be of any
+type.
+@c TODO add xref types of objects
+(XXX Types of Lisp Object XXX, for a list of Kernel object types.)
+Parameters with other sorts of names are
+discussed specifically in the description of the combiner. In some
+sections, features common to parameters of several combiners are
+described at the beginning.
+
+@c TODO xref to ptree
+@c TODO clean this up a little
+  Operative descriptions have the same format, but the word
+`Applicative' is  replaced by `Operative', and `Argument' is replaced
+by `Operand'. Also Operatives always have an environment parameter
+(that can be #ignore or a symbol).
+
+@node Acknowledgements,, Conventions, Introduction
+@section Acknowledgements
+
+  This manual was written by Andres Navarro.
+
+  The structure and some text for this introductory section were
+borrowed from the Elisp Manual by the Free Sofware Foundation. This
+manual also borrows freely from both the Kernel Report and the Scheme
+Reports.
diff --git a/manual/src/klisp.texi b/manual/src/klisp.texi
@@ -1,4 +1,4 @@
-\input texinfo  @c -*-texinfo-*-
+input texinfo  @c -*-texinfo-*-
 @c %**start of header
 @setfilename klisp
 @settitle klisp Reference Manual
@@ -14,7 +14,7 @@ for klisp version 0.1.
 
 Copyright (C) 2011 Andres Navarro
 
-Permission is granted to make and distribute this manual, in whole or
+Permission is granted to copy and distribute this manual, in whole or
 in part. 
 @c TODO put up better text for this.
 @end ifinfo
@@ -40,7 +40,7 @@ May 2011.@*
 
 @sp 2
 
-Permission is granted to make and distribute this manual, in whole or
+Permission is granted to copy and distribute this manual, in whole or
 in part. 
 @end titlepage
 @page
@@ -53,7 +53,7 @@ corresponding to klisp version 0.1.
 
 Copyright @copyright{} 2011 Andres Navarro
 
-Permission is granted to make and distribute this manual, in whole or
+Permission is granted to copy and distribute this manual, in whole or
 in part. 
 @c TODO put up better text for this.
 @end ifinfo