Difference between revisions of "Writing Documentation"

From PKP Wiki
Jump to: navigation, search
Line 1: Line 1:
* Integrate Ray Beswick's updates into 2.1.1 Help files
+
= Writing Docbook Documentation for the PKP =
* Update 2.1.1 Help files to 2.2
+
 
* Update OJS in an Hour 2.1.1 to 2.2
+
'''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 ===
 +
 
 +
* [http://docbook.org/tdg5/ DocBook v5.0: The Definitive 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
 +
 
 +
=== XML Editors ===
 +
 
 +
* [http://www.xmlmind.com/xmleditor/ XMLmind]
 +
* [http://altova.com XMLSpy]
 +
* [http://oxygenxml.com oXygen]
 +
* [http://www.adobe.com/products/framemaker/ Framemaker]
 +
 
 +
== 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="<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"><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 [http://www.docbook.org/tdg5/en/html/pt02.html 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 to a link that a user could click.
 +
* Use <![CDATA[[<nowiki><p>all this text up in here</p></nowiki>]]> for tags that should be ignored. (Let me know if you come up with a clever way to ignore <![CDATA[]]> itself).
 +
* Use <ulink ="<nowiki>http://pkp.sfu.ca</nowiki>">link text</ulink> to hyperlink.
 +
* Use <link linkend="sectionId">link text</link> for linking within the document itself.
 +
 
 +
=== 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.

Revision as of 12:51, 30 March 2008

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

XML Editors

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 to a link that a user could click.
  • Use <![CDATA[[<p>all this text up in here</p>]]> for tags that should be ignored. (Let me know if you come up with a clever way to ignore <![CDATA[]]> itself).
  • Use <ulink ="http://pkp.sfu.ca">link text</ulink> to hyperlink.
  • Use <link linkend="sectionId">link text</link> for linking within the document itself.

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.