RE: Help with Docbook

["Mark Baker" <mbaker -at- ca -dot- stilo -dot- com>]

> I want to create all documentation in XML - am not sure what tool to use I
> have looked at Xmetal and Framemaker and none grabbed my fancy although I
> couldn't figure out how to link in the docbook DTD's into XMetal and
> that's when I contacted their support about 3 weeks ago and haven't heard
> a peep from them since.

I'm afraid I don't have any immediate help to offer. In fact, I am just
taking advantage of Lisa's post to make point is that is often overlooked in
taking about moving to XML. Moving to DOCBOOK is not the same thing as
moving to XML.

DOCBOOK is a specific data format for which a number of specific tools
exist. The data format itself has its specific strengths and weaknesses. The
tools that work with DOCBOOK documents have their own specific strengths and
weaknesses. The DOCBOOK file format just happens to be expressed in XML (or
alternatively in SGML).

XML, on the other hand, is a specification for specifying tagging languages.
Tools exist to help you to design such tagging languages and to help you
develop applications to work with those languages.

When you adopt DOCBOOK you are adopting a specific format with specific
properties. It is similar to adopting FrameMaker format or XHTML or RTF. You
get specific capabilities and specific tools. The internals of the file
format do not matter to you any more in one case than they do in another.

Now some would argue that with an XML based format you can develop your own
processing code to process your documents in new and interesting ways. That
is true, but it is true of the other formats as well. Getting files in Frame
format or Word format into XML, so as to process them with XML processing
tools, is easy.

Some would argue that DOCBOOK's structures are more semantically rich than
those other formats. That is true in a limited way. DOCBOOK describes common
document structures, and you could write code that operated on those
structures without having to deduce them from stylistic clues, as you would
have to do with the Word of Frame format. However, there are three problems
with this.

1. Document structures by themselves do not really offer very many
interesting processing opportunities. For that you need specific information
about the semantics of the content itself.

2. DOCBOOK is huge, which means that processing applications have to account
for far more possible variations of structure than they would when
processing Word or Frame format -- a comprehensive DOCBOOK processing
application must be huge to accommodate all the possibilities.

3. People cheat. Because DOCBOOK is usually used with a potted set of
WYSIWYG editing and display tools, authors will often choose the element
that give the appearance they want rather than the one that correctly
describes the structures they are creating. (This is exactly what people do
with HTML, of course.) The result is that you cannot rely on the document
structure markup being an accurate reflection of the structure of the
document. That in turn means that you cannot process it reliably.

If you really need to do custom processing of your content, then, you need a
format that:

1. Has the ability to express the specific semantics of your content so that
you can process it in a meaningful way.

2. Is simple enough that it is possible to write comprehensive and reliable
processing code.

3. Is strict enough that people can't cheat or that cheaters can be easily
caught and corrected.

To accomplish these three goals, you need to develop tagging languages that
are specific to your content and the processes you want to apply to that
content. Any language that meets the above criteria must be small, strict,
and specific, and general purpose shared languages cannot be any of those
things.

It is when you start to develop your own tagging languages that you can
legitimately say that you are adopting XML, as opposed to adopting some
particular file format which may, incidentally, be expressed in XML.

The question of whether DOCBOOK is the right format/tool set for a
particular application remains an open one, but it is a question that must
be answered on a feature by feature comparison to other file formats/tool
sets such as Word, Frame, or XHTML. Adopting DOCBOOK is not adopting XML in
any meaningful sense.
---
Mark Baker
Stilo Corporation
1900 City Park Drive, Suite 504 , Ottawa, Ontario, Canada, K1J 1A3
Phone: 613-745-4242, Fax: 613-745-5560
Email mbaker -at- ca -dot- stilo -dot- com
Web: http://www.stilo.com

This message, including any attachments, is for the sole use of the
intended recipient and may contain confidential and privileged
information. Any unauthorized review, use, disclosure, copying, or
distribution is strictly prohibited. If you are not the intended
recipient please contact the sender by reply email and destroy
all copies of the original message and any attachments.





^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

NEED TO PUBLISH FRAMEMAKER CONTENT ONLINE? "Mustang" is a NEW single
sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required! http://www.ehelp.com/techwr-l3

Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot- 

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.