From: David Lichteblau <david@lichteblau.com>
Date: Sun, 27 Apr 2008 17:39:35 +0000 (+0200)
Subject: Package docstring
X-Git-Url: https://repo.or.cz/w/xuriella.git/commitdiff_plain/60c5a7198b7d42494f9cfbbfb2aa6f1b060b5b7b

Package docstring
---

diff --git a/doc/atdoc/index.css b/doc/atdoc.css
similarity index 93%
copy from doc/atdoc/index.css
copy to doc/atdoc.css
index 59a4fab..d9e85df 100644
--- a/doc/atdoc/index.css
+++ b/doc/atdoc.css
@@ -8,7 +8,7 @@ div.sidebar {
 a {
   text-decoration: none;
   color: black;
-  border-bottom: 1px solid #9c0000;
+  border-bottom: 1px solid #0070a0;
 }
 
 .nonlink {
@@ -57,7 +57,7 @@ body {
 }
 
 h2 {
-  color: #9c0000;
+  color: #0070a0;
 }
 
 .page-title {
@@ -65,9 +65,9 @@ h2 {
 }
 
 h3 {
-  color: #9c0000;
+  color: #0070a0;
   width: 90%;
-  border-bottom: 1px solid #9c0000;
+  border-bottom: 1px solid #0070a0;
    margin-left: -3px;
    padding-left: 3px;
 }
diff --git a/doc/atdoc.lisp b/doc/atdoc.lisp
dissimilarity index 86%
index 717da27..d77ca62 100644
--- a/doc/atdoc.lisp
+++ b/doc/atdoc.lisp
@@ -1,8 +1,11 @@
-(asdf:operate 'asdf:load-op :closure-html)
-(asdf:operate 'asdf:load-op :atdoc)
-(atdoc:generate-documentation
- '(:chtml :hax)
- "/home/david/src/lisp/closure-html/doc/atdoc/"
- :index-title "Closure HTML API reference"
- :heading "Closure HTML"
- :css "cxml.css")
+(asdf:operate 'asdf:load-op :xuriella)
+(asdf:operate 'asdf:load-op :atdoc)
+(let* ((base (asdf:component-pathname (asdf:find-system :xuriella)))
+       (atdoc-directory (merge-pathnames "doc/atdoc/" base)))
+  (ensure-directories-exist atdoc-directory)
+  (atdoc:generate-documentation
+   '(:xuriella)
+   atdoc-directory
+   :index-title "Xuriella XSLT API reference"
+   :heading "Xuriella XSLT"
+   :css (merge-pathnames "doc/atdoc.css" base)))
diff --git a/doc/atdoc/index.css b/doc/atdoc/index.css
index 59a4fab..d9e85df 100644
--- a/doc/atdoc/index.css
+++ b/doc/atdoc/index.css
@@ -8,7 +8,7 @@ div.sidebar {
 a {
   text-decoration: none;
   color: black;
-  border-bottom: 1px solid #9c0000;
+  border-bottom: 1px solid #0070a0;
 }
 
 .nonlink {
@@ -57,7 +57,7 @@ body {
 }
 
 h2 {
-  color: #9c0000;
+  color: #0070a0;
 }
 
 .page-title {
@@ -65,9 +65,9 @@ h2 {
 }
 
 h3 {
-  color: #9c0000;
+  color: #0070a0;
   width: 90%;
-  border-bottom: 1px solid #9c0000;
+  border-bottom: 1px solid #0070a0;
    margin-left: -3px;
    padding-left: 3px;
 }
diff --git a/doc/index.xsl b/doc/index.xsl
index 0f21241..287911c 100644
--- a/doc/index.xsl
+++ b/doc/index.xsl
@@ -99,8 +99,7 @@
 	    <br/>&#160;
 	  </li>
 	  <li>
-	    <a href="atdoc/index.html"><strike>API documentation</strike></a>
-	    (to be written)
+	    <a href="atdoc/pages/xuriella.html">API documentation</a>
           </li>
 	</ul>
       </div>
diff --git a/package.lisp b/package.lisp
index dbf23cc..1f06d63 100644
--- a/package.lisp
+++ b/package.lisp
@@ -52,4 +52,58 @@
 	   #:compile-instruction)
   (:import-from :xpath-protocol #:define-default-method)
   (:documentation
-   "Xuriella is an implementation of XSLT 1.0."))
+   "Xuriella is an implementation of XSLT 1.0.
+
+    @begin[Using XSLT]{section}
+      XSLT stylesheets are invoked using the @code{apply-stylesheet} function,
+      which can parse, compile, and apply XSLT stylesheets.
+
+      Top-level parameters to the stylesheet can be specified using
+      parameter instances created by @fun{make-parameter}.
+
+      @aboutfun{apply-stylesheet}
+      @aboutfun{make-parameter}
+    @end{section}
+    @begin[Compiling stylesheets explicitly]{section}
+      @code{parse-stylesheet} allows the compilation of XSLT stylesheets into
+      objects ahead of time, so that @code{apply-stylesheet} only needs to
+      invoke the pre-compiled sheet rather than having to parse and
+      compile it first.
+
+      @aboutfun{parse-stylesheet}
+    @end{section}
+    @begin[Defining extension elements]{section}
+      Xuriella can be extended in two ways:
+
+      Custom XPath functions can be implemented using the extension
+      mechanism in @a[http://common-lisp.net/project/plexippus-xpath/atdoc/pages/xpath-sys.html]{Plexippus}.
+
+      Custom XSLT elements can be implemented using the following macros.
+
+      @code{define-extension-group} is used to establish a namespace for
+      the extensions, which can then be activated using a namespace declaration
+      and the @code{extension-element-prefixes} attribute in the stylesheet.
+
+      Every individual extension element needs at least a definition
+      using @code{define-extension-parser}.  The parser will run at
+      compilation time and return an XSLT instruction in a sexp syntax.
+      If the extension can be implemented as a transformation into ordinary
+      XSLT elements, the parser only needs to return that XSLT sexp.
+
+      In addition, the sexp representation itself can be extended using
+      @code{define-extension-compiler}.  The extension compiler will be
+      invoked while the stylesheet is compiled to return a function, usually
+      a closure, that will be called by the stylesheet at run-time.
+
+      @aboutmacro{define-extension-group}
+      @aboutmacro{define-extension-parser}
+      @aboutmacro{define-extension-compiler}
+    @end{section}
+    @begin[Functions useful in extensions]{section}
+      The following functions can be used by extension parsers and compilers,
+      to parse child nodes as instructions, or to compile such instructions,
+      respectively.
+
+      @aboutfun{parse-body}
+      @aboutfun{compile-instruction}
+    @end{section}"))