/usr/share/doc/cl-htmlgen/htmlgen.html is in cl-htmlgen 1.2.42+cvs.2010.02.08-dfsg-1.2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 | <html>
<head>
<title>HTML Generation Facility</title>
<meta name="GENERATOR" content="Microsoft FrontPage 3.0">
</head>
<body>
<h1 align="center"><strong>HTML Generation Facility</strong></h1>
<p><small><small>This document copyright (c) 2000-2003 Franz Inc.</small></small></p>
<h2>Introduction</h2>
<p>We've defined a pair of macros which enable a program to generate <strong>html</strong>
in a concise and readable manner. These macros are quite a bit different
than those found in other <strong>html </strong>generation systems and thus we'll briefly
describe the justification for this design.</p>
<p><strong>html</strong> is a concise markup language. There is a tendency in language
design to assume that one's users won't be as smart as one's self and thus one tends to
dumb things down. For example, <strong>html</strong> uses <strong><p></strong>
to start a paragraph. The language designer says to himself: "while I
know that <strong>p</strong> means paragraph, my users won't so I'll spell it out as <strong>with-paragraph</strong>."
A similar thing is done for all the other html commands and soon a program to
generate html contains so many long markup commands that it's hard to see the text of the
document from the markup commands. A second problem is that as a user you're not
sure exactly what <strong>html</strong> will be generated by some high level <strong>with</strong>-<strong>xxx
</strong>forms. If you're trying to generate a particular sequence of <strong>html</strong>
you're left experimenting with the high level forms and hoping that by luck you get the
output you want. A third problem is that with the high level forms
you're forced to learn yet another markup language. There are plenty of books and
reference guides to <strong>html</strong> itself and it's an easy language to master.
Learning a particular high-level mapping of <strong>html </strong>is an
added burden.</p>
<p>With our <strong>html</strong> generation macros you write the actual <strong>html </strong>and
we just eliminate some of the tedious parts, such as closing off markup commands.
The result is that the structure of the document is visible and you can use any book on <strong>html</strong>
as a reference.</p>
<h2>Example</h2>
<p>The following example of generated web page will be useful to refer to in the
discussion below of the syntax of the <strong>html</strong> macro.</p>
<pre>(defvar *my-counter* 0) ; initialize counter variable.</pre>
<pre>(html (:html
(:head (:title "My Document"))
(:body (:h1 "My Document")
"Hello AllegroServe, the time is "
(:prin1 (get-universal-time))
(incf *my-counter*) ; evaluated but not printed
)))</pre>
<p> </p>
<p>This particular example generates a complete web page, but it's possible to use the
<strong>html</strong> macro to generate partial pages as well. In this
example, the generated page is surrounded by <strong><html></strong> and <strong></html></strong>
due to the <strong>:html</strong> form. The page contains a header and a
body surrounded by their respective html markers. The body of the document contains
a level 1 header followed by the text beginning "Hello, AllegroServe".
Following that is printed the universal time at the time that the page is
generated (i.e now rather than when the macro was first processed by lisp).
The following <strong>incf</strong> expression is evaluated but the result is not
printed. In this case we're keeping a private count of the number of times
this page has been accessed.</p>
<h2>html macro</h2>
<p>Now that you have a sense of how the <strong>html</strong> macro works, we will
describe the syntax in detail.</p>
<p> </p>
<p><strong><font face="Courier New">(html <em>form1 form2 ... formn) </font>
</em>[Macro]</strong></p>
<p>The forms are processed from left to right. The most likely effect is that
html output is generated. The output is sent to the stream <strong>net.html.generator:*html-stream*</strong>.
The <strong>html</strong> macro is designed to run inside AllegroServe's <strong>with-http-body</strong>
macro which binds <strong>*html-stream*</strong> to the correct stream. Also
the <strong>html-stream </strong>macro described below binds <strong>*html-stream* </strong>before
calling <strong>html.</strong> The action taken by <strong>html</strong> depends on
what the form looks like at macro-expansion time. The possibilities are:
<ul>
<li>string - A string is simply written (using <strong>princ</strong>) to the output
stream. Thus the string could contain embedded html commands.</li>
<li>keyword symbol - The keyword must name a known html operator. The
result is that the associated html markup command is sent to the output stream. The
mapping of keyword to html command is trivial -- the print name of the keyword is the html
command. So <strong>:p</strong> emits <strong><p></strong>.</li>
<li>list beginning with a keyword symbol - This names an <strong>html</strong> operator that
may or may not have an associated inverse operator beginning with "/". The
typical result of this form is to emit the associated html markup command, then process
the items in the list in the same way as the forms are processed, and then emit the
inverse markup command. Thus <strong>(:i "foo")</strong> emits <strong><i>foo</i>.
</strong> There is a special case when a single element list is given
(see below for details). Also there are some special keywords that are commands to
the <strong>html</strong> macro rather than markup commands. They are described
below.</li>
<li>list beginning with a list beginning with a keyword symbol - This is used to specify
markup commands that have parameters. For example <br>
<strong>((:a href "/foo/bar.html") "the link")</strong> turns into <strong><a
href="/foo/bar.html">the link</a></strong>. The
arguments are in plist form: a sequence of names and values. The names are <strong>not</strong>
evaluated, they should be symbols or strings. We often use keyword symbols for
the names since that looks more lisp-like and reduces the number of symbols we create.
The values <strong>are</strong> evaluated and printed with a function that escapes
characters with special meaning in html : <, >, &, ". If the
value is a symbol with a zero length print name, then something special is done: The
name alone is printed without a following equal sign. For example: <strong>((:option
:size 4 :selected '||) "foo")</strong> generates <strong><option
size="4" selected>foo</option></strong>. This form of
valueless argument is illegal html but in some older browsers it's the required syntax.</li>
<li>anything else - everything else is simply evaluated in the normal lisp way and the
value thrown away.</li>
</ul>
<p>Special cases:
<ul>
<li><strong>(:princ </strong>arg1 arg2 .. argn<strong>) </strong>causes the result of
evaluating each of the args to be printed to the html stream using the <strong>princ</strong>
function (which prints without inserting escape characters needed by the lisp reader to
read the result).</li>
<li><strong>(:prin1</strong> arg1 arg2 ... argn<strong>) </strong>causes the result of
evaluating each of the args to be printed to the html stream using the <strong>prin1 </strong>function
(which prints by inserting escape characters needed by the lisp reader to read the
result).</li>
<li><strong>(:princ-safe </strong>arg1 arg2 .. argn<strong>) </strong>acts like the <strong>:princ</strong>
case except that the output is scanned for characters that could be considered html markup
commands, and if found, these characters are escaped to prevent them from being treated as
html markup commands.</li>
<li><strong>(:prin1-safe </strong>arg1 arg2 .. argn<strong>) </strong>acts like the <strong>:prin1</strong>
case except that the output is scanned for characters that could be considered html markup
commands, and if found, these characters are escaped to prevent them from being treated as
html markup commands.</li>
<li><strong>:newline </strong>simply inserts a newline into the html output stream.
This will not have an effect on the result as viewed by a web browser (unless
it is emitted while inside an html markup command that specifies preformatted input).
The main use for this is to make the resulting html file easier to read by a human.</li>
<li>You can conditionally specify arguments to a markup command using an argument name of
<strong>:if*</strong>. Following the <strong>:if*</strong> is a lisp expression
which if true at runtime will cause the following argument value pair to be included in
the argument tag. For example <strong>((:td :if* (frob) :bgcolor
"#00ff00") "xx") </strong>will only put <strong>bgcolor="#00ff00"</strong>
in the argument if the expression <strong>(frob)</strong> returns true at runtime.</li>
</ul>
<p> </p>
<p> </p>
<p><strong><font face="Courier New">(html-stream <em>stream</em> <em>form1 form2 ...
formn)</font>
</em>[Macro]</strong></p>
<p>This binds <strong>net.html.generator:*html-stream*</strong> to the value of the stream
argument and then evaluates the <em>form<strong> </strong></em>arguments just like the <strong>html</strong>
macro. </p>
<p> </p>
<h2>Examples</h2>
<p>We will show how to build a page containing a table using successively more runtime
customization of the table. First we show how to build a table of squares.</p>
<pre>defun simple-table-a ()
(with-open-file (p "test.html"
:direction :output
:if-exists :supersede
:if-does-not-exist :create)
(html-stream p
(:html
(:head (:title "Test Table"))
(:body
(:table
(:tr (:td "0") (:td "0"))
(:tr (:td "1") (:td "1"))
(:tr (:td "2") (:td "4"))
(:tr (:td "3") (:td "9"))
(:tr (:td "4") (:td "16"))
(:tr (:td "5") (:td "25"))))))))</pre>
<p>The function <strong>simple-table-a </strong>builds a page containing this table:</p>
<table>
<tr>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>2</td>
<td>4</td>
</tr>
<tr>
<td>3</td>
<td>9</td>
</tr>
<tr>
<td>4</td>
<td>16</td>
</tr>
<tr>
<td>5</td>
<td>25</td>
</tr>
</table>
<p>It isn't very pretty but it's easy to see the correspondence between the <strong>html</strong>
macro and the resulting table. Note that if we had done, for example, <strong>(:td
1)</strong> instead of <strong>(:td "1")</strong> then nothing would have been
emitted. Only constant strings are printed, not constant integers. To
use an integer here we would have had to do <strong>(:td (:princ 1))</strong>.</p>
<p>We can use the ability to pass arguments to html markup commands to specify a border
around the elements of the table as shown here:</p>
<pre>(defun simple-table-b ()
(with-open-file (p "test.html"
:direction :output
:if-exists :supersede)
(html-stream p
(:html
(:head (:title "Test Table"))
(:body <strong>
</strong>(<strong>(:table border 2)</strong>
(:tr (:td "0") (:td "0"))
(:tr (:td "1") (:td "1"))
(:tr (:td "2") (:td "4"))
(:tr (:td "3") (:td "9"))
(:tr (:td "4") (:td "16"))
(:tr (:td "5") (:td "25"))))))))
</pre>
<p>The resulting table is:</p>
<table border="2">
<tr>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>2</td>
<td>4</td>
</tr>
<tr>
<td>3</td>
<td>9</td>
</tr>
<tr>
<td>4</td>
<td>16</td>
</tr>
<tr>
<td>5</td>
<td>25</td>
</tr>
</table>
<p><br>
Suppose we wanted to make the table include the squares of numbers from zero to 100.
That would take a lot of typing. Instead, let's modify the table generation
function to compute a table of any size:</p>
<pre>(defun simple-table-c (count)
(with-open-file (p "test.html"
:direction :output
:if-exists :supersede)
(html-stream p
(:html
(:head (:title "Test Table"))
(:body
((:table border 2)
<strong>(dotimes (i count)
(html (:tr (:td (:princ i))
(:td (:princ (* i i))))))</strong>))))))</pre>
<p> </p>
<p>Note that we can freely imbed calls to the <strong>html</strong> macro within another
call. The <strong>dotimes</strong> call inside the <strong>:body</strong>
expression is simply evaluated and its value ignored. However the side effect of the
<strong>dotimes</strong> is to generate more html and to send it to the stream bound in
the <strong>html-stream</strong> call. The result of <font face="Courier New">(simple-table-c
8)</font> is</p>
<table border="2">
<tr>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>2</td>
<td>4</td>
</tr>
<tr>
<td>3</td>
<td>9</td>
</tr>
<tr>
<td>4</td>
<td>16</td>
</tr>
<tr>
<td>5</td>
<td>25</td>
</tr>
<tr>
<td>6</td>
<td>36</td>
</tr>
<tr>
<td>7</td>
<td>49</td>
</tr>
</table>
<p> </p>
<p>We can specify at runtime values for the arguments to html markup forms. This
function allows us to specify parameters of the table being built:</p>
<pre>(defun simple-table-d (count border-width backg-color border-color)
(with-open-file (p "test.html"
:direction :output
:if-exists :supersede)
(html-stream p
(:html
(:head (:title "Test Table"))
(:body
(<strong>(:table border border-width
bordercolor border-color
bgcolor backg-color
cellpadding 3)</strong>
(:tr ((:td bgcolor "blue")
((:font :color "white" :size "+1")
"Value"))
((:td bgcolor "blue")
((:font :color "white" :size "+1")
"Square"))
)
(dotimes (i count)
(html (:tr (:td (:princ i))
(:td (:princ (* i i))))))))))))
</pre>
<p>This demonstrates that in an html markup command argument list the keywords aren't
evaluated but the values are. If we evaluate this expression:</p>
<pre>(simple-table-d 10 3 "silver" "blue")</pre>
<p>then we generate this table:</p>
<table border="3" bordercolor="blue" bgcolor="silver" cellpadding="3">
<tr>
<td bgcolor="blue"><font color="white" size="+1">Value</font></td>
<td bgcolor="blue"><font color="white" size="+1">Square</font></td>
</tr>
<tr>
<td>0</td>
<td>0</td>
</tr>
<tr>
<td>1</td>
<td>1</td>
</tr>
<tr>
<td>2</td>
<td>4</td>
</tr>
<tr>
<td>3</td>
<td>9</td>
</tr>
<tr>
<td>4</td>
<td>16</td>
</tr>
<tr>
<td>5</td>
<td>25</td>
</tr>
<tr>
<td>6</td>
<td>36</td>
</tr>
<tr>
<td>7</td>
<td>49</td>
</tr>
<tr>
<td>8</td>
<td>64</td>
</tr>
<tr>
<td>9</td>
<td>81</td>
</tr>
</table>
<p> </p>
<p> </p>
<p>An example of conditional arguments to a markup command is this:</p>
<pre>(defun simple-table-e (count)
(with-open-file (p "test.html"
:direction :output
:if-exists :supersede)
(html-stream p
(:html
(:head (:title "Test Table"))
(:body
((:table border 2)
(dotimes (i count)
(html (:tr
(dotimes (j count)
(html ((:td <strong>:if* (evenp j) :bgcolor "red"
:if* (not (evenp j)):bgcolor "green"</strong>)
(:princ (* i j))))))))))))))
</pre>
<p>This sets the color of the columns to alternately red and green: Here is <font
face="Courier New">(simple-table-e 6)</font></p>
<table border="2">
<tr>
<td bgcolor="red">0</td>
<td bgcolor="green">0</td>
<td bgcolor="red">0</td>
<td bgcolor="green">0</td>
<td bgcolor="red">0</td>
<td bgcolor="green">0</td>
</tr>
<tr>
<td bgcolor="red">0</td>
<td bgcolor="green">1</td>
<td bgcolor="red">2</td>
<td bgcolor="green">3</td>
<td bgcolor="red">4</td>
<td bgcolor="green">5</td>
</tr>
<tr>
<td bgcolor="red">0</td>
<td bgcolor="green">2</td>
<td bgcolor="red">4</td>
<td bgcolor="green">6</td>
<td bgcolor="red">8</td>
<td bgcolor="green">10</td>
</tr>
<tr>
<td bgcolor="red">0</td>
<td bgcolor="green">3</td>
<td bgcolor="red">6</td>
<td bgcolor="green">9</td>
<td bgcolor="red">12</td>
<td bgcolor="green">15</td>
</tr>
<tr>
<td bgcolor="red">0</td>
<td bgcolor="green">4</td>
<td bgcolor="red">8</td>
<td bgcolor="green">12</td>
<td bgcolor="red">16</td>
<td bgcolor="green">20</td>
</tr>
<tr>
<td bgcolor="red">0</td>
<td bgcolor="green">5</td>
<td bgcolor="red">10</td>
<td bgcolor="green">15</td>
<td bgcolor="red">20</td>
<td bgcolor="green">25</td>
</tr>
</table>
<p> </p>
<p> </p>
<p> </p>
<h2>HTML generation functions</h2>
<p>It's possible to express HTML using Lisp data structures. The form is based
on how HTML is written using the <strong>html</strong> macro above. </p>
<p>Lisp HTML (<strong>lhtml) </strong>is defined as one of the following
<ul>
<li>a string, which is rendered as HTML by simply printing it. Thus the string can
contain embedded HTML commands.</li>
<li>a list beginning with a valid <strong>lhtml</strong> keyword and containing <strong>lhtml</strong>
forms. The valid keywords are those corresponding to the HTML entity tags,
plus the special tags <strong>:princ, :princ-safe, :prin1, :prin1-safe</strong>, <strong>:newline</strong>
and <strong>:comment</strong>. These act just as they do in the <strong>html</strong>
macro. This form is rendered as an opening tag, then the rendering of the
body, and a closing HTML tag if one exists.</li>
<li>a list beginning with a list beginning with an <strong>lhtml</strong> keyword.
This is the form used when attributes are to be supplied with the opening entity
tag. </li>
</ul>
<p>Examples of valid <strong>lhtml</strong>:
<ul>
<li>"foo<i>bar</i>baz"</li>
<li>(:i "foo")</li>
<li>((:body :bgcolor "#xffffff") "the body")</li>
</ul>
<p> </p>
<p><strong><font face="Courier New">(html-print lhtml stream)</font></strong></p>
<p>Print the Lisp HTML expression <strong>lhtml</strong> to the <strong>stream.</strong></p>
<p> </p>
<p><font face="Courier New"><strong>(html-print-list lhtml-list stream)</strong></font></p>
<p>Print the list of <strong>lhtml</strong> forms to the <strong>stream. </strong>This
is equivalent to calling <strong>html-print</strong> on every element of <strong>lhtml-list</strong>.
</p>
<p> </p>
<p> </p>
<p> </p>
</body>
</html>
|