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 Wed, 05 Jan 2000 17:38:59 GMT
Stefano Mazzocchi wrote:
> Mike Pogue wrote:
> >
> > 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.

That's a good point.  Customer feedback from java.apache.org is good
feedback!  I'd also be fine with a "summary status" on the main page, as
long as it's short.  Detailed status should remain on the individual
status pages, though.  If there's a way to link to individual status
pages (the "global status index"), that would be good, too, IMHO.

For me, this is a factoring question, not a concurrency question. 

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

I think I'm suggesting that the too-wide code fragments be modified _by
hand_ to be the appropriate width.  Only programmers know how to make
code fragments look good in fixed width (in my experience, tools don't
get it right, because they don't understand how humans read code).

> > 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
> missing?

You're not missing anything!  I agree we should do this.  I personally
don't have the time to make the PDF side happen, though (do you? :-). 
I'd love to see our single XML documentation source become *both* HTML
and PDF, through one unified build process (script, etc.).
Any volunteers? 

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

And, I'm concerned that converging too soon on a single DTD means lack
of testing, lack of actual usage cases, and therefore lack of learning,
feedback, and increased chance of bad design.  Converging on One True
Grammar is nice to do at some point, but I think it's too early to do so
right now.  

Having a tool that supports an infinite number of grammars, and then
using it for exactly one ourselves, is a very seductive idea, but it's
also a dangerous narrowing of viewpoints.  

Besides, I want to see more people (other than Pier) build Styles!
> 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.

Exactly.  As you point out, the <counter/> tag might not be flexible
enough for everybody.  So, before we define "<counter/>" as the ONLY
acceptable counter-like thing for use at XML.Apache, I think we should
leave it open and flexible for a while longer. 

In the same way, I think it's too early to have a fixed tag set for
everybody's documentation.  I'd like to see some substantially DIFFERENT
styles, before we start converging.  

For example, all existing styles use a navbar on the left, a composited
banner on the top, and one at the bottom.  I'd like to see some
non-rectangular layouts, some wild and crazy navigation (dynamically
generated applets?), some more diversity, things I haven't even thought
of, before I am willing to say that our tagset is sufficient.  We just
don't have enough experience yet on these tagsets, to understand their

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

It was a joke, Stefano!  :-)  Your point is that you want to converge,
because of the benefits of convergence.  I'm pointing out the benefits
of divergence (for a while), before converging.

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

I don't think this is a choice between:

a) "converge NOW on a single DTD to reduce management costs" and 
b) "converge NEVER which will allow chaos to reign throughout the known

It's unfair to characterize my opinion as option b).

It's also not a simple choice between:

a) "converge NOW, shutting down all opportunity for creativity and
learning, and sticking us with the wrong DTD, incurring huge conversion
costs later when we realize our mistakes" and 		
b) "converge LATER, learning something from our customers, 
incorporating their feedback, and making the world a better place for

It would be completely unfair for me to characterize your opinion as
option a).  (And, I'm not doing so -- you have some good points, and so
do I).

So, we both already agree that we SHOULD converge.  Now, let's talk
about WHEN to converge.  What should be the criteria for converging? 
I'd personally like to see more than just our couple of Apache
subprojects invent some styles (grammars), before we require everybody
to use the same grammar.  Let's get some customer feedback first, then


View raw message