24 files changed, 3150 insertions, 0 deletions
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm
new file mode 100644
index 0000000..a39f495
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/ceiling.htm
@@ -0,0 +1,137 @@
+<html><head>
+
+<title>cl:ceiling</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:ceiling</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>ceiling</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward positive infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>ceiling</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+  <td valign="top"><nobr>returns</nobr></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+  <td></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:ceiling</font> (number &amp;optional (divisor
+                                    (if (integerp number) 1 1.0)
+                                    divisor-p))
+  (let ((quotient
+          (cond ((and (not divisor-p) (integerp number)) number)
+                ((= number divisor) 1)
+                (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+                         (f-quotient (/ (float number) divisor)))
+                     (if (or (= i-quotient f-quotient)  <font color="#008844">; integer result</font>
+                             (not (plusp f-quotient)))
+                          (truncate f-quotient)
+                          (1+ (truncate f-quotient))))))))
+    (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+          <font color="#AA5500">cl:*multiple-values*</font> t)
+    quotient))
+</pre>
+
+<p>The <nobr>cl:<b>ceiling</b></nobr> function computes a quotient that has
+been truncated toward positive infinity. <nobr>That is</nobr>, the quotient
+represents the smallest mathematical integer that is not smaller than the
+mathematical result.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm">&nbsp;T&nbsp;</a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p> 
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:ceiling  3.5)  =&gt;  4  <font color="#008844">; *rslt* =&gt; ( 4 -0.5)</font>
+(cl:ceiling -3.5)  =&gt; -3  <font color="#008844">; *rslt* =&gt; (-3 -0.5)</font>
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm
new file mode 100644
index 0000000..c61cb23
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/debug-mv.htm
@@ -0,0 +1,110 @@
+<html><head>
+
+<title>cl:debug:mv</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:debug:mv</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>debug:mv</b></b></nobr> function can be used to debug
+multiple value expressions:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>debug:mv</b> <i>expr</i></dt>
+<dd><i>expr</i> - a Lisp expression, returning an arbitrary number of values<br>
+returns - the normal Lisp return value from evaluating <i>expr</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:debug:mv</font> (expr)
+  (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+  (let ((result (eval expr)))
+    (format t <font color="#880000">";; cl:*multiple-values* =&gt; ~a~%"</font> <font color="#AA5500">cl:*multiple-values*</font>)
+    (format t <font color="#880000">";; *rslt* =&gt; ~a~a~%"</font> <font color="#AA5500">*rslt*</font>
+              (if <font color="#AA5500">cl:*multiple-values*</font> <font color="#880000">"" " [invalid]"</font>))
+    result))
+</pre>
+
+<p>The <nobr>cl:<b>debug:mv</b></nobr> function first sets the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>, then it
+evaluates the expression. After evaluation it prints the values of the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+and <a href="../../reference/global-rslt.htm">*rslt*</a> variables and
+returns the normal Lisp return value from the evaluation.</p>
+
+<p>Example:</p>
+
+<pre class="example">
+&gt; (cl:debug:mv '(cl:values 1 2 3))
+;; cl:*multiple-values* =&gt; T
+;; *rslt* =&gt; (1 2 3)
+1
+
+&gt; (cl:debug:mv 1)
+;; cl:*multiple-values* =&gt; NIL
+;; *rslt* =&gt; (1 2 3) [invalid]
+1
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm
new file mode 100644
index 0000000..14835c5
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/equalp.htm
@@ -0,0 +1,162 @@
+<html><head>
+
+<title>cl:equalp</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:equalp</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(<b>equalp</b> <i>expr1 expr2</i>)</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - <a href="t.htm">&nbsp;T&nbsp;</a> if the expressions
+are structurally equal, <a href="nil.htm">NIL</a> otherwise</dd>
+</dl>
+
+</div></p>
+
+<p>Two expressions are 'equalp':</p>
+
+<ul>
+
+<li><p>If the expressions
+<nobr>are <a href="../../reference/equal.htm">equal</a></nobr>.</p></li>
+
+<li><p>If two numbers of arbitrary type <nobr>are
+<a href="../../reference/number-equal.htm">&nbsp;=&nbsp;</a></nobr>.</p></li>
+
+<li><p>If two characters are
+<nobr><a href="../../reference/char-equal-i.htm">char-equal</a></nobr>.</p></li>
+
+<li><p>If two strings are <nobr><a
+href="../../reference/string-equal-i.htm">string-equal</a></nobr>.</p></li>
+
+<li><p>If the two <a href="../../reference/car.htm">car</a>s in conses are
+'equalp' and the two <a href="../../reference/cdr.htm">cdr</a>s in conses
+are 'equalp'.</p></li>
+
+<li><p>If two arrays have the same number of elements and dimensions, and
+the corresponding elements in all dimensions are 'equalp'.</p></li>
+
+</ul>
+
+<p>Note that only 'equalp' can compare arrays.</p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:equalp</font> (expr-1 expr-2)
+  (or (equal expr-1 expr-2)
+      (and (numberp expr-1) (numberp expr-2) (= expr-1 expr-2))
+      (let ((type (type-of expr-1)))
+        (when (eq type (type-of expr-2))
+          (case type
+            (character (char-equal expr-1 expr-2))
+            (string    (string-equal expr-1 expr-2))
+            (cons      (do ((x (first expr-1)
+                               (if (consp expr-1) (first expr-1) expr-1))
+                            (y (first expr-2)
+                               (if (consp expr-2) (first expr-2) expr-2)))
+                           ((or (null expr-1)
+                                (null expr-2)
+                                (not (equalp x y)))
+                            (and (null expr-1)
+                                 (null expr-2)))
+                         (setq expr-1 (and (consp expr-1) (rest expr-1))
+                               expr-2 (and (consp expr-2) (rest expr-2)))))
+            (array     (let ((end (length expr-1)))
+                         (when (eql end (length expr-2))
+                           (dotimes (index end t)
+                             (and (not (equalp (aref expr-1 index)
+                                               (aref expr-2 index)))
+                                  (return nil)))))))))))
+</pre>
+
+<p><b>cons:</b> <a href="../../reference/do.htm">do</a> is used instead of
+recursion because XLISP has only two kilobytes stack size. <nobr>The
+(<a href="../../reference/consp.htm">consp</a> <i>expr</i>)</nobr> tests are
+necessary because in a dotted list the last
+<a href="../../reference/rest.htm">rest</a> element is not a cons.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:equalp 1 1.0)                            =&gt; T
+(cl:equalp #\a #\A)                          =&gt; T
+(cl:equalp "Abc" "aBc")                      =&gt; T
+(cl:equalp '(1 #\a "Abc") '(1.0 #\A "aBc"))  =&gt; T
+(cl:equalp #(1 #\a "Abc") #(1.0 #\A "aBc"))  =&gt; T
+</pre>
+
+<p>Nested expressions only match if the nesting matches:</p>
+
+<pre class="example">
+(cl:equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>)  =&gt; T
+(cl:equalp '(1 <font color="#AA0000">(</font>2 3<font color="#AA0000">)</font>) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0)  =&gt; NIL
+(cl:equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(<font color="#AA0000">(</font>1.0 2.0<font color="#AA0000">)</font> 3.0)  =&gt; T
+(cl:equalp '(<font color="#AA0000">(</font>1 2<font color="#AA0000">)</font> 3) '(1.0 <font color="#AA0000">(</font>2.0 3.0<font color="#AA0000">)</font>)  =&gt; NIL
+</pre>
+
+<p>A character does not match a string with the same character:</p>
+
+<pre class="example">
+(cl:equalp #\a "a")  =&gt; NIL
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm
new file mode 100644
index 0000000..707e28e
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/exp.htm
@@ -0,0 +1,92 @@
+<html><head>
+
+<title>cl:exp</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:exp</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>exp</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/exp.htm">exp</a> function, but
+also accepts integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>exp</b> <i>power</i>)</dt>
+<dd><i>power</i> - an integer or floating-point number<br>
+returns - the result of <nobr>'e' [2.7128]</nobr> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:exp</font> (x)
+  (exp (float x)))
+</pre>
+
+<p>See <a href="../../reference/defun.htm">defun</a>,
+<a href="../../reference/exp.htm">exp</a>,
+<a href="../../reference/float.htm">float</a>.</p>
+
+<p>The <nobr>cl:<b>exp</b></nobr> function computes <nobr>'e'
+[2.7128]</nobr> raised to the specified 'power' and returns the result as a
+<nobr>floating-point</nobr> number.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm
new file mode 100644
index 0000000..05e95ea
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/expt.htm
@@ -0,0 +1,105 @@
+<html><head>
+
+<title>cl:expt</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:expt</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>expt</b></nobr> function computes the result of 'x' to
+the power <nobr>of 'y'</nobr>:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>expt</b> <i>base power</i>)</dt>
+<dd><i>base</i> - the base<br>
+<i>power</i> - the exponent<br>
+returns - the result of <i>base</i> to the power of <i>power</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:expt</font> (x y)
+  (let ((power (expt (float x) y)))
+    (if (and (integerp x) (integerp y))
+        (round power)
+        power)))
+</pre>
+
+<p>See <a href="../reference/and.htm">and</a>,
+<a href="../reference/defun.htm">defun</a>,
+<a href="../reference/expt.htm">expt</a>,
+<a href="../reference/float.htm">float</a>,
+<nobr><a href="../reference/if.htm">&nbsp;if&nbsp;</a></nobr>,
+<a href="../reference/integerp.htm">integerp</a>,
+<a href="../reference/let.htm">let</a>,
+<a href="../reference/power.htm">power</a>,
+<a href="../reference/round.htm">round</a>.</p>
+
+<p>The <nobr>cl:<b>expt</b></nobr> function accepts integer and floating
+point numbers as arguments. <nobr>If both</nobr> arguments are integer
+numbers, the result will be an integer number, <nobr>if one</nobr> or both
+arguments are <nobr>floating-point</nobr> numbers, the result will be a
+<nobr>floating-point</nobr> number. <nobr>In contrast</nobr> to the
+Nyquist/XLISP <a href="../../reference/expt.htm">expt</a> function, the
+'<nobr>cl:expt</nobr>' function accepts exactly two arguments.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm
new file mode 100644
index 0000000..79e046c
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/floor.htm
@@ -0,0 +1,150 @@
+<html><head>
+
+<title>cl:floor</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:floor</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>floor</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward negative infinity:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>floor</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+  <td valign="top"><nobr>returns</nobr></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+  <td></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:floor</font> (number &amp;optional (divisor
+                                  (if (integerp number) 1 1.0)
+                                  divisor-p))
+  (let ((quotient
+          (cond ((and (not divisor-p) (integerp number)) number)
+                ((= number divisor) 1)
+                (t (let ((i-quotient (/ (truncate number) (truncate divisor)))
+                         (f-quotient (/ (float number) divisor)))
+                     (if (or (= i-quotient f-quotient)  <font color="#008844">; integer result</font>
+                             (not (minusp f-quotient)))
+                          (truncate f-quotient)
+                          (1- (truncate f-quotient))))))))
+    (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+          <font color="#AA5500">cl:*multiple-values*</font> t)
+    quotient))
+</pre>
+
+<p>The <nobr>cl:<b>floor</b></nobr> function computes a quotient that has
+been truncated toward negative infinity. <nobr>That is</nobr>, the quotient
+represents the largest mathematical integer that is not larger than the
+mathematical quotient.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm">&nbsp;T&nbsp;</a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p> 
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:floor  3.5)  =&gt;  3  <font color="#008844">; *rslt* =&gt; ( 3 0.5)</font>
+(cl:floor -3.5)  =&gt; -4  <font color="#008844">; *rslt* =&gt; (-4 0.5)</font>
+</pre>
+
+<p>See also:</p>
+
+<ul>
+<li><nobr><a href="../../reference/rem.htm">rem</a> - remainder of an integer division</nobr></li>
+<li><nobr><a href="../../reference/round.htm">round</a> - round arbitrary numbers to integers</nobr></li>
+<li><nobr><a href="../../reference/truncate.htm">truncate</a> - truncate arbitrary numbers toward zero</nobr></li>
+<li><nobr><a href="mod.htm">cl:mod</a></nobr></li>
+<li><nobr><a href="rem.htm">cl:rem</a></nobr></li>
+<li><nobr><a href="round.htm">cl:round</a></nobr></li>
+<li><nobr><a href="truncate.htm">cl:truncate</a></nobr></li>
+<li><nobr><a href="ceiling.htm">cl:ceiling</a></nobr></li>
+</ul>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm
new file mode 100644
index 0000000..5ca1757
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/global-multiple-values.htm
@@ -0,0 +1,142 @@
+<html><head>
+
+<title>cl:*multiple-values*</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:*multiple-values*</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>*multiple-values*</b></nobr> variable is used to signal
+if a function has returned multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>cl:<b>*multiple-values*</b></dt>
+<dd>returns - <a href="../../reference/t.htm">&nbsp;T&nbsp;</a> if a
+function returned multiple values</dd>
+</dl>
+
+</div></p>
+
+<p>Test if a function has returned multiple values:</p>
+
+<pre class="example">
+(setf cl:*multiple-values* nil)
+(let ((result (function ...)))
+  (if cl:*multiple-values*
+      (do-something-with *rslt* ...)
+      (do-something-with result ...))
+  ... )
+</pre>
+
+<p>Do not use <nobr>cl:<b>*multiple-values*</b></nobr> with
+<a href="../../reference/let.htm">let</a> like this:</p>
+
+<pre class="example">
+(let ((cl:*multiple-values* nil)
+      (result (function ...)))
+  (if cl:*multiple-values*
+      (do-something-with *rslt* ...)
+      (do-something-with result ...))
+  ... )
+</pre>
+
+<p>This doesn't work because 'function' is evaluated in the global XLISP
+environment, where the lexical <a href="../../reference/let.htm">let</a>
+binding of the <nobr>cl:<b>*multiple-values*</b></nobr> variable does not
+exist, while the <a href="../../reference/if.htm">&nbsp;if&nbsp;</a> form
+inside the <a href="../../reference/let.htm">let</a> form cannot see a
+global change of the <nobr>cl:<b>*multiple-values*</b></nobr> variable,
+because the global value is shadowed by the lexical
+<a href="../../reference/let.htm">let</a> binding.
+<nobr>See <a href="../environment.htm">Environment</a></nobr> for more
+details about variables.</p>
+
+<p>The XLISP <a href="../../reference/progv.htm">progv</a> special form can
+be used to encapsulate a multiple value call while automatically restoring
+the old values at the end like this:</p>
+
+<pre class="example">
+(values 1 2 3)        =&gt; 1
+
+cl:*multiple-values*  =&gt; T
+*rslt*                =&gt; (1 2 3)
+
+(progv '(cl:*multiple-values* *rslt*) '(nil nil)
+  (let ((result (function ...)))
+    (if cl:*multiple-values*
+        (do-something-with *rslt* ...)
+        (do-something-with result ...))))
+
+cl:*multiple-values*  =&gt; T
+*rslt*                =&gt; (1 2 3)
+</pre>
+
+<p><div class="box">
+
+<p><b>Note:</b> All functions returning multiple values set 
+<nobr>cl:<b>*multiple-values*</b></nobr> to
+<a href="../../reference/t.htm">&nbsp;T&nbsp;</a>, but it's up to the
+Lisp programmer to reset the variable
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+</div></p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm
new file mode 100644
index 0000000..c7e5c5f
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/log.htm
@@ -0,0 +1,95 @@
+<html><head>
+
+<title>cl:log</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:log</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>log</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/log.htm">log</a> function, but also
+accepts integer numbers and has an optional 'base' argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>log</b> <i>number</i> [<i>base</i>])</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>base</i> - an integer or floating-point number<br>
+returns - the the logarithm of <i>number</i> in base <i>base</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:log</font> (number &amp;optional base)
+  (if base
+      (if (zerop base)
+          0.0
+          (/ (log (float number)) (log (float base))))
+      (log (float number))))
+</pre>
+
+<p>The '<nobr>cl:log</nobr>' function returns the logarithm of 'number' in
+base 'base'. <nobr>If 'base'</nobr> is not supplied its value <nobr>is
+'e'</nobr>, the base of the natural logarithms. <nobr>If the</nobr> 'base'
+argument is zero, then 'cl:log' returns zero. <nobr>The result</nobr> is
+always a <nobr>floating-point</nobr> number.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm
new file mode 100644
index 0000000..9454d4e
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/mod.htm
@@ -0,0 +1,97 @@
+<html><head>
+
+<title>cl:mod</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:mod</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>mod</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="#cl-floor">cl:floor</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:mod</font> (number divisor)
+  (if (= (abs number) (abs divisor))
+      (if (and (integerp number) (integerp divisor)) 0 0.0)
+      (let* ((i-quotient (/ (truncate number) (truncate divisor)))
+             (f-quotient (/ (float number) divisor))
+             (quotient (if (or (= i-quotient f-quotient)  <font color="#008844">; integer result</font>
+                               (not (minusp f-quotient)))
+                           (truncate f-quotient)
+                           (1- (truncate f-quotient)))))
+        (- number (* quotient divisor)))))
+</pre>
+
+<p>The <nobr>cl:<b>mod</b></nobr> function performs the
+<a href="floor.htm">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="floor.htm">cl:floor</a> operation. <nobr>The
+result</nobr> is either zero or an integer or <nobr>floating-point</nobr>
+number with the same sign as the 'divisor' argument. <nobr>If both</nobr>
+arguments are integer numbers, the <nobr>cl:<b>mod</b></nobr> function is
+equal to the mathematical modulus function.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm
new file mode 100644
index 0000000..32fdadf
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-bind.htm
@@ -0,0 +1,193 @@
+<html><head>
+
+<title>cl:multiple-value-bind</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-bind</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-bind</b></nobr> macro creates new bindings
+for a list of symbols and evaluates expressions that use these bindings:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-bind</b> <i>symbols values</i> [<i>expr1</i> ...])</dt>
+<dd><i>symbols</i> - a list of symbols<br>
+<i>values</i> - a Lisp expression returning one or more values<br>
+<i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the value[s] returned by the last expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-bind</font> (symbols expr &rest body)
+  (and (or (not (consp symbols))
+           (eq 'quote (first symbols))
+           (dolist (symbol symbols)
+             (or (symbolp symbol) (return t))))
+       (error <font color="#880000">"not a list of symbols"</font> symbols))
+  (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+  (let* ((result (eval expr))
+         (values (if <font color="#AA5500">cl:*multiple-values*</font>
+                     <font color="#AA5500">*rslt*</font>
+                     (list result)))
+         (number-of-symbols (length symbols))
+         (number-of-values  (length values))
+         (bindings nil))
+    (dotimes (index number-of-symbols)
+      (push (if (&lt; index number-of-values)
+                (list (nth index symbols)
+                      (list 'quote (nth index values)))
+                (nth index symbols))
+            bindings))
+    (setq bindings (reverse bindings))
+    `(let ,bindings ,@body)))
+</pre>
+
+<p>The 'values' expression is evaluated, and each of the symbols is bound to
+the respective value returned by the evaluation. <nobr>If there</nobr> are
+more symbols than values returned, extra values of
+<a href="../../reference/nilo.htm">NIL</a> are bound to the remaining
+symbols. <nobr>If there</nobr> are more values than symbols, the extra
+values are ignored. The symbols are bound to the values <nobr>by
+<a href="../../reference/let.htm">let</a></nobr>, behaving like an
+<nobr>implicit <a href="../../reference/progn.htm">progn</a></nobr>.</p>
+
+<p><nobr>Before evaluating 'expr1', the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm">&nbsp;T&nbsp;</a></nobr>
+if evaluating the 'values' expression returned multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>The <nobr>cl:<b>multiple-value-bind</b></nobr> macro binds multiple
+values to local <a href="../../reference/let.htm">let</a> variables::</p>
+
+<pre class="example">
+&gt; (macroexpand-1 '(cl:multiple-value-bind (a b c)
+                      (cl:values 1 2 3)
+                    (list a b c)))
+(LET ((A (QUOTE 1))
+      (B (QUOTE 2))
+      (C (QUOTE 3)))
+  (LIST A B C))
+</pre>
+
+<p>The <a href="../../reference/quote.htm">quote</a>s are necessary to
+prevent 'unbound variable' and 'unbound function' errors with symbols and
+lists.</p>
+
+<p>Examples:</p>
+
+<p><b>1.</b> The <nobr>cl:<b>multiple-value-bind</b></nobr> macro binds
+values returned by the <a href="values.htm">cl:values</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+  (cl:values 1 2 3))  <font color="#008844">; multiple return values</font>
+
+&gt; (cl:multiple-value-bind (a b c)
+      (multiple-value-function)
+    (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>2.</b> If there are no values returned in the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable, the normal
+function return value is bound to the first symbol and all remaining symbols
+are bound <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">normal-lisp-function</font> ()
+  (+ 1 1))  <font color="#008844">; normal return value</font>
+
+&gt; (cl:multiple-value-bind (a b c)
+      (normal-lisp-function)
+    (list a b c))
+(2 NIL NIL)
+</pre>
+
+<p><b>3.</b> If there are less values than symbols, the extra symbols are
+bound <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">not-enough-values-function</font> ()
+  (cl:values 1 2))  <font color="#008844">; multiple return values</font>
+
+&gt; (cl:multiple-value-bind (a b c)
+      (not-enough-values-function)
+    (list a b c))
+(1 2 NIL)
+</pre>
+
+<p><b>4.</b> If there are more values than symbols, the extra values are
+ignored:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">too-many-values-function</font> ()
+  (cl:values 1 2 3 4 5))  <font color="#008844">; multiple return values</font>
+
+&gt; (cl:multiple-value-bind (a b c)
+      (too-many-values-function)
+    (list a b c))
+(1 2 3)
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm
new file mode 100644
index 0000000..dba7c45
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-call.htm
@@ -0,0 +1,119 @@
+<html><head>
+
+<title>cl:multiple-value-call</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-call</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-call</b></nobr> macro applies a function
+to a list of return values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-call</b> <i>function</i> [<i>expr1</i> ...])</dt>
+<dd><i>function</i> - a  Lisp expression evaluating to a function call<br>
+<i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the values returned by the function</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-call</font> (function &amp;rest exprs)
+  (let (args)
+    (dolist (expr exprs)
+      (setq  <font color="#AA5500">cl:*multiple-values*</font> nil)
+      (let* ((result (eval expr)))
+        (if <font color="#AA5500">cl:*multiple-values*</font>
+            (dolist (rslt <font color="#AA5500">*rslt*</font>) (push rslt args))
+            (push result args))))
+    (setq args (reverse args))
+    `(progn
+       (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+       (apply ,function ',args)))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-call</b></nobr> macro first evaluates the
+expressions and collects all return values in a single list, then the
+'function' form is evaluated and the resulting function call is applied to
+the list of values.</p>
+
+<p>Before applying the function to the list of values the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set to <a href="../../reference/nil.htm">NIL</a>, the final value of
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+depends on the 'function' argument.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+&gt; (funcall #'+
+    (cl:values 1 2)
+    (cl:values 3 4))
+4  <font color="#008844">; (apply #'+ (1 3))</font>
+
+&gt; (cl:multiple-value-call #'+
+    (cl:values 1 2)
+    (cl:values 3 4))
+10  <font color="#008844">; (apply #'+ (1 2 3 4))</font>
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm
new file mode 100644
index 0000000..6e3a374
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-list.htm
@@ -0,0 +1,112 @@
+<html><head>
+
+<title>cl:multiple-value-list</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-list</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-list</b></nobr> macro evaluates a Lisp
+expression and returns all values in a list:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-list</b> <i>expr</i>)</dt>
+<dd><i>expr</i> - an arbitrary Lisp expression<br>
+returns - all values in a list</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-list</font> (expr)
+  (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+  (let ((result (eval expr)))
+    (if <font color="#AA5500">cl:*multiple-values*</font>
+        '<font color="#AA5500">*rslt*</font>
+        `(list ,result))))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-list</b></nobr> macro first evaluates the
+expression. <nobr>If the</nobr> evaluation returned multiple values, the
+value of the <a href="../../reference/global-rslt.htm">*rslt*</a> variable
+is returned, otherwise the normal Lisp return value is returned in a list of
+one element.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm">&nbsp;T&nbsp;</a></nobr>
+if evaluating the expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:multiple-value-list 1)  =&gt; (1)      <font color="#008844">; cl:*multiple-values* =&gt; NIL</font>
+                                        <font color="#008844">; *rslt* =&gt; [invalid]</font>
+(cl:multiple-value-list
+  (+ 1 1))                  =&gt; (2)      <font color="#008844">; cl:*multiple-values* =&gt; NIL</font>
+                                        <font color="#008844">; *rslt* =&gt; [invalid]</font>
+(cl:multiple-value-list
+  (cl:values 1 2 3))        =&gt; (1 2 3)  <font color="#008844">; cl:*multiple-values* =&gt; T</font>
+                                        <font color="#008844">; *rslt* =&gt; (1 2 3)</font>
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm
new file mode 100644
index 0000000..d5f5fc6
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-prog1.htm
@@ -0,0 +1,106 @@
+<html><head>
+
+<title>cl:multiple-value-prog1</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-prog1</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-prog1</b></nobr> macro is like
+<a href="../../reference/prog1.htm">prog1</a>, but it can handle multiple
+values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-prog1</b> <i>expr1</i> [<i>expr2</i> ...])</dt>
+<dd><i>exprN</i> - arbitrary Lisp expressions<br>
+returns - the values returned by the first expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-prog1</font> (expr &amp;rest body)
+  (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+  (let* ((result (eval expr)))
+    (if <font color="#AA5500">cl:*multiple-values*</font>
+        `(progn ,@body
+                (setq <font color="#AA5500">*rslt*</font> ',<font color="#AA5500">*rslt*</font>
+                      <font color="#AA5500">cl:*multiple-values*</font> t)
+                ',result)
+        `(progn ,@body ',result))))
+</pre>
+
+<p>The <nobr>cl:<b>multiple-value-prog1</b></nobr> macro evaluates the first
+expression and saves all the values returned by the evaluation. <nobr>It
+then</nobr> evaluates each of the following expressions from left to right,
+discarding their values. After the evaluation is finished, the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+and <a href="../../reference/global-rslt.htm">*rslt*</a> variables are
+restored and the primary value from evaluating the fist expression is
+returned.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm">&nbsp;T&nbsp;</a></nobr>
+if evaluating the first expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm
new file mode 100644
index 0000000..3a8b701
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-value-setq.htm
@@ -0,0 +1,239 @@
+<html><head>
+
+<title>cl:multiple-value-setq</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:multiple-value-setq</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
+values to multiple variables:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>multiple-value-setq</b> <i>symbols expr</i>)</dt>
+<dd><i>symbols</i> - a list of symbols<br>
+<i>expr</i> - a Lisp expression returning one or more values<br>
+returns - the primary value returned by evaluating the expression</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defmacro <font color="#0000CC">cl:multiple-value-setq</font> (symbols expr)
+  (and (or (not (consp symbols))
+           (eq 'quote (first symbols))
+           (dolist (symbol symbols)
+             (or (symbolp symbol) (return t))))
+       (error <font color="#880000">"not a list of symbols"</font> symbols))
+  (setq <font color="#AA5500">cl:*multiple-values*</font> nil)
+  (let* ((result (eval expr))
+         (values (if <font color="#AA5500">cl:*multiple-values*</font>
+                     <font color="#AA5500">*rslt*</font>
+                     (list result)))
+         (number-of-symbols (length symbols))
+         (number-of-values  (length values))
+         (assignments (list 'setq)))
+    (dotimes (index number-of-symbols)
+      (push (nth index symbols) assignments)
+      (push (when (&lt; index number-of-values)
+              (list 'quote (nth index values)))
+            assignments))
+    (setq assignments (reverse assignments))
+    `(progn ,assignments ',result)))
+</pre>
+
+<p>The expression is evaluated, and each symbol is assigned to the
+corresponding value returned by the evaluation. <nobr>If there</nobr> are
+more symbols than values returned,
+<a href="../../reference/nil.htm">NIL</a> is assigned to the extra symbols.
+<nobr>If there</nobr> are more values than symbols, the extra values are
+discarded.</p>
+
+<p><nobr>The
+<a href="#cl-global-multiple-values">cl:*multiple-values*</a></nobr>
+variable <nobr>is <a href="../../reference/t.htm">&nbsp;T&nbsp;</a></nobr>
+if evaluating the expression returns multiple values and
+<a href="../../reference/nil.htm">NIL</a> with a normal return value.</p>
+
+<p>The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns multiple
+values to multiple variables
+<nobr>using <a href="../../reference/setq.htm">setq</a>:</nobr></p>
+
+<pre class="example">
+&gt; (macroexpand-1 '(cl:multiple-value-setq (a b c)
+                    (cl:values 1 2 3)))
+(PROGN (SETQ A (QUOTE 1)
+             B (QUOTE 2)
+             C (QUOTE 3))
+       (QUOTE 1))
+</pre>
+
+<p>The <a href="../../reference/quote.htm">quote</a>s are necessary to
+prevent 'unbound variable' and 'unbound function' errors with symbols and
+lists.</p>
+
+<p>Examples:</p>
+
+<p><b>1.</b> The <nobr>cl:<b>multiple-value-setq</b></nobr> macro assigns
+values returned by the <a href="values.htm">cl:values</a> function:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+  (cl:values 1 2 3))  <font color="#008844">; multiple return values</font>
+
+&gt; (let ((a 'A) (b 'B) (c 'C))
+    (cl:multiple-value-setq (a b c)
+      (multiple-value-function))
+    (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>2.</b> If there are no values returned in the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable, the normal
+function return value is assigned to the first symbol and all remaining
+symbols are assigned
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">normal-lisp-function</font> ()
+  (+ 1 1))  <font color="#008844">; normal return value</font>
+
+&gt; (let ((a 'A) (b 'B) (c 'C))
+    (cl:multiple-value-setq (a b c)
+      (normal-lisp-function))
+    (list a b c))
+(2 NIL NIL)
+</pre>
+
+<p><b>3.</b> If there are less values than symbols, the extra symbols are
+assigned <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">not-enough-values-function</font> ()
+  (cl:values 1 2))  <font color="#008844">; multiple return values</font>
+
+&gt; (let ((a 'A) (b 'B) (c 'C))
+    (cl:multiple-value-setq (a b c)
+      (not-enough-values-function))
+    (list a b c))
+(1 2 NIL)
+</pre>
+
+<p><b>4.</b> If there are more values than symbols, the extra values are
+ignored:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">too-many-values-function</font> ()
+  (cl:values 1 2 3 4 5))  <font color="#008844">; multiple return values</font>
+
+&gt; (let ((a 'A) (b 'B) (c 'C))
+    (cl:multiple-value-setq (a b c)
+      (too-many-values-function))
+    (list a b c))
+(1 2 3)
+</pre>
+
+<p><b>5.</b> Symbols not contained in the
+<nobr>cl:<b>multiple-value-setq</b></nobr> <nobr>symbol-list</nobr> are not
+changed:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+  (cl:values 1 2 3))  <font color="#008844">; multiple return values</font>
+
+&gt; (let ((a 'A) (b 'B) (c 'C) (d 'D) (e 'E))
+    (cl:multiple-value-setq (a b c)
+      (multiple-value-function))
+    (list a b c d e))
+(1 2 3 D E)
+</pre>
+
+<p><b>5.</b> If no bindings exist, new variables will be created:</p>
+
+<pre class="example">
+(defun <font color="#0000CC">multiple-value-function</font> ()
+  (cl:values 1 2 3))  <font color="#008844">; multiple return values</font>
+
+&gt; (let ((c 'C) (d 'D) (e 'E))
+    (cl:multiple-value-setq (a b c)
+      (multiple-value-function))
+    (list a b c d e))
+(1 2 3 D E)
+</pre>
+
+<p><b>Caution:</b> In the last example, two global variables 'a' and 'b'
+were created, while the lexical <a href="../../reference/let.htm">let</a>
+variable 'c' was assigned to the <nobr>value 3</nobr>:</p>
+
+<pre class="example">
+&gt; (list a b)
+(1 2)
+
+&gt; (list a b c)
+<font color="#AA0000">error: unbound variable - C</font>
+</pre>
+
+<p>The lexical <a href="../../reference/let.htm">let</a> binding of 'c' does
+not exist in the global <nobr>top-level</nobr>.
+<nobr>See <a href="../environment.htm">Environment</a></nobr> for more
+details about variables.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm
new file mode 100644
index 0000000..d05df73
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/multiple-values.htm
@@ -0,0 +1,181 @@
+<html><head>
+
+<title>Multiple Values</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Multiple Values</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#multiple-values">Multiple Values</a></nobr></li>
+<ul>
+<li><nobr>Nyquist/XLISP helpers</nobr></li>
+<ul>
+<li><nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a> - [Variable] - signals if a function has returned multiple values</nobr></li>
+<li><nobr><a href="debug-mv.htm">cl:debug:mv</a> - [Function] - debug multiple values</nobr></li>
+</ul>
+<li><nobr>Returning Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="values.htm">cl:values</a> - [Function] - return multiple values</nobr></li>
+<li><nobr><a href="values-list.htm">cl:values-list</a> - [Function] - return multiple values from a list</nobr></li>
+</ul>
+<li><nobr>Working with Multiple Values</nobr></li>
+<ul>
+<li><nobr><a href="multiple-value-list.htm">cl:multiple-value-list</a> - [Macro] - evaluate an expression and return all values in a list</nobr></li>
+<li><nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a> - [Macro] - bind multiple values to multiple <a href="../reference/let.htm">let</a> variables</nobr></li>
+<li><nobr><a href="multiple-value-setq.htm">cl:multiple-value-setq</a> - [Macro] - assign multiple values to multiple variables using <a href="../reference/setq.htm">setq</a></nobr></li>
+<li><nobr><a href="multiple-value-prog1.htm">cl:multiple-value-prog1</a> - [Macro] - eveluate multiple expressions, return the values of the first expression</nobr></li>
+<li><nobr><a href="multiple-value-call.htm">cl:multiple-value-call</a> - [Macro] - apply a function to multiple values collected in a list</nobr></li>
+</ul>
+</ul>
+</ol>
+
+<a name="multiple-values"></a>
+
+<hr>
+
+<h2>Multiple Values</h2>
+
+<hr>
+
+<p>This is a port of the Common List framework for passing multiple values
+from one place to another. <nobr>It is</nobr> most often used to return
+multiple values from a function with
+<a href="values.htm">cl:values</a> or to bind multiple values to multiple
+variables with
+<nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a></nobr> or
+<nobr><a href="multiple-value-setq.htm">cl:multiple-value-setq</a></nobr>.</p>
+
+<p>The multiple value functions and macros use the
+<nobr>Nyquist/XLISP</nobr>
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable to store the
+values as a list, while the
+<nobr><a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is used as a flag to indicate if a function has returned multiple
+values.</p>
+
+<p><b>What happens if a normal Lisp function are given multiple
+values?</b></p>
+
+<p>A normal Lisp function only sees the 'primary' return value, as returned
+by every Lisp function. <nobr>The additional</nobr> return values
+[including the primary return value] are stored in the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and are only read
+by the multiple value functions. This also means that with multiple values,
+the most important value should always be returned as the first value,
+because only the first value can be seen by a normal Lisp function.
+<nobr>See <a href="values.htm">cl:values</a></nobr> for examples.</p>
+
+<p><b>What happens if a function expecting multiple values is given a normal
+Lisp return value?</b></p>
+
+<p>The first symbol will be set to the function's return value, while all
+other symbol will be set to <a href="../../reference/nil.htm">NIL</a>.
+<nobr>No symbol</nobr> will be left unset. <nobr>All functions</nobr>
+expecting multiple values are protected against a wrong number of values.
+<nobr>If there</nobr> are more symbols than values, then the extra symbols
+are set to <a href="../../reference/nil.htm">NIL</a>, if there are more
+values than symbols, the extra values will be ignored.</p>
+
+<p><div class="box">
+
+<p><b>Known Limitations</b></p>
+
+<p><b>1.</b> In Nyquist/XLISP, <a href="values.htm">cl:values</a> cannot be
+used as argument to <a href="../../reference/setf.htm">setf</a>. <nobr>But
+this</nobr> is not a real problem, because the values are stored as a
+simple list in the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable, where they can be manipulated with any arbitrary Lisp
+functions, not only <nobr>with
+<a href="../../reference/setf.htm">setf</a></nobr>.</p>
+
+<p><b>2.</b> In <nobr>Common Lisp</nobr> there exists the option to return
+<nobr>'no value</nobr>' by calling the 'values' function with no arguments.
+<nobr>In Nyquist/XLISP</nobr> there is no <nobr>built-in</nobr> way to
+return '<nobr>no value</nobr>' from a function. <nobr>The symbol</nobr>
+<a href="../../reference/global-unbound.htm">*unbound*</a> cannot be used for
+this because in <nobr>Common Lisp</nobr>, if '<nobr>no value</nobr>' is
+assigned to a symbol as variable value, the new value will be
+<a href="../../reference/nil.htm">NIL</a> and not
+<a href="../../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>In Nyquist/XLISP, the <a href="values.htm">cl:values</a> function, if
+called with no arguments, always returns
+<a href="../../reference/nil.htm">NIL</a>, and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable will be
+set <nobr>to <a href="../../reference/nil.htm">NIL</a>, too:</nobr></p>
+
+<pre class="example">
+(cl:values)      =&gt; NIL  <font color="#008844">; *rslt* = NIL</font>
+(cl:values nil)  =&gt; NIL  <font color="#008844">; *rslt* = (NIL)</font>
+</pre>
+
+<p>Maybe this observation helps to write a '<nobr>no values</nobr>' test if
+anybody really <nobr>needs it</nobr>.</p>
+
+<p><b>3.</b> Neither in <nobr>Common Lisp</nobr> nor in Nyquist/XLISP is it
+possibe to return nested multiple values:</p>
+
+<pre class="example">
+(cl:values (1 (cl:values 2 3) 4)  =&gt; 1  <font color="#008844">; *rslt* = (1 2 4)</font>
+</pre>
+
+</div></p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm
new file mode 100644
index 0000000..d1b684c
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/numbers.htm
@@ -0,0 +1,104 @@
+<html><head>
+
+<title>Numbers</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Numbers</h1>
+
+<hr>
+
+<ol>
+<li><nobr><a href="#number-types">Number Types</a></nobr></li>
+<li><nobr><a href="#integer-limits">Integer Limits</a></nobr></li>
+</ol>
+
+<a name="number-types"></a>
+
+<hr>
+
+<h2>Number Types</h2>
+
+<hr>
+
+<p>In Nyquist/XLISP only two types of numers exist:</p>
+
+<ul>
+<li><nobr><b>fixnum</b>  - integer numbers</nobr></li>
+<li><nobr><b>flonum</b>  - floating-point numbers</nobr></li>
+</ul>
+
+<p>In Nyquist/XLISP, there are no ratios or complex numbers. Even if the
+math functions in this section are modelled after <nobr>Common Lisp</nobr>,
+no attempt is made to emulate these numbers.</p>
+
+<a name="integer-limits"></a>
+
+<hr>
+
+<h2>Integer Limits</h2>
+
+<hr>
+
+<pre class="example">
+(setq <font color="#AA5500">*most-positive-fixnum*</font>  2147483647)
+(setq <font color="#AA5500">*most-negative-fixnum*</font> -2147483648)
+</pre>
+
+<p><b>Note:</b> these are the limits for <nobr>32-bit</nobr> machines.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm
new file mode 100644
index 0000000..aba20c5
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rem.htm
@@ -0,0 +1,93 @@
+<html><head>
+
+<title>cl:rem</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:rem</h1>
+
+<hr>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>rem</b> <i>number divisor</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+<i>divisor</i> - an integer or floating-point number<br>
+returns - the remainder of a <a href="cl-truncate">cl:truncate</a> operation</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:rem</font> (number divisor)
+  (if (= (abs number) (abs divisor))
+      (if (and (integerp number) (integerp divisor)) 0 0.0)
+      (let ((quotient (truncate (/ (float number) divisor))))
+        (- number (* quotient divisor)))))
+</pre>
+
+<p>The <nobr>cl:<b>rem</b></nobr> function performs the
+<a href="truncate.htm">cl:truncate</a> operation on its arguments and
+returns the remainder of the <a href="truncate.htm">cl:truncate</a>
+operation. <nobr>The result</nobr> is either zero or an integer or
+<nobr>floating-point</nobr> number with the same sign as the 'number'
+argument. <nobr>If both</nobr> arguments are integer numbers, the
+<nobr>cl:<b>rem</b></nobr> function is equal to the mathematical remainder
+function.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm
new file mode 100644
index 0000000..b7e89c4
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/remainder-and-modulus.htm
@@ -0,0 +1,93 @@
+<html><head>
+
+<title>Remainder and Modulus</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Remainder and Modulus</h1>
+
+<hr>
+
+<p>The <a href="mod.htm">cl:mod</a> and <a href="rem.htm">cl:rem</a>
+function are generalizations of the modulus and remainder functions.</p>
+
+<ul>
+
+<li><p><nobr>The <a href="mod.htm">cl:mod</a></nobr> function performs the
+<a href="floor.htm">cl:floor</a> operation on its arguments and returns the
+remainder of the <a href="floor.htm">cl:floor</a> operation.</p></li>
+
+<li><p><nobr>The <a href="rem.htm">cl:rem</a></nobr> function performs the
+<a href="truncate.htm">cl:truncate</a> operation on its arguments and returns
+the remainder of the <a href="truncate.htm">cl:truncate</a> operation.</p></li>
+
+</ul>
+
+<p><nobr>The <a href="mod.htm">cl:mod</a></nobr> and
+<a href="rem.htm">cl:rem</a> functions are the modulus and remainder
+functions when the 'number' and 'divisor' arguments both are integers.</p>
+
+<pre class="example">
+(mod  13    4)  =&gt;  1          (rem  13    4)  =&gt;  1 
+(mod -13    4)  =&gt;  3          (rem -13    4)  =&gt; -1 
+(mod  13   -4)  =&gt; -3          (rem  13   -4)  =&gt;  1 
+(mod -13   -4)  =&gt; -1          (rem -13   -4)  =&gt; -1 
+(mod  13.4  1)  =&gt;  0.4        (rem  13.4  1)  =&gt;  0.4 
+(mod -13.4  1)  =&gt;  0.6        (rem -13.4  1)  =&gt; -0.4
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm
new file mode 100644
index 0000000..cf0be2c
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/round.htm
@@ -0,0 +1,141 @@
+<html><head>
+
+<title>cl:round</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:round</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>round</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward the next integer:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>round</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+  <td valign="top"><nobr>returns</nobr></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the result of runding the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+  <td></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the remainder of the round operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:round</font> (number &amp;optional (divisor
+                                  (if (integerp number) 1 1.0)
+                                  divisor-p))
+  (let* ((x (/ (float number) divisor))
+         (quotient (cond ((and (not divisor-p) (integerp number)) number)
+                         ((= number divisor) 1)
+                         ((plusp x) (truncate (+ x 0.5)))
+                         ((= (- x 0.5) (truncate (- x 0.5)))
+                          (if (minusp x)
+                              (1- (truncate x))
+                              (truncate x)))
+                         (t (truncate (- x 0.5))))))
+    (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+          <font color="#AA5500">cl:*multiple-values*</font> t)
+    quotient))
+</pre>
+
+<p>The <nobr>cl:<b>round</b></nobr> function computes a quotient that has
+been rounded to the nearest mathematical integer. <nobr>If the</nobr>
+mathematical quotient is exactly halfway between two integers, [that is, it
+has the form <nobr>'integer+1/2']</nobr>, then the quotient has been rounded
+to the even [divisible <nobr>by two]</nobr> integer.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm">&nbsp;T&nbsp;</a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p> 
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(round  3.5)     =&gt;  4
+(round -3.5)     =&gt; -3
+
+(cl:round  3.5)  =&gt;  4  <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:round -3.5)  =&gt; -4  <font color="#008844">; *rslt* = (-4  0.5)</font>
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm
new file mode 100644
index 0000000..40eaebc
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/rounding-and-truncation.htm
@@ -0,0 +1,179 @@
+<html><head>
+
+<title>Rounding and Truncation</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>Rounding and Truncation</h1>
+
+<hr>
+
+<p>The <a href="round.htm">cl:round</a>,
+<a href="truncate.htm">cl:truncate</a>,
+<a href="ceiling.htm">cl:ceiling</a> and
+<a href="floor.htm">cl:floor</a> functions divide a number by a divisor,
+returning a quotient and a remainder:</p>
+
+<p><div class="box">
+
+<p><table cellpadding="0" cellspacing="0"><tbody>
+<tr valign="top">
+  <td align="right"><nobr>(<a href="round.htm">cl:round</a>&nbsp;</nobr></td>
+  <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+  <td><nobr>&nbsp; &rArr; &nbsp;</nobr></td>
+  <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+  <td align="right"><nobr>(<a href="truncate.htm">cl:truncate</a>&nbsp;</nobr></td>
+  <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+  <td><nobr>&nbsp; &rArr; &nbsp;</nobr></td>
+  <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+  <td align="right"><nobr>(<a href="ceiling.htm">cl:ceiling</a>&nbsp;</nobr></td>
+  <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+  <td><nobr>&nbsp; &rArr; &nbsp;</nobr></td>
+  <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+<tr valign="top">
+  <td align="right"><nobr>(<a href="floor.htm">cl:floor</a>&nbsp;</nobr></td>
+  <td><nobr><i>number</i> [<i>divisor</i>])</nobr></td>
+  <td><nobr>&nbsp; &rArr; &nbsp;</nobr></td>
+  <td><nobr><i>quotient</i>, <i>remainder</i></nobr></td>
+</tr>
+</tbody></table></p>
+
+<p><nobr>&nbsp;
+<i>quotient</i> * <i>divisor</i> + <i>remainder</i> = <i>number</i></nobr></p>
+
+</div></p>
+
+<p>The 'quotient' always represents a mathematical integer. <nobr>The
+'remainder'</nobr> is an integer if both 'number' and 'divisor' arguments
+are integers, and a <nobr>floating-point</nobr> number if either the
+'number' or the 'divisor' or both are <nobr>floating-point</nobr>
+numbers.</p>
+
+<p>With Nyquist/XLISP, the 'quotient' is always directly returned by the
+function, while a list:</p>
+
+<pre class="example">
+(<font color="#0000CC">quotient remainder</font>)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm">&nbsp;T&nbsp;</a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p>
+
+Examples:
+
+<pre class="example">
+(cl:round     3.5)  =&gt;  4  <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:truncate  3.5)  =&gt;  3  <font color="#008844">; *rslt* = ( 3  0.5)</font>
+(cl:ceiling   3.5)  =&gt;  4  <font color="#008844">; *rslt* = ( 4 -0.5)</font>
+(cl:floor     3.5)  =&gt;  3  <font color="#008844">; *rslt* = ( 3  0.5)</font>
+
+(cl:round    -3.5)  =&gt; -4  <font color="#008844">; *rslt* = (-4  0.5)</font>
+(cl:truncate -3.5)  =&gt; -3  <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:ceiling  -3.5)  =&gt; -3  <font color="#008844">; *rslt* = (-3 -0.5)</font>
+(cl:floor    -3.5)  =&gt; -4  <font color="#008844">; *rslt* = (-4  0.5)</font>
+</pre>
+
+<p>Force an integer division:</p>
+
+<pre class="example">
+(cl:truncate 3.0 2.0)              =&gt; 1  <font color="#008844">; Common Lisp</font>
+(/ (truncate 3.0) (truncate 2.0))  =&gt; 1  <font color="#008844">; Nyquist/XLISP</font>
+(/ 3 2)                            =&gt; 1  <font color="#008844">; integer division</font>
+</pre>
+
+<p><div class="box">
+
+<p><b>Implementation Notes</b></p>
+
+<pre class="example">
+(defun <font color="#0000CC">name</font> (number &amp;optional (divisor (if (<font color="#AA0000">integerp</font> number) 1 1.0)))
+  ... )
+</pre>
+
+<p>The <a href="../../reference/integerp.htm">integerp</a> test in the
+parameter list signals an error if the 'number' argument is not a number,
+also the <nobr><a href="../../reference/division.htm">&nbsp;/&nbsp;</a>
+[division]</nobr> function signals errors if the 'divisor' argument is zero
+or not a number, so we do not explicitely need to test the arguments.</p>
+
+<p>The <nobr><a href="ceiling.htm">cl:ceiling</a></nobr> and
+<nobr><a href="floor.htm">cl:floor</a></nobr> functions test if 'number' is
+an integer multiple of 'divisor' by comparing the results of an integer
+division and a <nobr>floating-point</nobr> division:</p>
+
+<pre class="example">
+(let ((<font color="#AA0000">i-quotient</font> (/ (truncate number) (truncate divisor)))
+      (<font color="#AA0000">f-quotient</font> (/ (float number) divisor)))
+  (if (= <font color="#AA0000">i-quotient f-quotient</font>)
+        ...
+</pre>
+
+<p>I'm not sure if this really catches all cases <nobr>[e.g.
+regarding</nobr> floating point precision], but have found no problems so
+far.</p>
+
+</div></p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm
new file mode 100644
index 0000000..b430da3
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/sqrt.htm
@@ -0,0 +1,92 @@
+<html><head>
+
+<title>cl:sqrt</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:sqrt</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>sqrt</b></nobr> function does the same as the
+Nyquist/XLISP <a href="../../reference/sqrt.htm">sqrt</a> function, but
+also accepts integer numbers as argument:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>sqrt</b> <i>number</i>)</dt>
+<dd><i>number</i> - an integer or floating-point number<br>
+returns - the square root of <i>number</i></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:sqrt</font> (x)
+  (sqrt (float x)))
+</pre>
+
+<p>See <a href="../../reference/defun.htm">defun</a>,
+<a href="../../reference/float.htm">float</a>,
+<a href="../../reference/sqrt.htm">sqrt</a>.</p>
+
+The <nobr>cl:<b>sqrt</b></nobr> function computes the square root of its
+argument and returns the result. as a <nobr>floating-point</nobr>
+number.</p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm
new file mode 100644
index 0000000..6032dd3
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/truncate.htm
@@ -0,0 +1,135 @@
+<html><head>
+
+<title>cl:truncate</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:truncate</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>truncate</b></nobr> function
+<a href="../../reference/truncate.htm">truncate</a>s an integer or
+<nobr>floating-point</nobr> number toward zero:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>truncate</b> <i>number </i> [<i>divisor</i>])</dt>
+<dd><i>number</i> - an integer or <nobr>floating-point</nobr> number<br>
+<i>divisor</i> - an integer or <nobr>floating-point</nobr> number, except zero<br>
+<table cellpadding="0" cellspacing="0"><tbody>
+<tr>
+  <td valign="top"><nobr>returns</nobr></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the result of truncating the result of <i>number</i> divided by <i>divisor</i></td>
+</tr>
+<tr>
+  <td></td>
+  <td valign="top"><nobr>&nbsp;-&nbsp;</nobr></td>
+  <td width="100%">the remainder of the truncate operation</td>
+</tr>
+</tbody></table></dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:truncate</font> (number &amp;optional (divisor (if (integerp number) 1 1.0)))
+  (let ((quotient (truncate (/ (float number) divisor))))
+    (setq <font color="#AA5500">*rslt*</font> (list quotient (- number (* quotient divisor)))
+          <font color="#AA5500">cl:*multiple-values*</font> t)
+    quotient))
+</pre>
+
+<p>The <nobr>cl:<b>truncate</b></nobr> function computes a quotient that has
+been truncated towards zero. <nobr>That is</nobr>, the quotient represents
+the mathematical integer of the same sign as the mathematical quotient, and
+that has the greatest integral magnitude not greater than that of the
+mathematical quotient.</p>
+
+<p>The quotient is directly returned by the function, while a list:</p>
+
+<pre class="example">
+(quotient remainder)
+</pre>
+
+<p>is stored in the Nyquist/XLISP
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable and the
+<a href="global-multiple-values.htm">cl:*multiple-values*</a> is set to
+<a href="../../reference/t.htm">&nbsp;T&nbsp;</a> to signal that
+<a href="multiple-values.htm">Multiple Values</a> are returned.</p> 
+
+<nobr>See
+<a href="rounding-and-truncation.htm">Rounding and Truncation</a></nobr>
+for more details.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:truncate  3.5)  =&gt;  0  <font color="#008844">; *rslt* =&gt; ( 3  0.5)</font>
+(cl:truncate -3.5)  =&gt; -3  <font color="#008844">; *rslt* =&gt; (-3 -0.5)</font>
+</pre>
+
+<p>Force an integer division:</p>
+
+<pre class="example">
+(cl:truncate 3.1 2.6)  =&gt; 1  <font color="#008844">; *rslt* =&gt; (1 0.5)</font>
+(/ 3 2)                =&gt; 1
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm
new file mode 100644
index 0000000..52fa6e6
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values-list.htm
@@ -0,0 +1,113 @@
+<html><head>
+
+<title>cl:values-list</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:values-list</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>values-list</b></nobr> function returns the elements of a
+list unevaluated as multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>values-list</b> <i>list</i>)</dt>
+<dd><i>list</i> - a list of values<br>
+returns - the elements of the list as multiple values</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:values-list</font> (list)
+  (or (listp list) (error <font color="#880000">"not a list"</font> list))
+  (or (null list) (consp (last list)) (error <font color="#880000">"not a proper list"</font> list))
+  (setq <font color="#AA5500">*rslt*</font> list
+        <font color="#AA5500">cl:*multiple-values*</font> t)
+  (first list))
+</pre>
+
+<p>The unevaluated first value from the list is returned as the primary
+return value, and the list is assigned to the Nyquist
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable. <nobr>If
+an</nobr> an empty list is given, <a href="../../reference/nil.htm">NIL</a>
+is returned and the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable is set <nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.
+<nobr>An error</nobr> is signalled if the 'list' argument is not a list or
+if the list does not end
+<nobr>with <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set <nobr>to
+<a href="../../reference/t.htm">&nbsp;T&nbsp;</a></nobr> to indicate that
+multiple values are returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:values-list nil)         =&gt; NIL  <font color="#008844">; *rslt* = NIL</font>
+(cl:values-list '(1))        =&gt; 1    <font color="#008844">; *rslt* = (1)</font>
+(cl:values-list '(1 2))      =&gt; 1    <font color="#008844">; *rslt* = (1 2)</font>
+(cl:values-list '(1 2 3))    =&gt; 1    <font color="#008844">; *rslt* = (1 2 3)</font>
+(cl:values-list '(1 2 . 3))  =&gt; <font color="#AA0000">error: not a proper list - (1 2 . 3)</font>
+</pre>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>
diff --git a/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm
new file mode 100644
index 0000000..92a828e
--- /dev/null
+++ b/docsrc/xlisp/xlisp-doc/examples/common-lisp/values.htm
@@ -0,0 +1,160 @@
+<html><head>
+
+<title>cl:values</title>
+
+<style type="text/css">
+.example {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  width:auto;
+}
+.button {
+  color: #000000;
+  background-color: #F5F5F5;
+  padding-top: 1px;
+  padding-bottom: 1px;
+  padding-left: 4px;
+  padding-right: 8px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+  white-space: pre;
+}
+.box {
+  color: #000000;
+  padding-top: 4px;
+  padding-bottom: 4px;
+  padding-left: 16px;
+  padding-right: 16px;
+  border: #808080;
+  border-style: solid;
+  border-width: 1px;
+}
+</style>
+
+</head>
+
+<body>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+<hr>
+
+<h1>cl:values</h1>
+
+<hr>
+
+<p>The <nobr>cl:<b>values</b></nobr> function evaluates all given Lisp
+expressions and returns the results as multiple values:</p>
+
+<p><div class="box">
+
+<dl>
+<dt>(cl:<b>values</b> [<i>expr1</i> ...])</dt>
+<dd><i>exprN</i> - an arbitrary Lisp expression<br>
+returns - the results of evaluating the expressions, as multiple values</dd>
+</dl>
+
+</div></p>
+
+<pre class="example">
+(defun <font color="#0000CC">cl:values</font> (&amp;rest exprs)
+  (setq <font color="#AA5500">*rslt*</font> exprs
+        <font color="#AA5500">cl:*multiple-values*</font> t)
+  (first exprs))
+</pre>
+
+<p>The primary return value <nobr>[the result</nobr> from evaluating the
+first expression] is returned by the <nobr>cl:<b>values</b></nobr> function
+and a list with the results of evaluating all expressions is assigned to the
+Nyquist <a href="../../reference/global-rslt.htm">*rslt*</a> variable.
+<nobr>If no</nobr> expressions are given,
+<a href="..././reference/nil.htm">NIL</a> is returned and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable is set
+<nobr>to <a href="../../reference/nil.htm">NIL</a></nobr>.</p>
+
+<p><nobr>The
+<a href="global-multiple-values.htm">cl:*multiple-values*</a></nobr>
+variable is set
+<nobr>to <a href="../../reference/t.htm">&nbsp;T&nbsp;</a></nobr>
+to indicate that multiple values are returned.</p>
+
+<p>Examples:</p>
+
+<pre class="example">
+(cl:values 1 2 3)  =&gt; 1        <font color="#008844">; primary value</font>
+*rslt*             =&gt; (1 2 3)  <font color="#008844">; all values</font>
+
+(cl:values 'a 'b)  =&gt; A        <font color="#008844">; primary value</font>
+*rslt*             =&gt; (A B)    <font color="#008844">; all values</font>
+
+&gt; (cl:multiple-value-bind (a b c)
+      (cl:values 1 2 3)
+    (list a b c))
+(1 2 3)
+</pre>
+
+<p>See
+<nobr><a href="multiple-value-bind.htm">cl:multiple-value-bind</a></nobr>,
+<a href="../../reference/list.htm">list</a>,
+<a href="../../reference/global-rslt.htm">*rslt*</a>.</p>
+
+<p><div class="box">
+
+<p><b>Known Limitations</b></p>
+
+<p><b>1.</b> In Nyquist/XLISP, <nobr>cl:<b>values</b></nobr> cannot be
+used as argument to <a href="../../reference/setf.htm">setf</a>. <nobr>But
+this</nobr> is not a real problem, because the values are stored as a
+simple list in the <a href="../../reference/global-rslt.htm">*rslt*</a>
+variable, where they can be manipulated with any arbitrary Lisp
+functions, not only <nobr>with
+<a href="../../reference/setf.htm">setf</a></nobr>.</p>
+
+<p><b>2.</b> In <nobr>Common Lisp</nobr> there exists the option to return
+<nobr>'no value</nobr>' by calling the 'values' function with no arguments.
+<nobr>In Nyquist/XLISP</nobr> there is no <nobr>built-in</nobr> way to
+return '<nobr>no value</nobr>' from a function. <nobr>The symbol</nobr>
+<a href="../../reference/global-unbound.htm">*unbound*</a> cannot be used for
+this because in <nobr>Common Lisp</nobr>, if '<nobr>no value</nobr>' is
+assigned to a symbol as variable value, the new value will be
+<a href="../../reference/nil.htm">NIL</a> and not
+<a href="../../reference/global-unbound.htm">*unbound*</a>.</p>
+
+<p>In Nyquist/XLISP, the cl:<b>values</b> function, if called with no
+arguments, always returns <a href="../../reference/nil.htm">NIL</a>, and the
+<a href="../../reference/global-rslt.htm">*rslt*</a> variable will be
+set <nobr>to <a href="../../reference/nil.htm">NIL</a>, too:</nobr></p>
+
+<pre class="example">
+(cl:values)      =&gt; NIL    <font color="#008844">; primary value</font>
+*rslt*           =&gt; NIL    <font color="#008844">; all values</font>
+
+(cl:values nil)  =&gt; NIL    <font color="#008844">; primary value</font>
+*rslt*           =&gt; (NIL)  <font color="#008844">; all values</font>
+</pre>
+
+<p>Maybe this observation helps to write a '<nobr>no values</nobr>' test if
+anybody really <nobr>needs it</nobr>.</p>
+
+</div></p>
+
+<p><nobr>&nbsp;&nbsp;<a href="#top">Back to top</a></nobr></p>
+
+<hr>
+
+<a href="../../start.htm">Nyquist / XLISP 2.0</a>&nbsp; -&nbsp;
+<a href="../../manual/contents.htm">Contents</a> |
+<a href="../../tutorials/tutorials.htm">Tutorials</a> |
+<a href="../examples.htm">Examples</a> |
+<a href="../../reference/reference-index.htm">Reference</a>
+
+</body></html>