48. Standard Generalized Markup Language (SGML)

This chapter contains DocBook SGML document type definitions (DTDs), DocBook DSSSL Stylesheets and DocBook tools to validate, transform, format and publish DocBook documents.

48.1 sgml-common-0.6.3

Introduction to SGML Common

The SGML Common package contains install-catalog. This is useful for creating and maintaining centralized SGML catalogs.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

Additional Downloads

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/sgml-common

Installation of SGML Common

Instead of the normal convention of including the autotools files in the package, the maintainers included symlinks to the files in /usr/share/automake. For previous versions of Automake this convention is correct, but recent versions of Automake install the internal files in version specific directories. This causes the configure script to abort. To fix this error, the autotools are regenerated. Since the included Makefile.am file uses a syntax not supported by current versions of Automake, a patch is required to fix the syntax.

patch -Np1 -i ../sgml-common-0.6.3-manpage-1.patch &&
autoreconf -f -i

Install SGML Common by running the following commands:

./configure --prefix=/usr --sysconfdir=/etc &&
make

This package does not come with a test suite.

Now, as the root user:

make docdir=/usr/share/doc install &&

install-catalog --add /etc/sgml/sgml-ent.cat \
    /usr/share/sgml/sgml-iso-entities-8879.1986/catalog &&

install-catalog --add /etc/sgml/sgml-docbook.cat \
    /etc/sgml/sgml-ent.cat

Update Hint

Remove the above catalog items prior to upgrading (as the root user) with:

install-catalog --remove /etc/sgml/sgml-ent.cat \
    /usr/share/sgml/sgml-iso-entities-8879.1986/catalog &&

install-catalog --remove /etc/sgml/sgml-docbook.cat \
    /etc/sgml/sgml-ent.cat

Configuring SGML Common

Config Files

/etc/sgml/sgml.conf

Configuration Information

No change in this file is necessary.

Contents

Installed Programs: install-catalog and sgmlwhich

Installed Libraries: None

Installed Files: SGML and XML DocBook entity files

Installed Directories: /etc/sgml, /usr/share/doc/sgml-common-0.6.3, and /usr/share/sgml

Short Descriptions

install-catalog creates a centralized catalog that maintains references to catalogs scattered throughout the /usr/share/sgml directory tree.

sgmlwhich prints to standard output the name of the main configuration file.

SGML entities files contains the basic character entities defined with SDATA entries.

XML entities files contains the basic character entities defined by a hexadecimal representation of the Unicode character number.

48.2 docbook-3.1-dtd

Introduction to DocBook-3.1 SGML DTD

The DocBook SGML DTD package contains document type definitions for verification of SGML data files against the DocBook rule set. These are useful for structuring books and software documentation to a standard allowing you to utilize transformations already written for that standard.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

DocBook-3.1 SGML DTD Dependencies

Required

sgml-common-0.6.3 and UnZip-6.0

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/sgml-dtd-3

Installation of DocBook-3.1 SGML DTD

Note

The package source is distributed in zip format and requires unzip. You should create a directory and change to that directory before unzipping the file to ease the removal of the source files after the package has been installed.

Install DocBook-3.1 SGML DTD by running the following commands:

sed -i -e '/ISO 8879/d' \
       -e 's|DTDDECL "-//OASIS//DTD DocBook V3.1//EN"|SGMLDECL|g' \
       docbook.cat

This package does not come with a test suite.

Now, as the root user:

install -v -d -m755 /usr/share/sgml/docbook/sgml-dtd-3.1 &&
chown -R root:root . &&
install -v docbook.cat /usr/share/sgml/docbook/sgml-dtd-3.1/catalog &&
cp -v -af *.dtd *.mod *.dcl /usr/share/sgml/docbook/sgml-dtd-3.1 &&

install-catalog --add /etc/sgml/sgml-docbook-dtd-3.1.cat \
    /usr/share/sgml/docbook/sgml-dtd-3.1/catalog &&

install-catalog --add /etc/sgml/sgml-docbook-dtd-3.1.cat \
    /etc/sgml/sgml-docbook.cat

Command Explanations

sed -i -e ‘/ISO 8879/d’ docbook.cat: This command removes the ENT definitions from the catalog file.

**sed -i -e ‘s DTDDECL “-//OASIS//DTD Docbook V3.1//EN” SGMLDECL g’ docbook.cat**: This command replaces the DTDDECL catalog entry, which is not supported by Linux SGML tools, with the SGMLDECL catalog entry.

Configuring DocBook-3.1 SGML DTD

Config Files

/etc/sgml/catalog

Configuration Information

The above installation script updates the catalog.

Using only the most current 3.x version of DocBook SGML DTD requires the following (perform as the root user):

cat >> /usr/share/sgml/docbook/sgml-dtd-3.1/catalog << "EOF"
  -- Begin Single Major Version catalog changes --

PUBLIC "-//Davenport//DTD DocBook V3.0//EN" "docbook.dtd"

  -- End Single Major Version catalog changes --
EOF

Contents

Installed Programs: None

Installed Libraries: None

Installed Files: SGML DTD and MOD files

Installed Directory: /usr/share/sgml/docbook/sgml-dtd-3.1

Short Descriptions

SGML DTD files contains a document type definition which defines the element types and the attribute lists that can be used in the corresponding SGML files.

SGML MOD files contains components of the document type definition that are sourced into the DTD files.

48.3 docbook-4.5-dtd

Introduction to DocBook-4.5 SGML DTD

The DocBook-4.5 SGML DTD package contains document type definitions for verification of SGML data files against the DocBook rule set. These are useful for structuring books and software documentation to a standard allowing you to utilize transformations already written for that standard.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

DocBook-4.5 SGML DTD Dependencies

Required

sgml-common-0.6.3 and UnZip-6.0

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/sgml-dtd

Installation of DocBook-4.5 SGML DTD

Note

The package source is distributed in zip format and requires unzip. You should create a directory and change to that directory before unzipping the file to ease the removal of the source files after the package has been installed.

Install DocBook-4.5 SGML DTD by running the following commands:

sed -i -e '/ISO 8879/d' \
       -e '/gml/d' docbook.cat

This package does not come with a test suite.

Now, as the root user:

install -v -d /usr/share/sgml/docbook/sgml-dtd-4.5 &&
chown -R root:root . &&

install -v docbook.cat /usr/share/sgml/docbook/sgml-dtd-4.5/catalog &&
cp -v -af *.dtd *.mod *.dcl /usr/share/sgml/docbook/sgml-dtd-4.5 &&

install-catalog --add /etc/sgml/sgml-docbook-dtd-4.5.cat \
    /usr/share/sgml/docbook/sgml-dtd-4.5/catalog &&

install-catalog --add /etc/sgml/sgml-docbook-dtd-4.5.cat \
    /etc/sgml/sgml-docbook.cat

Command Explanations

sed -i -e ‘/ISO 8879/d’ -e ‘/gml/d’ docbook.cat: This command removes the ENT definitions from the catalog file.

Configuring DocBook-4.5 SGML DTD

Config Files

/etc/sgml/catalog

Configuration Information

The above installation script updates the catalog.

Using only the most current 4.x version of DocBook SGML DTD requires the following (perform as the root user):

cat >> /usr/share/sgml/docbook/sgml-dtd-4.5/catalog << "EOF"
  -- Begin Single Major Version catalog changes --

PUBLIC "-//OASIS//DTD DocBook V4.4//EN" "docbook.dtd"
PUBLIC "-//OASIS//DTD DocBook V4.3//EN" "docbook.dtd"
PUBLIC "-//OASIS//DTD DocBook V4.2//EN" "docbook.dtd"
PUBLIC "-//OASIS//DTD DocBook V4.1//EN" "docbook.dtd"
PUBLIC "-//OASIS//DTD DocBook V4.0//EN" "docbook.dtd"

  -- End Single Major Version catalog changes --
EOF

Contents

Installed Programs: None

Installed Libraries: None

Installed Files: SGML DTD and MOD files

Installed Directory: /usr/share/sgml/docbook/sgml-dtd-4.5

Short Descriptions

SGML DTD files contains a document type definition which defines the element types and the attribute lists that can be used in the corresponding SGML files.

SGML MOD files contains components of the document type definition that are sourced into the DTD files.

48.4 OpenSP-1.5.2

Introduction to OpenSP

The OpenSP package contains a C++ library for using SGML/XML files. This is useful for validating, parsing and manipulating SGML and XML documents.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

OpenSP Dependencies

Required

sgml-common-0.6.3

Optional

libnsl-2.0.0 and xmlto-0.0.28

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/opensp

Installation of OpenSP

Install OpenSP by running the following commands:

sed -i 's/32,/253,/' lib/Syntax.cxx &&
sed -i 's/LITLEN          240 /LITLEN          8092/' \
    unicode/{gensyntax.pl,unicode.syn} &&

./configure --prefix=/usr                              \
            --disable-static                           \
            --disable-doc-build                        \
            --enable-default-catalog=/etc/sgml/catalog \
            --enable-http                              \
            --enable-default-search-path=/usr/share/sgml &&

make pkgdatadir=/usr/share/sgml/OpenSP-1.5.2

To test the results, issue: make check. As many as nine of the 23 tests may fail. Do not be alarmed.

Now, as the root user:

make pkgdatadir=/usr/share/sgml/OpenSP-1.5.2 \
     docdir=/usr/share/doc/OpenSP-1.5.2      \
     install &&

ln -v -sf onsgmls   /usr/bin/nsgmls   &&
ln -v -sf osgmlnorm /usr/bin/sgmlnorm &&
ln -v -sf ospam     /usr/bin/spam     &&
ln -v -sf ospcat    /usr/bin/spcat    &&
ln -v -sf ospent    /usr/bin/spent    &&
ln -v -sf osx       /usr/bin/sx       &&
ln -v -sf osx       /usr/bin/sgml2xml &&
ln -v -sf libosp.so /usr/lib/libsp.so

Command Explanations

sed -i ‘s/32,/253,/…unicode.syn}: These seds prevent some annoying messages that may otherwise appear while running openjade.

--disable-static: This switch prevents installation of static versions of the libraries.

--enable-http: This switch adds support for HTTP.

--disable-doc-build: This switch prevents the configure script checking if you have xmlto installed. If you have xmlto, you can remove this option.

--enable-default-catalog=/etc/sgml/catalog: This switch sets the path to the centralized catalog.

--enable-default-search-path: This switch sets the default value of SGML_SEARCH_PATH.

--enable-xml-messages: This switch adds support for XML Formatted Messages.

make pkgdatadir=/usr/share/sgml/OpenSP-1.5.2 : This sets the pkgdatadir variable in the Makefile from /usr/share/OpenSP to /usr/share/sgml/OpenSP-1.5.2.

ln -v -sf …: These commands create the SP equivalents of OpenSP executables and libraries.

Contents

Installed Programs: onsgmls, osgmlnorm, ospam, ospcat, ospent, osx, and the SP equivalent symlinks: nsgmls, sgml2xml, sgmlnorm, spam, spcat, spent, and sx

Installed Library: libosp.so and the SP equivalent symlink: libsp.so

Installed Directories: /usr/include/OpenSP, /usr/share/doc/OpenSP, and /usr/share/sgml/OpenSP-1.5.2

Short Descriptions

onsgmls is used to process SGML files.

osgmlnorm prints on the standard output a normalized document instance for the SGML document contained in the concatenation of the entities with system identifiers .nf and .fi.

ospam is a markup stream editor.

ospcat prints effective system identifiers found in the catalogs.

ospent provides access to OpenSP’s entity manager.

osx is an SGML normalizer or used to convert SGML files to XML files.

nsgmls is a symlink to onsgmls.

sgml2xml is a symlink to osx.

sgmlnorm is a symlink to osgmlnorm.

spam is a symlink to ospam.

spcat is a symlink to ospcat.

spent is a symlink to ospent.

sx is a symlink to osx.

libosp.so contains functions required by the OpenSP programs to parse, validate and manipulate SGML and XML files.

libsp.so is a symlink to libosp.so.

48.5 OpenJade-1.3.2

Introduction to OpenJade

The OpenJade package contains a DSSSL engine. This is useful for SGML and XML transformations into RTF, TeX, SGML and XML.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

Additional Download

OpenJade Dependencies

Required

OpenSP-1.5.2

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/openjade

Installation of OpenJade

First fix problems when building with newer compilers:

patch -Np1 -i ../openjade-1.3.2-upstream-1.patch

Now fix a compilation problem with perl-5.16 and later:

sed -i -e '/getopts/{N;s#&G#g#;s#do .getopts.pl.;##;}' \
       -e '/use POSIX/ause Getopt::Std;' msggen.pl

Install OpenJade by running the following commands:

export CXXFLAGS="${CXXFLAGS:--O2 -g} -fno-lifetime-dse"            &&
./configure --prefix=/usr                                \
            --mandir=/usr/share/man                      \
            --enable-http                                \
            --disable-static                             \
            --enable-default-catalog=/etc/sgml/catalog   \
            --enable-default-search-path=/usr/share/sgml \
            --datadir=/usr/share/sgml/openjade-1.3.2   &&
make

This package does not come with a test suite.

Now, as the root user:

make install                                                   &&
make install-man                                               &&
ln -v -sf openjade /usr/bin/jade                               &&
ln -v -sf libogrove.so /usr/lib/libgrove.so                    &&
ln -v -sf libospgrove.so /usr/lib/libspgrove.so                &&
ln -v -sf libostyle.so /usr/lib/libstyle.so                    &&

install -v -m644 dsssl/catalog /usr/share/sgml/openjade-1.3.2/ &&

install -v -m644 dsssl/*.{dtd,dsl,sgm}              \
    /usr/share/sgml/openjade-1.3.2                             &&

install-catalog --add /etc/sgml/openjade-1.3.2.cat  \
    /usr/share/sgml/openjade-1.3.2/catalog                     &&

install-catalog --add /etc/sgml/sgml-docbook.cat    \
    /etc/sgml/openjade-1.3.2.cat

Command Explanations

export CXXFLAGS=…: This command prevents segmentation faults when the package is compiled with gcc-6.1.

make install-man: This command installs the openjade man page.

--disable-static: This switch prevents the building of the static library.

--enable-http: This switch adds support for HTTP.

--enable-default-catalog=/etc/sgml/catalog: This switch sets the path to the centralized catalog.

--enable-default-search-path: This switch sets the default value of SGML_SEARCH_PATH.

--datadir=/usr/share/sgml/openjade-1.3.2: This switch puts data files in /usr/share/sgml/openjade-1.3.2 instead of /usr/share.

ln -v -sf …: These commands create the Jade equivalents of OpenJade executables and libraries.

Configuring OpenJade

Configuration Information

As the root user:

echo "SYSTEM \"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd\" \
    \"/usr/share/xml/docbook/xml-dtd-4.5/docbookx.dtd\"" >> \
    /usr/share/sgml/openjade-1.3.2/catalog

This configuration is only necessary if you intend to use OpenJade to process the BLFS XML files through DSSSL Stylesheets.

Contents

Installed Programs: openjade and the Jade equivalent symlink, jade

Installed Libraries: libogrove.so, libospgrove.so, libostyle.so, and the Jade equivalent symlinks: libgrove.so, libspgrove.so, and libstyle.so

Installed Directory: /usr/share/sgml/openjade-1.3.2

Short Descriptions

openjade is a DSSSL engine used for transformations.

jade is a symlink to openjade.

48.6 docbook-dsssl-1.79

Introduction to DocBook DSSSL Stylesheets

The DocBook DSSSL Stylesheets package contains DSSSL stylesheets. These are used by OpenJade or other tools to transform SGML and XML DocBook files.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

Additional Downloads

Documentation and test data

DocBook DSSSL Stylesheets Dependencies

Required

sgml-common-0.6.3

Required (to Test the DocBook SGML Toolchain)

docbook-3.1-dtd, docbook-4.5-dtd, OpenSP-1.5.2, and OpenJade-1.3.2

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/docbook-dsssl

Installation of DocBook DSSSL Stylesheets

If you downloaded the documentation, run:

tar -xf ../docbook-dsssl-doc-1.79.tar.bz2 --strip-components=1

Install DocBook DSSSL Stylesheets by running the following commands as the root user:

install -v -m755 bin/collateindex.pl /usr/bin                      &&
install -v -m644 bin/collateindex.pl.1 /usr/share/man/man1         &&
install -v -d -m755 /usr/share/sgml/docbook/dsssl-stylesheets-1.79 &&
cp -v -R * /usr/share/sgml/docbook/dsssl-stylesheets-1.79          &&

install-catalog --add /etc/sgml/dsssl-docbook-stylesheets.cat \
    /usr/share/sgml/docbook/dsssl-stylesheets-1.79/catalog         &&

install-catalog --add /etc/sgml/dsssl-docbook-stylesheets.cat \
    /usr/share/sgml/docbook/dsssl-stylesheets-1.79/common/catalog  &&

install-catalog --add /etc/sgml/sgml-docbook.cat              \
    /etc/sgml/dsssl-docbook-stylesheets.cat

Command Explanations

The above commands create an installation script for this package.

Testing the DocBook SGML Toolchain (Optional)

The following commands will perform the necessary tests to confirm that your installed DocBook SGML toolchain will produce desired results. You must have the docbook-3.1-dtd, docbook-4.5-dtd, OpenSP-1.5.2, and OpenJade-1.3.2 packages installed, and perform the tests as the root user.

All tests will be performed from the /usr/share/sgml/docbook/dsssl-stylesheets-1.79/doc/testdata directory as the root user:

cd /usr/share/sgml/docbook/dsssl-stylesheets-1.79/doc/testdata

The first test should produce no output to stdout (your screen) and create a file named jtest.rtf in the current directory:

openjade -t rtf -d jtest.dsl jtest.sgm

The next test should return only the following line to stdout: onsgmls:I: "OpenSP" version "1.5.2"

onsgmls -sv test.sgm

The next test should produce no output to stdout and create a file named test.rtf in the current directory:

openjade -t rtf \
    -d /usr/share/sgml/docbook/dsssl-stylesheets-1.79/print/docbook.dsl \
    test.sgm

The last test should produce no output to stdout and create a file named c1.htm in the current directory:

openjade -t sgml \
    -d /usr/share/sgml/docbook/dsssl-stylesheets-1.79/html/docbook.dsl \
    test.sgm

Finally, clean up:

rm jtest.rtf test.rtf c1.htm

Contents

Installed Program: collateindex.pl

Installed Libraries: None

Installed Files: DSSSL stylesheets

Installed Directory: /usr/share/sgml/docbook/dsssl-stylesheets-1.79

Short Descriptions

collateindex.pl is a Perl script that creates a DocBook index from raw index data.

48.7 DocBook-utils-0.6.14

Introduction to DocBook-utils

The DocBook-utils package is a collection of utility scripts used to convert and analyze SGML documents in general, and DocBook files in particular. The scripts are used to convert from DocBook or other SGML formats into “classical” file formats like HTML, man, info, RTF and many more. There’s also a utility to compare two SGML files and only display the differences in markup. This is useful for comparing documents prepared for different languages.

This package is known to build and work properly using an LFS 11.3 platform.

Package Information

Additional Downloads

DocBook-utils Dependencies

Required

OpenJade-1.3.2, docbook-dsssl-1.79, and docbook-3.1-dtd

Optional (Runtime Dependencies Only)

SGMLSpm-1.1 (for conversion to man and texinfo), and Lynx-2.8.9rel.1 or Links-2.28 or W3m (for conversion to ASCII text)

User Notes: https://wiki.linuxfromscratch.org/blfs/wiki/docbook-utils

Installation of DocBook-utils

Install DocBook-utils by running the following commands:

patch -Np1 -i ../docbook-utils-0.6.14-grep_fix-1.patch &&
sed -i 's:/html::' doc/HTML/Makefile.in                &&

./configure --prefix=/usr --mandir=/usr/share/man      &&
make

This package does not come with a test suite.

Now, as the root user:

make docdir=/usr/share/doc install

Many packages use an alternate name for the DocBook-utils scripts. If you wish to create these alternate names, use the following command as the root user:

for doctype in html ps dvi man pdf rtf tex texi txt
do
    ln -svf docbook2$doctype /usr/bin/db2$doctype
done

Note

The jw script uses the which command to locate required utilities. You must install Which-2.21 before attempting to use any of the DocBook-utils programs.

Command Explanations

patch -Np1 -i ../docbook-utils-0.6.14-grep_fix-1.patch: This patch corrects the syntax in the jw (Jade Wrapper) script which is at the heart of much db2* processing, so that the current version of grep will not reject it.

sed -i ‘s:/html::’ doc/HTML/Makefile.in: This command changes the installation directory of the HTML documents.

docdir=/usr/share/doc: This option is placed on the make install line because is is not recognized by configure.

Contents

Installed Programs: docbook2dvi, docbook2html, docbook2man, docbook2pdf, docbook2ps, docbook2rtf, docbook2tex, docbook2texi, docbook2txt, jw, and sgmldiff

Installed Libraries: None

Installed Directories: /usr/share/doc/docbook-utils-0.6.14 and /usr/share/sgml/docbook/utils-0.6.14

Installed Symlinks: db2dvi, db2html, db2man, db2pdf, db2ps, db2rtf, db2tex, db2texi, and db2txt

Short Descriptions

docbook2* are simple one-line wrapper scripts to jw. They are provided as easy-to-remember names used to convert DocBook or other SGML files to the respective format.

db2* are symlinks pointing at the respectively named docbook2* commands, created to satisfy some program’s use of these names.

jw is a script used to convert DocBook or other SGML files to various output formats. It hides most of OpenJade’s complexity and adds comfortable features.

sgmldiff is used to compare two SGML files and only return the differences in the markup. This is especially useful to compare files that should be identical except for language differences in the content.