Mailing-List: contact cocoon-dev-help@xml.apache.org; run by ezmlm
Message-ID: <3933C58E.DF478EA4@infoplanning.com>
Date: Tue, 30 May 2000 09:43:42 -0400
From: Berin Loritsch <bloritsch@infoplanning.com>
MIME-Version: 1.0
To: cocoon-dev@xml.apache.org
Subject: Re: Offer to help on Cocoon documentation
References: 
 <D1296DD028D0D21194FB0008C7E95BEA01C24B3C@mail.library.ualberta.ca>
 <3932CDC8.F2A5537@apache.org>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit

One question below:

Stefano Mazzocchi wrote:

> [copied on the list to let everyone know]
>
> pbinkley@library.ualberta.ca wrote:
> >
> > There
> > are lots of minor grammatical errors, and a few more significant problems
> > that make the meaning obscure. Since people always respond better to a text
> > that looks more "finished", I think it would be worthwhile to fix these
> > little errors, even the cosmetic ones. I have a humanities Ph.D. (medieval
> > history, God help me), I've written for publication, and I have experience
> > in editing English texts written by non-native-speakers for publication. I
> > would be very happy to take on some of the editing work, and perhaps free up
> > some of the developers' time for more important things.
>
> You are our saviour, man! I've always wanted somebody like you around,
> it would make the project _so_ much better and nicer....
>
> > If this makes sense to you, let me know how we can make this work.
>
> Totally!
>
> Ok, since many people asked to help in the documentation, I'll explain
> how the documentation process goes as far as Cocoon1 is concerned:
>
> 1) document originals are written in XML using a simple HTML-like DTD we
> designed. All the documents are found in the /xdocs/ directory and the
> DTDs are found in the /xdocs/DTD directory.
>
> 2) to generate the documentation simply type "./build.sh docs" or
> ".\build.bat docs" at the command line. HTML documents will be generated
> in the /build/docs directory.
>
> 3) feel free to modify, add, change, comment, expand, cleanup, fix, or
> otherwise improve the documentation you find in the xdocs directory. Do
> _NOT_ modify or send documentation in HTML since this won't be accepted.
>
> 4) if you want to add a page to the documentation, you have to modify
> "docs-book.xml" and "site-book.xml" files, which represent the
> micro-sitemap for documentation. (learn by example, the book schema is
> very easy)
>
> 5) provide us with patches or complete documents. Please, run them once
> in the build process to validate them and make sure the markup is
> correct (this will guarantee the stylesheets won't mess up with them,
> XML validation is awesome when used correctly!)
>
> So far so good.
>
> For the Cocoon2 project, I would love to move all the documentation into
> Docbook, but don't worry, this can be easily done with XSLT and the
> original DTD can be used if you think it's simpler. Anyway, do take a
> look at the DocBook DTD to find out the potentials.
>
> Thanks in advance for your help and don't feel pushed: anything help
> you'll be able to provide will make us happy.
>
> --
> Stefano Mazzocchi      One must still have chaos in oneself to be
>                           able to give birth to a dancing star.
> <stefano@apache.org>                             Friedrich Nietzsche
> --------------------------------------------------------------------
>  Missed us in Orlando? Make it up with ApacheCON Europe in London!
> ------------------------- http://ApacheCon.Com ---------------------

Do we post documentation changes/patches/additions here?  I want to get
involved with beefing up programmer oriented documentation / JavaDoc
improvements, and (of course) do not have privileges to update CVS
(or even an account).  How do we incorporate our work?