You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Diana Shannon <te...@mac.com> on 2002/04/18 00:48:00 UTC
Greetings
At the thoughtful prompting of Nicola Ken and Steven, I just wanted to
let everyone know I am now intently following this list. Today, I reread
the *entire* email archive and started to play with the most recent cvs.
I'm really impressed by the efforts to date. I also am mindful of the
crucial role this architecture will play in improving the quality and
features of Cocoon 2 and other Apache documentation down the road.
Nevertheless, if I'm voted in a document coordinator for Cocoon, I
suspect I will have my hands full, at least initially, addressing
problems related to the *substance* of the documentation (and not its
architectural basis). Go ahead and call me old-fashioned, but I remain
concerned that existing content problems prevent/delay a critical mass
of users from recognizing the brilliance of projects like Cocoon and
Forrest. Steven has kindly offered to help out with the documentation
coordination effort, and I have every confidence in his ability to make
sure that effort takes full advantage of Forrest.
Here are just a few (probably rookie) comments.
- This may be trivial issue, but you may want to consider how Forrest
might implement community-oriented features of web site. For example, a
search of "how-tos" at http://www.zope.org/Documentation revealed more
than 577 different topics/pages (maintained on member pages).
- The priority of clean URI space is going to be a welcome relief, given
the potential pitfalls of current linking habits within Cocoon's
existing document structure.
- Automatic document updates will free up document coordination efforts
to focus more on content. Hooray!
- The prospect of capturing user feedback (in far more creative ways
than form-based submission presently allows) at the critical moment when
they actually *use* a page is very cool indeed.
So great job everyone! Hope to be able to contribute something of value
down the road. Until then, I'll be paying close attention.
Diana Shannon
... quite relieved to have her name out of the subject line! :)
Re: Ok, I give up
Posted by "J.Pietschmann" <j3...@yahoo.de>.
Nicola Ken Barozzi wrote:
> Forrest guys, why not change the faq have sections?
I have this already for the Big FAQ in progress for FOP.
J.Pietschmann
faq.dtd [was: RE: Ok, I give up]
Posted by Steven Noels <st...@outerthought.org>.
Sylvain,
> >>So my non-voting +1 for adding sections and IDs to the FAQ.
> >>
> >
> >I tweaked the faq.dtd already yesterday: it can now be composed of a
> >number of 'parts', and Q/A already bear an id attribute.
> >
> >Is that what you were looking for?
> >
>
> Exactly. But couldn't you use the 'section' element that's already
> defined in the document DTD ?
Uh? How? Remember we currently are using DTDs, so element content models
cannot easily be adapted according to their context. So I used a 'part'
element on purpose, because the content model of 'section' contains a
lot of elements I don't want to have in our FAQ documents.
We could of course redefine the section element for faq documents in the
local declaration subset, but this would be overly hard to use for
XML-intimacies-challenged documentation editors:
somefaq.xml:
---------------------
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.1//EN" "faq-v11.dtd" [
<!-- locally declared elements override previous element
declaration -->
<!ELEMENT section ((faq | part)+) >
<!ATTLIST section %title.att; %common.att;>
]>
<faqs/>
---------------------
I'm quite sure nobody wants to start editing an faq if he first has to
make sure he follows the exact syntax as the example above... or not?
Regards,
</Steven>
Re: Ok, I give up
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Steven Noels wrote:
>Sylvain,
>
>(welcome ;-)
>
>>The FAQ DTD used in Cocoon 1 had sections and entries had an
>>ID, which
>>is especially usefull for linking or giving the URL as an answer to a
>>user question (autogenerated numbers change as new entries are added).
>>
>>So my non-voting +1 for adding sections and IDs to the FAQ.
>>
>
>I tweaked the faq.dtd already yesterday: it can now be composed of a
>number of 'parts', and Q/A already bear an id attribute.
>
>Is that what you were looking for?
>
Exactly. But couldn't you use the 'section' element that's already
defined in the document DTD ?
Sylvain
--
Sylvain Wallez
Anyware Technologies Apache Cocoon
http://www.anyware-tech.com mailto:sylvain@apache.org
RE: Ok, I give up
Posted by Steven Noels <st...@outerthought.org>.
Sylvain,
(welcome ;-)
>
> The FAQ DTD used in Cocoon 1 had sections and entries had an
> ID, which
> is especially usefull for linking or giving the URL as an answer to a
> user question (autogenerated numbers change as new entries are added).
>
> So my non-voting +1 for adding sections and IDs to the FAQ.
I tweaked the faq.dtd already yesterday: it can now be composed of a
number of 'parts', and Q/A already bear an id attribute.
Is that what you were looking for?
</Steven>
Re: Ok, I give up
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Nicola Ken Barozzi wrote:
>The request we had 20020406:
><whatwasposted>
>From: "Glen Stampoultzis" <gs...@iprimus.com.au>
>
>>It would be handy if the FAQ could contain sections. At the moment there's nothing that lets you distinguish entries.
>>
>
>Good suggestion.
>Forrest guys, why not change the faq have sections?
>
The FAQ DTD used in Cocoon 1 had sections and entries had an ID, which
is especially usefull for linking or giving the URL as an answer to a
user question (autogenerated numbers change as new entries are added).
See the DTD at
http://cvs.apache.org/viewcvs.cgi/xml-cocoon/xdocs/dtd/faq-v10.dtd?rev=1.3&content-type=text/vnd.viewcvs-markup
and the Cocoon 1 FAQ at
http://cvs.apache.org/viewcvs.cgi/xml-cocoon/xdocs/faq.xml?rev=1.51&content-type=text/vnd.viewcvs-markup
So my non-voting +1 for adding sections and IDs to the FAQ.
Sylvain (first post to forrest :)
--
Sylvain Wallez
Anyware Technologies Apache Cocoon
http://www.anyware-tech.com mailto:sylvain@apache.org
Re: Ok, I give up
Posted by Nicola Ken Barozzi <ni...@apache.org>.
The request we had 20020406:
<whatwasposted>
From: "Glen Stampoultzis" <gs...@iprimus.com.au>
> It would be handy if the FAQ could contain sections. At the moment
there's
> nothing that lets you distinguish entries.
Good suggestion.
Forrest guys, why not change the faq have sections?
</whatwasposted>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
----- Original Message -----
From: "Steven Noels" <st...@outerthought.org>
To: <fo...@xml.apache.org>
Sent: Thursday, April 18, 2002 4:21 PM
Subject: RE: Ok, I give up
> Oops:
>
> http://cvs.apache.org/viewcvs.cgi/xml-forrest/src/resources/schema/dtd/f
> aq-v11.dtd?rev=1.1&content-type=text/vnd.viewcvs-markup
>
> > -----Original Message-----
> > From: Steven Noels [mailto:stevenn@outerthought.org]
> > Sent: donderdag 18 april 2002 16:19
> > To: forrest-dev@xml.apache.org
> > Subject: RE: Ok, I give up
> >
> >
> > Alex,
> >
> > this is the FAQ dtd for now, but as you see it aggregates all faqs in
> > one file.
> >
> > it is very simple, and makes reference to the document.dtd (xdoc),
> > locates in the same xml-forrest cvs module
> >
> > regards,
> >
> > </Steven>
>
>
RE: Ok, I give up
Posted by Steven Noels <st...@outerthought.org>.
Oops:
http://cvs.apache.org/viewcvs.cgi/xml-forrest/src/resources/schema/dtd/f
aq-v11.dtd?rev=1.1&content-type=text/vnd.viewcvs-markup
> -----Original Message-----
> From: Steven Noels [mailto:stevenn@outerthought.org]
> Sent: donderdag 18 april 2002 16:19
> To: forrest-dev@xml.apache.org
> Subject: RE: Ok, I give up
>
>
> Alex,
>
> this is the FAQ dtd for now, but as you see it aggregates all faqs in
> one file.
>
> it is very simple, and makes reference to the document.dtd (xdoc),
> locates in the same xml-forrest cvs module
>
> regards,
>
> </Steven>
RE: Ok, I give up
Posted by Steven Noels <st...@outerthought.org>.
Alex,
this is the FAQ dtd for now, but as you see it aggregates all faqs in
one file.
it is very simple, and makes reference to the document.dtd (xdoc),
locates in the same xml-forrest cvs module
regards,
</Steven>
Re: Ok, I give up
Posted by alex <al...@yahoo.com>.
At 13:00 18/04/2002, Diana Shannon wrote:
>I get it now. You guys harrass people until they start contributing. Fine.
>Give me something to do.
>Diana
I'd be very greatful if someone could investigate FAQs and tell me whether
we have an official format for XML FAQs?
I am putting together a noddy little perl script
(http://www.OWAL.co.uk/cgi-bin/fopfaq.cgi ) which takes FAQ data stored in
the old Jyve FAQ program and presents it as HTML or in future XML. However
I don't know much about the FAQ ML or what we are using in Apache.
This *is* appropraite for forrest isn't it?
Alex
Re: Ok, I give up
Posted by Diana Shannon <te...@mac.com>.
David:
> No Diana, that is not our style. I think that Steven's previous
> posting "Welcome to DIANA SHANNON [was: RE: Greetings]"
> was just a joke, playing on your prior comment that it
> would be nice to get your name out of the subject line.
I realized the joke, just forget to add ;) to my response. My mistake.
> Also, i wonder if this discussion about Cocoon
> documentation is really meant for the cocoon-dev list.
> I thought that "Forrest" is intended as an infrastructure
> for pulling together consistent documentation for various
> projects. Each project's own documentation content and
> structure should be their issue.
I think Steven only suggested investigating C2 as a case study. I was
under the impression that we might abstract out, from that review,
components (document templates, author guidelines) which might be useful
to other projects. I was looking for something to do while waiting for
the C2 voting process to finish. I'm trying to learn how to leverage
existing resources. That's all.
Diana
Re: Ok, I give up
Posted by David Crossley <cr...@indexgeo.com.au>.
Diana Shannon wrote:
> I get it now. You guys harrass people until they start contributing.
> Fine. Give me something to do.
No Diana, that is not our style. I think that Steven's previous
posting "Welcome to DIANA SHANNON [was: RE: Greetings]"
was just a joke, playing on your prior comment that it
would be nice to get your name out of the subject line.
By the way, please use sensible subject lines for
discussion threads. It is already a nightmare trying
to follow these voluminous lists.
Also, i wonder if this discussion about Cocoon
documentation is really meant for the cocoon-dev list.
I thought that "Forrest" is intended as an infrastructure
for pulling together consistent documentation for various
projects. Each project's own documentation content and
structure should be their issue.
Anyway, welcome Diana, to both Cocoon and Forrest.
--David Crossley
Re: entry points [was:Re: Ok, I give up]
Posted by Stefano Mazzocchi <st...@apache.org>.
Robert Koberg wrote:
> > Couldn't agree with you more. However, Cocoon as "glue technology" has
> > an extremely varied potential user base.
>
> Yes, that was what I was trying to address.
Ehm, people: this list is supposed to talk to an instrstructure system
about documents, *not* about some 'cocoon' specific documentation
contents.
Please, let's move this over to Cocoon-dev, thanks.
--
Stefano Mazzocchi One must still have chaos in oneself to be
able to give birth to a dancing star.
<st...@apache.org> Friedrich Nietzsche
--------------------------------------------------------------------
Re: entry points [was:Re: Ok, I give up]
Posted by Robert Koberg <ro...@koberg.com>.
Diana Shannon wrote:
> Robert:
>
>> How about defining different entry points to cocoon. Example tracks:
>> 1. total newbie - very basic stuff to get them started
>> 2. experienced web developer but inexperienced at java or XSLT
>> 3. experienced web developer with java but inexperienced with XSLT
>> 4. inexperienced (serious) web developer that knows XSLT well
>> 5. ???
>
>
> Very good idea. We could develop audience profiles for these groups
> that include assumptions about concepts most likely to need
> reinforcement, based on pre-Cocoon preconceptions. This stuff pops up
> all the time on the user list, like folks wanting to override a
> serialization configuration from a stylesheet's xml:output method.
>
>> Everybody seems to be coming from cocoon at different angles. Define
>> what is common to all and then split out to the entry points.
>
>
> Couldn't agree with you more. However, Cocoon as "glue technology" has
> an extremely varied potential user base.
Yes, that was what I was trying to address.
> Also, think about how many flavors of experienced web developer types
> there are. I'm not saying it shouldn't/couldn't be done, but the
> audience comes with a lot of potential "baggage."
I would keep #2 as generic as possible. Over time, the users can fill in
the bulk of the specifics for a particular way in. I personally f�,�
this level of involvement would need a hierarchical organization of
contributors - not common ownership... hence some type of user
management. But that could be put off well into the future, I guess,
until there is a solid system in place.
>
>
>> For something like #4, speaking from experience, I would like to see
>> how you take an app that uses the XSLT/XPath document function to
>> aggregate content and turn that into a cocoon app that aggregates
>> content before the final transformation. I could provide the
>> XSLT/XML that aggregates content in the final transform using
>> document(), but I would not trust myself to give the best cocoon
>> conversion :(
>
>
> So how does that translate, ideally, into documents that fill up a
> learning path? Is this a tutorial directed specifically at audience
> #4? Or a combination of documents? If so, what types of documents?
I tried to use that as an example of - "here's how you do it with XYZ
technology" - "and here is how we would optimize it for/with cocoon." I
guess it would be a tutorial/philosophy thing.
Perhaps there is a page - "What do you want to do with Cocoon?" That
page is set up to look like a well organized FAQ that strings the user
out to something that they recognize. The path explores how they would
normally do things and compares that to how it should be done in cocoon
(always linking to more details). After they get exposed to cocoon in a
light that allows them to see, the path takes them into the common
cocoon learning/docs. That path brings them to the central idea of
cocoon with respect to their needs.
best,
-Rob
entry points [was:Re: Ok, I give up]
Posted by Diana Shannon <te...@mac.com>.
Robert:
> How about defining different entry points to cocoon. Example tracks:
> 1. total newbie - very basic stuff to get them started
> 2. experienced web developer but inexperienced at java or XSLT
> 3. experienced web developer with java but inexperienced with XSLT
> 4. inexperienced (serious) web developer that knows XSLT well
> 5. ???
Very good idea. We could develop audience profiles for these groups that
include assumptions about concepts most likely to need reinforcement,
based on pre-Cocoon preconceptions. This stuff pops up all the time on
the user list, like folks wanting to override a serialization
configuration from a stylesheet's xml:output method.
> Everybody seems to be coming from cocoon at different angles. Define
> what is common to all and then split out to the entry points.
Couldn't agree with you more. However, Cocoon as "glue technology" has
an extremely varied potential user base. Also, think about how many
flavors of experienced web developer types there are. I'm not saying it
shouldn't/couldn't be done, but the audience comes with a lot of
potential "baggage."
> For something like #4, speaking from experience, I would like to see
> how you take an app that uses the XSLT/XPath document function to
> aggregate content and turn that into a cocoon app that aggregates
> content before the final transformation. I could provide the XSLT/XML
> that aggregates content in the final transform using document(), but I
> would not trust myself to give the best cocoon conversion :(
So how does that translate, ideally, into documents that fill up a
learning path? Is this a tutorial directed specifically at audience #4?
Or a combination of documents? If so, what types of documents?
Diana
Re: Ok, I give up
Posted by Robert Koberg <ro...@koberg.com>.
Hi,
Steven Noels wrote:
>Diana,
>
>I'd start with outlining what is out there and try to define an overall
>document hierarchy - the docs aren't necessary badly structured, it's
>the access to the docs - I'm not too keen of the user/developer
>distinction.
>
>I can think of some and submit afterwards, but I'd really like you to
>give it a go...
>
>OK?
>
How about defining different entry points to cocoon. Example tracks:
1. total newbie - very basic stuff to get them started
2. experienced web developer but inexperienced at java or XSLT
3. experienced web developer with java but inexperienced with XSLT
4. inexperienced (serious) web developer that knows XSLT well
5. ???
Everybody seems to be coming from cocoon at different angles. Define
what is common to all and then split out to the entry points.
For something like #4, speaking from experience, I would like to see how
you take an app that uses the XSLT/XPath document function to aggregate
content and turn that into a cocoon app that aggregates content before
the final transformation. I could provide the XSLT/XML that aggregates
content in the final transform using document(), but I would not trust
myself to give the best cocoon conversion :(
On the XSLT list the default answer to the question - 'how do I use two
or more XML files as the source of my transformation?' - is always -
'use t���]ocument function, stupid.' It is rarely brought up that you
can or should aggregate content before the final transformation. So I
would bet that most people coming to cocoon from XSLT (which would seem
like a natural progression) are thouroughly confused by the approach taken.
best,
-Rob
[1] I could provide a set of XSLT and XML that can be used to create a
web site (dynamically or statically) by aggregating content at final
transform time. It contains:
article.xsl { // inlcudes
global_defintions.xsl { // which includes the following XSLTs
banner.xsl
find_xml.xsl
footer.xsl
head.xsl
html_tags.xsl
nav.xsl
}
}
article.xsl is a cached Templates object. It is transformed against the
particular site's site.xml file. Other config XML files are:
content.xml
// the following three deal with user management stuff
groups.xml
roles.xml
users.xml
you can use a simple sax content handler that quickly crawls through the
site.xml to generate the site to HTML, JSP, etc - or - you could use a
simple transform servlet if you want it dynamic.
Re: Ok, I give up
Posted by Diana Shannon <te...@mac.com>.
Steven Noels wrote:
> I'd start with outlining what is out there and try to define an overall
> document hierarchy
I've started this already.
> - the docs aren't necessary badly structured,
Well, I guess it depends on how you define structure. I would say they
are inconsistently structured within document types (e.g.
reference/concept/how-to etc.) at best.
> it's
> the access to the docs -
I agree with this and will try to illustrate how it occurs.
> I'm not too keen of the user/developer
> distinction.
Agree. It's artificial, somewhat arbitrary, and only serves to
discourage people. What might help, with certain types of docs, like
tutorials and how-tos, is to include some kind of classification level,
e.g., newbie/moderate/advanced.
> I can think of some and submit afterwards, but I'd really like you to
> give it a go...
Going. Thanks.
Diana
RE: Ok, I give up
Posted by Steven Noels <st...@outerthought.org>.
Diana,
I'd start with outlining what is out there and try to define an overall
document hierarchy - the docs aren't necessary badly structured, it's
the access to the docs - I'm not too keen of the user/developer
distinction.
I can think of some and submit afterwards, but I'd really like you to
give it a go...
OK?
</Steven>
Ok, I give up
Posted by Diana Shannon <te...@mac.com>.
I get it now. You guys harrass people until they start contributing.
Fine. Give me something to do.
- How about a list of documentation pieces to work on that Forrest
currently lacks and Cocoon also needs?
- Or, Steven mentioned something about making some new document
outlines. Would this be something on the order of creating some empty
page templates for authoring concept pieces/how-tos/code snippets/etc.?
I think it's a bit premature to subject them to any dtd other than
document-v11.dtd yet.
- I really like the cvs how-to section in the contrib.xml. I think lots
of users are overly intimidated by cvs. I could fill this out a bit,
even put it on its own page.
Diana
Re: Welcome to DIANA SHANNON [was: RE: Greetings]
Posted by Nicola Ken Barozzi <ni...@apache.org>.
;-P
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Welcome to DIANA SHANNON [was: RE: Greetings]
Posted by Steven Noels <st...@outerthought.org>.
hehe ;-)
</Steven>