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.
- Either Version 4 or Version 6 of Microsoft's XML Parser (MSXML). (To get the parser, see the Resources section of this article for a link.) Windows Vista users should use MSXML Version 6, which is included with the operating system.
- Internet Explorer Version 6 or 7, 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 as 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.
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 on 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 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, but the Windows preview shows the tutorial on a single page. On this single page, you can see where each new section begins. However, cross-links in the left navigation area and body of the tutorial do not work in the preview. The developerWorks staff will correct the pagination and linking.
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. - 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. 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.
After a few moments, 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.
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 are included by the server and 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, March 2009): Begin your developerWorks authoring
experience with our complete instructions and downloadable authoring
package.
-
"Authoring with
the developerWorks Word and Writer templates"
(developerWorks, March 2009): If, instead of using the XML templates, you
prefer to compose your content in Microsoft Word or OpenOffice.org Writer,
we also offer Word and Writer templates for your use.
-
"Illustrating your
article or tutorial for developerWorks: How to create effective graphics
"
(developerWorks, July 2008): 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.
Get products and technologies
- Microsoft's XML
Parser (MSXML)
Version 4
or
Version 6:
To use the dw-transform.vbs script to transform your article or tutorial,
you need either version 4 or version 6 of the MSXML parser. The file you
need is msxml.msi (version 4) or msxml6.msi (version 6).
-
IBM Developer Kit for Java,
Version 5.0:
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.
-
XML Copy Editor
is a fast, free, validating XML editor that can validate and transform
your XML files.
-
IBM trial
products for download:
Build your next development project with IBM trial software, available for
download directly from developerWorks.
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.
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. 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.
Comments (Undergoing maintenance)
Table of contents
Next steps from IBM
With the no-charge DB2 Express-C, pureXML, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.
- Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data.
- Article: See how DB2 pureXML schema capabilities can evolve schemas without making any changes to your applications.
- Tutorial: This tutorial shows you how to use DB2's pureXML to expose the native XML capabilities of DB2.
- Buy: DB2 9 for Linux, UNIX and Windows
My developerWorks community
Tags
Use the slider bar to see more or fewer tags.
Popular tags shows the top tags for this particular content zone (for example, Java technology, Linux, WebSphere).
My tags shows your tags for this particular content zone (for example, Java technology, Linux, WebSphere).
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
