cocoon-users mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Nicola Ken Barozzi" <nicola...@apache.org>
Subject Re: [DOC] How to contribute documentation
Date Sat, 11 May 2002 22:00:46 GMT
From: "Andreas Hochsteger" <e9625392@student.tuwien.ac.at>

> "Nicola Ken Barozzi" <nicolaken@apache.org> wrote:
>
> > From: "Andreas Hochsteger" <e9625392@student.tuwien.ac.at>
> > 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.

Yes, I think we all agree.
This is the current "generic" way, but we'll se to have something better in
place soon.

> > 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.

Cocoon should be able to do validation, but last time we turned it on,
strange things happend (don't remember why). When it works again (maybe it
does, haven't checked), it could be used.

> 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.

Yes, it's a big dream ATM. Krysalis Centipede is using a very very embrional
version of Forrest for creating documentation, but it will be more than
that.
Your suggestion is nice, I will see that it's discussed over there.

> > 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.

;-)  Well, it's not Cocoon. Any normal creator of Xml should use a
validating editor IMO, just as notmal Java developers use java editors with
automatic syntax checking.
You *can* compile the code to check these errors, but it's not practical.

> > 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.

--
Nicola Ken Barozzi                   nicolaken@apache.org
            - verba volant, scripta manent -
   (discussions get forgotten, just code remains)
---------------------------------------------------------------------


---------------------------------------------------------------------
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