Authoring with the developerWorks XML article template

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 also included.

Getting started
Thank 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 our content 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 format.
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 directory structure:

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, dw-entities-n.n.xsl, dw-ratingsform-n.n.xsl, dw-translated-text-worldwide-n.n.xsl, and 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 directory.

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 article.

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 HTML

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 XML

Approach 2. Using a command-line option
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 schema.

Two command-line options we recommend you try are the Microsoft Command Line Transformation Utility and Apache Xalan.

Using the Microsoft Command Line Transformation Utility
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 download site).

Place this file in the developerworks directory. Now open a command window. Change to the developerworks directory as shown in Figure 3.

Figure 3. Listing of C:\developerworks
$Listing of C:\developerworks$

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 text


msxsl template/template-dw-article-3.0.xml xsl/dw-document-html-3.0.xsl \
-o template/output.html

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 5.

Figure 4. Viewing HTML output

Using Apache 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.

Listing 3. Using the command line with Xalan


java org.apache.xalan.xslt.Process \
-IN input-file-name \
-XSL schema-file-name \
-OUT output-file-name

An example is shown in Listing 4.

Listing 4. Example Xalan command-line text


java org.apache.xalan.xslt.Process \
-IN template/template-dw-article-3.0.xml \
-XSL xsl/dw-document-html-3.0.xsl \
-OUT template/output.html

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 4.

Approach 3. Using Cooktop, a free XML editor
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 in Figure 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 writing.)

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 source code.
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 6.

Figure 6. Cooktop successful validation
Cooktop successful validation

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 writing.)

Figure 7. Cooktop displaying XML template as HTML

Approach 4. Using a commercial XML editor
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 article
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 spaces.
- Avoid hardcoding blank spaces or tabs at the end of a line of sample code.
- 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 (®)
<reg/>
Trademark (™)
<trade/>
For example, to code the angle brackets in the following sample code listing:
<TABLE border="0" width="100%">
Code the following in the XML template:

<TABLE border="0" width="100%">
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 tagging.

Submitting your article
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.

Release notes
At the 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 and stylesheets
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 and stylesheets
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 "Subscription")
Improving translation (stylesheet was enabled for worldwide use with 4 new translated text files)

Conclusion
The 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.

Resources

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 msxml.ms.i.
To use approach 2, download Microsoft's Command Line Transformation Utility, or download Apache Xalan and read the documentation on how to use it from the command line.
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 platforms.
For approach 4, download IBM WebSphere Studio Site Developer and get Studio information, or download Altova XMLSPY and view XMLSPY documentation.
Read about the developerWorks author guidelines and editorial policy for articles we publish on developerWorks.
Submit an article idea to developerWorks using our content submission form.
If you have questions, contact the developerWorks editor for the technology or product zone you're interested in.

About the author
This article was brought to you by the developerWorks editorial staff.

developerWorks

About IBM | Privacy | Terms of use | Contact