diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/docbook/docbook.txt | 101 |
1 files changed, 52 insertions, 49 deletions
diff --git a/docs/docbook/docbook.txt b/docs/docbook/docbook.txt index a69cf0ff9d..37cad90109 100644 --- a/docs/docbook/docbook.txt +++ b/docs/docbook/docbook.txt @@ -3,47 +3,53 @@ 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 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’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. +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. --------------- +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 ‘include’ 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’ 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) @@ -53,17 +59,17 @@ 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. +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 ‘defines’ 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’ 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" [ @@ -85,11 +91,11 @@ CDATA DSSSL> <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’t 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’t 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 @@ -97,11 +103,8 @@ To create the text version run the html through lynx : 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 - - - |