You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Tony Collen <co...@umn.edu> on 2004/06/24 11:45:54 UTC
[RT] The Cocoon Handbook
This is a late-night, rambling [RT]. I think it's a good idea. You may or may
not. Please flame, argue, discuss, rant, etc... it's an [RT], after all...
Have fun!
>> The Problem: Documentation <<
Right here is where I would discuss the problem in a more in-depth sort of way,
but since my brain is pretty much shut down, that's not going to happen. Insert
your own rambling explanation of why the docs stink. ;)
>> The Solution <<
I propose we create a free, high-quality electronic book (entitled
_The_Cocoon_Handbook_), which will eventually replace the mess of docs we
currently have. It will be in DocBook (possibly simplified) format.
Not only are we having a hard enough time keeping the documentation up-to-date
normally, fightning the rampant wiki spamming has become almost a full-time job
as it is.
We can integrate the eventual book with user-added notations, similar to how PHP
lets people log in and annotate the existing docs.
>> Considerations <<
There are several things we need to take into consideration. In no particular
order, they seem to be:
- The existing documentation.
How can we take advantage of what we already have? Further, how can we lose
the crap and keep the good stuff?
- Forrest.
How will it affect this plan, if at all?
- The Wiki.
We need to be able to allow people to annotate or refine the docs with ease.
How can this be done?
IMO there are two separate things that need to happen with the docs. One is
annotating the docs, adding user comments, etc, just like the PHP docs. The
other is to actually maintain the docs which are being annotated. That is, if a
new component comes out, or a feature is added, to change the actual DocBook
source. If someone is willing to help maintain the docs (although might not be
all that experienced of a Cocoon user), we should be willing to let them become
a committer in order to maintain the docs.
That's about all that my brain can spew out for now. I really think this is a
good idea, and I've been throwing the idea around in my head for a while now.
Regards,
Tony
Re: [RT] The Cocoon Handbook
Posted by Tony Collen <co...@umn.edu>.
Vadim Gritsenko wrote:
> What's current state of "doco"? Some time ago we agreed to migrate to it
> (once it's done ;-)
I think it got indefinitely sidelined when Stefano moved.
Tony
> Vadim
>
Re: [RT] The Cocoon Handbook
Posted by Stefano Mazzocchi <st...@apache.org>.
Vadim Gritsenko wrote:
> Tony Collen wrote:
>
>> Upayavira wrote:
>>
>>> Tony,
>>>
>>> I think I'd say simply that Cocoon operates as a 'do-ocracy'. He who
>>> does, chooses (usually!). It is widely accepted that something needs
>>> to happen on the docs. And really, what it is going to take is
>>> someone just getting on and doing it. I suspect that someone putting
>>> in the legwork would get a lot of support from the rest of us. That
>>> is the missing component, not the ideas. Are you offering? ;-)
>>
>>
>>
>> Yeah, more or less ;)
>
> What's current state of "doco"? Some time ago we agreed to migrate to it
> (once it's done ;-)
Sorry people, the doco architecture is still there, but there is no time
from my side to do anything about it.
My personal suggestion would be to start considering Lenya for our own
wiki-on-steroids.
--
Stefano.
Re: [RT] The Cocoon Handbook
Posted by Vadim Gritsenko <va...@reverycodes.com>.
Tony Collen wrote:
> Upayavira wrote:
>
>> Tony,
>>
>> I think I'd say simply that Cocoon operates as a 'do-ocracy'. He who
>> does, chooses (usually!). It is widely accepted that something needs
>> to happen on the docs. And really, what it is going to take is
>> someone just getting on and doing it. I suspect that someone putting
>> in the legwork would get a lot of support from the rest of us. That
>> is the missing component, not the ideas. Are you offering? ;-)
>
>
> Yeah, more or less ;)
What's current state of "doco"? Some time ago we agreed to migrate to it
(once it's done ;-)
Vadim
Re: [RT] The Cocoon Handbook
Posted by Upayavira <uv...@upaya.co.uk>.
Tony Collen wrote:
> Upayavira wrote:
>
>> Tony,
>>
>> I think I'd say simply that Cocoon operates as a 'do-ocracy'. He who
>> does, chooses (usually!). It is widely accepted that something needs
>> to happen on the docs. And really, what it is going to take is
>> someone just getting on and doing it. I suspect that someone putting
>> in the legwork would get a lot of support from the rest of us. That
>> is the missing component, not the ideas. Are you offering? ;-)
>
>
> Yeah, more or less ;)
Great!
> My time should be freeing up a little more in the coming week, so I'll
> keep progress posted in this thread.
Well, why not knock something up, and show us.
Regards, Upayavira
Re: [RT] The Cocoon Handbook
Posted by Tony Collen <co...@umn.edu>.
Upayavira wrote:
> Tony,
>
> I think I'd say simply that Cocoon operates as a 'do-ocracy'. He who
> does, chooses (usually!). It is widely accepted that something needs to
> happen on the docs. And really, what it is going to take is someone just
> getting on and doing it. I suspect that someone putting in the legwork
> would get a lot of support from the rest of us. That is the missing
> component, not the ideas. Are you offering? ;-)
Yeah, more or less ;)
My time should be freeing up a little more in the coming week, so I'll
keep progress posted in this thread.
Tony
Re: [RT] The Cocoon Handbook
Posted by Upayavira <uv...@upaya.co.uk>.
Tony,
I think I'd say simply that Cocoon operates as a 'do-ocracy'. He who
does, chooses (usually!). It is widely accepted that something needs to
happen on the docs. And really, what it is going to take is someone just
getting on and doing it. I suspect that someone putting in the legwork
would get a lot of support from the rest of us. That is the missing
component, not the ideas. Are you offering? ;-)
Regards, Upayavira
Tony Collen wrote:
> This is a late-night, rambling [RT]. I think it's a good idea. You
> may or may not. Please flame, argue, discuss, rant, etc... it's an
> [RT], after all... Have fun!
>
> >> The Problem: Documentation <<
> Right here is where I would discuss the problem in a more in-depth
> sort of way, but since my brain is pretty much shut down, that's not
> going to happen. Insert your own rambling explanation of why the docs
> stink. ;)
>
> >> The Solution <<
> I propose we create a free, high-quality electronic book (entitled
> _The_Cocoon_Handbook_), which will eventually replace the mess of docs
> we currently have. It will be in DocBook (possibly simplified) format.
>
> Not only are we having a hard enough time keeping the documentation
> up-to-date normally, fightning the rampant wiki spamming has become
> almost a full-time job as it is.
>
> We can integrate the eventual book with user-added notations, similar
> to how PHP lets people log in and annotate the existing docs.
>
> >> Considerations <<
> There are several things we need to take into consideration. In no
> particular order, they seem to be:
>
> - The existing documentation.
> How can we take advantage of what we already have? Further, how can
> we lose the crap and keep the good stuff?
>
> - Forrest.
> How will it affect this plan, if at all?
>
> - The Wiki.
> We need to be able to allow people to annotate or refine the docs
> with ease. How can this be done?
>
> IMO there are two separate things that need to happen with the docs.
> One is annotating the docs, adding user comments, etc, just like the
> PHP docs. The other is to actually maintain the docs which are being
> annotated. That is, if a new component comes out, or a feature is
> added, to change the actual DocBook source. If someone is willing to
> help maintain the docs (although might not be all that experienced of
> a Cocoon user), we should be willing to let them become a committer in
> order to maintain the docs.
>
> That's about all that my brain can spew out for now. I really think
> this is a good idea, and I've been throwing the idea around in my head
> for a while now.
>
> Regards,
>
> Tony
>
Re: [RT] The Cocoon Handbook
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Berin Loritsch wrote:
...
> All I can say is "Write On!" (pun intended).
:-D
> Seriously, having a good organizational structure helps writing
> comprehensibly. The structure does not need to be set in stone, but it
> does need to be there. The biggest problem is getting writers.
+1
> Question is, who is going to do the writing?
Easier task: what documentation is well written, so we can "copy" the
organization form that?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] The Cocoon Handbook
Posted by Joerg Heinicke <jo...@gmx.de>.
On 24.06.2004 20:00, Nicola Ken Barozzi wrote:
> IMHO the real thing we need is structure for others to fill in. Cocoon
> has a lot of docs, both on the site and on the Wiki, but it's hard to
> find them.
Don't forget Helma's effort on that:
http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC
Joerg
Re: [RT] The Cocoon Handbook
Posted by David Crossley <cr...@apache.org>.
Nicola Ken Barozzi wrote:
> Carlos Araya wrote:
>
> > I think that it needs to be a collaborative effort. There has to be a
> > coordinator/prodder and collector of volunteers/editor but there has to be a
> > collaborative effort as no one has expertise in all areas of Cocoon.
>
> We already did it, it was called the "documentation team". There was
> (still is?) a mailing list for it.
No. We tried it and then decided to rather discuss on the
dev and users lists, leaving the docs list for just Wiki diffs.
--
David Crossley
Re: [RT] The Cocoon Handbook
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Carlos Araya wrote:
> I think that it needs to be a collaborative effort. There has to be a
> coordinator/prodder and collector of volunteers/editor but there has to be a
> collaborative effort as no one has expertise in all areas of Cocoon.
We already did it, it was called the "documentation team". There was
(still is?) a mailing list for it.
IMHO the real thing we need is structure for others to fill in. Cocoon
has a lot of docs, both on the site and on the Wiki, but it's hard to
find them.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] The Cocoon Handbook
Posted by David Crossley <cr...@apache.org>.
Carlos Araya wrote:
> I think that it needs to be a collaborative effort. There has to be a
> coordinator/prodder and collector of volunteers/editor but there has to be a
> collaborative effort as no one has expertise in all areas of Cocoon.
Definitely.
We have the collaborators right here on the dev and users lists.
Any one of us can be a prodder. Any one of us can lead by example.
--
David Crossley
Re: [RT] The Cocoon Handbook
Posted by Carlos Araya <we...@earthlink.net>.
I think that it needs to be a collaborative effort. There has to be a
coordinator/prodder and collector of volunteers/editor but there has to be a
collaborative effort as no one has expertise in all areas of Cocoon.
I'll write an outline and present it in the next couple days and ask for
volunteers.
Carlos
----- Original Message -----
From: "Berin Loritsch" <bl...@d-haven.org>
To: <de...@cocoon.apache.org>
Sent: Thursday, June 24, 2004 8:54 AM
Subject: Re: [RT] The Cocoon Handbook
> Nicola Ken Barozzi wrote:
>
> > Tony Collen wrote:
> > ...
> >
> >> >> The Solution <<
> >> I propose we create a free, high-quality electronic book (entitled
> >> _The_Cocoon_Handbook_), which will eventually replace the mess of docs
> >> we currently have. It will be in DocBook (possibly simplified) format.
> >
> > ...
> >
> > Let's not make this a technology issue, it's a "people" issue.
> > IOW, it's not (only) the doc system that sucks, but it's the doc writers
> > that are missing.
> >
> > 1 - The first thing we need IMNSHO is to define a structure of this
> > book: The sections, the chapters.
> >
> > 2 - Then we can take the existing docs and put them into place in this
> > structure till there are no more, eventually enlarging the structure to
> > make them get in.
>
> All I can say is "Write On!" (pun intended).
>
> Seriously, having a good organizational structure helps writing
> comprehensibly. The structure does not need to be set in stone, but it
> does need to be there. The biggest problem is getting writers. It
> really doesn't matter how it is written as long as the information gets
> out there. Heck, use Wiki format to rough it in! It's easy and you
> don't have to worry about this tag or that. As long as the important
> information is stuck in people's heads and not in some easily extracted
> electronic format then it doesn't matter how elegant the doc build
> system is, it is still irrelevant.
>
> Question is, who is going to do the writing?
>
> --
>
> "Programming today is a race between software engineers striving to
> build bigger and better idiot-proof programs, and the Universe trying to
> produce bigger and better idiots. So far, the Universe is winning."
> - Rich Cook
>
Re: [RT] The Cocoon Handbook
Posted by Joerg Heinicke <jo...@gmx.de>.
On 24.06.2004 17:54, Berin Loritsch wrote:
> It really doesn't matter how it is written as long as the information
> gets out there.
I tend to Sylvain's POV:
> Yes, talking about technology rather than about writers, but IMO writers will come if they can use productive tools for the job.
> Heck, use Wiki format to rough it in! It's easy and you
> don't have to worry about this tag or that.
The Wiki format is ugly, different for every Wiki and difficult for more
sophisticated tasks like internal linking. How do you reference a
specific section? What happens if you move it around?
Joerg
Re: [RT] The Cocoon Handbook
Posted by Berin Loritsch <bl...@d-haven.org>.
Nicola Ken Barozzi wrote:
> Tony Collen wrote:
> ...
>
>> >> The Solution <<
>> I propose we create a free, high-quality electronic book (entitled
>> _The_Cocoon_Handbook_), which will eventually replace the mess of docs
>> we currently have. It will be in DocBook (possibly simplified) format.
>
> ...
>
> Let's not make this a technology issue, it's a "people" issue.
> IOW, it's not (only) the doc system that sucks, but it's the doc writers
> that are missing.
>
> 1 - The first thing we need IMNSHO is to define a structure of this
> book: The sections, the chapters.
>
> 2 - Then we can take the existing docs and put them into place in this
> structure till there are no more, eventually enlarging the structure to
> make them get in.
All I can say is "Write On!" (pun intended).
Seriously, having a good organizational structure helps writing
comprehensibly. The structure does not need to be set in stone, but it
does need to be there. The biggest problem is getting writers. It
really doesn't matter how it is written as long as the information gets
out there. Heck, use Wiki format to rough it in! It's easy and you
don't have to worry about this tag or that. As long as the important
information is stuck in people's heads and not in some easily extracted
electronic format then it doesn't matter how elegant the doc build
system is, it is still irrelevant.
Question is, who is going to do the writing?
--
"Programming today is a race between software engineers striving to
build bigger and better idiot-proof programs, and the Universe trying to
produce bigger and better idiots. So far, the Universe is winning."
- Rich Cook
Re: [RT] The Cocoon Handbook
Posted by Nicola Ken Barozzi <ni...@apache.org>.
gounis@osmosis.gr wrote:
...
>>I would also suggest to use simple html files (that Forrest can read),
>
> why not xhtml that are structured?
That's the idea. Forrest ditches all non-presentational tags...
> using a simple subset of xhmtl tags will be easy to tranform to PDF
...and then can transform to PDF :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] The Cocoon Handbook
Posted by go...@osmosis.gr.
On Thu, 24 Jun 2004, Nicola Ken Barozzi wrote:
> Tony Collen wrote:
> ...
> > >> The Solution <<
> > I propose we create a free, high-quality electronic book (entitled
> > _The_Cocoon_Handbook_), which will eventually replace the mess of docs
> > we currently have. It will be in DocBook (possibly simplified) format.
> ...
>
> Let's not make this a technology issue, it's a "people" issue.
> IOW, it's not (only) the doc system that sucks, but it's the doc writers
> that are missing.
>
> 1 - The first thing we need IMNSHO is to define a structure of this
> book: The sections, the chapters.
>
> 2 - Then we can take the existing docs and put them into place in this
> structure till there are no more, eventually enlarging the structure to
> make them get in.
>
> 3 - Finally, we need to fill in the missing gaps. Only at this point do
> we really need an easier documentation system ala DOCO.
>
> What I would suggest doing is to make a new documentation directory from
> Forrest and fill in the tabs.xml and site.xml files (step 1). The copy
> the docs from the current documentation and link them in the site.xml
> file (step 2).
>
> [Note that at this point we should be using SVN, and users can then be
> given fine grained access only to the docs even without having a Unix
> account. In this way we can give away SVN access just for documenters
> that don't need to become part of the project.]
>
> I would also suggest to use simple html files (that Forrest can read),
why not xhtml that are structured?
using a simple subset of xhmtl tags will be easy to tranform to PDF
-- stavros
> so that users can use any editor to create them without running Forrest,
> and they can be seen also in ViewCVS too.
>
> What I can help to do is to set up the initial Forrest doc space in the
> Cocoon CVS where this can start happening.
>
> WDOT?
>
>
Re: [RT] The Cocoon Handbook
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Tony Collen wrote:
...
> >> The Solution <<
> I propose we create a free, high-quality electronic book (entitled
> _The_Cocoon_Handbook_), which will eventually replace the mess of docs
> we currently have. It will be in DocBook (possibly simplified) format.
...
Let's not make this a technology issue, it's a "people" issue.
IOW, it's not (only) the doc system that sucks, but it's the doc writers
that are missing.
1 - The first thing we need IMNSHO is to define a structure of this
book: The sections, the chapters.
2 - Then we can take the existing docs and put them into place in this
structure till there are no more, eventually enlarging the structure to
make them get in.
3 - Finally, we need to fill in the missing gaps. Only at this point do
we really need an easier documentation system ala DOCO.
What I would suggest doing is to make a new documentation directory from
Forrest and fill in the tabs.xml and site.xml files (step 1). The copy
the docs from the current documentation and link them in the site.xml
file (step 2).
[Note that at this point we should be using SVN, and users can then be
given fine grained access only to the docs even without having a Unix
account. In this way we can give away SVN access just for documenters
that don't need to become part of the project.]
I would also suggest to use simple html files (that Forrest can read),
so that users can use any editor to create them without running Forrest,
and they can be seen also in ViewCVS too.
What I can help to do is to set up the initial Forrest doc space in the
Cocoon CVS where this can start happening.
WDOT?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] The Cocoon Handbook
Posted by David Crossley <cr...@apache.org>.
Joerg Heinicke wrote:
> I can live with both OO and DocBook. While the latter one is really
> straight forward for us, we will probably not really attract
> documentors, even with some fancy editors like XXE as the usability is
> not as good as with OO. But maybe that's only because the documentor
> must have the document structure in mind.
>
> With OO it is much more difficult for us to process the results. The
> documents are loose structured in the same way as HTML (no tree), but in
> contrary to HTML there is at least support for requirements like
> internal linking. A stylesheet processing those documents and adding the
> structure will be really hard (massive Muenchian Grouping), but not
> impossible of course. Therefore it's much easier for the documentor. I
> would be interested how you did the templates, Sylvain, to see if this
> solves problems of the post processing.
>
> The fact that OO files are not straight XML, but zipped XML, I would
> ignore. It's easy for us to do zip/unzip automatically. We only must not
> store the binaries in CVS, otherwise we will loose the possibility of
> doing diffs in CVS. Ah, when writing this another advantage of XXE come
> to my mind: a diff on OO files probably does not make much sense, as
> they store the XML unformatted. XXE indents and formats the XML nicely
> on save.
So is this the process? ... When committers receive an
update, then they unpack, view and save with XXE, then
diffs are clearly seen, then commit the indented XML.
--
David Crossley
Re: [RT] The Cocoon Handbook
Posted by Joerg Heinicke <jo...@gmx.de>.
Ok, after I have shoot on most of the proposals I guess I must provide
better alternatives :) My two alternatives for "large structured
documentations" already have been mentioned: DocBook and Open Office.
>> >> The Solution <<
>> I propose we create a free, high-quality electronic book (entitled
>> _The_Cocoon_Handbook_), which will eventually replace the mess of docs
>> we currently have.
>
> A big +1.
I also like the DocBook way very much, we did it that way at Virbus.
Customer requirement specifications and other documents were written
using DocBook and transformed using customized DocBook stylesheets into
Virbus CI PDFs.
> There are two main problems that IMO explain the poor state of Cocoon docs.
>
> The first one is that Cocoon being a large beast, it's doc has to be
> large, and therefore needs a well-defined structure.
Again my pointer on Helma's TOC effort:
http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC. It's a good
starting point IMO.
> The second one is that writing docs in XML is a major PITA, futhermore
> when we have fancy word processors just a click away on our computers.
> I'm sure that it refrains many prople from writing docs (including me).
> Intermediate tools like XXE ease the job, but aren't as userfriendly as
> good old MS Word.
We did it the XXE way at Virbus, it works really good, but it's of
course a developer's way, not a documentor's way.
> Simplified syntaxes as wiki are good for small
> documents (i.e. a page) but IMO don't scale for large structured
> documentations.
Yes, Wiki and HTML just can not work IMO. There is no editor available
for writing documentation with them. It starts with internal linking,
goes on with loose structure and ends with ... I don't know :)
> Now we have that nice thing called OpenOffice that is a wordprocessor
> storing its content as XML in a zip archive. We've used it as a
> front-end for a CMS
We too, but at a very low level.
> WDYT?
I can live with both OO and DocBook. While the latter one is really
straight forward for us, we will probably not really attract
documentors, even with some fancy editors like XXE as the usability is
not as good as with OO. But maybe that's only because the documentor
must have the document structure in mind.
With OO it is much more difficult for us to process the results. The
documents are loose structured in the same way as HTML (no tree), but in
contrary to HTML there is at least support for requirements like
internal linking. A stylesheet processing those documents and adding the
structure will be really hard (massive Muenchian Grouping), but not
impossible of course. Therefore it's much easier for the documentor. I
would be interested how you did the templates, Sylvain, to see if this
solves problems of the post processing.
The fact that OO files are not straight XML, but zipped XML, I would
ignore. It's easy for us to do zip/unzip automatically. We only must not
store the binaries in CVS, otherwise we will loose the possibility of
doing diffs in CVS. Ah, when writing this another advantage of XXE come
to my mind: a diff on OO files probably does not make much sense, as
they store the XML unformatted. XXE indents and formats the XML nicely
on save.
Joerg
Re: [RT] The Cocoon Handbook
Posted by Joerg Heinicke <jo...@gmx.de>.
On 25.06.2004 18:09, Tony Collen wrote:
> Hmm, how is OpenOffice on Win32? I've never ever used it, so it would
> be something new for me to pick up.. not like using office software is
> hard or anything. I'd be worried about usability or whatever. I
> suppose I'll download it and play with it.
I was never a hardcore Word user, so I can not tell you all the
differents in detail. But I wrote seminar papers with both Word and Open
Office. My personal preference __tends__ to Open Office since I had the
__feeling of better control__ of my document. Word does to much
auto-magic and shows strange behaviour, therefore I did not find out how
to do page numbering correctly with different styles for different parts
in the document using OO.
Joerg
Re: [RT] The Cocoon Handbook
Posted by Tony Collen <co...@umn.edu>.
Sylvain Wallez wrote:
>
> Now we have that nice thing called OpenOffice that is a wordprocessor
> storing its content as XML in a zip archive. We've used it as a
> front-end for a CMS, providing template documents with style sheets that
> have to be used. These styles match the structure of the target XML
> document that is produced from the OO file. This solution just rocks, as
> anybody (even a boss :-) is able to write content in a userfriendly and
> productive environment with spell checking, typing completion, etc etc.
> On the CMS side, the sxw archive is exploded, the XML content is
> transformed into the target markup (e.g. DocBook) and images are stored.
Hmm, how is OpenOffice on Win32? I've never ever used it, so it would be something new for me to
pick up.. not like using office software is hard or anything. I'd be worried about usability or
whatever. I suppose I'll download it and play with it.
Tony
Re: [RT] The Cocoon Handbook
Posted by Upayavira <uv...@upaya.co.uk>.
Vadim Gritsenko wrote:
> Sylvain Wallez wrote:
>
>> Now we have that nice thing called OpenOffice that is a wordprocessor
>> storing its content as XML in a zip archive. We've used it as a
>> front-end for a CMS, providing template documents with style sheets
>> that have to be used. These styles match the structure of the target
>> XML document that is produced from the OO file. This solution just
>> rocks, as anybody (even a boss :-) is able to write content in a
>> userfriendly and productive environment with spell checking, typing
>> completion, etc etc. On the CMS side, the sxw archive is exploded,
>> the XML content is transformed into the target markup (e.g. DocBook)
>> and images are stored.
>>
>> Sure, for the Cocoon docs, we cannot wait to have a CMS setup and
>> ready, or we'll never have docs ;-) What is rather simple, however,
>> is to have some offline processing (based on the CLI) that would do
>> the exploding/recomposition job to allow editing Cocoon docs with a
>> real wordprocessor.
>
>
>
> It would be simplier to store docs in sxw file itself; no
> recomposition is necessary, and html/pdf publishing out of sxw
> "repository" can be added to forrest.
I believe Reinhard added it a while ago.
Upayavira
Re: [RT] The Cocoon Handbook
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Joerg Heinicke wrote:
> On 25.06.2004 19:12, Nicola Ken Barozzi wrote:
>
>>> The problem is that it requires storing the sxw as a binary file,
>>> which doesn't help to track changes.
>>
>> Come on guys HTML, HTML, HTML! Forrest *already* can use HTML!
>
> Why that low-level? You don't have a real page structure then, it's to
> loose IMO.
HTML is not more low level than Document-DTD, and the h1s, h2s, h3s, etc
are transformed internally in sections.
Why HTML? Because everybody knows html, there are tons of books on it,
and virtually every editor can read and write html. And our primary
output is HTML.
> Don't forget Helma's effort on that:
> http://wiki.cocoondev.org/Wiki.jsp?page=Cocoon215TOC
Sure won't, thanks for the link :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] The Cocoon Handbook
Posted by Joerg Heinicke <jo...@gmx.de>.
On 25.06.2004 19:12, Nicola Ken Barozzi wrote:
>> The problem is that it requires storing the sxw as a binary file,
>> which doesn't help to track changes.
>
>
> Come on guys HTML, HTML, HTML! Forrest *already* can use HTML!
Why that low-level? You don't have a real page structure then, it's to
loose IMO.
Joerg
Re: [RT] The Cocoon Handbook
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Sylvain Wallez wrote:
...
> The problem is that it requires storing the sxw as a binary file, which
> doesn't help to track changes.
Come on guys HTML, HTML, HTML! Forrest *already* can use HTML!
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] The Cocoon Handbook
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Sylvain Wallez wrote:
...
> The problem is that it requires storing the sxw as a binary file, which
> doesn't help to track changes.
Come on guys HTML, HTML, HTML! Forrest *already* can use HTML!
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [RT] The Cocoon Handbook
Posted by Reinhard Poetz <re...@apache.org>.
Sylvain Wallez wrote:
> Vadim Gritsenko wrote:
>
>> Sylvain Wallez wrote:
>>
>>> Now we have that nice thing called OpenOffice that is a
>>> wordprocessor storing its content as XML in a zip archive. We've
>>> used it as a front-end for a CMS, providing template documents with
>>> style sheets that have to be used. These styles match the structure
>>> of the target XML document that is produced from the OO file. This
>>> solution just rocks, as anybody (even a boss :-) is able to write
>>> content in a userfriendly and productive environment with spell
>>> checking, typing completion, etc etc. On the CMS side, the sxw
>>> archive is exploded, the XML content is transformed into the target
>>> markup (e.g. DocBook) and images are stored.
>>>
>>> Sure, for the Cocoon docs, we cannot wait to have a CMS setup and
>>> ready, or we'll never have docs ;-) What is rather simple, however,
>>> is to have some offline processing (based on the CLI) that would do
>>> the exploding/recomposition job to allow editing Cocoon docs with a
>>> real wordprocessor.
>>
>>
>>
>>
>> It would be simplier to store docs in sxw file itself; no
>> recomposition is necessary, and html/pdf publishing out of sxw
>> "repository" can be added to forrest.
>
>
>
> The problem is that it requires storing the sxw as a binary file,
> which doesn't help to track changes.
>
> A mid-term solution can be to dezip the sxw and store it's various
> components as is. The exploding/recomposition process would then
> simply be unzip/zip.
Another way could be storing the whole document as one file by using
import/export filters that creates a single XML document and you don't
have to deal with the whole bunch of docs.
--
Reinhard
Re: [RT] The Cocoon Handbook
Posted by Sylvain Wallez <sy...@apache.org>.
Vadim Gritsenko wrote:
> Sylvain Wallez wrote:
>
>> Now we have that nice thing called OpenOffice that is a wordprocessor
>> storing its content as XML in a zip archive. We've used it as a
>> front-end for a CMS, providing template documents with style sheets
>> that have to be used. These styles match the structure of the target
>> XML document that is produced from the OO file. This solution just
>> rocks, as anybody (even a boss :-) is able to write content in a
>> userfriendly and productive environment with spell checking, typing
>> completion, etc etc. On the CMS side, the sxw archive is exploded,
>> the XML content is transformed into the target markup (e.g. DocBook)
>> and images are stored.
>>
>> Sure, for the Cocoon docs, we cannot wait to have a CMS setup and
>> ready, or we'll never have docs ;-) What is rather simple, however,
>> is to have some offline processing (based on the CLI) that would do
>> the exploding/recomposition job to allow editing Cocoon docs with a
>> real wordprocessor.
>
>
>
> It would be simplier to store docs in sxw file itself; no
> recomposition is necessary, and html/pdf publishing out of sxw
> "repository" can be added to forrest.
The problem is that it requires storing the sxw as a binary file, which
doesn't help to track changes.
A mid-term solution can be to dezip the sxw and store it's various
components as is. The exploding/recomposition process would then simply
be unzip/zip.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Re: [RT] The Cocoon Handbook
Posted by Vadim Gritsenko <va...@reverycodes.com>.
Sylvain Wallez wrote:
> Now we have that nice thing called OpenOffice that is a wordprocessor
> storing its content as XML in a zip archive. We've used it as a
> front-end for a CMS, providing template documents with style sheets
> that have to be used. These styles match the structure of the target
> XML document that is produced from the OO file. This solution just
> rocks, as anybody (even a boss :-) is able to write content in a
> userfriendly and productive environment with spell checking, typing
> completion, etc etc. On the CMS side, the sxw archive is exploded, the
> XML content is transformed into the target markup (e.g. DocBook) and
> images are stored.
>
> Sure, for the Cocoon docs, we cannot wait to have a CMS setup and
> ready, or we'll never have docs ;-) What is rather simple, however, is
> to have some offline processing (based on the CLI) that would do the
> exploding/recomposition job to allow editing Cocoon docs with a real
> wordprocessor.
It would be simplier to store docs in sxw file itself; no recomposition
is necessary, and html/pdf publishing out of sxw "repository" can be
added to forrest.
Vadim
Re: OpenOffice frontend for CMS
Posted by Jon Evans <jo...@misgl.com>.
Hi Sylvain,
On 25 Jun 2004, at 14:15, Sylvain Wallez wrote:
> It's proprietary, but some basic blocks that were needed to build it
> are
> now in Cocoon: ZipArchiveSerializer, CVSSource (at cocoondev.org), some
> parts of Cocoon Forms, etc.
OK, cheers. It sounds like an idea worth pursuing here for a web app
we're developing.
Thanks,
Jon
Re: OpenOffice frontend for CMS
Posted by Reinhard Poetz <re...@apache.org>.
Sylvain Wallez wrote:
> Jon Evans wrote:
>
>> Hi Sylvain,
>>
>> On 25 Jun 2004, at 11:42, Sylvain Wallez wrote:
>>
>>> Now we have that nice thing called OpenOffice that is a wordprocessor
>>> storing its content as XML in a zip archive. We've used it as a
>>> front-end for a CMS, providing template documents with style sheets
>>> that
>>> have to be used. These styles match the structure of the target XML
>>> document that is produced from the OO file. This solution just
>>> rocks, as
>>> anybody (even a boss :-) is able to write content in a userfriendly and
>>> productive environment with spell checking, typing completion, etc etc.
>>> On the CMS side, the sxw archive is exploded, the XML content is
>>> transformed into the target markup (e.g. DocBook) and images are
>>> stored.
>>
>>
>>
>> That's an inspired solution - is it all proprietary or is your code
>> published somewhere?
>
>
>
> It's proprietary, but some basic blocks that were needed to build it
> are now in Cocoon: ZipArchiveSerializer, CVSSource (at cocoondev.org),
> some parts of Cocoon Forms, etc.
>
> Sylvain
>
It is possible to use OpenOffice-Writer documents in Forrest - see the
examples after seeding a new Forrest project. For me this works well. I
think this could be interesting for Cocoon too.
Currently the .sxw docs are stored and during the rendering process the
ZIPSource is used to extract the content and create the documentation.
--
Reinhard, writing this without reading the whole thread
Re: OpenOffice frontend for CMS
Posted by Sylvain Wallez <sy...@apache.org>.
Jon Evans wrote:
> Hi Sylvain,
>
> On 25 Jun 2004, at 11:42, Sylvain Wallez wrote:
>
>> Now we have that nice thing called OpenOffice that is a wordprocessor
>> storing its content as XML in a zip archive. We've used it as a
>> front-end for a CMS, providing template documents with style sheets that
>> have to be used. These styles match the structure of the target XML
>> document that is produced from the OO file. This solution just rocks, as
>> anybody (even a boss :-) is able to write content in a userfriendly and
>> productive environment with spell checking, typing completion, etc etc.
>> On the CMS side, the sxw archive is exploded, the XML content is
>> transformed into the target markup (e.g. DocBook) and images are stored.
>
>
> That's an inspired solution - is it all proprietary or is your code
> published somewhere?
It's proprietary, but some basic blocks that were needed to build it are
now in Cocoon: ZipArchiveSerializer, CVSSource (at cocoondev.org), some
parts of Cocoon Forms, etc.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
OpenOffice frontend for CMS (was: [RT] The Cocoon Handbook)
Posted by Jon Evans <jo...@misgl.com>.
Hi Sylvain,
On 25 Jun 2004, at 11:42, Sylvain Wallez wrote:
> Now we have that nice thing called OpenOffice that is a wordprocessor
> storing its content as XML in a zip archive. We've used it as a
> front-end for a CMS, providing template documents with style sheets
> that
> have to be used. These styles match the structure of the target XML
> document that is produced from the OO file. This solution just rocks,
> as
> anybody (even a boss :-) is able to write content in a userfriendly and
> productive environment with spell checking, typing completion, etc etc.
> On the CMS side, the sxw archive is exploded, the XML content is
> transformed into the target markup (e.g. DocBook) and images are
> stored.
That's an inspired solution - is it all proprietary or is your code
published somewhere?
Cheers,
Jon
Re: [RT] The Cocoon Handbook
Posted by Sylvain Wallez <sy...@apache.org>.
Tony Collen wrote:
> This is a late-night, rambling [RT]. I think it's a good idea. You
> may or may not. Please flame, argue, discuss, rant, etc... it's an
> [RT], after all... Have fun!
>
> >> The Problem: Documentation <<
> Right here is where I would discuss the problem in a more in-depth
> sort of way, but since my brain is pretty much shut down, that's not
> going to happen. Insert your own rambling explanation of why the docs
> stink. ;)
>
> >> The Solution <<
> I propose we create a free, high-quality electronic book (entitled
> _The_Cocoon_Handbook_), which will eventually replace the mess of docs
> we currently have.
A big +1.
> It will be in DocBook (possibly simplified) format.
>
> Not only are we having a hard enough time keeping the documentation
> up-to-date normally, fightning the rampant wiki spamming has become
> almost a full-time job as it is.
>
> We can integrate the eventual book with user-added notations, similar
> to how PHP lets people log in and annotate the existing docs.
There are two main problems that IMO explain the poor state of Cocoon docs.
The first one is that Cocoon being a large beast, it's doc has to be
large, and therefore needs a well-defined structure. There has been
various attemps made which need to be continued, one problem being that
it seems whe have some fears to change the structure (or lack thereof)
of the current docs.
The second one is that writing docs in XML is a major PITA, futhermore
when we have fancy word processors just a click away on our computers.
I'm sure that it refrains many prople from writing docs (including me).
Intermediate tools like XXE ease the job, but aren't as userfriendly as
good old MS Word. Simplified syntaxes as wiki are good for small
documents (i.e. a page) but IMO don't scale for large structured
documentations.
Now we have that nice thing called OpenOffice that is a wordprocessor
storing its content as XML in a zip archive. We've used it as a
front-end for a CMS, providing template documents with style sheets that
have to be used. These styles match the structure of the target XML
document that is produced from the OO file. This solution just rocks, as
anybody (even a boss :-) is able to write content in a userfriendly and
productive environment with spell checking, typing completion, etc etc.
On the CMS side, the sxw archive is exploded, the XML content is
transformed into the target markup (e.g. DocBook) and images are stored.
Sure, for the Cocoon docs, we cannot wait to have a CMS setup and ready,
or we'll never have docs ;-) What is rather simple, however, is to have
some offline processing (based on the CLI) that would do the
exploding/recomposition job to allow editing Cocoon docs with a real
wordprocessor.
Yes, talking about technology rather than about writers, but IMO writers
will come if they can use productive tools for the job.
WDYT?
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }