Work on describing the detail XML format at a high level

[pspp] / spv-file-format.texi

diff --git a/spv-file-format.texi b/spv-file-format.texi
index 789a77707ce4d2894d80daec9f8af2975cd30ccb..6e73aef30960406ebbc9cdbc7ac88296d93d3ab1 100644 (file)
--- 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