Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
OPENJADE(1)							   OPENJADE(1)

       openjade	- apply	a DSSSL	stylesheet to an SGML or XML document

       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...]

	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

       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,	appli-
       cation/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) Mi-
	      crosoft'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

	      sgmldecl Warn about various dubious constructions	 in  the  SGML

	      should  Warn about various recommendations made in ISO 8879 that
	      the document does	not  comply  with.  (Recommendations  are  ex-
	      pressed 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 un-

	      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
	      -wvalid has the effect of	changing the SGML declaration to spec-
	      -wvalid nor -wno-valid are specified, then the VALIDITY and  IM-
	      PLYDEF specified in the SGML declaration will be used.

       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.

       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-

       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/ex-
       tensions.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.


       (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.



       (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 re-
       turns 1 plus the	number of elements that	started	before osnl. This pro-
       vides  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 en-
       tities (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.

       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".


       Several	things	that  it  would	 be  desirable	to have	checked	aren't

       * 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 de-
       clared in the features form.

       Other limitations

       The following primitives	are just stubs:

       char-script-case	Always returns last argument.

       address-visited?	Always returns #f.

       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

       openjade	-t sgml	-i html	-d docbook.dsl#html file.sgml


       James Clark, Ian	Castle.

OpenJade			 January 2002			   OPENJADE(1)


Want to link to this manual page? Use this URL:

home | help