Proposed way forward
James Green
run out of ideas and steam to drive them.
Thus I shall propose the following:
1). Those people who would like to see us use some form of cvs gateway
for those who don't have cvs or don't know how to use it can contribute
to the site, well you guys bring it to the table in a demonstratable
form, and we'll all take a look. I have no objections to adding such a
feature but it would be plain wrong to go off and develop it and then
find we can't use it for whatever reason... It would be much better if
only those interested in it were to try it first, the rest should
concentrate on the html/css and perl side of it.
2) The above also goes for the SGML/DocBook people. I just spoke to Dawn
Endico who says that making everyone use DocBook is out of the question,
but if parts of the site were available in such a form it would be great
(obvious rationale there). So again, bring to the table a demonstratable
system, and we'll look into making it work. That doesn't have to mean a
team of people doing a html->docbook translation, it could mean a
selected area html->docbook translation of say end-user documentation.
Whatever.
3) If you are one of those who believes firmly that using a database to
serve up the content, then you make a nice, quick-to-use interface, and
we'll take a look. If it's that quick to use, it should be no problem
with moving our work out of files and into the database, right? Again,
this should be interested parties only.
4) Am I right in thinking that XHTML1.0 and HTML 4.01 Strict are roughly
the same, at least in terms of code used and end result in browsers? If
so, we need to settle on one or the other.
5) We also need to settle on layout mechanisms. I tried to use floating
divs to lay out the homepage, and it was unsuable in netscape 4 (divs
floated above links and prevented them from being clickable). I would
suggest that we use <table>s, but without html attributes. Sadly that
means combining the current site's navigation menu with the main content
into one table, but it's that or risk being unusable in other browsers.
Blame the browser engineers, then cheer those who are reversing the
trend of non-compliance in the more recent browsers.
6) We need to settle on filesystem layout and URI layouts. Some have
been suggested, I'm not aware of anything we should be working to. It's
make our minds up time.
7) Layouts. Do we keep the current layout, even in a basic navbar on the
left, content on the right, system? We need to see suggestions on the
web. Use your homepages space.
8) I suggest several of us come up with designs that validate and that
also look good on older browsers. Once we have something that we would
be proud of seeing on mozilla.org and that doesn't make people using Nav
4.x on unix puke, then we go and see Dawn for final approval, then we
make the rest of the site work too.
Remember, this is my proposal.. Don't flame me saying you don't agree
with something, instead suggest an alternative.
Oh, and apparently we must work well on Nav 4.x on Solaris. So Dawn says.
If anyone's interested in hopping onto IRC, irc.mozilla.org
#documentation, I'll be around.
James Green
Simon P. Lucy
Alright we seem to have slowed down in here, which means we've probably run out of ideas and steam to drive them.
As a developer needing documentation I have very little interest in the delivery of content, I'd be happy with a bunch of text files so long as the content was accurate and easy to find. The emphasis is on easy to find so I for one would place high on the list a fast search engine, LXR pointed at the documentation would be fine.
So far as the delivery is concerned I think its important to deliver content in a variety of ways. There are still a great many people that suffer from phone connections at a per minute/second rate, providing only browsable material won't encourage those people to actually read the documentation.
There are also people of ancient grey matter such as myself that like to print things out, especially if they are formal specifications, I've yet to see a HTML presentation printed that wasn't badly laid out. Whilst PDF is truly awful at some things (pagination for example), it is a coherent package for printing material though the effort to get a reasonable result shouldn't be underestimated.
Thus I shall propose the following:
1). Those people who would like to see us use some form of cvs gateway for those who don't have cvs or don't know how to use it can contribute to the site, well you guys bring it to the table in a demonstratable form, and we'll all take a look. I have no objections to adding such a feature but it would be plain wrong to go off and develop it and then find we can't use it for whatever reason... It would be much better if only those interested in it were to try it first, the rest should concentrate on the html/css and perl side of it.
2) The above also goes for the SGML/DocBook people. I just spoke to Dawn Endico who says that making everyone use DocBook is out of the question, but if parts of the site were available in such a form it would be great (obvious rationale there). So again, bring to the table a demonstratable system, and we'll look into making it work. That doesn't have to mean a team of people doing a html->docbook translation, it could mean a selected area html->docbook translation of say end-user documentation. Whatever.
That means that if authors don't mark up their document in some way then someone else has to as I think has been pointed out.
Simon
Beware knowledge cheaply gained
for in the spending of it you may pay more than its worth.
S. P. Lucy
James Green
> At 00:20 08/01/2001 +0000, James Green wrote:
[ snip ]
> There already are gateways for cvs available with and without secure access.
Good. What we need is something that can work within the mozilla.org
setup. Those who want to see this happen, email end...@mozilla.org who's
interested in seeing such a thing, and keep the rest of us informed of
your progress/outcome. It will be interesting to see if this actually
results in something that gets used heavily or not.
>> 2) The above also goes for the SGML/DocBook people. I just spoke to
>> Dawn Endico who says that making everyone use DocBook is out of the
>> question, but if parts of the site were available in such a form it
>> would be great (obvious rationale there).
[ snip ]
> I'm trying to understand what out of the question means. I can
> understand not all authors/contributors being willing to hack a DTR for
> their document, I can understand a little less that they wouldn't be
> able to insert <chapter> </chapter> tags and the like but I don't
> understand incorporating content (regardless of the structure used),
> without it conforming to a single recognised and supported structure.
Putting a little more context into what she was saying, I believe the
problem was getting the document authors (of which many are outside
contributors) to all use the same thing. Getting them all to use
Composer is not easy (choice of editor is a very personal thing), but
getting them all to use DocBook would be nigh-on impossible, at least
initially.
If initial work were done on getting the site into DocBook format, and a
mechanism found that kept everything up-to-date, even getting authors tp
use DocBook, that wasn't time consuming and doesn't involve everyone
using special software that may or may not run in their environment,
then there's a possibility that all authors could See The Light and
start *wanting* to use DocBook. Of course, if everybody did use DocBook,
how would new contributors get involved?
Like I said, I'm not throwing the idea out of the window, but afaict
Dawn shares my opinion that DocBook isn't implementable since the
authors would have to change their ways too much. If a middle-layer army
of convertors was available to do html->docbook conversion then it too
would have to prove that it could work in a timely and accurate manner
that didn't piss the authors off. Remember, authors expect their work to
be put on line, not converted into DocBook and lose or change
presentational effects.
> If there is no codifying of the content then the documentation is still
> going to be an unholy mess.
You have a better idea? Bring a workable DocBook or alternative solution
to the table, and I'm sure we'll be more than happy to look at it. I
personally do not like the idea of storing out documentation in HTML
either, it present many archectural problems, but until everyone who
produces the documentation is happy to change the system, it stays (imo).
James Green
Simon P. Lucy
Simon P. Lucy wrote:
At 00:20 08/01/2001 +0000, James Green wrote:
[ snip ]
There already are gateways for cvs available with and without secure access.
Good. What we need is something that can work within the mozilla.org setup. Those who want to see this happen, email end...@mozilla.org who's interested in seeing such a thing, and keep the rest of us informed of your progress/outcome. It will be interesting to see if this actually results in something that gets used heavily or not.
There is a project on Sourceforge with a web client for CVS I've emailed the owner of the project.
<delenda est...>
Putting a little more context into what she was saying, I believe the problem was getting the document authors (of which many are outside contributors) to all use the same thing. Getting them all to use Composer is not easy (choice of editor is a very personal thing), but getting them all to use DocBook would be nigh-on impossible, at least initially.
If initial work were done on getting the site into DocBook format, and a mechanism found that kept everything up-to-date, even getting authors tp use DocBook, that wasn't time consuming and doesn't involve everyone using special software that may or may not run in their environment, then there's a possibility that all authors could See The Light and start *wanting* to use DocBook. Of course, if everybody did use DocBook, how would new contributors get involved?
Like I said, I'm not throwing the idea out of the window, but afaict Dawn shares my opinion that DocBook isn't implementable since the authors would have to change their ways too much. If a middle-layer army of convertors was available to do html->docbook conversion then it too would have to prove that it could work in a timely and accurate manner that didn't piss the authors off. Remember, authors expect their work to be put on line, not converted into DocBook and lose or change presentational effects.
This is much like a magazine where the editor and compositors flow and layout text and pictures and the authors provide copy. Editors of magazines are more than happy to get plain text that they can then layout to their hearts content. (umm pun not intended :-))
The worst position I can see is for everyone to submit their own carefully honed HTML and then try and squidge that into some kind of shape. If the authors can indicate logical content by some means (whether that's DocBook or something less I really don't care), then all the better but it isn't necessary that can be done by someone else. I certainly wouldn't mind structuring plain text, though I wouldn't particularly want to hack about with HTML laid out text I'd be able to do that as well. All bearing in mind that there is a structure.
But to carry on without defining a structure to the content is a waste of time.
If there is no codifying of the content then the documentation is still going to be an unholy mess.
You have a better idea? Bring a workable DocBook or alternative solution to the table, and I'm sure we'll be more than happy to look at it. I personally do not like the idea of storing out documentation in HTML either, it present many archectural problems, but until everyone who produces the documentation is happy to change the system, it stays (imo).
Sure, only accept plain text or structured text to whatever form that's agreed. Plain text can be simply laid out with a template regardless of whether any structure is applied to it previously or not. Once decided on (whether its DocBook or anything else), that can be applied to the plain text.
That's not to say there aren't still difficulties, tabular information for instance is a pig to define in just text since it relies on using delimiters, but then again the prettiness of the content isn't relevant for the submission. There would need to be some understanding as to what constitutes a paragraph and a page and if graphics were included then written instructions would have to be attached to the plain text in a separate file.
None of that is pretty but it is manageable, allowing chaos at the time of submission though isn't.
Simon
James Green
Gervase Markham
> for those who don't have cvs or don't know how to use it can contribute
> to the site, well you guys bring it to the table in a demonstratable
> form, and we'll all take a look.
That's all very well, but we are deciding things in the wrong order. If,
for example, we decide to use Zope to manage the site (which is quite
possible - st...@mozilla.org have a good relationship with the Zope
people, and we may well be able to get them to lend us a Zope guru. Also,
it solves a great deal of the problems we are looking at, including ease
of update, in one go) then this problem goes away.
> 2) The above also goes for the SGML/DocBook people. I just spoke to Dawn
This is _so_ out of the question, it's untrue :-) There is no way that you
will get all the contributors to a website of this size to work in these
formats; and anyway, it's very bad form for an organization dedicated to
the promotion of web technologies to then claim they are unsuitable for
its website source.
> 3) If you are one of those who believes firmly that using a database to
> serve up the content, then you make a nice, quick-to-use interface, and
> we'll take a look. If it's that quick to use, it should be no problem
> with moving our work out of files and into the database, right? Again,
> this should be interested parties only.
Again, I think this is the wrong way to look at it. Either a (specified)
database solution is the right way to go, or not. If it is, we should all
work towards that end. If it isn't, no-one should be spending time
prototyping. If we can't all agree on what site management solution to use
(with homebrew being an option) then we may have to have a vote, or ask
staff@ for a final verdict.
> 4) Am I right in thinking that XHTML1.0 and HTML 4.01 Strict are roughly
> the same, at least in terms of code used and end result in browsers? If
> so, we need to settle on one or the other.
No, absolutely not - particularly where Mozilla is concerned. See Henri's
comments - XHTML, served as application/xml, is passed through the XML
parser. HTML of any form goes through the HTML parser.
Regarding Matthew's earlier comments, which I can't find, it would be
_very_ _bad_ to use XHTML and serve it as text/html - without enforcing
the well-formedness constraint on XHTML from the very start, you are
throwing away the world's best chance to have a HTML-esque format which is
zero-cruft, and can be understood by lightweight parsers which don't need
to deal with broken code.
> 6) We need to settle on filesystem layout and URI layouts. Some have
> been suggested, I'm not aware of anything we should be working to. It's
> make our minds up time.
Again, this problem goes away if we use a content management system. More
important is the navigational layout, which is a separate thing which
keeps getting conflated with the filesystem layout and even the URI
layout.
> Oh, and apparently we must work well on Nav 4.x on Solaris. So Dawn says.
If it works on Nav 4.x on any platform, it should work on the others -
right?
Gerv
Gervase Markham
> presentational effects. They are providing content not layout. This is
this is exactly what HTML 4.01 Strict with a site-wide style sheet should
achieve. We don't need DocBook to get this (very laudable) goal.
HTML 4.01 Strict is designed for exactly the problem you are stating, and
has the added bonus that it renders readably, if not prettily, in legacy
browsers.
Gerv
Simon P. Lucy
> > Well in this regard the authors have very little say in terms of the
> > presentational effects. They are providing content not layout. This is
>
>achieve. We don't need DocBook to get this (very laudable) goal.
>
>HTML 4.01 Strict is designed for exactly the problem you are stating, and
>has the added bonus that it renders readably, if not prettily, in legacy
>browsers.
Does HTML 4.01 Strict give the logical structure? It also seems a high
barrier for contributing content, I'm not concerned with the layout of it.
Simon
>Gerv
We are not here to be nice to people.
Gervase Markham
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 .
> It also seems a high
> barrier for contributing content, I'm not concerned with the layout of it.
You can create HTML 4.01 strict in Mozilla Composer (just about) or by
running HTML Tidy over any other HTML.
Gerv
Matthew P. Barnson
How do I know if that H1 is the title of the page, or just something a person
wanted really big?
How does one know if that "<P>" tag indicates a block of addresses, a break
between paragraphs, or what?
How do I know if the "<pre>" tag indicates a block of commands to be executed
by the user, or just a chunk of a note someone threw into the page and didn't
have time to mark up?
The key thing is: what audience are we targetting with our documentation? If
the audience is *solely* web-based, yeah, standardizing on HTML is better
than nothing. But what if someone needs to print them out? HTML looks
butt-nasty when printed, I'm sorry. What if a publisher wishes to reprint
the documentation in book form? He will have an enormous time investment by
someone to convert it to a format the publisher can use. What if you want to
implement a search engine? The engine will pick up titles, meta tags,
comments, etc. and have no clue what type of data it is looking at, thus
continuing to make the Web more of a morass than it already is.
Semantic markup is vital to progress -- although I understand the concerns
that people should not be required to write in DocBook (and I quite agree),
it should be allowed and supported because those DocBook XML authors have
invested the time to make the world a better place : )
Mozilla supports XML, too, if I recall correctly -- DocBook is also an XML
DTD and, if the DTD is correctly installed on the users computer, should be
readable...
--
Matthew P. Barnson Manager, Systems Administration
Excite@Home mbar...@excitehome.net
"There is no spoon" -- Neo
Simon P. Lucy
> > Does HTML 4.01 Strict give the logical structure?
>
>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? 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.
> > It also seems a high
> > barrier for contributing content, I'm not concerned with the layout of it.
>
>You can create HTML 4.01 strict in Mozilla Composer (just about) or by
>running HTML Tidy over any other HTML.
What on earth is wrong with having authors produce just content, why should
an author learn a HTML layout app? 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.
Those four things actually seem to be the only thing any writer remembers
even if when not writing they are immersed in far more technical pursuits.
Simon P. Lucy
Simon
We are not here to be nice to people.
Gervase Markham
> How do I know if that H1 is the title of the page, or just something a person
> wanted really big?
Because if they wanted it really big, they shouldn't be using H1 to
achieve that :-) That's the "strict" part - it means "content markup only,
not presentational".
The "Strict" bit is partly the way you use it, as well as the definition.
> The key thing is: what audience are we targetting with our documentation? If
> the audience is *solely* web-based, yeah, standardizing on HTML is better
> than nothing. But what if someone needs to print them out? HTML looks
> butt-nasty when printed, I'm sorry.
Not if you apply a "printer" style sheet to stop it looking so. With a
site-wide sheet, this would only need to be written once.
> What if a publisher wishes to reprint
> the documentation in book form? He will have an enormous time investment by
> someone to convert it to a format the publisher can use.
Actually, not really. If the markup is content-only, any form of
conversion can be reasonably well automated.
> Semantic markup is vital to progress -- although I understand the concerns
> that people should not be required to write in DocBook (and I quite agree),
> it should be allowed and supported because those DocBook XML authors have
> invested the time to make the world a better place : )
HTML 4.01 Strict is semantic mark-up. :-)
> Mozilla supports XML, too, if I recall correctly -- DocBook is also an XML
> DTD and, if the DTD is correctly installed on the users computer, should be
> readable...
However, NS 4 and IE 4 don't :-(
Gerv
Gervase Markham
> >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.
> 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!
> 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.
> 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"?
Gerv
Matthew P. Barnson
don't know enough about it to discuss it intelligently yet. As soon as I am,
I'll pop back in with a revised opinion based upon my reading.
I like the old Mozilla.org strategy, when it comes to documentation:
"Write Some"
Peace, outtie for now.
Matthew Thomas
>...
> Regarding Matthew's earlier comments, which I can't find, it would be
> _very_ _bad_ to use XHTML and serve it as text/html - without
> enforcing the well-formedness constraint on XHTML from the very start,
> you are throwing away the world's best chance to have a HTML-esque
> format which is zero-cruft, and can be understood by lightweight
> parsers which don't need to deal with broken code.
I don't believe that for a moment. And the reason I don't believe it is
that XHTML 1.0 Transitional (which is what I propose we use) exists at
all. XHTML Transitional wouldn't exist, if XHTML hadn't been intended to
be served to clients which only understand text/html.
> > 6) We need to settle on filesystem layout and URI layouts. Some have
> > been suggested, I'm not aware of anything we should be working to.
> > It's make our minds up time.
>
> Again, this problem goes away if we use a content management system.
No, it doesn't. We need to minimize linkrot whether or not we use a
content management system. A content management system might make it
easy to keep links on our own site up to date, but it will do nothing to
update links to mozilla.org which reside on other people's Web sites and
bookmark lists.
> More important is the navigational layout, which is a separate thing
> which keeps getting conflated with the filesystem layout and even the
> URI layout.
To mazimize usability, the URI structure should match the navigational
structure as much as possible.
> > Oh, and apparently we must work well on Nav 4.x on Solaris. So Dawn
> > says.
>
> If it works on Nav 4.x on any platform, it should work on the others -
> right?
>...
No. 4.x versions for different platforms have different crasher bugs.
--
Matthew `mpt' Thomas, Mozilla user interface QA
Gervase Markham
> > _very_ _bad_ to use XHTML and serve it as text/html - without
> > enforcing the well-formedness constraint on XHTML from the very start,
> > you are throwing away the world's best chance to have a HTML-esque
> > format which is zero-cruft, and can be understood by lightweight
> > parsers which don't need to deal with broken code.
> >...
>
> I don't believe that for a moment. And the reason I don't believe it is
> that XHTML 1.0 Transitional (which is what I propose we use) exists at
> all. XHTML Transitional wouldn't exist, if XHTML hadn't been intended to
> be served to clients which only understand text/html.
What _benefits_ are there in using XHTML over HTML 4.01 Strict? I'm not
going to post Henri's opinion here a third time, but I do agree with it -
using XHTML without enforcing well-formedness at the browser is just
asking for trouble.
I remember reading, in a bug I think, that they had a big argument about
this on the W3C list. I am pretty sure that the conclusion was XHTML as
text/xml only, and HTML as text/html, but I'm not certain. dbaron (among
others) would know.
> > > 6) We need to settle on filesystem layout and URI layouts. Some have
> > > been suggested, I'm not aware of anything we should be working to.
> > > It's make our minds up time.
> >
> > Again, this problem goes away if we use a content management system.
>
> No, it doesn't. We need to minimize linkrot whether or not we use a
> content management system. A content management system might make it
> easy to keep links on our own site up to date, but it will do nothing to
> update links to mozilla.org which reside on other people's Web sites and
> bookmark lists.
If we use a content management system, there's no such thing as a
filesystem layout. Therefore there's no argument as to what it should be.
The only thing is the navigation layout (see below.)
> > More important is the navigational layout, which is a separate thing
> > which keeps getting conflated with the filesystem layout and even the
> > URI layout.
>
> To mazimize usability, the URI structure should match the navigational
> structure as much as possible.
But the navigational structure won't be a tree. At least, I would have
thought it wouldn't be - the problems we've had deciding where things live
are symptoms of the fact that, navigationally, some things live in two or
more places.
> > If it works on Nav 4.x on any platform, it should work on the others -
> > right?
> >...
>
> No. 4.x versions for different platforms have different crasher bugs.
But the rendering is basically the same? It's not like IE 5 for
Mac/Windows. Right?
Gerv
Simon P. Lucy
> > >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?
>
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.
Gervase Markham
> (XUL for instance) and might also belong to other projects or other layers
> of that project, (UI, Specifications, Guidelines, Tutorials, etc).
Fine, but what has it to do with HTML coding guidelines to produce a
consistent layout?
> 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.
Not if we have site-wide guidelines.
> 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.
Yes it does, if we use a document management system - you will be able to
attach metadata to a document.
With your XML dialect, you are attempting to re-solve a well-understood
problem in website management. We should use an already-produced solution
rather than rolling our own. This would be an order of magnitude less work
than defining everything from the ground up, as you suggest, writing all
the tools, and then (and this is the really impossible bit) getting people
to use them.
We will have enough trouble getting document authors to use Mozilla
Composer rather than Netscape Composer without them having to learn a
whole new XML dialect.
Gerv
Simon P. Lucy
> > 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).
>
>consistent layout?
Absolutely nothing I have very little interest in layout, but considerable
interest in content. I've said before to conflate the submission of
content with the delivery of content is wrong, the two are separate.
>
> > 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.
>
>Not if we have site-wide guidelines.
Err, that just isn't true. How does using <H1> get enforced? The tag <H3>,
for example, couldn't mean the level of a document, end-user, developer,
distributor because there's no further modifier all it can show is relative
structure within one document. Would it make sense to abstract all content
between <h3> tags from all documents? That's the kind of horizontal
structuring I'm talking about.
> > 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.
>
>Yes it does, if we use a document management system - you will be able to
>attach metadata to a document.
You mean metadata outside the body of the document? That is better than
nothing but it itsn't as useful as marking up the content logically. Where
is the metadata to come from? It seems a basic mistake to separate the
content from the logical structure especially when its easier not to.
>With your XML dialect, you are attempting to re-solve a well-understood
>problem in website management. We should use an already-produced solution
>rather than rolling our own. This would be an order of magnitude less work
>than defining everything from the ground up, as you suggest, writing all
>the tools, and then (and this is the really impossible bit) getting people
>to use them.
No, the XML dialect is an example of an implementation and exactly the kind
of implementation that XML was designed for, DocBook is another, HTML is
not a solution to this problem because its devoid of structural
tags. There's only one tool that's needed and that is a small refashioning
of an existing parser and in the case of DocBook even that isn't
required. Nobody need use any additional tools to contribute
documents. As far as maintenance of already marked up documents is
concerned, editing the content and so on, the text remains sufficiently
transparent for the original author to edit whilst ignoring the markup.
>We will have enough trouble getting document authors to use Mozilla
>Composer rather than Netscape Composer without them having to learn a
>whole new XML dialect.
They don't have to, I've already said that, they may learn and use it if
they wish but there's no need to compel them. Relatively few people need
to be involved in marking up documents whether it uses a novel XML variant
or DocBook.
Gervase Markham
> >consistent layout?
>
> Absolutely nothing I have very little interest in layout, but considerable
> interest in content. I've said before to conflate the submission of
> content with the delivery of content is wrong, the two are separate.
Not if the same bit of software is dealing with both.
> >Yes it does, if we use a document management system - you will be able to
> >attach metadata to a document.
>
> You mean metadata outside the body of the document? That is better than
> nothing but it itsn't as useful as marking up the content logically. Where
> is the metadata to come from?
It's entered when you add the document. This would be your "document
project name" and "document level" data.
> It seems a basic mistake to separate the
> content from the logical structure especially when its easier not to.
I'm not saying you need to separate the content from the logical
structure.
> >With your XML dialect, you are attempting to re-solve a well-understood
> >problem in website management. We should use an already-produced solution
> >rather than rolling our own. This would be an order of magnitude less work
> >than defining everything from the ground up, as you suggest, writing all
> >the tools, and then (and this is the really impossible bit) getting people
> >to use them.
>
> No, the XML dialect is an example of an implementation and exactly the kind
> of implementation that XML was designed for,
Yes. Indeed. However, I am disputing that a) we need to use any
specialised application of XML at all and b) if there were advantages to
doing so, that we'd be able to persuade anyone to use it.
> >We will have enough trouble getting document authors to use Mozilla
> >Composer rather than Netscape Composer without them having to learn a
> >whole new XML dialect.
>
> They don't have to, I've already said that, they may learn and use it if
> they wish but there's no need to compel them. Relatively few people need
> to be involved in marking up documents whether it uses a novel XML variant
> or DocBook.
Do you really think we will find long-term volunteers to do the extremely
tedious job of accepting documents in whatever forms you allow, converting
them to this XML dialect, just to watch them get converted back to HTML
again?
Simon, I don't want to be rude, but there is not a snowball's chance that
we will go down this route. Among other criteria, we are looking for:
1) Relative ease of deployment - everyone is busy
2) Low barriers to document contribution
3) Low maintenance
It fails all of these. If I suggested to st...@mozilla.org that what
www.mozilla.org needs is for us to write an entire document-handling
system based around an invented XML dialect for document description,
their reaction would be... interesting.
Gerv
Simon P. Lucy
> > >Fine, but what has it to do with HTML coding guidelines to produce a
> > >consistent layout?
> >
> > Absolutely nothing I have very little interest in layout, but considerable
> > interest in content. I've said before to conflate the submission of
> > content with the delivery of content is wrong, the two are separate.
>
That's a basic mistake.
<forgetting the rest.... :-)>
>Do you really think we will find long-term volunteers to do the extremely
>tedious job of accepting documents in whatever forms you allow, converting
>them to this XML dialect, just to watch them get converted back to HTML
>again?
You've already had two volunteers and the display of documents has very
little to do with the management of the structure so I don't see why anyone
would care, that's a little like saying that database administrators have
their feelings hurt if someone produces a report. The work isn't lost, its
used.
>Simon, I don't want to be rude, but there is not a snowball's chance that
>we will go down this route. Among other criteria, we are looking for:
>
>1) Relative ease of deployment - everyone is busy
Using structured markup is no harder if the work is segmented
properly. Over time authors may learn the minimal amount of tags required
to structure their own documents but it isn't necessary. There are two
volunteers already.
>2) Low barriers to document contribution
Providing plain text seems a very low barrier, far lower than requiring the
use of a particular tool.
>3) Low maintenance
The maintenance of already tagged documents is certainly no worse than
using HTML and usually easier because the actual content is relatively intact.
I don't mind if you are rude :-). I've said before its a relatively low
level task to mark up plain text structurally. I wasn't particularly
nominating my off the cuff dialect much as I might find it appealing,
that's not at all important. I have been trying to emphasise that HTML,
whether strict or not is not a suitable form for contributing content and
structuring it in a logical fashion. After all that is what we have now
and the result is a mess, continuing in the same way will only produce a
different mess later on.
>It fails all of these. If I suggested to st...@mozilla.org that what
>www.mozilla.org needs is for us to write an entire document-handling
>system based around an invented XML dialect for document description,
>their reaction would be... interesting.
I haven't suggested anything like that and any way I think I've shown that
it meets all of the above criteria. You might think it entirely pointless
but as other documentation projects solve the same problems in similar
ways, as publishing generally works in a similar way with authors providing
content and someone else being responsible with how that content is laid
out and yet a third is used to provide indexing it might just be worth
thinking about.
This is a documentation project, not the management of a web site, the web
site is just one possible medium.
P.S. For some reason your machine thinks its the 9th :-)
James Green
[ snip ]
> What _benefits_ are there in using XHTML over HTML 4.01 Strict? I'm not
> going to post Henri's opinion here a third time, but I do agree with it -
> using XHTML without enforcing well-formedness at the browser is just
> asking for trouble.
>
> I remember reading, in a bug I think, that they had a big argument about
> this on the W3C list. I am pretty sure that the conclusion was XHTML as
> text/xml only, and HTML as text/html, but I'm not certain. dbaron (among
> others) would know.
Just spoke with dbaron. While he didn't go into detail, the essence was
that xhtml wasn't ready to serve mozilla.org. Quite what isn't ready
(the specs or the clients) we didn't go into, although hints were made.
Basically, it's a no-no in his opinion from what I could tell.
[ MPT: links and management systems ]
>> No, it doesn't. We need to minimize linkrot whether or not we use a
>> content management system. A content management system might make it
>> easy to keep links on our own site up to date, but it will do nothing to
>> update links to mozilla.org which reside on other people's Web sites and
>> bookmark lists.
Doesn't that rather depend on what the content management system
actually does?
[ on to navigational structure ]
> But the navigational structure won't be a tree. At least, I would have
> thought it wouldn't be - the problems we've had deciding where things live
> are symptoms of the fact that, navigationally, some things live in two or
> more places.
How does that help prevent linkrot? Whether it is primarily flat or
heirarchical in structure, links will still be present to anywhere else
in the site.
I don't think we can prevent linkrot entirely, simply because we cannot
predict the future. However if the structure is natural and linear
(/en/news/2001/01/10 is a good example imo, as is
/en/developer/building/unix or whatever) then hopefully rot will be
minimised.
>>> If it works on Nav 4.x on any platform, it should work on the others -
>>> right?
>>> ...
>>
>> No. 4.x versions for different platforms have different crasher bugs.
> But the rendering is basically the same? It's not like IE 5 for
> Mac/Windows. Right?
From what I have heard, even tables render differently in IE3/4/5. From
the conversation I had with Dawn Endico Sunday evening, I think she will
accept HTML 4.01 Strict with CSS providing Netscape 4.x gets a reduced
stylesheet that does not expose the layout bugs in it, or none at all.
I *think* I can get her to accept CSS onto the site providing Navigator
4.x across all platforms gets sent html/css that still renders the page
'prettily' even if it's quite basic. She really worried me when she
hinted that no css at all would be preferable... but I'll work on that
front :)
I am looking into Zope as a content management system... So far just
creating an initial website is proving a hassle (you need an add-on
'product' to provide for multiple sites). I'll stick at it, and try to
fit it in with my normal work schedules.
James
psr
am working the design of a new website, so have been reading up a lot on
this sort of thing. Maybe I can be of some help.
Matthew P. Barnson wrote in message
<0101091547...@jarjar.imall.com>...
>I'll do some more reading tonight on HTML4 with "strict mode" -- I'm afraid
I
>don't know enough about it to discuss it intelligently yet. As soon as I
am,
>I'll pop back in with a revised opinion based upon my reading.
HTML 4.01 Strict DTD is for HTML which is litrally Strict HTML 4.01, HTML
which conforms precisely to the recomendation. This means that it allows
none of the depreciated tags and attributes, such as layout tags like font,
and tag attributes such as color= (why oh why no 'u') and align=, as these
should all be replaced by CSS. Unfortunately older browsers really don't do
CSS well, so HTML Transitional exists so that these tags can be supported.
If you want your page to appear anything other than black on grey to NS 2 or
3, you will need HTML transitional. (And there can be nothing wrong with
it, since the w3c use it on thier front page).
However HTML 4.01 is no longer the current html recomendation, XHTML 1.0 is.
XHTML is basically the same as HTML, with the same strict, transitional, and
Frameset modes. Basically it is HTML 4 tweaked to be XML, all tags are
lower case, and all of them must be closed, all attributes must be quoted.
It's not much extra work, but I'm sure it must be worth some Karma or
something, and you would then have a fully buzzword compliant website.
I must admit to liking the idea of using Docbook for the documentation pages
and converting them to HTML, I use LaTeX for all my writing, and having well
structured documents makes them much more useful.
>I like the old Mozilla.org strategy, when it comes to documentation:
> "Write Some"
Good Idea, where do I start.
--
psr
->8O)
[from address in headers munged, reply to address should be ok]
fantasai
> 6) We need to settle on filesystem layout and URI layouts. Some have
> been suggested, I'm not aware of anything we should be working to. It's
> make our minds up time.
This is the one thing that must be *completely finalized* when it goes
in; we're not going to change the URI structure once it's in effect.
Go take a look at the current mozilla.org tree; there are a /lot/ of
files have yet to be taken into account. I think you're rushing this one.
~fantasai
fantasai
Even if we use a content management system, there will still be a
hierarchy in the URI layout. Whether there is a filesystem matching
the URIs or a database below that is irrelevant; you link to the URI,
not the physical file.
> > > More important is the navigational layout, which is a separate thing
> > > which keeps getting conflated with the filesystem layout and even the
> > > URI layout.
> >
> > To mazimize usability, the URI structure should match the navigational
> > structure as much as possible.
>
> But the navigational structure won't be a tree. At least, I would have
> thought it wouldn't be - the problems we've had deciding where things live
> are symptoms of the fact that, navigationally, some things live in two or
> more places.
The navigational structure is a web, more or less. But a good web--
an /organized/ web--has strong spokes for filaments to attach to,
and those spokes are the URI hierarchy. They maintain organization,
provide a well-defined path for navigation, and can be oriented to
when lost.
Matthew P. Barnson
> The navigational structure is a web, more or less. But a good web--
> an /organized/ web--has strong spokes for filaments to attach to,
> and those spokes are the URI hierarchy. They maintain organization,
> provide a well-defined path for navigation, and can be oriented to
> when lost.
You just hit on a critical, oft-ignored problem with the Web currently --
URI structure is often random and haphazard. Certain sites, such as sun.com,
structure things in a manner that's naturally logical to a customer --
staroffice support is located at www.sun.com/staroffice, for example.
Logical heirarchy (I'm talking READER logical, not necessarily "management"
logical) is incredibly important here.
Whether it's a filesystem or a content management system like (ugh!) Zope,
you're still going to have the same navigational and organizational issues.
However, what Zope makes a lot easier:
Implementing searching is trivial
A massive rearrangement of heirarchy is trivial
Because of Zope's ability to "acquisition" (kind of the opposite of
inheritance) properties regarding its location, it is easy to embed a
document in multiple locations, with correct inheritance depending on the URI
calling it.
I think there are some other advantages. One of these days, we may play
with it again here, but for now it burned us too bad before.
Umm, I'm really not sure what the point of this post is, other than to say
"aye" to fantasai's last comment above.
Gervase Markham
> that xhtml wasn't ready to serve mozilla.org. Quite what isn't ready
> (the specs or the clients) we didn't go into, although hints were made.
> Basically, it's a no-no in his opinion from what I could tell.
I think that if two of the most knowledgeable web standards people I know
say not to use XHTML, then that's good enough for me.
> > But the rendering is basically the same? It's not like IE 5 for
> > Mac/Windows. Right?
>
> From what I have heard, even tables render differently in IE3/4/5. From
> the conversation I had with Dawn Endico Sunday evening, I think she will
> accept HTML 4.01 Strict with CSS providing Netscape 4.x gets a reduced
> stylesheet that does not expose the layout bugs in it, or none at all.
>
> I *think* I can get her to accept CSS onto the site providing Navigator
> 4.x across all platforms gets sent html/css that still renders the page
> 'prettily' even if it's quite basic. She really worried me when she
> hinted that no css at all would be preferable... but I'll work on that
> front :)
I think that this would be the ideal.
Henri Sivonen has just written an HTML 4.01-compliant version of the
wrapper. You should be able to find the patches soon in
http://bugzilla.mozilla.org/show_bug.cgi?id=64932 . This demonstrates that
we can do a lot which works even in Netscape 4.x. It uses a site-wide
style sheet, which we could add a few more things to to provide us with
functionality for marking up the actual content.
Gerv
Gervase Markham
> >tedious job of accepting documents in whatever forms you allow, converting
> >them to this XML dialect, just to watch them get converted back to HTML
> >again?
>
> You've already had two volunteers and the display of documents has very
> little to do with the management of the structure so I don't see why anyone
> would care, that's a little like saying that database administrators have
> their feelings hurt if someone produces a report. The work isn't lost, its
> used.
>
> >Simon, I don't want to be rude, but there is not a snowball's chance that
> >we will go down this route. Among other criteria, we are looking for:
> >
> >1) Relative ease of deployment - everyone is busy
>
> Using structured markup is no harder if the work is segmented
> properly. Over time authors may learn the minimal amount of tags required
> to structure their own documents but it isn't necessary. There are two
> volunteers already.
You do realise that there are something like 10,000 legacy documents on
mozilla.org you'd have to convert?
Also, if someone wants to write something and whack it up there, to meet a
need, they'd be a bit annoyed if they had to send it off to someone to do
a conversion first. Particularly if that person was on holiday.
> >2) Low barriers to document contribution
>
> Providing plain text seems a very low barrier, far lower than requiring the
> use of a particular tool.
It isn't, because are used to contributing website content with HTML
editors.
> After all that is what we have now
> and the result is a mess, continuing in the same way will only produce a
> different mess later on.
The mess we have currently is not the fault of the way we mark up the
content. :-)
> >It fails all of these. If I suggested to st...@mozilla.org that what
> >www.mozilla.org needs is for us to write an entire document-handling
> >system based around an invented XML dialect for document description,
> >their reaction would be... interesting.
>
> I haven't suggested anything like that and any way I think I've shown that
> it meets all of the above criteria.
Maybe I've misunderstood your proposal. You want all documents for the
website to be submitted as, or converted by volunteers to, your XML format
(or DocBook.) You then want them converted (either on the fly, or
once-only) to HTML for sending to browsers. You also want to write all the
necessary site management tools to deal with all this stuff.
Furthermore, you want us to throw away any possibilities of using any of
the myriad of currently-written tools, such as search indexers, that work
with HTML content. We also can't use a database because, again, they are
all based around the idea that you use HTML.
> You might think it entirely pointless
> but as other documentation projects solve the same problems in similar
> ways,
The mozilla.org website is not (except in some parts) a documentation
project in the same way that linuxdoc.org is. If you ask them, I very much
doubt they have their website pages originally written as anything other
than some form of HTML.
Gerv
Matthew Thomas
>
> Gervase Markham wrote:
>...
> > What _benefits_ are there in using XHTML over HTML 4.01 Strict? I'm
> > not going to post Henri's opinion here a third time, but I do agree
> > with it - using XHTML without enforcing well-formedness at the
> > browser is just asking for trouble.
> Just spoke with dbaron. While he didn't go into detail, the essence
> was that xhtml wasn't ready to serve mozilla.org. Quite what isn't
> ready (the specs or the clients) we didn't go into, although hints
> were made. Basically, it's a no-no in his opinion from what I could
> tell.
Well, I just spoke with Ian Hickson on IRC ... He had no problem with
serving XHTML 1.0 Transitional as text/html. Then I mentioned that the
site in question was mozilla.org, and he said: `Oh. Then I'm with what
henris and dbaron said.' His explanation was filled with much
hand-waving and mentioning of `tag soup', and I thought I understood it,
but I can't remember the gist of it now. :-/ And I still don't know why
XHTML Transitional exists, if it wasn't meant to be sent as text/html.
However. Apparently my fears of using HTML making it more difficult to
migrate to XML later were groundless; Ian tells me it would be trivial
to write a utility to convert from HTML 4.01 to XHTML 1.0. And in that
case, I have no objection to using HTML (apart from my own personal bias
towards XHTML, which is a result of having inadvertently written all my
Web pages in XHTML since before XML was invented).
I cannot take seriously, however, any suggestion that we use Strict
rather than Transitional. People would laugh at us. `Ooo, if their Web
browser is so great, why is their Web site is all gray and boring?' We
need to have a BODY element with all color attributes filled in (as
mozilla.org does now), for the next three or four years until browsers
without style sheet support drop off the radar. (Note that in the next
couple of years, the Web at large may well be asking users of Navigator
4.x and Internet Explorer 4.x: `please turn off style sheet support in
your browser, because if you don't you're making life extremely
difficult for the rest of us'.)
> [ MPT: links and management systems ]
>...
I don't need to respond to Gervase's objections here, since Fantasai did
that very well already. :-)
>...
> I don't think we can prevent linkrot entirely, simply because we
> cannot predict the future. However if the structure is natural and
> linear (/en/news/2001/01/10 is a good example imo, as is
> /en/developer/building/unix or whatever)
Erm, no. Language should be done using the Accept-Language: HTTP header,
not the URL. On the occasions that you needed to link to a particular
language version (e.g. `Does this translation look all right to you?'),
you'd use something like
<http://mozilla.org/contribute/hacking/build/unix/?de>.
>...
> From the conversation I had with Dawn Endico Sunday evening, I think
> she will accept HTML 4.01 Strict with CSS providing Netscape 4.x gets
> a reduced stylesheet that does not expose the layout bugs in it, or
> none at all.
>...
AFAIK, this can be done by using an @import command in the main
stylesheet, since that is a command which 4.x does not recognize.
--
Matthew `mpt' Thomas, Mozilla user interface QA
Mozilla UI decisions made within 48 hours, or the next one is free
Simon P. Lucy
>You do realise that there are something like 10,000 legacy documents on
>mozilla.org you'd have to convert?
Yes I'm not unaware that it would take time to modify existing documents, a
lot of that could be automated for a basic restructuring that could be
further refined later. As further refining is low on the scale of
probability the likelyhood is that the documents will become out of date
and be replaced by documents that are better structured.
>Also, if someone wants to write something and whack it up there, to meet a
>need, they'd be a bit annoyed if they had to send it off to someone to do
>a conversion first. Particularly if that person was on holiday.
So they'll be able to whack it up without any consultation process?
>
> > >2) Low barriers to document contribution
> >
> > Providing plain text seems a very low barrier, far lower than requiring the
> > use of a particular tool.
>
>It isn't, because are used to contributing website content with HTML
>editors.
Ummm you can't have your cake and eat it. You can't say that using
Composer is a barrier to new authors submitting and then say you can't use
the lowest common denominator because you are used to contributing with HTML.
> > After all that is what we have now
> > and the result is a mess, continuing in the same way will only produce a
> > different mess later on.
>
>The mess we have currently is not the fault of the way we mark up the
>content. :-)
Quite a lot of the mess is because its assumed that all a web site is is a
collection of HTML there is no structure that makes sense. Confusing the
submission of content with the delivery of content is a plain and basic
mistake.
> > >It fails all of these. If I suggested to st...@mozilla.org that what
> > >www.mozilla.org needs is for us to write an entire document-handling
> > >system based around an invented XML dialect for document description,
> > >their reaction would be... interesting.
> >
> > I haven't suggested anything like that and any way I think I've shown that
> > it meets all of the above criteria.
>
>Maybe I've misunderstood your proposal. You want all documents for the
>website to be submitted as, or converted by volunteers to, your XML format
>(or DocBook.) You then want them converted (either on the fly, or
>once-only) to HTML for sending to browsers. You also want to write all the
>necessary site management tools to deal with all this stuff.
The XML I gave was an off the cuff example to explain the kind of
structuring required if you want to achieve a logical structure that allows
documents to be delivered in a variety of ways and at the same time defend
against link rot. DocBook is an existing way of doing the same thing, its
learning curve is a little steeper than a simpler XML dialect which is why
I used an example dialect to illustrate the kind of process needed. But
that's what it was, an illustration.
Using either DocBook or XML does not preclude using HTML (I just think HTML
a god awful way of submitting content its the wrong tool for the job), I
was emphasising that the barrier to submission is constraining authors to
any format other than plain text. Constraining submissions to a particular
tool is going to reduce the number of authors still further, not increase them.
>Furthermore, you want us to throw away any possibilities of using any of
>the myriad of currently-written tools, such as search indexers, that work
>with HTML content. We also can't use a database because, again, they are
>all based around the idea that you use HTML.
Bollocks. Indexers such as LXR don't care about syntax, there are plenty
of indexers that don't care about the format of what is indexed, exclusion
syntax isn't very complicated. Thinking that a database cares about HTML
is asinine it could just as easily use XML, XML to database storage is
_simple_ that's part of the point of XML.
I can accept a great many objections as being valid, inserting a structural
markup step for instance might seem to make the process lengthier and more
tortuous but if you are constraining to HTML Strict you have that step
anyway. What I think is unacceptable is NIH as a reason for not
considering something.
Other than a parser, and DocBook doesn't require that, nothing I've
suggested requires the use of outlandish tools, it isn't reinventing wheels
its using wheels to build a better carriage.
> > You might think it entirely pointless
> > but as other documentation projects solve the same problems in similar
> > ways,
>
>The mozilla.org website is not (except in some parts) a documentation
>project in the same way that linuxdoc.org is. If you ask them, I very much
>doubt they have their website pages originally written as anything other
>than some form of HTML.
So Mozilla is never going to have documentation that end users and
distributors can use because its more important to do a web site?
I'm not one to flog dead horses, even if they are throroughbreds, so unless
anyone has any observations on it that take it forward I'll drop it
completely. :-)
Gervase Markham
> migrate to XML later were groundless; Ian tells me it would be trivial
> to write a utility to convert from HTML 4.01 to XHTML 1.0.
Yes - it's called HTML Tidy; the W3C have written it :-)
> And in that
> case, I have no objection to using HTML (apart from my own personal bias
> towards XHTML, which is a result of having inadvertently written all my
> Web pages in XHTML since before XML was invented).
What? With the trailing slashes on standalone elements ( <BR /> ) and
everything? :-)
> I cannot take seriously, however, any suggestion that we use Strict
> rather than Transitional. People would laugh at us. `Ooo, if their Web
> browser is so great, why is their Web site is all gray and boring?' We
AIUI, it would only be grey and boring in NS 4.x. Everything else that
matters supports style sheets well enough, doesn't it? Or am I sadly
deluded?
Is anyone going to make an argument for us writing a site that looks good
(as opposed to readable, which is fair enough) in version 3 browsers? No?
Good :-)
Gerv
Matthew Cruickshank
Although not on the scale of Mozilla's 10,000
documents I set up a Docbook system that exported to
HTML,PDF,RTF and it's flexibility has paid off.
/me volunteers for docbook conversion.
>MPT sez:
>AFAIK, this can be done by using an @import
>command in the main stylesheet, since that
>is a command which 4.x does not recognize.
You are correct, good sir.
_____________________________________________________________________________
http://au.classifieds.yahoo.com/au/car/ - Yahoo! Cars
- Buy, sell or finance a car..
Matthew Thomas
>...
> > And in that case, I have no objection to using HTML (apart from my
> > own personal bias towards XHTML, which is a result of having
> > inadvertently written all my Web pages in XHTML since before XML was
> > invented).
>
> What? With the trailing slashes on standalone elements ( <BR /> ) and
> everything? :-)
Yup. And the space before the trailing slashes, to work around Navigator
3.x. And the lower-case tags. The only thing I was missing was the XML
declaration, for which I think I can be excused on the grounds that XML
declarations didn't exist at the time.
> > I cannot take seriously, however, any suggestion that we use Strict
> > rather than Transitional. People would laugh at us. `Ooo, if their
> > Web browser is so great, why is their Web site is all gray and
> > boring?' We
>
> AIUI, it would only be grey and boring in NS 4.x.
Um, a *very* large proportion of Mozilla's potential base of testers and
developers are currently using 4.x.
> Everything else that
> matters supports style sheets well enough, doesn't it? Or am I sadly
> deluded?
>...
If you consider Internet Explorer 4.x's style sheet support to be
adequate, then no you're not.
Gervase Markham
> 3.x. And the lower-case tags. The only thing I was missing was the XML
> declaration, for which I think I can be excused on the grounds that XML
> declarations didn't exist at the time.
One question. Why?!?
Did you have an SGML childhood?
> > > I cannot take seriously, however, any suggestion that we use Strict
> > > rather than Transitional. People would laugh at us. `Ooo, if their
> > > Web browser is so great, why is their Web site is all gray and
> > > boring?' We
> >
> > AIUI, it would only be grey and boring in NS 4.x.
>
> Um, a *very* large proportion of Mozilla's potential base of testers and
> developers are currently using 4.x.
Are you sure? According to http://www.mozilla.org/webalizer/ , for
December and January, no 4.x User Agents feature in the top 15.
Admittedly, those stats are a bit pants as it's not amalgamating them
together correctly (I have mailed Dawn about this), but still, it shows
_something_...
> > Everything else that
> > matters supports style sheets well enough, doesn't it? Or am I sadly
> > deluded?
> >...
>
> If you consider Internet Explorer 4.x's style sheet support to be
> adequate, then no you're not.
There are no IE 4's in the top 15 either ;-)
Seriously, other sites have managed it, haven't they? Why can't we?
Gerv
James Green
[ snip what we should all know already ]
> Unfortunately older browsers really don't do
> CSS well, so HTML Transitional exists so that these tags can be supported.
> If you want your page to appear anything other than black on grey to NS 2 or
> 3, you will need HTML transitional. (And there can be nothing wrong with
> it, since the w3c use it on thier front page).
Not quite:
Content-Type: text/html; charset=us-ascii
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
We are advised against using text/html for xhtml.
James.
fantasai
> I cannot take seriously, however, any suggestion that we use Strict
> rather than Transitional. People would laugh at us. `Ooo, if their Web
> browser is so great, why is their Web site is all gray and boring?' We
> need to have a BODY element with all color attributes filled in (as
> mozilla.org does now), for the next three or four years until browsers
> without style sheet support drop off the radar. (Note that in the next
> couple of years, the Web at large may well be asking users of Navigator
> 4.x and Internet Explorer 4.x: `please turn off style sheet support in
> your browser, because if you don't you're making life extremely
> difficult for the rest of us'.)
I don't have a problem with serving HTML Transitional for
coloring and suchlike. But the documents must be /written/
to HTML 4.01 Strict before going through the wrapper.
~fantasai
Matthew P. Barnson
Will you provide the location of sources and/or documentation to create
such a system?
The Internet functions because of great ideas and RUNNING CODE. If we have
a system available that is proven to work *well* (unlike the current morass),
it counts more than 10,000 arguments that another way is better.
As always, my two cents. Don't take it personally. All opinions are those
of the author. YMMV, CYA, BYOB ASAP, etc.
On Thursday 11 January 2001 05:31, Matthew Cruickshank scratched this in the
dirt:
> I set up a Docbook system that exported to
> HTML,PDF,RTF and its flexibility has paid off.
>
> /me volunteers for docbook conversion.
--
psr
>Not quite:
>
>Content-Type: text/html; charset=us-ascii
>
><!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
> "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
>
>We are advised against using text/html for xhtml.
From the W3C recomendation for XHTML 1.0
http://www.w3.org/TR/xhtml1/#media ):
5.1 Internet Media Type
As of the publication of this recommendation, the general recommended MIME
labeling for XML-based applications has yet to be resolved.
However, XHTML Documents which follow the guidelines set forth in Appendix
C, "HTML Compatibility Guidelines" may be labeled with the Internet Media
Type "text/html", as they are compatible with most HTML browsers. This
document makes no recommendation about MIME labeling of other XHTML
documents.
So why is it that using XHTML Transitional is so wrong? Somebody said
something somewhere about tag soup, but I don't know what that was meant to
mean. I know that there may be no technical advantage in using XHTML 1 over
HTML 4, but I can't see that there is any technical dissadvantage either,
and saying that you can change it all once XML has become common place, does
not seem valid to me. I do however think that regardless of their being few
real *technical* differences, it has to be in mozilla.org's favour to be
seen to be using the cutting edge standards *now*, since mozilla is supposed
to be the standards compliant browser.
The best solution IMHO would be the following:
* Docs are submitted in some form of simple markup language (Docbook seems
like a good idea to me, as, if I understand correctly, it places lots of
emphasis on the structure, and very little on the layout, which makes it
easy for other people to customise the look and feel for thier own use in
any format, be it web based or otherwise) - Again, since this is an XML
application (am I right here?) we appear to be on the cutting edge.
* These docs are converted into XHTML by a script, with a standard Style
Sheet. The script can add some mozilla.org structural stuff to the tops and
bottoms of the file, maybe encapsulating it in a table - maybe not. The
files are put onto the webserver, served as text/html (which can be changes
easily enough later), and just for good measure the W3C validator is run
over it (since it doesn't mind about the MIME type). The Docbook (or
whatever) files are tarballed and squirreled away in a download section
somewhere, along with postscript, pdf, text etc. etc. versions.
I'm not trying to stir up arguments here, I really do just want to know what
is wrong with any of the above. Since I am working on something slightly
simillar for my own website, I really do have an interest in the problems in
using XHTML.
Thanks,
psr
Matthew P. Barnson
> * Docs are submitted in some form of simple markup language (Docbook seems
> like a good idea to me, as, if I understand correctly, it places lots of
> emphasis on the structure, and very little on the layout, which makes it
> easy for other people to customise the look and feel for thier own use in
> any format, be it web based or otherwise) - Again, since this is an XML
> application (am I right here?) we appear to be on the cutting edge.
You are correct; DocBook has both SGML and HTML variants. As a matter of
fact, if you design your DocBook SGML document correctly (principally, adhere
to all lowercase tagging), you can simply substitute a new DTD declaration to
make it XML, and vice-versa.
It''s a very flexible system, and superb documentation can be created with
the use of only a half-dozen different tags. If you want to get fancier with
ensuring you declare what type of text any given chunk is, you can use all
200+ tags.
The learning curve for DocBook XML, for anybody with HTML tagging
experience, is very very shallow. If you've never tagged anything before,
it's still fairly trivial. The steep part of the learning curve is getting
your SGML/XML editing environment set up -- and nobody's provided a popular,
easy tool for that yet : (
Emphasis on structure is my principal focus in this group -- that we know
that a chapter heading is a chapter heading, and not simply an H2 tag, that
table of contents can be arranged automatically and easily with low
maintenance, and that the documents be easily exportable to various formats
beyond HTML (ergo: printed bound, plain text, RTF, etc.) The only thing I've
seen that allows this kind of flexibility and low-end entry point is DocBook
XML/SGML.
As has been mentioned in previous threads, however, there are some barriers
to entry there, and a massive history of documents yet to be converted. I've
volunteered for the conversion duty, and have seen at least one other poster
who has as well (as soon as I finish my Bugzilla Guide, that is!)
> * These docs are converted into XHTML by a script, with a standard Style
> Sheet. [snip]
> DocBook ... files are tarballed and squirreled away in a download section
> somewhere, along with postscript, pdf, text etc. etc. versions.
Exactly the point of my first posting to the group. I plan on eventually
submitting The Bugzilla Guide for print and sale -- I can publish it cheaply
enough, and already know several people interested in buying a copy. Not
that I'd make any money on it, really, that is not my intention. The
widespread use and ubiquity of Bugzilla is my principle goal, and making
documentation available in printed form helps that goal along.
> I'm not trying to stir up arguments here, I really do just want to know
> what is wrong with any of the above. Since I am working on something
> slightly simillar for my own website, I really do have an interest in the
> problems in using XHTML.
Well, I believe I can sum up the argument fairly well (correct me if I'm
wrong)
1. "Anti-DocBook": How can people easily use a validating XML editor to
submit their documents? There aren't many, and those available are
considered hard-to-use or proprietary/commercial.
"Pro-DocBook": volunteers (such as myself) agree to tag submitted content
to DocBook XML, and ask submitters to send it to us in whatever format is
agreeable to them. Perhaps we could request the help of the Linux
Documentation Project folks in doing this, since they have a longer history
of doing so successfully.
2. "Anti-DocBook": Converting the existing (some say 10,000 pages) HTML
documentation to XHTML or HTML4.01 is trivial. Converting to DocBook is not.
"Pro-DocBook": You're right on that one. However, we could eventually get
through it.
3. "Anti-DocBook": Archiving documentation in DocBook and then running
background jobs against stylesheets to compile them to HTML and publish them
seems redundant when everyone is used to submitting documents in HTML anyway.
"Pro-DocBook": DocBook allows you to trivially compile to alternate
formats, such as PDF, TXT, RTF, etc. The point is not the web site -- printed
HTML is ugly. The point is to have documentation on the website and
available in other formats as well.
There are several great arguments in favor of DocBook as well... I'm out of
time to summarize then here.
It would be really great to see somebody compile all the plusses and minusses
of each system:
XHTML vs HTML4.01 vs DocBook XML/SGML vs Custom XML
and
File System +web server (ergo Apache) vs Database (ergo: Zope) for back-end
(unrelated to the formats question -- you can store and process all the above
formats on either type. I think some people have confused the issue.
Document format has nothing to do with filesystem or database layout.)
If I got anything wrong, correct me!
psr
>It would be really great to see somebody compile all the plusses and
minusses
>of each system:
>XHTML vs HTML4.01 vs DocBook XML/SGML vs Custom XML
>and
>File System +web server (ergo Apache) vs Database (ergo: Zope) for back-end
>(unrelated to the formats question -- you can store and process all the
above
>formats on either type. I think some people have confused the issue.
>Document format has nothing to do with filesystem or database layout.)
>
Well on the subject of Databases V Static files: Since the files on
mozilla.org are going to be changed quite infrequently, will be checked by a
human before being put on the server (I assume) and will be allways be
displayed in the same way, I cannot see that there is any need for a
database (as much as I love them), certainly not for the documentation part.
Databases come into thier own on sites where there are different users, who
will not necessarily ever see the same page in the same way, and who have
details that need storing.
Gervase Markham
> mozilla.org are going to be changed quite infrequently,
That's a sweeping generalisation that doesn't hold up. And, if
documentation changes infrequently, there's all the more need to have a
DB-driven comments system, so people can correct glaring deficiencies
simply and easily.
What we have currently is a static, infrequently-changing, non DB-driven,
non-interactive site - and it sucks. For lots of reasons other than the
above ones, but those are some of them.
Gerv
fantasai
>
> Howdy pilgrims,
>
> Although not on the scale of Mozilla's 10,000
> documents I set up a Docbook system that exported to
> HTML,PDF,RTF and it's flexibility has paid off.
From everything I've read here, DocBook would be ideal for
tecnical documentation on mozilla.org. However, I don't know
how well it adapts to website-specific use, like search engine
pages, forms, news & status reports, etc.
In any case, I agree with Gervase; we are not going to get
anywhere if we require DocBook convsersions for everything.
That doesn't mean it can't be used at all, though; if we
can set up a system that can simultaneously use both, that
would be fine.
psr
psr
>anywhere if we require DocBook convsersions for everything.
>That doesn't mean it can't be used at all, though; if we
>can set up a system that can simultaneously use both, that
>would be fine.
I don't think that anybody thought that Docbook would be used for anything
other than the documentaion, but I think that as a format for the docs it is
probably the best solution.
Matthew Thomas
>
> > Yup. And the space before the trailing slashes, to work around
> > Navigator 3.x. And the lower-case tags. The only thing I was missing
> > was the XML declaration, for which I think I can be excused on the
> > grounds that XML declarations didn't exist at the time.
>
> One question. Why?!?
It just seemed logical.
> Did you have an SGML childhood?
<gurgle/> :-)
No, I didn't know SGML existed.
>...
> > Um, a *very* large proportion of Mozilla's potential base of testers
> > and developers are currently using 4.x.
>
> Are you sure? According to http://www.mozilla.org/webalizer/ , for
> December and January, no 4.x User Agents feature in the top 15.
Hmmmm. Ok, the top user agents for mozilla.org are Internet Explorer,
followed by ... Internet Explorer, Internet Explorer, Internet Explorer,
Internet Explorer, and Internet Explorer.
Obviously we have some work to do.
>...
> > > Everything else
> > > that matters supports style sheets well enough, doesn't it? Or am
> > > I sadly deluded?
>...
> > If you consider Internet Explorer 4.x's style sheet support to be
> > adequate, then no you're not.
>...
> Seriously, other sites have managed it, haven't they? Why can't we?
>...
Have they? Are there any top100 (or even top500) sites which use HTML
4.x Strict and CSS, rather than HTML 4.x Transitional (or HTML 3.2) with
CSS as an occasional condiment? I would be surprised if there are.
--
Matthew `mpt' Thomas, Mozilla user interface QA
Mozilla UI decisions within 48 hours, or the next one is free