You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@forrest.apache.org by Nicola Ken Barozzi <ni...@apache.org> on 2004/04/28 15:05:37 UTC
[DEVOTE] Solving the skinconf riddle
What has happened AFAIK is that in the middle of a vote in which it
seemed that there was consensus, Juan has argumented strongly for his
position, and this has brought us to come up with at least two other
solutions.
As David has correctly noted, we should try to reconcile them in a final
decision. If there are other proposals to be made please add them now,
but please let's also refrain from commenting for at least a day, so we
have time to think these over a bit.
As a summary, the point of discussion is over validation or not, and how
to do it. 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.
The proposal are as follows:
Proposal 1 (From Cheche)
--------------------------
Historically the skinconf file has hold the document type definition
(DTD) within the same file. This DTD ensure that the xml nodes are
correct with that definition.
This lead of problems when this definition is updated, so some of us,
have put some effort to move out the DTD and replace with a public
reference:
<!DOCTYPE skinconfig PUBLIC
"-//APACHE//DTD Skin Configuration V0.6//EN"
"skinconfig-v06.dtd">
It can be used by xml editors to identity elements and attribute for
this file.
The problem with this public reference it that relays on a internet
connection, but for that issue we have the "Catalog Entity Resolver for
local DTDs" http://xml.apache.org/forrest/catalog.html
With this, all these xml editors knows how to tread the skinconf.xml file.
Proposal 2 (From Nicola Ken)
-----------
The latest happenings on skinconf have brought me to consider a format
for skinconf.xml.
Here is the proposal:
* Forrest should work also without any skinconf element: skinconf
elements are just hints, that a skin can decide not to follow
(as it happens already actually, just that the DTD makes people think
that Forrest will necessarily honor all hints)
* there is a simple DTD used as a structure (see below)
* features are listed in a doc file that is generated from the comments
put in the fresh-site skinconf.xml (an example of the possible
formats is included in proposal 3)
* any update to the skinconf that changes feature names will be included
in the general skinconf pipeline xsl
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>
<feature name="lucene" value="false"/>
<feature name="search" value="true">
<property name="domain">xml.apache.org</property>
<property name="name">Apache XML</property>
</feature>
...
<feature name="obfuscate-mail-links" value="true"/>
...
<!-- -->
<feature name="credits" value="true"/>
<element>
<property name="name">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>
<property name="name">...</property
<property name="url">...</property >
<property name="image">...</property >
<property name="width">...</property >
<property name="height">...</property >
</element>
...
</feature>
</skinconfig>
In this way we get lax and extensible elements but reasonable editing.
The DTD will not change, so we can easily inline it in the XML, thus
making it trivial for validating editors to validate it (no catalogs to
set).
In this way we will have a simple skinconf DTD, that is both extensible
and formally validated.
Proposal 3 (From Nicola Ken trying to mix Cheche's suggestions )
-----------------------------------------------------------------
- Add the forrest skinconf namespace
- Remove DTD
- use only RelaxNG validation for it, with no tag required
- add the injections of default tags in the skinconf pipeline
for the ones that skins requires
This should:
- Keep it extensible by namespacing
- Keep the stylesheets as are now
- Keep validation (as RelaxNG IIRC runs on namespaces)
- Make it loadable by XmlProperty
Here is an example of it:
<skin:skinconfig xmlns:skin="http://apache.org/forrest/skinconf/1.0"
xmlns:xd="http://apache.org/forrest/xd/1.0"
xmlns:myns"http://mydomain.org/myproject/xmyns/1.0">
<!-- 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>
<skin:search name="MyProject" domain="mydomain"/>
<!-- nicolaken: second simpler possible version of the comments -->
<xd:descr>Do we want to disable the print link? If enabled,
invalid HTML 4.0.1</xd:descr>
<skin:disable-print-link>true</skin:disable-print-link>
<xs:descr>Do we want to disable the PDF link?</xs:descr>
<skin:disable-pdf-link>false</skin:disable-pdf-link>
...
<!-- nicolaken: third type of possible documentation-->
<!-- project logo, skin: forrest-site renders it at the
top -->
<skin:project-name>MyProject</skin:project-name>
<skin:project-description>MyProject Descr</skin:project-description>
<skin:project-url>http://myproj.mygroup.org/</skin:project-url>
<skin:project-logo>images/project.png</skin:project-logo>
...
<!-- nicolaken: last 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>
</skinconfig>
Note that the docs could in the future be also mixed woth the
information of the RelaxNG schema that shows also teh possible formal
values that it can contain.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
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)
---------------------------------------------------------------------
Re: [DEVOTE] Solving the skinconf riddle
Posted by David Crossley <cr...@apache.org>.
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>.
Nicola Ken Barozzi wrote:
...
> ---
> |3|
> ---
>
> <!-- nicolaken: third type of possible documentation, the
> one I tend to prefer -->
I actually prefer comment version 4.
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
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).
>>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.
>>Here is an example of it:
>>
>><skin:skinconfig xmlns:skin="http://apache.org/forrest/skinconf/1.0"
>> xmlns:xd="http://apache.org/forrest/xd/1.0"
>> xmlns:myns"http://mydomain.org/myproject/xmyns/1.0">
>>
>> <!-- 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>
>> <skin:search name="MyProject" domain="mydomain"/>
>>
>> <!-- nicolaken: second simpler possible version of the comments -->
>> <xd:descr>Do we want to disable the print link? If enabled,
>> invalid HTML 4.0.1</xd:descr>
>> <skin:disable-print-link>true</skin:disable-print-link>
>
> <snip/>
>
> --------
> 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>
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):
<?xml version="1.0"?>
<xsl:stylesheet version="1.0"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="comment()">
<xsl:choose>
<xsl:when test="starts-with(.,'**')">
<comment>
<xsl:value-of select="substring-after(.,'**')" />
</comment>
</xsl:when>
<xsl:when test="starts-with(.,'@')">
<attribute>
<xsl:attribute name = "name" >
<xsl:value-of
select="normalize-space(substring-before(substring-after(.,'@'),' '))" />
</xsl:attribute>
<xsl:value-of
select="normalize-space(substring-after(substring-after(.,'@'),' '))" />
</attribute>
</xsl:when>
<xsl:otherwise>
<xsl:copy>
<xsl:apply-templates select="comment()"/>
</xsl:copy>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!-- Identity transformation template except comments-->
<xsl:template match="/ | @* | * | processing-instruction() | text()">
<xsl:copy>
<xsl:apply-templates select="@* | * | comment() |
processing-instruction() | text()"/>
</xsl:copy>
</xsl:template>
</xsl:stylesheet>
--
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 am still having trouble deciding which way to go,
so making some comments and asking some more questions ...
Nicola Ken Barozzi wrote:
> As a summary, the point of discussion is over validation or not, and how
> to do it.
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.
> The proposal are as follows:
>
> Proposal 1 (From Cheche)
> --------------------------
>
> Historically the skinconf file has hold the document type definition
> (DTD) within the same file. This DTD ensure that the xml nodes are
> correct with that definition.
> This lead of problems when this definition is updated, so some of us,
> have put some effort to move out the DTD and replace with a public
> reference:
>
> <!DOCTYPE skinconfig PUBLIC
> "-//APACHE//DTD Skin Configuration V0.6//EN"
> "skinconfig-v06.dtd">
>
> It can be used by xml editors to identity elements and attribute for
> this file.
>
> The problem with this public reference it that relays on a internet
> connection, but for that issue we have the "Catalog Entity Resolver for
> local DTDs" http://xml.apache.org/forrest/catalog.html
>
> With this, all these xml editors knows how to tread the skinconf.xml file.
I gather that the skinconf.dtd gets new version numbers for every
change and that this makes it easier for users to keep their skinconf
files up-to-date. There could even be helper transformations for
updating skinconf between versions.
The trouble is that writers of new skins cannot add special
elements for their purposes.
> Proposal 2 (From Nicola Ken)
> -----------
>
> The latest happenings on skinconf have brought me to consider a format
> for skinconf.xml.
>
> Here is the proposal:
>
> * Forrest should work also without any skinconf element: skinconf
> elements are just hints, that a skin can decide not to follow
> (as it happens already actually, just that the DTD makes people think
> that Forrest will necessarily honor all hints)
>
> * there is a simple DTD used as a structure (see below)
>
> * features are listed in a doc file that is generated from the comments
> put in the fresh-site skinconf.xml (an example of the possible
> formats is included in proposal 3)
>
> * any update to the skinconf that changes feature names will be included
> in the general skinconf pipeline xsl
>
> 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>
>
> <feature name="lucene" value="false"/>
>
> <feature name="search" value="true">
> <property name="domain">xml.apache.org</property>
> <property name="name">Apache XML</property>
> </feature>
> ...
> <feature name="obfuscate-mail-links" value="true"/>
> ...
> <!-- -->
> <feature name="credits" value="true"/>
> <element>
> <property name="name">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>
> <property name="name">...</property
> <property name="url">...</property >
> <property name="image">...</property >
> <property name="width">...</property >
> <property name="height">...</property >
> </element>
> ...
> </feature>
> </skinconfig>
>
> In this way we get lax and extensible elements but reasonable editing.
> The DTD will not change, so we can easily inline it in the XML, thus
> making it trivial for validating editors to validate it (no catalogs to
> set).
>
> In this way we will have a simple skinconf DTD, that is both extensible
> and formally validated.
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. 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.
> Proposal 3 (From Nicola Ken trying to mix Cheche's suggestions )
> -----------------------------------------------------------------
>
> - Add the forrest skinconf namespace
> - Remove DTD
> - use only RelaxNG validation for it, with no tag required
> - add the injections of default tags in the skinconf pipeline
> for the ones that skins requires
>
> This should:
>
> - Keep it extensible by namespacing
> - Keep the stylesheets as are now
> - Keep validation (as RelaxNG IIRC runs on namespaces)
I presume that future changes to skinconf then get a new
namespace ...skinconf/1.1 which enables the correct validation
to be applied.
> - 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() ?
What is the difference that makes it "loadable by XmlProperty"?
Is it because it has definite names for elements as opposed
to Proposal 2?
> Here is an example of it:
>
> <skin:skinconfig xmlns:skin="http://apache.org/forrest/skinconf/1.0"
> xmlns:xd="http://apache.org/forrest/xd/1.0"
> xmlns:myns"http://mydomain.org/myproject/xmyns/1.0">
>
> <!-- 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>
> <skin:search name="MyProject" domain="mydomain"/>
>
> <!-- nicolaken: second simpler possible version of the comments -->
> <xd:descr>Do we want to disable the print link? If enabled,
> invalid HTML 4.0.1</xd:descr>
> <skin:disable-print-link>true</skin:disable-print-link>
<snip/>
--------
Is there a Proposal 4 ... The simple feature-element-property
stuff from Proposal 2 but with multiple namespaces like Proposal 3.
--David
Re: [DEVOTE] Solving the skinconf riddle
Posted by Nicola Ken Barozzi <ni...@apache.org>.
Dave Brondsema wrote:
> We should consider a way for skins to declare what hints they honor, so users
> don't have to try enabling and disabling all possible elements to see what happens.
Gosh, you're right! Hmmm... so instead of the skinconf.xslt we can have
a skin descriptor that declares the needed tags along with their usage
and that is used for documentation and for setting the default values...
hmmm...
--
Nicola Ken Barozzi nicolaken@apache.org
- verba volant, scripta manent -
(discussions get forgotten, just code remains)
---------------------------------------------------------------------
RE: [DEVOTE] Solving the skinconf riddle
Posted by "Brian S. Hayes" <br...@comcast.net>.
> We should consider a way for skins to declare what hints they honor, so
> users
> don't have to try enabling and disabling all possible elements to see what
> happens.
What are some of your thoughts here? Are you thinking that the skin
authors/designers should provide a schema, or simply documentation? Or
something else?
/Brian
Re: [DEVOTE] Solving the skinconf riddle
Posted by Dave Brondsema <da...@brondsema.net>.
Quoting Nicola Ken Barozzi <ni...@apache.org>:
>
> Proposal 2 (From Nicola Ken)
> -----------
>
> The latest happenings on skinconf have brought me to consider a format
> for skinconf.xml.
>
> Here is the proposal:
>
> * Forrest should work also without any skinconf element: skinconf
> elements are just hints, that a skin can decide not to follow
> (as it happens already actually, just that the DTD makes people think
> that Forrest will necessarily honor all hints)
>
We should consider a way for skins to declare what hints they honor, so users
don't have to try enabling and disabling all possible elements to see what happens.
--
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 Dave Brondsema <da...@brondsema.net>.
On Wed, 28 Apr 2004, Nicola Ken Barozzi wrote:
> As a summary, the point of discussion is over validation or not, and how
> to do it.
And the format.
Extensability is a key concern and I think the two options that would
support it are
A.
DTD (or relaxng) validated skinconf in a standard feature/element/property
structure.
B.
Namespaced skinconf (only supported by relaxng, right?).
A make it easy for people to edit because it can be DTD validated and they
structure is simple and standard. Skins can also easily declare which
features/elements/properties they support and what is required and not.
The only disadvantages that I see is that we don't have per-skin
namespaces to directly show that a certain feature is specific to a
certain skin. And that everything has to fit into the
feature/element/property model. Some skins might prefer a more flexible
configuration (e.g. <footerlinks><link/>*</footerlinks> instead of
properties footerlink1 footerlink2 footerlink3 footerlink4 etc)
B This has the advantages that are disadvantages for A. Using namespaces
we directly associate features with certain skins, although then we have
an issue of when enough skins use the same feature, do we move it into the
forrest namespace? Skins can be flexible outside the
feature/element/property model. But only relaxng validation, and skin
declaration of configuration hints is probably more complicated.
I prefer A. So in summary: consistent feature/element/property format
with DTD validation.
It was mentioned that we could validate against the skin feature
declarations too. This would be good, but of course only possible within
forrest (not an editor).
--
Dave Brondsema : dave@brondsema.net
http://www.brondsema.net : personal
http://www.splike.com : programming
http://csx.calvin.edu : student org