openjade



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,
       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 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)
              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 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



SEE ALSO

       onsgmls(1)



AUTHORS

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



OpenJade                         January 2002                      OPENJADE(1)

Man(1) output converted with man2html