Re: Question: XML as data-tranfer tool - metadata in DTD

Subject: Re: Question: XML as data-tranfer tool - metadata in DTD
From: "Tim Altom" <taltom -at- simplywritten -dot- com>
To: "Guy K. Haas" <ghaas -at- selectica -dot- com>, "TechDoc List" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 31 Mar 2000 15:32:29 -0500

I guess I'm losing track of why you have to describe the DTD at all, unless
you have to paraphrase it. A DTD is just a text file and anybody who doesn't
know how to read one probably won't know how to read a representation of
one, either.

Your question presents a common problem, however, that of what to do when
the software, manual, or both are highly mutable. You see that a lot,
especially with enterprise software that can be modified on-site. Most
companies I'm familiar with supply two manuals: an operations manual for the
default operations, and an API for how to change things. But WHAT'S changed
and documenting it is the province of the user, not of the supplier.

Maybe if I could visualize the situation more clearly, I could recommend

Tim Altom
Simply Written, Inc.
Featuring FrameMaker and the Clustar(TM) System
"Better communication is a service to mankind."
Check our Web site for the upcoming Clustar class info

----- Original Message -----
From: Guy K. Haas <ghaas -at- selectica -dot- com>
To: TECHWR-L <techwr-l -at- lists -dot- raycomm -dot- com>
Sent: Friday, March 31, 2000 2:04 PM
Subject: Question: XML as data-tranfer tool - metadata in DTD

> I am documenting an API that returns data structures in XML.
> My (and my developer's) problem is that, although we see how
> pre-determined elements are specified in the DTD (Document Type
> Definition), we need to describe elements that are determined by a user.
> Example: In the DTD snippet
> <!ELEMENT books (title,authors)>
> <!ELEMENT title(#PCDATA)>
> <!ELEMENT authors(#PCDATA)>
> _books_ are composed of one _title_ element and one _authors_ element.
> What if the user is able to create another element of a book, such as
> _publisher_?
> How can we describe the DTD when some elements are hard-wired by the
> software manufacturer and some are added on the fly by the software
> user?
> TIA,
> Guy K. Haas
> Senior Technical Writer / Software Exegete
> Selectica, Inc.
> E-Mail: ghaas -at- selectica -dot- com


Previous by Author: Re: On degrees and the like...
Next by Author: Re: Single Sourcing
Previous by Thread: Question: XML as data-tranfer tool - metadata in DTD
Next by Thread: Re: Question: XML as data-tranfer tool - metadata in DTD

What this post helpful? Share it with friends and colleagues:

Sponsored Ads