forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Marc Portier <...@outerthought.org>
Subject Re: Link-Addressing, and breaking up the sitemap
Date Thu, 05 Sep 2002 15:36:58 GMT


[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 :-)

<snip on tabs and default pages />
<snip on snippets of sitemap />

[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 <link href=""> ?
(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:
> 
> <map:match pattern="*.html">
> <map:match pattern="**/*.html">
> 
> 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"
<map:match pattern="*.html">
<map:match pattern="**/*.html">
over
<map:match pattern="faq/**/*.html">

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 <xsl:import> 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


Mime
View raw message