DOCBOOK-APPS: Installing on RedHat Linux (Was: Jade/DSSSL vs. DocBookXML V4.1.2)

[Colin Paul Adams <colin at colina dot demon dot co dot uk>]

>>>>> "Lane" == Lane Stevens <lane@cycletime.com> writes:

    Lane> I seem to be caught between two errors.  Solving one causes
    Lane> the other.  I have installed the nwalsh modular stylesheets
    Lane> v 1.54. and performed all of the tests in the installation
    Lane> instructions successfully.  Next I created a simple DocBook
    Lane> XML v4.1.2 document that validates with nsgmls.

    Lane> The environment is RedHat Linux 6.2.

I presume you have installed the rpms that come with RedHat 6.2.

My advice to all users of RedHat Linux is not to use this approach,
but do it all by hand.

So:

1) rpm -e for docbook, stylesheets,
     jadetex, jade and sgml-common. The latter may need the --nodeps
     option, if you have psgml installed. Then do a rm -rf
     /usr/lib/sgml (check first that there are no files left there
     from other packages).

2) Download and install DocBook (version 4.1.2 XML)
   itself, from http://docbook.org/xml/4.1.2/
   or http://www.nwalsh.com/. You
   should create a directory, change to it, and then unzip from there. I
   recommend /usr/lib/sgml .

3) Then edit /usr/lib/sgml/docbook.cat. You need to
       insert an initial line saying:

         OVERRIDE YES

4) Next you will need some style-sheets. There are two
   choices for the style-sheets, corresponding to the language used
   to write them - DSSSL or XSL. The XSL style-sheets not very
   solid at the moment, so I recommend you use the DSSSL
   style-sheets (MacOS users will have to use XSL style-sheets). In
   any case, both are downloadable from 
    http://www.nwalsh.com/docbook/index.html.
   Whichever you choose, copy the zip file to
   /usr/lib/sgml and unzip it there.
   You will then need to edit
   /usr/lib/sgml/docbook/catalog, to comment out
   the SGMLDECL on the final line.

5) You will need to create a catalog file. Mine looks like:

  OVERRIDE YES

  CATALOG "/usr/src/openjade-1.3/dsssl/catalog"
  CATALOG "/usr/lib/sgml/docbook.cat"
  CATALOG "/usr/lib/sgml/docbook/catalog"

Name it catalog and put it in the directory where your application
.xml files are.



For XSL: If you have chosen to use the XSL stylesheets, then you will need
   to install an XSLT processor. XT from James Clark is a suitable
   choice (there are other good choices). You should also install
   Norman's OASIS Catalog java classes.

   Then a suitable command line for producing html look like:

   java -Dxml.catalog.files=./catalog com.arbortext.xsl.sax.Driver top.xml \
     ../docbook/xhtml/docbook.xsl >index.html
   
   or for PDF:

   java -Dxml.catalog.files=./catalog com.arbortext.xsl.sax.Driver top.xml \
     ../docbook/fo/docbook.xsl >top.fo

   pdfxmltex top.fo

  The latter line requires that you install passivetex. An alternative
  is fop (neither work for me at present).

  In either case, you will probably want to write a driver
  styledsheet, instead of calling docbook.xsl direct, but the
  instructions for doing this are invisible.

For DSSSL (preferred for now):

  6) Download and install openjade from
     http://openjade.sourceforge.net/.

  7) Next, if you are going produce printed output, you
     will need to install jadetex. Get it from
     http://www.tug.org/applications/jadetex/
     then follow the doc/install.pdf instructions
     (use the Makefile in the jadetex source. The instructions
     omit to mention that you must run mktexlsr after creating
     hugetex.fmt).

  8) Write a drive DSSSL stylesheet - there are good instructions for
     doing this in the DSSSL stylesheet documentation (so download
     that too).

  Then to generate html pages, a shell script such as:

#! /bin/sh
export SP_ENCODING=XML
DB_STYLESHEET=`pwd`/driver.dsl
XML_DECLARATION=/usr/lib/sgml/docbook/dtds/decls/xml.dcl
HTML_STYLESHEET=docbook.css
ADMON_GRAPHICS=/usr/lib/sgml/docbook/images/*.gif

output=db2html-dir
TMPDIR=DBTOHTML_OUTPUT_DIR$$

echo TMPDIR is $TMPDIR

if [ $# -gt 2 ]
then
  echo "Usage: `basename $0` [filename.xml]" >&2
  exit 1
fi

if [ $# -eq 1 ]
then
  if [ ! -r $1 ]
  then
    echo Cannot read \"$1\".  Exiting. >&2
    exit 1
  fi
  if echo $1 | egrep -i '\.xml$' >/dev/null 2>&1
  then
    # now make sure that the output directory is always a subdirectory
    # of the current directory
    echo
    input_file=`basename $1`
    output=`basename $1 .xml`
    echo "input file was called $input_file -- output will be in $output"
    echo
  fi
fi

# we used to generate a single file, but with the modular DB_STYLESHEETs
# it's best to make a new directory with several html files in it

mkdir $TMPDIR
SAVE_PWD=`pwd`
if [ $1 = `basename $1` ]; then
  echo "working on ../$1"
  (cd $TMPDIR; openjade -c ../catalog -t sgml -ihtml -d ${DB_STYLESHEET} ${XML_DECLARATION} ../$1; cd $SAVE_PWD)
else
  echo "working on $1"
  (cd $TMPDIR; openjade -c catalog -t sgml -ihtml -d ${DB_STYLESHEET} ${XML_DECLARATION} $1; cd $SAVE_PWD)
fi

if [ $# -eq 1 ]
then
  if [ -d ${output}.junk ]
  then
    /bin/rm -rf ${output}.junk
  fi
  if [ -d ${output} ]
  then
    mv $output ${output}.junk
  fi
  
  echo "about to copy cascading stylesheet to temp dir"
  cp ${HTML_STYLESHEET} ${TMPDIR}/

  echo "about to copy admon graphics to temp dir"
  mkdir ${TMPDIR}/stylesheet-images
  cp ${ADMON_GRAPHICS} ${TMPDIR}/stylesheet-images
  echo "about to rename temporary directory to $output"
  mv ${TMPDIR} $output
else
  cat $TMPDIR/*
fi

rm -rf $TMPDIR

exit 0

   can be used. (The top-level xml filename needs to be given as a
   parameter to this script.

   For generating PDF output, a shell script such as:

#! /bin/sh

export SP_ENCODING=XML
STYLESHEET=`pwd`/driver.dsl
XML_DECLARATION=/usr/lib/sgml/docbook/dtds/decls/xml.dcl

TMPFN=`echo $1 | sed 's/\.xml//'`

if [ $# -gt 2 ]
then
  echo "Usage: `basename $0` [filename.xml]" >&2
  exit 1
fi

if [ $# -eq 1 ]
then
  if [ ! -r $1 ]
  then
    echo Cannot read \"$1\".  Exiting. >&2
    exit 1
  fi
  if echo $1 | egrep -i '\.xml$|\.xml$' >/dev/null 2>&1
  then
    output="`echo $1 | sed 's,\.xml$,.pdf,;s,\.xml$,.pdf,'`"
  fi
fi

openjade -c catalog -t tex -ioutput.print.pdf -d ${STYLESHEET} -o ${TMPFN}.tex ${XML_DECLARATION} $1

pdfjadetex $TMPFN

if egrep '^LaTeX Warning: There were undefined references.$' ${TMPFN}.log >/dev/null 2>&1
then
  pdfjadetex $TMPFN
  pdfjadetex $TMPFN
fi


#if [ -f ${TMPFN}.cfg ]
#then
#  mv ${TMPFN}.cfg jade.cfg
#fi

exit 0


  In both cases, you will get a LOT of warnings looking like:

openjade:/usr/lib/sgml/ent/iso-cyr1.ent:71:17:E: "X042F" is not a function name

You can ignore these.
-- 
Colin Paul Adams
Preston Lancashire