Re: Configuration file problems
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
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
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
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
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
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
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
Configuration file problems
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
Re: Configuration file problems
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
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
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
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
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