AUTHOR: Gregory Davis <gregdavis at ieee dot org>
DATE: 2003-10-31
LICENSE: GNU Free Documentation License, Version 1.2
SYNOPSIS: Install supporting software to enable building of the Linux kernel documentation.
DESCRIPTION:
Lots of obscure software is required to build the Linux kernel
documentation into man, html, ps, or pdf format. This hint provides
instruction as to which packages are needed, how to install them, and how to
modify the kernel Makefiles in order to build properly. Probably only people
doing system level programming, or kernel programming will need these docs.
PREREQUISITES:
Docbook DSSSL stylesheets, SGML DTDs, and TeTeX 2.0.2 must be installed
according to BLFS (http://beyond.linuxfromscratch.org). In addition, a
kernel source tree is required, and recommended that it be from
http://www.kernel.org. This hint refers to 2.4.18 and 2.6.0-test8.
HINT:
Introduction
=============
Building the kernel does not require software beyond a base development
workstation (see http://www.linuxfromscratch.org). On the other hand,
building the kernel documentation requires that you install various
typesetting and parser programs. Additionally, the kernel documentation may
be, at times, broken! Broken documentation can be easily fixed with a plain
text editor and no prior knowledge of SGML (what is SGML anyway).
Download
========
Docbook-Utils, contains ``docbook2..." tools
ftp://sources.redhat.com/pub/docbook-tools/
new-trials/SOURCES/docbook-utils-0.6.13.tar.gz
af785716b207a7a562551851298a3b1a docbook-utils-0.6.13.tar.gz
SGMLS.PM, SGML perl class library for (N)SGMLS parser(s)
ftp://sources.redhat.com/pub/docbook-tools/
new-trials/SOURCES/SGMLSpm-1.03ii.tar.gz
5bcb197fd42e67d51c739b1414d514a7 SGMLSpm-1.03ii.tar.gz
JadeTex (3.13), linkage from TeX to pdf (needed for pdf docs)
http://sourceforge.net/project/showfiles.php?group_id=28782
Installing the Packages
=======================
Docbook-Utils:
$ cd docbook-utils-0.6.13
$ ./configure --prefix=/usr && make && make install
SGMLS.PM:
Note, simply typing make will automatically install the library and its docs.
$ cd SGMLS.PM
$ make BINDIR=/usr/bin PERL5DIR=/usr/lib/perl5/5.8.0 install
JadeTex:
Find the file ``texmf.cnf" (probably at /usr/share/texmf/texmf.cnf).
If the first line says ``% TeX Live texmf.cnf", go straight to ``make
install" in the jadetex-3.13 directory. If it says ``original" after the
``%", remove the ``original" completely from the first line, and tack this
onto the bottom:
%% beginning of JadeTex additions
% latex settings
main_memory.latex = 1100000
param_size.latex = 1500
stack_size.latex = 1500
hash_extra.latex = 15000
string_vacancies.latex = 45000
pool_free.latex = 47500
nest_size.latex = 500
save_size.latex = 5000
pool_size.latex = 500000
max_strings.latex = 55000
font_mem_size.latex= 400000
% jadetex & pdfjadetex
main_memory.jadetex = 1500000
param_size.jadetex = 1500
stack_size.jadetex = 1500
hash_extra.jadetex = 50000
string_vacancies.jadetex = 45000
pool_free.jadetex = 47500
nest_size.jadetex = 500
save_size.jadetex = 5000
pool_size.jadetex = 500000
max_strings.jadetex = 55000
main_memory.pdfjadetex = 2500000
param_size.pdfjadetex = 1500
stack_size.pdfjadetex = 1500
hash_extra.pdfjadetex = 50000
string_vacancies.pdfjadetex = 45000
pool_free.pdfjadetex = 47500
nest_size.pdfjadetex = 500
save_size.pdfjadetex = 5000
pool_size.pdfjadetex = 500000
max_strings.pdfjadetex = 55000
%% end of JadeTex additions
Now reconfigure your TeTeX installation...
$ cp -R /usr/share/texmf/tex/latex/config /tmp
$ cd /tmp/config
$ tex -ini -progname=latex latex.ini
$ mv /usr/share/texmf/web2c/latex.fmt /usr/share/texmf/web2c/latex.fmt.orig
$ mv latex.fmt /usr/share/texmf/web2c
$ rm -rf /tmp/config
Now install JadeTex, it automatically finds the right install path...
$ cd jadetex-3.13
$ make install
Convincing the Kernel
=====================
If $SRC is the path to the top-level directory of the kernel source tree,
the kernel's documentation is found in $SRC/Documentation/DocBook. There
is a Makefile in there that needs some spanking. The basic idea is thus:
2.4.x:
First, the kernel looks for db2(html), but docbook-utils installs
docbook2(html). Next, the docbook2html command needs to know where the
default stylesheet and respective declaration file are located. The
docbook2{ps,pdf} commands share a common stylesheet that is different from
the html one. Lastly, the 2.4.x kernel Makefile fails to create a new
subdirectory for each documentation book (i.e. parport, kernel-api, ...).
These problems and more resolved in the patch-file linux-2.4.18-docs.patch.
2.6.x:
Same problems as before, in the same Makefile, except for the subdirectory
creation. Fixed in linux-2.6.0-test8-docs.patch.
Conclusion
===========
Now in your $SRC/ kernel-toplevel-directory, you can execute ``make
{html,ps,pdf}docs" and useful things will come about from it. If you have
a 2.6 kernel, you can also run ``make mandocs". If any of the builds
fails with an error like:
jade:$SRC/Documentation/DocBook/deviceiobook.sgml:229:11:E: end tag for
"CHAPTER" which is not finished
make[1]: *** [deviceiobook.html] Error 8
make[1]: Leaving directory `$SRC/Documentation/DocBook'
make: *** [htmldocs] Error 2
Open deviceiobook.sgml, go to line 229, and put some stuff between
</title> and </chapter>. I like to put:
<para>
None.
</para>
Then only retype the offending make command (i.e. make htmldocs). This is
probably because somebody didn't put his/her code documents in the right
format.
TODO
=====
Testing. Provide a docbook2man rule in Makefile for 2.4.x kernel if one is
not made soon.
CHANGELOG:
[2003-10-31]
* Started hint