ttools: add full documentation for config options

Add documentation metadata for all(?) the config keys.
These can now be used to generate per-parameter XML text for insertion
into the user document.

ttools/src/main/uk/ac/starlink/ttools/plot2/config/OptionConfigKey.java

@@ -153,6 +153,41 @@ public OptionConfigKey<T> setOptionUsage() {
         return this;
     }
 
+    /**
+     * Convenience method to add the result of {@link #getOptionsXml}
+     * to the XML documentation of this key.
+     *
+     * @return  this object, as a convenience
+     */
+    public OptionConfigKey<T> addOptionsXml() {
+        ConfigMeta meta = getMeta();
+        meta.setXmlDescription( new StringBuffer()
+                               .append( meta.getXmlDescription() )
+                               .append( getOptionsXml() )
+                               .toString() );
+        return this;
+    }
+
+    /**
+     * Returns an XML list of the available options for this config key.
+     * Descriptions are not included.
+     *
+     * @return  p element
+     */
+    public String getOptionsXml() {
+        StringBuffer sbuf = new StringBuffer();
+        sbuf.append( "<p>The available options are:\n" )
+            .append( "<ul>\n" );
+        for ( T option : getOptions() ) {
+            sbuf.append( "<li><code>" )
+                .append( valueToString( option ) )
+                .append( "</code></li>\n" );
+        }
+        sbuf.append( "</ul>\n" )
+            .append( "</p>\n" );
+        return sbuf.toString();
+    }
+
     /**
      * Option specifier that uses horizontally laid out
      * radio buttons to present the options.

ttools/src/main/uk/ac/starlink/ttools/plot2/config/ShaderConfigKey.java

@@ -44,4 +44,30 @@ public Specifier<Shader> createSpecifier() {
         comboBox.setRenderer( new ShaderListCellRenderer( comboBox ) );
         return new ComboBoxSpecifier<Shader>( comboBox );
     }
+
+    /**
+     * Appends a list of the available shaders to the end of the existing
+     * XML documentation for this key.
+     *
+     * @return  this object, as a convenience
+     */
+    public ShaderConfigKey appendShaderDescription() {
+        StringBuffer sbuf = new StringBuffer();
+        sbuf.append( "<p>A mixed bag of colour ramps are available:\n" );
+        Shader[] shaders = getOptions();
+        int ns = shaders.length;
+        for ( int is = 0; is < ns; is++ ) {
+            sbuf.append( "<code>" )
+                .append( valueToString( shaders[ is ] ) )
+                .append( "</code>" )
+                .append( is < ns - 1 ? "," : "." )
+                .append( "\n" );
+        }
+        sbuf.append( "<em>Note:</em>" )
+            .append( "many of these, including rainbow-like ones," )
+            .append( "are frowned upon by the visualisation community.\n" );
+        sbuf.append( "</p>\n" );
+        getMeta().appendXmlDescription( new String[] { sbuf.toString() } );
+        return this;
+    }
 }

ttools/src/main/uk/ac/starlink/ttools/plot2/config/SkySysConfigKey.java

@@ -34,7 +34,7 @@ public SkySys stringToValue( String str ) {
      *
      * @return   options description
      */
-    public static String getOptionsXml() {
+    public static String getDescribedOptionsXml() {
         StringBuffer sbuf = new StringBuffer()
             .append( "<p>" )
             .append( "Available options are:\n" )