xml-general mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <stef...@apache.org>
Subject Re: [proposal] Better look and feel
Date Wed, 05 Jan 2000 14:31:46 GMT
Mike Pogue wrote:
> 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
> page.

Why? I'm not saying you should have this as the only place where to find
project status, but under java.apache.org many people were happy because
they could just look at a global "status index" to see if they are
up-to-date with the latests releases, instead of going in each and every
project page (which may have the version located in different places).

Given the update frequency, concurrency is not an issue.

> > 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).

Sounds like a dirty hack to me, but I think we can do that with Steve's
XSLT trick.
> 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.

What's stopping you from building the PDF version? Now that FOP has
images and SVG support, you should be in pretty good shape. What am I
> 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.

All right, +1 as well.
> > 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.

Are you kidding? Do you think something like the web would have evolved
out of SGML metasyntax alone?

The problem of XML will be its flexibility. Read: not lack of DTDs, but
lack of solid contracts. 
> 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.

You got it totally wrong. I'm not concerned about people having to mess
around with couple of grammars (markup grammars are easy to learn on a
by-example basis), but the ability to reuse work on other parts of the

For XSP, we give you the ability to apply logic to your defined tags.
For example to make <counter/> turn up the counter for your page. People
love it, but I'm already concerned on its flexibility. In fact, one will
end up cut/pasting the code from one logicsheet to the next because
there is no standard tag-lib.

The JSP people are having the same concerns.

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

This is not the point. Standards are compromises. I proposed to create a
project to outline such a grammar, not to use mine instead of yours. 

What I want is a solid contract I can base my work on. Solid contracts
are created by the commitment of projects to follow it.

> (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....)

This is the point. You see the value of a project-wide documentation
grammar, but you're afraid to change your documents.

That is IMO pointless for these reasons:

1) the more documents you have the harder it gets. Contracts should be
defined sooner rather than later.
2) changing XML grammar to a more powerful one is a matter of writing a
stylesheet to do it, no less no more.
3) the proposed XML grammar will be as simple as it is right now, just
more complete and created with ideas from every project.
4) document writers get used to new markup quickly if they have examples
to learn from (xslt-converted documentation will give that).

It's not a matter of being lazy, but you can't do nice things like the
Xmas look&feel if you have each project using it's own DTD. That's

In an ideal situation (but not far from reality, if all of us remove
their defensiveness about thier "modus operandi") is to have a series of
DTDs for things like

 - documents
 - specifications
 - faq lists
 - changes lists
 - todo lists
 - contributor lists

then a number of styles that apply on them.

This is the very foundation of the Cocoon project: solid contracts
between working groups to allow complete parallel development.

But you can't do this if the number of contracts grows linearly with the
working contexts involved.

Mike, you are managing your own projects and you know what I mean, all I
ask you is to consider this on a xml.apache.org base and help us
reducing the management costs for the entire project.

On the other hand, I totally understand this is a critical issue for you
and I understand this have to happen slowly and carefully. This is why I
wanted to create the site-wide DTD project, also because other Apache
projects could benefit from being able to reuse this technology as a
whole, with styles and all that.

What do others thing about this?

Am I the only fool that cares about solid DTDs as a way to reduce
management costs?

Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<stefano@apache.org>                             Friedrich Nietzsche
 Come to the first official Apache Software Foundation Conference!  
------------------------- http://ApacheCon.Com ---------------------

View raw message