<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Authoring with Eclipse</title><link href="images/default_style.htm" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"><meta name="description" content="The topic of technical publishing is relatively new to | |
the world of Eclipse. One can make the argument that | |
technical publishing is just another collaborative | |
development process involving several people with | |
different backgrounds and skills. This article will show | |
that the Eclipse platform is a viable platform for technical | |
publishing by discussing how to write documents such as | |
an article or a book within Eclipse. In fact, this | |
article was written using Eclipse."></head><body alink="#0000ff" bgcolor="white" link="#0000ff" text="black" vlink="#840084"><div align="right"> | |
| |
<span class="copy"> | |
Copyright ©2005 International Business Machines Corporation. All rights reserved.</span></div><div class="article" lang="en"><div class="titlepage"><div><h1 align="center">Authoring with Eclipse</h1><blockquote><b>Summary</b><br> | |
The topic of technical publishing is relatively new to | |
the world of Eclipse. One can make the argument that | |
technical publishing is just another collaborative | |
development process involving several people with | |
different backgrounds and skills. This article will show | |
that the Eclipse platform is a viable platform for technical | |
publishing by discussing how to write documents such as | |
an article or a book within Eclipse. In fact, this | |
article was written using Eclipse. | |
<br><p><b>By | |
Chris Aniszczyk, IBM Corporation<br>Lawrence Mandel, IBM Corporation<br></b><span class="date">December 14, 2005<br></span></p></blockquote></div><div></div><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="N10046"></a>Environment</h2></div></div><div></div></div><div class="note" style="margin-left: 0.38in; margin-right: 0.38in;"><table summary="Note" border="0"><tbody><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p> | |
The examples in this article were built and tested with: | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
<a href="http://www.eclipse.org/downloads/download.php?file=/eclipse/downloads/drops/R-3.1-200506271435/eclipse-SDK-3.1-win32.zip" target="_new"> | |
Eclipse 3.1 | |
</a> | |
</li><li> | |
<a href="http://archive.eclipse.org/webtools/downloads/drops/R1.0/R-1.0-200512210855/" target="_new"> | |
Eclipse Web Tools Platform (WTP) 1.0 | |
</a> | |
</li><li> | |
<a href="http://eclipsexslt.sourceforge.net/" target="_new"> | |
Orangevolt XSLT 1.0.4 | |
</a> | |
</li></ul></div> | |
<p></p></td></tr></tbody></table></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="N10063"></a>Introduction</h2></div></div><div></div></div><p> | |
The authors of this document view technical documentation as | |
another development process that shares the same | |
characteristics as a software process. In technical | |
publishing, you have writers, editors, typesetters, QA | |
reviewers, and so on. Technical publishing is a collaborative | |
process that currently lacks the tools to facilitate | |
collaboration. The goal of this article is two-fold: give an | |
introduction to technical documentation and show, through an | |
example, how Eclipse can help make technical documentation a | |
collaborative process. | |
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="N10068"></a>Technical Documentation</h2></div></div><div></div></div><p> | |
In the open source world, technical documentation is | |
primarily accomplished using two popular formats: DocBook | |
and the Darwin Information Typing Architecture (DITA). These two | |
formats share two important characteristics: they are both | |
systems for creating structured documents using XML and both focus on content that is written | |
in plain text (or in an editor such as OpenOffice). In this | |
article we focus on DocBook because of our familiarity with the | |
format. However, we will also provide complementary DITA | |
information where appropriate. | |
</p><div class="tip" style="margin-left: 0.38in; margin-right: 0.38in;"><table summary="Tip" border="0"><tbody><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p> | |
If you're unfamiliar with DocBook, there's an | |
<a href="http://www-128.ibm.com/developerworks/library/l-docbk.html" target="_new"> | |
article | |
</a> | |
on the <span class="trademark">IBM</span>® <span class="trademark">developerWorks</span>® site by Joe Brockmeier that can serve as a | |
gentle introduction. There is also an | |
<a href="http://www-128.ibm.com/developerworks/xml/library/x-dita1/index.html" target="_new"> | |
introduction | |
</a> | |
to DITA on developerWorks. | |
</p></td></tr></tbody></table></div><p> | |
The technical documentation process can be broken down into | |
three broad stages: creation, review, and publication. | |
</p><p> | |
Creation simply refers to populating a document with | |
content that adheres to whatever format you choose to write | |
against. This document is usually edited using an XML editor | |
of choice, although it can be edited with any text editor as | |
well. In this article we will use WTP's XML editor to edit | |
documents. | |
</p><p> | |
Once an initial version of the content has been written, it | |
is typically handed off to one or more trusted colleagues | |
for review. The role of these reviewers is to ensure | |
technical accuracy and improve the quality of the writing. | |
The comments and suggestions gathered from the review stage | |
are then used by the document's authors to create a final | |
revision of the document. | |
</p><p> | |
The final revision of a document involves making it is ready for | |
publication. When authoring in an XML format, you must eventually transform the document | |
must be transformed from XML to a human-readable format | |
(that is, one that has both style and formatting applied) | |
such as HTML or PDF. Once in a human-readable format, the | |
document is ready to be published by a selected publisher. | |
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10088"></a>Advantages of an XML format</h3></div></div><div></div></div><p> | |
Before diving into an actual example of the technical | |
documentation process using Eclipse, let's take a look | |
at some of the benefits of authoring in an XML format. | |
</p><p> | |
There are four advantages to authoring in XML that | |
really show the benefit of this format: modularity, | |
version control, consistent formatting, and publishing | |
to multiple formats. | |
</p><p> | |
<span class="emphasis"><em>Modularity</em></span> | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
XML formats such as DocBook and DITA are | |
modular. This allows you to break up your | |
documents into multiple sections, which can | |
be automatically combined into one document | |
using transformation during the publication | |
stage. Modularizing your documents can be | |
very beneficial when working on large | |
documents, such as a book, or when working | |
with multiple authors. As an example, the | |
book <span class="emphasis"><em>Java Web | |
Application Development with Eclipse</em></span> (set to | |
be published in time for EclipseCon 2006), | |
was written in DocBook. The book | |
was structured with one table of | |
contents XML file and a separate file for | |
each chapter. Of course, it's up to you to | |
determine the structure that works best for | |
your project. The key is that by using an | |
XML format, you have the freedom to configure | |
your document's structure. | |
</li></ul></div> | |
<span class="emphasis"><em>Version Control</em></span> | |
<div class="itemizedlist"><ul type="disc"><li> | |
Version control is very useful and has | |
become a staple in most development | |
processes. Why is it, then, that a system that | |
allows you to maintain the complete history | |
of your files, allowing you to revert to a | |
previous version at any time, is not part of | |
the authoring process? One reason is that many | |
documents are authored using word-processing | |
tools that mix formatting information and | |
content, such as <span class="trademark">Microsoft</span>® Word or Corel | |
WordPerfect. This mix results in files | |
containing many changes between revisions, | |
reducing the usefulness of version control | |
because it is difficult to view the relevant | |
changes between versions of the document. | |
XML formats do not suffer from this problem | |
as they are content-specific. Authoring in | |
an XML format allows you to use a version | |
control system and reap the benefits that | |
go with it. | |
</li></ul></div> | |
<span class="emphasis"><em>Consistent Formatting</em></span> | |
<div class="itemizedlist"><ul type="disc"><li> | |
Ensuring that your document is consistently | |
formatted is a time-consuming aspect of the | |
authoring process. This task can be further | |
aggravated when the authoring format | |
mixes content and formatting in one document | |
or when working with multiple authors or | |
files. One of the typical final steps in the | |
authoring process is ensuring that your | |
document uses consistent formatting. Using | |
an XML format solves the consistent | |
formatting problem by separating your | |
document's content from its formatting. In | |
the XML case, formatting can be applied | |
uniformly to your entire document using a | |
style sheet. An XML format saves you time and | |
guarantees consistent formatting. | |
</li></ul></div> | |
<span class="emphasis"><em>Publishing to Multiple Formats</em></span> | |
<div class="itemizedlist"><ul type="disc"><li> | |
By separating your document's | |
formatting from its content, you gain | |
an enormous freedom. Documents authored | |
in the XML format are not bound by one set | |
of formatting rules. This means that you can | |
author an article, such as this one, and | |
create an HTML version, a PDF version, and | |
even an Eclipse help system version simply | |
by transforming your document with different | |
style sheets. In fact, DocBook includes all | |
three of these stylesheets allowing you to | |
easily publish to any of the formats listed | |
above. | |
</li></ul></div> | |
<p></p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="N100B8"></a>Examples</h2></div></div><div></div></div><p> | |
To show the authoring tool chain in Eclipse, this article | |
will use a sample book document from the DocBook XSL project. The | |
XML version of the document can be seen | |
<a href="https://bugs.eclipse.org/bugs/files/book.xml" target="_new">here</a>. This DocBook source for this | |
article is also available and can be seen <a href="https://bugs.eclipse.org/bugs/AuthoringWithEclipse.xml" target="_new">here</a>. | |
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N100C5"></a>Tool Chain</h3></div></div><div></div></div><p> | |
A tool chain is a set of tools that are used to create a | |
more complex tool or product. The tools may be used in a | |
chain, so the output of each tool becomes the input of | |
the next | |
[<a href="#toolchain">3</a>] | |
. This concept should be very familiar to those who work | |
on the <span class="trademark">UNIX</span>®, | |
<span class="trademark">Linux</span>®, and | |
<span class="trademark">AIX</span>® platforms, | |
for example, where the output of one command | |
line tool is typically piped to the next tool, allowing | |
complex operations to be performed using several simple | |
tools. | |
</p><p> | |
The beginning of our technical publishing tool chain is | |
the WTP XML editor, which we use to edit our content. | |
After we have finished editing the content, we will feed the | |
output of what we edited into OrangeVolt, an XSLT | |
transformation engine, which will use style sheets to | |
publish the content into a human-readable format. | |
</p><p> | |
The limitation we put on these examples is that our | |
tool chain, including all three stages, creation, review, | |
and publication, will be built with tools available within | |
Eclipse. From our experience, Eclipse has enormous | |
potential as an integrated documentation | |
development environment. In the following sections, we'll | |
discuss how you can make this a reality with current | |
Eclipse tooling and where the tooling falls short. | |
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N100DD"></a>Creation and Review</h4></div></div><div></div></div><p> | |
Although creation and review are two separate parts | |
of the technical documentation process, the same | |
tools are required and therefore will be discussed | |
together. | |
</p><p> | |
As you may already know, the Eclipse project | |
is composed of serveral top-level projects including | |
Eclipse itself (known as the Eclipse base) and the | |
WTP project. WTP adds many tools to the Eclipse base | |
including an XML editor with graphical and source | |
representations of the content. Although the | |
graphical editor is useful for viewing your document, | |
we've found that the source editor, shown in | |
<a href="#xml-source-editor" title="Figure 1. The XML Source Editor">Figure 1, “The XML Source Editor”</a> | |
, is more useful when authoring in XML. | |
</p><div class="figure"><a name="xml-source-editor"></a><p class="title"><b>Figure 1. The XML Source Editor</b></p><div class="mediaobject"><table summary="manufactured viewport for HTML img" border="0" cellpadding="0" cellspacing="0" width="807"><tbody><tr style="height: 598px;"><td><img src="images/xmlsourceeditor.gif" alt="The XML Source Editor" width="807"></td></tr></tbody></table></div></div><p> | |
The XML editor provides many of the Eclipse | |
franchise functions that <span class="trademark">Java</span>™ developers have become | |
accustomed to with the Java editor. | |
</p><p> | |
<span class="emphasis"><em>Content Assistance</em></span> | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
Gives you a list of valid XML elements | |
constrained by an associated grammar. | |
</li></ul></div><p> | |
<span class="emphasis"><em>Syntax Highlighting</em></span> | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
Gives you improved code readability by | |
making certain errors instantly visible. | |
</li></ul></div><p> | |
<span class="emphasis"><em>Validation</em></span> | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
Ensures validity of an XML document based | |
on an associated grammar. | |
</li></ul></div><p> | |
<span class="emphasis"><em>Outline View</em></span> | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
Assists you in editing and viewing the | |
content of your document. | |
</li></ul></div><p> | |
<span class="emphasis"><em>XML Catalog</em></span> | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
Allows you to register Document Type | |
Definitions (DTD) and XML Schema grammars | |
associated with your document with your | |
workspace so you can work with the benefits | |
of validation while disconnected from the | |
Internet. | |
</li></ul></div><p> | |
Aside from the benefits of the XML editor, working | |
in Eclipse provides other benefits. Eclipse includes | |
integrated version control for CVS. (There is also a | |
freely available plug-in for subversion | |
[<a href="#subversion">6</a>], another version control | |
system.) Integrated | |
version control allows you to check your changes | |
into, and view others' changes in, your version | |
control system from within Eclipse. These tools are | |
also useful for your reviewers, who, if you give them | |
permission, can add comments and suggestions to your | |
document and check their changes in. Giving your reviewers | |
permission to make these changes allows you to avoid | |
the need to use e-mail or some other communication | |
mechanism. | |
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N1012B"></a>Publication</h4></div></div><div></div></div><p> | |
The DocBook XSL | |
[<a href="#docbookxsl">1</a>] | |
and DITA | |
[<a href="#dita">2</a>] | |
projects offer numerous transformations, including | |
HTML and PDF formats. The most common | |
transformation technique is to use an Ant file with | |
the appropriate tasks for the various | |
transformations. In this article we use the | |
Orangevolt XSLT tool to simplify this task. | |
Orangevolt XSLT integrates into the familiar Eclipse | |
launcher framework. This integration allows you to | |
select the style sheet and pass in necessary | |
parameters for the transformation. | |
</p><div class="tip" style="margin-left: 0.38in; margin-right: 0.38in;"><table summary="Tip" border="0"><tbody><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p> | |
The DITA Open Toolkit (DITA-OT) includes a DITA to DocBook | |
<a href="http://dita-ot.sourceforge.net/doc/DITA-antscript.html" target="_new"> | |
transformation | |
</a>. | |
</p></td></tr></tbody></table></div><p> | |
Along with the description in this article, we have | |
provided Flash movies that demonstrate how to | |
perform each transformation. Transformations for | |
both DocBook and DITA will be provided where | |
appropriate. | |
</p><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N1013F"></a>HTML</h5></div></div><div></div></div><p> | |
Of all the available transformations, | |
transforming your document into HTML is the | |
easiest to use. All that you need to do is | |
create a proper transformation launch | |
configuration and run the transformation. | |
Specifically, you need to specify the correct | |
style sheet: | |
</p><div class="itemizedlist"><ul type="disc"><li><p>DocBook</p><div class="itemizedlist"><ul type="circle"><li>html/docbook.xsl</li></ul></div></li><li><p>DITA</p><div class="itemizedlist"><ul type="circle"><li>xsl/dita2html.xsl</li></ul></div></li></ul></div> | |
<a href="#html-transformation" title="Figure 2. Sample HTML Transformation Configuration for book.xml">Figure 2, “Sample HTML Transformation Configuration for book.xml”</a> | |
shows a sample transformation configuration that | |
will transform our DocBook sample | |
<a href="https://bugs.eclipse.org/bugs/files/book.xml" target="_new">document</a> | |
into HTML. | |
<p></p><div class="figure"><a name="html-transformation"></a><p class="title"><b>Figure 2. Sample HTML Transformation Configuration for book.xml</b></p><div class="mediaobject"><table summary="manufactured viewport for HTML img" border="0" cellpadding="0" cellspacing="0" width="692"><tbody><tr style="height: 517px;"><td><img src="images/html.png" alt="Sample HTML Transformation Configuration for book.xml" width="692"></td></tr></tbody></table></div></div><div class="tip" style="margin-left: 0.38in; margin-right: 0.38in;"><table summary="Tip" border="0"><tbody><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p> | |
You can augment the transformation by | |
passing parameters to the style sheet. | |
There's a full listing of DocBook XSL | |
parameters that can be used to configure the | |
transformation located | |
<a href="http://docbook.sourceforge.net/release/xsl/current/doc/html/" target="_new"> | |
here | |
</a>. | |
</p></td></tr></tbody></table></div><p> | |
A Flash movie that | |
shows how to run the transformation can be seen | |
<a href="https://bugs.eclipse.org/bugs/files/DocBook-HTML.htm" target="_new">here</a> | |
. | |
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N10174"></a>PDF</h5></div></div><div></div></div><p> | |
Transforming a DocBook XML file to PDF format is | |
more involved than the transformation to HTML | |
but it is still possible using a style sheet. The | |
difference lies in a task that must be performed | |
before the actual transformation. So, the | |
transformation from XML to PDF is a two-step | |
process. | |
</p><p> | |
Step one is to generate an XSL formatting objects | |
(XSL-FO) document. This document will then be | |
transformed into a PDF. In order to generate an | |
XSL-FO document, you need to use the following | |
stylesheet: | |
<span class="emphasis"><em>fo/docbook.xsl</em></span>. | |
<a href="#xslfo-transformation" title="Figure 3. Sample XSL-FO Transformation Configuration for book.xml">Figure 3, “Sample XSL-FO Transformation Configuration for book.xml”</a> | |
shows a sample transformation configuration used | |
to generate an XSL-FO document from book.xml. | |
</p><div class="figure"><a name="xslfo-transformation"></a><p class="title"><b>Figure 3. Sample XSL-FO Transformation Configuration for book.xml</b></p><div class="mediaobject"><table summary="manufactured viewport for HTML img" border="0" cellpadding="0" cellspacing="0" width="692"><tbody><tr style="height: 517px;"><td><img src="images/xsl-fo.png" alt="Sample XSL-FO Transformation Configuration for book.xml" width="692"></td></tr></tbody></table></div></div><p> | |
Step two is to use a Formatting Objects | |
Processor (FOP) to transform your XSL-FO | |
document into a PDF. One of the more popular | |
open source FOPs is the | |
<a href="http://xmlgraphics.apache.org/fop/" target="_new"> | |
Apache FOP | |
</a> | |
. We'll use a third-party | |
<a href="http://www.ahmadsoft.org/fopbridge.html" target="_new"> | |
plug-in from Ahmadsoft | |
</a> | |
that integrates Apache FOP into Eclipse. After | |
installing this plug-in, all that you need to do | |
to render the XSL-FO document is run the FOP | |
transformation. | |
<a href="#pdf-transformation" title="Figure 4. Sample FOP Transformation">Figure 4, “Sample FOP Transformation”</a> | |
shows an example of running the FOP | |
transformation. | |
</p><div class="figure"><a name="pdf-transformation"></a><p class="title"><b>Figure 4. Sample FOP Transformation</b></p><div class="mediaobject"><table summary="manufactured viewport for HTML img" border="0" cellpadding="0" cellspacing="0" width="430"><tbody><tr style="height: 447px;"><td><img src="images/fop.png" alt="Sample FOP Transformation" width="430"></td></tr></tbody></table></div></div><div class="note" style="margin-left: 0.38in; margin-right: 0.38in;"><table summary="Note" border="0"><tbody><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p> | |
The example includes a sample Ant | |
<a href="https://bugs.eclipse.org/bugs/files/pdf/build.xml" target="_new"> | |
file | |
</a> | |
that performs the same transformation as | |
running the FOP transformation using the | |
<a href="http://www.ahmadsoft.org/fopbridge.html" target="_new"> | |
plug-in from Ahmadsoft | |
</a>. An Ant script is a popular method of | |
performing the publishing stage, and this | |
example should give you a good starting | |
point if you'd prefer to go this route. The | |
DITA project already includes an Ant script | |
(found in ant/sample_pdf.xml in DITA-OT) to perform | |
this exact task on DITA source files. | |
</p></td></tr></tbody></table></div><p> | |
As before, a Flash movie that shows the | |
transformation is available | |
<a href="https://bugs.eclipse.org/bugs/files/DocBook-PDF.htm" target="_new">here</a> | |
. | |
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h5 class="title"><a name="N101B7"></a>Eclipse Infocenter</h5></div></div><div></div></div><p> | |
In our opinion, one of the coolest features of | |
the DocBook and DITA projects is the generation | |
of an Eclipse help plug-in (information center) from | |
your source XML file. In order to perform this | |
transformation in DocBook, you need to specify a | |
few parameters and use the following style sheet: | |
<span class="emphasis"><em>eclipse/eclipse.xsl</em></span>. | |
<a href="#eclipse-transformation" title="Figure 5. Sample Eclipse Infocenter Transformation Configuration">Figure 5, “Sample Eclipse Infocenter Transformation Configuration”</a> | |
shows a sample transformation configuration | |
along with the correct parameters. To perform | |
this transformation using a DITA source file, use | |
the | |
<span class="emphasis"><em>ant/sample_eclipsehelp.xml</em></span> | |
Ant file. | |
</p><div class="figure"><a name="eclipse-transformation"></a><p class="title"><b>Figure 5. Sample Eclipse Infocenter Transformation Configuration</b></p><div class="mediaobject"><table summary="manufactured viewport for HTML img" border="0" cellpadding="0" cellspacing="0" width="803"><tbody><tr style="height: 388px;"><td><img src="images/eclipse.png" alt="Sample Eclipse Infocenter Transformation Configuration" height="388"></td></tr></tbody></table></div></div><div class="tip" style="margin-left: 0.38in; margin-right: 0.38in;"><table summary="Tip" border="0"><tbody><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p> | |
The complete list of DocBook XSL parameters | |
for the Eclipse Infocenter transformation | |
is located | |
<a href="http://docbook.sourceforge.net/release/xsl/current/doc/html/rn22.html" target="_new"> | |
here | |
</a> | |
. | |
</p></td></tr></tbody></table></div><p> | |
The Flash movie that shows the Eclipse | |
Infocenter DocBook transformation can be found | |
<a href="https://bugs.eclipse.org/bugs/files/DocBook-InfoCenter.htm" target="_new"> | |
here | |
</a> | |
. | |
</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N101DE"></a>Current Limitations</h4></div></div><div></div></div><p> | |
Although we have shown that Eclipse's current XML | |
authoring support is pretty good, there are a two | |
noteworthy limitations. | |
</p><p> | |
The first is grammar and spell-checking. While these | |
tools are commonplace in word-processing software, | |
they do not yet exist for WTP's XML editor. | |
</p><p> | |
The second is a WYSIWYG editor for XML documentation | |
formats such as DITA and DocBook (or a preview | |
window). The lack of a sophisticated editor or a way | |
to preview what you've written requires that you | |
stop authoring and transform your document in order | |
to view the results of your changes. | |
</p><p> | |
While neither of these limitations has been a show-stopper | |
in our authoring process, our hope is that as | |
Eclipse is recognized as an integrated documentation | |
development environment, these limitations will be | |
addressed. | |
</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="N101E9"></a>Summary</h2></div></div><div></div></div><p> | |
In this article, we introduced the technical documentation | |
process and showed that technical documentation development | |
is possible in Eclipse. We worked through examples showing | |
how to use Eclipse to aid the different phases of the | |
technical documentation process. Although there is still a | |
lot of room for improvement in this area we hope we've | |
convinced you that technical documentation in Eclipse is | |
both possible and already viable. It's now up to you in | |
the technical documentation community to speak up, make it | |
clear that Eclipse is being used for the authoring process, | |
and push to get the current limitations addressed. | |
</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="N101EE"></a>Acknowledgements</h2></div></div><div></div></div><p> | |
We'd like to thank: | |
</p><div class="itemizedlist"><ul type="disc"><li> | |
Sushma Patel and Anne James for correcting our horrible | |
grammar. | |
</li></ul></div> | |
<div class="itemizedlist"><ul type="disc"><li> | |
Don Day and Michael Priestly for their DITA | |
expertise. | |
</li></ul></div> | |
<p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both;"><a name="N101FD"></a>About the Authors</h2></div></div><div></div></div><p> | |
Chris Aniszczyk is a software developer at the IBM Austin | |
Labs and works in Tivoli Security. He's a developer on the | |
<a href="http://www.gentoo.org/" target="_new">Gentoo Linux</a> | |
distribution and also a committer on the | |
<a href="http://www.eclipse.org/emft" target="_new"> | |
Eclipse Modeling Framework Technology (EMFT) | |
</a> | |
project. | |
</p><p> | |
Lawrence Mandel, a software developer at the IBM Toronto | |
Laboratory, is the documentation lead and a | |
committer for the Eclipse | |
<a href="http://www.eclipse.org/webtools" target="_new"> | |
Web Tools Platform (WTP) | |
</a> | |
project. He is also authoring a book with Arthur Ryman and | |
Naci Dai about Java Web application development with | |
Eclipse. | |
</p></div><div class="bibliography"><div class="titlepage"><div><div><h2 class="title"><a name="N10210"></a>Resources</h2></div></div><div></div></div><div class="biblioentry"><a name="docbookxsl"></a><p>[1] <span class="bibliosource"> | |
<a href="http://docbook.sourceforge.net/projects/xsl/" target="_new"> | |
DocBook XSL Style Sheets | |
</a> | |
. </span></p></div><div class="biblioentry"><a name="dita"></a><p>[2] <span class="bibliosource"> | |
<a href="http://dita-ot.sourceforge.net/" target="_new"> | |
DITA Open Toolkit | |
</a> | |
. </span></p></div><div class="biblioentry"><a name="toolchain"></a><p>[3] <span class="bibliosource"> | |
<a href="http://en.wikipedia.org/wiki/Toolchain" target="_new"> | |
Wikipedia: Toolchain | |
</a> | |
. </span></p></div><div class="biblioentry"><a name="vex"></a><p>[4] <span class="bibliosource"> | |
<a href="http://vex.sf.net/" target="_new"> | |
Vex | |
</a> | |
. </span></p></div><div class="biblioentry"><a name="openoffice"></a><p>[5] <span class="bibliosource"> | |
<a href="http://www.openoffice.org/" target="_new"> | |
OpenOffice | |
</a> | |
. </span></p></div><div class="biblioentry"><a name="subversion"></a><p>[6] <span class="bibliosource"> | |
<a href="http://subversion.tigris.org/" target="_new"> | |
Subversion | |
</a> | |
. </span></p></div></div><div class="appendix" lang="en"><h2 class="title" style="clear: both;"><a name="N10243"></a>A. Appendix</h2><p> | |
The appendix contains a discussion about how this article | |
was written (including the HTML style sheet so you can write | |
your own eclipse.org article in DocBook). The appendix also | |
reviews a couple of other editors out there for technical | |
documentation in case WTP's XML editor doesn't suit your fancy. | |
</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10248"></a>The Article</h3></div></div><div></div></div><p> | |
This article was written in DocBook using WTP's XML | |
editor. To transform the article into the correct format | |
for eclipse.org, a style sheet was developed that extends | |
the transformation included in the DocBook XSL project. | |
The eclipse.org article style sheet can be downloaded | |
<a href="https://bugs.eclipse.org/bugs/files/article.xsl" target="_new">here</a>. | |
</p><div class="note" style="margin-left: 0.38in; margin-right: 0.38in;"><table summary="Note" border="0"><tbody><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="images/note.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p> | |
Eclipse.org is in the process of moving to a data driven format | |
for articles. You can find more information about this process | |
by following bug <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=115473" target="_new"> | |
#115473</a>. We will be contributing our stylesheets for DocBook and | |
DITA to this bug. | |
</p></td></tr></tbody></table></div> | |
<p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10259"></a>Editors</h3></div></div><div></div></div><p> | |
Part of the creation process involves editing the | |
content of your XML document in an editor. The editor | |
you use is a preference that is usually precious to the | |
content creator (think EMACS versus VI). We decided to | |
use the WTP XML editor as the editor for this article | |
because of our familiarity with it and because both of us like working | |
within Eclipse. However, we realize that there are other | |
options for creating and editing content so we'll | |
discuss of a couple of those options in the following | |
sections. | |
</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N1025E"></a>Vex</h4></div></div><div></div></div><p> | |
Vex | |
[<a href="#vex">4</a>] | |
is an open source project that lets you edit XML | |
files visually. Vex uses standard Document Type | |
Definition (DTD) files to define document types and | |
Cascading Style Sheets (CSS) to define document | |
layout. In essence, Vex only requires that you have | |
knowledge of CSS and DTDs in order to contribute a | |
visual editor for XML files. The Vex editor can be | |
seen in | |
<a href="#vex-editor" title="Figure A.1. Vex DocBook editor screenshot">Figure A.1, “Vex DocBook editor screenshot”</a> | |
. | |
</p><div class="figure"><a name="vex-editor"></a><p class="title"><b>Figure A.1. Vex DocBook editor screenshot</b></p><div class="mediaobject"><table summary="manufactured viewport for HTML img" border="0" cellpadding="0" cellspacing="0" width="652"><tbody><tr style="height: 498px;"><td><img src="images/vex.png" alt="Vex DocBook editor screenshot" width="652"></td></tr></tbody></table></div></div> | |
<p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10276"></a>OpenOffice</h4></div></div><div></div></div><p> | |
OpenOffice | |
[<a href="#openoffice">5</a>] | |
is a multi-platform open source office suite that is | |
capable of visually editing DocBook and various | |
other formats. OpenOffice is a popular editing | |
choice because of its ability to open multiple | |
document formats, including Microsoft Word, and then | |
export the documents to DocBook. | |
</p><p> | |
OpenOffice doesn't fully support DocBook. An | |
updated list of what portions of DocBook OpenOffice | |
supports can be found on the OpenOffice site | |
<a href="http://xml.openoffice.org/xmerge/docbook/DocBookTags.html" target="_new"> | |
here | |
</a> | |
. The site also contains a getting started | |
<a href="http://xml.openoffice.org/xmerge/docbook/UserGuide.html" target="_new"> | |
guide | |
</a> | |
that will get you started with DocBook in | |
OpenOffice. | |
</p></div></div></div><p></p><h3>Trademarks</h3><div><div class="legalnotice"><a name="N10038"></a><p> | |
IBM, AIX, and developerWorks are registered trademarks of International Business Machines | |
Corporation in the United States, other countries, or both. | |
</p><p> | |
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United | |
States, other countries, or both. | |
</p><p> | |
Linux is a trademark of Linus Torvalds in the United States, other countries, or both. | |
</p><p> | |
Microsoft is a trademark of Microsoft Corporation in the United States, other countries, or both. | |
</p><p> | |
UNIX is a registered trademark of The Open Group in the United States and other countries. | |
</p><p> | |
Other company, product, or service names may be trademarks or service marks of others. | |
</p></div></div></div></body></html> |