Producing_Open_Source_Software_Book: An HTML repository from svn2github

This directory contains the master sources for the book

               "Producing Open Source Software:
         How to Run a Successful Free Software Project"

by Karl Fogel.  You may have received this file as part of a static
package (e.g., producingoss-xml.tar.gz), or perhaps you checked out
the book from version control (see http://producingoss.com/vc.html).
Either way, the XML files here can be used to generate PostScript,
PDF, HTML, or other formats more suitable for readers.  These XML
files use the Docbook Lite DTD (a scaled-down version of Docbook;
see http://en.wikipedia.org/wiki/DocBook), from O'Reilly Media.
This document tells how to compile the sources into other formats.

Docbook
-------

  Docbook has a tortured, confusing history.  Before you do anything,
  take a look at Eric Raymond's excellent "Docbook Demystification HOWTO":

     http://tldp.org/HOWTO/DocBook-Demystification-HOWTO/

  It's very short and clears up many things.

Compiling
---------

1. Fetch XSL stylesheets for Docbook and place them in tools/xsl

   The "Docbook Open Repository" on Sourceforge has a large collection
   of XSL stylesheets that specifically operate on Docbook.  Download
   and install the latest 'docbook-xsl' package from this page:
  
      http://sourceforge.net/projects/docbook/files/docbook-xsl/

   Download the latest version of docbook-xsl, unpack it, then
   rename the unpacked directory to tools/xsl, something like this:

      $ cd tools
      $ tar zxvf docbook-xsl-X.YY.Z.tar.gz
      $ mv docbook-xsl-X.YY.Z xsl

   The default build process expects to the stylesheets to be in
   tools/xsl/.


2. Use XSLT to transform the book.

   XSLT applies an .xsl stylesheet to an .xml file, and produces some
   new markup document.

   * Get libxslt, a C library for XSLT, from http://xmlsoft.org/XSLT/.
     (If you're having trouble finding a source package to compile,
     try ftp://archive.progeny.com/GNOME/sources/libxslt/1.0/ or
     ftp://xmlsoft.org/libxslt/.)

     Install it:

        $ tar zxvf libxslt-1.0.22.tar.gz
        $ cd libxslt-1.0.22
        $ ./configure
        $ ./make
        # make install

     (Note: you may discover that you need to install libxml2 first.
     Find it at ftp://archive.progeny.com/GNOME/sources/libxml2/)

     If you don't want to compile libxslt, you can just fetch the
     appropriate OS binary package.  For example, on Debian GNU/Linux
     as of late 2011, packages "libxslt1.1" and "libxslt1-dev" were
     available; I also had to install package "xsltproc".

   * From the book directory, do 

        make all-html

     This produces a monolithic HTML version in book.html.
         
3. Make a PDF file.

   Formatting Objects (FO) is a layout language, kind of like
   postscript, dvi or css.  People are quickly standardizing on it.

   * Fetch FOP, a java program which converts .fo files into PDF:

        http://xml.apache.org/fop/index.html

     There are approximately 17577 ways to install FOP.  Rather than
     describe them all, we will recommend one way.  If you've already
     installed FOP some other way (e.g., via package "fop" on Debian
     GNU/Linux), then you can ignore the following recipe:

        1. Download the latest from 
           http://www.apache.org/dyn/closer.cgi/xmlgraphics/fop, for 
           example, fop-0.20.4-bin.tar.gz. Just get a binary 
           distribution, there's no need for the Java source.

        2. Unpack it into tools/fop/

           $ cd tools
           $ tar zxvf fop-0.20.4-bin.tar.gz
           $ mv fop-0.20.4 fop

     That should be enough.  The Makefile will actually invoke
     tools/bin/run-fop.sh.  That script attempts to find FOP already
     installed on your system, but falls back to the FOP unpacked into
     tools/fop/ if there's no other FOP available.

     Of course, to run FOP at all, you also need a Java runtime
     environment.  Try java.sun.com or www.blackdown.org if you don't
     already have that.

     Sometimes building the book can use more memory than Java is
     willing to allocate by default, and you may need to increase the
     default heap size.  With Sun's JVM, this is accomplished by
     passing the arguments "-Xms100m -Xmx200m" (known to work with
     versions 1.2.x-1.4.x, and likely different for JVMs from other
     vendors).  To tell fop.sh about these arguments, pass them via
     the environment variable FOP_OPTS (which is also configurable in
     your ~/.foprc).

        $ export FOP_OPTS="-Xms100m -Xmx200m"

     If you're doing all this on a Debian GNU/Linux system, you may
     see errors when the build process tries to run fop, like this:

     "/usr/bin/fop: Unable to locate servlet-api in /usr/share/java"

     If so, see http://wiki.debian.org/Java about setting a Java
     run-time environment on Debian.  You may still have problems -- I
     did, and have contacted freexian.com about paid help (2011-12-18).

   * If you want images to be included in the PDF, you'll need to use
     the JIMI image processing library.  Grab the latest release from
     http://java.sun.com/products/jimi/, then cp the jar file into the
     same place as the FOP jar files:

        $ cd tools/
        $ tar zxvf jimi1_0.tar.Z
        $ cp Jimi/examples/AppletDemo/JimiProClasses.jar fop/lib/

     Poof!  You now have PNG support.

   * From the top directory, do

        make all-pdf

     This produces book.pdf.


Hacking
-------

In addition to everything above, we recommend:

1. Get a nice editing environment for SGML/XML.

   This isn't strictly required, but it's nice when your editor
   colorizes things, understands the DTD, tells you what tags you can
   insert, etc.

   If you use emacs, we recommend the PSGML major-mode.  Most free
   operating systems package it, or its home page is here:

         http://www.lysator.liu.se/projects/about_psgml.html

   If you use vim, you might check out xmledit, at:

         http://www.vim.org/scripts/script.php?script_id=301


2. Get a validating parser.

   We recommend nsgmls, a parser written by James Clark:
   http://www.jclark.com/sp/nsgmls.  It's nice to check that the XML
   you write has matching tags, and follows the DTD correctly.

   Here is one command you can use to validate your xml:

   $ SP_CHARSET_FIXED=YES SP_ENCODING=XML nsgmls -wxml \
       -mdeclaration/xml.soc -ges                      \
       /path/to/your/declaration/xml.dcl book.xml


3. Read about the DocBook lite tags.

   See readme-dblite.html file which describes how to write with
   DocBook Lite.
svn2github/Producing_Open_Source_Software_Book
