[Hibernate-commits] Hibernate/doc/reference README,NONE,1.1

[<tu...@us...>]

Update of /cvsroot/hibernate/Hibernate/doc/reference
In directory sc8-pr-cvs1:/tmp/cvs-serv25884/doc/reference

Added Files:
	README 
Log Message:
Instructions for documentation generation

--- NEW FILE: README ---
############################################################################        
#                       REQUIRED SOFTWARE                                  #
############################################################################

Some packages are required to compile the HTML and PDF documentation.

On RedHat Linux 7.3, install RPMs:

rpm -i  jadetex-3.12-2.noarch.rpm \
        sgml-common-0.6.3-9.noarch.rpm \
        tetex-1.0.7-47.i386.rpm \
        tetex-latex-1.0.7-47.i386.rpm \
        tetex-dvips-1.0.7-47.i386.rpm \        
        openjade-1.3.1-4.i386.rpm \
        ed-0.2-25.i386.rpm \
        tetex-fonts-1.0.7-47.i386.rpm \
        docbook-dtds-1.0-8.noarch.rpm \
        docbook-style-xsl-1.49-1.noarch.rpm \
        docbook-style-dsssl-1.76-1.noarch.rpm
        
Link the current DTD to the real version name:

ln -s /usr/share/sgml/docbook/xml-dtd-4.1.2-1.0-8 \
      /usr/share/sgml/docbook/xml-dtd-4.1.2
                
Converting the DocBook XML source to HTML requires an XSL Transformer.
Don't use Xalan, it is broken with the current DocBook XSL stylesheets!

We recommend using Saxon from http://saxon.sourceforge.net/ - the 
version in use is 6.5.2. Just move saxon.jar to your libs directory
somewhere and change the path in the scripts.

The PDF output uses TeX and then converts from TeX to PDF. This stuff is
somewhat broken, as the DSSSL stylesheets change regulary and the whole
DocBook toolchain is just a big mess. The configuration files are only 
tested with the package versions of the RPMs above!



############################################################################        
#                       HTML DOCUMENTATION                                 #
############################################################################
        
The following bash script can be used to generate the HTML documentation
(set the path to saxon.jar):

-------------------------- dbtrans2html ------------------------------------
#!/bin/bash

SAXON=~/dev/lib/saxon.jar;
XSL_PARAMS="html.stylesheet='../style.css' \
            chunk.section.depth='5' \
            use.id.as.filename='1'";

USAGE="usage: dbtrans2html INFILE.xml STYLE.XSL OUTFILE.html|OUTDIR"

if [[ -z "$1" || -z "$2" || -z "$3" ]]; then
  echo $USAGE
  echo 
  exit
fi

if [ ! -r $1 ]; then
  echo $USAGE
  echo File $1 not found or not readable.
  echo
  exit
fi

echo "Generating HTML with Saxon from XML source: $1"

CLASSPATH=$JAVA_HOME/lib/tools.jar:$SAXON;

CURRDIR=$PWD;
if [ -d $3 ]; then
  cd $3;
  java -cp $CLASSPATH com.icl.saxon.StyleSheet $1 $2 $XSL_PARAMS
  cd $CURRDIR;
else
  java -cp $CLASSPATH com.icl.saxon.StyleSheet -o $3 $1 $2 $XSL_PARAMS
fi

echo "Finished."
----------------------------------------------------------------------------

Calling the script (use absolute path names!):

dbtrans2html ~/Hibernate/doc/reference/src/index.xml \
             /usr/share/sgml/docbook/xsl-stylesheets/html/docbook.xsl \
             ~/Hibernate/doc/reference/html_single/index.html

To generate the chunked online HTML documentation, change the XSL file and
use an existing directory as the OUTFILE parameter:

dbtrans2html ~/Hibernate/doc/reference/src/index.xml \
             /usr/share/sgml/docbook/xsl-stylesheets/html/chunk.xsl \
             ~/Hibernate/doc/reference/html/


             
############################################################################        
#                       PDF DOCUMENTATION                                  #
############################################################################
        
The following bash script can be used to generate the PDF documentation
(set the path to xml.dcl):

-------------------------- dbtrans2pdf -------------------------------------
#!/bin/bash

XMLDCL="/usr/share/doc/openjade-1.3.1/pubtext/xml.dcl";

USAGE="usage: dbtrans2pdf INFILE.xml OUTFILE.pdf /path/to/hibernate.dsl"

if [[ -z "$1" || -z "$2" ]]; then
  echo $USAGE
  echo 
  exit
fi

if [ ! -r $1 ]; then
  echo $USAGE
  echo File \"$1\" not found or not readable.
  echo
  exit
fi

# Generate LaTeX from XML source
echo "Generating TeX from XML source: $1"
TEMPFILE=`date +%s`;

jade -d $3 -t tex -o $TEMPFILE.tex $XMLDCL $1
RETVAL=$?

if [ $RETVAL -eq 0 ] ; then

    echo "Generating PDF..."
    # This is really broken, but required for references and TOC...
    # min. 3 times: 
    pdfjadetex $TEMPFILE.tex 2&>/dev/null
    pdfjadetex $TEMPFILE.tex 2&>/dev/null
    pdfjadetex $TEMPFILE.tex 2&>/dev/null

    # Final Move
    mv $TEMPFILE.pdf $2
    
    echo "Cleanup..."
    # Cleanup
    rm $TEMPFILE.*
    echo "Finished."
else
   echo "ERROR: jadetex failed."
   rm $TEMPFILE.tex 2&>/dev/null
fi
----------------------------------------------------------------------------

Calling the script (use absolute path names!):

dbtrans2pdf  ~/Hibernate/doc/reference/src/index.xml \
             ~/Hibernate/doc/reference/pdf/hibernate_reference.pdf \
             ~/Hibernate/doc/reference/hibernate.dsl
             
The script hides the STDERR of pdfjadetex (lots of debugging output) by 
default. If something goes wrong in this step, you won't see it. If
something is broken in the XML, the jade step will spit out errors earlier,
though.