Working XML: Fundamentals of Web publishing with XML
By Benoit Marchal2004-06-28
Enhancing the site
|
|
As you have seen in the previous section, the project wizard creates a sample site. The next step is to populate the src directory and enhance the stylesheets. If you adopt a popular vocabulary, such as DocBook, you can find pre-existing stylesheets that should speed up the process.
XML editors
Migration
If you are migrating from another publishing tool, it might not be possible to convert your content to XML overnight. Don't worry -- the plug-in publishes any HTML file that appears in the src directory, so you can convert to XML gradually.
Since you have to edit many XML documents, it pays to invest in a good XML editor. Your options are:
• A text editor, such as Eclipse. Text editors are appropriate for small corrections, but they are too cumbersome for serious editing.
• A pseudo-WYSIWYG XML editor such as XMetaL or XMLMind. These editors emulate a word processor and are ideal for serious editing.
• An RTF converter. These work with your word processor to generate XML and are perfect when you collect documents from many different authors who may not be familiar with XML.
Which option is best depends on the job at hand. I find it nearly impossible to write long documents with a text editor. Having to remember to balance open and close tags is a huge drag on my productivity. Most authors are uncomfortable with text editors for anything but the most basic corrections.
Pseudo-WYSIWYG editors offer the most comfortable environment and the author doesn't need to worry about the XML syntax (see Figure 3). They are called "pseudo-WYSIWYG" because they use color, boldness, and other typographic attributes to emulate a word processor with XML content. If you have never tried a pseudo-WYSIWYG editor, do yourself a favour and download an evaluation version right away. Be warned that the editors don't work right out of the box -- they must be customized for a given vocabulary. Fortunately, most editors ship with native support for DocBook -- another reason to adopt this popular vocabulary.
The last solution is to stick with your word processor and use an RTF converter to generate the XML document. In practice, you might find that the conversions are seldom trouble-free, but it's a good solution if you collect documents from authors who are not familiar with XML. At Pineapplesoft, we maintain community Web sites where many authors contribute to the sites, and we use converters extensively.
Figure 3. A pseudo-WYSIWYG editor
Hyperlinks and URLs
As a bonus, the XM plug-in for Eclipse manages hyperlinks to prevent broken links. The plug-in works with so-called relative URLs (URLs that give the path relative to the current file). Listing 1 shows a relative URL example.
Listing 1. Relative URL
about.xml
photos/index.xml
../images/logo.gif
Absolute URLs, on the other end, either include a host name or give the path from the root of the Web site. Listing 2 shows an absolute URL example.
Listing 2. Absolute URL
/photos/index.xml
http://www.ananas.org/
http://www.ibm.com/developerWorks
You should use relative hyperlinks as much as possible because the XM plug-in:
• Updates the file extension if needed, changing from .xml to .html wherever necessary
• Tests the link and issue a warning if it's broken
Error messages and troubleshooting
The plug-in reports problems with your XML documents or your stylesheets in the XM console. If you don't see the console, select XM Console from the Window > Show View menu. Read the error message carefully because it includes a description of the problem. The plug-in also lists the file and line where the error occurred (though it might be off by a line or two, so make sure to review the lines before and after the problem as well).
If the plug-in generates blank Web pages:
• Read error messages in the XM console carefully
• Make sure that the corresponding XML document is not empty
• Check that your stylesheet is appropriate for the document vocabulary, paying special attention to namespace
When something looks really weird, double-check the namespaces and the element names. Namespace mismatches account for 25 percent of all my students' problems.
Eclipse tips
I conclude with a few tips on the XM plug-in.
Select Preferences from the Window menu. Under the Workbench category, choose the File Associations entry and associate an editor with *.xml and *.xsl files. You can associate one of the many Eclipse text editors or use an external editor (such as XMLMind). When you double-click the file, it automatically opens the editor.
To choose the editor when you open the file, right-click it in the navigator and choose the Open with menu.
Eclipse automatically generates the Web site when you save a document from within Eclipse. If you are using an external editor, such as XMLMind, select Rebuild Project from the Project menu. If the menu is grayed, click on the project in the navigator first.
The XM plug-in does not recognize changes to the stylesheets when it rebuilds the Web site. If it looks like the plug-in is ignoring your changes, follow these steps:
1. Right-click on the project name in the navigator (mysite in the above example), then choose Properties.
2. Select XM Properties and make sure that "Run XM" performs a build is checked (see Figure 4).
3. Click OK.
4. Right-click on the project again, then choose "Run XM".
Figure 4. Edit the properties
Tutorial Pages:
» Fundamentals of Web publishing with XML
» Getting started
» Enhancing the site
» Moving forward
First published by IBM developerWorks
|
