On Thu, 5 Jun 2003, Rankin, SE (Stephen) wrote:

> 7. Nothing in bin/task dir.

true. this directory doesn't need to be there. You can doctor the
task/build.xml file to prevent it from being created if you want,
or I can on request.


> 12. Documentation, SUN/XXX docs - should the treeview and splat SUN docs now
> go in the docs package, have they been updated? Are they in the CVS? Only
> javadocs for classes and other java packages in starjava/docs/ dir when the
> install target is used. export_full_docs does not give the same output for
> the javadocs as the install target? We could do with some simple (two pages)

The javadocs in the install target aren't useful for much as far as
I can see, if you have built the javadocs from the export_full_docs target,
since the latter have the same content but with better cross-referencing.
They could be excluded from the CD if you wanted to save space???
The applications don't appear in the export_full_docs one though,
so their install-target javadocs are useful (though one could argue
not really appropriate for public consumption).

> documentation on what commands to run for the applications and also some
> simple descriptions.

The treeview SUN is no longer up to date and should be considered withdrawn.
The documentation on treeview is basically the online help
available from within the application, though this advertises the
treeview web page (http://www.starlink.ac.uk/treeview/), which also
contains some information for users.

The online help is not all that comprehensive, but it is pretty easy
to explore treeview, especially in conjunction with the test data
provided in the application, so I'm not currently planning to come up
with anything a lot more heavy duty as a matter of priority.

Thus the 'simple documentation' would just say 'run treeview', and you
can read the online docs/play around from there. For people who don't
have it installed, they can see the www page, which contains screenshots
and download info etc.

The only other issue is *how* you run treeview (i.e. type the script name
with the path set right and/or invoke the jar file direct).

If you want I can come up with a short document along these lines;
if so tell me what form you want it in (README/LaTeX/HTML/??) and some
thoughts about what it should look like, or at least under what
circumstances users will be looking at it. Same applies to TOPCAT.

TOPCAT documentation is entirely within the application as a JavaHelp
browser, though the docs exist as HTML files so could with a
bit of effort be made accessible externally (I may do this on the
TOPCAT www page). The main problem with this is that the help browser
is not accessible from the 'load table' dialog, which is what you get if
you just invoke 'topcat' on its own. It is not that hard, but not
trivial to fix this, and I didn't have time to do so before the
deadline this morning.


> In future we could do with having an overview of the
> classes and their functionality as well as the javadocs?

You're right, though these can go in the javadocs too - see Norman's
HDX overview for a good example. I have been remiss in putting
overview information in the class library javadocs for my packages
though. I will attempt to improve on this.


> 13. I will just be unpacking the starjava-xxxx.tar.gz, starjava.tar.gz
> and starjava-docs.tar.gz into the ${INSTALL}/starjava dir (with a
> makefile). On the next CD we can then just delete the starjava
> directory before installing the new starjava stuff. Are
> starjava.tar.gz and starjava-docs.tar.gz the same for all systems?

Yes, they are the same (or at least should be; it's possible that the
java compilers on the different platforms might produce different bytecode
from the same sources, but it ought not to be importantly different).
The only platform-specific differences are shared libraries in
lib/{i386,sparc,x86} directories.

BTW: I presume you have the latest versions of the x86 platform-specific
files (Windows DLLs); I've rather lost track of whether the ones on
my ftp site are completely up to date with the sources (JNIAST & JNIHDS)
or not. Peter will presumably have the most up to date ones.

> 14. Starlink Classes - jnihds, jniast, array, coco, fits, hdx, jaiutil,
> ndx, pal, rv, soap, table, task, util and votable. We also have
> nom.tam.fits API and the JSky API. Are there any version numbers?
>
> 15. Are there any version numbers for the applications, frog, jsky,
> ndtools, soapserver, sog, splat, task, treeview, topcat, starmirage,
> tablecopy.

Version numbers are defined in the build.xml files:

   % grep name=.version */build.xml
   ant/build.xml: <property name="version" value="1.5-2"/>
   array/build.xml: <property name="version" value="0.2"/>
   astgui/build.xml: <property name="version" value="1.0"/>
   axis/build.xml: <property name="version" value="1.0b2"/>
      ...

However, I for one am not scrupulous about updating these in a consistent
way. In the paradigm of lots of little incremental updates & bugfixes
to lots of packages which CVS encourages this becomes a bit of a pain.

I tend to maintain version numbers in a meaningful way only for those
of my packages which are likely to be used by outside customers;
this currently applies mostly to Treeview and TOPCAT. The version numbers
for these are:

   treeview: v2.1-3
   TOPCAT: v0.3b

The 'b' in TOPCAT indicates that it's beta software - in its short
life I have spent more time adding features than in rigorous testing,
so it may not be the most robust application I've ever sumitted for
release. I don't know whether this has implications for how/whether
we want to publicise it.

The version for JNIAST is the same as that of the AST it wants to
build against:

   JNIAST: v2.0-4

Starmirage probably shouldn't be publicised, since there are bugs
in mirage which make it not work half the time.

Ndtools I've discussed before isn't really ready for the glare of
publicity. Some of it works, but it's not a very coherent package.

Tablecopy works fine, and is a very simple but kind of useful tool,
but it isn't really documented anywhere because I don't know where
to document it. It doesn't really warrant a SUN of its own (and LaTeX
seems a bit non-java).


> 16. Run tests, find out which have tests.

Unit tests for all the packages should get run by an 'ant test' at the
top level, no? Some of my packages have quite rigorous tests, others
less so. Such ones as exist are invoked with the ant test target.


Here end my comments.

Mark
--
Mark Taylor Starlink Programmer Physics, Bristol University, UK
[log in to unmask] 0117 928 8776 http://www.star.bris.ac.uk/~mbt/