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 Sun, 02 May 2004 21:23:23 GMT
David Crossley wrote:
> Nicola Ken Barozzi wrote:
> 
>>David Crossley wrote:
...
>>>The skinconfig could still have a single namespace so that tools
>>>could decide which RNG grammar to apply.
>>
>>Hmmm, hadn't thought of that... IIUC this makes it possible for 
>>extensions to validate their part too. I like it, also because
>>of the suggestion from Dave, about skins declaring what they need
>>(in this case about non-standard features).
> 
> Oooh, that idea has potential. 

Mine or your's? ;-)  I love it when these ideas come out like this, and 
we both think that it's the other one that thought it. You can never 
tell who actually came up with it :-)

> When skin developers want to add a
> new feature, then they still follow the feature-element-property
> model and simply change the namespace to be
>  <skinconf xmlns="http://me.com/forrest/skinconf/x.y">
> and then apply their own RNG validation if they want to.
> This is then consistent with normal forrest skinning machinery.

Yup :-)

Or add their own namespace for the extra elements.

...
>>It's because XmlProperty does not use a catalog and fails to load DTDzed 
>>docs.
> 
> Ah, so a deficiency in Ant then.

(It's a deficiency in the the XmlProperty task that I wrote, so don't 
say it too loud... ;-)

>>>Is there a Proposal 4 ... The simple feature-element-property
>>>stuff from Proposal 2 but with multiple namespaces like Proposal 3.
>>
>>Proposal 4
>>-----------
>>
>><!-- add simple DTD here -->
>><skinconf  xmlns="http://apache.org/forrest/skinconf/1.0"
>>            xmlns:myns"http://mydomain.org/myproject/xmyns/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>
>>
>>   <myns:sample id="me" weight="84kg">My Name</myns:sample>
>></skinconf>
> 
> However, Proposal 4 could not have the internal DTD because
> the "myns:sample" addition would contravene it.

Oops...

Then this:

<!-- 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 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>

Or if one prefers this is an alternative syntax to the same effect:

<!-- add simple DTD here -->
<skinconf xmlns="http://apache.org/forrest/skinconf/1.0
           my:xmlns="http://mydomain.org/myproject/xmyns/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 the
          one needed to validate this skinconf extension -->
     <my:feature my:name="myfeature">
        <my:property my:name="me">My Name</my:property>
        <my:property my:name="weight">84kg</my:property>
     </my:feature>

</skinconf>

>>How about the comment section?
...
>>   ---
>>   |4|
>>   ---
>>
>>   <!--**
>>      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  -->
>>
>>
>>I think that (4) is the best for comments, as it can easily be 
>>transformed to documentation with a stylesheet like the one below, and 
>>is easy on the eye (in contrast with namespaced docs):
> 
> 
> ---
> |5|
> ---
> 
>   <feature name="credits" value="true"/>
>     <desc> <!-- The description of the feature -->
>       Display various credit logos.
>     </desc>
>     <doc> <!-- The documentation for the feature-elements -->
>       <desc>Logo to be shown for credits</desc>
>       <prop>
>         <name>title</name>
>         <purpose>The title for the logo</purpose>
>         <required>yes</required>
>       </prop>
>       <prop>
>         <name>url</name>
>         <purpose>The URL that the logo refers to</purpose>
>         <required>no</required>
>       </prop>
>       <prop>
>         <name>image</name>
>         <purpose>Relative path to the image file</purpose>
>         <required>yes</required>
>       </prop>
>       <prop>
>         <name>width</name>
>         <purpose>image width in pixels</purpose>
>         <required>yes</required>
>       </prop>
>       <prop>
>         <name>height</name>
>         <purpose>image height in pixels</purpose>
>         <required>yes</required>
>       </prop>
>     </doc>
>     <element>
>       <property name="title">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>...</element>
>     <element>...</element>
>   </feature>
> 
> Documentation can easily be generated from this.
> 
> The xml editors can control the addition of documentation
> for features in the skinconf.xml, because the doc structure
> can be defined in the simple internal skinconf DTD.

Hmmm... it looks *much* more verbose than version 4, 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.

> 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!

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>

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>

We can easily generate the schema and the default transformation xsl 
with both notations.

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


Mime
View raw message