Re: [proposal] Cocoon documentation system
Andreas Kuckartz wrote: Look at http://wiki.apache.org/cocoon/CocoonDocumentationSystem and find all my requirements. I'm sure that all six options are good enough but as *I* have to do it, I'll take the road that's the fastest for *me*. There was a misunderstanding on my side. I had thought that that was to be a project of the Apache Cocoon community and that other Cocoon-developers would also participate. In any case I wish you success with your project. Wait. Any developer can be involved and all ideas are good. Reinhard is running, the rest of us can catch up and help. Lenya is not ruled out. In fact, all those options that Reinhard listed could be used in parallel. The thing is, that we are trying to get started with something right now, start small and build up. --David
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote:
Bertrand Delacretaz wrote:
Le 18 janv. 05, à 09:59, Reinhard Poetz a écrit :
...as *I* have to do it, I'll take the road that's the fastest for
*me*...
+1, whoever does the work gets to decide (and later the community
decides to use the stuff or not, but in this case I'm not worried ;-)
+1, darwin and do-ocracy do the job a lot better.
If I were the one to do it I would start with the requirements and get
there with the simplest thing that can possibly work... and work from
there.
So, go Reinhard! :-)
[sylvain, you'd better keep up buddy, or I might change my hero plate
;-)]
Grmmbl... You're challenging me ;-)
Anyway, I hope your hero plate is large enough to hold the names of
everybody that deserves it. Keep up the good job, Reinhard!
Sylvain, in a conference room at the ObjectWebCon
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: [proposal] Cocoon documentation system
Sylvain Wallez wrote: Stefano Mazzocchi wrote: Bertrand Delacretaz wrote: Le 18 janv. 05, à 09:59, Reinhard Poetz a écrit : ...as *I* have to do it, I'll take the road that's the fastest for *me*... +1, whoever does the work gets to decide (and later the community decides to use the stuff or not, but in this case I'm not worried ;-) +1, darwin and do-ocracy do the job a lot better. If I were the one to do it I would start with the requirements and get there with the simplest thing that can possibly work... and work from there. So, go Reinhard! :-) [sylvain, you'd better keep up buddy, or I might change my hero plate ;-)] Grmmbl... You're challenging me ;-) Anyway, I hope your hero plate is large enough to hold the names of everybody that deserves it. Keep up the good job, Reinhard! Nah, the hero plate holds only *one* person at a time :-) Actually, and I'm not joking, I think we should have a hero plate on our web page and put the name and have a nomination!... some ego stimulation goes a lng way... h -- Stefano.
Re: [proposal] Cocoon documentation system
Actually, and I'm not joking, I think we should have a hero plate on our web page and put the name and have a nomination!... some ego stimulation goes a lng way... h Wow, employee^H^H^H^H^H^H^H^Hcommitter of the month! Now that would feel like working at McDonald's :-) -- Gianugo Rabellino Pro-netics s.r.l. - http://www.pro-netics.com Orixo, the XML business alliance: http://www.orixo.com (blogging at http://www.rabellino.it/blog/)
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: Stefano Mazzocchi wrote: ... tell you what. forget about it for now. Think about going dynamic and later we'll find a way to make a persistent copy of that (either via forrest or simply by wget or something) +1 Forrest - pardon my rudeness - sucks as a static site generation system. I can't wait to have it shine as a dynamic system :-) point taken :-) here my next steps: - adapt the proposal so that it reflects the results of the discussion - same for the two demo repositories - implement the web application For historical reasons, and for collaboration opportunity, Cocoon committers have committer access to the Forrest SVN repository. I'd personally be happy if you would like to work on this in the Forrest repo, and I'm positively sure that there would be no objections from other Forrest participants :-) -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains) -
Re: [proposal] Cocoon documentation system
Nicola Ken Barozzi wrote: Forrest - pardon my rudeness - sucks as a static site generation system. I can't wait to have it shine as a dynamic system :-) What prevents the use of Apache Lenya ? Cheers, Andreas
Re: [proposal] Cocoon documentation system
Andreas Kuckartz wrote: Nicola Ken Barozzi wrote: Forrest - pardon my rudeness - sucks as a static site generation system. I can't wait to have it shine as a dynamic system :-) What prevents the use of Apache Lenya ? Nothing or as less as the use of - Daisy, - Hippo CMS (if it is really OS licensed now), - Forrest, - Gianugo's little CMS (http://www.rabellino.it/blog/index.php ?title=writing_stuff_for_with_cocoonmore=1c=1tb=1pb=1) - write my own Look at http://wiki.apache.org/cocoon/CocoonDocumentationSystem and find all my requirements. I'm sure that all six options are good enough but as *I* have to do it, I'll take the road that's the fastest for *me*. Don't forget that learning where I have to add extensions to an enterprise level CMS like Daisy, Hippo or Lenya would take *a lot* of time. And as I have the (maybe illusionary) view, that I would be rather fast in implementing it on my own, I'll probably go the Forrest, Gianugo or write my own way. That's it. Once again, nothing speaks against taking one of the enterprise level CMS and if one of the communities around them does the implementation and takes all requirements listed at http://wiki.apache.org/cocoon/CocoonDocumentationSystem into consideration, I'm the last one who stops them. One thing to add: I want to see a prototyp of the webapp running in 6-8 weeks from now; whoever writes it. -- Reinhard
Re: [proposal] Cocoon documentation system
Look at http://wiki.apache.org/cocoon/CocoonDocumentationSystem and find all my requirements. I'm sure that all six options are good enough but as *I* have to do it, I'll take the road that's the fastest for *me*. There was a misunderstanding on my side. I had thought that that was to be a project of the Apache Cocoon community and that other Cocoon-developers would also participate. In any case I wish you success with your project. Cheers, Andreas
Re: [proposal] Cocoon documentation system
Andreas Kuckartz wrote: Look at http://wiki.apache.org/cocoon/CocoonDocumentationSystem and find all my requirements. I'm sure that all six options are good enough but as *I* have to do it, I'll take the road that's the fastest for *me*. There was a misunderstanding on my side. I had thought that that was to be a project of the Apache Cocoon community and that other Cocoon-developers would also participate. In any case I wish you success with your project. As we have been discussing it for years, I *really* don't want to wait any longer and in the next 6-8 weeks I should have some time for it. I can't force or pay anybody to do the work (means coding, configuring, installing, ...) for me, so *I* will do it. Whoever wants to help me, is invited - I wouldn't discuss my proposal in public if things would be different. -- Reinhard
Re: [proposal] Cocoon documentation system
On 18 Jan 2005, at 09:59, Reinhard Poetz wrote: Andreas Kuckartz wrote: Nicola Ken Barozzi wrote: Forrest - pardon my rudeness - sucks as a static site generation system. I can't wait to have it shine as a dynamic system :-) What prevents the use of Apache Lenya ? Nothing or as less as the use of - write my own :-) I think we're touching the core of the issue here. Rather than looking at lists of features, there's a list of requirements. Without any hard feelings at all, I've lost the ambition or energy to try and motivate people to shape their requirements to better reflect Daisy's features - I prefer Daisy users to make a positive choice instead (look at all the features I got!) rather than a negative one (only 85% of my requirements are addressed so I'm doomed). Look at how Jira (and in the future perhaps Confluence) quickly won lots of ASF users - even though Jira is a pig to keep running (Daisy isn't). I understand that part of the requirements is to comply with the existing ASF infrastructure. I've had my opportunity to run a non-ASF-infra-resource for two years, and I'm happy that I don't have to check server logs of the Wiki anymore. I do hate the current documentation system and MoinMoin wiki with a passion though, as its split personality is obviously not helping people to produce better documentation. So we definitely need one system, which supports both Wiki-style grassroots authoring, and a proper software documentation CMS. And yes, ASF-compliancy means we should be careful about security if we want to run alongside the code repositories. The only thing I am worried about is that your system will add a third option, and that you'll feel the pain in supporting it as I've felt with the JSPWiki at times. I think it will be very hard to combine both editorial and technical/logistical work. Yeah, I'm trying to sell you Daisy, while I don't commit myself to the documentation overhaul effort. That's because we want to support Daisy's users (which could very well be the documentation overhaulers), rather than loose ourselves again in both doing the work, and supporting the logistics around it. I'm a passive salesman here: I'd be happy and honoured if Cocoon picks Daisy for its features, but Daisy doesn't need such a project to succeed. /Steven -- Steven Noelshttp://outerthought.org/ Outerthought - Open Source Java XMLAn Orixo Member Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
Re: [proposal] Cocoon documentation system
Le 18 janv. 05, à 09:59, Reinhard Poetz a écrit : ...as *I* have to do it, I'll take the road that's the fastest for *me*... +1, whoever does the work gets to decide (and later the community decides to use the stuff or not, but in this case I'm not worried ;-) -Bertrand smime.p7s Description: S/MIME cryptographic signature
Re: [proposal] Cocoon documentation system
Steven Noels wrote: On 18 Jan 2005, at 09:59, Reinhard Poetz wrote: Andreas Kuckartz wrote: Nicola Ken Barozzi wrote: Forrest - pardon my rudeness - sucks as a static site generation system. I can't wait to have it shine as a dynamic system :-) What prevents the use of Apache Lenya ? Nothing or as less as the use of - write my own :-) I think we're touching the core of the issue here. Rather than looking at lists of features, there's a list of requirements. Without any hard feelings at all, I've lost the ambition or energy to try and motivate people to shape their requirements to better reflect Daisy's features - I'm not in the position to change the ASF policy and I don't have the energy to lead all the necessary discussions. I prefer Daisy users to make a positive choice instead (look at all the features I got!) rather than a negative one (only 85% of my requirements are addressed so I'm doomed). Look at how Jira (and in the future perhaps Confluence) quickly won lots of ASF users - even though Jira is a pig to keep running (Daisy isn't). I understand that part of the requirements is to comply with the existing ASF infrastructure. I've had my opportunity to run a non-ASF-infra-resource for two years, and I'm happy that I don't have to check server logs of the Wiki anymore. I do hate the current documentation system and MoinMoin wiki with a passion though, as its split personality is obviously not helping people to produce better documentation. So we definitely need one system, which supports both Wiki-style grassroots authoring, and a proper software documentation CMS. And yes, ASF-compliancy means we should be careful about security if we want to run alongside the code repositories. The only thing I am worried about is that your system will add a third option, and that you'll feel the pain in supporting it as I've felt with the JSPWiki at times. If I choose Daisy or whatever I could feel the same pain. In all my projects I've done so far, Cocoon runs pretty stable *and* in this community there are one or two Cocoon specialists available that could help out ;-) And of course the plan is to have the webapp running on ASF infrastructure. First on brutus.apache.org and I'm sure we get a secure server that is allowed to access our SVN repo, if tests on brutus run well. One thing to add: Of course I don't commit myself to provide a 24/7 support. Maybe my attempt will fail, don't know. Maybe somebody else will jump in then, I don't know. Maybe it's the start of a new area in Cocoon documentation, who knows. I think it will be very hard to combine both editorial and technical/logistical work. I'll concentrate on the technical/logistical work. Upayavira on the editoral work (I hope his plans haven't changed). Yeah, I'm trying to sell you Daisy, while I don't commit myself to the documentation overhaul effort. That's because we want to support Daisy's users (which could very well be the documentation overhaulers), rather than loose ourselves again in both doing the work, and supporting the logistics around it. I'm a passive salesman here: I'd be happy and honoured if Cocoon picks Daisy for its features, but Daisy doesn't need such a project to succeed. I'm sure! -- Reinhard
Re: [proposal] Cocoon documentation system
On 18 Jan 2005, at 10:59, Reinhard Poetz wrote: I'm not in the position to change the ASF policy and I don't have the energy to lead all the necessary discussions. Sure. Ditto here. :-) Besides, the ASF policy is sound, if only optimized a wee bit towards source code governance and the risk of trojans being embedded in our products, rather than documentation sites being hacked. I prefer Daisy users to make a positive choice instead (look at all the features I got!) rather than a negative one (only 85% of my requirements are addressed so I'm doomed). Look at how Jira (and in the future perhaps Confluence) quickly won lots of ASF users - even though Jira is a pig to keep running (Daisy isn't). I understand that part of the requirements is to comply with the existing ASF infrastructure. I've had my opportunity to run a non-ASF-infra-resource for two years, and I'm happy that I don't have to check server logs of the Wiki anymore. I do hate the current documentation system and MoinMoin wiki with a passion though, as its split personality is obviously not helping people to produce better documentation. So we definitely need one system, which supports both Wiki-style grassroots authoring, and a proper software documentation CMS. And yes, ASF-compliancy means we should be careful about security if we want to run alongside the code repositories. The only thing I am worried about is that your system will add a third option, and that you'll feel the pain in supporting it as I've felt with the JSPWiki at times. If I choose Daisy or whatever I could feel the same pain. In all my projects I've done so far, Cocoon runs pretty stable *and* in this community there are one or two Cocoon specialists available that could help out ;-) And of course the plan is to have the webapp running on ASF infrastructure. First on brutus.apache.org and I'm sure we get a secure server that is allowed to access our SVN repo, if tests on brutus run well. I'm not so optimistic about a) the chance that automated SVN commit access using role accounts will be granted, and b) whether the technicalities of a secure webapp which is tied to the ASF web of trust (keys, certificates) will get solved properly. That's why I'm steering clear of the ASF infrastructure issue. We can't possible require the ASF to host a specialized documentation system, since Cocoon will want to use Cocoon, some Geronimites are eager of Confluence, old-school folks prefer Anakia, etc etc. I know there's efforts underway to provide people with machine VMs that they can play with at leisure, but the infra folks remain severely understaffed (look at how SVN itself is doing lately), and I'm not sure whether there will ever be willingness to grant access from such an untrusted VM to the trusted SVN repo server. One thing to add: Of course I don't commit myself to provide a 24/7 support. Maybe my attempt will fail, don't know. Maybe somebody else will jump in then, I don't know. Maybe it's the start of a new area in Cocoon documentation, who knows. I think Cocoon needs better documentation, not a new area. ;-) What I fail to understand is your apparent eagerness to get going, yet you want to focus first on rebuilding things which are already readily accessible. IMHO, the documentation issue is only editorial, not technical. The only logistical issue we should address is merging the xdocs with the Wiki. /Steven -- Steven Noelshttp://outerthought.org/ Outerthought - Open Source Java XMLAn Orixo Member Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
Re: [proposal] Cocoon documentation system
Steven Noels wrote: On 18 Jan 2005, at 10:59, Reinhard Poetz wrote: I'm not in the position to change the ASF policy and I don't have the energy to lead all the necessary discussions. Sure. Ditto here. :-) Besides, the ASF policy is sound, if only optimized a wee bit towards source code governance and the risk of trojans being embedded in our products, rather than documentation sites being hacked. I prefer Daisy users to make a positive choice instead (look at all the features I got!) rather than a negative one (only 85% of my requirements are addressed so I'm doomed). Look at how Jira (and in the future perhaps Confluence) quickly won lots of ASF users - even though Jira is a pig to keep running (Daisy isn't). I understand that part of the requirements is to comply with the existing ASF infrastructure. I've had my opportunity to run a non-ASF-infra-resource for two years, and I'm happy that I don't have to check server logs of the Wiki anymore. I do hate the current documentation system and MoinMoin wiki with a passion though, as its split personality is obviously not helping people to produce better documentation. So we definitely need one system, which supports both Wiki-style grassroots authoring, and a proper software documentation CMS. And yes, ASF-compliancy means we should be careful about security if we want to run alongside the code repositories. The only thing I am worried about is that your system will add a third option, and that you'll feel the pain in supporting it as I've felt with the JSPWiki at times. If I choose Daisy or whatever I could feel the same pain. In all my projects I've done so far, Cocoon runs pretty stable *and* in this community there are one or two Cocoon specialists available that could help out ;-) And of course the plan is to have the webapp running on ASF infrastructure. First on brutus.apache.org and I'm sure we get a secure server that is allowed to access our SVN repo, if tests on brutus run well. I'm not so optimistic about a) the chance that automated SVN commit access using role accounts will be granted, and b) whether the technicalities of a secure webapp which is tied to the ASF web of trust (keys, certificates) will get solved properly. That's why I'm steering clear of the ASF infrastructure issue. We can't possible require the ASF to host a specialized documentation system, since Cocoon will want to use Cocoon, some Geronimites are eager of Confluence, old-school folks prefer Anakia, etc etc. I know there's efforts underway to provide people with machine VMs that they can play with at leisure, but the infra folks remain severely understaffed (look at how SVN itself is doing lately), and I'm not sure whether there will ever be willingness to grant access from such an untrusted VM to the trusted SVN repo server. chicken egg situation ... let's see what's going to be happen ... One thing to add: Of course I don't commit myself to provide a 24/7 support. Maybe my attempt will fail, don't know. Maybe somebody else will jump in then, I don't know. Maybe it's the start of a new area in Cocoon documentation, who knows. I think Cocoon needs better documentation, not a new area. ;-) meant era ;-) What I fail to understand is your apparent eagerness to get going, yet you want to focus first on rebuilding things which are already readily accessible. Therefore a concept that works without online CMS. Currently writing xdocs is a pain and the reason why (nearly) nobody is writting docs. Additionally our documentation has to be restructered and partly rewritten because it doesn't reflect how Cocoon 2.1/2.2 can/should be used. IMHO, the documentation issue is only editorial, not technical. The only logistical issue we should address is merging the xdocs with the Wiki. See above, IMHO this is different. -- Reinhard
[OT] svn libraries (Re: [proposal] Cocoon documentation system)
On Sat, Jan 15, 2005 at 02:54:33PM -0500, Stefano Mazzocchi wrote: Torsten Curdt wrote: People, again, let's be brave and get this of this silly pure java nonsense. the JNI connector works. Today! ...maybe for you :-/ ...maybe now We had so many problems with subclipse under linux that we finally went back to the commandline! ...maybe it's worth giving it another try. But a few months ago subclipse with JNI was just a PITA. Of course using JNI will result in more pain than a pure java library and if there was such a thing, I would not hesisate to use that one instead. Pure Java Subversion (SVN) Client Library - http://www.tmate.org/svn/ JIRA uses this for its Subversion support. It has worked pretty well for us so far. Incidentally, JNI libraries cause problems with users, not developers. Some people can barely type 'set JAVA_HOME=... ; cd bin ; startup.bat' - let alone locate and install svn libraries for their particular OS. --Jeff (Cocoon docs? Go Daisy! :) Write an xdoc importer, twist Steven's arm till he promises to maintain it like we do for JIRA, and its beer and skittles from there on!) (Sorry, couldn't resist adding my 2c:)) -- Stefano.
Re: [proposal] Cocoon documentation system
Obviously there probably would be something wrong somewhere if Apache Lenya were used to publish the documentation of Apache Cocoon while the Apache Lenya website is still published using different tools. So, this is first of all a suggestion to Apache Lenya itself: Eat own dogfood: use Lenya to publish Lenya website http://issues.apache.org/bugzilla/show_bug.cgi?id=33147 I have no idea when this happens ... Help is welcome ;-) Cheers, Andreas
Re: [proposal] Cocoon documentation system
Steven Noels wrote: On 18 Jan 2005, at 11:49, Reinhard Poetz wrote: Steven Noels wrote: I'm not so optimistic about a) the chance that automated SVN commit access using role accounts will be granted, and b) whether the technicalities of a secure webapp which is tied to the ASF web of trust (keys, certificates) will get solved properly. That's why I'm steering clear of the ASF infrastructure issue. We can't possible require the ASF to host a specialized documentation system, since Cocoon will want to use Cocoon, some Geronimites are eager of Confluence, old-school folks prefer Anakia, etc etc. I know there's efforts underway to provide people with machine VMs that they can play with at leisure, but the infra folks remain severely understaffed (look at how SVN itself is doing lately), and I'm not sure whether there will ever be willingness to grant access from such an untrusted VM to the trusted SVN repo server. chicken egg situation ... let's see what's going to be happen ... Sure. I don't want to hold you back - I'm just thinking out loudly. I think Cocoon needs better documentation, not a new area. ;-) meant era ;-) Ah - sorry. What I fail to understand is your apparent eagerness to get going, yet you want to focus first on rebuilding things which are already readily accessible. One word to my eagerness ;-) As said in some other mails: The next 6-8 weeks I have time to work on the documentation infrastructure. After this time, I don't know how things will develop ... Therefore a concept that works without online CMS. Currently writing xdocs is a pain and the reason why (nearly) nobody is writting docs. Additionally our documentation has to be restructered and partly rewritten because it doesn't reflect how Cocoon 2.1/2.2 can/should be used. WDYM with no online CMS? I meant online editing (vs. offline editing like we currently do it) The fact that the documentation can be exported statically and hosted on the ASF servers, preferably automated or at least synchronized with releases? Support for static technical documentation and software manuals is exactly what we need to do for the 1.3 release (1.2 is planned somewhere in the first two weeks of februari). IMHO, the documentation issue is only editorial, not technical. The only logistical issue we should address is merging the xdocs with the Wiki. See above, IMHO this is different. I suspect we want to say the same thing: the hard part will be getting people to work on the documentation (i.e. editorial) and provide them with a super-efficient environment to do so. and here we fail badly ATM, and as you suspect this is my main movivation I believe Daisy's editing environment is rather efficient, and that it should be quite feasible to build a custom publishing application (which can be crawled using wget for static renditions) on top of it. Let's see ... -- Reinhard
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: Steven Noels wrote: On 18 Jan 2005, at 10:59, Reinhard Poetz wrote: I'm not in the position to change the ASF policy and I don't have the energy to lead all the necessary discussions. Sure. Ditto here. :-) Besides, the ASF policy is sound, if only optimized a wee bit towards source code governance and the risk of trojans being embedded in our products, rather than documentation sites being hacked. I prefer Daisy users to make a positive choice instead (look at all the features I got!) rather than a negative one (only 85% of my requirements are addressed so I'm doomed). Look at how Jira (and in the future perhaps Confluence) quickly won lots of ASF users - even though Jira is a pig to keep running (Daisy isn't). I understand that part of the requirements is to comply with the existing ASF infrastructure. I've had my opportunity to run a non-ASF-infra-resource for two years, and I'm happy that I don't have to check server logs of the Wiki anymore. I do hate the current documentation system and MoinMoin wiki with a passion though, as its split personality is obviously not helping people to produce better documentation. So we definitely need one system, which supports both Wiki-style grassroots authoring, and a proper software documentation CMS. And yes, ASF-compliancy means we should be careful about security if we want to run alongside the code repositories. The only thing I am worried about is that your system will add a third option, and that you'll feel the pain in supporting it as I've felt with the JSPWiki at times. If I choose Daisy or whatever I could feel the same pain. In all my projects I've done so far, Cocoon runs pretty stable *and* in this community there are one or two Cocoon specialists available that could help out ;-) And of course the plan is to have the webapp running on ASF infrastructure. First on brutus.apache.org and I'm sure we get a secure server that is allowed to access our SVN repo, if tests on brutus run well. I'm not so optimistic about a) the chance that automated SVN commit access using role accounts will be granted, and b) whether the technicalities of a secure webapp which is tied to the ASF web of trust (keys, certificates) will get solved properly. That's why I'm steering clear of the ASF infrastructure issue. We can't possible require the ASF to host a specialized documentation system, since Cocoon will want to use Cocoon, some Geronimites are eager of Confluence, old-school folks prefer Anakia, etc etc. I know there's efforts underway to provide people with machine VMs that they can play with at leisure, but the infra folks remain severely understaffed (look at how SVN itself is doing lately), and I'm not sure whether there will ever be willingness to grant access from such an untrusted VM to the trusted SVN repo server. chicken egg situation ... let's see what's going to be happen ... ... and if there is no other way, I have ideas to perfectly work around the ASF infrastructure without having to forbear from online editing. -- Reinhard
Re: [OT] svn libraries (Re: [proposal] Cocoon documentation system)
We had so many problems with subclipse under linux that we finally went back to the commandline! ...maybe it's worth giving it another try. But a few months ago subclipse with JNI was just a PITA. Of course using JNI will result in more pain than a pure java library and if there was such a thing, I would not hesisate to use that one instead. Pure Java Subversion (SVN) Client Library - http://www.tmate.org/svn/ JIRA uses this for its Subversion support. It has worked pretty well for us so far. Cool ...you can hook it into subclipse! http://www.tmate.org/svn/subclipse.html And also IDEA is using it... Thanks for the pointer, mate! cheers -- Torsten
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: ... ... and if there is no other way, I have ideas to perfectly work around the ASF infrastructure without having to forbear from online editing. IMHO enough bike-shedding on this thread. You know what is available, you know what you want to do. Whatever you do or choose, I'll be very happy :-) -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains) -
Re: [proposal] Cocoon documentation system
On 18 Jan 2005, at 13:20, Reinhard Poetz wrote: ... and if there is no other way, I have ideas to perfectly work around the ASF infrastructure without having to forbear from online editing. Fair enough. I'm really curious though how you're going to handle authentication (other than running the entire app under SSL). Will users for your webapp be maintained separately? Where will username/passwords be stored? (not in the webapp, I presume) Or is your webapp going to use a role account to check information into SVN? (no bikeshedding intended BTW) /Steven -- Steven Noelshttp://outerthought.org/ Outerthought - Open Source Java XMLAn Orixo Member Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
Re: [proposal] Cocoon documentation system
Steven Noels wrote: On 18 Jan 2005, at 13:20, Reinhard Poetz wrote: ... and if there is no other way, I have ideas to perfectly work around the ASF infrastructure without having to forbear from online editing. Fair enough. I'm really curious though how you're going to handle authentication (other than running the entire app under SSL). Will users for your webapp be maintained separately? Where will username/passwords be stored? (not in the webapp, I presume) Or is your webapp going to use a role account to check information into SVN? (no bikeshedding intended BTW) every new/modified doc has to be approved by a committer. My plan is, that this approval is part of the online webapp. If this is not possible, we can run this locally on our machines as well - maybe as sample block of Cocoon. Some webservices query the online application to find out what's new and then the commit comes from the local machine using http://www.tmate.org/svn/. -- Reinhard
Re: [proposal] Cocoon documentation system
every new/modified doc has to be approved by a committer. My plan is, that this approval is part of the online webapp. RT Why not simple moderation via email? Committers could subscribe to a special closed mailing list. The webapp send emails with diffs and a link with a token. If anyone clicks on the link the webapp will commit the change. Well, or you could even count the clicks and require e.g. 3 committers to acknowledge the change ...things like that. Due to the amount of committers we would have still quite a good response time until changes appear live. ...which is important IMHO. /RT Though I doubt the infrastructure folks would like to give a webapp commit privileges. Actually it would also be even nice to pass on the credentials of the clicking/committing committer. So using a ssh to execute a remote command would be another option... The point to success: it must be comfortable - for users and committers. My 2 cents -- Torsten
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: As for french docs, I *strongly* think that we should do this thru content-negotiation rather than URL design. A person accessing the page with a french browser will get the page in french, that's all they have to know Can you rely that each person in France will have french browser? Can you rely that each french speaking Canadian will have french browser? I'm really curious as I've never seen accept-language header used at all (probably because nobody I knew had russian browser). (and the page will have a series of flags that will trigger an overload in locale, but that's going to be a parameter of the URL, not part of it). One thing I noticed is that it's harder to be cache friendly when page content variates depending on session attribute (locale in this case), and /en/ segment makes it trivial to support reverse proxies. How do you propose to solve this without uri segment - by preserving this request parameter, adding it to each link? Or do you see a better way? Vadim
Re: [proposal] Cocoon documentation system
Torsten Curdt wrote: every new/modified doc has to be approved by a committer. My plan is, that this approval is part of the online webapp. RT Why not simple moderation via email? Committers could subscribe to a special closed mailing list. The webapp send emails with diffs and a link with a token. If anyone clicks on the link the webapp will commit the change. Well, or you could even count the clicks and require e.g. 3 committers to acknowledge the change ...things like that. Due to the amount of committers we would have still quite a good response time until changes appear live. ...which is important IMHO. /RT Though I doubt the infrastructure folks would like to give a webapp commit privileges. Actually it would also be even nice to pass on the credentials of the clicking/committing committer. So using a ssh to execute a remote command would be another option... The point to success: it must be comfortable - for users and committers. My 2 cents Thank you. But as you say, it depends if it is allowed that either a webapp or a mail server is allowed to do a commit. If yes, we have many options. If no, having a locally running application that does the actual commit could be a workaround and I think rather comfortable for committers. -- Reinhard
Re: [proposal] Cocoon documentation system
Bertrand Delacretaz wrote: Le 18 janv. 05, à 09:59, Reinhard Poetz a écrit : ...as *I* have to do it, I'll take the road that's the fastest for *me*... +1, whoever does the work gets to decide (and later the community decides to use the stuff or not, but in this case I'm not worried ;-) +1, darwin and do-ocracy do the job a lot better. If I were the one to do it I would start with the requirements and get there with the simplest thing that can possibly work... and work from there. So, go Reinhard! :-) [sylvain, you'd better keep up buddy, or I might change my hero plate ;-)] -- Stefano.
Re: [proposal] Cocoon documentation system
Steven Noels wrote: On 18 Jan 2005, at 10:59, Reinhard Poetz wrote: I'm not in the position to change the ASF policy and I don't have the energy to lead all the necessary discussions. Sure. Ditto here. :-) Besides, the ASF policy is sound, if only optimized a wee bit towards source code governance and the risk of trojans being embedded in our products, rather than documentation sites being hacked. Very true... and cocoon (then forrest, then lenya) were seeded by me with the intention of changing that. 6 years later, still no chance. I think it's time I step down and let somebody else do it because, honeslty, I think I suck at doing that :-) I prefer Daisy users to make a positive choice instead (look at all the features I got!) rather than a negative one (only 85% of my requirements are addressed so I'm doomed). Look at how Jira (and in the future perhaps Confluence) quickly won lots of ASF users - even though Jira is a pig to keep running (Daisy isn't). I understand that part of the requirements is to comply with the existing ASF infrastructure. I've had my opportunity to run a non-ASF-infra-resource for two years, and I'm happy that I don't have to check server logs of the Wiki anymore. I do hate the current documentation system and MoinMoin wiki with a passion though, as its split personality is obviously not helping people to produce better documentation. So we definitely need one system, which supports both Wiki-style grassroots authoring, and a proper software documentation CMS. And yes, ASF-compliancy means we should be careful about security if we want to run alongside the code repositories. The only thing I am worried about is that your system will add a third option, and that you'll feel the pain in supporting it as I've felt with the JSPWiki at times. If I choose Daisy or whatever I could feel the same pain. In all my projects I've done so far, Cocoon runs pretty stable *and* in this community there are one or two Cocoon specialists available that could help out ;-) And of course the plan is to have the webapp running on ASF infrastructure. First on brutus.apache.org and I'm sure we get a secure server that is allowed to access our SVN repo, if tests on brutus run well. I'm not so optimistic about a) the chance that automated SVN commit access using role accounts will be granted, I hear you, but there is a difference now: granular SVN authentication. You can sandbox your documents and you are guaranteed that no trojians will get in your code. This was not possible with CVS... well, it was, but it was a pain to convince them. The problem was to try to convince them before having something running. Since the Gump PMC controls brutus, and brutus is already not considered safe, we can do whatever we want there, including having our own svn repository for docs. But more than anything, we need something working! and b) whether the technicalities of a secure webapp which is tied to the ASF web of trust (keys, certificates) will get solved properly. yeah, don't hold your breath. That's why I'm steering clear of the ASF infrastructure issue. We can't possible require the ASF to host a specialized documentation system, since Cocoon will want to use Cocoon, some Geronimites are eager of Confluence, old-school folks prefer Anakia, etc etc. I know there's efforts underway to provide people with machine VMs that they can play with at leisure, but the infra folks remain severely understaffed (look at how SVN itself is doing lately), and I'm not sure whether there will ever be willingness to grant access from such an untrusted VM to the trusted SVN repo server. the fact is, *we* don't need that. brutus is not super-secure, but it's, IMO, secure enough for content. I mean, if you have an edit this page link on the page itself, people will not see defacing as a problem with the apache web server security... we are long past that which was the entire point. One thing to add: Of course I don't commit myself to provide a 24/7 support. Maybe my attempt will fail, don't know. Maybe somebody else will jump in then, I don't know. Maybe it's the start of a new area in Cocoon documentation, who knows. I think Cocoon needs better documentation, not a new area. ;-) What I fail to understand is your apparent eagerness to get going, yet you want to focus first on rebuilding things which are already readily accessible. IMHO, the documentation issue is only editorial, not technical. I agree and disagree at the same time. There would be no wikipedia if it wasn't easy to use and we would have better docs and less wiki pages, if it was easier to edit the docs directly. The only logistical issue we should address is merging the xdocs with the Wiki. The day our documentation infrastructure is successful is the day the cocoon wiki gets zero activity. -- Stefano.
Re: [OT] svn libraries (Re: [proposal] Cocoon documentation system)
Torsten Curdt wrote: We had so many problems with subclipse under linux that we finally went back to the commandline! ...maybe it's worth giving it another try. But a few months ago subclipse with JNI was just a PITA. Of course using JNI will result in more pain than a pure java library and if there was such a thing, I would not hesisate to use that one instead. Pure Java Subversion (SVN) Client Library - http://www.tmate.org/svn/ JIRA uses this for its Subversion support. It has worked pretty well for us so far. Cool ...you can hook it into subclipse! http://www.tmate.org/svn/subclipse.html And also IDEA is using it... Thanks for the pointer, mate! AWESOME!!! -- Stefano... going to play with it!!!
Re: [proposal] Cocoon documentation system
Nicola Ken Barozzi wrote: Reinhard Poetz wrote: ... ... and if there is no other way, I have ideas to perfectly work around the ASF infrastructure without having to forbear from online editing. IMHO enough bike-shedding on this thread. You know what is available, you know what you want to do. Whatever you do or choose, I'll be very happy :-) Amen :-) -- Stefano.
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: Thank you. But as you say, it depends if it is allowed that either a webapp or a mail server is allowed to do a commit. If yes, we have many options. With the current situation, that is a no. Evidently there are solutions on the way. Spurts of discussion happen on [EMAIL PROTECTED] (like right now). In the meantime, we can get the demo on brutus happening. If no, having a locally running application that does the actual commit could be a workaround and I think rather comfortable for committers. Not sure what you mean. How can other people make changes? --David
Re: [proposal] Cocoon documentation system
David Crossley wrote: Reinhard Poetz wrote: Thank you. But as you say, it depends if it is allowed that either a webapp or a mail server is allowed to do a commit. If yes, we have many options. With the current situation, that is a no. Evidently there are solutions on the way. Spurts of discussion happen on [EMAIL PROTECTED] (like right now). In the meantime, we can get the demo on brutus happening. If no, having a locally running application that does the actual commit could be a workaround and I think rather comfortable for committers. Not sure what you mean. How can other people make changes? Doc authors do their changes via a web application. Only the approval process is done via a local running application, that also is responsible for the commit. But as being said, let's see what will happen, when we have a working solution that only needs to find a secure home. -- Reinhard
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: David Crossley wrote: Reinhard Poetz wrote: Yep. I hope that I can convince at least one of them to help me. Actually I need some Java code ;-) So here I ask officially: Who volunteers to write the Java code that communicates with the SVN repository (read and commit)? Dunno. At forrest-dev, Dave Brondsema used jsvn for the forrestbot. - enable the publishing process (forrestbot or cron) Unfortunatly I don't have any experience with setting up this publishing process. David, do you know who I can ping to get help here? See below. Both. At forrest-dev we are also starting to set up a demo of the new forrestbot and its webapp interface. So yes, we will be able to help on some aspects. The Proposal for ASF-wide documentation staging and publishing intends to enable various document management systems to feed into staging areas. I will add a para to the wiki page. Can you give me a pointer to this document? http://forrest.apache.org/proposal-asf-publish.html not restricted to forrest tools. And i am setting up a demo on brutus as we speak. More about that soon. --David
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system. I am *strongly* in favor of plain html as a source, as Forrest renders it nicely; the Incubator website is now all using html as a source format. Also, I don't see the need for a separate metadata file, which would duplicate stuff that is in SVN and in the source file. Comment file handling can be added as a Forrest plugin; I prefer it separate because in fact it *is* separate. Maybe putting the comments in a doc.comments directory, with each a separate html file would be nice. I added my comments to the Wiki BTW. -- Nicola Ken Barozzi [EMAIL PROTECTED] - verba volant, scripta manent - (discussions get forgotten, just code remains) -
Re: [proposal] Cocoon documentation system
Nicola Ken Barozzi wrote: Reinhard Poetz wrote: At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system. I am *strongly* in favor of plain html I know :-) as a source, as Forrest renders it nicely; the Incubator website is now all using html as a source format. After some thinking I propose supporting both formats. I think the HTML format is not necessary after the web appolication has gone online, but until we reach this point, HTML is very useful. (We can make Forrest fail, if there is the content in both formats available.) Also, I don't see the need for a separate metadata file, which would duplicate stuff that is in SVN and in the source file. It's not only about author and date. It's also about status, target audience and keywords. I'm in favor of having this information explicit marked up in useful XML. This simplifies the publishing process (guarantee a consistent layout) and in the future queryable. Comment file handling can be added as a Forrest plugin; I prefer it separate because in fact it *is* separate. Maybe putting the comments in a doc.comments directory, with each a separate html file would be nice. In my sample repository I used a custom sitemap which does the aggreagation. Pretty simple. See http://svn.apache.org/repos/asf/cocoon/whiteboard/doc-repos/2.2/src/documentation/sitemap.xmap I added my comments to the Wiki BTW. Thanks. Find my answers in the Wiki too. -- Reinhard
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: Sylvain Wallez wrote: snip/ One normaly solution is to have an english title even for non-english pages. I dislike that, it's very anglo-centric. Well, consider the state of Cocoon, the ASF, the opensource world and the whole IT industry: they're all anglo-centric. Would you have the same concerns if this was esperanto or interlingua rather than english (or more precisely international english)? Furthermore, translations must follow the original reference docs, which is the english one. So having all language-specific resources use the same name as their english counterpart isn't a problem to me. fair enough and coming from a french is rather something ;-) Hehe ;-) But maybe I'm not the usual stererotypic french guy, which is often considered arrogant and egocentric. Also, if you look around you won't see many french people working on projects using a BSD-style license whereas there are plenty of them on GPL projects. I had some thoughts about this, and IMO an explanation can be found in the french culture which is more about freedom in its libertarian or anarchistic meaning than sharing with others. But that's off-topic... snip/ Yeah, but Amazon is a large catalogue of things, not a documentation covering lots of different subjects from introduction to details. True enough. But hypermedia allows a page to reside in more than one trail of reading, while a hierarchical navigation imposes a TOC-like view, which might satisfy (and feel natural to one user) but look ugly and totally unfamiliar to others. I think it's the cataloguing part that makes writing documentation so hard and that's why things like wikipedia are taking off so much instead. I personally think that the problem with documentation is that there are two concerns: - writers - assemblers blogs, email, wikis, all share a common paradigm: you don't need to 'assemble' your thoughts, you just dump them. Other people do the assembly. If you wish, this is the beauty of microcontent: massive parallelization (and the reason why the web bloomed, because it removed the editing/cataloging bottleneck. but the problem was that searching for stuff used to be a nightmare (see early days of altavista). This mare magnum of content with no apparent structure made people get lost very easily. This is the same feeling you have in a wiki. You have a trail of the pages that you have visited, but that's useless (you have it in your browser too!), you want to be able to browse the content, go from this content to something that is relevant to you. In a book, this relevance was done by the author (or the editors) and was placed in sequential order. Or, if not, clustered in chapters or sections. What a wiki misses (even the good ones like Confluence) is such clustering notion... something that is easy to achieve with more structured system, like forrest by mean of tabs or trees of links. The problem with this approach is that there is only one way of clustering: repurposing pages becomes hell (and that's why there are so many broken links.. because the clustering evolves not only with the content of the page, but with the surroundings). By separating the contept of writers and assemblers, not only you unleash a tremendous effort in content production (as our wiki showed)... but you allow this content to be clusterized and, hear hear, *in parallel*! Conditio sine qua non of the above is a flat URL space. Numeric? no, not necessarely, but flat for sure. I agree with this. Actually (and IIRC we already discussed this), it would be interesting for a document to exist a different URLs: the main and persistent one (flat space), and other ones corresponding to different trails or navigational trees. We could then show in each page the permalink for the page (in the flat space) and the various cross-cutting trails in which the page appears. That way, you can navigate in the web of references from the original trail that led you to that page to other trails mentioning that same page. Actually, since geeks are used to hack into URLs but normal people do not, having a flat or bad URL space forces usability people to think about navigation in the page and not outside. How much I dislike such sites that require me to go from the main page to go down to a particular page that I've already seen... Sure, but that's a usability problem of the site, not of the URL space per se. Right. snip/ The language a page is written, just like the data-type of the page, should not belong in the URL. This makes the URL space way more solid overtime: I can link to http://cocoon.apache.org/2.2/3984948 and *be sure* that it will be there a few years from now and, by then, maybe a translation in my native language would have poped up! And why shouldn't e.g. http://cocoon.apache.org/2.1/userdocs/flow/continuations.html not be there? example: because somebody decided to split the user section by
Re: [proposal] Cocoon documentation system
Sylvain Wallez wrote: Stefano Mazzocchi wrote: Sylvain Wallez wrote: snip/ One normaly solution is to have an english title even for non-english pages. I dislike that, it's very anglo-centric. Well, consider the state of Cocoon, the ASF, the opensource world and the whole IT industry: they're all anglo-centric. Would you have the same concerns if this was esperanto or interlingua rather than english (or more precisely international english)? Furthermore, translations must follow the original reference docs, which is the english one. So having all language-specific resources use the same name as their english counterpart isn't a problem to me. fair enough and coming from a french is rather something ;-) Hehe ;-) Isn't it france that has an institute that tries to find frech translations for everything that comes from other languages (e.g. ordinateur) ;-) But maybe I'm not the usual stererotypic french guy, which is often considered arrogant and egocentric. Also, if you look around you won't see many french people working on projects using a BSD-style license whereas there are plenty of them on GPL projects. I had some thoughts about this, and IMO an explanation can be found in the french culture which is more about freedom in its libertarian or anarchistic meaning than sharing with others. But that's off-topic... snip/ Yeah, but Amazon is a large catalogue of things, not a documentation covering lots of different subjects from introduction to details. True enough. But hypermedia allows a page to reside in more than one trail of reading, while a hierarchical navigation imposes a TOC-like view, which might satisfy (and feel natural to one user) but look ugly and totally unfamiliar to others. I think it's the cataloguing part that makes writing documentation so hard and that's why things like wikipedia are taking off so much instead. I personally think that the problem with documentation is that there are two concerns: - writers - assemblers blogs, email, wikis, all share a common paradigm: you don't need to 'assemble' your thoughts, you just dump them. Other people do the assembly. If you wish, this is the beauty of microcontent: massive parallelization (and the reason why the web bloomed, because it removed the editing/cataloging bottleneck. but the problem was that searching for stuff used to be a nightmare (see early days of altavista). This mare magnum of content with no apparent structure made people get lost very easily. This is the same feeling you have in a wiki. You have a trail of the pages that you have visited, but that's useless (you have it in your browser too!), you want to be able to browse the content, go from this content to something that is relevant to you. In a book, this relevance was done by the author (or the editors) and was placed in sequential order. Or, if not, clustered in chapters or sections. What a wiki misses (even the good ones like Confluence) is such clustering notion... something that is easy to achieve with more structured system, like forrest by mean of tabs or trees of links. The problem with this approach is that there is only one way of clustering: repurposing pages becomes hell (and that's why there are so many broken links.. because the clustering evolves not only with the content of the page, but with the surroundings). By separating the contept of writers and assemblers, not only you unleash a tremendous effort in content production (as our wiki showed)... but you allow this content to be clusterized and, hear hear, *in parallel*! Conditio sine qua non of the above is a flat URL space. Numeric? no, not necessarely, but flat for sure. I'm sure that putting resources into a hierarchy and make these hierarchy public is harmful. About the numbers, I would try it but if so many people are against them because of some, I admit, good reasons, well ... My argument is still that in the long run, problems will pop up - as always when you use speaking keys. I agree with this. Actually (and IIRC we already discussed this), it would be interesting for a document to exist a different URLs: the main and persistent one (flat space), and other ones corresponding to different trails or navigational trees. We could then show in each page the permalink for the page (in the flat space) and the various cross-cutting trails in which the page appears. That way, you can navigate in the web of references from the original trail that led you to that page to other trails mentioning that same page. Look at http://apache.org/~reinhard/cocoon/2.2/1.html. The navigational structure is hierarchically organzied but not the files (only 1.html, 2.html and 17.html are working). I don't see the value of having the hierarchies in the URL. Actually, since geeks are used to hack into URLs but normal people do not, having a flat or bad URL space forces usability people to think about navigation in the page and not outside. How
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: Sun did this with the Java API did this and created a mess, people linked to java/1.4.2/ and then 1.4.3 was created and all links broke down. If a document shipped in 2.1.3 has a bug and was fixed in 2.1.4, why would anybody want to see it? and if 2.1.4 removed something useful for 2.1.3, that's a bug and we should fix it in the doc, rather than make everything available on the web. So I'm -1 on this. Makes sense, especially that all links to our docs may become out of date if the person linking to us doesn't use the dynamic version. The reason for publishing docs of patch versions is, that not everybody uses the latest Cocoon version. I know a company that uses 2.1.5 and every now and then I came across the problem that I'm not sure if a feature is already available. But maybe notes within the document are good enough here. And when setting up a new repository for a new minor Cocoon version all notes _can_ be skipped. As for french docs, I *strongly* think that we should do this thru content-negotiation rather than URL design. A person accessing the page with a french browser will get the page in french, that's all they have to know (and the page will have a series of flags that will trigger an overload in locale, but that's going to be a parameter of the URL, not part of it). The language a page is written, just like the data-type of the page, should not belong in the URL. This makes the URL space way more solid overtime: I can link to http://cocoon.apache.org/2.2/3984948 and *be sure* that it will be there a few years from now and, by then, maybe a translation in my native language would have poped up! let's be brave! :-) For my new website (hopefully it goes online very soon ;-) ) I provide the most docs in German and in English. The URL is the same and as you describe, based on the browsers language either the one or the other content is displayed. Additionally the user has the possibility to switch. Then I thought how e.g. Google can index both languages? It can follow the switching link but then it doesn't know that it should follow all links again. The result was the introdution of another transformer step in my pipeline that appends l=en or l=de (depending of the current language) to all links that makes all links unique and indexable. I think something similar can work for the published Cocoon docs maybe using some mod_rewrite tricks but it may become difficult when providing static docs. This probably needs some Forrest tweaks for generating the downloadable docs. -- Reinhard
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: Look at http://apache.org/~reinhard/cocoon/2.2/1.html. The navigational structure is hierarchically organzied but not the files (only 1.html, 2.html and 17.html are working). I don't see the value of having the hierarchies in the URL. no, but I somehow agree with Sylvain that it looks somewhat, hmmm, wiki-like to have those numbers... for example, Daisy does this and my understanding is that that people complained about. Steven, can you give us some feedback on how things went over at Daisy with the flat numeric URL space? Yes, another reason for numbers so that we do not end in docs like http://cocoon.apache.org/2.2/flowscript http://cocoon.apache.org/2.2/flowscriptInJava http://cocoon.apache.org/2.2/flowWithJavascript http://cocoon.apache.org/2.2/flowscript-api http://cocoon.apache.org/2.2/flowscript-overview http://cocoon.apache.org/2.2/flowscriptIntrocution http://cocoon.apache.org/2.2/flowscriptIntrocution typos in the URLs! that's a good one :-) I know that's the job of us committers who approve new docs and can find better names, but over the time (thinking in years) I fear that we end in a mess because it will not be very easy to keep oversight. well, ok, I use numeric URLs for my linotype URL space and I have to tell you that I'm not dissatisfied. First of all, they tend to be smaller, therefore easier for people to send into emails. Second, they have a sort of neutrality and makes people curious. For example, take a look at http://www.betaversion.org/~stefano/linotype/news/57/ [note that I think that news/57 is wrong, should be 57 and I'm working on migrating all my content to a new URL scheme!] The other problem is that people tend to think that http://www.betaversion.org/~stefano/linotype/news/57/ and http://www.betaversion.org/~stefano/linotype/news/57 are the same URL because most web servers do that translation automatically (which is *WRONG*, but you can't undo history)... as a result, I have to perform permanent redirects explicitly to avoid silly 404. If I used a title-based URL, the above would be http://www.betaversion.org/~stefano/linotype/news/A_No-Nonsense_Guide_to _Semantic_Web_Specs_for_XML_People_%5BPart_I%5B which not only would be long and hard for people to read, but it would also be really ugly with those %xx escaped entities But on the other hand, the URL identifier and the document title don't need to be exactly the same, so I could create a new field that says URL title and I would have had something like http://www.betaversion.org/~stefano/linotype/news/Semantic_Web_Guide_Part_1 which is more reasonable. this is, in fact, similar to how wikipedia does it and they have half a million pages and growing exponentially. There is something interesting to say about wikis: the fact that the notion of links is so embedded and the URL space so flat, makes it easy to get collisions. if you wish, a wiki URL space is not different from a folksonomy's tag, where you get collisions that sometimes could be bad, but most of the time are userful. Case in point http://en.wikipedia.org/wiki/Cocoon This is a disambiguation page a navigational aid which lists other pages that might otherwise share the same title. If an article link referred you here, you might want to go back and fix it to point directly to the intended page. Lovely. There is a lot to learn from Wikipedia... but one thing that they are missing: trails paths that guide the user to a given set of pages to learn a particular topic (see the java tutorial for a fine example of such a style... java's success is, I believe, partially due to that!) We could even use Wikipedia directly as our documentation infrastructure and forget about our own! http://en.wikipedia.org/wiki/Apache_Cocoon Anyway, the more I think of it, the more I think it makes sense to follow the URL model of Wikipedia. -- Stefano.
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: Stefano Mazzocchi wrote: Sun did this with the Java API did this and created a mess, people linked to java/1.4.2/ and then 1.4.3 was created and all links broke down. If a document shipped in 2.1.3 has a bug and was fixed in 2.1.4, why would anybody want to see it? and if 2.1.4 removed something useful for 2.1.3, that's a bug and we should fix it in the doc, rather than make everything available on the web. So I'm -1 on this. Makes sense, especially that all links to our docs may become out of date if the person linking to us doesn't use the dynamic version. The reason for publishing docs of patch versions is, that not everybody uses the latest Cocoon version. I know a company that uses 2.1.5 and every now and then I came across the problem that I'm not sure if a feature is already available. But maybe notes within the document are good enough here. And when setting up a new repository for a new minor Cocoon version all notes _can_ be skipped. cool. As for french docs, I *strongly* think that we should do this thru content-negotiation rather than URL design. A person accessing the page with a french browser will get the page in french, that's all they have to know (and the page will have a series of flags that will trigger an overload in locale, but that's going to be a parameter of the URL, not part of it). The language a page is written, just like the data-type of the page, should not belong in the URL. This makes the URL space way more solid overtime: I can link to http://cocoon.apache.org/2.2/3984948 and *be sure* that it will be there a few years from now and, by then, maybe a translation in my native language would have poped up! let's be brave! :-) For my new website (hopefully it goes online very soon ;-) ) I provide the most docs in German and in English. The URL is the same and as you describe, based on the browsers language either the one or the other content is displayed. Additionally the user has the possibility to switch. Right, having a list of small flags in the page somewhere is a must... it gives the user the ability to know how many translations of that page exist... and, also, provide a *stub* for others to start attacking the problem. Then I thought how e.g. Google can index both languages? following those links above :-) It can follow the switching link but then it doesn't know that it should follow all links again. The result was the introdution of another transformer step in my pipeline that appends l=en or l=de (depending of the current language) to all links that makes all links unique and indexable. yep, correct. the parameter overloads the facility. also easy to implement with request parameter matching ;-) I think something similar can work for the published Cocoon docs maybe using some mod_rewrite tricks but it may become difficult when providing static docs. This probably needs some Forrest tweaks for generating the downloadable docs. tell you what. forget about it for now. Think about going dynamic and later we'll find a way to make a persistent copy of that (either via forrest or simply by wget or something) -- Stefano.
Re: [proposal] Cocoon documentation system
On 17 Jan 2005, at 20:36, Stefano Mazzocchi wrote: Reinhard Poetz wrote: Look at http://apache.org/~reinhard/cocoon/2.2/1.html. The navigational structure is hierarchically organzied but not the files (only 1.html, 2.html and 17.html are working). I don't see the value of having the hierarchies in the URL. no, but I somehow agree with Sylvain that it looks somewhat, hmmm, wiki-like to have those numbers... for example, Daisy does this and my understanding is that that people complained about. Steven, can you give us some feedback on how things went over at Daisy with the flat numeric URL space? Well, we have a two-headed approach ATM, since we support both types of URIs. Numeric IDs are managed by the repository, while the pretty URIs are managed by the navigation tree (i.e. by the user/editor). I must honestly say that the remarks I found in this thread remind me a lot about the decisions we made for Daisy. We are using a different storage layer, but other than that I think we address a lot of the listed requirements. /Steven -- Steven Noelshttp://outerthought.org/ Outerthought - Open Source Java XMLAn Orixo Member Read my weblog athttp://blogs.cocoondev.org/stevenn/ stevenn at outerthought.orgstevenn at apache.org
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: Reinhard Poetz wrote: Stefano Mazzocchi wrote: Sun did this with the Java API did this and created a mess, people linked to java/1.4.2/ and then 1.4.3 was created and all links broke down. If a document shipped in 2.1.3 has a bug and was fixed in 2.1.4, why would anybody want to see it? and if 2.1.4 removed something useful for 2.1.3, that's a bug and we should fix it in the doc, rather than make everything available on the web. So I'm -1 on this. Makes sense, especially that all links to our docs may become out of date if the person linking to us doesn't use the dynamic version. The reason for publishing docs of patch versions is, that not everybody uses the latest Cocoon version. I know a company that uses 2.1.5 and every now and then I came across the problem that I'm not sure if a feature is already available. But maybe notes within the document are good enough here. And when setting up a new repository for a new minor Cocoon version all notes _can_ be skipped. cool. ok. I will adapt my proposal As for french docs, I *strongly* think that we should do this thru content-negotiation rather than URL design. A person accessing the page with a french browser will get the page in french, that's all they have to know (and the page will have a series of flags that will trigger an overload in locale, but that's going to be a parameter of the URL, not part of it). The language a page is written, just like the data-type of the page, should not belong in the URL. This makes the URL space way more solid overtime: I can link to http://cocoon.apache.org/2.2/3984948 and *be sure* that it will be there a few years from now and, by then, maybe a translation in my native language would have poped up! let's be brave! :-) For my new website (hopefully it goes online very soon ;-) ) I provide the most docs in German and in English. The URL is the same and as you describe, based on the browsers language either the one or the other content is displayed. Additionally the user has the possibility to switch. Right, having a list of small flags in the page somewhere is a must... it gives the user the ability to know how many translations of that page exist... and, also, provide a *stub* for others to start attacking the problem. Then I thought how e.g. Google can index both languages? following those links above :-) ... what shall I say ... sometimes the solution is s close and I don't see it ;-) It can follow the switching link but then it doesn't know that it should follow all links again. The result was the introdution of another transformer step in my pipeline that appends l=en or l=de (depending of the current language) to all links that makes all links unique and indexable. yep, correct. the parameter overloads the facility. also easy to implement with request parameter matching ;-) I think something similar can work for the published Cocoon docs maybe using some mod_rewrite tricks but it may become difficult when providing static docs. This probably needs some Forrest tweaks for generating the downloadable docs. tell you what. forget about it for now. Think about going dynamic and later we'll find a way to make a persistent copy of that (either via forrest or simply by wget or something) point taken :-) here my next steps: - adapt the proposal so that it reflects the results of the discussion - same for the two demo repositories - implement the web application -- Reinhard
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: Reinhard Poetz wrote: snip/ Anyway, the more I think of it, the more I think it makes sense to follow the URL model of Wikipedia. That's probably the best solution. I will restructure the sample repositories following the wikipedia URL model. -- Reinhard
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote:
snip/
My first goal is reusing existing functionality (SVN, Forrest,
static web pages). Writing the missing pieces (a small web
application to edit docs online) shouldn't be too difficult -
especially using CocoonForms (HTMLArea with HTMLCleaning convertor
are shining here!) and Flowscript.
At the end of the document you find a roadmap. It also contains some
parts where I *really* need some help by others:
- component (Java) that reads from and commits to SVN - should work
over
WebDAV, shouldn't it?
I know there are some specialist in this community who could help out
here (Unico, Gianugo, Guido)
We have a huge team of specialists on the dev list.
Yep. I hope that I can convince at least one of them to help me.
Actually I need some Java code ;-) So here I ask officially: Who
volunteers to write the Java code that communicates with the SVN
repository (read and commit)?
Dumb question: can't we use webdav over https?
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: Reinhard Poetz wrote: snip/ good point. I also want that every comment (not only doc changes) has to be approved by a committer. So we have a double-barrier (hope that's understandable English) for spamming bots. Ok, captchas + human moderation is clearly too high of a barrier for spammers and even for defacers. Even infra@ would not have a problem with that. There's an interesting chapter on circumventing captchas at wikipedia [1]. Are we interesting enough in terms of google ranking to attract such things? Two question to Stefano (and everybody else): I proposed numbers as document IDs? What do you think about this? I used to be a fanatic of 'readable URL'... but I think they present more problems than they solve. First of all, the encoding is a pain. It's fine for english, but until we ave IRI (internationalized resource identifiers, think unicode meets URI) support forget chinese, japanese, cyrillic, hebrew, korean and so on. One normaly solution is to have an english title even for non-english pages. I dislike that, it's very anglo-centric. Well, consider the state of Cocoon, the ASF, the opensource world and the whole IT industry: they're all anglo-centric. Would you have the same concerns if this was esperanto or interlingua rather than english (or more precisely international english)? Furthermore, translations must follow the original reference docs, which is the english one. So having all language-specific resources use the same name as their english counterpart isn't a problem to me. Second, people like Nielsen argue that readable URLs are easier to use and to remember. I think it's bullshit. Not even my bookmarks satisfy me anymore in terms of link management (del.icio.us + google killed my browser bookmarks), do you really think I would type in or remember any URL today? nonsense. I do remember a lot of URLs, provided of course that they are meaningful. And I have a very powerful tool to help me crawling in this tree of URLs that I know: the Firefox address bar autocompletion (which BTW just a reuse of the unix command-line behaviour). And the more you use a URL, the more it engraves into your mind. Nothing new in the cognition area here, but that means that a lot of regular users of Cocoon know the URLs space of its documentation by heart, or at least the main directory names. There are a few values of a readable URL. The first is actionable breadcrumbs. Breadcrumbs should better be generated from the navigational structure rather than the page path, even if both often match. So, if you find yourself in http://site.com/a/b/c/d/e/f/g you can automatically infer something like site.com a b c d e f g and, for shitty web sites, that is a *tremendous* navigation help. For URLs like http://site.com/page/39884984 that's it, there is no hierarchical context that you can infer from it. Now, we will not have a shitty web site, so this argument doesn't apply and Amazon (which is the most used e-commerce site in the world *and* has the worst URL space ever imagined!) shows that URL-space design does not impact usability, if the pages don't require so. Yeah, but Amazon is a large catalogue of things, not a documentation covering lots of different subjects from introduction to details. Actually, since geeks are used to hack into URLs but normal people do not, having a flat or bad URL space forces usability people to think about navigation in the page and not outside. How much I dislike such sites that require me to go from the main page to go down to a particular page that I've already seen... Another argument, and probably more important, is that a flat URL structure gives a sense of 'wikiness' that people have come to dislike. Now, again, this is a false impression (inspired by a plethora of bad practices rather than effectual technological limitations) but a strong one nevertheless (I do feel the same about it at times). But *exactly* because of that, I think we should be brave and show the world that a flat URL space *does not* automatically yield 'wiki-like' flat spaces that are extremely painful to navigate. Flat numeric URL spaces have also extremely interesting advantages: - pages can have their titles adjusted without impacting persistance (links are more solid over time) Adjusting a title doesn't mean you change its content, in which case there's no need to change its name. And if it's content changes, then it's a different page with a different name. - pages can be rearranged/repurposed/re-aggregated/re-used without impacting persistance Agree for rearranged as a flat space allows to change the navigation tree without impacting path names. Now repurposing a page requires to change its name (or id) and re-aggregating means removing (aggregation) or adding (split) some pages. Another question is the structure of URLs - the new efforts of Sylvain who wants to provide some docs in
Re: [proposal] Cocoon documentation system
Sylvain Wallez wrote: Well, consider the state of Cocoon, the ASF, the opensource world and the whole IT industry: they're all anglo-centric. Would you have the same concerns if this was esperanto or interlingua rather than english (or more precisely international english)? Furthermore, translations must follow the original reference docs, which is the english one. So having all language-specific resources use the same name as their english counterpart isn't a problem to me. Frankly, I'm not sure why we are even discussing I18n. It is one of those previously-solved problems that doesn't need a new solution. Heck, just use Cocoon :-) Seriously, Stefano's point here is right on the mark, in my opinion. There should only be one URL space. The locale is simply an attribute of how you access that URL space, not an inherent part of it. Second, people like Nielsen argue that readable URLs are easier to use and to remember. I think it's bullshit. Not even my bookmarks satisfy me anymore in terms of link management (del.icio.us + google killed my browser bookmarks), do you really think I would type in or remember any URL today? nonsense. I do remember a lot of URLs, provided of course that they are meaningful. And I have a very powerful tool to help me crawling in this tree of URLs that I know: the Firefox address bar autocompletion (which BTW just a reuse of the unix command-line behaviour). And the more you use a URL, the more it engraves into your mind. Nothing new in the cognition area here, but that means that a lot of regular users of Cocoon know the URLs space of its documentation by heart, or at least the main directory names. I can't even remember the URL of the Cocoon wiki and I go there a lot. That's because I alway just go to cocoon.apache.org/2.1 and click on the link. Any URL's beyond the main page are worthless to me. Wait, wait! I haven't proposed to translate the docs!! This is a tremendous and effort! I proposed to just translate the introductory page to accompany the french-speaking mailing-list. I'm not really sure what the value in that is, but whatever. Ralph
Re: [proposal] Cocoon documentation system
Sylvain Wallez wrote: Ok, captchas + human moderation is clearly too high of a barrier for spammers and even for defacers. Even infra@ would not have a problem with that. There's an interesting chapter on circumventing captchas at wikipedia [1]. Are we interesting enough in terms of google ranking to attract such things? Yeah! Apache is probably in top 1000 web sites in google. I think we are definately a target! Captchas are not impossible to break, of cource, but they are *hard enough* and provide a first filtering barrier. A second filtering barrier could be heuristical analysis of the comment. But distributed human moderation is clearly a barrier that no spammer will be able to pass, unless the load becomes dramatic and at that point, blacklisting is the way to go. Two question to Stefano (and everybody else): I proposed numbers as document IDs? What do you think about this? I used to be a fanatic of 'readable URL'... but I think they present more problems than they solve. First of all, the encoding is a pain. It's fine for english, but until we ave IRI (internationalized resource identifiers, think unicode meets URI) support forget chinese, japanese, cyrillic, hebrew, korean and so on. One normaly solution is to have an english title even for non-english pages. I dislike that, it's very anglo-centric. Well, consider the state of Cocoon, the ASF, the opensource world and the whole IT industry: they're all anglo-centric. Would you have the same concerns if this was esperanto or interlingua rather than english (or more precisely international english)? Furthermore, translations must follow the original reference docs, which is the english one. So having all language-specific resources use the same name as their english counterpart isn't a problem to me. fair enough and coming from a french is rather something ;-) Second, people like Nielsen argue that readable URLs are easier to use and to remember. I think it's bullshit. Not even my bookmarks satisfy me anymore in terms of link management (del.icio.us + google killed my browser bookmarks), do you really think I would type in or remember any URL today? nonsense. I do remember a lot of URLs, provided of course that they are meaningful. And I have a very powerful tool to help me crawling in this tree of URLs that I know: the Firefox address bar autocompletion (which BTW just a reuse of the unix command-line behaviour). And the more you use a URL, the more it engraves into your mind. Nothing new in the cognition area here, but that means that a lot of regular users of Cocoon know the URLs space of its documentation by heart, or at least the main directory names. here we are different. I use google even to get to the cocoon web page because typing cocoon and return is easier than http://cocoon.apache.org/ cocoon ... actually, I do [ctrl-space] co now that I have my bookmarks (both local and delicious) managed by Quicksilver. Readability of URL is just not much for me. There are a few values of a readable URL. The first is actionable breadcrumbs. Breadcrumbs should better be generated from the navigational structure rather than the page path, even if both often match. I agree here completely. So, if you find yourself in http://site.com/a/b/c/d/e/f/g you can automatically infer something like site.com a b c d e f g and, for shitty web sites, that is a *tremendous* navigation help. For URLs like http://site.com/page/39884984 that's it, there is no hierarchical context that you can infer from it. Now, we will not have a shitty web site, so this argument doesn't apply and Amazon (which is the most used e-commerce site in the world *and* has the worst URL space ever imagined!) shows that URL-space design does not impact usability, if the pages don't require so. Yeah, but Amazon is a large catalogue of things, not a documentation covering lots of different subjects from introduction to details. True enough. But hypermedia allows a page to reside in more than one trail of reading, while a hierarchical navigation imposes a TOC-like view, which might satisfy (and feel natural to one user) but look ugly and totally unfamiliar to others. I think it's the cataloguing part that makes writing documentation so hard and that's why things like wikipedia are taking off so much instead. I personally think that the problem with documentation is that there are two concerns: - writers - assemblers blogs, email, wikis, all share a common paradigm: you don't need to 'assemble' your thoughts, you just dump them. Other people do the assembly. If you wish, this is the beauty of microcontent: massive parallelization (and the reason why the web bloomed, because it removed the editing/cataloging bottleneck. but the problem was that searching for stuff used to be a nightmare (see early days of altavista). This mare magnum of content with no apparent structure made people get lost very easily. This is the same
Re: [proposal] Cocoon documentation system
Sylvain Wallez wrote: Reinhard Poetz wrote: snip/ My first goal is reusing existing functionality (SVN, Forrest, static web pages). Writing the missing pieces (a small web application to edit docs online) shouldn't be too difficult - especially using CocoonForms (HTMLArea with HTMLCleaning convertor are shining here!) and Flowscript. At the end of the document you find a roadmap. It also contains some parts where I *really* need some help by others: - component (Java) that reads from and commits to SVN - should work over WebDAV, shouldn't it? I know there are some specialist in this community who could help out here (Unico, Gianugo, Guido) We have a huge team of specialists on the dev list. Yep. I hope that I can convince at least one of them to help me. Actually I need some Java code ;-) So here I ask officially: Who volunteers to write the Java code that communicates with the SVN repository (read and commit)? Dumb question: can't we use webdav over https? This was my first thought too (see http://svnbook.red-bean.com/en/1.0/apc.html) and the reason why I directly addressed my request for help to three Cocoon committers that have WebDAV experiences (at least I know that they have). -- Reinhard
Re: [proposal] Cocoon documentation system
David Crossley wrote: Reinhard Poetz wrote: At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system. Thanks, a brilliant step. My first goal is reusing existing functionality (SVN, Forrest, static web pages). Writing the missing pieces (a small web application to edit docs online) shouldn't be too difficult - especially using CocoonForms (HTMLArea with HTMLCleaning convertor are shining here!) and Flowscript. At the end of the document you find a roadmap. It also contains some parts where I *really* need some help by others: - component (Java) that reads from and commits to SVN - should work over WebDAV, shouldn't it? I know there are some specialist in this community who could help out here (Unico, Gianugo, Guido) We have a huge team of specialists on the dev list. Yep. I hope that I can convince at least one of them to help me. Actually I need some Java code ;-) So here I ask officially: Who volunteers to write the Java code that communicates with the SVN repository (read and commit)? - enable the publishing process (forrestbot or cron) Unfortunatly I don't have any experience with setting up this publishing process. David, do you know who I can ping to get help here? Both. At forrest-dev we are also starting to set up a demo of the new forrestbot and its webapp interface. So yes, we will be able to help on some aspects. The Proposal for ASF-wide documentation staging and publishing intends to enable various document management systems to feed into staging areas. I will add a para to the wiki page. Can you give me a pointer to this document? - SSL setup I don't think that a technical solution will directly lead to better docs. I just think that making the doc authoring process much easier will invite much more people to help out. WDYT? WDYR = What Do You Reckon we think? ... excellent, of course. :-) -- Reinhard
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: David Crossley wrote: Stefano Mazzocchi wrote: Bertrand Delacretaz wrote: Reinhard Poetz a ?crit : At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system... Thanks Reinhard - to me this looks really good, and the fact that you're backing your proposal with actual work makes all the difference ;-) Touche'. I've tried with Doco but I never put it up with the expectations :-( What can I say: go for it! Well, some of the ideas and discussion from Doco would evolve into this system. Thanks for that much, it all helps. Glad to hear that. Yep, your proposal and the discussions helped a lot :-) ... and not to forget over the last 10 days, Upayavira helped me with many talks. I have only one problem with Reinhard's approach: open editing. And not because I fear defacing but I do fear link spamming bots. Please, do not leave the comments open for non-humans or it's going to be hell over again (at the very least let's use captchas) good point. I also want that every comment (not only doc changes) has to be approved by a committer. So we have a double-barrier (hope that's understandable English) for spamming bots. Two question to Stefano (and everybody else): I proposed numbers as document IDs? What do you think about this? Another question is the structure of URLs - the new efforts of Sylvain who wants to provide some docs in French needs some thinking where to put them. I propose http://c.a.o/ ... editable global docs (own repository) http://c.a.o/fr/ . editable global docs in French (own repository) http://c.a.o/2.2/ editable docs of 2.2 (own repository) http://c.a.o/2.2/fr/ . editable docs of 2.2 in French (own repository) http://c.a.o/2.2.1/ .. frozen docs of the 2.2.1 release http://c.a.o/2.2.1/en/ ... frozen French docs of the 2.2.1 release WDYT? -- Reinhard
Re: [proposal] Cocoon documentation system
On Sat, 15 Jan 2005 09:42:17 +0100, Reinhard Poetz [EMAIL PROTECTED] wrote: ... My first goal is reusing existing functionality (SVN, Forrest, static web pages). Writing the missing pieces (a small web application to edit docs online) shouldn't be too difficult - especially using CocoonForms (HTMLArea with HTMLCleaning convertor are shining here!) and Flowscript. At the end of the document you find a roadmap. It also contains some parts where I *really* need some help by others: - component (Java) that reads from and commits to SVN - should work over WebDAV, shouldn't it? I know there are some specialist in this community who could help out here (Unico, Gianugo, Guido) We have a huge team of specialists on the dev list. Yep. I hope that I can convince at least one of them to help me. Actually I need some Java code ;-) So here I ask officially: Who volunteers to write the Java code that communicates with the SVN repository (read and commit)? You may find this more problematic than you'd expect. I follow the subclipse list a little and have the impression that pure-java library development against SVN lags behind because it's difficult to keep up with the evolving standard. I should have thought that the rate of evolution has significantly slowed, but that is not the impression I get. Subclipse for instance uses jni for the low level svn operations so it can go against the original native libraries. On the other hand, there are some attempts to provide pure java svn libraries (one is called javaSVN I think?) so if these are usable in practice, the work could be trivial. Geoff
Re: [proposal] Cocoon documentation system
Geoff Howard wrote: On Sat, 15 Jan 2005 09:42:17 +0100, Reinhard Poetz [EMAIL PROTECTED] wrote: ... My first goal is reusing existing functionality (SVN, Forrest, static web pages). Writing the missing pieces (a small web application to edit docs online) shouldn't be too difficult - especially using CocoonForms (HTMLArea with HTMLCleaning convertor are shining here!) and Flowscript. At the end of the document you find a roadmap. It also contains some parts where I *really* need some help by others: - component (Java) that reads from and commits to SVN - should work over WebDAV, shouldn't it? I know there are some specialist in this community who could help out here (Unico, Gianugo, Guido) We have a huge team of specialists on the dev list. Yep. I hope that I can convince at least one of them to help me. Actually I need some Java code ;-) So here I ask officially: Who volunteers to write the Java code that communicates with the SVN repository (read and commit)? You may find this more problematic than you'd expect. I follow the subclipse list a little and have the impression that pure-java library development against SVN lags behind because it's difficult to keep up with the evolving standard. I should have thought that the rate of evolution has significantly slowed, but that is not the impression I get. Subclipse for instance uses jni for the low level svn operations so it can go against the original native libraries. On the other hand, there are some attempts to provide pure java svn libraries (one is called javaSVN I think?) so if these are usable in practice, the work could be trivial. People, again, let's be brave and get this of this silly pure java nonsense. the JNI connector works. Today! there is no need to play catchup with the SVN protocol (which is a proprietary extension/subset of WebDAV/DeltaV and very painful, I'll tell you) Besides, it's not that we have to distribute such a system. Let's do the simplest thing that can possibly work, that SWIG-based API is very very bad in the eyes of a java programmer, but well, it's way better than rewriting it from scratch. one day, hopefully, somebody will create a JSR170 wrapper for SVN... but until then, well, let's do what we can. -- Stefano.
Re: [proposal] Cocoon documentation system
People, again, let's be brave and get this of this silly pure java nonsense. the JNI connector works. Today! ...maybe for you :-/ ...maybe now We had so many problems with subclipse under linux that we finally went back to the commandline! ...maybe it's worth giving it another try. But a few months ago subclipse with JNI was just a PITA. cheers -- Torsten
Re: [proposal] Cocoon documentation system
On Sat, 15 Jan 2005 09:17:10 -0500, Geoff Howard [EMAIL PROTECTED] wrote: - component (Java) that reads from and commits to SVN - should work over WebDAV, shouldn't it? I know there are some specialist in this community who could help out here (Unico, Gianugo, Guido) We have a huge team of specialists on the dev list. Yep. I hope that I can convince at least one of them to help me. Actually I need some Java code ;-) So here I ask officially: Who volunteers to write the Java code that communicates with the SVN repository (read and commit)? You may find this more problematic than you'd expect. I follow the subclipse list a little and have the impression that pure-java library development against SVN lags behind because it's difficult to keep up with the evolving standard. Sorry for being late in jumping in. Just wanted to let you know that I already am using SVN+WebDAVblock+CForms editing for braindead content management (but it works, and I have code ready to contribute) Is there any peculiar reason for using Subversion proprietary calls when autoversioning works out of the box with plain old WebDAV? Going to read the wiki page now, but definitely count me in, at least for support. Ciao, -- Gianugo Rabellino Pro-netics s.r.l. - http://www.pro-netics.com Orixo, the XML business alliance: http://www.orixo.com (blogging at http://www.rabellino.it/blog/)
Re: [proposal] Cocoon documentation system
Torsten Curdt wrote: People, again, let's be brave and get this of this silly pure java nonsense. the JNI connector works. Today! ...maybe for you :-/ ...maybe now We had so many problems with subclipse under linux that we finally went back to the commandline! ...maybe it's worth giving it another try. But a few months ago subclipse with JNI was just a PITA. Well, you could switch to IntelliJ ;-) I've had the subversion plugin working in my Linux machine for a while. It isn't as good as the CVS support though. Ralph
Re: [proposal] Cocoon documentation system
Le 14 janv. 05, à 08:20, Reinhard Poetz a écrit : At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system... Thanks Reinhard - to me this looks really good, and the fact that you're backing your proposal with actual work makes all the difference ;-) I have added a few comments on the wiki, nothing very important at this stage. -Bertrand smime.p7s Description: S/MIME cryptographic signature
Re: [proposal] Cocoon documentation system
Bertrand Delacretaz wrote: Le 14 janv. 05, à 08:20, Reinhard Poetz a écrit : At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system... Thanks Reinhard - to me this looks really good, and the fact that you're backing your proposal with actual work makes all the difference ;-) I have added a few comments on the wiki, nothing very important at this stage. I like both of your ideas. The SimpleContentModel may solve the problems where to put resources like images (haven't had a solution up to now for this). Thank you! -- Reinhard
Re: [proposal] Cocoon documentation system
Le 14 janv. 05, à 09:35, Reinhard Poetz a écrit : ...The SimpleContentModel may solve the problems where to put resources like images (haven't had a solution up to now for this). Thank you! You're welcome - the SimpleContentModel is not my idea, it's Mark Lundquist's, but I read the page and found it interesting, and just mentally connected the two things. -Bertrand smime.p7s Description: S/MIME cryptographic signature
Re: [proposal] Cocoon documentation system
Stefano Mazzocchi wrote: Bertrand Delacretaz wrote: Reinhard Poetz a ?crit : At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system... Thanks Reinhard - to me this looks really good, and the fact that you're backing your proposal with actual work makes all the difference ;-) Touche'. I've tried with Doco but I never put it up with the expectations :-( What can I say: go for it! Well, some of the ideas and discussion from Doco would evolve into this system. Thanks for that much, it all helps. --David
Re: [proposal] Cocoon documentation system
Reinhard Poetz wrote: At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system. Thanks, a brilliant step. My first goal is reusing existing functionality (SVN, Forrest, static web pages). Writing the missing pieces (a small web application to edit docs online) shouldn't be too difficult - especially using CocoonForms (HTMLArea with HTMLCleaning convertor are shining here!) and Flowscript. At the end of the document you find a roadmap. It also contains some parts where I *really* need some help by others: - component (Java) that reads from and commits to SVN - should work over WebDAV, shouldn't it? I know there are some specialist in this community who could help out here (Unico, Gianugo, Guido) We have a huge team of specialists on the dev list. - enable the publishing process (forrestbot or cron) Both. At forrest-dev we are also starting to set up a demo of the new forrestbot and its webapp interface. So yes, we will be able to help on some aspects. The Proposal for ASF-wide documentation staging and publishing intends to enable various document management systems to feed into staging areas. I will add a para to the wiki page. - SSL setup I don't think that a technical solution will directly lead to better docs. I just think that making the doc authoring process much easier will invite much more people to help out. WDYT? WDYR = What Do You Reckon we think? ... excellent, of course. --David
Re: [proposal] Cocoon documentation system
David Crossley wrote: Stefano Mazzocchi wrote: Bertrand Delacretaz wrote: Reinhard Poetz a ?crit : At http://wiki.apache.org/cocoon/CocoonDocumentationSystem I propose the architecture of a new extensible documentation system... Thanks Reinhard - to me this looks really good, and the fact that you're backing your proposal with actual work makes all the difference ;-) Touche'. I've tried with Doco but I never put it up with the expectations :-( What can I say: go for it! Well, some of the ideas and discussion from Doco would evolve into this system. Thanks for that much, it all helps. Glad to hear that. I have only one problem with Reinhard's approach: open editing. And not because I fear defacing but I do fear link spamming bots. Please, do not leave the comments open for non-humans or it's going to be hell over again (at the very least let's use captchas) -- Stefano.
