Writing Documentation - Revision history

Jmacgreg at 22:11, 23 June 2010

2010-06-23T22:11:45Z

2010-03-19T21:50:19Z

‎Writing Docbook Documentation for the PKP

2008-06-10T20:19:27Z

‎Writing a Book

2008-06-10T20:19:09Z

‎Writing a Book

2008-06-10T19:36:34Z

2008-05-07T06:09:01Z

‎Writing a Book

2008-05-07T06:06:05Z

‎Writing a Book

2008-05-07T03:40:52Z

‎Transforming DocBook into Other Formats

2008-05-05T22:43:14Z

‎Transforming DocBook into Other Formats

2008-04-16T23:31:41Z

‎Other interesting stuff

← Older revision		Revision as of 21:50, 19 March 2010
Line 2:		Line 2:

	'''This document is currently extremely incomplete, and undergoing revisions as I switch from DocBook4.5 to 5.0.'''		'''This document is currently extremely incomplete, and undergoing revisions as I switch from DocBook4.5 to 5.0.'''
		+
		+	Not quite done with the upgrade yet. But will add information on translating/working with the userguide soon.

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

@@ Line 124: / Line 124: @@
   <chapter xml:id="chapter1">
        <title>Chapter 1</title>
-            <sect1 xml:id="chapter1section1>
+            <sect1 xml:id="chapter1section1">
             <title>Section 1</title>
             <para> ... </para>

@@ Line 124: / Line 124: @@
   <chapter xml:id="chapter1">
        <title>Chapter 1</title>
-            <sect1>
+            <sect1 xml:id="chapter1section1>
             <title>Section 1</title>
             <para> ... </para>

← Older revision		Revision as of 19:36, 10 June 2008
Line 271:		Line 271:

	''Or am I''?		''Or am I''?
		+
		+	== Notes on Converting the Technical Reference to DocBook ==
		+
		+	=== Assigning Unique ids ===
		+
		+	I'm currently adding xml:id's to each chapter and section. To stay unique, all section xml:ids inherit their chapter id first. So the chapter on plugins would be
		+
		+	<chapter xml:id="plugins">
		+	<title>Plugins</title>
		+	...
		+
		+	Whereas the plugins section in the Class Reference chapter would be
		+	<sect2 xml:id="classReferencePlugins">
		+	<title>Plugins</title>
		+	...
		+
		+	There may be a better way to do this.

@@ Line 84: / Line 84: @@
   <?xml version="1.0" encoding="UTF-8"?>
-  <'''book''' xmlns="<nowiki>http://docbook.org/ns/docbook</nowiki>"
+  <book xmlns="http://docbook.org/ns/docbook"
-    xmlns:xl="<nowiki>http://www.w3.org/1999/xlink</nowiki>" version="5.0">
+   xmlns:xl="http://www.w3.org/1999/xlink" version="5.0">
+   <info>
-A general outline of a DocBook book would look like so:
+       <title>Importing and Exporting Data with OJS</title>
+       <author>
-  <?xml version="1.0" encoding="UTF-8"?>
+           <orgname>The Public Knowledge Project</orgname>
- <book xmlns="<nowiki>http://docbook.org/ns/docbook</nowiki>"
+           <address>
-    xmlns:xl="<nowiki>http://www.w3.org/1999/xlink</nowiki>" version="5.0">
+               <city>Burnaby</city>
- <chapter xml:id="preface">
+               <street>8888 University Drive</street>
-      <title>Preface</title>
+               <postcode>V5A 1S6</postcode>
-      <para> ... </para>
+               <country>Canada</country>
- </chapter>
+           </address>
   <chapter xml:id="introduction">
        <title>Introduction</title>

@@ Line 77: / Line 77: @@
 == Writing a Book ==
 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:
@@ Line 84: / Line 86: @@
   <'''book''' xmlns="<nowiki>http://docbook.org/ns/docbook</nowiki>"
      xmlns:xl="<nowiki>http://www.w3.org/1999/xlink</nowiki>" version="5.0">
 == Common DocBook Elements You Should be Using ==

@@ Line 142: / Line 142: @@
   </itemizedList>
-== Transforming DocBook into Other Formats ==
+== Setting up the Tools you need to work with DocBook ==
 [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:
@@ Line 172: / Line 172: @@
 * '''Additional tips:''' Oxygen XML is available for OS X.
 === DocBook to HTML ===

← Older revision		Revision as of 22:43, 5 May 2008
Line 159:		Line 159:
	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 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.

		+	=== Installing this stuff on Mac OS X ===
		+
		+	Rough notes on moving my environment from Ubuntu to OS X:
		+
		+	* '''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.
		+
		+	* '''For the XSLT Processor:''' Use xsltproc -- this should already be on your machine and available from the terminal.
		+
		+	* '''For the XSL-FO Processor:''' Install [http://macports.org macports]. With macports, install fop:
		+
		+	sudo port install fop
		+
		+	* '''Additional tips:''' Oxygen XML is available for OS X.

	=== DocBook to HTML ===		=== DocBook to HTML ===

← Older revision		Revision as of 23:31, 16 April 2008
Line 25:		Line 25:

	* [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.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://ramikayyali.com/archives/2007/10/02/docbook_briefed a good intro into the whats and whys of DocBook]

	== Writing an Article ==		== Writing an Article ==