Time to Reorg the Doc? [Was: HTextArea form element ]
"Daniel W. Connolly" <connolly@oclc.org>
Date: Wed, 29 Jun 94 17:26:29 EDT
Message-id: <9406292125.AA04373@ulua.hal.com>
Reply-To: html-ig@oclc.org
Originator: html-ig@oclc.org
Sender: html-ig@oclc.org
Precedence: bulk
From: "Daniel W. Connolly" <connolly@oclc.org>
To: Multiple recipients of list <html-ig@oclc.org>
Subject: Time to Reorg the Doc? [Was: HTextArea form element ]
X-Listprocessor-Version: 6.0c -- ListProcessor by Anastasios Kotsikonas
X-Comment: HTML Implementation Group (Private)
In message <9406292018.AA13204@zeppo.East.Sun.COM>, Gary Adams - Sun Microsyste
ms Labs BOS writes:
>
>On the other hand if the PROPOSED elements were relegated to an Appendix of
>Future considerations, then it would be clearer that these elements do not
>reflect current practice, but are guiding principals for future spec writers
>and browser developers.
>
I've been wrestling with the idea of reorganizing the HTML document
into a normative part and an informative rationale, much like the
POSIX 1003.1 document.
The normative part would be somewhat minimalist, while retaining
enough info to be comprehensible in one or two readings. The rationale
section could contain all sorts of stuff
* proposed language changes
* pointers to discussion archives
* edited portions of those discussions
* known bugs in existing implementations
(e.g. comment parsing in Mosaic)
We could use two simple rules:
1. In the normative part, when in doubt, take it out.
2. In the rationale, when it doubt, leave it in.
The only thing is that this would be a pretty significant editorial
undertaking, and I wouldn't have any reliable way to track the
changes. We'd all have to carefully review the normative part when
this is done.
Every time I sit down to review and revise this thing, I think
"Crap. I just need to reorganize the whole thing." There are
widespread inconsistencies: internal conventions are sparsely followed
(e.g. mainstream/required/etc. status of elements); the spelling needs
checking; terminology is inconsistenly used (document/node/file). And
I get all caught up in the frontmatter -- "About this document" etc.
Depending on how the document is published, the packaging changes
significantly. The title page, headers and footers, revision history,
acknowledgements, and all that noise vary with the publication sytle
and audience. I'm tempted to make it look like an RFC or a LaTeX
article because folks are used to seeing that. But I don't have tools
to do that.
I've also been playing around with the FrameMaker/DocBook tools that
we have here at HaL. Is anybody out there planning to include this
with their docset? If I produced a DocBook version of this thing,
would that be valuable to folks? Or would you rather just take the
PostScript version and print that?
Sometimes I'm tempted to take a little bit of the verbiage from the
HTML files, stick it in the DTD, and call that the HTML 2.0 spec.
Then somebody else can write user documentation, tutorials, "how to
write a browser" documents, etc. -- stick all the stuff about how to
compose search URLs from ISMAP documents in there.
So let's inventory exactly what we require for an HTML 2.0 spec:
I invite folks to rate each of the following as:
5 - must have this for my purposes
4 - may have this, and I think it should
3 - may have this, but I don't care
2 - may have this, but I'd rather it did not
1 - must not have this
Connolly's Rating
Normative content:
* An SGML Declaration and one or more DTD subsets 5
* Minimal conformance definition 5
* Definition of element semantics 5
(e.g. what rendering distinctions MUST be made)
* Element reference 4
* Examples of recommended usage 3
* Explanation of operation of anchors, forms, ISINDEX, ISMAP 2
* Explanation of WWW linking and addressing 2
* Security Issues 2
(if only there were time...)
* Test Suite 4
Informative content:
* Publication History 4
* Summary of Changes since draft-iiir-html-01 4
* "Typical Rendering" instructions 3
* Historical notes about browser implementations that 3
conflict with the SGML standard
* Examples of common authoring errors 3
* Rationale behind contentious issues 3
(e.g. "why P is a container")
* Proposed language changes 3
Navigation Features and Media:
* A Postscript format file 5
* A collection of HTML nodes 4
* A plain text format file 4
* A DocBook document 3
* List of Reviewers 5
* Revision History 4
* Numberd Sections 4
* Title page 3
* Abstract 3
* Index 3
Publication Forums/Audiences:
* Publication through the IETF as an RFC or FYI 4
* Publication through the Davenport group 3
* Publication through SGML Open 3
Dan