Proposed policy for stellar astronomy data packages and programs in Debian
-----------------------------------------------------------------------

Rationale: 
Debian provides a number of astronomy related packages that make use of 
sometimes overlapping stardata catalogues. However, in some situations, the 
data format in use differs between them.


The goal of the stardata-common framework is to provide package maintainers
an infrastructure that can be used by astronomy packages and stardata
catalogs in order to allow for a tighter integration between them. This
allows catalogs to be removed from astronomy packages to avoid redundancy
and inclusion of architecture-independent data in binary packages. Since
some star data catalogs are non-free, this separation also provides a way
to have packages that can make use of that data (but do not depend on an
explicit catalog being available) available in the main archive.

--  Kevin McCarty
    Francisco Manuel García Claramonte
    Javier Fernández-Sanguino Peña
    29 Jul 2005



1. stardata-common package
--------------------------

Stardata-common Debian package, contains the program 
/usr/sbin/register-stardata and this policy 
(/usr/share/doc/stardata-common/policy.txt.gz).
 
The register-stardata program accepts arguments in the format

	register-stardata <action> <catalog> <program>

where <action> is one of {install,remove}, <catalog> is the name of
a stardata catalog, or "all" for all the stardata available, and <program> 
is the name of a astronomy package, or "all".  Both <program> and <catalog>
may not be "all" simultaneously.

The stardata-common package also contains a directory /usr/lib/stardata-common
which will be populated with executable scripts by astronomy program
packages (see section 3 below).

- When neither <catalog> nor <program> is "all", register-stardata executes
  the script /usr/lib/stardata-common/<program> with the arguments
  <action> <catalog>.
- When <program> is "all", register-stardata executes every script in
  the directory /usr/lib/stardata-common with arguments <action> <catalog>.
- When <catalog> is "all", register-stardata executes the script
  /usr/lib/stardata-common/<program> with the arguments <action> <datadir>
  repeatedly for each <datadir> in the /usr/share/stardata directory.
  

2. Star data packages
---------------------

A. Package relationships

Each data package should at least Suggest the package stardata-common.

Each data package should be in the appropriate section: one of science,
contrib/science, non-free/science.

B. Installation scripts

The postinst of each star data package, when called with "install" or
"upgrade", must execute the line

	register-stardata install <catalog> all

The prerm, when called with "remove", "upgrade", or "deconfigure", must
execute the line

	register-stardata remove <catalog> all

If the package only Suggests or Recommends stardata-common, then the
line must be protected by surrounding it with

	if [ -x /usr/sbin/register-stardata ] ; then
	...
	fi

C. Package contents

The actual ASCII data file must be named

	/usr/share/stardata/<catalog>/catalog.dat

(with a symlink, if desired).  If there are multiple data catalogs with
the same format, for instance one catalog for each hour of right ascension,
they must be named such that the glob

	/usr/share/stardata/<catalog>/catalog*.dat

expands into the name of all catalogs in the correct order.  The
recommended naming scheme is

	catalog1.dat ... catalog9.dat (for two to nine catalogs)
	catalog01.dat ... catalog99.dat (for 10 to 99 catalogs)

etc.  Again, this may be done via symlinks if desired.

Note that this naming scheme permits the use of catalogue.dat instead of
catalog.dat if desired :-)

Each star data package should put any additional upstream materials in
/usr/share/stardata/<catalog>/ or subdirectories thereof (for data and
descriptions of data format); or in /usr/share/doc/<packagename>/
(for READMEs, copyrights, etc.)

Star data packages should not include or rely upon any scripts specific
to a single astronomy software package; those scripts should instead be
included in the software package.


3. Stellar astronomy software packages
--------------------------------------

A. Package relationships

Each program that can use a star data catalog must at least Suggest
stardata-common.

Each program that can use a star data catalog must at least Suggest the
appropriate data package.  If the program fails to run when the data
catalog is not found, of course it must use the Depends relationship.
Therefore any program that requires a non-free data file to run must itself
be in contrib or non-free.

Each program should be in the appropriate section: one of science,
contrib/science, non-free/science.

B. Installation scripts

The postinst of each astronomy software package, when called with "install"
or "upgrade", must execute the line

	register-stardata install all <astronomy-package>
	
The prerm, when called with "remove", must similarly execute the line

	register-stardata remove all <astronomy-package>

If the package only Suggests or Recommends stardata-common, then the
line must be protected by surrounding it with

	if [ -x /usr/sbin/register-stardata ] ; then
	...
	fi

C. Software use of data files

Each policy-conforming program must ship with an executable script
/usr/lib/stardata-common/<program>, conforming to the following:

1) If called with the arguments "install <catalog>", the script must do
whatever is necessary to convert the file(s)
	/usr/share/stardata/<catalog>/catalog*.dat
into a form that can be used by the program with as little configuration
as possible required by the local user or admin.

a) If the program can use the data file directly, the script should drop
a symlink into the location where the program normally looks for data
files, pointing at the file in question.

b) If the program can use the data file only after some preprocessing,
the script should store the post-processed output into some appropriate
location, e.g., /var/lib/<program>/<catalog>.<ext>, where <ext> is a
program-dependent suffix.  The script may print some output indicating
what it is doing.  The script should also drop a symlink into
the location where the program normally looks for data files, pointing
at the post-processed file in question.  The software package must
include any related programs and data used by the script.  In the case
of starplot, for instance, this includes the starconvert binary and
any *.spec files used by it.

c) If the program cannot use the data file (for instance, no post-
processing script has been written for it yet), or if no files matching
the pattern /usr/share/stardata/<catalog>/catalog*.dat exist, the script
must do nothing and exit normally (with 0 exit status).

2) If called with the arguments "remove <catalog>", the script must
revert all changes made by calling it with the arguments "install <catalog>".
That is, it must delete all created symlinks and post-processed files
related to the given catalog, even if the star data package itself is
no longer installed.  If the program cannot use the specified catalog,
the script must do nothing and exit normally.

3) The script must be idempotent: calling it a second time with the same
arguments must result in no non-trivial changes occurring.

