Writing Documentation

Writing Docbook Documentation for the PKP

This document is currently extremely incomplete, and undergoing revisions as I switch from DocBook4.5 to 5.0.

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.

Resources

Writings, books on DocBook

• DocBook v5.0: The Definitive Guide
• DocBook XSL: The Complete Guide
• Dave Pawson's DocBook site, may be slightly out-of-date

XML Editors

• XMLmind
• XMLSpy
• oXygen
• Framemaker

Validators

• w3 online validator
• xmllint (available on most *nix systems)

Writing an Article

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.

At bare minimum, your source file will look like so:

<?xml version="1.0" encoding="UTF-8"?>
<article xmlns="http://docbook.org/ns/docbook" 
   xmlns:xl="http://www.w3.org/1999/xlink" 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

Info will come as I convert the OxS in an Hour docs as well as the Technical Reference.

Common Elements

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 <userinput>User Home</userinput> for referencing ... user ... input.

<para>To import a file, you can use
<userinput><embed></userinput> to place a file directly
within your XML document, or use
<userinput><href></userinput> to link to one.</para>

• Use <![CDATA[[<p>all this text up in here</p>]]> for tags that should be ignored. This example would tell the parser to ignore those

  tags. (Let me know if you come up with a clever way to ignore <![CDATA[]]> itself.)

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

• Use <programlisting>/multiple lines of code/</programlisting> for large, multiline code blocks.
• Use <tip><para>this is a tip</para></tip> for notes, suggestions, tips, etc.