You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Carsten Ziegeler <cz...@apache.org> on 2009/02/12 09:05:06 UTC
Spring Configurator Docs
Hi,
can someone point me to our online docs of the spring configurator? I
wasn't able to find it.. :(
Thanks
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: Documentation System [was: Spring Configurator Docs]
Posted by Luca Morandini <lm...@ieee.org>.
hepabolu wrote:
> Luca Morandini said the following on 12/2/09 20:27:
>>
>> Once upon a time there was planetcocoon.com... with blog and all sorts
>> of cocoon-related stuff, but it is now gone.
>
> But there was no new content in that. It was merely an aggregation of
> various sources. Nice to see everything in one place but not much in a
> way of documentation.
Hmm... I recall a feature like "Cocoon highlight of the week" or some
sort of blog: am I wrong ?
Regards,
--------------------
Luca Morandini
www.lucamorandini.it
--------------------
Re: Documentation System [was: Spring Configurator Docs]
Posted by hepabolu <he...@gmail.com>.
Luca Morandini said the following on 12/2/09 20:27:
> Benjamin Boksa wrote:
>>
>> As there is no official cocoon blog as far as I know I think such a
>> blog would be a good way (in addition to the existing documentation) to
>
> Once upon a time there was planetcocoon.com... with blog and all sorts
> of cocoon-related stuff, but it is now gone.
But there was no new content in that. It was merely an aggregation of
various sources. Nice to see everything in one place but not much in a
way of documentation.
Bye, Helma
Re: Documentation System [was: Spring Configurator Docs]
Posted by Luca Morandini <lm...@ieee.org>.
Benjamin Boksa wrote:
>
> As there is no official cocoon blog as far as I know I think such a blog
> would be a good way (in addition to the existing documentation) to
Once upon a time there was planetcocoon.com... with blog and all sorts
of cocoon-related stuff, but it is now gone.
Regards,
--------------------
Luca Morandini
www.lucamorandini.it
--------------------
Re: Documentation System [was: Spring Configurator Docs]
Posted by Benjamin Boksa <ma...@boksa.de>.
>> I did some "documentation port" myself, but I have to admit it is
>> not that easy, since something *may* indeed have changed in the
>> passage... bottom line: you have to know a component's behaviour in
>> both 2.1 and 2.2 before safely porting its doc.
> You're so right about that. It is a big job.
>
> I started updating the HTMLSerializer [1] but then realized there
> were actually two implementations of it with different sets of
> parameters. Not only that but a lot of 'folklore' and list wisdom
> was trapped in the mailing list and on the old wiki over the last
> few years and that needed to be set free.
I hope it is OK if I jump into this discussion - during the recent
months I have been working with Cocoon 2.2 a lot - it is really hard
to find documentation about some of the "advanced" features - and it
is even harder if some information are simply wrong (because they are
not up to date). I know I have not done my duty and corrected these
errors :-(
During some spare minutes (running, driving) I thought about about
possible ways to improve the documentation. On some blogs ([1], [2]) I
have found a lot of interesting (and quite accurate) information which
I could not find on the official cocoon page. I liked the HOWTO-
approach which imho is missing for many features (e.g. ("HOWTO
configure authentication")). The bits and pieces are there and
documented but I often miss the "red line" (hope I can say that in
english).
As there is no official cocoon blog as far as I know I think such a
blog would be a good way (in addition to the existing documentation) to
a) publish HOWTOs that do not fit into the source documentation
b) publish articles that aggregate information from the existing
documentation/link to them
c) link to other interesting articles from outside (which might
motivate some people to write about cocoon to get some traffic from
the official blog)
d) inform about updates
e) inform of other cocoon/apache-related events
What is published there could be revised by some developers before
publishing and people from outside can easily contribute stuff.
Commenting would also allow to improve possible published best
practices… Tagging would allow to structure information…
Just my two cents - thanks for reading this,
Benjamin
[1] http://mrhaki.blogspot.com/search/label/Cocoon
[2] http://happygiraffe.net/blog/tag/cocoon/
[ANN] VTD-XML 2.5
Posted by cr...@comcast.net.
VTD-XML 2.5 is now released. Please go to https://sourceforge.net/project/showfiles.php?group_id=110612&package_id=120172&release_id=661376 to download the latest version.
Changes from Version 2.4 (2/2009)
* Added separate VTD indexing generating and loading (see http://vtd-xml.sf.net/persistence.html for further info)
* Integrated extended VTD supporting 256 GB doc (In Java only).
* Added duplicateNav() for replicate multiple VTDNav instances sharing XML, VTD and LC buffer (availabe in Java and C#).
* Various bug fixes and enhancements
Re: Documentation System [was: Spring Configurator Docs]
Posted by Grzegorz Kossakowski <gr...@tuffmail.com>.
Carsten Ziegeler pisze:
> I think there are too many steps involved in getting something out -
> adding chapters is really a pain; and as we see above we're loosing
> content and nearly noone notices this and nearly noone knows how to
> restore this.
Yes, this system is complex but, to be honest, if we want to achieve all goals that we set in the past I don't see an
easy solution.
I believe that the whole idea behind our system is not that bad but there are so many small things that have to be
improved. When it comes to publishing it's not that hard if you make use of nightly builds that our zone does. Then it's
only editing in Daisy and doing svn ci on the zone.
When it comes to loosing content that nobody noticed. I think there are two reasons for that:
a) massive commits into svn (when someone publishes something) that I'm never happy with
b) problem with Daisy resending change notifications which, I guess, killed everyone's will to actively track changes
Both result in weak changes review that lead to such unpleasant situations. First is a more issue with people's habits
but the second is purely an issue with our Daisy installation.
I would investigate but we would need to update our Daisy instance as we are using really old version. I wanted to do
that a few times in the past but the amount of the work and fragility of our current setup always scared me away. Still
doing it is a must. I would take this challenge if there was someone more knowledgeable with Solaris administration
willing to help.
Might it be a task for Amsterdam's hackathon provided we had done earlier preparations?
> And still I think the resulting urls are really not pretty urls, I
> really would prefer something like
> http://cocoon.apache.org/spring-configurator/index.html
>
> But again, maybe it's just me.
No, it's not only you.
Actually, I've played with this over summer a little bit but I decided to give up until we upgrade our Daisy instance
because that work would probably have to be redone after the upgrade.
The biggest challenge is to track renames correctly including first time rename from Daisy's ids to real names. I don't
think it's impossible to be done (and not so hard once you know how Maven plug-in works internally) but still I would
prefer if it have attracted attention of more than one person so chances of a mistake are minimized.
--
Best regards,
Grzegorz Kossakowski
Re: Documentation System [was: Spring Configurator Docs]
Posted by Carsten Ziegeler <cz...@apache.org>.
Grzegorz Kossakowski wrote:
> Grzegorz Kossakowski pisze:
>> Hi Carsten,
>>
>> Apparently, there is a mess with configurator docs.
>>
>> Here you can see that there are no 2.0 docs:
>> http://svn.eu.apache.org/repos/asf/cocoon/site/site/subprojects/configuration/
>>
>> Even if we have a link to them here:
>> http://cocoon.apache.org/subprojects/
>>
>> This looks like someone forgot to regenerate docs after the release.
>>
>> Anyway, this does not explain why docs are not reachable even if I remember they were. I'll try to ask git bisect for a
>> faulty commit.
>>
>> Will report my findings.
>
> Ok, I found the faulty change:
> http://cocoon.zones.apache.org/daisy/cdocs/g2/g7/1329/version/5/diff?otherVersion=6
>
> As you can see, this change removed the whole table that linked to documentation of Configurator. I have no clue on this
> change so I guess we'll need to ask Reinhard what's going on.
>
> As a side-note: I can feel your pain with our current documentation system. I don't think it's fundamentally flawed but
> little bit not maintained-enough. There are areas for improvements.
> The biggest I can see is removing mismatch between version information stored in svn and daisy. Daisy lacks any
> information about our artifacts we are releasing which leads to annoying problems.
>
I think there are too many steps involved in getting something out -
adding chapters is really a pain; and as we see above we're loosing
content and nearly noone notices this and nearly noone knows how to
restore this.
And still I think the resulting urls are really not pretty urls, I
really would prefer something like
http://cocoon.apache.org/spring-configurator/index.html
But again, maybe it's just me.
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: Documentation System [was: Spring Configurator Docs]
Posted by Grzegorz Kossakowski <gr...@tuffmail.com>.
Grzegorz Kossakowski pisze:
>
> Hi Carsten,
>
> Apparently, there is a mess with configurator docs.
>
> Here you can see that there are no 2.0 docs:
> http://svn.eu.apache.org/repos/asf/cocoon/site/site/subprojects/configuration/
>
> Even if we have a link to them here:
> http://cocoon.apache.org/subprojects/
>
> This looks like someone forgot to regenerate docs after the release.
>
> Anyway, this does not explain why docs are not reachable even if I remember they were. I'll try to ask git bisect for a
> faulty commit.
>
> Will report my findings.
Ok, I found the faulty change:
http://cocoon.zones.apache.org/daisy/cdocs/g2/g7/1329/version/5/diff?otherVersion=6
As you can see, this change removed the whole table that linked to documentation of Configurator. I have no clue on this
change so I guess we'll need to ask Reinhard what's going on.
As a side-note: I can feel your pain with our current documentation system. I don't think it's fundamentally flawed but
little bit not maintained-enough. There are areas for improvements.
The biggest I can see is removing mismatch between version information stored in svn and daisy. Daisy lacks any
information about our artifacts we are releasing which leads to annoying problems.
--
Best regards,
Grzegorz Kossakowski
Re: Documentation System [was: Spring Configurator Docs]
Posted by Grzegorz Kossakowski <gr...@tuffmail.com>.
Carsten Ziegeler pisze:
> Robby Pelssers schrieb:
>> Hi Carsten,
>>
>> It's a bit hidden, but if you click on the link Cocoon2.2 under
>> versions, you will get the overview page with a link to the spring
>> configurator.
>>
> Hmm, but this opens
>
> http://cocoon.apache.org/subprojects/configuration/1.0/1329_1_1.html
>
> which allows me to just download the configurator, but I still can't see
> the docs :)
Hi Carsten,
Apparently, there is a mess with configurator docs.
Here you can see that there are no 2.0 docs:
http://svn.eu.apache.org/repos/asf/cocoon/site/site/subprojects/configuration/
Even if we have a link to them here:
http://cocoon.apache.org/subprojects/
This looks like someone forgot to regenerate docs after the release.
Anyway, this does not explain why docs are not reachable even if I remember they were. I'll try to ask git bisect for a
faulty commit.
Will report my findings.
--
Best regards,
Grzeogrz Kossakowski
Re: Documentation System [was: Spring Configurator Docs]
Posted by Carsten Ziegeler <cz...@apache.org>.
Robby Pelssers schrieb:
> Hi Carsten,
>
> It's a bit hidden, but if you click on the link Cocoon2.2 under
> versions, you will get the overview page with a link to the spring
> configurator.
>
Hmm, but this opens
http://cocoon.apache.org/subprojects/configuration/1.0/1329_1_1.html
which allows me to just download the configurator, but I still can't see
the docs :)
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
RE: Documentation System [was: Spring Configurator Docs]
Posted by Robby Pelssers <ro...@ciber.nl>.
Hi Carsten,
It's a bit hidden, but if you click on the link Cocoon2.2 under
versions, you will get the overview page with a link to the spring
configurator.
Would be nice if the site had full-text search which would show links to
all pages containing the searchargument and maybe showing the title of
the pages.... Not sure if Daisy provides this functionality?
Kind regards,
Robby Pelssers
-----Original Message-----
From: Carsten Ziegeler [mailto:cziegeler@apache.org]
Sent: vrijdag 13 februari 2009 9:10
To: dev@cocoon.apache.org
Subject: Re: Documentation System [was: Spring Configurator Docs]
hepabolu wrote:
>
> As one of the initiators of the current Daisy documentation route, I
am
> feeling the same pain. My current use of Cocoon is 0% although I can't
> get myself to unsubscribe from the lists. ;-)
> The current pace of development is too quick to help out in
> documentation if you're not heavily involved in the project.
>
> My initial ideas about this setup was that it's fairly easy and quick
to
> open up a page in Daisy and start adding documentation. That way the
> chances of actually adding documentation increase. Anything that takes
a
> lot of time will spoil the chance of actual writing.
> Don't think that each page in Daisy should immediately be added to the
> general site, but use the update frequency to let it simmer and
improve
> the quality.
>
Once you have a page, adding/editing the docs is easy with Daisy -
that's fine; but adding new pages or new folders has always been a
mystery for me. There are some docs on how to do this, but even
following them is rather complicated. Anyway, if the people who
contribute to the docs are fine with this setup, its great. In most of
the other Apache projects I'm working on, we're using Confluence which
has the important advantage that the installation is supported by infra.
It would be great if someone could find out why the docs for the spring
configurator are not linked anymore on our site (or I'm still too dumb
to find the links). Thanks
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: Documentation System [was: Spring Configurator Docs]
Posted by Carsten Ziegeler <cz...@apache.org>.
hepabolu wrote:
>
> As one of the initiators of the current Daisy documentation route, I am
> feeling the same pain. My current use of Cocoon is 0% although I can't
> get myself to unsubscribe from the lists. ;-)
> The current pace of development is too quick to help out in
> documentation if you're not heavily involved in the project.
>
> My initial ideas about this setup was that it's fairly easy and quick to
> open up a page in Daisy and start adding documentation. That way the
> chances of actually adding documentation increase. Anything that takes a
> lot of time will spoil the chance of actual writing.
> Don't think that each page in Daisy should immediately be added to the
> general site, but use the update frequency to let it simmer and improve
> the quality.
>
Once you have a page, adding/editing the docs is easy with Daisy -
that's fine; but adding new pages or new folders has always been a
mystery for me. There are some docs on how to do this, but even
following them is rather complicated. Anyway, if the people who
contribute to the docs are fine with this setup, its great. In most of
the other Apache projects I'm working on, we're using Confluence which
has the important advantage that the installation is supported by infra.
It would be great if someone could find out why the docs for the spring
configurator are not linked anymore on our site (or I'm still too dumb
to find the links). Thanks
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: Documentation System [was: Spring Configurator Docs]
Posted by hepabolu <he...@gmail.com>.
David Legg said the following on 12/2/09 16:42:
> Luca,
>
>> I did some "documentation port" myself, but I have to admit it is not
>> that easy, since something *may* indeed have changed in the passage...
>> bottom line: you have to know a component's behaviour in both 2.1 and
>> 2.2 before safely porting its doc.
> You're so right about that. It is a big job.
>
> I started updating the HTMLSerializer [1] but then realized there were
> actually two implementations of it with different sets of parameters.
> Not only that but a lot of 'folklore' and list wisdom was trapped in the
> mailing list and on the old wiki over the last few years and that needed
> to be set free.
As one of the initiators of the current Daisy documentation route, I am
feeling the same pain. My current use of Cocoon is 0% although I can't
get myself to unsubscribe from the lists. ;-)
The current pace of development is too quick to help out in
documentation if you're not heavily involved in the project.
My initial ideas about this setup was that it's fairly easy and quick to
open up a page in Daisy and start adding documentation. That way the
chances of actually adding documentation increase. Anything that takes a
lot of time will spoil the chance of actual writing.
Don't think that each page in Daisy should immediately be added to the
general site, but use the update frequency to let it simmer and improve
the quality.
Bye, Helma
Re: Documentation System [was: Spring Configurator Docs]
Posted by David Legg <da...@searchevent.co.uk>.
Luca,
> I did some "documentation port" myself, but I have to admit it is not
> that easy, since something *may* indeed have changed in the passage...
> bottom line: you have to know a component's behaviour in both 2.1 and
> 2.2 before safely porting its doc.
You're so right about that. It is a big job.
I started updating the HTMLSerializer [1] but then realized there were
actually two implementations of it with different sets of parameters.
Not only that but a lot of 'folklore' and list wisdom was trapped in the
mailing list and on the old wiki over the last few years and that needed
to be set free.
Regards,
David Legg
[1]
http://cocoon.zones.apache.org/daisy/cdocs/g1/g1/g2/g4/Serializer/896.html
Re: Documentation System [was: Spring Configurator Docs]
Posted by Luca Morandini <lm...@ieee.org>.
David Legg wrote:
>
> I still cringe about the number of empty pages. I must continue to put
> more content in... I believe it is killing the project at the moment.
Me too... actually, I suggested to delay the release of 2.2 in order to
move all the applicable 2.1 docs into the 2.2 sub-site, but that
suggestion was turned down.
I did some "documentation port" myself, but I have to admit it is not
that easy, since something *may* indeed have changed in the passage...
bottom line: you have to know a component's behaviour in both 2.1 and
2.2 before safely porting its doc.
> Ok... you win!
That's refreshing... I'm used to lose most (all ?) arguments ;)
Regards,
--------------------
Luca Morandini
www.lucamorandini.it
--------------------
Documentation System [was: Spring Configurator Docs]
Posted by David Legg <da...@searchevent.co.uk>.
Hi Luca,
>> Also it might have seemed like a brilliant idea to extract
>> documentation directly out of the code but that actually adds a
>> further barrier to getting it done as you are then faced with
>> updating the code when all you wanted to do was write about it.
>
> One has to choose the lesser of two evils: steeper learning curve vs
> probable de-synchronization of docs from the actual code... I'd say
> the former is the less harmful.
I *was* going to respond by listing all the pages which currently say
"No documentation available yet" e.g. [1]. But as I started I realized
you were right :-)
I can see now that automatically lifting information out of the code
has, if anything, saved the docs from being completely bare!
I still cringe about the number of empty pages. I must continue to put
more content in... I believe it is killing the project at the moment.
>> The final hurdle is that even after you have edited the page and made
>> it active it still isn't visible on the main Cocoon site until some
>> arcane command line incantations are performed.
>
> I think having a staging docbase is not bad at all, it lets you revise
> stuff before being published, not to mention the better performance of
> the published site.
I just tried looking at the documentation for this [2] and noticed it
has been updated. It looks easier to do now!
Ok... you win!
Regards,
David Legg
[1] http://cocoon.apache.org/2.2/core-modules/core/2.2/1043_1_1.html
[2] http://cocoon.apache.org/1418_1_1.html
Re: Spring Configurator Docs
Posted by Luca Morandini <lm...@ieee.org>.
David Legg wrote:
> I have to agree that the current documentation system is a bit of a
> nightmare.
>
> As I see it there are too many hurdles that have to be passed through
> before documents become visible to the general public. I had a go at
> updating a few pages using the Daisy system. Editing an existing
> document is easy enough but I never had the time to learn how to drive
> the navigation sytem... and I suspect nobody else did either ;-) This
> is why moving between docs is so difficult.
Well, Daisy has a rather flexible way of grouping documents by using
"collections" (one document may belong to more than one collection); I
understand this is different from the strictly hierarchical way of, say,
Confluence... but it is easier to maintain too.
> Also it might have seemed like a brilliant idea to extract documentation
> directly out of the code but that actually adds a further barrier to
> getting it done as you are then faced with updating the code when all
> you wanted to do was write about it.
One has to choose the lesser of two evils: steeper learning curve vs
probable de-synchronization of docs from the actual code... I'd say the
former is the less harmful.
> The final hurdle is that even after you have edited the page and made it
> active it still isn't visible on the main Cocoon site until some arcane
> command line incantations are performed.
I think having a staging docbase is not bad at all, it lets you revise
stuff before being published, not to mention the better performance of
the published site.
> Bring back the wiki I say!
I beg to differ ;)
Regards,
--------------------
Luca Morandini
www.lucamorandini.it
--------------------
Re: Spring Configurator Docs
Posted by David Legg <da...@searchevent.co.uk>.
I have to agree that the current documentation system is a bit of a
nightmare.
As I see it there are too many hurdles that have to be passed through
before documents become visible to the general public. I had a go at
updating a few pages using the Daisy system. Editing an existing
document is easy enough but I never had the time to learn how to drive
the navigation sytem... and I suspect nobody else did either ;-) This
is why moving between docs is so difficult.
Also it might have seemed like a brilliant idea to extract documentation
directly out of the code but that actually adds a further barrier to
getting it done as you are then faced with updating the code when all
you wanted to do was write about it.
The final hurdle is that even after you have edited the page and made it
active it still isn't visible on the main Cocoon site until some arcane
command line incantations are performed.
Bring back the wiki I say!
Regards,
David Legg
Re: Spring Configurator Docs
Posted by Carsten Ziegeler <cz...@apache.org>.
Robby Pelssers wrote:
> Speaking of docs...
>
> I really have difficulties finding documentation on the new cocoon2.2
> site. The 2.1 was much more structured in my opinion. There probably is
> a lot well documented but it's a nightmare to find the information
> back. The menu only has a few links to get started but there is no
> clear way of navigating to the other pages...
>
Hmm, yes I agree and I had the same feeling when trying to edit/update docs
back in the good old days :(
May be it's time to use something like confluence for C3....
Carsten
--
Carsten Ziegeler
cziegeler@apache.org
RE: Spring Configurator Docs
Posted by Robby Pelssers <ro...@ciber.nl>.
Speaking of docs...
I really have difficulties finding documentation on the new cocoon2.2
site. The 2.1 was much more structured in my opinion. There probably is
a lot well documented but it's a nightmare to find the information
back. The menu only has a few links to get started but there is no
clear way of navigating to the other pages...
Unless somebody can point me out how-to ;-)
Cheers,
Robby
-----Original Message-----
From: Carsten Ziegeler [mailto:cziegeler@apache.org]
Sent: donderdag 12 februari 2009 9:54
To: dev@cocoon.apache.org
Subject: Re: Spring Configurator Docs
Chirathuru, Nagaraju wrote:
> Hi Carsten,
>
> Here it is.....
>
>
http://cocoon.apache.org/subprojects/configuration/1.0/spring-configurat
> or/2.0/1304_1_1.html
>
Ah, thanks!
Is there a link from the main or the sub projects site?
All I see is this:
http://cocoon.apache.org/subprojects/configuration/1.0/1329_1_1.html
without any pointers to the docs.
Carsten
>
> Cheers
> Nagaraju Chittathuru
>
> -----Original Message-----
> From: Carsten Ziegeler [mailto:cziegeler@apache.org]
> Sent: Thursday, February 12, 2009 1:35 PM
> To: Cocoon-Dev
> Subject: Spring Configurator Docs
>
> Hi,
>
> can someone point me to our online docs of the spring configurator? I
> wasn't able to find it.. :(
>
> Thanks
> Carsten
--
Carsten Ziegeler
cziegeler@apache.org
Re: Spring Configurator Docs
Posted by Carsten Ziegeler <cz...@apache.org>.
Chirathuru, Nagaraju wrote:
> Hi Carsten,
>
> Here it is.....
>
> http://cocoon.apache.org/subprojects/configuration/1.0/spring-configurat
> or/2.0/1304_1_1.html
>
Ah, thanks!
Is there a link from the main or the sub projects site?
All I see is this:
http://cocoon.apache.org/subprojects/configuration/1.0/1329_1_1.html
without any pointers to the docs.
Carsten
>
> Cheers
> Nagaraju Chittathuru
>
> -----Original Message-----
> From: Carsten Ziegeler [mailto:cziegeler@apache.org]
> Sent: Thursday, February 12, 2009 1:35 PM
> To: Cocoon-Dev
> Subject: Spring Configurator Docs
>
> Hi,
>
> can someone point me to our online docs of the spring configurator? I
> wasn't able to find it.. :(
>
> Thanks
> Carsten
--
Carsten Ziegeler
cziegeler@apache.org
RE: Spring Configurator Docs
Posted by "Chirathuru, Nagaraju" <NC...@ciber.com>.
Hi Carsten,
Here it is.....
http://cocoon.apache.org/subprojects/configuration/1.0/spring-configurat
or/2.0/1304_1_1.html
Cheers
Nagaraju Chittathuru
-----Original Message-----
From: Carsten Ziegeler [mailto:cziegeler@apache.org]
Sent: Thursday, February 12, 2009 1:35 PM
To: Cocoon-Dev
Subject: Spring Configurator Docs
Hi,
can someone point me to our online docs of the spring configurator? I
wasn't able to find it.. :(
Thanks
Carsten
--
Carsten Ziegeler
cziegeler@apache.org