You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by Bruno Dumon <br...@outerthought.org> on 2005/06/17 12:40:51 UTC
[docs] old docs import done
Hi all,
The import is done, see here:
http://cocoon.zones.apache.org/daisy/legacydocs
All the imported docs belong to a collection called "legacydocs". If a
document belongs to this collection, a warning is put on top.
Later this afternoon, I will start moving some docs to the new
documentation (I'll probably start with the forms docs). I suggest that
we create a collection/site "documentation" for this purpose.
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
Re: [docs] old docs import done
Posted by Bruno Dumon <br...@outerthought.org>.
On Fri, 2005-06-17 at 12:40 +0200, Bruno Dumon wrote:
> Hi all,
>
> The import is done, see here:
> http://cocoon.zones.apache.org/daisy/legacydocs
>
> All the imported docs belong to a collection called "legacydocs". If a
> document belongs to this collection, a warning is put on top.
Forgot to mention, if anyone wants to change the warning message content
or styling, this can be done by editing this XSL:
/home/daisy/daisy/daisywiki/webapp/daisy/resources/document-styling/default/html/Document.xsl
(on the zone)
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
Re: [docs] old docs import done
Posted by Bruno Dumon <br...@outerthought.org>.
On Fri, 2005-06-17 at 14:54 +0100, Mark Leicester wrote:
> Hi Bruno,
>
> Great! I've done a fair amount of work on the Cocoon In Action section.
> Should we look at merging the two, or do they have sufficiently
> distinct purposes to keep them separated?
This is just IMHO...
The parts of Cocoon In Action that talk about the build system and
getting the code from SVN certainly belong in the documentation.
The rest... I'm undecided yet. I have some preference to keep tutorials
separate.
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
Re: [docs] old docs import done
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 17 juin 05, à 17:56, Bruno Dumon a écrit :
> ...Depends a bit on what is part of the automatically-generated docs.
> IMHO
> documentation that provides usage notes on components (thus, which is
> not really javadoc) should better not be maintained as javadoc...
The idea, based on the summer of code cocoon-refdoc project [1], is to
mostly use what already exists to build the reference docs / manpages:
sitemap snippets, example input files, parameters information extracted
from code comments, and some short narrative which can be entered
either inside the code or in separate files (html or wiki formats).
But it's all vaporware for now ;-)
We'll know more if the cocoon-refdoc project actually happens.
-Bertrand
[1] http://wiki.apache.org/cocoon/CocoonRefDocProject
Re: [docs] old docs import done
Posted by Sylvain Wallez <sy...@apache.org>.
Bruno Dumon wrote:
>On Fri, 2005-06-17 at 17:15 +0200, Bertrand Delacretaz wrote:
>
>
>>Le 17 juin 05, à 17:08, Upayavira a écrit :
>>
>>
>>>...a document detailing how the HTMLGenerator works, with all of its
>>>options, wouldn't be that useful in other parts of the documentation
>>>(other than as a link), IMO.
>>>
>>>
Agree. The reference section should be distinct from the tutorial
section ("section" meaning here either site of navigation subtree),
furthermore considering that a single component can be referenced from
several places in different tutorials.
>>IMHO such reference documents should have permanent and predictable
>>short URLs, say "reference/components/HTMLGenerator" in this case.
>>That's hoping these will be generated automatically of course, at some
>>point.
>>
>>
>
>Depends a bit on what is part of the automatically-generated docs. IMHO
>documentation that provides usage notes on components (thus, which is
>not really javadoc) should better not be maintained as javadoc. For
>example, take the I18nTransformer. There's a very very long javadoc
>there which is essentially user documentation and is very hard to
>read/maintain in the form of javadoc.
>
>
+1. A lot of components have their user docs in the javadoc as it wasn't
much harder to write it there rather than in xdocs. Things are different
now :-)
>I am +1 though on merging technical information on the component (such a
>it is cacheable, is it poolable, ...) automatically from the sources.
>
>
Yup.
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: [docs] old docs import done
Posted by Bruno Dumon <br...@outerthought.org>.
On Fri, 2005-06-17 at 17:15 +0200, Bertrand Delacretaz wrote:
> Le 17 juin 05, à 17:08, Upayavira a écrit :
>
> > ...a document detailing how the HTMLGenerator works, with all of its
> > options, wouldn't be that useful in other parts of the documentation
> > (other than as a link), IMO.
>
> IMHO such reference documents should have permanent and predictable
> short URLs, say "reference/components/HTMLGenerator" in this case.
> That's hoping these will be generated automatically of course, at some
> point.
Depends a bit on what is part of the automatically-generated docs. IMHO
documentation that provides usage notes on components (thus, which is
not really javadoc) should better not be maintained as javadoc. For
example, take the I18nTransformer. There's a very very long javadoc
there which is essentially user documentation and is very hard to
read/maintain in the form of javadoc.
I am +1 though on merging technical information on the component (such a
it is cacheable, is it poolable, ...) automatically from the sources.
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org
Re: [docs] old docs import done
Posted by Bertrand Delacretaz <bd...@apache.org>.
Le 17 juin 05, à 17:08, Upayavira a écrit :
> ...a document detailing how the HTMLGenerator works, with all of its
> options, wouldn't be that useful in other parts of the documentation
> (other than as a link), IMO.
IMHO such reference documents should have permanent and predictable
short URLs, say "reference/components/HTMLGenerator" in this case.
That's hoping these will be generated automatically of course, at some
point.
-Bertrand
Re: [docs] old docs import done
Posted by Upayavira <uv...@odoko.co.uk>.
Steven Noels wrote:
> On 17 Jun 2005, at 16:53, Upayavira wrote:
>
>> Mark Leicester wrote:
>>
>>> Hi Bruno,
>>> Great! I've done a fair amount of work on the Cocoon In Action
>>> section. Should we look at merging the two, or do they have
>>> sufficiently distinct purposes to keep them separated? Helma, what do
>>> you think?
>>
>>
>> Personally, what I want to see is two sections
>
>
> "sites" or "sections": content can be repurposed in several places at
> the same time. Using this new environment, we'll hopefully be able to
> create smaller, more reusable pieces of content.
I want to see two sections. i.e. one navigation that covers both
reference and tutorials. Yes documents can be reused, but a document
detailing how the HTMLGenerator works, with all of its options, wouldn't
be that useful in other parts of the documentation (other than as a
link), IMO.
Upayavira
Re: [docs] old docs import done
Posted by Steven Noels <st...@outerthought.org>.
On 17 Jun 2005, at 16:53, Upayavira wrote:
> Mark Leicester wrote:
>> Hi Bruno,
>> Great! I've done a fair amount of work on the Cocoon In Action
>> section. Should we look at merging the two, or do they have
>> sufficiently distinct purposes to keep them separated? Helma, what do
>> you think?
>
> Personally, what I want to see is two sections
"sites" or "sections": content can be repurposed in several places at
the same time. Using this new environment, we'll hopefully be able to
create smaller, more reusable pieces of content.
</Steven>
--
Steven Noels http://outerthought.org/
Outerthought Open Source Java & XML
stevenn at outerthought.org stevenn at apache.org
Re: [docs] old docs import done
Posted by Upayavira <uv...@odoko.co.uk>.
Mark Leicester wrote:
> Hi Bruno,
>
> Great! I've done a fair amount of work on the Cocoon In Action section.
> Should we look at merging the two, or do they have sufficiently distinct
> purposes to keep them separated? Helma, what do you think?
Personally, what I want to see is two sections: one for reference docs
and one for tutorials, etc. But within the same documentation.
Regards, Upayavira
> On 17 Jun 2005, at 14:11, Bruno Dumon wrote:
>
>> On Fri, 2005-06-17 at 12:40 +0200, Bruno Dumon wrote:
>>
>>> Hi all,
>>>
>>> The import is done, see here:
>>> http://cocoon.zones.apache.org/daisy/legacydocs
>>>
>>> All the imported docs belong to a collection called "legacydocs". If a
>>> document belongs to this collection, a warning is put on top.
>>>
>>> Later this afternoon, I will start moving some docs to the new
>>> documentation (I'll probably start with the forms docs). I suggest that
>>> we create a collection/site "documentation" for this purpose.
>>
>>
>> Done:
>> http://cocoon.zones.apache.org/daisy/documentation
>>
>> Now we can start working on content ;-)
>>
>> --
>> Bruno Dumon http://outerthought.org/
>> Outerthought - Open Source, Java & XML Competence Support Center
>> bruno@outerthought.org bruno@apache.org
>>
>
>
Re: [docs] old docs import done
Posted by Mark Leicester <ma...@efurbishment.com>.
Hi Bruno,
Great! I've done a fair amount of work on the Cocoon In Action section.
Should we look at merging the two, or do they have sufficiently
distinct purposes to keep them separated? Helma, what do you think?
Mark
On 17 Jun 2005, at 14:11, Bruno Dumon wrote:
> On Fri, 2005-06-17 at 12:40 +0200, Bruno Dumon wrote:
>> Hi all,
>>
>> The import is done, see here:
>> http://cocoon.zones.apache.org/daisy/legacydocs
>>
>> All the imported docs belong to a collection called "legacydocs". If a
>> document belongs to this collection, a warning is put on top.
>>
>> Later this afternoon, I will start moving some docs to the new
>> documentation (I'll probably start with the forms docs). I suggest
>> that
>> we create a collection/site "documentation" for this purpose.
>
> Done:
> http://cocoon.zones.apache.org/daisy/documentation
>
> Now we can start working on content ;-)
>
> --
> Bruno Dumon http://outerthought.org/
> Outerthought - Open Source, Java & XML Competence Support Center
> bruno@outerthought.org bruno@apache.org
>
Re: [docs] old docs import done
Posted by Sylvain Wallez <sy...@apache.org>.
Bruno Dumon wrote:
>On Fri, 2005-06-17 at 12:40 +0200, Bruno Dumon wrote:
>
>
>>Hi all,
>>
>>The import is done, see here:
>>http://cocoon.zones.apache.org/daisy/legacydocs
>>
>>All the imported docs belong to a collection called "legacydocs". If a
>>document belongs to this collection, a warning is put on top.
>>
>>Later this afternoon, I will start moving some docs to the new
>>documentation (I'll probably start with the forms docs). I suggest that
>>we create a collection/site "documentation" for this purpose.
>>
>>
>
>Done:
>http://cocoon.zones.apache.org/daisy/documentation
>
>Now we can start working on content ;-)
>
>
Great! Thanks Bruno!
Sylvain
--
Sylvain Wallez Anyware Technologies
http://apache.org/~sylvain http://anyware-tech.com
Apache Software Foundation Member Research & Technology Director
Re: [docs] old docs import done
Posted by Bruno Dumon <br...@outerthought.org>.
On Fri, 2005-06-17 at 12:40 +0200, Bruno Dumon wrote:
> Hi all,
>
> The import is done, see here:
> http://cocoon.zones.apache.org/daisy/legacydocs
>
> All the imported docs belong to a collection called "legacydocs". If a
> document belongs to this collection, a warning is put on top.
>
> Later this afternoon, I will start moving some docs to the new
> documentation (I'll probably start with the forms docs). I suggest that
> we create a collection/site "documentation" for this purpose.
Done:
http://cocoon.zones.apache.org/daisy/documentation
Now we can start working on content ;-)
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org