You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Diana Shannon <sh...@apache.org> on 2002/06/18 05:51:34 UTC
Cocoon docs transition report
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!
PHASE ONE
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
PHASE TWO
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
xml-cocoon2/src/documentation/xdocs to
c2-forrest/src/testcases/c2/v10
with the following exceptions:
- test/* (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.)
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)
4. Edited src/resources/library/xslt/docv10todocv11.xsl. (attached)
- 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
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
7. Typed "./build.sh scratchpad"
8. At interactive prompt, entered "transform-v11"
9. Iterated through doc transformation. Fixed any docs with problems
(and updated cocoon cvs)
o----------o
PHASE THREE
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
(attached) to
- validate using a locally declared xmlcatalog (with paths to all dtd
and entity files!). The xmlcatalog element is WAAAAY cool.
3. Typed "./build.sh 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
PHASE FOUR
Docs Builds
1. Copy new docs from
forrest/src/testcases/c2/v11 to
src/documentation/content/xdocs
2. Type "./build.sh clean docs"
Even with validation problems, docs built ok. I used bert skin. You can
view the result at
http://www.terracare.com/cocoon-forrest/
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.
o----------o
ISSUES
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 "http://xml.apache.org/forrest/" 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.
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
Re: Cocoon docs transition report
Posted by David Crossley <cr...@indexgeo.com.au>.
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 ...
http://marc.theaimsgroup.com/?l=forrest-dev&m=102455612705941
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!
>
> PHASE ONE
> 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
>
> PHASE TWO
> 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 "./build.sh scratchpad"
> 8. At interactive prompt, entered "transform-v11"
> 9. Iterated through doc transformation. Fixed any docs with problems
> (and updated cocoon cvs)
>
> o----------o
>
> PHASE THREE
> 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 "./build.sh 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
>
> PHASE FOUR
> Docs Builds
> 1. Copy new docs from
> forrest/src/testcases/c2/v11 to
> src/documentation/content/xdocs
> 2. Type "./build.sh clean docs"
> Even with validation problems, docs built ok. I used bert skin. You can
> view the result at
> http://www.terracare.com/cocoon-forrest/
> 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 ...
./build.sh clean docs; ./build.sh docs
> o----------o
>
> ISSUES
> 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 "http://xml.apache.org/forrest/" 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. -Duse.skin=bert seems to be ignored.
See some answers to ISSUES in previous email.
--David
> 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
>
Re: Cocoon docs transition report
Posted by Diana Shannon <sh...@apache.org>.
On Tuesday, June 18, 2002, at 07:45 AM, David Crossley wrote:
> Diana Shannon wrote:
> <snip/>
> Excellent stuff Diana. I will answer some other bits later.
>
>> o----------o
>>
>> ISSUES
>> 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
>
> They are probably not defined in src/targets/project.xtarget
No, which brings up an issue. Can projects have customized build
targets? Seems to me they will be somewhat different across projects. In
addition to schema management, will Forrest manage such build changes
(as well as sitemap changes). It's hard to imagine all project working
from the same sitemap design, especially in the case of Cocoon which
will probably want to lead with new sitemap design approaches. It's also
difficult imagining projects going through Forrest for sitemap and build
change "approvals." Am I misunderstanding the mission of Forrest?
>
>> 3. No time to look at example files.
>
> Not sure what you mean here ... the final HTML that is produced?
Yes. How we want to implement validation, if necessary. Remember, we
need to pull example content out, somewhat, into the main docs to
increase their visibility. There's also problems with dirctories like
ctwig who include sample files with no dtds at all. It would be nice to
perform wholesale doc validation, but define ways to skip files (without
manually editing excludes/includes) etc. within a centipede target.
> If so yes, we need to spend time to be sure that most stuff is
> properly handled. We can cope with minor glitches later.
<snip />
>> 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.
>
> We never did need relative paths for systemIdentifiers. The
> equally excellent catalog entity resolver in Cocoon and Forrest
> took care of it. However some people liked the belt-and-braces
> for impoverished xml tools. I prefer to rely on an entity resolver.
> These are XML Framework projects after all. Great to hear that
> Ant is starting to use one too.
Well, at least it will help contributors and committers who don't
validate single or multiple page contributions with their standard
tools. Up to now, I wasn't performing wholesale xdocd validation either,
just the individual pages with which I was dealing.
Diana
Re: Cocoon docs transition report
Posted by David Crossley <cr...@indexgeo.com.au>.
Diana Shannon wrote:
<snip/>
Excellent stuff Diana. I will answer some other bits later.
> o----------o
>
> ISSUES
> 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
They are probably not defined in src/targets/project.xtarget
> 3. No time to look at example files.
Not sure what you mean here ... the final HTML that is produced?
If so yes, we need to spend time to be sure that most stuff is
properly handled. We can cope with minor glitches later.
> 4. What's going on with the header crumb trail? Is the @project-
> logo.href@ hard-coded as "http://xml.apache.org/forrest/" in the build
> file or is my forrest.xgump file misconfigured?
They are hard-coded in Forrest's solitary
src/targets/project.xtarget
I recall someone suggesting creating snippet *.xtarget
fragments for each project. Job still to do.
> 5. Will cocoon-dev need to vote on the Forrest skin?
This is an interesting issue. I thought that each project
was going to provide their own skin, perhaps based on the
forrest-site/bert skin. I have never been clear on this
aspect ... what is Forrest, how broadly is its look-and-feel
to be applied.
> 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.
We never did need relative paths for systemIdentifiers. The
equally excellent catalog entity resolver in Cocoon and Forrest
took care of it. However some people liked the belt-and-braces
for impoverished xml tools. I prefer to rely on an entity resolver.
These are XML Framework projects after all. Great to hear that
Ant is starting to use one too.
> 7. Several other issues, but I'm completely out of time to
> comment further.
Many thanks. There is plenty for us to go on with.
> 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
It was fine for me. Yes i am in the same situation but
will try to follow your work and give it a go myself.
--David
Re: Cocoon docs transition report
Posted by Diana Shannon <sh...@apache.org>.
>
> 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.
Cancel what I said in point 2. Validation is ok, as the source child
elements aren't recognized as such because of the < substitution etc.
Diana