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 product.
+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
+product.
-This short note (strange isn\92t 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.
+This short note (strange isn\92t 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.
---------------
+The format
+----------
-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).
+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 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.
+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.
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.
+----------
-I have not had the need to make man pages from a DocBook document yet, anyone
-want to send me some pointers ??
+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.
-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.
+I have not had the need to make man pages from a DocBook document yet,
+anyone want to send me some pointers ??
+
+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
--------------
+---------
-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 \91include\92 files is a bit messy but once installed is pretty easy.
+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\92 files is a
+bit messy but once installed is pretty easy.
On one of my RedHat 6.2 systems I installed the following:
* sgml-common (as an rpm)
* 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.
+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.
+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 \91defines\92 to achieve a suitable output. I made a local dsl file that I called
-html.dsl that looks like this :
+In either case you will need to include in the html/docbook.dsl and most
+likely a couple of 'defines\92 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" [
<external-specification id="docbook" document="dbstyle">
</style-sheet>
-Note the top block that refers to where the dsssl-157 style sheets are installed, if you
-don\92t put them there make sure you edit the file.
+Note the top block that refers to where the dsssl-157 style sheets are
+installed, if you don\92t put them there make sure you edit the file.
-To use this stylesheet, have it in your working directory along with your sgml files.
-Jade does the actual conversion to html, call it like this :
+To use this stylesheet, have it in your working directory along with your
+sgml files. Jade does the actual conversion to html, call it like this :
jade -t sgml -d html.dsl stuff.sgml
Lynx -dump -nolist stuff.html > stuff.txt
-These instructions are crude by might help someone get going. Please feel free to
-contact me if you have any questions or if you can correct any one of the many
-mistakes I must have made above.
+These instructions are crude by might help someone get going. Please feel
+free to contact me if you have any questions or if you can correct any one
+of the many mistakes I must have made above.
David
-
-
-
git.samba.org / ira / wip.git / commitdiff