docbook/README.txt

   1 $Id$
   2
   3 This directory contains the source files needed to build the:
   4
   5 Ethereal User's guide (almost ready to release, has to be reviewed)
   6
   7 and the:
   8
   9 Ethereal Developer's Guide  (long time unchanged still a very early state).
  10
  11 To build the User's Guide, just do 'make', but see requirements below.
  12 The Developer's Guide is currently not generated, as it has no content.
  13
  14
  15 The guides are written in Docbook/XML (formerly Docbook/SGML). This format is
  16 now used by many other documentation projects, e.g. "the linux documentation
  17 project" uses it too.
  18
  19 To get HTML, PDF or other output formats, conversions are done using XSL
  20 stylesheets, which provides a flexible way for these conversions.
  21
  22 The current Makefile is running under Win32 in the cygwin environment, so it uses
  23 GNU make and such. It should be pretty easy to use it in UNIX environments too.
  24 Using Microsoft make (nmake) is not supported.
  25
  26 By default the Makefile generates HTML in single page and multiple (chunked) formats.
  27 Optional output formats are PDF and CHM.
  28
  29
  30 Requirements:
  31 -------------
  32
  33 Settings in Makefile and catalog.xml
  34 ------------------------------------
  35 You have to edit the settings in these files, to point to the DTD/XSL files, fop (and possibly hhc).
  36
  37 DocBook XML DTD
  38 ---------------
  39 DocBook "official" XML DTD V4.2 from:
  40 http://www.oasis-open.org/docbook/xml/
  41 (or using cygwin package docbook-xml42)
  42
  43 DocBook XSL
  44 -----------
  45 The "official" XSL stylesheets from Norman Walsh:
  46 http://docbook.sourceforge.net/
  47 (or using cygwin package docbook-xsl)
  48
  49 xsltproc
  50 --------
  51 The XSL processor xsltproc.
  52 (it seems to be packages libxml2 and libxslt, ... please give comments)
  53
  54 FOP processor (for PDF generation only)
  55 ---------------------------------------
  56 FOP processor from the apache project:
  57 http://xml.apache.org/fop/
  58 FOP is a JAVA program, so you need to have a JAVA environment installed.
  59 I have put the fop-0.20.5 dir right into the sources dir. If you have it somewhere else,
  60 you'll have to change the setting in the Makefile.
  61
  62 Be sure to also have installed JAI and/or jimi to be able to use/convert the png graphics files.
  63 The fop release note webpage tells how to do it:
  64 download jimi from:
  65 http://java.sun.com/products/jimi/
  66 then extract the archive, then copy JimiProClasses.zip to FOP's lib dir and rename it to jimi-1.0.jar.
  67
  68 As I got OutOfMemoryException when running fop, I had to insert -Xmx256m into the last line of the fop.bat file from:
  69 java -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
  70 to:
  71 java -Xmx256m -cp "%LOCALCLASSPATH%" org.apache.fop.apps.Fop %1 %2 %3 %4 %5 %6 %7 %8
  72
  73 HTML help compiler (for chm file generation only)
  74 -------------------------------------------------
  75 hhc compiler from Microsoft:
  76 http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/hwMicrosoftHTMLHelpDownloads.asp
  77
  78
  79 Makefile:
  80 ---------
  81 There are several ways and tools to do these conversion, following is a short
  82 description of the way the makefile targets are doing things and which output
  83 files required for a release in that format.
  84
  85 all
  86 Will generate all output formats (see below).
  87
  88 make eug_html
  89 The HTML file is generated using xsltproc and the XSL stylesheets from
  90 Norman Walsh. This is a conversion into a single HTML page.
  91 output: eug_html
  92
  93 make eug_htmlchunk
  94 The HTML files are generated using xsltproc and the XSL stylesheets from
  95 Norman Walsh. This is a conversion into chunked (multiple) HTML pages.
  96 output: eug_html_chunked
  97
  98 make eug_pdf_us
  99 make eug_pdf_a4
 100 The PDF is generated using an intermediate format named XSL-FO (XSL
 101 formatting objects). xsltproc converts the XML to a FO file, and then fop
 102 (apache's formatting object processor) is used to generate the PDF document,
 103 in US letter or A4 paper format.
 104 TIPP: You will get lot's of INFO/WARNING/ERROR messages when generating pdf,
 105 but conversation works just fine.
 106 output: user-guide.pdf
 107
 108 make eug_chm
 109 On Win32 platforms, the "famous" HTML help format can be generated by using a
 110 special HTML chunked conversion and then use the htmlhelp compiler from
 111 Microsoft.
 112 output: htmlhelp.chm
 113
 114 The makefile is written to be run with gmake on unix/linux platforms. Win32
 115 platforms have to use the cygwin environment (Microsoft nmake is not
 116 supported).
 117
 118
 119 Docbook web references:
 120 -----------------------
 121 Some web references to further documentation about Docbook/XML and Docbook XSL conversions:
 122
 123 DocBook: The Definitive Guide
 124 by Norman Walsh and Leonard Muellner
 125 http://www.docbook.org/tdg/en/html/docbook.html
 126
 127 DocBook XSL: The Complete Guide
 128 by Bob Stayton
 129 http://www.sagehill.net/docbookxsl/index.html
 130
 131 Documention with DocBook on Win32
 132 by Jim Crafton
 133 http://www.codeproject.com/winhelp/docbook_howto.asp
 134
 135 FO Parameter Reference
 136 by Norman Walsh
 137 http://docbook.sourceforge.net/release/xsl/current/doc/fo/