openjade-1.4devel - Online in the Cloud

PROGRAM:

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 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. 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 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 OpenSP (see onsgmls(1))
options (note that all options are case-sensitive, 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 expression, openjade will
display a stack trace. Note that this disables 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 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 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) 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 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 variable 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 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.

-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 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.

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 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. 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-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. 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, auxiliary parsing, node
regular expressions.

Query rules, sosofo synchronization, 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".

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 context where it is
allowed.

* OpenJade does not prevent flow objects being attached to the principal port of a flow
object when the flow object shouldn't have a principal 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

Use openjade-1.4devel online using onworks.net services