docs/docbook/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
   9 What are DocBook documents doing in the Samba Distribution ?
  10 -----------------------------------------------------------
  11
  12 We have converted all samba docs to XML/DocBook V4.2
  13 in order to make them easier to maintain and produce a nicer looking
  14 product.
  15
  16 This short note (strange isn't it how it always starts out as a short note
  17 and becomes a long one ?) will explain very briefly how and why we have
  18 done this.
  19
  20
  21 The format
  22 ----------
  23 If you are new to xml, regard an xml file as 'source code'. You don't
  24 read it directly, but use it to create other formats (like the txt and html
  25 included in ../txtdocs and ../htmldocs).
  26
  27 Docbook is a particular XML style, particularly suited to producing
  28 technical manuals.
  29
  30 For more information on DocBook tags and format, see "DocBook: The
  31 Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
  32 This book covers DocBook V4.2 and is available on-line
  33 at http://www.docbook.org/
  34
  35 The Output
  36 ----------
  37 The current Samba CVS tree contains the XML/DocBook source files as well
  38 as the following autogenerated formats:
  39
  40   * man pages
  41   * HTML
  42   * PDF
  43
  44 The following formats are not available in CVS but can be generated by
  45 the build scripts:
  46
  47   * PostScript
  48   * DVI
  49   * LaTeX
  50   * ASCII text
  51
  52 The Tools
  53 ---------
  54
  55 To generate the docs, you need to have the following packages installed:
  56
  57  * docbook-utils
  58  * xsltproc
  59  * pngtopnm and pnmtops (from the netpbm utilities)
  60
  61 For generating PDF (thru LaTeX):
  62  * pdflatex
  63
  64 For generating PostScript (thru LaTeX):
  65  * latex
  66  * dvips
  67
  68 For generating ASCII:
  69  * xmlto
  70
  71 This directory now contains a ./configure script and Makefile to
  72 support the automated building of man pages (including HTML versions), and
  73 the building of the Samba-HOWTO-Collection and the
  74 Samba Developers Guide (HTML,DVI,TeX,PDF,PS,Text versions).