Introduction

This article will cover a number of topics, but it's main point is to show you how to get up an running with producing documentation using the DocBook help processor, and then creating customizations for producing plain html file for use on the web or offline, or in making a single Microsoft HTML Help file (.chm) for windows. By the end of the article I'll show you how to create and process your own DocBook file(s), customize the style sheets for it's output, and create a simple makefile to run the whole thing from a command line. The article will mention a number of technologies, and my aim is not to explain in detail how they work, but mainly explain how to use them to create html based documentation for Win32 (though much of this is generic to pretty much any OS that can run the various DocBook tools) systems. This is based on my experiences with DocBook in using it to produce the documentation for my VCF project that I spend much of my time on.

DocBook is a very cool XML-based syntax that allows you to author documentation in a single format, and then run it through various processors to create your final documentation output. From a single DocBook source you can output html, PDF, latex, rtf, and many other formats. We'll focus on dealing with html and HTML Help. Once you have written your DocBook files you have a choice in how they are processed. The original way was through a DSSSL processor such as Jade or OpenJade. DSSSL has a lisp like syntax and is a bit unwieldy to use. The other way, and the one apparently most people use, is XSL style sheets run through an xsl processor, like xsltproc. You can use other processors for XSL but many of them will not work correctly, and xsltproc is nice because it doesn't require a Java runtime to be installed. I found this out the hard way after spending the better part of a day downloading and trying several different XSL processors!

One of the many neat things about DocBook, is that from the single, plain text source, the customization style sheets can automatically produce index, table of contents, and all sorts of extra stuff, all without you having to put much effort into it in terms of extra writing in your documentation.

Before we do anything though, we are going to have to get some tools set up. When working with DocBook on Windows, half the hassle is getting the tools and your environment set up right. So, first get the following tools:

Cygwin - this is free tool that provides a whole slew of command line tools that are typical with *nix systems. Cygwin is, simply put, and awesome collection of tools for doing command line work - I can't imagine working without it. Some of the tools included (in no particular order) are ssh, cvs, gcc, make, touch, scp, more, less, cat, bash, perl, python, and many, many others. The setup is trivial to do (you will need be online though), and allows you to pick and choose exactly what you want. For our purposes make sure you have at least the following selected:

bash (this the shell you use in *nix, and will let you run all sort of cool shell scripts)

One note: when you come to the "Select Install Directory" page make sure to click on the "DOS" choice for Default Text Type (trust me, this will save you a lot of headaches later on).

Most of these will come with the default Cygwin installer's selection of tools. The one's to watch for are libxslt and sed. If you miss something, you can always run the installer again and select the missing programs.

Microsoft'sHTML Help Workshop will allow you to edit and compile HTML Help chm files, both from the GUI tool as well as a command line program. We'll be using the command line version (hhc.exe) of the tool in this article.

Now open up your bash command line and type (you can do this via Start > Programs > Cygwin > Cygwin Bash Shell):

This is a simple example that create a basic unit, a "book", and adds a title, preface, and two chapters. Your basic building blocks in terms of organizing the various sections are a book, a chapter, and a section. Chapters can nest under a book, and sections can nest under a chapter or another section. Paragraphs are wrapped with the <para> tags and can occur most anywhere you want.

To produce our html lets run this file through our XSL processor. To use the xsltproc program, you pass it the file name of an XSL style sheet to use, and a file name of the XML file to process. The file that gets processed must be a valid XML file, if not xsltproc will whine and complain and will not process it. Specifically, you must have the <FONT color=#000000><?xml version="1.0"?> right at the top of the file, otherwise you'll scratch your head and curse fluently at your machine for not processing your perfectly valid XML file. Also when passing in file names, make sure to use the "/" and not the "\" - failure to so this will cause xsltproc to trip up and not work correctly.

Now you can open up index.html in a browser and view your documentation!

The --nonet option tells xsltproc to not attempt to connect via the network and attempt to verify the DTD. I use this so I don't have to fight with producing documentation when I don't have a valid or reasonable fast network connection. For other kinds of XSL processing this may be an issue, but for DocBook processing --nonet seems to work just fine.

The first thing you may want to do is break up your documentation into multiple files, as a single file may not be the easiest thing to work with. Luckily this is easy to do. If you create a two files, chap1.xml and chap2.xml, and copy and paste the following into chap1.xml

The use of the <FONT color=#000000><!ENTITY> tags creates entities named chap1 and chap2. Using them automatically includes their contents in to the simple.xml file, so be careful to not put the <?xml?> preprocessor tags in the included files (chap1.xml and chap2.xml respectively). We can verify that all this works by running xsltproc again:

Again we get the same output as before and we have now broken apart our documentation into multiple files for easier editing.

Now lets generate our chm. To do this we simply call the command line HTML help compiler (hhc.exe) and pass the generated hhp file.

hhc htmlhelp.hhp

And voila! we now have our chm file:

Adding an index

Now that we can create out DocBook output and create our chm file, lets get a little fancier and add support for an index. In DocBook it's so simple we can do this in a single line, so let's modify simple.xml like so:

This now gives indexing support. However to actually ensure an item is placed in the index, we have to indicate which items we want to mark as being indexed. Doing so is simple, we just use the <indexterm> tag and give the term a name. So let's modify both chap1.xml and chap2.xml and add some index support:

Now just run it through the xsltproc to produce our html output. Then run the compile step again with hhc. Now one thing to note at this point, there seems to be a bug, because once you add index support, the HTML Help compiler will complain about a mysteriously missing ix01.html file. It will however properly generate the chm file, complete with indexing support, so I don't know what the deal is. However it can cause problems with other programs that may run the hhc program from a script as it will now return an error code, despite successfully creating the chm! We'll address this a bit more later on. And now for our obligatory screenshot:

Kewl!

Now, lets add one more thing: how to produce a single html file, such as we might want if we were to use DocBook to write an article for CodeProject. To do this, we'll use the same XML file(s), remember, single documentation source, multiple outputs, but this time specify a different XSL style sheet to use. We will also not produce any chm file, but only a single html output file. To run the processor we simply type:

xsltproc --nonet D:/docbook-xsl-1.60.1/html/docbook.xsl simple.xml

Note the change in style sheets, and the fact that it simply dumps the output to stdout. No worries though - we can just dump the output to a file like so:

More DocBook tags

All right, up till now we've only seen some pretty basic usage of the various DocBook tags available. While I am not going to attempt to cover all of them, I will try cover some of the more useful one, at least in my experience. For a more thorough article on this, please see the online version of "DocBook: The Definitive Guide" from O'Reilly.

Meta data

With DocBook you can describe various peices of information about the documentation, such as the author, legal notices, book version, and copyright(s) notice. We start this by adding a <FONT color=#000000><bookinfo> tag.

Now we can add a quick legal notice, author, and copyright sections to our simple.xml file:

<book><bookinfo><legalnotice><para>
Here a short legal notice: You agree that all your base
belongs to me!
</para></legalnotice><author><firstname>Bob</firstname><surname>Grey</surname></author><copyright><year>2003</year><year>2021</year><holder>Pennywise the Clown</holder></copyright></bookinfo><title>Simple Book</title><!-- ... --></book>

Tables

Tables are critical for just about any kind of documentation, and DocBook fully supports them. Lets add a simple one to our chap1.xml file:

Notice the <FONT color=#000000><tgroup> - this is critical to have, otherwise the table will not get rendered correctly. When we process this, we'll see some thing like this:

Chapter 1. On Foo's

Stuff about Foo's goes here.

And now for some data in a table:

Table 1.1.

Column 1

Column 2

Column 3

Heres

A

Row entry!

Note that DocBook automatically add table numbering for you and ties it to your chapters numbers. If we had 3 tables in chapter 2, we'd see them numbered as Table 2.1, Table 2.2, and Table 2.3. We'll see how to turn off the table numbering later on.

Links

In DocBook there are several way to link to things. I'll show you how to link to external URL's and to items within your DocBook documentation.

To link to external URL's you use the <FONT color=#000000><ulink> tag as follows:

Note the fileref attribute - this is what points to the file. Fileref can point to a url, for example, fileref="</FONT>http://images.sourceforge.net/head_bg_new.gif" is also valid syntax.

Notes

Adding notes is another really cool feature of DocBook. A note is a little paragraph that stands out, usual with some kind of extra, or special case documentation about a feature. For example:

chap2.xml:

<chapter><title>On Bars's</title><para><FONTsize=2><indexterm><primary>About Bar's</primary></indexterm></FONT>
Stuff about Bars's goes here.
</para><para>To learn more about the wonderful world of Bar's look
<ulinkurl="http://www.google.com/search?q=Bars">
here
</ulink></para><para>
Don't forget: Graphics are important!
<graphicfileref="smiley.bmp"></graphic></para><note>
Not only can DocBook do graphics, but it can handle notes as well!
Isn't that just cool?
</note></chapter>

Chapter 2. On Bars's

Note

Not only can DocBook do graphics, but it can handle notes as well! Isn't that just cool?

Special Formatting

In general formatting is not something that is relevant to DocBook. The idea is that DocBook is for specifying content and formatting is handled via CSS style sheets. However there are a few tags you can use. For example, the most common is the <FONT color=#000000><emphasis> tag, used like so:

chap1.xml file:

<chapter><title>On Foo's</title><para><FONTsize=2><indexterm><primary>About Foo's</primary></indexterm></FONT>
Stuff about Foo's goes here.
</para><para>And now for some data in a table:
<tableframe="none"pgwide="1"><tgroupcols="3"align="left"colsep="1"rowsep="1"><thead><row><entry>Column 1</entry><entry>Column 2</entry><entry>Column 3</entry></row></thead><tbody><row><entry>Heres</entry><entry>A</entry><entry>Row entry!</entry></row></tbody></tgroup></table></para><para>
Not only are Foo's important to proper software development, but they are
critical to understanding the synergistic relationship between Neo
<emphasis>and</emphasis> Trinity.
</para></chapter>

DocBook renders it like so:

Chapter 1. On Foo's

Stuff about Foo's goes here.

And now for some data in a table:

Table 1.1.

Column 1

Column 2

Column 3

Heres

A

Row entry!

Not only are Foo's important to proper software development, but they are critical to understanding the synergistic relationship between Neo and Trinity.

Plain text formatting

Sometimes you'll want to include program listings, or plain unformatted text, say a console dump to demonstrate a command line program. For source listing, a frequent way to do this is the <FONT color=#000000><programlisting> tag. For example:

chap1.xml file:

<chapter><title>On Foo's</title><para><FONTsize=2><indexterm><primary>About Foo's</primary></indexterm></FONT>
Stuff about Foo's goes here.
</para><para>And now for some data in a table:
<tableframe="none"pgwide="1"><tgroupcols="3"align="left"colsep="1"rowsep="1"><thead><row><entry>Column 1</entry><entry>Column 2</entry><entry>Column 3</entry></row></thead><tbody><row><entry>Heres</entry><entry>A</entry><entry>Row entry!</entry></row></tbody></tgroup></table></para><para>
Not only are Foo's important to proper software development, but they are
critical to understanding the synergistic relationship between Neo
<emphasis>and</emphasis> Trinity.
</para><para>
Here's an example of a code listing:
<programlisting>
int foo = 12 * 23;
multiply_endlessly( foo );
</programlisting></para></chapter>

A frequent thing you need in a program listing is the use of the < or > characters. If you simple use them in your content, you'll get errors when you go to process the DocBook files. However, if you use the <FONT color=#000000>CDATA tags you can put any characters you please in the listing, they'll be ignored till the processor encounters the closing CDATA tag. An example:

chap1.xml file:

<chapter><title>On Foo's</title><para><FONTsize=2><indexterm><primary>About Foo's</primary></indexterm></FONT>
Stuff about Foo's goes here.
</para><para>And now for some data in a table:
<tableframe="none"pgwide="1"><tgroupcols="3"align="left"colsep="1"rowsep="1"><thead><row><entry>Column 1</entry><entry>Column 2</entry><entry>Column 3</entry></row></thead><tbody><row><entry>Heres</entry><entry>A</entry><entry>Row entry!</entry></row></tbody></tgroup></table></para><para>
Not only are Foo's important to proper software development, but they are
critical to understanding the synergistic relationship between Neo
<emphasis>and</emphasis> Trinity.
</para><para>
Here's an example of a code listing:
<programlisting><![CDATA[int foo = 12 * 23;
std::vector<int> vec;
vec.push_back( foo );
]]></programlisting></para></chapter>

Using the <FONT color=#000000>CDATA tag makes it much easier to handle special characters that are common in programming, but are also used in XML, and it's much nicer to read than a whole bunch of "&lt;" tags.

Faqs

Writing FAQ's is common with technical documentation, particularly if it is documentation that is destined for online usage. DocBook provides some neat tags that support this as well. To do this, lets create a new xml file, faqs.xml, and add the appropriate entity to our main xml file, like so:

Faqs can be organized in question and answer sets, which provide a way to organize the individual questions and answers into logical groups. The sets can be broken into entries (<FONT color=#000000><qandaentry> tags), and then each entry can have it's series of question and answer tags. To fill this out, lets add some arbitrary question and answers, which, hopefully, will impart our deep and profound wisdom unto the reader:

<section><title>FAQs</title><qandaset><title>The Big Questions</title><qandaentry><question><para>Why did the chicken cross the road?</para></question><answer><para>
To get to the chicken feed.
</para></answer><question><para>Will anyone, in fact, ever need more than 640K of memory?</para></question><answer><para>
Two words: "Doom III".
</para></answer></qandaentry></qandaset><qandaset><title>Even Bigger Questions!</title><qandaentry><question><para>Is Neo really the One?</para></question><answer><para>
That all depends on your perception of both reality, and your
understanding of sub-atomic quantum scale micro causality. In
addition, this will require a support call to Technical Support.
Please call 1-888-232-1NEO.
</para></answer><question><para>Is VB really cooler than C++?</para></question><answer><para>
No. Thanks for playing.
</para></answer></qandaentry></qandaset></section>

Even Bigger Questions!

That all depends on your perception of both reality, and your understanding of sub-atomic quantum scale micro causality. In addition, this will require a support call to Technical Support. Please call 1-888-232-1NEO

1.

Is VB really cooler than C++?

No. Thanks for playing.

Customizing the Style Sheet

So far we have covered the basics of producing our DocBook content, but at some point you're going to want to control what it's output looks like. As an example of what you can do, I humbly submit my own work with it, the VCF Documentation. This content is simply regular DocBook, but through heavy customization of the style sheets I have been able to control things like header, footers, CSS, where standard DocBook images are looked for, and even how internal links are formatted. So to get started lets create our style sheet, and call it simple.xsl. Then lets add the boiler plate basics:

Note the <FONT color=#000000><xsl:import> tag, this tells the processor to import, or include, the URL referred to by the href attribute. In our case we are going to refer to our local htmlhelp.xsl style sheet. This is the same style sheet that we were using earlier in the arguments that we passed to the xsltproc program, only now we are "inheriting" from it by including it here. From here on out our command line to xsltproc will look like this:

xsltproc --nonet simple.xsl simple.xml

This will now replace the default HTML Help style sheet with our custom style sheet, which we will now start to add our specific changes to.

The style sheets use XSL which is, as I understand it, and I am by no means an expert here, a sort of XML like programming syntax that lets you tell the processor (in our case xsltproc) what to do with the XML tree that is built as a result of a successful parsing of the XML source file (in our case simple.xml).

Our first customizations will be simple ones, where we'll see how to turn on (or off) various parameters that DocBook uses in it's style sheets. So the first thing we'll do is to ensure that the legal info we have is generated (and linked to) as a separate output file (in this case html). To do this we add the following:

Note how we did this: by add a new line using the <FONT color=#000000><xsl:param> tag we can specify a certain parameter's value. In this case we specified that the "generate.legalnotice.link" parameter should have a value of 1, or true.

Next we'll make sure that the "Next" and "Back" navigation links at the bottom of each page is enabled. When generating HTML Help output, the default style sheet turns this off, meaning that we won't see it. We are going to turn it on here:

Once you have turned the default DocBook images on, you also need to specify where they live. By default, the links to them will be <FONT color=#000000>"images/<imagename>.png". So if you do not have an "images" directory and you have no png images, then you'll end up with the ugly broken image warning in the browser's rendering of the page. So, to fix this, lets tell DocBook what directory our images will be in:

Chapter 2. On Bars's

Not only can DocBook do graphics, but it can handle notes as well! Isn't that just cool?

Now the note we added has a little hand pointer graphic! This happens whenever you use the <FONT color=#000000><note> tag, with no worrying about the graphics content. You can create your own image to use as well, so long as it is in the gfx directory and named note.png.

Adding CSS support

OK so we have seen how to control some of the basic variables used in outputting our processed DocBook documentation. Now lets look at how to control the content look via CSS style sheets. First let's create a simple CSS file called simple.css. Then add the following to it:

If you're not familiar with how CSS works, here's a Google link to a variety of potential information about it. Basically we have declared that any <FONT color=#000000><a>, <body>, <div>, <table>, or <td> tags will use some sort of sans serif font, preferably a font named Verdana, Geneva, Arial, or Helvetica. Furthermore, we have declared that the <body> tag should use a background color of light grey, a text color of black, have no margins whatsoever, and have a 1 pixel solid black border.

To actually get DocBook to use this CSS sheet, we need to now customize out simple.xsl file, as follows:

This instructs DocBook to use the CSS file that we specify in the "select" attribute, in our case the simple.css file. If you run the processor again, you'll see that we now have html that uses the style sheets specifications!

More Style Sheet customizations

There are a lot of things you can do when customizing the style sheets, so we'll look at a few more simple parameters that we can change, as well as some advanced changes, like adding a header and footer.

Lets adjust the file name for the chm file that will be produced when we run the hhc HTML Help compiler. Lets once again change simple.xsl to the following:

Next, we'll control how deep various sections should be shown. Each time you nest a <FONT color=#000000><section> tag inside another <section> tag it causes a new level of numbering (i.e. 1.1, and it's first child 1.1.1). The top of each page can display a certain amount of the pages sections and sub sections in a TOC style set of links. By adjusting the style sheet, we can control how deep this goes.

Next lets move on to adding a custom html header to the top of all the pages. To do this we'll override the default behavior for the XSL processing of a certain template. So the first thing we'll add is the initial tags for overriding the template, like so:

Now within the <FONT color=#000000><xsl:template> tag we can put whatever HTML we want, and it will automatically be added to the beginning of each page, after the <body> tag, and before any of our DocBook content! So lets try this:

Unfortunately the xsltproc is expecting XML compliant tags, while standard HTML does not enforce this. So while <FONT color=#000000><hr> is perfectly acceptable HTML syntax it is not acceptable to XML parsers. Luckily we can write<hr></hr>
and still be acceptable to browsers. So a quick change:

And once again, if we process this, like before, we'll now see this footer applied to each page of our documentation!

Adding automatic version numbering: fun with sed

At this point we've covered most of the basics of actually using DocBook and processing our content. However, what we frequently want to do with our documentation is to have some section of it labeled with a version, one that matches up with the software it is documenting. As far as I know DocBook offers no real support for this, so we'll look at doing it the "hard" way. The process I'll describe is a pretty typical one for OSS projects. I don't know how frequently it is used in the Win32 world, but it does work, and is pretty flexible. What we'll end up with is a special file that keeps our version number. Then we'll write a simple script that reads the file into a variable, and then performs a find-and-replace in our simple.xml where we'll have referenced the version number using a variable name, which will then be replaced. To accomplish this we'll use sed, a unix program that can, among many other things, perform this find and replace operation for us.

First lets create a file appropriately called, version.txt. Add the following line to it:

1.2.3

Verify it's contents by using the cat command:

$ cat version.txt
1.2.3

Now alter the simple.xml to use a version variable to describe it's documentation version.

<!DOCTYPEbookPUBLIC"-//OASIS//DTDDocBookXMLV4.2//EN""http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"[<!ENTITYchap1SYSTEM"chap1.xml"><!ENTITYchap2SYSTEM"chap2.xml"><!ENTITYfaqsSYSTEM"faqs.xml">
]>
<book><bookinfo><legalnotice><para>
Here a short legal notice: You agree that all your base
belongs to me!
</para></legalnotice><author><firstname>Bob</firstname><surname>Grey</surname></author><copyright><year>2003</year><year>2021</year><holder>Pennywise the Clown</holder></copyright></bookinfo><title>Simple Book Version BOOK_VERSION</title><titleabbrev>Simple</titleabbrev><preface><title>Introduction</title><para>
Hello! Here's an introduction!
</para></preface>
&chap1;
&chap2;
&faqs;<indexid="index"/></book>

Note where we added the "Version BOOK_VERSION" the text "BOOK_VERSION" will be used as a place holder for the actual version stored in the version.txt file.

Next lets assign a variable in the shell to the contents of the version.txt file:

$ bk_ver=`cat version.txt`

Notice the use of the ` `, or back quotes. This tells the shell to assign to the variable bk_ver whatever the output is that came from executing the text in the back quotes. To test this:

$ echo $bk_ver
1.2.3

So far so good. Now lets get really icky and introduce our little sed script:

sed "s?BOOK_VERSION?$bk_ver?g" simple.xml > simple.xml.tmp

This will find the string "BOOK_VERSION" in the file simple.xml and replace it with the contents of the variable bk_ver, and then dump the output of all this to the file simple.xml.tmp. The original file, simple.xml, will be left alone for now.

Now we can just copy a temporary version of simple.xml (say to simple.xml.orig), rename simple.xml.tmp to simple.xml, and run the processor over it, and viola! we get a nice version number in our documentation. Then if we now rename our older copy of simple.xml.orig to simple.xml, we have the old file back and ready to edit.

Automating the process: Make to the rescue!

Now while the above does work, it is kind of a pain to remember, so let's get even more sophisticated and create a small makefile to do all this for us. Makefile's, for those of you blessed enough to not have encountered this rather cryptic syntax, are a script that you write that defines a series of targets and dependencies, and rules for building each one. You create a Makefile, and then run it through a program called "make". I'll be using the syntax of the more traditional Unix make (specifically that compatible with GNU make program), not the goofier variants espoused by Microsoft or Borland. We could jsut write a script, but using a makefile automates certain parts for us, especially if we want to add other features later on.

Makefiles list each target, followed by a ":", and then a series of 0 or more dependencies, separated by whitespace. The "#" is a single line comment. After a target, you can have a series of one or more rules. Each rule must be preceded by a single TAB character. I repeat, you must precede the rule by a TAB or make will crap out on you. Of course this is a stupid requirement, but that's make for you. Each target can be a file or just a symbolic name. If the target is a file name, make will attempt to determine if it is "up to date" (based on it's dependencies) before going ahead and building the target. If the target is a symbolic name (like ArdVark) it will always get built. So, without further ado, lets create our Makefile like so (make sure the file is just named Makefile):

Our Makefile has one variable book_ver. We can access it's value by using the $(<variable name>) syntax. We have one target "docs" with no dependcies, so it will always be built. If any rule fails (the execution returns a non-zero value) make will stop. If you remember our earlier issue with the HTML Help compiler and it not returning a succesful return code, despite actually creating the correct chm file, you'll see that we use a "-" character before the hhc rule. Using the "-" character tells make to ignore the return code and proceed on, even if the rule "fails".

Save the Makefile and then run make:

make docs

You should see the commands run and at the end of it all, you should end up with a simple.chm with the correct version, as specified in version.txt, and the original simpl.xml should still have it's "BOOK_VERSION" placeholder in it.

We're going to add one final thing to wrap this all up. Wouldn't it be neat if we could make a single file that we could use to hold all the current source documents that we are currently working on? It sure would! So lets add one more target to our make file:

You'll end up with the file simple-1.2.3.tar.gz which has all the source to your documentation! Cool.

There's lots more you can do with make, but I'll leave that as an exercise to the reader to play with that. Hopefully this gives you a basic starting point.

Conclusion

Well we have covered a whole lot of ground, and hopefully I didn't lose anyone! We've gone over the basics of DocBook content creation, discussed how to install and process the content to produce html and HTML Help based output. We've customized some of the style sheets for our own use, and written a makefile to support versioning and producing our DocBook generated HTML Help. If you have further questions explore the DocBook links I have provided in the article, feel free to email me, or better yet post a question below. Also, feel free to browse through the VCF's documentation and documentation Makefile. It covers everything in this article plus offers some other, more advanced, customizations.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

Share

About the Author

Currently working on the Visual Component Framework, a really cool C++ framework. Currently the VCF has millions upon millions upon billions of Users. If I make anymore money from it I'll have to buy my own country.

Comments and Discussions

Specifically, let's say I have output my docbook xml as HTML. Now I have a directory of static HTML pages and graphics. What I want though is to have a "wrapper" around those pages so that I can incorporate search and indexing into the docbook content. Much like the output of WebWorks - when it builds HTML from FrameMaker source (for example), it does so in a way that provides index and search.

I'm not really sure. You could customize your docbook output such that the header or footer html that's spit out has some custom "search" fields that then call some function (javascript?). If you do this you need to look at customizing the xsl style sheets. Beyond that, I don't really know.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

I've taken a look at the sample documentation files on your VCF project.

I surprized to see that there are source documentation (possibly produced by doxygen) which share presentation layer with the user documentation.

How did you do it?

I have googled about this subject but found outdated articles. They talk about need for writing an xlst - but nobody has that one. Then one can use doxygen output as docbook input to produce documentation that has the same look and feel.

I used docbook 1.66, 1.69, 1.7 with the same result. Simple.xml file contains exactly what you recommended to copy and paste into it. I'm not sure where the simple.xml file should be located. My docbook xsl is located as the path above shows, I tried to put simple.xml file into the same directory, but it did not make difference. I have libxslt tool properly installed so that xsltproc -version command gives correct result. Please, help. Thanks in advance.

Using DocBook on WindowsLong time ago, I bookmarked Jim Crafton's tutorial Documentation with Docbook on Windows to follow later in the hopes of installing (and using) docbook on my Windows box. Today I finally decided to download Cygwin

Following his instructions I installed the following:bashmakelibxsltsedtargzipfindand ofcouse Docbook-xsl-* and HTML Help Workshop by Microsoft.

At first I had selected UNIX like configuration but changed it to DOS like based on his suggestion.

I fired up the shell (Start > Programs > Cygwin > Cygwin Bash Shell) and was greeted with the following message:

Copying skeleton files.These files are for the user to personalisetheir cygwin experience.

Couple of things may be wrong:1) your system may not have xslt setup properly. Are you using Cygwin? If so are you running this from the Cygwin prompt (as opposed ot the regular DOS prompt)?2) Something new has changed in docbook 1.70. This worked in 1.69 - try and older version and see if that makes a difference. If it does work with the older version then chances are the new docbook is broken, or more likely it has changed and the simple.xml needs to be updated to reflect this.

You might try google and see if anyone else has run into these problem with this version of docbook.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

How to add support Context help and other Topic in .chm generated from the DocBook source?

In normal development process I link resource.h (#define IDC_XXXX 102) in help-project then write in source IDC_XXX, compile and call result chm from application. But inDocBook project I not understand where I should white IDC_XXX in source?

If you're referring to the popup help tips, then yeah you still have to set up all that manually, there are no provisions (as far as I know) for this in DocBook. So you need to edit the hhp generated by docbook and add this in manually.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

For those of you that want to save the hassle of manually setting up a DocBook environment, you might want to have a look at the >e-novative> DocBook Environment (eDE). It's a free GPL'ed ready-to-go DocBook environment for Windows.

I haven't looked at DocBook in great detail yet but I'm considering using it to provide a User Help / Training manual for one of my products. The product was made using Visual C++ 6.0. Here's my question....

As far as I can tell, DocBook supports the newer (HTML style) help system as favoured by Microsoft's HTML Help SDK. However, Visual C++ 6.0 seems to support only the older, "WinHelp" type Help projects.

How would I incorporate a DocBook generated Help system into a VC++ 6.0 project such that when Windows issues an ID_HELP command (e.g. when the user presses 'F1') my DocBook Help project would be launched?

Well first you need to get hte DocBook to generate HTML Help output. Then the next step is to customize your code to take advantage of the presence of the HTML Help as opposed to WinHelp. Take a look around CodeProject, as they have some articles that deal expressly with this. I hace done this several times at work, and it's not too bad. Maybe I should publish an article on this.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

If I have simple html like a horizontal ruler <hr/>, the parser warns "No template matches HR in section". It will parse but the generated html has the <hr /> converted to the entity references. Is there a way to have it "pass through" html without having to wrap everything with CDATA?

Apologies, I know this is covered in an earlier thread, but hopefully this subject line leaps out more.This does seem to be an xslt stylesheet problem. The stylesheet generates a 'next' reference in the HTML file for the final chapter to a non-existent ix01.html file, when it should simply omit the 'next' link.As a clue to DocBook experts, using 1.65.1 of the stylesheets, line 444 in html/chunk-common.xsl generates the ixNN filename to use with the Next button. However I haven't found where the button is generated, I suppose the relevant code needs to be conditionalised on whether we are generating the final chapter.As everyone has said, the problem is irritating rather than harmful to the user. The next button on the final chapter simply goes to a dead link. Pending a correction to the spreadsheet one can delete the next button from the HTML of the final chaper, a 'sed' application perhaps

If you are trying to organize a large document/book it seems like using Entities could get pretty messy. XInclude seems like a better way to organize large docs, are there other ways? Does any one have any suggestions or reference urls?

I prefer XInclude because every single file (for example chapter, sect1 or whatever)could be written with the complete header:<?xml ... ?><!DOCTYPE chapter ...>With the header my editor (which is jEdit) is able to check the file with the DTD and gives me information about the allowed tags etc.

Hi there i was following the tutorial and did it to the end... so, when running the make command i got some errors... ill paste them here to see if any of you could help to solve them!..

THe first error is this:HHC5003: Error: Compilation failed while compiling ix01.html.

The following files were not compiled:ix01.html

so i got all my files created, index.html , ch01. html... etc etc whe im navigating my files within IE or any other browser i reach the last page in my case chapter 2 and i have the navigation NEXT link that point to Index (no index.html), so when i click i get a page not found..

Anotehr question, how do i create relative path in my documentation.. my links are pointing to C:\cgywin.....\index.html... hos can i do for makin a "./ch01.html" instead the "c:\dir/subdir/ch01.html"

yeah.. about the path i noticed later that its ok.. the status bar was linking that but after checking the source html ive noticed tht path and its correct...

ok.. about the other error that you said i can ignore its ok.. but what happens with the lasd link that point to thatt file?.. ix01.html. when i hit next link in navigation on my last chapter i get a not found page

At the same time, even if the index.hkk file is generated it does not appears in the index.html file in any way, not even using html/docbook.xslThe index entries appear in the generated chm file though.

Couple of thingsHelp and Manual looks nice. However you can't do anything without the tool. And I believe you're limitied to *what* you transform to, by whatever the tool supports. This is not the case with docbook - want a output form - find or write the xsl transformation ,and you're good to go.Also docbook is cross platform, Help and Manual is not. DocBook is readily ammendable to large scale command line builds via shell scripts. My experience with most Help authoring programs is that they do not support command line builds very well, if at all (RoboHelp was awful for this). At the moment generating PDF with docbook is painful, so it appears Help and Manual's PDF support is a big win.

I just looked at the command line support, and it's quite nice - and you can control a number of parameters from a text file which is cool. A very nice program. However I still like docbook and it's my goal to have a decent editor and build tool that automates some of the icky internals of dealing with docbook adn building output.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

It sure is.In my scripts I usually define a variable that holds the full path to the HHC executable, and then just use the variable to refer to it. Alternately you can put the path to the executable in you PATH envirment variable and then just invoking hhc should do the trick.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

I wouldn't use this one, I think writing doc in XML is too slow. If you know javadoc, there is some similiar program - but puting the C(++) comments into html, and after downloading htmlhelp workshop puting into .chm file. After downloading doxybar, you can do it all at once - just one button press from your MSVC++.

I don't think that DocBook generates documentation from your source files like Doxygen. I may be completly off base here but it looks like you create xml files and it converts them to html help. I guess there is a reason for this but my first thought is why not write them in html in the first place?? But when I think about it a little I guess this way can be more powerful by letting you control the html output over the full documentation by making changes in the configuration.

Actually doxygen is strictly for generating source from embedded source code comments. It is not meant as a general, single source, documentation solution, whereas DocBook *is*. Also DocBook can generate output in man, latex, pdf, dvi, ps, and others.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

Jim, article is very good and I used your examples. This was my first experience with DocBook.I tried to test with non English (iso-8859-2 or windows-1250) text changed in your "simple" to transform xml to HtmlHelp. I read DocBook documentation and searched mail list to find the way. There are some solutions with saxon, but no one work on cygwin or I do some mistakes.Does you or anybody know any real example to solve of this problem?

Sorry about that, I have zero experience using DocBook this way. Did you try irc - if you go to irc.freenode.net port 6667 channel #docbook, there are usually people there hanging out that might be able to help. I got some help there when I couldn't find stuff on the web.

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!

Within DocBook, defining language is quite easy. Just give the element <book> an attribute lang with country-code (ISO 639, like nl for dutch, but you can also use extended code like en-us). <book lang="nl">.In this case I used Dutch, and all the tables will have the name Tabel (Table in Dutch ), figure will become Figuur, etc. Also TOC will be translated. If for some reason you want Figuur named differently, just open the lang-file found in the docbook-xsl-1.60.1/common folder, and change the fields:(in this case the dutch one: nl.xml, with the equivalent Afbeelding instead of Figuur)

If you like DocBook and/or XML editing in general and you are looking for a great XML editor, check out www.arbortext.com. Best XML editor around. Of course, I'm biased because I work for Arbortext. Not only do we support DocBook, we have our own custom extensions to DocBook -- we call it AxDocBook. I could not do it justice here if I tried to describe the extensions. It is best to check it out on our web site. Is editing in XML hard? Not really, just different. It takes some getting used to and it is easy if you have a great editor like Arbortext's Epic Editor. Not only do we support DocBook, but we also support any DTD/Schema you may want to define. Best of all, Epic can output your data to virtually any format -- web, pdf, html, paper, etc.... Ok, enough shameless self promotion... but seriously, check out www.arbortext.com for a great XML editor.

Do you guys ever sponsor open source projects (as long we are self promoting here )? If you do, check out mine at http://vcf.sf.net! I could certainly use this if it is as good as you say. Also if you're looking for a cross platfrom C++ app framework, you might consider the VCF Too bad you don't seem to have anywhere to download an eval version, and at $500 a pop that's out of my price range!

¡El diablo está en mis pantalones! ¡Mire, mire!

Real Mentats use only 100% pure, unfooled around with Sapho Juice(tm)!