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.
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
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>email@example.com</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.
You can find a list of all elements for DocBook 5.0 here.
- 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.
- 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.