![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
Creating an article or tutorial for publication on developerWorks involves these steps:
- Download the author package and unzip the file.
- Copy the XML template for articles or the XML template for tutorials.
- Edit the XML template to add your content, then validate that XML against the schema, and correct any errors.
- Preview your article or tutorial in a browser to get an idea of how it will appear on developerWorks.
Start by reading and completing Step 1 and Step 2 in the article, "Authoring with the developerWorks XML templates." That article shows you how to download the author package that contains the tools and all files you'll need. It also includes tips for composing and submitting your content.
Then return to this article after you have completed Step 1 and Step 2. You will have downloaded the author package, unzipped the contents to your hard drive, and created a copy of the template using the new-tutorial or new-article tools described in that article. You are now ready to do the remaining steps: edit, validate, and preview your content using the instructions below.
You will need:
- A text editor or word processor that can save in plain text format. Although not necessary, you will find it convenient to have an editor that can display line numbers, because any errors detected in the validation phase will be reported by line number. The Notepad application on Windows XP will display line numbers if you select the View > Status Bar menu option. Note that this option is not available in Notepad in earlier versions of Windows.
- The latest version of Microsoft's XML Parser (MSXML), which is contained in Microsoft Core XML Services (MSXML) 6.0 at this writing. MSXML 4.0 Service Pack 2 (Microsoft XML Core Services) will also work. (To get the parser, see the Resources section of this article for a link.) Use the link to msxml6.msi to install Microsoft Core XML Services (MSXML) 6.0 on your computer. You may also save msxml6.msi to your local disk for later installation.
- Internet Explorer Version 6, 7, or 8, or another Web browser such as Mozilla, Firefox, or Opera.
Navigate to your new folder and edit your file
(index.xml) using your favorite text editor.
Notepad will suffice if you don't have another preferred editor. Follow
the detailed comments in the index.xml template
file. They will help you understand what you need to do.
Be sure to save your file as plain text if you are using a word processor. Similarly, 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 be sure to save your XML file as plain text. Do not change the file name from index.xml, and do not edit the HTML file (index.html) that you may generate using our tools; your developerWorks editor will work from the XML version. Save any images, such as photos or screen shots, in the directory you created for your article or tutorial (my-article, in our example).
When editing your article or tutorial, you will need to validate the changes against our schema. If you are new to XML, we suggest validating your file as you go along. It will help you identify the errors more easily.
A tool for validating your XML was installed in your project directory when you created your new article or tutorial. Click the dw-transform.vbs script in your article or tutorial directory. Depending on your Windows settings, this may simply show as dw-transform. You should see a window like Figure 1.
Figure 1. Validating your article with the dw-transform script
Step 3. Correct validation problems
If you happened to make an XML coding error, you will see an error output instead. Using the dw-transform script, you should see a window like Figure 2.
Figure 2. An invalid article (VB script checker)
In this case, we introduced a deliberate error by including
<u>Underline error.</u>. Because
links are underlined, we do not use underlined text for other purposes in
developerWorks articles or tutorials, so.the
<u> and
</u> tags are not permitted by the
schema. The tool will identify the location of the first error and give a
reason for it. The reasons are generated by the MSXML parser. Although
they are somewhat cryptic, they will usually help you locate the problem.
If the reason contains Expecting a, b, br, ... with a long list
of other tag names, you've probably mistyped a tag name or attempted to
use a tag that isn't supported by the developerWorks schema. An editor
that displays line numbers will help you find errors quickly. See Figure 3, where we have marked the
invalid text starting at the offending line and column number.
Figure 3. Locating an error in your XML with Notepad
After you have located and corrected your error, save the file and run dw-transform.vbs again to recheck it. Repeat this process until you have no more errors.
Step 4. Preview your article or tutorial
When you have no errors, you are ready to see a preview of how your article
or tutorial will look on developerWorks. You should have a file called
index.html in your directory. Open this file
with your preferred browser to preview your content. If you are using
Internet Explorer with Windows XP Service Pack 2, you may see a pop-up
window and an information bar advising that Internet Explorer has
restricted the file from showing active content. Click the information bar
and select Allow blocked content... in order to preview
your article or tutorial.
Figure 4. Previewing your article
Notes:
- Some of the stylesheets and some dynamic elements are included by the server, so the formatting in your preview won't appear exactly as it will when generated by the developerWorks staff and published on the server.
- The final published version of a tutorial will be several separate pages, with index.xml being the first page.
Congratulations! You've edited, validated, and previewed your article or tutorial. Now, return to "Authoring with the developerWorks XML templates" for tips on finishing and submitting your content to your developerWorks editor.
Using Linux or another operating system
You will need:
- A text editor or word processor that can save in plain text format.
Although not necessary, you will find it convenient to have an editor
that can display line numbers, because any errors detected in the
validation phase will be reported by line number. Many Linux and
UNIX® editors (including
viandemacs) will display line numbers, either always or as a user option. If your editor can also display column numbers, that will help you even more. - An IBM Developer Kit for Java Version 5.0 or later. If you install from the tarball rather than the RPM, unpack in /opt/ibm. If you do not have root access to your computer, you can unpack the tarball version into a subfolder of the developerworks folder that contains this package. The IBM Runtime Environment for Java 2 (JRE) includes the necessary Xalan and Xerces functions and can be installed alongside other Java implementations. See the Resources section of this article for download links. If you use another Java runtime or developer kit, you may also need the Apache Xalan Version 2.7 or later package (which includes the required Xerces functions) if it is not included with your Java version. You may also need to modify the developerworks/tools/dwxmlxslt.sh script or set a CLASSPATH environment variable.
- The appropriate zenity, gdialog, or kdialog package for your GNOME or KDE desktop if you are using a graphical environment, or the dialog package if you are using a non-graphical environment.
- A graphical browser such as Mozilla, Firefox, or Opera.
Navigate to your new folder and edit your XML file using your favorite text
editor. Follow the detailed comments in the
index.xml file. Be sure to save your file as
plain text if you are using a word processor. Do not change the file name
from index.xml. Save any images, such as photos or screen shots, in the
directory you created for your article or tutorial (my-tutorial, in our
example).
When editing your article or tutorial, you will need to validate the changes against our schema. If you are new to XML, we suggest validating your file as you go along. It will help you identify the errors more easily.
The tool for validating your article or tutorial was installed in your directory when you created your new article or new tutorial. Run the dw-transform.sh script in your directory. If you are running the KDE or GNOME desktops, you may run this from a graphical manager, such as Nautilus or Konqueror; otherwise, you should run the script in a terminal window.
The first time you run the validation script, it searches for a suitable Java version. This may take a few moments. Once a suitable Java executable is found, its path is saved in the tools directory in a file called dwjava.txt. This path is checked first in the future to improve speed. If you remove this file, or if the path in the file is no longer valid, a new search will be performed. If you install the IBM developer kit in a location other than in the /opt, /usr, or developerworks (author package) tree, you can manually edit this file to tell the scripts where to find the Java executable. If you are using version 6 of the IBM developer kit on a 64-bit system and it is installed under /opt, your developerworks/tools/java.txt will look like Listing 1.
Listing 1. Typical dwjava.txt
/opt/ibm/java-x86_64-60/jre/bin/java |
When the script completes, you should see a message box like Figure 5 if all is well.
Figure 5. Validating your tutorial with the dw-transform shell script
Step 3. Correct validation problems
If you happened to make an XML coding error, your message box will show an error similar to Figure 6.
Figure 6. An invalid tutorial (shell script checker)
In this case, we introduced a deliberate error by including
<u>Underline error.</u>. Because
links are underlined, we do not use underlined text for other purposes in
developerWorks articles or tutorials, so the
<u> and
</u> tags are not permitted by the
schema. The tool will identify the location of the first error and give a
reason for it. The reasons are generated by the Java parser. Although they
are somewhat cryptic, they will usually help you locate the problem. If
the reason contains One of '{"" with a long list of other tag
names, you've probably mistyped a tag name or attempted to use a tag that
isn't supported by the developerWorks schema (as in our example here). An
editor that displays line numbers will help you find errors quickly. See
Figure 7, where we have marked the
invalid text starting at the offending line and column number.
Figure 7. Locating an error in your tutorial with the gedit editor
After you have located and corrected your error, save the file and rerun the dw-transform.sh script to recheck your file. Repeat this process until you have no more errors.
Notes:
- Some errors, such as a legitimate opening tag without a matching closing tag, may result in an error without a line number. Validate often.
- If you use tabs to indent your article or tutorial, the column number shown in your editor may not match the column number reported in an error message.
Step 4. Preview your article or tutorial
When you have no more errors, you are ready to see a preview of how your article or tutorial will look on developerWorks. You should have a file called index.html in your directory. Open this file with your preferred browser to preview your article or tutorial.
Figure 8. Previewing your tutorial
Notes:
- Some of the stylesheets and some dynamic elements are included by the server, so the formatting in your preview won't appear exactly as it will when generated by the developerWorks staff and published on the server.
- You may use the left navigation area to navigate between and within sections of you tutorial as the Linux transformation tool produces several html pages similar to those that will be in the final version.
Congratulations! You've edited, validated, and previewed your article or tutorial. Now, return to "Authoring with the developerWorks XML templates" for tips on finishing and submitting your content to your developerWorks editor.
Learn
- "Authoring with the developerWorks XML templates" (developerWorks,
December 2010): Begin your developerWorks authoring experience with our
complete instructions and downloadable authoring package.
- "Authoring
with the developerWorks Word and OpenDocument templates"
(developerWorks, April 2010): If, instead of using the XML templates, you
prefer to compose your content in Microsoft Word or OpenDocument,
we also offer Word and OpenDocument templates for your use.
- "Illustrating your article or tutorial for developerWorks: How to
create effective graphics " (developerWorks, April 2010): Get
detailed guidelines and tips on creating and submitting graphics for your
article or tutorial.
-
developerWorks author guidelines and editorial policy: Learn more
about our editorial policy and peek at each developerWorks editor's
content wish list.
-
developerWorks technical events and webcasts: Stay current on IBM
products and IT topics.
-
Free developerWorks Live! briefings: Get up-to-speed quickly on
IBM products and tools as well as IT industry trends.
-
developerWorks on-demand demos: Watch demos ranging from product
installation and setup demos for beginners, to advanced functionality for
experienced developers.
-
developerWorks on
Twitter: Follow us.
Get products and technologies
-
Microsoft Core XML Services (MSXML) 6.0: To use the
dw-transform.vbs script to transform your article or tutorial, you need
the latest version of the MSXML parser. This is currently version 6. The
file you need is msxml6.msi.
-
IBM Developer Kit
for Java, Version 6: To use the dw-transform.sh script on Linux to
transform your article or tutorial, you need the IBM Developer Kit for
Java, Version 5.0 or later.
-
Apache Xalan: If
you are using the Linux tools (dw-transform.sh) and not using the IBM
Developer Kit for Java, you may need Apache Xalan.
-
Evaluate
IBM products: Download a product trial, try a product online, use
a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented
Architecture efficiently.
Discuss
-
Content submission form: Submit an article or tutorial idea to
developerWorks, and start talking with a developerWorks editor. Check to
see what content is most desired in the content wish
list.
-
developerWorks editor contact info: If you have questions,
contact the editor for the technology or product zone you're interested
in.
-
developerWorks
community: Connect with other developerWorks users while exploring
the developer-driven blogs, forums, groups, and wikis.
Ian Shields works on a multitude of Linux projects for the developerWorks Linux zone. He is a Senior Programmer at IBM at the Research Triangle Park, NC. He joined IBM in Canberra, Australia, as a Systems Engineer in 1973, and has since worked on communications systems and pervasive computing in Montreal, Canada, and RTP, NC. He has several patents and has published several papers. His undergraduate degree is in pure mathematics and philosophy from the Australian National University. He has an M.S. and Ph.D. in computer science from North Carolina State University. Learn more about Ian in in Ian's profile on My developerWorks.
