cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From hepabolu <>
Subject Re: [Documentation] clarifications about docs
Date Sat, 05 Nov 2005 22:35:20 GMT
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.

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

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 
>> but will be 
>> moved to 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 
> 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 
> (that I am aware of).

Sorry, bad wording on my part. That's just my wishful thinking. I meant 
"there should be...".

Bye, Helma

View raw message