docs/README

   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 Quick start
  11 -----------
  12
  13 Run:
  14
  15 make all
  16
  17 What are DocBook documents doing in the Samba Distribution ?
  18 -----------------------------------------------------------
  19
  20 We have converted all samba docs to XML/DocBook V4.2
  21 in order to make them easier to maintain and produce a nicer looking
  22 product.
  23
  24 This short note (strange isn't it how it always starts out as a short note
  25 and becomes a long one ?) will explain very briefly how and why we have
  26 done this.
  27
  28
  29 The format
  30 ----------
  31 If you are new to xml, regard an xml file as 'source code'. You don't
  32 read it directly, but use it to create other formats (like the txt and html
  33 included in ../txtdocs and ../htmldocs).
  34
  35 Docbook is a particular XML style, particularly suited to producing
  36 technical manuals.
  37
  38 For more information on DocBook tags and format, see "DocBook: The
  39 Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
  40 This book covers DocBook V4.2 and is available on-line
  41 at http://www.docbook.org/
  42
  43 The Output
  44 ----------
  45 The current Samba Subversion tree contains the XML/DocBook source files.
  46
  47 A regularly generated version can be found at http://samba.org/samba/docs/.
  48
  49 The Tools
  50 ---------
  51
  52 To generate the docs, you need to have the following packages installed:
  53
  54  * GNU Make
  55  * GNU autoconf
  56  * docbook-utils
  57  * xsltproc
  58  * pngtopnm and pnmtops (from the netpbm utilities)
  59  * dia
  60
  61 For generating PDF (thru LaTeX):
  62  * db2latex (from http://db2latex.sf.net/). Make sure to get CVS version
  63    dated 20030622 -- it works best. Versions previous to 20030425 are known
  64    to have problems, as well as current (as of 20031210) snapshots.
  65  * pdflatex
  66  * thumbpdf
  67
  68 For generating PDF (thru FO):
  69  * fop (http://xml.apache.org/fop/)
  70
  71 For generating PostScript (thru LaTeX):
  72  * db2latex
  73  * latex
  74  * dvips
  75
  76 For generating ASCII:
  77  * html2text
  78
  79 For generating Palm-viewable docs:
  80  * plucker-build
  81
  82 For generating texi files:
  83  * docbook2x-texi
  84  * makeinfo
  85
  86 For validating:
  87  * xmllint
  88
  89 This directory now contains a ./configure script and Makefile to
  90 support the automated building of man pages (including HTML versions), and
  91 the building of the Samba-HOWTO-Collection and the
  92 Samba Developers Guide (HTML,DVI,TeX,PDF,PS,Text versions).
  93
  94 The configure script detects which of the required utilities are installed
  95 and builds as much docs as it can using these tools.
  96
  97 Help! Building the docs generates a lot of HTTP traffic...
  98 -------------
  99 To be able to build the docs without an internet connection (or faster with
 100 a slow internet connection), you need to set up "catalogs".
 101
 102 A catalog contains a list of mappings to locally cached documents. E.g. :
 103 http://db2latex.sf.net/xsl/ -> /usr/share/sgml/docbook/db2latex/xsl/
 104
 105 Add the following two lines to /etc/xml/catalog for db2latex:
 106 <rewriteURI uriStartString="http://db2latex.sourceforge.net/xsl/" rewritePrefix="/export/user/me/source/docbook/db2latex/xsl/"/>
 107 <rewriteURI uriStartString="http://docbook.sourceforge.net/release/xsl/current/" rewritePrefix="/export/user/me/source/docbook/docbook-xsl/"/>
 108
 109 For the Pearson DTD, add something like:
 110
 111   <public publicId="-//Pearson//DTD Books//DE" uri="file:///home/jelmer/Xml_dtd_1.1/pearson.dtd"/>
 112
 113 (of course, adapt /export/user/me/source/ to whatever path db2latex is
 114  installed in...)
 115
 116 catalog entries for the other DTD's and XSL scripts should be present on your
 117 system already.
 118
 119 Windows Help files
 120 ----------
 121 http://htmlhelp.berlios.de/howto/mshh4wine.php