forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [DEVOTE] Solving the skinconf riddle
Date Fri, 30 Apr 2004 11:19:03 GMT
I am still having trouble deciding which way to go,
so making some comments and asking some more questions ...

Nicola Ken Barozzi wrote:
> As a summary, the point of discussion is over validation or not, and how 
> to do it.

I think that the main point is to make it easy for users
to configure it and easy to maintain between versions of Forrest.

> I would like to try removing strong validation, as I see 
> mainly the drawbacks, while Cheche feels that strong formal validation 
> is needed and that the DTD format is the best for the editors.

It is very interesting to note the discussion on the cocoon-users
saying that xml editors utilise RELAX NG now.

> The proposal are as follows:
> 
> Proposal 1 (From Cheche)
> --------------------------
> 
> Historically the skinconf file has hold the document type definition 
> (DTD)  within the same file. This DTD ensure that the xml nodes are 
> correct with that definition.
> This lead of problems when this definition is updated, so some of us, 
> have put some effort to move out the DTD and replace with a public 
> reference:
> 
>   <!DOCTYPE skinconfig PUBLIC
>          "-//APACHE//DTD Skin Configuration V0.6//EN"
>          "skinconfig-v06.dtd">
> 
> It can be used by xml editors to identity elements and attribute for 
> this file.
> 
> The problem with this public reference it that relays on a internet 
> connection, but for that issue we have the "Catalog Entity Resolver for 
> local DTDs" http://xml.apache.org/forrest/catalog.html
> 
> With this, all these xml editors knows how to tread the skinconf.xml file.

I gather that the skinconf.dtd gets new version numbers for every
change and that this makes it easier for users to keep their skinconf
files up-to-date. There could even be helper transformations for
updating skinconf between versions.

The trouble is that writers of new skins cannot add special
elements for their purposes.

> Proposal 2 (From Nicola Ken)
> -----------
> 
> The latest happenings on skinconf have brought me to consider a format 
> for skinconf.xml.
> 
> Here is the proposal:
> 
> * Forrest should work also without any skinconf element: skinconf
>    elements are just hints, that a skin can decide not to follow
>    (as it happens already actually, just that the DTD makes people think
>     that Forrest will necessarily honor all hints)
> 
> * there is a simple DTD used as a structure (see below)
> 
> * features are listed in a doc file that is generated from the comments
>    put in the fresh-site skinconf.xml (an example of the possible
>    formats is included in proposal 3)
> 
> * any update to the skinconf that changes feature names will be included
>    in the general skinconf pipeline xsl
> 
> Here is a proposed skinconf:
> 
> <skinconfig>
>    <feature name="logo">
>       <property name="name">Forrest"</property>
>       <property name="url">http://xml.apache.org/forrest/</property>
>       <property name="logo">images/project-logo.gif</property>
>    </feature>
> 
>    <feature name="lucene" value="false"/>
> 
>    <feature name="search" value="true">
>       <property name="domain">xml.apache.org</property>
>       <property name="name">Apache XML</property>
>    </feature>
>    ...
>    <feature name="obfuscate-mail-links" value="true"/>
>    ...
>    <!--  -->
>    <feature name="credits" value="true"/>
>      <element>
>        <property name="name">Built with Cocoon</property
>        <property name="url">http://xml.apache.org/cocoon/</property >
>        <property name="image">images/built-with-cocoon.gif</property >
>        <property name="width">88</property >
>        <property name="height">31</property >
>      </element>
>      <element>
>        <property name="name">...</property
>        <property name="url">...</property >
>        <property name="image">...</property >
>        <property name="width">...</property >
>        <property name="height">...</property >
>      </element>
>       ...
>    </feature>
> </skinconfig>
> 
> In this way we get lax and extensible elements but reasonable editing.
> The DTD will not change, so we can easily inline it in the XML, thus 
> making it trivial for validating editors to validate it (no catalogs to 
> set).
> 
> In this way we will have a simple skinconf DTD, that is both extensible 
> and formally validated.

I do like this very simple schema. The internal DTD allows
some basic structural validation by all xml editors. I presume
that we can then do various RELAX NG validations of the content,
ensure certain attributes, etc. This is good because it separates
the concerns (validation of structure and validation of content).

The skinconfig could still have a single namespace so that tools
could decide which RNG grammar to apply.

> Proposal 3 (From Nicola Ken trying to mix Cheche's suggestions )
> -----------------------------------------------------------------
> 
> - Add the forrest skinconf namespace
> - Remove DTD
> - use only RelaxNG validation for it, with no tag required
> - add the injections of default tags in the skinconf pipeline
>    for the ones that skins requires
> 
> This should:
> 
> - Keep it extensible by namespacing
> - Keep the stylesheets as are now
> - Keep validation (as RelaxNG IIRC runs on namespaces)

I presume that future changes to skinconf then get a new
namespace ...skinconf/1.1 which enables the correct validation
to be applied.

> - Make it loadable by XmlProperty

This sounds important. Does that mean that we can get away
from the need to use the document() function via XSLT?
Do Proposal 1 and Proposal 2 still need to use document() ?

What is the difference that makes it "loadable by XmlProperty"?
Is it because it has definite names for elements as opposed
to Proposal 2?

> Here is an example of it:
> 
> <skin:skinconfig xmlns:skin="http://apache.org/forrest/skinconf/1.0"
>                   xmlns:xd="http://apache.org/forrest/xd/1.0"
>                   xmlns:myns"http://mydomain.org/myproject/xmyns/1.0">
> 
>    <!-- nicolaken: a possible version of the comments -->
>    <xd:doc>
>       <xd:descr>To enable lucene search add
>                     provider="lucene"</xd:descr>
>       <xd:attr name="name">The name of the project</xd:attr >
>       <xd:attr name="domain">The URL domain of the
>                                                  project</xd:attr >
>    </xd:doc>
>    <skin:search name="MyProject" domain="mydomain"/>
> 
>    <!-- nicolaken: second simpler possible version of the comments -->
>    <xd:descr>Do we want to disable the print link? If enabled,
>              invalid HTML 4.0.1</xd:descr>
>    <skin:disable-print-link>true</skin:disable-print-link>
<snip/>

                         --------
Is there a Proposal 4 ... The simple feature-element-property
stuff from Proposal 2 but with multiple namespaces like Proposal 3.

--David



Mime
View raw message