1OPENJADE(1) OPENJADE(1)
2
6 openjade - apply a DSSSL stylesheet to an SGML or XML document
7
9 openjade [-vCegG2s] [-b encoding] [-f error_file]
10 [-c catalog_sysid] [-D dir] [-a link_type]
11 [-A arch] [-E max_errors] [-i entity]
12 [-w warning_type] [-d dsssl_spec] [-V variable=value]
13 [-t output_type] [-o output_file] [sysid...]
14
18 openjade is an implementation of the ISO/IEC 10179:1996 standard DSSSL
19 language. The DSSSL engine receives as input an SGML or XML document
20 and transforms it into formats like:
21 * XML representation of the flow object tree.
24 * RTF format that can be rendered and printed with Microsoft's free
27 Word Viewer 97
28 * TeX format
31 * MIF format that can be rendered and printed with Framemaker
34 * SGML or XML format. This is used in conjunction with non-standard
37 flow object classes to generate SGML, thus allowing openjade to be used
38 for SGML/XML transformations.
39 The system identifier of the document to be processed is specified as
42 an argument to openjade. If this is omitted, standard input will be
43 read.
44 openjade determines the system identifier for the DSSSL specification
47 as follows:
48 1. If the -d option is specified, it will use the argument as the sys‐
51 tem identifier.
52 2. Otherwise, it will look for processing instructions in the prolog of
55 the document. Two kinds of processing instruction are recognized:
56 <?stylesheet href="sysid" type="text/dsssl">
59 The system data of the processing instruction is parsed like an SGML
62 start-tag. It will be parsed using the reference concrete syntax what‐
63 ever the actual concrete syntax of the document. The name that starts
64 the processing instruction can be either stylesheet, xml-stylesheet or
65 xml:stylesheet. The processing instruction will be ignored unless the
66 value of the type attribute is one of text/dsssl, text/x-dsssl, appli‐
67 cation/dsssl, or application/x-dsssl. The value of href attribute is
68 the system identifier of the DSSSL specification.
69 <?dsssl sysid>
72 The system identifier is the portion of the system data of the process‐
75 ing instruction following the initial name and any whitespace.
76 Although the processing instruction is only recognized in the prolog,
79 it need not occur in the document entity. For example, it could occur
80 in a DTD. The system identifier will be interpreted relative to where
81 the the processing instruction occurs.
82 3. Otherwise, it will use the system identifier of the document with
85 any extension changed to .dsl.
86 A DSSSL specification document can contain more than one style-specifi‐
89 cation. If the system identifier of the DSSSL specification is followed
90 by #id, then openjade will use the style-specification whose unique
91 identifier is id. This is allowed both with the -d option and with the
92 processing instructions.
93 The DSSSL specification must be an SGML document conforming to the
96 DSSSL architecture. For an example, see dsssl/demo.dsl.
97 openjade supports the following options in addition to the normal
100 OpenSP (see onsgmls(1)) options (note that all options are case-sensi‐
101 tive, ie -g and -G are different options):
102 -d dsssl_spec
105 This specifies that dsssl_spec is the system identifier of the
106 DSSSL specification to be used.
107 -G Debug mode. When an error occurs in the evaluation of an expres‐
110 sion, openjade will display a stack trace. Note that this dis‐
111 ables tail-call optimization.
112 -c filename
115 The filename arguments specify catalog files rather than the
116 document entity. The document entity is specified by the first
117 DOCUMENT entry in the catalog files.
118 -s Strict compliance mode. Currently the only effect is that jade
121 doesn't use any predefined character names, sdata-entity map‐
122 pings or name-characters. This is useful for checking that your
123 stylesheet is portable to other DSSSL implementations and that
124 it is strictly compliant to the DSSSL specifications.
125 -t output_type
128 output_type specifies the type of output as follows:
129 fot An XML representation of the flow object tree
131 rtf rtf-95 RTF (used for SGML/XML to RTF transformations) Mi‐
133 crosoft's Rich Text Format. rtf-95 produces output optimized for
134 Word 95 rather than Word 97.
135 tex TeX (used for SGML/XML to TeX transformations)
137 sgml sgml-raw SGML (used for SGML/XML to SGML transformations).
139 sgml-raw doesn't emit linebreaks in tags.
140 xml xml-raw XML (used for SGML/XML to XML transformations). xml-
142 raw doesn't emit linebreaks in tags.
143 html HTML (used for SGML/XML to HTML transformations)
145 mif MIF (used for SGML/XML to MIF transformations)
147 -o output_file
150 Write output to output_file instead of the default. The default
151 filename is the name of the last input file with its extension
152 replaced by the name of the type of output. If there is no input
153 filename, then the extension is added onto jade-out.
154 -V variable
157 This is equivalent to doing (define variable #t) except that
158 this definition will take priority over any definition of vari‐
159 able in a style-sheet.
160 -V variable=value
163 This is equivalent to doing (define variable "value") except
164 that this definition will take priority over any definition of
165 variable in a style-sheet.
166 -V (define variable value)
169 This is equivalent to doing (define variable value) except that
170 this definition will take priority over any definition of vari‐
171 able in a style-sheet. Note that you will probably have to use
172 some escaping mechanism for the spaces to get the entire scheme
173 expression parsed as one cmdline argument.
174 -wtype Control warnings and errors. Multiple -w options are allowed.
177 The following values of type enable warnings:
178 xml Warn about constructs that are not allowed by XML.
180 mixed Warn about mixed content models that do not allow #pcdata
182 anywhere.
183 sgmldecl Warn about various dubious constructions in the SGML
185 declaration.
186 should Warn about various recommendations made in ISO 8879 that
188 the document does not comply with. (Recommendations are
189 expressed with ``should'', as distinct from requirements which
190 are usually expressed with ``shall''.)
191 default Warn about defaulted references.
193 duplicate Warn about duplicate entity declarations.
195 undefined Warn about undefined elements: elements used in the
197 DTD but not defined.
198 unclosed Warn about unclosed start and end-tags.
200 empty Warn about empty start and end-tags.
202 net Warn about net-enabling start-tags and null end-tags.
204 min-tag Warn about minimized start and end-tags. Equivalent to
206 combination of unclosed, empty and net warnings.
207 unused-map Warn about unused short reference maps: maps that are
209 declared with a short reference mapping declaration but never
210 used in a short reference use declaration in the DTD.
211 unused-param Warn about parameter entities that are defined but
213 not used in a DTD. Unused internal parameter entities whose text
214 is INCLUDE or IGNORE won't get the warning.
215 notation-sysid Warn about notations for which no system identi‐
217 fier could be generated.
218 all Warn about conditions that should usually be avoided (in the
220 opinion of the author). Equivalent to: mixed, should, default,
221 undefined, sgmldecl, unused-map, unused-param, empty and
222 unclosed.
223 A warning can be disabled by using its name prefixed with no-.
225 Thus -wall -wno-duplicate will enable all warnings except those
226 about duplicate entity declarations.
227 The following values for warning_type disable errors:
229 no-idref Do not give an error for an ID reference value which no
231 element has as its ID. The effect will be as if each attribute
232 declared as an ID reference value had been declared as a name.
233 no-significant Do not give an error when a character that is not
235 a significant character in the reference concrete syntax occurs
236 in a literal in the SGML declaration. This may be useful in con‐
237 junction with certain buggy test suites.
238 no-valid Do not require the document to be type-valid. This has
240 the effect of changing the SGML declaration to specify VALIDITY
241 NOASSERT and IMPLYDEF ATTLIST YES ELEMENT YES. An option of
242 -wvalid has the effect of changing the SGML declaration to spec‐
243 ify VALIDITY TYPE and IMPLYDEF ATTLIST NO ELEMENT NO. If neither
244 -wvalid nor -wno-valid are specified, then the VALIDITY and
245 IMPLYDEF specified in the SGML declaration will be used.
246
249 OpenJade ignores the SP_CHARSET_FIXED and SP_SYSTEM_CHARSET environment
250 variables and always uses Unicode as its internal character set, as if
251 SP_CHARSET_FIXED was 1 and SP_SYSTEM_CHARSET was unset. Thus only the
252 SP_ENCODING environment variable is relevant to OpenJade's handling of
253 character sets.
254
257 The following external procedures are available. These external proce‐
258 dures are defined by a prototype in the same manner as in the standard.
259 To use one of these external procedures, you must make use of the stan‐
260 dard external-procedure procedure, using a public identifier of "UNREG‐
261 ISTERED::James Clark//Procedure::name" where name is the name given
262 here, typically by including the following in the DSSSL specification:
263 (define name (external-procedure "UNREGISTERED::James Clark//Proce‐
266 dure::name"))
267 Note that external-procedure returns #f if it doesn't know about the
270 specified public identifier. You can use this to enable your DSSSL
271 specifications to work gracefully with other implementations which do
272 not support these extensions.
273 For external procedures added by the OpenJade team, use a public iden‐
276 tifier of the form "UNREGISTERED::OpenJade//Procedure::name".
277 An easy way to get access to all external procedures is to use the
280 style specification dsssl/extensions.dsl#procedures. The file
281 dsssl/extensions.dsl also contains style specifications which make the
282 nonstandard flow object classes and inherited characteristics supported
283 by the backends available in a convenient way.
284 Debugging
287 (debug obj)
290 Generates a message including the value of obj and then returns obj.
293 Simple-page-sequence header/footer control
296 (if-first-page sosofo1 sosofo2)
299 This can be used only in the specification of the value of one of the
302 header/footer characteristics of simple-page-sequence. It returns a
303 sosofo that will display as sosofo1 if the page is the first page of
304 the simple-page-sequence and as sosofo2 otherwise.
305 (if-front-page sosofo1 sosofo2)
308 This can be used only in the specification of the value of one of the
311 header/footer characteristics of simple-page-sequence. It returns a
312 sosofo that will display as sosofo1 if the page is a front (ie recto,
313 odd-numbered) page and as sosofo2 if it is a back (ie verso, even-num‐
314 bered) page.
315 Numbering
318 (all-element-number)
321 (all-element-number osnl)
324 This is the same as element-number except it counts elements with any
327 generic identifier. If osnl is not an element returns #f, otherwise
328 returns 1 plus the number of elements that started before osnl. This
329 provides an efficient way of creating a unique identifier for any ele‐
330 ment in a document.
331 External entity access
334 (read-entity string)
337 This returns a string containing the contents of the external entity
340 with system identifier string. This should be used only for textual
341 entities (CDATA and SDATA), and not for binary entities (NDATA).
342 POSIX locale access
345 (language lang country)
348 This procedure returns an object of type language, if the system sup‐
351 ports the specified language. lang is a string or symbol giving the two
352 letter language code. country is a string or symbol giving the two let‐
353 ter country code.
354 This procedure uses POSIX locales. It is an OpenJade addition. It is
357 not supported on all operating systems.
358 Extended standard procedures
361 (sgml-parse sysid #!key active: parent: architecture:)
364 This allows you to specify an SGML architecture with respect to which
367 the document should be parsed. It is an OpenJade addition.
368 (expt q k)
371 This allows you to raise a quantity to an integral power. It is an
374 OpenJade addition.
375
378 This section describes the limitations of the front-end (the general-
379 purpose DSSSL engine); each backend also has its own limitations.
380 openjade doesn't allow internal definitions at the beginning of bodies
383 and the (test => recipient) variant of cond clauses.
384 openjade supports only a single, fixed grove plan which comprises the
387 following modules:
388 * baseabs
391 * prlgabs0
394 * prlgabs1
397 * instabs
400 * basesds0
403 * instsds0
406 * subdcabs
409 It doesn't implement the following parts of SDQL: HyTime support, aux‐
412 iliary parsing, node regular expressions.
413 Query rules, sosofo synchronization, indirect sosofos, reference val‐
416 ues, decoration areas and font properties are not supported.
417 Note that only inherited characteristics that are applicable to some
420 supported flow object can be specified.
421 Character/glyph handling
424 It only supports a single pre-defined character repertoire. A character
427 name of the form U-XXXX where XXXX are four upper-case hexadecimal dig‐
428 its, is recognized as referring to the Unicode character with that
429 code. For many characters, it is also possible to use the ISO/IEC 10646
430 name in lower-case with words separated by hyphens.
431 Some common SDATA entity names from the ISO entity sets are recognized
434 and mapped to characters. In addition an SDATA entity name of the form
435 U-XXXX, where XXXX are four upper-case hexadecimal digits, is mapped to
436 the Unicode character with that code.
437 OpenJade now supports the standard-chars, map-sdata-entity, add-name-
440 chars, add-separator-chars and char-repertoire declaration element
441 forms, allowing a style-sheet to define additional character names,
442 sdata entity mappings, name characters (i.e. characters allowed in
443 identifiers) and separator characters. Currently the only recognized
444 character repertoire is the built-in repertoire. It has the public
445 identifier "UNREGISTERED::OpenJade//Character Repertoire::OpenJade".
446 Validation
449 Several things that it would be desirable to have checked aren't
452 checked:
453 * When the allowed value of an inherited characteristic is a symbol,
456 OpenJade checks only that the value is a symbol that is allowed as the
457 value of some characteristic; #t and #f are treated as a special kind
458 of symbol in this case.
459 * OpenJade doesn't check whether a flow object is occurring in a con‐
462 text where it is allowed.
463 * OpenJade does not prevent flow objects being attached to the princi‐
466 pal port of a flow object when the flow object shouldn't have a princi‐
467 pal port.
468 * Most type-checking is done at run-time not compile-time.
471 * OpenJade does not check for non-inherited characteristics that are
474 required to be specified.
475 * It doesn't check that optional features that have been used were
478 declared in the features form.
479 Other limitations
482 The following primitives are just stubs:
485 char-script-case Always returns last argument.
488 address-visited? Always returns #f.
491
494 Given an SGML file file.sgml, use the stylesheet file.dsl and publish
495 as an rtf file.
496 openjade -t rtf file.sgml
499 Using a different stylesheet:
502 openjade -t rtf -d docbook.dsl file.sgml
505 Using the print style specification contained within the stylesheet
508 openjade -t rtf -d docbook.dsl#print file.sgml
511 And use the html specification within the style sheet to convert to
514 html
515 openjade -t sgml -i html -d docbook.dsl#html file.sgml
518
521 onsgmls(1)
522
525 James Clark, Ian Castle <ian.castle@looksystems.co.uk>.
526OpenJade January 2002 OPENJADE(1)