# OpenJade 1.3.3-pre1

## Release Notes

### OpenJade Project

Copyright © 2003 by OpenJade Project

List of Tables
1-1. Platforms on which OpenJade 1.3.3-pre1 is known to build.
1-2. OpenJade specific configure options
1-3. Changes for release 1.3.2
1-4. Changes for release 1.3.1

# Chapter 1. OpenJade 1.3.3-pre1 Release Notes

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.

## Applications of OpenJade

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.

## Obtaining 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.

## Supported Platforms

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.3-pre1 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.

## Building OpenJade from Source

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.3-pre1.tar.gz | tar xvf -
    cd openjade-1.3.3-pre1
    ./configure [options…]
    make

You may need to switch to the super user root to complete the installation

    make install

If you wish to install man pages for the various commands you should then do

    make install-man

The configure script supports many options. These can be displayed using the command

    ./configure --help

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

## Binary Distributions

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.

## Installation

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.

## Support

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.

## Version 1.3.3-pre1

Released April 2003. This release adds support for many new flow objects.

## Version 1.3.2

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.

## Version 1.3.1

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:

- Support for nested tables.

- `cell-after-column-margin:` and `cell-before-column-margin:` wasn't really working.

- Row spanning was broken. This fix only supports `'start` row alignment though.

- Paragraphs in cell spanning multiple column are now working.

- Support for the `row-alignment:` characteristic.

- Support for `cell-background?` and `background-color` properties

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.

## Version 1.3

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

## Version 1.2.2

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>=?`.

## Jade Version 1.2.1

Released October 1998. Jade 1.2.1 was the final release of jade from James Clark. OpenJade is based on this code base.