;; $Revision: 1.1 $ $Date: 2005/07/14 04:11:44 $

(use eggdoc)
(include "eggdoc-zb.scm")

(define doc
  `((eggdoc:begin
     (name "eggdoc")
     (description "An egg documentation tool")
     (author (url ,zbigniew-homepage "Zbigniew"))
     (history
      (version "1.2" (tt "eggdoc:make-defsig") "; subsub[sub]section tags; with-default-param tag")
      (version "1.1" "setup scripts adds documentation and version info [Thanks to Jim Miller]")
      (version "1.0" "Initial release"))

     (requires (url "sxml-transforms.html" "sxml-transforms")
               (url "doctype.html" "doctype"))

     (usage)
     (download "eggdoc.egg")

     (documentation
      (p "eggdoc is an SXML documentation tool which produces HTML pages for Chicken eggs.  It uses the sxml-transforms extension to transform your SXML via a comprehensive XML stylesheet, simplifying the creation of egg documentation.  It's also quite customizable.")

      (group
       (procedure "(eggdoc->html DOC [STYLESHEET])"
                  (p "Transform the SXML document " (tt "DOC") " using the optional SXSLT stylesheet " (tt "STYLESHEET") ".  If not specified, the built-in stylesheet will be used, which is also accessible with " (tt "(eggdoc:make-stylesheet)") "."))
       
       (procedure "(eggdoc:make-stylesheet DOC)"
                  (p "Returns the default SXSLT stylesheet.  This is a procedure because the stylesheet is built dynamically using the contents of the SXML document " (tt "DOC") ".  For example, the value of the (name) tag is retrieved at build time and inserted in the header and the usage information.")
                  (p "You can append to or modify this stylesheet and then pass it to " (tt "eggdoc->html") ".  This is done in doctype's eggdoc to provide a new tag, (strings), which makes the SXML much cleaner."))
       (parameter "eggdoc:doctype"
                  (p "The DOCTYPE for this document, typically as defined in the doctype extension.  This defaults to doctype:xhtml-1.0-strict."))
       (parameter "eggdoc:css"
                  (p "CSS text inserted verbatim between the document's <style> tags.  This must be <!-- wrapped in HTML comments -->.  The default is quite reasonable.")
                  (p "If you wish to source a CSS file instead of inserting the text directly, you can override the eggdoc-style tag in the default stylesheet to do so."))
       (procedure "(eggdoc:make-defsig TAG SIG . [BODY])"
                  (p "Use this procedure inside a stylesheet to generate a new signature tag, just like "
                     (tt "procedure") " or " (tt "macro") ".  It expands to a "
                     (tt "(definition (signatures (signature ...)))") " expression.  For example,")
                  (pre "(eggdoc->html doc `( ,@(eggdoc:make-stylesheet doc)\n"
                       "                     (constant *macro* . ,eggdoc:make-defsig)\n"
                       "                     (method   *macro* . ,eggdoc:make-defsig) ))")
                  (p "will create new " (tt "constant") " and " (tt "method") " tags.")))
      (subsection "Subsections"
                   (p "Document section tags must be nested in the order " (tt "section -> subsection -> subsubsection -> subsubsubsection") ".  You may not nest section tags of the same level, as in " (tt "(section \"name\" (section ...))") ", and you may not skip a level. " (tt "eggdoc") " won't complain if you violate these rules" (& "mdash") "the HTML driver is pretty lax" (& "mdash") "but the appearance will be off and " (tt "eggdoc-texinfo") " will fail on such a document.  " (tt "eggdoc-texinfo") " is more sensitive to malformed documents, so it is recommended to generate " (tt ".info") " and " (tt ".pdf") " output as well to ensure your document is correct.")
                   (p (tt "documentation") ", " (tt "examples") ", and " (tt "license") " are " (tt "section") " tags in disguise.  In particular, " (tt "(documentation (section ...))") " is invalid; use " (tt "(documentation (subsection ...))."))))

     (examples
      (p "Complete examples for the Chicken extensions " (tt "args, doctype, eggdoc, hostinfo, sxml-tools, sxml-transforms,") " and " (tt "vector-lib") " are provided in the egg under src/.  These all validate as XHTML Strict 1.0.")
      (p "Also, " (tt "eggdoc") " has become the standard documentation tool for Chicken eggs, and an eggdoc source file is included in many eggs.  Unpack (untar) the egg by hand, or browse the SVN egg repository, to access the source."))

     (license
      ,licenses:zbigniew-bsd))))

(eggdoc->html doc)