You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by David Crossley <cr...@apache.org> on 2004/05/01 06:24:29 UTC
Re: [DEVOTE] Solving the skinconf riddle
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
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
David Crossley wrote:
> I tried to apply the new format to the content of the
> current "fresh-site" skinconf.xml and attached the file
> http://issues.cocoondev.org/jira/secure/ViewIssue.jspa?key=FOR-144
>
> Time expired before i could complete it. There are still
> some difficult ones remaining: colors, extra-css, pdf.
first try...
<feature name="extra-css">
<!-- extra css here -->
</feature>
<feature name="colors">
<element>
<property name="header">#294563</property>
<property name="tab-selected">#294563</property>
<property name="tab-selected-link">#0F3660</property>
<property name="tab-selected-vlink">#0F3660</property>
<property name="tab-selected-hlink">#0F3660</property>
<property name="tab-unselected">#294563</property>
...etc
</element>
</feature>
<feature name="pdf">
<element>
<property name="page-size">#letter</property>
<property name="page-orientation">portrait</property>
<property name="margins-double-sided">false</property>
<property name="margins-top">lin</property>
<property name="margins-bottom">lin</property>
<property name="margins-inner">1.25in</property>
<property name="margins-outer">lin</property>
</element>
</feature>
On second thought though, maybe keeping with the structure and adding
names to elements is better:
<feature name="extra-css">
<element>
<property name="contents">
<!-- extra css here -->
</property>
</element>
</feature>
<feature name="colors">
<element name="header">
^^^^^^^
<property name="color">#294563</property>
</element>
<element name="tab-selected">
^^^^^^^
<property name="color">#294563</property>
<property name="link">#0F3660</property>
<property name="vlink">#0F3660</property>
<property name="hlink">#0F3660</property>
</element>
<element name="tab-unselected">
^^^^^^^
<property name="color">#294563</property>
</element>
<!-- etc -->
</feature>
<feature name="pdf">
<element name="page">
<property name="size">#letter</property>
<property name="orientation">portrait</property>
</element>
<element name="margins">
<property name="double-sided">false</property>
<property name="top">lin</property>
<property name="bottom">lin</property>
<property name="inner">1.25in</property>
<property name="outer">lin</property>
</element>
</feature>
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [DEVOTE] Solving the skinconf riddle
Posted by David Crossley <cr...@apache.org>.
I tried to apply the new format to the content of the
current "fresh-site" skinconf.xml and attached the file
http://issues.cocoondev.org/jira/secure/ViewIssue.jspa?key=FOR-144
Time expired before i could complete it. There are still
some difficult ones remaining: colors, extra-css, pdf.
--David
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Dave Brondsema wrote:
> On Tue, 5 May 2004, David Crossley wrote:
>
>>Nicola Ken Barozzi wrote:
>>
>>>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.
>>
>>Great, this sounds like we have a solution then.
>
> AFAICT, you guys have been talking about maintaining the skinconf in
> forrest seed site, right?
No, after your mail we realized that it was not the only thing needed.
> How will 3rd party skins declare their features?
"
>>>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"."
> How will changes to the forrest skins (e.g., new optional
> features) get reflected in existing projects?
skinconf.xsl now add default values if needed, but with this proposal
these values will be in the skin's skinconf.xml.
> I think we need to seperate
> the concerns of configuring the skin (per project in skinconf) and skin's
> documentation/declaration (per skin in a skindef file).
>
> Please see my earlier email in this thread for more details.
Already done :-)
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [DEVOTE] Solving the skinconf riddle
Posted by Dave Brondsema <da...@brondsema.net>.
On Tue, 5 May 2004, David Crossley wrote:
> Nicola Ken Barozzi wrote:
> >
> > 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.
>
> Great, this sounds like we have a solution then.
>
AFAICT, you guys have been talking about maintaining the skinconf in
forrest seed site, right? How will 3rd party skins declare their
features? How will changes to the forrest skins (e.g., new optional
features) get reflected in existing projects? I think we need to seperate
the concerns of configuring the skin (per project in skinconf) and skin's
documentation/declaration (per skin in a skindef file).
Please see my earlier email in this thread for more details.
--
Dave Brondsema : dave@brondsema.net
http://www.brondsema.net : personal
http://www.splike.com : programming
http://csx.calvin.edu : student org
Re: [DEVOTE] Solving the skinconf riddle
Posted by David Crossley <cr...@apache.org>.
Nicola Ken Barozzi wrote:
>
> 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.
Great, this sounds like we have a solution then.
--David
Re: [DEVOTE] Solving the skinconf riddle
Posted by Dave Brondsema <da...@brondsema.net>.
Quoting David Crossley <cr...@apache.org>:
> Nicola Ken Barozzi wrote:
> > David Crossley wrote:
> > > Nicola Ken Barozzi wrote:
> > >
> > >>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.
> > >
> > >
> > > I too am confused as to how it hangs together. Is this it? ...
> > >
> > > Each skin has a skinconf.xml (or is that skindef.xml) which is
> > > managed by the skin creator people, not the users. It has the
> > > documentation comments and the "@required" comments and has
> > > all possible features.
> >
> > Correct.
> >
> > > There is a build task that generates certain files from that:
> > > * skinconf.xsl which injects default values
> >
> > This is to be done in the sitemap IMHO, no build-time stuff.
>
> You are right. My discussion points were more intended to define
> what was generated rather than how or when.
>
> > > * skinconf-vXY.rng which enables validation of users' skinconf.xml
> >
> > Correct. Validation is a build-time task, so it there is no issue in
> > having it generated at that point.
> >
> > > * skinconf.xml which is an example file for users to apply
> > > to their project skinconf.xml if they need to over-ride or
> > > disable certain features.
> >
> > Hmmm, I was thinking instead of including a page in the Forrest docs
> > with the documentation and an example version for cut-and-paste.
>
> That too. It would also be good to have an actual xml file
> that people can diff with their project skinconf.xml
>
> Okay, it seems that we are on the same wavelength.
>
> What is the next step?
>
> --David
>
Make a branch and start doing it? :-)
--
Dave Brondsema : dave@brondsema.net
http://www.brondsema.net : personal
http://www.splike.com : programming
http://csx.calvin.edu : student org
Re: [DEVOTE] Solving the skinconf riddle
Posted by David Crossley <cr...@apache.org>.
Nicola Ken Barozzi wrote:
> David Crossley wrote:
> > Nicola Ken Barozzi wrote:
> >
> >>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.
> >
> >
> > I too am confused as to how it hangs together. Is this it? ...
> >
> > Each skin has a skinconf.xml (or is that skindef.xml) which is
> > managed by the skin creator people, not the users. It has the
> > documentation comments and the "@required" comments and has
> > all possible features.
>
> Correct.
>
> > There is a build task that generates certain files from that:
> > * skinconf.xsl which injects default values
>
> This is to be done in the sitemap IMHO, no build-time stuff.
You are right. My discussion points were more intended to define
what was generated rather than how or when.
> > * skinconf-vXY.rng which enables validation of users' skinconf.xml
>
> Correct. Validation is a build-time task, so it there is no issue in
> having it generated at that point.
>
> > * skinconf.xml which is an example file for users to apply
> > to their project skinconf.xml if they need to over-ride or
> > disable certain features.
>
> Hmmm, I was thinking instead of including a page in the Forrest docs
> with the documentation and an example version for cut-and-paste.
That too. It would also be good to have an actual xml file
that people can diff with their project skinconf.xml
Okay, it seems that we are on the same wavelength.
What is the next step?
--David
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
David Crossley wrote:
> Dave Brondsema wrote:
>
>>Will each skin's skinconf include all the features it uses? Or will we have a
>>skinconf for the 'common' skin which includes the features that pretty much all
>>skins use? And then each skin's skinconf would only include additional features.
>
> Aha, i like the latter. That issue was bothering me too.
Hmmm, I'm not so sure. I mean, what if we add some value? The skin would
not use them, but still seem as if it does... I would actually make
every skin declare every tag it uses, especially now that we are making
features optional.
> Also, perhaps a skin could over-ride a "common" feature.
This is any case.
...
>>
>>What is the next step?
>
> Make a branch and start doing it? :-)
What about: finishing off the copyless branch bugs, merging with trunk,
then barnching again for this, and releaseing the trunk ASAP?
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [DEVOTE] Solving the skinconf riddle
Posted by David Crossley <cr...@apache.org>.
Dave Brondsema wrote:
>
> Will each skin's skinconf include all the features it uses? Or will we have a
> skinconf for the 'common' skin which includes the features that pretty much all
> skins use? And then each skin's skinconf would only include additional features.
Aha, i like the latter. That issue was bothering me too.
Also, perhaps a skin could over-ride a "common" feature.
--David
Re: [DEVOTE] Solving the skinconf riddle
Posted by Dave Brondsema <da...@brondsema.net>.
Quoting Nicola Ken Barozzi <ni...@apache.org>:
> David Crossley wrote:
>
> > Nicola Ken Barozzi wrote:
> >
> >>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.
> >
> >
> > I too am confused as to how it hangs together. Is this it? ...
> >
> > Each skin has a skinconf.xml (or is that skindef.xml) which is
> > managed by the skin creator people, not the users. It has the
> > documentation comments and the "@required" comments and has
> > all possible features.
>
> Correct.
>
Will each skin's skinconf include all the features it uses? Or will we have a
skinconf for the 'common' skin which includes the features that pretty much all
skins use? And then each skin's skinconf would only include additional features.
--
Dave Brondsema : dave@brondsema.net
http://www.brondsema.net : personal
http://www.splike.com : programming
http://csx.calvin.edu : student org
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
David Crossley wrote:
> Nicola Ken Barozzi wrote:
>
>>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.
>
>
> I too am confused as to how it hangs together. Is this it? ...
>
> Each skin has a skinconf.xml (or is that skindef.xml) which is
> managed by the skin creator people, not the users. It has the
> documentation comments and the "@required" comments and has
> all possible features.
Correct.
> There is a build task that generates certain files from that:
> * skinconf.xsl which injects default values
This is to be done in the sitemap IMHO, no build-time stuff.
> * skinconf-vXY.rng which enables validation of users' skinconf.xml
Correct. Validation is a build-time task, so it there is no issue in
having it generated at that point.
> * skinconf.xml which is an example file for users to apply
> to their project skinconf.xml if they need to over-ride or
> disable certain features.
Hmmm, I was thinking instead of including a page in the Forrest docs
with the documentation and an example version for cut-and-paste.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [DEVOTE] Solving the skinconf riddle
Posted by David Crossley <cr...@apache.org>.
Nicola Ken Barozzi wrote:
>
> 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.
I too am confused as to how it hangs together. Is this it? ...
Each skin has a skinconf.xml (or is that skindef.xml) which is
managed by the skin creator people, not the users. It has the
documentation comments and the "@required" comments and has
all possible features.
There is a build task that generates certain files from that:
* skinconf.xsl which injects default values
* skinconf-vXY.rng which enables validation of users' skinconf.xml
* skinconf.xml which is an example file for users to apply
to their project skinconf.xml if they need to over-ride or
disable certain features.
Is that how it will work or am i off-track?
--David
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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)
---------------------------------------------------------------------
Re: [DEVOTE] Solving the skinconf riddle
Posted by Dave Brondsema <da...@brondsema.net>.
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
Re: [DEVOTE] Solving the skinconf riddle
Posted by David Crossley <cr...@apache.org>.
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
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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)
---------------------------------------------------------------------