Return-Path: 
 <forrest-dev-return-9953-apmail-xml-forrest-dev-archive=xml.apache.org@xml.apache.org>
Delivered-To: apmail-xml-forrest-dev-archive@www.apache.org
Received: (qmail 64604 invoked from network); 3 May 2004 07:04:17 -0000
Received: from daedalus.apache.org (HELO mail.apache.org) (208.185.179.12)
  by minotaur-2.apache.org with SMTP; 3 May 2004 07:04:17 -0000
Received: (qmail 96699 invoked by uid 500); 3 May 2004 07:03:52 -0000
Delivered-To: apmail-xml-forrest-dev-archive@xml.apache.org
Received: (qmail 96659 invoked by uid 500); 3 May 2004 07:03:52 -0000
Mailing-List: contact forrest-dev-help@xml.apache.org; run by ezmlm
Precedence: bulk
list-help: <mailto:forrest-dev-help@xml.apache.org>
list-unsubscribe: <mailto:forrest-dev-unsubscribe@xml.apache.org>
list-post: <mailto:forrest-dev@xml.apache.org>
Reply-To: forrest-dev@xml.apache.org
Delivered-To: mailing list forrest-dev@xml.apache.org
Received: (qmail 96645 invoked from network); 3 May 2004 07:03:51 -0000
Received: from unknown (HELO indexgeo.net) (65.77.211.93)
  by daedalus.apache.org with SMTP; 3 May 2004 07:03:51 -0000
Received: from dialup-163.146.220.203.acc01-aubu-gou.comindico.com.au
 (dialup-163.146.220.203.acc01-aubu-gou.comindico.com.au [203.220.146.163])
	(authenticated bits=0)
	by www2.kc.aoindustries.com (8.12.9-20030917/8.12.9) with ESMTP id
 i4373nKc019257
	for <forrest-dev@xml.apache.org>; Mon, 3 May 2004 02:04:01 -0500
Subject: Re: [DEVOTE] Solving the skinconf riddle
From: David Crossley <crossley@apache.org>
To: forrest-dev@xml.apache.org
In-Reply-To: <c73osu$2p9$1@sea.gmane.org>
References: <c6oa7i$iqf$1@sea.gmane.org> <1083323942.2035.162.camel@ighp>
	 <c6tl6s$9mm$1@sea.gmane.org> <1083385469.5609.92.camel@ighp>
	 <c73osu$2p9$1@sea.gmane.org>
Content-Type: text/plain
Organization: 
Message-Id: <1083567826.31080.225.camel@ighp>
Mime-Version: 1.0
X-Mailer: Ximian Evolution 1.2.2 (1.2.2-5) 
Date: 03 May 2004 17:03:48 +1000
Content-Transfer-Encoding: 7bit
X-Spam-Rating: daedalus.apache.org 1.6.2 0/1000/N
X-Spam-Rating: minotaur-2.apache.org 1.6.2 0/1000/N

Nicola Ken Barozzi wrote: 
> 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 :-)

Yes, opensource is wonderful. Nobody owns the ideas, they just evolve.

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

I was trying to stay away from multiple namespaces for this task
because that means that we cannot have the simple DTD.

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

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

This is back to the multiple namespaces which means that we
cannot have the simple internal DTD.

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

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.

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.

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

--David