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