Re: Configuration file problems

2006-09-15 Thread Jeremias Maerki
I wouldn't go that far. A proper schema validation already tells you if
you have an element in the wrong place. Besides that I guess what I want
most is that users read and interpret error messages. :-)

On 13.09.2006 20:31:03 Simon Pepping wrote:
 On Tue, Sep 12, 2006 at 09:37:20PM +0200, Jeremias Maerki wrote:
  
  On 12.09.2006 21:13:35 Simon Pepping wrote:
   Re extensibility: A XML file is validated according to the DTD or
   schema that it declares (Relax-NG is an exception). The user can put a
   DTD or schema of his own choice in the user configuration file:
   
   !DOCTYPE fop
 PUBLIC '-//MYSELF//DTD My FOP Configuration XML V1.0//EN'
  'http://myserver.mydomain.eu/fop-configuration.dtd'
   
   and the parser will validate against it. This means that a user can
   extend the configuration file at will, and that FOP cannot be assured
   that the config file is valid. Embedded users can always avoid
   validation.
  
  Yes, but you already assume a non-novice user. If our goal is to have
  less problems, fewer support requests because of configuration errors,
  we have to do it fool-proof. You can't rely on everyone putting the DTD
  or XSD on top of the configuration file. The first time the XML doesn't
  validate, people remove the schema reference.
 
 This sounds like you want to catch user errors in any case. That would
 be a custom program that applies heuristics based on knowledge of
 common user errors. For example,
 
 'Do you mean to configure font XXX? I found a font configuration
 element in a position where FOP will not pick it up.'
 
 Class UserConfigDoctor.
 
 A possibility besides Java is to do it in XSLT, in the manner of
 Schematron. Write templates for known suspect XPaths in the file, such
 as all font elements not in /*/renderers/renderer/fonts.
 
 Regards, Simon
 
 -- 
 Simon Pepping
 home page: http://www.leverkruid.eu



Jeremias Maerki



Re: Configuration file problems

2006-09-15 Thread Jeremias Maerki
Oops.

On 14.09.2006 02:23:49 Manuel Mall wrote:
snip/
 This made me look at our 'upgrading' page. It does NOT(!) mention 
 that the config file format has changed!
 
 Seems to me the easiest fix to all of this is to actually tell users 
 that they also have to change the config file used with 0.20.5 when 
 upgrading.



Jeremias Maerki



Re: Configuration file problems

2006-09-13 Thread Simon Pepping
On Tue, Sep 12, 2006 at 09:37:20PM +0200, Jeremias Maerki wrote:
 
 On 12.09.2006 21:13:35 Simon Pepping wrote:
  Re extensibility: A XML file is validated according to the DTD or
  schema that it declares (Relax-NG is an exception). The user can put a
  DTD or schema of his own choice in the user configuration file:
  
  !DOCTYPE fop
PUBLIC '-//MYSELF//DTD My FOP Configuration XML V1.0//EN'
   'http://myserver.mydomain.eu/fop-configuration.dtd'
  
  and the parser will validate against it. This means that a user can
  extend the configuration file at will, and that FOP cannot be assured
  that the config file is valid. Embedded users can always avoid
  validation.
 
 Yes, but you already assume a non-novice user. If our goal is to have
 less problems, fewer support requests because of configuration errors,
 we have to do it fool-proof. You can't rely on everyone putting the DTD
 or XSD on top of the configuration file. The first time the XML doesn't
 validate, people remove the schema reference.

This sounds like you want to catch user errors in any case. That would
be a custom program that applies heuristics based on knowledge of
common user errors. For example,

'Do you mean to configure font XXX? I found a font configuration
element in a position where FOP will not pick it up.'

Class UserConfigDoctor.

A possibility besides Java is to do it in XSLT, in the manner of
Schematron. Write templates for known suspect XPaths in the file, such
as all font elements not in /*/renderers/renderer/fonts.

Regards, Simon

-- 
Simon Pepping
home page: http://www.leverkruid.eu


Re: Configuration file problems

2006-09-13 Thread J.Pietschmann

Jeremias Maerki wrote:

Ok, I consider myself defeated concerning the way we handle the
configuration file (See recent threads on fop-users). The Avalon
configuration approach is very nice for the developer but obviously
bullshit in terms of end-user-friendlyness.


Back from vacation, a few quick thoughts:
The problem seems to be the unexperienced users who *have* to fiddle
with the config file for getting basic features working.

Possible solutions:
- Reduce the need to fiddle with config settings. Some options
  - Use conventions instead of explicit values
  - Autodetection and other rule base approaches
  This concerns probably mainly the baseStuff* settings
- Provide a GUI application for changing commonly changed settings
- Get commonly changed settings from a file with an easier format,
  like Java properties

Did I get the problem right?

J.Pietschmann


Re: Configuration file problems

2006-09-13 Thread Manuel Mall
On Thursday 14 September 2006 07:34, J.Pietschmann wrote:
 Jeremias Maerki wrote:
  Ok, I consider myself defeated concerning the way we handle the
  configuration file (See recent threads on fop-users). The Avalon
  configuration approach is very nice for the developer but obviously
  bullshit in terms of end-user-friendlyness.

 Back from vacation, a few quick thoughts:
 The problem seems to be the unexperienced users who *have* to fiddle
 with the config file for getting basic features working.

snip/
 Did I get the problem right?

I had a quick (unscientific) look at the fop-user mailing list. 
According to my count we had 3 threads in the last 2 months related to 
config issues. In all cases it was due to an upgrade from 0.20.5 to 
0.9x. This made me look at our 'upgrading' page. It does NOT(!) mention 
that the config file format has changed!

Seems to me the easiest fix to all of this is to actually tell users 
that they also have to change the config file used with 0.20.5 when 
upgrading.


 J.Pietschmann

Manuel


Re: Configuration file problems

2006-09-12 Thread Simon Pepping
Jeremias,

What is the problem you are trying to address:

1. Users use configuration files with errors which can be detected by
   the fop-configuration schema, but they do not validate it.

2. Users use configuration files with errors which cannot be detected
   by the fop-configuration schema.

Ad 1: It is perfectly possible to let fop validate the user
configuration file in a command line invocation. The problem is to
ensure that the location of the schema does not become a source of
errors in its turn. It is possible to write an Entity and URI Resolver
which looks for 'fop-configuration.xsd' along the classpath, and for
other schemas and DTDs delegates to a CatalogResolver if that is
available, and otherwise returns the absolute URI of the system or
schema location path.

Re extensibility: A XML file is validated according to the DTD or
schema that it declares (Relax-NG is an exception). The user can put a
DTD or schema of his own choice in the user configuration file:

!DOCTYPE fop
  PUBLIC '-//MYSELF//DTD My FOP Configuration XML V1.0//EN'
 'http://myserver.mydomain.eu/fop-configuration.dtd'

and the parser will validate against it. This means that a user can
extend the configuration file at will, and that FOP cannot be assured
that the config file is valid. Embedded users can always avoid
validation.

I do like Manuel's suggestion to supply a separate command line
validation option.

Note that we have not advertised the configuration schema. It is not
documented anywhere. I will add some documentation to the
configuration web page.

Ad 2: The schema cannot enforce a specific content model depending on
the type attribute. But it does a nice job limiting the
possibilities: One cannot mix and match parts of different renderer
configuration options. For example, it is perfectly possible to
configure a PostScript renderer with the elements applicable for a PDF
renderer. But it is not possible to start with a filterList, and
continue with auto-rotate-landscape.

It is possible to force the correct content model for each renderer
type by giving them different element names,
e.g. renderer-application-pdf or application-pdf for short.

Regards, Simon

On Sun, Sep 10, 2006 at 02:52:31PM +0200, Jeremias Maerki wrote:
 Ok, I consider myself defeated concerning the way we handle the
 configuration file (See recent threads on fop-users). The Avalon
 configuration approach is very nice for the developer but obviously
 bullshit in terms of end-user-friendlyness. The attempt to overlay the
 configuration layout with an XSD is generally a good idea but with the
 current configuration layout, it's not a workable solution.
 
 If anyone has a good plan to improve the situation, I'm all ears. I
 think the configuration file needs to be built based on an XML Schema
 and FOP should by default validate the configuration file (hard-coded in
 FOP) so the users get proper feedback if they try to feed FOP with an
 invalid format. But that means the XML Schema must be water-tight. On
 the other side, we will probably lose extensibility of the configuration
 file format. When someone adds his own renderer, for example, he can't
 just have his own config values because he can't change the XML Schema.
 So that may mean we probably can't use XML Schema to validate the file.
 But then, maybe we can define the individual renderer config parts as
 xsd:any or something like that and let each renderer validate its own
 configuration (either manually or using an XSD).
 
 ATM, I can't think of a good solution but apparently, we need to change
 something at some point. Any ideas, thoughts?
 
 Jeremias Maerki
 

-- 
Simon Pepping
home page: http://www.leverkruid.eu


Re: Configuration file problems

2006-09-12 Thread Jeremias Maerki

On 12.09.2006 21:13:35 Simon Pepping wrote:
 Jeremias,
 
 What is the problem you are trying to address:
 
 1. Users use configuration files with errors which can be detected by
the fop-configuration schema, but they do not validate it.
 
 2. Users use configuration files with errors which cannot be detected
by the fop-configuration schema.

Both as well as a few others. :-)

 Ad 1: It is perfectly possible to let fop validate the user
 configuration file in a command line invocation. The problem is to
 ensure that the location of the schema does not become a source of
 errors in its turn. It is possible to write an Entity and URI Resolver
 which looks for 'fop-configuration.xsd' along the classpath, and for
 other schemas and DTDs delegates to a CatalogResolver if that is
 available, and otherwise returns the absolute URI of the system or
 schema location path.
 
 Re extensibility: A XML file is validated according to the DTD or
 schema that it declares (Relax-NG is an exception). The user can put a
 DTD or schema of his own choice in the user configuration file:
 
 !DOCTYPE fop
   PUBLIC '-//MYSELF//DTD My FOP Configuration XML V1.0//EN'
'http://myserver.mydomain.eu/fop-configuration.dtd'
 
 and the parser will validate against it. This means that a user can
 extend the configuration file at will, and that FOP cannot be assured
 that the config file is valid. Embedded users can always avoid
 validation.

Yes, but you already assume a non-novice user. If our goal is to have
less problems, fewer support requests because of configuration errors,
we have to do it fool-proof. You can't rely on everyone putting the DTD
or XSD on top of the configuration file. The first time the XML doesn't
validate, people remove the schema reference.

 I do like Manuel's suggestion to supply a separate command line
 validation option.

Me, too. You'll still have to tell the people to use the switch after
they've run into a problem. That's why I'm in favor of forcing
configuration validation for the command-line (but not for embedded use).

 Note that we have not advertised the configuration schema. It is not
 documented anywhere. I will add some documentation to the
 configuration web page.

+1 although I don't think it solves any of the problems for the group of
people I'm currently looking at.

 Ad 2: The schema cannot enforce a specific content model depending on
 the type attribute. But it does a nice job limiting the
 possibilities: One cannot mix and match parts of different renderer
 configuration options. For example, it is perfectly possible to
 configure a PostScript renderer with the elements applicable for a PDF
 renderer. But it is not possible to start with a filterList, and
 continue with auto-rotate-landscape.
 
 It is possible to force the correct content model for each renderer
 type by giving them different element names,
 e.g. renderer-application-pdf or application-pdf for short.

Exactly my point. We have to change at least the configuration layout to
improve the situation. The current layout cannot be validated
satisfyingly against an XSD.

Sure, I overreacted again. I know that and I'm sorry. But the longer I'm
on the fop-users list the more I think we have to build fool-proof
software. OTOH, as long as people don't use their brains when reading the
simplest of warning messages there's no hope anyway.

 Regards, Simon
 
 On Sun, Sep 10, 2006 at 02:52:31PM +0200, Jeremias Maerki wrote:
  Ok, I consider myself defeated concerning the way we handle the
  configuration file (See recent threads on fop-users). The Avalon
  configuration approach is very nice for the developer but obviously
  bullshit in terms of end-user-friendlyness. The attempt to overlay the
  configuration layout with an XSD is generally a good idea but with the
  current configuration layout, it's not a workable solution.
  
  If anyone has a good plan to improve the situation, I'm all ears. I
  think the configuration file needs to be built based on an XML Schema
  and FOP should by default validate the configuration file (hard-coded in
  FOP) so the users get proper feedback if they try to feed FOP with an
  invalid format. But that means the XML Schema must be water-tight. On
  the other side, we will probably lose extensibility of the configuration
  file format. When someone adds his own renderer, for example, he can't
  just have his own config values because he can't change the XML Schema.
  So that may mean we probably can't use XML Schema to validate the file.
  But then, maybe we can define the individual renderer config parts as
  xsd:any or something like that and let each renderer validate its own
  configuration (either manually or using an XSD).
  
  ATM, I can't think of a good solution but apparently, we need to change
  something at some point. Any ideas, thoughts?
  
  Jeremias Maerki
  
 
 -- 
 Simon Pepping
 home page: http://www.leverkruid.eu



Jeremias Maerki



Re: Configuration file problems

2006-09-10 Thread Manuel Mall
On Sunday 10 September 2006 20:52, Jeremias Maerki wrote:
 Ok, I consider myself defeated concerning the way we handle the
 configuration file (See recent threads on fop-users). The Avalon
 configuration approach is very nice for the developer but obviously
 bullshit in terms of end-user-friendlyness. The attempt to overlay
 the configuration layout with an XSD is generally a good idea but
 with the current configuration layout, it's not a workable solution.

Not sure I agree with the bleak picture you are painting. In my 
assessment most problems seem to be caused by the change of config 
format from 0.20.5 to 0.9x. Not by the format itself.

What about having a command line option which triggers a config file 
validation. Similar to Apache HTTPD:
apachectl -t

Run a configuration file syntax test. It parses  the  configura-
tion  files and either reports Syntax Ok or detailed information
about  the  particular  syntax  error.

Manuel
 If anyone has a good plan to improve the situation, I'm all ears. I
 think the configuration file needs to be built based on an XML Schema
 and FOP should by default validate the configuration file (hard-coded
 in FOP) so the users get proper feedback if they try to feed FOP with
 an invalid format. But that means the XML Schema must be water-tight.
 On the other side, we will probably lose extensibility of the
 configuration file format. When someone adds his own renderer, for
 example, he can't just have his own config values because he can't
 change the XML Schema. So that may mean we probably can't use XML
 Schema to validate the file. But then, maybe we can define the
 individual renderer config parts as xsd:any or something like that
 and let each renderer validate its own configuration (either manually
 or using an XSD).

 ATM, I can't think of a good solution but apparently, we need to
 change something at some point. Any ideas, thoughts?

 Jeremias Maerki


Re: Configuration file problems

2006-09-10 Thread Jeremias Maerki
Ok, but with your statement you're carefully avoiding the topic about
how to actually validate the configuration. Are we then writing a number
of plug-ins which contain manually written code that verifies the config
file on the various levels (root, renderer, fonts)? Possible, not
difficult but takes quite a bit of work to get done.

On 10.09.2006 16:03:06 Manuel Mall wrote:
 On Sunday 10 September 2006 20:52, Jeremias Maerki wrote:
  Ok, I consider myself defeated concerning the way we handle the
  configuration file (See recent threads on fop-users). The Avalon
  configuration approach is very nice for the developer but obviously
  bullshit in terms of end-user-friendlyness. The attempt to overlay
  the configuration layout with an XSD is generally a good idea but
  with the current configuration layout, it's not a workable solution.
 
 Not sure I agree with the bleak picture you are painting. In my 
 assessment most problems seem to be caused by the change of config 
 format from 0.20.5 to 0.9x. Not by the format itself.
 
 What about having a command line option which triggers a config file 
 validation. Similar to Apache HTTPD:
 apachectl -t
 
 Run a configuration file syntax test. It parses  the  configura-
 tion  files and either reports Syntax Ok or detailed information
 about  the  particular  syntax  error.
 
 Manuel
  If anyone has a good plan to improve the situation, I'm all ears. I
  think the configuration file needs to be built based on an XML Schema
  and FOP should by default validate the configuration file (hard-coded
  in FOP) so the users get proper feedback if they try to feed FOP with
  an invalid format. But that means the XML Schema must be water-tight.
  On the other side, we will probably lose extensibility of the
  configuration file format. When someone adds his own renderer, for
  example, he can't just have his own config values because he can't
  change the XML Schema. So that may mean we probably can't use XML
  Schema to validate the file. But then, maybe we can define the
  individual renderer config parts as xsd:any or something like that
  and let each renderer validate its own configuration (either manually
  or using an XSD).
 
  ATM, I can't think of a good solution but apparently, we need to
  change something at some point. Any ideas, thoughts?
 
  Jeremias Maerki



Jeremias Maerki



Re: Re: Configuration file problems

2006-09-10 Thread The Web Maestro

We could just identify the schema in the DOCTYPE (or DTD if we decide
to go that route--a schema is much more powerful, but isn't it more
overhead?). Then, we could alter the location at will. Instead of
embedding the file in FOP, it could be located either locally
(relative to FOP or the XML files), or it could be located on a remote
server.

As for validating, when someone creates a plug-in (or updates FOP to
handle some new, configurable feature), one portion of the PATCH would
update the fop-config.xsd file.

On a related point, does it make sense that all configuration be
handled in one place (e.g., fonts too)?

Clay

--
Regards,

The Web Maestro
--
[EMAIL PROTECTED] - http://homepage.mac.com/webmaestro/
My religion is simple. My religion is kindness.
- HH The 14th Dalai Lama of Tibet


Re: Configuration file problems

2006-09-10 Thread Jeremias Maerki

On 10.09.2006 17:01:30 The Web Maestro wrote:
 We could just identify the schema in the DOCTYPE (or DTD if we decide
 to go that route--a schema is much more powerful, but isn't it more
 overhead?). Then, we could alter the location at will. Instead of
 embedding the file in FOP, it could be located either locally
 (relative to FOP or the XML files), or it could be located on a remote
 server.

Locating or specifying a DTD or an XML Schema is not the issue. We
already have an XML Schema we can use but XML Schema is not expressive
enough to properly validate the current configuration XML.

 As for validating, when someone creates a plug-in (or updates FOP to
 handle some new, configurable feature), one portion of the PATCH would
 update the fop-config.xsd file.

It's possible to assemble an ad-hoc XML Schema using the import
feature as needed (Renderers would contribute a sub-schema, for example),
but again, XML Schema is not expressive enough for the current format 
(distinction of a single element type by a type attribute, e.g.
renderer). The problem with the ad-hoc schema is that it's not
feasible for validation in an XML editor, only during FOP runtime.

 On a related point, does it make sense that all configuration be
 handled in one place (e.g., fonts too)?

Can you explain further what you mean?

Jeremias Maerki



Re: Re: Configuration file problems

2006-09-10 Thread The Web Maestro

On 9/10/06, Jeremias Maerki [EMAIL PROTECTED] wrote:

On 10.09.2006 17:01:30 The Web Maestro wrote:
 On a related point, does it make sense that all configuration be
 handled in one place (e.g., fonts too)?

Can you explain further what you mean?


Sorry. For some reason I thought the FONT configuration was in a
different spot from normal FOP config. I re-read the FOP Config[1] 
the FONT configuration[2] sections again, and realized I was confusing
the PostScript  TrueType metrics file generation process with FOP's
configuration file.

Never mind!

[1] FOP Configuration:
http://xmlgraphics.apache.org/fop/0.92/configuration.html

[2] FOP Fonts Configuration:
http://xmlgraphics.apache.org/fop/0.92/fonts.html

--
Regards,

The Web Maestro
--
[EMAIL PROTECTED] - http://homepage.mac.com/webmaestro/
My religion is simple. My religion is kindness.
- HH The 14th Dalai Lama of Tibet