OPENJADE(1)

👑 OPENJADE 👑 — the openjade(1) manual, but make it make sense 💅

okay bestie, buckle up, because this is the openjade page and she is long. we're in part 1 of 2, so hydrate and stay with me 🫶

---

✨ NAME ✨

openjade — apply a DSSSL stylesheet to an SGML or XML document. literally that's the whole job. iconic.

---

🌸 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 💖

so openjade is an implementation of the ISO/IEC 10179:1996 standard DSSSL language. no cap. the DSSSL engine takes an SGML or XML document as input and transforms it into formats like:

• An 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. (yes bestie, stdin, she's flexible like that 💅)

---

🦋 how openjade figures out the DSSSL system identifier 🦋

this is the part where she goes hunting for the spec. here's the order of operations, fr fr:

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. (pick your fave by name, she'll respect it 💜)

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

---

🌈 OPTIONS 🌈

openjade supports the following options in addition to the normal OpenSP (see onsgmls(1)) options. and listen — all options are case-sensitive, ie -g and -G are different options. she does NOT play about case. 👑

• -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. 😭 (yes, the shell will fight you. use your quotes. protect her.)
• -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. ✨ (unicode always, she said. we don't do alternatives here.)

---

✨ OPENJADE EXTENSIONS ✨

okay bestie so OpenJade has extra external procedures beyond the standard ones, and they're defined by a prototype exactly the same way the standard does it. 🫶 To use one, you gotta go through the standard external-procedure procedure and hand it a public identifier shaped like "UNREGISTERED::James Clark//Procedure::name" — where name is the name listed down below. In practice that means your DSSSL spec looks like this:

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

Heads up though: external-procedure returns #f if it doesn't know about the public identifier you gave it. Which is honestly a feature, because it means your DSSSL specs can degrade gracefully on other implementations that don't support these extensions. 💅

And for the external procedures that the OpenJade team themselves added? Those use a public identifier of the form "UNREGISTERED::OpenJade//Procedure::name".

Easiest way to grab all of them at once is the style specification dsssl/extensions.dsl#procedures. And the file dsssl/extensions.dsl also carries style specifications that make the nonstandard flow object classes and inherited characteristics that the backends support available to you in a convenient way. ✨

---

🐛 Debugging

• (debug obj) — spits out a message with the value of obj in it, then hands you back obj. It's giving "peek at the vibes, no consequences". 🔍

📄 Simple-page-sequence header/footer control

• (if-first-page sosofo1 sosofo2) — you can ONLY use this when you're specifying the value of one of the header/footer characteristics of simple-page-sequence. It returns a sosofo that'll render as sosofo1 if the page is the first page of the simple-page-sequence, and as sosofo2 otherwise. 🥇
• (if-front-page sosofo1 sosofo2) — also ONLY usable when specifying the value of one of the header/footer characteristics of simple-page-sequence. It returns a sosofo that renders as sosofo1 if the page is a front page (that's recto, the odd-numbered ones, bestie) and as sosofo2 if it's a back page (verso, even-numbered). 🦋

🔢 Numbering

• (all-element-number)
• (all-element-number osnl) — same energy as element-number, except it counts elements with any generic identifier. If osnl isn't an element it returns #f, otherwise it returns 1 plus the number of elements that started before osnl. So it's a super efficient way to cook up a unique identifier for literally any element in a document. 👑

📦 External entity access

• (read-entity string) — returns a string holding the contents of the external entity whose system identifier is string. ⚠️ ONLY use this for textual entities (that's CDATA and SDATA), never for binary entities (NDATA). Not the move. 🙈

🌍 POSIX locale access

• (language lang country) — returns an object of type language, as long as your system supports the language you asked for. lang is a string or symbol with the two letter language code, and country is a string or symbol with the two letter country code.

This one runs on POSIX locales. It's an OpenJade addition. And ngl, it is not supported on all operating systems. 😭

🧚 Extended standard procedures

• (sgml-parse sysid #!key active: parent: architecture:) — lets you specify an SGML architecture that the document should be parsed with respect to. It's an OpenJade addition. 🏗️
• (expt q k) — lets you raise a quantity to an integral power. Also an OpenJade addition. 📈

---

💀 LIMITATIONS

This bit is all about the limitations of the front-end (aka the general-purpose DSSSL engine). And btw, every backend has its own limitations too, so this isn't the whole story. 🙃

openjade doesn't allow internal definitions at the beginning of bodies, and it doesn't do the (test => recipient) variant of cond clauses.

openjade supports only a single, fixed grove plan, and that plan comprises these modules:

• baseabs
• prlgabs0
• prlgabs1
• instabs
• basesds0
• instsds0
• subdcabs

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

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

Also, 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. And for many characters you can also 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. On top of that, 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, which lets a style-sheet 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, and its public identifier is "UNREGISTERED::OpenJade//Character Repertoire::OpenJade". ✨

✅ Validation

Several things that it would be desirable to have checked just… aren't checked. Rude, but here we are: 🫠

• 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 the last argument.
• address-visited? — always returns #f.

---

🌸 EXAMPLES

So say you've got an SGML file file.sgml, you're using the stylesheet file.dsl, and you wanna 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

Slay. 💅✨

---

👀 SEE ALSO

• onsgmls(1)

---

👑 AUTHORS

James Clark, Ian Castle <ian.castle@looksystems.co.uk>. 🫶

---

and that's the whole page, bestie!! 🎀 this one's from OpenJade, dated January 2002, and the manual page itself is OPENJADE(1). ily, go read a grove plan or something 🌈💖