Bug#268786: libxml-commons-resolver1.1-java: does not install CatalogManager.properties file

[Mark Johnson]

/Hi Mike,

Thanks for the updates to the resolver bug. Earlier today I upgraded the
severity of the bug to 'grave', which should speed up the process of fixing
the bug. (Hi Arnaud:)

(Some suggested package improvement suggestions are given at the end of this
message.)

I also read your posts re potential installation locations for the
CatalogManager.properties file, and decided to read the debian policy docs
as to where the file should be installed. Given your active
interest/commitment in suggesting possible install locations, I was inspired
to actually scan all the relevant debian docs (policy & developer) to see if
there existed some obvious place to install CatalogManager.properties.

Boring, yeah, but here's what I found:

Debian Policy:
==============

In the 'Debian Policy' doc, the relevant section [1] doesn't require
anything beyond putting the file somewhere in /etc. Specifically, here's
what it says:

  10.7.2 Location
  
  Any configuration files created or used by your package must reside in
  /etc.  If there are several, consider creating a subdirectory of /etc named
  after your package.

-CONCLUSION: so it's gotta be in /etc. No surprises here.

Debian Java Policy:
===================
According to the Debian Java Policy [2]

  Chapter 4. Advices to Java packagers
   ...

  * Java properties files are probably better under /etc and flagged as
    configuration files (this will be integrated in the policy, one day).

-CONCLUSION: Same here - java policy only requires that it be installed in /etc.


Debian Developer's Reference:
=============================
I also looked in the Developer's Reference [3], but couldn't find any
relevant material.


A Suggested Configuration:
==========================

Some suggested choices & following comments regarding each choice (IMHO, of
course):

- /etc/CatalogManager.properties
	- too general a location. I don't know where the other xml-commons
	  package(s) install their config files, but it'd make sense to put
	  them all under the same subdir in /etc/, esp given the importance
	  of these classes, esp the resolver.

* /etc/xml-commons-resolver/CatalogManager.properties
  (which is roughly of the form /etc/<packagename>/CatalogManager.properties)
	- this makes the sense to me, as it makes it easy to find the
	  file (which will quite likely be edited by the site admin).


* /etc/xml/CatalogManager.properties

	- this suggestion is certainly reasonable and happens to make good
	  sense. However, /etc/xml/<filename> is' kind of' reserved for
          package catalogs. Where 'kind of' means that the XML policy [5]
          only addresses the installation location of the package catalogs
          into /etc/xml. It doesn't mention (IIRC) where to install other
          XML-related config files.

- /etc/java/resolver/CatalogManager.properties

	- this location is too far afield not to break some debian policy

- /etc/xml/commons/resolver/CatalogManager.properties
	- although this wasn't a suggestion, something like this would make
           sense if the developers wanted to put the file under /etc/xml.


Summary
=======

IMO, the CatalogManager.properties file should be installed into one of the
following directories (depending somewhat on the other components of
the upstream xml-commons package):
xml-
  (a) /etc/xml/commons/resolver/, or
  (b) /etc/xml-commons/resolver/, or 
  (c) /etc/xml-commons-resolver/


Other Suggestions:
==================
I highly recommend that 

(a) the default CatalogManager.properties use the
    properties suggested by Mike Smith in his initial bug report [4]

(b) a suitable README.Debian be composed that documents how to use the
    resolver classes to add XML catalog support for the most common XSLT
    processors: Xalan2 and Saxon. Perhaps some example wrapper scripts could
    be provided:)

---------------------------------------------------------------------

I hope you find this information to be useful.


Cheers,
Mark

References:
-----------
[1] http://www.debian.org/doc/debian-policy/ch-files.html#s-config-files
[2] http://www.debian.org/doc/packaging-manuals/java-policy/c173.html
[3] http://www.debian.org/doc/developers-reference/
[4] http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=268786
[4] http://debian-xml-sgml.alioth.debian.org/xml-policy
 


-- 
____________________________________________________________
Mark Johnson      <mrj@debian.org>
Debian XML/SGML:  <http://debian-xml-sgml.alioth.debian.org>
Home Page:        <http://dulug.duke.edu/~mark/>
GPG fp: DBEA FA3C C46A 70B5 F120  568B 89D5 4F61 C07D E242