xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Mike Pogue <mpo...@apache.org>
Subject Re: [proposal] Better look and feel
Date Tue, 04 Jan 2000 01:08:47 GMT
Stefano Mazzocchi wrote:
> People,
> I personally love the xml.apache.org web site but there is still
> something we can do to improve it.
> 1) the home page is never changing: if there is one think that makes
> your project seem alive is a front page that changes, a sort of portal
> to the site. I propose to make the xml.apache.org page follow the same
> pattern used for java.apache.org where the page is made of three parts
>  - lead story
>  - news
>  - project status
> see http://java.apache.org for more information. In fact, to be honest,
> the whole Cocoon/Stylebook deal started because of this page: we wanted
> a tool to make it easy to update a complex HTML page without WYSIWYG
> tools. We covered much more ground from that early idea, but now that we
> have the technology we should use it.
> The status column will show the latest release available as well as
> other informations on a per-project basis.
> The news status will allow us to announce events, releases, press
> coverage or anything that should be put up front.

Since there are many projects under the xml.apache.org umbrella, I
propose that the status (which I vote +1 on) should be on each
individual subproject home page, and NOT on the main xml.apache.org home

> 2) the table used have fixed size. While this allows faster page
> rendering, it is very painful to adopt when source code fragments (using
> HTML <pre>) are used. This screws up the pages in a very unpleasant way.
> There are solutions:
> - adopt flexible tables: slower to render but better looking, also for
> distributed HTMl documentation.
> - adopt frames: much faster to render, they same bandwith, they simplify
> the stylesheets. Problem is the use of javascript to allow updating of
> two frames with a single menu click. And browser "back" is also screwed.
> ??? any suggestion?

I propose that code fragments that are wider than the fixed width table
be rewritten so that they aren't so wide.  This is almost always
possible.  So, I vote +1 for fixed width pages (I like very much to be
able to print them).

In the long term, I'd like the regular regen of the site to build BOTH
the HTML and the PDF version of the site.  Then, the tables in the HTML
can go back to variable width.  Until we have a working PDF solution,
however, I think they should stay fixed width.

So, I guess this is +1 for leaving them fixed for now, and +1 for
changing them to variable width when PDF format for docs is available.
> 3) the DTD used to write and generate the documentation should be
> site-wide. I propose to start a "DTD project" that should take care of
> DTD definition. when a project has particular needs, it should propose
> them to the project rather than write their own style.
> This allows better DTDs to be developed and styles to be reused on a
> site-wide basis.

I think that Stylebook should not force one style and one grammar on
everybody.  I think it's important that it be able to (on a regular
basis) use different grammars and stylesheets.  We already have two
stylesheets (apache and Xmas-apache, and I know of two more used
internal to IBM, bringing the total to 4).  We have a couple of grammars
(for each subproject).  If we go down to a single grammar, we will lose
out on our testing, and our thinking will be narrow.  

Also, I think there are very few people who actually do
writing/documentation for more than one subproject at the same time, so
making them common (while nice in the ideal case), is not required.  

Besides, I don't like Stefano's grammar, and he doesn't like mine!  :-)

(Note: somewhere down the road, when we have enough testing on this
thing, and it stabilizes, I might be more convinced.  Right now, it's
just making a change to the grammar, for at least one of us, with no
real benefit to the individual subprojects. For all the same reasons, we
don't force people to use Docbook....)


View raw message