Documentation (Was: [OT] Too Quiet)

[Alma J Wetzker]

Kurt Wall wrote:
> 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.

Please don't go off list.  I am hearing more and more about this XML thing. 
If you are going to discuss something that might make the alphabet soup 
comprehensible, I would like to be included.

     -- Alma