1OPENJADE(1)                                                        OPENJADE(1)
2
3
4

NAME

6       openjade - apply a DSSSL stylesheet to an SGML or XML document
7

SYNOPSIS

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
15
16

DESCRIPTION

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
22
23       * XML representation of the flow object tree.
24
25
26       *  RTF  format  that  can be rendered and printed with Microsoft's free
27       Word Viewer 97
28
29
30       * TeX format
31
32
33       * MIF format that can be rendered and printed with Framemaker
34
35
36       * 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
40
41       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
45
46       openjade determines the system identifier for the  DSSSL  specification
47       as follows:
48
49
50       1.  If the -d option is specified, it will use the argument as the sys‐
51       tem identifier.
52
53
54       2. Otherwise, it will look for processing instructions in the prolog of
55       the document. Two kinds of processing instruction are recognized:
56
57
58       <?stylesheet href="sysid" type="text/dsssl">
59
60
61       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
70
71       <?dsssl sysid>
72
73
74       The system identifier is the portion of the system data of the process‐
75       ing instruction following the initial name and any whitespace.
76
77
78       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
83
84       3. Otherwise, it will use the system identifier of  the  document  with
85       any extension changed to .dsl.
86
87
88       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
94
95       The  DSSSL  specification  must  be  an SGML document conforming to the
96       DSSSL architecture. For an example, see dsssl/demo.dsl.
97
98
99       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
103
104       -d dsssl_spec
105              This specifies that dsssl_spec is the system identifier  of  the
106              DSSSL specification to be used.
107
108
109       -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
113
114       -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
119
120       -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
126
127       -t output_type
128              output_type specifies the type of output as follows:
129
130              fot  An XML representation of the flow object tree
131
132              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
136              tex TeX (used for SGML/XML to TeX transformations)
137
138              sgml  sgml-raw SGML (used for SGML/XML to SGML transformations).
139              sgml-raw doesn't emit linebreaks in tags.
140
141              xml xml-raw XML (used for SGML/XML to XML transformations). xml-
142              raw doesn't emit linebreaks in tags.
143
144              html  HTML (used for SGML/XML to HTML transformations)
145
146              mif MIF (used for SGML/XML to MIF transformations)
147
148
149       -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
155
156       -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
161
162       -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
167
168       -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
175
176       -wtype Control warnings and errors. Multiple -w  options  are  allowed.
177              The following values of type enable warnings:
178
179              xml Warn about constructs that are not allowed by XML.
180
181              mixed  Warn about mixed content models that do not allow #pcdata
182              anywhere.
183
184              sgmldecl Warn about various dubious constructions  in  the  SGML
185              declaration.
186
187              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
192              default Warn about defaulted references.
193
194              duplicate Warn about duplicate entity declarations.
195
196              undefined Warn about undefined elements: elements  used  in  the
197              DTD but not defined.
198
199              unclosed Warn about unclosed start and end-tags.
200
201              empty Warn about empty start and end-tags.
202
203              net Warn about net-enabling start-tags and null end-tags.
204
205              min-tag  Warn  about minimized start and end-tags. Equivalent to
206              combination of unclosed, empty and net warnings.
207
208              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
212              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
216              notation-sysid Warn about notations for which no system  identi‐
217              fier could be generated.
218
219              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
224              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
228              The following values for warning_type disable errors:
229
230              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
234              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
239              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
247

ENVIRONMENT

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
255

OPENJADE EXTENSIONS

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
264
265       (define  name  (external-procedure  "UNREGISTERED::James  Clark//Proce‐
266       dure::name"))
267
268
269       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
274
275       For external procedures added by the OpenJade team, use a public  iden‐
276       tifier of the form "UNREGISTERED::OpenJade//Procedure::name".
277
278
279       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
285
286       Debugging
287
288
289       (debug obj)
290
291
292       Generates a message including the value of obj and then returns obj.
293
294
295       Simple-page-sequence header/footer control
296
297
298       (if-first-page sosofo1 sosofo2)
299
300
301       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
306
307       (if-front-page sosofo1 sosofo2)
308
309
310       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
316
317       Numbering
318
319
320       (all-element-number)
321
322
323       (all-element-number osnl)
324
325
326       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
332
333       External entity access
334
335
336       (read-entity string)
337
338
339       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
343
344       POSIX locale access
345
346
347       (language lang country)
348
349
350       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
355
356       This  procedure  uses  POSIX locales. It is an OpenJade addition. It is
357       not supported on all operating systems.
358
359
360       Extended standard procedures
361
362
363       (sgml-parse sysid #!key active: parent: architecture:)
364
365
366       This allows you to specify an SGML architecture with respect  to  which
367       the document should be parsed. It is an OpenJade addition.
368
369
370       (expt q k)
371
372
373       This  allows  you  to  raise  a quantity to an integral power. It is an
374       OpenJade addition.
375
376

LIMITATIONS

378       This section describes the limitations of the front-end  (the  general-
379       purpose DSSSL engine); each backend also has its own limitations.
380
381
382       openjade  doesn't allow internal definitions at the beginning of bodies
383       and the (test => recipient) variant of cond clauses.
384
385
386       openjade supports only a single, fixed grove plan which  comprises  the
387       following modules:
388
389
390       * baseabs
391
392
393       * prlgabs0
394
395
396       * prlgabs1
397
398
399       * instabs
400
401
402       * basesds0
403
404
405       * instsds0
406
407
408       * subdcabs
409
410
411       It  doesn't implement the following parts of SDQL: HyTime support, aux‐
412       iliary parsing, node regular expressions.
413
414
415       Query rules, sosofo synchronization, indirect sosofos,  reference  val‐
416       ues, decoration areas and font properties are not supported.
417
418
419       Note  that  only  inherited characteristics that are applicable to some
420       supported flow object can be specified.
421
422
423       Character/glyph handling
424
425
426       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
432
433       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
438
439       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
447
448       Validation
449
450
451       Several  things  that  it  would  be  desirable  to have checked aren't
452       checked:
453
454
455       * 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
460
461       *  OpenJade  doesn't check whether a flow object is occurring in a con‐
462       text where it is allowed.
463
464
465       * 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
469
470       * Most type-checking is done at run-time not compile-time.
471
472
473       * OpenJade does not check for non-inherited  characteristics  that  are
474       required to be specified.
475
476
477       *  It  doesn't  check  that  optional features that have been used were
478       declared in the features form.
479
480
481       Other limitations
482
483
484       The following primitives are just stubs:
485
486
487       char-script-case Always returns last argument.
488
489
490       address-visited? Always returns #f.
491
492

EXAMPLES

494       Given an SGML file file.sgml, use the stylesheet file.dsl  and  publish
495       as an rtf file.
496
497
498       openjade -t rtf file.sgml
499
500
501       Using a different stylesheet:
502
503
504       openjade -t rtf -d docbook.dsl file.sgml
505
506
507       Using the print style specification contained within the stylesheet
508
509
510       openjade -t rtf -d docbook.dsl#print file.sgml
511
512
513       And  use  the  html  specification within the style sheet to convert to
514       html
515
516
517       openjade -t sgml -i html -d docbook.dsl#html file.sgml
518
519

SEE ALSO

521       onsgmls(1)
522
523

AUTHORS

525       James Clark, Ian Castle <ian.castle@looksystems.co.uk>.
526
527
528
529OpenJade                         January 2002                      OPENJADE(1)
Impressum