- From: Dave Raggett <dsr@w3.org>
- Date: Thu, 31 Jul 1997 08:52:51 -0400 ()
- To: Jordan Reiter <jreiter@mail.slc.edu>
- cc: Brian Kelly <lisbk@ukoln.ac.uk>, eighner@io.com, www-html@w3.org
On Wed, 30 Jul 1997, Jordan Reiter wrote:
re ... separating 4.0 spec into several documents
> This would be excellent, especially since it could separate out
> some of the more technical and confusing information, such as DTD.
> People like being given clear boundaries, where it isn't so fuzzy
> about what is happening. Tell them, "Your document *must* contain
> a doctype declaration" in <plain English> (to use a somewhat
> limiting yet contextually accurate term), and they'll be more
> likely to put it in.
A general approach to describing elements, I've found
useful in the past is:
a) short introduction
b) motivating examples
c) DTD fragment for the element
d) detailed definition
For common attributes its convenient to provide a few words
only as a reminder, plus a link to the full description.
Some issues are:
o How to group definitions
e.g. alphabetically by tag name; according to the
role the tag plays in the DTD (block-level/inlines);
or thematically (scripting, style, basic idioms, ...)
o How to summarise the syntax
e.g. via DTD fragments or some other notation
Initial work on 4.0 tried to grouped the elements according
to the role they play in the DTD, plus some sections focussing
on particular topics. The current draft takes a somewhat
different approach, trying to group elements by the roles
they are used for in documents rather than in the DTD, for
instance, ignoring the block-level/inline distinction.
I would welcome feedback on the current draft and alternative
suggestions for structuring the specification, so as to
improve its effectiveness for a wide audience. I see this
audience as including implementors, web designers, authors
of HTML handbooks, and course designers. What do you think?
Regards,
-- Dave Raggett <dsr@w3.org> http://www.w3.org/People/Raggett
phone: +44 122 578 2521 (office) +44 385 320 444 (gsm mobile)
World Wide Web Consortium (on assignment from HP Labs)
Received on Thursday, 31 July 1997 08:53:13 UTC