[C2] Cocoon2 2.0a3 with CLI

[Stefano Mazzocchi <st...@apache.org>]

People, 

it's with great joy that I announce the availability of a new milestone
for Cocoon2 with the integration of an operational command line
interface.

WARNING: 'operationals' means that is somehow works, but it doens't mean
all the planned functionalities are in place at this time.

To experience the command line yourself, simply do:

 ./build.sh dist
 cd ./dist/cocoon-2.0a3
 ./run.sh welcome

and Cocoon will automagically save on the ./site directory a static copy
of the resources accessible from the welcome page. 

Note 1: no servlet engine is required for this.
Note 2: a java compiler *is* still required to compile the sitemaps (but
the scripts take care of everything)

                 -------------- o --------------

How does it work?
-----------------

Cocoon2 CLI is based on XLink and the notion of 'resource views'.

The simplified algorithm works like this:

 1) bootstrap the Cocoon engine (sitemaps are compiled)
 2) request the "links" view of the requested root resource
 3) cocoon returns the list of linked resources
 4) iterates on each resource calling number 2) recursively
 5) save the resource on disk by translating the links

[look in Mail.java for a the complete algorithm implementation]


What does it mean to me?
------------------------

In theory, it means we can throw StyleBook finally down the drain.

In practive, this is not yet so for a number of reasons:

1) link translation is implemented by not called since, honestly, I have
no idea on how to call it :( (more later)

This means the files are saved on disk, but all the links are broken so
file navigation is not impossible.

2) stylebook has modest (yet important) internal content aggregation
capabilities (the sitebar is automatically created out of a
DirectoryGenerator... Cocoon2 has no internal content aggregation
capabilities, even if they are planned for the near future.

3) XHTML has no notion of XLink and there is no "official" way to do
this. [note: the XSchema spec is currently stalled *exactly* for this
reason, so this is very likely to be resolved in the future]

This means that you have to translate your pages into an XLink-extended
HTML in order for the link serializer to understand that your images in
the pages are to be downloaded and saved on disk.

For now, this behavior is not yet implemented and this is why the cocoon
logo on welcome.html is not saved on disk (because it's not yet present
when the link view parsers the links!)

XLink and views force you to rethink completely the content aggregation
capabilities of web pages... I admit it's hard to think this way for
myself... it's not clear how hard this will be in the future.... of
course, as always, we are at least 6 months ahead of anybody else so the
bleeding edge hurts...

Anyway, your feedback is appreciated.


How do I test my documents?
---------------------------

First look into the ./webapp/docs/samples/samples.xml and try accessing
the 'links' view of the 'welcome' resource

 http://localhost/cocoon/welcome?cocoon-view=links

this will return you a link list such as 

+ hello.html
+ hello.wml
+ hello.vml
+ hello.svg
+ hello.wrl
+ hello.pdf
+ sites/java.apache.org
+ sites/jakarta.apache.org
+ fo
+ svg
- slides/slides
- xsp/simple
- sql/sql-page
- status
- generror

where +/- indicate whether or not Cocoon should follow those links or
not. This is triggered by an XLink "role" of the element in the original
document, so in samples.xml we have

   ...
   <sample name="scalable vector graphics" 
           xlink:href="svg" xlink:type="simple">
    An example of a SVG file rendered to a PNG image.
   </sample>
   <sample name="slides" 
           xlink:href="slides/slides" xlink:type="simple" 
           xlink:role="dynamic">
    Example of complex XSLT usage.
   </sample>
   ...

where you can see that the first sample didn't have a specific role
defined (so Cocoon interprets no role as "static" role and place a '+'
in front in the link view), while the second sample has a different
XLink role and it's not listed for parsing.

Note that it's up to the client to interpret this information... the
link view is simply suggesting you what to do.

WARNING: the XLinkSerializer responsible to create the links view, is
triggered by the presence of 

 xlink:type="simple" 

or

 xlink:type="locator"

*NOT* by the presence of 

 xlink:href="..."

alone. So, either you specify those attributes in your DTD or XSchema,
or you are forced to use them.

SEMANTIC NOTE: the difference between a simple link and a locator is not
simple and you should read the XLink spec to find out... but in short,
you can think of a locator as the abstraction of the HTML <img
src="..."> while simple link is the abstraction of <a href="...">.

The problem is that XHTML uses 

 <a href=""></a> and <img src=""/>

so you would have to write something like

 <a href="" xlink:type"simple" xlink:href=""></a> 

and 

 <img src="" xlink:type="locator" xlink:href=""/>

in order for Cocoon to understand these are links.

Currently the XMLSchema is working on allowing something close to
element/attribute behavioral inheritance (hopefully nothing as complex
as SGML HyTime Architectural Forms), so you might be able to say in your
XMLSchema that
 
 element 'a' has xlink:type="simple" and has attribute 'xlink:href' that
inherits content from 'href'

or
 
 element 'img' has xlink:type="locator" and has attribute 'xlink:href'
that inherits content from 'src'

Something like this is *vital* for C2 CLI to be of any use without a
babel of language-specific link serializers and to allow a safe and
algorithmically certain link translation.

For any further question, problem, suggestion, as always, feel free to
answer.

Happy hacking :)

-- 
Stefano Mazzocchi      One must still have chaos in oneself to be
                          able to give birth to a dancing star.
<st...@apache.org>                             Friedrich Nietzsche
--------------------------------------------------------------------
 Missed us in Orlando? Make it up with ApacheCON Europe in London!
------------------------- http://ApacheCon.Com ---------------------