# HG changeset patch
# User Henry S. Thompson <ht@markup.co.uk>
# Date 1497267656 -7200
# Node ID 9cf99d5131970154f7ca8d2c71016c2f82150be8
# Parent  e46b3efbe84568d4a47b5745cff9e6d9911b6d3e
intro complete

diff -r e46b3efbe845 -r 9cf99d513197 annotate.xml
--- a/annotate.xml	Mon Jun 12 13:11:02 2017 +0200
+++ b/annotate.xml	Mon Jun 12 13:40:56 2017 +0200
@@ -17,14 +17,37 @@
   </div>
   <div>
    <title>Top-level menus</title>
+   <note>If the selection is a single cell I guess we try popping up a selection type menu,
+with choices 'Row', 'Column', 'Matrix' and 'None' (the latter resulting in <code>_Nnnn</code>).</note>
    <p>Right-clicking 'Annotate' when over a selected range will create a new
 defined name of the form <code>_Xnnn</code>, where <code>X</code> is one of <code>R</code>,
 <code>C</code> or <code>M</code> for <name>r</name>ows (horizontal range
 selection), <name>c</name>olumns (vertical range selection) or
 <name>m</name>atrix (for two-dimensional range selection) respectively, and
 <code>nnn</code> is a serial number for the relevant selection type.</p>
-   <note>If the selection is a single cell I guess we try popping up a selection type menu,
-with choices 'Row', 'Column', 'Matrix' and 'None' (the latter resulting in <code>_Nnnn</code>).</note>
+   <p>The comment field (attribute in the XML) of the defined name should contain a
+feature-value dictionary, represented in JSON/Python style, that is, using the
+following BNF</p>:
+   <display><code>fvd := '{' ( fvp ( ',' fvp )* )? '}'
+fvp := key ':' value
+key := string
+value := string | number | fvp | array
+string := '"' char* '"'
+array := '[' ( value ( ',' value )* )? ']'</code></display>
+<p>with whitespace ignored, 'number' being the usual integer or decimal
+representation and 'char' being ASCII-only (?).</p>
+   <p>If possible, the selected range should appear as the value of the new
+name <emph>without</emph> single-quotes.</p>
+   <p>Some top-level features should be computed, others require annotator
+decision.  Some features are unique to a particular selection type, others are
+shared across all or some types.</p>
+   <p>Accordingly, in order for the annotator to supply the required
+information, a form should pop up with all the features appropriate to the
+selection type.  Literal or array-valued form fields will just require a value
+menu (allowing multiple selection in the array-valued case), but features with
+dictionary values will require cascading sub-forms.</p>
+   <p>The sections below tabulate the annotator-supplied features and their
+possible values.</p>
   </div>
  </body>
 </doc>