Running jade
jade is, as you probably gathered from Figure 19.1, a command-line program; it doesn't have any user interface with menus and dialog boxes to enter all the parameters.
Before running jade, you should copy the catalog file (supplied in the jade distribution) and edit the entries to reflect the location of the jade support files on your computer.
If any of the SGML or XML files that you will be processing reference a DTD by means of a PUBLIC identifier, you will also have to add an entry for each of them. An example of a modified catalog file is shown in Listing 19.1.
Listing 19.1 A Sample catalog File for jade
1: PUBLIC "-//James Clark//DTD DSSSL Flow Object Tree//EN" 2: "d:\jade\fot.dtd" 3: PUBLIC "ISO/IEC 10179:1996//DTD DSSSL Architecture//EN" 4: "d:\jade\dsssl.dtd" 5: PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" 6: "d:\jade\style-sheet.dtd" 7: PUBLIC "-//IETF//DTD HTML Strict//EN" "d:\jade\html-s.dtd" 8: PUBLIC "-//W3C//DTD HTML 3.2//EN" "d:\jade\html32.dtd" 9: PUBLIC "ISO 8879-1986//ENTITIES Added Latin 1//EN//HTML" 10: "d:\jade\ISOLat1.sgm" 11: PUBLIC "-//Free Text Project//DTD Play//EN" 12: "d:\jade\work\play.dtd"
| The first three lines of the catalog file are essential; without these lines jade simply won't output anything but a long list of errors. The other lines are all optional-one for each PUBLIC DTD declaration you will encounter (this saves you the trouble of having to edit every file to change the document type declaration into a SYSTEM identifier). |
|
The following are some typical commands you will need for running jade:
This command converts an HTML file into RTF (Microsoft Word 97):
jade -f error.log -t rtf -d html32hc.dsl -o simon.rtf simon.html
The DSSSL style sheet html32hc.dsl is distributed with jade, and is a good style sheet for general purpose HTML to RTF conversion. It even adds a table of contents to the RTF file (to update the page number entries, press Control + End, press Control + A, and then press F9).
This command converts an XML file into MIF (FrameMaker Interchange Format):
jade -f error.log -t mif -wxml -d simon.dsl -o simon.rtf simon.xml
Note the additional -wxml parameter. Jade is really designed to work with SGML files and it will complain about the missing tag minimization characters in the XML DTD if you don't use this parameter. Generally, these errors are just a nuisance and can be ignored but it is better to be safe than sorry. This parameter only applies if the XML document is valid (there is an SGML parser hidden inside jade). If your XML document is only well-formed and not necessarily valid, or if you just want to skip the validation step, use the -wno-valid parameter instead.
This command converts an XML file into HTML:
jade -f error.log -t sgml -wno-valid -d simon.dsl simon.xml > simon.html
Note that this time you will have to pipe the output (using the > character) to the output file.
This command converts an HTML file into XML:
jade -f error.log -t xml -d simon.dsl simon.html > simon.xml
Now that you've got the basics of the jade command line, let's look at the official meanings of these command-line parameters (these are also explained in the jade documentation):
- • -c catalog_file-An alternative to copying the catalog file (described earlier) to the directory in which you are going to run jade is to specify the path to the catalog file with this parameter.
- • -d dsssl_spec-This parameter gives the path to the DSSSL style specification (style sheet) to be used.
| Officially the file that contains the DSSSL formatting instructions is a style sheet that contains one or more DSSSL style specifications. In jade the style sheet is actually an SGML document that conforms to the style sheet DTD. |
To avoid confusing you with too many terms, I'm simply going to use the term DSSSL style sheet throughout the rest of this chapter. Our style sheets will only contain one style specification and, because the DTD allows all of the element start and end tags in a style sheet to be omitted, you won't ever have to worry about the difference.
- • -f log_file-This parameter gives the name of the file to which error messages are to be written.
- • -G-This switch enables debug mode. When an error occurs in the evaluation of an expression, jade displays a stack trace. You will probably find this doesn't help much until you've gained quite a bit of experience using jade. (There are also some more powerful DSSSL debugging functions on the Web that will give you much more useful information.)
-
• -t output_type-This parameter specifies the type of output to be created, where output_type is one of the following keywords:
- fot-An XML representation of the flow object tree.
- Rtf or rtf-95: Microsoft's Rich Text Format-rtf-95 produces output optimized for Word 95 rather than Word 97.
- tex-TeX.
- sgml-SGML (used for SGML-SGML transformations).
- xml-XML (used for SGML-to-XML transformations).
- • -o output_file-This parameter tells jade to write its output to the named output_file instead of the default. The default filename is the name of the last input file with its extension replaced by the name of the type of output (rtf, mif, and so on). If there is no input filename, the extension is added onto the name jade-out.
- • -V variable-This parameter allows you to set the value of the named variable to true. For example, in the DSSSL style sheet that accompanies Jon Bosak's distribution of Shakespeare's plays in XML form (you can download these for free from http://www.hypermedic.com/style/shakespeare/index.htm) you can specify -V fm to toggle the display of the front matter (the fm element); this content is normally skipped.
- • -w-This parameter allows you to specify some XML processing options:
-wxml switches jade to XML processing mode.
-wno-valid tells jade that the XML document doesn't have to be valid (the document always has to be well-formed).