6. Generating Output
Prev   Next

6. Generating Output

We currently need several output formats for most manuals. “Chunk HTML” is needed for the web site. This is HTML output split into manageable chunks so that documentation can be read easily online. For those interested in browsing the HTML offline with a browser, we need downloadable copies in HTML format, too. Finally, we need PDF format output so that users can print off the documentation for use when not connected to the Internet or just because they like printed manuals.

Use any method that works on your system to generate output. If you can produce one output format using any tool, other volunteers will produce the “official” output from your DocBook XML source. Generally, if the DocBook syntax will produce any output it will produce all formats, using all XSLs and any other tool.

If possible, please use the Linux Documentation Project's XSL files to generate both HTML files and directories. You may have to edit both the ldp-html-chunk.xsl and ldp-html.xsl to change the path to your DocBook XSL files. At this time, the LDP XSL files do not produce print files.

6.1. Generating Output On Linux

There are several commands available under Linux to convert DocBook XML to output. I have been successful at generating both types of HTML on Linux using xsltproc. Use the following command: 

C:\>xsltproc -o outfile /path/to/ldpxsl/ldp-html?????.xsl /your/file.xml
Where /path/to/ldpxsl/ldp-html?????.xsl can point to either ldp-html-chunk.xsl or ldp-html.xsl. outfile is an html output file for ldp-html.xsl. For ldp-html-chunk.xsl end it with a "/" to indicate an existing directory that will receive the HTML chunks. Finally, /your/file.xml is your DocBook source file.

On Linux, the 

$ db2pdf /your/file.xml
command can be used to generate PDF files.

You may also want to use the xmlto, db2xxx and the docbook2xxx command sets. Check the man pages for db2pdf, docbook2pdf and xmlto.

6.2. Generating Output On Windows

Use the E-Novative .bat files to create and initialize a directory for the manual you wish to work on. For example, if you wish to modify the Installation Manual, issue the 

C:\\docbook\bat\docbook_create book ipcop-install-en
command. This will create a C:\docbook\book\ipcop-install-en directory, and place a dummy ipcop-install-en.xml file in it. Change the header in the generated file to: 
<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE book
  PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "../../dtd/docbookx.dtd"
  [
    <!ENTITY imagepath "/ipcopdoc/images/install/" >
    <!ENTITY fdlfile SYSTEM "/ipcopdoc/en/fdlappendix.xml" >
    <!ENTITY % global.entities SYSTEM "../../include/global.xml">
    %global.entities;

    <!ENTITY % entities SYSTEM "entities.xml">
    %entities;
  ]
>
Where the imagepath entity should point to the directory where the graphics for your manual reside and fdlfile should point to the FDL fdlappendix.xml file. Then merge in the rest of the document. Note: DocBook tools recognize forward slashes in filenames, even under Windows.

With the start of the file modified as described, above, it should be possible to use the E-Novative .bat commands to generate output from your XML files. You may receive lots of warning and error messages when generating PDF files, but the output seems to be OK.

Prev Up Next
5. Guidelines For IPCop Documentation  Home 7. CVS