Javadoc comments or equivalent in XSchema

[Peter Murray-Rust]

At 19:55 25/07/98 -0800, Carl Hage wrote:
[... much useful stuff snipped...]

I'm very much in agreement with the sort of thing that Carl has been
doing/is_suggesting. A good 'schema' - whatever that evolves to - must have
componentised documentation, behaviour, semantics (however you interpret
that word) and so forth. I've been doing the same sort of thing with JUMBO,
trying to get an XML-driven application (In my own case it is driven by a
hyperglossary and some of those components can make useful documentation)

>
>As with javadoc, the documentation associated with a DTD shouldn't be a
bunch 
>of arbitrary HTML (IBTWSH) pages. The documentation for an element, etc. is 
>specific kinds of text that is assembled into various kinds of
documentation, 
>not something normally read in isolation. Javadoc uses the @ notation to 
>identify the semantics of the documentation text so it can format the
content 
>appropriately, including href links and names.

I think that IBTWSH was only ever meant to be a first step towards
increasing the value of schemas. It is a necessary first step - attaching
human-readable document to an XSC component in a way that is impossible
with DTDs. 

My hope is that the current XSC project will prove the concept of schemas
at the simplest level and this will provide a base to build on. Then, I
think, we shall benefit from an open discussion about what the next set of
components may be. Of course they may come from elsewhere (XML-data, RDF,
XSL, etc.) but we may need to assemble other sets - I think it's too early
to say. 

>
>I would be willing to write up a proposal for a set of elements useful in 
>documentation, though it will have to be a week from now. Without thinking 
>about it, the kinds of documentation elements I've used are something like:

[... snipped...]

As with all these things, anyone who make a persuasive case, has the
necessary e-charisma and is capable of putting in the effort has every
chance of seeing a successful XML-DEV project get off the ground :-) 

	P.


Peter Murray-Rust, Director Virtual School of Molecular Sciences, domestic
net connection
VSMS http://www.nottingham.ac.uk/vsms, Virtual Hyperglossary
http://www.venus.co.uk/vhg

xml-dev: A list for W3C XML Developers. To post, mailto:xml-dev at ic.ac.uk
Archived as: http://www.lists.ic.ac.uk/hypermail/xml-dev/
To (un)subscribe, mailto:majordomo at ic.ac.uk the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)