kernel_documentation.txt

   1 AUTHOR:  Gregory Davis <gregdavis at ieee dot org>
   2
   3 DATE:  2003-10-31
   4
   5 LICENSE:  GNU Free Documentation License, Version 1.2
   6
   7 SYNOPSIS: Install supporting software to enable building of the Linux kernel documentation.
   8
   9 DESCRIPTION:
  10 Lots of obscure software is required to build the Linux kernel
  11 documentation into man, html, ps, or pdf format.  This hint provides
  12 instruction as to which packages are needed, how to install them, and how to
  13 modify the kernel Makefiles in order to build properly.  Probably only people
  14 doing system level programming, or kernel programming will need these docs.
  15
  16
  17 PREREQUISITES:
  18 Docbook DSSSL stylesheets, SGML DTDs, and TeTeX 2.0.2 must be installed
  19 according to BLFS (http://beyond.linuxfromscratch.org).  In addition, a
  20 kernel source tree is required, and recommended that it be from
  21 http://www.kernel.org.  This hint refers to 2.4.18 and 2.6.0-test8.
  22
  23 HINT:
  24
  25 Introduction
  26 =============
  27 Building the kernel does not require software beyond a base development
  28 workstation (see http://www.linuxfromscratch.org).  On the other hand,
  29 building the kernel documentation requires that you install various
  30 typesetting and parser programs.  Additionally, the kernel documentation may
  31 be, at times, broken!  Broken documentation can be easily fixed with a plain
  32 text editor and no prior knowledge of SGML (what is SGML anyway).
  33
  34 Download
  35 ========
  36 Docbook-Utils, contains ``docbook2..." tools
  37 ftp://sources.redhat.com/pub/docbook-tools/
  38 new-trials/SOURCES/docbook-utils-0.6.13.tar.gz
  39 af785716b207a7a562551851298a3b1a  docbook-utils-0.6.13.tar.gz
  40
  41 SGMLS.PM, SGML perl class library for (N)SGMLS parser(s)
  42 ftp://sources.redhat.com/pub/docbook-tools/
  43 new-trials/SOURCES/SGMLSpm-1.03ii.tar.gz
  44 5bcb197fd42e67d51c739b1414d514a7  SGMLSpm-1.03ii.tar.gz
  45
  46 JadeTex (3.13), linkage from TeX to pdf (needed for pdf docs)
  47 http://sourceforge.net/project/showfiles.php?group_id=28782
  48
  49 Installing the Packages
  50 =======================
  51 Docbook-Utils:
  52 $ cd docbook-utils-0.6.13
  53 $ ./configure --prefix=/usr && make && make install
  54
  55 SGMLS.PM:
  56 Note, simply typing make will automatically install the library and its docs.
  57 $ cd SGMLS.PM
  58 $ make BINDIR=/usr/bin PERL5DIR=/usr/lib/perl5/5.8.0 install
  59
  60 JadeTex:
  61 Find the file ``texmf.cnf" (probably at /usr/share/texmf/texmf.cnf).
  62 If the first line says ``% TeX Live texmf.cnf", go straight to ``make
  63 install" in the jadetex-3.13 directory.  If it says ``original" after the
  64 ``%", remove the ``original" completely from the first line, and tack this
  65 onto the bottom:
  66
  67 %% beginning of JadeTex additions
  68 % latex settings
  69 main_memory.latex = 1100000
  70 param_size.latex = 1500
  71 stack_size.latex = 1500
  72 hash_extra.latex = 15000
  73 string_vacancies.latex = 45000
  74 pool_free.latex = 47500
  75 nest_size.latex = 500
  76 save_size.latex = 5000
  77 pool_size.latex = 500000
  78 max_strings.latex = 55000
  79 font_mem_size.latex= 400000
  80
  81 % jadetex & pdfjadetex
  82 main_memory.jadetex = 1500000
  83 param_size.jadetex = 1500
  84 stack_size.jadetex = 1500
  85 hash_extra.jadetex = 50000
  86 string_vacancies.jadetex = 45000
  87 pool_free.jadetex = 47500
  88 nest_size.jadetex = 500
  89 save_size.jadetex = 5000
  90 pool_size.jadetex = 500000
  91 max_strings.jadetex = 55000
  92
  93 main_memory.pdfjadetex = 2500000
  94 param_size.pdfjadetex = 1500
  95 stack_size.pdfjadetex = 1500
  96 hash_extra.pdfjadetex = 50000
  97 string_vacancies.pdfjadetex = 45000
  98 pool_free.pdfjadetex = 47500
  99 nest_size.pdfjadetex = 500
 100 save_size.pdfjadetex = 5000
 101 pool_size.pdfjadetex = 500000
 102 max_strings.pdfjadetex = 55000
 103 %% end of JadeTex additions
 104
 105 Now reconfigure your TeTeX installation...
 106 $ cp -R /usr/share/texmf/tex/latex/config /tmp
 107 $ cd /tmp/config
 108 $ tex -ini -progname=latex latex.ini
 109 $ mv /usr/share/texmf/web2c/latex.fmt /usr/share/texmf/web2c/latex.fmt.orig
 110 $ mv latex.fmt /usr/share/texmf/web2c
 111 $ rm -rf /tmp/config
 112
 113 Now install JadeTex, it automatically finds the right install path...
 114 $ cd jadetex-3.13
 115 $ make install
 116
 117 Convincing the Kernel
 118 =====================
 119 If $SRC is the path to the top-level directory of the kernel source tree,
 120 the kernel's documentation is found in $SRC/Documentation/DocBook.  There
 121 is a Makefile in there that needs some spanking.  The basic idea is thus:
 122
 123 2.4.x:
 124 First, the kernel looks for db2(html), but docbook-utils installs
 125 docbook2(html).  Next, the docbook2html command needs to know where the
 126 default stylesheet and respective declaration file are located.  The
 127 docbook2{ps,pdf} commands share a common stylesheet that is different from
 128 the html one.  Lastly, the 2.4.x kernel Makefile fails to create a new
 129 subdirectory for each documentation book (i.e. parport, kernel-api, ...).
 130 These problems and more resolved in the patch-file linux-2.4.18-docs.patch.
 131
 132 2.6.x:
 133 Same problems as before, in the same Makefile, except for the subdirectory
 134 creation.  Fixed in linux-2.6.0-test8-docs.patch.
 135
 136 Conclusion
 137 ===========
 138 Now in your $SRC/ kernel-toplevel-directory, you can execute ``make
 139 {html,ps,pdf}docs" and useful things will come about from it.  If you have
 140 a 2.6 kernel, you can also run ``make mandocs".  If any of the builds
 141 fails with an error like:
 142
 143 jade:$SRC/Documentation/DocBook/deviceiobook.sgml:229:11:E: end tag for
 144 "CHAPTER" which is not finished
 145 make[1]: *** [deviceiobook.html] Error 8
 146 make[1]: Leaving directory `$SRC/Documentation/DocBook'
 147 make: *** [htmldocs] Error 2
 148
 149 Open deviceiobook.sgml, go to line 229, and put some stuff between
 150 </title> and </chapter>.  I like to put:
 151
 152 <para>
 153 None.
 154 </para>
 155
 156 Then only retype the offending make command (i.e. make htmldocs).  This is
 157 probably because somebody didn't put his/her code documents in the right
 158 format.
 159
 160 TODO
 161 =====
 162 Testing.  Provide a docbook2man rule in Makefile for 2.4.x kernel if one is
 163 not made soon.
 164
 165
 166 CHANGELOG:
 167 [2003-10-31]
 168 * Started hint