cvs commit: hints kernel_documentation.txt

tushar at linuxfromscratch.org tushar at linuxfromscratch.org
Fri Oct 31 21:01:12 PST 2003


tushar      03/10/31 22:01:12

  Added:       .        kernel_documentation.txt
  Log:
  Added Hint: kernel_documentation
  
  Revision  Changes    Path
  1.1                  hints/kernel_documentation.txt
  
  Index: kernel_documentation.txt
  ===================================================================
  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
  
  
  



More information about the hints mailing list