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