forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject [DEVOTE] Solving the skinconf riddle
Date Wed, 28 Apr 2004 13:05:37 GMT

What has happened AFAIK is that in the middle of a vote in which it 
seemed that there was consensus, Juan has argumented strongly for his 
position, and this has brought us to come up with at least two other 
solutions.

As David has correctly noted, we should try to reconcile them in a final 
decision. If there are other proposals to be made please add them now, 
but please let's also refrain from commenting for at least a day, so we 
have time to think these over a bit.

As a summary, the point of discussion is over validation or not, and how 
to do it. 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.


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.


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.


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)
- Make it loadable by XmlProperty

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>

   <xs:descr>Do we want to disable the PDF link?</xs:descr>
   <skin:disable-pdf-link>false</skin:disable-pdf-link>
...

   <!-- nicolaken: third type of possible documentation-->

   <!-- project logo, skin: forrest-site renders it at the
        top  -->
   <skin:project-name>MyProject</skin:project-name>

   <skin:project-description>MyProject Descr</skin:project-description>
   <skin:project-url>http://myproj.mygroup.org/</skin:project-url>
   <skin:project-logo>images/project.png</skin:project-logo>

...

   <!-- nicolaken: last type of possible documentation, the
                   one I tend to prefer -->
   <!--
      A sample tag with external namespace, and the third type of
      possible comments. Note that the comment system we add here
      can easily be added to any Forrest document in xml.
      @id     the id of the person
      @weight the weight of the person in kilograms
   -->
   <myns:sample id="me" weight="84kg">My Name   </myns:sample>

</skinconfig>

Note that the docs could in the future be also mixed woth the 
information of the RelaxNG schema that shows also teh possible formal 
values that it can contain.

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message