Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"
Linux Tracker

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
Copyright Info
Terms of Use
Privacy Info
Masthead / Impressum
Your Account

Private Messages

News Archive
Submit News
User Articles
Web Links


The Web

Who's Online
There are currently, 111 guest(s) and 0 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here



Current HOWTO: DocBook-Install

Install the Packages

3. Install the Packages

3.1. Before You Install

The following sections suggest how you might install the downloaded packages to setup your DocBook SGML environment. The examples may make reference to old versions of the packages but you should adapt the examples and use the most recent versions instead.

For the most up-to-date, authoritative information, always read the documentation that comes with a package you are installing. Often, you will find a README and a INSTALL file after you unpack an archive.

The detailed instructions below may not work exactly as shown since packages are changing all the time. However, the instructions should still give you a general idea of the procedure to get DocBook SGML working.

3.2. Install OpenJade

3.2.1. openjade

Here is what to do, but remember to read the files that come with OpenJade to see if there are any things you want to do special for your platform:

		cd /usr/local
		tar -xvzf ~/openjade-1.3.tar.gz
		cd openjade-1.3
		./configure --prefix=/usr/local/openjade-1.3
		make install

		# Once installed, the objects etc. can be deleted.
		make clean
The installation puts libraries in /usr/local/openjade-1.3/lib, so you might like to add it to /etc/ld.so.conf and run ldconfig. Add /usr/local/openjade-1.3/bin to your $PATH.

You might be wondering why I dump the openjade source directly into /usr/local. The author experienced some issues with openjade's installation. However, with newer releases of OpenJade, you might try a standard (/usr/local/src) location for the openjade source package with some other prefix install location, and see how it goes.

3.2.2. jadetex & pdfjadetex

As mentioned, jadetex and pdfjadetex are TeX macros that are packaged with OpenJade. They can be found in /usr/local/openjade-3.1/dsssl. A handy guide to installing these macros was prepared by Frank Atanassow Christoph and can be found at:



The following is based on the instructions in install.pdf: Create hugelatex (if needed)

The jadetex and pdfjadetex tex macros require more memory than a regular run of tex. The default tex memory limit configuration is often too limited. The tex configuration file, texmf.cnf, can be edited and variables which limit tex's memory use can be increased. But rather than just editing the texmf.cnf file to allow tex in all instances to have more memory, a custom tex context can be created, called hugelatex. If hugelatex is already configured on your system, you can skip this subsection (which hugelatex).

Verify that a working TeX is installed and find its directory:

		bash$ which tex
		bash$ kpsewhich -expand-var='$TEXMFMAIN'

Using which should find the location of the tex program. If its not found, then you might need to install teTeX then return here. kpsewhich is a utility that comes with teTeX and finds the main tex directory if all goes well.

Now that the texmf directory is known, installation can begin:

		cd /usr/share/texmf
		cd tex/latex
		cp -r config config-temp
		cd config-temp
		tex -ini -progname=hugelatex latex.ini
		mv latex.fmt hugelatex.fmt
		mv hugelatex.fmt /usr/share/texmf/web2c
		cd ..
		rm -r config-temp
		cd /usr/share/texmf/bin
		ln -s tex hugelatex
		cd /usr/share/texmf/web2c
The web2c directory contains the texmf.cnf configuration file. Make a backup of this file: cp texmf.cnf texmf.cnf.orig. Edit the file using whatever editor you like, and add the following lines at the end:
		% hugelatex settings
		extra_mem_top.hugelatex = 8000000
		extra_mem_bot.hugelatex = 8000000
		hash_extra.hugelatex = 15000
		pool_size.hugelatex = 5000000
		string_vacancies.hugelatex = 45000
		max_strings.hugelatex = 55000
		pool_free.hugelatex = 47500
		nest_size.hugelatex = 500
		param_size.hugelatex = 1500
		save_size.hugelatex = 5000
		stack_size.hugelatex = 15000

		% jadetex
		extra_mem_top.jadetex = 8000000
		extra_mem_bot.jadetex = 8000000
		hash_extra.jadetex = 20000
		pool_size.jadetex = 5000000
		string_vacancies.jadetex = 45000
		max_strings.jadetex = 55000
		pool_free.jadetex = 47500
		nest_size.jadetex = 500
		param_size.jadetex = 1500
		save_size.jadetex = 5000
		stack_size.jadetex = 15000

		% pdfjadetex
		extra_mem_top.pdfjadetex = 8000000
		extra_mem_bot.pdfjadetex = 8000000
		hash_extra.pdfjadetex = 20000
		pool_size.pdfjadetex = 5000000
		string_vacancies.pdfjadetex = 45000
		max_strings.pdfjadetex = 55000
		pool_free.pdfjadetex = 47500
		nest_size.pdfjadetex = 500
		param_size.pdfjadetex = 1500
		save_size.pdfjadetex = 5000
		stack_size.pdfjadetex = 15000
Here, we've gone ahead and added entries for jadetex and pdfjadetex, which we'll be setting up below. You can play with these memory settings any way you like if you experience trouble with them.

After setting up hugelatex, like above, it may not work until the texhash program is called:

		root# texhash
		texhash: Updating /usr/share/texmf/ls-R...
		texhash: Updating /var/cache/fonts/ls-R...
		texhash: Done.
		root# jadetex & pdfjadetex

Setting up jadetex and pdfjadetex is similar to hugelatex.

		cd /usr/local/openjade-1.3/dsssl
		make -f Makefile.jadetex install
		# make creates and installs the .fmt
		# files to /usr/share/texmf/web2c

		# Now create symlinks ...
		cd /usr/share/texmf/bin
		ln -s tex jadetex
		ln -s pdftex pdfjadetex

		# Finally, run texhash.
		root# texhash
This Makefile uses hugelatex, so hugelatex must have been setup already. When tex is run as hugelatex, jadetex, or pdfjadetex, it gets its program name (context) from argv[0] in the environment. Then, it scans texmf.cnf, and uses any context-specific settings it finds. The format (.fmt) files in /usr/share/texmf/web2c are also loaded based on the context.

The jadetex command takes a tex file generated from openjade, and outputs a dvi file. pdfjadetex takes a tex file generated from openjade, and outputs a pdf. The dvips program takes the dvi file and outputs a PostScript ps file that you can send to your printer or view with ghostscript gs.

3.3. DocBook SGML DTD

3.3.1. Unpack the DocBook SGML DTD

The DocBook DTD is just some sgml text files, so there is nothing to compile. Just unzip them somewhere:

		# DocBook DTD V4.1 in
		# /usr/local/share/sgml/docbook/4.1

		cd /usr/local/share
		mkdir sgml; cd sgml
		mkdir docbook; cd docbook
		mkdir 4.1; cd 4.1
		unzip -a ~/docbk41.zip
If you install doctools-1.2 from the XFree86 distribution, it will put some older versions of DocBook DTD, like 2.4.1/ and 3.0/ in subdirectories of docbook.

There are some differences between the different versions of the DocBook DTD. The xxissues.txt files document those issues. Tags have been added, removed, and renamed between the versions.

If you need to use DocBook DTD V3.1, it is available from the same place where V4.1 is downloaded. V3.1 is used a lot, so its a good idea to get it and install it in a 3.1/ subdirectory.

3.3.2. Unpack the ISO8879 Entities

For each DocBook DTD version unpacked, go into its directory and unpack the iso8879-entities.tar.gz file:

		cd /usr/local/share/sgml/docbook/4.1
		tar -xvzf ~/iso8879-entities.tar.gz
In each DocBook directory, there should be a docbook.cat file or a catalog file, or both. If both are present, they are likely to be identical. If only docbook.cat is present, go ahead and make a symlink:
		# If needed ...
		cd /usr/local/share/sgml/docbook/4.1
		ln -s docbook.cat catalog

3.4. DocBook DSSSL

Installation of the DocBook DSSSL, which works for all versions of DocBook, is just a matter of unzipping it somwhere.

		cd /usr/local/share/sgml
		mkdir dsssl; cd dsssl
		unzip -a ~/db160.zip

		# If you downloaded the ldp.dsl stylesheet
		# customization, copy it to ...
		cd docbook
		cp ~/ldp.dsl html
		cp ~/ldp.dsl print
		# Copy into both directories.
That's all there is to installing the DSSSL, except for the setup of the $SGML_CATALOG_PATH discussed later. Don't forget to straighten out the file modes and owner/group of these unpacked files - often they are scrambled and inappropriate.

3.5. SGMLtools-Lite

If you like it, you can install the SGMLtools-Lite, but it is optional. Its installation is the standard:

		cd /usr/src
		tar -xvzf ~/sgmltools-lite-3.0.2.tar.gz
		cd sgmltools-lite-3.0.2
		make install
This installs the sgmltools python script to /usr/local/bin. Note that it uses python, so if you don't have it, then this package is useless.

One tweak that has to be done to make the sgmltools script work, is you have to edit it and set the path to openjade: vi `which sgmltools`. Consult its docs to learn more about it.

3.6. htmldoc

3.6.1. binary

Preferrably you downloaded a binary distribution of htmldoc for your platform. The installation is straightforward: just unpack it and run the setup. Read the docs in the package for more info.

3.6.2. source

If you downloaded the source, you will also need the Fast Light Tool Kit or else it will not link:


Installation is autoconf style. Just run the configure script, make, make install. If all goes well, it will install in /usr/bin.

3.6.3. ldp_print

The htmldoc program has (or had) a few glitches when generating output from html files from openjade. For instance, bullet items are not rendered properly and shaded areas are not always shaded.

To fix this problem, a perl script (ldp_print) is available from LinuxDoc.org. The lpd_print script processes a nochunks html file from openjade and then runs htmldoc on it to produce correctly rendered pdf and ps.


Get it!

		tar -xvzf ldp_print.tar.gz
		cd ldp_print

		# Copy the lib somewhere where perl looks.
		cp fix_print_html.lib /usr/lib/perl5/site_perl

		cp ldp_print /usr/local/bin
Take a look at the script in case there are lines in it you need to change for your system. Perhaps someday htmldoc's bugs will be fixed and this script will not be needed anymore.

3.7. DocBook2X and SGMLS.pm (sgmlspl)

3.7.1. sgmlspl

Before the spec files from DocBook2X are of any use, the SGMLS.pm module for perl version 5 has to be installed, assuming that perl version 5 is installed. The installation of this module is not as automated as most perl module installs. It uses a Makefile that has to be edited first before running make.

		cd /usr/src
		tar -xvzf ~/SGMLSpm-1.03ii.tar.gz
		cd SGMLSpm

		# Edit Makfile
		vi Makefile
		# In the user options of the Makefile
		# set everything correct for
		# your system.
		# Example:
		#	PERL = /usr/bin/perl
		#	BINDIR = /usr/local/bin
		#	PERL5DIR = /usr/lib/perl5/site_perl
		#	HTMLDIR= /usr/local/apache/htdocs

		make install
sgmlspl gets copied to /usr/local/bin.

3.7.2. docbook2X (docbook2man-spec.pl)

DocBook2X contains no program to compile or install, though it has some scripts you might want to look at, so all there is to do is unpack it somwhere.

		cd /usr/local/share/sgml
		tar -xvzf ~/docbook2X-0.6.0.tar.gz
		cd docbook2X
In the unpacked directory is the docbook2man-spec.pl and a patch file for it that corrects a few things. Applying the patch is optional but recommended.
		patch docbook2man-spec.pl docbook2man-spec.pl.patch
Later, in Using DocBook, you will see how to use sgmlspl and docbook2man-spec.pl to generate a man page from a <refentry> DocBook document.


The $SGML_CATALOG_FILES environment variable is used by openjade (and other SGML software) to locate DTDs and DSL (stylesheets). SGML software cannot function without finding these files, which have been unpacked to various directories. Given the setup as done so far, here is how $SGML_CATALOG_FILES can be set in /etc/profile:

# SGML DocBook - openjade sgmltools-lite


# DSSSL stylesheets
#       Norman Walsh's Modular DocBook Stylesheets
#       OpenJade stylesheets
#       sgmltools-lite's stylesheets

# DocBook DTD
#       From OASIS-Open.org
#       These old ones were installed with doctools-1.2 from XFree86.org

# sgmltools-lite catalogs for LinuxDoc

Save your profile, logout and then log back in to take effect.

Installation is complete! In the next section, we'll test the installation and convert some test DocBook files.

The Linux Tutorial completely respects the rights of authors and artists to decide for themselves if and how their works can be used, independent of any existing licenses. This means if you are the author of any document presented on this site and do no wish it to be displayed as it is on this site or do not wish it to be displayed at all, please contact us and we will do our very best to accommodate you. If we are unable to accommodate you, we will, at your request, remove your document as quickly as possible.

If you are the author of any document presented on this site and would like a share of the advertising revenue, please contact us using the standard Feedback Form.

Show your Support for the Linux Tutorial

Purchase one of the products from our new online shop. For each product you purchase, the Linux Tutorial gets a portion of the proceeds to help keep us going.



Security Code
Security Code
Type Security Code

Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!

Amazon Wish List

Did You Know?
The Linux Tutorial welcomes your suggestions and ideas.


Tell a Friend About Us

Bookmark and Share

Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.15 Seconds