Authoring with the developerWorks XML templates on Windows
A step-by-step guide for authors to create content for publication on developerWorks
The editors at developerWorks look forward to working with you to publish your article. Be sure that you have presented your idea to an editor and have obtained the approval to proceed with developing your article before using these instructions. If you haven't already, fill in the Submit article proposal form to propose your idea.
The XML author package contains a set of tools written in VBScript (.vbs) that run on the Windows operating system (32-bit or 64-bit versions). If you do not have access to a Windows system, you need to use either the Word template or the beta-level Python scripts described in the adjacent sidebars.
The basic steps to create an article are:
- Download the author package and extract it.
- Create a new project folder with an index.xml file for your article using a script from the package.
- Edit your article.xml file, validate the XML, transform the XML into HTML, and preview in a browser.
Download and extract the author package
Download the author-package zip file and extract it. This creates a developerworks directory (or folder) on your file system. To ensure that the tools work correctly, do not change the structure of this directory or rename any of its subdirectories or files.
Create a project folder and files
Double-click the new-article.vbs file in your developerworks directory.
In the dialog box for providing the name of your new project folder, enter any valid folder name or leave the default value of my-article and click OK.
You should now see your new project folder in the developerworks directory. The project folder contains the following files:
- index.xml: The XML file that you edit to write your article.
- dw-transform.vbs: The script that you use in Step 3 to validate your index.xml file and transform it into an HTML file that you can preview in a browser.
- template-dw-article-8.0.xml: The original article template XML file. As you edit your index.xml file, it might be helpful to occasionally refer back to this template.
- The folder also contains two .jpg files for the two figures in the article template.
Edit, validate, transform, and preview your article
You can use any text editor that can save files in plain text format along with the VBScript validation tool supplied in the author package to edit, validate, transform, and preview your article. The validation tool requires that you have installed the latest version of Microsoft's XML Parser (MSXML). The current version at the time of this writing is 6.0. See Related topics for a link to MSXML 6.0.
Edit the XML file
Open the index.xml file from your project folder in your editor. Use the comments in the file and the Composition tips section of this article as a guide while you are writing. When you save your file, be sure to save it as plain text and do not change its name to anything other than index.xml.
Save any graphics or screen shots that you create in the same project directory as your article. See "Illustrating your content for developerWorks" for details on creating graphics.
Validate the XML and correct errors
As you write your article, you need to validate the index.xml file against the developerWorks article schema. Validating as you go along helps you identify errors more easily.
Each time you want to validate, go to the project directory and double-click the dw-transform.vbs file. If your index.xml file validates without any errors, you see the window shown in Figure 1.
Figure 1. Message after transforming a valid article XML file
If your file contains invalid markup, you instead see an error message window describing the first error encountered and its line number in your index.xml file.
The error messages are generated by the MSXML parser. Sometimes the messages are a bit cryptic, but along with the line number, you should have enough information to figure out the problem. For example, if the reason contains Expecting a, b, br, ... with a long list of other tags, you have probably mistyped a tag name or attempted to use a tag that isn't supported by the developerWorks schema.
After you have located and corrected an error, save the file and run dw-transform.vbs again to recheck it. Repeat this process until you have no more errors.
Preview your content
When your index.xml file is valid, running dw-transform.vbs also creates an HTML version of your article in your project folder and names it index.html. Open this file with your preferred browser to preview your article.
The preview provides a general idea of what the final output will look like. While previewing, focus on the text and don't worry about presentation or style issues—your developerWorks editor will address these types of issues during the final edit.
Congratulations! You've edited, validated, and previewed your article. Following are some tips to help you finish up your article and submit it to your developerWorks editor.
The index.xml file for your article contains comments and sample markup that provide you with guidance for properly coding your article. Here are some additional tips:
- Copying and pasting from Microsoft Word or OpenDocument files:
- Do not copy and paste directly from a formatted file. Use your editor's capabilities to paste (or paste special) as text, or first save the file as a TXT file before you copy and paste from it.
- If your Word or OpenDocument file has embedded images, don't worry about extracting them; simply forward the Word or OpenDocument file to your developerWorks editor, and our team of visual designers will extract and refine the images.
- If your Word or OpenDocument file has "Track Changes" turned on, be sure to turn it off before you copy and paste into the XML template; otherwise, all your deleted material will reappear intermingled among your text.
- Closing tags. Remember to use closing tags. For example, every paragraph tag (<p>) needs its closing tag (</p>). Also, self-closing tags like the line break (<br />) and the image tag (<img />) need a closing slash (/).
- Tags to avoid. Do not use span tags, code font tags, font classes, or CDATA tags.
- Including sample code in your article:
- The article schema allows two different code elements: <code-listing> and <code>. Use the <code-listing> element to set your code sample apart from surrounding text. If you want to put a code snippet within a paragraph or list item (inline code), use the <code> element.
- The column width available for your code listing varies depending on the viewport size of the user's browser or mobile device. If the code listing exceeds the available width of the content column, a horizontal scroll bar displays at the bottom of the listing. We recommend you limit code lines to no more than 75 characters. Long lines do not autowrap. Code listings should be short enough to avoid interrupting the reading flow of your article.
- 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, use blank spaces.
- If you need to use angle brackets in your sample code, use < and > (see the other special characters in Table 1).
- Downloadable sample code. When providing downloadable sample code for the "Downloadable resources" section, compress the code and send the .zip file to your editor separately. Your editor is responsible for ensuring that the download file works correctly within the article.
- Artwork. Create all artwork files, including screen captures, as JPG, GIF, or PNG files. Send the artwork files to your editor. See "Illustrating your content for developerWorks" for details on creating graphics.
- Comment lines. As you write your article, feel free to remove the instructional comments as you become familiar with the tagging.
- Accessibility. Consider vision-challenged readers and ensure that your article satisfies web content accessibility requirements. Specifically, (1) use color sparingly, if at all, and (2) include text alternatives to images in your article by adding explanatory text before or after images and providing a short description of the image in the "alt" attribute of the <img> tag. These accessibility requirements are covered in greater detail in "Illustrating your content for developerWorks."
- Special characters. Code special characters as shown in Table 1.
Table 1. Special characters
|Ampersand (&)||& (Always code ampersands as & — even in URLs)|
|Em-dash (—)||<mdash />|
|Left angle bracket, or less-than sign (<)||<|
|Quotation mark (")||" (In text, use the keyboard quote, but to include a quotation mark in an XML element, use ")|
|Registered trademark (®)||<reg/> (Authors can, but don't need to, insert trademark symbols; the developerWorks editorial staff takes care of trademarks)|
|Right angle bracket, or greater-than sign (>)||>|
|Trademark (™)||<trade/> (Authors can, but don't need to, insert trademark symbols; the developerWorks editorial staff takes care of trademarks)|
For example, to include HTML tags in a code listing like this:
<TABLE border="0" width="100%">
You would put the following in your article.xml file:
Not sure how to highlight code strings? Do you emphasize an article or book title? When should you use no highlighting at all? The developerWorks editorial style guide shows the highlighting conventions recommended for developerWorks articles.
Submitting your article to developerWorks
After you've finished writing your article, email the index.xml file, along with any associated graphics and sample code, to your editor.
If you have any questions or problems, contact your editor for additional help.
The developerWorks staff would like to acknowledge the tremendous contribution of Ian Shields to the tools described in this article. Ian is a former member of the developerWorks team and a long-time contributor to the Linux zone on developerWorks.
- "Authoring with the developerWorks Word and OpenDocument templates" (developerWorks, August 2013): If, instead of using the XML templates, you prefer to compose your article in Microsoft Word, OpenOffice.org Writer, or another OpenDocument editor, we also offer Word and OpenDocument templates for your use.
- "Illustrating your content for developerWorks: How to create effective graphics" (developerWorks, August 2013): Get detailed guidelines and tips on creating and submitting graphics for your article.
- Microsoft's XML Parser (MSXML) Version 6: To use the dw-transform.vbs script to transform your article, you need Version 6 of the MSXML parser. The file you need is msxml6.msi.
- Here are some examples of commercial and free validating XML editors:
- Rational® Application Developer for WebSphere® Software: Download a no-charge trial version directly from developerWorks.
- oXygen XML Editor & XSLT Debugger (for multiple platforms): Learn about or download a trial version of this commercial XML editor.
- Altova XMLSpy (for Windows): Learn about or download a trial version of this commercial XML editor.
- XML Copy Editor: Learn about this fast, free, validating XML editor that can validate and transform your XML files.
- Notepad++: Learn about this free source code editor and Notepad replacement that runs in the Micorosft Windows environment. After installing Notepad++, you can use the Plugin Manager to install XML tools to validate your XML file.
- IBM trial products for download: Build your next development project with IBM trial software, available for download directly from developerWorks.
- developerWorks author guidelines and editorial policy: Learn more about our editorial policy.