AUTHOR: Gregory Davis 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 and . I like to put: None. 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