From 0d67d0719de2c475f2f48e6fc5b93758c4e7819d Mon Sep 17 00:00:00 2001 From: dlichteblau Date: Sun, 18 Feb 2007 12:35:49 +0000 Subject: [PATCH] use xsl to build the html documentation from xml --- README | 29 +++ doc/GNUmakefile | 4 + doc/dom.html | 209 -------------------- doc/dom.xml | 150 ++++++++++++++ doc/html.xsl | 85 ++++++++ README.html => doc/index.xml | 116 +---------- doc/{installation.html => installation.xml} | 72 +------ doc/{klacks.html => klacks.xml} | 77 +------- doc/quickstart.html | 115 ----------- doc/quickstart.xml | 56 ++++++ doc/{using.html => sax.xml} | 163 +++++++-------- doc/{xmls-compat.html => xmls-compat.xml} | 75 +------ 12 files changed, 418 insertions(+), 733 deletions(-) create mode 100644 README create mode 100644 doc/GNUmakefile delete mode 100644 doc/dom.html create mode 100644 doc/dom.xml create mode 100644 doc/html.xsl rename README.html => doc/index.xml (51%) rename doc/{installation.html => installation.xml} (55%) rename doc/{klacks.html => klacks.xml} (72%) delete mode 100644 doc/quickstart.html create mode 100644 doc/quickstart.xml rename doc/{using.html => sax.xml} (84%) rename doc/{xmls-compat.html => xmls-compat.xml} (53%) diff --git a/README b/README new file mode 100644 index 0000000..4fd622e --- /dev/null +++ b/README @@ -0,0 +1,29 @@ + +Closure XML Parser + + An XML parser written in Common Lisp. + + Closure XML was written by Gilbert Baumann (unk6 at + rz.uni-karlsruhe.de) as part of the Closure web browser. + + Contributions to the parser by + * Henrik Motakef (hmot at henrik-motakef.de) + * David Lichteblau (david@lichteblau.com) + + CXML implements a namespace-aware, validating XML 1.0 parser + as well as the DOM Level 2 Core interfaces. Two parser interfaces + are offered, one SAX-like, the other similar to StAX. + + CXML is licensed under Lisp-LGPL. + + Send bug reports to cxml-devel@common-lisp.net + (http://common-lisp.net/cgi-bin/mailman/listinfo/cxml-devel) + + +Documentation + + Please refer to http://common-lisp.net/project/cxml/ for details. + + The documentation is also available in the doc/ subdirectory of this + source distribution, run `make' in that directory to build HTML + for the XML sources (requires xsltproc). diff --git a/doc/GNUmakefile b/doc/GNUmakefile new file mode 100644 index 0000000..3c7d1f7 --- /dev/null +++ b/doc/GNUmakefile @@ -0,0 +1,4 @@ +all: dom.html index.html installation.html klacks.html quickstart.html sax.html xmls-compat.html + +%.html: %.xml html.xsl + xsltproc html.xsl $< >$@ diff --git a/doc/dom.html b/doc/dom.html deleted file mode 100644 index fcea54b..0000000 --- a/doc/dom.html +++ /dev/null @@ -1,209 +0,0 @@ - - - - - Closure XML - - - -
-
- Closure XML -
-
- -
-
- -

The DOM implementation

-

- CXML implements the DOM Level 2 Core interfaces.  For details - on DOM, please refer to the specification. -

- - -

Parsing into DOM

-

- To parse an XML document into a DOM tree, use the SAX parser with a - DOM builder as the SAX handler. Example: -

- 
(cxml:parse-file "test.xml" (cxml-dom:make-dom-builder))
-

-

Function CXML-DOM:MAKE-DOM-BUILDER ()
- Create a SAX handler which builds a DOM document. -

-

- This functions returns a DOM builder that will work with the default - configuration of the SAX parser and is guaranteed to use - characters/strings instead of runes/rods, if that makes a - difference on the Lisp in question. -

-

- This is the same as rune-dom:make-dom-builder on Lisps - with Unicode support, and the same as - utf8-dom:make-dom-builder otherwise. -

- -

-

Function RUNE-DOM:MAKE-DOM-BUILDER ()
- Create a SAX handler which builds a DOM document using runes and rods. -

- -

-

Function UTF8-DOM:MAKE-DOM-BUILDER ()
- (Only on Lisps without Unicode support:) - Create a SAX handler which builds a DOM document using - UTF-8-encoded strings. -

- - -

Serializing DOM

-

- To serialize a DOM document, use a SAX serialization sink as the - argument to dom:map-document, which generates SAX events - for the DOM tree. -

-

- Applications dealing with namespaces might want to inject a - namespace normalizer into the - sink chain. -

-

-

Function DOM:MAP-DOCUMENT (handler document &key include-xmlns-attributes include-default-values include-doctype)
- Traverse a DOM document and call SAX functions as if an XML - representation of the document was processed by a SAX parser. -

-

Keyword arguments:

- - - -

DOM/Lisp mapping

-

- Note that there is no "standard" DOM mapping for Lisp. -

-

- DOM is specified - in CORBA IDL, but it refrains from using object-oriented IDL - features, allowing for a much more natural Lisp implemenation than - the the ordinary IDL/Lisp mapping would.  - Differences between CXML's DOM and the direct IDL/Lisp mapping: -

- - - diff --git a/doc/dom.xml b/doc/dom.xml new file mode 100644 index 0000000..cf95bdb --- /dev/null +++ b/doc/dom.xml @@ -0,0 +1,150 @@ + +

W3C DOM

+

+ CXML implements the DOM Level 2 Core interfaces.  For details + on DOM, please refer to the specification. +

+ + +

Parsing into DOM

+

+ To parse an XML document into a DOM tree, use the SAX parser with a + DOM builder as the SAX handler. Example: +

+ 
(cxml:parse-file "test.xml" (cxml-dom:make-dom-builder))
+

+

Function CXML-DOM:MAKE-DOM-BUILDER ()
+ Create a SAX handler which builds a DOM document. +

+

+ This functions returns a DOM builder that will work with the default + configuration of the SAX parser and is guaranteed to use + characters/strings instead of runes/rods, if that makes a + difference on the Lisp in question. +

+

+ This is the same as rune-dom:make-dom-builder on Lisps + with Unicode support, and the same as + utf8-dom:make-dom-builder otherwise. +

+ +

+

Function RUNE-DOM:MAKE-DOM-BUILDER ()
+ Create a SAX handler which builds a DOM document using runes and rods. +

+ +

+

Function UTF8-DOM:MAKE-DOM-BUILDER ()
+ (Only on Lisps without Unicode support:) + Create a SAX handler which builds a DOM document using + UTF-8-encoded strings. +

+ + +

Serializing DOM

+

+ To serialize a DOM document, use a SAX serialization sink as the + argument to dom:map-document, which generates SAX events + for the DOM tree. +

+

+ Applications dealing with namespaces might want to inject a + namespace normalizer into the + sink chain. +

+

+

Function DOM:MAP-DOCUMENT (handler document &key include-xmlns-attributes include-default-values include-doctype)
+ Traverse a DOM document and call SAX functions as if an XML + representation of the document was processed by a SAX parser. +

+

Keyword arguments:

+ + + +

DOM/Lisp mapping

+

+ Note that there is no "standard" DOM mapping for Lisp. +

+

+ DOM is specified + in CORBA IDL, but it refrains from using object-oriented IDL + features, allowing for a much more natural Lisp implemenation than + the the ordinary IDL/Lisp mapping would.  + Differences between CXML's DOM and the direct IDL/Lisp mapping: +

+ + diff --git a/doc/html.xsl b/doc/html.xsl new file mode 100644 index 0000000..149158e --- /dev/null +++ b/doc/html.xsl @@ -0,0 +1,85 @@ + + + + + + + + + + + + + + <xsl:value-of select="@title"/> + + + + + +
+
+ Closure XML +
+
+ +
+
+ + + + + + diff --git a/README.html b/doc/index.xml similarity index 51% rename from README.html rename to doc/index.xml index 9769d97..74d694b 100644 --- a/README.html +++ b/doc/index.xml @@ -1,62 +1,4 @@ - - - - - Closure XML - - - -
-
- Closure XML -
-
- -
-
- +

Closure XML Parser

An XML parser written in Common Lisp.

@@ -87,9 +29,9 @@ CXML implements a namespace-aware, validating XML 1.0 + href="http://www.w3.org/TR/2000/REC-xml-20001006">XML 1.0 parser as well as the DOM Level 2 Core + href="http://www.w3.org/TR/DOM-Level-2-Core/">DOM Level 2 Core interfaces. Two parser interfaces are offered, one SAX-like, the other similar to StAX.

@@ -170,54 +112,4 @@ - - - - - + diff --git a/doc/installation.html b/doc/installation.xml similarity index 55% rename from doc/installation.html rename to doc/installation.xml index 0d69923..676ca73 100644 --- a/doc/installation.html +++ b/doc/installation.xml @@ -1,61 +1,4 @@ - - - - - Closure XML - - - -
-
- Closure XML -
-
- -
-
+

Installation of Closure XML

@@ -123,7 +66,7 @@ $ cvs co cxml $ cvs login # password is "anonymous" $ cvs co 2001/XML-Test-Suite/xmlconf $ cvs co -D '2005-05-06 23:00' 2001/DOM-Test-Suite -$ cd 2001/DOM-Test-Suite && ant dom1-dtd dom2-dtd +$ cd 2001/DOM-Test-Suite && ant dom1-dtd dom2-dtd

Omit -D to get the latest version, which may not work with cxml yet. The ant step is necessary to run the DOM @@ -144,7 +87,7 @@ $ cd 2001/DOM-Test-Suite && ant dom1-dtd dom2-dtd

fixme domtest.lisp does not understand the current - testsuite driver anymore.  To fix this problem, revert the + testsuite driver anymore.  To fix this problem, revert the affected files manually after check-out:

@@ -153,10 +96,9 @@ xmltest$ patch -p0 -R </path/to/cxml/test/xmlconf-base.diff

The log message for the changes reads "Removed unnecessary - xml:base attribute".  If I understand correctly, only - DOM 3 parsers provide the baseURI attribute necessary for - understanding xmlconf.xml now.  We don't have that + xml:base attribute".  If I understand correctly, only + DOM 3 parsers provide the baseURI attribute necessary for + understanding xmlconf.xml now.  We don't have that yet.

- - + diff --git a/doc/klacks.html b/doc/klacks.xml similarity index 72% rename from doc/klacks.html rename to doc/klacks.xml index 7db7577..0cab5d8 100644 --- a/doc/klacks.html +++ b/doc/klacks.xml @@ -1,69 +1,4 @@ - - - - - Closure XML - - - -
-
- Closure XML -
-
- -
-
- +

Klacks parser

The Klacks parser provides an alternative parsing interface, @@ -115,7 +50,7 @@ NIL To parse using Klacks, create an XML source first.

-

Function CXML:MAKE-SOURCE (input &key validate +
Function CXML:MAKE-SOURCE (input &key validate dtd root entity-resolver disallow-external-subset pathname)
Create and return a source for input.

@@ -163,7 +98,7 @@ NIL

Keyword arguments have the same meaning as with the SAX parser, please refer to the documentation of parse-file for more information: + href="sax.html#parser">parse-file for more information: