[conceptual on the idea/resent of having sitemap generated]
>
> Yes, trying to 'hide' the sitemap could just introduce a layer of
> complexity and get in the way.
>
although one of my arguments pro-siteplan would of have been that
it could be _easier_ then the cocoon sitemap (reduce
complexity, rather then add a layer that tries to enable
everything in different wording...)
given the fact that it would not try to offer everything of the
underlaying cocoon (but as stated before: people knowing it is
cocoon will not take that)
[practical on the idea of 'relativising' the 'staticalized' html]
>>whadayathink?
>>using the CLI is about "staticalizing" your content. The webapp
>
>
> That's almost as bad as 'prextensination'! ;)
>
that was Steven's word for it (although my idea)
>
>>does not have this concern, so only the CLI needs to be taking up
>>this concern to 'relativise' all the /-leading references in the
>>produced static content.
>
>
> +1. Just like how JSP tags all treat '/'-leading paths as relative to the
> servlet context, not the server root.
>
yep, glad you like the idea more then the word :-)
[theoretically on goals]
>>sounds good, but needs some elaboration though...
>
> It would be best to define the goals first:
>
> - Users need to be able to customize the sitemap with their own
> matchers, for whatever crazy reasons they want.
maybe we should find reasons just to make sure this _is_ a valid
goal, AND to make sure that those 'crazy' reasons will be
satisfied by allowing snippets of sitemaps?
>
> - In addition, we'd like to provide quick'n simple ways of doing routine
> customizations, like specifying javadoc prefixes, and adding pipelines
> for new document types (docbook, say). Ie, a siteplan.
adding pipelines for the document types should be covered by the
CAPs and the previous discussion no?
mmm, provided the end-user can add to that of course, but again:
maybe the CAP could be told in a different way then the sitemap
about possibly new stuff?
mmm, lets look at how the CAP turns out first, then we can
discuss on letting it know about newer stuff
> - Forrest's sitemap needs to be modularized, so users can choose just
> the functionality they need. If they don't want svg2png, don't include
> Batik. If they don't want PDFs, don't include FOP.
>
isn't this the kind of challenge that asks cocoon to be
modularized first?
could be me, but it is probably not the first goal of forrest to
do that cocoon-work?
>
> To meet these goals, I'd like to chop the sitemap into functional
> sections:
>
> - Straight *.xml to *.html
> - Site statistics reporting (apachestats)
> - todo generation
> - changelog generation
> - faq
> - 'community' section with feedback
> - doclist
> - DTD documentation
> - PDFs-of-every-page
>
> Each of these is in a sitemap 'snippet'. Users can add project-specific
> functionality by adding new snippets.
>
mmm, most of the ones you mention are about types and the
pipeline to get them through the 2-step-view rendition towards
pdf, html, whadayanameit... so that is the stuff we covered with
the CAPS & hints discussion, no?
the new thing I want to address is how to find and
cross-reference these documents...
[stubborn on the issue at hand]
let me try to restate my original posting on this:
Suppose...
I produce an xdoc page that explains how to contribute to my
project X... so naturally I think about making a link to the
javadoc of the central class of my API (something like a service
facade, imagine)... what do I write down in the ?
(same for book.xml links to junit reports e.g.)
and the issue should not be the trailing part any more
- given it's javadoc it could be ready html to read, or maybe
skinless xml to pull through the pipes... don't care: CAP should
solve it
what needs to be solved:
where is the javadoc html?
how do I reference it?
1. either we don't care and say:
the link reads:
http://someserver/path-to-javadoc/package-path-to-class/ClassName
(of content-type text/html)
and it is up to the organizer of the site to make sure that the
expected content is there.
+ we forresters can go happy to sleap
- our end-user looses sleap when he needs to update all his links :-(
- end-users that want to sleep now and then are forced to dirty
copy-with-filter ant tasks or additional xslt stuff before their
xdoc should be picked up by forrest (being the ignorant PITA,
although it does nice skinning, sir!)
2. either we expect the end-user to have covered it by not only
*producing* this stuff in an ant-task that preceeds the
forrest-task... but also: moving it into the cocoon context
directory!
now the link reads "/jdoc/package-path-to-class/Name.html"
(or a version that he makes relative himself ?)
and he just makes sure the CAP-hint pipeline grabs it there by
letting ant produce/move the stuff to the cocoon context directory
Great idea, however
- the cocoon context dir is where forrest puts it, sorry
- it is also organized the way forrest does it, sorry
in other words: this is making too much of our internals public
as features, no?
It could still be possible though, and forrest would never know:
If the content-dir this person provides to the forrest-task would
not be ./src/documentation but ./build/documentation where he
first mingles all his stuff himself...
3. we could possibly aid more...
- in all cases the enduser still needs the ant tasks (foreign
processes) to generate the javadoc (or other stuff)
- he knows where they are relative to his project.home
- we let him tell forrest (1) where that is, (2) how other
documents are referencing the root of this stuff...
my current guess would be to do that with the XML snippet I
proposed... (but possibly you all feel that letting him write the
mingle-into-build/documentation/ ant is easier?)
then let some smart ant-task (part of the forrest activity) read
that file, copy the described stuff over into the cocoon context
dir (we stay in charge of location and organization) where the
CAP-hints pipeline deals with it as soon as the webapp or crawler
asks for it
if we go for 3 over 2
then we could also hook in the tabs here (but that would be the
next issue)
[analytical on why mounting subsitemaps will not do this]
> Could this breakup be done by mounting subsitemaps? I don't think so,
> because it would be impossible to order the subsitemap mounts correctly,
> without knowing what's in them. Eg, say the "straight *.xml to *.html"
> subsitemap is mounted first. It contains matchers for:
>
>
>
>
> That's going to match requests that ought to be left for the todo,
> changelog, faq and community snippets. Conclusion: the master sitemap
> writer would need to know in detail, just what mounted snippets contain
> and how they could interact. It's perfectly feasible that two snippets
> could 'deadlock', with A required before B in some circumstances, and B
> before A in others.
>
> So my suggested alternative to subsitemaps is to simply throw all snippet
> contents together into one big sitemap, and then sort by increasing
> matcher generality. So *.html and **/*.html will end up near the bottom.
>
>
>>and again, maybe solving it with less ant and more new cocoon
>>components would probably also solve it, and be more welcomed?
>
>
> The cleanest solution is for Cocoon to not care about matcher order. You
> don't have to order your templates in XSLT, so why should you have to
> order matchers in a sitemap? If the sitemap didn't care about order, then
your principle of the "increasing matcher generality"
over
assumes that all colliding matches are of a form that allows
deduction of (like Java does) "unreachable code", no?
there could be complex rules to find to 'order' these
/prefix/**
*.html
in terms of increased generality?
and what if we throw in regex matchers: p(.*)l
this makes me think about priorities inside xslt :-(
In every case, I think the issue I tried to address does not
require this... again pipelines, matchers, renditions should be
covered.... we only look for (a hopefully simple) mechanism to
slide in different content, with different structure,...
in a way that it can be cross-referenced...
-marc=
> we could just mount subsitemaps for each snippet, just like in an XSLT
> you can various XSLTs in any order.
>
> So given this solution, either implemented as an Ant task, or as an
> enhanced Cocoon, how does it meet the goals?
>
> - Users need to be able to customize the sitemap with their own
> matchers, for whatever crazy reasons they want.
>
> The Ant task just includes ${project.home}/src/documentation/*.xmap,
> which adds user-defined snippets to the mix.
>
> - In addition, we'd like to provide quick'n simple ways of doing
> routine customizations, like specifying javadoc prefixes, and adding
> pipelines for new document types (docbook, say). Ie, a siteplan.
>
> The Ant task transforms the siteplan into a number of .xmap snippets,
> which are then included.
>
> - Forrest's sitemap needs to be modularized, so users can choose just
> the functionality they need. If they don't want svg2png, don't
> include Batik. If they don't want PDFs, don't include FOP.
>
> If the user can edit the includes and excludes pattern that the Ant task
> uses to find .xmap snippets, then they can exclude snippets they don't
> want.
>
> Problem solved :) Technically, all that is required is a way of ordering
> matcher patterns, and then the Ant task is easy. Then we ask Sylvain if he'll
> kindly write us another sitemap processor that ignores matcher order, and
> it's beer and skittles from there on.
>
>
> --Jeff
>
>
>
>>-marc=
>
>
--
Marc Portier http://outerthought.org/
Outerthought - Open Source, Java & XML Competence Support Center
mpo@outerthought.org mpo@apache.org