import of xml.apache.org main site into forrest

[Steven Noels <st...@outerthought.org>]

Hi all,

some mysterious motivational wind was blowing in my direction this
evening, and I went haywire after my last visit to the ugly
xml.apache.org main site.

Result:

- I've run all docs in the {xml-site}/sources/xml-site through the new
docv10->docv11 translation stylesheet, tweaked the result manually, and
imported the result of this into
{xml-forrest}/src/documentation/content/xdocs/xml-site/
- I rewrote the website.xml that came with it to our book.xml syntax,
and added a link to the xml-site directory in our main book.xml

If all goes well, we have a draft version of the main xml.apache.org
site at www.krysalis.org/forrest/xml-site/ after forrestbot has done its
job.

What has this 3 hour exercise taught me:

- if the state of the other projects xml source files is comparable with
those of the main site, we will need some thorough editorial review
after migrating projects to forrest - people have been rather creative
with the elements allowed by the old v10 DTD - using section-level
elements instead of lists, inserting non-breakable spaces for table-like
layout, <br>'s inside list items to mimick definition lists, etc... I
haven't done much to solve these issues - so there's plenty of work for
the editorially challenged amongst us :-)

- we need to do something with the 'link' situation. Joerg, David et al,
let's prepare a vote on this and resolve this thing. Now.

- Please have a look at
http://cvs.apache.org/viewcvs.cgi/xml-site/sources/website.xml?rev=1.27&
content-type=text/vnd.viewcvs-markup which is the 'old' book.xml as has
been used by the now defunct stylebook. I see <hidden> and <external>
and I find these quite interesting. Your ideas?

- Previous xdocs didn't require an authors element being filled in - how
will be solve this? Making authors optional again?

- Auto-generation of mini TOC's - should this be parametrizable? TOCs
are generated now if sections exist within sections in a document, which
was good for the forrest docs so far, but suboptimal for the content
imported from the main site. On the other hand, these imported docs have
been abusing the DTD to obtain certain visual effects, IMNSHO - so we
could fix the docs, too.

- The bert skin - in general, I think the body text is a point (or two)
too big - there isn't too much text on a screen. Bert, can we fix this?
I know I can change the settings of my browser, but I believe the
default font-size is 12pt, which is simply too big, showing too little
content on a 1024*768 screen.

Please review the result of this little transition exercise and post
other issues you come across with.

Regards,

</Steven>

Re: import of xml.apache.org main site into forrest

[Bert Van Kets <be...@vankets.com>]

<snip/>

> >
> > - Please have a look at
> > http://cvs.apache.org/viewcvs.cgi/xml-site/sources/website.xml?rev=1.27&
> > content-type=text/vnd.viewcvs-markup which is the 'old' book.xml as has
> > been used by the now defunct stylebook. I see <hidden> and <external>
> > and I find these quite interesting. Your ideas?
>
>I really don't understand "hidden" much, but external should be something to
>add to the link tag (ie in-context link or out of context).

I have included the external feature in the book2xhtml.xsl I'm doing to get 
the menu the Cocoon way.
The hidden attribute would let you set a link hidden.  Can be nice in 
dynamic systems where you want to put part of a site offline for a moment 
or during development without having to remove the tag.  In Forrest it's a 
bit obsolete since we build a static site every time.  Do I remove the 
attribute?

<snip/>

 > - The bert skin - in general, I think the body text is a point (or two)
> > too big - there isn't too much text on a screen. Bert, can we fix this?
> > I know I can change the settings of my browser, but I believe the
> > default font-size is 12pt, which is simply too big, showing too little
> > content on a 1024*768 screen.

This is the disadvantage of having a big screen (1600 x 1200).  I'll adjust 
the CSS file to a more appropriate level.  I guess the text in the menu 
needs to be adjusted too.

Here's another matter: The <code> areas that are too wide.
This has also been discussed by Stefano.  He offered several solutions.  I 
don't see how we can wrap the text server side (at least I don't).  If we 
REALLY need <pre> tags then the committer must make sure the page is not 
too wide.  Having ANT catch this on the production machine is a bit of a 
nuisance I think, but can be used as a test locally.
The current font size is 75% of the default font size (0.75em).  This 
results in 10px size on a normal text height.  I will reset it to 1em since 
too many people complain, but then the scrolling problem is not solved.
Stefano also proposed <textarea> as a solution.  Any thoughts on this 
one?  Using CSS I can remove the borders, but there will be scrollbars if 
the text is too wide.
Any thoughts?


>+1
>
> > Please review the result of this little transition exercise and post
> > other issues you come across with.
>
>On the top: apache : xml.apache : forrest
>Which is normal of course, since you imported it in the forrest run.
>We will need to remember to check this.

These are indeed imported from Ant parameters and thus fixed.  Does this 
need to be dynamic in the future?  If so, where will we get the data for 
this path?

Bert


>--
>Nicola Ken Barozzi                   nicolaken@apache.org
>             - verba volant, scripta manent -
>    (discussions get forgotten, just code remains)
>---------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Stefano Mazzocchi <st...@apache.org>]

Nicola Ken Barozzi wrote:

> Now, Jason has explicitely stated on the Avalon-dev list that he will
> propose Maven as a substitute to Gump, and switch the descriptor format to
> Maven's, this for all Java Apache projects of course.

Nobody has the power to *impose* something on a project, expecially if
the person is not a committer of that project.

I suggest to keep working with what we have and consider moving to other
formats if the necessity emerges.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Stefano Mazzocchi" <st...@apache.org>

> Nicola Ken Barozzi wrote:
>
> > >  3) there is no DTD for .xgump and this makes the changes and toto
DTDs
> > > obsolete. Having a complete DTD for xgump and removing the obsoleted
> > > DTDs is another showstopper.
> >
> > Latest Centipede has a more articulate set of descriptors.
> > The developers, changes, and todos have been put in status.xml, as they
are
> > more dynamic.
> > When switching to latest Centipede, we will use that if you all are ok.
> >
> > Just as an information: Maven will soon propose to switch Gump to using
the
> > Maven descriptor.
> > This will be a real PITA if it will fet through.
>
> Can you elaborate more on this?

Ok.

Gump has his descriptor for the projects.
Good or bad, it works, and there is one for every Java Apache project.

Now, Jason van Zyl <jv...@zenplex.com> doesn't like it, and the last
changes it had (the module/project dichotomy) were AFAIK result of his
suggestions, allthough he now thinks it's crap.

Jason started making Maven (AFAIK) as a possible replacement to Gump, since
he doesn't like the current scripting approach (fair enough).
At one point, he took the Gump classes that describe the objectmodel, Moved
Maven under Turbine, and started a new project descriptor.

In the meantime, I started using Gump's descriptor with additions for
Centipede, and the projects that use Centipede (Forrest included).

Sam and I tried to get Jason agree on a common format, but failed.

I posted a proposal on alexandria-dev that intends to make Gump, Alexandria,
Maven, Centipede, etc... work seamlessly, and it had a very good acceptance.
I'm working on it, and will post a patch to Alexandria-dev soon.

Now, Jason has explicitely stated on the Avalon-dev list that he will
propose Maven as a substitute to Gump, and switch the descriptor format to
Maven's, this for all Java Apache projects of course.

If we start using the enhanced gump descriptor to describe projects in
Forrest, and then it changes, *that* would be a PITA.

I suppose everyone knows how I fell about it, since I have explained it
enough to nauseate anybody, and that's why I was maybe too criptic in the
first place.

I'm not accusing anybody, in case it isn't clear.
All Maven guys and specifically Jason are doing a great job with Maven and
Commons; these are just the facts+my feelings, not judgements on people.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Stefano Mazzocchi <st...@apache.org>]

Nicola Ken Barozzi wrote:

> >  3) there is no DTD for .xgump and this makes the changes and toto DTDs
> > obsolete. Having a complete DTD for xgump and removing the obsoleted
> > DTDs is another showstopper.
> 
> Latest Centipede has a more articulate set of descriptors.
> The developers, changes, and todos have been put in status.xml, as they are
> more dynamic.
> When switching to latest Centipede, we will use that if you all are ok.
> 
> Just as an information: Maven will soon propose to switch Gump to using the
> Maven descriptor.
> This will be a real PITA if it will fet through.

Can you elaborate more on this?

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Stefano Mazzocchi" <st...@apache.org>

> Now, I believe the best place for 'behavioral skinning' controls should
> be the book.xml file, which is sort of a high level site map (not in the
> cocoon's sense of the term, but in the original 'map of the site' sense)
>
> So, depending on the document, it's up to who links the documento to the
> book to indicate whether or not this document should have particular
> skinning behaviors associated. Examples might be:
>
>  1) minitoc yes/no
>  2) printable version yes/no
>  3) multipage yes/no
>  4) ???
>
> allowing us to set those behaviors in a single location and separating
> the concern from the document author simplifis the editor's job of
> providing the best visual coherence and usability for the entire doco
> corpus.

+1

Also for being able to specify a spine, a guide and a tour descriptors.

See my [Re: DocBook vs Open eBook] latest post.

>  3) there is no DTD for .xgump and this makes the changes and toto DTDs
> obsolete. Having a complete DTD for xgump and removing the obsoleted
> DTDs is another showstopper.

Latest Centipede has a more articulate set of descriptors.
The developers, changes, and todos have been put in status.xml, as they are
more dynamic.
When switching to latest Centipede, we will use that if you all are ok.

Just as an information: Maven will soon propose to switch Gump to using the
Maven descriptor.
This will be a real PITA if it will fet through.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: escaping the ego trap

[Nicola Ken Barozzi <ni...@apache.org>]

From: "David Crossley" <cr...@indexgeo.com.au>

> Liberate Libre !
> 
> I think that Forrest is the place for it. You say that Libre
> has scope broader than Forrest. Yet the scope of Forrest is
> actually broader than itself, so this place does suit.

+1

There is no place&community more appropriate ATM.
Maybe no other place at all ;-)

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: escaping the ego trap

[David Crossley <cr...@indexgeo.com.au>]

Liberate Libre !

I think that Forrest is the place for it. You say that Libre
has scope broader than Forrest. Yet the scope of Forrest is
actually broader than itself, so this place does suit.

The Forrest community is growing stronger each day, so i
reckon that you will soon gain the necessary attention.
It is also a very relevant enhancement to this project.

With respect to the CVS/commit issue ...
I am happy to accept the code right now. However we can vote
if that is needed. Anyway once the facility is in CVS, then
Marc can respond to feedback on forrest-dev, send some patches,
then we can soon do the voting procedure, i.e the usual.
So i do not see any issue at all.

If it turns out that Libre should later move to someplace more
appropriate, then that is OK too.

--David


Steven Noels wrote:
> Stefano Mazzocchi wrote:
> 
> > NOTE: I do this to avoid Steven and his colleagues to waste time. It
> > would be simple for me to vote -1 to libre and keep going with what we
> > have, but that would be very rude and unrespectful of their
> > contributed effort.
> 
> Indeed :-)
> 
> OK - how do we proceed from here. Some points & issues.
> 
> * We have a pre-refactored version of libre in our own CVS, which does
> basically what I have described in
> http://marc.theaimsgroup.com/?l=forrest-dev&m=102336035108059&w=2. Given
> Stefano's remarks and our own belief in release early & often, we could
> contribute this as-is to Forrest.
> 
> * We believe Libre has a scope which can be broader than Forrest,
> however, given the fact the refactoring currently going on is mostly
> about Avalonizing the thing, the idea of traversing other repositories,
> and also having other output implementations than the Cocoon Generator
> (there is a CLI output already, others may follow). So we don't know
> whether this should be part of Forrest, Cocoon, Avalon, Krysalis or
> outerthought.sf.net. We could contribute the Jar of course, but that
> means only we have CVS-access to the (open) source, which is not in the
> spirit of our donation.
> 
> * Practical issue: I'm not the author of the thing, only the cardboard
> engineer. Marc Portier <ma...@outerthought.org> is, and it would be
> very impractical for him/us when the canonical version resides in a CVS
> repository where he has no commit rights to. At the same time, we
> sincerely believe this should not be an easy way of gaining commit
> rights for him on Forrest. So it is much more likely that we start with
> adding it to SF, and re-using the Jar within Forrest. This of course
> will mean that it won't be readily available for Forresteers, they will
> have to look it up on SF instead.
> 
> * We could send an archive with source, examples, etc to interested
> parties or the list, if that would help in the mean time. I won't expect
> the refactoring be finished soon, and we now understand that this would
> be better with some more eyeballs looking into our work. I am not sure
> whether we'll find these eyeballs here, maybe cocoon-dev is a better
> place.
> 
> We feel we might be missing an opportunity window here, so please help
> us out in resolving this issue.
> 
> Thanks for your patience,
> 
> </Steven>
> stevenn@outerthought.org, next mail will be in the spirit of my
> apache.org alter ego again ;-)

RE: escaping the ego trap [was: RE: import of xml.apache.org main site into forrest]

[Marc Portier <mp...@outerthought.org>]

> > > Stefano's remarks and our own belief in release early &
> > often, we could
> > > contribute this as-is to Forrest.
> >
> > Great.
>
> I'm not sure and I'd rather want Bruno or Marc to answer this, but there
> might be some issues. As previously stated, we are thinking of further

Only issue I see is that switching the order from 1-refactoring 2-'make
public' to the reverse could increase the number of patches required...
and this discussion just kinda proved that we favor this over the other,
so...

> Avalonizing it (to make it more open to other implementations than
> Cocoon only), and I assume the current build system might not be
> sufficient for this - so we'll have to patch this too, import some more
> stuff from the Cocoon build environment, and I currently don't know

euh, just need to get into the centipede way of working still, hadn't done
that.
comments on how this is best done are welcome
(current guess is an extra xtarget under scratchpad?)

practically I'm now just throwing libre as is in the /src/scratchpad/java
section and considering the required build.xml and *.xtargets additions to
get it in there
(and the needed extra pipelines to get it to show)

I'll probably better add some libre.TODO explaining the refactorings we had
in mind
(ie the shortcomings we see)

as for docs... do you really need them :-P
(just ask I would say, some examples and being around to answer questions
makes more sense I guess, we'll see where itches occur, promise to help out
scratching)

> whether Nicola thinks upgrading the current build system to Centipede
> 1.0 is still necessary.
>

Nicola?
How much will it affect the work if we switch later?
Can I help in joint-realizing the upgrade first?  Any head start?
(Somebody else that already started on it?)

> > > * We believe Libre has a scope which can be broader than Forrest,
> > > however, given the fact the refactoring currently going on is mostly
> > > about Avalonizing the thing, the idea of traversing other
> > repositories,
> > > and also having other output implementations than the
> > Cocoon Generator
> > > (there is a CLI output already, others may follow). So we don't know
> > > whether this should be part of Forrest, Cocoon, Avalon, Krysalis or
> > > outerthought.sf.net. We could contribute the Jar of course, but that
> > > means only we have CVS-access to the (open) source, which
> > is not in the
> > > spirit of our donation.
> >
> > No, I would not like to accept a binary donation anyway. I
> > would suggest
> > to keep the thing here in forrest for now.
>
> I won't commit it right now, I'd prefer to send a patch to the list and
> have some fellow Forresteers check it out on their local copies and see
> if it is fit for committing.
>
> > > * Practical issue: I'm not the author of the thing, only
> > the cardboard
> > > engineer. Marc Portier <ma...@outerthought.org> is,
> > and it would be
> > > very impractical for him/us when the canonical version
> > resides in a CVS
> > > repository where he has no commit rights to. At the same time, we
> > > sincerely believe this should not be an easy way of gaining commit
> > > rights for him on Forrest. So it is much more likely that
> > we start with
> > > adding it to SF, and re-using the Jar within Forrest. This of course
> > > will mean that it won't be readily available for
> > Forresteers, they will
> > > have to look it up on SF instead.
> >
> > Hmmmm, to be entirely honest with you, I think that the
> > normal routines
> > apply: somebody makes a donation, keeps submitting patches, developers
> > get bored of applying the patches to they give commit access.
> >
> > That's as simple as that, no need for SF proxying.
>
> I know Marc was readying himself for SF, so he has to answer that one,
> too.
>

let's go for this, we'll see how it works out in practice soon enough...

> > > * We could send an archive with source, examples, etc to interested
> > > parties or the list, if that would help in the mean time. I
> > won't expect
> > > the refactoring be finished soon, and we now understand
> > that this would
> > > be better with some more eyeballs looking into our work. I
> > am not sure
> > > whether we'll find these eyeballs here, maybe cocoon-dev is a better
> > > place.
> >
> > I think those doco-headed people are subscribed to both lists, so it
> > doesn't really matter. for now, I would suggest keeping the
> > focus on the
> > functionality (not the code) and donate it here in the forrest
> > scratchpad.
>
> +1 on the functionality
>
> > > We feel we might be missing an opportunity window here, so
> > please help
> > > us out in resolving this issue.
> >
> > Hope this helps.
> >
> > > Thanks for your patience,
> >
> > No probs.
>
> I thought so ;-)
>
> </Steven>
>

practical question: any people with strong feelings on the org.outerj.*
prefixing on the current classes?

my suggestion would be to really offer the classes as they are now (only
focussing on integrating build, which I am) then discussing new features,
refactoring and package renaming once we've all actually seen it?

-marc=

RE: escaping the ego trap [was: RE: import of xml.apache.org main site into forrest]

[Steven Noels <st...@outerthought.org>]

> From: Stefano Mazzocchi [mailto:stefano@apache.org]

> Steven Noels wrote:

> > OK - how do we proceed from here. Some points & issues.
> >
> > * We have a pre-refactored version of libre in our own CVS,
> which does
> > basically what I have described in
> >
> http://marc.theaimsgroup.com/?l=forrest-dev&m=102336035108059&
> w=2. Given
> > Stefano's remarks and our own belief in release early &
> often, we could
> > contribute this as-is to Forrest.
>
> Great.

I'm not sure and I'd rather want Bruno or Marc to answer this, but there
might be some issues. As previously stated, we are thinking of further
Avalonizing it (to make it more open to other implementations than
Cocoon only), and I assume the current build system might not be
sufficient for this - so we'll have to patch this too, import some more
stuff from the Cocoon build environment, and I currently don't know
whether Nicola thinks upgrading the current build system to Centipede
1.0 is still necessary.

> > * We believe Libre has a scope which can be broader than Forrest,
> > however, given the fact the refactoring currently going on is mostly
> > about Avalonizing the thing, the idea of traversing other
> repositories,
> > and also having other output implementations than the
> Cocoon Generator
> > (there is a CLI output already, others may follow). So we don't know
> > whether this should be part of Forrest, Cocoon, Avalon, Krysalis or
> > outerthought.sf.net. We could contribute the Jar of course, but that
> > means only we have CVS-access to the (open) source, which
> is not in the
> > spirit of our donation.
>
> No, I would not like to accept a binary donation anyway. I
> would suggest
> to keep the thing here in forrest for now.

I won't commit it right now, I'd prefer to send a patch to the list and
have some fellow Forresteers check it out on their local copies and see
if it is fit for committing.

> > * Practical issue: I'm not the author of the thing, only
> the cardboard
> > engineer. Marc Portier <ma...@outerthought.org> is,
> and it would be
> > very impractical for him/us when the canonical version
> resides in a CVS
> > repository where he has no commit rights to. At the same time, we
> > sincerely believe this should not be an easy way of gaining commit
> > rights for him on Forrest. So it is much more likely that
> we start with
> > adding it to SF, and re-using the Jar within Forrest. This of course
> > will mean that it won't be readily available for
> Forresteers, they will
> > have to look it up on SF instead.
>
> Hmmmm, to be entirely honest with you, I think that the
> normal routines
> apply: somebody makes a donation, keeps submitting patches, developers
> get bored of applying the patches to they give commit access.
>
> That's as simple as that, no need for SF proxying.

I know Marc was readying himself for SF, so he has to answer that one,
too.

> > * We could send an archive with source, examples, etc to interested
> > parties or the list, if that would help in the mean time. I
> won't expect
> > the refactoring be finished soon, and we now understand
> that this would
> > be better with some more eyeballs looking into our work. I
> am not sure
> > whether we'll find these eyeballs here, maybe cocoon-dev is a better
> > place.
>
> I think those doco-headed people are subscribed to both lists, so it
> doesn't really matter. for now, I would suggest keeping the
> focus on the
> functionality (not the code) and donate it here in the forrest
> scratchpad.

+1 on the functionality

> > We feel we might be missing an opportunity window here, so
> please help
> > us out in resolving this issue.
>
> Hope this helps.
>
> > Thanks for your patience,
>
> No probs.

I thought so ;-)

</Steven>

Re: escaping the ego trap [was: RE: import of xml.apache.org main site into forrest]

[Stefano Mazzocchi <st...@apache.org>]

Steven Noels wrote:
> 
> > From: Stefano Mazzocchi [mailto:stefano@apache.org]
> 
> > NOTE: I do this to avoid Steven and his colleagues to waste time. I
> > would be simple for me to vote -1 to libre and keep going with what we
> > have, but that would be very rude and unrespectful of their
> > contributed
> > effort.
> 
> Indeed :-)
> 
> OK - how do we proceed from here. Some points & issues.
> 
> * We have a pre-refactored version of libre in our own CVS, which does
> basically what I have described in
> http://marc.theaimsgroup.com/?l=forrest-dev&m=102336035108059&w=2. Given
> Stefano's remarks and our own belief in release early & often, we could
> contribute this as-is to Forrest.

Great.

> * We believe Libre has a scope which can be broader than Forrest,
> however, given the fact the refactoring currently going on is mostly
> about Avalonizing the thing, the idea of traversing other repositories,
> and also having other output implementations than the Cocoon Generator
> (there is a CLI output already, others may follow). So we don't know
> whether this should be part of Forrest, Cocoon, Avalon, Krysalis or
> outerthought.sf.net. We could contribute the Jar of course, but that
> means only we have CVS-access to the (open) source, which is not in the
> spirit of our donation.

No, I would not like to accept a binary donation anyway. I would suggest
to keep the thing here in forrest for now.

> * Practical issue: I'm not the author of the thing, only the cardboard
> engineer. Marc Portier <ma...@outerthought.org> is, and it would be
> very impractical for him/us when the canonical version resides in a CVS
> repository where he has no commit rights to. At the same time, we
> sincerely believe this should not be an easy way of gaining commit
> rights for him on Forrest. So it is much more likely that we start with
> adding it to SF, and re-using the Jar within Forrest. This of course
> will mean that it won't be readily available for Forresteers, they will
> have to look it up on SF instead.

Hmmmm, to be entirely honest with you, I think that the normal routines
apply: somebody makes a donation, keeps submitting patches, developers
get bored of applying the patches to they give commit access.

That's as simple as that, no need for SF proxying.

> * We could send an archive with source, examples, etc to interested
> parties or the list, if that would help in the mean time. I won't expect
> the refactoring be finished soon, and we now understand that this would
> be better with some more eyeballs looking into our work. I am not sure
> whether we'll find these eyeballs here, maybe cocoon-dev is a better
> place.

I think those doco-headed people are subscribed to both lists, so it
doesn't really matter. for now, I would suggest keeping the focus on the
functionality (not the code) and donate it here in the forrest
scratchpad.
 
> We feel we might be missing an opportunity window here, so please help
> us out in resolving this issue.

Hope this helps.
 
> Thanks for your patience,

No probs.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

escaping the ego trap [was: RE: import of xml.apache.org main site into forrest]

[Steven Noels <st...@outerthought.org>]

> From: Stefano Mazzocchi [mailto:stefano@apache.org]

> NOTE: I do this to avoid Steven and his colleagues to waste time. I
> would be simple for me to vote -1 to libre and keep going with what we
> have, but that would be very rude and unrespectful of their
> contributed
> effort.

Indeed :-)

OK - how do we proceed from here. Some points & issues.

* We have a pre-refactored version of libre in our own CVS, which does
basically what I have described in
http://marc.theaimsgroup.com/?l=forrest-dev&m=102336035108059&w=2. Given
Stefano's remarks and our own belief in release early & often, we could
contribute this as-is to Forrest.

* We believe Libre has a scope which can be broader than Forrest,
however, given the fact the refactoring currently going on is mostly
about Avalonizing the thing, the idea of traversing other repositories,
and also having other output implementations than the Cocoon Generator
(there is a CLI output already, others may follow). So we don't know
whether this should be part of Forrest, Cocoon, Avalon, Krysalis or
outerthought.sf.net. We could contribute the Jar of course, but that
means only we have CVS-access to the (open) source, which is not in the
spirit of our donation.

* Practical issue: I'm not the author of the thing, only the cardboard
engineer. Marc Portier <ma...@outerthought.org> is, and it would be
very impractical for him/us when the canonical version resides in a CVS
repository where he has no commit rights to. At the same time, we
sincerely believe this should not be an easy way of gaining commit
rights for him on Forrest. So it is much more likely that we start with
adding it to SF, and re-using the Jar within Forrest. This of course
will mean that it won't be readily available for Forresteers, they will
have to look it up on SF instead.

* We could send an archive with source, examples, etc to interested
parties or the list, if that would help in the mean time. I won't expect
the refactoring be finished soon, and we now understand that this would
be better with some more eyeballs looking into our work. I am not sure
whether we'll find these eyeballs here, maybe cocoon-dev is a better
place.

We feel we might be missing an opportunity window here, so please help
us out in resolving this issue.

Thanks for your patience,

</Steven>
stevenn@outerthought.org, next mail will be in the spirit of my
apache.org alter ego again ;-)

Re: import of xml.apache.org main site into forrest

[Stefano Mazzocchi <st...@apache.org>]

Nicola Ken Barozzi wrote:

> > I have the impression that you guys might be caught in the good old
> > "don't who till is ready" ego trap with your 'libre' effort. Release
> > early and often means also 'release when it barely does anything' so
> > that people can interact with you *before* you spend months developping
> > and find out that many things that you considered *very cool* are simply
> > not needed anymore.
> 
> Stefano, currently Forrest is using book.xml. Noone on this list AFAIK is
> waiting for the "libre" effort to proceed, and in fact as you've seen from
> the mails with root and infrastructure things are moving.

In reality, I was going to add metadata information to book.xml (for
pagination and print-friendly versions) but I stopped and asked because
I knew that a uber-generator would have blasted my effort.

So I asked and my concerns were right.
 
> > > > > Please review the result of this little transition exercise and post
> > > > > other issues you come across with.
> > > >
> > > > I'm offline so I don't have access (yet) to what you did, but I have a
> > > > few comments since I spent yesterday afternoon making myself
> > > > up-to-date
> > > > with Forrest.
> > > >
> > > > Things to note:
> > > >
> > > >  1) the navigation path on top of the page is static. I mean, when you
> > > > change page, the path doesn't change. We *must* fix this before making
> > > > Forrest go live.
> > >
> > > -0 - we can do this later on, too. This is another area which could be
> > > touched by upcoming book.xml alternatives/additions, so we need to be
> > > careful with this.
> >
> > Again, it's kind of hard to understand what to plan if we don't even
> > know what you guys are up to.
> 
> I guess Steven is the only one to know ;-)

Might not be the case, but the problem is that we don't know and we
can't influence its design until it might be hard to change.

NOTE: I do this to avoid Steven and his colleagues to waste time. I
would be simple for me to vote -1 to libre and keep going with what we
have, but that would be very rude and unrespectful of their contributed
effort.

I'm just proposing a way to avoid all this.

> What I know, is that maybe, in the future, someone will come up with a solid
> proposal to change book.xml to something that is better, but I don't count
> on it now.

Ok, that might be a sane position from where forrest stands today, but I
believe I'm a little more farsighted for possible community friction and
I hate to act when it's too late so I spoke up.

> > > >  3) there is no DTD for .xgump and this makes the changes and
> > > > toto DTDs
> > > > obsolete. Having a complete DTD for xgump and removing the obsoleted
> > > > DTDs is another showstopper.
> > >
> > > Honestly, we don't have much dependencies on Gump. Build & project
> > > automation is a very political area,  cfr. Nicola's remark. Some careful
> > > thinking will be required.
> >
> > I still don't understand why we need to incorporate changes and todos
> > into a project description file.
> >
> > Nicola, what's your thinking about this?
> 
> I agree. In fact the latest Centipede has them separated from the
> descriptor.

Cool.

> Ok, I guess it's time do describe here what are the descriptors centipede
> currently uses:
> http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/krysalis/krysalis-centipede/
> 
> (project descriptors)
>   module.xml (enhanced gump descriptor)
>   status.xml (developers, todos and changes)
> (build descriptors)
>   build.xml  (ant buildfile)
>   properties.xml (ant properties in xml)
>   layout.xml (description of the project dir structure)
> 
> The reason why I put developers, todos and changes is that they have a
> similar update frequency (and removing a todo with a change), and that the
> changes and todos need developers as references.

That's a good point.

> I would like to upgrade Forrest's centipede to use the latest descriptors
> and
> 1. upgrade Gump DTD to the compatible module.xml one
> 2. make the status.xml DTD part of the Forrest dtds, instead of changes and
> todo.
> 
> What do you think?

+1 on my side.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Stefano Mazzocchi" <st...@apache.org>


> Steven Noels wrote:
> > > Now, I believe the best place for 'behavioral skinning'
> > > controls should
> > > be the book.xml file, which is sort of a high level site map
> > > (not in the
> > > cocoon's sense of the term, but in the original 'map of the
> > > site' sense)
> > >
> > > So, depending on the document, it's up to who links the
> > > documento to the
> > > book to indicate whether or not this document should have particular
> > > skinning behaviors associated. Examples might be:
> > >
> > >  1) minitoc yes/no
> > >  2) printable version yes/no
> > >  3) multipage yes/no
> > >  4) ???
> > >
> > > allowing us to set those behaviors in a single location and separating
> > > the concern from the document author simplifis the editor's job of
> > > providing the best visual coherence and usability for the entire doco
> > > corpus.
> >
> > I like this idea, we need to think about this.
>
> I have the impression that you guys might be caught in the good old
> "don't who till is ready" ego trap with your 'libre' effort. Release
> early and often means also 'release when it barely does anything' so
> that people can interact with you *before* you spend months developping
> and find out that many things that you considered *very cool* are simply
> not needed anymore.

Stefano, currently Forrest is using book.xml. Noone on this list AFAIK is
waiting for the "libre" effort to proceed, and in fact as you've seen from
the mails with root and infrastructure things are moving.

> > > > Please review the result of this little transition exercise and post
> > > > other issues you come across with.
> > >
> > > I'm offline so I don't have access (yet) to what you did, but I have a
> > > few comments since I spent yesterday afternoon making myself
> > > up-to-date
> > > with Forrest.
> > >
> > > Things to note:
> > >
> > >  1) the navigation path on top of the page is static. I mean, when you
> > > change page, the path doesn't change. We *must* fix this before making
> > > Forrest go live.
> >
> > -0 - we can do this later on, too. This is another area which could be
> > touched by upcoming book.xml alternatives/additions, so we need to be
> > careful with this.
>
> Again, it's kind of hard to understand what to plan if we don't even
> know what you guys are up to.

I guess Steven is the only one to know ;-)

What I know, is that maybe, in the future, someone will come up with a solid
proposal to change book.xml to something that is better, but I don't count
on it now.

> > >  3) there is no DTD for .xgump and this makes the changes and
> > > toto DTDs
> > > obsolete. Having a complete DTD for xgump and removing the obsoleted
> > > DTDs is another showstopper.
> >
> > Honestly, we don't have much dependencies on Gump. Build & project
> > automation is a very political area,  cfr. Nicola's remark. Some careful
> > thinking will be required.
>
> I still don't understand why we need to incorporate changes and todos
> into a project description file.
>
> Nicola, what's your thinking about this?

I agree. In fact the latest Centipede has them separated from the
descriptor.

Ok, I guess it's time do describe here what are the descriptors centipede
currently uses:
http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/krysalis/krysalis-centipede/

(project descriptors)
  module.xml (enhanced gump descriptor)
  status.xml (developers, todos and changes)
(build descriptors)
  build.xml  (ant buildfile)
  properties.xml (ant properties in xml)
  layout.xml (description of the project dir structure)

The reason why I put developers, todos and changes is that they have a
similar update frequency (and removing a todo with a change), and that the
changes and todos need developers as references.

I would like to upgrade Forrest's centipede to use the latest descriptors
and
1. upgrade Gump DTD to the compatible module.xml one
2. make the status.xml DTD part of the Forrest dtds, instead of changes and
todo.

What do you think?

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Stefano Mazzocchi <st...@apache.org>]

Steven Noels wrote:
> 
> > From: Stefano Mazzocchi [mailto:stefano@apache.org]
> 
> > > I like this idea, we need to think about this.
> 
> 1) the 'we' was 'forrest', not outerthought

Ok, cool.

> > I have the impression that you guys might be caught in the good old
> > "don't who till is ready" ego trap with your 'libre' effort. Release
> > early and often means also 'release when it barely does anything' so
> 
> 2) touche :-(
> 
> point is that this thing has been sitting for quite some time on our
> harddisks (it's already more or less integrated in my local copy of
> forrest AAMOF), but since I said to my colleagues that I wanted to
> submit it to forrest, we have been discussing refactoring and some
> additional features ever since :-(

Yep, ego trap right there.

> I'm also aware however of the fact that providing a functional codebase
> helps with the adoption of new components, and we could go on endlessly
> in RT-mode if we don't come up with a codebase to start with. After all,
> Forrest has been mostly dead in the early days (sic) until Nicola and I
> jumpstarted it with the addition of the early centipede codebase, which
> was already pretty much cooked up prior to committing it

Exactly. Remember that evolution works best if done in small steps, not
in big jumps, because adaptability is maximum.

> > that people can interact with you *before* you spend months
> > developping
> > and find out that many things that you considered *very cool*
> > are simply
> > not needed anymore.
> 
> agree, we are anxiously trying to balance momentum and good design
> practices, and you know momentum is a prime mover & shaker in OSS
> projects. The result *will* be released under an Apache license however,
> whether it is used within Forrest or not, hopefully as being part of
> Forrest or Cocoon, or on SF. While the scope of libre is much smaller
> than the S&N portal contribution to Cocoon, its genesys should be
> comparable: it was mostly finished intra muros before being released as
> a contribution.

Ok
 
> > In fact, I don't want the book.xml to be removed by a
> > generator because
> > no matter how powerful the generator is the book.xml file can contain
> > much more metadata than any file system... and placing site-related
> > metadata (such the one I suggested above) inside the document and have
> > the generator extract it (a-la XPathDirectoryGenerator) seems like the
> > wrong approach to me since it mixes concerns between the document
> > authors and those who manage the site (which normally have different
> > concerns).
> 
> -1
> 
> I hate book.xml from a user's POV. It's non-intuitive, duplicates
> information, yet another thing people need to learn before they can
> trust project documentation to the Forrest service, etc...
> 
> For simple document collections, it should be sufficient to put files in
> a directory structure, and extract sequence and labeling from the
> filename or by applying XPath onto the files. To do so, we have a simple
> approach, configured using a little configuration file libre.xml, which
> you could compare with .htaccess
> 
> It's all under reconsideration right now, but what we have working
> currently is this:
> 
> libre.xml config file in content/xdocs:
> 
> <libre xmlns="http://outerx.org/libre/config/0.1">
>   <auto>
>     <filter logic="normal">
>       <property name="name" regex=".*\.xml"/>
>     </filter>
>     <label>
>       <xpath expression="/document/header/title/text()"/>
>     </label>
>   </auto>
> </libre>
> 
> Output of our libre generator:
> 
> <collection xmlns="http://outerx.org/yer/hierarchy/0.1">
>   <item/>
>   <item label="Contribution to Forrest"/>
>   <item label="The document-v1.1 DTD"/>
>   <item label="Forrest dream list"/>
>   <item/>
>   <item/>
>   <item label="Welcome to Forrest"/>
>   <item label="The Apache Software License, Version 1.1"/>
>   <item label="Mailing List Archives"/>
>   <item label="Mailing Lists"/>
>   <item label="The Forrest Primer"/>
>   <item label="Who we are"/>
> </collection>
> 
> As you can see, there are still issues (like directory handling in the
> above example, which we are addressing), but this would mean a lot of
> the information which now has to be hardcoded in book.xml can retrieved
> from the documents itself.
> 
> We have basically three actions we do on a hierarchy (and this stuff is
> being componentized so that we could implement this also on top of
> non-filesystem hierarchies like a WebDAV resource):
> 
>  - filtering
>  - labeling
>  - sorting
> 
> all three of them based on xpath expressions, resource properties
> (filename, mod date, etc) and regexes on these properties, with and'ing,
> or'ing and not'ing for filters.

Sounds very cool but...
 
> On your SoC remark: you're right, and maybe we will still need such an
> additional metadata config file for a filesystem repository, but WebDAV
> resource meta-attributes also move this responsibility to the individual
> resource maintainer, and not to the collection manager, if my
> assumptions are correct.

... I still question this.

> > I might be totally wrong and I'd love to be because I hate raining on
> > somebody else's party (I'm abusing this metaphor today) but your "*we*
> > need to think about this" rang a bell in my head.
> 
> you and me and other forresteers, thus, not 'we' ;-)

Ok, sorry for having misunderstood.

> <aside>
> > I still don't understand why we need to incorporate changes and todos
> > into a project description file.
> 
> and I can only agree with that.
> </aside>
> 
> Hopefully we find time to act upon our promises, you know we are trying
> really hard ;-)

Oh, gosh, I really don't care if people don't act upon their promises,
we are volunteers, damn it, there are tons of others things in our
priority list that come before this. You even have a new baby to take
care of. That's more than an excuse for me.

What I really dislike is the fact that people say their are going to do
something and they don't. But the problem is not that they didn't, is
that they told people!

For example: when I started Forrest, I never said I was working on
something, otherwise others (you and Nicola, in this case) wouldn't even
start any effort.

NOTE: I did this mistake several times before and this is why I'm
sensible about this.

So I changed about RT-style programming: tell people what the heck I
have in mind and tell them all my doubts, never telling them I'm working
on something. Work incrementally, commit something even if it doesn't
work as expected, even if it barely compiles. It's fine, it's what OSS
is about.

So, instead of telling us "we are thinking about redesign" and stopping
all our contributions for weeks, tell us your problems, give us the code
and we might even be able to solve them and release pressure and give
more time to you for other things.

Sure, you have to exit the ego trap to do this, but that's exactly the
obstacle that we must understand to reach the next step. ;-)

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

RE: import of xml.apache.org main site into forrest

[Steven Noels <st...@outerthought.org>]

> From: Stefano Mazzocchi [mailto:stefano@apache.org]

> > I like this idea, we need to think about this.

1) the 'we' was 'forrest', not outerthought

> I have the impression that you guys might be caught in the good old
> "don't who till is ready" ego trap with your 'libre' effort. Release
> early and often means also 'release when it barely does anything' so

2) touche :-(

point is that this thing has been sitting for quite some time on our
harddisks (it's already more or less integrated in my local copy of
forrest AAMOF), but since I said to my colleagues that I wanted to
submit it to forrest, we have been discussing refactoring and some
additional features ever since :-(

I'm also aware however of the fact that providing a functional codebase
helps with the adoption of new components, and we could go on endlessly
in RT-mode if we don't come up with a codebase to start with. After all,
Forrest has been mostly dead in the early days (sic) until Nicola and I
jumpstarted it with the addition of the early centipede codebase, which
was already pretty much cooked up prior to committing it

> that people can interact with you *before* you spend months
> developping
> and find out that many things that you considered *very cool*
> are simply
> not needed anymore.

agree, we are anxiously trying to balance momentum and good design
practices, and you know momentum is a prime mover & shaker in OSS
projects. The result *will* be released under an Apache license however,
whether it is used within Forrest or not, hopefully as being part of
Forrest or Cocoon, or on SF. While the scope of libre is much smaller
than the S&N portal contribution to Cocoon, its genesys should be
comparable: it was mostly finished intra muros before being released as
a contribution.

> In fact, I don't want the book.xml to be removed by a
> generator because
> no matter how powerful the generator is the book.xml file can contain
> much more metadata than any file system... and placing site-related
> metadata (such the one I suggested above) inside the document and have
> the generator extract it (a-la XPathDirectoryGenerator) seems like the
> wrong approach to me since it mixes concerns between the document
> authors and those who manage the site (which normally have different
> concerns).

-1

I hate book.xml from a user's POV. It's non-intuitive, duplicates
information, yet another thing people need to learn before they can
trust project documentation to the Forrest service, etc...

For simple document collections, it should be sufficient to put files in
a directory structure, and extract sequence and labeling from the
filename or by applying XPath onto the files. To do so, we have a simple
approach, configured using a little configuration file libre.xml, which
you could compare with .htaccess

It's all under reconsideration right now, but what we have working
currently is this:

libre.xml config file in content/xdocs:

<libre xmlns="http://outerx.org/libre/config/0.1">
  <auto>
    <filter logic="normal">
      <property name="name" regex=".*\.xml"/>
    </filter>
    <label>
      <xpath expression="/document/header/title/text()"/>
    </label>
  </auto>
</libre>

Output of our libre generator:

<collection xmlns="http://outerx.org/yer/hierarchy/0.1">
  <item/>
  <item label="Contribution to Forrest"/>
  <item label="The document-v1.1 DTD"/>
  <item label="Forrest dream list"/>
  <item/>
  <item/>
  <item label="Welcome to Forrest"/>
  <item label="The Apache Software License, Version 1.1"/>
  <item label="Mailing List Archives"/>
  <item label="Mailing Lists"/>
  <item label="The Forrest Primer"/>
  <item label="Who we are"/>
</collection>

As you can see, there are still issues (like directory handling in the
above example, which we are addressing), but this would mean a lot of
the information which now has to be hardcoded in book.xml can retrieved
from the documents itself.

We have basically three actions we do on a hierarchy (and this stuff is
being componentized so that we could implement this also on top of
non-filesystem hierarchies like a WebDAV resource):

 - filtering
 - labeling
 - sorting

all three of them based on xpath expressions, resource properties
(filename, mod date, etc) and regexes on these properties, with and'ing,
or'ing and not'ing for filters.

On your SoC remark: you're right, and maybe we will still need such an
additional metadata config file for a filesystem repository, but WebDAV
resource meta-attributes also move this responsibility to the individual
resource maintainer, and not to the collection manager, if my
assumptions are correct.

> I might be totally wrong and I'd love to be because I hate raining on
> somebody else's party (I'm abusing this metaphor today) but your "*we*
> need to think about this" rang a bell in my head.

you and me and other forresteers, thus, not 'we' ;-)

<aside>
> I still don't understand why we need to incorporate changes and todos
> into a project description file.

and I can only agree with that.
</aside>

Hopefully we find time to act upon our promises, you know we are trying
really hard ;-)

</Steven>

Re: import of xml.apache.org main site into forrest

[Stefano Mazzocchi <st...@apache.org>]

Steven Noels wrote:
> 
> > From: Stefano Mazzocchi [mailto:stefano@apache.org]
> 
> > Don't want to rain on the party, but are you sure that
> > xml-site/sources
> > contains the *uptodate* sources from all the various projects? I'm
> > pretty sure it doesn't.
> 
> Me, too. This is simply a showcase, and I've only translated the main
> site docs, nothing subproject-specific.
> 
> > This you do it to actually generate the xml.apache.org site
> > or just as a
> > test?
> 
> A test, and a starting ground for the main site.

Ok, very cool.

> > Yes, I wanted to raise this point earlier: there is no need
> > to 'require'
> > a document to have an author. For example, I dislike the fact
> > that even
> > the 'license.html' file has an author on top. It might lead to think
> > that the person is the author of the content of the page, rather than
> > the person who assembled the page from the content authored by other
> > people.
> 
> +1, will make that optional if no-one objects to this.

Great.
 
> > In those situations, it's much better to leave it out of the page.
> >
> > > - Auto-generation of mini TOC's - should this be
> > parametrizable? TOCs
> > > are generated now if sections exist within sections in a
> > document, which
> > > was good for the forrest docs so far, but suboptimal for the content
> > > imported from the main site. On the other hand, these
> > imported docs have
> > > been abusing the DTD to obtain certain visual effects,
> > IMNSHO - so we
> > > could fix the docs, too.
> >
> > I was going to patch this on my local copy removing the 'isfaq'
> > parameter (which semantically sucks!) and adding a 'minitoc'
> > parameter.
> 
> Oops... you're wright ;->

:)
 
> > Now, I believe the best place for 'behavioral skinning'
> > controls should
> > be the book.xml file, which is sort of a high level site map
> > (not in the
> > cocoon's sense of the term, but in the original 'map of the
> > site' sense)
> >
> > So, depending on the document, it's up to who links the
> > documento to the
> > book to indicate whether or not this document should have particular
> > skinning behaviors associated. Examples might be:
> >
> >  1) minitoc yes/no
> >  2) printable version yes/no
> >  3) multipage yes/no
> >  4) ???
> >
> > allowing us to set those behaviors in a single location and separating
> > the concern from the document author simplifis the editor's job of
> > providing the best visual coherence and usability for the entire doco
> > corpus.
> 
> I like this idea, we need to think about this.

I have the impression that you guys might be caught in the good old
"don't who till is ready" ego trap with your 'libre' effort. Release
early and often means also 'release when it barely does anything' so
that people can interact with you *before* you spend months developping
and find out that many things that you considered *very cool* are simply
not needed anymore.

In fact, I don't want the book.xml to be removed by a generator because
no matter how powerful the generator is the book.xml file can contain
much more metadata than any file system... and placing site-related
metadata (such the one I suggested above) inside the document and have
the generator extract it (a-la XPathDirectoryGenerator) seems like the
wrong approach to me since it mixes concerns between the document
authors and those who manage the site (which normally have different
concerns).

I might be totally wrong and I'd love to be because I hate raining on
somebody else's party (I'm abusing this metaphor today) but your "*we*
need to think about this" rang a bell in my head.
 
> > > Please review the result of this little transition exercise and post
> > > other issues you come across with.
> >
> > I'm offline so I don't have access (yet) to what you did, but I have a
> > few comments since I spent yesterday afternoon making myself
> > up-to-date
> > with Forrest.
> >
> > Things to note:
> >
> >  1) the navigation path on top of the page is static. I mean, when you
> > change page, the path doesn't change. We *must* fix this before making
> > Forrest go live.
> 
> -0 - we can do this later on, too. This is another area which could be
> touched by upcoming book.xml alternatives/additions, so we need to be
> careful with this.

Again, it's kind of hard to understand what to plan if we don't even
know what you guys are up to.
 
> >  2) the tabs are fake as well. this is another big showstopper.
> 
> I've seen Bert has a solutions for this, we need to wait and
> investigate.

Yes, our emails crossed, I'll sure take a look at what he did and report
back.
 
> >  3) there is no DTD for .xgump and this makes the changes and
> > toto DTDs
> > obsolete. Having a complete DTD for xgump and removing the obsoleted
> > DTDs is another showstopper.
> 
> Honestly, we don't have much dependencies on Gump. Build & project
> automation is a very political area,  cfr. Nicola's remark. Some careful
> thinking will be required.

I still don't understand why we need to incorporate changes and todos
into a project description file.

Nicola, what's your thinking about this?
 
> >  4) the javadoc DTD is unused and it doesn't seem that nobody is
> > interested in making it work for Forrest ATM. I propose to move it in
> > the scratchpad area.
> >
> > Expect more things as I go along.
> 
> You're absolutely welcome :-)

Cool.

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

RE: import of xml.apache.org main site into forrest

[Steven Noels <st...@outerthought.org>]

> From: Stefano Mazzocchi [mailto:stefano@apache.org]

> Don't want to rain on the party, but are you sure that
> xml-site/sources
> contains the *uptodate* sources from all the various projects? I'm
> pretty sure it doesn't.

Me, too. This is simply a showcase, and I've only translated the main
site docs, nothing subproject-specific.

> This you do it to actually generate the xml.apache.org site
> or just as a
> test?

A test, and a starting ground for the main site.

> Yes, I wanted to raise this point earlier: there is no need
> to 'require'
> a document to have an author. For example, I dislike the fact
> that even
> the 'license.html' file has an author on top. It might lead to think
> that the person is the author of the content of the page, rather than
> the person who assembled the page from the content authored by other
> people.

+1, will make that optional if no-one objects to this.

> In those situations, it's much better to leave it out of the page.
>
> > - Auto-generation of mini TOC's - should this be
> parametrizable? TOCs
> > are generated now if sections exist within sections in a
> document, which
> > was good for the forrest docs so far, but suboptimal for the content
> > imported from the main site. On the other hand, these
> imported docs have
> > been abusing the DTD to obtain certain visual effects,
> IMNSHO - so we
> > could fix the docs, too.
>
> I was going to patch this on my local copy removing the 'isfaq'
> parameter (which semantically sucks!) and adding a 'minitoc'
> parameter.

Oops... you're wright ;->

> Now, I believe the best place for 'behavioral skinning'
> controls should
> be the book.xml file, which is sort of a high level site map
> (not in the
> cocoon's sense of the term, but in the original 'map of the
> site' sense)
>
> So, depending on the document, it's up to who links the
> documento to the
> book to indicate whether or not this document should have particular
> skinning behaviors associated. Examples might be:
>
>  1) minitoc yes/no
>  2) printable version yes/no
>  3) multipage yes/no
>  4) ???
>
> allowing us to set those behaviors in a single location and separating
> the concern from the document author simplifis the editor's job of
> providing the best visual coherence and usability for the entire doco
> corpus.

I like this idea, we need to think about this.

> > Please review the result of this little transition exercise and post
> > other issues you come across with.
>
> I'm offline so I don't have access (yet) to what you did, but I have a
> few comments since I spent yesterday afternoon making myself
> up-to-date
> with Forrest.
>
> Things to note:
>
>  1) the navigation path on top of the page is static. I mean, when you
> change page, the path doesn't change. We *must* fix this before making
> Forrest go live.

-0 - we can do this later on, too. This is another area which could be
touched by upcoming book.xml alternatives/additions, so we need to be
careful with this.

>  2) the tabs are fake as well. this is another big showstopper.

I've seen Bert has a solutions for this, we need to wait and
investigate.

>  3) there is no DTD for .xgump and this makes the changes and
> toto DTDs
> obsolete. Having a complete DTD for xgump and removing the obsoleted
> DTDs is another showstopper.

Honestly, we don't have much dependencies on Gump. Build & project
automation is a very political area,  cfr. Nicola's remark. Some careful
thinking will be required.

>  4) the javadoc DTD is unused and it doesn't seem that nobody is
> interested in making it work for Forrest ATM. I propose to move it in
> the scratchpad area.
>
> Expect more things as I go along.

You're absolutely welcome :-)

</Steven>

Re: import of xml.apache.org main site into forrest

[Stefano Mazzocchi <st...@apache.org>]

Steven Noels wrote:
> 
> Hi all,
> 
> some mysterious motivational wind was blowing in my direction this
> evening, and I went haywire after my last visit to the ugly
> xml.apache.org main site.
> 
> Result:
> 
> - I've run all docs in the {xml-site}/sources/xml-site through the new
> docv10->docv11 translation stylesheet, tweaked the result manually, and
> imported the result of this into
> {xml-forrest}/src/documentation/content/xdocs/xml-site/
> - I rewrote the website.xml that came with it to our book.xml syntax,
> and added a link to the xml-site directory in our main book.xml

Don't want to rain on the party, but are you sure that xml-site/sources
contains the *uptodate* sources from all the various projects? I'm
pretty sure it doesn't.

This you do it to actually generate the xml.apache.org site or just as a
test?

> If all goes well, we have a draft version of the main xml.apache.org
> site at www.krysalis.org/forrest/xml-site/ after forrestbot has done its
> job.
> 
> What has this 3 hour exercise taught me:
> 
> - if the state of the other projects xml source files is comparable with
> those of the main site, we will need some thorough editorial review
> after migrating projects to forrest - people have been rather creative
> with the elements allowed by the old v10 DTD - using section-level
> elements instead of lists, inserting non-breakable spaces for table-like
> layout, <br>'s inside list items to mimick definition lists, etc... I
> haven't done much to solve these issues - so there's plenty of work for
> the editorially challenged amongst us :-)

Well, this is the reason why I'm scared from the use of more complex
DTDs and the lack of multi-channel output: People tend to 'tweak' the
markup based on the visual results, not the other way around.
 
> - we need to do something with the 'link' situation. Joerg, David et al,
> let's prepare a vote on this and resolve this thing. Now.

Done.

> - Please have a look at
> http://cvs.apache.org/viewcvs.cgi/xml-site/sources/website.xml?rev=1.27&
> content-type=text/vnd.viewcvs-markup which is the 'old' book.xml as has
> been used by the now defunct stylebook. I see <hidden> and <external>
> and I find these quite interesting. Your ideas?

I don't see the need for 'hidden' and the book.dtd shows that 'external'
is already in place (even if I don't see the need for it).
 
> - Previous xdocs didn't require an authors element being filled in - how
> will be solve this? Making authors optional again?

Yes, I wanted to raise this point earlier: there is no need to 'require'
a document to have an author. For example, I dislike the fact that even
the 'license.html' file has an author on top. It might lead to think
that the person is the author of the content of the page, rather than
the person who assembled the page from the content authored by other
people.

In those situations, it's much better to leave it out of the page.
 
> - Auto-generation of mini TOC's - should this be parametrizable? TOCs
> are generated now if sections exist within sections in a document, which
> was good for the forrest docs so far, but suboptimal for the content
> imported from the main site. On the other hand, these imported docs have
> been abusing the DTD to obtain certain visual effects, IMNSHO - so we
> could fix the docs, too.

I was going to patch this on my local copy removing the 'isfaq'
parameter (which semantically sucks!) and adding a 'minitoc' parameter.

Now, I believe the best place for 'behavioral skinning' controls should
be the book.xml file, which is sort of a high level site map (not in the
cocoon's sense of the term, but in the original 'map of the site' sense)

So, depending on the document, it's up to who links the documento to the
book to indicate whether or not this document should have particular
skinning behaviors associated. Examples might be:

 1) minitoc yes/no
 2) printable version yes/no
 3) multipage yes/no
 4) ???

allowing us to set those behaviors in a single location and separating
the concern from the document author simplifis the editor's job of
providing the best visual coherence and usability for the entire doco
corpus.

> - The bert skin - in general, I think the body text is a point (or two)
> too big - there isn't too much text on a screen. Bert, can we fix this?
> I know I can change the settings of my browser, but I believe the
> default font-size is 12pt, which is simply too big, showing too little
> content on a 1024*768 screen.

I agree.
 
> Please review the result of this little transition exercise and post
> other issues you come across with.

I'm offline so I don't have access (yet) to what you did, but I have a
few comments since I spent yesterday afternoon making myself up-to-date
with Forrest.

Things to note:

 1) the navigation path on top of the page is static. I mean, when you
change page, the path doesn't change. We *must* fix this before making
Forrest go live.

 2) the tabs are fake as well. this is another big showstopper.

 3) there is no DTD for .xgump and this makes the changes and toto DTDs
obsolete. Having a complete DTD for xgump and removing the obsoleted
DTDs is another showstopper.

 4) the javadoc DTD is unused and it doesn't seem that nobody is
interested in making it work for Forrest ATM. I propose to move it in
the scratchpad area.

Expect more things as I go along.
 
-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Steven Noels" <st...@outerthought.org>

> Hi all,
>
> some mysterious motivational wind was blowing in my direction this
> evening, and I went haywire after my last visit to the ugly
> xml.apache.org main site.

:-D

> Result:
>
> - I've run all docs in the {xml-site}/sources/xml-site through the new
> docv10->docv11 translation stylesheet, tweaked the result manually, and
> imported the result of this into
> {xml-forrest}/src/documentation/content/xdocs/xml-site/
> - I rewrote the website.xml that came with it to our book.xml syntax,
> and added a link to the xml-site directory in our main book.xml
>
> If all goes well, we have a draft version of the main xml.apache.org
> site at www.krysalis.org/forrest/xml-site/ after forrestbot has done its
> job.

Yup, it's there!!!  :-D

> What has this 3 hour exercise taught me:
>
> - if the state of the other projects xml source files is comparable with
> those of the main site, we will need some thorough editorial review
> after migrating projects to forrest - people have been rather creative
> with the elements allowed by the old v10 DTD - using section-level
> elements instead of lists, inserting non-breakable spaces for table-like
> layout, <br>'s inside list items to mimick definition lists, etc... I
> haven't done much to solve these issues - so there's plenty of work for
> the editorially challenged amongst us :-)

Yup, I've had the same problems with other projects.
This means that our only possible route is helping to convert to our format.

> - we need to do something with the 'link' situation. Joerg, David et al,
> let's prepare a vote on this and resolve this thing. Now.
>
> - Please have a look at
> http://cvs.apache.org/viewcvs.cgi/xml-site/sources/website.xml?rev=1.27&
> content-type=text/vnd.viewcvs-markup which is the 'old' book.xml as has
> been used by the now defunct stylebook. I see <hidden> and <external>
> and I find these quite interesting. Your ideas?

I really don't understand "hidden" much, but external should be something to
add to the link tag (ie in-context link or out of context).

> - Previous xdocs didn't require an authors element being filled in - how
> will be solve this? Making authors optional again?

I'd leave unknown for now, so that it's seen.

> - Auto-generation of mini TOC's - should this be parametrizable? TOCs
> are generated now if sections exist within sections in a document, which
> was good for the forrest docs so far, but suboptimal for the content
> imported from the main site. On the other hand, these imported docs have
> been abusing the DTD to obtain certain visual effects, IMNSHO - so we
> could fix the docs, too.
>
> - The bert skin - in general, I think the body text is a point (or two)
> too big - there isn't too much text on a screen. Bert, can we fix this?
> I know I can change the settings of my browser, but I believe the
> default font-size is 12pt, which is simply too big, showing too little
> content on a 1024*768 screen.

+1

> Please review the result of this little transition exercise and post
> other issues you come across with.

On the top: apache : xml.apache : forrest
Which is normal of course, since you imported it in the forrest run.
We will need to remember to check this.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

Re: import of xml.apache.org main site into forrest

[Nicola Ken Barozzi <ni...@apache.org>]

From: "Steven Noels" <st...@outerthought.org>

> > From: Steven Noels [mailto:stevenn@outerthought.org]
>
> > What has this 3 hour exercise taught me:
>
> some other thoughts after a night of sleep:
>
> - error handling: there were some invalid links in the documents after
> translation, pointing to unexisting resources (basically the old <link
> idref=""/> elements). The crawler chokes on these with the interesting
> ArrayOutOfBoundsException and 10 screens of further garbage (this always
> reminds me of the beauty of Java exception handling ;-) - but no real
> error message on what is going wrong - the crawler should be patched for
> this. IIRC, Cocoon Servlet exception handling has been improved lately,
> could someone brief me on this?

Well, basically now Cocoon handles the errors that once were directly sent
to the servlet contaainer and closes the stream... I don't think it would
mean much to us...

> - which brings me to another idea: Gump-like runs, i.e. be silent when
> everything goes well, but nag the project when there is a validation or
> docs generation error - with a meaningfull error message. There is
> someone on this list who has some experience with this matter ;-)

If we upgrade Ant to 1.5 there is a maillogger that gets triggered on fails.
I'll put that in, Gump uses scripts instead, and it's a bit more messy in
this regard ;-)

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------

RE: import of xml.apache.org main site into forrest

[Steven Noels <st...@outerthought.org>]

> From: Steven Noels [mailto:stevenn@outerthought.org]

> What has this 3 hour exercise taught me:

some other thoughts after a night of sleep:

- error handling: there were some invalid links in the documents after
translation, pointing to unexisting resources (basically the old <link
idref=""/> elements). The crawler chokes on these with the interesting
ArrayOutOfBoundsException and 10 screens of further garbage (this always
reminds me of the beauty of Java exception handling ;-) - but no real
error message on what is going wrong - the crawler should be patched for
this. IIRC, Cocoon Servlet exception handling has been improved lately,
could someone brief me on this?

- which brings me to another idea: Gump-like runs, i.e. be silent when
everything goes well, but nag the project when there is a validation or
docs generation error - with a meaningfull error message. There is
someone on this list who has some experience with this matter ;-)

</Steven>