Javadoc comments or equivalent in XSchema
cowan at locke.ccil.org
Mon Jul 27 15:39:05 BST 1998
Carl Hage wrote:
> As with javadoc, the documentation associated with a DTD shouldn't be a bunch
> of arbitrary HTML (IBTWSH) pages.
And I'm all for that. The point of IBTWSH is to provide just enough
support so that the non-predictable part of the documentation can
exploit rich text too. Javadoc does this haphazard, not documenting
which HTML tags are allowed and which will make a hash of the
> 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.
The IBTWSH analog of the Javadoc "@xxx" is the non-HTML tag "XML", which
has a content model of ANY, thus allowing random embedded stuff
which a Javadoc-type processor will of course need to interpret
and turn into smooth and flowing HTML.
> In contrast to tags marking the semantics of the parts of the documentation,
> use of certain presentation-oriented tags, e.g. <font> can cause serious
IBTWSH no longer has FONT.
> IBTWSH is a good basis, but I don't think all the tags in this set
> is appropriate for XSC documentation. Tags like <hr> should probably be
HR is not valid in XSchema documentation, because it is not part of
the parameter entity "horiz.model".
> Tags like <big> and <small> should be banned. The usual use is
> something like "<big><b>Something</b></big><br>" because some author doesn't
> like the way Nescape spaces <h3>Something</h3>. The usual reason for <small>
> is to wrap everything, because some author thinks the fonts are too big when
> view on his 21" monitor.
Nevertheless, there is a valid use, namely to mark <big>important</big>
and <small>unimportant</small> text respectively. The concept of
"fine print" is really a structural one, like that of "emphatic text",
and it's a pity that HTML 4.0 doesn't have a structural tag for it,
but it doesn't and too late to complain now.
John Cowan http://www.ccil.org/~cowan cowan at ccil.org
You tollerday donsk? N. You tolkatiff scowegian? Nn.
You spigotty anglease? Nnn. You phonio saxo? Nnnn.
Clear all so! 'Tis a Jute.... (Finnegans Wake 16.5)
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;
To subscribe to the digests, mailto:majordomo at ic.ac.uk the following message;
List coordinator, Henry Rzepa (mailto:rzepa at ic.ac.uk)
More information about the Xml-dev