Commit 5129f152 authored by Marco Antoniotti's avatar Marco Antoniotti 💬
Browse files

Documentation updated.

parent 34f0a81c
......@@ -35,33 +35,33 @@
<h3>
Arguments and Values:
</h3>
<ul style="list-style-type: none">
<ul>
<li style="list-style-type: none">
<i>
<code>
SYNTAX
XHTML-FORM
</code>
</i>
:
a T.
a Sexp representing some (X)HTML code.
</li>
<li style="list-style-type: none">
<i>
<code>
XHTML-FORM
SYNTAX
</code>
</i>
:
a T.
a HTML-SEXP-SYNTAX designator; defaults to *DEFAULT-HTML-SEXP-SYNTAX*
</li>
<li style="list-style-type: none">
<i>
<code>
result
FORM
</code>
</i>
:
a FORM.
a FORM
</li>
</ul>
<h2>
......
<head>
<title>
:
MACRO
with-html-syntax-output
</title>
<link rel="stylesheet" href="../helambdap.css" />
</head>
<body>
<h1>
<i>
MACRO
</i>
<strong>
with-html-syntax-output
</strong>
</h1>
<h2>
Package:
</h2>
<p>
<code>
IT.UNIMIB.DISCO.MA.XHTMLAMBDA
</code>
</p>
<h2>
Syntax:
</h2>
<div>
<p>
<pre>
<strong style="color: red">with-html-syntax-output</strong> (<i>STREAM</i> <span style="color: blue">&KEY</span> <i>PRINT-PRETTY</i> <i>SYNTAX</i>) <i>HTML</i> &rArr; <i>form</i></pre>
</p>
</div>
<h3>
Arguments and Values:
</h3>
<ul>
<li style="list-style-type: none">
<i>
<code>
STREAM
</code>
</i>
:
a STREAM
</li>
<li style="list-style-type: none">
<i>
<code>
PRINT-PRETTY
</code>
</i>
:
a generalized boolean; defaults to *print-pretty*
</li>
<li style="list-style-type: none">
<i>
<code>
SYNTAX
</code>
</i>
:
a HTML-SEXP-SYNTAX value; defaults to *default-html-sexp-syntax*
</li>
<li style="list-style-type: none">
<i>
<code>
FORM
</code>
</i>
:
a FORM
</li>
</ul>
<h2>
Description:
</h2>
<p>
Writes out a (X)HTML form to a stream.
</p>
<p>
The writing is done using the XHTMLambda pretty-print dispatch table,
which is used if PRINT-PRETTY is non-NIL. The HTML form is
represented using the appropriate SYNTAX.
</p>
<h2>
Examples:
</h2>
<pre>
cl-prompt&gt; (&lt;:with-html-syntax-output (*standard-output* :syntax :standard
:print-pretty t)
(&lt;:p () (&lt;:code () "for i in $ZZ do ...")))
&lt;p&gt;
&lt;code&gt;
for i in $ZZ do ...
&lt;/code&gt;
&lt;/p&gt;
&lt;p&gt;&lt;code&gt;for i in $ZZ do ...&lt;/code&gt;&lt;/p&gt;
</pre>
<h2>
See Also:
</h2>
<p>
*default-html-sexp-syntax* and html-sexp-syntax
</p>
</body>
\ No newline at end of file
......@@ -19,6 +19,24 @@
IT.UNIMIB.DISCO.MA.XHTMLAMBDA
</h3>
<div class="helambdap_navmap">
<h4>
Parameters
</h4>
<p class="navindex">
<a href="Parameter-*DEFAULT-HTML-SEXP-SYNTAX*.htm"
target="dictionary-entries_frame">
*default-html-sexp-syntax*
</a>
</p>
<h4>
Types
</h4>
<p class="navindex">
<a href="Type-HTML-SEXP-SYNTAX.htm"
target="dictionary-entries_frame">
html-sexp-syntax
</a>
</p>
<h4>
Macros
</h4>
......@@ -28,6 +46,12 @@
htmlise
</a>
</p>
<p class="navindex">
<a href="Macro-WITH-HTML-SYNTAX-OUTPUT.htm"
target="dictionary-entries_frame">
with-html-syntax-output
</a>
</p>
</div>
</body>
</html>
<head>
<title>
Parameter *default-html-sexp-syntax*
</title>
<link rel="stylesheet" href="../helambdap.css" />
</head>
<body>
<h1>
<i>
Parameter
</i>
<strong>
*default-html-sexp-syntax*
</strong>
</h1>
<h2>
Package:
</h2>
<p>
IT.UNIMIB.DISCO.MA.XHTMLAMBDA
</p>
<h2>
Description:
</h2>
<p>
The default HTML syntax used in the SEXP-based coding of HTML.
</p>
<p>
The variable can take on the values of the type HTML-SEXP-SYNTAX,
i.e., :COMPACT or :STANDARD. The default is :COMPACT.
</p>
<h2>
See Also:
</h2>
<p>
Type html-sexp-syntax
</p>
</body>
\ No newline at end of file
<head>
<title>
:
TYPE
html-sexp-syntax
</title>
<link rel="stylesheet" href="../helambdap.css" />
</head>
<body>
<h1>
<i>
TYPE
</i>
<strong>
html-sexp-syntax
</strong>
</h1>
<h2>
Package:
</h2>
<p>
<code>
IT.UNIMIB.DISCO.MA.XHTMLAMBDA
</code>
</p>
<h2>
Syntax:
</h2>
<div>
<p>
<pre>
<strong style="color: red">html-sexp-syntax</strong> </pre>
</p>
</div>
<h2>
Description:
</h2>
<p>
The (enumerated) type of 'syntaxes' for the HTML Sexp-based representation.
</p>
<p>
The actual type is defined to be (member :compact :standard).
</p>
<h2>
Examples:
</h2>
<pre>
:COMPACT
tag
(tag . body)
((tag . attribute) . body)
:STANDARD
tag
(tag attributes . body)
</pre>
</body>
\ No newline at end of file
......@@ -12,14 +12,14 @@
<body style="margin: 0pt 0pt 0pt 0pt;">
<div class="copyright">
<strong>
(X)TM&Lambda
(X)HTM&Lambda;
</strong>
documentation produced with
HE&Lambda;P
<br />
<!-- hhmts start -->
Last modified:
Thu Jun 27 23:11:29 GMT5 2013
Fri Jun 28 15:41:5 GMT5 2013
<!-- hhmts end -->
<br />
&copy; 2013, Marco Antoniotti, all rights reserved.
......
......@@ -13,7 +13,7 @@
<div class="header"
style="padding-left: 2em; padding-top: 5pt; color: #41286f; font-size: 14pt">
<strong>
(X)TM&Lambda
(X)HTM&Lambda;
</strong>
<div class="navigation" style="right: 2m">
<a href="../index.htm"
......
......@@ -7,7 +7,7 @@
<html>
<head>
<title>
(X)TM&Lambda
(X)HTM&Lambda;
</title>
<link rel="stylesheet" href="../helambdap.css" />
</head>
......
......@@ -12,14 +12,14 @@
<body style="margin: 0pt 0pt 0pt 0pt;">
<div class="copyright">
<strong>
(X)TM&Lambda
(X)HTM&Lambda;
</strong>
documentation produced with
HE&Lambda;P
<br />
<!-- hhmts start -->
Last modified:
Thu Jun 27 23:11:29 GMT5 2013
Fri Jun 28 15:41:5 GMT5 2013
<!-- hhmts end -->
<br />
&copy; 2013, Marco Antoniotti, all rights reserved.
......
......@@ -13,7 +13,7 @@
<div class="header"
style="padding-left: 2em; padding-top: 5pt; color: #41286f; font-size: 14pt">
<strong>
(X)TM&Lambda
(X)HTM&Lambda;
</strong>
<div class="navigation" style="right: 2m">
<a href="index.htm"
......
......@@ -13,7 +13,40 @@
<link rel="stylesheet" href="helambdap.css" />
</head>
<body>
<ul />
<ul>
<li style="list-style-type: none">
<a href="introduction.htm#Printing XHTM&Lambda;"
target="introduction_frame">
Printing XHTM&Lambda;
</a>
</li>
<li style="list-style-type: none">
<a href="introduction.htm#Yet another<sup><i>n</i></sup> HTML generation
library"
target="introduction_frame">
Yet another<sup><i>n</i></sup> HTML generation
library
</a>
</li>
<li style="list-style-type: none">
<a href="introduction.htm#XHTM&Lambda; Syntax"
target="introduction_frame">
XHTM&Lambda; Syntax
</a>
</li>
<li style="list-style-type: none">
<a href="introduction.htm#Availability"
target="introduction_frame">
Availability
</a>
</li>
<li style="list-style-type: none">
<a href="introduction.htm#References"
target="introduction_frame">
References
</a>
</li>
</ul>
</body>
</html>
......
......@@ -7,7 +7,7 @@
<html>
<head>
<title>
(X)TM&Lambda
(X)HTM&Lambda;
</title>
<link rel="stylesheet" href="helambdap.css" />
</head>
......
<!-- introduction.htm -->
<!DOCTYPE HTML PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<title>Printing XHTM&Lambda;</title>
<link rel="stylesheet" href="helambdap.css">
</head>
<body>
<h1><a name="Printing XHTM&Lambda;">Printing XHTM&Lambda;</a></h1>
<p>I finally bit the bullet! I swear I tried! I pestered people! I
failed. I.e., I failed to like any of the &quot;major&quot; HTML-producing
libraries &quot;out there&quot; and so I rolled up my own. In the process, I
(re)learned a few things and I believe I made good use of parts of the
language that are usually overlooked.</p>
<h2>My problems with the other libraries</h2>
<p>This section must start with an apology.</p>
<p>All the libraries I tried, are very fine and sophisticated pieces
of software that <b>do</b> solve problems. Alas, myself being a
rotten Lisper, I found that I &quot;needed something different&quot; (read:
&quot;something I wrote&quot;). Therefore, the comments you'll read below are
<b>not</b> to be intended as general statements about such libraries,
but <b>only</b> as testimony of my whims.</p>
<p>The libraires I looked at are <a
href="http://www.cl-http.org:8001/cl-http/">CL-HTTP</a>, <a
href="http://weitz.de/cl-who/">CL-WHO</a> and variations of TFEB's <a
href="http://www.tfeb.org/lisp/hax.html#HTOUT">htout</a> and Franz <a
href="http://allegroserve.sourceforge.net/aserve-dist/doc/htmlgen.html">htmlgen</a>,
especially in the XHTML-GENERATOR version that comes with <a
href="http://common-lisp.net/project/cxml/">CXML</a>.</p>
<p>As I said, my idiosyncrasies with the the whole business of CL
programming found problems with each of these otherwise fine
libraries. More specifically, I found <a
href="http://www.cl-http.org:8001/cl-http/">CL-HTTP</a> too heavy to
use just to generate HTML. One gripe I had with CL-WHO is that it did
not handle <em>pretty printing</em> of HTML well (indentation is off
in &quot;recursive&quot; use); more or less the same can be said of htout and
htmlgen. CXML XHTML-GENERATOR is essentially a &quot;round-trip&quot; utilities
and it makes your life quite unhappy if you are trying to use simple
HTML entities like - surprise - &lambda; and &Lambda;.</p>
<p>CL-WHO, htout, htmlgen and XHTML-GENERATOR all take the approach
summarized as <em>I will compile a SExp representing &quot;HTML&quot; and will
generate - in line - a set of specialized writing calls (yes: mostly
<code>WRITE</code> and <code>WRITE-STRING</code>).</em> (Cfr. the
examples in CL-WHO documentation; .)</p>
<p>There is nothing wrong with this approach, but it makes the
resulting library and overall implementation more monolithic and it
does not leverage some of the bells and whistles that you have
available in <strong>CL</strong>.
Thus I rolled my own (and I called it <b>XHTM&Lambda;</b>).
</p>
<h1><a name="Yet another<sup><i>n</i></sup> HTML generation
library">Yet another<sup><i>n</i></sup> HTML generation
library</a></h1>
<p>My approach to HTML (or XML) generation is the following:
<ol>
<li>HTML (or XML!) element need not be &quot;lists&quot; or &quot;conses&quot;; they can
be bona-fide objects, i.e., structures.</li>
<li><code>print-object</code>, and, above all, the <em>pretty
printer</em> are my friends.</li>
<li><code>*print-pretty*</code>, <code>*print-readably*</code> etc.,
are more than useful.</li>
</ol>
<p>There are a few consequences from this choices and they should be
exposed. Before doing that, let's see what happens in the basic
case.</p>
<p>The basic definition in the implementation of XHTM&Lambda; is the
representation of a HTML (or XML!) &quot;element&quot;. It is very
simple and it does accommodate the HTML5 bits and pieces.</p>
<p>
<pre><code>
(defstruct (<span style="color: red"><b>element</b></span> (:constructor %element))
(tag nil :type symbol)
(attributes () :type list)
(content () :type list))</code></pre></p>
<p><code>tag</code> is ... the tag, <code>attributes</code> is a
p-list and <code>content</code> is a possibly empty list of other
<code>element</code>s.</p>
<h2>&quot;Printing&quot; an element</h2>
<p>Let's forget a minute about the constructor and let's instead
concentrate on an element &quot;printing&quot; process. The main
entry point is a <code>print-object</code> method.</p>
<p>
<pre><code>
(defmethod <b>print-object</b> ((e element) (s stream))
(let ((tag (element-tag e))
(attributes (element-attributes e))
(content (element-content e))
)
(cond (<b>*print-pretty*</b>
(<b><span style="color: blue">pprint-xhtml</span></b> s e))
(<b>*print-readably*</b>
(format s <span style="color: green">"#S(~S :TAG ~S :ATTRIBUTES ~S :CONTENT ~S)"</span>
(type-of e)
tag
attributes
content))
(t
<i><span style="color: red">;; Format string showing-off!!!!</span></i>
(format s <span style="color: green">"<~A~{ ~A=\"~A\"~}~:[ />~;>~:*~{~S~^ ~}&lt;/~3:*~A>~]"</span>
(string-downcase tag)
attributes
content
)
))
))</code></pre>
</p>
<p>The method is rather straightforward (apart from the last
<code>format</code> string, which does many things at once: (1) writes
the attributes, (2) checks whether there is content and if not closes
the tag, otherwise backs up to print it, and (3) finally it backs up
again to the tag to print the proper closing element). Note that, in
order to properly and nicely printing the element, if
<code>*print-pretty*</code> is non-NIL, then the function
<code>pprint-xhtml</code> is called.</p>
<h3>Using the pretty printer</h3>
<p>It may be just me, but I believe that the pretty printer is an
under-used part of the <strong>CL</strong> standard. Therefore, I set
out to use it heavily in order to get &quot;properly indented&quot;
(meaning, the way I like it) (X)HTML. The function <span
style="color: blue"><b><code>pprint-xhtml</code></b></span> does
that.</p>
<p>
<pre><code>
(defun <span style="color: blue"><b>pprint-xhtml</b></span> (s xhtml-element)
(declare (type stream s)
(type element xhtml-element))
(let ((tag (string-downcase (element-tag xhtml-element)))
(attrs (element-attributes xhtml-element))
(content (element-content xhtml-element))
)
(<span style="color: maroon"><b>pprint-logical-block</b></span> (s content) <span style="color: red">; (1)</span>
(<span style="color: maroon"><b>pprint-logical-block</b></span> (s content) <span style="color: red">; (2)</span>
(format s <span style="color: green">"&lt;~A<span style="color: maroon"><b>~@&lt;</b></span>~{~^ ~A=\"~S\"<span style="color: maroon"><b>~^~_</b></span>~}<span style="color: maroon"><b>~:&gt;</b></span>"</span> tag attrs) <span style="color: red">; (3)</span>
(when content
(write-char #\> s)
(<span style="color: maroon"><b>pprint-newline</b></span> :mandatory s)
(format s <span style="color: green">"~{~4,0:T <span style="color: maroon"><b>~:W~_</b></span>~}"</span> content)
))
(if content
(format s <span style="color: green">"<span style="color: maroon"><b>~0I</b></span>&lt;/~A&gt;"</span> tag)
(format s <span style="color: green">" /&gt;"</span>))
)))
</code></pre></p>
<p>The function requires a few explanations (of course, if you are a
&quot;pretty printer black-belt&quot; this may be a bit boring).
First of all, a display of what I want to obtain.</p>
<p><pre>
&lt;body style="color: red"&gt;
&lt;p&gt;
Some text here
&lt;ul&gt;
&lt;li&gt;
Line 1
&lt;/li&gt;
&lt;/ul&gt;
&lt;/p&gt;
&lt;/body&gt;</pre></p>
<p>This indentation may not be the best possible and there are some
pitfalls, but it is better than what you get with the other libraries.
But how does the function <span style="color:
blue"><b><code>pprint-xhtml</code></b></span> achieve this result
while interacting with the pretty printing machinery?</p>
<p>The function <span style="color:
blue"><b><code>pprint-xhtml</code></b></span> uses three <em>logical
blocks</em>. Two for the element and a third for the attributes. The
logical block for the attributes is introduced in the
<code>format</code> string using the <span style="color:
maroon"><b><code>~@&lt;&nbsp;...&nbsp;~:&gt;</code></b></span>
directive. Note also the conditional newline <span style="color:
maroon"><b><code>~_</code></b></span> in the list iteration
construction <span style="color:
maroon"><b><code>~{&nbsp;...&nbsp;~}</code></b></span>. The other two
<span style="color:
maroon"><b><code>pprint-logical-block</code></b></span> establish the
fence for the whole element and for the &quot;inside&quot; of the
same. The <em>outer</em> <span style="color:
maroon"><b><code>pprint-logical-block</code></b></span> serves
essentially to print the closing tag (if needed) correctly indented.
The &quot;inner&quot; <span style="color: