Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "OAW Documentation Engineering"
(New page: == Writing oAW Documentation == Originally, oAW documentation has been written using OpenOffice and exported to PDF for end user convenience. Starting in March 2007, we're converting all d...) |
|||
| Line 1: | Line 1: | ||
| − | |||
Originally, oAW documentation has been written using OpenOffice and exported to PDF for end user convenience. Starting in March 2007, we're converting all documents to DocBook which gives us the tremendous benefit of creating both PDF documentation for printing purposes and Eclipse online help from one source (single-source publishing). | Originally, oAW documentation has been written using OpenOffice and exported to PDF for end user convenience. Starting in March 2007, we're converting all documents to DocBook which gives us the tremendous benefit of creating both PDF documentation for printing purposes and Eclipse online help from one source (single-source publishing). | ||
| − | + | == Prerequisites == | |
Here's what you need to create DocBook documentation: | Here's what you need to create DocBook documentation: | ||
* Your favourite XML editor. We recommend using the free [http://www.xmlmind.com/xmleditor/ XMLMind Personal Edition]. In order to keep the DocBook sources consistent, you should go to ''"Options / Preferences"'' and use the following settings in XMLMind: [[Image:XMLMind_Preferences.jpg]] | * Your favourite XML editor. We recommend using the free [http://www.xmlmind.com/xmleditor/ XMLMind Personal Edition]. In order to keep the DocBook sources consistent, you should go to ''"Options / Preferences"'' and use the following settings in XMLMind: [[Image:XMLMind_Preferences.jpg]] | ||
| Line 11: | Line 10: | ||
** and an ANT build script to compile the documentation | ** and an ANT build script to compile the documentation | ||
| − | + | == Learning DocBook == | |
If you're new to DocBook, fear not. It's plain XML and you will learn the most important tags (about 15 or so) in no time. We suggest to take a look at the existing DocBook files in order to get an idea. Here are the most important tags: | If you're new to DocBook, fear not. It's plain XML and you will learn the most important tags (about 15 or so) in no time. We suggest to take a look at the existing DocBook files in order to get an idea. Here are the most important tags: | ||
| Line 23: | Line 22: | ||
If you are in need of further information, please have a look at the manuals in '''documentation/lib/docbook/manuals''' | If you are in need of further information, please have a look at the manuals in '''documentation/lib/docbook/manuals''' | ||
| − | + | == Writing == | |
# After you have checked out the ''documentation'' project, | # After you have checked out the ''documentation'' project, | ||
# navigate to the documentation/docbook-src/oaw4.1 folder | # navigate to the documentation/docbook-src/oaw4.1 folder | ||
| Line 31: | Line 30: | ||
'''Important:''' Since storing the DocBook sources in ''UTF-8'' encoding caused a lot of trouble when creating patches against the repository, we decided to store the documentation sources in ''ISO-8859-1'' encoding. So, if you change something, please make sure that you save the files with ''ISO-8859-1'' encoding. | '''Important:''' Since storing the DocBook sources in ''UTF-8'' encoding caused a lot of trouble when creating patches against the repository, we decided to store the documentation sources in ''ISO-8859-1'' encoding. So, if you change something, please make sure that you save the files with ''ISO-8859-1'' encoding. | ||
| − | + | === Adding a new chapter to the documentation === | |
If you want to add a new chapter, | If you want to add a new chapter, | ||
# create a new XML document similar to ''gettingstarted-emf_tutorial.xml'' | # create a new XML document similar to ''gettingstarted-emf_tutorial.xml'' | ||
# and add an Entity import to the ''index.xml'' file (<!ENTITY gettingstarted-emf_tutorial SYSTEM "gettingstarted-emf_tutorial.xml">) | # and add an Entity import to the ''index.xml'' file (<!ENTITY gettingstarted-emf_tutorial SYSTEM "gettingstarted-emf_tutorial.xml">) | ||
| − | + | === Compiling === | |
In order to convert your DocBook XML into a PDF and Eclipse Online Help: | In order to convert your DocBook XML into a PDF and Eclipse Online Help: | ||
# select ''build-docbook.xml'' | # select ''build-docbook.xml'' | ||
# run it as an ANT file | # run it as an ANT file | ||
The PDF will be written to ''documentation/pdf/oaw4.1'', the Eclipse Online Help will be created in a separate project (''org.openarchitectureware.help.userguide'', please make sure you've checked out this project from CVS before generating DocBook). | The PDF will be written to ''documentation/pdf/oaw4.1'', the Eclipse Online Help will be created in a separate project (''org.openarchitectureware.help.userguide'', please make sure you've checked out this project from CVS before generating DocBook). | ||
Revision as of 05:37, 8 February 2008
Originally, oAW documentation has been written using OpenOffice and exported to PDF for end user convenience. Starting in March 2007, we're converting all documents to DocBook which gives us the tremendous benefit of creating both PDF documentation for printing purposes and Eclipse online help from one source (single-source publishing).
Contents
Prerequisites
Here's what you need to create DocBook documentation:
- Your favourite XML editor. We recommend using the free XMLMind Personal Edition. In order to keep the DocBook sources consistent, you should go to "Options / Preferences" and use the following settings in XMLMind:
- The documentation subproject of oAW. Get it from our developer CVS.
- This projects contains all source files,
- DocBook XSL transformation and stylesheets,
- DocBook DocBook DTD
- and an ANT build script to compile the documentation
Learning DocBook
If you're new to DocBook, fear not. It's plain XML and you will learn the most important tags (about 15 or so) in no time. We suggest to take a look at the existing DocBook files in order to get an idea. Here are the most important tags:
- <chapter>: starts a new chapter
- <section>: starts a new section. Sections can be nested infinitely (although we recomment not nesting too deeply)
- <para>: a paragraph
- <itemizedlist>: an itemized list
- <orderedlist>: an ordered list
- lists contain <listitem>s
If you are in need of further information, please have a look at the manuals in documentation/lib/docbook/manuals
Writing
- After you have checked out the documentation project,
- navigate to the documentation/docbook-src/oaw4.1 folder
The index.xml file is the documentation root and contains includes for all subdocuments.
Important: Since storing the DocBook sources in UTF-8 encoding caused a lot of trouble when creating patches against the repository, we decided to store the documentation sources in ISO-8859-1 encoding. So, if you change something, please make sure that you save the files with ISO-8859-1 encoding.
Adding a new chapter to the documentation
If you want to add a new chapter,
- create a new XML document similar to gettingstarted-emf_tutorial.xml
- and add an Entity import to the index.xml file (<!ENTITY gettingstarted-emf_tutorial SYSTEM "gettingstarted-emf_tutorial.xml">)
Compiling
In order to convert your DocBook XML into a PDF and Eclipse Online Help:
- select build-docbook.xml
- run it as an ANT file
The PDF will be written to documentation/pdf/oaw4.1, the Eclipse Online Help will be created in a separate project (org.openarchitectureware.help.userguide, please make sure you've checked out this project from CVS before generating DocBook).