Menu
▾
▴
SF.net SVN: docbook: [6916] trunk/xsl
|
From: <xm...@us...> - 2007-06-30 04:36:24
|
Revision: 6916
http://svn.sourceforge.net/docbook/?rev=6916&view=rev
Author: xmldoc
Date: 2007-06-29 21:36:21 -0700 (Fri, 29 Jun 2007)
Log Message:
-----------
Added draft notes on how to do docbook-xsl release builds.
This draft is only about half finished at this point.
Modified Paths:
--------------
trunk/xsl/Makefile
Added Paths:
-----------
trunk/xsl/README.RELEASE-BUILD
Modified: trunk/xsl/Makefile
===================================================================
--- trunk/xsl/Makefile 2007-06-30 04:17:51 UTC (rev 6915)
+++ trunk/xsl/Makefile 2007-06-30 04:36:21 UTC (rev 6916)
@@ -21,7 +21,7 @@
# value of ZIP_EXCLUDES is a space-separated list of any file or
# directory names (shell wildcards OK) that should be excluded
# from the zip file and tarball for the release
-DISTRIB_EXCLUDES = extensions/xsltproc doc/reference.txt$$ reference.txt.html$$ doc/reference.fo$$ doc/reference.pdf$$ tools/xsl xhtml/html2xhtml.xsl
+DISTRIB_EXCLUDES = extensions/xsltproc doc/reference.txt$$ reference.txt.html$$ doc/reference.fo$$ doc/reference.pdf$$ tools/xsl xhtml/html2xhtml.xsl README.RELEASE-BUILD
# value of DISTRIB_PACKAGES is a space-separated list of any
# directory names that should be packaged as separate zip/tar
Added: trunk/xsl/README.RELEASE-BUILD
===================================================================
--- trunk/xsl/README.RELEASE-BUILD (rev 0)
+++ trunk/xsl/README.RELEASE-BUILD 2007-06-30 04:36:21 UTC (rev 6916)
@@ -0,0 +1,231 @@
+$Id$
+
+These are how-to instructions for building release versions of the
+DocBook Project XSL Stylesheets and for performing other tasks
+related to releases.
+
+DocBook Project developers are encouraged to edit/change any part
+of this document and to add to it anything they want.
+
+FIXME: This document is only half-finished.
+
+-----------------------------------------------------------------
+Release Build Setup/Testing
+-----------------------------------------------------------------
+0. Environment and dependencies.
+ Make sure your environment is set up correctly with information
+ about some of the dependencies needed to build.
+
+ a. DocBook Project modules
+ In addition to having an up-to-date working copy of the
+ source for the "xsl" module, you also need to have
+ up-to-date working copies of the following modules:
+
+ gentext
+ litprog
+ buildtools
+ releasetools
+
+ a. Shell Environment.
+ To get my environment variables set up, I have a file that I
+ name "docbk.sh", with the following in it:
+
+ # directory that is base directory for all your DocBook modules
+ export DOCBOOK_SVN=/opt/sandbox/docbook/trunk
+ # directory containing all your jar files
+ export JARDIR=/usr/share/java
+ export CLASSPATH=$CLASSPATH:$JARDIR/xml-commons-resolver-1.1.jar
+ export CLASSPATH=$CLASSPATH:$JARDIR/xercesImpl.jar
+ export CLASSPATH=$CLASSPATH:$JARDIR/jaxp-1.3.jar
+ export CLASSPATH=$CLASSPATH:$JARDIR/xalan-2.7.0.jar
+ export CLASSPATH=$CLASSPATH:$JARDIR/saxon-6.5.5.jar
+ # directory containing CatalogManager.properties file
+ export CLASSPATH=$CLASSPATH:/etc/xml/resolver/
+ export SGML_CATALOG_FILES=/etc/sgml/catalog
+
+ I source that by putting the following in my ~/.bashrc file:
+
+ # set up some environment variables for DocBook/XML stuff
+ . ~/docbk.sh
+
+ b. .xmlrc
+
+ You need an .xmlrc file with some system-specific data for Java
+ and XML tools in your environment. I use the following:
+
+ <?xml version='1.0' encoding='utf-8'?> <!-- -*- nxml -*- -->
+ <config>
+ <java classpath-separator=":" xml:id="java">
+ <system-property name="javax.xml.parsers.DocumentBuilderFactory"
+ value="org.apache.xerces.jaxp.DocumentBuilderFactoryImpl"/>
+ <system-property name="javax.xml.parsers.SAXParserFactory"
+ value="org.apache.xerces.jaxp.SAXParserFactoryImpl"/>
+ <classpath path="/usr/share/java/xercesImpl.jar"/>
+ <classpath path="/usr/share/java/jaxp-1.3.jar"/>
+ <classpath path="/usr/share/java/xml-commons-resolver-1.1.jar"/>
+ </java>
+ <java xml:id="bigmem">
+ <java-option name="Xmx512m"/>
+ </java>
+ <saxon xml:id="saxon" extends="java">
+ <arg name="x" value="org.apache.xml.resolver.tools.ResolvingXMLReader"/>
+ <arg name="y" value="org.apache.xml.resolver.tools.ResolvingXMLReader"/>
+ <arg name="r" value="org.apache.xml.resolver.tools.CatalogResolver"/>
+ <param name="use.extensions" value="1"/>
+ </saxon>
+ <saxon xml:id="saxon-8a" extends="saxon" class="net.sf.saxon.Transform"
+ java="/usr/bin/java">
+ <classpath path="/usr/share/java/saxon8.jar"/>
+ </saxon>
+ <saxon xml:id="saxon-6" extends="saxon" class="com.icl.saxon.StyleSheet">
+ <classpath path="/usr/share/java/saxon-6.5.5.jar"/>
+ <classpath path="/opt/sandbox/docbook/trunk/xsl-java/saxon65.jar"/>
+ </saxon>
+ <xsltproc xml:id="xsltproc" exec="xsltproc"></xsltproc>
+ <xmllint xml:id="xmllint" exec="xmllint"></xmllint>
+ </config>
+
+1. Test I: make all
+ Run a test "make all" build to make sure there are no problems
+ with the non-docs/non-release "normal" part of the build (the
+ part that basically just builds the gentext and param files and
+ gives you a working set of stylesheets to use). The way I
+ usually run that is this:
+
+ . ~/docbk.sh && \
+ svn-clean && \
+ make all 2>&1 \
+ XSLT="$DOCBOOK_SVN/buildtools/xslt -xsltproc" \
+ | tee LOG
+
+ NOTE: If you want to build with saxon instead of xsltproc,
+ change the "-xsltproc" above to "-saxon".
+
+ NOTE: The svn-clean command is something that's not part of the
+ core subversion distribution (on my system, it's part of the
+ subversion-tools package). Its function is to "wipe out
+ unversioned files from Subversion working copy". I use it
+ because our own "clean" make target doesn't clean out
+ everything that needs to be cleaned out to get your working
+ directory back to a fresh state. But svn-clean does.
+
+2. grep the LOG file.
+ After running the above, I then grep through the LOG file to
+ see if anything looks busted, using something like:
+
+ egrep -i "error|fail|\*[^.]" LOG
+
+ FIXME: The regexp in that grep may not catch all error messages
+ emitted; probably should be refined with a more complete regexp.
+
+3. Fix and problems/commit fixes.
+ If the grep of the LOG file reveals problems, fix them, commit
+ your changes (if the fixes required changes to source files)
+ then repeat Step 1 until you don't see any more problems.
+
+4. Test II: Smoke Test
+ At this point you should have a working set of stylesheets to
+ test with, so run a test of at least each of the following
+ against a document instance:
+
+ fo/docbook.xsl
+ fo/profile-docbook.xsl
+ manpages/docbook.xsl
+ manpages/profile-docbook.xsl
+ html/docbook.xsl
+ html/chunk.xsl
+ html/onechunk.xsl
+ html/profile-docbook.xsl
+ html/profile-chunk.xsl
+ html/profile-onechunk.xsl
+ xhtml/docbook.xsl
+ xhtml/chunk.xsl
+ xhtml/onechunk.xsl
+ xhtml/profile-docbook.xsl
+ xhtml/profile-chunk.xsl
+ xhtml/profile-onechunk.xsl
+ htmlhelp/htmlhelp.xsl
+ htmlhelp/profile-htmlhelp.xsl
+ eclipse/profile-eclipse.xsl
+ eclipse/eclipse.xsl
+ javahelp/profile-javahelp.xsl
+ javahelp/javahelp.xsl
+ roundtrip/dbk2ooo.xsl
+ roundtrip/dbk2pages.xsl
+ roundtrip/dbk2wordml.xsl
+ slides/html/default.xsl
+ slides/xhtml/default.xsl
+ slides/fo/plain.xsl
+ website/website.xsl
+ website/chunk-website.xsl
+
+5. Test III: make distrib
+ If you have resolved all problems with the "make all" build, do
+ a test run of "make distrib" (to build the docs and other
+ additional stuff needed for the distribution).
+
+ make install.sh && ./install.sh --batch \
+ && . $(pwd)/.profile.incl && ./test.sh &&
+ make distrib 2>&1 \
+ XSLT="$DOCBOOK_SVN/buildtools/xslt -xsltproc" \
+ PDF_MAKER=dblatex \
+ | tee LOG \
+ && ./uninstall.sh --batch 2>&1
+
+ NOTE: If you want to build with saxon instead of xsltproc,
+ change the "-xsltproc" above to "-saxon".
+
+ NOTE: The engine specified in PDF_MAKER is only used to build a
+ PDF of the release notes. If you want to use xep instead of
+ dblatex, specify PDF_MAKER=xep. (There's no option to use fop
+ because last time I tested it, fop still did a miserable job of
+ formatting the release notes.)
+
+ NOTE: The "make install.sh && ./install.sh --batch &&
+ . $(pwd)/.profile.incl" parts do an "install" of XML Catalog
+ settings in your environment so xsltproc/saxon will resolve the
+ http://docbook.sourceforge.net/release/xsl/current/ canonical
+ URL to the working directory you're actually building in
+ (instead of to whatever it would normally resolve to).
+
+ The reason for that "install" step is that there is one part of
+ the doc/distrib build that relies on the litprog stylesheets,
+ and the litprog stylesheets use the http: canonical URL for the
+ stylesheets (instead of using a relative path, as the
+ stylesheets themselves do), so the "install" steps tell
+ xsltproc and saxon that when they find that http: URL in the
+ litprog stylesheets, they should resolve it to the path to the
+ working directory you are building in (instead of to any
+ installed docbook-xsl release stylesheets or whatever other
+ sets of the stylesheets you may installed on your system).
+
+ The "uninstall.sh" step at the end causes all changes made by
+ that temporary XML Catalog "install" step to reverted.
+
+6. grep the LOG file (again).
+ Repeat Step 2 above to grep the LOG file for error messages. If
+ you find problems, go back to Step 1. Otherwise, proceed to the
+ Release Preparation steps below.
+
+-----------------------------------------------------------------
+Release Preparation
+-----------------------------------------------------------------
+1. Edit the VERSION file.
+ a. Update the release number in the fm:Version element.
+ b. Uncomment the appropriate text in the fm:Release-Focus
+ element to match the type of release this is; for example,
+ "Major feature enhancements", "Minor bugfixes", etc.
+ c. If necessary, edit the fm:Changes element to describe this
+ release. Keep it at one sentence; e.g.; "This is a bug-fix
+ release with a few feature enhancements." I don't recommend
+ wasting time doing much more than that, because the dumbass
+ at Freshmeat who reviews all submissions will likely edit
+ what you submit and manage to bork it up in some way.
+
+2. Check in the VERSION file:
+
+ svn commit -m "Version 1.NN.N released" VERSION
+
+3. Open the RELEASE-NOTES.xml file and comment out the paragraphs
+ about snapshot releases, then uncomment the paragraph about
+ official releases.
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.
|