Author: steveh Date: Thu Aug 5 13:36:06 2004 New Revision: 35752 Added: incubator/beehive/trunk/netui/docs/BUILDING_NETUI_DOCS.txt (contents, props changed) incubator/beehive/trunk/netui/docs/tools/README.txt (contents, props changed) Log: Adding instructions for building the netui docs, and a readme.txt describing how the custom doclet works.
Added: incubator/beehive/trunk/netui/docs/BUILDING_NETUI_DOCS.txt ============================================================================== --- (empty file) +++ incubator/beehive/trunk/netui/docs/BUILDING_NETUI_DOCS.txt Thu Aug 5 13:36:06 2004 @@ -0,0 +1,31 @@ +Building Netui Docs +------------------- +This documents describes how to build documentation for the beehive/netui project. + +Documentation Components +------------------------ +There are three documentation components for the beehive/netui project. + +(1) Conceptual Docs - describes how to use Page Flow technology to build web applications +(2) Netui API Reference - standard javadoc derived from the JAVA source files +(3) Netui Tag Library - a reference for the <netui> JSP tag library (generated from the JAVA source file using a custom doclet tool) + +How To Build the Documentation +------------------------------ + +Open a command shell. + +set JAVA_HOME to your local JDK5 (=JDK1.5.0) installation. + +cd to your local BEEHIVE_HOME. + +run beehiveEnv.cmd + +cd to BEEHIVE_HOME/netui/ant + +run ant -f javadoc.xml build -lib %BEEHIVE_HOME%\netui\test\external\xalan-241.jar + +(You must include the -lib flag, because the 'build' target depends on a Xalan extension.) + +The completed documentation can be found at BEEHIVE_HOME/netui/build/docs. + \ No newline at end of file Added: incubator/beehive/trunk/netui/docs/tools/README.txt ============================================================================== --- (empty file) +++ incubator/beehive/trunk/netui/docs/tools/README.txt Thu Aug 5 13:36:06 2004 @@ -0,0 +1,89 @@ +Custom Doclet: JSP Tag Library Reference +---------------------------------------- + +This document describes how the JSP Tag Library Reference is generated using a custom doclet. + +Introduction +------------ + +The custom doclet was created especially for JSP tag library documentation. +From a JSP tag-user perspective, standard Javadoc can be difficult to read: standard javadoc +output contains too many implementation details and the information that the tag-user is +looking for often gets lost in the thicket of information. + +To solve this problem, the custom doclet generates HTML topics oriented specifically for the tag-user: +They include (1) a syntax section that describes the JSP tag's syntax, (2) an attributes section which describes +how each JSP tag attribute works, and (3) an example section that shows the JSP tag in action on a JSP page. + +Custom Doclet Files +------------------- + +The custom doclet files are contained in three directories: + +(1) BEEHIVE_HOME/netui/docs/tools/lib + Contains doclet resources encapsulated in JAR files. These JAR files contain doclet classes that + extend the Javadoc API. (The source code for these JARs will be posted in the Apache Commons project at a later date.) + +(2) BEEHIVE_HOME/netui/docs/tools/static_files + Contains static HTML and CSS files. + +(3) BEEHIVE_HOME/netui/docs/tools/xslt + Contains XML stylesheets (XSTL files) that convert XML files into HTML files. + +How the Custom Doclet Works +--------------------------- + +The doclet generates HTML documentation in two stages. + + ----- ----- ----- + | | | | | | + | | ---(1)---> | | ---(2)---> | | + | | | | | | + ----- ----- ----- + + JAVA tag XML files HTML topics + handler classes + + (1) First XML documents are constructed from the javadoc content in the Java source files (= the tag handler classes). + (2) HTML topics are constructed from the XML documents. + +In the XML-generating step, the doclet makes one XML document for each Java tag handler class. +The doclet reads content from the @jsptagref.xxx javadoc annotations in the Java source files, +and creates an XML document from the content. + +For example, here is a snippet from the tag handler class Anchor.java, which handles the <netui:anchor> JSP tag. + + * @jsptagref.tagdescription + * <p> + * Generates an anchor that can link... + +The doclet reads this content, and constructs the following XML snippet. + + <tagdescription prefix="jsptagref"> + <lead> + <p>Generates an anchor that can link... + +In the HTML-generating step, XML stylesheets (XSLT files) are used to construct HTML topics based on +the XML files. The stylesheets map the content in the XML files into HTML files. +The following diagram shows how the stylesheets divide up the real estate in the HTML pages. + + -------------------------- + | | | + | | | + taglib-overview-frame.xslt --> | | | + | | | + -------- | + | | | + | | | + | | | <--- taglib-overview-summary.xslt + | | | <--- taglib-summary.xslt + all-tablibs-frame.xslt ---> | | | <--- tag_topics.xslt + taglib-frame.xslt ---> | | | + | | | + | | | + | | | + | | | + | | | + -------------------------- + + \ No newline at end of file
