src/parse/documentation.lisp

   1 ;;; -*- Mode: Lisp; Syntax: Common-Lisp; Package: SGML; Readtable: GLISP; -*-
   2 ;;; ---------------------------------------------------------------------------
   3 ;;;     Title: Documentation strings for the Closure HTML
   4 ;;;   Created: 2007-10-20
   5 ;;;    Author: David Lichteblau
   6 ;;;   License: MIT style (see below)
   7 ;;; ---------------------------------------------------------------------------
   8 ;;;  (c) copyright 2007 David Lichteblau
   9
  10 ;;;  Permission is hereby granted, free of charge, to any person obtaining
  11 ;;;  a copy of this software and associated documentation files (the
  12 ;;;  "Software"), to deal in the Software without restriction, including
  13 ;;;  without limitation the rights to use, copy, modify, merge, publish,
  14 ;;;  distribute, sublicense, and/or sell copies of the Software, and to
  15 ;;;  permit persons to whom the Software is furnished to do so, subject to
  16 ;;;  the following conditions:
  17 ;;;
  18 ;;;  The above copyright notice and this permission notice shall be
  19 ;;;  included in all copies or substantial portions of the Software.
  20 ;;;
  21 ;;;  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  22 ;;;  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  23 ;;;  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
  24 ;;;  IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
  25 ;;;  CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
  26 ;;;  TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  27 ;;;  SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  28
  29 (in-package :closure-html)
  30
  31 (setf (documentation 'parse 'function)
  32       "@arg[input]{a pathname, stream, string, or octet array}
  33        @arg[handler]{nil, or a HAX/SAX handler}
  34        @return{The return value of this function is determined by the
  35          @var{handler} argument; see below.}
  36        @short{Parse the HTML document given as an argument, or referred to
  37        using a pathname.}
  38
  39        @var{input} can have one of the following types:
  40        @begin{itemize}
  41        @item{pathname -- a Common Lisp pathname. Opens the file specified by
  42          the pathname parses it as an HTML document.}
  43        @item{stream -- a Common Lisp stream that has already been opened.}
  44        @item{array -- an @code{(unsigned-byte 8)} array.  The array is parsed
  45          directly, and interpreted according to the encoding it specifies.}
  46        @item{string/rod -- a rod (or string on unicode-capable
  47          implementations). Parses an XML document from the input string that
  48          has already undergone external-format decoding.}
  49        @end{itemize}
  50
  51        If @var{handler} is @code{nil}, the parser's internal representation
  52        of the document is returned.  The result is equivalent to that
  53        returned using a PT builder as returned by @fun{make-pt-builder}, but
  54        avoids creating the same representation twice.
  55
  56        Alternatively, @var{handler} can be a HAX handler
  57        (see @class{hax:abstract-handler}) or a SAX handler (see the
  58        @a[http://common-lisp.net/project/cxml/sax.html#sax]{SAX protocol in
  59        cxml}). In this case, the document will be serialized to the specified
  60        handler, and the result of @fun{hax:end-document} will be returned
  61        from this function. Note that the parser will currently always process
  62        the entire document before sending the first HAX event.")
  63
  64 (setf (documentation 'make-lhtml-builder 'function)
  65       "@return{The @class{lhtml-builder}, a HAX handler.}
  66        @short{Create a HAX handler which builds LHTML list structures.}
  67
  68        Example:
  69        @begin{pre}
  70  (chtml:parse \"<p>nada</p>\" (chtml:make-lhtml-builder))
  71        @end{pre}
  72        @begin{code}
  73  => (:HTML NIL (:HEAD NIL) (:BODY NIL (:P NIL \"nada\")))
  74        @end{code}
  75
  76        @see{parse}
  77        @see{serialize-lhtml}")
  78
  79 (setf (documentation 'lhtml-builder 'type)
  80       "@short{A HAX handler which builds LHTML list structures.}
  81
  82        LHTML represents each HTML element as a list of the form
  83
  84   @code{(}@em{name}@code{ (}@em{attributes...}@code{) }@em{children...}@code{)}
  85
  86        and each attribute as a list of the form
  87
  88   @code{(}@em{name value}@code{)}
  89
  90        Element and attribute names are symbols in the keyword package
  91        with uppercase names.  Attribute values are rods or strings.
  92
  93        @see{make-lhtml-builder}
  94        @see{serialize-lhtml}")
  95
  96 (setf (documentation 'serialize-lhtml 'function)
  97       "@arg[document]{an LHTML list}
  98        @arg[handler]{a HAX/SAX handler}
  99        @arg[name]{root element name, a rod/string}
 100        @arg[public-id]{nil or the Public ID, a rod/string}
 101        @arg[system-id]{nil or the System ID/URI, a rod/string}
 102        @return{The return value of this function is determined by the
 103          @var{handler} argument; see below.}
 104        @short{Serialize the LHTML document into HAX events, sent to the
 105          specified HAX handler.}
 106
 107        @var{handler} can be a HAX handler
 108        (see @class{hax:abstract-handler}) or a SAX handler (see the
 109        @a[http://common-lisp.net/project/cxml/sax.html#sax]{SAX protocol in
 110        cxml}).
 111
 112        The result of calling @fun{hax:end-document} on the handler will be
 113        returned from this function.
 114
 115        If @var{system-id} is specified, a doctype will be written
 116        according to the arguments @var{name}, @var{public-id}, and
 117        @var{system-id}.
 118
 119        Use this function with a serialization sink to get a string or file
 120        with a serialized HTML document, or with a HAX/SAX builder to
 121        convert LHTML into a different representation, like DOM, PT, or
 122        STP.
 123
 124        Example:
 125        @begin{pre}
 126  (let ((x '(:HTML NIL (:HEAD NIL) (:BODY NIL (:P NIL \"nada\"))))))
 127    (chtml:serialize-lhtml x (chtml:make-string-sink))
 128        @end{pre}
 129        @begin{code}
 130  => \"<HTML><HEAD></HEAD><BODY><P>nada</P></BODY></HTML>\"
 131        @end{code}
 132
 133        @see{parse}
 134        @see{make-lhtml-builder}")
 135
 136 (setf (documentation 'make-pt-builder 'function)
 137       "@return{The @class{pt-builder}, a HAX handler.}
 138        @short{Create a HAX handler which builds @class{pt} structures.}
 139
 140        Example:
 141        @begin{pre}
 142  (chtml:parse \"<p>nada</p>\" (chtml:make-pt-builder))
 143        @end{pre}
 144        @begin{code}
 145  => #<SGML:PT HTML ..>
 146        @end{code}
 147
 148        @see{parse}
 149        @see{serialize-pt}")
 150
 151 (setf (documentation 'pt-builder 'type)
 152       "@short{A HAX handler which builds PT structures.}
 153
 154        PT represents each HTML element as a structure instance of type
 155        @class{pt}.
 156
 157        @see{make-pt-builder}
 158        @see{serialize-pt}")
 159
 160 (setf (documentation 'serialize-pt 'function)
 161       "@arg[document]{an @class{pt} instance}
 162        @arg[handler]{a HAX/SAX handler}
 163        @arg[name]{root element name, a rod/string}
 164        @arg[public-id]{nil or the Public ID, a rod/string}
 165        @arg[system-id]{nil or the System ID/URI, a rod/string}
 166        @return{The return value of this function is determined by the
 167          @var{handler} argument; see below.}
 168        @short{Serialize the PT node into HAX events, sent to the
 169          specified HAX handler.}
 170
 171        @var{handler} can be a HAX handler
 172        (see @class{hax:abstract-handler}) or a SAX handler (see the
 173        @a[http://common-lisp.net/project/cxml/sax.html#sax]{SAX protocol in
 174        cxml}).
 175
 176        The result of calling @fun{hax:end-document} on the handler will be
 177        returned from this function.
 178
 179        If @var{system-id} is specified, a doctype will be written
 180        according to the arguments @var{name}, @var{public-id}, and
 181        @var{system-id}.
 182
 183        Use this function with a serialization sink to get a string or file
 184        with a serialized HTML document, or with a HAX/SAX builder to
 185        convert PT into a different representation, like DOM, LHTML, or
 186        STP.
 187
 188        Example:
 189        @begin{pre}
 190  (let ((x (chtml:parse \"<p>nada</p>\" (chtml:make-pt-builder)))))
 191    (chtml:serialize-pt x (chtml:make-string-sink))
 192        @end{pre}
 193        @begin{code}
 194  => \"<HTML><HEAD></HEAD><BODY><P>nada</P></BODY></HTML>\"
 195        @end{code}
 196
 197        @see{parse}
 198        @see{make-pt-builder}")
 199
 200 (setf (documentation 'pt 'type)
 201       "@short{Represents an HTML element.}
 202
 203        PT represents each HTML element as a structure instance, named by
 204        a keyword symbol.  The children of a PT node are strings (rods)
 205        for text nodes, or other PT nodes for elements.
 206
 207        @see{make-pt-builder}
 208        @see{serialize-pt}
 209        @see-slot{pt-name}
 210        @see-slot{pt-children}
 211        @see-slot{pt-parent}
 212        @see-slot{pt-attrs}")
 213
 214 (setf (documentation 'pt-name 'function)
 215       "@arg[instance]{a @class{pt} node}
 216        @return{a keyword symbol}
 217        @short{Returns the element's name.}
 218
 219        HTML element names are symbols in the keyword package with uppercase
 220        names.")
 221
 222 (setf (documentation 'pt-children 'function)
 223       "@arg[instance]{a @class{pt} node}
 224        @return{a list}
 225        @short{Returns the element's children.}
 226
 227        The children of a PT node are strings (rods)
 228        for text nodes, or other PT nodes for elements.
 229
 230        @see{pt-parent}")
 231
 232 (setf (documentation 'pt-parent 'function)
 233       "@arg[instance]{a @class{pt} node}
 234        @return{nil, or a @class{pt} node}
 235        @short{Returns the element's parent node.}
 236
 237        This slot should refer to the node's parent, if it is included
 238        in the list of that node's children.
 239
 240        @see{pt-children}")
 241
 242 (setf (documentation 'pt-attrs 'function)
 243       "@arg[instance]{a @class{pt} node}
 244        @return{a plist}
 245        @short{Returns the element's attributes as a plist.}
 246
 247        This plist maps attribute names to their values.
 248
 249        Attribute names are symbols in the keyword package with uppercase
 250        names.  Attribute values are strings/rods.")
 251
 252 (setf (documentation 'make-octet-vector-sink 'function)
 253       "@return{a HAX handler}
 254        @short{Returns a sink creating octet vectors.}
 255
 256        This function creates a serialization sink.  Sinks are HAX handlers
 257        that write events in their normal HTML syntax, and return
 258        the result from @fun{hax:end-document}, if applicable.
 259
 260        This particular kind of sink creates an HTML document in an array
 261        of @code{(unsigned-byte 8)}.
 262
 263        @see{make-character-stream-sink}
 264        @see{make-octet-stream-sink}
 265        @see{make-rod-sink}
 266        @see{make-string-sink}")
 267
 268 (setf (documentation 'make-octet-stream-sink 'function)
 269       "@return{a HAX handler}
 270        @short{Returns a sink writing to an octet stream.}
 271
 272        This function creates a serialization sink.  Sinks are HAX handlers
 273        that write events in their normal HTML syntax.
 274
 275        This particular kind of sink writen the HTML document to a stream
 276        of element-type @code{(unsigned-byte 8)}.
 277
 278        @see{make-character-stream-sink}
 279        @see{make-octet-vector-sink}
 280        @see{make-rod-sink}
 281        @see{make-string-sink}")
 282
 283 #+rune-is-character
 284 (setf (documentation 'make-string-sink 'function)
 285       "@return{a HAX handler}
 286        @short{Returns a sink creating strings.}
 287
 288        This function creates a serialization sink.  Sinks are HAX handlers
 289        that write events in their normal HTML syntax, and return
 290        the result from @fun{hax:end-document}, if applicable.
 291
 292        This particular kind of sink creates an HTML document in a string.
 293        The string is @em{not} encoded into an external-format.  When
 294        writing this string to a Lisp character stream at a later point, make
 295        sure that the stream's external format agrees with the encoding
 296        declared by the document, if any.
 297
 298        @b{Supported only on Lisps with Unicode support.}  On Lisps without
 299        Unicode characters, try @em{make-string-sink/utf8} as an alternative
 300        that has different encoding behaviour, but still uses strings.  Or
 301        use @em{make-rod-sink}, which creates arrays of code points.
 302
 303        @see{make-character-stream-sink}
 304        @see{make-octet-stream-sink}
 305        @see{make-octet-vector-sink}
 306        @see{make-rod-sink}")
 307
 308 (setf (documentation 'make-rod-sink 'function)
 309       "@return{a HAX handler}
 310        @short{Returns a sink creating rods.}
 311
 312        This function creates a serialization sink.  Sinks are HAX handlers
 313        that write events in their normal HTML syntax, and return
 314        the result from @fun{hax:end-document}, if applicable.
 315
 316        This particular kind of sink creates an HTML document in a rod.
 317
 318        On Lisps with Unicode support, @code{make-string-sink} is an alias for
 319        this function.
 320
 321        @see{make-character-stream-sink}
 322        @see{make-octet-stream-sink}
 323        @see{make-octet-vector-sink}
 324        @see{make-string-sink}")
 325
 326 #+rune-is-character
 327 (setf (documentation 'make-character-stream-sink 'function)
 328       "@return{a HAX handler}
 329        @short{Returns a sink writing to a character stream.}
 330
 331        This function creates a serialization sink.  Sinks are HAX handlers
 332        that write events in their normal HTML syntax.
 333
 334        This particular kind of sink writen the HTML document to a stream
 335        of element-type @code{character}. The characters written are @em{not}
 336        encoded into an external-format. Make sure that the stream's external
 337        format agrees with the encoding declared by the document, if any.
 338
 339        @b{Supported only on Lisps with Unicode support.}  On Lisps without
 340        Unicode characters, try @em{make-character-stream-sink/utf8} as
 341        an alternative that has different encoding behaviour, but still uses
 342        character streams.
 343
 344        @see{make-octet-stream-sink}
 345        @see{make-octet-vector-sink}
 346        @see{make-rod-sink}
 347        @see{make-string-sink}")
 348
 349 (setf (documentation 'with-element 'function)
 350       "@arg[name]{the element's name, a string/rod}
 351        @arg[body]{an implicit progn}
 352        @return{the value of @var{body}}
 353        @short{Generate @fun{hax:start-element} and @fun{hax:end-element}
 354          events.}
 355
 356        Execute @var{body} as an implicit progn.  Send a start-element event to
 357        the current sink (before the first child element begins, or the
 358        current element ends), including all attributes specified using
 359        @fun{attribute} until that point.  Send an end-element event after
 360        @var{body} is finished.
 361
 362        To be used in the extent of an @fun{with-html-output} invocation.")
 363
 364 (setf (documentation 'with-output-sink 'function)
 365       "@arg[var]{the variable name, a symbol}
 366        @arg[body]{an implicit progn}
 367        @return{the value of @var{body}}
 368        @short{Bind a variable to the current serialization sink.}
 369
 370        Execute @var{body} as an implicit progn with @var{var} bound to a
 371        serialization sink that @var{body} can safely call HAX functions on.
 372
 373        To be used in the extent of an @fun{with-html-output} invocation.")
 374
 375 (setf (documentation 'with-html-output 'function)
 376       "@arg[sink]{a HAX/SAX handler}
 377        @arg[name]{root element name, a rod/string}
 378        @arg[public-id]{nil or the Public ID, a rod/string}
 379        @arg[system-id]{nil or the System ID/URI, a rod/string}
 380        @arg[body]{an implicit progn}
 381        @return{the value of @var{body}}
 382        @short{Generate @fun{hax:start-document} and @fun{hax:end-document}
 383          events.}
 384
 385        Send a start-document event to the current sink, then execute
 386        @var{body} as an implicit progn.  Afterwards, send an end-element
 387        event.
 388
 389        @see{with-output-sink}
 390        @see{with-element}
 391        @see{attribute}
 392        @see{text}
 393        @see{comment}")
 394
 395 (setf (documentation 'attribute 'function)
 396       "@arg[name]{a string/rod}
 397        @arg[value]{a string/rod or other object}
 398        @return{the @var{value}}
 399        @short{Add an attribute to the current element.}
 400
 401        To be used in the extent of an @fun{with-element} invocation, this
 402        function adds an attribute to the element being serialized.")
 403
 404 (setf (documentation 'text 'function)
 405       "@arg[data]{a string/rod}
 406        @return{the @var{data}}
 407        @short{Write a text node.}
 408
 409        To be used in the extent of an @fun{with-html-output} invocation, this
 410        function serializes a text node.")
 411
 412 (setf (documentation 'comment 'function)
 413       "@arg[data]{a string/rod}
 414        @return{the @var{data}}
 415        @short{Write a comment node.}
 416
 417        To be used in the extent of an @fun{with-html-output} invocation, this
 418        function serializes a comment.")
 419
 420 (setf (documentation '*html-dtd* 'variable)
 421       "fixme: exported only for the benefit of Closure")