At 22:04 09/01/2001 +0000, Gervase Markham wrote:
> > >Just about. A few site guidelines, such as "An H1 at the top, please, and
> > >H2s as major headings blah blah" should do the trick. We already have such
> > >things, of a sort - http://www.mozilla.org/README-style.html .
> >
> > No that doesn't do it at all, where is the project structure? Where the
> > horizontal structures?
>
>I don't follow.
The point I thought was to organise the documentation so that it was
structured not just within a particular documents but that the documents
themselves were structured together in ways which made it feasible to have
a variety of views depending on how a particular viewer sliced it.
So that, documents were identified as belonging to a particular project
(XUL for instance) and might also belong to other projects or other layers
of that project, (UI, Specifications, Guidelines, Tutorials, etc).
> > HTML strict or not is just layout it isn't logical
> > structure at all. Morphing things like headers as structural content
> > doesn't do the job.
>
>Headers _are_ structural content!
If HTML strict imposed rules on <Hn> then that might be true, but even then
it would be true relative only to other headers within the same
document. Having a convention external to the document that H1 means this
and H2 means that isn't structuring documents, especially when there is no
defined order to those tags. You can have H1 followed by H6 followed by H3
followed by H1.
Using HTML also presupposes that the document is somewhat fixed, especially
in relation to other documents and the links to them. The author, or more
accurately the document has to know the exact URL to link to (unless you
use some complicated CGI).
Originally I proposed a very small dialect of XML that would allow the
logical structuring of documents without imposing that pain on
authors. DpcBook is a very large and very complete method to do the same
thing and probably in structuring terms superior to a custom rolled
dialect, but it is more complicated.
To illustrate what I mean, imagine a document regarding plugins and the
browser. Its overall project is the Browser (whether SeaMonkey is
appropriate or not is irrelevant), it happens to be and end user document
and it contains examples and links to another document on 4.x plugins as
well as a reference to the plugin SDK.
Using HTML the document, other than within the content or its place within
a file system has no structured way of defining the project it belongs to,
that it is an end user document and that it contains examples. The
document also has to know within the content the URL of each of the other
documents which may or may not have been written by the same author, and in
fact they may not even exist as of yet.
A document with structure tags can resolve those issues, a straightforward
parser can then take that document and deliver its content appropriately.
You could have something like...
<document='MyDocumentFilename' project name = "Browser" level=enduser
topic='Plugin Overview'>
Text..... could include simple modifiers such as <B> <I> etc...
<connect project='Browser' type = 'document' topic='netscape 4.x
plugin support'/>
<example name='Example 1.'>
text of an example
</example>
more text....
<references rows = 25>
table of references text
<connect project='Browser' type = 'document' topic='Plugin
SDK'/>
<connect project='Unknown' type='http'
topic='www.reallygoodstuff.com/plugins'/>
</references>
</document>
And so on. The above structure was without a great deal of thought and
I'd certainly agree that there are holes in it, how would topics be defined
and so on (I'd go for a topic registry). I'd also not make it too
restrictive you could have the parser apply a strict DTD but allow tags it
didn't recognise to just live as part of the content, that way you needn't
reinvent wheels to cope with vestiges of layout markup a more appropriate
parser downstream can cope with the output.
It wouldn't be too onerous for someone to take either plain text or god
forbid HTML and tag it up with something like that kind of logical
structure, it certainly isn't beyond the wit of us to write a parser that
can take the above and emit HTML strict out the other side. Naturally CSS
would apply just as well as in any other XML dialect.
The advantages are that documents can be integrated in a variety of
directions without any of the documents needing to know precisely where the
others are in relation to them, content within documents (examples say),
can be addressed directly without too much pain and the level of
documentation itself can be structured so that you can see all the end user
documentation together or all the documentation for a project together.
A user browsing or downloading the documentation need only define the kind
of documentation they want and the appropriate documentation is delivered,
it becomes easier to treat this as a publishing exercise rather than a
dumping ground for barely laid out text with links that erode over time.
>
> > What on earth is wrong with having authors produce just content, why should
> > an author learn a HTML layout app?
>
>As opposed to Emacs to produce DocBook? Or are you recommending that
>everyone submit as plain text ASCII, and someone translates it into
>something browser-readable? I don't understand.
I've said people either submit plain text (I left out ASCII because of
double byte characters and such), or they submit it already logically
structured to whatever format is agreed on. The process of submitting
would mean that any document would have to go through some human somewhere
to either be structurally marked up or for it to be validated by a
validating engine. That in itself isn't too bad because documents have to
go through some kind of review process and as the tagging is not about
layout but about structure its actually a lot easier and a lot quicker to
do than to fix someone's badly formed HTML.
Of course if someone submits badly formed HTML in the first place that
would still take time to fix, hence my preference for submitting plain text.
> > Some of them may, that's true but an
> > awful lot of good authors know 4 things about creating documents on a
> > computer, how to open a document, how to operate a keyboard, how to save a
> > document and how to forget to save a document.
>
>Are we talking about "a lot of authors" or "a lot of authors who are going
>to be contributing documentation/pages to mozilla.org"?
Authors in general, my tongue was firmly lodged in the buccal cavity :-)
Simon
>Gerv
===============================================
The more exotic the Project name the more ordinary the Product
S.P.L.
