Javadoc comments or equivalent in XSchema

John Cowan cowan at
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
document structure.

> 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
> problems.

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
> banned.

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		cowan at
	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
Archived as:
To (un)subscribe, mailto:majordomo at the following message;
(un)subscribe xml-dev
To subscribe to the digests, mailto:majordomo at the following message;
subscribe xml-dev-digest
List coordinator, Henry Rzepa (mailto:rzepa at

More information about the Xml-dev mailing list