Attached is my previous file which documents the current jakarta-taglibs dir/file
layout and build process. Included at the end is my proposal for a new
dir/file layout and build process.
Comments? Votes?
The usual rules apply:
[ ] +1 = I agree with this proposal and will support it
[ ] +0 = I agree with this proposal, but do not have time to support it
[ ] -0 = I do not agree with this proposal, but don't want to try
to block it
[ ] -1 = I do not agree with this proposal (requires reasons)
If approved, I can make the overall changes to jakarta-taglibs.
Once those are in place the individual taglibs can be migrated.
I will take care of the taglibs I authored, the request, response,
session, regexp, datetime, and foundation taglibs. It would be nice
if other taglib authors would volunteer to migrate the taglibs they
wrote.
Regards,
Glenn
----------------------------------------------------------------------
Glenn Nielsen [EMAIL PROTECTED] | /* Spelin donut madder |
MOREnet System Programming | * if iz ina coment. |
Missouri Research and Education Network | */ |
----------------------------------------------------------------------
I have been looking at all the mechanisms for building jakarta-taglibs site,
building individual taglibs, and generating documentation for a taglib.
The following individual efforts have helped a great deal to improve the
process:
Use of XML and XSL to build the Jakarta-Taglibs site and individual tag
library site pages done by Justyna.
Development of the taglib release process and updating the Jakarta-Taglibs
site with news contributed by Morgan.
Streamlining and standardizing individual tag library builds using common.xml
contributed by Tim Dawson.
Use of XML and XSL to build individual tag library tld and documentation
contributed by Scott Stirling.
Overall Jakarta project directory layout guidelines by Ceki.
http://jakarta.apache.org/site/dirlayout.html
Thanks!
Glenn
Here is the current structure of jakarta-taglibs and an individual taglib or
ctlx tool. Please let me know if I have missed anything. Later I will
make a proposal for merging all these together and restructuring the layout
and build process. Please let me know if you have any comments or
suggestions for improving any of the below.
Current directory layout for jakarta-taglibs
============================================
Text Files
----------
HOWTO-RELEASE - Morgans great document for how to release a taglib
LICENSE - Apache License
README - Readme about using and building taglibs
Build Files
-----------
build.bat - Windows build script
build.sh - Unix build script
build.xml - Overall taglibs Ant build config
common.properties - common properties for building a taglib
common.xml - common Ant config for building a taglib
Jakarta Site static documents
-----------------------------
doc/
doc/binarydist.html - http:/jakarta.apache.org/taglibs/binarydist.html
doc/sourcedist.html - http:/jakarta.apache.org/taglibs/sourcedist.html
doc/tutorial.html - http:/jakarta.apache.org/taglibs/tutorial.html
Jakarta Site generated documents source
---------------------------------------
src/doc/index.xml - http:/jakarta.apache.org/taglibs/index.html
src/doc/project.xml - http:/jakarta.apache.org/taglibs/index.html (Menu)
src/doc/taglibs_docs.dtd - DTD for use with index.html and taglib intro.xml
src/doc/images/jakarta-logo.gif - The Jakarta logo
src/doc/images/taglibs.gif - The Jakarta-Taglibs logo
src/doc/stylesheets/taglibs.xsl - Transform index.xml & project.xml into index.html
Template files for individual taglib documentation
--------------------------------------------------
taglib-doc-kit/
taglib-doc-kit/README.txt - All about dynamically generating your taglib docs
taglib-doc-kit/taglib-doc-build.xml - A sample build file for taglib
taglib-doc-kit/xml/footer.xsl - Footer for taglib documenation
taglib-doc-kit/xml/jndi-tags.xml - Example taglib XML data file for JNDI taglib
taglib-doc-kit/xml/taglib-doc.xsl - Transform jndi-tags.xml into the taglib index.html
doc
taglib-doc-kit/xml/taglib-template-tags_xml - Template for taglib XML data
taglib-doc-kit/xml/taglib.css - CSS for use with taglib index.html doc
taglib-doc-kit/xml/tld.xsl - Transform jndi-tags.xml into a JSP 1.1 TLD file
Custom Tag Libraries
--------------------
<taglib>/ - Source for a custom tag library
Custom Tag Library Extensions (CTLX)
------------------------------------
tools/<tool>/<version>/ - Source for a publishing tool JSP taglib extension
Generated files from taglib build process
-----------------------------------------
../build/taglibs/ - Where all the taglibs go when you build them
../build/taglibs/doc/ - Where the jakarta site documentation goes when you use the ant
target "compile.documentation"
../dist/taglibs/ - Where all the taglibs go when you build a binary distribution
Current Directory Layout for a taglib
=====================================
Jakarta Site generated document source
--------------------------------------
<taglib>/doc/web/intro.xml - Taglib Jakarta site XML data file, transformed by
src/doc/stylesheets/taglibs.xsl
Build Files
-----------
<taglib>/build.bat - Windows build script (Not needed if using common.xml based build)
<taglib>/build.sh - Unix build script (Not needed if using common.xml based build)
<taglib>/build.xml - Ant build file for taglib
Static Configuration and Documentation Files (Original)
-------------------------------------------------------
<taglib>/conf/<taglib>.tld - TLD for taglib
<taglib>/doc/conf/web.xml - web.xml for <taglib>-doc.war
<taglib>/doc/web/changes.html - Taglib change history for site docs and
<taglib>-doc.war
<taglib>/doc/web/index.html - Taglib documentation for site docs and <taglib>-doc.war
Configuration Files (taglib-doc-kit)
------------------------------------
<taglib>/xml/<taglib>-tags.xml - Taglib and tag XML data transformed by
taglib-doc-kit/xml/taglib-doc.xsl into the taglib index.html documentation and by
taglib-doc-kit/xml/tld.xsl into the <taglib>.tld
Examples web application
------------------------
examples/conf/web.xml - web.xml for <taglib>-examples.war
examples/web/index.html - Static root document for <taglib>-examples.war
examples/web/*.html - Additional static documents for <taglib>-examples,war
examples/web/*.jsp - One or more static example jsp pages for <taglib>-examples.war
Taglib java source
------------------
<taglib>/src/ - taglib java source in package org.apache.taglibs
Generated files from taglib build process
-----------------------------------------
../build/taglibs/<taglib> - Compiled java class files
../build/taglibs/<taglib>-doc - Taglib documentation web app directories and files
../build/taglibs/<taglib>-examples - Taglib examples web app directories and files
../dist/taglibs/<taglib>/<taglib>-doc.war - Taglib documentation war file
../dist/taglibs/<taglib>/<taglib>-examples.war - Taglib examples war file.
../dist/taglibs/<taglib>/<taglib>.jar - Taglib jar file
../dist/taglibs/<taglib>/<taglib>.tld - Taglib TLD file
Proposal for new jakarta-taglibs and taglib dir/file layout and build process:
New directory layout for jakarta-taglibs
============================================
Text Files
----------
HOWTO-RELEASE - Morgans great document for how to release a taglib
HOWTO-PUBLISH - New document that documents how to create and publish new taglibs
LICENSE - Apache License
README - Readme about using and building taglibs: Update with info about new layout
and build
Build Files
-----------
.cvsignore - CVS file specifying what files to ignore, add build, dist, and
build.properties
build.properties.sample
Example build properties file used to configure ant properties for required jar
files.
The jar file properties will be in the form "servlet.jar=<path to jar file>",
version specific jars would be "servlet-2.2.jar=<path to jar file>. This means that
the build.bat and build.sh scripts can be removed. $ANT_HOME/bin would have to be
in your PATH so that you could build by using "ant dist".
build.bat - Windows build script: Remove, no longer needed
build.sh - Unix build script: Remove, no longer needed
build.xml - Overall taglibs Ant build config
common.properties - common properties for building a taglib
common.xml - common Ant config for building a taglib:
Switch common.xml from using env vars for jar files to using build.properties.
Add the ability to generate documentation using the new taglib-doc-kit.
Jakarta Site static documents
-----------------------------
doc/
doc/binarydist.html - http:/jakarta.apache.org/taglibs/binarydist.html
doc/sourcedist.html - http:/jakarta.apache.org/taglibs/sourcedist.html
doc/tutorial.html - http:/jakarta.apache.org/taglibs/tutorial.html
Jakarta Site generated documents source
---------------------------------------
src/doc/index.xml - http:/jakarta.apache.org/taglibs/index.html
src/doc/project.xml - http:/jakarta.apache.org/taglibs/index.html (Menu)
src/doc/taglibs_docs.dtd - DTD for use with index.xml and taglib intro.xml
src/doc/images/jakarta-logo.gif - The Jakarta logo
src/doc/images/taglibs.gif - The Jakarta-Taglibs logo
src/doc/stylesheets/taglibs.xsl - Transform index.xml & project.xml into index.html
Template files for individual taglib documentation
--------------------------------------------------
The taglib-doc-kit will be removed and necessary files split out into those
files used dynamically to generate documenation during the build process,
and those used to setup template files for a new taglib. The build example
will be merged into common.xml.
taglib-doc-kit/ - Taglib documentation kit: Removed
taglib-doc-kit/README.txt - All about dynamically generating your taglib docs: Removed
taglib-doc-kit/taglib-doc-build.xml - A sample build file for taglib: Merged into
build.xml, removed
taglib-doc-kit/xml/footer.xsl - Footer for taglib documenation: Moved
taglib-doc-kit/xml/jndi-tags.xml - Example taglib XML data file for JNDI taglib:
Removed
taglib-doc-kit/xml/taglib-doc.xsl - Transform jndi-tags.xml into the taglib index.html
doc: Moved
taglib-doc-kit/xml/taglib-template-tags_xml - Template for taglib XML data: Moved
taglib-doc-kit/xml/taglib.css - CSS for use with taglib index.html doc: Moved
taglib-doc-kit/xml/tld.xsl - Transform jndi-tags.xml into a JSP 1.1 TLD file: Moved
New directory for common source files used at build time to generate taglib
documentation:
src/taglib/
src/taglib/footer.xsl
src/taglib/taglib-doc.xsl
src/taglib/taglib.css
src/taglib/tld11.xsl
New directory for template files for use when creating a new taglib.
Just mkdir <taglib>, then cp -r src/taglib-template <taglib>.
src/taglib-template/build.xml - Template for an example build file
src/taglib-template/doc/ - Source used to generate <taglib>-doc.war
src/taglib-template/doc/conf/web.xml - Template for <taglib>-doc web application
web.xml
src/taglib-template/doc/web/changes.html - Template for taglib changes.html document
src/taglib-template/examples/ - Source used to generate <taglib>-examples.war
src/taglib-template/examples/conf/web.xml - Template for <taglib>-examples web
application web.xml
src/taglib-template/examples/web/ - Location for example html and jsp files
src/taglib-template/src/org/apache/taglibs/ - Java source code directory
src/taglib-template/xml/intro.xml - Template for taglib XML data used for generating
taglib intro.html doc file for the Jakarta-Taglibs site
src/taglib-template/xml/tags.xml - Template for taglib XML data for taglib and tags
Custom Tag Libraries
--------------------
<taglib>/ - Source for a custom tag library
Custom Tag Library Extensions (CTLX)
------------------------------------
tools/<tool>/<version>/ - Source for a publishing tool JSP taglib extension
Generated files from taglib build process
-----------------------------------------
Move build and dist directories into jakarta-taglibs directory.
build/taglibs/ - Where all the taglibs go when you build them
build/taglibs/doc/ - Where the jakarta site documentation goes when you use the ant
target "compile.doc
umentation"
dist/taglibs/ - Where all the taglibs go when you build a binary distribution
Current Directory Layout for a taglib
=====================================
Jakarta Site generated document source
--------------------------------------
Move to <taglib>/doc/xml/intro.xml.
<taglib>/doc/web/intro.xml - Taglib Jakarta site XML data file, transformed by
src/doc/stylesheets/taglibs
.xsl
Build Files
-----------
<taglib>/build.bat - Windows build script: (Leave in place until all taglibs migrated
to using common.xml)
<taglib>/build.sh - Unix build script: (Leave in place until all taglibs migrated to
using common.xml)
<taglib>/build.xml - Ant build file for taglib: Switch over to using common.xml
Static Configuration and Documentation Files (Original)
-------------------------------------------------------
<taglib>/conf/<taglib>.tld - TLD for taglib (Not needed if using taglib-doc-kit)
<taglib>/doc/conf/web.xml - web.xml for <taglib>-doc.war
<taglib>/doc/web/changes.html - Taglib change history for site docs and
<taglib>-doc.war
<taglib>/doc/web/index.html - Taglib documentation for site docs and <taglib>-doc.war
(Not needed if using taglib-doc-kit)
Configuration Files (taglib-doc-kit)
------------------------------------
<taglib>/xml/<taglib>-tags.xml - Taglib and tag XML data transformed by
taglib-doc-kit/xml/taglib-doc.xsl
into the taglib index.html documentation and by taglib-doc-kit/xml/tld11.xsl into the
<taglib>.tld
Examples web application
------------------------
examples/conf/web.xml - web.xml for <taglib>-examples.war
examples/web/index.html - Static root document for <taglib>-examples.war
examples/web/*.html - Additional static documents for <taglib>-examples,war
examples/web/*.jsp - One or more static example jsp pages for <taglib>-examples.war
Taglib java source
------------------
<taglib>/src/ - taglib java source in package org.apache.taglibs
Generated files from taglib build process
-----------------------------------------
The build and dist directories are moved into jakarta-taglibs directory.
The buld directory will use a <taglib> sub directory where it will put
the build files and directories for each individual taglib.
build/taglibs/<taglib>/<taglib> - Compiled java class files
build/taglibs/<taglib>/<taglib>-doc - Taglib documentation web app directories and
files
build/taglibs/<taglib>/<taglib>-examples - Taglib examples web app directories and
files
build/taglibs/<taglib>/<taglib>.tld - Generated taglib TLD file
dist/taglibs/<taglib>/<taglib>-doc.war - Taglib documentation war file
dist/taglibs/<taglib>/<taglib>-examples.war - Taglib examples war file.
dist/taglibs/<taglib>/<taglib>.jar - Taglib jar file
dist/taglibs/<taglib>/<taglib>.tld - Taglib TLD file
