RE: Moving docs from Wiki
On Wed, 26 Nov 2003, Reinhard Poetz wrote: > > From: David Crossley > > > Vadim Gritsenko wrote: > > > Reinhard Poetz wrote: > > > > > > >No problem, that was not the difficult part - I had more problems > > > >with the publishing process itself: > > > > I presume that you know about > > http://wiki.cocoondev.org/Wiki.jsp?page=CocoonWebsiteUpdate > > > > Agreed, the process could be easier. Thank your lucky stars > > that you were not struggling with Cocoon docs a couple of years ago. > > > > > > 1) complete build of Cocoon including documentation > > > > 2) use forrest to generate 'real' documentation > > > > > > "build docs" does these two items. > > > > > > > 3) then I used 'forrest run' and and XML editor to edit/create > > > > my docs (it took me very long until I found out *where* I > > > > can edit my docs) > > > > Sorry. The cvs head version of Forrest is leaving source and > > skins in-place and not copying them around. (But Cocoon is > > using 0.5 ATM.) > > > > > > BTW: an XML editor is the *worst* thing to edit > > content at all > > > > ... > > > > Why do you say that? We should fix it then. > > The only fix which will help me is a WYSIWIG-editor - otherwise it is > always painful to edit content. altova's authentic can provide a WYSIWIG but every time i had to try to setup an XML/XSL/SPS (SPS is a autheintic xml file that "drive" the WYSISWG) i have no reluts. maybe a authentic view of xdocs can help -- stavros > > > > > > > 4) then I had to copy the changed docs *manually* back into > > > > the Cocoon docs to check them in > > > > Yes, see answer to 3). In Forrest-0.5 there is the 'forrest > > backcopy' target for that. > > > > > > 5) then I had to generate the 'site' and copy them *manually* > > > > into cocoon-site > > > > > > "build docs" does (5) too. > > > > > > > 6) then I checked in cocoon-2.1 > > > > 7) then I checked in cocoon-site > > > > Cannot be avoided. > > > > > > 8) then I updated our website using the CVS client on > > > > cvs.apache.org > > > > > > Yes, these are manual steps. > > > > Some projects have a cron job to do that automatically, > > say every 12 hours. > > > thanks for your explanations - I'll look them up when I add/change some > docs in the future! > > -- > Reinhard > >
RE: Moving docs from Wiki
From: David Crossley > Vadim Gritsenko wrote: > > Reinhard Poetz wrote: > > > > >No problem, that was not the difficult part - I had more problems > > >with the publishing process itself: > > I presume that you know about > http://wiki.cocoondev.org/Wiki.jsp?page=CocoonWebsiteUpdate > > Agreed, the process could be easier. Thank your lucky stars > that you were not struggling with Cocoon docs a couple of years ago. > > > > 1) complete build of Cocoon including documentation > > > 2) use forrest to generate 'real' documentation > > > > "build docs" does these two items. > > > > > 3) then I used 'forrest run' and and XML editor to edit/create > > > my docs (it took me very long until I found out *where* I > > > can edit my docs) > > Sorry. The cvs head version of Forrest is leaving source and > skins in-place and not copying them around. (But Cocoon is > using 0.5 ATM.) > > > > BTW: an XML editor is the *worst* thing to edit > content at all > > > ... > > Why do you say that? We should fix it then. The only fix which will help me is a WYSIWIG-editor - otherwise it is always painful to edit content. > > > > 4) then I had to copy the changed docs *manually* back into > > > the Cocoon docs to check them in > > Yes, see answer to 3). In Forrest-0.5 there is the 'forrest > backcopy' target for that. > > > > 5) then I had to generate the 'site' and copy them *manually* > > > into cocoon-site > > > > "build docs" does (5) too. > > > > > 6) then I checked in cocoon-2.1 > > > 7) then I checked in cocoon-site > > Cannot be avoided. > > > > 8) then I updated our website using the CVS client on > > > cvs.apache.org > > > > Yes, these are manual steps. > > Some projects have a cron job to do that automatically, > say every 12 hours. thanks for your explanations - I'll look them up when I add/change some docs in the future! -- Reinhard
Re: Moving docs from Wiki
Vadim Gritsenko wrote: > Reinhard Poetz wrote: > > >No problem, that was not the difficult part - I had more problems with > >the publishing process itself: I presume that you know about http://wiki.cocoondev.org/Wiki.jsp?page=CocoonWebsiteUpdate Agreed, the process could be easier. Thank your lucky stars that you were not struggling with Cocoon docs a couple of years ago. > > 1) complete build of Cocoon including documentation > > 2) use forrest to generate 'real' documentation > > "build docs" does these two items. > > > 3) then I used 'forrest run' and and XML editor to edit/create > > my docs (it took me very long until I found out *where* I > > can edit my docs) Sorry. The cvs head version of Forrest is leaving source and skins in-place and not copying them around. (But Cocoon is using 0.5 ATM.) > > BTW: an XML editor is the *worst* thing to edit content at all ... Why do you say that? We should fix it then. > > 4) then I had to copy the changed docs *manually* back into > > the Cocoon docs to check them in Yes, see answer to 3). In Forrest-0.5 there is the 'forrest backcopy' target for that. > > 5) then I had to generate the 'site' and copy them *manually* > > into cocoon-site > > "build docs" does (5) too. > > > 6) then I checked in cocoon-2.1 > > 7) then I checked in cocoon-site Cannot be avoided. > > 8) then I updated our website using the CVS client on cvs.apache.org > > Yes, these are manual steps. Some projects have a cron job to do that automatically, say every 12 hours. --David
Re: Moving docs from Wiki
Reinhard Poetz wrote: ... No problem, that was not the difficult part - I had more problems with the publishing process itself: 1) complete build of Cocoon including documentation 2) use forrest to generate 'real' documentation "build docs" does these two items. 3) then I used 'forrest run' and and XML editor to edit/create my docs (it took me very long until I found out *where* I can edit my docs) BTW: an XML editor is the *worst* thing to edit content at all ... 4) then I had to copy the changed docs *manually* back into the Cocoon docs to check them in 5) then I had to generate the 'site' and copy them *manually* into cocoon-site "build docs" does (5) too. 6) then I checked in cocoon-2.1 7) then I checked in cocoon-site 8) then I updated our website using the CVS client on cvs.apache.org Yes, these are manual steps. Vadim
RE: Moving docs from Wiki
From: David Crossley > Tony Collen wrote: > > Bertrand Delacretaz wrote: > > > Reinhard Poetz a écrit : > > > > > >> ..It's time for Doco because moving content from Wiki to > CVS is a > > >> very, very, very, very boring job. (Aren't there any tools which > > >> could help?)... > > > > > > If you're talking about format conversion, JSPWiki's HTML > shouldn't > > > be > > > hard to convert to xdocs via XSLT. It uses skins so it is > also possible > > > to add more structure to the HTML to make this easier. > > > > Or we get Chaperon to parse the Wiki files themselves. This seems > > simpler. > > There is this excellent project called Apache Forrest. > See the demo of 'forrest seed site' at > http://forrestbot.cocoondev.org/sites/x> ml-forrest-template/ > > and look for the Wiki Sample which > employs Chaperon. > > I am very sorry Reinhard, i should have recalled that ability > when you talked about moving the Features doc. No problem, that was not the difficult part - I had more problems with the publishing process itself: 1) complete build of Cocoon including documentation 2) use forrest to generate 'real' documentation 3) then I used 'forrest run' and and XML editor to edit/create my docs (it took me very long until I found out *where* I can edit my docs) BTW: an XML editor is the *worst* thing to edit content at all ... 4) then I had to copy the changed docs *manually* back into the Cocoon docs to check them in 5) then I had to generate the 'site' and copy them *manually* into cocoon-site (... I forgot to copy some of the docs - thanks to Jörg who reminded me that a change in the menu structure has impact on many docs) 6) then I checked in cocoon-2.1 7) then I checked in cocoon-site 8) then I updated our website using the CVS client on cvs.apache.org As I had never done this before it took me a while to figure out how all those things work together. Sorry, that's no fun. If the features docs hadn't been so important for me because I think this was *the* big missing thing in our docs I would have given up after an hour. As I already said three times in my mails yesterday I'm really looking forward to using Doco - this will give the Cocoon documentation a great push forward!!! Cheers, Reinhard
Re: Moving docs from Wiki
Tony Collen wrote: > Bertrand Delacretaz wrote: > > Reinhard Poetz a écrit : > > > >> ..It's time for Doco because moving content from Wiki to CVS is a very, > >> very, very, very boring job. (Aren't there any tools which could > >> help?)... > > > > If you're talking about format conversion, JSPWiki's HTML shouldn't be > > hard to convert to xdocs via XSLT. It uses skins so it is also possible > > to add more structure to the HTML to make this easier. > > Or we get Chaperon to parse the Wiki files themselves. This seems simpler. There is this excellent project called Apache Forrest. See the demo of 'forrest seed site' at http://forrestbot.cocoondev.org/sites/xml-forrest-template/ and look for the Wiki Sample which employs Chaperon. I am very sorry Reinhard, i should have recalled that ability when you talked about moving the Features doc. --David
Re: Moving docs from Wiki
Joerg Heinicke wrote: On 24.11.2003 21:55, Upayavira wrote: Tony Collen wrote: BTW, when a page is moved, I think we should keep the page on the wiki, and perhaps keep a record of when the last version was committed to CVS. Blowing away docs (like the features list) isn't too useful, especially since I was going to point to the version of the docs in the Wiki, and possibly make a bunch of revisions to the page. But then I suppose I could just edit the new file in CVS and commit. I agree that blowing away docs is bad. However, just leaving them is pretty bad too. IMO, once a doc is moved to CVS, the original wiki page should be replaced by a placeholder, which is where people can place comments about the related page in CVS. From that point of view my solution must be really good in your opinion :-) http://wiki.cocoondev.org/Wiki.jsp?page=CocoonFeatures Yup! Hadn't looked :-( Regards, Upayavira
Re: Moving docs from Wiki
Bertrand Delacretaz wrote: Le Lundi, 24 nov 2003, à 22:00 Europe/Zurich, Joerg Heinicke a écrit : ...From that point of view my solution must be really good in your opinion :-) http://wiki.cocoondev.org/Wiki.jsp?page=CocoonFeatures hmmm..maybe we should push a little more towards patches? Instead of If you want to add further features or correct some issues please add it either here or provide a patch to the official documentation. I'd write You can still use this page for comments, but for content changes please provide patches as described in [MovedToCvs]. +1. I like the idea of having stuff gravitate more towards getting docs into CVS.. but sometimes I just want to be able to flesh some stuff out on the Wiki. After enough revisions, I'd probably just delete it and commit it myself, so we should just reccommend that patches be provided. WDYT? Tony
Re: Moving docs from Wiki
Tony Collen wrote: Joerg Heinicke wrote: The problem I saw (and because of this I removed the list) are the missing diffs (or the bad usability with it) after further additions to the page are made. Imagine in a half year you want to update the page in the CVS, in the meantime there were 10 changes in the wiki page, maybe someone reordered all the things! You can start from scratch then or try to reproduce all the changes for the CVS version - and this from version n to v. n+1, from v. n+1 to v. n+2 and so on. After the removal of the list I think we have a cleaner approach. Hmm, then perhaps just a note of when the old docs were moved to CVS would suffice? Exactly, and a reference to the new doc, and a space where people can comment on the new doc. So only changes go on this wiki page. Regards, Upayavira
Re: Moving docs from Wiki
On 24.11.2003 22:05, Bertrand Delacretaz wrote: Le Lundi, 24 nov 2003, à 22:00 Europe/Zurich, Joerg Heinicke a écrit : ...From that point of view my solution must be really good in your opinion :-) http://wiki.cocoondev.org/Wiki.jsp?page=CocoonFeatures hmmm..maybe we should push a little more towards patches? Instead of If you want to add further features or correct some issues please add it either here or provide a patch to the official documentation. I'd write You can still use this page for comments, but for content changes please provide patches as described in [MovedToCvs]. WDYT? No objection. Change it as you want to. Joerg
Re: Moving docs from Wiki
Le Lundi, 24 nov 2003, à 22:00 Europe/Zurich, Joerg Heinicke a écrit : ...From that point of view my solution must be really good in your opinion :-) http://wiki.cocoondev.org/Wiki.jsp?page=CocoonFeatures hmmm..maybe we should push a little more towards patches? Instead of If you want to add further features or correct some issues please add it either here or provide a patch to the official documentation. I'd write You can still use this page for comments, but for content changes please provide patches as described in [MovedToCvs]. WDYT?
Re: Moving docs from Wiki
Le Lundi, 24 nov 2003, à 22:06 Europe/Zurich, Tony Collen a écrit : ...Would a centralized list of pages that were moved over (along with the last date they were moved) be useful to maintain? If all moved pages point to http://wiki.cocoondev.org/Wiki.jsp?page=MovedToCvs then the "Referenced by" link of that page is your list ;-) -Bertrand
Re: Moving docs from Wiki
Bertrand Delacretaz wrote: I have added a note about this at http://wiki.cocoondev.org/Wiki.jsp?page=MovedToCvs . Of course this can still be discussed here, but having the "rules" on the wiki should help. I also put a note on the CocoonFeatures page about when it was last moved over to CVS, which is useful. Would a centralized list of pages that were moved over (along with the last date they were moved) be useful to maintain? Or maybe that's too much to keep track of. -Bertrand Tony
Re: Moving docs from Wiki
On 24.11.2003 21:58, Bertrand Delacretaz wrote: ...I agree that blowing away docs is bad. However, just leaving them is pretty bad too. IMO, once a doc is moved to CVS, the original wiki page should be replaced by a placeholder, which is where people can place comments about the related page in CVS. I have added a note about this at http://wiki.cocoondev.org/Wiki.jsp?page=MovedToCvs . Of course this can still be discussed here, but having the "rules" on the wiki should help. -Bertrand Perfect, Bertrans :-) Joerg
Re: Moving docs from Wiki
On 24.11.2003 21:55, Upayavira wrote: Tony Collen wrote: BTW, when a page is moved, I think we should keep the page on the wiki, and perhaps keep a record of when the last version was committed to CVS. Blowing away docs (like the features list) isn't too useful, especially since I was going to point to the version of the docs in the Wiki, and possibly make a bunch of revisions to the page. But then I suppose I could just edit the new file in CVS and commit. I agree that blowing away docs is bad. However, just leaving them is pretty bad too. IMO, once a doc is moved to CVS, the original wiki page should be replaced by a placeholder, which is where people can place comments about the related page in CVS. From that point of view my solution must be really good in your opinion :-) http://wiki.cocoondev.org/Wiki.jsp?page=CocoonFeatures Joerg
Re: Moving docs from Wiki
Le Lundi, 24 nov 2003, à 21:55 Europe/Zurich, Upayavira a écrit : ...I agree that blowing away docs is bad. However, just leaving them is pretty bad too. IMO, once a doc is moved to CVS, the original wiki page should be replaced by a placeholder, which is where people can place comments about the related page in CVS. I have added a note about this at http://wiki.cocoondev.org/Wiki.jsp?page=MovedToCvs . Of course this can still be discussed here, but having the "rules" on the wiki should help. -Bertrand
Re: Moving docs from Wiki
Tony Collen wrote: BTW, when a page is moved, I think we should keep the page on the wiki, and perhaps keep a record of when the last version was committed to CVS. Blowing away docs (like the features list) isn't too useful, especially since I was going to point to the version of the docs in the Wiki, and possibly make a bunch of revisions to the page. But then I suppose I could just edit the new file in CVS and commit. I agree that blowing away docs is bad. However, just leaving them is pretty bad too. IMO, once a doc is moved to CVS, the original wiki page should be replaced by a placeholder, which is where people can place comments about the related page in CVS. Regards, Upayavira
Re: Moving docs from Wiki
Joerg Heinicke wrote: The problem I saw (and because of this I removed the list) are the missing diffs (or the bad usability with it) after further additions to the page are made. Imagine in a half year you want to update the page in the CVS, in the meantime there were 10 changes in the wiki page, maybe someone reordered all the things! You can start from scratch then or try to reproduce all the changes for the CVS version - and this from version n to v. n+1, from v. n+1 to v. n+2 and so on. After the removal of the list I think we have a cleaner approach. Hmm, then perhaps just a note of when the old docs were moved to CVS would suffice? Joerg Tony, can't think of a funny sig anymore.
Re: Moving docs from Wiki
On 24.11.2003 21:28, Tony Collen wrote: BTW, when a page is moved, I think we should keep the page on the wiki, and perhaps keep a record of when the last version was committed to CVS. Blowing away docs (like the features list) isn't too useful, especially since I was going to point to the version of the docs in the Wiki, and possibly make a bunch of revisions to the page. But then I suppose I could just edit the new file in CVS and commit. The problem I saw (and because of this I removed the list) are the missing diffs (or the bad usability with it) after further additions to the page are made. Imagine in a half year you want to update the page in the CVS, in the meantime there were 10 changes in the wiki page, maybe someone reordered all the things! You can start from scratch then or try to reproduce all the changes for the CVS version - and this from version n to v. n+1, from v. n+1 to v. n+2 and so on. After the removal of the list I think we have a cleaner approach. Joerg
Re: Moving docs from Wiki
BTW, when a page is moved, I think we should keep the page on the wiki, and perhaps keep a record of when the last version was committed to CVS. Blowing away docs (like the features list) isn't too useful, especially since I was going to point to the version of the docs in the Wiki, and possibly make a bunch of revisions to the page. But then I suppose I could just edit the new file in CVS and commit. Tony
Re: Moving docs from Wiki (was : cvs commit: cocoon-2.1/src/documentation/xdocs features.xml ...)
Bertrand Delacretaz wrote: Le Lundi, 24 nov 2003, à 19:22 Europe/Zurich, Reinhard Poetz a écrit : ..It's time for Doco because moving content from Wiki to CVS is a very, very, very, very boring job. (Aren't there any tools which could help?)... If you're talking about format conversion, JSPWiki's HTML shouldn't be hard to convert to xdocs via XSLT. It uses skins so it is also possible to add more structure to the HTML to make this easier. Or we get Chaperon to parse the Wiki files themselves. This seems simpler. - Bertrand, who likes these funny new sigs but is afraid he won't have much time for Cocoon in the next few weeks Tony, who will have a hard time coming up with a new sig every time he writes to the lists.
