<?xml version="1.0" encoding="utf-8"?> | |
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" | |
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> | |
<article id="article"> | |
<articleinfo> | |
<title>Authoring with Eclipse</title> | |
<releaseinfo> | |
<remark>Updated May 2008 by Peter Friese, itemis AG (see <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=225714">Bug 225714)</ulink>.</remark> | |
</releaseinfo> | |
<date>December 14, 2005</date> | |
<authorgroup> | |
<author> | |
<firstname>Chris</firstname> | |
<surname>Aniszczyk</surname> | |
<affiliation> | |
<orgname>IBM Corporation</orgname> | |
<address> | |
<email>zx@us.ibm.com</email> | |
</address> | |
</affiliation> | |
</author> | |
<author> | |
<firstname>Lawrence</firstname> | |
<surname>Mandel</surname> | |
<affiliation> | |
<orgname>IBM Corporation</orgname> | |
<address> | |
<email>lmandel@ca.ibm.com</email> | |
</address> | |
</affiliation> | |
</author> | |
</authorgroup> | |
<copyright> | |
<year>2005</year> | |
<holder>International Business Machines Corporation. All rights reserved.</holder> | |
</copyright> | |
<abstract> | |
<para> | |
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. | |
</para> | |
</abstract> | |
<legalnotice> | |
<para> | |
IBM, AIX, and developerWorks are registered trademarks of International Business Machines | |
Corporation in the United States, other countries, or both. | |
</para> | |
<para> | |
Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United | |
States, other countries, or both. | |
</para> | |
<para> | |
Linux is a trademark of Linus Torvalds in the United States, other countries, or both. | |
</para> | |
<para> | |
Microsoft is a trademark of Microsoft Corporation in the United States, other countries, or both. | |
</para> | |
<para> | |
UNIX is a registered trademark of The Open Group in the United States and other countries. | |
</para> | |
<para> | |
Other company, product, or service names may be trademarks or service marks of others. | |
</para> | |
</legalnotice> | |
</articleinfo> | |
<section> | |
<title>Environment</title> | |
<note> | |
<para> | |
The examples in this article were built and tested with: | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
<ulink | |
url="http://www.eclipse.org/downloads/download.php?file=/eclipse/downloads/drops/R-3.1-200506271435/eclipse-SDK-3.1-win32.zip"> | |
Eclipse 3.1 | |
</ulink> | |
</simpara> | |
</listitem> | |
<listitem> | |
<simpara> | |
<ulink | |
url="http://download.eclipse.org/webtools/downloads/drops/R-1.0-/"> | |
Eclipse Web Tools Platform (WTP) 1.0 | |
</ulink> | |
</simpara> | |
</listitem> | |
<listitem> | |
<simpara> | |
<ulink | |
url="http://eclipsexslt.sourceforge.net/"> | |
Orangevolt XSLT 1.0.4 | |
</ulink> | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
</para> | |
</note> | |
</section> | |
<section> | |
<title>Introduction</title> | |
<para> | |
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. | |
</para> | |
</section> | |
<section> | |
<title>Technical Documentation</title> | |
<para> | |
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. | |
</para> | |
<tip> | |
<para> | |
If you're unfamiliar with DocBook, there's an | |
<ulink | |
url="http://www-128.ibm.com/developerworks/library/l-docbk.html"> | |
article | |
</ulink> | |
on the <trademark class="registered">IBM</trademark> <trademark class="registered">developerWorks</trademark> site by Joe Brockmeier that can serve as a | |
gentle introduction. There is also an | |
<ulink | |
url="http://www-128.ibm.com/developerworks/xml/library/x-dita1/index.html"> | |
introduction | |
</ulink> | |
to DITA on developerWorks. | |
</para> | |
</tip> | |
<para> | |
The technical documentation process can be broken down into | |
three broad stages: creation, review, and publication. | |
</para> | |
<para> | |
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. | |
</para> | |
<para> | |
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. | |
</para> | |
<para> | |
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. | |
</para> | |
<section> | |
<title>Advantages of an XML format</title> | |
<para> | |
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. | |
</para> | |
<para> | |
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. | |
</para> | |
<para> | |
<emphasis>Modularity</emphasis> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
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 <emphasis>Java Web | |
Application Development with Eclipse</emphasis> (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. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<emphasis>Version Control</emphasis> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
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 <trademark class="registered">Microsoft</trademark> 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. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<emphasis>Consistent Formatting</emphasis> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
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. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<emphasis>Publishing to Multiple Formats</emphasis> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
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. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
</para> | |
</section> | |
</section> | |
<section> | |
<title>Examples</title> | |
<para> | |
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 | |
<ulink url="files/book.xml">here</ulink>. This DocBook source for this | |
article is also available and can be seen <ulink url="AuthoringWithEclipse.xml">here</ulink>. | |
</para> | |
<section> | |
<title>Tool Chain</title> | |
<para> | |
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 | |
<xref linkend="toolchain" /> | |
. This concept should be very familiar to those who work | |
on the <trademark class="registered">UNIX</trademark>, | |
<trademark class="registered">Linux</trademark>, and | |
<trademark class="registered">AIX</trademark> 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. | |
</para> | |
<para> | |
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. | |
</para> | |
<para> | |
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. | |
</para> | |
<section> | |
<title>Creation and Review</title> | |
<para> | |
Although creation and review are two separate parts | |
of the technical documentation process, the same | |
tools are required and therefore will be discussed | |
together. | |
</para> | |
<para> | |
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 | |
<xref linkend="xml-source-editor" /> | |
, is more useful when authoring in XML. | |
</para> | |
<figure id="xml-source-editor"> | |
<title>The XML Source Editor</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="807" depth="598" fileref="images/xmlsourceeditor.gif" | |
format="GIF" /> | |
</imageobject> | |
</mediaobject> | |
</figure> | |
<para> | |
The XML editor provides many of the Eclipse | |
franchise functions that <trademark>Java</trademark> developers have become | |
accustomed to with the Java editor. | |
</para> | |
<simpara> | |
<emphasis>Content Assistance</emphasis> | |
</simpara> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
Gives you a list of valid XML elements | |
constrained by an associated grammar. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<simpara> | |
<emphasis>Syntax Highlighting</emphasis> | |
</simpara> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
Gives you improved code readability by | |
making certain errors instantly visible. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<simpara> | |
<emphasis>Validation</emphasis> | |
</simpara> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
Ensures validity of an XML document based | |
on an associated grammar. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<simpara> | |
<emphasis>Outline View</emphasis> | |
</simpara> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
Assists you in editing and viewing the | |
content of your document. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<simpara> | |
<emphasis>XML Catalog</emphasis> | |
</simpara> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
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. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<para> | |
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 | |
<xref linkend="subversion" />, 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. | |
</para> | |
</section> | |
<section> | |
<title>Publication</title> | |
<para> | |
The DocBook XSL | |
<xref linkend="docbookxsl" /> | |
and DITA | |
<xref linkend="dita" /> | |
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. | |
</para> | |
<tip> | |
<simpara> | |
The DITA Open Toolkit (DITA-OT) includes a DITA to DocBook | |
<ulink | |
url="http://dita-ot.sourceforge.net/doc/DITA-antscript.html"> | |
transformation | |
</ulink>. | |
</simpara> | |
</tip> | |
<para> | |
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. | |
</para> | |
<section> | |
<title>HTML</title> | |
<para> | |
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: | |
<itemizedlist> | |
<listitem> | |
<simpara>DocBook</simpara> | |
<itemizedlist> | |
<listitem> | |
<simpara>html/docbook.xsl</simpara> | |
</listitem> | |
</itemizedlist> | |
</listitem> | |
<listitem> | |
<simpara>DITA</simpara> | |
<itemizedlist> | |
<listitem> | |
<simpara>xsl/dita2html.xsl</simpara> | |
</listitem> | |
</itemizedlist> | |
</listitem> | |
</itemizedlist> | |
<xref linkend="html-transformation" /> | |
shows a sample transformation configuration that | |
will transform our DocBook sample | |
<ulink url="files/book.xml">document</ulink> | |
into HTML. | |
</para> | |
<figure id="html-transformation"> | |
<title>Sample HTML Transformation Configuration for book.xml</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="692" depth="517" fileref="images/html.png" | |
format="PNG" /> | |
</imageobject> | |
</mediaobject> | |
</figure> | |
<tip> | |
<para> | |
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 | |
<ulink | |
url="http://docbook.sourceforge.net/release/xsl/current/doc/html/"> | |
here | |
</ulink>. | |
</para> | |
</tip> | |
<para> | |
A Flash movie that | |
shows how to run the transformation can be seen | |
<ulink url="files/DocBook-HTML.htm">here</ulink> | |
. | |
</para> | |
</section> | |
<section> | |
<title>PDF</title> | |
<para> | |
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. | |
</para> | |
<para> | |
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: | |
<emphasis>fo/docbook.xsl</emphasis>. | |
<xref linkend="xslfo-transformation" /> | |
shows a sample transformation configuration used | |
to generate an XSL-FO document from book.xml. | |
</para> | |
<figure id="xslfo-transformation"> | |
<title>Sample XSL-FO Transformation Configuration for book.xml</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="692" depth="517" fileref="images/xsl-fo.png" | |
format="PNG" /> | |
</imageobject> | |
</mediaobject> | |
</figure> | |
<para> | |
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 | |
<ulink | |
url="http://xmlgraphics.apache.org/fop/"> | |
Apache FOP | |
</ulink> | |
. We'll use a third-party | |
<ulink | |
url="http://www.ahmadsoft.org/fopbridge.html"> | |
plug-in from Ahmadsoft | |
</ulink> | |
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. | |
<xref linkend="pdf-transformation" /> | |
shows an example of running the FOP | |
transformation. | |
</para> | |
<figure id="pdf-transformation"> | |
<title>Sample FOP Transformation</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="430" depth="447" fileref="images/fop.png" | |
format="PNG" /> | |
</imageobject> | |
</mediaobject> | |
</figure> | |
<note> | |
<para> | |
The example includes a sample Ant | |
<ulink url="files/pdf/build.xml"> | |
file | |
</ulink> | |
that performs the same transformation as | |
running the FOP transformation using the | |
<ulink | |
url="http://www.ahmadsoft.org/fopbridge.html"> | |
plug-in from Ahmadsoft | |
</ulink>. 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. | |
</para> | |
</note> | |
<para> | |
As before, a Flash movie that shows the | |
transformation is available | |
<ulink url="files/DocBook-PDF.htm">here</ulink> | |
. | |
</para> | |
</section> | |
<section> | |
<title>Eclipse Infocenter</title> | |
<para> | |
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: | |
<emphasis>eclipse/eclipse.xsl</emphasis>. | |
<xref linkend="eclipse-transformation" /> | |
shows a sample transformation configuration | |
along with the correct parameters. To perform | |
this transformation using a DITA source file, use | |
the | |
<emphasis>ant/sample_eclipsehelp.xml</emphasis> | |
Ant file. | |
</para> | |
<figure id="eclipse-transformation"> | |
<title>Sample Eclipse Infocenter Transformation Configuration</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="803" depth="388" fileref="images/eclipse.png" | |
format="PNG" /> | |
</imageobject> | |
</mediaobject> | |
</figure> | |
<tip> | |
<para> | |
The complete list of DocBook XSL parameters | |
for the Eclipse Infocenter transformation | |
is located | |
<ulink | |
url="http://docbook.sourceforge.net/release/xsl/current/doc/html/rn22.html"> | |
here | |
</ulink> | |
. | |
</para> | |
</tip> | |
<para> | |
The Flash movie that shows the Eclipse | |
Infocenter DocBook transformation can be found | |
<ulink url="files/DocBook-InfoCenter.htm"> | |
here | |
</ulink> | |
. | |
</para> | |
</section> | |
</section> | |
<section> | |
<title>Current Limitations</title> | |
<para> | |
Although we have shown that Eclipse's current XML | |
authoring support is pretty good, there are a two | |
noteworthy limitations. | |
</para> | |
<para> | |
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. | |
</para> | |
<para> | |
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. | |
</para> | |
<para> | |
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. | |
</para> | |
</section> | |
</section> | |
</section> | |
<section> | |
<title>Summary</title> | |
<para> | |
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. | |
</para> | |
</section> | |
<section> | |
<title>Acknowledgements</title> | |
<para> | |
We'd like to thank: | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
Sushma Patel and Anne James for correcting our horrible | |
grammar. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
<itemizedlist> | |
<listitem> | |
<simpara> | |
Don Day and Michael Priestly for their DITA | |
expertise. | |
</simpara> | |
</listitem> | |
</itemizedlist> | |
</para> | |
</section> | |
<section> | |
<title>About the Authors</title> | |
<para> | |
Chris Aniszczyk is a software developer at the IBM Austin | |
Labs and works in Tivoli Security. He's a developer on the | |
<ulink url="http://www.gentoo.org">Gentoo Linux</ulink> | |
distribution and also a committer on the | |
<ulink url="http://www.eclipse.org/emft"> | |
Eclipse Modeling Framework Technology (EMFT) | |
</ulink> | |
project. | |
</para> | |
<para> | |
Lawrence Mandel, a software developer at the IBM Toronto | |
Laboratory, is the documentation lead and a | |
committer for the Eclipse | |
<ulink url="http://www.eclipse.org/webtools"> | |
Web Tools Platform (WTP) | |
</ulink> | |
project. He is also authoring a book with Arthur Ryman and | |
Naci Dai about Java Web application development with | |
Eclipse. | |
</para> | |
</section> | |
<bibliography> | |
<title>Resources</title> | |
<biblioentry id="docbookxsl"> | |
<bibliosource> | |
<ulink url="http://docbook.sourceforge.net/projects/xsl/"> | |
DocBook XSL Style Sheets | |
</ulink> | |
</bibliosource> | |
</biblioentry> | |
<biblioentry id="dita"> | |
<bibliosource> | |
<ulink url="http://dita-ot.sourceforge.net/"> | |
DITA Open Toolkit | |
</ulink> | |
</bibliosource> | |
</biblioentry> | |
<biblioentry id="toolchain"> | |
<bibliosource> | |
<ulink url="http://en.wikipedia.org/wiki/Toolchain"> | |
Wikipedia: Toolchain | |
</ulink> | |
</bibliosource> | |
</biblioentry> | |
<biblioentry id="vex"> | |
<bibliosource> | |
<ulink url="http://vex.sf.net"> | |
Vex | |
</ulink> | |
</bibliosource> | |
</biblioentry> | |
<biblioentry id="openoffice"> | |
<bibliosource> | |
<ulink url="http://www.openoffice.org"> | |
OpenOffice | |
</ulink> | |
</bibliosource> | |
</biblioentry> | |
<biblioentry id="subversion"> | |
<bibliosource> | |
<ulink url="http://subversion.tigris.org/"> | |
Subversion | |
</ulink> | |
</bibliosource> | |
</biblioentry> | |
</bibliography> | |
<appendix> | |
<title>Appendix</title> | |
<para> | |
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. | |
</para> | |
<section> | |
<title>The Article</title> | |
<para> | |
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 | |
<ulink url="files/article.xsl">here</ulink>. | |
<note> | |
<para> | |
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 <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=115473"> | |
#115473</ulink>. We will be contributing our stylesheets for DocBook and | |
DITA to this bug. | |
</para> | |
</note> | |
</para> | |
</section> | |
<section> | |
<title>Editors</title> | |
<para> | |
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. | |
</para> | |
<section> | |
<title>Vex</title> | |
<para> | |
Vex | |
<xref linkend="vex" /> | |
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 | |
<xref linkend="vex-editor" /> | |
. | |
<figure id="vex-editor"> | |
<title>Vex DocBook editor screenshot</title> | |
<mediaobject> | |
<imageobject> | |
<imagedata width="652" depth="498" fileref="images/vex.png" | |
format="PNG" /> | |
</imageobject> | |
</mediaobject> | |
</figure> | |
</para> | |
</section> | |
<section> | |
<title>OpenOffice</title> | |
<para> | |
OpenOffice | |
<xref linkend="openoffice" /> | |
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. | |
</para> | |
<para> | |
OpenOffice doesn't fully support DocBook. An | |
updated list of what portions of DocBook OpenOffice | |
supports can be found on the OpenOffice site | |
<ulink | |
url="http://xml.openoffice.org/xmerge/docbook/DocBookTags.html"> | |
here | |
</ulink> | |
. The site also contains a getting started | |
<ulink | |
url="http://xml.openoffice.org/xmerge/docbook/UserGuide.html"> | |
guide | |
</ulink> | |
that will get you started with DocBook in | |
OpenOffice. | |
</para> | |
</section> | |
</section> | |
</appendix> | |
</article> |