Docbook

[gstuckey]

I've been studying ArborText and going through theDocbook DTD, which is overwhelming. I have my trusty O'Reilly book tohelp me understand the descriptions for the elements. I have two weeks to do a proof of concept on just one page, a parts list.One problem is, I haven't spent enough time using Arbortext to set up the basics. The editor is no big deal andI understand entities and file references and quite like them.

Another problem is setting up theDocbook DTD. There is just so much in the DTD. Do I just need to pick out what I think I'll use and comment out the rest? How about when I get to service manuals and operator's manual where I have procedures and descriptive text in addition to pictures. How do I use the DTD for that if I've commented out elements? Is setting up a document template in ArborText the best way to get around it?

Ginger Shew-Stuckey
Technical Publications Specialist
Heil Environemental

[ebenton]

Assuming you have installed the supplemental doctypes or whatever they are called when you installed Arbortext Editor, if you launch the Editor and select File->New and then select either Arbortext XML DocBook V4.0 or DocBook V4.0 and then check the Sample box, you can get a sample document instance that you can play with and see what you want. There are <procedure> tags in the sample document as well.
If you want to use a modified DocBook DTD, see the Help about using a custom doctype. (Help 6676 in 5.2.)

[jdreystadt]

I suggest using one of the DTDs that comes with Arbortext Editor and do any customizations by tweaking the DCF or PCF files. Out of the box, there is a DTD called AxDocBook which is pretty much standard DocBook except for some alterations we made to make it easier to use.

Using the DCF file, you can hide elements or attributes that you would rather not have your authors using. That can go a long way towards getting all your authors to do things the same way. And it also makes it less overwhelming for new authors trying to figure out what all these tags mean and when to use them.

John Dreystadt
Software Development Director
Arbortext - PTC
734-352-2835
-

[gstuckey]

Thanks for the information. I think that I'm probably getting caught up in the process of getting from Word to XML. In my mind, the process goes something like:

1. Analyze documentation
2. Create DTD (using an existing DTD and modify)
3. Create templates
4. Create style sheets
5. Test
6. Revise DTD, templates, style sheets (Rinse and repeat)
7. Create documentation

I know that I want to control the tags that can be used in the documentation and I'm just not sure how to do that.

I've been looking at axdocbook. I'll also give the existing options in File/New a try as well. We will see.

Ginger