forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Dave Brondsema <d...@brondsema.net>
Subject Re: [DEVOTE] Solving the skinconf riddle
Date Mon, 03 May 2004 07:23:16 GMT
On Mon, 3 May 2004, David Crossley wrote:

> > > --
> > > |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, ...
>
> Yes, it is verbose. However there are other things to bear in mind.
>
> 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.
>
> The <doc> information does not need to be repeated on every
> <element> and <property> for a particular feature.
>
> Does the verbosity really matter?
>
> > ... 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.
>
> > > 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.
>

In both cases, the description and required flag should be controlled by
the skin, not the skinconf.  The skinconf should only have
feature/element/property and property should only have @name and a value.
I suggest having a skin definition (or declaration) file which would
consist of the <doc> elements from 5 or everything except from 6a except
the value of properties.  This seperates the skin's concerns (which
changer per skin version) with the skinconf's concerns (which of course
change per project, but notably do not have to be updated when a new skin
version adds optional properties).

I slightly prefer 6a over 5 because the skindef and skinconf structures
would be the same, except for attributes.  See below why I don't like 6b.

To elaborate on a skindef, we would have one per skin which defined
skin-specific properties and a general skindef which would define
properties which are common to many skins.  Probably everything we have
now would go into the common skindef.

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

I concur.  Pure XML would be better.

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

-- 
Dave Brondsema : dave@brondsema.net
http://www.brondsema.net : personal
http://www.splike.com : programming
http://csx.calvin.edu : student org

Mime
View raw message