Difference between revisions of "Writing Documentation"

From PKP Wiki
Jump to: navigation, search
(Other interesting stuff)
 
(8 intermediate revisions by 2 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://wiki.docbook.org/topic/DocBookAuthoringTools Exhaustive list on the DocBook wiki]
 
* [http://wiki.docbook.org/topic/DocBookAuthoringTools Exhaustive list on the DocBook wiki]
 +
* [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://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.
 +
 +
=== 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 22: Line 29:
 
* [http://xmlsoft.org/xmllint.html xmllint (available on most *nix systems)]
 
* [http://xmlsoft.org/xmllint.html xmllint (available on most *nix systems)]
  
=== Other interesting stuff ===
+
(Note that many XML Editors include a validation function.)
 +
 
 +
=== Other Interesting Stuff ===
  
 
* [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.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]
 
* [http://ramikayyali.com/archives/2007/10/02/docbook_briefed a good intro into the whats and whys of DocBook]
  
== Writing an Article ==
+
== Working with Documentation the Easy Way ==
  
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. 
+
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:
  
At bare minimum, your source file will look like so:
+
1. Download and install an XML Editor. I'd recommend one with an authoring/WYSIWYG option, such as XXE or Oxygen XML.
  
<?xml version="1.0" encoding="UTF-8"?>
+
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/.  
<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"><title>Preface</title>
+
       
+
        <para>Open Journal Systems is a research and development initiative of the Public Knowledge
+
            Project at the University of British Columbia. Its continuing development is currently
+
            overseen by a partnership among UBC's Public Knowledge Project, the Canadian Center for
+
            Studies in Publishing, and the Simon Fraser University Library. For more information,
+
            see the Public Knowledge Project web site:
+
            <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://pkp.sfu.ca">http://pkp.sfu.ca</link>.
+
        </para>
+
+
        <para>This work is licensed under the Creative Commons Attribution-Share Alike 2.5 Canada
+
            License. To view a copy of this license, visit
+
            <link xmlns:xlink="http://www.w3.org/1999/xlink"
+
            xlink:href="http://creativecommons.org/licenses/by-sa/2.5/ca/">http://creativecommons.org/licenses/by-sa/2.5/ca/</link>
+
            or send a letter to Creative Commons, 559 Nathan Abbott Way, Stanford, California 94305, USA.
+
        </para>
+
           
+
    </sect1>
+
</article>
+
  
Using ''<sect>'' tags, you can create a nicely-nested article with main section, subsections, etc. When you transform your document, sect1 tags will become items in the article's Table of Contents; sect2 items will become nested items in the Table of Contents; but sect3 and below will not appear.  
+
* 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].  
  
When I start a new document, I typically take the above template and flesh out the overall document structure by section. You can view an example framework [http://deadcancon.org/docbook/translating-framework.xml here]. Keep in mind that you need to add xml:id attributes to the sect element, and that they need to be unique; and that each section should have a title as well. Then, it's just a matter of filling in the para tags with relevant information.  
+
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.  
  
You can view a full example XML file [http://deadcancon.org/docbook/importexport.xml here]. I used this to make the current importexport document available from the OJS [http://pkp.sfu.ca/ojs_documentation documentation page].
+
SCREENSHOTS
  
== Writing a Book ==
+
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.
  
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:  
+
* 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 ===
Line 93: Line 112:
 
* 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
+
within your XML document, or use
+
<userinput>&lt;href&gt;</userinput> to link to one.</para>
+
* 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 <nowiki><p></nowiki> tags. (Let me know if you come up with a clever way to ignore '''<![CDATA[]]>''' itself.)
+
  
 
=== Linking ===
 
=== Linking ===
Line 111: Line 125:
  
 
* '''For code examples, listings, etc.:'''
 
* '''For code examples, listings, etc.:'''
for large, multiline code blocks. You can also use <informalexample> and omit the title information.
 
 
  <example>
 
  <example>
 
       <title>Example Code Snippet</title>
 
       <title>Example Code Snippet</title>
Line 117: Line 130:
 
  </example>
 
  </example>
  
 +
for large, multiline code blocks. You can also use <informalexample> and omit the title information.
  
 
* '''For Tips:'''  
 
* '''For Tips:'''  
Line 127: Line 141:
 
       <para>this is a warning</para>
 
       <para>this is a warning</para>
 
  </warning>
 
  </warning>
 +
 +
* '''For Notes'''
 +
<note>
 +
      <para>this is a note</para>
 +
</note>
  
 
* '''For non-numbered lists:'''
 
* '''For non-numbered lists:'''
Line 142: Line 161:
 
  </itemizedList>
 
  </itemizedList>
  
== Transforming DocBook into Other Formats ==
+
* '''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 ==
  
 
[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 153: 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 159: 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
+
 
+
xsltproc --output /usr/share/xml/docbook/stylesheet/nwalsh/xhtml/chunk.xsl example.xml
+
 
+
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/docbook/pkp.xsl here]. You'll have to add it to the xhtml stylesheet directory, as it references chunk.xsl, and then point xsltproc to it instead of chunk.xsl. This customization layer is still under development.
+
 
+
=== DocBook to PDF ===
+
 
+
To transform to PDF, you'll first have to transform to FO.
+
 
+
xsltproc --output example.fo --stringparam fop1.extensions 1 /usr/share/xml/docbook/stylesheet/nwalsh/fo/docbook.xsl example.xml
+
 
+
This command has xsltproc take example.xml and transform it to example.fo. Using FOP, you can then transform example.fo to example.pdf:
+
 
+
/path/to/fop -fo myfile.fo myfile.pdf
+
 
+
You should now have a set of HTML files, an FO file that you can pitch, and a PDF file.
+
 
+
I've created a PKP-specific customization layer that works around some of the more common PDF transformation issues, available [http://deadcancon.org/docbook/pkpfo.xsl here]. You'll have to add it to the fo stylesheet directory, as it references docbook.xsl, and then point xsltproc to it instead of docbook.xsl. This customization layer is still under development.
+
 
+
=== DocBook to Drupal ===
+
 
+
Although Drupal supports DocBook export of a book, there is currently no way to import a DocBook XML file into Drupal. This is an issue for us as we're using Drupal to manage the PKP site, and we'd understandably like to integrate our documentation as best we can. We'll be working on this in one way or another in the near future.
+
  
[[DocBook to Drupal]]
+
* '''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.
  
=== DocBook to OJS ===
+
* '''For the XSLT Processor:''' Use xsltproc -- this should already be on your machine and available from the terminal.
  
Just joking.
+
* '''For the XSL-FO Processor:''' Install [http://macports.org macports]. With macports, install fop:
  
''Or am I''?
+
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