Difference between revisions of "Writing Documentation"

From PKP Wiki
Jump to: navigation, search
(Transforming DocBook into Other Formats)
 
(31 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Writing Docbook Documentation for the PKP =
+
= Writing and Translating Docbook Documentation for the PKP =
  
'''This document is currently extremely incomplete, and undergoing revisions as I switch from DocBook4.5 to 5.0.'''
+
Official PKP documentation is written in [http://docbook.org DocBook XML]. DocBook XML is easy to write in and maintain, and allows us to quickly create HTML and PDF versions of our documentation from a single source file. Many XML Editors support DocBook, and two in particular ([http://www.xmlmind.com/xmleditor/ XXE] and [http://www.oxygenxml.com/ Oxygen XML]) include WYSIWYG-like editing features that make editing and translating documents easier for those who don't know XML.
  
Creating a Docbook XML sourcefile is mainly a matter of identifying what kind of document you are working on, what kinds of tags you should be using to describe your document. This meta-document details the steps I use to create book- and article-level source documentation for the Public Knowledge Project. It will also describe the steps I take to transform XML source files to HTML and PDF.  
+
This page will introduce DocBook briefly, and describe how we use it and the associated stylesheets to create documentation. It also describes how these documents may be easily translated and contributed back to PKP.  
  
 
== Resources ==
 
== Resources ==
Line 11: Line 11:
 
* [http://docbook.org/tdg5/ DocBook v5.0: The Definitive Guide]
 
* [http://docbook.org/tdg5/ DocBook v5.0: The Definitive Guide]
 
* [http://www.sagehill.net/docbookxsl/ DocBook XSL: The Complete Guide]
 
* [http://www.sagehill.net/docbookxsl/ DocBook XSL: The Complete Guide]
* [http://www.dpawson.co.uk/docbook/ Dave Pawson's DocBook site], may be slightly out-of-date
+
* [http://www.dpawson.co.uk/docbook/ Dave Pawson's DocBook site]
  
 
=== XML Editors ===
 
=== XML Editors ===
  
* [http://www.xmlmind.com/xmleditor/ XMLmind]
+
* [http://wiki.docbook.org/topic/DocBookAuthoringTools Exhaustive list on the DocBook wiki]
* [http://altova.com XMLSpy]
+
* [http://www.xmlmind.com/xmleditor/ XXE]: Multi-platform XML Editor. This Editor supports DocBook, and will provide a WYSIWYG interface. The personal edition is free, but the program itself is not Open Source.
* [http://oxygenxml.com oXygen]
+
* [http://www.oxygenxml.com/ Oxygen XML]: Multi-platform XML Editor. This Editor supports DocBook, and will provide a WYSIWYG interface. It is not Free/Open Source. There is a 30-day trial available.
* [http://www.adobe.com/products/framemaker/ Framemaker]
+
 
 +
=== Source and Transformation Files ===
 +
 
 +
* [http://sourceforge.net/projects/docbook/ DocBook XSL stylesheet library]
 +
* [http://github.com/pkp/docs XML document source files and custom XSL styleshets]
  
 
=== Validators ===
 
=== Validators ===
Line 25: Line 29:
 
* [http://xmlsoft.org/xmllint.html xmllint (available on most *nix systems)]
 
* [http://xmlsoft.org/xmllint.html xmllint (available on most *nix systems)]
  
== Writing an Article ==
+
(Note that many XML Editors include a validation function.)
  
First, choose whether you are writing a book or an article. This identifies the root element you'll start with: <book> or <article>. For the rest of this document, we'll assume we're writing an article. 
+
=== Other Interesting Stuff ===
  
At bare minimum, your source file will look like so:
+
* [http://www.onlamp.com/pub/a/php/2004/11/11/writingphp5.html 'Writing "Learning PHP 5"] -- an article by David Sklar; he talks about writing his book using DocBook Lite and XEmacs, with some neat keybindings.
 +
* [http://www.xml.com/pub/a/2007/06/20/getting-productive-with-xmlmind.html?page=1 Getting Productive with XMLMind] -- an article by O'Reilly on how they use XXE to edit their documents.
 +
* [http://ramikayyali.com/archives/2007/10/02/docbook_briefed a good intro into the whats and whys of DocBook]
  
<?xml version="1.0" encoding="UTF-8"?>
+
== Working with Documentation the Easy Way ==
<article xmlns="<nowiki>http://docbook.org/ns/docbook</nowiki>"
+
    xmlns:xl="<nowiki>http://www.w3.org/1999/xlink</nowiki>" version="5.0">
+
    <info>
+
        <title>Importing and Exporting Data with OJS</title>
+
        <author>
+
            <orgname>The Public Knowledge Project</orgname>
+
            <address>
+
                <city>Burnaby</city>
+
                <street>8888 University Drive</street>
+
                <postcode>V5A 1S6</postcode>
+
                <country>Canada</country>
+
            </address>
+
            <email>pkp-support@sfu.ca</email>
+
        </author>
+
    </info>
+
<sect1 xml:id="preface"><info><title>Preface</title></info>
+
    <para>...</para>
+
</sect1>
+
</article>
+
  
== Writing a Book ==
+
If you are only interested in translating or copyediting one of our already-existing documents, and are not worried about transforming the document into HTML or PDF, you are only a few steps away from doing so:
  
Info will come as I convert the OxS in an Hour docs as well as the Technical Reference. But mostly it's about using the following as your root element/namespace identifier:  
+
1. Download and install an XML Editor. I'd recommend one with an authoring/WYSIWYG option, such as XXE or Oxygen XML.
 +
 
 +
2. Download the most recent XML source file (and optionally, figures) from our [http://github.com/pkp/docs Github repository], or request them by sending an email to pkp.contact@gmail.com. For example, if you want to work on the OJS Userguide, download the source XML file and images (optional) from the following URL: http://github.com/pkp/docs/tree/master/ojs/userguide/.
 +
 
 +
* Note: You can use Git to download the full document repository if you want. Instructions are [http://pkp.sfu.ca/wiki/index.php/HOW-TO_check_out_PKP_applications_from_git here].
 +
 
 +
3. Open the document with your XML editor, switch to the authoring view, and edit away! You don't have to worry too much about the XML in the background, although it's a good idea to validate the document every once in a while. By stepping through the document systematically, you can edit and even translate the whole document one paragraph at a time, just as if it were a word processing document.
 +
 
 +
SCREENSHOTS
 +
 
 +
4. (Optional) Add/Update any images to reflect textual changes. If you have added content to the document, you may also want to add new figures: images, screenshots, etc. These should go into a Figures folder, and should either be linked to within the document, or should be referenced within the document for us to link to.
 +
 
 +
* If you are translating a large document such as the Userguide, be aware that it may include many, many screenshots, which are most likely in English. Replacing them with screenshots specific to your language may be very time consuming. You should evaluate whether it is better to have text only translated in a timely fashion, or whether a complete, images-included translation is worthwhile.
 +
 
 +
* To properly scale in PDF, all images must be saved with a resolution of 100 dpi, and shouldn't be wider than 6 inches.
 +
 
 +
5. Send your completed changes to PKP. Files can be sent to pkp.contact@gmail.com. If you are sending us a translation, we will host the translation on our site in HTML and PDF for others to benefit from, and will acknowledge your contribution online as well. If you are sending us a copyedited document, we will merge your changes into our source document; provide the updated HTML and PDF files online; and acknowledge your contribution online.
 +
 
 +
== Working with Documentation the Complete Way ==
 +
 
 +
Follow these instructions if you want to do more involved XML editing, and also manage the transformation from XML to HTML and/or PDF yourself.
 +
 
 +
1. To convert an XML file to HTML, you need an XSLT processor such as [http://xml.apache.org/xalan-j/ Xalan] or [http://xmlsoft.org/XSLT/xsltproc2.html xsltproc] installed on your system. xsltproc is available on many *nix systems, and its use will be described in this document. More XSLT processors are described [http://en.wikipedia.org/wiki/XML_template_engine here].
 +
 
 +
Converting an XML file into PDF is actually a two-step process: you first need to convert the file into a Formatting Object (FO) file, using an XSLT processor; and then convert the FO file into PDF using a Formatting Objects processor, such as [http://xmlgraphics.apache.org/fop/ fop]. Fop is used in this document.
 +
 
 +
2. If you want to manage the transformation of the source XML file into HTML and/or PDF yourself, you will need to download the [http://sourceforge.net/projects/docbook/ DocBook stylesheet library] and optionally, our most recent [http://github.com/pkp/docs/tree/master/xslt/ custom stylesheets].
 +
 
 +
* The file pkp.xsl is a custom XML->XHTML stylesheet, which will add a custom header and other information to the HTML output. It must be placed within the extracted DocBook stylesheet library, within the xhtml/ directory.
 +
 
 +
* The file pkpfo.xsl is a custom XML->FO stylesheet, which is needed as part of the PDF creation process, and which will result in a PKP-styled PDF document. It needs to go in the fo/ directory.
 +
 
 +
3. You also need to download a number of files common to all PKP documents. These header and footer images; a css stylesheet for HTML output; and organization logos. They can be found bundled together in the common/ directory in the [http://github.com/pkp/docs Git repository].
 +
 
 +
When transforming, proper document structure is important! The XSLT files expect the common/ directory to be at the same level as the document directory itself (eg. at the same level as userguide/). So if you want to transform a document that includes a number of figures, and want to include the common/ files, your directory structure would look like so:
 +
 
 +
documents/
 +
-- common/
 +
-- baronness_logo.git
 +
-- cc.png
 +
-- docstyle.css
 +
-- logo_list.png
 +
-- pkplogo.png
 +
-- userguide/
 +
-- figures/
 +
-- figure1.png
 +
-- figure2.png
 +
-- ...
 +
-- userguide.xml
 +
 
 +
4. Once you have edited the document, you can use your XSLT processor to transform the XML file into HTML. If you have an FO processor, you can also transform the XML to FO and then PDF.
 +
 
 +
If you have xsltproc installed, you can run the following command from the command line to convert the XML file to a set of HTML files. The command specifies an output type and file ("index.html"); specifies the stylesheet to be used to transform the XML file (in this example, the custom pkp.xsl file that can be downloaded as per step 2 above); and specifies the source XML document to be transformed. This example assumes that you are within the directory that the XML file resides in, and will create a number of chunked HTML files within that directory.
 +
 
 +
xsltproc --output index.html /path/to/docbook/xhtml/pkp.xsl userguide.xml
 +
 
 +
To create a PDF file, you must first transform the XML file into an FO file; and then transform that file to PDF. If you are using xsltproc and FOP, you can do so with the following two commands. The FO and PDF files will be created in the directory from which you run the commands; it's assumed that you are running these commands from the directory that the XML file resides in:  
 +
 
 +
xsltpro --output userguide.fo /path/to/docbook/fo/pkpfo.xsl userguide.xml
 +
/path/to/fop userguide.fo userguide.pdf
  
  
<?xml version="1.0" encoding="UTF-8"?>
 
<'''book''' xmlns="<nowiki>http://docbook.org/ns/docbook</nowiki>"
 
    xmlns:xl="<nowiki>http://www.w3.org/1999/xlink</nowiki>" version="5.0">
 
  
 
== Common DocBook Elements You Should be Using ==
 
== Common DocBook Elements You Should be Using ==
  
You can find a list of all elements for DocBook 5.0 [http://www.docbook.org/tdg5/en/html/pt02.html here].
+
You might find that you need to add some elements to the document you are editing. You can probably do this using the WYSIWYG/Author interface provided by the XML editor you are using; you can also use the following elements in the raw XML. You can find a list of all elements for DocBook 5.0 [http://www.docbook.org/tdg5/en/html/pt02.html here].
  
 
=== Inline Elements ===
 
=== Inline Elements ===
  
 
* Use '''<filename>'''/plugins/importExport/native/native.dtd'''</filename>''' when you are referring to file names and locations.  
 
* Use '''<filename>'''/plugins/importExport/native/native.dtd'''</filename>''' when you are referring to file names and locations.  
* Use '''<command'''>'''php importExport.php'''</command>''' when you reference commands.
+
* Use '''<command>'''php importExport.php'''</command>''' when you reference commands.
* Use''' <userinput>User Home'''</userinput>''' for referencing ... user ... input.
+
* Use '''<guibutton>'''User Home'''</guibutton>''' for referencing user input such as links, buttons, etc..
<para>To import a file, you can use
+
 
<userinput>&lt;embed&gt;</userinput> to place a file directly
+
=== Linking ===
within your XML document, or use
+
 
<userinput>&lt;href&gt;</userinput> to link to one.</para>
+
* Use '''<''element'' xl:href="<nowiki>http://pkp.sfu.ca</nowiki>">'''Public Knowledge Project'''</''element''>''' to hyperlink to an external page. "element" can be any inline element. You can also use "link" as a generic elementu.
* Use '''<![CDATA[['''<nowiki><p>all this text up in here</p></nowiki>''']]>''' for tags that should be ignored. This example would tell the parser to ignore those <p> tags. (Let me know if you come up with a clever way to ignore '''<![CDATA[]]>''' itself.)
+
* Use '''<''element'' linkend="sectionId">'''link text'''</''element''>''' for linking within the document itself. "element" can be any inline element. You can also use "link" as a generic element.
* Use '''<''element'' xl:href="<nowiki>http://pkp.sfu.ca</nowiki>">'''Public Knowledge Project'''</''element''>''' to hyperlink to an external page. "element" can be any inline element. You can also use "link" as a generic element I think.
+
 
* Use '''<''element'' linkend="sectionId">'''link text'''</''element''>''' for linking within the document itself. "element" can be any inline element. You can also use "link" as a generic element I think.
+
  
 
=== Block Elements ===
 
=== Block Elements ===
  
* Use <programlisting>/multiple lines of code/</programlisting> for large, multiline code blocks.
+
Block elements come into play when you have paragraph-level blocks of text that need to be identified and formatted differently than a normal paragraph, for example lists, examples, tips, and so on.
* Use <tip><para>this is a tip</para></tip> for notes, suggestions, tips, etc.
+
 
 +
* '''For code examples, listings, etc.:'''
 +
<example>
 +
      <title>Example Code Snippet</title>
 +
      <programlisting>/multiple lines of code/</programlisting>
 +
</example>
 +
 
 +
for large, multiline code blocks. You can also use <informalexample> and omit the title information.  
 +
 
 +
* '''For Tips:'''
 +
<tip>
 +
      <para>this is a tip</para>
 +
</tip>
 +
 
 +
* '''For Warnings'''
 +
<warning>
 +
      <para>this is a warning</para>
 +
</warning>
 +
 
 +
* '''For Notes'''
 +
<note>
 +
      <para>this is a note</para>
 +
</note>
 +
 
 +
* '''For non-numbered lists:'''
 +
 
 +
<itemizedlist>
 +
      <listitem>
 +
          <para>Item one</para>
 +
      </listitem>
 +
      <listitem>
 +
          <para>Item two</para>
 +
      </listitem>
 +
      <listitem>
 +
          <para>Item three</para>
 +
      </listitem>
 +
</itemizedList>
 +
 
 +
* '''For ordered lists:'''
 +
 
 +
<orderedlist>
 +
      <listitem>
 +
          <para>Item one</para>
 +
      </listitem>
 +
      <listitem>
 +
          <para>Item two</para>
 +
      </listitem>
 +
      <listitem>
 +
          <para>Item three</para>
 +
      </listitem>
 +
</itemizedList>
 +
 
  
== Transforming DocBook into Other Formats ==
+
== Setting up the Tools you need to work with DocBook ==
  
 
[http://www.sagehill.net/docbookxsl/ DocBook XSL: The Complete Guide] has a very good [http://www.sagehill.net/docbookxsl/ToolsSetup.html chapter] on setting up all the tools you'll need to transform DocBook XML into HTML and PDF. You can download OS/platform-specific packages [http://wiki.docbook.org/topic/DocBookPackages here], or at a minimum you can make sure you have the following installed:  
 
[http://www.sagehill.net/docbookxsl/ DocBook XSL: The Complete Guide] has a very good [http://www.sagehill.net/docbookxsl/ToolsSetup.html chapter] on setting up all the tools you'll need to transform DocBook XML into HTML and PDF. You can download OS/platform-specific packages [http://wiki.docbook.org/topic/DocBookPackages here], or at a minimum you can make sure you have the following installed:  
Line 94: Line 187:
 
=== Installing this stuff on Ubuntu ===
 
=== Installing this stuff on Ubuntu ===
  
I'm currently handling all of my transformations on Ubuntu using [http://xmlsoft.org/XSLT/xsltproc2.html xsltproc] for HTML and FO, and [http://xmlgraphics.apache.org/fop/ FOP] for FO->PDF. The following instructions will assume you are using the same tools in the same general environment.  
+
You can transform XML files into HTML and PDF in Ubuntu/Debian using [http://xmlsoft.org/XSLT/xsltproc2.html xsltproc] for HTML and FO, and [http://xmlgraphics.apache.org/fop/ FOP] for FO->PDF. The following instructions will assume you are using the same tools in the same general environment.  
  
 
To install the first three items in Ubuntu, install the following packages through apt-get or Synaptic: docbook-xml (installs the DTD), docbook-xsl (the stylesheets), xsltproc (the tool to transform to HTML and FO). Ubuntu installs the stylesheets to /usr/share/xml/docbook/stylesheet/nwalsh/. You can put them anywhere you want because you'll just be pointing to particular ones with xsltproc, but I'll reference that location below. You can also download them separately if you're not running Ubuntu from [http://docbook.sourceforge.net/ here].  
 
To install the first three items in Ubuntu, install the following packages through apt-get or Synaptic: docbook-xml (installs the DTD), docbook-xsl (the stylesheets), xsltproc (the tool to transform to HTML and FO). Ubuntu installs the stylesheets to /usr/share/xml/docbook/stylesheet/nwalsh/. You can put them anywhere you want because you'll just be pointing to particular ones with xsltproc, but I'll reference that location below. You can also download them separately if you're not running Ubuntu from [http://docbook.sourceforge.net/ here].  
Line 100: Line 193:
 
You can't use Synaptic or apt-get to install FOP on Ubuntu, but the DocBook XSL guide has a page on installing it [http://www.sagehill.net/docbookxsl/InstallingAnFO.html#InstallFop here]. I had some minor difficulty in getting it to work, but if memory serves that was a Java problem that got fixed by paying attention to the guide.  
 
You can't use Synaptic or apt-get to install FOP on Ubuntu, but the DocBook XSL guide has a page on installing it [http://www.sagehill.net/docbookxsl/InstallingAnFO.html#InstallFop here]. I had some minor difficulty in getting it to work, but if memory serves that was a Java problem that got fixed by paying attention to the guide.  
  
 +
=== Installing this stuff on Mac OS X ===
  
=== DocBook to HTML ===
+
Rough notes on moving my environment from Ubuntu to OS X:
 
+
If you have a valid DocBook XML file by the name of example.xml, you should now be able to run the command
+
 
+
xsltproc --output example.html /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/docbook.xsl example.xml
+
 
+
That line is basically saying "take example.xml, and use the xHTML docbook stylesheet in conjunction with xsltproc to spit out example.html".
+
  
To "chunk", or split your outputted by section into multiple pages, use
+
* '''For the stylesheets:''' Download the [http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=16608 docbook xsl stylesheets] from Sourceforge; install them somewhere reasonable (I extracted the tar file to /Users/jmacgreg/docbook). You'll have to remember this path later.
  
xsltproc --output /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/chunk.xsl example.xml
+
* '''For the XSLT Processor:''' Use xsltproc -- this should already be on your machine and available from the terminal.  
  
I've created a PKP-specific [http://www.sagehill.net/docbookxsl/CustomMethods.html#CustomizationLayer customization layer] that adds header image links and a link to the PKP documentation stylesheet, available [http://deadcancon.org/pkp.xsl here]. You'll have to add it to the xhtml stylesheet directory, as it references chunk.xsl.
+
* '''For the XSL-FO Processor:''' Install [http://macports.org macports]. With macports, install fop:
  
=== PDF ===
+
sudo port install fop

Latest revision as of 15:11, 23 June 2010

Writing and Translating Docbook Documentation for the PKP

Official PKP documentation is written in DocBook XML. DocBook XML is easy to write in and maintain, and allows us to quickly create HTML and PDF versions of our documentation from a single source file. Many XML Editors support DocBook, and two in particular (XXE and Oxygen XML) include WYSIWYG-like editing features that make editing and translating documents easier for those who don't know XML.

This page will introduce DocBook briefly, and describe how we use it and the associated stylesheets to create documentation. It also describes how these documents may be easily translated and contributed back to PKP.

Resources

Writings, books on DocBook

XML Editors

  • Exhaustive list on the DocBook wiki
  • XXE: Multi-platform XML Editor. This Editor supports DocBook, and will provide a WYSIWYG interface. The personal edition is free, but the program itself is not Open Source.
  • Oxygen XML: Multi-platform XML Editor. This Editor supports DocBook, and will provide a WYSIWYG interface. It is not Free/Open Source. There is a 30-day trial available.

Source and Transformation Files

Validators

(Note that many XML Editors include a validation function.)

Other Interesting Stuff

Working with Documentation the Easy Way

If you are only interested in translating or copyediting one of our already-existing documents, and are not worried about transforming the document into HTML or PDF, you are only a few steps away from doing so:

1. Download and install an XML Editor. I'd recommend one with an authoring/WYSIWYG option, such as XXE or Oxygen XML.

2. Download the most recent XML source file (and optionally, figures) from our Github repository, or request them by sending an email to pkp.contact@gmail.com. For example, if you want to work on the OJS Userguide, download the source XML file and images (optional) from the following URL: http://github.com/pkp/docs/tree/master/ojs/userguide/.

  • Note: You can use Git to download the full document repository if you want. Instructions are here.

3. Open the document with your XML editor, switch to the authoring view, and edit away! You don't have to worry too much about the XML in the background, although it's a good idea to validate the document every once in a while. By stepping through the document systematically, you can edit and even translate the whole document one paragraph at a time, just as if it were a word processing document.

SCREENSHOTS

4. (Optional) Add/Update any images to reflect textual changes. If you have added content to the document, you may also want to add new figures: images, screenshots, etc. These should go into a Figures folder, and should either be linked to within the document, or should be referenced within the document for us to link to.

  • If you are translating a large document such as the Userguide, be aware that it may include many, many screenshots, which are most likely in English. Replacing them with screenshots specific to your language may be very time consuming. You should evaluate whether it is better to have text only translated in a timely fashion, or whether a complete, images-included translation is worthwhile.
  • To properly scale in PDF, all images must be saved with a resolution of 100 dpi, and shouldn't be wider than 6 inches.

5. Send your completed changes to PKP. Files can be sent to pkp.contact@gmail.com. If you are sending us a translation, we will host the translation on our site in HTML and PDF for others to benefit from, and will acknowledge your contribution online as well. If you are sending us a copyedited document, we will merge your changes into our source document; provide the updated HTML and PDF files online; and acknowledge your contribution online.

Working with Documentation the Complete Way

Follow these instructions if you want to do more involved XML editing, and also manage the transformation from XML to HTML and/or PDF yourself.

1. To convert an XML file to HTML, you need an XSLT processor such as Xalan or xsltproc installed on your system. xsltproc is available on many *nix systems, and its use will be described in this document. More XSLT processors are described here.

Converting an XML file into PDF is actually a two-step process: you first need to convert the file into a Formatting Object (FO) file, using an XSLT processor; and then convert the FO file into PDF using a Formatting Objects processor, such as fop. Fop is used in this document.

2. If you want to manage the transformation of the source XML file into HTML and/or PDF yourself, you will need to download the DocBook stylesheet library and optionally, our most recent custom stylesheets.

  • The file pkp.xsl is a custom XML->XHTML stylesheet, which will add a custom header and other information to the HTML output. It must be placed within the extracted DocBook stylesheet library, within the xhtml/ directory.
  • The file pkpfo.xsl is a custom XML->FO stylesheet, which is needed as part of the PDF creation process, and which will result in a PKP-styled PDF document. It needs to go in the fo/ directory.

3. You also need to download a number of files common to all PKP documents. These header and footer images; a css stylesheet for HTML output; and organization logos. They can be found bundled together in the common/ directory in the Git repository.

When transforming, proper document structure is important! The XSLT files expect the common/ directory to be at the same level as the document directory itself (eg. at the same level as userguide/). So if you want to transform a document that includes a number of figures, and want to include the common/ files, your directory structure would look like so:

documents/ -- common/ -- baronness_logo.git -- cc.png -- docstyle.css -- logo_list.png -- pkplogo.png -- userguide/ -- figures/ -- figure1.png -- figure2.png -- ... -- userguide.xml

4. Once you have edited the document, you can use your XSLT processor to transform the XML file into HTML. If you have an FO processor, you can also transform the XML to FO and then PDF.

If you have xsltproc installed, you can run the following command from the command line to convert the XML file to a set of HTML files. The command specifies an output type and file ("index.html"); specifies the stylesheet to be used to transform the XML file (in this example, the custom pkp.xsl file that can be downloaded as per step 2 above); and specifies the source XML document to be transformed. This example assumes that you are within the directory that the XML file resides in, and will create a number of chunked HTML files within that directory.

xsltproc --output index.html /path/to/docbook/xhtml/pkp.xsl userguide.xml

To create a PDF file, you must first transform the XML file into an FO file; and then transform that file to PDF. If you are using xsltproc and FOP, you can do so with the following two commands. The FO and PDF files will be created in the directory from which you run the commands; it's assumed that you are running these commands from the directory that the XML file resides in:

xsltpro --output userguide.fo /path/to/docbook/fo/pkpfo.xsl userguide.xml
/path/to/fop userguide.fo userguide.pdf


Common DocBook Elements You Should be Using

You might find that you need to add some elements to the document you are editing. You can probably do this using the WYSIWYG/Author interface provided by the XML editor you are using; you can also use the following elements in the raw XML. You can find a list of all elements for DocBook 5.0 here.

Inline Elements

  • Use <filename>/plugins/importExport/native/native.dtd</filename> when you are referring to file names and locations.
  • Use <command>php importExport.php</command> when you reference commands.
  • Use <guibutton>User Home</guibutton> for referencing user input such as links, buttons, etc..

Linking

  • Use <element xl:href="http://pkp.sfu.ca">Public Knowledge Project</element> to hyperlink to an external page. "element" can be any inline element. You can also use "link" as a generic elementu.
  • Use <element linkend="sectionId">link text</element> for linking within the document itself. "element" can be any inline element. You can also use "link" as a generic element.


Block Elements

Block elements come into play when you have paragraph-level blocks of text that need to be identified and formatted differently than a normal paragraph, for example lists, examples, tips, and so on.

  • For code examples, listings, etc.:
<example>
     <title>Example Code Snippet</title>
     <programlisting>/multiple lines of code/</programlisting>
</example>

for large, multiline code blocks. You can also use <informalexample> and omit the title information.

  • For Tips:
<tip>
     <para>this is a tip</para>
</tip>
  • For Warnings
<warning>
     <para>this is a warning</para>
</warning>
  • For Notes
<note>
     <para>this is a note</para>
</note>
  • For non-numbered lists:
<itemizedlist>
     <listitem>
          <para>Item one</para>
     </listitem>
     <listitem>
          <para>Item two</para>
     </listitem>
     <listitem>
          <para>Item three</para>
     </listitem>
</itemizedList>
  • For ordered lists:
<orderedlist>
     <listitem>
          <para>Item one</para>
     </listitem>
     <listitem>
          <para>Item two</para>
     </listitem>
     <listitem>
          <para>Item three</para>
     </listitem>
</itemizedList>


Setting up the Tools you need to work with DocBook

DocBook XSL: The Complete Guide has a very good chapter on setting up all the tools you'll need to transform DocBook XML into HTML and PDF. You can download OS/platform-specific packages here, or at a minimum you can make sure you have the following installed:

  • DocBook DTD (you can always point to an online DTD, of course)
  • DocBook XSL Stylesheets
  • XSLT Processor (to transform to HTML and FO)
  • XSL-FO Processor (to transform from FO to PDF)

Installing this stuff on Ubuntu

You can transform XML files into HTML and PDF in Ubuntu/Debian using xsltproc for HTML and FO, and FOP for FO->PDF. The following instructions will assume you are using the same tools in the same general environment.

To install the first three items in Ubuntu, install the following packages through apt-get or Synaptic: docbook-xml (installs the DTD), docbook-xsl (the stylesheets), xsltproc (the tool to transform to HTML and FO). Ubuntu installs the stylesheets to /usr/share/xml/docbook/stylesheet/nwalsh/. You can put them anywhere you want because you'll just be pointing to particular ones with xsltproc, but I'll reference that location below. You can also download them separately if you're not running Ubuntu from here.

You can't use Synaptic or apt-get to install FOP on Ubuntu, but the DocBook XSL guide has a page on installing it here. I had some minor difficulty in getting it to work, but if memory serves that was a Java problem that got fixed by paying attention to the guide.

Installing this stuff on Mac OS X

Rough notes on moving my environment from Ubuntu to OS X:

  • For the stylesheets: Download the docbook xsl stylesheets from Sourceforge; install them somewhere reasonable (I extracted the tar file to /Users/jmacgreg/docbook). You'll have to remember this path later.
  • For the XSLT Processor: Use xsltproc -- this should already be on your machine and available from the terminal.
  • For the XSL-FO Processor: Install macports. With macports, install fop:
sudo port install fop