You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@cocoon.apache.org by hepabolu <he...@gmail.com> on 2005/11/05 18:51:57 UTC
[Documentation] clarifications about docs
Guys,
just to get the confusion level down I'd like to verify that my ideas
about the current docs are complete and correct.
From what I've gathered from the various threads the idea is currently
as follows:
In general:
- Daisy at the cocoon.zones is our staging server for the documentation
of all current and future version of Cocoon. The main advantage is the
ease of creating/editing the documentation. It is not our main
documentation site, because both the server and Daisy will most likely
not be able to handle the performance load of a large number of visitors.
- cocoon.apache.org is our main documentation site and there should be
an automated process that updates this site based on the info in Daisy.
- we want to include a snapshot of the documentation in every cocoon
release, i.e. it should be available for download, but separated from
the cocoon release.
Cocoon 2.1.8+
- to keep the documentation "backward compatible", cocoon.apache.org
should look very similar to the old version, i.e. with a blue header
bar, a blue menu bar with rounded edges. It should also have the same
urls as the old version.
- the site is generated using Forrest with an automated process set up
on forrest.zones. The result is currently available at
http://forrest.zones.apache.org/ft/build/cocoon-docs/2.1/ but will be
moved to cocoon.apache.org after the 2.1.8 release.
Cocoon 2.2+
- the documentation is generated as a Daisy book in both PDF and HTML.
- there is a minimal static part of the website, that is generated and
maintained by Maven2. The content of this part of the site is mostly
what can be defined in the top-level pom.xml:
- "about us" with a link to the Daisy documentation,
- "changes.xml" with the info of our current status.xml
- some extra default Maven pages, like info on mailing lists, SVN access
- both the "maven site" as well as the HTML Daisy book are restyled and
can have a different look. I do suggest something different, although I
think the main color should be blue, to at least keep some link with the
previous versions. A change of logo is also ok, _BUT_ it should be at
least recognizable as the word cocoon. Hint: <cocoon/> ?
- there is an automated process that can generate the static site as
well as the do the Daisy book generation and exportation to
cocoon.apache.org.
Did I miss something?
Did I write something that is not correct?
Bye, Helma
Re: [Documentation] clarifications about docs
Posted by hepabolu <he...@gmail.com>.
Ross Gardler wrote:
> Yes, although sine the 2.2 xdocs are still in SVN (cocoon/site) so there
> may be overlap at present.
Hmm, I haven't looked lately but I was under the impression that they
were moved out already. I'll see about that as soon as I find some time.
>> - cocoon.apache.org is our main documentation site and there should be
>> an automated process that updates this site based on the info in Daisy.
>
>
> There is some data on that site that is not currently in Daisy. For
> example, the index page. I suspect this is why the cocoon-site
> forrestbot is working on
> http://forrest.zones.apache.org/fr/build/cocoon-site/
Hmm, well, I haven't really looked what is where. There is also the
Cocoon 1.X stuff and other parts that are not regenerated any more. I
simply decided to stick with the 2.1 part and see how the rest would
sort out later.
> I hope the URLs point is correct. I worked hard on that part ;-)
I know, as much as I've worked at getting all the node-ids in. ;-)
> There are some docs in Daisy at present that do not have a name in the
> URL, I suspect that these are new documents, but have not yet had the
> time to verify this. For example, see document 755
I did notice some in the "forrest failed to build" log file. We'll have
to see about this. If it's up to me, things go as follow:
- cocoon 2.1.8+: we stick to the navigation in the legacydocs. That one
has 99% of the documents "fixed" with node-ids. The occasional document
that is added could be marked with a node-id.
- cocoon 2.2+: we use the navigation defined in the Daisy book. If that
results in numeric urls, so be it. Since we're doing an almost complete
rehaul of the website, we might as well give up on the "old" urls, as
long as it's easy to find the information.
In that case, I don't really bother marking new documents in the legacy
navigation docs with a node-id. There is no previous "memory" of a url
anyway and besides it would be easier to find the page back in the new docs.
>> - the site is generated using Forrest with an automated process set up
>> on forrest.zones. The result is currently available at
>> http://forrest.zones.apache.org/ft/build/cocoon-docs/2.1/ but will be
>> moved to cocoon.apache.org after the 2.1.8 release.
>
>
> Yes, that is the current state of play. During the release process
> either David Crossley or myself will have to zip the build in the
> Forrest zone for the release.
yes please.
> For future releases, if Cocoon sticks with Forrest, I think we should
> set up a Forrestbot in the Cocoon Zone so that Cocoon devs have access
> to it and its generated files.
True, OTOH I do hope that 2.1.8 or maybe 2.1.9 will be the last of the
2.1 branch. From that point on the 2.1 part of the website is frozen and
will not be updated any more.
>> Cocoon 2.2+
>> - the documentation is generated as a Daisy book in both PDF and HTML.
>
>
> It is, but the current structure does not lend itself to being a book.
> We should discuss this.
True, but that is not a major issue for this writeup. I.e. I do think it
is important, but not for the subject of this thread.
>> - there is a minimal static part of the website, that is generated and
>> maintained by Maven2. The content of this part of the site is mostly
>> what can be defined in the top-level pom.xml:
>> - "about us" with a link to the Daisy documentation,
>> - "changes.xml" with the info of our current status.xml
>> - some extra default Maven pages, like info on mailing lists, SVN
>> access
>
>
> I have no idea about the maven stuff. But currently this is part of the
> Forrest generated cocoon-site as well.
Ah um, this is part my idea, part loose ideas in various maven related
threads. Sorry for the wording.
Maven has a standard site generation plugin that builds some webpages
from information in the pom.xml. Since these are the pages with the
"easy access" stuff (about us, developer team, mailing lists, svn
access, changes) that are not really in a conspiquous place at the
Cocoon website, I figured that we might as well enter the information in
the top-level pom.xml and generate the information using Maven.
I haven't thought the consequences through, so this might lead to nothing.
> There is nothing to stop us creating a new skin for Forrest generated
> docs as well. I don't recall any discussion about moving to a Maven +
> Daisy setup.
As said, the Maven part is more my interpretation of incidental ideas I
read here and there in the dev list.
AFAIUC the idea to use the Daisy Books for the documentation (at least
for Cocoon 2.2+) was more or less common consensus. But the Daisy books
should have a proper navigation.
> I have no objection right now, but is it the right thing?
Well, it's not set in stone, but let's postpone this discussion until
after the upcoming release.
>> - there is an automated process that can generate the static site as
>> well as the do the Daisy book generation and exportation to
>> cocoon.apache.org.
>
>
> Is there? I am only aware of the ForrestBot as an automated process.
> That can build the static site and it could be configured to extract the
> Daisy Book. I'm not aware of any other automation at this time.
>
> There is no automated process for exporting directly to
> cocoon.apache.org (that I am aware of).
Sorry, bad wording on my part. That's just my wishful thinking. I meant
"there should be...".
Bye, Helma
Re: [Documentation] clarifications about docs
Posted by David Crossley <cr...@apache.org>.
David Crossley wrote:
> Ross Gardler wrote:
> > hepabolu wrote:
> > >just to get the confusion level down I'd like to verify that my ideas
> > >about the current docs are complete and correct.
> >
> > Good idea, I've been a little confused by the need for continuing the
> > cocoon-site build. Here's what I think I understand...
>
> The Cocoon docs are basically in two sections:
>
> 1) The top-level docs, i.e. the "Home" tab at
> cocoon.apache.org (and the "Fr" tab).
>
> 2) The docs for each version, i.e. 2.1
>
> All the *generated* docs are stored in
> http://svn.apache.org/repos/asf/cocoon/site/site
> and that is made live on the server by doing
> svn checkout of that section of the repository.
>
> The sources and forrest config for the top-level
> website are at http://svn.apache.org/repos/asf/cocoon/site
>
> There is some scanty documentation at
> http://wiki.apache.org/cocoon/CocoonWebsiteUpdate
Ah, i am beginning to understand what people are doing
with the most recent documentation effort.
Some time ago we had separated the top-level stuff from the
branch-specific stuff to ease its management, as i described
above. It seems like that has been merged again.
Sorry for confusing things by continuing to build the old stuff.
I had looked that the forrestbot build and assumed that the
empty space at http://forrest.zones.apache.org/ft/build/cocoon-docs/
was waiting for the generation of the top-level docs
to fill the void.
I see two main problems with this merge.
The "Fr" tab and docs will go away, and it seems that some
other docs have been removed. At a glance i see that the
"Committer tips" and "Developer Infos" are missing.
I see a bigger problem with the URL space.
This puts the top-level docs inside the /2.1/ directory.
Perhaps the mapping from Daisy IDs needs to put only the docs
that are under the "Documentation" label in the left-menu,
into the /2.1/ directory.
-David
Re: [Documentation] clarifications about docs
Posted by David Crossley <cr...@apache.org>.
Ross Gardler wrote:
> hepabolu wrote:
> >just to get the confusion level down I'd like to verify that my ideas
> >about the current docs are complete and correct.
>
> Good idea, I've been a little confused by the need for continuing the
> cocoon-site build. Here's what I think I understand...
The Cocoon docs are basically in two sections:
1) The top-level docs, i.e. the "Home" tab at
cocoon.apache.org (and the "Fr" tab).
2) The docs for each version, i.e. 2.1
All the *generated* docs are stored in
http://svn.apache.org/repos/asf/cocoon/site/site
and that is made live on the server by doing
svn checkout of that section of the repository.
The sources and forrest config for the top-level
website are at http://svn.apache.org/repos/asf/cocoon/site
There is some scanty documentation at
http://wiki.apache.org/cocoon/CocoonWebsiteUpdate
> > From what I've gathered from the various threads the idea is currently
> >as follows:
> >
> >In general:
> >- Daisy at the cocoon.zones is our staging server for the documentation
> >of all current and future version of Cocoon. The main advantage is the
> >ease of creating/editing the documentation. It is not our main
> >documentation site, because both the server and Daisy will most likely
> >not be able to handle the performance load of a large number of visitors.
>
> Yes, although sine the 2.2 xdocs are still in SVN (cocoon/site) so there
> may be overlap at present.
I presume you are talking about the Cocoon 2.1 generated docs.
See above.
> >- cocoon.apache.org is our main documentation site and there should be
> >an automated process that updates this site based on the info in Daisy.
>
> There is some data on that site that is not currently in Daisy. For
> example, the index page. I suspect this is why the cocoon-site
> forrestbot is working on
> http://forrest.zones.apache.org/fr/build/cocoon-site/
Helma, no there is no automated process to publish the site.
Forrestbot is only building the documentation so that
doc editors can see the result. Also it makes sure that
people don't break the integrity of the site with broken
internal links and missing images etc. It also lets us tweak
the colours and placement of logos etc.
You will understand more with the above wiki page.
Also see the instructions for all ASF committers
about building their project websites.
http://www.apache.org/dev/project-site.html
> >- we want to include a snapshot of the documentation in every cocoon
> >release, i.e. it should be available for download, but separated from
> >the cocoon release.
>
> Yes
>
> >Cocoon 2.1.8+
> >- to keep the documentation "backward compatible", cocoon.apache.org
> >should look very similar to the old version, i.e. with a blue header
> >bar, a blue menu bar with rounded edges. It should also have the same
> >urls as the old version.
>
> I hope the URLs point is correct. I worked hard on that part ;-)
Thanks for your efforts with that.
I hope that someone else has checked that we are not
going to make a mess of the URL space at
cocoon.apage.org/2.1/ as it would be very important
a technology like Cocoon and Forrest do not break any URLs.
> There are some docs in Daisy at present that do not have a name in the
> URL, I suspect that these are new documents, but have not yet had the
> time to verify this. For example, see document 755
>
> >- the site is generated using Forrest with an automated process set up
> >on forrest.zones. The result is currently available at
> >http://forrest.zones.apache.org/ft/build/cocoon-docs/2.1/ but will be
> >moved to cocoon.apache.org after the 2.1.8 release.
>
> Yes, that is the current state of play. During the release process
> either David Crossley or myself will have to zip the build in the
> Forrest zone for the release.
For the release, someone needs to decide how we are
going to package the docs with the release.
For the website, the generated content needs svn checkin.
> For future releases, if Cocoon sticks with Forrest, I think we should
> set up a Forrestbot in the Cocoon Zone so that Cocoon devs have access
> to it and its generated files.
I am not so sure about that. It would be better that
we worked together at the infra site-dev mailing list
to solve some of the broader issues.
> >- there is an automated process that can generate the static site as
> >well as the do the Daisy book generation and exportation to
> >cocoon.apache.org.
>
> Is there? I am only aware of the ForrestBot as an automated process.
> That can build the static site and it could be configured to extract the
> Daisy Book. I'm not aware of any other automation at this time.
>
> There is no automated process for exporting directly to
> cocoon.apache.org (that I am aware of).
That is correct. Cocoon committers need to build it locally
using Forrest and commit the generated docs. Generally they
don't bother. So the website stagnates.
-David
Re: [Documentation] clarifications about docs
Posted by Ross Gardler <rg...@apache.org>.
hepabolu wrote:
> just to get the confusion level down I'd like to verify that my ideas
> about the current docs are complete and correct.
Good idea, I've been a little confused by the need for continuing the
cocoon-site build. Here's what I think I understand...
> From what I've gathered from the various threads the idea is currently
> as follows:
>
> In general:
> - Daisy at the cocoon.zones is our staging server for the documentation
> of all current and future version of Cocoon. The main advantage is the
> ease of creating/editing the documentation. It is not our main
> documentation site, because both the server and Daisy will most likely
> not be able to handle the performance load of a large number of visitors.
Yes, although sine the 2.2 xdocs are still in SVN (cocoon/site) so there
may be overlap at present.
> - cocoon.apache.org is our main documentation site and there should be
> an automated process that updates this site based on the info in Daisy.
There is some data on that site that is not currently in Daisy. For
example, the index page. I suspect this is why the cocoon-site
forrestbot is working on
http://forrest.zones.apache.org/fr/build/cocoon-site/
> - we want to include a snapshot of the documentation in every cocoon
> release, i.e. it should be available for download, but separated from
> the cocoon release.
Yes
> Cocoon 2.1.8+
> - to keep the documentation "backward compatible", cocoon.apache.org
> should look very similar to the old version, i.e. with a blue header
> bar, a blue menu bar with rounded edges. It should also have the same
> urls as the old version.
I hope the URLs point is correct. I worked hard on that part ;-)
There are some docs in Daisy at present that do not have a name in the
URL, I suspect that these are new documents, but have not yet had the
time to verify this. For example, see document 755
> - the site is generated using Forrest with an automated process set up
> on forrest.zones. The result is currently available at
> http://forrest.zones.apache.org/ft/build/cocoon-docs/2.1/ but will be
> moved to cocoon.apache.org after the 2.1.8 release.
Yes, that is the current state of play. During the release process
either David Crossley or myself will have to zip the build in the
Forrest zone for the release.
For future releases, if Cocoon sticks with Forrest, I think we should
set up a Forrestbot in the Cocoon Zone so that Cocoon devs have access
to it and its generated files.
> Cocoon 2.2+
> - the documentation is generated as a Daisy book in both PDF and HTML.
It is, but the current structure does not lend itself to being a book.
We should discuss this.
> - there is a minimal static part of the website, that is generated and
> maintained by Maven2. The content of this part of the site is mostly
> what can be defined in the top-level pom.xml:
> - "about us" with a link to the Daisy documentation,
> - "changes.xml" with the info of our current status.xml
> - some extra default Maven pages, like info on mailing lists, SVN access
I have no idea about the maven stuff. But currently this is part of the
Forrest generated cocoon-site as well.
> - both the "maven site" as well as the HTML Daisy book are restyled and
> can have a different look. I do suggest something different, although I
> think the main color should be blue, to at least keep some link with the
> previous versions. A change of logo is also ok, _BUT_ it should be at
> least recognizable as the word cocoon. Hint: <cocoon/> ?
There is nothing to stop us creating a new skin for Forrest generated
docs as well. I don't recall any discussion about moving to a Maven +
Daisy setup.
I have no objection right now, but is it the right thing?
> - there is an automated process that can generate the static site as
> well as the do the Daisy book generation and exportation to
> cocoon.apache.org.
Is there? I am only aware of the ForrestBot as an automated process.
That can build the static site and it could be configured to extract the
Daisy Book. I'm not aware of any other automation at this time.
There is no automated process for exporting directly to
cocoon.apache.org (that I am aware of).
Ross
Re: [Documentation] clarifications about docs
Posted by Bruno Dumon <br...@outerthought.org>.
On Sat, 2005-11-05 at 18:51 +0100, hepabolu wrote:
> Guys,
<snip/>
> Cocoon 2.2+
> - the documentation is generated as a Daisy book in both PDF and HTML.
As an additional resource next to the normal site, I assume? I mean, the
books are fine for printing or linear reading, but the primary rendering
would stay something like we currently have, I thought/hoped.
--
Bruno Dumon http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
bruno@outerthought.org bruno@apache.org