Rami has written "The Smallest DocBook Big Picture," a good bird's-eye view of the documentation standard. DocBook is an SGML schema ideal for authoring articles (or books) and creating readable and appropriate text for various. While HTML and CSS are improving in media-specific output, DocBook is still the king.

The DocBook site says it "is a schema (available in several languages including RELAX NG, SGML and XML DTDs, and W3C XML Schema) maintained by the DocBook Technical Committee of OASIS." To put it in plain English, DocBook is a list of markup elements suitable for writing Documents and Books, hence the name. It's like HTML, in a sense that it has tags and uses plain text files, but unlike HTML, it’s more suitable for writing books. DocBook has no idea how your final document will look like. That's the job of the DocBook toolkit. When we want to start a new paragraph in HTML, we use a

paragraph

tag. The browser knows how to display a paragraph tag, it knows that it should insert a margin above and below. DocBook, following the same concept, uses a tag. DocBook uses a toolkit to read DocBook files and generate final documents. A toolkit has tools to validate DocBook files, apply formatting, import images, according to a set of rules defined in stylesheets.

HTML and CSS address different media by using a stylesheet for the media itself. For example, a document targeted for print or handhelds might have the following line:

The stylesheet would have a tag specifying the media type:

@media print { /* style sheet for print goes here */ }

This is a good way to manage media in HTML, but HTML still translates poorly to books, and compliance with CSS levels is various browsers is still unreliable. DocBook uses purely semantic tags for everything. Instead of , there's or . Instead of

and

, there are named sections: and . In addition, DocBook files are validating XML files, requiring matched tags. However, one crucial difference is that more people know HTML than DocBook. Thus, the "Big Picture" is good to have in hand, and there are a number of references to help get you started in DocBook if you're interested, including David Rugge's Writing Documentation Using DocBook: A Crash Course, which guides through the process fairly clearly (although with some dated elements).

Rami has written "The Smallest DocBook Big Picture," a good bird's-eye view of the documentation standard. DocBook is an SGML schema ideal for authoring articles (or books) and creating readable and appropriate text for various. While HTML and CSS are improving in media-specific output, DocBook is still the king.

If I'm not mistaken DocBook is XML based now or at least offers an XML-only option. Even with DocBook, you will (most likely) be using CSS if you are producing HTML. DocBook is more like a replacement for Word. I'm experimenting with DocBook articles for technical documentation and creating templates for generating DocBook documents. Does anyone have an recommendations for light-weight (preferably free) XML editors that are schema aware? Ideally this editor would be able to stand alone.

Does anyone have an recommendations for light-weight (preferably free) XML editors that are schema aware? Ideally this editor would be able to stand alone.

XMLBuddy is all you need. It's not stand alone, but why do you need to leave Eclipse?

This is a good way to manage media in HTML, but HTML still translates poorly to books, and compliance with CSS levels is various browsers is still unreliable.

I agree that CSS levels at various browsers are still unreliable, but why would you want to use a browser to generate your PDF anyways.? See my recent blog post about how we are using the prince html to pdf processor to generate great looking PDF files for the Apache Camel project. Hiram Iona Open Source the Enterprise Way

This is a good way to manage media in HTML, but HTML still translates poorly to books, and compliance with CSS levels is various browsers is still unreliable.

I agree that CSS levels at various browsers are still unreliable, but why would you want to use a browser to generate your PDF anyways.?

My question is why I would want write documentation in HTML? HTML couples the information with the format just like a word processing application does. What do I gain? I can just use OpenOffice and generate a PDF from there or buy a plug-in for Word and use that. Of course, if you already have a lot of HTML I can see how this would be useful but for those starting from scratch, it seems like a step in the wrong direction.

This is a good way to manage media in HTML, but HTML still translates poorly to books, and compliance with CSS levels is various browsers is still unreliable.

I agree that CSS levels at various browsers are still unreliable, but why would you want to use a browser to generate your PDF anyways.?

My question is why I would want write documentation in HTML?

You could use a wiki that generates the HTML if you don't wanna use HTML. Though there's a ton of rich HTML editors these days including the browser itself.

HTML couples the information with the format just like a word processing application does.

CSS! There's no need to put any formatting in your HTML other than the basic headings, paragraphs, lists and bold/italic. Let CSS do the rest. But I take your point; some users prefer to use Word/OpenOffice for documentation. Others prefer to use a wiki, CMS or HTML for documentation. Editing tools are like IDEs; quite personal things. James Iona Open Source the Enterprise Way

CSS! There's no need to put any formatting in your HTML other than the basic headings, paragraphs, lists and bold/italic. Let CSS do the rest.

I see bold and italic and headings as format information. But I don't want to be unfair because the difference between 'bold' and 'emphasis' is pretty subtle. The key for me is that like the extra semantic information in DocBook. For example, in my DocBook, I might have a code listing element. In HTML I can use a PRE element. Later in my DocBook I might put in a quote. In HTML that's another PRE element, or perhaps an italics element or whatever (I'm not really an HTML guy.) It seem to me that in the HTML case, I am losing information and I'm still deciding how it's going to look too early. I am absolutely open to new ideas on this. I'm probably missing something big about the approach with Camel. Again, I'm not really that great with HTML or CSS for that matter.

The key for me is that like the extra semantic information in DocBook. For example, in my DocBook, I might have a code listing element. In HTML I can use a PRE element.

I disagree. HTML can preserve the semantic meaning.. just do a google search for micro formats. We decided to use a Boom based micro format. Our code sections are just wrapped with

The key for me is that like the extra semantic information in DocBook. For example, in my DocBook, I might have a code listing element. In HTML I can use a PRE element.

I disagree. HTML can preserve the semantic meaning.. just do a google search for micro formats. We decided to use a Boom based micro format. Our code sections are just wrapped with

tags. In other words css classes can be used to tag the semantic meaning in the content.

I, um, don't quite think that CSS is *ever* meant for semantic meaning. I'm sure it can be used for that - after all, bold and italics tags offer "semantic" meaning - but I think that's a bit of an abuse of what stylesheets are meant to be.

The key for me is that like the extra semantic information in DocBook. For example, in my DocBook, I might have a code listing element. In HTML I can use a PRE element.

I disagree. HTML can preserve the semantic meaning.. just do a google search for micro formats. We decided to use a Boom based micro format. Our code sections are just wrapped with

tags. In other words css classes can be used to tag the semantic meaning in the content.

I kind of figured this would be the response. Isn't that really just reproducing DocBook in a less readable way? What's the advantage? More flexibility?

Isn't that really just reproducing DocBook in a less readable way? What's the advantage? More flexibility?

Flexibility, and common, commodity toolset. Granted, what's the difference between: and

Effectively none, save that most every computer in the world can render the latter (in some manner), and not the former.

If you mean browser when you say every computer (I work with one that doesn't render HTML by the way) sure. But browsers will render any XML. It will be plain (without a stylesheet) but so will div elements (without a stylesheet). And in terms of a toolset, I don't see much difference in getting apache camel instead of apache fop. Honestly I don't really care that much. I just think DocBook is a little cleaner and I get a lot of free stuff with it.

My question is why I would want write documentation in HTML?

You could use a wiki that generates the HTML if you don't wanna use HTML. Though there's a ton of rich HTML editors these days including the browser itself.

I was unclear here. What I mean is "why would I want to store my documentation as HTML?"

How does Prince differ from Flying Saucer?

DocBook in practice boils down to XSLT. Oldtimers will remember the battles between XSL and CSS that took place the XML camp in 1999 and that were memorialized in http://www.xml.com/pub/a/2000/06/21/deviant/index.html

Actually, scrap that. DocBook is more of an exchange format, which means it has to become popular in order to reach its potential.