commons-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Phil Steitz" <phil.ste...@gmail.com>
Subject Re: Problems...
Date Sun, 05 Mar 2006 00:24:17 GMT
On 3/4/06, Brett Porter <brett@apache.org> wrote:
> Henri Yandell wrote:
> >> IMO, until any further consensus, *all* {proper,sandbox} components
> >> should have a {m102,xdoc192} build. Anyone is welcome to make progress
> >> on the m2 side if they wish, but not having a m102 build just makes
> >> those components "unavailable" for anyone who doesn't want to deal
> >> with m2 yet.
> >
> > m1.1 is an upcoming issue too :)
>
> m1.1 was intended to be backwards compatible. If it's not, that's a bug.
> Your builds should work with both.

See below.  I would not call it so much a bug as our having relied on
some undocumented behaviors that have changed.

>
> >> This is the least of my concerns. Like Martin, I don't have any
> >> trouble with the site, I stick to the book. But unlike Martin, I've
> >> built quite a few sites lately (ofcourse, there may still be some
> >> sites that are troublesome, it will be nice to know what the exact
> >> issues are -- apart from not heeding the correct versions of
> >> maven/plugins to build).
> >
> > My site issues are information-architecture/design issues - I think
> > it's too noisy and big, in many places we don't pay attention to user
> > manuals but spend too much space on the basic info and we don't treat
> > the documentation properly in releases. The cop-out is to have a site
> > per release, but that's ignoring the issue that our sites and
> > documentation are intermingled.
> >
>
> The thing to consider here is that the site is really hard to work with.
> Some others have gone through considerable pain to get it in a working
> state. So, if there are issues in the future they will be harder to work
> through, and if Hen's design/IA concerns yield suggestions that require
> changes to the structure or appearance of the site, someone is going to
> have to go through that pain again.
>
> That's not a reason to change now, but its a reason to investigate it
> which is why I'm doing it.
>

I agree with you, Brett and think our goal should be to make it as
simple as possible to maintain the site.  I also like to be able to
generate individual component "sites" individually.  There are two
things in the current setup that create challenges:

1.  The custom site.jsl.  That forces xdoc 1.9.2 in m1.  It is also an
ugly and painful thing to even think about maintaining.

2. The entities-based nav includes.  That is what is breaking in m1.1.
 I think that Paul is right that it is not the relative paths per se
that are causing 1.1 to choke.  I can get 1.1 to work by changing the
relative path in the standard navigation.xml to eliminate one of the
../ jumps.  I wish it were possible to put ${basedir} in the dtd
reference or we could just find another way to do this while we
prepare for m2.  One workaround would be to use URL paths to svn, but
that would make it impossible to build sites offline.  Does anyone
care about this?  Any better ideas?

As it stands, things work fine with 1.0.2 and xdoc 1.9.2, so if there
are no objections, I will at least update all of the m1 poms to make
the 1.9.2 dependency explicit (at least for the ones that I can get to
build).

Phil

> - Brett
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
> For additional commands, e-mail: commons-dev-help@jakarta.apache.org
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org


Mime
View raw message