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

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

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]

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

+

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:

−

== Writing a Book ==

+

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

−

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:

+

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.

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:

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 '''<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 <p> tags. (Let me know if you come up with a clever way to ignore '''<![CDATA[]]>''' itself.)

+

−

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

* 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 <tip><para>this is a tip</para></tip> for notes, suggestions, tips, etc.

+

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

−

== Transforming DocBook into Other Formats ==

−

[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:

+

=== Block Elements ===

−

* DocBook DTD (you can always point to an online DTD, of course)

+

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.

−

* 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 ===

+

* '''For code examples, listings, etc.:'''

+

<example>

+

<title>Example Code Snippet</title>

+

<programlisting>/multiple lines of code/</programlisting>

+

</example>

−

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.

+

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

−

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

+

* '''For Tips:'''

+

<tip>

+

<para>this is a tip</para>

+

</tip>

−

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.

+

* '''For Warnings'''

+

<warning>

+

<para>this is a warning</para>

+

</warning>

+

* '''For Notes'''

+

<note>

+

<para>this is a note</para>

+

</note>

−

=== DocBook to HTML ===

+

* '''For non-numbered lists:'''

−

If you have a valid DocBook XML file by the name of example.xml, you should now be able to run the command

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.

+

[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:

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.

−

This command has xsltproc take example.xml and transform it to example.fo. Using FOP, you can then transform example.fo to example.pdf:

+

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

−

/path/to/fop -fo myfile.fo myfile.pdf

+

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

+

=== Installing this stuff on Mac OS X ===

−

=== DocBook to Drupal ===

+

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

−

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.

+

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

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.

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.

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.

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:

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.

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:

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.

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: