Documentation (Was: [OT] Too Quiet)

[Kurt Wall]

On Fri, Nov 05, 2004 at 01:40:47PM +1100, James McDonald took 29 lines to write:
> >* Converting MS Word documents, HTML help files, and SGML source files to
> > XML (almost done with that, actually)
> >* Updating the corporate style sheet for product documentation
> >* Working on XSLT transforms for said XML-based documentation
> >* Learning a new, odious XML editor (I was comfortable with emacs)
> >* Integrating document production into our existing build system
> >* Figuring out how to shoehorn document rendering into the new build
> > system
> I am finding an increasing need to document things in a standard and 
> portable manner.

XML is good.

> You mention that you are converting documents of varying formats into XML. 
> I am curious as to how you are doing this.

For the SGML source, I use osx (SGML->XML). For the Word format, I use
antiword. For the HTML, we wrote some macros and sed scripts to do the
heavy lifting. Interestingly, the Word->XML conversion was trivial using
antiword. The SGML->XML was slightly more involved. HTML->XML required a
lot of editing after the conversion, perhaps more a result of the lousy
HTML markup than anything else.

> Also the 'style sheet' you mention I have long wanted to have some sort of 
> template for documentation but can't seem to get started on docbook and the 
> like. Is it really as manual as it seems... I was wondering if there are 
> gui editors out there to make the markup.

"Style sheet" in this context means "style guide," which is about content,
conventions, usage, and diction rather than format, presentation, and
appearance.

> Can anyone recommend a book that can get one off the ground as regards 
> documentation.... I'm tired of having several formats. It would be nice to 
> have a central base format and then be able to spit out html/pdf/etc as 
> needed.

I recommend DocBook XML. I've found it easiest to start with small examples
that have the tags you need to use. You'll eventually want the DocBook book
(http://docbook.org/tdg/en/html/docbook.html) and, if you intend to use
XML, the DocBook XSL guide, written by a fellow I used to work with at
Caldera, Bob Stayton (see http://www.sagehill.net/docbookxsl/).

If you have other questions, it might be most prudent to contact me
off-list.

Kurt
-- 
Vote for ME -- I'm well-tapered, half-cocked, ill-conceived and
TAX-DEFERRED!