docs/docbook/docbook.txt

   1 !==
   2 !== docbook.txt for Samba 2.2.0 release
   3 !==
   4 !== Author:     David Bannon, D.Bannon@latrobe.edu.au  November, 2000
   5 !== Updates:    Gerald (Jerry) Carter, jerry@samba.org, Feb. 2001
   6
   7 What are DocBook documents doing in the Samba Distribution ?
   8 -----------------------------------------------------------
   9
  10 We are planning to convert all of the samba docs to SGML/DocBook V4.1
  11 in order to make them easier to maintain and produce a nicer looking
  12 product.
  13
  14 This short note (strange isn't it how it always starts out as a short note
  15 and becomes a long one ?) will explain very briefly how and why we are
  16 doing this.
  17
  18
  19 The format
  20 ----------
  21
  22 If you are new to sgml, regard an sgml file as 'source code'. You don't
  23 read it directly, use it to create other formats (like the txt and html
  24 included in ../txt and ../html).
  25
  26 Docbook is a particular SGML style, particularly suited to producing
  27 technical manuals.  In the two documents I have produced so far I have used
  28 DocBook 4.1, it seems that products like RedHat Linux is still include only
  29 version 3.1, the differences are minor. The Linux Documentation Project is
  30 using a modified version of 3.1 but are really geared up to make multi
  31 paged documents, something we want to avoid for logistic reasons.
  32
  33 For more information on DocBook tags and format, see "DocBook: The
  34 Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
  35 This book covers DocBook V3.1 and is available on-line
  36 at http://www.docbook.org/
  37
  38 The Output
  39 ----------
  40
  41 The current Samba CVS tree contains the SGML/DocBook source files as well
  42 as the following autogenerated formats
  43
  44   * man pages
  45   * HTML
  46   * ASCII text (where appropriate)
  47
  48
  49 The Tools
  50 ---------
  51
  52 [
  53  addendum: For a good general overview of installing the tools
  54  needed for generating files from SGML/DocBook source, refer
  55  to the DocBook-Install mini HOWTO at
  56  http://www.ibiblio.org/pub/Linux/docs/HOWTO/mini/DocBook-Install
  57
  58  While the above link is to a Linux HOWTO, the tools can be installed
  59  on almost any UNIX platform.
  60
  61  David's original notes follow below:
  62 ]
  63
  64 Any sgml document needs to be referred to a suitable style sheet
  65 (describing syntax) and other sheets that tell the translating programmes
  66 how to do the translations. The list of necessary 'included files is a
  67 bit messy but once installed is pretty easy.
  68
  69 On one of my RedHat 6.2 systems I installed the following:
  70 * sgml-common (as an rpm)
  71 * docbook  (as an rpm)
  72 * stylesheets  (as an rpm)
  73 * jade  (as an rpm)
  74 * Docbook 4.1 from http://docbook.org
  75 * DSSSL 157 from http://nwalsh.com/docbook/dsssl/
  76
  77 There are several downloadable descriptions of the DocBook syntax at the
  78 web sites mentioned above. Note that a lot of the docs only talk about
  79 version 3.1 with 4.1 as an add-on.
  80
  81 In either case you will need to include in the html/docbook.dsl and most
  82 likely a couple of defines to achieve a suitable output. I made a
  83 local dsl file that I called html.dsl that looks like this :
  84
  85 <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
  86 <!ENTITY dbstyle SYSTEM "/usr/lib/sgml/dsssl-157/docbook/html/docbook.dsl"
  87 CDATA DSSSL>
  88 ]>
  89
  90 <style-sheet>
  91 <style-specification use="docbook">
  92 <style-specification-body>
  93
  94 (define nochunks #t)                    ;; Dont make multiple pages
  95 (define rootchunk #t)                   ;; Do make a 'root' page
  96 (define %use-id-as-filename% #t)        ;; Use book id as filename
  97 (define %html-ext% ".html")             ;; give it a proper html extension
  98
  99 </style-specification-body>
 100 </style-specification>
 101 <external-specification id="docbook" document="dbstyle">
 102 </style-sheet>
 103
 104 Note the top block that refers to where the dsssl-157 style sheets are
 105 installed, if you don\92t put them there make sure you edit the file.
 106
 107 To use this stylesheet, have it in your working directory along with your
 108 sgml files.  Jade does the actual conversion to html, call it like this :
 109
 110 jade -t sgml -d html.dsl stuff.sgml
 111
 112 To create the text version run the html through lynx :
 113
 114 Lynx  -dump  -nolist  stuff.html  >  stuff.txt
 115
 116 These instructions are crude by might help someone get going. Please feel
 117 free to contact me if you have any questions or if you can correct any one
 118 of the many mistakes I must have made above.
 119
 120 David
 121
 122 ==========================================================================
 123
 124 This directory now contains a ./configure script and Makefile to
 125 support the automated building of man pages (including HTML versions).
 126 The DocBook V4.1 DTD and ISO entity files have also been included in CVS
 127 to make sure we are all working from the same plate.
 128
 129 The SGML_CATALOG_FILES environment variable should be set as follows
 130 (this assumes you have a working local installation of jade and
 131 Norman's Walsh's DSSSL stylesheets):
 132
 133   export SGML_CATALOG_FILES=$SGML_CATALOG_FILES:./dbsgml/catalog
 134
 135
 136 --jerry