Article-Authoring-With-Eclipse/AuthoringWithEclipse.xml

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