Mercurial > hg > ooxml

annotate annotate.xml @ 67:b66bcfae65d6

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
consistent defn style
author Henry S. Thompson <ht@markup.co.uk>
date Mon, 12 Jun 2017 17:20:14 +0200
parents 53dd4ccac4fb
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
62
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
1 <?xml version='1.0'?>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
2 <?xml-stylesheet type="text/xsl" href="../../../lib/xml/doc.xsl" ?>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
3 <!DOCTYPE doc SYSTEM "../../../lib/xml/doc.dtd" >
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
4 <doc>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
5 <head>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
6 <title>Spreadsheet annotation spec</title>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
7 <author>Henry S. Thompson</author>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
8 <date>$Id$</date>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
9 </head>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
10 <body>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
11 <div>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
12 <title>Introduction</title>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
13 <p>This is a first pass at defining an annotation menu structure for
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
14 spreadsheets. The assumption is that we'll have an 'Annotate' entry in the Excel
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
15 right-button menu for selected regions, which will pop up region-appropriate
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
16 menus.</p>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
17 </div>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
18 <div>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
19 <title>Top-level menus</title>
63
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
20 <note>If the selection is a single cell I guess we try popping up a selection type menu,
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
21 with choices 'Row', 'Column', 'Matrix' and 'None' (the latter resulting in <code>_Nnnn</code>).</note>
62
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
22 <p>Right-clicking 'Annotate' when over a selected range will create a new
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
23 defined name of the form <code>_Xnnn</code>, where <code>X</code> is one of <code>R</code>,
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
24 <code>C</code> or <code>M</code> for <name>r</name>ows (horizontal range
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
25 selection), <name>c</name>olumns (vertical range selection) or
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
26 <name>m</name>atrix (for two-dimensional range selection) respectively, and
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
27 <code>nnn</code> is a serial number for the relevant selection type.</p>
63
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
28 <p>The comment field (attribute in the XML) of the defined name should contain a
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
29 feature-value dictionary, represented in JSON/Python style, that is, using the
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
30 following BNF</p>:
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
31 <display><code>fvd := '{' ( fvp ( ',' fvp )* )? '}'
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
32 fvp := key ':' value
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
33 key := string
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
34 value := string | number | fvp | array
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
35 string := '"' char* '"'
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
36 array := '[' ( value ( ',' value )* )? ']'</code></display>
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
37 <p>with whitespace ignored, 'number' being the usual integer or decimal
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
38 representation and 'char' being ASCII-only (?).</p>
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
39 <p>If possible, the selected range should appear as the value of the new
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
40 name <emph>without</emph> single-quotes.</p>
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
41 <p>Some features can and should be computed, others require annotator
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
42 decision. Some features and/or feature values are unique to a particular selection type, others are
63
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
43 shared across all or some types.</p>
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
44 <p>Accordingly, in order for the annotator to supply the required
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
45 information, a form should pop up with all the features appropriate to the
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
46 selection type. Literal or array-valued form fields will just require a value
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
47 menu (allowing multiple selection in the array-valued case), but features with
9cf99d513197 intro complete
Henry S. Thompson <ht@markup.co.uk>
parents: 62
diff changeset
48 dictionary values will require cascading sub-forms.</p>
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
49 <p>The next two sections document the annotator-supplied and
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
50 software-supplied features. Except for 'comment', whose value is free text,
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
51 allowed values are tabulated.</p>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
52 </div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
53 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
54 <title>Annotator-supplied features</title>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
55 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
56 <title>All types</title>
67
b66bcfae65d6 consistent defn style
Henry S. Thompson <ht@markup.co.uk>
parents: 65
diff changeset
57 <list type="1defn">
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
58 <item term="comment">string: unconstrained. By its nature difficult to
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
59 exploit, really should only be used to document a problem with the available
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
60 feature&amp;value vocabulary or structure.</item>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
61 </list>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
62 </div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
63 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
64 <title>Both one-dimensional types</title>
67
b66bcfae65d6 consistent defn style
Henry S. Thompson <ht@markup.co.uk>
parents: 65
diff changeset
65 <list type="1defn">
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
66 <item term="type">string: <code>"data"|"key"|"label"</code>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
67 <p>"key" is my preferred word for what Dresden call "attribute". In the
67
b66bcfae65d6 consistent defn style
Henry S. Thompson <ht@markup.co.uk>
parents: 65
diff changeset
68 simpler cases, think of it as what you find as the first row/column of the 2nd argument to an HLOOKUP/VLOOKUP call.</p>
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
69 </item>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
70 <item term="content">fvd:
67
b66bcfae65d6 consistent defn style
Henry S. Thompson <ht@markup.co.uk>
parents: 65
diff changeset
71 <list type="1defn">
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
72 <item term="type">string: <code>"currency"|"date"|"datetime"|"integer"|"float"|"key"|"label"|"string"|"time"</code></item>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
73 </list>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
74 <p>The "key" and "label" content types are for use (as in the Dresden
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
75 paper example) where compound keys/labels are indicated by row or column spans.</p>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
76 </item>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
77 </list>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
78 </div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
79 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
80 <title>Matrices</title>
67
b66bcfae65d6 consistent defn style
Henry S. Thompson <ht@markup.co.uk>
parents: 65
diff changeset
81 <list type="1defn">
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
82 <item term="type">string: <code>"table"|"data"|"label"|"condition"</code></item>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
83 <item term="content">fvd:
67
b66bcfae65d6 consistent defn style
Henry S. Thompson <ht@markup.co.uk>
parents: 65
diff changeset
84 <list type="1defn">
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
85 <item term="type">string: <code>"rows"|"columns"|"cells"</code></item>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
86 </list>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
87 </item>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
88 </list>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
89 <p>When a form for a matrix is completed, if <code>type</code> is 'data' a pop-up should offer to auto-fill
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
90 based on <code>content/type</code>. If chosen, this fills the matrix with
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
91 named ranges of the appropriate orientation (rows, columns or, in the case of
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
92 <code>cells</code>, both). If
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
93 it's not too hard, it would be good to go on to pop up the form for each
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
94 generated range
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
95 in turn, either having asked in advance for appropriate
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
96 features whose values are the same for all the ranges, or carrying forward
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
97 values from one to the next as defaults.</p>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
98 </div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
99 </div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
100 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
101 <title>Software-supplied features</title>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
102 </div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
103 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
104 <title>Issues</title>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
105 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
106 <title>Compound labels and keys</title>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
107 <p>There's a problem with
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
108 defining the structure I want for compound labels and keys, in that you can't
65
53dd4ccac4fb decorated version of dresden figure
Henry S. Thompson <ht@markup.co.uk>
parents: 64
diff changeset
109 for example select the 6th column of rows 3 through 5 in the Dresden example,
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
110 to denote the "Group stage/Match 2/GA" column label:</p>
65
53dd4ccac4fb decorated version of dresden figure
Henry S. Thompson <ht@markup.co.uk>
parents: 64
diff changeset
111 <image source="dresdenPlus.png" textGloss="table with three-row labels involving column spans, row and column labels added, F3:F5 highlighted" original="http://upcommons.upc.edu/bitstream/handle/2117/100584/KDIR_2016_47_CR.pdf" width="75%">
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
112 <licence></licence>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
113 </image>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
114 <p>Excel would allow you to define a name for
65
53dd4ccac4fb decorated version of dresden figure
Henry S. Thompson <ht@markup.co.uk>
parents: 64
diff changeset
115 F3:F5 in that spreadsheet, but I don't <emph>think</emph> you can select that
53dd4ccac4fb decorated version of dresden figure
Henry S. Thompson <ht@markup.co.uk>
parents: 64
diff changeset
116 range with the mouse.</p>
64
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
117 </div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
118 <div>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
119 <title>Metadata</title>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
120 <p>Nothing in the above proposal provides a way to annotate what Dresden
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
121 call 'Metadata'. We could simply provide another 1-D type, e.g. 'meta', I suppose, or just allow uninteresting regions to remain unannotated.
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
122 There is a difference between on the one hand informative prose such as occurs in the Dresden
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
123 example with the Metadata label, and regions whose type is just not obvious (as
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
124 e.g. lots in the Kenneth Lay sheet from the Enron dataset...</p>
823ac978f4ab scrappy first pass w/o auto features
Henry S. Thompson <ht@markup.co.uk>
parents: 63
diff changeset
125 </div>
62
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
126 </div>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
127 </body>
e46b3efbe845 start work on annotation menu desing
Henry S. Thompson <ht@markup.co.uk>
parents:
diff changeset
128 </doc>