You are viewing a plain text version of this content. The canonical link for it is here.
Posted to fop-dev@xmlgraphics.apache.org by Jeremias Maerki <de...@jeremias-maerki.ch> on 2006/09/10 14:52:31 UTC
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
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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
Posted by Manuel Mall <ma...@apache.org>.
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
Posted by "J.Pietschmann" <j3...@yahoo.de>.
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 base<Stuff>* 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
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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
Posted by Simon Pepping <sp...@leverkruid.eu>.
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
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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
Posted by Simon Pepping <sp...@leverkruid.eu>.
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: Re: Configuration file problems
Posted by The Web Maestro <th...@gmail.com>.
On 9/10/06, Jeremias Maerki <de...@jeremias-maerki.ch> 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
--
<th...@gmail.com> - <http://homepage.mac.com/webmaestro/>
My religion is simple. My religion is kindness.
- HH The 14th Dalai Lama of Tibet
Re: Configuration file problems
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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
Posted by The Web Maestro <th...@gmail.com>.
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
--
<th...@gmail.com> - <http://homepage.mac.com/webmaestro/>
My religion is simple. My religion is kindness.
- HH The 14th Dalai Lama of Tibet
Re: Configuration file problems
Posted by Jeremias Maerki <de...@jeremias-maerki.ch>.
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: Configuration file problems
Posted by Manuel Mall <mm...@arcus.com.au>.
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