sin/samba-mirror
1
0
Fork 0
mirror of https://github.com/samba-team/samba.git synced 2025-02-05 21:57:51 +03:00
Code

updated comments on using DocBook.

Browse Source 
jerry
(This used to be commit 3171e54ad5c1e618fa24ceaba1c66c8037a09bfa)
This commit is contained in:
Gerald Carter 2001-02-19 22:49:18 +00:00
parent 2e99f0f8d3
commit 1ea2d3b01b
1 changed files with 35 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
docs/docbook/docbook.txt
View File

@ -1,16 +1,21 @@
!==
!== docbook.txt for Samba 2.2.0 release
!==
!== Author: David Bannon, D.Bannon@latrobe.edu.au November, 2000
!== Updates: Gerald (Jerry) Carter, jerry@samba.org, Feb. 2001
What are DocBook documents doing in the Samba Distribution ?
-----------------------------------------------------------
By David Bannon, D.Bannon@latrobe.edu.au November, 2000
----------------------------------------------------------
We are planning to convert some or all (?) of the samba docs to sgml
DocBook to make them easier to maintain and produce a nicer looking
We are planning to convert all of the samba docs to SGML/DocBook V4.1
in order to make them easier to maintain and produce a nicer looking
product.
This short note (strange isn’t it how it always starts out as a short note
This short note (strange isn't it how it always starts out as a short note
and becomes a long one ?) will explain very briefly how and why we are
doing this.
The format
----------
@ -18,37 +23,47 @@ If you are new to sgml, regard an sgml file as 'source code'. You don't
read it directly, use it to create other formats (like the txt and html
included in ../txt and ../html).
Docbook is a particular sgml style, particularly suited to producing
Docbook is a particular SGML style, particularly suited to producing
technical manuals. In the two documents I have produced so far I have used
DocBook 4.1, it seems that products like RedHat Linux is still include only
version 3.1, the differences are minor. The Linux Documentation Project is
using a modified version of 3.1 but are really geared up to make multi
paged documents, something we want to avoid for logistic reasons.
For more information on DocBook tags and format, see "DocBook: The
Definitive Guide" by Walsh and Muellner, (c) O'Reilly Publishing.
This book covers DocBook V3.1 and is available on-line
at http://www.docbook.org/
The Output
----------
Formatted html or xml is easily produced from a DocBook document, however I
had difficulty making a txt file directly ! It appears that the people who
make DocBook did not imagine anyone wanting to make plain text from a
DocBook document. At least one set of sgml tools appears to have decided
that the easiest way is to make the html and then convert that, this works
fine.
The current Samba CVS tree contains the SGML/DocBook source files as well
as the following autogenerated formats
I have not had the need to make man pages from a DocBook document yet,
anyone want to send me some pointers ??
* man pages
* HTML
* ASCII text (where appropriate)
To make file handling and distribution easy I have opted for a single file
or page per document. In the Samba 2.2 distribution I made an html and a
txt version of each sgml file and placed that in the appropriate directory
under ~/doc.
The Tools
---------
[
addendum: For a good general overview of installing the tools
needed for generating files from SGML/DocBook source, refer
to the DocBook-Install mini HOWTO at
http://www.ibiblio.org/pub/Linux/docs/HOWTO/mini/DocBook-Install
While the above link is to a Linux HOWTO, the tools can be installed
on almost any UNIX platform.
David's original notes follow below:
]
Any sgml document needs to be referred to a suitable style sheet
(describing syntax) and other sheets that tell the translating programmes
how to do the translations. The list of necessary 'include’ files is a
how to do the translations. The list of necessary 'included files is a
bit messy but once installed is pretty easy.
On one of my RedHat 6.2 systems I installed the following:
@ -59,19 +74,14 @@ On one of my RedHat 6.2 systems I installed the following:
* Docbook 4.1 from http://docbook.org
* DSSSL 157 from http://nwalsh.com/docbook/dsssl/
If you would be happy using DocBook 3.1 (and why not ?) then stop after the
four rpms. If you want to use 4.1 and the current DSSSL then you will need
a bit of manual editing of the catalog files.
There are several downloadable descriptions of the DocBook syntax at the
web sites mentioned above. Note that a lot of the docs only talk about
version 3.1 with 4.1 as an add-on.
In either case you will need to include in the html/docbook.dsl and most
likely a couple of 'defines’ to achieve a suitable output. I made a
likely a couple of defines to achieve a suitable output. I made a
local dsl file that I called html.dsl that looks like this :
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
<!ENTITY dbstyle SYSTEM "/usr/lib/sgml/dsssl-157/docbook/html/docbook.dsl"
CDATA DSSSL>