From 2fd5ae863380ca80272555ae606ac814dfd2e403 Mon Sep 17 00:00:00 2001
From: Ben Pfaff <blp@cs.stanford.edu>
Date: Wed, 20 Jan 2016 22:47:05 -0800
Subject: [PATCH] Work on describing the detail XML format at a high level

(What's a "facet"?)
---
 parse-xml.c          | 20 ++++++++++++++++++++
 spv-file-format.texi | 39 +++++++++++++++++++++++++++++++++++----
 2 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/parse-xml.c b/parse-xml.c
index 2f6b33813e..3a32ee36e2 100644
--- a/parse-xml.c
+++ b/parse-xml.c
@@ -159,6 +159,24 @@ print_attribute (xmlNode *node, const char *attr)
     }
 }
 
+static void
+print_element (xmlDoc *doc, xmlNode *node, const char *element)
+{
+  for (; node; node = node->next)
+    {
+      if (!strcmp(element, (char *) node->name))
+        {
+          xmlBuffer *buf = xmlBufferCreate();
+          xmlNodeDump (buf, doc, node, 0, 1);
+          xmlBufferDump (stdout, buf);
+          xmlBufferFree (buf);
+          putchar ('\n');
+        }
+
+      print_element (doc, node->children, element);
+    }
+}
+
 static __attribute__((unused)) xmlNode *
 find_page_setup (xmlNode *node)
 {
@@ -237,6 +255,8 @@ main (int argc, char **argv)
     print_cdata (root);
   else if (!strcmp(argv[2], "text"))
     print_text (root);
+  else if (!strncmp(argv[2], "element:", 8))
+    print_element (doc, root, argv[2] + 8);
   else if (!strncmp(argv[2], "attr:", 5))
     print_attribute (root, argv[2] + 5);
   else if (!strcmp(argv[2], "labels"))
diff --git a/spv-file-format.texi b/spv-file-format.texi
index 789a77707c..6e73aef309 100644
--- a/spv-file-format.texi
+++ b/spv-file-format.texi
@@ -1227,7 +1227,35 @@ label is the string @code{s}.  Each label also includes a
 
 This format is still under investigation.
 
-All elements have an optional @code{id} attribute.
+The design of the detail XML format is not what one would end up with
+for describing pivot tables.  This is because it is a specialization
+of a much more general format (``visualization XML'' or ``VizML'')
+that can describe a wide range of visualizations.  Most of this
+generality is overkill for tables, and so we end up with a funny
+subset of a general-purpose format.
+
+The important elements of the detail XML format are:
+
+@itemize @bullet
+@item
+Variables.  Variables in detail XML roughly correspond to the
+dimensions in a light detail member.  There is one variable for each
+dimension, plus one variable for each level of labeling along an axis.
+
+The bulk of variables are defined with @code{sourceVariable} elements.
+The data for these variables comes from the associated
+@code{tableData.bin} member.  Some variables are defined, with
+@code{derivedVariable} elements, as a constant or in terms of a
+mapping function from a source variable.
+
+@item
+Assignment of variables to axes.  A variable can appear as columns, or
+rows, or layers.  The @code{faceting} element and its sub-elements
+describe this assignment.
+@end itemize
+
+All elements have an optional @code{id} attribute.  In practice many
+elements are assigned @code{id} attributes that are never referenced.
 
 @node SPV Detail visualization Element
 @subsection The @code{visualization} Element
@@ -1309,7 +1337,8 @@ Contents: @code{extension}* (@code{format} @math{|} @code{stringFormat})?
 
 This element defines a variable whose values can be used elsewhere in
 the visualization.  It ties this element's @code{id} to a variable
-from the @file{.bin} member that corresponds to this @file{.xml}.
+from the @file{tableData.bin} member that corresponds to this
+@file{.xml}.
 
 This element has the following attributes.
 
@@ -1319,12 +1348,14 @@ Always set to @code{true}.
 
 @defvr {Required} source
 Always set to @code{tableData}, the @code{source-name} in the
-corresponding @file{.bin} member (@pxref{SPV Legacy Member Metadata}).
+corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
+Metadata}).
 @end defvr
 
 @defvr {Required} sourceName
 The name of a variable within the source, the @code{variable-name} in
-the corresponding @file{.bin} member (@pxref{SPV Legacy Member Data}).
+the corresponding @file{tableData.bin} member (@pxref{SPV Legacy
+Member Data}).
 @end defvr
 
 @defvr {Optional} dependsOn
-- 
2.30.2