OpenJade is a suite of tools for validating, processing and applying DSSSL (Document Style Semantics and Specification Language) style sheets to SGML and XML documents.
OpenJade is a project undertaken by the DSSSL community to maintain and extend James Clark's Jade, as well as the related SP suite of SGML/XML processing tools. OpenJade and OpenSP are distributed under the same license as Jade.
Many different projects, organizations and companies make use of OpenJade to publish documentation. The SGML/XML backend enables the generation of "world wide web ready" documents while the TeX backend allows high quality "ready for press" output to be obtained. The FreeBSD Handbook (second edition) ISBN: 1571763031 is one such example of a book created using OpenJade.
OpenJade is a project hosted at sourceforge.net and is available from the OpenJade web site at http://openjade.sourceforge.net or directly from the OpenJade project page at http://sourceforge.net/projects/openjade
OpenJade is provided in source code form. However as a courtesy to Win32 users where development tools are not always available, a binary release for the Win32 platform is usually available.
OpenJade is intended to be as portable as possible. It should be possible to compile and build on most contemporary UNIX type platforms. In addition OpenJade will also build on Microsoft's Win32 based operating systems.
OpenJade is known to compile with both the GNU gcc c++ compiler and Microsoft Visual C++. Other compilers have not been extensively tested.
OpenJade has been successfully built with the following GNU compilers: Red Hat g++ 2.96, GCC g++ 2.95.3, GCC g++ 3.2
OpenJade has been built on a number of architectures including Intel i386 and ia64, Alpha AXP, Sparc, PPC and S/390, S/390x.
The following table details known successful builds
Table 1-1. Platforms on which OpenJade 1.3.2 is known to build.
Arch. | OS | Compiler | Notes |
---|---|---|---|
alpha | Debian 3.0 | GNU gcc 3.2 | |
arm | Debian 3.0 | GNU gcc 3.2 | |
hppa | Debian 3.0 | GNU gcc 3.2 | |
i386 | Debian 3.0 | GNU gcc 3.2 | |
Red Hat Linux 7.3 | Red Hat gcc 2.96 | ||
Red Hat Linux 7.3 | GNU gcc 3.2 | ||
SuSE Linux 8.1 | GNU gcc 3.2 | ||
ia64 | Debian 3.0 | GNU gcc 3.2 | |
m68k | Debian 3.0 | GNU gcc 3.2 | |
mips, mipsel | Debian 3.0 | GNU gcc 3.2 | |
powerpc | Debian 3.0 | GNU gcc 3.2 | |
s390 | Debian 3.0 | GNU gcc 3.2 | |
sparc | Debian 3.0 | GNU gcc 3.2 |
Please report any successful builds not mentioned above to <openjade-devel@lists.sourceforge.net>, including any diffs/patches you have used.
OpenJade requires 40Mb to 50Mb of disk space to build. An installation will require around 15Mb to 20Mb depending on architecture.
OpenJade makes use of the GNU software configuration tools (autoconf, libtool, automake etc). The GNU C++ compiler and make utility should also be used. The steps required to build the OpenJade tools (onsgmls, openjade, osgmlnorm, ospam, ospent, osx) and libraries are as follows:
gzip -d openjade-1.3.2.tar.gz | tar xvf -
cd openjade-1.3.2
./configure [options…]
make
You may need to switch to the super user root to complete the installation
make installIf you wish to install man pages for the various commands you should then do
make install-manThe configure script supports many options. These can be displayed using the command
./configure --helpIn addition to the standard options, the following table describes options specific to openjade.
Table 1-2. OpenJade specific configure options
Option | Default | Explanation |
---|---|---|
--enable-spincludedir=path | /usr/include/OpenSP | Define the path where the OpenSP include files may be found. |
--enable-splibdir=path | /usr/lib | Define the path where the OpenSP library (libosp) may be found. |
--disable-mif | MIF support is enabled | disable support for FrameMaker MIF output (the -t mif option) to openjade. |
--disable-html | html support enabled | disable support for HTML+CSS output (the -t html to openjade). |
--enable-default-catalog=pathlist | Not enabled | Provide one or more default catalog files or sysids, e.g. /usr/local/lib/sgml/catalog |
--enable-default-search-path=pathlist | Not enabled | Provide a default value for SGML_SEARCH_PATH |
Please refer to the system documentation for details on building on the Win32 platform.
Although the OpenJade project does not make binary distributions available, OpenJade has been a part of many software distributions, including the major Linux distributions as well as FreeBSD. Expect pre-compiled and packaged versions of the latest version of OpenJade to be available from your distributor in due course.
In addition to the OpenJade executables and libraries you will also need various DTDs and stylesheets. Some DTDs and associated files (entity definitions) are available in the pubtext directory of the distribution. However, more authoritative sources should be referenced to ensure that up-to-date versions are used. If you wish to process XML files, then suitable SGML declarations for valid XML documents should be used. Again, a sample set of declarations (xml.dcl) is provided in the pubtext, but more complete or recent versions may be available from other sources.
OpenJade supports the standard SGML catalog facility; it is recommended that you set up and use such a catalog system. Generally speaking you will create your own DSSSL stylesheets for use with OpenJade, however, users of the OASIS DocBook DTD should be aware that extensive, and modular, stylesheets are available from the DocBook project at http://docbook.sourceforge.net.
If you wish to make use of the TeX backend you will require an up to date distribution of laTeX such as teTeX, TeXlive or fpTeX. In addition you will also require the jadetex package, available from http://jadetex.sourceforge.net.
If, after reading the documentation, you still have a problem, then you may require some additional help. The OpenJade project is a volunteer effort and as such does not provide any formal support. Instead, you should look to the community for support. Once part of the community, you, in turn, will be able to play your part in helping those that come after you. Here are some pointers to obtaining help:
If you obtained your OpenJade tools in binary form from your operating system distributor and you have a build related problem - such as openjade crashing, then your first port of call should be your distributor.
If you have a problem with the usage of openjade and tools, or general queries about DSSSL then you should try the DSSSL mailing list, see http://www.mulberrytech.com/dsssl/dssslist/ for details.
If you are using the DocBook DTD and especially if you are also using the Modular DocBook DSSSL stylesheets, then the docbook-apps mailing list is the place to go. See http://www.oasis-open.org/docbook/mailinglist/ for details.
If you have a patch or bug fix for OpenJade, or are trying to use the OpenSP API then the openjade-devel mailing list is the appropriate forum.
Please choose only one mailing list to post to, as cross-posting is generally frowned upon. The various mailing lists are archived and searchable. It is always worth searching for your problem first, as it is often the case that someone has had the same problem before.
Released December 2002. This release allows openjade to be built against the most recent OpenSP release - version 1.5. It also contains some fixes for the MIF backend which were omitted from the 1.3.1 release. OpenSP is now distributed in a separate package and made available on its own release cycle
Table 1-3. Changes for release 1.3.2
Item 1 | MIF Backend Fixes |
---|---|
References | G. Seshadri et al. |
Category | Software Bug |
Problem | Issues with page size and page header/footers |
Resolution | Fix to make sure that right header is shown in documents and that document page size is initialised correctly. |
Item 2 | Support for building OpenSP 1.5 |
---|---|
References | Ian Castle, Karl Eichwalder |
Category | Software Bug |
Problem | OpenSP is now at version 1.5 which has many improvements over 1.3.4 |
Resolution | It is desirable to use OpenSP 1.5 which has many improvements over version 1.3.4 which shipped with openjade 1.3.1. However, it is awkward having to have two versions of OpenSP at the same time. OpenJade 1.4 is not ready for release yet, so version 1.3.2 will link against OpenSP 1.5 and later - and no longer includes the old version 1.3.4 of OpenSP. |
Item 3 | Correct definition of "attribute" in builtin.dsl |
---|---|
References | Toby Speight, Debian Bug #145242 |
Category | Software Bug |
Problem | The definition of "attribute" (ISO/IEC 10179:1996, section 10.2.5) for SGML property operations was not correct. |
Resolution | The definition has been corrected in accordance with the standard. |
Item 4 | XML backend doesn't quote "&" in attribute values |
---|---|
References | Toby Speight, Debian Bug #147073 |
Category | Software Bug |
Problem | When using OpenJade with the XML or SGML backend to output attribute values containing the '&' character, the output is not well-formed. |
Resolution | Fixed the Transform FOT Builder so that for XML output the '&' character is properly quoted. |
Released January 2002. This release is primarily a maintenance release. It delivers two key advantages over the OpenJade 1.3 release: Support for contemporary platforms (operating systems and compilers) and incorporates the various patches and improvements, especially to the TeX backend, which have been extensively used over the last few years. Probably the biggest benefit to TeX backend users are the enhanced table support and improved two sided output support (in conjunction with improvements to the companion jadetex package).
The following table details the major improvements in Openjade 1.3.1
Table 1-4. Changes for release 1.3.1
Item 1 | Support for MacOS X/ Darwin |
---|---|
References | Fink Project; Kogulé, Ryo |
Category | Software Bug |
Problem | OpenJade 1.3 does not build and run on the Mac OS X/Darwin platform |
Resolution | OpenJade 1.3.1 has been enhanced to support Mac OS X/Darwin 1.4. The autoconf configuration system has been upgraded and also includes specific platform support. Some minor code alterations to improve code portability (C++ style changes). Note that the POSIX locale feature is not available on this platform. |
Item 2 | UNIX on-line manual pages |
---|---|
References | None |
Category | Documentation Bug |
Problem | No on-line manual (man) pages available on UNIX platforms |
Resolution | OpenJade 1.3.1 now has a man page for every command. Additionally, if OpenJade is used as a replacement for Jade, then compatibility man pages are included (i.e. man jade is synonymous with man openjade). |
Item 3 | Upgrade GNU source configuration tools |
---|---|
References | Various sourceforge problem reports, SuSE Linux 7.3, Red Hat 7.2, Red Hat Bugzilla #46212 |
Category | Software Bug |
Problem | The source configuration system is based on old versions of libtool and autoconf. In addition, there are problems with the generated Makefile files such that installation directories are not created. |
Resolution | Upgraded to autoconf 2.52 and libtool 1.4. Upgraded the various support files. Included elements of automake support. Made the Makefiles more robust. These changes should facilitate porting to new/updated environments (i.e. those supported by newer versions of autoconf). Work has been done to enhance some of the custom autoconf tests to improve reliability. |
Item 4 | Support for XML Byte Order Marks (BOM) |
---|---|
References | Source Forge bug #442560 (Terje Bless/Liam Quinn) |
Category | Software Bug |
Problem | Since OpenJade 1.3 was released, a second edition of the XML 1.0 specification has been released (REC-xml-20001006). This specification introduced the concept of Byte Order Marks to increase the sophistication of the detection of the character encoding system. OpenJade 1.3 would not recognize these, and rejected any XML file which included these as invalid. |
Resolution | XML 1.0 Byte Order Marks are now accepted as valid XML. |
Item 5 | Fix missing white space problem in processing instruction flow object |
---|---|
References | Source Forge Ref #505113, #505124 (Markus Hoenicka) |
Category | Software Bug |
Problem | No white space was emitted between the public-id and the system-id causing a malformed XML file to be generated. |
Resolution | Fixed OpenJade to output a space between the public-id and the system-id. |
Item 6 | Jadetex is now distributed independently |
---|---|
References | None |
Category | Software Bug |
Problem | OpenJade 1.3 shipped with Jadetex 2.7. Jadetex is developed and released separately from OpenJade. |
Resolution | Removed jadetex files. Jadetex can be obtained from http://jadetex.sourceforge.net |
Item 7 | Support for FreeBSD 4.4 |
---|---|
References | FreeBSD 4.4 openjade port |
Category | Software Bug |
Problem | OpenJade 1.3 would not build on FreeBSD 4.x |
Resolution | The source configuration system has been enhanced to support FreeBSD out of the box. Note that the POSIX locale feature of OpenJade is not available under FreeBSD. |
Item 8 | Allow non alpha numeric characters in Table of Contents |
---|---|
References | Red Hat Bugzilla #31525 |
Category | Software Bug |
Problem | Certain non alpha-numeric characters (such as $) do not appear correctly in the table of contents. This problem is confined to the TeX backend. |
Resolution | Special characters are now correctly escaped in the TeX output file. |
Item 9 | Support for latest Win32 build environments |
---|---|
References | None |
Category | Software Bug |
Problem | OpenJade 1.3 does not build with Visual C++ 6.0 |
Resolution | Fix C++ style to be compatible with Visual C++. Update build environment. OpenJade 1.3.1 should run in all Windows 32 environments from Windows 95 through Windows NT to Windows XP. |
Item 10 | Enhancements for Software Packaging |
---|---|
References | SuSE Linux 7.3 |
Category | Software Bug |
Problem | Numerous patches need to be applied to OpenJade 1.3 to enable packages to be built (RPM) |
Resolution | Enhance Makefiles to ensure that packages are easy to build (including addition of DESTDIR environment variable). It should now be possible to build RPM packages and BSD ports without resorting to patches. |
Item 11 | Support for newer GNU C++ compilers |
---|---|
References | SuSE Linux 7.3 (Andreas Schwab), Red Hat Linux 7.2, Connectiva Linux |
Category | Software Bug |
Problem | C++ is a shifting target. New compilers/standards demand changes. |
Resolution | Various enhancements to allow OpenJade to build with the new GNU GCC 3.0 and the soon to be released GNU GCC 3.1 c++ compilers |
Item 12 | Support for jadetex 3.4 and greater macros for two sided support |
---|---|
References | Sourceforge patch #439755, http://iNdev.iNsu.COM/openjade/ (Francis J. Lacoste) |
Category | Software Bug |
Problem | Two Sided output support with the TeX backend is unreliable in OpenJade 1.3 and Jadetex 2.x. |
Resolution | Enhance the TeX backend two sided output support and bring into line with advances in the jadetex latex front end. Two extension characteristics are introduced to allow control of two-side and two-side-start-on-right. This also fixes the "blank page at the end of the document" problem. The following new characteristics are available: "UNREGISTERED::OpenJade//Characteristic::page-two-side?" "UNREGISTERED::OpenJade//Characteristic::two-side-start-on-right?" |
Item 13 | Prevent incorrect generation of ligatures in the TeX Backend |
---|---|
References | Red Hat Bugzilla #11497, #11779 |
Category | Software Bug |
Problem | Certain sequences of characters (such as --) are not correctly escaped in the TeX backend, so that TeX incorrectly creates ligatures out of them (so that -- becomes an em dash —). |
Resolution | OpenJade 1.3.1 now correctly escapes these character sequences. This is a particular problem when representing program code where sequences such as -- are often operators. |
Item 14 | Improved time string handling |
---|---|
References | http://iNdev.iNsu.COM/openjade/ (Francis J. Lacoste) |
Category | Software Bug |
Problem | OpenJade 1.3 does not support the (time<=?) comparison |
Resolution | Various bugs fixed in the time string support of OpenJade. It is now possible to compare time, date and datetime. Also partial formats (such as YY-MM-DD, YYYY-MM or HH:MM) are now supported |
Item 15 | Improvements in handling sosofo-append |
---|---|
References | http://iNdev.iNsu.COM/openjade/ (Francis J. Lacoste) |
Category | Software Bug |
Problem | sosofo-append has problems with memory/stack usage when handling large lists of sosofo |
Resolution | The fix optimizes sosofo-append to reduce its memory and stack usage when using it to build long list of sosofo : (let loop ( (res (empty-sosofo)) (nl (node-list-rest (children (current-node))))) (loop (sosofo-append res (process-node-list (node-list-first nl))) (node-list-rest nl))) |
Item 16 | Improved Table handling in TeX Backend |
---|---|
References | http://iNdev.iNsu.COM/openjade/ (Francis J. Lacoste) |
Category | Software Bug |
Problem | Table handling in the TeX backend has numerous problems. |
Resolution | Support for tables in the TeX backend has been improved with:
|
Item 17 | Support for 'asis and 'asis-wrap |
---|---|
References | http://iNdev.iNsu.COM/openjade/ (Francis J. Lacoste) |
Category | Software Bug |
Problem | The lines: characteristic in the paragraph flow object does not support the 'asis and 'asis-wrap values. |
Resolution | This adds support for the 'asis and 'asis-wrap values for the paragraph's lines: characteristic. |
Released October 1999. Version 1.3 added many improvements to increase the scope of the implementation of DSSSL. Changes include:
The SGML backend will now emit linebreaks when used as -t sgml-raw.
Jade can bind variables to arbitrary values on the command line with the -V option.
The prlabs1 module of the SGML property set is supported.
Style sheet extensions.dsl lists all known external procedures ready for easy inclusion as an external-specification.
External procedure with public identifier
"UNREGISTERED::OpenJade//Procedure::expt"to provide integral powers of quantities.
External procedure with public identifier
"UNREGISTERED::OpenJade//Procedure::sgml-parse"allows to parse w.r.t. an architecture.
Jade supports force! for inherited characteristics.
Jade supports character properties.
Jade supports special-query-expressions.
Jade can bind variables to string values on the command line.
All standard color spaces supported.
Jade ignores duplicate keywords in make expressions, as mandated by DSSSL.
External procedure with public identifier
"UNREGISTERED::OpenJade//Procedure::language"to create a language object by reference to a POSIX locale.
Language-dependent procedures of the expression language: language?, current-language, declare-default-language, with-language, define-language, char<?, char>?, char<=?, char>=?, char-ci=?, char-ci<?, char-ci>?, char-ci<=?, char-ci<=?, char-upcase, char-downcase, string-ci=?, string-equiv?, string<?, string>?, string<=?, string>=?, string-ci<?, string-ci>?, string-ci<=?, string-ci>=?.
The style-sheet.dtd derived from the DSSSL architecture has been extended (in a backward compatible way) to include the declaration element type forms supported by Jade. The public identifier for the dtd is
"-//OpenJade//DTD DSSSL Style Sheet//EN"
char-repertoire, add-name-chars and add-separator-chars declaration element type forms are supported. When given the -s command line flag, Jade doesn't use its built in character repertoire.
Most of the derived procedures in the query language: current-root, node-list-reduce, node-list-contains?, node-list-remove-duplicates, node-list-union, node-list-intersection, node-list-difference, node-list-symmetric-difference, node-list-union-map, node-list-some?, node-list-every?, node-list-filter, node-list->list, node-list-tail, node-list-head, node-list-sublist, node-list-count, node-list-last, node-list-property, origin, origin-to-subnode-rel, tree-root, grove-root, source, subtree, subgrove, ancestors, grove-root-path, rsiblings, ipreced, ifollow, grove-before?, sort-in-tree-order, tree-before?, tree-before, property-lookup, select-by-property, select-by-null-property, select-by-missing-property, attribute, referent, q-element, q-class, q-sdata.
Released June 1999. The first release of OpenJade.
Changes in OpenJade 1.2.2
The HTML and MIF backends are now enabled by default.
The TeX backend has support for PDF bookmarks. This is supported by the new version of jadetex which is included.
Predefined character names line-feed and carriage-return for the character numbers 10 and 13.
standard-chars and map-sdata-entity declaration element type forms are supported.
Style language additions: map-constructor.
+ and - return a length-spec if any of there arguments is a length-spec.
Most of the DSSSL non-core expression language: c...r, assoc, keyword->string, string->keyword, exact?, inexact?, zero?, positive?, negative?, odd?, even?, exp, log, sin, cos, tan, asin, acos, atan, expt, exact->inexact, inexact->exact, quantity->number, string->list, list->string, map, time<?, time>?, time<=?, time>=?.
Released October 1998. Jade 1.2.1 was the final release of jade from James Clark. OpenJade is based on this code base.