forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <>
Subject Re: Cocoon docs transition report
Date Thu, 20 Jun 2002 09:03:07 GMT
I followed Diana's excellent instructions and ran the
testcase of Cocoon for myself. Great it works ...
Thanks yet again to the wonderful Ant.

However, i have found that the entity resolution part of
this build is not actually working. At PHASE TWO Step 2
do not copy the xdocs/dtd/ stuff from Cocoon and you will
see that the build fails. Never mind, i have fixed it by
configuring the scratchpad/targets/ a little differently.

Certain parts of Diana's stuff below has been placed into
Forrest CVS. The rest of the instructions below are still
relevant. I have indicated the bits that you do not need to
bother with. You still need the other pieces from Diana's
original attachment, e.g. sitemap.xmap, forrest.xgump, etc.
You also still need to get your own Ant-1.5Beta2 jars.

I have also added the relevant document-v10 DTDs from
Cocoon into xml-forrest/src/resources/schema
See other thread about a dilemma ...

Thanks again to Diana. This is all a major step forward.

On Tue 2002-06-18 Diana Shannon wrote:
> Here's what I did. Hope I properly understood my mission ;-) Thanks, 
> Ken, for the helpful scratchpad targets! And thanks also, Dion, for the 
> very cool xmlcatalog capability! What great tools!
> Modified Forrest cvs to work as prototype Cocoon project cvs
> 1. Updated my local version of Forrest cvs.
> 2. Copied it, renamed as c2-forrest (for clarification of paths below)
> 3. Deleted all docs from src/documentation/content/xdoc
> 4. Substituted a makeshift cocoon logo in place of the Forrest one at 
> src/documentation/resources/images/project-logo.gif (attached)
> 5. Copied other necessary cocoon picts to 
> src/documentation/resources/images/
> 6. Edited forrest.xgump (attached).
> - I merged in *some* values from Cocoon's changes.xml, todo.xml, and 
> who.xml. This is by no means complete, just something to get started. I 
> wasn't sure how much release info to add to changes, what to indicate 
> for version, etc. Perhaps comments would help...
> 7. Validated forrest.xgump. Based on problems, I
> - changed assigned-to attribute to dev for all action elements
> - added required dev attribute to a number of action elements
> 8. Tweaked sitemap (attached)
> - Added <map:match pattern="body-**faq/*.xml"> ...
> - Commented out aggregated tab.xml file, for the time being. (We should 
> probably decide tab issues later on cocoon-dev, along with other content 
> refactoring issues like guide consolidation.)
> - Adjusted <map:match pattern="body-doclist.xml"> as necessary
> - Adjusted <map:match pattern="body-*/changes-*.xml"> to include 
> plan/changes-doc.html
> - Adjusted <map:match pattern="body-*/todo-*.xml"> to include 
> plan/todo-doc.html
> o----------o
> Transformed C2 docs to Forrest-dtd-compliant docs
> 1. Updated my local copy of c2 cvs HEAD as of Saturday, 6/16/02
> 2. Copied all files (xml/ and dtd/) from
DC> do not copy dtd/
>    xml-cocoon2/src/documentation/xdocs to
>    c2-forrest/src/testcases/c2/v10
> with the following exceptions:
>   - drafts/* (not used in docs)
> I also manually added entity files to this directory (as catalog-
> test.xml complained during transformation) Didn't want to bother with 
> declaring an xmlcatalog just for this transformation step. (I also 
> wasn't using the latest and greatest ant jar ... yet.)
DC> Leave the catalog-test.xml in place.
DC> Replace your tools/ant/lib/ant-1.4.1*.jar with ant-1.5Beta2
DC> jars at this stage.

> 3. Added centipede target src/scratchpad/targets/transform-v11.xml 
> (attached) to
> - transform document-v10 files to document-v11 files
> - transform faqv10 to faqv11 files (new doctype header)
> - transform bookv10 to bookv10 files (clean relative path within doctype 
> header)
> - transform changesv10 to changesv10 files (plan/changes-doc content, 
> not included in forrest.xgump)
DC> All new scratchpad targets are now in Forrest CVS.

> 4. Edited src/resources/library/xslt/docv10todocv11.xsl. (attached)
DC> This stylesheet is now in Forrest CVS.
> - uncommented xsl:output tag and:
>      - added attributes for document-v11 doctype declaration
>      - added an indent attribute
>      - experimented (with no success) with different applications of 
> cdata-section-elements="source"
> - fixed treatment of section/title elements (document-v11.dtd was 
> updated to reflect new treatment; this stylesheet was not)
> NOTE: We're losing CDATA sections, in other words, the content 
> originally wrapped by CDATA is changed to entities. AFAIK, there is no 
> way around this. If so, what a PITA because: (1) The content becomes 
> much harder to work with in text editors. (2) This also *breaks* 
> validation on any page when a code snippet introduces non-document-v11 
> elements! Looks like a manual edit, I guess. Big Yuck.
> 5. Added src/resources/library/xslt/faqv10tofaqv11.xslt. (attached)
> - Replaces doctype declaration.
> - added a template to eliminate some odd link attributes
DC> This stylesheet is now in Forrest CVS.

> 6. Added src/resources/library/xslt/bookv10.xsl.
> - Cleaned up doctype declaration (no more relative paths to dtd)
> - added a matcher to eliminate some odd link attributes
DC> This stylesheet is now in Forrest CVS.

> 7. Typed "./ scratchpad"
> 8. At interactive prompt, entered "transform-v11"
> 9. Iterated through doc transformation. Fixed any docs with problems 
> (and updated cocoon cvs)
> o----------o
> Validated new xdoc files
> 1. Downloaded jars for ant-1.5Beta2. Placed in tools/ant/lib
> 2. Added centipede target src/scratchpad/targets/validate-v11.xml
DC> All new scratchpad targets are now in Forrest CVS.

> (attached) to
> - validate using  a locally declared xmlcatalog (with paths to all dtd 
> and entity files!). The xmlcatalog element is WAAAAY cool.
DC> Modified Diana's xtargets to include the xmlcatalog
DC> from src/resources/catalog-ant.xcat
DC> This is still not ideal, but it works.

> 3. Typed "./ scratchpad"
> 4. At interactive prompt, entered "validate-v11"
> Problems:
> - plan/changes-doc.xml didn't validate (change doc or dtd?)
> - plan/todo-doc.xml didn't validate (change doc or dtd?)
> - some files with source snippets failed to validate (manual edits?)
> Short-term fix
> - excluded problematic files from validation step (see target file)
> o----------o
> Docs Builds
> 1. Copy new docs from
>    forrest/src/testcases/c2/v11 to
>    src/documentation/content/xdocs
> 2. Type "./ clean docs"
> Even with validation problems, docs built ok. I used bert skin. You can 
> view the result at
> Better, though, to generate the result yourself. It's not overly 
> time-consuming with the new scratchpad targets. You will need to the 
> ant-1.5Beta2.jar to validate with the xmlcatalog. The new ant jar worked 
> ok for all other build targets, at least it did for me.

I was going to update Forrest's Ant but there is a small
hitch. You need to repeat the build docs after clean ...
./ clean docs; ./ docs

> o----------o
> 1. We need to add jar.xml generation to Forrest docs build. John?
> 2. We're don't seem to be catching all @XXXX@ tokens (e.g. 
> released.version) in cocoon xdocs during build filtering
> 3. No time to look at example files.
> 4. What's going on with the header crumb trail? Is the @project-
> logo.href@ hard-coded as "" in the build 
> file or is my forrest.xgump file misconfigured?
> 5. Will cocoon-dev need to vote on the Forrest skin?
> 6. Most relative doctype paths to dtd were stripped during 
> transformation because of v10-v11 changes. I assume we don't need 
> relative local paths anymore, given the new path capabilities of 
> validation with xmlcatalog.
> 7. Several other issues, but I'm completely out of time to comment 
> further.

 8. seems to be ignored.

See some answers to ISSUES in previous email.

> I have some paid work to catch up with, so I won't be able to pick this 
> up again for a few days. Hope the attachment comes through ok. Please 
> holler otherwise.
> -- Diana

View raw message