diff options
Diffstat (limited to 'doc/index.html')
| -rw-r--r-- | doc/index.html | 109 |
1 files changed, 52 insertions, 57 deletions
diff --git a/doc/index.html b/doc/index.html index 62a5bfd..91c9ec6 100644 --- a/doc/index.html +++ b/doc/index.html @@ -48,7 +48,7 @@ href="http://weitz.de/html-template/">HTML-TEMPLATE</a>. I wrote this one in 2002 although at least Tim Bradshaw's <a href="http://www.cliki.net/htout">htout</a> and <a href="http://opensource.franz.com/aserve/aserve-dist/doc/htmlgen.html">AllegroServe's -HTML generation facilities</a> by John Foderaro of Franz Inc. where +HTML generation facilities</a> by John Foderaro of Franz Inc. were readily available. Actually, I don't remember why I had to write my own library - maybe just because it was fun and didn't take very long. The syntax was obviously inspired by htout although it is slightly @@ -60,8 +60,7 @@ CL-WHO macros will usually be a sequence of <code>WRITE-STRING</code> forms for constant parts of the output interspersed with arbitrary code inserted by the user of the macro. CL-WHO will make sure that there aren't two adjacent <code>WRITE-STRING</code> forms with -constant strings - see -examples <a href="#show-html-expansion">below</a>. CL-WHO's output is +constant strings. CL-WHO's output is either XHTML (default) or 'plain' (SGML) HTML — depending on what you've set <a href="#html-mode"><code>HTML-MODE</code></a> to. <p> @@ -74,7 +73,7 @@ It comes with a <a href="http://www.opensource.org/licenses/bsd-license.php">BSD-style license</a> so you can basically do with it whatever you want. <p> -CL-WHO is used by <a href="http://clutu.com/">clutu</a>, <a href="http://ergoweb.de/">ERGO</a>, and <a href="http://heikestephan.de/">Heike Stephan</a>. +CL-WHO is for example used by <a href="http://clutu.com/">clutu</a> and <a href="http://heikestephan.de/">Heike Stephan</a>. <p> <font color=red>Download shortcut:</font> <a href="http://weitz.de/files/cl-who.tar.gz">http://weitz.de/files/cl-who.tar.gz</a>. @@ -90,7 +89,6 @@ CL-WHO is used by <a href="http://clutu.com/">clutu</a>, <a href="http://ergoweb <ol> <li><a href="#with-html-output"><code>with-html-output</code></a> <li><a href="#with-html-output-to-string"><code>with-html-output-to-string</code></a> - <li><a href="#show-html-expansion"><code>show-html-expansion</code></a> <li><a href="#*attribute-quote-char*"><code>*attribute-quote-char*</code></a> <li><a href="#*prologue*"><code>*prologue*</code></a> <li><a href="#*html-empty-tag-aware-p*"><code>*html-empty-tag-aware-p*</code></a> @@ -106,7 +104,6 @@ CL-WHO is used by <a href="http://clutu.com/">clutu</a>, <a href="http://ergoweb <li><a href="#*escape-char-p*"><code>*escape-char-p*</code></a> <li><a href="#escape-string-minimal"><code>escape-string-minimal</code></a> <li><a href="#escape-string-minimal-plus-quotes"><code>escape-string-minimal-plus-quotes</code></a> - <li><a href="#escape-string-iso-8859"><code>escape-string-iso-8859</code></a> <li><a href="#escape-string-iso-8859-1"><code>escape-string-iso-8859-1</code></a> <li><a href="#escape-string-all"><code>escape-string-all</code></a> <li><a href="#escape-char-minimal"><code>escape-char-minimal</code></a> @@ -146,7 +143,7 @@ together with the Lisp code generated by CL-WHO and the resulting HTML output. <tr> <td bgcolor="#e0e0e0" valign=top><pre> -<font color="orange">;; Code generated by CL-WHO</font> +<font color="orange">;; code generated by CL-WHO (simplified)</font> (let ((*http-stream* *http-stream*)) (progn @@ -185,7 +182,7 @@ together with the Lisp code generated by CL-WHO and the resulting HTML output. <tr> <td bgcolor="#e0e0e0" valign=top><pre> -<font color="orange">;; Code generated by CL-WHO</font> +<font color="orange">;; code generated by CL-WHO (simplified)</font> (let ((*http-stream* *http-stream*)) (progn @@ -226,7 +223,7 @@ together with the Lisp code generated by CL-WHO and the resulting HTML output. <tr> <td bgcolor="#e0e0e0" valign=top><pre> -<font color="orange">;; Code generated by CL-WHO</font> +<font color="orange">;; code generated by CL-WHO (simplified)</font> (let ((*http-stream* *http-stream*)) (progn @@ -256,9 +253,9 @@ together with the Lisp code generated by CL-WHO and the resulting HTML output. CL-WHO together with this documentation can be downloaded from <a href="http://weitz.de/files/cl-who.tar.gz">http://weitz.de/files/cl-who.tar.gz</a>. The -current version is 0.11.0. +current version is 0.2.0. <p> -The preferred method to compile and load Hunchentoot is via <a href="http://www.cliki.net/asdf">ASDF</a>. +The preferred method to compile and load CL-WHO is via <a href="http://www.cliki.net/asdf">ASDF</a>. <p> If you're on <a href="http://www.debian.org/">Debian</a> you can probably use @@ -274,6 +271,12 @@ Luís Oliveira maintains a <a href="http://darcs.net/">darcs</a> repository of CL-WHO at <a href="http://common-lisp.net/~loliveira/ediware/">http://common-lisp.net/~loliveira/ediware/</a>. +<p> +You can run a test suite which tests <em>some</em> (but +not <em>all</em>) aspects of the library with +<pre> +(asdf:oos 'asdf:test-op :cl-who) +</pre> <br> <br><h3><a name="mail" class=none>Support and mailing lists</a></h3> @@ -343,7 +346,7 @@ is transformed into an (X)HTML <b>tag</b> of the same (usually <href="#*downcase <table border=0 cellpadding=2 cellspacing=3><tr><td><pre>(:table :border 3) <font color="red">=></font> (write-string "<table border='3' />" s)</pre></td></tr></table> - <li>If it is any other form it will be left as is and later evaluated at run time and printed with <a + <li>If it is any other form it will be left as is and later evaluated at run time and printed like with <a href="http://www.lispworks.com/reference/HyperSpec/Body/f_wr_pr.htm"><code>PRINC</code></a> <em>unless</em> the value is <code>T</code> or <code>NIL</code> which will be treated as above. (It is the application developer's job to provide the correct <a href="http://www.lispworks.com/reference/HyperSpec/Body/26_glo_p.htm#printer_control_variable">printer control variables</a>.) <table border=0 cellpadding=2 cellspacing=3><tr><td><pre><font color="orange">;; simplified example, see function CHECKBOX below @@ -403,11 +406,10 @@ CHECKBOX <table border=0 cellpadding=2 cellspacing=3><tr><td><pre>:hr <font color="red">=></font> (write-string "<hr />" s)</pre></td></tr></table> - <li>A form which is neither a string nor a keyword nor a list beginning with a keyword will be left as is except for the following <em>substitutions</em>: + <li>A form which is neither a string nor a keyword nor a list beginning with a keyword will be left as is except for the following <a href="http://www.lispworks.com/documentation/HyperSpec/Body/s_flet_.htm#macrolet">local macros</a>: <ul> - <li>Forms that look like <code>(<b>str</b> <i>form1</i> <i>form*</i>)</code> will be substituted with - <span style="white-space: nowrap"><code>(let ((result <i>form1</i>)) (when result (princ result s)))</code></span>. <br> - (Note that all forms behind <code><i>form1</i></code> are ignored.) + <li>Forms that look like <code>(<b>str</b> <i>form</i>)</code> will be substituted with + <span style="white-space: nowrap"><code>(let ((result <i>form</i>)) (when result (princ result s)))</code></span>. <table border=0 cellpadding=2 cellspacing=3><tr><td><pre>(loop for i below 10 do (str i)) <font color="red">=></font> (loop for i below 10 do @@ -417,10 +419,10 @@ CHECKBOX <li>Forms that look like <code>(<b>fmt</b> <i>form*</i>)</code> will be substituted with <code>(format s <i>form*</i>)</code>. <table border=0 cellpadding=2 cellspacing=3><tr><td><pre>(loop for i below 10 do (fmt "~R" i)) <font color="red">=></font> (loop for i below 10 do (format s "~R" i))</pre></td></tr></table> - <li>Forms that look like <code>(<b>esc</b> <i>form1</i> <i>form*</i>)</code> will be substituted with - <span style="white-space: nowrap"><code>(let ((result <i>form1</i>)) (when result (write-string (<a href="#escape-string">escape-string</a> result s))))</code></span>. + <li>Forms that look like <code>(<b>esc</b> <i>form</i>)</code> will be substituted with + <span style="white-space: nowrap"><code>(let ((result <i>form</i>)) (when result (write-string (<a href="#escape-string">escape-string</a> result s))))</code></span>. - <li>If a form looks like <code>(<b>htm</b> <i>form*</i>)</code> then each of the <code><i>forms</i></code> will be subject to the transformation rules we're just describing. + <li>If a form looks like <code>(<b>htm</b> <i>form*</i>)</code> then each of the <code><i>forms</i></code> will be subject to the transformation rules we're just describing, i.e. this is the body is wrapped with another invocation of <a href="#with-html-output"><code>WITH-HTML-OUTPUT</code></a>. <table border=0 cellpadding=2 cellspacing=3><tr><td><pre>(loop for i below 100 do (htm (:b "foo") :br)) <font color="red">=></font> (loop for i below 100 do (progn (write-string "<b>foo</b><br />" s)))</pre></td></tr></table> @@ -438,8 +440,35 @@ CL-WHO exports the following symbols: <p><br>[Macro] <br><a class=none name="with-html-output"><b>with-html-output</b> <i>(var <tt>&optional</tt> stream <tt>&key</tt> prologue indent) declaration* form*</i> => <i>result*</i></a> -<blockquote><br> -This is the main macro of CL-WHO. It will transform its body by the transformation rules described in <a href="#syntax"><em>Syntax and Semantics</em></a> such that the output generated is sent to the stream denoted by <code><i>var</i></code> and <code><i>stream</i></code>. <code><i>var</i></code> must be a symbol. If <code><i>stream</i></code> is <code>NIL</code> it is assumed that <code><i>var</i></code> is already bound to a stream, if <code><i>stream</i></code> is not <code>NIL</code> <code><i>var</i></code> will be bound to the form <code><i>stream</i></code> which will be evaluated at run time. <code><i>prologue</i></code> should be a string (or <code>NIL</code> for the empty string which is the default) which is guaranteed to be the first thing sent to the stream from within the body of this macro. If <code><i>prologue</i></code> is <code>T</code> the prologue string is the value of <a href="#*prologue*"><code>*PROLOGUE*</code></a>. CL-WHO will usually try not to insert any unnecessary whitespace in order to save bandwidth. However, if <code><i>indent</i></code> is <em>true</em> line breaks will be inserted and nested tags will be intended properly. The value of <code><i>indent</i></code> - if it is an integer - will be taken as the initial indentation. If it is not an integer it is assumed to mean <code>0</code>. The <code><i>results</i></code> are the values returned by the <code><i>forms</i></code>. +<blockquote><br> This is the main macro of CL-WHO. It will transform +its body by the transformation rules described +in <a href="#syntax"><em>Syntax and Semantics</em></a> such that the +output generated is sent to the stream denoted +by <code><i>var</i></code> +and <code><i>stream</i></code>. <code><i>var</i></code> must be a +symbol. If <code><i>stream</i></code> is <code>NIL</code> it is +assumed that <code><i>var</i></code> is already bound to a stream, +if <code><i>stream</i></code> is +not <code>NIL</code> <code><i>var</i></code> will be bound to the +form <code><i>stream</i></code> which will be evaluated at run +time. <code><i>prologue</i></code> should be a string +(or <code>NIL</code> for the empty string which is the default) which +is guaranteed to be the first thing sent to the stream from within the +body of this macro. If <code><i>prologue</i></code> is <code>T</code> +the prologue string is the value +of <a href="#*prologue*"><code>*PROLOGUE*</code></a>. CL-WHO will +usually try not to insert any unnecessary whitespace in order to save +bandwidth. However, if <code><i>indent</i></code> is <em>true</em> +line breaks will be inserted and nested tags will be indented +properly. The value of <code><i>indent</i></code> - if it is an +integer - will be taken as the initial indentation. If it is not an +integer it is assumed to mean <code>0</code>. (But note that +indentation might change the semantics of the generated HTML. This is +for example the case for the <code>PRE</code> +and <code>TEXTAREA</code> tags, and in certain situations additional +whitespace might also change the layout of tables.) +The <code><i>results</i></code> are the values returned by +the <code><i>forms</i></code>. <p> Note that the keyword arguments <code><i>prologue</i></code> and <code><i>indent</i></code> are used at macro expansion time. @@ -473,7 +502,7 @@ Note that the keyword arguments <code><i>prologue</i></code> and <code><i>indent This is just a thin wrapper around <a href="#with-html-output"><code>WITH-HTML-OUTPUT</code></a>. Indeed, the wrapper is so thin that the best explanation probably is to show its definition: <pre> (defmacro with-html-output-to-string ((var &optional string-form - &key (element-type 'character) + &key (element-type ''character) prologue indent) &body body) @@ -486,34 +515,6 @@ into Lisp code which creates the corresponding HTML as a string." Note that the <code><i>results</i></code> of this macro are determined by the behaviour of <a href="http://www.lispworks.com/reference/HyperSpec/Body/m_w_out_.htm"><code>WITH-OUTPUT-TO-STRING</code></a>. </blockquote> -<p><br>[Macro] -<br><a class=none name="show-html-expansion"><b>show-html-expansion</b> <i>(var <tt>&optional</tt> stream <tt>&key</tt> prologue indent) declaration* form*</i> => <tt><no values></tt></a> - -<blockquote><br> -This macro is intended for debugging purposes. It'll print to <code>*STANDARD-OUTPUT*</code> the code which would have been generated by <a href="#with-html-output"><code>WITH-HTML-OUTPUT</code></a> had it been invoked with the same arguments. - -<pre> -* (show-html-expansion (s) - (:html - (:body :bgcolor "white" - (:table - (:tr - (dotimes (i 5) - (htm (:td :align "left" - (str i))))))))) -(LET ((S S)) - (PROGN - (WRITE-STRING - "<html><body bgcolor='white'><table><tr>" S) - (DOTIMES (I 5) - (PROGN - (WRITE-STRING "<td align='left'>" S) - (PRINC I S) - (WRITE-STRING "</td>" S))) - (WRITE-STRING "</tr></table></body></html>" S))) -</pre> -</blockquote> - <p><br>[Special variable] <br><a class=none name="*attribute-quote-char*"><b>*attribute-quote-char*</b></a> @@ -629,8 +630,6 @@ This is the default for the <code><i>test</i></code> keyword argument to <a href <br>[Function] <br><a class=none name="escape-string-iso-8859-1"><b>escape-string-iso-8859-1</b> <i>string</i> => <i>escaped-string</i></a> <br>[Function] -<br><a class=none name="escape-string-iso-8859"><b>escape-string-iso-8859</b> <i>string</i> => <i>escaped-string</i></a> -<br>[Function] <br><a class=none name="escape-string-all"><b>escape-string-all</b> <i>string</i> => <i>escaped-string</i></a> <br>[Function] <br><a class=none name="escape-char-minimal"><b>escape-char-minimal</b> <i>character</i> => <i>escaped-string</i></a> @@ -661,10 +660,6 @@ functions are defined in a way similar to this one: (or (find char "<>&'\"") (> (char-code char) 255))))) -(defun escape-string-iso-8859 (string) - "Identical to ESCAPE-STRING-ISO-8859-1. Kept for backward compatibility." - (escape-string-iso-8859-1 string)) - (defun escape-string-all (string) "Escapes all characters in STRING which aren't in the 7-bit ASCII character set." @@ -800,7 +795,7 @@ Thanks to Stefan Scholl for the 'old school' patch. Thanks to Mac Chan for several useful additions. <p> -$Header: /usr/local/cvsrep/cl-who/doc/index.html,v 1.58 2007/08/24 08:01:40 edi Exp $ +$Header: /usr/local/cvsrep/cl-who/doc/index.html,v 1.68 2009/03/09 21:54:11 edi Exp $ <p><a href="http://weitz.de/index.html">BACK TO MY HOMEPAGE</a> </body> |