[PATCH] XML Policy

[Frans Englich]

On Tuesday 22 February 2005 21:45, Adriaan de Groot wrote:
> On Tue, 22 Feb 2005, Frans Englich wrote:
> > On Tuesday 22 February 2005 00:49, Jason Keirstead wrote:
> >> On February 21, 2005 06:50 pm, Cornelius Schumacher wrote:
> >>> It contains formalities (e.g. the RFC references), but not much content
> >>> than some made-up rules (e.g. the capitalization rules for tag names or
> >>> the requirement of an XML Schema).
>
> Frans, you've clearly put an effort into this,

And that's no problem(but everyone would say that). 

This is about that I have an interest in bringing out more of KDE's implicit 
rules to a larger audience. I see a need for documentation in KDE.

<snip>

> but you seem to have gone totally gonzo overboard with the
> expression of the guidelines. We're not the ISO, we can be informal
> sometimes. 

And this I have surely learned for the next time; it will be no RFC 
references, and look much more informal. Because that was what made this 
being called ISO, "specification", etc.

If we look at the content, it just says "should" and "recommended" most of the 
time. It's not a big deal. If I had suggested to commit the content in a way 
similar to "Common Programming Mistakes", it would have achieved the same 
practical result, but without this policy paranoia. 

As said before and what Waldo also hinted; we really should rename this 
"policy" concept to something else, otherwise it will be too much friction 
when we want to commit documentation which simply is informative and sensible 
suggestions.

This is about documenting what we do. Such that my intent is clear: what I 
probably will do in the future is markup kdelibs/NAMING(unchanged) as a 
policy, for the only reason of making it more visible and easier to find, 
such that it's not necessary to go hunting in our repository or bugging 
people with private mails to find out how things are done.

> Let me summarize your 10k
> document:
>
> - XML documents should have a schema
> - This schema should have a URI in www.kde.org/standards/
> - The schema should follow the same camelCaps style as our C++ code
>
> Did I miss anything there?
>

<snip>
> - When designing new XML file formats for KDE, keep these rules in mind.
> Existing formats don't always follow them, but we can put a little effort
> into bending them to these rules.

No, nothing missed except the schema design suggestions(similar to how to keep 
BC in ABIs). AFAICT, what it now have become is: "See how little this is. 
It's obvious. Who needs it?". 

And when the RFC reference is removed, and the tag coding too(no way a 
consensus will be reached), it will be even smaller.

Have you forgotten how even the smallest comments in incomprehensible code are 
found like small pieces of gold? Yes, it matters; I don't see things as 
obvious, or that something can be too small for being documented, I want to 
make it dead easy for newbies and companies to interface with KDE.

Also, look at it from a broader perspective. XML is central no matter where; 
and there's plenty of activity in kdenonbeta/kdom and related. In a timespan 
just a bit bigger than stretching to right now, it can be a good idea to have 
things like this in place.

I won't push this further. No one have explained what harm it does to document 
how namespaces should look, or list schema-design suggestion. But if the doc 
still is the lague after the RFC ref. is removed as well as the coding style, 
then that is the end result of this discussion.


Cheers,

		Frans

1.
http://developer.kde.org/documentation/other/mistakes.html