Man Pages

openjade(1) - phpMan openjade(1) - phpMan

Command: man perldoc info search(apropos)  


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 omit-
       ted, 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  pro-
       cessing 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 pro-
       cessing 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 mech-
              anism 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  warn-
              ings:

              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. (Rec-
              ommendations 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 refer-
              ence 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 declara-
              tion 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  dec-
              laration 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::Open-
       Jade//Procedure::name".


       An  easy  way  to  get  access  to  all  external  procedures  is  to  use the style specification dsssl/exten-
       sions.dsl#procedures. The file dsssl/extensions.dsl also contains style specifications which make the  nonstan-
       dard 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 coun-
       try 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  Uni-
       code character with that code.


       OpenJade now supports the standard-chars, map-sdata-entity, add-name-chars, add-separator-chars and char-reper-
       toire declaration element forms, allowing a style-sheet to define additional character names, sdata entity map-
       pings,  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::Open-
       Jade//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.castleATlooksystems.uk>.



OpenJade                         January 2002                      OPENJADE(1)