@node SPSS Viewer File Format
-@chapter SPSS Viewer File Format
+@appendix SPSS Viewer File Format
SPSS Viewer or @file{.spv} files, here called SPV files, are written
by SPSS 16 and later to represent the contents of its output editor.
@node SPV Structure Member Format
@section Structure Member Format
+A structure member lays out the high-level structure for a group of
+output items such as heading, tables, and charts. Structure members
+do not include the details of tables and charts but instead refer to
+them by their member names.
+
Structure members' XML files claim conformance with a collection of
XML Schemas. These schemas are distributed, under a nonfree license,
with SPSS binaries. Fortunately, the schemas are not necessary to
-understand the structure members. To a degree, the schemas can even
+understand the structure members. The schemas can even
be deceptive because they document elements and attributes that are
not in the corpus and do not document elements and attributes that are
-commonly found there.
+commonly found in the corpus.
Structure members use a different XML namespace for each schema, but
these namespaces are not entirely consistent. In some SPV files, for
One may ignore all of the above in interpreting a structure member.
The actual XML has a simple and straightforward form that does not
-require a reader to take schemas or namespaces into account.
+require a reader to take schemas or namespaces into account. A
+structure member's root is @code{heading} element, which contains
+@code{heading} or @code{container} elements (or a mix), forming a
+tree. In turn, @code{container} holds a @code{label} and one more
+child, usually @code{text} or @code{table}.
+
+The following diagram shows the hierarchy within an SPV structure
+member more precisely. Names represent elements and <text> and
+<cdata> represent plain text and CDATA, respectively. Edges point
+from parent to child. Unlabeled edges indicate that the child appears
+exactly once; edges labeled with *, zero or more times; edges labeled
+with ?, zero or one times. Where possible, child elements are shown
+in the order they actually appear within a parent element.
+
+@example
+@group
+heading
+ +--?--> pageSetup
+ | +--> pageHeader +--> pageParagraph --> text --> <cdata>
+ | +--> pageFooter +--> pageParagraph --> text --> <cdata>
+ +-----> label --?--> <text>
+ +--*--> heading
+ +--*--> container
+ +-----> label --?--> <text>
+ +--?--> text ---> html --> <cdata>
+ +--?--> table
+ | +--?-- tableProperties
+ | | +--> generalProperties
+ | | +--> footnoteProperties
+ | | +--> cellFormatProperties
+ | | | +--> caption -------> style
+ | | | +--> footnotes -----> style
+ | | | +--> rowLabelse ----> style
+ | | | +--> columnLabels --> style
+ | | | +--> data ----------> style
+ | | | +--> layers --------> style
+ | | | +--> title ---------> style
+ | | | +--> cornerLabels --> style
+ | | +--> borderProperties
+ | | | +--> topInnerFrame
+ | | | +--> rightInnerFrame
+ | | | +--> horizontalDimensionBorderColumns
+ | | | +--> horizontalDimensionBorderRows
+ | | | +--> horizontalCategoryBorderColumns
+ | | | +--> leftInnerFrame
+ | | | +--> verticalDimensionBorderRows
+ | | | +--> titleLayerSeparator
+ | | | +--> verticalCategoryBorderRows
+ | | | +--> topOuterFrame
+ | | | +--> bottomInnerFrame
+ | | | +--> leftOuterFrame
+ | | | +--> dataAreaTop
+ | | | +--> verticalDimensionBorderColumns
+ | | | +--> dataAreaLeft
+ | | | +--> horizontalCategoryBorderRows
+ | | | +--> bottomOuterFrame
+ | | | +--> rightOuterFrame
+ | | | +--> verticalCategoryBorderColumns
+ | | +--> printingProperties
+ | +----- tableStructure
+ | +--?--> path ------> <text>
+ | +-----> dataPath --> <text>
+ +--?--> graph
+ | +--?--> dataPath --> <text>
+ | +-----> path ------> <text>
+ +--?--> model
+ +--?--> ViZml --> <text>
+ +--?--> path ---> <text>
+ +--?--> pmmlContainerPath ---> <text>
+ +--?--> statsContainerPath --> <text>
+@end group
+@end example
The elements found in structure members are documented below. For
each element, we note the possible parent elements and the element's
Zero or more @var{x}.
@end table
-@ifnottex
-For a diagram illustrating the hierarchy of elements within an SPV
-structure member, please refer to a PDF version of the manual.
-@end ifnottex
+The following example shows the contents of a typical structure member
+for a @cmd{DESCRIPTIVES} procedure. A real structure member is not
+indented. This example also omits most attributes, all XML namespace
+information, and the CSS from the embedded HTML:
-@iftex
-The following diagram shows the hierarchy of elements within an SPV
-structure member. Edges point from parent to child elements.
-Unlabeled edges indicate that the child appears exactly once; edges
-labeled with *, zero or more times; edges labeled with ?, zero or one
-times.
-@center @image{dev/spv-structure, 5in}
-@end iftex
+@example
+<?xml version="1.0" encoding="utf-8"?>
+<heading>
+ <label>Output</label>
+ <heading commandName="Descriptives">
+ <label>Descriptives</label>
+ <container>
+ <label>Title</label>
+ <text commandName="Descriptives" type="title">
+ <html lang="en">
+<![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
+ </html>
+ </text>
+ </container>
+ <container visibility="hidden">
+ <label>Notes</label>
+ <table commandName="Descriptives" subType="Notes" type="note">
+ <tableStructure>
+ <dataPath>00000000001_lightNotesData.bin</dataPath>
+ </tableStructure>
+ </table>
+ </container>
+ <container>
+ <label>Descriptive Statistics</label>
+ <table commandName="Descriptives" subType="Descriptive Statistics"
+ type="table">
+ <tableStructure>
+ <dataPath>00000000002_lightTableData.bin</dataPath>
+ </tableStructure>
+ </table>
+ </container>
+ </heading>
+</heading>
+@end example
@menu
* SPV Structure heading Element::
* SPV Structure html Element::
* SPV Structure table Element::
* SPV Structure tableStructure Element::
-* SPV Structure dataPath Element::
+* SPV Structure graph Element::
+* SPV Structure model Element::
+* SPV Structure dataPath and path Elements::
* SPV Structure pageSetup Element::
* SPV Structure pageHeader and pageFooter Elements::
* SPV Structure pageParagraph Element::
The root of a structure member is a @code{heading}, which represents a
section of output beginning with a title (the @code{label}) and
ordinarily followed by content containers or further nested
-(sub)-sections of output.
+(sub)-sections of output. Unlike heading elements in HTML and other
+common document formats, which precede the content that they head,
+@code{heading} contains the elements that appear below the heading.
The document root heading, only, may also contain a @code{pageSetup}
element.
according to the output language, e.g.@: in Italian a frequency table
procedure is labeled ``Frequenze''.
-The corpus contains one example of an empty label, one that contains
+The corpus contains a few examples of empty labels, ones that contain
no text.
This element has no attributes.
@subsection The @code{container} Element
Parent: @code{heading} @*
-Contents: @code{label} (@code{table} @math{|} @code{text})?
+Contents: @code{label} (@code{table} @math{|} @code{text} @math{|} @code{graph} @math{|} @code{model})
A @code{container} serves to label a @code{table} or a @code{text}
item.
Contents: CDATA
The CDATA contains an HTML document. In some cases, the document
-starts with @code{<html>} and ends with @code{</html}; in others the
+starts with @code{<html>} and ends with @code{</html>}; in others the
@code{html} element is implied. Generally the HTML includes a
@code{head} element with a CSS stylesheet. The HTML body often begins
with @code{<BR>}. The actual content ranges from trivial to simple:
This element has no attributes.
-@node SPV Structure dataPath Element
-@subsection The @code{dataPath} Element
+@node SPV Structure graph Element
+@subsection The @code{graph} Element
+
+Parent: @code{container} @*
+Contents: @code{dataPath}? @code{path}
+
+This element represents a graph. The @code{dataPath} and @code{path}
+elements name the Zip members that give the details of the graph.
+Normally, both elements are present; there is only one counterexample
+in the corpus.
+
+@node SPV Structure model Element
+@subsection The @code{model} Element
+
+Parent: @code{container} @*
+Contents: (@code{ViZml}? @code{path}) @math{|} (@code{pmmlContainerPath} @code{statsContainerPath})
-Parent: @code{tableStructure} @*
+This element represents a model. The @code{dataPath} and @code{path}
+elements name the Zip members that give the details of the model.
+Normally, both elements are present; there is only one counterexample
+in the corpus.
+
+The details are unexplored. The @code{ViZml} element contains base-64
+encoded text, that decodes to a binary format with some embedded text
+strings, and @code{path} names an Zip member that contains XML.
+Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
+name Zip members with @file{.scf} extension.
+
+@node SPV Structure dataPath and path Elements
+@subsection The @code{dataPath} and @code{path} Elements
+
+Parent: @code{tableStructure} or @code{graph} or @code{model} @*
Contents: text
-Contains the name of the Zip member that holds the table details,
-e.g.@: @code{0000000001437_lightTableData.bin}.
+These element contain the name of the Zip members that hold details
+for a container. For tables:
-This element has no attributes.
+@itemize @bullet
+@item
+When a ``light'' format is used, only @code{dataPath} is present, and
+it names a @file{.bin} member of the Zip file that has @code{light} in
+its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
+Light Detail Member Format}).
+
+@item
+When the legacy format is used, both are present. In this case,
+@code{dataPath} names a Zip member with a legacy binary format that
+contains relevant data (@pxref{SPV Legacy Detail Member Binary
+Format}), and @code{path} names a Zip member that uses an XML format
+(@pxref{SPV Legacy Detail Member XML Format}).
+@end itemize
+
+Graphs normally follow the legacy approach described above. The
+corpus contains one example of a graph with @code{path} but not
+@code{dataPath}. The reason is unexplored.
+
+Models use @code{path} but not @code{dataPath}. @xref{SPV Structure
+graph Element}, for more information.
+
+These elements have no attributes.
@node SPV Structure pageSetup Element
@subsection The @code{pageSetup} Element
@node SPV Structure @code{text} Element (Inside @code{pageParagraph})
@subsection The @code{text} Element (Inside @code{pageParagraph})
-Parent: @code{pageParagraph}
+Parent: @code{pageParagraph} @*
Contents: CDATA?
This @code{text} element is nested inside a @code{pageParagraph}. There
text: in the corpus, either an @code{html} or @code{p} element. It is
@emph{almost}-XHTML because the @code{html} element designates the
default namespace as
-@code{http://xml.spss.com/spss/viewer/viewer-tree} instead of an XHTML
+@indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of an XHTML
namespace, and because the CDATA can contain substitution variables:
@code{&[Page]} for the page number and @code{&[PageTitle]} for the
page title.
projects / pspp / blobdiff