OpenOffice suitable for documentation
From Morfeo Wiki
Contents |
Open source solutions to generate documentation
OpenOffice
Openoffice is an office suite that contains some programs such as a word processor, a spreadsheet, a drawing tool, etc. OpenOffice is an office suite application available free of charge for a number of different computing operating systems. It supports the OpenDocument standard for data interchange as its default file formats, as well as Microsoft Office '97-2003 formats, among many others.
OpenOffice is a free software, available under the GNU Lesser General Public License (LGPL).
We have tested OpenOffice, and we have created a DocBook document with OpenOffice, but the file with extension xml with format DocBook generated it's not OK. To create a DocBook document it is easy, you just need to choose “DocBook (.xml)” when you save the project.
Figure 1 .- How to save a DocBook project with OpenOffice
Docbook
DockBook is a markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software but it can be used for any other sort of documentation.
One of the principal benefits of DocBook is that it enables its users to create document content in a presentation-neutral form that captures the logical structure of the content; that content can then be published in a variety of formats, including HTML on single file, HTML in various files, PDF and other formats without requiring users to make any changes to the source.
How it works
When a docbook file is going to be converted into other file formats, it follows the flow shown in Figure 2. First the docbook file is validated and afterwards, the required XSL is applied. After that, if the target is an HTML file the process is finished here, but if the target formatis PDF or DVI, it must be convert to a FO file. Finally the FO file is converted into the desired format.
Figure 2 .- DocBook processing convert
Setting up the system
LINUX: Before you can start use DocBook, you must install the following packages in your UNIX/LINUX system, typing:
# apt-get install docbook docbook-xml docbook-xsl docbook-utils
# apt-get install xmlto
# apt-get install xsltproc
With this packages, you can convert from .docbook file to a HTML, PDF, etc.
WINDOWS: Before you can start use DocBook, you must install the xsltproc in your Windows system. You can download it for Windows from this site: http://www.zlatkovic.com/libxml.en.html That page also describes how to install the files and use xsltproc on Windows. You need to download the packages for libxml, libxslt, zlib, and iconv. They arrive as .zip files which can be unpacked with any of the zip utilities on Windows. Once you have unpacked them, your environment's PATH variable must include the locations of the command files like xsltproc.exe and the set of library files named with the .dll suffix. Since they install into separate directories, you may need to add several PATH entries. So it is perhaps simplest to just copy all the files into a single location already in the PATH. For example, find and copy thefollowing files into C:\Windows\System32:
libxslt.dll, iconv.dll, xmllint.exe, libxml2.dll, zlib.dll, libexslt.dll, xsltproc.exe
DocBook commands
For conveting a docbook file to an navigable html file, you must type in your command line the following:
xsltproc --xinclude --output Template.html --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 style.xsl Template.xml
Then it is generated a file: “Template.html”. To convert to PDF you must open the file Template.html with OpenOffice (Only be necessary to introduce a page break by example in the first page) and push the button “Export to PDF”.
Ways to edit the docbook template
There are three ways to edit the template docbook. There is a tool for Microsoft Windows denominates XMLmind XML Editor, there is another tool for Linux denominates Conglomerate and another posibility is to edit the docbook template by hand.
XMLmind XML Editor (XXE)
XMLmind XML Editor featuring DTD and XML Schema aware editing commands and a word processor-like view configured using W3C's cascading style sheets (CSS).
Also XMLmind XML Editor allows editing large, complex, modular, XML documents. It makes it easy mastering XML vocabularies such as DocBook.
XMLmind XML Editor is available in two editions: Personal Edition and Professional Edition. Personal Edition is free of charge, is restricted to non-commercial use and has fewer features than Professional Edition. We can use Personal Edition because this version is free of charge.
Main features:
- XXE fully supports XML Schema and namespaces.
- XXE can be used with or without a grammar (DTD or XML Schema).
- XXE can be used to edit an invalid XML document (that doesn't conform to the grammar constraining it).
- DTD and XML Schema are themselves validated before being used to validate the document. By default, after first use, they are cached on disk in a fast loading binary format for quicker reuse.
- XXE can use XML catalogs to associate a local copy of a DTD to the public ID of this DTD.
- Comments and processing instructions can be edited and styled (using a CSS2 extension).
As you can see it in the screen shot below, XMLmind XML Editor is not a tool for programmers. Its users are generally technical writers.
Figure 3 .- Example created with XMLmind XML Editor tool
Now we can edit the document, and to add several objets.
Conglomerate
With Conglometare you are be able to create documents that are organised in a way that makes sense for you, rather than what your word processor wants. For instance, if you are writing a recipe book you'll want to think about "Ingredients" and "Preparation Instructions" rather than "Sections" and "Lists". You can then use your document to generate high-quality output in a variety of formats (such as HTML pages, PDF files, traditional word-processor files etc). You may also be able to do things that are almost impossible in a traditional word-processor, such as "Give me a list of all recipes that serve 8 people that are safe for those with an allergy to nuts".
As you can see it in the screen shot below, Conglomerate is not a tool for programmers. Its users are generally technical writers.
Figure 4 .- Conglomerate book interface
Edit the docbook template by hand
Other way of modify the docbook template is editing it by hand. It's easy do it. For example to add a new section you must add the following text:
<section> <title>Title of this section</title> <para>This is the content of this section</para> </section>
Also it's posible to have several input files. You only need to invoke another file from Template.xml file, ie suffice to add the following line:
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template2.xml" />
The resulting XML of generate the document:
<?xml version="1.0"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
]>
<article>
<title>IDEAL</title>
<subtitle>Interface Description Authoring Language (Working Draft — 1 December 2007)
</subtitle>
<para>
<variablelist>
<varlistentry>
<term>This version:</term>
<listitem>
<para>
<ulink url="http://mymobileweb.morfeo-project.org/specs/2007/WD-ideal-20071201/">
http://mymobileweb.morfeo-project.org/specs/2007/WD-ideal-20071201/</ulink></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<variablelist>
<varlistentry>
<term>Latest version:</term>
<listitem><para><ulink
url="http://mymobileweb.morfeo-project.org/specs/ideal">
http://mymobileweb.morfeo-project.org/specs/ideal</ulink></para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<variablelist>
<varlistentry>
<term>Last Update:</term>
<listitem><para>Date:</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<variablelist>
<varlistentry>
<term>Editors:</term>
<listitem><para>Jose Manuel Cantera Fonseca, Telefonica I+D</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<variablelist>
<varlistentry>
<term>Authors:</term>
<listitem><para>Jose Manuel Cantera Fonseca, Telefonica I+D</para></listitem>
</varlistentry>
</variablelist>
</para>
<para>
<variablelist>
<varlistentry>
<term>Contributors:</term>
<listitem><para>See <link
linkend="acknowledgments">acknowledgements</link></para></listitem>
</varlistentry>
</variablelist>
</para>
<section>
<title>Introduction</title>
<para>El texto del artículo va aquí</para>
<section>
<title>Purpose</title>
<para>This is a text</para>
<section>
<title>Sub-Purpose</title>
<para>This is another text</para>
</section>
</section>
</section>
<section>
<title>Second section</title>
<para>This is the second section</para>
</section>
<section id="acknowledgments">
<title>Acknowledgements</title>
<para>This is the second section</para>
</section>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="Template2.xml" />
<appendix>
<title>References</title>
<para>
<variablelist>
<varlistentry>
<term>DIWG</term>
<listitem>
<para>W3C Device Independence Working Group (See http://www.w3.org/2001/di/.)</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</appendix>
<appendix>
<title>Glosary</title>
<para>This is the glosary</para>
</appendix>
</article>
The result of this document in HTML is a web page, having used xsltproc to the converting process. Under, you can see the results:
$xsltproc --xinclude --output Template.html --stringparam section.autolabel 1 --stringparam section.label.includes.component.label 1 style.xsl Template.xml
Figure 5 .- HTML file obtained
Conclusions
After to study OpenOffice and another solutions for creating documentation, the conclusions obtained are the following:
- OpenOffice is not suitable to generate navigable documentation in HTML and PDF formats by now. We can expect in the upcoming version to have a better DocBook supports that overcomes the current shortcommings identified that prevent the generated DocBook files to be processed with the DocBook tools.
- DocBook is a suitable solution to create navigable documentation in HTML and PDF formats, but an editor to boost productivity should be used.
- There are serveral tools that support editing files that follow DocBook format. Two tools have been shown for this purpose in the previous sections:a tool for the Windows plattform and another one for the Linux plattform.
- Converting a DocBook file to HTML and PDF formats is easy by using DocBook tools for Linux, it is not that easy for the Windows platform.
