docs/docbook.txt

   1 !==
   2 !== docbook.txt for Samba 3.0
   3 !==
   4 !== Author:     David Bannon, D.Bannon@latrobe.edu.au  November, 2000
   5 !== Updates:    Gerald (Jerry) Carter, jerry@samba.org, Feb. 2001
   6 !== Updates:    Jelmer Vernooij, jelmer@samba.org,              Aug, 2002
   7 !== Updates:    Jelmer Vernooij, jelmer@samba.org,              Jun, 2003
   8 !== Updates:    Jelmer Vernooij, jelmer@samba.org,              May, 2004
   9
  10 What are DocBook documents doing in the Samba Distribution ?
  11 -----------------------------------------------------------
  12
  13 We have converted all samba docs to XML/DocBook V4.2
  14 in order to make them easier to maintain and produce a nicer looking
  15 product.
  16
  17 This short note (strange isn't it how it always starts out as a short note
  18 and becomes a long one ?) will explain very briefly how and why we have
  19 done this.
  20
  21
  22 The format
  23 ----------
  24 If you are new to xml, regard an xml file as 'source code'. You don't
  25 read it directly, but use it to create other formats (like the txt and html
  26 included in ../txtdocs and ../htmldocs).
  27
  28 Docbook is a particular XML style, particularly suited to producing
  29 technical manuals.
  30
  31 For more information on DocBook tags and format, see "DocBook: The
  32 Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
  33 This book covers DocBook V4.2 and is available on-line
  34 at http://www.docbook.org/
  35
  36 The Output
  37 ----------
  38 The current Samba CVS tree contains the XML/DocBook source files.
  39
  40 A regularly generated version can be found at http://samba.org/samba/docs/.
  41
  42 The Tools
  43 ---------
  44
  45 To generate the docs, you need to have the following packages installed:
  46
  47  * autoconf
  48  * docbook-utils
  49  * xsltproc
  50  * pngtopnm and pnmtops (from the netpbm utilities)
  51
  52 For generating PDF (thru LaTeX):
  53  * db2latex (from http://db2latex.sf.net/). Make sure to get CVS version
  54    dated 20030622 -- it works best. Versions previous to 20030425 are known
  55    to have problems, as well as current (as of 20031210) snapshots.
  56  * pdflatex
  57
  58 For generating PostScript (thru LaTeX):
  59  * latex
  60  * dvips
  61
  62 For generating ASCII:
  63  * xmlto
  64
  65 This directory now contains a ./configure script and Makefile to
  66 support the automated building of man pages (including HTML versions), and
  67 the building of the Samba-HOWTO-Collection and the
  68 Samba Developers Guide (HTML,DVI,TeX,PDF,PS,Text versions).
  69
  70 The configure script detects which of the required utilities are installed
  71 and builds as much docs as it can using these tools.