jade - apply a DSSSL stylesheet to an SGML or XML document
openjade [-vCegG2s] [-b encoding] [-f error_file] [-c catalog_sysid] [-D dir] [-a link_type] [-A arch] [-E max_errors] [-i entity] [-w warning_type] [-d dsssl_spec] [-V variable=value] [-t output_type] [-o output_file] [sysid...]
OPENJADE(1) OPENJADE(1)
NAME
openjade - apply a DSSSL stylesheet to an SGML or XML document
SYNOPSIS
openjade [-vCegG2s] [-b encoding] [-f error_file]
[-c catalog_sysid] [-D dir] [-a link_type]
[-A arch] [-E max_errors] [-i entity]
[-w warning_type] [-d dsssl_spec] [-V variable=value]
[-t output_type] [-o output_file] [sysid...]
DESCRIPTION
openjade is an implementation of the ISO/IEC 10179:1996 standard DSSSL
language. 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.
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 sys-
tem 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 what-
ever 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, appli-
cation/dsssl, or application/x-dsssl. The value of href attribute is
the system identifier of the DSSSL specification.
<?dsssl sysid>
The system identifier is the portion of the system data of the process-
ing 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-specifi-
cation. 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
OpenSP (see onsgmls(1)) options (note that all options are case-sensi-
tive, ie -g and -G are different options):
-d dsssl_spec
This specifies that dsssl_spec is the system identifier of the
DSSSL specification to be used.
-G Debug mode. When an error occurs in the evaluation of an expres-
sion, openjade will display a stack trace. Note that this dis-
ables tail-call optimization.
-c filename
The filename 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 compliance mode. Currently the only effect is that jade
doesn't use any predefined character names, sdata-entity map-
pings 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 output_type
output_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) Mi-
crosoft'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 output_file
Write output to 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. If there is no input
filename, then the extension is added onto jade-out.
-V variable
This is equivalent to doing (define variable #t) except that
this definition will take priority over any definition of vari-
able in a style-sheet.
-V 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)
This is equivalent to doing (define variable value) except that
this definition will take priority over any definition of vari-
able 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.
-wtype 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 identi-
fier 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 con-
junction 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 spec-
ify 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.
ENVIRONMENT
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.
OPENJADE EXTENSIONS
The following external procedures are available. These external proce-
dures 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 stan-
dard external-procedure procedure, using a public identifier of "UNREG-
ISTERED::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//Proce-
dure::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 iden-
tifier 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. The file
dsssl/extensions.dsl also contains style specifications which make the
nonstandard flow object classes and inherited characteristics supported
by the backends available in a convenient way.
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-num-
bered) 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 ele-
ment 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 sup-
ports the specified language. lang is a string or symbol giving the two
letter language code. country is a string or symbol giving the two let-
ter country code.
This procedure uses POSIX locales. It is an OpenJade addition. It is
not supported on all operating systems.
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.
LIMITATIONS
This section describes the limitations of the front-end (the general-
purpose DSSSL engine); each backend also has its own limitations.
openjade doesn't allow internal definitions at the beginning of bodies
and the (test => recipient) variant of cond clauses.
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, aux-
iliary parsing, node regular expressions.
Query rules, sosofo synchronization, indirect sosofos, reference val-
ues, 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 dig-
its, 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".
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 doesn't check whether a flow object is occurring in a con-
text where it is allowed.
* OpenJade does not prevent flow objects being attached to the princi-
pal port of a flow object when the flow object shouldn't have a princi-
pal port.
* 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.
* It doesn't check that optional features that have been used were
declared in the features form.
Other limitations
The following primitives are just stubs:
char-script-case Always returns last argument.
address-visited? Always returns #f.
EXAMPLES
Given an SGML file file.sgml, use the stylesheet file.dsl and publish
as an rtf file.
openjade -t rtf file.sgml
Using a different stylesheet:
openjade -t rtf -d docbook.dsl file.sgml
Using the print style specification contained within the stylesheet
openjade -t rtf -d docbook.dsl#print file.sgml
And use the html specification within the style sheet to convert to
html
openjade -t sgml -i html -d docbook.dsl#html file.sgml
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
+---------------+---------------------------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+---------------------------------------+
|Availability | developer/documentation-tool/openjade |
+---------------+---------------------------------------+
|Stability | Volatile |
+---------------+---------------------------------------+
SEE ALSO
onsgmls(1)
AUTHORS
James Clark, Ian Castle <ian.castle@looksystems.co.uk>.
NOTES
Source code for open source software components in Oracle Solaris can
be found at https://www.oracle.com/downloads/opensource/solaris-source-
code-downloads.html.
This software was built from source available at
https://github.com/oracle/solaris-userland. The original community
source was downloaded from http://prdownloads.sourceforge.net/open-
jade/openjade-1.3.2.tar.gz.
Further information about this software can be found on the open source
community website at http://openjade.sourceforge.net/.
OpenJade January 2002 OPENJADE(1)