forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Piroumian Konstantin <KPiroum...@protek.com>
Subject RE: Cocoon docs transition report
Date Tue, 18 Jun 2002 08:21:34 GMT
Great work, Diana!!!

As I remember, Bert has made some changes to the skin, like adding icons to
the menu, fixing the current page indication and some more and as I remember
we've decided to use that skin as default. But now I see that forrest-skin
is default. Did I miss something and is it the intended behavior?

For the Cocoon docs I'd like to see them generated using the fixed skin
(from Bert), but I would wait a little with the voting procedure on
cocoon-dev, cause we have no a good solution for the 'global-path', tabs,
etc. 

What I don't like in the current approach, that we should add explicit links
to parent topics, to the main menu from the child pages, e.g.:
xml-forrest\docs\community\howto\v10\howto-v10.html - we have to put a
book.xml into this directory for just having a link to the parent.
Originally, this was solved by having the path info at the top like:
apache > xml.apache > forrest > docs > howtos > howto-v10[1].html

You could say that in this case we won't have anything in the menu at left,
but again, if you look at the prototype page.html you'll notice that it
contains the titles of the sections of the content document. And I don't
like much the current approach of having that information in the content
part. I think that for the documentation [tab] we need to solve this
problems. 

IMHO, other issues like pagination, printable and single page views are not
stoppers for using Forrest with Cocoon documentation. I'm going to look at
the pagination as I have a little free time. Though, I don't think that it
will be soon ;(.

--
Konstantin Piroumian 
kpiroumian@apache.org


> -----Original Message-----
> From: Diana Shannon [mailto:shannon@apache.org] 
> Sent: Tuesday, June 18, 2002 7:52 AM
> To: forrest-dev@xml.apache.org
> Subject: 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
> 
> 

Mime
View raw message