fb2c1eb16494a800b38a14e5e756e3c26176d0de
[pspp] / doc / dev / spv-file-format.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2019 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
9 @c
10
11 @node SPSS Viewer File Format
12 @appendix SPSS Viewer File Format
13
14 SPSS Viewer or @file{.spv} files, here called SPV files, are written
15 by SPSS 16 and later to represent the contents of its output editor.
16 This chapter documents the format, based on examination of a corpus of
17 about 8,000 files from a variety of sources.  This description is
18 detailed enough to both read and write SPV files.
19
20 SPSS 15 and earlier versions instead use @file{.spo} files, which have
21 a completely different output format based on the Microsoft Compound
22 Document Format.  This format is not documented here.
23
24 An SPV file is a Zip archive that can be read with @command{zipinfo}
25 and @command{unzip} and similar programs.  The final member in the Zip
26 archive is the @dfn{manifest}, a file named
27 @file{META-INF/MANIFEST.MF}.  This structure makes SPV files resemble
28 Java ``JAR'' files (and ODF files), but whereas a JAR manifest
29 contains a sequence of colon-delimited key/value pairs, an SPV
30 manifest contains the string @samp{allowPivoting=true}, without a
31 new-line.  PSPP uses this string to identify an SPV file; it is
32 invariant across the corpus.@footnote{SPV files always begin with the
33 7-byte sequence 50 4b 03 04 14 00 08, but this is not a useful magic
34 number because most Zip archives start the same way.}@footnote{SPSS
35 writes @file{META-INF/MANIFEST.MF} to every SPV file, but it does not
36 read it or even require it to exist, so using different contents,
37 e.g.@: as @samp{allowingPivot=false} has no effect.}
38
39 The rest of the members in an SPV file's Zip archive fall into two
40 categories: @dfn{structure} and @dfn{detail} members.  Structure
41 member names take the form with @file{outputViewer@var{number}.xml} or
42 @file{outputViewer@var{number}_heading.xml}, where @var{number} is an
43 10-digit decimal number.  Each of these members represents some kind
44 of output item (a table, a heading, a block of text, etc.) or a group
45 of them.  The member whose output goes at the beginning of the
46 document is numbered 0, the next member in the output is numbered 1,
47 and so on.
48
49 Structure members contain XML.  This XML is sometimes self-contained,
50 but it often references detail members in the Zip archive, which are
51 named as follows:
52
53 @table @asis
54 @item @file{@var{prefix}_table.xml} and @file{@var{prefix}_tableData.bin}
55 @itemx @file{@var{prefix}_lightTableData.bin}
56 The structure of a table plus its data.  Older SPV files pair a
57 @file{@var{prefix}_table.xml} file that describes the table's
58 structure with a binary @file{@var{prefix}_tableData.bin} file that
59 gives its data.  Newer SPV files (the majority of those in the corpus)
60 instead include a single @file{@var{prefix}_lightTableData.bin} file
61 that incorporates both into a single binary format.
62
63 @item @file{@var{prefix}_warning.xml} and @file{@var{prefix}_warningData.bin}
64 @itemx @file{@var{prefix}_lightWarningData.bin}
65 Same format used for tables, with a different name.
66
67 @item @file{@var{prefix}_notes.xml} and @file{@var{prefix}_notesData.bin}
68 @itemx @file{@var{prefix}_lightNotesData.bin}
69 Same format used for tables, with a different name.
70
71 @item @file{@var{prefix}_chartData.bin} and @file{@var{prefix}_chart.xml}
72 The structure of a chart plus its data.  Charts do not have a
73 ``light'' format.
74
75 @item @file{@var{prefix}_Imagegeneric.png}
76 @itemx @file{@var{prefix}_PastedObjectgeneric.png}
77 @itemx @file{@var{prefix}_imageData.bin}
78 A PNG image referenced by an @code{object} element (in the first two
79 cases) or an @code{image} element (in the final case).  @xref{SPV
80 Structure object and image Elements}.
81
82 @item @file{@var{prefix}_pmml.scf}
83 @itemx @file{@var{prefix}_stats.scf}
84 @item @file{@var{prefix}_model.xml}
85 Not yet investigated.  The corpus contains few examples.
86 @end table
87
88 The @file{@var{prefix}} in the names of the detail members is
89 typically an 11-digit decimal number that increases for each item,
90 tending to skip values.  Older SPV files use different naming
91 conventions for detail members.  Structure member refer to detail
92 members by name, and so their exact names do not matter to readers as
93 long as they are unique.
94
95 SPSS tolerates corrupted Zip archives that Zip reader libraries tend
96 to reject.  These can be fixed up with @command{zip -FF}.
97
98 @menu
99 * SPV Structure Member Format::
100 * SPV Light Detail Member Format::
101 * SPV Legacy Detail Member Binary Format::
102 * SPV Legacy Detail Member XML Format::
103 @end menu
104
105 @node SPV Structure Member Format
106 @section Structure Member Format
107
108 A structure member lays out the high-level structure for a group of
109 output items such as heading, tables, and charts.  Structure members
110 do not include the details of tables and charts but instead refer to
111 them by their member names.
112
113 Structure members' XML files claim conformance with a collection of
114 XML Schemas.  These schemas are distributed, under a nonfree license,
115 with SPSS binaries.  Fortunately, the schemas are not necessary to
116 understand the structure members.  The schemas can even
117 be deceptive because they document elements and attributes that are
118 not in the corpus and do not document elements and attributes that are
119 commonly found in the corpus.
120
121 Structure members use a different XML namespace for each schema, but
122 these namespaces are not entirely consistent.  In some SPV files, for
123 example, the @code{viewer-tree} schema is associated with namespace
124 @indicateurl{http://xml.spss.com/spss/viewer-tree} and in others with
125 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} (note the
126 additional @file{viewer/}).  Under either name, the schema URIs are
127 not resolvable to obtain the schemas themselves.
128
129 One may ignore all of the above in interpreting a structure member.
130 The actual XML has a simple and straightforward form that does not
131 require a reader to take schemas or namespaces into account.  A
132 structure member's root is @code{heading} element, which contains
133 @code{heading} or @code{container} elements (or a mix), forming a
134 tree.  In turn, @code{container} holds a @code{label} and one more
135 child, usually @code{text} or @code{table}.
136
137 The following sections document the elements found in structure
138 members in a context-free grammar-like fashion.  Consider the
139 following example, which specifies the attributes and content for the
140 @code{container} element:
141
142 @example
143 container
144    :visibility=(visible | hidden)
145    :page-break-before=(always)?
146    :text-align=(left | center)?
147    :width=dimension
148 => label (table | container_text | graph | model | object | image | tree)
149 @end example
150
151 Each attribute specification begins with @samp{:} followed by the
152 attribute's name.  If the attribute's value has an easily specified
153 form, then @samp{=} and its description follows the name.  Finally, if
154 the attribute is optional, the specification ends with @samp{?}.  The
155 following value specifications are defined:
156
157 @table @code
158 @item (@var{a} | @var{b} | @dots{})
159 One of the listed literal strings.  If only one string is listed, it
160 is the only acceptable value.  If @code{OTHER} is listed, then any
161 string not explicitly listed is also accepted.
162
163 @item bool
164 Either @code{true} or @code{false}.
165
166 @item dimension
167 A floating-point number followed by a unit, e.g.@: @code{10pt}.  Units
168 in the corpus include @code{in} (inch), @code{pt} (points, 72/inch),
169 @code{px} (``device-independent pixels'', 96/inch), and @code{cm}.  If
170 the unit is omitted then points should be assumed.  The number and
171 unit may be separated by white space.
172
173 The corpus also includes localized names for units.  A reader must
174 understand these to properly interpret the dimension:
175
176 @table @asis
177 @item inch
178 @code{인치}, @code{pol.}, @code{cala}, @code{cali}
179
180 @item point
181 @code{пт}
182
183 @item centimeter
184 @code{см}
185 @end table
186
187 @item real
188 A floating-point number.
189
190 @item int
191 An integer.
192
193 @item color
194 A color in one of the forms @code{#@var{rr}@var{gg}@var{bb}} or
195 @code{@var{rr}@var{gg}@var{bb}}, or the string @code{transparent}, or
196 one of the standard Web color names.
197
198 @item ref
199 @item ref @var{element}
200 @itemx ref(@var{elem1} | @var{elem2} | @dots{})
201 The name from the @code{id} attribute in some element.  If one or more
202 elements are named, the name must refer to one of those elements,
203 otherwise any element is acceptable.
204 @end table
205
206 All elements have an optional @code{id} attribute.  If present, its
207 value must be unique.  In practice many elements are assigned
208 @code{id} attributes that are never referenced.
209
210 The content specification for an element supports the following
211 syntax:
212
213 @table @code
214 @item @var{element}
215 An element.
216
217 @item @var{a} @var{b}
218 @var{a} followed by @var{b}.
219
220 @item @var{a} | @var{b} | @var{c}
221 One of @var{a} or @var{b} or @var{c}.
222
223 @item @var{a}?
224 Zero or one instances of @var{a}.
225
226 @item @var{a}*
227 Zero or more instances of @var{a}.
228
229 @item @var{b}+
230 One or more instances of @var{a}.
231
232 @item (@var{subexpression})
233 Grouping for a subexpression.
234
235 @item EMPTY
236 No content.
237
238 @item TEXT
239 Text and CDATA.
240 @end table
241
242 Element and attribute names are sometimes suffixed by another name in
243 square brackets to distinguish different uses of the same name.  For
244 example, structure XML has two @code{text} elements, one inside
245 @code{container}, the other inside @code{pageParagraph}.  The former
246 is defined as @code{text[container_text]} and referenced as
247 @code{container_text}, the latter defined as
248 @code{text[pageParagraph_text]} and referenced as
249 @code{pageParagraph_text}.
250
251 This language is used in the PSPP source code for parsing structure
252 and detail XML members.  Refer to
253 @file{src/output/spv/structure-xml.grammar} and
254 @file{src/output/spv/detail-xml.grammar} for the full grammars.
255
256 The following example shows the contents of a typical structure member
257 for a @cmd{DESCRIPTIVES} procedure.  A real structure member is not
258 indented.  This example also omits most attributes, all XML namespace
259 information, and the CSS from the embedded HTML:
260
261 @example
262 <?xml version="1.0" encoding="utf-8"?>
263 <heading>
264   <label>Output</label>
265   <heading commandName="Descriptives">
266     <label>Descriptives</label>
267     <container>
268       <label>Title</label>
269       <text commandName="Descriptives" type="title">
270         <html lang="en">
271 <![CDATA[<head><style type="text/css">...</style></head><BR>Descriptives]]>
272         </html>
273       </text>
274     </container>
275     <container visibility="hidden">
276       <label>Notes</label>
277       <table commandName="Descriptives" subType="Notes" type="note">
278         <tableStructure>
279           <dataPath>00000000001_lightNotesData.bin</dataPath>
280         </tableStructure>
281       </table>
282     </container>
283     <container>
284       <label>Descriptive Statistics</label>
285       <table commandName="Descriptives" subType="Descriptive Statistics"
286              type="table">
287         <tableStructure>
288           <dataPath>00000000002_lightTableData.bin</dataPath>
289         </tableStructure>
290       </table>
291     </container>
292   </heading>
293 </heading>
294 @end example
295
296 @menu
297 * SPV Structure heading Element::
298 * SPV Structure label Element::
299 * SPV Structure container Element::
300 * SPV Structure text Element (Inside @code{container})::
301 * SPV Structure html Element::
302 * SPV Structure table Element::
303 * SPV Structure graph Element::
304 * SPV Structure model Element::
305 * SPV Structure object and image Elements::
306 * SPV Structure tree Element::
307 * SPV Structure Path Elements::
308 * SPV Structure pageSetup Element::
309 * SPV Structure @code{text} Element (Inside @code{pageParagraph})::
310 @end menu
311
312 @node SPV Structure heading Element
313 @subsection The @code{heading} Element
314
315 @example
316 heading[root_heading]
317    :creator-version?
318    :creator?
319    :creation-date-time?
320    :lockReader=bool?
321    :schemaLocation?
322 => label pageSetup? (container | heading)*
323
324 heading
325    :creator-version?
326    :commandName?
327    :visibility[heading_visibility]=(collapsed)?
328    :locale?
329    :olang?
330 => label (container | heading)*
331 @end example
332
333 A @code{heading} represents a tree of content that appears in an
334 output viewer window.  It contains a @code{label} text string that is
335 shown in the outline view ordinarily followed by content containers or
336 further nested (sub)-sections of output.  Unlike heading elements in
337 HTML and other common document formats, which precede the content that
338 they head, @code{heading} contains the elements that appear below the
339 heading.
340
341 The root of a structure member is a special @code{heading}.  The
342 direct children of the root @code{heading} elements in all structure
343 members in an SPV file are siblings.  That is, the root @code{heading}
344 in all of the structure members conceptually represent the same node.
345 The root heading's @code{label} is ignored (see @pxref{SPV Structure
346 label Element}).  The root heading in the first structure member in
347 the Zip file may contain a @code{pageSetup} element.
348
349 The schema implies that any @code{heading} may contain a sequence of
350 any number of @code{heading} and @code{container} elements.  This does
351 not work for the root @code{heading} in practice, which must actually
352 contain exactly one @code{container} or @code{heading} child element.
353 Furthermore, if the root heading's child is a @code{heading}, then the
354 structure member's name must end in @file{_heading.xml}; if it is a
355 @code{container} child, then it must not.
356
357 The following attributes have been observed on both document root and
358 nested @code{heading} elements.
359
360 @defvr {Attribute} creator-version
361 The version of the software that created this SPV file.  A string of
362 the form @code{xxyyzzww} represents software version xx.yy.zz.ww,
363 e.g.@: @code{21000001} is version 21.0.0.1.  Trailing pairs of zeros
364 are sometimes omitted, so that @code{21}, @code{210000}, and
365 @code{21000000} are all version 21.0.0.0 (and the corpus contains all
366 three of those forms).
367 @end defvr
368
369 @noindent
370 The following attributes have been observed on document root
371 @code{heading} elements only:
372
373 @defvr {Attribute} @code{creator}
374 The directory in the file system of the software that created this SPV
375 file.
376 @end defvr
377
378 @defvr {Attribute} @code{creation-date-time}
379 The date and time at which the SPV file was written, in a
380 locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
381 PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
382 December 5, 2014 5:00:19 o'clock PM EST}.
383 @end defvr
384
385 @defvr {Attribute} @code{lockReader}
386 Whether a reader should be allowed to edit the output.  The possible
387 values are @code{true} and @code{false}.  The value @code{false} is by
388 far the most common.
389 @end defvr
390
391 @defvr {Attribute} @code{schemaLocation}
392 This is actually an XML Namespace attribute.  A reader may ignore it.
393 @end defvr
394
395 @noindent
396 The following attributes have been observed only on nested
397 @code{heading} elements:
398
399 @defvr {Attribute} @code{commandName}
400 A locale-invariant identifier for the command that produced the
401 output, e.g.@: @code{Frequencies}, @code{T-Test}, @code{Non Par Corr}.
402 @end defvr
403
404 @defvr {Attribute} @code{visibility}
405 If this attribute is absent, the heading's content is expanded in the
406 outline view.  If it is set to @code{collapsed}, it is collapsed.
407 (This attribute is never present in a root @code{heading} because the
408 root node is always expanded when a file is loaded, even though the UI
409 can be used to collapse it interactively.)
410 @end defvr
411
412 @defvr {Attribute} @code{locale}
413 The locale used for output, in Windows format, which is similar to the
414 format used in Unix with the underscore replaced by a hyphen, e.g.@:
415 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
416 @end defvr
417
418 @defvr {Attribute} @code{olang}
419 The output language, e.g.@: @code{en}, @code{it}, @code{es},
420 @code{de}, @code{pt-BR}.
421 @end defvr
422
423 @node SPV Structure label Element
424 @subsection The @code{label} Element
425
426 @example
427 label => TEXT
428 @end example
429
430 Every @code{heading} and @code{container} holds a @code{label} as its
431 first child.  The label text is what appears in the outline pane of
432 the GUI's viewer window.  PSPP also puts it into the outline of PDF
433 output.  The label text doesn't appear in the output itself.
434
435 The text in @code{label} describes what it labels, often by naming the
436 statistical procedure that was executed, e.g.@: ``Frequencies'' or
437 ``T-Test''.  Labels are often very generic, especially within a
438 @code{container}, e.g.@: ``Title'' or ``Warnings'' or ``Notes''.
439 Label text is localized according to the output language, e.g.@: in
440 Italian a frequency table procedure is labeled ``Frequenze''.
441
442 The user can edit labels to be anything they want.  The corpus
443 contains a few examples of empty labels, ones that contain no text,
444 probably as a result of user editing.
445
446 The root @code{heading} in an SPV file has a @code{label}, like every
447 @code{heading}.  It normally contains ``Output'' but its content is
448 disregarded anyway.  The user cannot edit it.
449
450 @node SPV Structure container Element
451 @subsection The @code{container} Element
452
453 @example
454 container
455    :visibility=(visible | hidden)
456    :page-break-before=(always)?
457    :text-align=(left | center)?
458    :width=dimension
459 => label (table | container_text | graph | model | object | image | tree)
460 @end example
461
462 A @code{container} serves to contain and label a @code{table},
463 @code{text}, or other kind of item.
464
465 This element has the following attributes.
466
467 @defvr {Attribute} @code{visibility}
468 Whether the container's content is displayed.  ``Notes'' tables are
469 often hidden; other data is usually visible.
470 @end defvr
471
472 @defvr {Attribute} @code{text-align}
473 Alignment of text within the container.  Observed with nested
474 @code{table} and @code{text} elements.
475 @end defvr
476
477 @defvr {Attribute} @code{width}
478 The width of the container, e.g.@: @code{1097px}.
479 @end defvr
480
481 All of the elements that nest inside @code{container} (except the
482 @code{label}) have the following optional attribute.
483
484 @defvr {Attribute} @code{commandName}
485 As on the @code{heading} element.  The corpus contains one example
486 of where @code{commandName} is present but set to the empty string.
487 @end defvr
488
489 @node SPV Structure text Element (Inside @code{container})
490 @subsection The @code{text} Element (Inside @code{container})
491
492 @example
493 text[container_text]
494   :type[text_type]=(title | log | text | page-title)
495   :commandName?
496   :creator-version?
497 => html
498 @end example
499
500 This @code{text} element is nested inside a @code{container}.  There
501 is a different @code{text} element that is nested inside a
502 @code{pageParagraph}.
503
504 This element has the following attributes.
505
506 @defvr {Attribute} @code{commandName}
507 @xref{SPV Structure container Element}.  For output not specific to a
508 command, this is simply @code{log}.
509 @end defvr
510
511 @defvr {Attribute} @code{type}
512 The semantics of the text.
513 @end defvr
514
515 @defvr {Attribute} @code{creator-version}
516 As on the @code{heading} element.
517 @end defvr
518
519 @node SPV Structure html Element
520 @subsection The @code{html} Element
521
522 @example
523 html :lang=(en) => TEXT
524 @end example
525
526 The element contains an HTML document as text (or, in practice, as
527 CDATA).  In some cases, the document starts with @code{<html>} and
528 ends with @code{</html>}; in others the @code{html} element is
529 implied.  Generally the HTML includes a @code{head} element with a CSS
530 stylesheet.  The HTML body often begins with @code{<BR>}.
531
532 The HTML document uses only the following elements:
533
534 @table @code
535 @item html
536 Sometimes, the document is enclosed with
537 @code{<html>}@dots{}@code{</html>}.
538
539 @item br
540 The HTML body often begins with @code{<BR>} and may contain it as well.
541
542 @item b
543 @itemx i
544 @itemx u
545 Styling.
546
547 @item font
548 The attributes @code{face}, @code{color}, and @code{size} are
549 observed.  The value of @code{color} takes one of the forms
550 @code{#@var{rr}@var{gg}@var{bb}} or @code{rgb (@var{r}, @var{g},
551 @var{b})}.  The value of @code{size} is a number between 1 and 7,
552 inclusive.
553 @end table
554
555 The CSS in the corpus is simple.  To understand it, a parser only
556 needs to be able to skip white space, @code{<!--}, and @code{-->}, and
557 parse style only for @code{p} elements.  Only the following properties
558 matter:
559
560 @table @code
561 @item color
562 In the form @code{@var{rr}@var{gg}@var{bb}}, e.g. @code{000000}, with
563 no leading @samp{#}.
564
565 @item font-weight
566 Either @code{bold} or @code{normal}.
567
568 @item font-style
569 Either @code{italic} or @code{normal}.
570
571 @item text-decoration
572 Either @code{underline} or @code{normal}.
573
574 @item font-family
575 A font name, commonly @code{Monospaced} or @code{SansSerif}.
576
577 @item font-size
578 Values claim to be in points, e.g.@: @code{14pt}, but the values are
579 actually in ``device-independent pixels'' (px), at 96/inch.
580 @end table
581
582 This element has the following attributes.
583
584 @defvr {Attribute} @code{lang}
585 This always contains @code{en} in the corpus.
586 @end defvr
587
588 @node SPV Structure table Element
589 @subsection The @code{table} Element
590
591 @example
592 table
593    :VDPId?
594    :ViZmlSource?
595    :activePageId=int?
596    :commandName
597    :creator-version?
598    :displayFiltering=bool?
599    :maxNumCells=int?
600    :orphanTolerance=int?
601    :rowBreakNumber=int?
602    :subType
603    :tableId
604    :tableLookId?
605    :type[table_type]=(table | note | warning)
606 => tableProperties? tableStructure
607
608 tableStructure => path? dataPath csvPath?
609 @end example
610
611 This element has the following attributes.
612
613 @defvr {Attribute} @code{commandName}
614 @xref{SPV Structure container Element}.
615 @end defvr
616
617 @defvr {Attribute} @code{type}
618 One of @code{table}, @code{note}, or @code{warning}.
619 @end defvr
620
621 @defvr {Attribute} @code{subType}
622 The locale-invariant command ID for the particular kind of output that
623 this table represents in the procedure.  This can be the same as
624 @code{commandName} e.g.@: @code{Frequencies}, or different, e.g.@:
625 @code{Case Processing Summary}.  Generic subtypes @code{Notes} and
626 @code{Warnings} are often used.
627 @end defvr
628
629 @defvr {Attribute} @code{tableId}
630 A number that uniquely identifies the table within the SPV file,
631 typically a large negative number such as @code{-4147135649387905023}.
632 @end defvr
633
634 @defvr {Attribute} @code{creator-version}
635 As on the @code{heading} element.  In the corpus, this is only present
636 for version 21 and up and always includes all 8 digits.
637 @end defvr
638
639 @xref{SPV Detail Legacy Properties}, for details on the
640 @code{tableProperties} element.
641
642 @node SPV Structure graph Element
643 @subsection The @code{graph} Element
644
645 @example
646 graph
647    :VDPId?
648    :ViZmlSource?
649    :commandName?
650    :creator-version?
651    :dataMapId?
652    :dataMapURI?
653    :editor?
654    :refMapId?
655    :refMapURI?
656    :csvFileIds?
657    :csvFileNames?
658 => dataPath? path csvPath?
659 @end example
660
661 This element represents a graph.  The @code{dataPath} and @code{path}
662 elements name the Zip members that give the details of the graph.
663 Normally, both elements are present; there is only one counterexample
664 in the corpus.
665
666 @code{csvPath} only appears in one SPV file in the corpus, for two
667 graphs.  In these two cases, @code{dataPath}, @code{path}, and
668 @code{csvPath} all appear.  These @code{csvPath} name Zip members with
669 names of the form @file{@var{number}_csv.bin}, where @var{number} is a
670 many-digit number and the same as the @code{csvFileIds}.  The named
671 Zip members are CSV text files (despite the @file{.bin} extension).
672 The CSV files are encoded in UTF-8 and begin with a U+FEFF byte-order
673 marker.
674
675 @node SPV Structure model Element
676 @subsection The @code{model} Element
677
678 @example
679 model
680    :PMMLContainerId?
681    :PMMLId
682    :StatXMLContainerId
683    :VDPId
684    :auxiliaryViewName
685    :commandName
686    :creator-version
687    :mainViewName
688 => ViZml? dataPath? path | pmmlContainerPath statsContainerPath
689
690 pmmlContainerPath => TEXT
691
692 statsContainerPath => TEXT
693
694 ViZml :viewName? => TEXT
695 @end example
696
697 This element represents a model.  The @code{dataPath} and @code{path}
698 elements name the Zip members that give the details of the model.
699 Normally, both elements are present; there is only one counterexample
700 in the corpus.
701
702 The details are unexplored.  The @code{ViZml} element contains base-64
703 encoded text, that decodes to a binary format with some embedded text
704 strings, and @code{path} names an Zip member that contains XML.
705 Alternatively, @code{pmmlContainerPath} and @code{statsContainerPath}
706 name Zip members with @file{.scf} extension.
707
708 @node SPV Structure object and image Elements
709 @subsection The @code{object} and @code{image} Elements
710
711 @example
712 object
713    :commandName?
714    :type[object_type]=(unknown)?
715    :uri
716 => EMPTY
717
718 image
719    :commandName?
720    :VDPId
721 => dataPath
722 @end example
723
724 These two elements represent an image in PNG format.  They are
725 equivalent and the corpus contains examples of both.  The only
726 difference is the syntax: for @code{object}, the @code{uri} attribute
727 names the Zip member that contains a PNG file; for @code{image}, the
728 text of the inner @code{dataPath} element names the Zip member.
729
730 PSPP writes @code{object} in output but there is no strong reason to
731 choose this form.
732
733 The corpus only contains PNG image files.
734
735 @node SPV Structure tree Element
736 @subsection The @code{tree} Element
737
738 @example
739 tree
740    :commandName
741    :creator-version
742    :name
743    :type
744 => dataPath path
745 @end example
746
747 This element represents a tree.  The @code{dataPath} and @code{path}
748 elements name the Zip members that give the details of the tree.
749 The details are unexplored.
750
751 @node SPV Structure Path Elements
752 @subsection Path Elements
753
754 @example
755 dataPath => TEXT
756
757 path => TEXT
758
759 csvPath => TEXT
760 @end example
761
762 These element contain the name of the Zip members that hold details
763 for a container.  For tables:
764
765 @itemize @bullet
766 @item
767 When a ``light'' format is used, only @code{dataPath} is present, and
768 it names a @file{.bin} member of the Zip file that has @code{light} in
769 its name, e.g.@: @code{0000000001437_lightTableData.bin} (@pxref{SPV
770 Light Detail Member Format}).
771
772 @item
773 When the legacy format is used, both are present.  In this case,
774 @code{dataPath} names a Zip member with a legacy binary format that
775 contains relevant data (@pxref{SPV Legacy Detail Member Binary
776 Format}), and @code{path} names a Zip member that uses an XML format
777 (@pxref{SPV Legacy Detail Member XML Format}).
778 @end itemize
779
780 Graphs normally follow the legacy approach described above.  The
781 corpus contains one example of a graph with @code{path} but not
782 @code{dataPath}.  The reason is unexplored.
783
784 Models use @code{path} but not @code{dataPath}.  @xref{SPV Structure
785 graph Element}, for more information.
786
787 These elements have no attributes.
788
789 @node SPV Structure pageSetup Element
790 @subsection The @code{pageSetup} Element
791
792 @example
793 pageSetup
794    :initial-page-number=int?
795    :chart-size=(as-is | full-height | half-height | quarter-height | OTHER)?
796    :margin-left=dimension?
797    :margin-right=dimension?
798    :margin-top=dimension?
799    :margin-bottom=dimension?
800    :paper-height=dimension?
801    :paper-width=dimension?
802    :reference-orientation?
803    :space-after=dimension?
804 => pageHeader pageFooter
805
806 pageHeader => pageParagraph?
807
808 pageFooter => pageParagraph?
809
810 pageParagraph => pageParagraph_text
811 @end example
812
813 The @code{pageSetup} element has the following attributes.
814
815 @defvr {Attribute} @code{initial-page-number}
816 The page number to put on the first page of printed output.  Usually
817 @code{1}.
818 @end defvr
819
820 @defvr {Attribute} @code{chart-size}
821 One of the listed, self-explanatory chart sizes,
822 @code{quarter-height}, or a localization (!) of one of these (e.g.@:
823 @code{dimensione attuale}, @code{Wie vorgegeben}).
824 @end defvr
825
826 @defvr {Attribute} @code{margin-left}
827 @defvrx {Attribute} @code{margin-right}
828 @defvrx {Attribute} @code{margin-top}
829 @defvrx {Attribute} @code{margin-bottom}
830 Margin sizes, e.g.@: @code{0.25in}.
831 @end defvr
832
833 @defvr {Attribute} @code{paper-height}
834 @defvrx {Attribute} @code{paper-width}
835 Paper sizes.
836 @end defvr
837
838 @defvr {Attribute} @code{reference-orientation}
839 Indicates the orientation of the output page.  Either @code{0deg}
840 (portrait) or @code{90deg} (landscape),
841 @end defvr
842
843 @defvr {Attribute} @code{space-after}
844 The amount of space between printed objects, typically @code{12pt}.
845 @end defvr
846
847 @node SPV Structure @code{text} Element (Inside @code{pageParagraph})
848 @subsection The @code{text} Element (Inside @code{pageParagraph})
849
850 @example
851 text[pageParagraph_text] :type=(title | text) => TEXT
852 @end example
853
854 This @code{text} element is nested inside a @code{pageParagraph}.  There
855 is a different @code{text} element that is nested inside a
856 @code{container}.
857
858 The element is either empty, or contains CDATA that holds almost-XHTML
859 text: in the corpus, either an @code{html} or @code{p} element.  It is
860 @emph{almost}-XHTML because the @code{html} element designates the
861 default namespace as
862 @indicateurl{http://xml.spss.com/spss/viewer/viewer-tree} instead of
863 an XHTML namespace, and because the CDATA can contain substitution
864 variables.  The following variables are supported:
865
866 @table @code
867 @item &[Date]
868 @itemx &[Time]
869 The current date or time in the preferred format for the locale.
870
871 @item &[Head1]
872 @itemx &[Head2]
873 @itemx &[Head3]
874 @itemx &[Head4]
875 First-, second-, third-, or fourth-level heading.
876
877 @item &[PageTitle]
878 The page title.
879
880 @item &[Filename]
881 Name of the output file.
882
883 @item &[Page]
884 The page number.
885 @end table
886
887 @code{&[Page]} for the page number and @code{&[PageTitle]} for the
888 page title.
889
890 Typical contents (indented for clarity):
891
892 @example
893 <html xmlns="http://xml.spss.com/spss/viewer/viewer-tree">
894     <head></head>
895     <body>
896         <p style="text-align:right; margin-top: 0">Page &[Page]</p>
897     </body>
898 </html>
899 @end example
900
901 This element has the following attributes.
902
903 @defvr {Attribute} @code{type}
904 Always @code{text}.
905 @end defvr
906
907 @node SPV Light Detail Member Format
908 @section Light Detail Member Format
909
910 This section describes the format of ``light'' detail @file{.bin}
911 members.  These members have a binary format which we describe here in
912 terms of a context-free grammar using the following conventions:
913
914 @table @asis
915 @item NonTerminal @result{} @dots{}
916 Nonterminals have CamelCaps names, and @result{} indicates a
917 production.  The right-hand side of a production is often broken
918 across multiple lines.  Break points are chosen for aesthetics only
919 and have no semantic significance.
920
921 @item 00, 01, @dots{}, ff.
922 A bytes with a fixed value, written as a pair of hexadecimal digits.
923
924 @item i0, i1, @dots{}, i9, i10, i11, @dots{}
925 @itemx ib0, ib1, @dots{}, ib9, ib10, ib11, @dots{}
926 A 32-bit integer in little-endian or big-endian byte order,
927 respectively, with a fixed value, written in decimal.  Prefixed by
928 @samp{i} for little-endian or @samp{ib} for big-endian.
929
930 @item byte
931 A byte.
932
933 @item bool
934 A byte with value 0 or 1.
935
936 @item int16
937 @itemx be16
938 A 16-bit unsigned integer in little-endian or big-endian byte order,
939 respectively.
940
941 @item int32
942 @itemx be32
943 A 32-bit unsigned integer in little-endian or big-endian byte order,
944 respectively.
945
946 @item int64
947 @itemx be64
948 A 64-bit unsigned integer in little-endian or big-endian byte order,
949 respectively.
950
951 @item double
952 A 64-bit IEEE floating-point number.
953
954 @item float
955 A 32-bit IEEE floating-point number.
956
957 @item string
958 @itemx bestring
959 A 32-bit unsigned integer, in little-endian or big-endian byte order,
960 respectively, followed by the specified number of bytes of character
961 data.  (The encoding is indicated by the Formats nonterminal.)
962
963 @item @var{x}?
964 @var{x} is optional, e.g.@: 00? is an optional zero byte.
965
966 @item @var{x}*@var{n}
967 @var{x} is repeated @var{n} times, e.g.@: byte*10 for ten arbitrary bytes.
968
969 @item @var{x}[@var{name}]
970 Gives @var{x} the specified @var{name}.  Names are used in textual
971 explanations.  They are also used, also bracketed, to indicate counts,
972 e.g.@: @code{int32[n] byte*[n]} for a 32-bit integer followed by the
973 specified number of arbitrary bytes.
974
975 @item @var{a} @math{|} @var{b}
976 Either @var{a} or @var{b}.
977
978 @item (@var{x})
979 Parentheses are used for grouping to make precedence clear, especially
980 in the presence of @math{|}, e.g.@: in 00 (01 @math{|} 02 @math{|} 03)
981 00.
982
983 @item count(@var{x})
984 @itemx becount(@var{x})
985 A 32-bit unsigned integer, in little-endian or big-endian byte order,
986 respectively, that indicates the number of bytes in @var{x}, followed
987 by @var{x} itself.
988
989 @item v1(@var{x})
990 In a version 1 @file{.bin} member, @var{x}; in version 3, nothing.
991 (The @file{.bin} header indicates the version.)
992
993 @item v3(@var{x})
994 In a version 3 @file{.bin} member, @var{x}; in version 1, nothing.
995 @end table
996
997 PSPP uses this grammar to parse light detail members.  See
998 @file{src/output/spv/light-binary.grammar} in the PSPP source tree for
999 the full grammar.
1000
1001 Little-endian byte order is far more common in this format, but a few
1002 pieces of the format use big-endian byte order.
1003
1004 Light detail members express linear units in two ways: points (pt), at
1005 72/inch, and ``device-independent pixels'' (px), at 96/inch.  To
1006 convert from pt to px, multiply by 1.33 and round up.  To convert
1007 from px to pt, divide by 1.33 and round down.
1008
1009 A ``light'' detail member @file{.bin} consists of a number of sections
1010 concatenated together, terminated by an optional byte 01:
1011
1012 @example
1013 Table =>
1014     Header Titles Footnotes
1015     Areas Borders PrintSettings TableSettings Formats
1016     Dimensions Axes Cells
1017     01?
1018 @end example
1019
1020 The following sections go into more detail.
1021
1022 @menu
1023 * SPV Light Member Header::
1024 * SPV Light Member Titles::
1025 * SPV Light Member Footnotes::
1026 * SPV Light Member Areas::
1027 * SPV Light Member Borders::
1028 * SPV Light Member Print Settings::
1029 * SPV Light Member Table Settings::
1030 * SPV Light Member Formats::
1031 * SPV Light Member Dimensions::
1032 * SPV Light Member Categories::
1033 * SPV Light Member Axes::
1034 * SPV Light Member Cells::
1035 * SPV Light Member Value::
1036 * SPV Light Member ValueMod::
1037 @end menu
1038
1039 @node SPV Light Member Header
1040 @subsection Header
1041
1042 An SPV light member begins with a 39-byte header:
1043
1044 @example
1045 Header =>
1046     01 00
1047     (i1 @math{|} i3)[version]
1048     bool[x0]
1049     bool[x1]
1050     bool[rotate-inner-column-labels]
1051     bool[rotate-outer-row-labels]
1052     bool[x2]
1053     int32[x3]
1054     int32[min-col-width] int32[max-col-width]
1055     int32[min-row-width] int32[max-row-width]
1056     int64[table-id]
1057 @end example
1058
1059 @code{version} is a version number that affects the interpretation of
1060 some of the other data in the member.  We will refer to ``version 1''
1061 and ``version 3'' later on and use v1(@dots{}) and v3(@dots{}) for
1062 version-specific formatting (as described previously).
1063
1064 If @code{rotate-inner-column-labels} is 1, then column labels closest
1065 to the data are rotated 90° counterclockwise; otherwise, they are
1066 shown in the normal way.
1067
1068 If @code{rotate-outer-row-labels} is 1, then row labels farthest from
1069 the data are rotated 90° counterclockwise; otherwise, they are shown
1070 in the normal way.
1071
1072 @code{min-col-width} is the minimum width that a column will be
1073 assigned automatically.  @code{max-col-width} is the maximum width
1074 that a column will be assigned to accommodate a long column label.
1075 @code{min-row-width} and @code{max-row-width} are a similar range for
1076 the width of row labels.  All of these measurements are in 1/96 inch
1077 units (called a ``device independent pixel'' unit in Windows).
1078
1079 @code{table-id} is a binary version of the @code{tableId} attribute in
1080 the structure member that refers to the detail member.  For example,
1081 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
1082 would be 0xc6c99d183b300001.
1083
1084 The meaning of the other variable parts of the header is not known.  A
1085 writer may safely use version 3, true for @code{x0}, false for
1086 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
1087
1088 @node SPV Light Member Titles
1089 @subsection Titles
1090
1091 @example
1092 Titles =>
1093     Value[title] 01?
1094     Value[subtype] 01? 31
1095     Value[user-title] 01?
1096     (31 Value[corner-text] @math{|} 58)
1097     (31 Value[caption] @math{|} 58)
1098 @end example
1099
1100 The Titles follow the Header and specify the table's title, caption,
1101 and corner text.
1102
1103 The @code{user-title} reflects any user
1104 editing of the title text or style.  The @code{title} is the title
1105 originally generated by the procedure.  Both of these are appropriate
1106 for presentation and localized to the user's language.  For example,
1107 for a frequency table, @code{title} and @code{user-title} normally
1108 name the variable and @code{c} is simply ``Frequencies''.
1109
1110 @code{subtype} is the same as the @code{subType} attribute in the
1111 @code{table} structure XML element that referred to this member.
1112 @xref{SPV Structure table Element}, for details.
1113
1114 The @code{corner-text}, if present, is shown in the upper-left corner
1115 of the table, above the row headings and to the left of the column
1116 headings.  It is usually absent.  When row dimension labels are
1117 displayed in the corner (see @code{show-row-labels-in-corner}), corner
1118 text is hidden.
1119
1120 The @code{caption}, if present, is shown below the table.
1121 @code{caption} reflects user editing of the caption.
1122
1123 @node SPV Light Member Footnotes
1124 @subsection Footnotes
1125
1126 @example
1127 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
1128 Footnote => Value[text] (58 @math{|} 31 Value[marker]) int32[show]
1129 @end example
1130
1131 Each footnote has @code{text} and an optional custom @code{marker}
1132 (such as @samp{*}).
1133
1134 The syntax for Value would allow footnotes (and their markers) to
1135 reference other footnotes, but in practice this doesn't work.
1136
1137 @code{show} is a 32-bit signed integer.  It is positive to show the
1138 footnote or negative to hide it.  Its magnitude is often 1, and in
1139 other cases tends to be the number of references to the footnote.
1140 It is safe to write 1 to show a footnote and -1 to hide it.
1141
1142 @node SPV Light Member Areas
1143 @subsection Areas
1144
1145 @example
1146 Areas => 00? Area*8
1147 Area =>
1148     byte[index] 31
1149     string[typeface] float[size] int32[style] bool[underline]
1150     int32[halign] int32[valign]
1151     string[fg-color] string[bg-color]
1152     bool[alternate] string[alt-fg-color] string[alt-bg-color]
1153     v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1154 @end example
1155
1156 Each Area represents the style for a different area of the table, in
1157 the following order: title, caption, footer, corner, column labels,
1158 row labels, data, and layers.
1159
1160 @code{index} is the 1-based index of the Area, i.e.@: 1 for the first
1161 Area, through 8 for the final Area.
1162
1163 @code{typeface} is the string name of the font used in the area.  In
1164 the corpus, this is @code{SansSerif} in over 99% of instances and
1165 @code{Times New Roman} in the rest.
1166
1167 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1168 Member Format}). The most common size in the corpus is 12 px.  Even
1169 though @code{size} has a floating-point type, in the corpus its values
1170 are always integers.
1171
1172 @code{style} is a bit mask.  Bit 0 (with value 1) is set for bold, bit
1173 1 (with value 2) is set for italic.
1174
1175 @code{underline} is 1 if the font is underlined, 0 otherwise.
1176
1177 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1178 left, 4 for right, 61453 for decimal, 64173 for mixed.  Mixed
1179 alignment varies according to type: string data is left-justified,
1180 numbers and most other formats are right-justified.
1181
1182 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1183 for bottom.
1184
1185 @code{fg-color} and @code{bg-color} are the foreground color and
1186 background color, respectively.  In the corpus, these are always
1187 @code{#000000} and @code{#ffffff}, respectively.
1188
1189 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1190 should be the same color.  When @code{alternate} is 1,
1191 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1192 alternate rows; otherwise they are empty strings.
1193
1194 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1195 @code{bottom-margin} are measured in px.
1196
1197 @node SPV Light Member Borders
1198 @subsection Borders
1199
1200 @example
1201 Borders =>
1202     count(
1203         ib1[endian]
1204         be32[n-borders] Border*[n-borders]
1205         bool[show-grid-lines]
1206         00 00 00)
1207
1208 Border =>
1209     be32[border-type]
1210     be32[stroke-type]
1211     be32[color]
1212 @end example
1213
1214 The Borders reflect how borders between regions are drawn.
1215
1216 The fixed value of @code{endian} can be used to validate the
1217 endianness.
1218
1219 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1220
1221 Each Border describes one kind of border.  @code{n-borders} seems to
1222 always be 19.  Each @code{border-type} appears once (although in an
1223 unpredictable order) and correspond to the following borders:
1224
1225 @table @asis
1226 @item 0
1227 Title.
1228 @item 1@dots{}4
1229 Left, top, right, and bottom outer frame.
1230 @item 5@dots{}8
1231 Left, top, right, and bottom inner frame.
1232 @item 9, 10
1233 Left and top of data area.
1234 @item 11, 12
1235 Horizontal and vertical dimension rows.
1236 @item 13, 14
1237 Horizontal and vertical dimension columns.
1238 @item 15, 16
1239 Horizontal and vertical category rows.
1240 @item 17, 18
1241 Horizontal and vertical category columns.
1242 @end table
1243
1244 @code{stroke-type} describes how a border is drawn, as one of:
1245
1246 @table @asis
1247 @item 0
1248 No line.
1249 @item 1
1250 Solid line.
1251 @item 2
1252 Dashed line.
1253 @item 3
1254 Thick line.
1255 @item 4
1256 Thin line.
1257 @item 5
1258 Double line.
1259 @end table
1260
1261 @code{color} is an RGB color.  Bits 24--31 are alpha, bits 16--23 are
1262 red, 8--15 are green, 0--7 are blue.  An alpha of 255 indicates an
1263 opaque color, therefore opaque black is 0xff000000.
1264
1265 @node SPV Light Member Print Settings
1266 @subsection Print Settings
1267
1268 @example
1269 PrintSettings =>
1270     count(
1271         ib1[endian]
1272         bool[all-layers]
1273         bool[paginate-layers]
1274         bool[fit-width]
1275         bool[fit-length]
1276         bool[top-continuation]
1277         bool[bottom-continuation]
1278         be32[n-orphan-lines]
1279         bestring[continuation-string])
1280 @end example
1281
1282 The PrintSettings reflect settings for printing.  The fixed value of
1283 @code{endian} can be used to validate the endianness.
1284
1285 @code{all-layers} is 1 to print all layers, 0 to print only the layer
1286 designated by @code{current-layer} in TableSettings (@pxref{SPV Light
1287 Member Table Settings}).
1288
1289 @code{paginate-layers} is 1 to print each layer at the start of a new
1290 page, 0 otherwise.  (This setting is honored only @code{all-layers} is
1291 1, since otherwise only one layer is printed.)
1292
1293 @code{fit-width} and @code{fit-length} control whether the table is
1294 shrunk to fit within a page's width or length, respectively.
1295
1296 @code{n-orphan-lines} is the minimum number of rows or columns to put
1297 in one part of a table that is broken across pages.
1298
1299 If @code{top-continuation} is 1, then @code{continuation-string} is
1300 printed at the top of a page when a table is broken across pages for
1301 printing; similarly for @code{bottom-continuation} and the bottom of a
1302 page.  Usually, @code{continuation-string} is empty.
1303
1304 @node SPV Light Member Table Settings
1305 @subsection Table Settings
1306
1307 @example
1308 TableSettings =>
1309     count(
1310       v3(
1311         ib1[endian]
1312         be32[x5]
1313         be32[current-layer]
1314         bool[omit-empty]
1315         bool[show-row-labels-in-corner]
1316         bool[show-alphabetic-markers]
1317         bool[footnote-marker-superscripts]
1318         byte[x6]
1319         becount(
1320           Breakpoints[row-breaks] Breakpoints[column-breaks]
1321           Keeps[row-keeps] Keeps[column-keeps]
1322           PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1323         )
1324         bestring[notes]
1325         bestring[table-look]
1326         )...)
1327
1328 Breakpoints => be32[n-breaks] be32*[n-breaks]
1329
1330 Keeps => be32[n-keeps] Keep*[n-keeps]
1331 Keep => be32[offset] be32[n]
1332
1333 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1334 PointKeep => be32[offset] be32 be32
1335 @end example
1336
1337 The TableSettings reflect display settings.  The fixed value of
1338 @code{endian} can be used to validate the endianness.
1339
1340 @code{current-layer} is the displayed layer.  Suppose there are
1341 @math{d} layers, numbered 1 through @math{d} in the order given in the
1342 Dimensions (@pxref{SPV Light Member Dimensions}), and that the
1343 displayed value of dimension @math{i} is @math{d_i}, @math{0 \le x_i <
1344 n_i}, where @math{n_i} is the number of categories in dimension
1345 @math{i}.  Then @code{current-layer} is calculated by the following
1346 algorithm:
1347
1348 @display
1349 let @code{current-layer} = 0
1350 for each @math{i} from @math{d} downto 1:
1351     @code{current-layer} = (@math{n_i \times} @code{current-layer}) @math{+} @math{x_i}
1352 @end display
1353
1354 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1355 any cell) are hidden; otherwise, they are shown.
1356
1357 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1358 the upper left corner; otherwise, they are shown nested.
1359
1360 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1361 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1362 shown as numbers starting from 1.
1363
1364 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1365 as superscripts, otherwise as subscripts.
1366
1367 The Breakpoints are rows or columns after which there is a page break;
1368 for example, a row break of 1 requests a page break after the second
1369 row.  Usually no breakpoints are specified, indicating that page
1370 breaks should be selected automatically.
1371
1372 The Keeps are ranges of rows or columns to be kept together without a
1373 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1374 10 requests that the 10 rows starting with the second row be kept
1375 together.  Usually no Keeps are specified.
1376
1377 The PointKeeps seem to be generated automatically based on
1378 user-specified Keeps.  They seems to indicate a conversion from rows
1379 or columns to pixel or point offsets.
1380
1381 @code{notes} is a text string that contains user-specified notes.  It
1382 is displayed when the user hovers the cursor over the table, like text
1383 in the @code{title} attribute in HTML@.  It is not printed.  It is
1384 usually empty.
1385
1386 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1387 such as ``Default'' or ``Academic''; it is often empty.
1388
1389 TableSettings ends with an arbitrary number of null bytes.  A writer
1390 may safely write 82 null bytes.
1391
1392 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1393
1394 @node SPV Light Member Formats
1395 @subsection Formats
1396
1397 @example
1398 Formats =>
1399     int32[n-widths] int32*[n-widths]
1400     string[locale]
1401     int32[current-layer]
1402     bool[x7] bool[x8] bool[x9]
1403     Y0
1404     CustomCurrency
1405     count(
1406       v1(X0?)
1407       v3(count(X1 count(X2)) count(X3)))
1408 Y0 => int32[epoch] byte[decimal] byte[grouping]
1409 CustomCurrency => int32[n-ccs] string*[n-ccs]
1410 @end example
1411
1412 If @code{n-widths} is nonzero, then the accompanying integers are
1413 column widths as manually adjusted by the user.
1414
1415 @code{locale} is a locale including an encoding, such as
1416 @code{en_US.windows-1252} or @code{it_IT.windows-1252}.
1417 (@code{locale} is often duplicated in Y1, described below).
1418
1419 @code{epoch} is the year that starts the epoch.  A 2-digit year is
1420 interpreted as belonging to the 100 years beginning at the epoch.  The
1421 default epoch year is 69 years prior to the current year; thus, in
1422 2017 this field by default contains 1948.  In the corpus, @code{epoch}
1423 ranges from 1943 to 1948, plus some contain -1.
1424
1425 @code{decimal} is the decimal point character.  The observed values
1426 are @samp{.} and @samp{,}.
1427
1428 @code{grouping} is the grouping character.  Usually, it is @samp{,} if
1429 @code{decimal} is @samp{.}, and vice versa.  Other observed values are
1430 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1431 indicating that digits should not be grouped).
1432
1433 @code{n-ccs} is observed as either 0 or 5.  When it is 5, the
1434 following strings are CCA through CCE format strings.  @xref{Custom
1435 Currency Formats,,, pspp, PSPP}.  Most commonly these are all
1436 @code{-,,,} but other strings occur.
1437
1438 A writer may safely use false for @code{x7}, @code{x8}, and @code{x9}.
1439
1440 @subsubheading X0
1441
1442 X0 only appears, optionally, in version 1 members.
1443
1444 @example
1445 X0 => byte*14 Y1 Y2
1446 Y1 =>
1447     string[command] string[command-local]
1448     string[language] string[charset] string[locale]
1449     bool[x10] bool[include-leading-zero] bool[x12] bool[x13]
1450     Y0
1451 Y2 => CustomCurrency byte[missing] bool[x17]
1452 @end example
1453
1454 @code{command} describes the statistical procedure that generated the
1455 output, in English.  It is not necessarily the literal syntax name of
1456 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1457 Tests.''  @code{command-local} is the procedure's name, translated
1458 into the output language; it is often empty and, when it is not,
1459 sometimes the same as @code{command}.
1460
1461 @code{include-leading-zero} is the @code{LEADZERO} setting for the
1462 table, where false is @code{OFF} (the default) and true is @code{ON}.
1463 @xref{SET LEADZERO,,, pspp, PSPP}.
1464
1465 @code{missing} is the character used to indicate that a cell contains
1466 a missing value.  It is always observed as @samp{.}.
1467
1468 A writer may safely use false for @code{x10} and @code{x17} and true
1469 for @code{x12} and @code{x13}.
1470
1471 @subsubheading X1
1472
1473 X1 only appears in version 3 members.
1474
1475 @example
1476 X1 =>
1477     bool[x14]
1478     byte[show-title]
1479     bool[x16]
1480     byte[lang]
1481     byte[show-variables]
1482     byte[show-values]
1483     int32[x18] int32[x19]
1484     00*17
1485     bool[x20]
1486     bool[show-caption]
1487 @end example
1488
1489 @code{lang} may indicate the language in use.  Some values seem to be
1490 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1491 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}.
1492
1493 @code{show-variables} determines how variables are displayed by
1494 default.  A value of 1 means to display variable names, 2 to display
1495 variable labels when available, 3 to display both (name followed by
1496 label, separated by a space).  The most common value is 0, which
1497 probably means to use a global default.
1498
1499 @code{show-values} is a similar setting for values.  A value of 1
1500 means to display the value, 2 to display the value label when
1501 available, 3 to display both.  Again, the most common value is 0,
1502 which probably means to use a global default.
1503
1504 @code{show-title} is 1 to show the caption, 10 to hide it.
1505
1506 @code{show-caption} is true to show the caption, false to hide it.
1507
1508 A writer may safely use false for @code{x14}, false for @code{x16}, 0
1509 for @code{lang}, -1 for @code{x18} and @code{x19}, and false for
1510 @code{x20}.
1511
1512 @subsubheading X2
1513
1514 X2 only appears in version 3 members.
1515
1516 @example
1517 X2 =>
1518     int32[n-row-heights] int32*[n-row-heights]
1519     int32[n-style-map] StyleMap*[n-style-map]
1520     int32[n-styles] StylePair*[n-styles]
1521     count((i0 i0)?)
1522 StyleMap => int64[cell-index] int16[style-index]
1523 @end example
1524
1525 If present, @code{n-row-heights} and the accompanying integers are row
1526 heights as manually adjusted by the user.
1527
1528 The rest of X2 specifies styles for data cells.  At first glance this
1529 is odd, because each data cell can have its own style embedded as part
1530 of the data, but in practice X2 specifies a style for a cell only if
1531 that cell is empty (and thus does not appear in the data at all).
1532 Each StyleMap specifies the index of a blank cell, calculated the same
1533 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1534 0-based index into the accompanying StylePair array.
1535
1536 A writer may safely omit the optional @code{i0 i0} inside the
1537 @code{count(@dots{})}.
1538
1539 @subsubheading X3
1540
1541 X3 only appears in version 3 members.
1542
1543 @example
1544 X3 =>
1545     01 00 byte[x21] 00 00 00
1546     Y1
1547     double[small] 01
1548     (string[dataset] string[datafile] i0 int32[date] i0)?
1549     Y2
1550     (int32[x22] i0)?
1551 @end example
1552
1553 @code{small} is a small real number.  In the corpus, it overwhelmingly
1554 takes the value 0.0001, with zero occasionally seen.  Nonzero numbers
1555 with format 40 (@pxref{SPV Light Member Value}) whose magnitudes are
1556 smaller than displayed in scientific notation.  (Thus, a @code{small}
1557 of zero prevents scientific notation from being chosen.)
1558
1559 @code{dataset} is the name of the dataset analyzed to produce the
1560 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1561 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}.  The latter
1562 is sometimes the empty string.
1563
1564 @code{date} is a date, as seconds since the epoch, i.e.@: since
1565 January 1, 1970.  Pivot tables within an SPV file often have dates a
1566 few minutes apart, so this is probably a creation date for the table
1567 rather than for the file.
1568
1569 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1570 and other times they are absent.  The reader can distinguish by
1571 assuming that they are present and then checking whether the
1572 presumptive @code{dataset} contains a null byte (a valid string never
1573 will).
1574
1575 @code{x22} is usually 0 or 2000000.
1576
1577 A writer may safely use 4 for @code{x21} and omit @code{x22} and the
1578 other optional bytes at the end.
1579
1580 @subsubheading Encoding
1581
1582 Formats contains several indications of character encoding:
1583
1584 @itemize @bullet
1585 @item
1586 @code{locale} in Formats itself.
1587
1588 @item
1589 @code{locale} in Y1 (in version 1, Y1 is optionally nested inside X0;
1590 in version 3, Y1 is nested inside X3).
1591
1592 @item
1593 @code{charset} in version 3, in Y1.
1594
1595 @item
1596 @code{lang} in X1, in version 3.
1597 @end itemize
1598
1599 @code{charset}, if present, is a good indication of character
1600 encoding, and in its absence the encoding suffix on @code{locale} in
1601 Formats will work.
1602
1603 @code{locale} in Y1 can be disregarded: it is normally the same as
1604 @code{locale} in Formats, and it is only present if @code{charset} is
1605 also.
1606
1607 @code{lang} is not helpful and should be ignored for character
1608 encoding purposes.
1609
1610 However, the corpus contains many examples of light members whose
1611 strings are encoded in UTF-8 despite declaring some other character
1612 set.  Furthermore, the corpus contains several examples of light
1613 members in which some strings are encoded in UTF-8 (and contain
1614 multibyte characters) and other strings are encoded in another
1615 character set (and contain non-ASCII characters).  PSPP treats any
1616 valid UTF-8 string as UTF-8 and only falls back to the declared
1617 encoding for strings that are not valid UTF-8.
1618
1619 The @command{pspp-output} program's @command{strings} command can help
1620 analyze the encoding in an SPV light member.  Use @code{pspp-output
1621 --help-dev} to see its usage.
1622
1623 @node SPV Light Member Dimensions
1624 @subsection Dimensions
1625
1626 A pivot table presents multidimensional data.  A Dimension identifies
1627 the categories associated with each dimension.
1628
1629 @example
1630 Dimensions => int32[n-dims] Dimension*[n-dims]
1631 Dimension =>
1632     Value[name] DimProperties
1633     int32[n-categories] Category*[n-categories]
1634 DimProperties =>
1635     byte[x1]
1636     byte[x2]
1637     int32[x3]
1638     bool[hide-dim-label]
1639     bool[hide-all-labels]
1640     01 int32[dim-index]
1641 @end example
1642
1643 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1644 @code{Statistics}, or a variable name.
1645
1646 The meanings of @code{x1} and @code{x3} are unknown.  @code{x1} is
1647 usually 0 but many other values have been observed.  A writer may
1648 safely use 0 for @code{x1} and 2 for @code{x3}.
1649
1650 @code{x2} is 0, 1, or 2.  For a pivot table with @var{L} layer
1651 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1652 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1653 @var{R} dimensions, and 1 for the remaining @var{C} dimensions.  This
1654 does not mean that the layer dimensions must be presented first,
1655 followed by the row dimensions, followed by the column dimensions---on
1656 the contrary, they are frequently in a different order---but @code{x2}
1657 must follow this pattern to prevent the pivot table from being
1658 misinterpreted.
1659
1660 If @code{hide-dim-label} is 00, the pivot table displays a label for
1661 the dimension itself.  Because usually the group and category labels
1662 are enough explanation, it is usually 01.
1663
1664 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1665 the dimension, including group and category labels.  It is usually 00.
1666 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1667
1668 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1669 0 for the first dimension, 1 for the second, and so on.  Sometimes it
1670 is -1.  There is no visible difference.  A writer may safely use the
1671 0-based index.
1672
1673 @node SPV Light Member Categories
1674 @subsection Categories
1675
1676 Categories are arranged in a tree.  Only the leaf nodes in the tree
1677 are really categories; the others just serve as grouping constructs.
1678
1679 @example
1680 Category => Value[name] (Leaf @math{|} Group)
1681 Leaf => 00 00 00 i2 int32[leaf-index] i0
1682 Group =>
1683     bool[merge] 00 01 int32[x23]
1684     i-1 int32[n-subcategories] Category*[n-subcategories]
1685 @end example
1686
1687 @code{name} is the name of the category (or group).
1688
1689 A Leaf represents a leaf category.  The Leaf's @code{leaf-index} is a
1690 nonnegative integer unique within the Dimension and less than
1691 @code{n-categories} in the Dimension.  If the user does not sort or
1692 rearrange the categories, then @code{leaf-index} starts at 0 for the
1693 first Leaf in the dimension and increments by 1 with each successive
1694 Leaf.  If the user does sorts or rearrange the categories, then the
1695 order of categories in the file reflects that change and
1696 @code{leaf-index} reflects the original order.
1697
1698 A dimension can have no leaf categories at all.  A table that
1699 contains such a dimension necessarily has no data at all.
1700
1701 A Group is a group of nested categories.  Usually a Group contains at
1702 least one Category, so that @code{n-subcategories} is positive, but
1703 Groups with zero subcategories have been observed.
1704
1705 If a Group's @code{merge} is 00, the most common value, then the group
1706 is really a distinct group that should be represented as such in the
1707 visual representation and user interface.  If @code{merge} is 01, the
1708 categories in this group should be shown and treated as if they were
1709 direct children of the group's containing group (or if it has no
1710 parent group, then direct children of the dimension), and this group's
1711 name is irrelevant and should not be displayed.  (Merged groups can be
1712 nested!)
1713
1714 Writers need not use merged groups.
1715
1716 A Group's @code{x23} appears to be i2 when all of the categories
1717 within a group are leaf categories that directly represent data values
1718 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1719 of values in a variable being tabulated) and i0 otherwise.  A writer
1720 may safely write a constant 0 in this field.
1721
1722 @node SPV Light Member Axes
1723 @subsection Axes
1724
1725 After the dimensions come assignment of each dimension to one of the
1726 axes: layers, rows, and columns.
1727
1728 @example
1729 Axes =>
1730     int32[n-layers] int32[n-rows] int32[n-columns]
1731     int32*[n-layers] int32*[n-rows] int32*[n-columns]
1732 @end example
1733
1734 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1735 each specifies the number of dimensions displayed in layers, rows, and
1736 columns, respectively.  Any of them may be zero.  Their values sum to
1737 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1738 Dimensions}).
1739
1740 The following @code{n-dimensions} integers, in three groups, are a
1741 permutation of the 0-based dimension numbers.  The first
1742 @code{n-layers} integers specify each of the dimensions represented by
1743 layers, the next @code{n-rows} integers specify the dimensions
1744 represented by rows, and the final @code{n-columns} integers specify
1745 the dimensions represented by columns.  When there is more than one
1746 dimension of a given kind, the inner dimensions are given first.  (For
1747 the layer axis, this means that the first dimension is at the bottom
1748 of the list and the last dimension is at the top when the current
1749 layer is displayed.)
1750
1751 @node SPV Light Member Cells
1752 @subsection Cells
1753
1754 The final part of an SPV light member contains the actual data.
1755
1756 @example
1757 Cells => int32[n-cells] Cell*[n-cells]
1758 Cell => int64[index] v1(00?) Value
1759 @end example
1760
1761 A Cell consists of an @code{index} and a Value.  Suppose there are
1762 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1763 the Dimensions previously, and that dimension @math{i} has @math{n_i}
1764 categories.  Consider the cell at coordinates @math{x_i}, @math{1 \le
1765 i \le d}, and note that @math{0 \le x_i < n_i}.  Then the index is
1766 calculated by the following algorithm:
1767
1768 @display
1769 let @i{index} = 0
1770 for each @math{i} from 1 to @math{d}:
1771     @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1772 @end display
1773
1774 For example, suppose there are 3 dimensions with 3, 4, and 5
1775 categories, respectively.  The cell at coordinates (1, 2, 3) has
1776 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1777 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1778
1779 @node SPV Light Member Value
1780 @subsection Value
1781
1782 Value is used throughout the SPV light member format.  It boils down
1783 to a number or a string.
1784
1785 @example
1786 Value => 00? 00? 00? 00? RawValue
1787 RawValue =>
1788     01 ValueMod int32[format] double[x]
1789   @math{|} 02 ValueMod int32[format] double[x]
1790     string[var-name] string[value-label] byte[show]
1791   @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1792   @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1793     byte[show] string[s]
1794   @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1795   @math{|} 06 string[local] ValueMod string[id] string[c]
1796   @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1797 Argument =>
1798     i0 Value
1799   @math{|} int32[x] i0 Value*[x]      /* x > 0 */
1800 @end example
1801
1802 There are several possible encodings, which one can distinguish by the
1803 first nonzero byte in the encoding.
1804
1805 @table @asis
1806 @item 01
1807 The numeric value @code{x}, intended to be presented to the user
1808 formatted according to @code{format}, which is about the same as the
1809 format described for system files (@pxref{System File Output
1810 Formats}).  The exception is that format 40 is not MTIME but instead
1811 approximately a synonym for F format with a different rule for whether
1812 a value is shown in scientific notation: a value in format 40 is shown
1813 in scientific notation if and only if it is nonzero and its magnitude
1814 is less than @code{small} (@pxref{SPV Light Member Formats}).
1815
1816 Most commonly, @code{format} has width 40 (the maximum).
1817
1818 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1819 represents the system-missing value SYSMIS.  (HIGHEST and LOWEST have
1820 not been observed.)  See @ref{System File Format}, for more about
1821 these special values.
1822
1823 @item 02
1824 Similar to @code{01}, with the additional information that @code{x} is
1825 a value of variable @code{var-name} and has value label
1826 @code{value-label}.  Both @code{var-name} and @code{value-label} can
1827 be the empty string, the latter very commonly.
1828
1829 @code{show} determines whether to show the numeric value or the value
1830 label.  A value of 1 means to show the value, 2 to show the label, 3
1831 to show both, and 0 means to use the default specified in
1832 @code{show-values} (@pxref{SPV Light Member Formats}).
1833
1834 @item 03
1835 A text string, in two forms: @code{c} is in English, and sometimes
1836 abbreviated or obscure, and @code{local} is localized to the user's
1837 locale.  In an English-language locale, the two strings are often the
1838 same, and in the cases where they differ, @code{local} is more
1839 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1840 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1841 where P must be greater than 1.''
1842
1843 @code{c} and @code{local} are always either both empty or both
1844 nonempty.
1845
1846 @code{id} is a brief identifying string whose form seems to resemble a
1847 programming language identifier, e.g.@: @code{cumulative_percent} or
1848 @code{factor_14}.  It is not unique.
1849
1850 @code{fixed} is 00 for text taken from user input, such as syntax
1851 fragment, expressions, file names, data set names, and 01 for fixed
1852 text strings such as names of procedures or statistics.  In the former
1853 case, @code{id} is always the empty string; in the latter case,
1854 @code{id} is still sometimes empty.
1855
1856 @item 04
1857 The string value @code{s}, intended to be presented to the user
1858 formatted according to @code{format}.  The format for a string is not
1859 too interesting, and the corpus contains many clearly invalid formats
1860 like A16.39 or A255.127 or A134.1, so readers should probably entirely
1861 disregard the format.  PSPP only checks @code{format} to distinguish
1862 AHEX format.
1863
1864 @code{s} is a value of variable @code{var-name} and has value label
1865 @code{value-label}.  @code{var-name} is never empty but
1866 @code{value-label} is commonly empty.
1867
1868 @code{show} has the same meaning as in the encoding for 02.
1869
1870 @item 05
1871 Variable @code{var-name} with variable label @code{var-label}.  In the
1872 corpus, @code{var-name} is rarely empty and @code{var-label} is often
1873 empty.
1874
1875 @code{show} determines whether to show the variable name or the
1876 variable label.  A value of 1 means to show the name, 2 to show the
1877 label, 3 to show both, and 0 means to use the default specified in
1878 @code{show-variables} (@pxref{SPV Light Member Formats}).
1879
1880 @item 06
1881 Similar to type 03, with @code{fixed} assumed to be true.
1882
1883 @item otherwise
1884 When the first byte of a RawValue is not one of the above, the
1885 RawValue starts with a ValueMod, whose syntax is described in the next
1886 section.  (A ValueMod always begins with byte 31 or 58.)
1887
1888 This case is a template string, analogous to @code{printf}, followed
1889 by one or more Arguments, each of which has one or more values.  The
1890 template string is copied directly into the output except for the
1891 following special syntax,
1892
1893 @table @code
1894 @item \%
1895 @itemx \:
1896 @itemx \[
1897 @itemx \]
1898 Each of these expands to the character following @samp{\\}, to escape
1899 characters that have special meaning in template strings.  These are
1900 effective inside and outside the @code{[@dots{}]}  syntax forms
1901 described below.
1902
1903 @item \n
1904 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1905 described below.
1906
1907 @item ^@var{i}
1908 Expands to a formatted version of argument @var{i}, which must have
1909 only a single value.  For example, @code{^1} expands to the first
1910 argument's @code{value}.
1911
1912 @item [:@var{a}:]@var{i}
1913 Expands @var{a} for each of the values in @var{i}.  @var{a}
1914 should contain one or more @code{^@var{j}} conversions, which are
1915 drawn from the values for argument @var{i} in order.  Some examples
1916 from the corpus:
1917
1918 @table @code
1919 @item [:^1:]1
1920 All of the values for the first argument, concatenated.
1921
1922 @item [:^1\n:]1
1923 Expands to the values for the first argument, each followed by
1924 a new-line.
1925
1926 @item [:^1 = ^2:]2
1927 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1928 argument's first value and @var{y} is its second value.  (This would
1929 be used only if the argument has two values.  If there were more
1930 values, the second and third values would be directly concatenated,
1931 which would look funny.)
1932 @end table
1933
1934 @item [@var{a}:@var{b}:]@var{i}
1935 This extends the previous form so that the first values are expanded
1936 using @var{a} and later values are expanded using @var{b}.  For an
1937 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1938 instead written as @code{%@var{j}}.  Some examples from the corpus:
1939
1940 @table @code
1941 @item [%1:*^1:]1
1942 Expands to all of the values for the first argument, separated by
1943 @samp{*}.
1944
1945 @item [%1 = %2:, ^1 = ^2:]1
1946 Given appropriate values for the first argument, expands to @code{X =
1947 1, Y = 2, Z = 3}.
1948
1949 @item [%1:, ^1:]1
1950 Given appropriate values, expands to @code{1, 2, 3}.
1951 @end table
1952 @end table
1953
1954 The template string is localized to the user's locale.
1955 @end table
1956
1957 A writer may safely omit all of the optional 00 bytes at the beginning
1958 of a Value, except that it should write a single 00 byte before a
1959 templated Value.
1960
1961 @node SPV Light Member ValueMod
1962 @subsection ValueMod
1963
1964 A ValueMod can specify special modifications to a Value.
1965
1966 @example
1967 ValueMod =>
1968     58
1969   @math{|} 31
1970     int32[n-refs] int16*[n-refs]
1971     int32[n-subscripts] string*[n-subscripts]
1972     v1(00 (i1 | i2) 00? 00? int32 00? 00?)
1973     v3(count(TemplateString StylePair))
1974
1975 TemplateString => count((count((i0 (58 @math{|} 31 55))?) (58 @math{|} 31 string[id]))?)
1976
1977 StylePair =>
1978     (31 FontStyle | 58)
1979     (31 CellStyle | 58)
1980
1981 FontStyle =>
1982     bool[bold] bool[italic] bool[underline] bool[show]
1983     string[fg-color] string[bg-color]
1984     string[typeface] byte[size]
1985
1986 CellStyle =>
1987     int32[halign] int32[valign] double[decimal-offset]
1988     int16[left-margin] int16[right-margin]
1989     int16[top-margin] int16[bottom-margin]
1990 @end example
1991
1992 A ValueMod that begins with ``31'' specifies special modifications to
1993 a Value.
1994
1995 Each of the @code{n-refs} integers is a reference to a Footnote
1996 (@pxref{SPV Light Member Footnotes}) by 0-based index.  Footnote
1997 markers are shown appended to the main text of the Value, as
1998 superscripts or subscripts.
1999
2000 The @code{subscripts}, if present, are strings to append to the main
2001 text of the Value, as subscripts.  Each subscript text is a brief
2002 indicator, e.g.@: @samp{a} or @samp{b}, with its meaning indicated by
2003 the table caption.  When multiple subscripts are present, they are
2004 displayed separated by commas.
2005
2006 The @code{id} inside the TemplateString, if present, is a template
2007 string for substitutions using the syntax explained previously.  It
2008 appears to be an English-language version of the localized template
2009 string in the Value in which the Template is nested.  A writer may
2010 safely omit the optional fixed data in TemplateString.
2011
2012 FontStyle and CellStyle, if present, change the style for this
2013 individual Value.  In FontStyle, @code{bold}, @code{italic}, and
2014 @code{underline} control the particular style.  @code{show} is
2015 ordinarily 1; if it is 0, then the cell data is not shown.
2016 @code{fg-color} and @code{bg-color} are strings in the format
2017 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
2018 white.  The empty string is occasionally observed also.  The
2019 @code{size} is a font size in units of 1/128 inch.
2020
2021 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
2022 6 for decimal, 0xffffffad for mixed.  For decimal alignment,
2023 @code{decimal-offset} is the decimal point's offset from the right
2024 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
2025 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
2026 for bottom.  @code{left-margin}, @code{right-margin},
2027 @code{top-margin}, and @code{bottom-margin} are in pt.
2028
2029 @node SPV Legacy Detail Member Binary Format
2030 @section Legacy Detail Member Binary Format
2031
2032 Whereas the light binary format represents everything about a given
2033 pivot table, the legacy binary format conceptually consists of a
2034 number of named sources, each of which consists of a number of named
2035 variables, each of which is a 1-dimensional array of numbers or
2036 strings or a mix.  Thus, the legacy binary member format is quite
2037 simple.
2038
2039 This section uses the same context-free grammar notation as in the
2040 previous section, with the following additions:
2041
2042 @table @asis
2043 @item vAF(@var{x})
2044 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
2045 (The legacy member header indicates the version; see below.)
2046
2047 @item vB0(@var{x})
2048 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
2049 @end table
2050
2051 A legacy detail member @file{.bin} has the following overall format:
2052
2053 @example
2054 LegacyBinary =>
2055     00 byte[version] int16[n-sources] int32[member-size]
2056     Metadata*[n-sources]
2057     #Data*[n-sources]
2058     #Strings?
2059 @end example
2060
2061 @code{version} is a version number that affects the interpretation of
2062 some of the other data in the member.  Versions 0xaf and 0xb0 are
2063 known.  We will refer to ``version 0xaf'' and ``version 0xb0'' members
2064 later on.
2065
2066 A legacy member consists of @code{n-sources} data sources, each of
2067 which has Metadata and Data.
2068
2069 @code{member-size} is the size of the legacy binary member, in bytes.
2070
2071 The Data and Strings above are commented out because the Metadata has
2072 some oddities that mean that the Data sometimes seems to start at
2073 an unexpected place.  The following section goes into detail.
2074
2075 @menu
2076 * SPV Legacy Member Metadata::
2077 * SPV Legacy Member Numeric Data::
2078 * SPV Legacy Member String Data::
2079 @end menu
2080
2081 @node SPV Legacy Member Metadata
2082 @subsection Metadata
2083
2084 @example
2085 Metadata =>
2086     int32[n-values] int32[n-variables] int32[data-offset]
2087     vAF(byte*28[source-name])
2088     vB0(byte*64[source-name] int32[x])
2089 @end example
2090
2091 A data source has @code{n-variables} variables, each with
2092 @code{n-values} data values.
2093
2094 @code{source-name} is a 28- or 64-byte string padded on the right with
2095 0-bytes.  The names that appear in the corpus are very generic:
2096 usually @code{tableData} for pivot table data or @code{source0} for
2097 chart data.
2098
2099 A given Metadata's @code{data-offset} is the offset, in bytes, from
2100 the beginning of the member to the start of the corresponding Data.
2101 This allows programs to skip to the beginning of the data for a
2102 particular source.  In every case in the corpus, the Data follow the
2103 Metadata in the same order, but it is important to use
2104 @code{data-offset} instead of reading sequentially through the file
2105 because of the exception described below.
2106
2107 One SPV file in the corpus has legacy binary members with version 0xb0
2108 but a 28-byte @code{source-name} field (and only a single source).  In
2109 practice, this means that the 64-byte @code{source-name} used in
2110 version 0xb0 has a lot of 0-bytes in the middle followed by the
2111 @code{variable-name} of the following Data.  As long as a reader
2112 treats the first 0-byte in the @code{source-name} as terminating the
2113 string, it can properly interpret these members.
2114
2115 The meaning of @code{x} in version 0xb0 is unknown.
2116
2117 @node SPV Legacy Member Numeric Data
2118 @subsection Numeric Data
2119
2120 @example
2121 Data => Variable*[n-variables]
2122 Variable => byte*288[variable-name] double*[n-values]
2123 @end example
2124
2125 Data follow the Metadata in the legacy binary format, with sources in
2126 the same order (but readers should use the @code{data-offset} in
2127 Metadata records, rather than reading sequentially).  Each Variable
2128 begins with a @code{variable-name} that generally indicates its role
2129 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
2130 ``dimension0categories'', ``dimension0group0'', followed by the
2131 numeric data, one double per datum.  A double with the maximum
2132 negative double @code{-DBL_MAX} represents the system-missing value
2133 SYSMIS.
2134
2135 @node SPV Legacy Member String Data
2136 @subsection String Data
2137
2138 @example
2139 Strings => SourceMaps[maps] Labels
2140
2141 SourceMaps => int32[n-maps] SourceMap*[n-maps]
2142
2143 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
2144 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
2145 DatumMap => int32[value-idx] int32[label-idx]
2146
2147 Labels => int32[n-labels] Label*[n-labels]
2148 Label => int32[frequency] string[label]
2149 @end example
2150
2151 Each variable may include a mix of numeric and string data values.  If
2152 a legacy binary member contains any string data, Strings is present;
2153 otherwise, it ends just after the last Data element.
2154
2155 The string data overlays the numeric data.  When a variable includes
2156 any string data, its Variable represents the string values with a
2157 SYSMIS or NaN placeholder.  (Not all such values need be
2158 placeholders.)
2159
2160 Each SourceMap provides a mapping between SYSMIS or NaN values in source
2161 @code{source-name} and the string data that they represent.
2162 @code{n-variables} is the number of variables in the source that
2163 include string data.  More precisely, it is the 1-based index of the
2164 last variable in the source that includes any string data; thus, it
2165 would be 4 if there are 5 variables and only the fourth one includes
2166 string data.
2167
2168 A VariableMap repeats its variable's name, but variables are always
2169 present in the same order as the source, starting from the first
2170 variable, without skipping any even if they have no string values.
2171 Each VariableMap contains DatumMap nonterminals, each of which maps
2172 from a 0-based index within its variable's data to a 0-based label
2173 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
2174 that the third data value (which must be SYSMIS or NaN) is to be
2175 replaced by the string of the fourth Label.
2176
2177 The labels themselves follow the pairs.  The valuable part of each
2178 label is the string @code{label}.  Each label also includes a
2179 @code{frequency} that reports the number of DatumMaps that reference
2180 it (although this is not useful).
2181
2182 @node SPV Legacy Detail Member XML Format
2183 @section Legacy Detail Member XML Format
2184
2185 The design of the detail XML format is not what one would end up with
2186 for describing pivot tables.  This is because it is a special case
2187 of a much more general format (``visualization XML'' or ``VizML'')
2188 that can describe a wide range of visualizations.  Most of this
2189 generality is overkill for tables, and so we end up with a funny
2190 subset of a general-purpose format.
2191
2192 An XML Schema for VizML is available, distributed with SPSS binaries,
2193 under a nonfree license.  It contains documentation that is
2194 occasionally helpful.
2195
2196 This section describes the detail XML format using the same notation
2197 already used for the structure XML format (@pxref{SPV Structure Member
2198 Format}).  See @file{src/output/spv/detail-xml.grammar} in the PSPP
2199 source tree for the full grammar that it uses for parsing.
2200
2201 The important elements of the detail XML format are:
2202
2203 @itemize @bullet
2204 @item
2205 Variables.  @xref{SPV Detail Variable Elements}.
2206
2207 @item
2208 Assignment of variables to axes.  A variable can appear as columns, or
2209 rows, or layers.  The @code{faceting} element and its sub-elements
2210 describe this assignment.
2211
2212 @item
2213 Styles and other annotations.
2214 @end itemize
2215
2216 This description is not detailed enough to write legacy tables.
2217 Instead, write tables in the light binary format.
2218
2219 @menu
2220 * SPV Detail visualization Element::
2221 * SPV Detail Variable Elements::
2222 * SPV Detail extension Element::
2223 * SPV Detail graph Element::
2224 * SPV Detail location Element::
2225 * SPV Detail faceting Element::
2226 * SPV Detail facetLayout Element::
2227 * SPV Detail label Element::
2228 * SPV Detail setCellProperties Element::
2229 * SPV Detail setFormat Element::
2230 * SPV Detail interval Element::
2231 * SPV Detail style Element::
2232 * SPV Detail labelFrame Element::
2233 * SPV Detail Legacy Properties::
2234 @end menu
2235
2236 @node SPV Detail visualization Element
2237 @subsection The @code{visualization} Element
2238
2239 @example
2240 visualization
2241    :creator
2242    :date
2243    :lang
2244    :name
2245    :style[style_ref]=ref style
2246    :type
2247    :version
2248    :schemaLocation?
2249 => visualization_extension?
2250    userSource
2251    (sourceVariable | derivedVariable)+
2252    categoricalDomain?
2253    graph
2254    labelFrame[lf1]*
2255    container?
2256    labelFrame[lf2]*
2257    style+
2258    layerController?
2259
2260 extension[visualization_extension]
2261    :numRows=int?
2262    :showGridline=bool?
2263    :minWidthSet=(true)?
2264    :maxWidthSet=(true)?
2265 => EMPTY
2266
2267 userSource :missing=(listwise | pairwise)? => EMPTY
2268
2269 categoricalDomain => variableReference simpleSort
2270
2271 simpleSort :method[sort_method]=(custom) => categoryOrder
2272
2273 container :style=ref style => container_extension? location+ labelFrame*
2274
2275 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2276
2277 layerController
2278    :source=(tableData)
2279    :target=ref label?
2280 => EMPTY
2281 @end example
2282
2283 The @code{visualization} element is the root of detail XML member.  It
2284 has the following attributes:
2285
2286 @defvr {Attribute} creator
2287 The version of the software that created this SPV file, as a string of
2288 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2289 e.g.@: @code{160001} is version 16.0.1.  The corpus includes major
2290 versions 16 through 19.
2291 @end defvr
2292
2293 @defvr {Attribute} date
2294 The date on the which the file was created, as a string of the form
2295 @code{YYYY-MM-DD}.
2296 @end defvr
2297
2298 @defvr {Attribute} lang
2299 The locale used for output, in Windows format, which is similar to the
2300 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2301 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2302 @end defvr
2303
2304 @defvr {Attribute} name
2305 The title of the pivot table, localized to the output language.
2306 @end defvr
2307
2308 @defvr {Attribute} style
2309 The base style for the pivot table.  In every example in the corpus,
2310 the @code{style} element has no attributes other than @code{id}.
2311 @end defvr
2312
2313 @defvr {Attribute} type
2314 A floating-point number.  The meaning is unknown.
2315 @end defvr
2316
2317 @defvr {Attribute} version
2318 The visualization schema version number.  In the corpus, the value is
2319 one of 2.4, 2.5, 2.7, and 2.8.
2320 @end defvr
2321
2322 The @code{userSource} element has no visible effect.
2323
2324 The @code{extension} element as a child of @code{visualization} has
2325 the following attributes.
2326
2327 @defvr {Attribute} numRows
2328 An integer that presumably defines the number of rows in the displayed
2329 pivot table.
2330 @end defvr
2331
2332 @defvr {Attribute} showGridline
2333 Always set to @code{false} in the corpus.
2334 @end defvr
2335
2336 @defvr {Attribute} minWidthSet
2337 @defvrx {Attribute} maxWidthSet
2338 Always set to @code{true} in the corpus.
2339 @end defvr
2340
2341 The @code{extension} element as a child of @code{container} has the
2342 following attribute
2343
2344 @defvr {Attribute} combinedFootnotes
2345 Meaning unknown.
2346 @end defvr
2347
2348 The @code{categoricalDomain} and @code{simpleSort} elements have no
2349 visible effect.
2350
2351 The @code{layerController} element has no visible effect.
2352
2353 @node SPV Detail Variable Elements
2354 @subsection Variable Elements
2355
2356 A ``variable'' in detail XML is a 1-dimensional array of data.  Each
2357 element of the array may, independently, have string or numeric
2358 content.  All of the variables in a given detail XML member either
2359 have the same number of elements or have zero elements.
2360
2361 Two different elements define variables and their content:
2362
2363 @table @code
2364 @item sourceVariable
2365 These variables' data comes from the associated @code{tableData.bin}
2366 member.
2367
2368 @item derivedVariable
2369 These variables are defined in terms of a mapping function from a
2370 source variable, or they are empty.
2371 @end table
2372
2373 A variable named @code{cell} always exists.  This variable holds the
2374 data displayed in the table.
2375
2376 Variables in detail XML roughly correspond to the dimensions in a
2377 light detail member.  Each dimension has the following variables with
2378 stylized names, where @var{n} is a number for the dimension starting
2379 from 0:
2380
2381 @table @code
2382 @item dimension@var{n}categories
2383 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2384
2385 @item dimension@var{n}group0
2386 Present only if the dimension's categories are grouped, this variable
2387 holds the group labels for the categories.  Grouping is inferred
2388 through adjacent identical labels.  Categories that are not part of a
2389 group have empty-string data in this variable.
2390
2391 @item dimension@var{n}group1
2392 Present only if the first-level groups are further grouped, this
2393 variable holds the labels for the second-level groups.  There can be
2394 additional variables with further levels of grouping.
2395
2396 @item dimension@var{n}
2397 An empty variable.
2398 @end table
2399
2400 Determining the data for a (non-empty) variable is a multi-step
2401 process:
2402
2403 @enumerate
2404 @item
2405 Draw initial data from its source, for a @code{sourceVariable}, or
2406 from another named variable, for a @code{derivedVariable}.
2407
2408 @item
2409 Apply mappings from @code{valueMapEntry} elements within the
2410 @code{derivedVariable} element, if any.
2411
2412 @item
2413 Apply mappings from @code{relabel} elements within a @code{format} or
2414 @code{stringFormat} element in the @code{sourceVariable} or
2415 @code{derivedVariable} element, if any.
2416
2417 @item
2418 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2419 attribute, and there were no mappings to apply in previous steps, then
2420 replace each element of the variable by the corresponding value in the
2421 label variable.
2422 @end enumerate
2423
2424 A single variable's data can be modified in two of the steps, if both
2425 @code{valueMapEntry} and @code{relabel} are used.  The following
2426 example from the corpus maps several integers to 2, then maps 2 in
2427 turn to the string ``Input'':
2428
2429 @example
2430 <derivedVariable categorical="true" dependsOn="dimension0categories"
2431                  id="dimension0group0map" value="map(dimension0group0)">
2432   <stringFormat>
2433     <relabel from="2" to="Input"/>
2434     <relabel from="10" to="Missing Value Handling"/>
2435     <relabel from="14" to="Resources"/>
2436     <relabel from="0" to=""/>
2437     <relabel from="1" to=""/>
2438     <relabel from="13" to=""/>
2439   </stringFormat>
2440   <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2441   <valueMapEntry from="10;11" to="10"/>
2442   <valueMapEntry from="14;15" to="14"/>
2443   <valueMapEntry from="0" to="0"/>
2444   <valueMapEntry from="1" to="1"/>
2445   <valueMapEntry from="13" to="13"/>
2446 </derivedVariable>
2447 @end example
2448
2449 @menu
2450 * SPV Detail sourceVariable Element::
2451 * SPV Detail derivedVariable Element::
2452 * SPV Detail valueMapEntry Element::
2453 @end menu
2454
2455 @node SPV Detail sourceVariable Element
2456 @subsubsection The @code{sourceVariable} Element
2457
2458 @example
2459 sourceVariable
2460    :id
2461    :categorical=(true)
2462    :source
2463    :domain=ref categoricalDomain?
2464    :sourceName
2465    :dependsOn=ref sourceVariable?
2466    :label?
2467    :labelVariable=ref sourceVariable?
2468 => variable_extension* (format | stringFormat)?
2469 @end example
2470
2471 This element defines a variable whose data comes from the
2472 @file{tableData.bin} member that corresponds to this @file{.xml}.
2473
2474 This element has the following attributes.
2475
2476 @defvr {Attribute} id
2477 An @code{id} is always present because this element exists to be
2478 referenced from other elements.
2479 @end defvr
2480
2481 @defvr {Attribute} categorical
2482 Always set to @code{true}.
2483 @end defvr
2484
2485 @defvr {Attribute} source
2486 Always set to @code{tableData}, the @code{source-name} in the
2487 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2488 Metadata}).
2489 @end defvr
2490
2491 @defvr {Attribute} sourceName
2492 The name of a variable within the source, corresponding to the
2493 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2494 Legacy Member Numeric Data}).
2495 @end defvr
2496
2497 @defvr {Attribute} label
2498 The variable label, if any.
2499 @end defvr
2500
2501 @defvr {Attribute} labelVariable
2502 The @code{variable-name} of a variable whose string values correspond
2503 one-to-one with the values of this variable and are suitable for use
2504 as value labels.
2505 @end defvr
2506
2507 @defvr {Attribute} dependsOn
2508 This attribute doesn't affect the display of a table.
2509 @end defvr
2510
2511 @node SPV Detail derivedVariable Element
2512 @subsubsection The @code{derivedVariable} Element
2513
2514 @example
2515 derivedVariable
2516    :id
2517    :categorical=(true)
2518    :value
2519    :dependsOn=ref sourceVariable?
2520 => variable_extension* (format | stringFormat)? valueMapEntry*
2521 @end example
2522
2523 Like @code{sourceVariable}, this element defines a variable whose
2524 values can be used elsewhere in the visualization.  Instead of being
2525 read from a data source, the variable's data are defined by a
2526 mathematical expression.
2527
2528 This element has the following attributes.
2529
2530 @defvr {Attribute} id
2531 An @code{id} is always present because this element exists to be
2532 referenced from other elements.
2533 @end defvr
2534
2535 @defvr {Attribute} categorical
2536 Always set to @code{true}.
2537 @end defvr
2538
2539 @defvr {Attribute} value
2540 An expression that defines the variable's value.  In theory this could
2541 be an arbitrary expression in terms of constants, functions, and other
2542 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}.  In practice,
2543 the corpus contains only the following forms of expressions:
2544
2545 @table @code
2546 @item constant(0)
2547 @itemx constant(@var{variable})
2548 All zeros.  The reason why a variable is sometimes named is unknown.
2549 Sometimes the ``variable name'' has spaces in it.
2550
2551 @item map(@var{variable})
2552 Transforms the values in the named @var{variable} using the
2553 @code{valueMapEntry}s contained within the element.
2554 @end table
2555 @end defvr
2556
2557 @defvr {Attribute} dependsOn
2558 This attribute doesn't affect the display of a table.
2559 @end defvr
2560
2561 @node SPV Detail valueMapEntry Element
2562 @subsubsection The @code{valueMapEntry} Element
2563
2564 @example
2565 valueMapEntry :from :to => EMPTY
2566 @end example
2567
2568 A @code{valueMapEntry} element defines a mapping from one or more
2569 values of a source expression to a target value.  (In the corpus, the
2570 source expression is always just the name of a variable.)  Each target
2571 value requires a separate @code{valueMapEntry}.  If multiple source
2572 values map to the same target value, they can be combined or separate.
2573
2574 In the corpus, all of the source and target values are integers.
2575
2576 @code{valueMapEntry} has the following attributes.
2577
2578 @defvr {Attribute} from
2579 A source value, or multiple source values separated by semicolons,
2580 e.g.@: @code{0} or @code{13;14;15;16}.
2581 @end defvr
2582
2583 @defvr {Attribute} to
2584 The target value, e.g.@: @code{0}.
2585 @end defvr
2586
2587 @node SPV Detail extension Element
2588 @subsection The @code{extension} Element
2589
2590 This is a general-purpose ``extension'' element.  Readers that don't
2591 understand a given extension should be able to safely ignore it.  The
2592 attributes on this element, and their meanings, vary based on the
2593 context.  Each known usage is described separately below.  The current
2594 extensions use attributes exclusively, without any nested elements.
2595
2596 @subsubheading @code{container} Parent Element
2597
2598 @example
2599 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2600 @end example
2601
2602 With @code{container} as its parent element, @code{extension} has the
2603 following attributes.
2604
2605 @defvr {Attribute} combinedFootnotes
2606 Always set to @code{true} in the corpus.
2607 @end defvr
2608
2609 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2610
2611 @example
2612 extension[variable_extension] :from :helpId => EMPTY
2613 @end example
2614
2615 With @code{sourceVariable} or @code{derivedVariable} as its parent
2616 element, @code{extension} has the following attributes.  A given
2617 parent element often contains several @code{extension} elements that
2618 specify the meaning of the source data's variables or sources, e.g.@:
2619
2620 @example
2621 <extension from="0" helpId="corrected_model"/>
2622 <extension from="3" helpId="error"/>
2623 <extension from="4" helpId="total_9"/>
2624 <extension from="5" helpId="corrected_total"/>
2625 @end example
2626
2627 More commonly they are less helpful, e.g.@:
2628
2629 @example
2630 <extension from="0" helpId="notes"/>
2631 <extension from="1" helpId="notes"/>
2632 <extension from="2" helpId="notes"/>
2633 <extension from="5" helpId="notes"/>
2634 <extension from="6" helpId="notes"/>
2635 <extension from="7" helpId="notes"/>
2636 <extension from="8" helpId="notes"/>
2637 <extension from="12" helpId="notes"/>
2638 <extension from="13" helpId="no_help"/>
2639 <extension from="14" helpId="notes"/>
2640 @end example
2641
2642 @defvr {Attribute} from
2643 An integer or a name like ``dimension0''.
2644 @end defvr
2645
2646 @defvr {Attribute} helpId
2647 An identifier.
2648 @end defvr
2649
2650 @node SPV Detail graph Element
2651 @subsection The @code{graph} Element
2652
2653 @example
2654 graph
2655    :cellStyle=ref style
2656    :style=ref style
2657 => location+ coordinates faceting facetLayout interval
2658
2659 coordinates => EMPTY
2660 @end example
2661
2662 @code{graph} has the following attributes.
2663
2664 @defvr {Attribute} cellStyle
2665 @defvrx {Attribute} style
2666 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2667 Detail style Element}).  The former is the default style for
2668 individual cells, the latter for the entire table.
2669 @end defvr
2670
2671 @node SPV Detail location Element
2672 @subsection The @code{location} Element
2673
2674 @example
2675 location
2676    :part=(height | width | top | bottom | left | right)
2677    :method=(sizeToContent | attach | fixed | same)
2678    :min=dimension?
2679    :max=dimension?
2680    :target=ref (labelFrame | graph | container)?
2681    :value?
2682 => EMPTY
2683 @end example
2684
2685 Each instance of this element specifies where some part of the table
2686 frame is located.  All the examples in the corpus have four instances
2687 of this element, one for each of the parts @code{height},
2688 @code{width}, @code{left}, and @code{top}.  Some examples in the
2689 corpus add a fifth for part @code{bottom}, even though it is not clear
2690 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2691 at the same time.  In any case, @code{location} seems to have little
2692 importance in representing tables; a reader can safely ignore it.
2693
2694 @defvr {Attribute} part
2695 The part of the table being located.
2696 @end defvr
2697
2698 @defvr {Attribute} method
2699 How the location is determined:
2700
2701 @table @code
2702 @item sizeToContent
2703 Based on the natural size of the table.  Observed only for
2704 parts @code{height} and @code{width}.
2705
2706 @item attach
2707 Based on the location specified in @code{target}.  Observed only for
2708 parts @code{top} and @code{bottom}.
2709
2710 @item fixed
2711 Using the value in @code{value}.  Observed only for parts @code{top},
2712 @code{bottom}, and @code{left}.
2713
2714 @item same
2715 Same as the specified @code{target}.  Observed only for part
2716 @code{left}.
2717 @end table
2718 @end defvr
2719
2720 @defvr {Attribute} min
2721 Minimum size.  Only observed with value @code{100pt}.  Only observed
2722 for part @code{width}.
2723 @end defvr
2724
2725 @defvr {Dependent} target
2726 Required when @code{method} is @code{attach} or @code{same}, not
2727 observed otherwise.  This identifies an element to attach to.
2728 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2729 and other elements.
2730 @end defvr
2731
2732 @defvr {Dependent} value
2733 Required when @code{method} is @code{fixed}, not observed otherwise.
2734 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2735 on parts @code{top} and @code{left}, and @code{100%} on part
2736 @code{bottom}.
2737 @end defvr
2738
2739 @node SPV Detail faceting Element
2740 @subsection The @code{faceting} Element
2741
2742 @example
2743 faceting => layer[layers1]* cross layer[layers2]*
2744
2745 cross => (unity | nest) (unity | nest)
2746
2747 unity => EMPTY
2748
2749 nest => variableReference[vars]+
2750
2751 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2752
2753 layer
2754    :variable=ref (sourceVariable | derivedVariable)
2755    :value
2756    :visible=bool?
2757    :method[layer_method]=(nest)?
2758    :titleVisible=bool?
2759 => EMPTY
2760 @end example
2761
2762 The @code{faceting} element describes the row, column, and layer
2763 structure of the table.  Its @code{cross} child determines the row and
2764 column structure, and each @code{layer} child (if any) represents a
2765 layer.  Layers may appear before or after @code{cross}.
2766
2767 The @code{cross} element describes the row and column structure of the
2768 table.  It has exactly two children, the first of which describes the
2769 table's columns and the second the table's rows.  Each child is a
2770 @code{nest} element if the table has any dimensions along the axis in
2771 question, otherwise a @code{unity} element.
2772
2773 A @code{nest} element contains of one or more dimensions listed from
2774 innermost to outermost, each represented by @code{variableReference}
2775 child elements.  Each variable in a dimension is listed in order.
2776 @xref{SPV Detail Variable Elements}, for information on the variables
2777 that comprise a dimension.
2778
2779 A @code{nest} can contain a single dimension, e.g.:
2780
2781 @example
2782 <nest>
2783   <variableReference ref="dimension0categories"/>
2784   <variableReference ref="dimension0group0"/>
2785   <variableReference ref="dimension0"/>
2786 </nest>
2787 @end example
2788
2789 @noindent
2790 A @code{nest} can contain multiple dimensions, e.g.:
2791
2792 @example
2793 <nest>
2794   <variableReference ref="dimension1categories"/>
2795   <variableReference ref="dimension1group0"/>
2796   <variableReference ref="dimension1"/>
2797   <variableReference ref="dimension0categories"/>
2798   <variableReference ref="dimension0"/>
2799 </nest>
2800 @end example
2801
2802 A @code{nest} may have no dimensions, in which case it still has one
2803 @code{variableReference} child, which references a
2804 @code{derivedVariable} whose @code{value} attribute is
2805 @code{constant(0)}.  In the corpus, such a @code{derivedVariable} has
2806 @code{row} or @code{column}, respectively, as its @code{id}.  This is
2807 equivalent to using a @code{unity} element in place of @code{nest}.
2808
2809 A @code{variableReference} element refers to a variable through its
2810 @code{ref} attribute.
2811
2812 Each @code{layer} element represents a dimension, e.g.:
2813
2814 @example
2815 <layer value="0" variable="dimension0categories" visible="true"/>
2816 <layer value="dimension0" variable="dimension0" visible="false"/>
2817 @end example
2818
2819 @noindent
2820 @code{layer} has the following attributes.
2821
2822 @defvr {Attribute} variable
2823 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2824 @end defvr
2825
2826 @defvr {Attribute} value
2827 The value to select.  For a category variable, this is always
2828 @code{0}; for a data variable, it is the same as the @code{variable}
2829 attribute.
2830 @end defvr
2831
2832 @defvr {Attribute} visible
2833 Whether the layer is visible.  Generally, category layers are visible
2834 and data layers are not, but sometimes this attribute is omitted.
2835 @end defvr
2836
2837 @defvr {Attribute} method
2838 When present, this is always @code{nest}.
2839 @end defvr
2840
2841 @node SPV Detail facetLayout Element
2842 @subsection The @code{facetLayout} Element
2843
2844 @example
2845 facetLayout => tableLayout setCellProperties[scp1]*
2846                facetLevel+ setCellProperties[scp2]*
2847
2848 tableLayout
2849    :verticalTitlesInCorner=bool
2850    :style=ref style?
2851    :fitCells=(ticks both)?
2852 => EMPTY
2853 @end example
2854
2855 The @code{facetLayout} element and its descendants control styling for
2856 the table.
2857
2858 Its @code{tableLayout} child has the following attributes
2859
2860 @defvr {Attribute} verticalTitlesInCorner
2861 If true, in the absence of corner text, row headings will be displayed
2862 in the corner.
2863 @end defvr
2864
2865 @defvr {Attribute} style
2866 Refers to a @code{style} element.
2867 @end defvr
2868
2869 @defvr {Attribute} fitCells
2870 Meaning unknown.
2871 @end defvr
2872
2873 @subsubheading The @code{facetLevel} Element
2874
2875 @example
2876 facetLevel :level=int :gap=dimension? => axis
2877
2878 axis :style=ref style => label? majorTicks
2879
2880 majorTicks
2881    :labelAngle=int
2882    :length=dimension
2883    :style=ref style
2884    :tickFrameStyle=ref style
2885    :labelFrequency=int?
2886    :stagger=bool?
2887 => gridline?
2888
2889 gridline
2890    :style=ref style
2891    :zOrder=int
2892 => EMPTY
2893 @end example
2894
2895 Each @code{facetLevel} describes a @code{variableReference} or
2896 @code{layer}, and a table has one @code{facetLevel} element for
2897 each such element.  For example, an SPV detail member that contains
2898 four @code{variableReference} elements and two @code{layer} elements
2899 will contain six @code{facetLevel} elements.
2900
2901 In the corpus, @code{facetLevel} elements and the elements that they
2902 describe are always in the same order.  The correspondence may also be
2903 observed in two other ways.  First, one may use the @code{level}
2904 attribute, described below.  Second, in the corpus, a
2905 @code{facetLevel} always has an @code{id} that is the same as the
2906 @code{id} of the element it describes with @code{_facetLevel}
2907 appended.  One should not formally rely on this, of course, but it is
2908 usefully indicative.
2909
2910 @defvr {Attribute} level
2911 A 1-based index into the @code{variableReference} and @code{layer}
2912 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2913 describes the first @code{variableReference} in the SPV detail member,
2914 and in a member with four @code{variableReference} elements, a
2915 @code{facetLayout} with a @code{level} of 5 describes the first
2916 @code{layer} in the member.
2917 @end defvr
2918
2919 @defvr {Attribute} gap
2920 Always observed as @code{0pt}.
2921 @end defvr
2922
2923 Each @code{facetLevel} contains an @code{axis}, which in turn may
2924 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2925 label Element}) and does contain a @code{majorTicks} element.
2926
2927 @defvr {Attribute} labelAngle
2928 Normally 0.  The value -90 causes inner column or outer row labels to
2929 be rotated vertically.
2930 @end defvr
2931
2932 @defvr {Attribute} style
2933 @defvrx {Attribute} tickFrameStyle
2934 Each refers to a @code{style} element.  @code{style} is the style of
2935 the tick labels, @code{tickFrameStyle} the style for the frames around
2936 the labels.
2937 @end defvr
2938
2939 @node SPV Detail label Element
2940 @subsection The @code{label} Element
2941
2942 @example
2943 label
2944    :style=ref style
2945    :textFrameStyle=ref style?
2946    :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2947 => text+ | descriptionGroup
2948
2949 descriptionGroup
2950    :target=ref faceting
2951    :separator?
2952 => (description | text)+
2953
2954 description :name=(variable | value) => EMPTY
2955
2956 text
2957    :usesReference=int?
2958    :definesReference=int?
2959    :position=(subscript | superscript)?
2960    :style=ref style
2961 => TEXT
2962 @end example
2963
2964 This element represents a label on some aspect of the table.
2965
2966 @defvr {Attribute} style
2967 @defvrx {Attribute} textFrameStyle
2968 Each of these refers to a @code{style} element.  @code{style} is the
2969 style of the label text, @code{textFrameStyle} the style for the frame
2970 around the label.
2971 @end defvr
2972
2973 @defvr {Attribute} purpose
2974 The kind of entity being labeled.
2975 @end defvr
2976
2977 A @code{descriptionGroup} concatenates one or more elements to form a
2978 label.  Each element can be a @code{text} element, which contains
2979 literal text, or a @code{description} element that substitutes a value
2980 or a variable name.
2981
2982 @defvr {Attribute} target
2983 The @code{id} of an element being described.  In the corpus, this is
2984 always @code{faceting}.
2985 @end defvr
2986
2987 @defvr {Attribute} separator
2988 A string to separate the description of multiple groups, if the
2989 @code{target} has more than one.  In the corpus, this is always a
2990 new-line.
2991 @end defvr
2992
2993 Typical contents for a @code{descriptionGroup} are a value by itself:
2994 @example
2995 <description name="value"/>
2996 @end example
2997 @noindent or a variable and its value, separated by a colon:
2998 @example
2999 <description name="variable"/><text>:</text><description name="value"/>
3000 @end example
3001
3002 A @code{description} is like a macro that expands to some property of
3003 the target of its parent @code{descriptionGroup}.  The @code{name}
3004 attribute specifies the property.
3005
3006 @node SPV Detail setCellProperties Element
3007 @subsection The @code{setCellProperties} Element
3008
3009 @example
3010 setCellProperties
3011    :applyToConverse=bool?
3012 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
3013 @end example
3014
3015 The @code{setCellProperties} element sets style properties of cells or
3016 row or column labels.
3017
3018 Interpreting @code{setCellProperties} requires answering two
3019 questions: which cells or labels to style, and what styles to use.
3020
3021 @subsubheading Which Cells?
3022
3023 @example
3024 union => intersect+
3025
3026 intersect => where+ | intersectWhere | alternating | EMPTY
3027
3028 where
3029    :variable=ref (sourceVariable | derivedVariable)
3030    :include
3031 => EMPTY
3032
3033 intersectWhere
3034    :variable=ref (sourceVariable | derivedVariable)
3035    :variable2=ref (sourceVariable | derivedVariable)
3036 => EMPTY
3037
3038 alternating => EMPTY
3039 @end example
3040
3041 When @code{union} is present with @code{intersect} children, each of
3042 those children specifies a group of cells that should be styled, and
3043 the total group is all those cells taken together.  When @code{union}
3044 is absent, every cell is styled.  One attribute on
3045 @code{setCellProperties} affects the choice of cells:
3046
3047 @defvr {Attribute} applyToConverse
3048 If true, this inverts the meaning of the cell selection: the selected
3049 cells are the ones @emph{not} designated.  This is confusing, given
3050 the additional restrictions of @code{union}, but in the corpus
3051 @code{applyToConverse} is never present along with @code{union}.
3052 @end defvr
3053
3054 An @code{intersect} specifies restrictions on the cells to be matched.
3055 Each @code{where} child specifies which values of a given variable to
3056 include.  The attributes of @code{intersect} are:
3057
3058 @defvr {Attribute} variable
3059 Refers to a variable, e.g.@: @code{dimension0categories}.  Only
3060 ``categories'' variables make sense here, but other variables, e.g.@:
3061 @code{dimension0group0map}, are sometimes seen.  The reader may ignore
3062 these.
3063 @end defvr
3064
3065 @defvr {Attribute} include
3066 A value, or multiple values separated by semicolons,
3067 e.g.@: @code{0} or @code{13;14;15;16}.
3068 @end defvr
3069
3070 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
3071 present.
3072
3073 @subsubheading What Styles?
3074
3075 @example
3076 setStyle
3077    :target=ref (labeling | graph | interval | majorTicks)
3078    :style=ref style
3079 => EMPTY
3080
3081 setMetaData :target=ref graph :key :value => EMPTY
3082
3083 setFormat
3084    :target=ref (majorTicks | labeling)
3085    :reset=bool?
3086 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3087
3088 setFrameStyle
3089    :style=ref style
3090    :target=ref majorTicks
3091 => EMPTY
3092 @end example
3093
3094 The @code{set*} children of @code{setCellProperties} determine the
3095 styles to set.
3096
3097 When @code{setCellProperties} contains a @code{setFormat} whose
3098 @code{target} references a @code{labeling} element, or if it contains
3099 a @code{setStyle} that references a @code{labeling} or @code{interval}
3100 element, the @code{setCellProperties} sets the style for table cells.
3101 The format from the @code{setFormat}, if present, replaces the cells'
3102 format.  The style from the @code{setStyle} that references
3103 @code{labeling}, if present, replaces the label's font and cell
3104 styles, except that the background color is taken instead from the
3105 @code{interval}'s style, if present.
3106
3107 When @code{setCellProperties} contains a @code{setFormat} whose
3108 @code{target} references a @code{majorTicks} element, or if it
3109 contains a @code{setStyle} whose @code{target} references a
3110 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
3111 the @code{setCellProperties} sets the style for row or column labels.
3112 In this case, the @code{setCellProperties} always contains a single
3113 @code{where} element whose @code{variable} designates the variable
3114 whose labels are to be styled.  The format from the @code{setFormat},
3115 if present, replaces the labels' format.  The style from the
3116 @code{setStyle} that references @code{majorTicks}, if present,
3117 replaces the labels' font and cell styles, except that the background
3118 color is taken instead from the @code{setFrameStyle}'s style, if
3119 present.
3120
3121 When @code{setCellProperties} contains a @code{setStyle} whose
3122 @code{target} references a @code{graph} element, and one that
3123 references a @code{labeling} element, and the @code{union} element
3124 contains @code{alternating}, the @code{setCellProperties} sets the
3125 alternate foreground and background colors for the data area.  The
3126 foreground color is taken from the style referenced by the
3127 @code{setStyle} that targets the @code{graph}, the background color
3128 from the @code{setStyle} for @code{labeling}.
3129
3130 A reader may ignore a @code{setCellProperties} that only contains
3131 @code{setMetaData}, as well as @code{setMetaData} within other
3132 @code{setCellProperties}.
3133
3134 A reader may ignore a @code{setCellProperties} whose only @code{set*}
3135 child is a @code{setStyle} that targets the @code{graph} element.
3136
3137 @subsubheading The @code{setStyle} Element
3138
3139 @example
3140 setStyle
3141    :target=ref (labeling | graph | interval | majorTicks)
3142    :style=ref style
3143 => EMPTY
3144 @end example
3145
3146 This element associates a style with the target.
3147
3148 @defvr {Attribute} target
3149 The @code{id} of an element whose style is to be set.
3150 @end defvr
3151
3152 @defvr {Attribute} style
3153 The @code{id} of a @code{style} element that identifies the style to
3154 set on the target.
3155 @end defvr
3156
3157 @node SPV Detail setFormat Element
3158 @subsection The @code{setFormat} Element
3159
3160 @example
3161 setFormat
3162    :target=ref (majorTicks | labeling)
3163    :reset=bool?
3164 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3165 @end example
3166
3167 This element sets the format of the target, ``format'' in this case
3168 meaning the SPSS print format for a variable.
3169
3170 The details of this element vary depending on the schema version, as
3171 declared in the root @code{visualization} element's @code{version}
3172 attribute (@pxref{SPV Detail visualization Element}).  A reader can
3173 interpret the content without knowing the schema version.
3174
3175 The @code{setFormat} element itself has the following attributes.
3176
3177 @defvr {Attribute} target
3178 Refers to an element whose style is to be set.
3179 @end defvr
3180
3181 @defvr {Attribute} reset
3182 If this is @code{true}, this format replaces the target's previous
3183 format.  If it is @code{false}, the modifies the previous format.
3184 @end defvr
3185
3186 @menu
3187 * SPV Detail numberFormat Element::
3188 * SPV Detail stringFormat Element::
3189 * SPV Detail dateTimeFormat Element::
3190 * SPV Detail elapsedTimeFormat Element::
3191 * SPV Detail format Element::
3192 * SPV Detail affix Element::
3193 @end menu
3194
3195 @node SPV Detail numberFormat Element
3196 @subsubsection The @code{numberFormat} Element
3197
3198 @example
3199 numberFormat
3200    :minimumIntegerDigits=int?
3201    :maximumFractionDigits=int?
3202    :minimumFractionDigits=int?
3203    :useGrouping=bool?
3204    :scientific=(onlyForSmall | whenNeeded | true | false)?
3205    :small=real?
3206    :prefix?
3207    :suffix?
3208 => affix*
3209 @end example
3210
3211 Specifies a format for displaying a number.  The available options are
3212 a superset of those available from PSPP print formats.  PSPP chooses a
3213 print format type for a @code{numberFormat} as follows:
3214
3215 @enumerate
3216 @item
3217 If @code{scientific} is @code{true}, uses @code{E} format.
3218
3219 @item
3220 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
3221
3222 @item
3223 If @code{suffix} is @code{%}, uses @code{PCT} format.
3224
3225 @item
3226 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
3227
3228 @item
3229 Otherwise, uses @code{F} format.
3230 @end enumerate
3231
3232 For translating to a print format, PSPP uses
3233 @code{maximumFractionDigits} as the number of decimals, unless that
3234 attribute is missing or out of the range [0,15], in which case it uses
3235 2 decimals.
3236
3237 @defvr {Attribute} minimumIntegerDigits
3238 Minimum number of digits to display before the decimal point.  Always
3239 observed as @code{0}.
3240 @end defvr
3241
3242 @defvr {Attribute} maximumFractionDigits
3243 @defvrx {Attribute} minimumFractionDigits
3244 Maximum or minimum, respectively, number of digits to display after
3245 the decimal point.  The observed values of each attribute range from 0
3246 to 9.
3247 @end defvr
3248
3249 @defvr {Attribute} useGrouping
3250 Whether to use the grouping character to group digits in large
3251 numbers.
3252 @end defvr
3253
3254 @defvr {Attribute} scientific
3255 This attribute controls when and whether the number is formatted in
3256 scientific notation.  It takes the following values:
3257
3258 @table @code
3259 @item onlyForSmall
3260 Use scientific notation only when the number's magnitude is smaller
3261 than the value of the @code{small} attribute.
3262
3263 @item whenNeeded
3264 Use scientific notation when the number will not otherwise fit in the
3265 available space.
3266
3267 @item true
3268 Always use scientific notation.  Not observed in the corpus.
3269
3270 @item false
3271 Never use scientific notation.  A number that won't otherwise fit will
3272 be replaced by an error indication (see the @code{errorCharacter}
3273 attribute).  Not observed in the corpus.
3274 @end table
3275 @end defvr
3276
3277 @defvr {Attribute} small
3278 Only present when the @code{scientific} attribute is
3279 @code{onlyForSmall}, this is a numeric magnitude below which the
3280 number will be formatted in scientific notation.  The values @code{0}
3281 and @code{0.0001} have been observed.  The value @code{0} seems like a
3282 pathological choice, since no real number has a magnitude less than 0;
3283 perhaps in practice such a choice is equivalent to setting
3284 @code{scientific} to @code{false}.
3285 @end defvr
3286
3287 @defvr {Attribute} prefix
3288 @defvrx {Attribute} suffix
3289 Specifies a prefix or a suffix to apply to the formatted number.  Only
3290 @code{suffix} has been observed, with value @samp{%}.
3291 @end defvr
3292
3293 @node SPV Detail stringFormat Element
3294 @subsubsection The @code{stringFormat} Element
3295
3296 @example
3297 stringFormat => relabel* affix*
3298
3299 relabel :from=real :to => EMPTY
3300 @end example
3301
3302 The @code{stringFormat} element specifies how to display a string.  By
3303 default, a string is displayed verbatim, but @code{relabel} can change
3304 it.
3305
3306 The @code{relabel} element appears as a child of @code{stringFormat}
3307 (and of @code{format}, when it is used to format strings).  It
3308 specifies how to display a given value.  It is used to implement value
3309 labels and to display the system-missing value in a human-readable
3310 way.  It has the following attributes:
3311
3312 @defvr {Attribute} from
3313 The value to map.  In the corpus this is an integer or the
3314 system-missing value @code{-1.797693134862316E300}.
3315 @end defvr
3316
3317 @defvr {Attribute} to
3318 The string to display in place of the value of @code{from}.  In the
3319 corpus this is a wide variety of value labels; the system-missing
3320 value is mapped to @samp{.}.
3321 @end defvr
3322
3323 @node SPV Detail dateTimeFormat Element
3324 @subsubsection The @code{dateTimeFormat} Element
3325
3326 @example
3327 dateTimeFormat
3328    :baseFormat[dt_base_format]=(date | time | dateTime)
3329    :separatorChars?
3330    :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3331    :showYear=bool?
3332    :yearAbbreviation=bool?
3333    :showQuarter=bool?
3334    :quarterPrefix?
3335    :quarterSuffix?
3336    :showMonth=bool?
3337    :monthFormat=(long | short | number | paddedNumber)?
3338    :showWeek=bool?
3339    :weekPadding=bool?
3340    :weekSuffix?
3341    :showDayOfWeek=bool?
3342    :dayOfWeekAbbreviation=bool?
3343    :dayPadding=bool?
3344    :dayOfMonthPadding=bool?
3345    :hourPadding=bool?
3346    :minutePadding=bool?
3347    :secondPadding=bool?
3348    :showDay=bool?
3349    :showHour=bool?
3350    :showMinute=bool?
3351    :showSecond=bool?
3352    :showMillis=bool?
3353    :dayType=(month | year)?
3354    :hourFormat=(AMPM | AS_24 | AS_12)?
3355 => affix*
3356 @end example
3357
3358 This element appears only in schema version 2.5 and earlier
3359 (@pxref{SPV Detail visualization Element}).
3360
3361 Data to be formatted in date formats is stored as strings in legacy
3362 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3363 and reformatted by the reader.
3364
3365 The following attribute is required.
3366
3367 @defvr {Attribute} baseFormat
3368 Specifies whether a date and time are both to be displayed, or just
3369 one of them.
3370 @end defvr
3371
3372 Many of the attributes' meanings are obvious.  The following seem to
3373 be worth documenting.
3374
3375 @defvr {Attribute} separatorChars
3376 Exactly four characters.  In order, these are used for: decimal point,
3377 grouping, date separator, time separator.  Always @samp{.,-:}.
3378 @end defvr
3379
3380 @defvr {Attribute} mdyOrder
3381 Within a date, the order of the days, months, and years.
3382 @code{dayMonthYear} is the only observed value, but one would expect
3383 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3384 well.
3385 @end defvr
3386
3387 @defvr {Attribute} showYear
3388 @defvrx {Attribute} yearAbbreviation
3389 Whether to include the year and, if so, whether the year should be
3390 shown abbreviated, that is, with only 2 digits.  Each is @code{true}
3391 or @code{false}; only values of @code{true} and @code{false},
3392 respectively, have been observed.
3393 @end defvr
3394
3395 @defvr {Attribute} showMonth
3396 @defvrx {Attribute} monthFormat
3397 Whether to include the month (@code{true} or @code{false}) and, if so,
3398 how to format it.  @code{monthFormat} is one of the following:
3399
3400 @table @code
3401 @item long
3402 The full name of the month, e.g.@: in an English locale,
3403 @code{September}.
3404
3405 @item short
3406 The abbreviated name of the month, e.g.@: in an English locale,
3407 @code{Sep}.
3408
3409 @item number
3410 The number representing the month, e.g.@: 9 for September.
3411
3412 @item paddedNumber
3413 A two-digit number representing the month, e.g.@: 09 for September.
3414 @end table
3415
3416 Only values of @code{true} and @code{short}, respectively, have been
3417 observed.
3418 @end defvr
3419
3420 @defvr {Attribute} dayType
3421 This attribute is always @code{month} in the corpus, specifying that
3422 the day of the month is to be displayed; a value of @code{year} is
3423 supposed to indicate that the day of the year, where 1 is January 1,
3424 is to be displayed instead.
3425 @end defvr
3426
3427 @defvr {Attribute} hourFormat
3428 @code{hourFormat}, if present, is one of:
3429
3430 @table @code
3431 @item AMPM
3432 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3433 @code{10:15pm}.
3434
3435 @item AS_24
3436 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3437
3438 This is the only value observed in the corpus.
3439
3440 @item AS_12
3441 The time is displayed in a 12-hour format, without distinguishing
3442 morning or evening, e.g.@: @code{10;15}.
3443 @end table
3444
3445 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3446 which is confusing since a time duration does not have a concept of AM
3447 or PM.  This might indicate a bug in the code that generated the XML
3448 in the corpus, or it might indicate that @code{elapsedTime} is
3449 sometimes used to format a time of day.
3450 @end defvr
3451
3452 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3453 type based on the following rules:
3454
3455 @enumerate
3456 @item
3457 If @code{showQuarter} is true: @code{QYR}.
3458
3459 @item
3460 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3461
3462 @item
3463 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3464
3465 @enumerate a
3466 @item
3467 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3468
3469 @item
3470 Otherwise: @code{DATE}.
3471 @end enumerate
3472
3473 @item
3474 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3475
3476 @item
3477 Otherwise, @code{ADATE}.
3478 @end enumerate
3479
3480 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3481 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3482 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3483 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3484 true, otherwise @code{MTIME}.
3485
3486 For a @code{baseFormat} of @code{date}, the chosen width is the
3487 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3488 false or omitted.  For other base formats, the chosen width is the
3489 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3490 if @code{showMillis} is also true.  Decimals are 0 by default, or 3
3491 if @code{showMillis} is true.
3492
3493 @node SPV Detail elapsedTimeFormat Element
3494 @subsubsection The @code{elapsedTimeFormat} Element
3495
3496 @example
3497 elapsedTimeFormat
3498    :baseFormat[dt_base_format]=(date | time | dateTime)
3499    :dayPadding=bool?
3500    :hourPadding=bool?
3501    :minutePadding=bool?
3502    :secondPadding=bool?
3503    :showYear=bool?
3504    :showDay=bool?
3505    :showHour=bool?
3506    :showMinute=bool?
3507    :showSecond=bool?
3508    :showMillis=bool?
3509 => affix*
3510 @end example
3511
3512 This element specifies the way to display a time duration.
3513
3514 Data to be formatted in elapsed time formats is stored as strings in
3515 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3516 digits as needed for long durations, and must be parsed and
3517 reformatted by the reader.
3518
3519 The following attribute is required.
3520
3521 @defvr {Attribute} baseFormat
3522 Specifies whether a day and a time are both to be displayed, or just
3523 one of them.
3524 @end defvr
3525
3526 The remaining attributes specify exactly how to display the elapsed
3527 time.
3528
3529 For @code{baseFormat} of @code{time}, PSPP converts this element to
3530 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3531 to @code{TIME}; otherwise, to @code{MTIME}.  The chosen width is the
3532 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3533 adding 4 more if @code{showMillis} is also true.  Decimals are 0 by
3534 default, or 3 if @code{showMillis} is true.
3535
3536 @node SPV Detail format Element
3537 @subsubsection The @code{format} Element
3538
3539 @example
3540 format
3541    :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3542    :errorCharacter?
3543    :separatorChars?
3544    :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3545    :showYear=bool?
3546    :showQuarter=bool?
3547    :quarterPrefix?
3548    :quarterSuffix?
3549    :yearAbbreviation=bool?
3550    :showMonth=bool?
3551    :monthFormat=(long | short | number | paddedNumber)?
3552    :dayPadding=bool?
3553    :dayOfMonthPadding=bool?
3554    :showWeek=bool?
3555    :weekPadding=bool?
3556    :weekSuffix?
3557    :showDayOfWeek=bool?
3558    :dayOfWeekAbbreviation=bool?
3559    :hourPadding=bool?
3560    :minutePadding=bool?
3561    :secondPadding=bool?
3562    :showDay=bool?
3563    :showHour=bool?
3564    :showMinute=bool?
3565    :showSecond=bool?
3566    :showMillis=bool?
3567    :dayType=(month | year)?
3568    :hourFormat=(AMPM | AS_24 | AS_12)?
3569    :minimumIntegerDigits=int?
3570    :maximumFractionDigits=int?
3571    :minimumFractionDigits=int?
3572    :useGrouping=bool?
3573    :scientific=(onlyForSmall | whenNeeded | true | false)?
3574    :small=real?
3575    :prefix?
3576    :suffix?
3577    :tryStringsAsNumbers=bool?
3578    :negativesOutside=bool?
3579 => relabel* affix*
3580 @end example
3581
3582 This element is the union of all of the more-specific format elements.
3583 It is interpreted in the same way as one of those format elements,
3584 using @code{baseFormat} to determine which kind of format to use.
3585
3586 There are a few attributes not present in the more specific formats:
3587
3588 @defvr {Attribute} tryStringsAsNumbers
3589 When this is @code{true}, it is supposed to indicate that string
3590 values should be parsed as numbers and then displayed according to
3591 numeric formatting rules.  However, in the corpus it is always
3592 @code{false}.
3593 @end defvr
3594
3595 @defvr {Attribute} negativesOutside
3596 If true, the negative sign should be shown before the prefix; if
3597 false, it should be shown after.
3598 @end defvr
3599
3600 @node SPV Detail affix Element
3601 @subsubsection The @code{affix} Element
3602
3603 @example
3604 affix
3605    :definesReference=int
3606    :position=(subscript | superscript)
3607    :suffix=bool
3608    :value
3609 => EMPTY
3610 @end example
3611
3612 This defines a suffix (or, theoretically, a prefix) for a formatted
3613 value.  It is used to insert a reference to a footnote.  It has the
3614 following attributes:
3615
3616 @defvr {Attribute} definesReference
3617 This specifies the footnote number as a natural number: 1 for the
3618 first footnote, 2 for the second, and so on.
3619 @end defvr
3620
3621 @defvr {Attribute} position
3622 Position for the footnote label.  Always @code{superscript}.
3623 @end defvr
3624
3625 @defvr {Attribute} suffix
3626 Whether the affix is a suffix (@code{true}) or a prefix
3627 (@code{false}).  Always @code{true}.
3628 @end defvr
3629
3630 @defvr {Attribute} value
3631 The text of the suffix or prefix.  Typically a letter, e.g.@: @code{a}
3632 for footnote 1, @code{b} for footnote 2, @enddots{}  The corpus
3633 contains other values: @code{*}, @code{**}, and a few that begin with
3634 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3635 @end defvr
3636
3637 @node SPV Detail interval Element
3638 @subsection The @code{interval} Element
3639
3640 @example
3641 interval :style=ref style => labeling footnotes?
3642
3643 labeling
3644    :style=ref style?
3645    :variable=ref (sourceVariable | derivedVariable)
3646 => (formatting | format | footnotes)*
3647
3648 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3649
3650 formatMapping :from=int => format?
3651
3652 footnotes
3653    :superscript=bool?
3654    :variable=ref (sourceVariable | derivedVariable)
3655 => footnoteMapping*
3656
3657 footnoteMapping :definesReference=int :from=int :to => EMPTY
3658 @end example
3659
3660 The @code{interval} element and its descendants determine the basic
3661 formatting and labeling for the table's cells.  These basic styles are
3662 overridden by more specific styles set using @code{setCellProperties}
3663 (@pxref{SPV Detail setCellProperties Element}).
3664
3665 The @code{style} attribute of @code{interval} itself may be ignored.
3666
3667 The @code{labeling} element may have a single @code{formatting} child.
3668 If present, its @code{variable} attribute refers to a variable whose
3669 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3670 However, the numbers are not actually interpreted that way.  Instead,
3671 each number actually present in the variable's data is mapped by a
3672 @code{formatMapping} child of @code{formatting} to a @code{format}
3673 that specifies how to display it.
3674
3675 The @code{labeling} element may also have a @code{footnotes} child
3676 element.  The @code{variable} attribute of this element refers to a
3677 variable whose values are comma-delimited strings that list the
3678 1-based indexes of footnote references.  (Cells without any footnote
3679 references are numeric 0 instead of strings.)
3680
3681 Each @code{footnoteMapping} child of the @code{footnotes} element
3682 defines the footnote marker to be its @code{to} attribute text for the
3683 footnote whose 1-based index is given in its @code{definesReference}
3684 attribute.
3685
3686 @node SPV Detail style Element
3687 @subsection The @code{style} Element
3688
3689 @example
3690 style
3691    :color=color?
3692    :color2=color?
3693    :labelAngle=real?
3694    :border-bottom=(solid | thick | thin | double | none)?
3695    :border-top=(solid | thick | thin | double | none)?
3696    :border-left=(solid | thick | thin | double | none)?
3697    :border-right=(solid | thick | thin | double | none)?
3698    :border-bottom-color?
3699    :border-top-color?
3700    :border-left-color?
3701    :border-right-color?
3702    :font-family?
3703    :font-size?
3704    :font-weight=(regular | bold)?
3705    :font-style=(regular | italic)?
3706    :font-underline=(none | underline)?
3707    :margin-bottom=dimension?
3708    :margin-left=dimension?
3709    :margin-right=dimension?
3710    :margin-top=dimension?
3711    :textAlignment=(left | right | center | decimal | mixed)?
3712    :labelLocationHorizontal=(positive | negative | center)?
3713    :labelLocationVertical=(positive | negative | center)?
3714    :decimal-offset=dimension?
3715    :size?
3716    :width?
3717    :visible=bool?
3718 => EMPTY
3719 @end example
3720
3721 A @code{style} element has an effect only when it is referenced by
3722 another element to set some aspect of the table's style.  Most of the
3723 attributes are self-explanatory.  The rest are described below.
3724
3725 @defvr {Attribute} {color}
3726 In some cases, the text color; in others, the background color.
3727 @end defvr
3728
3729 @defvr {Attribute} {color2}
3730 Not used.
3731 @end defvr
3732
3733 @defvr {Attribute} {labelAngle}
3734 Normally 0.  The value -90 causes inner column or outer row labels to
3735 be rotated vertically.
3736 @end defvr
3737
3738 @defvr {Attribute} {labelLocationHorizontal}
3739 Not used.
3740 @end defvr
3741
3742 @defvr {Attribute} {labelLocationVertical}
3743 The value @code{positive} corresponds to vertically aligning text to
3744 the top of a cell, @code{negative} to the bottom, @code{center} to the
3745 middle.
3746 @end defvr
3747
3748 @node SPV Detail labelFrame Element
3749 @subsection The @code{labelFrame} Element
3750
3751 @example
3752 labelFrame :style=ref style => location+ label? paragraph?
3753
3754 paragraph :hangingIndent=dimension? => EMPTY
3755 @end example
3756
3757 A @code{labelFrame} element specifies content and style for some
3758 aspect of a table.  Only @code{labelFrame} elements that have a
3759 @code{label} child are important.  The @code{purpose} attribute in the
3760 @code{label} determines what the @code{labelFrame} affects:
3761
3762 @table @code
3763 @item title
3764 The table's title and its style.
3765
3766 @item subTitle
3767 The table's caption and its style.
3768
3769 @item footnote
3770 The table's footnotes and the style for the footer area.
3771
3772 @item layer
3773 The style for the layer area.
3774
3775 @item subSubTitle
3776 Ignored.
3777 @end table
3778
3779 The @code{style} attribute references the style to use for the area.
3780
3781 The @code{label}, if present, specifies the text to put into the title
3782 or caption or footnotes.  For footnotes, the label has two @code{text}
3783 children for every footnote, each of which has a @code{usesReference}
3784 attribute identifying the 1-based index of a footnote.  The first,
3785 third, fifth, @dots{} @code{text} child specifies the content for a
3786 footnote; the second, fourth, sixth, @dots{} child specifies the
3787 marker.  Content tends to end in a new-line, which the reader may wish
3788 to trim; similarly, markers tend to end in @samp{.}.
3789
3790 The @code{paragraph}, if present, may be ignored, since it is always
3791 empty.
3792
3793 @node SPV Detail Legacy Properties
3794 @subsection Legacy Properties
3795
3796 The detail XML format has features for styling most of the aspects of
3797 a table.  It also inherits defaults for many aspects from structure
3798 XML, which has the following @code{tableProperties} element:
3799
3800 @example
3801 tableProperties
3802    :name?
3803 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3804
3805 generalProperties
3806    :hideEmptyRows=bool?
3807    :maximumColumnWidth=dimension?
3808    :maximumRowWidth=dimension?
3809    :minimumColumnWidth=dimension?
3810    :minimumRowWidth=dimension?
3811    :rowDimensionLabels=(inCorner | nested)?
3812 => EMPTY
3813
3814 footnoteProperties
3815    :markerPosition=(superscript | subscript)?
3816    :numberFormat=(alphabetic | numeric)?
3817 => EMPTY
3818
3819 cellFormatProperties => cell_style+
3820
3821 any[cell_style]
3822    :alternatingColor=color?
3823    :alternatingTextColor=color?
3824 => style
3825
3826 style
3827    :color=color?
3828    :color2=color?
3829    :font-family?
3830    :font-size?
3831    :font-style=(regular | italic)?
3832    :font-weight=(regular | bold)?
3833    :font-underline=(none | underline)?
3834    :labelLocationVertical=(positive | negative | center)?
3835    :margin-bottom=dimension?
3836    :margin-left=dimension?
3837    :margin-right=dimension?
3838    :margin-top=dimension?
3839    :textAlignment=(left | right | center | decimal | mixed)?
3840    :decimal-offset=dimension?
3841 => EMPTY
3842
3843 borderProperties => border_style+
3844
3845 any[border_style]
3846    :borderStyleType=(none | solid | dashed | thick | thin | double)?
3847    :color=color?
3848 => EMPTY
3849
3850 printingProperties
3851    :printAllLayers=bool?
3852    :rescaleLongTableToFitPage=bool?
3853    :rescaleWideTableToFitPage=bool?
3854    :windowOrphanLines=int?
3855    :continuationText?
3856    :continuationTextAtBottom=bool?
3857    :continuationTextAtTop=bool?
3858    :printEachLayerOnSeparatePage=bool?
3859 => EMPTY
3860 @end example
3861
3862 The @code{name} attribute appears only in standalone @file{.stt} files
3863 (@pxref{SPSS TableLook STT Format}).