Snitz Forums 2000
Snitz Forums 2000
Home | Profile | Register | Active Topics | Members | Search | FAQ
Username:
Password:
Save Password
Forgot your Password?

 All Forums
 Snitz Forums 2000 DOC-Group
 DOC Discussion
 Explained: What is Docbook ? (part 1)
 Forum Locked  Topic Locked
 Printer Friendly
Author Previous Topic Topic Next Topic  

gor
Retired Admin

Netherlands
5511 Posts

Posted - 02 February 2002 :  03:11:52  Show Profile  Visit gor's Homepage
<b>What is it?</b>
Technically, Docbook is 'just' a DTD, in this case the set of rules that make up the Docbook 'fileformat'. Just like you have a set of rules that describes how an .rtf, .pdf or .doc file should look like.
The nice thing of having a DTD is that it is easier to find an editor that will understand what the structure of a Docbook file is.

So because of the rules in the DTD this is valid:<pre id=code><font face=courier size=2 id=code>
<chapter revision="$Revision: 1.4 $ $Date: 2002/01/06 15:38:10 $"
id="installation">
<title> Installation</title>
<para>Understanding how CVS works is easy once you've got all the software
setup. You'll find a lot of HOWTO's concerning this, but most of them (also)
have Linux in mind. And that can get very confusing from time to time. To get
started you need to have three applications: a CVS client to upload and
download the files, a SSH client for the secure connection and preferably
something to check out the differences between versions of files. </para>
<sect1 id="before_you_start">
</font id=code></pre id=code> And this is not:
<pre id=code><font face=courier size=2 id=code>
<chapter revision="$Revision: 1.4 $ $Date: 2002/01/06 15:38:10 $"
id="installation">
<para>Understanding how CVS works is easy once you've got all the software
setup. You'll find a lot of HOWTO's concerning this, but most of them (also)
have Linux in mind. And that can get very confusing from time to time. To get
started you need to have three applications: a CVS client to upload and
download the files, a SSH client for the secure connection and preferably
something to check out the differences between versions of files. </para>
<sect2 id="before_you_start">
</font id=code></pre id=code> Because according to the DTS, you can't have a <sect2> without a <sect1> and the <title></title> is missing.

<b>Validating editor</b>
If I have a so called validating editor, that means that that editor can read any DTD, interpret the set of rules in it and then understands what the structure of the file should be.
It can indicate that the structure is not correct and allows you to edit it so it is correct again (instead of just saying 'cannot open file'), and it can do that without ever having heard of a think called Docbook.

Only bad thing is that I haven't been able to find a really good validating xml-editor for windows.
I've tried the free Merlot editor, but it isn't really good for document-based XML. I don't like XML-Spy either because of the way I have to edit a XML file. For docbook files I like the (not-free) XMetal editor best.
Good thing is that you can try them all for free and decide which one you like best.
You can of course als use a plain texteditor and have the parser do the validating afterwards, but I just hate having to type tags over and over again.

<b>XSL (eXtensible Stylesheet Language)</b>
XSL is a language for expressing stylesheets. It consists of three parts: XSL Transformations (XSLT): a language for transforming XML documents, the XML Path Language (XPath), an expression language used by XSLT to access or refer to parts of an XML document. (XPath is also used by the XML Linking specification). The third part is XSL Formatting Objects (FO): an XML vocabulary for specifying formatting semantics. (source).

You use XSL to create the templates that determine how the XML, after being parsed, is going to look. See this page for an example.

Now if we all would have to start from scratch while creating our own stylesheets for a DTD as huge as Docbook, nobody would be using the DTD since it would be way too expensive.
The good news is that there is no need to create your own stylesheets. You can download a set of stylesheet from the Docbook SourceForge site. You can customise those if you like, or just use them like they are.
Nice features are things like support for other languages. So if I set the language to Dutch and create a pdf file, then a chapter heading starts with "Hoofdstuk" instead of "Chapter".

<b>XSL-FO</b>
Intended for the transformation of XML to paperbased output.
Also see the XSL-FO introduction by Dave Pawson.

<b>DSSSL (Document Style and Semantics Specification Language)</b>
If you look at the stylesheets you can download at SourceForge, you'll also see something called DSSSL.
It stands for Document Style and Semantics Specification Language and is an alternative to XSL to describe how the XML files need to be transformed to .html, .fo etc.
DSSSL, by James Clark, pre-dates XSL. If you don't know either of them, they both are a bit hard to read/understand. At first the docbook stylesheets were created using DSSSL, now they also are available in XSL. Some say the DSSSL stylesheets are better, more mature, because they have been tweaked more, others hate DSSSL and urge everyone to go for XSL.

<b>Parser</b>
Now XML and XSL both are nice, but to get your HTML or PDF file you need to somehow combine them. You do that using a parser. A parser reads the XSL file and formats the XML according to the templates described in the XSL file.
For the Docbook to HTML-help conversion I use Saxon (and the HTMLHelp compiler of course).
For the Docbook to PDF conversion I use the FOP.bat batch-file that comes with the FOP parser. The FOP parser is a .fo to .pdf parser, but in the batchfile it routes the xml file through a couple of parsers (batik,xalan,xerces,jimi) at one go and outputs .pdf in the end.

<b>Examples and more info</b>
The documentation you see at this page is created using Docbook. So for the .pdf, .htm and .chm files I used the exact same sourcefile and all I did was parse them using different parsers and stylesheets.
You can find all the sourcefiles here. If you look in the build directory you'll find the batch file with the commandsyntax, the parsers and stylesheets. Remember though that those files were not intended to be used by others, so there is not documentation in those batchfiles.
The most recent (not yet published) version of the docbook manual is also available online.
On this site you can find an overview of all the current docbook related projects.

<b>Pierre</b>
<font size=1><font color=blue><b>Join a Snitz Mailinglist</b></font id=blue></font id=size1>

<font color=red>Note: I locked the topic so I could set it to "don't archive", not to prevent you from commenting <img src=icon_smile.gif border=0 align=middle></font id=red>

Rasco
Advanced Member

Germany
3192 Posts

Posted - 02 February 2002 :  04:08:21  Show Profile  Send Rasco an ICQ Message
Only two remarks.

At http://www.conglomerate.org you can get Conglomerate. Another Editor.

The homepage of the DocBook schema maintainers you can find here:
http://www.oasis-open.org/docbook/

Greetings
Robert

now waiting for part II

<
Go to Top of Page

gor
Retired Admin

Netherlands
5511 Posts

Posted - 02 February 2002 :  04:29:30  Show Profile  Visit gor's Homepage
quote:

At http://www.conglomerate.org you can get Conglomerate. Another Editor.



Robert,

Thanks for the link, the screenshots look very good.
Only problem I have is finding a allready compiled Windows download.
Is it just me, or isn't it there?
If so, anyone feel like providing an executable? (would be much appreciated).

Pierre
Join a Snitz Mailinglist<
Go to Top of Page
  Previous Topic Topic Next Topic  
 Forum Locked  Topic Locked
 Printer Friendly
Jump To:
Snitz Forums 2000 © 2000-2021 Snitz™ Communications Go To Top Of Page
This page was generated in 0.07 seconds. Powered By: Snitz Forums 2000 Version 3.4.07