forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Ross Gardler <rgard...@apache.org>
Subject Re: [JIRA] Updated: (FOR-446) Dokumentation: HowTo Customize HTML Processing
Date Thu, 24 Feb 2005 11:15:16 GMT
issues@cocoondev.org wrote:
> The following issue has been updated:
> 
>     Updater: Ferdinand Soethe (mailto:sammler@soethe.net)
>        Date: Thu, 24 Feb 2005 2:19 AM
>     Comment:
> Thanks for the corrections. Attached is an update of the xml-text.

I'll look later today.

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

Well you have done through this list now. That is enough for me, and in 
the longer run is fairer on others who contribute after you and I stop 
working on it.

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

I didn't, this was a note for myself to go back and reconsider, I then 
realised I misread it in the first place (I thought it said write access 
to Forrest directory). I meant to delete before posting.

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

Hmmm... the anchors is the tricky one. The only alternative I can think 
of would be much more work, although would result in a better document. 
That would be use multiple <source id="myID"><![CDATA[ ... snippet 
...]]></source> with sections and introductory text. Perhaps this is for 
a later iteration as it would be quite a bit of work.

> ico> - if you use "<source><![CDATA[ ... ]]></source>"
> ico> there is no need to escape the '<' and '>' symbols.
> 
> Thanks, that's a good one. Will keep that in mind for the next one.
> Any reason to change it in this howto as well?

Only that having docs that use the easiest way to include stuff like 
that makes for good examples (our docs are also our examples). Since it 
is a search and replace perhaps we can do it easily.

> ico> <fixme>
> ico> I'm unclear about the translation from the property
> ico> project.stylesheets-dir to the variable {forrest:stylesheets}.
> ico> How and where does it take place and why are the names different?
> ico> That seems very confusing!                                 
> ico> </fixme>
> 
> ico> - There is no such translation. The two values are not connected
> 
> ico> ---
> 
> ico> " <strong>&lt;map:transform
> ico> src="{forrest:stylesheets}/fixMyBadHTML.xsl"/&gt;</strong>"
> 
> ico> - should be src="project:stylesheets-dir/fixMyBadHTML.xsl"
> 
> Confused! Why is forrest.xmap using {forrest:stylesheets} all over the place?

There are two locations for the stylesheets, the first is referenced by 
{forrest:stylesheets} which points to 
FORREST_HOME/main/resources/stylesheets and contains all the stylesheets 
that Forrest uses internally and the user should not touch, the second 
is {project:stylesheets-dir} which usually points to 
PROJECT_HOME/src/documentation/resources/stylesheets and is where the 
use puts stylesheets they have created.

This ensures that if you package up your project_home directory 
everything you need to build the site is present, this would not be the 
case if you put your custom stylesheets in {forrest:stylesheets}.

Ross

Mime
View raw message