Writing Documentation

From PKP Wiki
Jump to: navigation, search

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.


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


(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.


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..


  • 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.:
     <title>Example Code Snippet</title>
     <programlisting>/multiple lines of code/</programlisting>

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

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

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