forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Nicola Ken Barozzi <nicola...@apache.org>
Subject Re: skinconf versioning (Was: svn commit: rev 10172)
Date Fri, 23 Apr 2004 10:23:34 GMT
David Crossley wrote:
> Nicola Ken Barozzi wrote:
> 
>>The fact is that somehow I was still getting errors in the logs
>>about a missing DTD, so I got irritated and took them away.
>>Ok, so this is not a technical reason,
> 
> Can't you just ignore the "error" until we get time to fix it. :-)

It seems that I can't get the SVG logos to render with it, don't ask me 
why, I didn't investigate ;-)

>>...but the more I think of it, the more it seems to make 
>>sense. Do property files have a DTD? Do they need one?
> 
> Well i think that they do. I have never been able to understand
> how haphazard configuration files can ever support compatibility
> between versions.
> 
> User: Hey, my so-and-so is busted!
> Support: Er, what version of the skinconf file do you have?
> User: Shrug, dunno.
> Support: You need to add the <so-and-so> tag.
> User: What is that, how do i use it?
> Support: Oh my god, not again.

This is correct as long as we assume that Forrest breaks on invalid 
config tags. All my reasoning instead is based on the assumption that 
any config file, even only one with <skinconf/> should work. In this way 
it won't be Forrest busting, but just a feature not appearing.

>>For example, let's say that somebody makes a skin that needs some extra 
>>customization values... where do they put them? Without a DTD, they can 
>>easily add them to the skinconf file.
> 
> The skinconf-*.rng could me more lenient, allowing them to
> add extra optional stuff to their own skinconf.xml file.

But then it won't really catch errors to remove the above problem.

<skinconf>
...
    <searchseite-domain>my.org</searchseite-domain>
...
</skinconf>

The above will validate, as being lenient? It still creates problems. 
Wouldn't it be easier to just do simple xml well-formedness?

>>What are the reasons we should keep the DTD, given the above point and 
>>the problems we have been having till now (not no mention having to make 
>>users update the DTD at every change)?
> 
> One reason that i have heard, is that having a DTD declared
> for the skinconf.xml file enables people to use their favourite
> XML editor.
> 
> I think that we are getting into this bind because we do not
> release Forrest often enough. The contracts with users via
> releases are too lax.

Or maybe the current tag-specifies-a-function format is not the solution.

Maybe something like:

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

> Dave Brondsema wrote:
> 
>>The only users that have to update their DTDs frequently are people keeping up
>>with SVN.  And in that case the DTD will make sure they keep up to date with any
>>changes.
> 
> As users, we all need to keep our skinconf.xml files up-to-date
> anyway, so with or without a DTD, user-level changes need to be made. 

Currently there is an auto-update for skinconf directly in the pipeline...

>>I'm ok without a DTD so long as we replace it with a (web) document that lists
>>and explains each element & attribute.  It should be up-to-date all the time for
>>both the latest release and current SVN.
>>
>>And a [headsup] email to forrest-dev for any change to the skinconf that isn't
>>backwards compatable. 
> 
> It will be impossible to manually document the many different
> versions of the evolving skinconf structure.
> 
> If we had a series of well-defined schema, then we have tools
> to automatically generate web-page documentation from them.
> 
> I think that it is very important to have well-defined structure
> for this file and to validate it before proceeding with the build.
> If we don't control it, then i think we would descend into chaos.

I don't agree, as we can't say that forrest.properties has gotten intop 
caos.

> Would this procedure be okay ...
> 
> * Use a versioned namespace in the skinconf.xml
> 
> * Do not declare a DTD in the skinconf.xml
> 
> * Define a RELAX NG grammar with separate filename for
> each substantial change.
> 
> * Document each change in status.xml
> 
> * Release Forrest more often.
> 
> * Generate a DTD from each RNG. Generate html doco too.
> 
> * Users can insert a DTD declaration into their skinconf.xml
> if they want to (or configure their xml editor in some other way).
> 
> * The Forrest build system strips any DTD declaration from the
> file before using it, so that the parser does not trip up on it.
> Is this really needed?
> 
> * The Forrest build system uses the relaxng/schematron to
> validate the skinconf.xml - Jing can evidently respond to the
> namespace to apply the correct schema.
> 
> * Add some build targets to automate skinconf upgrade.

All of this seems really too complex.

Let's say instead:

* Forrest should work also without any skinconf element

* there is a simple DTD used as a structure

* features are listed in a doc file that is generated from the comments 
put in the fresh-site skinconf.xml

* any update to the skinconf that changes feature names will be included 
in the general skinconf pipeline xsl

WDYT?

> * Release Forrest more often.

+1

-- 
Nicola Ken Barozzi                   nicolaken@apache.org
             - verba volant, scripta manent -
    (discussions get forgotten, just code remains)
---------------------------------------------------------------------


Mime
View raw message