cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Andreas Hochsteger" <e9625...@student.tuwien.ac.at>
Subject Re: [DOC] How to contribute documentation
Date Sat, 11 May 2002 21:02:20 GMT
Hi!

"Nicola Ken Barozzi" <nicolaken@apache.org> wrote:

> From: "Andreas Hochsteger" <e9625392@student.tuwien.ac.at>
> 
> 
> > I just started to contribute some documentation to cocoon and saw some
> > difficulties to get it going for a cocoon newbie.
> > Diana had the nice idea that I could write up a howto for that task.
> Therefore
> > I need to ask the community some questions about the documentation
> > contribution process.
> 
> :-)
> 
> > If you got the correct xml files done and updated the corresponding
> book.xml
> > you have to open a bug report in bugzilla.
> >
> > I used the following options which I not quite sure if they are alright:
> > Product: Cocoon2
> > Component: General components (shouldn't there be Documentation?)
> > Platform: All
> > OS: All
> > Version: Current CVS
> > Severity: Enhancement
> >
> > If a person works over and over again on the same docs, is it ok to
reopen
> an
> > existing bug report and just provide a new attachment or do you have to
> open
> > a new bug report (and enter much redundant information again)?
> 
> Usually when a "bug", or in this case enhancement is "committed" (ie
> accepted and inserted), the bug is closed.
> If it weren't so we would have very long bug reports, and it would make it
> difficult to manage.

I understand. So in the future I'll do it that way and will document that in
the howto.
Nevertheless I think it might be good to provide a better solution for
documentation writers.
Especially for newbies, which don't have the knowledge of experienced
developers.

> If, instead, your second submission enhances the previous one, and the
> previous one hasn't been "committed" yet, you should add (to the same bug
> report) a patch that substitutes the previous one.
> 
> > I edited my docs with a standard text editor and viewed the results
> directly
> > through a local running cocoon. In the contribution docs I read that
> cocoon
> > cannot provide you with detailed information about documentation errors.
> > Wouldn't it be nice to have such thing in cocoon, to make the author's
> life
> > much easier?
> 
> Could you please expand more on this? It seems like an intersting feature
> one would need.

If you look at http://xml.apache.org/cocoon/contrib.html at the last section

named "Contribution Notes and Tips" you can find the following mentioned
there:

When making changes to XML documentation, or any XML document for that
matter, 
use a validating parser (one that is tried and true is OpenSP/onsgmls). 
This procedure will detect errors without having to go through the whole
build docs process to find them. 
Do not expect Cocoon or the build system to detect the validation errors for
you - they can do it, but that is not their purpose. 
(Anyway, onsgmls validation error messages are more informative.) 

I thought that it would be nice, to have cocoon using such a validating
parser 
with a special pipeline designed for authors.
There would be even more possibilities to help documentation writers in their
task.

Something like a list of referenced internal and external documents or link
checking
comes to my mind. Perhaps the Forrest project provides something like that, 
but I couldn't find any information about it yet. It seems that there only
exists 
a cvs repository, so a little information about it would be helpful.

> Since the document is XML, we encourage to use an editor that can validate
> your document with the right DTD.

I know that a validating xml editor is the right choice, but everybody has
his
own favourite editor and cocoon should not force an author to use a special
kind of it.

> In this way you are sure that Cocoon will be able to compile it without
> having to recreate all the docs.
> 
> A cool editor I use (free) is XML Cooktop 2000
> http://www.xmleverywhere.com/cooktop/
> (or at http://www.simtel.net/pub/pd/53216.html)

Thanks, I'll try it.

> Cheers!
> 
> --
> Nicola Ken Barozzi                   nicolaken@apache.org

Bye,

        Andreas




---------------------------------------------------------------------
Please check that your question has not already been answered in the
FAQ before posting. <http://xml.apache.org/cocoon/faqs.html>

To unsubscribe, e-mail: <cocoon-users-unsubscribe@xml.apache.org>
For additional commands, e-mail: <cocoon-users-help@xml.apache.org>


Mime
View raw message