forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From David Crossley <cross...@apache.org>
Subject Re: [DEVOTE] Solving the skinconf riddle
Date Sat, 01 May 2004 04:24:29 GMT
Nicola Ken Barozzi wrote:
> David Crossley wrote:
> > I think that the main point is to make it easy for users
> > to configure it and easy to maintain between versions of Forrest.
> ...
> >>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.
> > 
> > It is very interesting to note the discussion on the cocoon-users
> > saying that xml editors utilise RELAX NG now.
> 
> That's cool, especially for the future XHTML2 that has only a RelaxNG 
> schema ATM.
> 
> ...
> >>Proposal 2 (From Nicola Ken)
> ...
> >>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>
> ...
> > I do like this very simple schema. The internal DTD allows
> > some basic structural validation by all xml editors. I presume
> > that we can then do various RELAX NG validations of the content,
> > ensure certain attributes, etc. 
> 
> Yes.
> 
> > This is good because it separates
> > the concerns (validation of structure and validation of content).
> > 
> > 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. 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.

> >>Proposal 3 (From Nicola Ken trying to mix Cheche's suggestions )
> >>-----------------------------------------------------------------
> ...
> >>- Make it loadable by XmlProperty
> > 
> > This sounds important. Does that mean that we can get away
> > from the need to use the document() function via XSLT?
> > Do Proposal 1 and Proposal 2 still need to use document() ?
> 
> No, it's a different issue. In the copyless branch, and IIUC in teh 
> trunk now too with Juan's backport, we lamost don't need the document() 
> function anymore :-)
> 
> > What is the difference that makes it "loadable by XmlProperty"?
> 
> That the Ant XmlProperty task can load it and use it for the build if 
> necessary (currently it is, although it should go away too as a 
> requirement in the future).
> 
> > Is it because it has definite names for elements as opposed
> > to Proposal 2?
>
> It's because XmlProperty does not use a catalog and fails to load DTDzed 
> docs.

Ah, so a deficiency in Ant then.

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

> How about the comment section?
> 
>    ---
>    |1|
>    ---
> 
>    <!-- 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>
> 
>    ---
>    |2|
>    ---
> 
>    <!-- nicolaken: second simpler possible version of the comments -->
> 
>    <xs:descr>Do we want to disable the PDF link?</xs:descr>
> 
> 
>    ---
>    |3|
>    ---
> 
>    <!-- nicolaken: third 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>
> 
> 
>    ---
>    |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.

Perhaps even RELAX NG grammars can be generated from the
skinconf.xml files.

--David



Mime
View raw message