# Using Jade for SGML transformations

Jade does not support the DSSSL Transformation Language. However, it provides some simple, non-standardized extensions to the DSSSL Style Language that allow it to be used for SGML transformations.

These extensions are used in conjunction with the SGML backend which is selected with the `-t sgml` or `-t xml` options. Unlike other backends, the SGML backend writes its output to the standard output.

The `-t xml` option makes empty elements and processing instructions use the XML syntax. Note that the XML declaration is not automatically emitted.

The extensions consist of a collection of flow object classes that are used instead of the standard DSSSL-defined flow object classes:

`element`
`empty-element`
  Each of these flow objects results in an element in the output. The `element` flow object is a compound flow object (one that can have child flow objects). Both a start-tag and an end-tag are generated for this flow object. The `empty-element` is an atomic flow object (one that cannot have child flow objects). Only a start-tag is output for this. It should should be used for elements with a declared content of EMPTY or with a content reference attribute. Both of these flow objects support the following non-inherited characteristics:
  `gi`
    This is a string-valued characteristic that specifies the element's generic identifier. It defaults to the generic identifier of the current node.
  `attributes`
    This specifies the element's attributes as a list of lists each of which consists of exactly two strings, the first specifying the attribute name and the second the attribute value. It defaults to the empty list.
`processing-instruction`
  This is an atomic flow object that results in a processing instruction. It supports the following non-inherited characteristics:
  `data`
    This is a string-valued characteristic that specifies the content of the processing instruction. It defaults to the empty string.
`document-type`
  This is an atomic flow object that results in a DOCTYPE declaration. It supports the following non-inherited characteristics:
  `name`
    This is a string-valued characteristic that specifies the name of the document type (which must be the same as the name of the document element). It must not be omitted.
  `system-id`
    This is a string-valued characteristic that specifies the system identifier of the document type. If non-empty, this will be used as the system identifier in the doctype declaration. The default value is the empty string.
  `public-id`
    This is a string-valued characteristic that specifies the public identifier of the document type. If non-empty, this will be used as the public identifier in the doctype declaration. The default value is the empty string.
`entity`
  This is an compound flow object that stores its content in a separate entity. It supports the following non-inherited characteristic:
  `system-id`
    The system identifier of the entity. For now this is treated as a filename not as an FSI.

  Note that no entity reference or declaration is emitted.

`entity-ref`
  This is an atomic flow object that results in an entity reference. It supports the following non-inherited characteristic:
  `name`
    The name of the entity.
`formatting-instruction`
  This is an atomic flow object that inserts characters into the output without change. It supports the following non-inherited characteristic:
  `data`
    This is the string to be inserted.

  It differs from normal data characters in the `&`, `<` and `>` will not be escaped.

There is also the following characteristic:

`preserve-sdata?`
  This is an inherited boolean characteristic that applies to character flow objects. When true, if the current-node for the character flow object was an sdata node, then the character will be output as a reference to an entity with the same name. The initial value is #f.

Each of these flow object classes must be declared using `declare-flow-object-class` in any DSSSL specification that makes use of it. A suitable set of declarations is:

    (declare-flow-object-class element
      "UNREGISTERED::James Clark//Flow Object Class::element")
    (declare-flow-object-class empty-element
      "UNREGISTERED::James Clark//Flow Object Class::empty-element")
    (declare-flow-object-class document-type
      "UNREGISTERED::James Clark//Flow Object Class::document-type")
    (declare-flow-object-class processing-instruction
      "UNREGISTERED::James Clark//Flow Object Class::processing-instruction")
    (declare-flow-object-class entity
      "UNREGISTERED::James Clark//Flow Object Class::entity")
    (declare-flow-object-class entity-ref
      "UNREGISTERED::James Clark//Flow Object Class::entity-ref")
    (declare-flow-object-class formatting-instruction
      "UNREGISTERED::James Clark//Flow Object Class::formatting-instruction")
    (declare-characteristic preserve-sdata?
      "UNREGISTERED::James Clark//Characteristic::preserve-sdata?"
      #f)

Here's a simple example that does the identity transformation:

    <!doctype style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN">

    (declare-flow-object-class element
      "UNREGISTERED::James Clark//Flow Object Class::element")

    (define (copy-attributes #!optional (nd (current-node)))
      (let loop ((atts (named-node-list-names (attributes nd))))
        (if (null? atts)
            '()
            (let* ((name (car atts))
                   (value (attribute-string name nd)))
              (if value
                  (cons (list name value)
                        (loop (cdr atts)))
                  (loop (cdr atts)))))))

    (default (make element
                   attributes: (copy-attributes)))

Note that this does not deal with empty elements nor processing instructions, nor does it include a doctype declaration.