... > > I may very well be getting confused on the terms root and current. > > The forrest docs say that " Forrest's sitemap comprises the > > $FORREST_HOME/context/*.xmap files." This leads me to believe that > > the terms root and current are conceptual rather than physical which > > would mean they are one and the same for the forrest cocoon app and > > mounting is just a mechanism to bring the physical maps together? > > Firstly that documentation is now misleading because we have plugin > sitemaps and project sitemaps as well now. Can you please point us to > the file you read that in so we can clarify it.
Sure, it's http://forrest.apache.org/0.7/docs/sitemap-ref.html I've got a patch for it that adds {project.sitemap-dir} and the plugins. And while we're on the fixing documentation subject, what's the preferred method for receiving them? Seems kinda heavyweight to open an issue for a relatively minor doc change but then I understand patches through email is frowned upon. ... > It may help you top read > http://forrest.apache.org/0.7/docs/howto/howto-custom-html-source.html > Although this how-to is not about what you want to do it does have a > very clear description of the logic in sitemap processing. It is most unfortunate that such a good discussion of the pipeline process is hidden under that title. It even says the intended audience is "everybody who wants to learn more about Forrest's pipelines in general." I *highly* recommend changing this title to something more generic and even consider putting in the main docs. Something like "Forrest Pipelines by Example" should get folks attention. This short little doc could have literally shaved days off my learning curve. > > If > > those terms are applied physically it might be more understandable why > > they are used differently in forrest but then i would like to make > > some suggestions to the documentation as i would consider it to be > > misleading in it's current form. > > This is another reason why we don't mind taking the time to clarify > things in response to your questions. It is our hope that you will > indeed provide patches to the docs based on the understanding you gain > from asking those questions. > > In other words, bring on those patches :-)) > > >>cocoon:// will mount from *any* sitemap in the app > > > > > > again, sitemap as a physical file? meaning \main\webapp\*.xmap + > > {project.sitemap}? > > Yes, but as mentioned above we also have plugin sitemaps and project > sitemaps now. You can see the mounts for these in > /main/webapp/sitemap.xmap and /main/webapp/forest.xmap > > >>In other words, you can make it break if you change the wrong one. > > > > > > Right, but I'm still not clear on what would qualify as the "wrong one". > > > > Here are a few examples that seem odd to me. > > > > linkmap.xmap - For the match "**linkmap-*", the generator is pointing > > to cocoon://abs-linkmap which in my understanding would go back to the > > root sitemap (ie., sitemap.xmap) and match the abs-linkmap there which > > essentially points right back to the match that was above it in the > > first place. In this case, why not use cocoon:/abs-linkmap. > > OK The truth is that many developers do not understand the full > implications of the subtleties of things like the difference between > cocoon:// and cocoon:/ The further truth is that my explanations here > are "as I understand it" (a disclaimer I had in the very first sentence > of my initial response). What I am saying is that many of us devs do > what makes it work, it may not be the *best* way, but it does work. In > other words, just because it is in our code base it does not mean it is > necessarily the right way. > > As you know one of the benefits of Open Source is the many eyes > principle. That is with lots of devs looking at the code it gradually > gets improved. The principle also applies to mailing list discussions > like this, if my assumptions are incorrect, it is hoped that someone > will spot that and clarify the situation. > > In your example above I imagine (there's another of those disclaimers) > that using cocoon:/ as you suggest would in fact be more efficient, as > Cocoon would not need to check for a match in sitemap.xmap, only in > linkmap.xmap. > > I'd suggest changing things and doing: > > cd FORREST_HOME/main > ./build clean test > > If everything works then you can submit a patch. At this point someone > will definitely review the code and, if our assumptions are correct it > will be applied and hence the code will be improved (along with out > understanding). > > > tabs.xmap - the last transformer has a src of > > "cocoon:/{1}linkmap-{2}.html" which apparently goes resolves in > > sitemap.xmap and ultimately linkmap.xmap seems link it should be > > cocoon:// if anything should. > > OK, this would seem to imply that my assumptions of the behaviour of > cocoon:/ and cocoon:// are incorrect. So let me go to the Cocoon docs... > > In http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html > > I found: > > # Use cocoon:/current-sitemap-pipeline/foo/bar to merge in xml content > from the current sitemap. The appropriate pipeline is selected matching > current-sitemap-pipeline. > # Use cocoon://root-sitmap-pipeline/foo/bar to merge in xml content from > the root sitemap. The appropriate pipeline is selected matching > root-sitemap-pipeline. > > and > > Mount points allow sitemaps to be cascaded and site management workload > to be parallelized. This creates a tree of sitemaps with the main > sitemap at the root and possibly several sub-sitemaps as nodes and leaves. > > This seems to agree with what I have said so far. So what is the difference? > > I don't know the answer to this one. Lets hope someone else here knows > and explains for us. If not then we need to go to the cocoon-users list > and check their archives and if necessary ask the question. > > I will hazard a guess based on the behaviour I have witnessed (and it is > a guess). It might be that the cocoon:/ falls back to searching from the > root sitemap if no match is found in the current sitemap. I am offering > this as a guess since I know that you can have two matchers in different > sitemaps that would ultimately do the same thing (i.e. both match > "*.xml"). If you do cocoon:// from the sub sitemap then the matcher in > the root is used. If you do cocoon:/ then the one in the sub sitemap > (current) is used (i.e. the behaviour is as described). > > > >>>2) The same doesn't appear to hold true of forrest-core.xconf as > >>>things do break if the correct one isn't used. Since all of them here > >>>are to the root sitemap (e.g., cocoon://) is forrest-core.xconf > >>>outside the forrest conceptual sitemap? > >> > >>Pass > > > > > > Fair enough, anyone else? Ironically enough, it was your reference to > > cocoon://locationmap.xml in xconf that got me reading: > > http://cocoon.apache.org/2.1/userdocs/concepts/sitemap.html#Protocols > > and wondering how these schemes work. > > > Ahhh... well now I can tell you what "my understanding" is. > > the value cocoon://locationmap.xml is just a value of a variable used in > the LocationMap code. It is used within the processing of the sitemap > and so the behaviour is no different. In other words it says, start > looking in the root sitemap (FORREST_HOME/main/webapp/sitemap.xmap) and > if necessary look in any relevant mounted maps. > > >>>3) Are project specific sitemap.xmaps are separate root sitemaps or > >>>extensions of the forrest application sitemap? > >> > >> > >>The are mounted from the application sitemap by the following: > > > > ... > > > > Yes, I saw that but am still not clear on whether that makes them > > interchangable with cocoon:/ and cocoon://. All others within > > main\webapp are mounted as well so are they equals? > > According to my understanding as expressed above a cocoon:/ in the > project sitemap will *not* search the root sitemap, a cocoon:// will. > > Of course, you have provided an example that indicates this is not the > case despite the Cocoon docs agreeing with this. The hypothesised > fallback behaviour would fit this case too. > > To have a definitive answer you will need to search the cocoon mail list > archives and if necessary ask over there. I did search the Cocoon mailing list and it brought me some comfort in knowing that there are many folks confused by the cocoon protocols. --tim
