gbin: add user-level documentation

The GBIN format is now documented in the STILTS and TOPCAT user
documents.

The documentation text is stored in the GBIN package
and imported into SUN/253; the same could be done for SUN/256,
but at present the other formats are just documented in a couple
of lines there, so follow the same practice.  That was done
(presumably?) to avoid repeated text, but importing the text
from an external package like I have done here would make it
work.  Maybe fix it for the other formats one day.

gbin/build.xml

@@ -129,6 +129,7 @@
   <!-- Directories to receive the various build components -->
   <property name="build.dir" value="${basedir}/build"/>
   <property name="build.classes" value="${build.dir}/classes"/>
+  <property name="build.docs" value="${build.dir}/docs"/>
   <property name="build.java" value="${build.dir}/java"/>
   <property name="build.tests" value="${build.dir}/testcases"/>
   <property name="build.tests.javadocs" value="${build.dir}/javadocs.test/"/>
@@ -513,11 +514,9 @@
 
     <!-- Copy extra documentation, note doesn't include javadocs these
      !   are generated from the source-->
-  <!--
     <copy todir="${dist.docs.pkg}">
       <fileset dir="${src.docs}"/>
     </copy>
-   !-->
 
     <!-- Set permissions on contents of distribution directories -->
     <chmod perm="ugo+rx" dir="${dist.dir}" type="dir" includes="**"

gbin/src/docs/gbin-stil-appexample.xdoc

@@ -0,0 +1,24 @@
+<!-- Required entities:
+ !   &gbin-package-name;       TOPCAT
+ !   &gbin-package-cmdline;    topcat
+ !   &gbin-package-classpath;  topcat-full.jar
+ |   &gbin-package-mainclass;  uk.ac.starlink.topcat.Driver
+ !-->
+
+<p>Suppose you have the <code>MDBExplorerStandalone.jar</code> file
+mentioned above, you can do it by starting &gbin-package-name; like this:
+<verbatim>
+   &gbin-package-cmdline; -classpath MDBExplorerStandalone.jar
+</verbatim>
+or like this:
+<verbatim>
+   java -classpath &gbin-package-classpath;:MDBExplorerStandalone.jar &gbin-package-mainclass;
+</verbatim>
+Note you will need to be using whatever version of java is required
+by GaiaTools, probably java 7.
+</p>
+
+<p>The GBIN format is recognised automatically, so you do not need to
+explicitly set the file type when loading GBIN files.
+</p>
+

gbin/src/docs/gbin-stil-intro.xdoc

@@ -0,0 +1,44 @@
+<!-- Required entities:
+ !   &gbin-package-name;       TOPCAT
+ !-->
+
+<p>GBIN format is a special-interest file format used within DPAC,
+the Data Processing and Analysis Consortium working on data from the
+<webref url="http://www.cosmos.esa.int/web/gaia">Gaia</webref>
+astrometry satellite.
+It is based on java serialization, and in all of its various forms
+has the peculiarity that you only stand any chance of decoding it
+if you have the Gaia data model classes on your java classpath at runtime.
+Since the set of relevant classes is very large,
+and also depends on what version of the data model your GBIN file
+corresponds to, those classes will not be packaged as part of
+the standard &gbin-package-name; distribution,
+so some additional setup is required to read GBIN files.
+</p>
+
+<p>As well as the data model classes, you must provide on the runtime
+classpath the GaiaTools classes required for GBIN reading.
+The table input handler accesses these by reflection,
+partly because GaiaTools is targeted at java 7 while STIL is at
+time of writing java 1.5 compatible, and partly to avoid an
+additional large library dependency for a rather niche requirement.
+It is likely that since you have to supply the required data model classes
+you will also have the required GaiaTools classes to hand as well,
+so this shouldn't constitute much of an additional burden for usage.
+</p>
+
+<p>In practice, if you have a jar file or files for pretty much any
+java library or application which is capable of reading a given
+GBIN file, just adding it or them to &gbin-package-name;'s classpath
+at run time ought to do the trick.
+Examples of such jar files are
+the 
+<webref url="http://gaia.esac.esa.int/mdbexp/lib/MDBExplorerStandalone.jar"
+        ><code>MDBExplorerStandalone.jar</code></webref>
+file available from
+<webref url="http://gaia.esac.esa.int/mdbexp/"/>,
+or the <code>gbcat.jar</code> file you can build from the
+<webref url="http://gaia.esac.esa.int/dpacsvn/DPAC/CU9/software/gbcat/"
+                                                  >CU9/software/gbcat/</webref>
+directory in the DPAC subversion repository.
+</p>

gbin/src/docs/gbin-stil-notes.xdoc

@@ -0,0 +1,22 @@
+<p>The GBIN format doesn't really store tables, it stores arrays of
+java objects, so the input handler has to make some decisions about how to
+flatten these into table rows.  It basically looks for public instance
+methods of the form <code>getXxx()</code>
+and uses the <code>Xxx</code> as column names.
+If the corresponding values are themselves objects with suitable getter
+methods, those objects are added as new columns instead.
+This more or less follows the practice of the
+<code>gaia.cu1.tools.util.GbinInterogator</code>/<code>gbcat</code> tool.
+Method names are sorted alphabetically.
+Arrays of complex objects are not handled well,
+and various other things may trip it up.
+See the source code (e.g. <code>uk.ac.starlink.gbin.GbinTableProfile</code>)
+for more details.
+</p>
+
+<p>Note that support for GBIN files is somewhat experimental.
+Please contact the author (who is not a GBIN expert)
+if it doesn't seem to be working properly
+or you think it should do things differently.
+</p>
+

topcat/build.xml

@@ -122,6 +122,7 @@
   <property name="user.doc" value="sun253"/>
   <property name="src.docs" value="${src.dir}/docs"/>
   <property name="xdoc.etc" value="${star.dir}/etc/xdoc"/>
+  <property name="gbin.docs" value="${star.dir}/docs/gbin"/>
 
   <!-- Directory containing any script required to execute or setup package-->
   <property name="script.dir" value="${src.dir}/script"/>
@@ -1403,6 +1404,8 @@
                includes="images/*"/>
       <fileset dir="${xdoc.etc}"
                includes="docs.dtd"/>
+      <fileset dir="${gbin.docs}"
+               includes="gbin-stil-*.xdoc"/>
     </copy>
 
     <!-- Write a file containing entity definitions for all the image files

topcat/src/docs/sun253.xml

@@ -13,6 +13,15 @@
                                          "activation-classes-javadocs.xml">
   <!ENTITY topcat.usage SYSTEM "topcat.usage">
 
+  <!-- Import entity definitions from other packages including customisation -->
+  <!ENTITY gbin.stil.intro SYSTEM "gbin-stil-intro.xdoc">
+  <!ENTITY gbin.stil.appexample SYSTEM "gbin-stil-appexample.xdoc">
+  <!ENTITY gbin.stil.notes SYSTEM "gbin-stil-notes.xdoc">
+  <!ENTITY gbin-package-name 'TOPCAT'>
+  <!ENTITY gbin-package-cmdline 'topcat'>
+  <!ENTITY gbin-package-classpath 'topcat-full.jar'>
+  <!ENTITY gbin-package-mainclass 'uk.ac.starlink.topcat.Driver'>
+
   <!-- Define some character constants. -->
   <!ENTITY column.id.char '$'>
   <!ENTITY subset.id.char '_'>
@@ -443,7 +452,8 @@ something like
 <code>java -jar topcat-full.jar</code> (see <ref id="invoke"/> for
 more detail).  To view a table that you have on disk, you can either
 give its name on the command line or load it using the <label>Load</label>
-button from the GUI.  FITS, VOTable and CDF files are recognised automatically;
+button from the GUI.  FITS, VOTable, CDF and GBIN files
+are recognised automatically;
 if your data is in another format such as ASCII (see <ref id="inFormats"/>)
 you need to tell the program (e.g. <code>-f ascii</code> on the command line).
 If you just want to try the program out, <code>topcat -demo</code> will
@@ -920,7 +930,7 @@ supported input formats have matching output formats and vice versa.
 <p>Loading tables into TOPCAT is done either from the command line
 when you start the program up or
 using the <ref id="LoadWindow">Load Table</ref> dialogue.
-For FITS, VOTable and CDF formats
+For FITS, VOTable, CDF and GBIN formats
 the file format can be detected automatically
 (note this is done by looking at the file content, it has nothing
 to do with filename extensions).
@@ -1298,6 +1308,15 @@ you wish to load a table in <code>csv</code> format.
 
 </subsubsubsect>
 
+<subsubsubsect id="inGbin">
+<subhead><title>GBIN</title></subhead>
+
+&gbin.stil.intro;
+&gbin.stil.appexample;
+&gbin.stil.notes;
+
+</subsubsubsect>
+
 <subsubsubsect id="inTst">
 <subhead><title>Tab-Separated Table</title></subhead>
 
@@ -20427,6 +20446,7 @@ introduced since the last version:
         in the underlying table.
         The special variable <code>index</code> is also deprecated in favour
         of <code>$index</code> or <code>$0</code>.</li>
+    <li>Add (experimental) read-only support for Gaia/DPAC GBIN format.</li>
     </ul>
     </p></dd>
 

ttools/src/docs/sun256.xml

@@ -1331,7 +1331,7 @@ the location, but be aware that this may be less efficient on memory.
 As with command-line STILTS, the <code>fmt</code> argument
 is one of the options in <ref id="inFormats"/>, but may be
 left as the default if the format auto-detectable,
-which currently means if the file is in VOTable, FITS or CDF format.
+which currently means if the file is in VOTable, FITS, CDF or GBIN format.
 The <code>random</code> argument can be used to ensure that the returned file
 has random (i.e. not sequential-only) access;
 for some table formats the default way of reading them in means that
@@ -1979,6 +1979,16 @@ The following list gives the values usually allowed for this
     using approximately the conventions used by MS Excel.
     </p></dd>
 
+<dt><code>gbin</code></dt>
+<dd><p>Special-interest GBIN format for internal use by the DPAC
+    consortium in relation to the Gaia astrometry satellite.
+    Additional classes (data model and GaiaTools GBIN reader)
+    are required on the classpath at runtime to use this format
+    (e.g. <code>stilts -classpath MDBExplorerStandalone.jar</code>
+     or <code>java -classpath stilts.jar:MDBExplorerStandalone.jar
+              uk.ac.starlink.ttools.Stilts</code>).
+    </p></dd>
+
 <dt><code>tst</code></dt>
 <dd><p>Tab-Separated Table format,
     as used by Starlink's GAIA and ESO's SkyCat amongst other tools.
@@ -1997,7 +2007,7 @@ For more details on these formats, see the descriptions in
 <docxref doc="sun253" loc="inFormats"/>.
 </p>
 
-<p>In some cases (when using VOTable or FITS format tables) the 
+<p>In some cases (when using VOTable, FITS, CDF or GBIN format tables) the 
 tools can detect the table format automatically, and no explicit 
 specification is necessary.  If this isn't the case and you omit
 the format specification, the tool will fail with a suitable error
@@ -9857,6 +9867,7 @@ eds. C. Gabriel et al., ASP Conf. Ser. 351, p. 666 (2006)
     <li>Fix <code>stilts</code> invocation script to pick up classes from
         <code>stilts.jar</code> in script directory in preference to
         other places (e.g. topcat-full.jar).</li>
+    <li>Add (experimental) read-only support for Gaia/DPAC GBIN format.</li>
     </ul>
     </p></dd>