Ovidiu Predescu wrote:
>
> Hi Berin,
>
> On Mon, 20 Aug 2001 10:12:16 -0400, Berin Loritsch <[EMAIL PROTECTED]> 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: [EMAIL PROTECTED]
For additional commands, email: [EMAIL PROTECTED]
