Mailing-List: contact general-help@xml.apache.org; run by ezmlm
Message-ID: <3874AAAA.F9F30435@apache.org>
Date: Thu, 06 Jan 2000 15:46:02 +0100
From: Stefano Mazzocchi <stefano@apache.org>
Organization: Apache Software Foundation
MIME-Version: 1.0
To: general@xml.apache.org
Subject: Re: [proposal] Better look and feel
References: <3870E33A.C72B1FEC@apache.org> <3871481F.AAC3B8CC@apache.org>
 <387355D2.15EFAB21@apache.org> <387381B3.84704E24@apache.org>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Mike Pogue wrote:
> 
> 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.

Great. Here's the deal:

we make a front-door page that looks like java.apache.org (please, look
there, everybody), a very short news description ("Xalan 1.0.1 is out!
come and get it" or "XXX talks about us!" type of news, simple info with
an hyperlink) and a very breif status column, pointing to the
subdirectory where the project is hosted.

Of course, this page is XML and has very simple DTD (look under
xml-cocoon/samples/sites/java.apache.org/news.xml to know what I mean)
and each project/site maintainer will modify it when a new release is
made or when some news show off.

Then every project is free to do whatever they want for that.
 
> > > > 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).

Good point. this is what I've been doing so far, but honestly it's a
real pain in the ass :)
 
> > > 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?

not me :), at least, not now :)

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

This is a very good point, I agree.
 
> Besides, I want to see more people (other than Pier) build Styles!

This is the key issue. I already had major discussions on Pier about
this. I think the learning curve for Stylebook is _way_ too steep given
the amount of XSLT transformations that happen, also, we now agree that
the book->project XSLT transformation is acting like a black box for
most users (and me too, I admit) because it's very painful to see what
stylebook is doing.

The sitemap proposal Pier and I made last week is supposed to create the
basis for an easier look at the processing needed to write "site skins"
(term that I like more than "styles").

We put many brain cycles into the sitemap proposal (and a few sleepless
nights at Pier's place :) and I'm confident the energy gap will be
reduced.

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

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

Ok, I understand you better, now.
 
> ...
> > 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
> universe".
> 
> It's unfair to characterize my opinion as option b).

Agreed, not fair at all.
 
> 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
> everybody".

Wiser, you're right :) 
 
> 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
> converge.

Great points, really, show how much I have to learn about project
management. I think I have to apologize for my shortsightness.

Anyway, what happens if I need something to add to the current DTD
without breaking exising compatibility? what do I do? is it so bad to
have a project that takes care of handling this "customer feedback"
finding safe and unexpensive ways to merge them with what we already
have?

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