xenial (1) openjade-1.4devel.1.gz

Provided by: openjade_1.4devel1-21.1_amd64 bug

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

SEE ALSO

       onsgmls(1)

AUTHORS

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