Difference between revisions of "Writing Documentation"

From PKP Wiki
Jump to: navigation, search
(Inline Elements)
Line 59: Line 59:
 
* 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 to a link that a user could click.
+
* Use <userinput>User Home</userinput> for referencing ... user ... input.
 +
<para>To import a file, you can use
 +
<nowiki><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></nowiki>
 
* 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 <![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 <ulink ="<nowiki>http://pkp.sfu.ca</nowiki>">link text</ulink> to hyperlink.

Revision as of 12:55, 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 ... 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. (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.