Dokumentation: HowTo Customize HTML Processing

• Key: FOR-446
• Type: Improvement
• Status: Closed
• Resolution: Fixed
• Priority: Minor
• Assignee: David Crossley
• Reporter: Ferdinand Soethe
• Component/s: Documentation and website
• Affects Version/s: 0.7
• Fix Version/s: 0.7

Description

A long HowTo with lots of info on how Forrest processes requests for html document. Requires checking for facts, language and a few fixmes.

Comments

[Ferdinand Soethe]

zip file contains index.xml (the howto) and three html-files that are referenced in the howto and need to be in the same directory.

Excellent contribution to our docs. There are a few spelling/grammatical errors, but I've ignored them for the moment. Here are the more important points:

---

"In doing the research for this How To, Ross Gardler taucht me so many interesting facts"

- much as I appreciate the acknowledgement we don't directly reference developers in the docs. This is because over time many people will typically contribute to documents such as this.

---

"A basic understanding of coocons pipelines and their compontents."
- perhaps a link to relevant Cocoon docs would be helpful, there are some links on http://forrest.apache.org/docs/your-project.html#sitemap.xmap

---

"If you plan on creating your own custom processing for
HTML-pages, you'll also need write access to Forrest's
project directory.
"

---

"Follow this link to the <a href="sitemap.xmap.html#%3C%21--Start+of+Sitemap--%3E">start of the Sitemap.</a>"

- why a .html file?

---

"'*.xlex' that would match if our file ended with '.xlex'"

- it's the request that needs to end with .xlex rather than the file.

---

"<source>
&lt;map:match pattern="**/*.html"&gt;
    &lt;map:aggregate element="site"&gt;
      &lt;map:part"

- if you use "<source><![CDATA[ ... ]]

[Ferdinand Soethe]

Thanks for the corrections. Attached is an update of the xml-text.

Ferdinand


ico> - much as I appreciate the acknowledgement we don't
ico> directly reference developers in the docs. This is because over

Doesn't seem fair not to give credit but I changed that.

ico> - perhaps a link to relevant Cocoon docs would be helpful,
Good idea. Add a link to "Understanding Apache Cocoon"

ico> "If you plan on creating your own custom processing for
ico> HTML-pages, you'll also
ico> need write access to Forrest's
ico> project directory.
ico> "

Not sure what you meant to say here???

ico> "Follow this link to the <a
ico> href="sitemap.xmap.html#%3C%21--Start+of+Sitemap--%3E">start of
ico> the Sitemap.</a>"

ico> - why a .html file?

Converting them to HTML seemed the quickest way I knew to have them
rendered reliably in every browser and be able to add anchors and
comments for easy referencing.

What alternative are you suggesting???

ico> - it's the request that needs to end with .xlex rather than the file.
true, fixed it.

ico> - if you use "<source><![CDATA[ ... ]]

[David Crossley]

Thanks Ferdinand, that is added now. I split it into two HowTo documents:
* How to understand html processing and sitemap pipelines
* How to customize processing of html source

Both documents still need some work. Now that they are in SVN, we can all help.

I am concerned about the annotated sitemaps in *.xmap.html as it will be difficult to keep these synchronised as the Forrest core sitemaps change over time. Perhaps we could trim some stuff from them to make that easier.

It would be better to use CDATA sections so that we don't need to escape all the angle brackets and also make it easier to compare with the core sitemaps. I have done that change already.

[Ferdinand Soethe]

Thanks for the feedback.


Re splitting

The reason I did not split them after some consideration, is that you really need to understand what happens to be able to customize the pipeline documents properly (in fact that's how I learned all this because I found that Ross just telling me what to do will raise further questions right away). I'd be interested to know why you changed that.

Re CDATA

Thanks for doing the CDATA-stuff. I learned about this too late to apply it to this howto.

Re annotated sitemaps

I agree with your concerns. But I figured that you really need to follow and see those steps in the sitemap to understand what is going on. I'd be happy to use a different mechanism if it is practical.

For a start I could add more genereal comments to sections of the sitemap. And if we find a way to add some stable markers (comments?) to the sitemap I could perhaps use xincludes to quote the sitemap. Any suggestions on if and how this could be done?

[David Crossley]

Thanks, i will respond to those questions on the mailing list - they are not specific to this issue.