docs/docbook/docbook.txt

   1 !==
   2 !== docbook.txt for Samba HEAD
   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
   8 What are DocBook documents doing in the Samba Distribution ?
   9 -----------------------------------------------------------
  10
  11 We are planning to convert all of the samba docs to SGML/DocBook V4.1
  12 in order to make them easier to maintain and produce a nicer looking
  13 product.
  14
  15 This short note (strange isn't it how it always starts out as a short note
  16 and becomes a long one ?) will explain very briefly how and why we are
  17 doing this.
  18
  19
  20 The format
  21 ----------
  22
  23 If you are new to sgml, regard an sgml file as 'source code'. You don't
  24 read it directly, use it to create other formats (like the txt and html
  25 included in ../txt and ../html).
  26
  27 Docbook is a particular SGML style, particularly suited to producing
  28 technical manuals.  In the two documents I have produced so far I have used
  29 DocBook 4.1, it seems that products like RedHat Linux is still include only
  30 version 3.1, the differences are minor. The Linux Documentation Project is
  31 using a modified version of 3.1 but are really geared up to make multi
  32 paged documents, something we want to avoid for logistic reasons.
  33
  34 For more information on DocBook tags and format, see "DocBook: The
  35 Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
  36 This book covers DocBook V3.1 and is available on-line
  37 at http://www.docbook.org/
  38
  39 The Output
  40 ----------
  41
  42 The current Samba CVS tree contains the SGML/DocBook source files as well
  43 as the following autogenerated formats:
  44
  45   * man pages
  46   * HTML
  47   * ASCII text (where appropriate)
  48   * PDF
  49
  50
  51 The Tools
  52 ---------
  53
  54 To generate the docs, you need to have the following packages installed:
  55
  56 * docbook-utils
  57 * htmldoc
  58
  59 This directory now contains a ./configure script and Makefile to
  60 support the automated building of man pages (including HTML versions), and
  61 the building of the Samba-HOWTO-Collection (HTML,PDF,PS,Text versions).