You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Ovidiu Predescu <ov...@cup.hp.com> on 2001/08/21 09:17:32 UTC
Re: [Docs] General Planning
Hi Berin,
On Mon, 20 Aug 2001 10:12:16 -0400, Berin Loritsch <bl...@apache.org> wrote:
> The 1st order of business is the _requirement_ of both
> printable and browsable documentation. The Printable
> docs will be a very simple markup, with minimal graphics.
> They will have *no* navigation links. Browsable docs
> will be the current complex XML.apache.org format (which
> really needs revisiting). The Browsable docs will all
> have an extra link to view the printable version.
What do you mean by no navigation links inside the printable
documentation? If we generate PDF, we can have highlighted words which
are active links inside the PDF. When you print the PDF, the
highlighting disappears and looks like normal text. For an example
check-out the second page in:
http://xslt-process.sourceforge.net/xslt-process.pdf
> We need 3 documentation tracks:
>
> 1) Installation and Configuration
> 2) Using Cocoon (creating your own webapps)
> 3) Developing Cocoon (maintaining Cocoon/Cocoon architecture).
This sounds very good! I was thinking at exactly the same type of
documentation.
> I propose that for new documentation we use DocBook format.
> You will see examples in Avalon CVS (the Developing with
> Avalon documentation). The Stylesheets in the Avalon CVS
> can be adapted for Cocoon.
Why do we develop new stylesheets for DocBook? There is already a
project, DocBook-XSL, of Norman Walsh and many others, the DocBook
author, which has fairly extensive stylesheets. There are stylesheets
that generate HTML, XHTML and XML FO. The system is setup such that is
fairly easy to customize your own look and feel for the generated
output. I think we should use this rather than spend the energy on
creating our own stuff.
Take a look at:
http://docbook.sourceforge.net/
You need to look at the DocBook-XSL project.
> The URI space will be planned as such:
>
> cocoon2/ Welcome page and general overview--links to mailing
> lists, CVS, and distributions
>
> cocoon2/api The JavaDocs for Cocoon
>
> cocoon2/authors The list of author bios (linked from the documentation
> pages--like on Jakarta Avalon site)
>
> cocoon2/installing The installation and configuration documentation
>
> cocoon2/userdocs The user documentation (i.e. HowTo write your own
> webapps with Cocoon)
>
> cocoon2/developing The developer's docs on the architecture and design
> of Cocoon.
This looks good to me.
> There should be 4 FAQ documents:
>
> 1) cocoon2/faq.html Questions about Cocoon in general (what is it? why
> was it built? etc).
>
> 2) cocoon2/installing/faq.html Questions about installing and configuring
> Cocoon (XYZ doesn't work, what should I do?)
>
> 3) cocoon2/userdocs/faq.html Questions about how to do something in Cocoon
> (I need to serialize XML from a database, how?)
>
> 4) cocoon2/developing/faq.html Questions about maintaining Cocoon
> (I've spotted a bug and have a fix, how do I
> get it committed? Why is XYZ ThreadSafe?)
Should we try to use one of the Web FAQ tools out there? I especially
like the way the PHP documentation is setup (see for example
http://www.php.net/manual/en/functions.php). It allows external
contributors, not only commiters to add their own comments to the
documentation. It's a very powerful and loosely coupled way of
collaborating, especially on FAQs, and documentation examples.
Now I know we may not be very interested in having a PHP system
running on xml.apache.org, but it may be something to get us going
until we develop a Cocoon based system. We should just use the tool
that does the job, even if it's "not invented here" (TM) ;-).
I think the current way of managing the FAQ is making it slow for
updates and makes people think of alternative solutions. Just look at
the recent thread on cocoon-users, "reg c2 documentation HOW DO I", to
see what I mean. Even a simple process as sending an email with an FAQ
item to one of the committers for inclusion in the FAQ, may be a
process too much.
Greetings,
--
Ovidiu Predescu <ov...@cup.hp.com>
http://orion.nsr.hp.com/ (inside HP's firewall only)
http://sourceforge.net/users/ovidiu/ (my SourceForge page)
http://www.geocities.com/SiliconValley/Monitor/7464/ (GNU, Emacs, other stuff)
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [Docs] General Planning
Posted by David Crossley <cr...@indexgeo.com.au>.
On Tue, 21 Aug 2001, Ovidiu Predescu wrote:
> On Mon, 20 Aug 2001 Berin Loritsch <bl...@apache.org> wrote:
> > [ snip ]
> >
> > There should be 4 FAQ documents:
> >
> > 1) cocoon2/faq.html Questions about Cocoon in general (what is it? why
> > was it built? etc).
> >
> > 2) cocoon2/installing/faq.html Questions about installing and configuring
> > Cocoon (XYZ doesn't work, what should I do?)
> >
> > 3) cocoon2/userdocs/faq.html Questions about how to do something in Cocoon
> > (I need to serialize XML from a database, how?)
> >
> > 4) cocoon2/developing/faq.html Questions about maintaining Cocoon
> > (I've spotted a bug and have a fix, how do I
> > get it committed? Why is XYZ ThreadSafe?)
I am afraid that even that arrangement will turn into
clumsy monster FAQ documents which are slow to render
by the client. My proposal on a separate thread, to split
the current giant FAQ into topic documents, was only
meant as a stop-gap solution.
The general proposal from Ovidiu below to use a Web-based
FAQ tool is far better. The best that i have seen is
FAQ-O-Matic ... http://faqomatic.sourceforge.net/
It has a real nice interface, immensely configurable.
Its most important feature is that it is collaborative
(both on input and on content management). It is a
stand-alone CGI-based application (in Perl i think).
Whichever solution is chosen, we need to be sure that we
can export the content in a structured way to take to a
future Cocoon-based application.
cheers, David Crossley
Ovidiu Predescu continued:
> Should we try to use one of the Web FAQ tools out there? I especially
> like the way the PHP documentation is setup (see for example
> http://www.php.net/manual/en/functions.php). It allows external
> contributors, not only commiters to add their own comments to the
> documentation. It's a very powerful and loosely coupled way of
> collaborating, especially on FAQs, and documentation examples.
>
> Now I know we may not be very interested in having a PHP system
> running on xml.apache.org, but it may be something to get us going
> until we develop a Cocoon based system. We should just use the tool
> that does the job, even if it's "not invented here" (TM) ;-).
>
> I think the current way of managing the FAQ is making it slow for
> updates and makes people think of alternative solutions. Just look at
> the recent thread on cocoon-users, "reg c2 documentation HOW DO I", to
> see what I mean. Even a simple process as sending an email with an FAQ
> item to one of the committers for inclusion in the FAQ, may be a
> process too much.
>
> Greetings,
> --
> Ovidiu Predescu <ov...@cup.hp.com>
> http://orion.nsr.hp.com/ (inside HP's firewall only)
> http://sourceforge.net/users/ovidiu/ (my SourceForge page)
> http://www.geocities.com/SiliconValley/Monitor/7464/ (GNU, Emacs, other stuff)
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [Docs] General Planning
Posted by Berin Loritsch <bl...@apache.org>.
Ovidiu Predescu wrote:
>
> Hi Berin,
>
> On Mon, 20 Aug 2001 10:12:16 -0400, Berin Loritsch <bl...@apache.org> wrote:
>
> > The 1st order of business is the _requirement_ of both
> > printable and browsable documentation. The Printable
> > docs will be a very simple markup, with minimal graphics.
> > They will have *no* navigation links. Browsable docs
> > will be the current complex XML.apache.org format (which
> > really needs revisiting). The Browsable docs will all
> > have an extra link to view the printable version.
>
> What do you mean by no navigation links inside the printable
> documentation? If we generate PDF, we can have highlighted words which
> are active links inside the PDF. When you print the PDF, the
> highlighting disappears and looks like normal text. For an example
> check-out the second page in:
>
> http://xslt-process.sourceforge.net/xslt-process.pdf
That's fine. I was refering to the links on the side that are present
in the current printable docs. The whole point is that the tables used
on those pages constrain the browser, and cause the pages to cut off
the important text on the right side of the page when printed.
> > We need 3 documentation tracks:
> >
> > 1) Installation and Configuration
> > 2) Using Cocoon (creating your own webapps)
> > 3) Developing Cocoon (maintaining Cocoon/Cocoon architecture).
>
> This sounds very good! I was thinking at exactly the same type of
> documentation.
>
> > I propose that for new documentation we use DocBook format.
> > You will see examples in Avalon CVS (the Developing with
> > Avalon documentation). The Stylesheets in the Avalon CVS
> > can be adapted for Cocoon.
>
> Why do we develop new stylesheets for DocBook? There is already a
> project, DocBook-XSL, of Norman Walsh and many others, the DocBook
> author, which has fairly extensive stylesheets. There are stylesheets
> that generate HTML, XHTML and XML FO. The system is setup such that is
> fairly easy to customize your own look and feel for the generated
> output. I think we should use this rather than spend the energy on
> creating our own stuff.
I have looked at those, and tried to use them. They are slow, cumbersome,
and difficult to customize. Moreover, the results are kind of ugly. Part
of this is due to the great many things Norman Walsh is doing to get 100%
of DocBook working through XSL. The stylesheets I wrote for Avalon are fast,
simple, and easy to customize. They do not try to do 100% of DocBook, awaiting
customization for elements as they are needed--instead of trying to build the
whole thing at one time.
> Should we try to use one of the Web FAQ tools out there? I especially
> like the way the PHP documentation is setup (see for example
> http://www.php.net/manual/en/functions.php). It allows external
> contributors, not only commiters to add their own comments to the
> documentation. It's a very powerful and loosely coupled way of
> collaborating, especially on FAQs, and documentation examples.
This is Cocoon after all, we could do our own....
There is also the Apache FAQ tool that is up and down, and needs maintenance.
It can't be customized to make it look like Cocoon's site.
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [Docs] General Planning
Posted by David Crossley <cr...@indexgeo.com.au>.
Perhaps the DocBook subset would be appropriate.
www.oasis-open.org/docbook/
follow the link to "A Simplified DocBook subset".
regards, David Crossley
Ovidiu Predescu said:
> Berin Loritsch said:
> > I propose that for new documentation we use DocBook format.
> > You will see examples in Avalon CVS (the Developing with
> > Avalon documentation). The Stylesheets in the Avalon CVS
> > can be adapted for Cocoon.
>
> Why do we develop new stylesheets for DocBook? There is already a
> project, DocBook-XSL, of Norman Walsh and many others, the DocBook
> author, which has fairly extensive stylesheets. There are stylesheets
> that generate HTML, XHTML and XML FO. The system is setup such that is
> fairly easy to customize your own look and feel for the generated
> output. I think we should use this rather than spend the energy on
> creating our own stuff.
>
> Take a look at:
>
> http://docbook.sourceforge.net/
>
> You need to look at the DocBook-XSL project.
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org