An author's step-by-step guide
21 Jul 2003
Updated 13 Mar
This article shows authors how to prepare technical articles
for publication on developerWorks. These steps will help you download an
XML-based template for your article content, which you can then fill in
using any of four approaches described here. Tips for composing your
article and for submitting your article to the developerWorks staff are
you for your willingness to write an article for IBM developerWorks. The
editors at developerWorks look forward to working with you to publish your
article. Please be sure you have presented your article idea to an editor
and have obtained his or her approval to proceed before using these
instructions to compose your article. If you haven't already, you can use
submission form to submit your idea.
At developerWorks, we ask authors to use our XML template to develop
their articles. Using our template has several benefits to authors:
- Speed. Your article will get published sooner.
- Accuracy. Transcription errors are less likely, since the
developerWorks staff will not need to convert your article to our XML
- Preview. You can get a good idea of what your article will look like
when published on our site. (An active Internet connection is required
if you wish to do this.)
Here are four approaches to using our XML template, starting with the
simplest to implement. Most authors prefer the first approach:
- Approach 1: Using a text editor and Internet Explorer to edit
and view the XML template
- Approach 2: Using a command-line option if the first approach
does not work for you
- Approach 3: Using a free XML editor, such as Cooktop
- Approach 4: Using a commercial XML editor, such as IBM
WebSphere® Studio Site Developer or Altova XMLSPY
Note that approaches 1 and 2 do not check syntax (and may delay
publication a bit while the developerWorks editorial staff fixes any
coding errors you might not have caught). Approaches 3 and 4 do provide
complete syntax checking and increase the chances that you will deliver an
error-free XML file to the developerWorks staff.
Regardless of which approach you choose, begin by downloading the
author-package.zip file (see Resources for a link). Place this file in a suitable
location (for example,
C:\). Next, unzip it. This will place
all the files in their correct locations. You should see the following
- developerworks\i -- This directory contains small images
commonly used in dW articles. Having these common images ensures that
you can view your article completely.
- developerworks\my-article -- This directory contains the XML
article template file that you should use for your article. You may copy
this template as the base for your article. Besides your article file,
collect in this folder any article-specific graphics, source code, and
any other files that you intend to submit to your developerWorks editor.
- developerworks\readme -- This directory contains the XML
source for this article in the file readme.xml, the HTML output
in the file readme.html as well as the graphics.
- developerworks\schema -- This directory contains one schema
file named dw-document-n.n.xsd. (n.n is the level
of the developerWorks schema in use. For example, 3.0 is the current
schema level at the time of this writing.)
- developerworks\template -- This directory contains the XML
article template file named template-dw-article-n.n.xml
that you should use for your article. (Again, n.n is the level of
the schema in use.)
- developerworks\xsl -- This directory contains five stylesheet
files named dw-document-html-n.n.xsl,
xslt-utilities-n.n.xsl. (And as you know by now,
n.n is the level of the schema in use.)
Although the instructions in this article focus on the Microsoft
Windows platform, we have also successfully tested the author-package.zip
file on Linux.
If you are using Internet Explorer, ensure that you have IE version 6.
You should also download the latest version of Microsoft's XML Parser
(MSXML). The file you need is msxml.msi (see the Resources section of this article for a link to the
download site) -- install the parser by double-clicking on the downloaded
file. The latest versions of the Mozilla and Netscape browsers should also
work with the XML template.
In the examples that follow, we will experiment with the template-dw-article-n.n.xml
file in the template directory.
Before you begin composing your own article, copy the template file (template-dw-article-n.n.xml)
and save it with the name of your choice (an appropriate name to identify
your article) and store it in the my-article directory. As
mentioned above, also place your graphics, source code, and any other
files that you intend to submit to your developerWorks editor in this same
Approach 1. Using a text editor
and Internet Explorer (IE)
Most authors find this approach
appropriate for their needs. But again, note that approach 1 does not
provide the complete syntax checking required to ensure that your XML
coding conforms to the schema. If you want to increase your chances of
delivering an error-free XML file to the developerWorks staff, consider
using approach 3 or 4.
You can edit the XML template file using your favorite word processor
or text editor. Notepad would be sufficient. Follow the detailed comments
in your copy of the XML article template to correctly format your
To view the article in Internet Explorer, ensure that you are using IE
version 6. Open your article template in IE (File > Open) and you
should see the XML file rendered into HTML. If IE reports any errors, go
back and fix these and try again. Figure 1
shows how the XML template should correctly appear in IE. (References in
figures to "2.2" refer to the level of the developerWorks schema in use,
which is 3.0 at the time of this writing.)
Figure 1. IE displaying XML template as
If you have correctly formatted your article and IE does not report any
errors, but still does not render your article into HTML, and it appears
as shown in Figure
2, the next approach may help you. (References in figures to "2.2"
refer to the level of the developerWorks schema in use, which is 3.0 at
the time of this writing.)
Figure 2. IE displaying XML template as
Approach 2. Using a command-line
If you have difficulties viewing the XML template in
IE, you may be able to view the output with a command-line option, but
keep in mind that this approach also does not provide the complete syntax
checking required to ensure that your XML coding conforms to the
Two command-line options we recommend you try are the Microsoft Command
Line Transformation Utility and Apache Xalan.
Using the Microsoft Command Line
Download the Command Line
Transformation Utility from Microsoft's Web site. The file you need is msxsl.exe (see the Resources section of this article for a link to the
Place this file in the developerworks directory. Now open a command
window. Change to the developerworks directory as shown in Figure
Figure 3. Listing of
On the command line, type the text shown in Listing
1, substituting the appropriate file names for input-file-name, schema-file-name, and output-file-name.Listing 1. Using the command line
msxsl input-file-name schema-file-name -o output-file-name
An example is shown in Listing
2.Listing 2. Example command-line
msxsl template/template-dw-article-3.0.xml xsl/dw-document-html-3.0.xsl \
In this example, an output file called output.html is produced;
you can double-click and view this file in a browser, as shown in Figure
Figure 4. Viewing HTML output
XalanListing 3. Using the command line with Xalan
You may already have Xalan installed and configured on
your personal computer. If not, you can freely download it from the Apache
Web site (see Resources for a download link). To use Xalan from the
command line, open a command window and change to the developerworks
directory as previously shown in Figure
3. On the command line, type the text shown in Listing
3, substituting the appropriate file names for input-file-name, schema-file-name, and output-file-name.
java org.apache.xalan.xslt.Process \
-IN input-file-name \
-XSL schema-file-name \
An example is shown in Listing
4.Listing 4. Example Xalan command-line
java org.apache.xalan.xslt.Process \
-IN template/template-dw-article-3.0.xml \
-XSL xsl/dw-document-html-3.0.xsl \
In this example, an output file called output.html is also
produced; you can double-click and view this file in a browser, and it
should also appear the same as Figure
Approach 3. Using Cooktop, a free
Fortunately, there are many free XML editors
available today that you can use to edit your articles and transform them
into HTML. A good list is maintained by Lars Marius Garshol (see Resources for a link).
One editor that is simple to use and provides a color-coded editing
environment is Cooktop. It is a free tool, and you can download the fully
functional product (see Resources for a download link).
With Cooktop, after you have opened your XML template file (File > Open file...),
the working interface is simple and consists of five main tabs, as shown
5. (References in figures to "2.2" refer to the level of the
developerWorks schema in use, which is 3.0 at the time of this
Figure 5. Cooktop main tabs
From left to right, these tabs are:
- source (xml) -- Shows the XML template file that has pointers
to your schema and stylesheets.
- xpath console -- You should not need to use this; it is
needed only for debugging XSLT stylesheet code.
- stylesheet (xsl) -- Open this tab and load the stylesheet
dw-document-html-3.0.xsl using File > Open file...
- result -- After a transformation, shows the resulting HTML
- result (html) -- After a transformation, shows the rendered
HTML as a browser would.
To configure your XML parser, go to Options > XSLT
Engine, and select the XML parser you have installed on your machine
(for example, MSXML 4.0).
To validate an XML file once the XML file is loaded in the "source
(xml)" window, select XML > Validate. If
unsuccessful, you'll get an error message telling you the line and column
of the error. Or, if successful, Cooktop will tell you how many
milliseconds it took to validate the file, as shown in Figure
Figure 6. Cooktop successful
To transform a file, again in the "source (xml)" window, select XML > Run XSLT. If
successful, you'll see the resulting HTML source code under the result
tab, and the rendered HTML under the result (html) tab, as shown in Figure
7. (References in figures to "2.2" refer to the level of the
developerWorks schema in use, which is 3.0 at the time of this
Figure 7. Cooktop displaying XML template as
Approach 4. Using a commercial XML
There are many commercial XML editors on the market
today. Two that you might consider using are IBM WebSphere Studio Site
Developer and Altova XMLSPY (see Resources for links to downloads and documentation).
Both have free downloadable trial versions available, and we recommend
that you read the instructions that come with these products to learn how
to use them. All the required and supporting files you will need to use
both products, and other commercial XML editors, are in the developerWorks
author-package.zip file (see Resources for a link).
Tips for composing your
The XML article template file (template-dw-article-n.n.xml
in the template directory) is
your best source for comprehensive tips on developing your article.
Extensive tips are coded in comment lines; they walk you through every
aspect of coding your article. You can also look at the the XML source for
this article (readme.xml in the readme directory) as a
guide. Both these files are in the author-package zip file (see Resources for a link). Here are some other tips you
might find helpful:
- You can cut and paste from other file formats into the XML template.
If you cut and paste from a file with embedded formatting such as a
Microsoft Word file, either use your editor's capabilities to paste (or
paste special) as text, or save the file as a TXT file before you cut
and paste from it. Do not cut and paste directly from a formatted file
such as a DOC file.
- Remember to use end tags. For example, every paragraph tag
(<p>) needs its closing tag (</p>). Also, empty elements
like the break tag (<br/>) and the image tag (<img/>) need
their closing slash.
- Avoid span tags, code font tags, and font classes.
- When including listings of sample code:
- Confine code line lengths to 90 characters, INCLUDING blank
- Avoid hardcoding blank spaces or tabs at the end of a line of
- Avoid using tabs at the beginning of a line of sample code. If you
must indent, it is better to use blank spaces.
- Do not use color. If you want to use highlighting in sample code,
use bold instead.
- When providing downloadable sample code, zip the code up and send
the zip file separately.
- Create all artwork files, including screen captures, as JPG or GIF
files and be sure they do not exceed 600 pixels in width.
- Code special characters as follows:
- Ampersand (&)
- Apostrophe (')
- ' (always code ampersands as & -- even in URLs
- Greater than sign (>)
- Less than sign (<)
- Quotation mark (")
- Registered trademark (®)
- Trademark (™)
For example, to code the angle brackets in the following sample code
<TABLE border="0" width="100%">
Code the following in the XML template:
- And finally, to endear yourself to your developerWorks editor -- and
to better see your own content as you develop it -- you may remove the
comment lines from the article file as you become familiar with the
Once you have finished your masterpiece, you will
need to send it to your developerWorks editor. If you followed the
instructions in this article, all files specific to your article should be
in the my-article directory.
Send the XML file for your article (along with any associated graphics or
source code specific your article) in an e-mail to your editor.
time of this writing, 3.0 is the release level of the developerWorks
schema and stylesheets. The author-package.zip file and this authoring
article conform to the 3.0 release. You should prepare your article using
the 3.0 schema and stylesheets. If you are using the 2.2 (or previous)
release of the developerWorks schema and stylesheets, you'll need to
download the current (3.0) author-package.zip file (see Resources for a link).
Release notes for the 2.2 schema
The 2.2 schema and stylesheets were released
on 20 November 2003. Major changes for articles included:
- Updating element tags ("zone" became "content-area"; "zip" became
"download-feature" with new attributes; abstract elements were reworked
to "abstract" and "abstract-extended"; author bio elements had slight
changes; ratings form link changed)
- Reflecting site changes (new autonomic content area; "IBM developer
solutions" content area became "Scenarios"; new "Subscription" section
under "Related content")
- Improving search and translation capabilities
- Meeting ibm.com standards (color and meta tagging changes)
Release notes for the 3.0 schema
The 3.0 schema and stylesheets were released
on 10 March 2004. Major changes for articles included:
- Updating element tags ("download-feature" gained 4 new download file
types: bat, java, pl, sh; content-area value of "toolbox" became
- Improving translation (stylesheet was enabled for worldwide use with
4 new translated text files)
instructions and options in this article should help you set up your
environment to use the developerWorks XML article template and associated
files. If you have any questions or problems, please contact your
editor for additional help.
- Get started by downloading the author-package zip file.
- To use Internet Explorer to preview your article, download the
latest version of Microsoft's XML Parser (MSXML). The file you need is
- To use approach 2, download Microsoft's Command Line Transformation Utility, or
Xalan and read the documentation on how to use it from the command
- For approach 3, download Cooktop, or select another XML editor from the list
of free XML
Editors maintained by Lars Marius Garshol.
- Another option for approach 3 is to learn about and download the Morphon
XML-Editor Suite, a Java-based, multiplatform XML editor. Packages
are available for Linux, Mac OS X, Windows, and many other
- For approach 4, download IBM
WebSphere Studio Site Developer and get Studio
information, or download Altova
XMLSPY and view XMLSPY
- Read about the developerWorks author guidelines and editorial
policy for articles we publish on developerWorks.
- Submit an article idea to developerWorks using our content
- If you have questions, contact the developerWorks editor for the technology or product
zone you're interested in.