| 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 | * inkscape
|
|---|
| 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
|
|---|
