cvs commit: LFS/newxml INSTALL README

matthew at linuxfromscratch.org matthew at linuxfromscratch.org
Mon May 3 03:19:01 PDT 2004


matthew     04/05/03 04:19:01

  Modified:    newxml   README
  Added:       newxml   INSTALL
  Log:
  * Changed README and added INSTALL to match the format in current HEAD.  Also
    removed a lot of instructions that are already in BLFS.
  
  Revision  Changes    Path
  1.12      +17 -207   LFS/newxml/README
  
  Index: README
  ===================================================================
  RCS file: /home/cvsroot/LFS/newxml/README,v
  retrieving revision 1.11
  retrieving revision 1.12
  diff -u -r1.11 -r1.12
  --- README	1 Apr 2004 22:33:25 -0000	1.11
  +++ README	3 May 2004 10:19:01 -0000	1.12
  @@ -1,210 +1,20 @@
  -README for the newxml module
  -~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  +LFS Book Readme
   
  -1. Requirements
  -~~~~~~~~~~~~~~~
  +This document is meant to instruct the user on how to convert the book's XML 
  +source to other formats (e.g. HTML, PDF, PS and TXT).  First, if you have not 
  +already done so, please read the INSTALL file for instructions on how to install
  +the required software.  If you have already completed the steps outlined in the
  +INSTALL file, then continue reading for examples how to convert these files into
  +various other formats.
   
  -DocBook XML DTD 4.3 - this is required as the 4.2 version doesn't properly
  -                      support XIncludes
  +XML to XHTML:
  +-------------
   
  -DocBook XSL Stylesheets 1.65.1 - older versions of the stylesheets had a bug
  -                                 which caused broken hyperlinks (they pointed to
  -                                 the wrong directory).
  -
  -libxml2-2.6.8 & libxslt-1.1.5 - these releases have a couple of XInclude related
  -                                bugfixes in them
  -
  -FOP-0.20.5 - required for PDF generation.  The easiest method of installation is
  -             to download the binary tarball, extract it to /opt/fop and set
  -             JAVA_HOME, FOP_HOME and PATH appropriately.
  -
  -2. Setting up the DTD
  -~~~~~~~~~~~~~~~~~~~~~
  -
  -2.1. Short and swift version
  -~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  -
  -If you're comfortable with it then here's a quick run down of what needs
  -to be done:
  -
  -1) Follow the instructions in the *first* grey box in the BLFS book, but
  -   substitute 4.2 with 4.3.  This will install the 4.3 version of the DTD and
  -   allow local resolution.
  -
  -2) Follow the instructions in the *second* grey box in the BLFS book, but
  -   substituting 4.2 with 4.3.  This allows processing of the BLFS book against
  -   the 4.3 DTD.
  -
  -3) Follow the instructions in the *third* grey box in the BLFS book, but
  -   substitute 4.2 with 4.3.  This allows anything wanting to use the 4.1.2
  -   version of the DTD to use our local copy of 4.3 instead.
  -
  -4) Follow the instructions in the *third* grey box *again*, but this time
  -   substitute 4.2 with 4.3 and 4.1.2 with 4.2.  This allows anything wanting
  -   to use the 4.2 version of the DTD to use our local copy of 4.3.
  -
  -
  -2.2. The long winded but (hopefully) RPM/APT/YAST user proof method
  -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  -
  -2.2.1. Install the 4.3 version of the DTD
  -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  -
  -install -d /usr/share/xml/docbook/xml-dtd-4.3 &&
  -cp -af docbook.cat *.dtd ent/ *.mod /usr/share/xml/docbook/xml-dtd-4.3 &&
  -if [ ! -e /etc/xml/catalog ]; then mkdir -p /etc/xml; xmlcatalog --noout \
  ---create /etc/xml/catalog; fi &&
  -if [ ! -e /etc/xml/docbook ]; then xmlcatalog --noout --create \
  -/etc/xml/docbook; fi &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//ELEMENTS DocBook XML Information Pool V4.3//EN" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3/dbpoolx.mod" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//DTD DocBook XML V4.3//EN" \
  -"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//ENTITIES DocBook XML Character Entities V4.3//EN" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3/dbcentx.mod" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//ENTITIES DocBook XML Notations V4.3//EN" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3/dbnotnx.mod" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//ENTITIES DocBook XML Additional General Entities V4.3//EN" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3/dbgenent.mod" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//ELEMENTS DocBook XML Document Hierarchy V4.3//EN" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3/dbhierx.mod" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//DTD XML Exchange Table Model 19990315//EN" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3/soextblx.dtd" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//DTD DocBook XML CALS Table Model V4.3//EN" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3/calstblx.dtd" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "rewriteSystem" \
  -"http://www.oasis-open.org/docbook/xml/4.3" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "rewriteURI" \
  -"http://www.oasis-open.org/docbook/xml/4.3" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "delegatePublic" \
  -"-//OASIS//ENTITIES DocBook XML" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "delegatePublic" \
  -"-//OASIS//DTD DocBook XML" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "delegateSystem" \
  -"http://www.oasis-open.org/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "delegateURI" \
  -"http://www.oasis-open.org/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog
  -
  -2.2.2. Enable processing of the BLFS book
  -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  -
  -xmlcatalog --noout --add "delegateSystem" \
  -"/usr/share/docbook/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "delegateURI" \
  -"/usr/share/docbook/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "rewriteSystem" \
  -"/usr/share/docbook" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "rewriteURI" \
  -"/usr/share/docbook" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook
  -
  -2.2.3. Enable 4.3 to be used when 4.1.2. is requested
  -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  -
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//DTD DocBook XML V4.1.2//EN" \
  -"http://oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "delegateSystem" \
  -"http://www.oasis-open.org/docbook/xml/4.1.2/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "delegateURI" \
  -"http://www.oasis-open.org/docbook/xml/4.1.2/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "rewriteSystem" \
  -"http://www.oasis-open.org/docbook/xml/4.1.2" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "rewriteURI" \
  -"http://www.oasis-open.org/docbook/xml/4.1.2" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook
  -
  -2.2.4. Enable 4.3 to be used when 4.2 is requested
  -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  -
  -xmlcatalog --noout --add "public" \
  -"-//OASIS//DTD DocBook XML V4.2//EN" \
  -"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "delegateSystem" \
  -"http://www.oasis-open.org/docbook/xml/4.2/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "delegateURI" \
  -"http://www.oasis-open.org/docbook/xml/4.2/" \
  -"file:///etc/xml/docbook" /etc/xml/catalog &&
  -xmlcatalog --noout --add "rewriteSystem" \
  -"http://www.oasis-open.org/docbook/xml/4.2" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook &&
  -xmlcatalog --noout --add "rewriteURI" \
  -"http://www.oasis-open.org/docbook/xml/4.2" \
  -"file:///usr/share/xml/docbook/xml-dtd-4.3" \
  -/etc/xml/docbook
  -
  -
  -3. Processing the sources
  -~~~~~~~~~~~~~~~~~~~~~~~~~
  -
  -By far the easiest way to process the source is by running `make`.  An
  -explanation of the process follows:
  -
  -For the HTML output, we run the top-level index.xml file through
  -xsltproc in conjunction with the lfs-chunked.xsl stylesheet.  The
  -index.xml file just has a bunch of XInclude instructions in it, which
  -pull in all the different chapters of the book.  The lfs-chunked
  -stylesheet (in stylesheets/) is a customisation layer, on top of the
  -docbook-xsl XHTML/chunked.xsl stylesheet.  It basically configures some
  -layout related variables to tweak the output to the liking of the LFS
  -readership.  The majority of work is delegated to the docbook-xsl
  -stylesheets.  Note that the directory that the HTML files are output to
  -can be altered by changing the BASEDIR variable at the top of the Makefile,
  -ensuring that when you do so, you're new value has a trailing "/".
  -
  -For the PDF output we use a two stage process.  The first stage creates an
  -XSL-FO (Formatting Objects) file, which is essentially an output-format
  -independent description of the layout of the book.  xsltproc carries out
  -this part of the processing for us, again taking index.xml as the input
  -source and stylesheets/lfs-pdf.xsl as it's stylesheet.  Similar to
  -lfs-chunked.xsl, lfs-pdf.xsl is a customisation layer around
  -docbook-xsl's fo/docbook.xsl stylesheet.  Once generated, the .fo file
  -can then be fed into a FO Processor, which can translate it into any format it
  -supports.  In our case we use FOP (http://xml.apache.org/fop/index.html), which
  -requires a Java runtime environment.  Note that FOP is currently
  -undergoing a redesign, and as such they have two versions available for
  -download.  It is recommended to use the 0.20.5 version at this time.
  -FOP is simply told which FO file to process and the name of the output file (it
  -infers the desired output format from the file extension).
  -
  -In time their will be other XSL files in the stylesheets directory to
  -process the sources into formats such as LaTeX, Text, nALFS profiles and others
  -(if requested).
  +BASEDIR=/path/to/output/location make
  +
  +
  +XML to PDF:
  +-----------
  +
  +make pdf &&
  +cp lfs.pdf /path/to/output/location
  
  
  
  1.1                  LFS/newxml/INSTALL
  
  Index: INSTALL
  ===================================================================
  LFS Book Conversion Tools Installation Instructions
  
  After downloading the CVS source, there are some things that need to be set up 
  on your computer if you want to convert the XML source into something easier to 
  read (e.g. HTML, TXT, PS or PDF).  If you are interested in this, then keep 
  reading.  If you are only interested in editing the XML source for re- 
  submission to the lfs-book or lfs-dev mailing lists, then you do not need this 
  document.  Instead, you need to read the LFS Editor's Manual.  See the LFS 
  website at http://www.linuxfromscratch.org for more information.
  
  -------------------------------------------------------------------------------
  If all you want to do is convert XML to HTML perform the following:
  
  * libxml2
    - http://www.linuxfromscratch.org/blfs/view/cvs/general/libxml2.html
  
  * libxslt
    - http://www.linuxfromscratch.org/blfs/view/cvs/general/libxslt.html
  
  * DocBook DTD 
    - http://www.linuxfromscratch.org/blfs/view/cvs/pst/DocBook.html
  
  * DocBook XSL Stylesheets 
    - http://www.linuxfromscratch.org/blfs/view/cvs/pst/docbook-xsl.html
  
  ------------------------------------------------------------------------------- 
  If you want to be able to convert the book into PDF as well, then you will need
  the FOP package.  This takes an XSL-FO file (created with libxslt which you
  already installed) and converts it to PDF:
  
    - http://www.apache.org/dist/xml/fop/fop-0.20.5-bin.tar.gz
  
    Install FOP by running:
  
    cd /opt &&
    tar -xzvf /usr/src/fop-0.20.5-bin.tar.gz &&
    mv fop-0.20.5 fop
  
    Now set JAVA_HOME, FOP_HOME and PATH to values appropriate to your system.
  
  
  



More information about the lfs-book mailing list