Re: [DOC] How to contribute documentation

[David Crossley]

Woops wrong list :-) Try again.

From: David Crossley <[EMAIL PROTECTED]>
To: [EMAIL PROTECTED]

Andreas Hochsteger wrote:
>> Something like a list of referenced internal and external documents
>> or link checking comes to my mind.

Internal link checking happens during the "build docs". If you have
the wrong filename in a link, then it will report errors. This is why it is
very important to run "build docs" before preparing a patch.

External link checking is another matter and is a very specialised task.
We run the excellent LinkAlarm service over the Cocoon website after
each release so that errors can be fixed before the next release.

For some reason the README docs about this were recently
removed from CVS. I just added them back and scheduled LinkAlarm
to do its magic over the recent 2.0.2 release. I will send cocoon-* lists
an announcement when it is done and we can all help to fix.

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

Apache Forrest is a fledgling project and there is no website yet.
This is yet another call for people to come and help us.
--David

-
Please check that your question has not already been answered in the
FAQ before posting. 

To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>

Re: [DOC] How to contribute documentation

[David Crossley]

Woops wrong list :-) Try again.

From: David Crossley <[EMAIL PROTECTED]>
To: [EMAIL PROTECTED]

Thanks to Ken for his ever-capable answers. I can add a
little bit extra on a couple of the topics ...

Andreas Hochsteger wrote:
>> 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.

Nicola Ken Barozzi wrote:
> 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.

We did used to have Cocoon doing validation during "build docs"
but something changed, which caused it to break.
 http://nagoya.apache.org/bugzilla/show_bug.cgi?id=6200
 Parser failure with validate=true when processing stylesheet
It would be of enourmous benefit to Cocoon, Forrest, and other
projects, if someone could help to fix that capability.

--David

-
Please check that your question has not already been answered in the
FAQ before posting. 

To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>

Re: [DOC] How to contribute documentation

[Nicola Ken Barozzi]

From: "Andreas Hochsteger" <[EMAIL PROTECTED]>

> "Nicola Ken Barozzi" <[EMAIL PROTECTED]> wrote:
>
> > From: "Andreas Hochsteger" <[EMAIL PROTECTED]>
> > 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   [EMAIL PROTECTED]
- 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. 

To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>

Re: [DOC] How to contribute documentation

[Andreas Hochsteger]

Hi!

"Nicola Ken Barozzi" <[EMAIL PROTECTED]> wrote:

> From: "Andreas Hochsteger" <[EMAIL PROTECTED]>
> 
> 
> > 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   [EMAIL PROTECTED]

Bye,

Andreas




-
Please check that your question has not already been answered in the
FAQ before posting. 

To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>

Re: [DOC] How to contribute documentation

[Andrew C. Oliver]

 the docs.
> 
> And, of course, Nicola Ken is responsible for a very wonderful part of 
> the Forrest project, which among many other things, helps build static 
> versions of Apache-like web sites. When it is integrated into Cocoon, 
> you will have even more useful tools as a contributor. His build scripts 
> are a great way to take advantage of Cocoon's command line when you need 
> to generate static parts of your web site.  Among other things, this 
> static build process in Forrest includes a mechanism for checking links. 
> This could be very useful to Cocoon-doc effort, because it will help 
> contributors discover if their revisions impact other pages/links within 
> the site.
> 


ss ...  It will go to his head.  :-D

> Diana
> 
> 
> -
> Please check that your question has not already been answered in the
> FAQ before posting. 
> 
> To unsubscribe, e-mail: <[EMAIL PROTECTED]>
> For additional commands, e-mail: <[EMAIL PROTECTED]>
> 
-- 
http://www.superlinksoftware.com - software solutions for business
http://jakarta.apache.org/poi - Excel/Word/OLE 2 Compound Document in
Java
http://krysalis.sourceforge.net/centipede - the best build/project
structure
a guy/gal could have! - Make Ant simple on complex Projects!
The avalanche has already started. It is too late for the pebbles to
vote.
-Ambassador Kosh


-
Please check that your question has not already been answered in the
FAQ before posting. 

To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>

Re: [DOC] How to contribute documentation

[Diana Shannon]

On Saturday, May 11, 2002, at 08:34  AM, Nicola Ken Barozzi wrote:

> Could you please expand more on this? It seems like an intersting 
> feature
> one would need.
>
> Since the document is XML, we encourage to use an editor that can 
> validate
> your document with the right DTD.
>
> In this way you are sure that Cocoon will be able to compile it without
> having to recreate all the docs.

And, of course, Nicola Ken is responsible for a very wonderful part of 
the Forrest project, which among many other things, helps build static 
versions of Apache-like web sites. When it is integrated into Cocoon, 
you will have even more useful tools as a contributor. His build scripts 
are a great way to take advantage of Cocoon's command line when you need 
to generate static parts of your web site.  Among other things, this 
static build process in Forrest includes a mechanism for checking links. 
This could be very useful to Cocoon-doc effort, because it will help 
contributors discover if their revisions impact other pages/links within 
the site.

Diana


-
Please check that your question has not already been answered in the
FAQ before posting. 

To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>

Re: [DOC] How to contribute documentation

[Nicola Ken Barozzi]

From: "Andreas Hochsteger" <[EMAIL PROTECTED]>


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

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.

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

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)

Cheers!

--
Nicola Ken Barozzi   [EMAIL PROTECTED]
- 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. 

To unsubscribe, e-mail: <[EMAIL PROTECTED]>
For additional commands, e-mail: <[EMAIL PROTECTED]>