sin/samba-mirror
1
0
Fork 0
mirror of https://github.com/samba-team/samba.git synced 2025-01-04 05:18:06 +03:00
Code

Reformatted to look nicer on 80-character screen.

Browse Source 
Replaced 8-bit ascii characters with appropriate 7-bit ones.
This commit is contained in:
Tim Potter 0001-01-01 00:00:00 +00:00
parent 077ee4a7ac
commit cfe4cb5dfa
1 changed files with 52 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
docs/docbook/docbook.txt
View File

@ -3,47 +3,53 @@ What are DocBook documents doing in the Samba Distribution ?
By David Bannon, D.Bannon@latrobe.edu.au November, 2000 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 We are planning to convert some or all (?) of the samba docs to sgml
make them easier to maintain and produce a nicer looking product. 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 This short note (strange isn’t it how it always starts out as a short note
long one ?) will explain very briefly how and why we are doing this. 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 If you are new to sgml, regard an sgml file as 'source code'. You don't
directly, use it to create other formats (like the txt and html included in ../txt and read it directly, use it to create other formats (like the txt and html
../html). included in ../txt and ../html).
Docbook is a particular sgml style, particularly suited to producing technical manuals. Docbook is a particular sgml style, particularly suited to producing
In the two documents I have produced so far I have used DocBook 4.1, it seems that technical manuals. In the two documents I have produced so far I have used
products like RedHat Linux is still include only version 3.1, the differences are DocBook 4.1, it seems that products like RedHat Linux is still include only
minor. The Linux Documentation Project is using a modified version of 3.1 but are version 3.1, the differences are minor. The Linux Documentation Project is
really geared up to make multi paged documents, something we want to avoid for using a modified version of 3.1 but are really geared up to make multi
logistic reasons. paged documents, something we want to avoid for logistic reasons.
The Output The Output
-------------- ----------
Formatted html or xml is easily produced from a DocBook document, however I 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 had difficulty making a txt file directly ! It appears that the people who
DocBook did not imagine anyone wanting to make plain text from a DocBook make DocBook did not imagine anyone wanting to make plain text from a
document. At least one set of sgml tools appears to have decided that the easiest way DocBook document. At least one set of sgml tools appears to have decided
is to make the html and then convert that, this works fine. 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 I have not had the need to make man pages from a DocBook document yet,
want to send me some pointers ?? anyone want to send me some pointers ??
To make file handling and distribution easy I have opted for a single file or page per To make file handling and distribution easy I have opted for a single file
document. In the Samba 2.2 distribution I made an html and a txt version of each sgml or page per document. In the Samba 2.2 distribution I made an html and a
file and placed that in the appropriate directory under ~/doc. txt version of each sgml file and placed that in the appropriate directory
under ~/doc.
The Tools The Tools
------------- ---------
Any sgml document needs to be referred to a suitable style sheet (describing syntax) Any sgml document needs to be referred to a suitable style sheet
and other sheets that tell the translating programmes how to do the translations. The (describing syntax) and other sheets that tell the translating programmes
list of necessary ‘include’ files is a bit messy but once installed is pretty easy. 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: On one of my RedHat 6.2 systems I installed the following:
* sgml-common (as an rpm) * 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 * Docbook 4.1 from http://docbook.org
* DSSSL 157 from http://nwalsh.com/docbook/dsssl/ * 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 If you would be happy using DocBook 3.1 (and why not ?) then stop after the
rpms. If you want to use 4.1 and the current DSSSL then you will need a bit of four rpms. If you want to use 4.1 and the current DSSSL then you will need
manual editing of the catalog files. a bit of manual editing of the catalog files.
There are several downloadable descriptions of the DocBook syntax at the web sites There are several downloadable descriptions of the DocBook syntax at the
mentioned above. Note that a lot of the docs only talk about version 3.1 with 4.1 as an web sites mentioned above. Note that a lot of the docs only talk about
add-on. 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 In either case you will need to include in the html/docbook.dsl and most
couple of ‘defines’ to achieve a suitable output. I made a local dsl file that I called likely a couple of 'defines’ to achieve a suitable output. I made a
html.dsl that looks like this : local dsl file that I called html.dsl that looks like this :
<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ <!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [
@ -85,11 +91,11 @@ CDATA DSSSL>
<external-specification id="docbook" document="dbstyle"> <external-specification id="docbook" document="dbstyle">
</style-sheet> </style-sheet>
Note the top block that refers to where the dsssl-157 style sheets are installed, if you Note the top block that refers to where the dsssl-157 style sheets are
don’t put them there make sure you edit the file. 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. To use this stylesheet, have it in your working directory along with your
Jade does the actual conversion to html, call it like this : sgml files. Jade does the actual conversion to html, call it like this :
jade -t sgml -d html.dsl stuff.sgml 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 Lynx -dump -nolist stuff.html > stuff.txt
These instructions are crude by might help someone get going. Please feel free to These instructions are crude by might help someone get going. Please feel
contact me if you have any questions or if you can correct any one of the many free to contact me if you have any questions or if you can correct any one
mistakes I must have made above. of the many mistakes I must have made above.
David David