# OpenJade

## Contents

- What is OpenJade?
- Copyright
- Getting OpenJade
- Building OpenJade
- Installing OpenJade
- Using OpenJade
- OpenJade Extensions
- Current OpenJade Limitations
- New additions to previous versions
- Experimental DSSSL extensions
- Backends
  - RTF
  - XML Flow Object Tree
  - TeX
  - MIF
  - SGML Transformation
- About OpenJade sources
- Reporting bugs in OpenJade
- OpenJade contributors

## What is OpenJade?

OpenJade is an implementation of the ISO/IEC 10179:1996 standard DSSSL language. It is based on the James Clark implementation of DSSSL named Jade. OpenJade is now developed and maintained by the OpenJade team. The current version is 1.4.

For general information about DSSSL, see the OpenJade home page. The OpenJade home page contains useful resources such as links to articles, tutorials, libraries, etc.

Another site with lots of in-depth information about DSSSL is that of Mulberry Technologies. Among other things, it hosts the DSSSL Users mailing list.

OpenJade is a command line application and a set of components. The DSSSL engine receives as input an SGML or XML document and transforms it into formats like:

- XML representation of the flow object tree.
- RTF format that can be rendered and printed with Microsoft's free Word Viewer 97
- TeX format
- MIF format that can be rendered and printed with Framemaker
- SGML or XML format. This is used in conjunction with non-standard flow object classes to generate SGML, thus allowing OpenJade to be used for SGML/XML transformations.

Back to top

## Copyright

OpenJade is licensed with almost no restrictions even for commercial use (see license terms).

If you do use OpenJade in a commercial product, we ask you, as a courtesy, to acknowledge the use of OpenJade.

Back to top

## Building OpenJade

### Win32

Only Microsoft Visual C++ 6.0 is supported. Also, Perl 5 is required; the executable must be on your PATH.

To build on the command line, ensure that the directories containing `msdev` and `nmake` are in your path, typically by executing the command:

    path C:/Program Files/Microsoft Visual Studio/Common/MSDev98/Bin;
        C:/Program Files/Microsoft Visual Studio/VC98/Bin;%path%

(all in one long line) then run the command:

    build-win32.bat

To build using the Visual Studio GUI, open the workspace `jade.dsw` and build the `Win32 Release` configuration of the `all` project. You must first do a command-line build, however, to get the perl-generated files.

### Unix

Use the autoconf support.

Back to top

## Installing OpenJade

### Win32

OpenJade requires the file `dsssl/builtins.dsl` to operate. You can tell OpenJade where this file is in one of two ways:

- By including a SYSTEM catalog entry for "builtins.dsl" pointing to this file. See `dsssl/catalog` for an example.
- By including the `dsssl/catalog` catalog with the `-c` command line option or the `SGML_CATALOG_FILES` environment variable.

### Unix

Run

    make install

as `root`.

Back to top

## Using OpenJade

Add the directory containing the OpenJade binary to your path, change directory to the dsssl directory, and do

    openjade demo.sgm

If everything is working, there should be a well-formed XML file `demo.fot` created.

The system identifier of the document to be processed is specified as an argument to OpenJade. If this is omitted, standard input will be read.

OpenJade determines the system identifier for the DSSSL specification as follows:

1. If the `-d` option is specified, it will use the argument as the system identifier.
2. Otherwise, it will look for processing instructions in the prolog of the document. Two kinds of processing instruction are recognized:
   `<?stylesheet href="sysid" type="text/dsssl">`
     The system data of the processing instruction is parsed like an SGML start-tag. It will be parsed using the reference concrete syntax whatever the actual concrete syntax of the document. The name that starts the processing instruction can be either `stylesheet`, `xml-stylesheet` or `xml:stylesheet`. The processing instruction will be ignored unless the value of the `type` attribute is one of `text/dsssl`, `text/x-dsssl`, `application/dsssl`, or `application/x-dsssl`. It is also ignored if the selected backend is not suitable for one of the media types listed as the value of the `media` attribute. OpenJade recognizes the media types "print" (FOT, RTF, TeX and MIF backends) and "screen" (FOT and HTML backends). See the HTML4.0 specification for a list of valid media types. The value of `href` attribute is the system identifier of the DSSSL specification. If there are multiple processing instructions in the prolog, OpenJade selects one according to the mechanism described in the HTML4.0 specification, taking the values of the `alternate` and `title` attributes into account.
   `<?dsssl` `sysid``>`
     The system identifier is the portion of the system data of the processing instruction following the initial name and any whitespace.

   Although the processing instruction is only recognized in the prolog, it need not occur in the document entity. For example, it could occur in a DTD. The system identifier will be interpreted relative to where the the processing instruction occurs.

3. Otherwise, it will use the system identifier of the document with any extension changed to `.dsl`.

A DSSSL specification document can contain more than one style-specification. If the system identifier of the DSSSL specification is followed by `#``id`, then OpenJade will use the style-specification whose unique identifier is `id`. This is allowed both with the `-d` option and with the processing instructions.

The DSSSL specification must be an SGML document conforming to the DSSSL architecture. For an example, see `dsssl/demo.dsl`.

OpenJade supports the following options in addition to the normal SP options (note that all options are case-sensitive, ie `-g` and `-G` are different options):

`-h`, `--help`
  Display a help message and exit.
`-v`, `--version`
  Show the version number.
`-d` sysid, `--specification=`sysid
  This specifies that sysid is the system identifier of the DSSSL specification to be used.
`-T` name, `--spec-title=`name
  This specifies that name is the title of the processing instruction to be used in determining the applicable DSSSL specification.
`-G`, `--debug`
  Debug mode. When an error occurs in the evaluation of an expression, OpenJade will display a stack trace. Note that this disables tail-call optimization.
`-c` sysid, `--catalog=`sysid
  Use catalog sysid.
`-C`, `--catalogs`
  The arguments specify catalog files rather than the document entity. The document entity is specified by the first `DOCUMENT` entry in the catalog files.
`-s`, `--strict`
  Strict compliance mode. Currently the only effect is that jade doesn't use any predefined character names, sdata-entity mappings or name-characters. This is useful for checking that your stylesheet is portable to other DSSSL implementations and that it is strictly compliant to the DSSSL specifications.
`-t` type, `--output-type=`type
  type specifies the type of output as follows:
  `fot`
    An XML representation of the flow object tree
  `rtf` `rtf-95`
    RTF (used for SGML/XML to RTF transformations)
    Microsoft's Rich Text Format. `rtf-95` produces output optimized for Word 95 rather than Word 97.
  `tex`
    TeX (used for SGML/XML to TeX transformations)
  `sgml` `sgml-raw`
    SGML (used for SGML/XML to SGML transformations). `sgml-raw` doesn't emit linebreaks in tags.
  `xml` `xml-raw`
    XML (used for SGML/XML to XML transformations). `xml-raw` doesn't emit linebreaks in tags.
  html
    HTML (used for SGML/XML to HTML transformations)
  `mif`
    MIF (used for SGML/XML to MIF transformations)
`-o` file, `--output-file=`file
  Write output to 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. If there is no input filename, then the extension is added onto jade-out.
`-V` variable, `--define=`variable
  This is equivalent to doing `(define variable #t)` except that this definition will take priority over any definition of variable in a style-sheet.
`-V` variable=value, `--define=`variable=value
  This is equivalent to doing `(define variable "value")` except that this definition will take priority over any definition of variable in a style-sheet.
`-V` (define variable value), `--define=`(define variable value)
  This is equivalent to doing `(define variable value)` except that this definition will take priority over any definition of variable in a style-sheet. Note that you will probably have to use some escaping mechanism for the spaces to get the entire scheme expression parsed as one cmdline argument.
`-2`
  Enable experimental DSSSL extensions.
`-w` type, `--warning=`type (examples: wxml, wmixed, wsgmldecl, etc.)
  Control warnings and errors. Multiple `-w` options are allowed. The following values of `type` enable warnings:
  `xml`
    Warn about constructs that are not allowed by XML.
  `mixed`
    Warn about mixed content models that do not allow #pcdata anywhere.
  `sgmldecl`
    Warn about various dubious constructions in the SGML declaration.
  `should`
    Warn about various recommendations made in ISO 8879 that the document does not comply with. (Recommendations are expressed with ``should'', as distinct from requirements which are usually expressed with ``shall''.)
  `default`
    Warn about defaulted references.
  `duplicate`
    Warn about duplicate entity declarations.
  `undefined`
    Warn about undefined elements: elements used in the DTD but not defined.
  `unclosed`
    Warn about unclosed start and end-tags.
  `empty`
    Warn about empty start and end-tags.
  `net`
    Warn about net-enabling start-tags and null end-tags.
  `min-tag`
    Warn about minimized start and end-tags. Equivalent to combination of `unclosed`, `empty` and `net` warnings.
  `unused-map`
    Warn about unused short reference maps: maps that are declared with a short reference mapping declaration but never used in a short reference use declaration in the DTD.
  `unused-param`
    Warn about parameter entities that are defined but not used in a DTD. Unused internal parameter entities whose text is `INCLUDE` or `IGNORE` won't get the warning.
  `notation-sysid`
    Warn about notations for which no system identifier could be generated.
  `all`
    Warn about conditions that should usually be avoided (in the opinion of the author). Equivalent to: `mixed`, `should`, `default`, `undefined`, `sgmldecl`, `unused-map`, `unused-param`, `empty` and `unclosed`.

  A warning can be disabled by using its name prefixed with `no-`. Thus `-wall -wno-duplicate` will enable all warnings except those about duplicate entity declarations.

  The following values for `warning_type` disable errors:

  `no-idref`
    Do not give an error for an ID reference value which no element has as its ID. The effect will be as if each attribute declared as an ID reference value had been declared as a name.
  `no-significant`
    Do not give an error when a character that is not a significant character in the reference concrete syntax occurs in a literal in the SGML declaration. This may be useful in conjunction with certain buggy test suites.
  `no-valid`
    Do not require the document to be type-valid. This has the effect of changing the SGML declaration to specify `VALIDITY NOASSERT` and `IMPLYDEF ATTLIST YES ELEMENT YES`. An option of `-wvalid` has the effect of changing the SGML declaration to specify `VALIDITY TYPE` and `IMPLYDEF ATTLIST NO ELEMENT NO`. If neither `-wvalid` nor `-wno-valid` are specified, then the `VALIDITY` and `IMPLYDEF` specified in the SGML declaration will be used.

The following options are the same as their unprefixed SP counterparts, but apply only to the SGML parser used for the document or stylesheet, respectively:

`--doc-open-entities`, `--spec-open-entities`
`--doc-open-elements`, `--spec-open-elements`
`--doc-error-numbers`, `--spec-error-numbers`
`--doc-references`, `--spec-references`
`--doc-include`, `--spec-include`
`--doc-warning`, `--spec-warning`

OpenJade ignores the `SP_CHARSET_FIXED` and `SP_SYSTEM_CHARSET` environment variables and always uses Unicode as its internal character set, as if `SP_CHARSET_FIXED` was 1 and `SP_SYSTEM_CHARSET` was unset. Thus only the `SP_ENCODING` environment variable is relevant to OpenJade's handling of character sets.

Back to top

## OpenJade Extensions

The following external procedures are available. These external procedures are defined by a prototype in the same manner as in the standard. To use one of these external procedures, you must make use of the standard `external-procedure` procedure, using a public identifier of `"UNREGISTERED::James Clark//Procedure::``name``"` where `name` is the name given here, typically by including the following in the DSSSL specification:

    (define name
      (external-procedure "UNREGISTERED::James Clark//Procedure::name"))

Note that `external-procedure` returns `#f` if it doesn't know about the specified public identifier. You can use this to enable your DSSSL specifications to work gracefully with other implementations which do not support these extensions.

For external procedures added by the OpenJade team, use a public identifier of the form `"UNREGISTERED::OpenJade//Procedure::``name``"`.

An easy way to get access to all external procedures is to use the style specification `dsssl/extensions.dsl#procedures`.

### Debugging

    (debug obj)

Generates a message including the value of `obj` and then returns `obj`.

### Simple-page-sequence header/footer control

    (if-first-page sosofo1 sosofo2)

This can be used only in the specification of the value of one of the header/footer characteristics of simple-page-sequence. It returns a sosofo that will display as `sosofo1` if the page is the first page of the simple-page-sequence and as `sosofo2` otherwise.

    (if-front-page sosofo1 sosofo2)

This can be used only in the specification of the value of one of the header/footer characteristics of simple-page-sequence. It returns a sosofo that will display as `sosofo1` if the page is a front (ie recto, odd-numbered) page and as `sosofo2` if it is a back (ie verso, even-numbered) page.

### Numbering

    (all-element-number)
    (all-element-number osnl)

This is the same as `element-number` except it counts elements with any generic identifier. If `osnl` is not an element returns #f, otherwise returns 1 plus the number of elements that started before `osnl`. This provides an efficient way of creating a unique identifier for any element in a document.

### External entity access

    (read-entity string)

This returns a string containing the contents of the external entity with system identifier `string`. This should be used only for textual entities (CDATA and SDATA), and not for binary entities (NDATA).

### POSIX locale access

    (language lang country)

This procedure returns an object of type `language`, if the system supports the specified language. `lang` is a string or symbol giving the two letter language code. `country` is a string or symbol giving the two letter country code.

This procedure uses POSIX locales. It is an OpenJade addition.

### URI addresses

    (uri-ref-addres uri)

This procedure returns an object of type address for the resource pointed to by the given URI.

### Extended standard procedures

    (sgml-parse sysid #!key active: parent: architecture:)

This allows you to specify an SGML architecture with respect to which the document should be parsed. It is an OpenJade addition.

    (expt q k)

This allows you to raise a quantity to an integral power. It is an OpenJade addition.

Back to top

## Current OpenJade Limitations

This section describes the limitations of the front-end (the general-purpose DSSSL engine); each backend also has its own limitations.

OpenJade supports only a single, fixed grove plan which comprises the following modules:

- baseabs
- prlgabs0
- prlgabs1
- instabs
- basesds0
- instsds0
- subdcabs

It doesn't implement the following parts of SDQL: HyTime support, auxiliary parsing, node regular expressions.

Query rules, sosofo synchronisation, indirect sosofos, reference values, decoration areas and font properties are not supported.

Note that only inherited characteristics that are applicable to some supported flow object can be specified.

### Character/glyph handling

It only supports a single pre-defined character repertoire. A character name of the form `U-``XXXX` where `XXXX` are four upper-case hexadecimal digits, is recognized as referring to the Unicode character with that code. For many characters, it is also possible to use the ISO/IEC 10646 name in lower-case with words separated by hyphens.

Some common SDATA entity names from the ISO entity sets are recognized and mapped to characters. In addition an SDATA entity name of the form `U-``XXXX`, where `XXXX` are four upper-case hexadecimal digits, is mapped to the Unicode character with that code.

OpenJade now supports the standard-chars, map-sdata-entity, add-name-chars, add-separator-chars and char-repertoire declaration element forms, allowing a style-sheet to define additional character names, sdata entity mappings, name characters (i.e. characters allowed in identifiers) and separator characters. Currently the only recognized character repertoire is the built-in repertoire. It has the public identifier `"UNREGISTERED::OpenJade//Character Repertoire::OpenJade"`.

Character properties are supported, but `declare-char-characteristic+property` is only partially supported.

### Validation

Several things that it would be desirable to have checked aren't checked:

- When the allowed value of an inherited characteristic is a symbol, OpenJade checks only that the value is a symbol that is allowed as the value of some characteristic; #t and #f are treated as a special kind of symbol in this case.
- OpenJade checks whether a standard flow object is occurring in a context where it is allowed, however extension flow objects (declared with `declare-flow-object-class`) are not checked by the front-end.
- Most type-checking is done at run-time not compile-time.
- OpenJade does not check for non-inherited characteristics that are required to be specified.

### Other limitations

The following primitives are just stubs:

`char-script-case`
  Always returns last argument.
`address-visited?`
  Always returns #f.

Back to top

## About OpenJade sources

The source of OpenJade is available via CVS from peano.mathematik.uni-freiburg.de. See the OpenJade home page for more details.

Back to top

All trademarks herein are the property of their respective owners.
Copyright © 1999 OpenJade project, All rights reserved. Created by Didier PH Martin, modified: September 7, 1999