forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: [DEVOTE] Solving the skinconf riddle
Date Mon, 03 May 2004 09:53:48 GMT
David Crossley wrote:
> Nicola Ken Barozzi wrote: 
...
>><!-- add simple DTD here -->
>><skinconf xmlns="http://apache.org/forrest/skinconf/1.0">
>>
>>     <feature name="logo">
>>        <property name="name">Forrest"</property>
>>        <property name="url">http://.../forrest/</property>
>>        <property name="logo">images/project-logo.gif</property>
>>     </feature>
>>
>>     <!-- set the default namespace of this section to the
>>          one needed to validate this skinconf extension -->
>>     <feature xmlns="http://mydomain.org/myproject/xmyns/1.0"
>>              name="myfeature">
>>        <property name="me">My Name</property>
>>        <property name="weight">84kg</property>
>>     </feature>
>>
>></skinconf>
> 
> Okay, i created a simple skinconf.xml instance along
> those lines and it can be validated using an internal DTD.
> 
> This format seems ideal to me.

...

> We are aiming to generate documentation and schema from
> these comments, so i would think it would be more reliable
> to control that information with a good structure and the
> internal DTD.
...
>>... and defeats the 
>>purpose of using comments, that is to make the system available to any 
>>xml file, regardless the schema-dtd-whatever it uses to validate.
> 
> Sorry, i cannot parse that. Would you try to explain again please.

I mean that the stylesheet that generates the documentation in the case 
of <!--@ tags can be applied to any xml file, without adding namespaces, 
so it could become a sort of standard xmldoc format.

>>>Perhaps even RELAX NG grammars can be generated from the
>>>skinconf.xml files.
>>
>>This is an excellent idea! A sort of schema by example, really neat!
> 
> We have not done it yet, but yes, it seems to be possible.
...
>>Hmm, what about this then:
>>
>>  --
>>  |6|
>>  --
>>
>>    <feature name="credits"
>>             value="true"
>>             description="Display various credit logos" >
>>
>>      <element>
>>        <property description="The title for the logo"
>>                  required="true"
>>                  name="title" >Built with Cocoon</property>
>>
>>        <property description="The URL that the logo refers to"
>>                  required="true"
>>                  name="url" >http://xml.apache.org/cocoon/</property >
>>
>>        <property description="Relative path to the image file"
>>                  required="true"
>>                  name="image" >images/built-with-cocoon.gif</property >
>>
>>        <property description="image width in pixels"
>>                  required="false"
>>                  name="width" >88</property >
>>
>>        <property description="image height in pixels"
>>                  required="false"
>>                  name="height" >31</property >
>>      </element>
>>    </feature>
> 
> 
> This might confuse the user. Which attributes do they need to edit
> and which attributes are for doc purposes? There are mixed concerns.

Err, you are right...

> However, that is a minor issue. This format is looking really neat
> and also well-defined.
> 
>>Alternative comment notation:
>>
>>    <!--** Display various credit logos-->
>>    <feature name="credits"
>>             value="true">
>>
>>      <element>
>>        <!--The title for the logo-->
>>        <!--@required true -->
>>        <property name="title" >Built with Cocoon</property>
>>
>>        <!--The URL that the logo refers to-->
>>        <!--@required true -->
>>        <property name="url" >http://xml.apache.org/cocoon/</property >
>>
>>        <!--Relative path to the image file-->
>>        <!--@required true -->
>>        <property name="image" >images/built-with-cocoon.gif</property >
>>
>>        <!--image width in pixels-->
>>        <!--@required false-->
>>        <property name="width" >88</property >
>>
>>        <!--image height in pixels-->
>>        <!--@required false-->
>>        <property name="height" >31</property >
>>
>>      </element>
>>    </feature>
> 
> 
> My worry with this is that it might not be robust enough to
> generate documentation and schema from it. However, the main
> file will be the one in "forrest seed site" and we have control
> over that, so perhaps this will be okay.

The fact is that in the comments we have:

(a) <!-- -->

(b) <!--@required false-->

(a) can be missing, it's not needed to generate the schema.
(b) IMHO can still be missing, as we assume that it's not required in 
that case.

I've read Dave's comment about "Pure XML would be better", and actually 
it seemed right. But then I read your comment about mixing docs with the 
file instance, and I start to wonder. In fact, the 6b version does not 
mix the things in the same xml.

On the other hand, I start to ask myself: in which files do we need the 
@required tag? They are required by the skins, so in fact that should 
*not* be in the skinconf.

IOW

The fresh-site should have this:

<!-- add internal DTD here -->

<!-- These are the basic tags that the skins of the standard Forrest
      distro understand. Refer to the docs of the actual skin being used
      for extra tags -->
<skinconf xmlns="http://apache.org/forrest/skinconf/1.0">

     <!--Display various credit logos-->
     <feature name="credits"
              value="true">

       <element>
         <!--The title for the logo-->
         <property name="title" >Built with Cocoon</property>

         <!--The URL that the logo refers to-->
         <property name="url" >http://xml.apache.org/cocoon/</property >

         <!--Relative path to the image file-->
         <property name="image" >images/built-with-cocoon.gif</property >

         <!--image width in pixels-->
         <property name="width" >88</property >

         <!--image height in pixels-->
         <property name="height" >31</property >

       </element>
     </feature>
</skinconf>

Each skin would have the complete version instead, with the 
<!--@required--> tag stuff or the required="" attribute, from which 
Forrest would dynamically create the skinconf.xsl file that is now done 
"by hand".

Given that this file would be made by skin authors and that it's better 
to keep a single schema for skinconfs maybe it's better to use the <!--@ 
annotations for this file instance.

Hmmm...

> So the competitors in the grand final are 5 and 6a and 6b.

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


Mime
View raw message