[PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Over at Cocoon they are starting to use Daisy for their docs. I propose 
we do the same.

We recently voted Ferdinand in as a committer because of his efforts on 
the docs and we have had a flurry of new users providing docs patches of 
great value too. I think we need to make it easier for these people to 
work on our documentation.

I have completed preliminary work on the locationmap that allows us to 
integrate our existing content with new content developed in Daisy. This 
means we do not need to migrate existing content to Daisy until we 
actually edit it, so the only set up we need to do is get Daisy 
installed on our Zone.

As you know the locationmap work is in a branch at the moment and needs 
a little more testing before merging with trunk. But I do not expect any 
problems (but then one never does). Perhaps this could be a good test of 
it before we merge.

Steven Noels set up Daisy for the Cocoon community and so there will be 
the auto-generated docs in the Cocoon zone for how to do it, I'm sure he 
will help us if we get stuck.

So, shall we do it?

Ross

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> The CMS is a "super wiki" - loosely controlled, low barrier to entry - 
> most importantly *not* published as official docs

lenya does have the authoring and live view for this purpose (and 
workflow), so presumably the barrier for editing / submitting for 
approval would be lower, and approval/publish would come from a commiter.

> The published docs are managed by Forrest as normal using the 
> locationmap to bring content from both SVN and the CMS
> (this step may not be necessary if Lenya can use SVN as a repository)

it cannot yet, but that is one of the things we want to work out.

http://mail-archives.apache.org/mod_mbox/lenya-dev/200505.mbox/%3c4293FE22.3050000@apache.org%3e

>> Perhaps we are using different terminology here. I see that
>> committers review/edit and then "commit" changes. The "publish"
>> is a separate process whereby a group of committed edits
>> is now ready and the documents are generated and moved to the
>> actual website.

imho, the commit to SVN of the source document can and should happen 
only after a document has been reviewed & approved. this would keep 
intermediary versions out of SVN, and would make sure only commiters can 
initiate commits to SVN.


>> After that, how do those "finished" documents get edited again?
> 
> In the CMS just like before. Our published docs are generated from the 
> CMS repository, this is no different from the current situation in which 
> we publish from our SVN repository.

right, the CMS keeps track of both source and rendered versions, and 
after a rewiew/publish cycle, the editing process can start anew.

>>> In other words, we have the chaos of constantly evolving docs under 
>>> the surface, on the surface we have nice ordered, version controlled 
>>> and managed publications for our users. The migration path between 
>>> the two is the close attention to detali of the review process.
>>
>> Oh dear, i am feeling overwhelmed with the thought of chaos.

if these tools help to get more people involved with working on 
documentation, then i think having to review more changes to the docs 
than today is a nice burden to have ;)

> (with Daisy, Gregor has already acknowledge Lenya doesn't do diffs this 
> is a *big* problem)

.. and therefore needs attention from the lenya community:

http://issues.apache.org/bugzilla/show_bug.cgi?id=32008

> Yes, this is one of the advantages of the fact that the Daisy wiki 
> tidies the edited content. you always get good diffs regardless of how 
> the author wrote the content.

lenya uses xml wysiwyg editors, so the diffs should also be quite ok. 
there are tools like xmldiff for that purpose.

wyona has some code for this, let me see if we can donate it.


> That is exactly my proposal - no dependency. However, if Daisy were to 
> adopt Forrest as the *only* publishing engine then there would be a 
> dependency in the sense they could not do static publishing without 
> Forrest. Since they do not need the multiple input formats they are not 
> interested in using Forrest as the publishing engine.

i personally would love to delegate lenya's publishing to forrest :)

> My thinking precisely. I'd rather go to infra with the start of a solution.

+1

>> Sounds like duplication of effort to me.

at least for lenya, this dogfood problem exposes some issues that we 
need to be working on anyway.

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> The CMS is a "super wiki" - loosely controlled, low barrier to entry - 
> most importantly *not* published as official docs

lenya does have the authoring and live view for this purpose (and 
workflow), so presumably the barrier for editing / submitting for 
approval would be lower, and approval/publish would come from a commiter.

> The published docs are managed by Forrest as normal using the 
> locationmap to bring content from both SVN and the CMS
> (this step may not be necessary if Lenya can use SVN as a repository)

it cannot yet, but that is one of the things we want to work out.

http://mail-archives.apache.org/mod_mbox/lenya-dev/200505.mbox/%3c4293FE22.3050000@apache.org%3e

>> Perhaps we are using different terminology here. I see that
>> committers review/edit and then "commit" changes. The "publish"
>> is a separate process whereby a group of committed edits
>> is now ready and the documents are generated and moved to the
>> actual website.

imho, the commit to SVN of the source document can and should happen 
only after a document has been reviewed & approved. this would keep 
intermediary versions out of SVN, and would make sure only commiters can 
initiate commits to SVN.


>> After that, how do those "finished" documents get edited again?
> 
> In the CMS just like before. Our published docs are generated from the 
> CMS repository, this is no different from the current situation in which 
> we publish from our SVN repository.

right, the CMS keeps track of both source and rendered versions, and 
after a rewiew/publish cycle, the editing process can start anew.

>>> In other words, we have the chaos of constantly evolving docs under 
>>> the surface, on the surface we have nice ordered, version controlled 
>>> and managed publications for our users. The migration path between 
>>> the two is the close attention to detali of the review process.
>>
>> Oh dear, i am feeling overwhelmed with the thought of chaos.

if these tools help to get more people involved with working on 
documentation, then i think having to review more changes to the docs 
than today is a nice burden to have ;)

> (with Daisy, Gregor has already acknowledge Lenya doesn't do diffs this 
> is a *big* problem)

.. and therefore needs attention from the lenya community:

http://issues.apache.org/bugzilla/show_bug.cgi?id=32008

> Yes, this is one of the advantages of the fact that the Daisy wiki 
> tidies the edited content. you always get good diffs regardless of how 
> the author wrote the content.

lenya uses xml wysiwyg editors, so the diffs should also be quite ok. 
there are tools like xmldiff for that purpose.

wyona has some code for this, let me see if we can donate it.


> That is exactly my proposal - no dependency. However, if Daisy were to 
> adopt Forrest as the *only* publishing engine then there would be a 
> dependency in the sense they could not do static publishing without 
> Forrest. Since they do not need the multiple input formats they are not 
> interested in using Forrest as the publishing engine.

i personally would love to delegate lenya's publishing to forrest :)

> My thinking precisely. I'd rather go to infra with the start of a solution.

+1

>> Sounds like duplication of effort to me.

at least for lenya, this dogfood problem exposes some issues that we 
need to be working on anyway.

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

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Ross Gardler wrote:
> 
>>David Crossley wrote:
>>
>>>How will the changed content get back into our SVN?
>>
>>For development, it doesn't. Daisy is fully version controlled (and I 
>>think Lenya is). For publishing we do just as we are doing now.
> 
> 
> I don't yet see the distinction. ASF projects have assets:
> e.g. code, docs, etc. All assets are stored in SVN. So i would think
> that the sources for all docs are stored in ASF repositories.

This is the position that Cocoon started with. However, it is simply not 
try, not all assets are in SVN, mailing list archives and wiki documents 
being the two most relevant to this situation. This has resulted in 
Cocoon agreeing that the docs don't need to go into SVN.

However, I have to admit, I am more of a mind that the *published* docs 
should go into SVN. So here is my proposal:

The CMS is a "super wiki" - loosely controlled, low barrier to entry - 
most importantly *not* published as official docs

The published docs are managed by Forrest as normal using the 
locationmap to bring content from both SVN and the CMS
(this step may not be necessary if Lenya can use SVN as a repository)

Periodically we do a "forrest site" and commit the generated docs to SVN

The advantage of this approach is that a tight integration between Lenya 
and SVN can allow people to edit the docs offline.

>>>How is the workflow managed to get the content reviewed
>>>and then published onto the website? At the moment we
>>>do have a workflow of sorts.
>>
>>Any registered user can edit. Only committers can publish. The Forrest 
>>generated site is only created from published changes.
>>
>>In other words, the same workflow as at present but we replace the edit 
>>document/create patch/submit patch/review patch/apply patch process with 
>>edit document/review edit/publish edit process.
> 
> 
> Perhaps we are using different terminology here. I see that
> committers review/edit and then "commit" changes. The "publish"
> is a separate process whereby a group of committed edits
> is now ready and the documents are generated and moved to the
> actual website.

OK, there are two distinct processes:

One for the wiki docs:



edit in wiki -> review edit in wiki -> publish edit in wiki
     /|\                /|\                     /|\
      |                  |                       |
(almost) anyone   Docs Committers          Docs Committers




and one for the published docs:



review wiki docs -> publish in Forrest site
      /|\                    /|\
       |                      |
   committers             committers


Note I have added a new type of committer here. One with a lower barrier 
to entry. We don't have to do this we could just have the existing 
structure, but it is an option.

>>>I also agree with Ferdinand. We would need a structure to
>>>add these docs, or we end up with the un-manageable mess
>>>that they call Wiki.
> 
> 
> Clarification: When i said mess/Wiki then i did not specifically
> mean Daisy or whatever. I refer to the problem where any user can
> create a new document, which probably repeats content in other
> documents. Most wikis that i have seen, have an unstructured
> collection of repetitive documents.

Yes, that was my understanding of what you said. Please understand we 
have *two* documentation tools, the "in development" tools and the 
"publishing" tools. Using these tools we can manage the quality of our 
published docs whilst at the same time allowing people to just jump in 
and get their feet wet. Take my recent discussion with Tim regarding 
locationmaps and the cocoon: protocol. In those mails there is alot of 
really valuable documentation, in the case of the cocoon: protocol it is 
valuable to Forrest and Cocoon.

If Tim could just cut and paste the text into a WYSIWYM editor I believe 
we would have a decent start to a doc. Later a dev says OK, that Doc is 
pretty good, I'll add it into the published site with a few additional 
comments and fixme's.


>>The idea is that the CMS is freeform like a wiki, but the published docs 
>>only come from an Forrest generated site. In other words, we use the 
>>Wiki to allow anyone to add content/edit content. We optimise the wiki 
>>for the editors of content (as opposed to the users of content), that is 
>>committers and technical users will likely use the Wiki as the primary 
>>souce of documentation. Whilst users will use the published website.
> 
> 
> What will actually happen is that users will come to this preparation
> area to find the "most up-to-date docs". I suppose that we can have
> big red warning banners.

Well, right now we have 0.6 and 0.7-dev docs on the site, is it a 
problem that some users are coming to the 0.7-dev docs?

Incidentally, I still think we should continue with publishing the next 
version docs in this way.

>>The published docs are managed using Forrest. Only those documents that 
>>are of sufficient quality make it into the published docs that appear in 
>>our distributions and on our website.
> 
> 
> After that, how do those "finished" documents get edited again?

In the CMS just like before. Our published docs are generated from the 
CMS repository, this is no different from the current situation in which 
we publish from our SVN repository.

>>In other words, we have the chaos of constantly evolving docs under the 
>>surface, on the surface we have nice ordered, version controlled and 
>>managed publications for our users. The migration path between the two 
>>is the close attention to detali of the review process.
> 
> 
> Oh dear, i am feeling overwhelmed with the thought of chaos.

:-))

I mean "managed chaos". Would you call Wikipedia chaotic? I would it's 
madness in there. Spam all over the place, random edits by unknown 
people, duplication across articles. However, at the end of the day it 
is an excellent resource because it is managed well.

Then look at http://www.answers.com most of their content comes from 
wikipedia. What they do is take a dump of the wikipedia database, do 
some quality assurance work and publish it. What you end up with is the 
quality of Wikipedia without the chaos.

This is the same model as my proposal here.

>>>Will we see sensible diffs, so that the committers can
>>>oversee the content or do we get the voluminous diffs
>>>like wiki where you cannot see what has been changed?
>>>e.g. most paragraphs are one long line, so diffs are useless.
>>
>>Yes (at least for Daisy, don't know about Lenya). You can play around by 
>>looking at the versions on Daisy home page at CocoonDev.org 
>>http://www.cocoondev.org/daisy/index/versions.html
> 
> 
> That helps a bit. What i was more concerned about is that diffs
> need to come to a mailing list, because committers need to review
> them as they come in. We cannot go off to a website to see if there
> have been any changes.

It's better than that ;-)

(with Daisy, Gregor has already acknowledge Lenya doesn't do diffs this 
is a *big* problem)

With Daisy each registered user is able to subscribe to particular 
pages, pages within a given collection or all pages. This means that you 
could opt to have changes to a particular set of pages mailed to you 
personally. i.e. you can take "ownership" of a portion of the documentation.

We could still have the mailing list receive all change emails as well.

> Look at the diffs that come from Cocoon Wiki. Whenever there
> is one long paragraph (common on a wiki) then email diffs
> are impossible to monitor.

Yes, this is one of the advantages of the fact that the Daisy wiki 
tidies the edited content. you always get good diffs regardless of how 
the author wrote the content.

>>>Who will be able to add content? Anyone? Do they need to
>>>be a committer? Do they need to be on forrest-dev?
>>
>>My proposal is:
>>
>>1) any visitor can add comments (see Comments link at bottom of 
>>http://www.cocoondev.org/daisy/index.html)
>>
>>2) any registered visitor can make edits, but their edits are not 
>>published automaticall. People can self register but an email address 
>>and confirmation email is used so we can tackle spammers
> 
> 
> Not sure yet about the self-register thing. The day will come
> when there is a disruptive person (perhaps well-intentioned) that
> creates unnecessary work by continually changing stuff that they
> do not understand.

Yes, but everything is version controlled. Since those without "docs 
commit" access cannot publish (even to the wiki), they can only edit. A 
change is reviewed before it is published (to the wiki) and then 
(optionally) reviewed again before published to the official docs.

But this can be changed at any time in the future, so no need to worry now.

...

>>
>>The Lenya team seem a more willing to work *with* us on integrating 
>>Forrest and Daisy. I have discussed the Daisy plugin on the Daisy dev 
>>list, I offered to donate the code to them and work on it over there 
>>since they have static only publication and books on their roadmap (both 
>>of which can be achieved with Daisy + Forrest). However, they were not 
>>interested, preferring insted to build their own system that was not 
>>dependant on Forrest. Since I need the multiple input formats of Forrest 
>>that leaves me on my own here :-(
> 
> 
> That does not sound very constructive. I thought that your suggestion was
> that if a content managemnent system simply exposes the source, then
> Forrest can process it. There is no "dependency".

That is exactly my proposal - no dependency. However, if Daisy were to 
adopt Forrest as the *only* publishing engine then there would be a 
dependency in the sense they could not do static publishing without 
Forrest. Since they do not need the multiple input formats they are not 
interested in using Forrest as the publishing engine.

You can see the discussion, if you are interested, at:

http://lists.cocoondev.org/pipermail/daisy/2005-May/001302.html

And the final position of the Daisy community is made cleat in another 
thread:

http://lists.cocoondev.org/pipermail/daisy/2005-May/001316.html

As you can see from this message it boils down to different use cases 
between the Daisy community and the ASF.

...

>>It is my thinking that since Forrest is used by many projects within 
>>Apache we should take it upon ourselves to develop and test a system 
>>intended to be used across Apache. When we agree on how to do this we 
>>should announce this on Infrastructure@a.o and invite interested parties 
>>to come and help. As long as we have enough people committed here then 
>>it will not matter if (when?) they do not come.
> 
> 
> Lets try then. However i don't suggest "announcing" anything to
> Infrastructure. There would surely be a requirement that has not
> been addressed that sends us back to the drawing board. It would
> be better to work with them.

My thinking precisely. I'd rather go to infra with the start of a solution.

>>I understand. I've just had these same discussions (minus the infra@a.o 
>>part) over at Cocoon so most of these issues have been discussed and 
>>answered from the Cocoon perspective. Of course, that may be different 
>>from the Forrest perspective.
> 
> 
> Sounds like duplication of effort to me.

Not at all, since I have offered to work on the integration of the Daisy 
repository for them, which I am doing for a client. This integration 
involves enhancements to Forrest (I want to use views for this as well, 
my clients use case involves pulling materials from different 
repositories in a single page). Because it involves work on Forrest I 
would rather be doing it here and passing the finished results to them 
there.

The only duplication is the installation of a CMS, which is why I 
proposed Daisy over Lenya. But if Lenya is going to collaborate with us, 
as I have said, I am willing to work with them too.

Ross

Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> David Crossley wrote:
> >
> >How will the changed content get back into our SVN?
> 
> For development, it doesn't. Daisy is fully version controlled (and I 
> think Lenya is). For publishing we do just as we are doing now.

I don't yet see the distinction. ASF projects have assets:
e.g. code, docs, etc. All assets are stored in SVN. So i would think
that the sources for all docs are stored in ASF repositories.

> >How is the workflow managed to get the content reviewed
> >and then published onto the website? At the moment we
> >do have a workflow of sorts.
> 
> Any registered user can edit. Only committers can publish. The Forrest 
> generated site is only created from published changes.
> 
> In other words, the same workflow as at present but we replace the edit 
> document/create patch/submit patch/review patch/apply patch process with 
> edit document/review edit/publish edit process.

Perhaps we are using different terminology here. I see that
committers review/edit and then "commit" changes. The "publish"
is a separate process whereby a group of committed edits
is now ready and the documents are generated and moved to the
actual website.

> >I also agree with Ferdinand. We would need a structure to
> >add these docs, or we end up with the un-manageable mess
> >that they call Wiki.

Clarification: When i said mess/Wiki then i did not specifically
mean Daisy or whatever. I refer to the problem where any user can
create a new document, which probably repeats content in other
documents. Most wikis that i have seen, have an unstructured
collection of repetitive documents.

> The idea is that the CMS is freeform like a wiki, but the published docs 
> only come from an Forrest generated site. In other words, we use the 
> Wiki to allow anyone to add content/edit content. We optimise the wiki 
> for the editors of content (as opposed to the users of content), that is 
> committers and technical users will likely use the Wiki as the primary 
> souce of documentation. Whilst users will use the published website.

What will actually happen is that users will come to this preparation
area to find the "most up-to-date docs". I suppose that we can have
big red warning banners.

> The published docs are managed using Forrest. Only those documents that 
> are of sufficient quality make it into the published docs that appear in 
> our distributions and on our website.

After that, how do those "finished" documents get edited again?

> In other words, we have the chaos of constantly evolving docs under the 
> surface, on the surface we have nice ordered, version controlled and 
> managed publications for our users. The migration path between the two 
> is the close attention to detali of the review process.

Oh dear, i am feeling overwhelmed with the thought of chaos.

> >Will we see sensible diffs, so that the committers can
> >oversee the content or do we get the voluminous diffs
> >like wiki where you cannot see what has been changed?
> >e.g. most paragraphs are one long line, so diffs are useless.
> 
> Yes (at least for Daisy, don't know about Lenya). You can play around by 
> looking at the versions on Daisy home page at CocoonDev.org 
> http://www.cocoondev.org/daisy/index/versions.html

That helps a bit. What i was more concerned about is that diffs
need to come to a mailing list, because committers need to review
them as they come in. We cannot go off to a website to see if there
have been any changes.

Look at the diffs that come from Cocoon Wiki. Whenever there
is one long paragraph (common on a wiki) then email diffs
are impossible to monitor.

> >Who will be able to add content? Anyone? Do they need to
> >be a committer? Do they need to be on forrest-dev?
> 
> My proposal is:
> 
> 1) any visitor can add comments (see Comments link at bottom of 
> http://www.cocoondev.org/daisy/index.html)
> 
> 2) any registered visitor can make edits, but their edits are not 
> published automaticall. People can self register but an email address 
> and confirmation email is used so we can tackle spammers

Not sure yet about the self-register thing. The day will come
when there is a disruptive person (perhaps well-intentioned) that
creates unnecessary work by continually changing stuff that they
do not understand.

> 3) any committer can publish edits
> 
> 4) change emails will be sent to our existing commit email list 
> (although they can be sent to individual users)
> 
> If we wanted a tighter control we can, of course have it, i.e. only 
> committers able to edit. But that would make it *harder* for 
> non-committers to contribute.
> 
> >Are the contributions assigned copyright to ASF?
> 
> We are currently discussing this over at Cocoon, the position seems to 
> be settling on:
> 
> 
> --- start of mail copied from Cocoon-dev ---
> 
> > We can consider that a CLA is needed for "document committers" as 
> they control official (i.e. published) docs,
> 
> 
> +1
> 
> > whereas "document contributors" are considered like people 
> contributing wiki pages and bugzilla patches, and implicitely accept 
> their contributions to be used by document committers under the ASL. A 
> way to ensure people don't miss this is a checkbox in the registration 
> screen stating "I accept my contributions to be used, modified or even 
> trashed by the documentation committers according to ASL 2.0".
> 
> 
> We could always add such verbiage to the registration screen, but I 
> would prefer not to do this in Daisy-proper. The registration form is 
> just a CForms form so that shouldn't be too hard - it's just something 
> we should remember when upgrading Daisy.
> 
> 
> --- end of copied mail ---
> 
> >I actually far prefer the current process where people
> >need to send patches. That way they get reviewed by a committer.
> 
> In this approach all I am proposing is we make it easier for people to 
> submit patches. I am not proposing that we remove the review stage, we 
> still have:
> 
> edit -> draft -> review -> public/reject
> 
> >Who will manage this Daisy installation? We cannot be stuck
> >with one person who knows a bit about it. We would need a
> >management plan. Same applies if we use Lenya.
> 
> The Lenya team seem a more willing to work *with* us on integrating 
> Forrest and Daisy. I have discussed the Daisy plugin on the Daisy dev 
> list, I offered to donate the code to them and work on it over there 
> since they have static only publication and books on their roadmap (both 
> of which can be achieved with Daisy + Forrest). However, they were not 
> interested, preferring insted to build their own system that was not 
> dependant on Forrest. Since I need the multiple input formats of Forrest 
> that leaves me on my own here :-(

That does not sound very constructive. I thought that your suggestion was
that if a content managemnent system simply exposes the source, then
Forrest can process it. There is no "dependency".

> Gregor says (in another reply on this thread) that a number of the Lenya 
> team are willing to help us out. The concern I have is how easy it is to 
> integrate Forrest as the publication engine. I've tried and failed in 
> the past, but now I've figured out the locationmap maybe it will be 
> easier. Furthermore Lenya has moved on a fair bit since my last attempt.
> 
> I'm willing to work on either platform. I have a client using Daisy, 
> that is the only reason for my preference. If we have the excplicit help 
> of the Lenya team here then I would happily work with Lenya, although my 
> time will not be as copious as it would be for Daisy (at least till 
> Lenya convinces me it is better and I sell a Lenya + Forrest system to 
> someone ;-)
> 
> >I find this very alarming. Some people at Infrastructure are
> >trying to get a cross-project environment established for managing
> >documentation tools and site-building. All PMCs were asked to
> >join and discuss this. Some people have, but mainly the process
> >has stalled again.
> >
> >Instead we see projects like Cocoon rushing off to do their
> >own thing. Now we will get duplicate instances of Daisy/Forrest.
> 
> It is my thinking that since Forrest is used by many projects within 
> Apache we should take it upon ourselves to develop and test a system 
> intended to be used across Apache. When we agree on how to do this we 
> should announce this on Infrastructure@a.o and invite interested parties 
> to come and help. As long as we have enough people committed here then 
> it will not matter if (when?) they do not come.

Lets try then. However i don't suggest "announcing" anything to
Infrastructure. There would surely be a requirement that has not
been addressed that sends us back to the drawing board. It would
be better to work with them.

> I'm offering some of my time (post 0.7) to get this going.
> 
> Can we count on the Lenya team to assist?
> 
> Thorsten, do you still need to create the Forrest Lenya integration? Can 
> we count on some of your time for that part of it?
> 
> >Sorry, i am not trying to be obstructive, just that i see too
> >many unanswered issues.
> 
> I understand. I've just had these same discussions (minus the infra@a.o 
> part) over at Cocoon so most of these issues have been discussed and 
> answered from the Cocoon perspective. Of course, that may be different 
> from the Forrest perspective.

Sounds like duplication of effort to me.

--David

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> Yes (at least for Daisy, don't know about Lenya). You can play around by 
> looking at the versions on Daisy home page at CocoonDev.org 
> http://www.cocoondev.org/daisy/index/versions.html

lenya doesn't have such a nice diff view yet, so it would have to be an 
external diff tool.

> The Lenya team seem a more willing to work *with* us on integrating 
> Forrest and Daisy. I have discussed the Daisy plugin on the Daisy dev 
> list, I offered to donate the code to them and work on it over there 
> since they have static only publication and books on their roadmap (both 
> of which can be achieved with Daisy + Forrest). However, they were not 
> interested, preferring insted to build their own system that was not 
> dependant on Forrest. Since I need the multiple input formats of Forrest 
> that leaves me on my own here :-(

the motivation for lenya is that forrest has traditionally been very 
strong on the publishing end of things, with ready to go pdf output, 
etc. this is something that we at lenya would have to reinvent 
eventually, were it not for forrest. fortunately, some committers have a 
foot in both communities, which should help with communication.

> Gregor says (in another reply on this thread) that a number of the Lenya 
> team are willing to help us out. The concern I have is how easy it is to 
> integrate Forrest as the publication engine. I've tried and failed in 
> the past, but now I've figured out the locationmap maybe it will be 
> easier. Furthermore Lenya has moved on a fair bit since my last attempt.

indeed. you were likely looking at 1.2 at the time, no? any integration 
should be based on trunk, which is much cleaner and easier to develop 
for (no more XSP / actions / ant task madness ;)

> I'm willing to work on either platform. I have a client using Daisy, 
> that is the only reason for my preference. If we have the excplicit help 
> of the Lenya team here then I would happily work with Lenya, although my 
> time will not be as copious as it would be for Daisy (at least till 
> Lenya convinces me it is better and I sell a Lenya + Forrest system to 
> someone ;-)

;)

> It is my thinking that since Forrest is used by many projects within 
> Apache we should take it upon ourselves to develop and test a system 
> intended to be used across Apache. When we agree on how to do this we 
> should announce this on Infrastructure@a.o and invite interested parties 
> to come and help. As long as we have enough people committed here then 
> it will not matter if (when?) they do not come.
> 
> I'm offering some of my time (post 0.7) to get this going.
> 
> Can we count on the Lenya team to assist?

maybe this is another stepping stone for the doco proposal.

i have emphasized elsewhere that we need to start with the low hanging 
fruit (the raw html view seems a good start), while keeping the doco 
goals in mind.

-gregor

Re: [PROPOSAL] A CMS for our Docs

[Thorsten Scherler <th...@apache.org>]

On Mon, 2005-06-06 at 16:12 +0100, Ross Gardler wrote:
<snip/>
> 
> I'm offering some of my time (post 0.7) to get this going.
> 
> Can we count on the Lenya team to assist?
> 
> Thorsten, do you still need to create the Forrest Lenya integration? Can 
> we count on some of your time for that part of it?

Yes, I just wanted to state that I am not the only one in lenya-land
that is willing to help. 

If it would have been like this I wouldn't want to be in the situation
you described:
> If we go for Lenya instead then we will have to rely on Thorsten to
get 
> it up and running and do any modifications/integration we need 
> (hopefully my work on the Locationmap and Daisy integration will help
here).

I do not like that a community depends on one person (too much
pressure). It is better when the two communities make it work together.

Count on me in trying to help where I can!

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Ross Gardler wrote:
> 
>>Over at Cocoon they are starting to use Daisy for their docs. I propose 
>>we do the same.
> 
> 
> I have too many questions at this stage.
> 
> How will the changed content get back into our SVN?

For development, it doesn't. Daisy is fully version controlled (and I 
think Lenya is). For publishing we do just as we are doing now.

> How is the workflow managed to get the content reviewed
> and then published onto the website? At the moment we
> do have a workflow of sorts.

Any registered user can edit. Only committers can publish. The Forrest 
generated site is only created from published changes.

In other words, the same workflow as at present but we replace the edit 
document/create patch/submit patch/review patch/apply patch process with 
edit document/review edit/publish edit process.

> I also agree with Ferdinand. We would need a structure to
> add these docs, or we end up with the un-manageable mess
> that they call Wiki.

The idea is that the CMS is freeform like a wiki, but the published docs 
only come from an Forrest generated site. In other words, we use the 
Wiki to allow anyone to add content/edit content. We optimise the wiki 
for the editors of content (as opposed to the users of content), that is 
committers and technical users will likely use the Wiki as the primary 
souce of documentation. Whilst users will use the published website.

The published docs are managed using Forrest. Only those documents that 
are of sufficient quality make it into the published docs that appear in 
our distributions and on our website.

In other words, we have the chaos of constantly evolving docs under the 
surface, on the surface we have nice ordered, version controlled and 
managed publications for our users. The migration path between the two 
is the close attention to detali of the review process.

> Will we see sensible diffs, so that the committers can
> oversee the content or do we get the voluminous diffs
> like wiki where you cannot see what has been changed?
> e.g. most paragraphs are one long line, so diffs are useless.

Yes (at least for Daisy, don't know about Lenya). You can play around by 
looking at the versions on Daisy home page at CocoonDev.org 
http://www.cocoondev.org/daisy/index/versions.html

> Who will be able to add content? Anyone? Do they need to
> be a committer? Do they need to be on forrest-dev?

My proposal is:

1) any visitor can add comments (see Comments link at bottom of 
http://www.cocoondev.org/daisy/index.html)

2) any registered visitor can make edits, but their edits are not 
published automaticall. People can self register but an email address 
and confirmation email is used so we can tackle spammers

3) any committer can publish edits

4) change emails will be sent to our existing commit email list 
(although they can be sent to individual users)

If we wanted a tighter control we can, of course have it, i.e. only 
committers able to edit. But that would make it *harder* for 
non-committers to contribute.


> Are the contributions assigned copyright to ASF?

We are currently discussing this over at Cocoon, the position seems to 
be settling on:


--- start of mail copied from Cocoon-dev ---

 > We can consider that a CLA is needed for "document committers" as 
they control official (i.e. published) docs,


+1

 > whereas "document contributors" are considered like people 
contributing wiki pages and bugzilla patches, and implicitely accept 
their contributions to be used by document committers under the ASL. A 
way to ensure people don't miss this is a checkbox in the registration 
screen stating "I accept my contributions to be used, modified or even 
trashed by the documentation committers according to ASL 2.0".


We could always add such verbiage to the registration screen, but I 
would prefer not to do this in Daisy-proper. The registration form is 
just a CForms form so that shouldn't be too hard - it's just something 
we should remember when upgrading Daisy.


--- end of copied mail ---

> I actually far prefer the current process where people
> need to send patches. That way they get reviewed by a committer.

In this approach all I am proposing is we make it easier for people to 
submit patches. I am not proposing that we remove the review stage, we 
still have:

edit -> draft -> review -> public/reject

> Who will manage this Daisy installation? We cannot be stuck
> with one person who knows a bit about it. We would need a
> management plan. Same applies if we use Lenya.

The Lenya team seem a more willing to work *with* us on integrating 
Forrest and Daisy. I have discussed the Daisy plugin on the Daisy dev 
list, I offered to donate the code to them and work on it over there 
since they have static only publication and books on their roadmap (both 
of which can be achieved with Daisy + Forrest). However, they were not 
interested, preferring insted to build their own system that was not 
dependant on Forrest. Since I need the multiple input formats of Forrest 
that leaves me on my own here :-(

Gregor says (in another reply on this thread) that a number of the Lenya 
team are willing to help us out. The concern I have is how easy it is to 
integrate Forrest as the publication engine. I've tried and failed in 
the past, but now I've figured out the locationmap maybe it will be 
easier. Furthermore Lenya has moved on a fair bit since my last attempt.

I'm willing to work on either platform. I have a client using Daisy, 
that is the only reason for my preference. If we have the excplicit help 
of the Lenya team here then I would happily work with Lenya, although my 
time will not be as copious as it would be for Daisy (at least till 
Lenya convinces me it is better and I sell a Lenya + Forrest system to 
someone ;-)

> I find this very alarming. Some people at Infrastructure are
> trying to get a cross-project environment established for managing
> documentation tools and site-building. All PMCs were asked to
> join and discuss this. Some people have, but mainly the process
> has stalled again.
> 
> Instead we see projects like Cocoon rushing off to do their
> own thing. Now we will get duplicate instances of Daisy/Forrest.

It is my thinking that since Forrest is used by many projects within 
Apache we should take it upon ourselves to develop and test a system 
intended to be used across Apache. When we agree on how to do this we 
should announce this on Infrastructure@a.o and invite interested parties 
to come and help. As long as we have enough people committed here then 
it will not matter if (when?) they do not come.

I'm offering some of my time (post 0.7) to get this going.

Can we count on the Lenya team to assist?

Thorsten, do you still need to create the Forrest Lenya integration? Can 
we count on some of your time for that part of it?

> Sorry, i am not trying to be obstructive, just that i see too
> many unanswered issues.

I understand. I've just had these same discussions (minus the infra@a.o 
part) over at Cocoon so most of these issues have been discussed and 
answered from the Cocoon perspective. Of course, that may be different 
from the Forrest perspective.

Ross

Re: [PROPOSAL] A CMS for our Docs

[Ferdinand Soethe <sa...@soethe.net>]

David Crossley wrote:

> I have another issue with being forced to do all editing via a
> web interface. With the current method of editing the source using
> whatever text-editor/xml-editor, i can be much more productive.
> I use UNIX tools like find and grep to search for certain occurences
> of strings (like when we had to replace all mentions of src/core/context).
> I can also edit a number of documents simultaneously.

These and other considerations make me think that I'd be happy to give
this a try on the understanding that it is very experimental and
there will be no expectations for this to become the production
documentation system unless these issues are addressed.

--
Ferdinand Soethe

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[Thorsten Scherler <th...@apache.org>]

On Tue, 2005-06-07 at 16:12 -0400, Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
> > Excellent. I think I can try and summarise this thread and lay out a 
> > course of action.
> > 
> > a) The Lenya team host a version of Lenya in their Zone for the use of 
> > Forrest (whether this means a separate instance or a publication within 
> > your own documentation instance is up to you).
> > 
> > b) Forrest work on the static publication part (locationmap + views + 
> > forrestbot)
> > 
> > c) We get Lenya writing to SVN in order to allow people to use their 
> > preferred tools to edit rather than be forced to use a web interface
> > 
> > d) we experiment in order to find the correct access rights and 
> > publishing workflow
> > 
> > e) we take this solution to infra@a.o as a potential apache wide effort
> > 
> > Does this sound OK?
> > 
> > Ross
> 
> +1
> 
> lenya devs?
> 

+2 (for lenya and forrest) ;-)

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Michael Wechner wrote:

> Well, I think Andreas should. If we want to get started then we should 
> start with
> people involved from the very beginning.

absolutely

> Well, maybe it would help if we could organize a "Sprint" over IRC.

ok

> I am bit confused who is actually going to work now on the search task, 
> because
> I got/saw various requests, e.g. Robert Goene, Greg Lee, ...

the best proposal will be selected.

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

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[Michael Wechner <mi...@wyona.com>]

Gregor J. Rothfuss wrote:

> Michael Wechner wrote:
>
>
>> +1 whereas I would mention that in order to do so we could start a 
>> "Lenya Forrest publication" within the Lenya sandbox
>>
>> http://svn.apache.org/repos/asf/lenya/sandbox/
>
>
> andreas already started, but hasnt checked it in yet.


Well, I think Andreas should. If we want to get started then we should 
start with
people involved from the very beginning.

>
>
> speaking of sandbox, i think it would be good if you commited your 
> nutch experiments there to help the summer of code participants


there is no real code which would make sense for Lenya yet, just 
experience and ideas I was collecting, but which I was to turn into real 
code ;-)

Well, maybe it would help if we could organize a "Sprint" over IRC.

I am bit confused who is actually going to work now on the search task, 
because
I got/saw various requests, e.g. Robert Goene, Greg Lee, ...

Maybe someone can enlighten me ;-)

Thanks

Michi

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


-- 
Michael Wechner
Wyona Inc.  -   Open Source Content Management   -   Apache Lenya
http://www.wyona.com                      http://lenya.apache.org
michael.wechner@wyona.com                        michi@apache.org


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

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Michael Wechner wrote:


> +1 whereas I would mention that in order to do so we could start a 
> "Lenya Forrest publication" within the Lenya sandbox
> 
> http://svn.apache.org/repos/asf/lenya/sandbox/

andreas already started, but hasnt checked it in yet.

speaking of sandbox, i think it would be good if you commited your nutch 
experiments there to help the summer of code participants

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

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[Michael Wechner <mi...@wyona.com>]

Gregor J. Rothfuss wrote:

> Ross Gardler wrote:
>
>> Excellent. I think I can try and summarise this thread and lay out a 
>> course of action.
>>
>> a) The Lenya team host a version of Lenya in their Zone for the use 
>> of Forrest (whether this means a separate instance or a publication 
>> within your own documentation instance is up to you).
>>
>> b) Forrest work on the static publication part (locationmap + views + 
>> forrestbot)
>>
>> c) We get Lenya writing to SVN in order to allow people to use their 
>> preferred tools to edit rather than be forced to use a web interface
>>
>> d) we experiment in order to find the correct access rights and 
>> publishing workflow
>>
>> e) we take this solution to infra@a.o as a potential apache wide effort
>>
>> Does this sound OK?
>>
>> Ross
>
>
> +1
>
> lenya devs?


+1 whereas I would mention that in order to do so we could start a 
"Lenya Forrest publication" within the Lenya sandbox

http://svn.apache.org/repos/asf/lenya/sandbox/

WDYT?

Michi

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


-- 
Michael Wechner
Wyona Inc.  -   Open Source Content Management   -   Apache Lenya
http://www.wyona.com                      http://lenya.apache.org
michael.wechner@wyona.com                        michi@apache.org


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

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[Thorsten Scherler <th...@apache.org>]

On Tue, 2005-06-07 at 16:12 -0400, Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
> > Excellent. I think I can try and summarise this thread and lay out a 
> > course of action.
> > 
> > a) The Lenya team host a version of Lenya in their Zone for the use of 
> > Forrest (whether this means a separate instance or a publication within 
> > your own documentation instance is up to you).
> > 
> > b) Forrest work on the static publication part (locationmap + views + 
> > forrestbot)
> > 
> > c) We get Lenya writing to SVN in order to allow people to use their 
> > preferred tools to edit rather than be forced to use a web interface
> > 
> > d) we experiment in order to find the correct access rights and 
> > publishing workflow
> > 
> > e) we take this solution to infra@a.o as a potential apache wide effort
> > 
> > Does this sound OK?
> > 
> > Ross
> 
> +1
> 
> lenya devs?
> 

+2 (for lenya and forrest) ;-)

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)


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

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> Excellent. I think I can try and summarise this thread and lay out a 
> course of action.
> 
> a) The Lenya team host a version of Lenya in their Zone for the use of 
> Forrest (whether this means a separate instance or a publication within 
> your own documentation instance is up to you).
> 
> b) Forrest work on the static publication part (locationmap + views + 
> forrestbot)
> 
> c) We get Lenya writing to SVN in order to allow people to use their 
> preferred tools to edit rather than be forced to use a web interface
> 
> d) we experiment in order to find the correct access rights and 
> publishing workflow
> 
> e) we take this solution to infra@a.o as a potential apache wide effort
> 
> Does this sound OK?
> 
> Ross

+1

lenya devs?

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

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> Excellent. I think I can try and summarise this thread and lay out a 
> course of action.
> 
> a) The Lenya team host a version of Lenya in their Zone for the use of 
> Forrest (whether this means a separate instance or a publication within 
> your own documentation instance is up to you).
> 
> b) Forrest work on the static publication part (locationmap + views + 
> forrestbot)
> 
> c) We get Lenya writing to SVN in order to allow people to use their 
> preferred tools to edit rather than be forced to use a web interface
> 
> d) we experiment in order to find the correct access rights and 
> publishing workflow
> 
> e) we take this solution to infra@a.o as a potential apache wide effort
> 
> Does this sound OK?
> 
> Ross

+1

lenya devs?

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Nicola Ken Barozzi wrote:
> 
>>David Crossley wrote:
>>
>>>Ross Gardler wrote:
>>
>>...
>>
>>>>Does this sound OK?
>>>
>>>It sounds brilliant. 
>>
>>Indeed!
>>
>>
>>>The part that i like most is that each project
>>>is focussing on their own tools, we are not duplicating, and we are
>>>collaborating.
>>
>>David, it seems Ross cracked open the coconut [1] and we now have 
>>opensource nirvana. Cool beans! :-)
>>
>>[1] Since sayings are so different from place to place, I am inventing 
>>my own, so all will be equally disoriented ;-)
> 
> 
> Yes, i do get your drift (i.e. know what you mean).
> 
> Hey Ross, do coconut milk and Whiskey mix? If so then i'll buy you
> one or two at ApacheCon. If not, then still, name your poison.

I'm afraid I'm a bit of a snob [1] when it comes to whiskey - nothing 
but a splash of water in the best single malt available is all that will 
do. However, coconut water and rum, now that works well, is much 
cheaper, and I don't have to be snobbish about it ;-)

(incidentally, Nicola, I'm afraid I heard that saying in Trinidad - it 
refers to being totally parched in the sun with nothing to drink but 
Coconut Water, which can only be found in the green nuts, which are 40 
feet in the air, still on the palm trees.)

Ross

[1] For the non-English speakers you may need this, snob is not a common 
word, at least in the UK, anymore: 
http://dictionary.reference.com/search?q=snob

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Nicola Ken Barozzi wrote:
> David Crossley wrote:
> >Ross Gardler wrote:
> ...
> >>Does this sound OK?
> >
> >It sounds brilliant. 
> 
> Indeed!
> 
> >The part that i like most is that each project
> >is focussing on their own tools, we are not duplicating, and we are
> >collaborating.
> 
> David, it seems Ross cracked open the coconut [1] and we now have 
> opensource nirvana. Cool beans! :-)
> 
> [1] Since sayings are so different from place to place, I am inventing 
> my own, so all will be equally disoriented ;-)

Yes, i do get your drift (i.e. know what you mean).

Hey Ross, do coconut milk and Whiskey mix? If so then i'll buy you
one or two at ApacheCon. If not, then still, name your poison.

--David

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

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

David Crossley wrote:
> Ross Gardler wrote:
...
>>Does this sound OK?
> 
> It sounds brilliant. 

Indeed!

> The part that i like most is that each project
> is focussing on their own tools, we are not duplicating, and we are
> collaborating.

David, it seems Ross cracked open the coconut [1] and we now have 
opensource nirvana. Cool beans! :-)

[1] Since sayings are so different from place to place, I am inventing 
my own, so all will be equally disoriented ;-)

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

Re: [SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> Gregor J. Rothfuss wrote:
> >Ross Gardler wrote:
> >
> >>As mentioned I want to see the ability to work offline in the users 
> >>preferred tool (a requirement of my work on the Digital Divide). Maybe 
> >>we can make your wish come true eventually, the way I see it is we 
> >>need to make Lenya use SVN as a repository. But that will come much 
> >>later I am sure.
> >
> >indeed, that dovetails with the outline i posted at
> >
> >http://mail-archives.apache.org/mod_mbox/lenya-dev/200505.mbox/%3c4293FE22.3050000@apache.org%3e 
> 
> Excellent. I think I can try and summarise this thread and lay out a 
> course of action.
> 
> a) The Lenya team host a version of Lenya in their Zone for the use of 
> Forrest (whether this means a separate instance or a publication within 
> your own documentation instance is up to you).
> 
> b) Forrest work on the static publication part (locationmap + views + 
> forrestbot)
> 
> c) We get Lenya writing to SVN in order to allow people to use their 
> preferred tools to edit rather than be forced to use a web interface
> 
> d) we experiment in order to find the correct access rights and 
> publishing workflow
> 
> e) we take this solution to infra@a.o as a potential apache wide effort
> 
> Does this sound OK?

It sounds brilliant. The part that i like most is that each project
is focussing on their own tools, we are not duplicating, and we are
collaborating.

--David

[SUMMARY] Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
>> As mentioned I want to see the ability to work offline in the users 
>> preferred tool (a requirement of my work on the Digital Divide). Maybe 
>> we can make your wish come true eventually, the way I see it is we 
>> need to make Lenya use SVN as a repository. But that will come much 
>> later I am sure.
> 
> 
> indeed, that dovetails with the outline i posted at
> 
> http://mail-archives.apache.org/mod_mbox/lenya-dev/200505.mbox/%3c4293FE22.3050000@apache.org%3e 

Excellent. I think I can try and summarise this thread and lay out a 
course of action.

a) The Lenya team host a version of Lenya in their Zone for the use of 
Forrest (whether this means a separate instance or a publication within 
your own documentation instance is up to you).

b) Forrest work on the static publication part (locationmap + views + 
forrestbot)

c) We get Lenya writing to SVN in order to allow people to use their 
preferred tools to edit rather than be forced to use a web interface

d) we experiment in order to find the correct access rights and 
publishing workflow

e) we take this solution to infra@a.o as a potential apache wide effort

Does this sound OK?

Ross

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> As mentioned I want to see the ability to work offline in the users 
> preferred tool (a requirement of my work on the Digital Divide). Maybe 
> we can make your wish come true eventually, the way I see it is we need 
> to make Lenya use SVN as a repository. But that will come much later I 
> am sure.

indeed, that dovetails with the outline i posted at

http://mail-archives.apache.org/mod_mbox/lenya-dev/200505.mbox/%3c4293FE22.3050000@apache.org%3e

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

David Crossley wrote:
> Ross Gardler wrote:
> 
>>Ferdinand Soethe wrote:
>>
>>
>>>I still don't like the fact that it is online editing only but
>>>perhaps I'm the only one still on a dial up line ...
>>
>>I don't think you are the only one. Even if you are, many of us work 
>>while traveling, so it is still an issue.
> 
> 
> Until recently i was on dail-up, much of Australia still is.
> 
> I have another issue with being forced to do all editing via a
> web interface. With the current method of editing the source using
> whatever text-editor/xml-editor, i can be much more productive.
> I use UNIX tools like find and grep to search for certain occurences
> of strings (like when we had to replace all mentions of src/core/context).
> I can also edit a number of documents simultaneously.
> 
> However i know that most new people don't work that way, so i suppose
> that i will need to suffer the loss of such tools.

As mentioned I want to see the ability to work offline in the users 
preferred tool (a requirement of my work on the Digital Divide). Maybe 
we can make your wish come true eventually, the way I see it is we need 
to make Lenya use SVN as a repository. But that will come much later I 
am sure.

Ross

Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> Ferdinand Soethe wrote:
>
> >I still don't like the fact that it is online editing only but
> >perhaps I'm the only one still on a dial up line ...
> 
> I don't think you are the only one. Even if you are, many of us work 
> while traveling, so it is still an issue.

Until recently i was on dail-up, much of Australia still is.

I have another issue with being forced to do all editing via a
web interface. With the current method of editing the source using
whatever text-editor/xml-editor, i can be much more productive.
I use UNIX tools like find and grep to search for certain occurences
of strings (like when we had to replace all mentions of src/core/context).
I can also edit a number of documents simultaneously.

However i know that most new people don't work that way, so i suppose
that i will need to suffer the loss of such tools.

--David

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> edit ->> review changes -> publish/reject
> 
> I like the idea to trial run this for a while w/o touching the real
> docs. Seems like the best way to explore all the dimensions of this
> complex change.

+1

> I still don't like the fact that it is online editing only but
> perhaps I'm the only one still on a dial up line ...

I don't think you are the only one. Even if you are, many of us work 
while traveling, so it is still an issue.

Burrokeet has many users in the developing world (I started the project 
whilst living in Trinidad and Tobago). As a result one of our goals is 
to provide full offline editing for an online CMS system with Forrest as 
the publishing engine. However, I have to admit, it is fairly low on the 
todo list. I'd be glad to work with Lenya to solve this problem once we 
have something up and running and the initial integration stuff is done.

>>Furthermore, I am not talking about open editing like wikipedia (which
> 
> 
> No, but I'd like to raise this as one of the questions here. Do we
> really need to maintain tight control or would something like wikipedia work
> for us as well?

Lets return to that when we have a system in place. I know many will 
resist totally open access, Spam is a real pain.

Ross

Re: [PROPOSAL] A CMS for our Docs

[Ferdinand Soethe <sa...@soethe.net>]

edit ->> review changes -> publish/reject

I like the idea to trial run this for a while w/o touching the real
docs. Seems like the best way to explore all the dimensions of this
complex change.

Designing the outline for our manual would be great to thoroughly test
this.

I still don't like the fact that it is online editing only but
perhaps I'm the only one still on a dial up line ...

> Furthermore, I am not talking about open editing like wikipedia (which

No, but I'd like to raise this as one of the questions here. Do we
really need to maintain tight control or would something like wikipedia work
for us as well?

--
Ferdinand Soethe

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> I guess the whole issue might come down to a question of philosophy.
> 
> And while I have fears for our content, I must admit that some wikis
> such as Wikipedia have evolved into high quality content without a
> controlling hand.
> 
> What seems hard to achieve will be to maintain a bit of control. We
> can either go for an open system or stick with the old, or use daisy
> with as much control as the old system (but then where is the
> benefit)?

I agree with the intent of what you are saying, but it is not an open 
system or a closed system. I am proposing a step in between. See my 
other mail re workflow. We go from:

checkout svn -> edit -> generate patch -> submit patch -> review patch 
-> publish/reject

to

edit -> review changes -> publish/reject

Note that the last two stages (the control part) are the same. It is 
only the first stages (the ease of editing) that has changed.

Furthermore, I am not talking about open editing like wikipedia (which 
allows anonymous edits). I am talking about "controlled open" editing. 
That is you must register to be able to edit.

Ross

Re: [PROPOSAL] A CMS for our Docs

[Ferdinand Soethe <sa...@soethe.net>]

I guess the whole issue might come down to a question of philosophy.

And while I have fears for our content, I must admit that some wikis
such as Wikipedia have evolved into high quality content without a
controlling hand.

What seems hard to achieve will be to maintain a bit of control. We
can either go for an open system or stick with the old, or use daisy
with as much control as the old system (but then where is the
benefit)?

--
Ferdinand Soethe

Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Nicola Ken Barozzi wrote:
> David Crossley wrote:
> >Nicola Ken Barozzi wrote:
> >>David Crossley wrote:
> >>...
> >>>I find this very alarming. Some people at Infrastructure are
> >>>trying to get a cross-project environment established for managing
> >>>documentation tools and site-building. All PMCs were asked to
> >>>join and discuss this. Some people have, but mainly the process
> >>>has stalled again.
> >>
> >>Because it's discussion instead of DIY.
> >
> >Necessary discussion. The main issue was/is trying to solve how
> >ASF projects can conduct oversight of the content, how the tools
> >would get maintained, and oversight of the publishing process.
> >That is a requirement.
> 
> But it's not a requirement that experimentation stops in the meantime.

I agree.

> You have called this "alarming", I disagree.

My alarm is about duplication (multiplication) of effort.

> I would be alarmed if, once 
> the rules are decided, people would not want to follow them. But before 
> that, stopping things is only harmful.
> 
> As soon as new needs come out from site-dev, please relay them here, so 
> that we can make the system compliant with the requirements.

Sorry, i don't have the energy to be a go-between.

> >>>Instead we see projects like Cocoon rushing off to do their
> >>>own thing. Now we will get duplicate instances of Daisy/Forrest.
> >>
> >>I find it very constructive that people are rushing to make it work. 
> >>Consolidation can come later.
> >
> >Good in theory. In my OSS experience "consolidation" never happens.
> >People rush on to the next new thing.
> 
> In my -personal- experience, discussions rarely lead to action.

I know what you mean. I got sick of discussions and acted instead
to set up the forrestbot on brutus. Now that is gone because of
tangential infrastructure issues. I had to set it up all over again
at yet another temporary place in my home directory on our zone.
Some prior planning and discussion might have helped to have
a permanent home. Somehow we need to find the right mixture of
discussion and action. The holy grail of OSS.

--David

> How long have I talked about the locationmap? Have I ever done anything 
> concrete on it? How long has the Doco document been waiting? How much 
> time has passed since the first mail on repository@apache.org?
> 
> >>Would it be better just to see this as an experiment, and not (yet) 
> >>really move the docs there till we have a vote with a working system and 
> >>a plan?
> >
> >Perhaps we should start with a specific set of user-oriented
> >documents, and leave the core docs in the current system.
> 
> We can start using it as a "super wiki", I agree.
> 
> -- 
> Nicola Ken Barozzi                   nicolaken@apache.org
>             - verba volant, scripta manent -
>    (discussions get forgotten, just code remains)
> ---------------------------------------------------------------------

Re: [PROPOSAL] A CMS for our Docs

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

David Crossley wrote:
> Nicola Ken Barozzi wrote:
> 
>>David Crossley wrote:
>>...
>>>I find this very alarming. Some people at Infrastructure are
>>>trying to get a cross-project environment established for managing
>>>documentation tools and site-building. All PMCs were asked to
>>>join and discuss this. Some people have, but mainly the process
>>>has stalled again.
>>
>>Because it's discussion instead of DIY.
> 
> Necessary discussion. The main issue was/is trying to solve how
> ASF projects can conduct oversight of the content, how the tools
> would get maintained, and oversight of the publishing process.
> That is a requirement.

But it's not a requirement that experimentation stops in the meantime.

You have called this "alarming", I disagree. I would be alarmed if, once 
the rules are decided, people would not want to follow them. But before 
that, stopping things is only harmful.

As soon as new needs come out from site-dev, please relay them here, so 
that we can make the system compliant with the requirements.

>>>Instead we see projects like Cocoon rushing off to do their
>>>own thing. Now we will get duplicate instances of Daisy/Forrest.
>>
>>I find it very constructive that people are rushing to make it work. 
>>Consolidation can come later.
> 
> Good in theory. In my OSS experience "consolidation" never happens.
> People rush on to the next new thing.

In my -personal- experience, discussions rarely lead to action.

How long have I talked about the locationmap? Have I ever done anything 
concrete on it? How long has the Doco document been waiting? How much 
time has passed since the first mail on repository@apache.org?

>>Would it be better just to see this as an experiment, and not (yet) 
>>really move the docs there till we have a vote with a working system and 
>>a plan?
> 
> Perhaps we should start with a specific set of user-oriented
> documents, and leave the core docs in the current system.

We can start using it as a "super wiki", I agree.

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

Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Nicola Ken Barozzi wrote:
> David Crossley wrote:
> ...
> >I find this very alarming. Some people at Infrastructure are
> >trying to get a cross-project environment established for managing
> >documentation tools and site-building. All PMCs were asked to
> >join and discuss this. Some people have, but mainly the process
> >has stalled again.
> 
> Because it's discussion instead of DIY.

Necessary discussion. The main issue was/is trying to solve how
ASF projects can conduct oversight of the content, how the tools
would get maintained, and oversight of the publishing process.
That is a requirement.

> >Instead we see projects like Cocoon rushing off to do their
> >own thing. Now we will get duplicate instances of Daisy/Forrest.
> 
> I find it very constructive that people are rushing to make it work. 
> Consolidation can come later.

Good in theory. In my OSS experience "consolidation" never happens.
People rush on to the next new thing.

> Would it be better just to see this as an experiment, and not (yet) 
> really move the docs there till we have a vote with a working system and 
> a plan?

Perhaps we should start with a specific set of user-oriented
documents, and leave the core docs in the current system.

--David

Re: [PROPOSAL] A CMS for our Docs

[Ferdinand Soethe <sa...@soethe.net>]

Ross Gardler wrote:


> In other words with the locationmap our source documentation is no 
> longer limited to being on the local file system, nor is it limited from
> being from a single remote repository. We can go as far as to have every
> page come from a different source.

Thanks for explaining.

--
Ferdinand Soethe

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> Ross Gardler wrote:
> 
> 
>>Ahh, but that is the "smart" part of my proposal.
> 
> 
> Hey, are you saying there are sometimes not so smart parts in your
> proposals :-)

Well I think my recent fresh-site fix for raw HTML that completely 
removed the current 0.7 behaviour is a pretty good example of a dumb 
idea :-))

>>There is no need to
>>move existing docs if we don't want to. With the locationmap branch we
>>can use content form multiple locations.
> 
> 
> Can somebody put this in plain apprentice English for me pls ...

OK.

Imagine a Forrest site that has the following sections:

Developer Documentation
User Documentation
Official Plugins
3rd Party Plugins overview
3rd Party Skins overview

The content for each of these sections may come from (for example)

Dev Docs - existing docs in SVN
User Docs - new docs on the CMS
Official plugins - generated by the plugin system
3rd Party plugins overview - various 3rd party sites
3rd Party Skins overview - various 3rd party sites

In addition we may take the odd page from other sources. For example:

Creating a diff - from the SVN Book
Single Source Publishing - from Wikipedia (ignoring license issues)

etc. etc.

In other words with the locationmap our source documentation is no 
longer limited to being on the local file system, nor is it limited from 
being from a single remote repository. We can go as far as to have every 
page come from a different source.

site.xml looks just the same as normal and is used to define the URI 
space the user sees. A locationmap file is used to tell Forrest where to 
get a source file from. The location of the source file can be changed 
independently of the users urlspace.

If, at a later date we decide to consolidate on the CMS or revert to 
using SVN. No problem, use Forrest to generate the relevant format, 
place them in the CMS/SVN as appropriate and update the locationmap. The 
user URLspace is unchanged, but the source URLspace has changed.

If you want to know more about *how* rather than *what* then checkout 
the locationmap branch, do "forrest seed" and look at the locationmap 
sample.

Ross

Re: [PROPOSAL] A CMS for our Docs

[Ferdinand Soethe <sa...@soethe.net>]

Ross Gardler wrote:

> Ahh, but that is the "smart" part of my proposal.

Hey, are you saying there are sometimes not so smart parts in your
proposals :-)

> There is no need to
> move existing docs if we don't want to. With the locationmap branch we
> can use content form multiple locations.

Can somebody put this in plain apprentice English for me pls ...

> So what is currently in SVN
> stays there until we decide to move it.

> Like Nicola says "Consolodation can come later". We won't know what to
> consolodate on until we have experimented more.

Arg. I've done such jobs before and found it a pain ...


I'd rather we test this on a new and rather independent part of the
docs (such as the manual) to avoid this.

--
Ferdinand Soethe

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Nicola Ken Barozzi wrote:
> David Crossley wrote:
> ...
> 

...

> I find it very constructive that people are rushing to make it work. 
> Consolidation can come later.
> 
> Would it be better just to see this as an experiment, and not (yet) 
> really move the docs there till we have a vote with a working system and 
> a plan?

Ahh, but that is the "smart" part of my proposal. There is no need to 
move existing docs if we don't want to. With the locationmap branch we 
can use content form multiple locations. So what is currently in SVN 
stays there until we decide to move it.

Like Nicola says "Consolodation can come later". We won't know what to 
consolodate on until we have experimented more.

Ross

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Nicola Ken Barozzi wrote:

> I find it very constructive that people are rushing to make it work. 
> Consolidation can come later.

i see the site-dev@ list mostly for setting policy at this time, less so 
for development given the diverse nature of tools on that list (forrest, 
maven, anakia, htmlmake and who knows what else).

i would be very happy to go back to site-dev@ once we have a working 
prototype that makes progress towards the policy questions raised there.

> Would it be better just to see this as an experiment, and not (yet) 
> really move the docs there till we have a vote with a working system and 
> a plan?

sounds reasonable to me.

Re: [PROPOSAL] A CMS for our Docs

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

David Crossley wrote:
...
> I find this very alarming. Some people at Infrastructure are
> trying to get a cross-project environment established for managing
> documentation tools and site-building. All PMCs were asked to
> join and discuss this. Some people have, but mainly the process
> has stalled again.

Because it's discussion instead of DIY.

> Instead we see projects like Cocoon rushing off to do their
> own thing. Now we will get duplicate instances of Daisy/Forrest.

I find it very constructive that people are rushing to make it work. 
Consolidation can come later.

Would it be better just to see this as an experiment, and not (yet) 
really move the docs there till we have a vote with a working system and 
a plan?

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

Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Ross Gardler wrote:
> Over at Cocoon they are starting to use Daisy for their docs. I propose 
> we do the same.

I have too many questions at this stage.

How will the changed content get back into our SVN?

How is the workflow managed to get the content reviewed
and then published onto the website? At the moment we
do have a workflow of sorts.

I also agree with Ferdinand. We would need a structure to
add these docs, or we end up with the un-manageable mess
that they call Wiki.

Will we see sensible diffs, so that the committers can
oversee the content or do we get the voluminous diffs
like wiki where you cannot see what has been changed?
e.g. most paragraphs are one long line, so diffs are useless.

Who will be able to add content? Anyone? Do they need to
be a committer? Do they need to be on forrest-dev?

Are the contributions assigned copyright to ASF?

I actually far prefer the current process where people
need to send patches. That way they get reviewed by a committer.

Who will manage this Daisy installation? We cannot be stuck
with one person who knows a bit about it. We would need a
management plan. Same applies if we use Lenya.

I find this very alarming. Some people at Infrastructure are
trying to get a cross-project environment established for managing
documentation tools and site-building. All PMCs were asked to
join and discuss this. Some people have, but mainly the process
has stalled again.

Instead we see projects like Cocoon rushing off to do their
own thing. Now we will get duplicate instances of Daisy/Forrest.

Sorry, i am not trying to be obstructive, just that i see too
many unanswered issues.

--David

Re: [PROPOSAL] A CMS for our Docs

[Ferdinand Soethe <sa...@soethe.net>]

Ross Gardler wrote:

> Ferdinand Soethe wrote:

>> As far as new docs are concerned, it would be nice if we could provide
>> a basic structure for new docs to snap in. The ability to freely add
>> new docs in my experience leads to a maze rather then a web of
>> documentation and is not soo desirable or helpful.

> Are you volunteering? I'm not, but I agree with your intent.

I'd certainly help. Although - given my addiction to frequent kayaking
trips - this is really a task for a group who will back up one
another. Unless you are planning to implement a release workflow so
that new additions can be checked as time permits.

>> - can we still write documents off-line and upload them into the
>>   daisy-system? If so, what input format would be required?

> The yes is you could write the content in your favourite editor then
> paste it into the the editor. However, this would walk all over the 
> version control stuff in Daisy. I you need to work this way then you
> need SVN.

This is definitely a weak point as it excludes people who have no
cheap permanent internet connection.

> It wouldn't be a problem for new documents though.

Might be good enough. The only remaining problem are problems requiring
extensive editing. I'd not be happy to have to do that online.

I think we need to think some more about this ...

--
Ferdinand Soethe

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Ferdinand Soethe wrote:
> I think this is worth considering.
> 
> It certainly would make corrections and minor adjustments a lot
> easier.
> 
> As far as new docs are concerned, it would be nice if we could provide
> a basic structure for new docs to snap in. The ability to freely add
> new docs in my experience leads to a maze rather then a web of
> documentation and is not soo desirable or helpful.

Are you volunteering? I'm not, but I agree with your intent.

> I also have some questions regarding this
> 
> - can we still write documents off-line and upload them into the
>   daisy-system? If so, what input format would be required?

Yes, and no.

The yes is you could write the content in your favourite editor then 
paste it into the the editor. However, this would walk all over the 
version control stuff in Daisy. I you need to work this way then you 
need SVN.

It wouldn't be a problem for new documents though.

It is a goal of the Burrokeet project to integrate Daisy in such a way 
that offline editing of repositories. However, it is quite a long way 
down the todo list right now.

> - does daisy offer spell checking online?

Not yet, it is on the roadmap, but not scheduled for a particular 
release yet.

Ross

Re: [PROPOSAL] A CMS for our Docs

[Ferdinand Soethe <sa...@soethe.net>]

I think this is worth considering.

It certainly would make corrections and minor adjustments a lot
easier.

As far as new docs are concerned, it would be nice if we could provide
a basic structure for new docs to snap in. The ability to freely add
new docs in my experience leads to a maze rather then a web of
documentation and is not soo desirable or helpful.

I also have some questions regarding this

- can we still write documents off-line and upload them into the
  daisy-system? If so, what input format would be required?

- does daisy offer spell checking online?

--
Ferdinand Soethe

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Torsten Schlabach wrote:
> Thorsten Scherler wrote:
>  > Generally I would favor lenya over daisy but I will not be in the way
>  > of daisy either because I do not have the time to give the requested
>  > support for lenya.
> 
> I might be able to help! Depending on what the plan is.
> 

Cool, Cocoon is using Daisy and I need the Daisy integration so I'll be 
working on that. Your help will be very much aprrecitated.

My intention is to have most of the work downe in the Locationmap 
additions so that the actual repositor(y)(ies) used is only a matter of 
a few config settings.

Ross

Re: [PROPOSAL] A CMS for our Docs

[Torsten Schlabach <ts...@apache.org>]

Thorsten Scherler wrote:
 > Generally I would favor lenya over daisy but I will not be in the way
 > of daisy either because I do not have the time to give the requested
 > support for lenya.

I might be able to help! Depending on what the plan is.

Regards,
Torsten

Thorsten Scherler schrieb:
> On Mon, 2005-06-06 at 12:28 +0100, Ross Gardler wrote:
> 
>>Nicola Ken Barozzi wrote:
>>
>>>Ross Gardler wrote:
>>>
>>>
>>>>Over at Cocoon they are starting to use Daisy for their docs. I 
>>>>propose we do the same.
>>>
>>>
>>>I would prefer to use Lenya, as Cocoon will already stress test the 
>>>Daisy integration aplenty. On the other hand, I have no will nor time to 
>>>help, and Daisy is good too.
>>>
>>>+0 for the proposal
>>>+0 for Lenya
>>><applause> for the one who sets up either system.
>>
>>I proposed Daisy because I am familiar with it and we are able to 
>>publish documents from it using Forrest. However, I am not against using 
>>Lenya instead.
>>
>>I'm familiar with Daisy and what it can do. I much prefer it's design 
>>and find it much easier to customise.
>>
>>If we go for Lenya instead then we will have to rely on Thorsten to get 
>>it up and running and do any modifications/integration we need 
>>(hopefully my work on the Locationmap and Daisy integration will help here).
>>
>>So I am +0 for Lenya, +1 for Daisy (in that I can set Daisy up).
>>
>>If Thorsten wants to set up Lenya I will be glad to accept the 
>>opportunity to learn.
>>
> 
> 
> Just a quick remark on that, I guess gregor, andreas, michi and other
> would happily help us with that, but my time is too limited to actually
> being a big help for doing it. 
> 
> Generally I would favor lenya over daisy but I will not be in the way of
> daisy either because I do not have the time to give the requested
> support for lenya. 
> 
> salu2

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[David Crossley <cr...@apache.org>]

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
> >OK, along the same theme of quick hacks I've put a simple demo together 
> >for you. To see it you need to checkout the locationmap_branch of 
> >Forrest. Seed a fresh site, do "forrest run" and look at the locaitonmap 
> >sample (last item in the samples menu).
> >
> >There are a few things to note here:
> >
> >Lenya uses tables to do layout of the page (shame on you). As a result 
> >you can see the table borders (this is a stylesheet issue).
> 
> yeah i know :) will be fixed shortly.
> 
> >There are no headings in the page you provide as a demo, so no sections 
> >are defined, so no TOC. This has highlighted a bug in our skin that 
> >places the TOC horizontal rules in place, even if no TOC is present.
> 
> we are having some publishing issues related to jdk 1.5, so the demo is 
> kinda lame, i know. hopefully i can soon demo a full fledged site ;)

Are you saying that there is only Java 1.5 on the zones machine or
that you really want to use 1.5 instead? If the former, then maybe
ask Infrastructure to add jdk 1.4 to the global zone.

--David

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:

...

>> Although a long way from perfect I hope this is enough to illustrate 
>> how to do the integration (see I told you it was easy with the 
>> locationmap :-))
> 
> 
> thanks for this, this definitely helps.

I've rejoined the Lenya dev list so will try and get to grips with 
things there. I cannot offer my undivided attention, but I am working on 
the Locationmap stuff actively so yell if you need help.

Ross

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> OK, along the same theme of quick hacks I've put a simple demo together 
> for you. To see it you need to checkout the locationmap_branch of 
> Forrest. Seed a fresh site, do "forrest run" and look at the locaitonmap 
> sample (last item in the samples menu).
> 
> There are a few things to note here:
> 
> Lenya uses tables to do layout of the page (shame on you). As a result 
> you can see the table borders (this is a stylesheet issue).

yeah i know :) will be fixed shortly.

> There are no headings in the page you provide as a demo, so no sections 
> are defined, so no TOC. This has highlighted a bug in our skin that 
> places the TOC horizontal rules in place, even if no TOC is present.

we are having some publishing issues related to jdk 1.5, so the demo is 
kinda lame, i know. hopefully i can soon demo a full fledged site ;)

> The image does not work yet. There are two reasons for this:
> 
> a) it is an absolute URL and we need to rewrite these so that the 
> locationmap will match them
> 
> b) I've not enabled the locationmap for resources yet
> 
> For a) you could have a look at the Daisy plugin (in the whiteboard of 
> the locationmap branch). This provides pre and post filters to documents 
> retrieved from daisy for doing things like URL rewriting and adding 
> additional content (such as a disclaimer that the content is from a 
> remote site, a license, a link back to the edit page for the document, 
> that kind of thing). I suspect that the way I am doing this stuff will 
> change when I find the time to get to grips with views.

will do when i get a chance. thorsten? ;)

> Although a long way from perfect I hope this is enough to illustrate how 
> to do the integration (see I told you it was easy with the locationmap :-))

thanks for this, this definitely helps.

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> Yes, this is my biggest complaint about Daisy right now. Every single 
> change gets the same "priority" in the version management system. So if 
> I change a single letter, it create a new version and generates a commit 
> mail.
> 
> Wiki's deal with this by allowing you to mark something as a minor edit. 
> But that doesn't work in my experience, people just don't bother (try 
> subscribing to an active Wikipedia page for example).

indeed. i was hoping that the frequency would be reduced by only storing 
approved versions in SVN.

> However, Nicola points out that if a committer creates a document 
> directly in SVN it will not be present in the Lenya repo for editing. 
> Lenya will have to address this, in the medium term, in some way. I'm 
> not familiar enough with Lenya to make any suggestions though.

doug chestnut is working on WebDAV integration right now, which might 
help with this. as a start, people could do their docs offline, and then 
  add them to lenya through webdav. lenya then takes care of checking 
them in to the lenya revision control, doing workflow initialization, 
and whatever else is required to make a document editable in lenya.

this wouldn't solve checking into SVN yet, but it might be a reasonable 
start. at least you could edit docs offline with your favorite tools.

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

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> Yes, this is my biggest complaint about Daisy right now. Every single 
> change gets the same "priority" in the version management system. So if 
> I change a single letter, it create a new version and generates a commit 
> mail.
> 
> Wiki's deal with this by allowing you to mark something as a minor edit. 
> But that doesn't work in my experience, people just don't bother (try 
> subscribing to an active Wikipedia page for example).

indeed. i was hoping that the frequency would be reduced by only storing 
approved versions in SVN.

> However, Nicola points out that if a committer creates a document 
> directly in SVN it will not be present in the Lenya repo for editing. 
> Lenya will have to address this, in the medium term, in some way. I'm 
> not familiar enough with Lenya to make any suggestions though.

doug chestnut is working on WebDAV integration right now, which might 
help with this. as a start, people could do their docs offline, and then 
  add them to lenya through webdav. lenya then takes care of checking 
them in to the lenya revision control, doing workflow initialization, 
and whatever else is required to make a document editable in lenya.

this wouldn't solve checking into SVN yet, but it might be a reasonable 
start. at least you could edit docs offline with your favorite tools.

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Gregor J. Rothfuss wrote:

> doug chestnut is working on WebDAV integration right now, which might 
> help with this. as a start, people could do their docs offline, and then 
>  add them to lenya through webdav. lenya then takes care of checking 
> them in to the lenya revision control, doing workflow initialization, 
> and whatever else is required to make a document editable in lenya.
> 
> this wouldn't solve checking into SVN yet, but it might be a reasonable 
> start. at least you could edit docs offline with your favorite tools.

http://issues.apache.org/bugzilla/attachment.cgi?id=15359&action=view

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Gregor J. Rothfuss wrote:
> Nicola Ken Barozzi wrote:
> 
>> Hmmm... wait a second. Let's say that I add myfile.xml to SVN... can 
>> it be later edited in Lenya? 
> 
> 
> that could be made to work. needs some initialization though, because 
> lenya creates worfklow histories etc for each document.

Nicola raises an important point, we need to address this.

>> Also, is it good to bypass all the publishing workflow?
> 
> 
> presumably, a committer knows what they are doing,

Furthermore, we are not really bypassing the publishing workflow since 
it is only committers who can publish to the final docs anyway. They are 
just bypassing the initial review cycle.

It's the same as the the current code contribution workflow:

Non committers:

edit code -> submit patch -> committer review -> apply patch -> 
community review

committers:

edit code -> apply patch -> community review

>> What is confusing me is the presence of two repos, and editing made 
>> possible on the publishing one. Please excuse my ignorance, but can't 
>> Lenya use just SVN as a repo?
> 
> 
> that is definitely a goal, too. it currently can't, yet. another point 
> for two repos is that you dont want every little diff in SVN, just the 
> ones that are being approved. lenya saves a version for every edit 
> cycle, and there can be an unlimited number of those before someone 
> decides to submit it for approval.

Yes, this is my biggest complaint about Daisy right now. Every single 
change gets the same "priority" in the version management system. So if 
I change a single letter, it create a new version and generates a commit 
mail.

Wiki's deal with this by allowing you to mark something as a minor edit. 
But that doesn't work in my experience, people just don't bother (try 
subscribing to an active Wikipedia page for example).

However, Nicola points out that if a committer creates a document 
directly in SVN it will not be present in the Lenya repo for editing. 
Lenya will have to address this, in the medium term, in some way. I'm 
not familiar enough with Lenya to make any suggestions though.

Ross

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Nicola Ken Barozzi wrote:

> Hmmm... wait a second. Let's say that I add myfile.xml to SVN... can it 
> be later edited in Lenya? 

that could be made to work. needs some initialization though, because 
lenya creates worfklow histories etc for each document.

> Also, is it good to bypass all the publishing 
> workflow?

presumably, a committer knows what they are doing,

> What is confusing me is the presence of two repos, and editing made 
> possible on the publishing one. Please excuse my ignorance, but can't 
> Lenya use just SVN as a repo?

that is definitely a goal, too. it currently can't, yet. another point 
for two repos is that you dont want every little diff in SVN, just the 
ones that are being approved. lenya saves a version for every edit 
cycle, and there can be an unlimited number of those before someone 
decides to submit it for approval.

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

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

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
>> -------- committers ------------. .---- Non-Committers ---
>>                                 | |
>>                                 | |
>> +---------+    +---------+    +-------+    +----------+
>> | Forrest |<---| SVN     |<---| Lenya |--->|Lenya Repo|
>> +---------+    +---------+    +-------+    +----------+
>>                    .               /|\          |
>>                   /|\               |___________|
>>                    |
>>               +------------+
>>               | Committers |
>>               | Tools      |
>>               +------------+
> 
...
>> In this model there is the potential for conflict between edits in the 
>> Lenya Repo that have not yet been published and edits by committers 
>> working directly with SVN. In my view this is no more of a problem 
>> than the potential for conflicts between in progress edits on 
>> individual checked out copies of SVN, or at least if we stay on top of 
>> publishing changes to Lenya this should be the case. What do others 
>> think about this?
> 
> lenya uses pessimistic offline locking. with svn 1.2, there is now lock 
> support, so this should'nt be a problem.

Hmmm... wait a second. Let's say that I add myfile.xml to SVN... can it 
be later edited in Lenya? Also, is it good to bypass all the publishing 
workflow?

What is confusing me is the presence of two repos, and editing made 
possible on the publishing one. Please excuse my ignorance, but can't 
Lenya use just SVN as a repo?

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

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> -------- committers ------------. .---- Non-Committers ---
>                                 | |
>                                 | |
> +---------+    +---------+    +-------+    +----------+
> | Forrest |<---| SVN     |<---| Lenya |--->|Lenya Repo|
> +---------+    +---------+    +-------+    +----------+
>                    .               /|\          |
>                   /|\               |___________|
>                    |
>               +------------+
>               | Committers |
>               | Tools      |
>               +------------+
> 

nice diagram!

> So non-committers edit freely in the Lenya repo but cannot publish 
> within Lenya. When an edit is reviewed and published by a committer, 
> that change is propagated to SVN.
> 
> Committers can use whatever tool they prefer, working directly with SVN 
> or with Lenya.
> 
> In this model there is the potential for conflict between edits in the 
> Lenya Repo that have not yet been published and edits by committers 
> working directly with SVN. In my view this is no more of a problem than 
> the potential for conflicts between in progress edits on individual 
> checked out copies of SVN, or at least if we stay on top of publishing 
> changes to Lenya this should be the case. What do others think about this?

lenya uses pessimistic offline locking. with svn 1.2, there is now lock 
support, so this should'nt be a problem.


>> What do you think about this architecture, is it really needed? I'm 
>> not sure it's *that* different from asking Lenya to get the docs for 
>> us, as it's a simple URL request. Basically, Lenya would be doing what 
>> the SLIDE+LENYA combo does in the graphic, thus removing the need for 
>> DASL that only Slide at Apache has, making us use Subversion.
> 
> 
> I agree. The above is very similar to the original proposal minus the 
> mail workflow)

+1

>> What remains to do are diffs.
> 
> 
> The above gives us diffs of published documents but Lenya does not 
> publish good diffs of edits of its own repository. However, the Lenya 
> community are addressing this (I have a Summer of Code applicant who has 
> expressed interest in this aspect and a couple of Lenya devs have agreed 
> to co-mentor).

exactly.

>> I'm not sure that the mail workflow is something we really need ATM. 
>> IMHO just adding editors that cannot publish, along with diffs, is 
>> something that gives us enough control.
> 
> 
> I agree. The mail workflow is a nice have. It would be wonderful to be 
> able to publish simple changes by replying to a mail as is proposed in 
> [1]. But  we can manage with the diffs and a link to an URL to publish 
> the changes, and another to reject the changes.

the mail workflow becomes important once there is such a huge amount of 
changes that approval needs to be super-efficient. i'm glad if we get to 
a level where we have such problems ;)

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

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Thorsten Scherler <th...@apache.org>]

On Wed, 2005-06-08 at 11:11 +0100, Ross Gardler wrote:
> Thorsten Scherler wrote:
> > On Wed, 2005-06-08 at 10:08 +0100, Ross Gardler wrote:
> > 
> >>Thorsten Scherler wrote:
> >>
> 
> ...
> 
> >>>:) Yeah, that is simply a contract that contains a link to
> >>>daisy/lenya/anyOtherCms edit page. I will make an example as soon I have
> >>>updated the locationmap branch on my harddrive and understood all the
> >>>mails around the topic. ;-)
> >>
> >>I'll do you a deal, if you create the contract with an example linking 
> >>to the demo page Gregor created for us, I'll move it into the 
> >>Locationmap branch and make it work with that the locationmap stuff.
> >>
> > 
> > 
> > I would like to set up that branch to work by default with views if that
> > is alright with you?
> 
> Yes, that is just fine. I intend to use views to its fullest there.
> 

:) ok

+1 

> >>i.e. just hard code the URLs in the contract, I'll do what is necessary 
> >>with locationmap.
> > 
> > 
> > No, there is no need to hardcode urls in the contracts. We can use the
> > same mechanism we used in the feeder-contract (remember the example you
> > brought up as enhancement of the view design). 
> 
> Yes, but the URL has to come from the locationmap. What I meant was you 
> throw together a simple demo and I'll add the locationmap stuff. Of 
> course, if you want to use this as an opportunity to get to grips with 
> the locationmap I'll answer your questions instead of doing it.
> 

I will give it a go after the how-to. I need to get into that stuff to
help lenya, forrest and the businessHelper plugin. ;-)

...and do not worry, I know your eMail address. ;-) lol

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Thorsten Scherler wrote:
> On Wed, 2005-06-08 at 10:08 +0100, Ross Gardler wrote:
> 
>>Thorsten Scherler wrote:
>>

...

>>>:) Yeah, that is simply a contract that contains a link to
>>>daisy/lenya/anyOtherCms edit page. I will make an example as soon I have
>>>updated the locationmap branch on my harddrive and understood all the
>>>mails around the topic. ;-)
>>
>>I'll do you a deal, if you create the contract with an example linking 
>>to the demo page Gregor created for us, I'll move it into the 
>>Locationmap branch and make it work with that the locationmap stuff.
>>
> 
> 
> I would like to set up that branch to work by default with views if that
> is alright with you?

Yes, that is just fine. I intend to use views to its fullest there.

>>i.e. just hard code the URLs in the contract, I'll do what is necessary 
>>with locationmap.
> 
> 
> No, there is no need to hardcode urls in the contracts. We can use the
> same mechanism we used in the feeder-contract (remember the example you
> brought up as enhancement of the view design). 

Yes, but the URL has to come from the locationmap. What I meant was you 
throw together a simple demo and I'll add the locationmap stuff. Of 
course, if you want to use this as an opportunity to get to grips with 
the locationmap I'll answer your questions instead of doing it.

Ross

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Thorsten Scherler <th...@apache.org>]

On Wed, 2005-06-08 at 10:08 +0100, Ross Gardler wrote:
> Thorsten Scherler wrote:
> > On Wed, 2005-06-08 at 09:21 +0100, Ross Gardler wrote:
> > 
> >>Nicola Ken Barozzi wrote:
> 
> ...
> 
> >>>Aditionally, what we would need is just to add an _edit_ link to each 
> >>>Forrest page that points to the url Lenya uses for editing.
> >>
> >>Currently this is done through filter XSL's (see the daisy plugin in the 
> >>locationmap branch), but I think views may provide a better solution. 
> >>It's on my todo list.
> >>
> > 
> > 
> > :) Yeah, that is simply a contract that contains a link to
> > daisy/lenya/anyOtherCms edit page. I will make an example as soon I have
> > updated the locationmap branch on my harddrive and understood all the
> > mails around the topic. ;-)
> 
> I'll do you a deal, if you create the contract with an example linking 
> to the demo page Gregor created for us, I'll move it into the 
> Locationmap branch and make it work with that the locationmap stuff.
> 

I would like to set up that branch to work by default with views if that
is alright with you?

> i.e. just hard code the URLs in the contract, I'll do what is necessary 
> with locationmap.

No, there is no need to hardcode urls in the contracts. We can use the
same mechanism we used in the feeder-contract (remember the example you
brought up as enhancement of the view design). 

This way each contract can be based on a different location per view.

...done deal. ;-)

> 
> Ross


salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Thorsten Scherler wrote:
> On Wed, 2005-06-08 at 09:21 +0100, Ross Gardler wrote:
> 
>>Nicola Ken Barozzi wrote:

...

>>>Aditionally, what we would need is just to add an _edit_ link to each 
>>>Forrest page that points to the url Lenya uses for editing.
>>
>>Currently this is done through filter XSL's (see the daisy plugin in the 
>>locationmap branch), but I think views may provide a better solution. 
>>It's on my todo list.
>>
> 
> 
> :) Yeah, that is simply a contract that contains a link to
> daisy/lenya/anyOtherCms edit page. I will make an example as soon I have
> updated the locationmap branch on my harddrive and understood all the
> mails around the topic. ;-)

I'll do you a deal, if you create the contract with an example linking 
to the demo page Gregor created for us, I'll move it into the 
Locationmap branch and make it work with that the locationmap stuff.

i.e. just hard code the URLs in the contract, I'll do what is necessary 
with locationmap.

Ross

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Thorsten Scherler <th...@apache.org>]

On Wed, 2005-06-08 at 09:21 +0100, Ross Gardler wrote:
> Nicola Ken Barozzi wrote:
> > Gregor J. Rothfuss wrote:
> > ...
> > 
> >> so initially, people could write documents in lenya, publish them, and 
> >> then head over to forrest(bot?) to slurp all these pages in? 
> > 
> > 
> > My personal view is not to use the Forrestbot, but to 
> > mod_proxy/mod_cache a live Forrest instance that gets files from a 
> > published Lenya pubblication. In this way, publishing in Lenya is the 
> > only step needed to... publish :-)
> 
> OK - as long as someone shows me how when the time comes.
> 
> This would mean published docs in Lenya that are already *approved* for 
> publication in the final docs would automatically appear. New published 
> docs in lenya would need adding to the relevant site.xml for the real 
> docs, this is the point at which we bring order to the chaos (the 
> http://www.answers.com order to the http://www.wikipedia.org chaos)
> 

Yes, new docs have to be published before they are going into svn. I
will have a look after I finished the last view how-to that is on my
todo list.

Anyway I hope we (as in lenya) can show an example pretty soon, that we
get some momentum. The only thing is that there are so much do to and so
limit time. ;-)

> > Aditionally, what we would need is just to add an _edit_ link to each 
> > Forrest page that points to the url Lenya uses for editing.
> 
> Currently this is done through filter XSL's (see the daisy plugin in the 
> locationmap branch), but I think views may provide a better solution. 
> It's on my todo list.
> 

:) Yeah, that is simply a contract that contains a link to
daisy/lenya/anyOtherCms edit page. I will make an example as soon I have
updated the locationmap branch on my harddrive and understood all the
mails around the topic. ;-)


> > Looking at the Doco document [1] I see that Lenya and Forrest are not 
> > directly interacting, as both talk to a common repository.
> 
> The wiki is down at the moment. I'll come back to the rest of this mail 
> later.
> 
> Ross


salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Nicola Ken Barozzi wrote:
> Gregor J. Rothfuss wrote:
> ...
> 
>> so initially, people could write documents in lenya, publish them, and 
>> then head over to forrest(bot?) to slurp all these pages in? 
> 
> 
> My personal view is not to use the Forrestbot, but to 
> mod_proxy/mod_cache a live Forrest instance that gets files from a 
> published Lenya pubblication. In this way, publishing in Lenya is the 
> only step needed to... publish :-)

OK - as long as someone shows me how when the time comes.

This would mean published docs in Lenya that are already *approved* for 
publication in the final docs would automatically appear. New published 
docs in lenya would need adding to the relevant site.xml for the real 
docs, this is the point at which we bring order to the chaos (the 
http://www.answers.com order to the http://www.wikipedia.org chaos)

> Aditionally, what we would need is just to add an _edit_ link to each 
> Forrest page that points to the url Lenya uses for editing.

Currently this is done through filter XSL's (see the daisy plugin in the 
locationmap branch), but I think views may provide a better solution. 
It's on my todo list.

> Looking at the Doco document [1] I see that Lenya and Forrest are not 
> directly interacting, as both talk to a common repository.

The wiki is down at the moment. I'll come back to the rest of this mail 
later.

Ross

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> -------- committers ------------. .---- Non-Committers ---
>                                 | |
>                                 | |
> +---------+    +---------+    +-------+    +----------+
> | Forrest |<---| SVN     |<---| Lenya |--->|Lenya Repo|
> +---------+    +---------+    +-------+    +----------+
>                    .               /|\          |
>                   /|\               |___________|
>                    |
>               +------------+
>               | Committers |
>               | Tools      |
>               +------------+
> 

nice diagram!

> So non-committers edit freely in the Lenya repo but cannot publish 
> within Lenya. When an edit is reviewed and published by a committer, 
> that change is propagated to SVN.
> 
> Committers can use whatever tool they prefer, working directly with SVN 
> or with Lenya.
> 
> In this model there is the potential for conflict between edits in the 
> Lenya Repo that have not yet been published and edits by committers 
> working directly with SVN. In my view this is no more of a problem than 
> the potential for conflicts between in progress edits on individual 
> checked out copies of SVN, or at least if we stay on top of publishing 
> changes to Lenya this should be the case. What do others think about this?

lenya uses pessimistic offline locking. with svn 1.2, there is now lock 
support, so this should'nt be a problem.


>> What do you think about this architecture, is it really needed? I'm 
>> not sure it's *that* different from asking Lenya to get the docs for 
>> us, as it's a simple URL request. Basically, Lenya would be doing what 
>> the SLIDE+LENYA combo does in the graphic, thus removing the need for 
>> DASL that only Slide at Apache has, making us use Subversion.
> 
> 
> I agree. The above is very similar to the original proposal minus the 
> mail workflow)

+1

>> What remains to do are diffs.
> 
> 
> The above gives us diffs of published documents but Lenya does not 
> publish good diffs of edits of its own repository. However, the Lenya 
> community are addressing this (I have a Summer of Code applicant who has 
> expressed interest in this aspect and a couple of Lenya devs have agreed 
> to co-mentor).

exactly.

>> I'm not sure that the mail workflow is something we really need ATM. 
>> IMHO just adding editors that cannot publish, along with diffs, is 
>> something that gives us enough control.
> 
> 
> I agree. The mail workflow is a nice have. It would be wonderful to be 
> able to publish simple changes by replying to a mail as is proposed in 
> [1]. But  we can manage with the diffs and a link to an URL to publish 
> the changes, and another to reject the changes.

the mail workflow becomes important once there is such a huge amount of 
changes that approval needs to be super-efficient. i'm glad if we get to 
a level where we have such problems ;)

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Nicola Ken Barozzi wrote:

(cc'd to Lenya Dev for their comments as well - please reply-all)

...

> 
> Looking at the Doco document [1] I see that Lenya and Forrest are not 
> directly interacting, as both talk to a common repository.

Right now, what we have is:


--- committers ---. .---- Non-Committers ---
                   | |
                   | |
+---------+    +-------+    +----------+
| Forrest |<---| Lenya |<-->|Lenya Repo|
+---------+    +-------+    +----------+



(I've simplified by ignoring other repository types, but we should 
remember Forrest can now integrate content from multiple repositories, 
for example, Tim has the Locationmap working with a slide repo and you 
know that we have Daisy too)

This architecture does not allow for committers to write docs with their 
preferred tools via SVN, as has been requested. Nor does it keep the 
published artifacts in SVN as is desired on Apache projects. So I see 
the target architecture like this:



-------- committers ------------. .---- Non-Committers ---
                                 | |
                                 | |
+---------+    +---------+    +-------+    +----------+
| Forrest |<---| SVN     |<---| Lenya |--->|Lenya Repo|
+---------+    +---------+    +-------+    +----------+
                    .               /|\          |
                   /|\               |___________|
                    |
               +------------+
               | Committers |
               | Tools      |
               +------------+



So non-committers edit freely in the Lenya repo but cannot publish 
within Lenya. When an edit is reviewed and published by a committer, 
that change is propagated to SVN.

Committers can use whatever tool they prefer, working directly with SVN 
or with Lenya.

In this model there is the potential for conflict between edits in the 
Lenya Repo that have not yet been published and edits by committers 
working directly with SVN. In my view this is no more of a problem than 
the potential for conflicts between in progress edits on individual 
checked out copies of SVN, or at least if we stay on top of publishing 
changes to Lenya this should be the case. What do others think about this?

> What do you think about this architecture, is it really needed? I'm not 
> sure it's *that* different from asking Lenya to get the docs for us, as 
> it's a simple URL request. Basically, Lenya would be doing what the 
> SLIDE+LENYA combo does in the graphic, thus removing the need for DASL 
> that only Slide at Apache has, making us use Subversion.

I agree. The above is very similar to the original proposal minus the 
mail workflow)

> What remains to do are diffs.

The above gives us diffs of published documents but Lenya does not 
publish good diffs of edits of its own repository. However, the Lenya 
community are addressing this (I have a Summer of Code applicant who has 
expressed interest in this aspect and a couple of Lenya devs have agreed 
to co-mentor).

> I'm not sure that the mail workflow is 
> something we really need ATM. IMHO just adding editors that cannot 
> publish, along with diffs, is something that gives us enough control.

I agree. The mail workflow is a nice have. It would be wonderful to be 
able to publish simple changes by replying to a mail as is proposed in 
[1]. But  we can manage with the diffs and a link to an URL to publish 
the changes, and another to reject the changes.

Ross

> [1] http://wiki.apache.org/cocoon/Doco

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Nicola Ken Barozzi wrote:

(cc'd to Lenya Dev for their comments as well - please reply-all)

...

> 
> Looking at the Doco document [1] I see that Lenya and Forrest are not 
> directly interacting, as both talk to a common repository.

Right now, what we have is:


--- committers ---. .---- Non-Committers ---
                   | |
                   | |
+---------+    +-------+    +----------+
| Forrest |<---| Lenya |<-->|Lenya Repo|
+---------+    +-------+    +----------+



(I've simplified by ignoring other repository types, but we should 
remember Forrest can now integrate content from multiple repositories, 
for example, Tim has the Locationmap working with a slide repo and you 
know that we have Daisy too)

This architecture does not allow for committers to write docs with their 
preferred tools via SVN, as has been requested. Nor does it keep the 
published artifacts in SVN as is desired on Apache projects. So I see 
the target architecture like this:



-------- committers ------------. .---- Non-Committers ---
                                 | |
                                 | |
+---------+    +---------+    +-------+    +----------+
| Forrest |<---| SVN     |<---| Lenya |--->|Lenya Repo|
+---------+    +---------+    +-------+    +----------+
                    .               /|\          |
                   /|\               |___________|
                    |
               +------------+
               | Committers |
               | Tools      |
               +------------+



So non-committers edit freely in the Lenya repo but cannot publish 
within Lenya. When an edit is reviewed and published by a committer, 
that change is propagated to SVN.

Committers can use whatever tool they prefer, working directly with SVN 
or with Lenya.

In this model there is the potential for conflict between edits in the 
Lenya Repo that have not yet been published and edits by committers 
working directly with SVN. In my view this is no more of a problem than 
the potential for conflicts between in progress edits on individual 
checked out copies of SVN, or at least if we stay on top of publishing 
changes to Lenya this should be the case. What do others think about this?

> What do you think about this architecture, is it really needed? I'm not 
> sure it's *that* different from asking Lenya to get the docs for us, as 
> it's a simple URL request. Basically, Lenya would be doing what the 
> SLIDE+LENYA combo does in the graphic, thus removing the need for DASL 
> that only Slide at Apache has, making us use Subversion.

I agree. The above is very similar to the original proposal minus the 
mail workflow)

> What remains to do are diffs.

The above gives us diffs of published documents but Lenya does not 
publish good diffs of edits of its own repository. However, the Lenya 
community are addressing this (I have a Summer of Code applicant who has 
expressed interest in this aspect and a couple of Lenya devs have agreed 
to co-mentor).

> I'm not sure that the mail workflow is 
> something we really need ATM. IMHO just adding editors that cannot 
> publish, along with diffs, is something that gives us enough control.

I agree. The mail workflow is a nice have. It would be wonderful to be 
able to publish simple changes by replying to a mail as is proposed in 
[1]. But  we can manage with the diffs and a link to an URL to publish 
the changes, and another to reject the changes.

Ross

> [1] http://wiki.apache.org/cocoon/Doco



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

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

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

Gregor J. Rothfuss wrote:
...
> so initially, people could write documents in lenya, publish them, and 
> then head over to forrest(bot?) to slurp all these pages in? 

My personal view is not to use the Forrestbot, but to 
mod_proxy/mod_cache a live Forrest instance that gets files from a 
published Lenya pubblication. In this way, publishing in Lenya is the 
only step needed to... publish :-)

The Forrestbot is still needed though for the projects that do not use 
Lenya, and for the creation of daily site tarballs that can be used to 
get the site back up quickly in case of problems.

Aditionally, what we would need is just to add an _edit_ link to each 
Forrest page that points to the url Lenya uses for editing.

                                - ~ -

Looking at the Doco document [1] I see that Lenya and Forrest are not 
directly interacting, as both talk to a common repository.

What do you think about this architecture, is it really needed? I'm not 
sure it's *that* different from asking Lenya to get the docs for us, as 
it's a simple URL request. Basically, Lenya would be doing what the 
SLIDE+LENYA combo does in the graphic, thus removing the need for DASL 
that only Slide at Apache has, making us use Subversion.

What remains to do are diffs. I'm not sure that the mail workflow is 
something we really need ATM. IMHO just adding editors that cannot 
publish, along with diffs, is something that gives us enough control.

[1] http://wiki.apache.org/cocoon/Doco

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

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
>> OK, along the same theme of quick hacks I've put a simple demo 
>> together for you. To see it you need to checkout the 
>> locationmap_branch of Forrest. Seed a fresh site, do "forrest run" and 
>> look at the locaitonmap sample (last item in the samples menu).
> 
> 
> cool, seems to work fine:
> 
> http://greg.abstrakt.ch/gallery/lenya/lenya_in_forrest
> 
>> There are a few things to note here:
> 
> 
>> For a) you could have a look at the Daisy plugin (in the whiteboard of 
>> the locationmap branch). This provides pre and post filters to 
>> documents retrieved from daisy for doing things like URL rewriting and 
>> adding additional content (such as a disclaimer that the content is 
>> from a remote site, a license, a link back to the edit page for the 
>> document, that kind of thing). I suspect that the way I am doing this 
>> stuff will change when I find the time to get to grips with views.
>>
>> Although a long way from perfect I hope this is enough to illustrate 
>> how to do the integration (see I told you it was easy with the 
>> locationmap :-))
> 
> 
> so initially, people could write documents in lenya, publish them, and 
> then head over to forrest(bot?) to slurp all these pages in? the precise 
> workflow will of course have to be worked out.

Precisely.

With a longer term goal of having Lenya writing to SVN so that we can 
also work offline in our preferred editing tools.

Ross

Re: Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> OK, along the same theme of quick hacks I've put a simple demo together 
> for you. To see it you need to checkout the locationmap_branch of 
> Forrest. Seed a fresh site, do "forrest run" and look at the locaitonmap 
> sample (last item in the samples menu).

cool, seems to work fine:

http://greg.abstrakt.ch/gallery/lenya/lenya_in_forrest

> There are a few things to note here:

> For a) you could have a look at the Daisy plugin (in the whiteboard of 
> the locationmap branch). This provides pre and post filters to documents 
> retrieved from daisy for doing things like URL rewriting and adding 
> additional content (such as a disclaimer that the content is from a 
> remote site, a license, a link back to the edit page for the document, 
> that kind of thing). I suspect that the way I am doing this stuff will 
> change when I find the time to get to grips with views.
> 
> Although a long way from perfect I hope this is enough to illustrate how 
> to do the integration (see I told you it was easy with the locationmap :-))

so initially, people could write documents in lenya, publish them, and 
then head over to forrest(bot?) to slurp all these pages in? the precise 
workflow will of course have to be worked out.

-gregor

Forrest + Lenya (Re: [PROPOSAL] A CMS for our Docs)

[Ross Gardler <rg...@apache.org>]

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
>> When you have a little demo going pass me a URL for a demo page that 
>> has no navigation, I'll add it to the sample in the locationmap branch 
>> (we don't have images working yet, but it should only be a sitemap 
>> addition).
> 
> 
> http://lenya.zones.apache.org:8888/default/live/index.html with navigation,
> 
> http://lenya.zones.apache.org:8888/default/live/index.html?raw=true 
> without.
> 
> note that this is just a quick stylesheet hack, not permanent.

OK, along the same theme of quick hacks I've put a simple demo together 
for you. To see it you need to checkout the locationmap_branch of 
Forrest. Seed a fresh site, do "forrest run" and look at the locaitonmap 
sample (last item in the samples menu).

There are a few things to note here:

Lenya uses tables to do layout of the page (shame on you). As a result 
you can see the table borders (this is a stylesheet issue).

There are no headings in the page you provide as a demo, so no sections 
are defined, so no TOC. This has highlighted a bug in our skin that 
places the TOC horizontal rules in place, even if no TOC is present.

The image does not work yet. There are two reasons for this:

a) it is an absolute URL and we need to rewrite these so that the 
locationmap will match them

b) I've not enabled the locationmap for resources yet

For a) you could have a look at the Daisy plugin (in the whiteboard of 
the locationmap branch). This provides pre and post filters to documents 
retrieved from daisy for doing things like URL rewriting and adding 
additional content (such as a disclaimer that the content is from a 
remote site, a license, a link back to the edit page for the document, 
that kind of thing). I suspect that the way I am doing this stuff will 
change when I find the time to get to grips with views.

Although a long way from perfect I hope this is enough to illustrate how 
to do the integration (see I told you it was easy with the locationmap :-))

Ross

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

David Crossley wrote:
> Gregor J. Rothfuss wrote:
> 
>>Ross Gardler wrote:
>>
>>
>>>When you have a little demo going pass me a URL for a demo page that has 
>>>no navigation, I'll add it to the sample in the locationmap branch (we 
>>>don't have images working yet, but it should only be a sitemap addition).
>>
>>http://lenya.zones.apache.org:8888/default/live/index.html with navigation,
> 
> 
> I am not seeing any navigation on that page. There are no "Concepts" or
> "Features" sections as referred to in the page text.
> (Mac OS X and both FireFox and Safari.)

i forgot to publish additional pages, my bad. we are still grappling 
with jdk 1.5 compatibility, and some features do not work properly at 
the moment (such as publishing)

Re: [PROPOSAL] A CMS for our Docs

[David Crossley <cr...@apache.org>]

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
> >When you have a little demo going pass me a URL for a demo page that has 
> >no navigation, I'll add it to the sample in the locationmap branch (we 
> >don't have images working yet, but it should only be a sitemap addition).
> 
> http://lenya.zones.apache.org:8888/default/live/index.html with navigation,

I am not seeing any navigation on that page. There are no "Concepts" or
"Features" sections as referred to in the page text.
(Mac OS X and both FireFox and Safari.)

--David

> http://lenya.zones.apache.org:8888/default/live/index.html?raw=true 
> without.
> 
> note that this is just a quick stylesheet hack, not permanent.

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> When you have a little demo going pass me a URL for a demo page that has 
> no navigation, I'll add it to the sample in the locationmap branch (we 
> don't have images working yet, but it should only be a sitemap addition).

http://lenya.zones.apache.org:8888/default/live/index.html with navigation,

http://lenya.zones.apache.org:8888/default/live/index.html?raw=true 
without.

note that this is just a quick stylesheet hack, not permanent.

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Gregor J. Rothfuss wrote:
> Ross Gardler wrote:
> 
>> How difficult is it to provide a version of a page without the 
>> navigation stuff, just the raw content? If you can do this then you 
>> are already integrated (if you use the locationmap branch of Forrest).
> 
> 
> fairly trivial. i had no idea integration would be that easy :) let me 
> hack a little demo on our zone..
> 
> this would still be html output, right? so it would not yet do the full 
> xdocs. seems like a very good, low hurdle start.

Yes, Forrest will turn your HTML into XDoc.

When you have a little demo going pass me a URL for a demo page that has 
no navigation, I'll add it to the sample in the locationmap branch (we 
don't have images working yet, but it should only be a sitemap addition).

Ross

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Ross Gardler wrote:

> How difficult is it to provide a version of a page without the 
> navigation stuff, just the raw content? If you can do this then you are 
> already integrated (if you use the locationmap branch of Forrest).

fairly trivial. i had no idea integration would be that easy :) let me 
hack a little demo on our zone..

this would still be html output, right? so it would not yet do the full 
xdocs. seems like a very good, low hurdle start.


> See my other response to Davids concerns about about maintenance and the 
> need for an Apache-wide system. So far it seems Lenya would be a better 
> choice as long as the integration is not a real pain and there is enough 
> buy in from the two communities.

there are degrees to the integration, and i think it's important to 
start gradually to not fall into the 'let's invent tools' trap :)

but your idea above is very encouraging.

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Gregor J. Rothfuss wrote:
> Thorsten Scherler wrote:
> 
>> Just a quick remark on that, I guess gregor, andreas, michi and other
>> would happily help us with that, but my time is too limited to actually
>> being a big help for doing it. 
> 
> 
> install is easy enough, and i would gladly do that. we need some help to 
>  mimic the daisy integration's capabilities though.

How difficult is it to provide a version of a page without the 
navigation stuff, just the raw content? If you can do this then you are 
already integrated (if you use the locationmap branch of Forrest).

>> Generally I would favor lenya over daisy but I will not be in the way of
>> daisy either because I do not have the time to give the requested
>> support for lenya. 
> 
> 
> well, since over at lenya, we have the same problem (generating xdoc 
> from lenya), i think we can work on the solution together.

See my other response to Davids concerns about about maintenance and the 
need for an Apache-wide system. So far it seems Lenya would be a better 
choice as long as the integration is not a real pain and there is enough 
buy in from the two communities.

Ross

Re: [PROPOSAL] A CMS for our Docs

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

Gregor J. Rothfuss wrote:
> Thorsten Scherler wrote:
> 
>> Just a quick remark on that, I guess gregor, andreas, michi and other
>> would happily help us with that, but my time is too limited to actually
>> being a big help for doing it. 
> 
>  install is easy enough, and i would gladly do that. we need some help to 
>  mimic the daisy integration's capabilities though.

I'd say we start making what we have work fully, and then work from there.

>> Generally I would favor lenya over daisy but I will not be in the way of
>> daisy either because I do not have the time to give the requested
>> support for lenya. 
> 
> well, since over at lenya, we have the same problem (generating xdoc 
> from lenya), i think we can work on the solution together.

Oh, very nice.

Even if I have said that I don't have time, I am really attracted by 
Lenya+Forrest. It bugs me to see Lenya using Forrest for publication: 
better integration would benefit both of us and make us concentrate on 
what we like best.

Since Cocoon is already trying out Daisy+Forrest, I humbly propose that 
ATM we start out with Lenya, although it's not a -1 if someone wants to 
install Daisy in our zone too.

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

Re: [PROPOSAL] A CMS for our Docs

["Gregor J. Rothfuss" <gr...@apache.org>]

Thorsten Scherler wrote:

> Just a quick remark on that, I guess gregor, andreas, michi and other
> would happily help us with that, but my time is too limited to actually
> being a big help for doing it. 

install is easy enough, and i would gladly do that. we need some help to 
  mimic the daisy integration's capabilities though.

> Generally I would favor lenya over daisy but I will not be in the way of
> daisy either because I do not have the time to give the requested
> support for lenya. 

well, since over at lenya, we have the same problem (generating xdoc 
from lenya), i think we can work on the solution together.

Re: [PROPOSAL] A CMS for our Docs

[Thorsten Scherler <th...@apache.org>]

On Mon, 2005-06-06 at 12:28 +0100, Ross Gardler wrote:
> Nicola Ken Barozzi wrote:
> > Ross Gardler wrote:
> > 
> >> Over at Cocoon they are starting to use Daisy for their docs. I 
> >> propose we do the same.
> > 
> > 
> > I would prefer to use Lenya, as Cocoon will already stress test the 
> > Daisy integration aplenty. On the other hand, I have no will nor time to 
> > help, and Daisy is good too.
> > 
> > +0 for the proposal
> > +0 for Lenya
> > <applause> for the one who sets up either system.
> 
> I proposed Daisy because I am familiar with it and we are able to 
> publish documents from it using Forrest. However, I am not against using 
> Lenya instead.
> 
> I'm familiar with Daisy and what it can do. I much prefer it's design 
> and find it much easier to customise.
> 
> If we go for Lenya instead then we will have to rely on Thorsten to get 
> it up and running and do any modifications/integration we need 
> (hopefully my work on the Locationmap and Daisy integration will help here).
> 
> So I am +0 for Lenya, +1 for Daisy (in that I can set Daisy up).
> 
> If Thorsten wants to set up Lenya I will be glad to accept the 
> opportunity to learn.
> 

Just a quick remark on that, I guess gregor, andreas, michi and other
would happily help us with that, but my time is too limited to actually
being a big help for doing it. 

Generally I would favor lenya over daisy but I will not be in the way of
daisy either because I do not have the time to give the requested
support for lenya. 

salu2
-- 
thorsten

"Together we stand, divided we fall!" 
Hey you (Pink Floyd)

Re: [PROPOSAL] A CMS for our Docs

[Ross Gardler <rg...@apache.org>]

Nicola Ken Barozzi wrote:
> Ross Gardler wrote:
> 
>> Over at Cocoon they are starting to use Daisy for their docs. I 
>> propose we do the same.
> 
> 
> I would prefer to use Lenya, as Cocoon will already stress test the 
> Daisy integration aplenty. On the other hand, I have no will nor time to 
> help, and Daisy is good too.
> 
> +0 for the proposal
> +0 for Lenya
> <applause> for the one who sets up either system.

I proposed Daisy because I am familiar with it and we are able to 
publish documents from it using Forrest. However, I am not against using 
Lenya instead.

I'm familiar with Daisy and what it can do. I much prefer it's design 
and find it much easier to customise.

If we go for Lenya instead then we will have to rely on Thorsten to get 
it up and running and do any modifications/integration we need 
(hopefully my work on the Locationmap and Daisy integration will help here).

So I am +0 for Lenya, +1 for Daisy (in that I can set Daisy up).

If Thorsten wants to set up Lenya I will be glad to accept the 
opportunity to learn.

Ross

Re: [PROPOSAL] A CMS for our Docs

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

Ross Gardler wrote:
> Over at Cocoon they are starting to use Daisy for their docs. I propose 
> we do the same.

I would prefer to use Lenya, as Cocoon will already stress test the 
Daisy integration aplenty. On the other hand, I have no will nor time to 
help, and Daisy is good too.

+0 for the proposal
+0 for Lenya
<applause> for the one who sets up either system.

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