[Config4gnu-developer] Re: XML specification (1st draft)

[Justin Y. <ju...@sk...>]

On Sat, 2002-10-26 at 13:54, Jason Long wrote:
> Justin
> 
> Attached is an attempt to clearly document the XML that is used to
> communicate between the parsers and the Config4GNU system. It is not even
> close to being set in stone; I already have things I want to change about it
> :). But I send it for your information and feedback.
> 
> It has a few diagrams with it so I attach it as a tarball. It is in Docbook
> format, but I included the HTML as well.

As requested, some feedback (in the order things appear in the file). 
If you want, I can update these things in the sgml (or just the ones you
agree with), or whatever.  Once I get your response, I can add it to the
website source tree & make it live (unless you want to?).

Your hierarchy in Figure 1 shows "localhost" as the top node in the xml
structure.  At this point, that is no problem, but what about if/when
remote administration is possible?  I submit that we should have a node
at least 1 (or even 2 to allow for hosts to be grouped?) levels above
localhost to allow room for this.  Granted, I'm not sure whether that
would even matter since our solutions seem pretty general, but we should
at least allow room in the code/spec for these levels to be added
later.  Appears from the source tree you're doing this to some extent.

In Example 2:  I'm unsure of your reasoning for the <inifile> and
<inisection> tags.  I suggest that inisection should be generalized to
section so frontends don't need to worry about whether something is
section, inisection, apachesection, colonsection, etc.  I'm looking
through the source tree, perhaps this is handled more easily than I'm
thinking it can be...  I'm still wondering whether or not this is an
unnecessary distinction.  I do agree w/ your use of <inifile> and
similar though, I assume in your config4gnu.xml you're over-riding the
read & write command default values for testing purposes, very nice.

Regarding sub-tags of Properties:

They should have the 3 you mentioned, whitespace, comment, value.  They
should also have rightcomment (if we're still allowing those). 
Whitespace *must* be inside a CDATA (since otherwise "whitespace" is
ignored by most/all xml parsers, making the tag useless)  Comments, I
suggest, also should always be in CDATAs for uniformity as for
multi-line comments, the linebreaks would be lost upon unparsing. 
Values should also be in CDATAs all the time for the same reasons,
although I admit I can't think of a situation off hand where a value has
whitespace in it, but I'm sure they do somewhere.

I can't think of a situation where multiple whitespace or comment tags
are needed, so I think only allowing 1 is safe.

Some additional properties I believe may be important to leave room for
at this point.  Some of these are just ideas, I'm not sure how I feel
about them:

- <default>, the default value of a node.  This need not be specified on
*each* property since it could be inherited, but in most cases it would
be specified.  This might be difficult to handle, but its important. 
Widgets could then display the default value in a greyed out text,
indicating that the value isn't explicitly set, but only set by
default.  Such a <property> could have a <default> sub-node but not a
<value> sub-node, and still make sense.  Either the unparser or the
middle layer would be responsible for ignoring <property> tags w/o an
explicitly set value, so that this doesn't break things.

- <doc>, distro/vendor/etc supplied documentation on the property (this
should also exist for other node types!).  It should be in HTML format,
since both a web-based client and a GUI can easily display HTML.  For
other formats, it can be converted to plain text, if it is displayed.

- <man>, any relevant information from a manual page.  This data would
ideally be automatically collected by a man page parser (Samba has a
great manpage for smb.conf that would allow this).

- <type>, the type of the property (to tell which widget/validation for
the front end to use), be it IP, Text, Integer, Color, etc. or maybe
even a special type such as User which would lookup data from another
section of the XML to create an appropriate widget.

- <required> 0 or 1, whether it must be set to a non-empty value

- <excludedby> would contain subnode(s) indicating which other
parameters (or values of parameters) preclude this parameter having any
usefulness or being allowed to be set.  An example (from samba of
course) is that if load printers is set to no/false, then setting the
value of the printing parameter is silly.  This would allow front ends
to say either "Sorry, you can't set this property because property XXX
is set to AAA", or "In order for this property to be meaningful, you
must set property XXX to AAA, shall I do this for you?"  Maybe this
would make more sense being separated into <excludedby> and <needs> to
break it into the two slightly different types of conditions.

- <permissions> This might make more sense to apply to sections, not
parameters, although both would probably be better.  This tag won't be
used any time in the conceivable future.

- <name> This could be used to replace the current <property
name="blah"> convention.  Instead the name="blah" would specify that the
node is to be *displayed* as blah, whereas its real name in the config
file would be in the <name> tag.  I'm thinking this would be good for
things like the /etc/modules.conf where each node is (or may) be the
same thing in the config file, but they should be displayed
differently.  I'm not sure if that makes sense.

- <displayname> This is similar to <name>, and mostly just a slightly
different idea.  Instead of the name="blah" inside the actual <property>
tag, just get rid of it altogether and have a name tag be the real name
in the config file and displayname be the name it is displayed to be in
the tree and/or in the list of properties.  This could (there are other
ways to do it) help allow for internationalization.  

A lot of these tags would *not* be created by the config file parsers. 
Some, such as required, needs, excludes, & default could be added by the
middle layer based on meta-config files.  Things like <man> tags would
be included by merging the output of parse.ini.pl /etc/samba/smb.conf
with the output of parse.man.pl smb.conf

I suggest that just as the middle layer would be responsible for merging
in the docs & default values as the XML travels from the back to the
front ends, it would also be responsible for merging out anything which
the unparser isn't supposed to know about or would make the unparsing
process needlessly complicated.  The unparsers should have to worry
about as little as possible, since they may be written in a slower
language and plus this makes them easier to write and less prone to
errors in the way they handle those things.

Just some thoughts.

Justin

-- 
SkiingYAC.com
Custom Solutions
su...@sk...
http://www.SkiingYAC.com