Javadoc comments or equivalent in XSchema

[John Cowan]

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	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;
(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)