JAL-908 JAL-912 JAL-516 documented annotation HTML description line and general tidyu...

diff --git a/help/html/features/annotationsFormat.html b/help/html/features/annotationsFormat.html
index 38d17e2..682edfd 100755 (executable)
--- a/help/html/features/annotationsFormat.html
+++ b/help/html/features/annotationsFormat.html
@@ -37,51 +37,81 @@ following ways:<br>
        menu of an alignment window.</li>
 </ul>
 </p>
-<p><strong>Annotations File Format</strong></p>
-<p>The File consists of lines containing an instruction followed by
+<p><h3><font face="Arial, Helvetica, sans-serif">Format of an Annotations File</font></h3>
+<p>The file consists of lines containing an instruction followed by
 tab delimited fields, and any lines starting with &quot;#&quot; are
 ignored. The first non-commented out line of a valid Annotations file
 must begin with :<strong><pre>JALVIEW_ANNOTATION</pre></strong></p>
-<p>A row of annotation is added with a line like <strong><pre><em>GRAPH_TYPE</em>&#9;<em>Label</em>&#9;<em>Values</em></pre></strong></p>
-<p>The <em>GRAPH_TYPE</em> field, which appears first, defines the
-appearance of the annotation row when rendered by Jalview. The next field is the row label for the annotation. The final <em>Values</em> field contains a series of &quot;|&quot;
-separated value fields. Each value field is itself a comma separated list of fields of a particular type defined by the annotation row's
-GRAPH_TYPE. The allowed values of GRAPH_TYPE and the format of their respective value fields (with the trailing &quot;<strong>|</strong>&quot; symbol) are shown below:<ul>
-       <li>BAR_GRAPH<br>
-       Plots a histogram with labels below each bar.<br>
-       <em>number</em>,<em>text character</em>,<em>Tooltip text</em></li>
-       <li>LINE_GRAPH<br>
-       Draws a line between values on the annotation row.<br>
-       <em>number</em></li>
-       <li>NO_GRAPH<br>
-       For a row consisting of text labels and/or secondary structure symbols.<br>
-       <em>{Secondary Structure Symbol}</em>,<em>text label</em>,<em>Tooltip text</em><br>
-       Currently supported secondary structure structure symbols are <em>H</em> (for   helix) and <em>E</em> (for strand)</li>
-</ul>
-Any or all value fields may be left empty, as well as the BAR_GRAPH's
+<p>A row of annotation is added with a line like <strong><pre><em>GRAPH_TYPE</em>&#9;<em>Label</em>&#9;<em>Description</em> (optional)&#9;<em>Values</em></pre></strong></p>
+       <p>
+               The <em>GRAPH_TYPE</em> field, which appears first, defines the
+               appearance of the annotation row when rendered by Jalview. The next
+               field is the row <em>label</em> for the annotation. This may be
+               followed by a <em>description</em> for the row, which is shown in a
+               tooltip when the user mouses over the annotation row's label. Since
+               Jalview 2.7, the description field may also contain html in the same
+               way as a <a href="featuresFile.html">sequence feature's</a> label,
+               providing the html is enclosed in an &lt;html/&gt; tag.
+       
+       <ul><em>Please note: URL links embedded in HTML descriptions will
+                               be supported in a future release of Jalview</em>
+       </ul>
+       </p>
+               <p>The final <em>Values</em>
+               field contains a series of &quot;|&quot; separated value fields. Each
+               value field is itself a comma separated list of fields of a particular
+               type defined by the annotation row's GRAPH_TYPE. The allowed values of
+               GRAPH_TYPE and the format of their respective value fields (with the
+               trailing &quot;<strong>|</strong>&quot; symbol) are shown below:
+       
+       <ul>
+               <li>BAR_GRAPH<br> Plots a histogram with labels below each
+                       bar.<br> <em>number</em>,<em>text character</em>,<em>Tooltip
+                               text</em>
+               </li>
+               <li>LINE_GRAPH<br> Draws a line between values on the
+                       annotation row.<br> <em>number</em>
+               </li>
+               <li>NO_GRAPH<br> For a row consisting of text labels and/or
+                       secondary structure symbols.<br> <em>{Secondary Structure
+                               Symbol}</em>,<em>text label</em>,<em>Tooltip text</em><br> Currently
+                       supported secondary structure structure symbols are <em>H</em> (for
+                       helix) and <em>E</em> (for strand)</li>
+       </ul>
+       Any or all value fields may be left empty, as well as the BAR_GRAPH's
 text character field, and either or both of the text-label and secondary
 structure symbol fields of the NO_GRAPH type annotation rows.</p>
 <p>Color strings can be embedded in a value field by enclosing an RGB triplet in square brackets to colour that position in an annotation row.  
 </p>
-<p>You can associate an annotation with a sequence by preceding its
+<p><h3><font face="Arial, Helvetica, sans-serif">SEQUENCE_REF and GROUP_REF</font></h3>
+       By
+               default, annotation is associated with the alignment as a whole.
+               However, it is also possible to have an annotation row associated with
+               a specific sequence, or a sequence group. Clicking the annotation
+               label for sequence or group associated annotation will highlight the
+               associated rows in the alignment, and double clicking will select
+               those rows, allowing further analysis. While group associated
+               annotation remains associated with a particular alignment, sequence
+               associated annotation can move with a sequence - so copying a sequence
+               to another alignment will also copy its associated annotation.
+       </p>
+       <p>You can associate an annotation with a sequence by preceding its
 definition with the line: 
 <pre>SEQUENCE_REF&#9;<em>seq_name</em>&#9;<em>[startIndex]</em></pre>
 All Annotations defined after a SEQUENCE_REF command will then be
 associated with that sequence, and the first field in the Value field
 list will (optionally) be placed at the <em>startIndex</em>'th column.</p>
-<ul><em>New in Jalview 2.4</em>: the tooltip displayed when the mouse is moved over the row 
-label for sequence associated annotation  gives the associated 
-sequence's name followed by the annotation row's description.<br/>
-<em>New in Jalview 2.5 Desktop</em>: Clicking on a sequence or group associated annotation row's label will highlight the sequence or sequence group in the alignment, and double clicking the annotation row label will select the associated sequence or group.</ul> 
+
 <p>Sequence associations are turned off for subsequent annotation
 definitions by: 
 <pre>SEQUENCE_REF&#9;ALIGNMENT</pre>
 </p>
-<p>Since version 2.5, Jalview allows annotation rows to be associated with a group defined on the alignment, by preceding the annotation row with the line:
+<p>Similarly, since Jalview 2.5, group associated annotation can be defined by preceding the row definitions with the line:
 <pre>GROUP_REF&#9;<em>group_name</em></pre>
-Group association is turned off for subsequent annotation rows by 
+Group association is turned off for subsequent annotation rows by: 
 <pre>GROUP_REF&#9;<em>ALIGNMENT</em></pre>
-Annotations may be associated with both a sequence and a group, however - group annotations are still experimental and unexpected behaviour may be observed when editing alignments containing both group and sequence associated annotation rows.</p>
+</p>
+<h3><font face="Arial, Helvetica, sans-serif">LINE_GRAPH Grouping</font></h3>
 <p><em>LINE_GRAPH</em> type annotations can be given a colour
 (specified as 24 bit RGB triplet in hexadecimal or comma separated
 values), combined onto the same vertical axis, and have ordinate lines
@@ -91,6 +121,7 @@ following commands (respectively):
 COMBINE&#9;<em>graph_1_name</em>&#9;<em>graph_2_name</em>
 GRAPHLINE&#9;<em>graph_name</em>&#9;<em>value</em>&#9;<em>label</em>&#9;<em>colour</em><strong><em>
 </em></strong></pre>
+</p>
 <h3><font face="Arial, Helvetica, sans-serif">(Since Jalview 2.5) ROWPROPERTIES</font></h3>
 <p>The visual display properties for a set of annotation rows can be modified using the following tab-delimited line:</p>
 <pre>ROWPROPERTIES&#9;<em>Row label</em>&#9;<em>centrelabs=true( or false)</em>&#9;<em>showalllabs=true(default is false)</em>&#9;<em>scaletofit=true (default is false)</em></pre>
@@ -153,7 +184,7 @@ property, then the idColour will also be used to colour the sequence.</li>
 <pre>#Comment lines follow the hash symbol
 JALVIEW_ANNOTATION
 SEQUENCE_REF&#9;FER1_MESCR&#9;5
-BAR_GRAPH&#9;Bar Graph 1&#9;||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
+BAR_GRAPH&#9;Bar Graph 1&#9;&lt;html&gt;an &lt;em&gt;html tooltip&lt;/em&gt; for Bar graph 1.&lt;/html&gt;&#9;||-100,-|-200,-|-300,-|-400,-|200,+|300,+|150,+
 LINE_GRAPH&#9;Green Values&#9;1.1|2.2|1.3|3.4|0.7|1.4|3.3|2.2|2.1|-1.1|3.2
 LINE_GRAPH&#9;Red Values&#9;2.1|3.2|1.3|-1.4|5.5|1.4|1.3|4.2|-1.1|1.1|3.2
 BAR_GRAPH&#9;Bar Graph&#9;2 1,.|2,*|3,:|4,.|5,*|4,:|3,.|2|1|1|2|3|4|5|4