output: Correctly define and properly implement column width ranges.
[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 @chapter 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-heading-width] int32[max-col-heading-width]
1055     int32[min-row-heading-width] int32[max-row-heading-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-heading-width}, @code{max-col-heading-width}, @code{min-row-heading-width}, and
1073 @code{max-row-heading-width} are measurements in 1/96 inch units (called
1074 ``device independent pixel'' units in Windows) whose values influence
1075 column widths.  For the purpose of interpreting these values, a table
1076 is divided into the three regions shown below:
1077
1078 @example
1079 +------------------+-------------------------------------------------+
1080 |                  |                  column headings                |
1081 |                  +-------------------------------------------------+
1082 |      corner      |                                                 |
1083 |       and        |                                                 |
1084 |   row headings   |                      data                       |
1085 |                  |                                                 |
1086 |                  |                                                 |
1087 +------------------+-------------------------------------------------+
1088 @end example
1089
1090 @code{min-col-heading-width} and @code{max-col-heading-width} apply to the columns in
1091 the column headings region.  @code{min-col-heading-width} is the minimum width
1092 that any of these columns will be given automatically.  In addition,
1093 @code{max-col-heading-width} is the maximum width that a column will be
1094 assigned to accommodate a long label in the column headings cells.
1095 These columns will still be made wider to accommodate wide data values
1096 in the data region.
1097
1098 @code{min-row-heading-width} is the minimum width that a column in the corner
1099 and row headings region will be given automatically.
1100 @code{max-col-heading-width} is the maximum width that a column in this region
1101 will be assigned to accomodate a long label.  This region doesn't
1102 include data, so data values don't affect column widths.
1103
1104 @code{table-id} is a binary version of the @code{tableId} attribute in
1105 the structure member that refers to the detail member.  For example,
1106 if @code{tableId} is @code{-4122591256483201023}, then @code{table-id}
1107 would be 0xc6c99d183b300001.
1108
1109 The meaning of the other variable parts of the header is not known.  A
1110 writer may safely use version 3, true for @code{x0}, false for
1111 @code{x1}, true for @code{x2}, and 0x15 for @code{x3}.
1112
1113 @node SPV Light Member Titles
1114 @subsection Titles
1115
1116 @example
1117 Titles =>
1118     Value[title] 01?
1119     Value[subtype] 01? 31
1120     Value[user-title] 01?
1121     (31 Value[corner-text] @math{|} 58)
1122     (31 Value[caption] @math{|} 58)
1123 @end example
1124
1125 The Titles follow the Header and specify the table's title, caption,
1126 and corner text.
1127
1128 The @code{user-title} reflects any user
1129 editing of the title text or style.  The @code{title} is the title
1130 originally generated by the procedure.  Both of these are appropriate
1131 for presentation and localized to the user's language.  For example,
1132 for a frequency table, @code{title} and @code{user-title} normally
1133 name the variable and @code{c} is simply ``Frequencies''.
1134
1135 @code{subtype} is the same as the @code{subType} attribute in the
1136 @code{table} structure XML element that referred to this member.
1137 @xref{SPV Structure table Element}, for details.
1138
1139 The @code{corner-text}, if present, is shown in the upper-left corner
1140 of the table, above the row headings and to the left of the column
1141 headings.  It is usually absent.  When row dimension labels are
1142 displayed in the corner (see @code{show-row-labels-in-corner}), corner
1143 text is hidden.
1144
1145 The @code{caption}, if present, is shown below the table.
1146 @code{caption} reflects user editing of the caption.
1147
1148 @node SPV Light Member Footnotes
1149 @subsection Footnotes
1150
1151 @example
1152 Footnotes => int32[n-footnotes] Footnote*[n-footnotes]
1153 Footnote => Value[text] (58 @math{|} 31 Value[marker]) int32[show]
1154 @end example
1155
1156 Each footnote has @code{text} and an optional custom @code{marker}
1157 (such as @samp{*}).
1158
1159 The syntax for Value would allow footnotes (and their markers) to
1160 reference other footnotes, but in practice this doesn't work.
1161
1162 @code{show} is a 32-bit signed integer.  It is positive to show the
1163 footnote or negative to hide it.  Its magnitude is often 1, and in
1164 other cases tends to be the number of references to the footnote.
1165 It is safe to write 1 to show a footnote and -1 to hide it.
1166
1167 @node SPV Light Member Areas
1168 @subsection Areas
1169
1170 @example
1171 Areas => 00? Area*8
1172 Area =>
1173     byte[index] 31
1174     string[typeface] float[size] int32[style] bool[underline]
1175     int32[halign] int32[valign]
1176     string[fg-color] string[bg-color]
1177     bool[alternate] string[alt-fg-color] string[alt-bg-color]
1178     v3(int32[left-margin] int32[right-margin] int32[top-margin] int32[bottom-margin])
1179 @end example
1180
1181 Each Area represents the style for a different area of the table, in
1182 the following order: title, caption, footer, corner, column labels,
1183 row labels, data, and layers.
1184
1185 @code{index} is the 1-based index of the Area, i.e.@: 1 for the first
1186 Area, through 8 for the final Area.
1187
1188 @code{typeface} is the string name of the font used in the area.  In
1189 the corpus, this is @code{SansSerif} in over 99% of instances and
1190 @code{Times New Roman} in the rest.
1191
1192 @code{size} is the size of the font, in px (@pxref{SPV Light Detail
1193 Member Format}). The most common size in the corpus is 12 px.  Even
1194 though @code{size} has a floating-point type, in the corpus its values
1195 are always integers.
1196
1197 @code{style} is a bit mask.  Bit 0 (with value 1) is set for bold, bit
1198 1 (with value 2) is set for italic.
1199
1200 @code{underline} is 1 if the font is underlined, 0 otherwise.
1201
1202 @code{halign} specifies horizontal alignment: 0 for center, 2 for
1203 left, 4 for right, 61453 for decimal, 64173 for mixed.  Mixed
1204 alignment varies according to type: string data is left-justified,
1205 numbers and most other formats are right-justified.
1206
1207 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
1208 for bottom.
1209
1210 @code{fg-color} and @code{bg-color} are the foreground color and
1211 background color, respectively.  In the corpus, these are always
1212 @code{#000000} and @code{#ffffff}, respectively.
1213
1214 @code{alternate} is 1 if rows should alternate colors, 0 if all rows
1215 should be the same color.  When @code{alternate} is 1,
1216 @code{alt-fg-color} and @code{alt-bg-color} specify the colors for the
1217 alternate rows; otherwise they are empty strings.
1218
1219 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
1220 @code{bottom-margin} are measured in px.
1221
1222 @node SPV Light Member Borders
1223 @subsection Borders
1224
1225 @example
1226 Borders =>
1227     count(
1228         ib1[endian]
1229         be32[n-borders] Border*[n-borders]
1230         bool[show-grid-lines]
1231         00 00 00)
1232
1233 Border =>
1234     be32[border-type]
1235     be32[stroke-type]
1236     be32[color]
1237 @end example
1238
1239 The Borders reflect how borders between regions are drawn.
1240
1241 The fixed value of @code{endian} can be used to validate the
1242 endianness.
1243
1244 @code{show-grid-lines} is 1 to draw grid lines, otherwise 0.
1245
1246 Each Border describes one kind of border.  @code{n-borders} seems to
1247 always be 19.  Each @code{border-type} appears once (although in an
1248 unpredictable order) and correspond to the following borders:
1249
1250 @table @asis
1251 @item 0
1252 Title.
1253 @item 1@dots{}4
1254 Left, top, right, and bottom outer frame.
1255 @item 5@dots{}8
1256 Left, top, right, and bottom inner frame.
1257 @item 9, 10
1258 Left and top of data area.
1259 @item 11, 12
1260 Horizontal and vertical dimension rows.
1261 @item 13, 14
1262 Horizontal and vertical dimension columns.
1263 @item 15, 16
1264 Horizontal and vertical category rows.
1265 @item 17, 18
1266 Horizontal and vertical category columns.
1267 @end table
1268
1269 @code{stroke-type} describes how a border is drawn, as one of:
1270
1271 @table @asis
1272 @item 0
1273 No line.
1274 @item 1
1275 Solid line.
1276 @item 2
1277 Dashed line.
1278 @item 3
1279 Thick line.
1280 @item 4
1281 Thin line.
1282 @item 5
1283 Double line.
1284 @end table
1285
1286 @code{color} is an RGB color.  Bits 24--31 are alpha, bits 16--23 are
1287 red, 8--15 are green, 0--7 are blue.  An alpha of 255 indicates an
1288 opaque color, therefore opaque black is 0xff000000.
1289
1290 @node SPV Light Member Print Settings
1291 @subsection Print Settings
1292
1293 @example
1294 PrintSettings =>
1295     count(
1296         ib1[endian]
1297         bool[all-layers]
1298         bool[paginate-layers]
1299         bool[fit-width]
1300         bool[fit-length]
1301         bool[top-continuation]
1302         bool[bottom-continuation]
1303         be32[n-orphan-lines]
1304         bestring[continuation-string])
1305 @end example
1306
1307 The PrintSettings reflect settings for printing.  The fixed value of
1308 @code{endian} can be used to validate the endianness.
1309
1310 @code{all-layers} is 1 to print all layers, 0 to print only the layer
1311 designated by @code{current-layer} in TableSettings (@pxref{SPV Light
1312 Member Table Settings}).
1313
1314 @code{paginate-layers} is 1 to print each layer at the start of a new
1315 page, 0 otherwise.  (This setting is honored only @code{all-layers} is
1316 1, since otherwise only one layer is printed.)
1317
1318 @code{fit-width} and @code{fit-length} control whether the table is
1319 shrunk to fit within a page's width or length, respectively.
1320
1321 @code{n-orphan-lines} is the minimum number of rows or columns to put
1322 in one part of a table that is broken across pages.
1323
1324 If @code{top-continuation} is 1, then @code{continuation-string} is
1325 printed at the top of a page when a table is broken across pages for
1326 printing; similarly for @code{bottom-continuation} and the bottom of a
1327 page.  Usually, @code{continuation-string} is empty.
1328
1329 @node SPV Light Member Table Settings
1330 @subsection Table Settings
1331
1332 @example
1333 TableSettings =>
1334     count(
1335       v3(
1336         ib1[endian]
1337         be32[x5]
1338         be32[current-layer]
1339         bool[omit-empty]
1340         bool[show-row-labels-in-corner]
1341         bool[show-alphabetic-markers]
1342         bool[footnote-marker-superscripts]
1343         byte[x6]
1344         becount(
1345           Breakpoints[row-breaks] Breakpoints[column-breaks]
1346           Keeps[row-keeps] Keeps[column-keeps]
1347           PointKeeps[row-point-keeps] PointKeeps[column-point-keeps]
1348         )
1349         bestring[notes]
1350         bestring[table-look]
1351         )...)
1352
1353 Breakpoints => be32[n-breaks] be32*[n-breaks]
1354
1355 Keeps => be32[n-keeps] Keep*[n-keeps]
1356 Keep => be32[offset] be32[n]
1357
1358 PointKeeps => be32[n-point-keeps] PointKeep*[n-point-keeps]
1359 PointKeep => be32[offset] be32 be32
1360 @end example
1361
1362 The TableSettings reflect display settings.  The fixed value of
1363 @code{endian} can be used to validate the endianness.
1364
1365 @code{current-layer} is the displayed layer.  Suppose there are
1366 @math{d} layers, numbered 1 through @math{d} in the order given in the
1367 Dimensions (@pxref{SPV Light Member Dimensions}), and that the
1368 displayed value of dimension @math{i} is @math{d_i}, @math{0 \le x_i <
1369 n_i}, where @math{n_i} is the number of categories in dimension
1370 @math{i}.  Then @code{current-layer} is calculated by the following
1371 algorithm:
1372
1373 @display
1374 let @code{current-layer} = 0
1375 for each @math{i} from @math{d} downto 1:
1376     @code{current-layer} = (@math{n_i \times} @code{current-layer}) @math{+} @math{x_i}
1377 @end display
1378
1379 If @code{omit-empty} is 1, empty rows or columns (ones with nothing in
1380 any cell) are hidden; otherwise, they are shown.
1381
1382 If @code{show-row-labels-in-corner} is 1, then row labels are shown in
1383 the upper left corner; otherwise, they are shown nested.
1384
1385 If @code{show-alphabetic-markers} is 1, markers are shown as letters
1386 (e.g.@: @samp{a}, @samp{b}, @samp{c}, @dots{}); otherwise, they are
1387 shown as numbers starting from 1.
1388
1389 When @code{footnote-marker-superscripts} is 1, footnote markers are shown
1390 as superscripts, otherwise as subscripts.
1391
1392 The Breakpoints are rows or columns after which there is a page break;
1393 for example, a row break of 1 requests a page break after the second
1394 row.  Usually no breakpoints are specified, indicating that page
1395 breaks should be selected automatically.
1396
1397 The Keeps are ranges of rows or columns to be kept together without a
1398 page break; for example, a row Keep with @code{offset} 1 and @code{n}
1399 10 requests that the 10 rows starting with the second row be kept
1400 together.  Usually no Keeps are specified.
1401
1402 The PointKeeps seem to be generated automatically based on
1403 user-specified Keeps.  They seems to indicate a conversion from rows
1404 or columns to pixel or point offsets.
1405
1406 @code{notes} is a text string that contains user-specified notes.  It
1407 is displayed when the user hovers the cursor over the table, like text
1408 in the @code{title} attribute in HTML@.  It is not printed.  It is
1409 usually empty.
1410
1411 @code{table-look} is the name of a SPSS ``TableLook'' table style,
1412 such as ``Default'' or ``Academic''; it is often empty.
1413
1414 TableSettings ends with an arbitrary number of null bytes.  A writer
1415 may safely write 82 null bytes.
1416
1417 A writer may safely use 4 for @code{x5} and 0 for @code{x6}.
1418
1419 @node SPV Light Member Formats
1420 @subsection Formats
1421
1422 @example
1423 Formats =>
1424     int32[n-widths] int32*[n-widths]
1425     string[locale]
1426     int32[current-layer]
1427     bool[x7] bool[x8] bool[x9]
1428     Y0
1429     CustomCurrency
1430     count(
1431       v1(X0?)
1432       v3(count(X1 count(X2)) count(X3)))
1433 Y0 => int32[epoch] byte[decimal] byte[grouping]
1434 CustomCurrency => int32[n-ccs] string*[n-ccs]
1435 @end example
1436
1437 If @code{n-widths} is nonzero, then the accompanying integers are
1438 column widths as manually adjusted by the user.
1439
1440 @code{locale} is a locale including an encoding, such as
1441 @code{en_US.windows-1252} or @code{it_IT.windows-1252}.
1442 (@code{locale} is often duplicated in Y1, described below).
1443
1444 @code{epoch} is the year that starts the epoch.  A 2-digit year is
1445 interpreted as belonging to the 100 years beginning at the epoch.  The
1446 default epoch year is 69 years prior to the current year; thus, in
1447 2017 this field by default contains 1948.  In the corpus, @code{epoch}
1448 ranges from 1943 to 1948, plus some contain -1.
1449
1450 @code{decimal} is the decimal point character.  The observed values
1451 are @samp{.} and @samp{,}.
1452
1453 @code{grouping} is the grouping character.  Usually, it is @samp{,} if
1454 @code{decimal} is @samp{.}, and vice versa.  Other observed values are
1455 @samp{'} (apostrophe), @samp{ } (space), and zero (presumably
1456 indicating that digits should not be grouped).
1457
1458 @code{n-ccs} is observed as either 0 or 5.  When it is 5, the
1459 following strings are CCA through CCE format strings.  @xref{Custom
1460 Currency Formats,,, pspp, PSPP}.  Most commonly these are all
1461 @code{-,,,} but other strings occur.
1462
1463 A writer may safely use false for @code{x7}, @code{x8}, and @code{x9}.
1464
1465 @subsubheading X0
1466
1467 X0 only appears, optionally, in version 1 members.
1468
1469 @example
1470 X0 => byte*14 Y1 Y2
1471 Y1 =>
1472     string[command] string[command-local]
1473     string[language] string[charset] string[locale]
1474     bool[x10] bool[include-leading-zero] bool[x12] bool[x13]
1475     Y0
1476 Y2 => CustomCurrency byte[missing] bool[x17]
1477 @end example
1478
1479 @code{command} describes the statistical procedure that generated the
1480 output, in English.  It is not necessarily the literal syntax name of
1481 the procedure: for example, NPAR TESTS becomes ``Nonparametric
1482 Tests.''  @code{command-local} is the procedure's name, translated
1483 into the output language; it is often empty and, when it is not,
1484 sometimes the same as @code{command}.
1485
1486 @code{include-leading-zero} is the @code{LEADZERO} setting for the
1487 table, where false is @code{OFF} (the default) and true is @code{ON}.
1488 @xref{SET LEADZERO,,, pspp, PSPP}.
1489
1490 @code{missing} is the character used to indicate that a cell contains
1491 a missing value.  It is always observed as @samp{.}.
1492
1493 A writer may safely use false for @code{x10} and @code{x17} and true
1494 for @code{x12} and @code{x13}.
1495
1496 @subsubheading X1
1497
1498 X1 only appears in version 3 members.
1499
1500 @example
1501 X1 =>
1502     bool[x14]
1503     byte[show-title]
1504     bool[x16]
1505     byte[lang]
1506     byte[show-variables]
1507     byte[show-values]
1508     int32[x18] int32[x19]
1509     00*17
1510     bool[x20]
1511     bool[show-caption]
1512 @end example
1513
1514 @code{lang} may indicate the language in use.  Some values seem to be
1515 0: @t{en}, 1: @t{de}, 2: @t{es}, 3: @t{it}, 5: @t{ko}, 6: @t{pl}, 8:
1516 @t{zh-tw}, 10: @t{pt_BR}, 11: @t{fr}.
1517
1518 @code{show-variables} determines how variables are displayed by
1519 default.  A value of 1 means to display variable names, 2 to display
1520 variable labels when available, 3 to display both (name followed by
1521 label, separated by a space).  The most common value is 0, which
1522 probably means to use a global default.
1523
1524 @code{show-values} is a similar setting for values.  A value of 1
1525 means to display the value, 2 to display the value label when
1526 available, 3 to display both.  Again, the most common value is 0,
1527 which probably means to use a global default.
1528
1529 @code{show-title} is 1 to show the caption, 10 to hide it.
1530
1531 @code{show-caption} is true to show the caption, false to hide it.
1532
1533 A writer may safely use false for @code{x14}, false for @code{x16}, 0
1534 for @code{lang}, -1 for @code{x18} and @code{x19}, and false for
1535 @code{x20}.
1536
1537 @subsubheading X2
1538
1539 X2 only appears in version 3 members.
1540
1541 @example
1542 X2 =>
1543     int32[n-row-heights] int32*[n-row-heights]
1544     int32[n-style-map] StyleMap*[n-style-map]
1545     int32[n-styles] StylePair*[n-styles]
1546     count((i0 i0)?)
1547 StyleMap => int64[cell-index] int16[style-index]
1548 @end example
1549
1550 If present, @code{n-row-heights} and the accompanying integers are row
1551 heights as manually adjusted by the user.
1552
1553 The rest of X2 specifies styles for data cells.  At first glance this
1554 is odd, because each data cell can have its own style embedded as part
1555 of the data, but in practice X2 specifies a style for a cell only if
1556 that cell is empty (and thus does not appear in the data at all).
1557 Each StyleMap specifies the index of a blank cell, calculated the same
1558 was as in the Cells (@pxref{SPV Light Member Cells}), along with a
1559 0-based index into the accompanying StylePair array.
1560
1561 A writer may safely omit the optional @code{i0 i0} inside the
1562 @code{count(@dots{})}.
1563
1564 @subsubheading X3
1565
1566 X3 only appears in version 3 members.
1567
1568 @example
1569 X3 =>
1570     01 00 byte[x21] 00 00 00
1571     Y1
1572     double[small] 01
1573     (string[dataset] string[datafile] i0 int32[date] i0)?
1574     Y2
1575     (int32[x22] i0 01?)?
1576 @end example
1577
1578 @code{small} is a small real number.  In the corpus, it overwhelmingly
1579 takes the value 0.0001, with zero occasionally seen.  Nonzero numbers
1580 with format 40 (@pxref{SPV Light Member Value}) whose magnitudes are
1581 smaller than displayed in scientific notation.  (Thus, a @code{small}
1582 of zero prevents scientific notation from being chosen.)
1583
1584 @code{dataset} is the name of the dataset analyzed to produce the
1585 output, e.g.@: @code{DataSet1}, and @code{datafile} the name of the
1586 file it was read from, e.g.@: @file{C:\Users\foo\bar.sav}.  The latter
1587 is sometimes the empty string.
1588
1589 @code{date} is a date, as seconds since the epoch, i.e.@: since
1590 January 1, 1970.  Pivot tables within an SPV file often have dates a
1591 few minutes apart, so this is probably a creation date for the table
1592 rather than for the file.
1593
1594 Sometimes @code{dataset}, @code{datafile}, and @code{date} are present
1595 and other times they are absent.  The reader can distinguish by
1596 assuming that they are present and then checking whether the
1597 presumptive @code{dataset} contains a null byte (a valid string never
1598 will).
1599
1600 @code{x22} is usually 0 or 2000000.
1601
1602 A writer may safely use 4 for @code{x21} and omit @code{x22} and the
1603 other optional bytes at the end.
1604
1605 @subsubheading Encoding
1606
1607 Formats contains several indications of character encoding:
1608
1609 @itemize @bullet
1610 @item
1611 @code{locale} in Formats itself.
1612
1613 @item
1614 @code{locale} in Y1 (in version 1, Y1 is optionally nested inside X0;
1615 in version 3, Y1 is nested inside X3).
1616
1617 @item
1618 @code{charset} in version 3, in Y1.
1619
1620 @item
1621 @code{lang} in X1, in version 3.
1622 @end itemize
1623
1624 @code{charset}, if present, is a good indication of character
1625 encoding, and in its absence the encoding suffix on @code{locale} in
1626 Formats will work.
1627
1628 @code{locale} in Y1 can be disregarded: it is normally the same as
1629 @code{locale} in Formats, and it is only present if @code{charset} is
1630 also.
1631
1632 @code{lang} is not helpful and should be ignored for character
1633 encoding purposes.
1634
1635 However, the corpus contains many examples of light members whose
1636 strings are encoded in UTF-8 despite declaring some other character
1637 set.  Furthermore, the corpus contains several examples of light
1638 members in which some strings are encoded in UTF-8 (and contain
1639 multibyte characters) and other strings are encoded in another
1640 character set (and contain non-ASCII characters).  PSPP treats any
1641 valid UTF-8 string as UTF-8 and only falls back to the declared
1642 encoding for strings that are not valid UTF-8.
1643
1644 The @command{pspp-output} program's @command{strings} command can help
1645 analyze the encoding in an SPV light member.  Use @code{pspp-output
1646 --help-dev} to see its usage.
1647
1648 @node SPV Light Member Dimensions
1649 @subsection Dimensions
1650
1651 A pivot table presents multidimensional data.  A Dimension identifies
1652 the categories associated with each dimension.
1653
1654 @example
1655 Dimensions => int32[n-dims] Dimension*[n-dims]
1656 Dimension =>
1657     Value[name] DimProperties
1658     int32[n-categories] Category*[n-categories]
1659 DimProperties =>
1660     byte[x1]
1661     byte[x2]
1662     int32[x3]
1663     bool[hide-dim-label]
1664     bool[hide-all-labels]
1665     01 int32[dim-index]
1666 @end example
1667
1668 @code{name} is the name of the dimension, e.g.@: @code{Variables},
1669 @code{Statistics}, or a variable name.
1670
1671 The meanings of @code{x1} and @code{x3} are unknown.  @code{x1} is
1672 usually 0 but many other values have been observed.  A writer may
1673 safely use 0 for @code{x1} and 2 for @code{x3}.
1674
1675 @code{x2} is 0, 1, or 2.  For a pivot table with @var{L} layer
1676 dimensions, @var{R} row dimensions, and @var{C} column dimensions,
1677 @code{x2} is 2 for the first @var{L} dimensions, 0 for the next
1678 @var{R} dimensions, and 1 for the remaining @var{C} dimensions.  This
1679 does not mean that the layer dimensions must be presented first,
1680 followed by the row dimensions, followed by the column dimensions---on
1681 the contrary, they are frequently in a different order---but @code{x2}
1682 must follow this pattern to prevent the pivot table from being
1683 misinterpreted.
1684
1685 If @code{hide-dim-label} is 00, the pivot table displays a label for
1686 the dimension itself.  Because usually the group and category labels
1687 are enough explanation, it is usually 01.
1688
1689 If @code{hide-all-labels} is 01, the pivot table omits all labels for
1690 the dimension, including group and category labels.  It is usually 00.
1691 When @code{hide-all-labels} is 01, @code{show-dim-label} is ignored.
1692
1693 @code{dim-index} is usually the 0-based index of the dimension, e.g.@:
1694 0 for the first dimension, 1 for the second, and so on.  Sometimes it
1695 is -1.  There is no visible difference.  A writer may safely use the
1696 0-based index.
1697
1698 @node SPV Light Member Categories
1699 @subsection Categories
1700
1701 Categories are arranged in a tree.  Only the leaf nodes in the tree
1702 are really categories; the others just serve as grouping constructs.
1703
1704 @example
1705 Category => Value[name] (Leaf @math{|} Group)
1706 Leaf => 00 00 00 i2 int32[leaf-index] i0
1707 Group =>
1708     bool[merge] 00 01 int32[x23]
1709     i-1 int32[n-subcategories] Category*[n-subcategories]
1710 @end example
1711
1712 @code{name} is the name of the category (or group).
1713
1714 A Leaf represents a leaf category.  The Leaf's @code{leaf-index} is a
1715 nonnegative integer unique within the Dimension and less than
1716 @code{n-categories} in the Dimension.  If the user does not sort or
1717 rearrange the categories, then @code{leaf-index} starts at 0 for the
1718 first Leaf in the dimension and increments by 1 with each successive
1719 Leaf.  If the user does sorts or rearrange the categories, then the
1720 order of categories in the file reflects that change and
1721 @code{leaf-index} reflects the original order.
1722
1723 A dimension can have no leaf categories at all.  A table that
1724 contains such a dimension necessarily has no data at all.
1725
1726 A Group is a group of nested categories.  Usually a Group contains at
1727 least one Category, so that @code{n-subcategories} is positive, but
1728 Groups with zero subcategories have been observed.
1729
1730 If a Group's @code{merge} is 00, the most common value, then the group
1731 is really a distinct group that should be represented as such in the
1732 visual representation and user interface.  If @code{merge} is 01, the
1733 categories in this group should be shown and treated as if they were
1734 direct children of the group's containing group (or if it has no
1735 parent group, then direct children of the dimension), and this group's
1736 name is irrelevant and should not be displayed.  (Merged groups can be
1737 nested!)
1738
1739 Writers need not use merged groups.
1740
1741 A Group's @code{x23} appears to be i2 when all of the categories
1742 within a group are leaf categories that directly represent data values
1743 for a variable (e.g.@: in a frequency table or crosstabulation, a group
1744 of values in a variable being tabulated) and i0 otherwise.  A writer
1745 may safely write a constant 0 in this field.
1746
1747 @node SPV Light Member Axes
1748 @subsection Axes
1749
1750 After the dimensions come assignment of each dimension to one of the
1751 axes: layers, rows, and columns.
1752
1753 @example
1754 Axes =>
1755     int32[n-layers] int32[n-rows] int32[n-columns]
1756     int32*[n-layers] int32*[n-rows] int32*[n-columns]
1757 @end example
1758
1759 The values of @code{n-layers}, @code{n-rows}, and @code{n-columns}
1760 each specifies the number of dimensions displayed in layers, rows, and
1761 columns, respectively.  Any of them may be zero.  Their values sum to
1762 @code{n-dimensions} from Dimensions (@pxref{SPV Light Member
1763 Dimensions}).
1764
1765 The following @code{n-dimensions} integers, in three groups, are a
1766 permutation of the 0-based dimension numbers.  The first
1767 @code{n-layers} integers specify each of the dimensions represented by
1768 layers, the next @code{n-rows} integers specify the dimensions
1769 represented by rows, and the final @code{n-columns} integers specify
1770 the dimensions represented by columns.  When there is more than one
1771 dimension of a given kind, the inner dimensions are given first.  (For
1772 the layer axis, this means that the first dimension is at the bottom
1773 of the list and the last dimension is at the top when the current
1774 layer is displayed.)
1775
1776 @node SPV Light Member Cells
1777 @subsection Cells
1778
1779 The final part of an SPV light member contains the actual data.
1780
1781 @example
1782 Cells => int32[n-cells] Cell*[n-cells]
1783 Cell => int64[index] v1(00?) Value
1784 @end example
1785
1786 A Cell consists of an @code{index} and a Value.  Suppose there are
1787 @math{d} dimensions, numbered 1 through @math{d} in the order given in
1788 the Dimensions previously, and that dimension @math{i} has @math{n_i}
1789 categories.  Consider the cell at coordinates @math{x_i}, @math{1 \le
1790 i \le d}, and note that @math{0 \le x_i < n_i}.  Then the index is
1791 calculated by the following algorithm:
1792
1793 @display
1794 let @i{index} = 0
1795 for each @math{i} from 1 to @math{d}:
1796     @i{index} = (@math{n_i \times} @i{index}) @math{+} @math{x_i}
1797 @end display
1798
1799 For example, suppose there are 3 dimensions with 3, 4, and 5
1800 categories, respectively.  The cell at coordinates (1, 2, 3) has
1801 index @math{5 \times (4 \times (3 \times 0 + 1) + 2) + 3 = 33}.
1802 Within a given dimension, the index is the @code{leaf-index} in a Leaf.
1803
1804 @node SPV Light Member Value
1805 @subsection Value
1806
1807 Value is used throughout the SPV light member format.  It boils down
1808 to a number or a string.
1809
1810 @example
1811 Value => 00? 00? 00? 00? RawValue
1812 RawValue =>
1813     01 ValueMod int32[format] double[x]
1814   @math{|} 02 ValueMod int32[format] double[x]
1815     string[var-name] string[value-label] byte[show]
1816   @math{|} 03 string[local] ValueMod string[id] string[c] bool[fixed]
1817   @math{|} 04 ValueMod int32[format] string[value-label] string[var-name]
1818     byte[show] string[s]
1819   @math{|} 05 ValueMod string[var-name] string[var-label] byte[show]
1820   @math{|} 06 string[local] ValueMod string[id] string[c]
1821   @math{|} ValueMod string[template] int32[n-args] Argument*[n-args]
1822 Argument =>
1823     i0 Value
1824   @math{|} int32[x] i0 Value*[x]      /* x > 0 */
1825 @end example
1826
1827 There are several possible encodings, which one can distinguish by the
1828 first nonzero byte in the encoding.
1829
1830 @table @asis
1831 @item 01
1832 The numeric value @code{x}, intended to be presented to the user
1833 formatted according to @code{format}, which is about the same as the
1834 format described for system files (@pxref{System File Output
1835 Formats}).  The exception is that format 40 is not MTIME but instead
1836 approximately a synonym for F format with a different rule for whether
1837 a value is shown in scientific notation: a value in format 40 is shown
1838 in scientific notation if and only if it is nonzero and its magnitude
1839 is less than @code{small} (@pxref{SPV Light Member Formats}).
1840
1841 Most commonly, @code{format} has width 40 (the maximum).
1842
1843 An @code{x} with the maximum negative double value @code{-DBL_MAX}
1844 represents the system-missing value SYSMIS.  (HIGHEST and LOWEST have
1845 not been observed.)  See @ref{System File Format}, for more about
1846 these special values.
1847
1848 @item 02
1849 Similar to @code{01}, with the additional information that @code{x} is
1850 a value of variable @code{var-name} and has value label
1851 @code{value-label}.  Both @code{var-name} and @code{value-label} can
1852 be the empty string, the latter very commonly.
1853
1854 @code{show} determines whether to show the numeric value or the value
1855 label.  A value of 1 means to show the value, 2 to show the label, 3
1856 to show both, and 0 means to use the default specified in
1857 @code{show-values} (@pxref{SPV Light Member Formats}).
1858
1859 @item 03
1860 A text string, in two forms: @code{c} is in English, and sometimes
1861 abbreviated or obscure, and @code{local} is localized to the user's
1862 locale.  In an English-language locale, the two strings are often the
1863 same, and in the cases where they differ, @code{local} is more
1864 appropriate for a user interface, e.g.@: @code{c} of ``Not a PxP table
1865 for MCN...'' versus @code{local} of ``Computed only for a PxP table,
1866 where P must be greater than 1.''
1867
1868 @code{c} and @code{local} are always either both empty or both
1869 nonempty.
1870
1871 @code{id} is a brief identifying string whose form seems to resemble a
1872 programming language identifier, e.g.@: @code{cumulative_percent} or
1873 @code{factor_14}.  It is not unique.
1874
1875 @code{fixed} is 00 for text taken from user input, such as syntax
1876 fragment, expressions, file names, data set names, and 01 for fixed
1877 text strings such as names of procedures or statistics.  In the former
1878 case, @code{id} is always the empty string; in the latter case,
1879 @code{id} is still sometimes empty.
1880
1881 @item 04
1882 The string value @code{s}, intended to be presented to the user
1883 formatted according to @code{format}.  The format for a string is not
1884 too interesting, and the corpus contains many clearly invalid formats
1885 like A16.39 or A255.127 or A134.1, so readers should probably entirely
1886 disregard the format.  PSPP only checks @code{format} to distinguish
1887 AHEX format.
1888
1889 @code{s} is a value of variable @code{var-name} and has value label
1890 @code{value-label}.  @code{var-name} is never empty but
1891 @code{value-label} is commonly empty.
1892
1893 @code{show} has the same meaning as in the encoding for 02.
1894
1895 @item 05
1896 Variable @code{var-name} with variable label @code{var-label}.  In the
1897 corpus, @code{var-name} is rarely empty and @code{var-label} is often
1898 empty.
1899
1900 @code{show} determines whether to show the variable name or the
1901 variable label.  A value of 1 means to show the name, 2 to show the
1902 label, 3 to show both, and 0 means to use the default specified in
1903 @code{show-variables} (@pxref{SPV Light Member Formats}).
1904
1905 @item 06
1906 Similar to type 03, with @code{fixed} assumed to be true.
1907
1908 @item otherwise
1909 When the first byte of a RawValue is not one of the above, the
1910 RawValue starts with a ValueMod, whose syntax is described in the next
1911 section.  (A ValueMod always begins with byte 31 or 58.)
1912
1913 This case is a template string, analogous to @code{printf}, followed
1914 by one or more Arguments, each of which has one or more values.  The
1915 template string is copied directly into the output except for the
1916 following special syntax,
1917
1918 @table @code
1919 @item \%
1920 @itemx \:
1921 @itemx \[
1922 @itemx \]
1923 Each of these expands to the character following @samp{\\}, to escape
1924 characters that have special meaning in template strings.  These are
1925 effective inside and outside the @code{[@dots{}]}  syntax forms
1926 described below.
1927
1928 @item \n
1929 Expands to a new-line, inside or outside the @code{[@dots{}]} forms
1930 described below.
1931
1932 @item ^@var{i}
1933 Expands to a formatted version of argument @var{i}, which must have
1934 only a single value.  For example, @code{^1} expands to the first
1935 argument's @code{value}.
1936
1937 @item [:@var{a}:]@var{i}
1938 Expands @var{a} for each of the values in @var{i}.  @var{a}
1939 should contain one or more @code{^@var{j}} conversions, which are
1940 drawn from the values for argument @var{i} in order.  Some examples
1941 from the corpus:
1942
1943 @table @code
1944 @item [:^1:]1
1945 All of the values for the first argument, concatenated.
1946
1947 @item [:^1\n:]1
1948 Expands to the values for the first argument, each followed by
1949 a new-line.
1950
1951 @item [:^1 = ^2:]2
1952 Expands to @code{@var{x} = @var{y}} where @var{x} is the second
1953 argument's first value and @var{y} is its second value.  (This would
1954 be used only if the argument has two values.  If there were more
1955 values, the second and third values would be directly concatenated,
1956 which would look funny.)
1957 @end table
1958
1959 @item [@var{a}:@var{b}:]@var{i}
1960 This extends the previous form so that the first values are expanded
1961 using @var{a} and later values are expanded using @var{b}.  For an
1962 unknown reason, within @var{a} the @code{^@var{j}} conversions are
1963 instead written as @code{%@var{j}}.  Some examples from the corpus:
1964
1965 @table @code
1966 @item [%1:*^1:]1
1967 Expands to all of the values for the first argument, separated by
1968 @samp{*}.
1969
1970 @item [%1 = %2:, ^1 = ^2:]1
1971 Given appropriate values for the first argument, expands to @code{X =
1972 1, Y = 2, Z = 3}.
1973
1974 @item [%1:, ^1:]1
1975 Given appropriate values, expands to @code{1, 2, 3}.
1976 @end table
1977 @end table
1978
1979 The template string is localized to the user's locale.
1980 @end table
1981
1982 A writer may safely omit all of the optional 00 bytes at the beginning
1983 of a Value, except that it should write a single 00 byte before a
1984 templated Value.
1985
1986 @node SPV Light Member ValueMod
1987 @subsection ValueMod
1988
1989 A ValueMod can specify special modifications to a Value.
1990
1991 @example
1992 ValueMod =>
1993     58
1994   @math{|} 31
1995     int32[n-refs] int16*[n-refs]
1996     int32[n-subscripts] string*[n-subscripts]
1997     v1(00 (i1 | i2) 00? 00? int32 00? 00?)
1998     v3(count(TemplateString StylePair))
1999
2000 TemplateString => count((count((i0 (58 @math{|} 31 55))?) (58 @math{|} 31 string[id]))?)
2001
2002 StylePair =>
2003     (31 FontStyle | 58)
2004     (31 CellStyle | 58)
2005
2006 FontStyle =>
2007     bool[bold] bool[italic] bool[underline] bool[show]
2008     string[fg-color] string[bg-color]
2009     string[typeface] byte[size]
2010
2011 CellStyle =>
2012     int32[halign] int32[valign] double[decimal-offset]
2013     int16[left-margin] int16[right-margin]
2014     int16[top-margin] int16[bottom-margin]
2015 @end example
2016
2017 A ValueMod that begins with ``31'' specifies special modifications to
2018 a Value.
2019
2020 Each of the @code{n-refs} integers is a reference to a Footnote
2021 (@pxref{SPV Light Member Footnotes}) by 0-based index.  Footnote
2022 markers are shown appended to the main text of the Value, as
2023 superscripts or subscripts.
2024
2025 The @code{subscripts}, if present, are strings to append to the main
2026 text of the Value, as subscripts.  Each subscript text is a brief
2027 indicator, e.g.@: @samp{a} or @samp{b}, with its meaning indicated by
2028 the table caption.  When multiple subscripts are present, they are
2029 displayed separated by commas.
2030
2031 The @code{id} inside the TemplateString, if present, is a template
2032 string for substitutions using the syntax explained previously.  It
2033 appears to be an English-language version of the localized template
2034 string in the Value in which the Template is nested.  A writer may
2035 safely omit the optional fixed data in TemplateString.
2036
2037 FontStyle and CellStyle, if present, change the style for this
2038 individual Value.  In FontStyle, @code{bold}, @code{italic}, and
2039 @code{underline} control the particular style.  @code{show} is
2040 ordinarily 1; if it is 0, then the cell data is not shown.
2041 @code{fg-color} and @code{bg-color} are strings in the format
2042 @code{#rrggbb}, e.g.@: @code{#ff0000} for red or @code{#ffffff} for
2043 white.  The empty string is occasionally observed also.  The
2044 @code{size} is a font size in units of 1/128 inch.
2045
2046 In CellStyle, @code{halign} is 0 for center, 2 for left, 4 for right,
2047 6 for decimal, 0xffffffad for mixed.  For decimal alignment,
2048 @code{decimal-offset} is the decimal point's offset from the right
2049 side of the cell, in pt (@pxref{SPV Light Detail Member Format}).
2050 @code{valign} specifies vertical alignment: 0 for center, 1 for top, 3
2051 for bottom.  @code{left-margin}, @code{right-margin},
2052 @code{top-margin}, and @code{bottom-margin} are in pt.
2053
2054 @node SPV Legacy Detail Member Binary Format
2055 @section Legacy Detail Member Binary Format
2056
2057 Whereas the light binary format represents everything about a given
2058 pivot table, the legacy binary format conceptually consists of a
2059 number of named sources, each of which consists of a number of named
2060 variables, each of which is a 1-dimensional array of numbers or
2061 strings or a mix.  Thus, the legacy binary member format is quite
2062 simple.
2063
2064 This section uses the same context-free grammar notation as in the
2065 previous section, with the following additions:
2066
2067 @table @asis
2068 @item vAF(@var{x})
2069 In a version 0xaf legacy member, @var{x}; in other versions, nothing.
2070 (The legacy member header indicates the version; see below.)
2071
2072 @item vB0(@var{x})
2073 In a version 0xb0 legacy member, @var{x}; in other versions, nothing.
2074 @end table
2075
2076 A legacy detail member @file{.bin} has the following overall format:
2077
2078 @example
2079 LegacyBinary =>
2080     00 byte[version] int16[n-sources] int32[member-size]
2081     Metadata*[n-sources]
2082     #Data*[n-sources]
2083     #Strings?
2084 @end example
2085
2086 @code{version} is a version number that affects the interpretation of
2087 some of the other data in the member.  Versions 0xaf and 0xb0 are
2088 known.  We will refer to ``version 0xaf'' and ``version 0xb0'' members
2089 later on.
2090
2091 A legacy member consists of @code{n-sources} data sources, each of
2092 which has Metadata and Data.
2093
2094 @code{member-size} is the size of the legacy binary member, in bytes.
2095
2096 The Data and Strings above are commented out because the Metadata has
2097 some oddities that mean that the Data sometimes seems to start at
2098 an unexpected place.  The following section goes into detail.
2099
2100 @menu
2101 * SPV Legacy Member Metadata::
2102 * SPV Legacy Member Numeric Data::
2103 * SPV Legacy Member String Data::
2104 @end menu
2105
2106 @node SPV Legacy Member Metadata
2107 @subsection Metadata
2108
2109 @example
2110 Metadata =>
2111     int32[n-values] int32[n-variables] int32[data-offset]
2112     vAF(byte*28[source-name])
2113     vB0(byte*64[source-name] int32[x])
2114 @end example
2115
2116 A data source has @code{n-variables} variables, each with
2117 @code{n-values} data values.
2118
2119 @code{source-name} is a 28- or 64-byte string padded on the right with
2120 0-bytes.  The names that appear in the corpus are very generic:
2121 usually @code{tableData} for pivot table data or @code{source0} for
2122 chart data.
2123
2124 A given Metadata's @code{data-offset} is the offset, in bytes, from
2125 the beginning of the member to the start of the corresponding Data.
2126 This allows programs to skip to the beginning of the data for a
2127 particular source.  In every case in the corpus, the Data follow the
2128 Metadata in the same order, but it is important to use
2129 @code{data-offset} instead of reading sequentially through the file
2130 because of the exception described below.
2131
2132 One SPV file in the corpus has legacy binary members with version 0xb0
2133 but a 28-byte @code{source-name} field (and only a single source).  In
2134 practice, this means that the 64-byte @code{source-name} used in
2135 version 0xb0 has a lot of 0-bytes in the middle followed by the
2136 @code{variable-name} of the following Data.  As long as a reader
2137 treats the first 0-byte in the @code{source-name} as terminating the
2138 string, it can properly interpret these members.
2139
2140 The meaning of @code{x} in version 0xb0 is unknown.
2141
2142 @node SPV Legacy Member Numeric Data
2143 @subsection Numeric Data
2144
2145 @example
2146 Data => Variable*[n-variables]
2147 Variable => byte*288[variable-name] double*[n-values]
2148 @end example
2149
2150 Data follow the Metadata in the legacy binary format, with sources in
2151 the same order (but readers should use the @code{data-offset} in
2152 Metadata records, rather than reading sequentially).  Each Variable
2153 begins with a @code{variable-name} that generally indicates its role
2154 in the pivot table, e.g.@: ``cell'', ``cellFormat'',
2155 ``dimension0categories'', ``dimension0group0'', followed by the
2156 numeric data, one double per datum.  A double with the maximum
2157 negative double @code{-DBL_MAX} represents the system-missing value
2158 SYSMIS.
2159
2160 @node SPV Legacy Member String Data
2161 @subsection String Data
2162
2163 @example
2164 Strings => SourceMaps[maps] Labels
2165
2166 SourceMaps => int32[n-maps] SourceMap*[n-maps]
2167
2168 SourceMap => string[source-name] int32[n-variables] VariableMap*[n-variables]
2169 VariableMap => string[variable-name] int32[n-data] DatumMap*[n-data]
2170 DatumMap => int32[value-idx] int32[label-idx]
2171
2172 Labels => int32[n-labels] Label*[n-labels]
2173 Label => int32[frequency] string[label]
2174 @end example
2175
2176 Each variable may include a mix of numeric and string data values.  If
2177 a legacy binary member contains any string data, Strings is present;
2178 otherwise, it ends just after the last Data element.
2179
2180 The string data overlays the numeric data.  When a variable includes
2181 any string data, its Variable represents the string values with a
2182 SYSMIS or NaN placeholder.  (Not all such values need be
2183 placeholders.)
2184
2185 Each SourceMap provides a mapping between SYSMIS or NaN values in source
2186 @code{source-name} and the string data that they represent.
2187 @code{n-variables} is the number of variables in the source that
2188 include string data.  More precisely, it is the 1-based index of the
2189 last variable in the source that includes any string data; thus, it
2190 would be 4 if there are 5 variables and only the fourth one includes
2191 string data.
2192
2193 A VariableMap repeats its variable's name, but variables are always
2194 present in the same order as the source, starting from the first
2195 variable, without skipping any even if they have no string values.
2196 Each VariableMap contains DatumMap nonterminals, each of which maps
2197 from a 0-based index within its variable's data to a 0-based label
2198 index, e.g.@: pair @code{value-idx} = 2, @code{label-idx} = 3, means
2199 that the third data value (which must be SYSMIS or NaN) is to be
2200 replaced by the string of the fourth Label.
2201
2202 The labels themselves follow the pairs.  The valuable part of each
2203 label is the string @code{label}.  Each label also includes a
2204 @code{frequency} that reports the number of DatumMaps that reference
2205 it (although this is not useful).
2206
2207 @node SPV Legacy Detail Member XML Format
2208 @section Legacy Detail Member XML Format
2209
2210 The design of the detail XML format is not what one would end up with
2211 for describing pivot tables.  This is because it is a special case
2212 of a much more general format (``visualization XML'' or ``VizML'')
2213 that can describe a wide range of visualizations.  Most of this
2214 generality is overkill for tables, and so we end up with a funny
2215 subset of a general-purpose format.
2216
2217 An XML Schema for VizML is available, distributed with SPSS binaries,
2218 under a nonfree license.  It contains documentation that is
2219 occasionally helpful.
2220
2221 This section describes the detail XML format using the same notation
2222 already used for the structure XML format (@pxref{SPV Structure Member
2223 Format}).  See @file{src/output/spv/detail-xml.grammar} in the PSPP
2224 source tree for the full grammar that it uses for parsing.
2225
2226 The important elements of the detail XML format are:
2227
2228 @itemize @bullet
2229 @item
2230 Variables.  @xref{SPV Detail Variable Elements}.
2231
2232 @item
2233 Assignment of variables to axes.  A variable can appear as columns, or
2234 rows, or layers.  The @code{faceting} element and its sub-elements
2235 describe this assignment.
2236
2237 @item
2238 Styles and other annotations.
2239 @end itemize
2240
2241 This description is not detailed enough to write legacy tables.
2242 Instead, write tables in the light binary format.
2243
2244 @menu
2245 * SPV Detail visualization Element::
2246 * SPV Detail Variable Elements::
2247 * SPV Detail extension Element::
2248 * SPV Detail graph Element::
2249 * SPV Detail location Element::
2250 * SPV Detail faceting Element::
2251 * SPV Detail facetLayout Element::
2252 * SPV Detail label Element::
2253 * SPV Detail setCellProperties Element::
2254 * SPV Detail setFormat Element::
2255 * SPV Detail interval Element::
2256 * SPV Detail style Element::
2257 * SPV Detail labelFrame Element::
2258 * SPV Detail Legacy Properties::
2259 @end menu
2260
2261 @node SPV Detail visualization Element
2262 @subsection The @code{visualization} Element
2263
2264 @example
2265 visualization
2266    :creator
2267    :date
2268    :lang
2269    :name
2270    :style[style_ref]=ref style
2271    :type
2272    :version
2273    :schemaLocation?
2274 => visualization_extension?
2275    userSource
2276    (sourceVariable | derivedVariable)+
2277    categoricalDomain?
2278    graph
2279    labelFrame[lf1]*
2280    container?
2281    labelFrame[lf2]*
2282    style+
2283    layerController?
2284
2285 extension[visualization_extension]
2286    :numRows=int?
2287    :showGridline=bool?
2288    :minWidthSet=(true)?
2289    :maxWidthSet=(true)?
2290 => EMPTY
2291
2292 userSource :missing=(listwise | pairwise)? => EMPTY
2293
2294 categoricalDomain => variableReference simpleSort
2295
2296 simpleSort :method[sort_method]=(custom) => categoryOrder
2297
2298 container :style=ref style => container_extension? location+ labelFrame*
2299
2300 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2301
2302 layerController
2303    :source=(tableData)
2304    :target=ref label?
2305 => EMPTY
2306 @end example
2307
2308 The @code{visualization} element is the root of detail XML member.  It
2309 has the following attributes:
2310
2311 @defvr {Attribute} creator
2312 The version of the software that created this SPV file, as a string of
2313 the form @code{xxyyzz}, which represents software version xx.yy.zz,
2314 e.g.@: @code{160001} is version 16.0.1.  The corpus includes major
2315 versions 16 through 19.
2316 @end defvr
2317
2318 @defvr {Attribute} date
2319 The date on the which the file was created, as a string of the form
2320 @code{YYYY-MM-DD}.
2321 @end defvr
2322
2323 @defvr {Attribute} lang
2324 The locale used for output, in Windows format, which is similar to the
2325 format used in Unix with the underscore replaced by a hyphen, e.g.@:
2326 @code{en-US}, @code{en-GB}, @code{el-GR}, @code{sr-Cryl-RS}.
2327 @end defvr
2328
2329 @defvr {Attribute} name
2330 The title of the pivot table, localized to the output language.
2331 @end defvr
2332
2333 @defvr {Attribute} style
2334 The base style for the pivot table.  In every example in the corpus,
2335 the @code{style} element has no attributes other than @code{id}.
2336 @end defvr
2337
2338 @defvr {Attribute} type
2339 A floating-point number.  The meaning is unknown.
2340 @end defvr
2341
2342 @defvr {Attribute} version
2343 The visualization schema version number.  In the corpus, the value is
2344 one of 2.4, 2.5, 2.7, and 2.8.
2345 @end defvr
2346
2347 The @code{userSource} element has no visible effect.
2348
2349 The @code{extension} element as a child of @code{visualization} has
2350 the following attributes.
2351
2352 @defvr {Attribute} numRows
2353 An integer that presumably defines the number of rows in the displayed
2354 pivot table.
2355 @end defvr
2356
2357 @defvr {Attribute} showGridline
2358 Always set to @code{false} in the corpus.
2359 @end defvr
2360
2361 @defvr {Attribute} minWidthSet
2362 @defvrx {Attribute} maxWidthSet
2363 Always set to @code{true} in the corpus.
2364 @end defvr
2365
2366 The @code{extension} element as a child of @code{container} has the
2367 following attribute
2368
2369 @defvr {Attribute} combinedFootnotes
2370 Meaning unknown.
2371 @end defvr
2372
2373 The @code{categoricalDomain} and @code{simpleSort} elements have no
2374 visible effect.
2375
2376 The @code{layerController} element has no visible effect.
2377
2378 @node SPV Detail Variable Elements
2379 @subsection Variable Elements
2380
2381 A ``variable'' in detail XML is a 1-dimensional array of data.  Each
2382 element of the array may, independently, have string or numeric
2383 content.  All of the variables in a given detail XML member either
2384 have the same number of elements or have zero elements.
2385
2386 Two different elements define variables and their content:
2387
2388 @table @code
2389 @item sourceVariable
2390 These variables' data comes from the associated @code{tableData.bin}
2391 member.
2392
2393 @item derivedVariable
2394 These variables are defined in terms of a mapping function from a
2395 source variable, or they are empty.
2396 @end table
2397
2398 A variable named @code{cell} always exists.  This variable holds the
2399 data displayed in the table.
2400
2401 Variables in detail XML roughly correspond to the dimensions in a
2402 light detail member.  Each dimension has the following variables with
2403 stylized names, where @var{n} is a number for the dimension starting
2404 from 0:
2405
2406 @table @code
2407 @item dimension@var{n}categories
2408 The dimension's leaf categories (@pxref{SPV Light Member Categories}).
2409
2410 @item dimension@var{n}group0
2411 Present only if the dimension's categories are grouped, this variable
2412 holds the group labels for the categories.  Grouping is inferred
2413 through adjacent identical labels.  Categories that are not part of a
2414 group have empty-string data in this variable.
2415
2416 @item dimension@var{n}group1
2417 Present only if the first-level groups are further grouped, this
2418 variable holds the labels for the second-level groups.  There can be
2419 additional variables with further levels of grouping.
2420
2421 @item dimension@var{n}
2422 An empty variable.
2423 @end table
2424
2425 Determining the data for a (non-empty) variable is a multi-step
2426 process:
2427
2428 @enumerate
2429 @item
2430 Draw initial data from its source, for a @code{sourceVariable}, or
2431 from another named variable, for a @code{derivedVariable}.
2432
2433 @item
2434 Apply mappings from @code{valueMapEntry} elements within the
2435 @code{derivedVariable} element, if any.
2436
2437 @item
2438 Apply mappings from @code{relabel} elements within a @code{format} or
2439 @code{stringFormat} element in the @code{sourceVariable} or
2440 @code{derivedVariable} element, if any.
2441
2442 @item
2443 If the variable is a @code{sourceVariable} with a @code{labelVariable}
2444 attribute, and there were no mappings to apply in previous steps, then
2445 replace each element of the variable by the corresponding value in the
2446 label variable.
2447 @end enumerate
2448
2449 A single variable's data can be modified in two of the steps, if both
2450 @code{valueMapEntry} and @code{relabel} are used.  The following
2451 example from the corpus maps several integers to 2, then maps 2 in
2452 turn to the string ``Input'':
2453
2454 @example
2455 <derivedVariable categorical="true" dependsOn="dimension0categories"
2456                  id="dimension0group0map" value="map(dimension0group0)">
2457   <stringFormat>
2458     <relabel from="2" to="Input"/>
2459     <relabel from="10" to="Missing Value Handling"/>
2460     <relabel from="14" to="Resources"/>
2461     <relabel from="0" to=""/>
2462     <relabel from="1" to=""/>
2463     <relabel from="13" to=""/>
2464   </stringFormat>
2465   <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
2466   <valueMapEntry from="10;11" to="10"/>
2467   <valueMapEntry from="14;15" to="14"/>
2468   <valueMapEntry from="0" to="0"/>
2469   <valueMapEntry from="1" to="1"/>
2470   <valueMapEntry from="13" to="13"/>
2471 </derivedVariable>
2472 @end example
2473
2474 @menu
2475 * SPV Detail sourceVariable Element::
2476 * SPV Detail derivedVariable Element::
2477 * SPV Detail valueMapEntry Element::
2478 @end menu
2479
2480 @node SPV Detail sourceVariable Element
2481 @subsubsection The @code{sourceVariable} Element
2482
2483 @example
2484 sourceVariable
2485    :id
2486    :categorical=(true)
2487    :source
2488    :domain=ref categoricalDomain?
2489    :sourceName
2490    :dependsOn=ref sourceVariable?
2491    :label?
2492    :labelVariable=ref sourceVariable?
2493 => variable_extension* (format | stringFormat)?
2494 @end example
2495
2496 This element defines a variable whose data comes from the
2497 @file{tableData.bin} member that corresponds to this @file{.xml}.
2498
2499 This element has the following attributes.
2500
2501 @defvr {Attribute} id
2502 An @code{id} is always present because this element exists to be
2503 referenced from other elements.
2504 @end defvr
2505
2506 @defvr {Attribute} categorical
2507 Always set to @code{true}.
2508 @end defvr
2509
2510 @defvr {Attribute} source
2511 Always set to @code{tableData}, the @code{source-name} in the
2512 corresponding @file{tableData.bin} member (@pxref{SPV Legacy Member
2513 Metadata}).
2514 @end defvr
2515
2516 @defvr {Attribute} sourceName
2517 The name of a variable within the source, corresponding to the
2518 @code{variable-name} in the @file{tableData.bin} member (@pxref{SPV
2519 Legacy Member Numeric Data}).
2520 @end defvr
2521
2522 @defvr {Attribute} label
2523 The variable label, if any.
2524 @end defvr
2525
2526 @defvr {Attribute} labelVariable
2527 The @code{variable-name} of a variable whose string values correspond
2528 one-to-one with the values of this variable and are suitable for use
2529 as value labels.
2530 @end defvr
2531
2532 @defvr {Attribute} dependsOn
2533 This attribute doesn't affect the display of a table.
2534 @end defvr
2535
2536 @node SPV Detail derivedVariable Element
2537 @subsubsection The @code{derivedVariable} Element
2538
2539 @example
2540 derivedVariable
2541    :id
2542    :categorical=(true)
2543    :value
2544    :dependsOn=ref sourceVariable?
2545 => variable_extension* (format | stringFormat)? valueMapEntry*
2546 @end example
2547
2548 Like @code{sourceVariable}, this element defines a variable whose
2549 values can be used elsewhere in the visualization.  Instead of being
2550 read from a data source, the variable's data are defined by a
2551 mathematical expression.
2552
2553 This element has the following attributes.
2554
2555 @defvr {Attribute} id
2556 An @code{id} is always present because this element exists to be
2557 referenced from other elements.
2558 @end defvr
2559
2560 @defvr {Attribute} categorical
2561 Always set to @code{true}.
2562 @end defvr
2563
2564 @defvr {Attribute} value
2565 An expression that defines the variable's value.  In theory this could
2566 be an arbitrary expression in terms of constants, functions, and other
2567 variables, e.g.@: @math{(@var{var1} + @var{var2}) / 2}.  In practice,
2568 the corpus contains only the following forms of expressions:
2569
2570 @table @code
2571 @item constant(0)
2572 @itemx constant(@var{variable})
2573 All zeros.  The reason why a variable is sometimes named is unknown.
2574 Sometimes the ``variable name'' has spaces in it.
2575
2576 @item map(@var{variable})
2577 Transforms the values in the named @var{variable} using the
2578 @code{valueMapEntry}s contained within the element.
2579 @end table
2580 @end defvr
2581
2582 @defvr {Attribute} dependsOn
2583 This attribute doesn't affect the display of a table.
2584 @end defvr
2585
2586 @node SPV Detail valueMapEntry Element
2587 @subsubsection The @code{valueMapEntry} Element
2588
2589 @example
2590 valueMapEntry :from :to => EMPTY
2591 @end example
2592
2593 A @code{valueMapEntry} element defines a mapping from one or more
2594 values of a source expression to a target value.  (In the corpus, the
2595 source expression is always just the name of a variable.)  Each target
2596 value requires a separate @code{valueMapEntry}.  If multiple source
2597 values map to the same target value, they can be combined or separate.
2598
2599 In the corpus, all of the source and target values are integers.
2600
2601 @code{valueMapEntry} has the following attributes.
2602
2603 @defvr {Attribute} from
2604 A source value, or multiple source values separated by semicolons,
2605 e.g.@: @code{0} or @code{13;14;15;16}.
2606 @end defvr
2607
2608 @defvr {Attribute} to
2609 The target value, e.g.@: @code{0}.
2610 @end defvr
2611
2612 @node SPV Detail extension Element
2613 @subsection The @code{extension} Element
2614
2615 This is a general-purpose ``extension'' element.  Readers that don't
2616 understand a given extension should be able to safely ignore it.  The
2617 attributes on this element, and their meanings, vary based on the
2618 context.  Each known usage is described separately below.  The current
2619 extensions use attributes exclusively, without any nested elements.
2620
2621 @subsubheading @code{container} Parent Element
2622
2623 @example
2624 extension[container_extension] :combinedFootnotes=(true) => EMPTY
2625 @end example
2626
2627 With @code{container} as its parent element, @code{extension} has the
2628 following attributes.
2629
2630 @defvr {Attribute} combinedFootnotes
2631 Always set to @code{true} in the corpus.
2632 @end defvr
2633
2634 @subsubheading @code{sourceVariable} and @code{derivedVariable} Parent Element
2635
2636 @example
2637 extension[variable_extension] :from :helpId => EMPTY
2638 @end example
2639
2640 With @code{sourceVariable} or @code{derivedVariable} as its parent
2641 element, @code{extension} has the following attributes.  A given
2642 parent element often contains several @code{extension} elements that
2643 specify the meaning of the source data's variables or sources, e.g.@:
2644
2645 @example
2646 <extension from="0" helpId="corrected_model"/>
2647 <extension from="3" helpId="error"/>
2648 <extension from="4" helpId="total_9"/>
2649 <extension from="5" helpId="corrected_total"/>
2650 @end example
2651
2652 More commonly they are less helpful, e.g.@:
2653
2654 @example
2655 <extension from="0" helpId="notes"/>
2656 <extension from="1" helpId="notes"/>
2657 <extension from="2" helpId="notes"/>
2658 <extension from="5" helpId="notes"/>
2659 <extension from="6" helpId="notes"/>
2660 <extension from="7" helpId="notes"/>
2661 <extension from="8" helpId="notes"/>
2662 <extension from="12" helpId="notes"/>
2663 <extension from="13" helpId="no_help"/>
2664 <extension from="14" helpId="notes"/>
2665 @end example
2666
2667 @defvr {Attribute} from
2668 An integer or a name like ``dimension0''.
2669 @end defvr
2670
2671 @defvr {Attribute} helpId
2672 An identifier.
2673 @end defvr
2674
2675 @node SPV Detail graph Element
2676 @subsection The @code{graph} Element
2677
2678 @example
2679 graph
2680    :cellStyle=ref style
2681    :style=ref style
2682 => location+ coordinates faceting facetLayout interval
2683
2684 coordinates => EMPTY
2685 @end example
2686
2687 @code{graph} has the following attributes.
2688
2689 @defvr {Attribute} cellStyle
2690 @defvrx {Attribute} style
2691 Each of these is the @code{id} of a @code{style} element (@pxref{SPV
2692 Detail style Element}).  The former is the default style for
2693 individual cells, the latter for the entire table.
2694 @end defvr
2695
2696 @node SPV Detail location Element
2697 @subsection The @code{location} Element
2698
2699 @example
2700 location
2701    :part=(height | width | top | bottom | left | right)
2702    :method=(sizeToContent | attach | fixed | same)
2703    :min=dimension?
2704    :max=dimension?
2705    :target=ref (labelFrame | graph | container)?
2706    :value?
2707 => EMPTY
2708 @end example
2709
2710 Each instance of this element specifies where some part of the table
2711 frame is located.  All the examples in the corpus have four instances
2712 of this element, one for each of the parts @code{height},
2713 @code{width}, @code{left}, and @code{top}.  Some examples in the
2714 corpus add a fifth for part @code{bottom}, even though it is not clear
2715 how all of @code{top}, @code{bottom}, and @code{height} can be honored
2716 at the same time.  In any case, @code{location} seems to have little
2717 importance in representing tables; a reader can safely ignore it.
2718
2719 @defvr {Attribute} part
2720 The part of the table being located.
2721 @end defvr
2722
2723 @defvr {Attribute} method
2724 How the location is determined:
2725
2726 @table @code
2727 @item sizeToContent
2728 Based on the natural size of the table.  Observed only for
2729 parts @code{height} and @code{width}.
2730
2731 @item attach
2732 Based on the location specified in @code{target}.  Observed only for
2733 parts @code{top} and @code{bottom}.
2734
2735 @item fixed
2736 Using the value in @code{value}.  Observed only for parts @code{top},
2737 @code{bottom}, and @code{left}.
2738
2739 @item same
2740 Same as the specified @code{target}.  Observed only for part
2741 @code{left}.
2742 @end table
2743 @end defvr
2744
2745 @defvr {Attribute} min
2746 Minimum size.  Only observed with value @code{100pt}.  Only observed
2747 for part @code{width}.
2748 @end defvr
2749
2750 @defvr {Dependent} target
2751 Required when @code{method} is @code{attach} or @code{same}, not
2752 observed otherwise.  This identifies an element to attach to.
2753 Observed with the ID of @code{title}, @code{footnote}, @code{graph},
2754 and other elements.
2755 @end defvr
2756
2757 @defvr {Dependent} value
2758 Required when @code{method} is @code{fixed}, not observed otherwise.
2759 Observed values are @code{0%}, @code{0px}, @code{1px}, and @code{3px}
2760 on parts @code{top} and @code{left}, and @code{100%} on part
2761 @code{bottom}.
2762 @end defvr
2763
2764 @node SPV Detail faceting Element
2765 @subsection The @code{faceting} Element
2766
2767 @example
2768 faceting => layer[layers1]* cross layer[layers2]*
2769
2770 cross => (unity | nest) (unity | nest)
2771
2772 unity => EMPTY
2773
2774 nest => variableReference[vars]+
2775
2776 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY
2777
2778 layer
2779    :variable=ref (sourceVariable | derivedVariable)
2780    :value
2781    :visible=bool?
2782    :method[layer_method]=(nest)?
2783    :titleVisible=bool?
2784 => EMPTY
2785 @end example
2786
2787 The @code{faceting} element describes the row, column, and layer
2788 structure of the table.  Its @code{cross} child determines the row and
2789 column structure, and each @code{layer} child (if any) represents a
2790 layer.  Layers may appear before or after @code{cross}.
2791
2792 The @code{cross} element describes the row and column structure of the
2793 table.  It has exactly two children, the first of which describes the
2794 table's columns and the second the table's rows.  Each child is a
2795 @code{nest} element if the table has any dimensions along the axis in
2796 question, otherwise a @code{unity} element.
2797
2798 A @code{nest} element contains of one or more dimensions listed from
2799 innermost to outermost, each represented by @code{variableReference}
2800 child elements.  Each variable in a dimension is listed in order.
2801 @xref{SPV Detail Variable Elements}, for information on the variables
2802 that comprise a dimension.
2803
2804 A @code{nest} can contain a single dimension, e.g.:
2805
2806 @example
2807 <nest>
2808   <variableReference ref="dimension0categories"/>
2809   <variableReference ref="dimension0group0"/>
2810   <variableReference ref="dimension0"/>
2811 </nest>
2812 @end example
2813
2814 @noindent
2815 A @code{nest} can contain multiple dimensions, e.g.:
2816
2817 @example
2818 <nest>
2819   <variableReference ref="dimension1categories"/>
2820   <variableReference ref="dimension1group0"/>
2821   <variableReference ref="dimension1"/>
2822   <variableReference ref="dimension0categories"/>
2823   <variableReference ref="dimension0"/>
2824 </nest>
2825 @end example
2826
2827 A @code{nest} may have no dimensions, in which case it still has one
2828 @code{variableReference} child, which references a
2829 @code{derivedVariable} whose @code{value} attribute is
2830 @code{constant(0)}.  In the corpus, such a @code{derivedVariable} has
2831 @code{row} or @code{column}, respectively, as its @code{id}.  This is
2832 equivalent to using a @code{unity} element in place of @code{nest}.
2833
2834 A @code{variableReference} element refers to a variable through its
2835 @code{ref} attribute.
2836
2837 Each @code{layer} element represents a dimension, e.g.:
2838
2839 @example
2840 <layer value="0" variable="dimension0categories" visible="true"/>
2841 <layer value="dimension0" variable="dimension0" visible="false"/>
2842 @end example
2843
2844 @noindent
2845 @code{layer} has the following attributes.
2846
2847 @defvr {Attribute} variable
2848 Refers to a @code{sourceVariable} or @code{derivedVariable} element.
2849 @end defvr
2850
2851 @defvr {Attribute} value
2852 The value to select.  For a category variable, this is always
2853 @code{0}; for a data variable, it is the same as the @code{variable}
2854 attribute.
2855 @end defvr
2856
2857 @defvr {Attribute} visible
2858 Whether the layer is visible.  Generally, category layers are visible
2859 and data layers are not, but sometimes this attribute is omitted.
2860 @end defvr
2861
2862 @defvr {Attribute} method
2863 When present, this is always @code{nest}.
2864 @end defvr
2865
2866 @node SPV Detail facetLayout Element
2867 @subsection The @code{facetLayout} Element
2868
2869 @example
2870 facetLayout => tableLayout setCellProperties[scp1]*
2871                facetLevel+ setCellProperties[scp2]*
2872
2873 tableLayout
2874    :verticalTitlesInCorner=bool
2875    :style=ref style?
2876    :fitCells=(ticks both)?
2877 => EMPTY
2878 @end example
2879
2880 The @code{facetLayout} element and its descendants control styling for
2881 the table.
2882
2883 Its @code{tableLayout} child has the following attributes
2884
2885 @defvr {Attribute} verticalTitlesInCorner
2886 If true, in the absence of corner text, row headings will be displayed
2887 in the corner.
2888 @end defvr
2889
2890 @defvr {Attribute} style
2891 Refers to a @code{style} element.
2892 @end defvr
2893
2894 @defvr {Attribute} fitCells
2895 Meaning unknown.
2896 @end defvr
2897
2898 @subsubheading The @code{facetLevel} Element
2899
2900 @example
2901 facetLevel :level=int :gap=dimension? => axis
2902
2903 axis :style=ref style => label? majorTicks
2904
2905 majorTicks
2906    :labelAngle=int
2907    :length=dimension
2908    :style=ref style
2909    :tickFrameStyle=ref style
2910    :labelFrequency=int?
2911    :stagger=bool?
2912 => gridline?
2913
2914 gridline
2915    :style=ref style
2916    :zOrder=int
2917 => EMPTY
2918 @end example
2919
2920 Each @code{facetLevel} describes a @code{variableReference} or
2921 @code{layer}, and a table has one @code{facetLevel} element for
2922 each such element.  For example, an SPV detail member that contains
2923 four @code{variableReference} elements and two @code{layer} elements
2924 will contain six @code{facetLevel} elements.
2925
2926 In the corpus, @code{facetLevel} elements and the elements that they
2927 describe are always in the same order.  The correspondence may also be
2928 observed in two other ways.  First, one may use the @code{level}
2929 attribute, described below.  Second, in the corpus, a
2930 @code{facetLevel} always has an @code{id} that is the same as the
2931 @code{id} of the element it describes with @code{_facetLevel}
2932 appended.  One should not formally rely on this, of course, but it is
2933 usefully indicative.
2934
2935 @defvr {Attribute} level
2936 A 1-based index into the @code{variableReference} and @code{layer}
2937 elements, e.g.@: a @code{facetLayout} with a @code{level} of 1
2938 describes the first @code{variableReference} in the SPV detail member,
2939 and in a member with four @code{variableReference} elements, a
2940 @code{facetLayout} with a @code{level} of 5 describes the first
2941 @code{layer} in the member.
2942 @end defvr
2943
2944 @defvr {Attribute} gap
2945 Always observed as @code{0pt}.
2946 @end defvr
2947
2948 Each @code{facetLevel} contains an @code{axis}, which in turn may
2949 contain a @code{label} for the @code{facetLevel} (@pxref{SPV Detail
2950 label Element}) and does contain a @code{majorTicks} element.
2951
2952 @defvr {Attribute} labelAngle
2953 Normally 0.  The value -90 causes inner column or outer row labels to
2954 be rotated vertically.
2955 @end defvr
2956
2957 @defvr {Attribute} style
2958 @defvrx {Attribute} tickFrameStyle
2959 Each refers to a @code{style} element.  @code{style} is the style of
2960 the tick labels, @code{tickFrameStyle} the style for the frames around
2961 the labels.
2962 @end defvr
2963
2964 @node SPV Detail label Element
2965 @subsection The @code{label} Element
2966
2967 @example
2968 label
2969    :style=ref style
2970    :textFrameStyle=ref style?
2971    :purpose=(title | subTitle | subSubTitle | layer | footnote)?
2972 => text+ | descriptionGroup
2973
2974 descriptionGroup
2975    :target=ref faceting
2976    :separator?
2977 => (description | text)+
2978
2979 description :name=(variable | value) => EMPTY
2980
2981 text
2982    :usesReference=int?
2983    :definesReference=int?
2984    :position=(subscript | superscript)?
2985    :style=ref style
2986 => TEXT
2987 @end example
2988
2989 This element represents a label on some aspect of the table.
2990
2991 @defvr {Attribute} style
2992 @defvrx {Attribute} textFrameStyle
2993 Each of these refers to a @code{style} element.  @code{style} is the
2994 style of the label text, @code{textFrameStyle} the style for the frame
2995 around the label.
2996 @end defvr
2997
2998 @defvr {Attribute} purpose
2999 The kind of entity being labeled.
3000 @end defvr
3001
3002 A @code{descriptionGroup} concatenates one or more elements to form a
3003 label.  Each element can be a @code{text} element, which contains
3004 literal text, or a @code{description} element that substitutes a value
3005 or a variable name.
3006
3007 @defvr {Attribute} target
3008 The @code{id} of an element being described.  In the corpus, this is
3009 always @code{faceting}.
3010 @end defvr
3011
3012 @defvr {Attribute} separator
3013 A string to separate the description of multiple groups, if the
3014 @code{target} has more than one.  In the corpus, this is always a
3015 new-line.
3016 @end defvr
3017
3018 Typical contents for a @code{descriptionGroup} are a value by itself:
3019 @example
3020 <description name="value"/>
3021 @end example
3022 @noindent or a variable and its value, separated by a colon:
3023 @example
3024 <description name="variable"/><text>:</text><description name="value"/>
3025 @end example
3026
3027 A @code{description} is like a macro that expands to some property of
3028 the target of its parent @code{descriptionGroup}.  The @code{name}
3029 attribute specifies the property.
3030
3031 @node SPV Detail setCellProperties Element
3032 @subsection The @code{setCellProperties} Element
3033
3034 @example
3035 setCellProperties
3036    :applyToConverse=bool?
3037 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?
3038 @end example
3039
3040 The @code{setCellProperties} element sets style properties of cells or
3041 row or column labels.
3042
3043 Interpreting @code{setCellProperties} requires answering two
3044 questions: which cells or labels to style, and what styles to use.
3045
3046 @subsubheading Which Cells?
3047
3048 @example
3049 union => intersect+
3050
3051 intersect => where+ | intersectWhere | alternating | EMPTY
3052
3053 where
3054    :variable=ref (sourceVariable | derivedVariable)
3055    :include
3056 => EMPTY
3057
3058 intersectWhere
3059    :variable=ref (sourceVariable | derivedVariable)
3060    :variable2=ref (sourceVariable | derivedVariable)
3061 => EMPTY
3062
3063 alternating => EMPTY
3064 @end example
3065
3066 When @code{union} is present with @code{intersect} children, each of
3067 those children specifies a group of cells that should be styled, and
3068 the total group is all those cells taken together.  When @code{union}
3069 is absent, every cell is styled.  One attribute on
3070 @code{setCellProperties} affects the choice of cells:
3071
3072 @defvr {Attribute} applyToConverse
3073 If true, this inverts the meaning of the cell selection: the selected
3074 cells are the ones @emph{not} designated.  This is confusing, given
3075 the additional restrictions of @code{union}, but in the corpus
3076 @code{applyToConverse} is never present along with @code{union}.
3077 @end defvr
3078
3079 An @code{intersect} specifies restrictions on the cells to be matched.
3080 Each @code{where} child specifies which values of a given variable to
3081 include.  The attributes of @code{intersect} are:
3082
3083 @defvr {Attribute} variable
3084 Refers to a variable, e.g.@: @code{dimension0categories}.  Only
3085 ``categories'' variables make sense here, but other variables, e.g.@:
3086 @code{dimension0group0map}, are sometimes seen.  The reader may ignore
3087 these.
3088 @end defvr
3089
3090 @defvr {Attribute} include
3091 A value, or multiple values separated by semicolons,
3092 e.g.@: @code{0} or @code{13;14;15;16}.
3093 @end defvr
3094
3095 PSPP ignores @code{setCellProperties} when @code{intersectWhere} is
3096 present.
3097
3098 @subsubheading What Styles?
3099
3100 @example
3101 setStyle
3102    :target=ref (labeling | graph | interval | majorTicks)
3103    :style=ref style
3104 => EMPTY
3105
3106 setMetaData :target=ref graph :key :value => EMPTY
3107
3108 setFormat
3109    :target=ref (majorTicks | labeling)
3110    :reset=bool?
3111 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3112
3113 setFrameStyle
3114    :style=ref style
3115    :target=ref majorTicks
3116 => EMPTY
3117 @end example
3118
3119 The @code{set*} children of @code{setCellProperties} determine the
3120 styles to set.
3121
3122 When @code{setCellProperties} contains a @code{setFormat} whose
3123 @code{target} references a @code{labeling} element, or if it contains
3124 a @code{setStyle} that references a @code{labeling} or @code{interval}
3125 element, the @code{setCellProperties} sets the style for table cells.
3126 The format from the @code{setFormat}, if present, replaces the cells'
3127 format.  The style from the @code{setStyle} that references
3128 @code{labeling}, if present, replaces the label's font and cell
3129 styles, except that the background color is taken instead from the
3130 @code{interval}'s style, if present.
3131
3132 When @code{setCellProperties} contains a @code{setFormat} whose
3133 @code{target} references a @code{majorTicks} element, or if it
3134 contains a @code{setStyle} whose @code{target} references a
3135 @code{majorTicks}, or if it contains a @code{setFrameStyle} element,
3136 the @code{setCellProperties} sets the style for row or column labels.
3137 In this case, the @code{setCellProperties} always contains a single
3138 @code{where} element whose @code{variable} designates the variable
3139 whose labels are to be styled.  The format from the @code{setFormat},
3140 if present, replaces the labels' format.  The style from the
3141 @code{setStyle} that references @code{majorTicks}, if present,
3142 replaces the labels' font and cell styles, except that the background
3143 color is taken instead from the @code{setFrameStyle}'s style, if
3144 present.
3145
3146 When @code{setCellProperties} contains a @code{setStyle} whose
3147 @code{target} references a @code{graph} element, and one that
3148 references a @code{labeling} element, and the @code{union} element
3149 contains @code{alternating}, the @code{setCellProperties} sets the
3150 alternate foreground and background colors for the data area.  The
3151 foreground color is taken from the style referenced by the
3152 @code{setStyle} that targets the @code{graph}, the background color
3153 from the @code{setStyle} for @code{labeling}.
3154
3155 A reader may ignore a @code{setCellProperties} that only contains
3156 @code{setMetaData}, as well as @code{setMetaData} within other
3157 @code{setCellProperties}.
3158
3159 A reader may ignore a @code{setCellProperties} whose only @code{set*}
3160 child is a @code{setStyle} that targets the @code{graph} element.
3161
3162 @subsubheading The @code{setStyle} Element
3163
3164 @example
3165 setStyle
3166    :target=ref (labeling | graph | interval | majorTicks)
3167    :style=ref style
3168 => EMPTY
3169 @end example
3170
3171 This element associates a style with the target.
3172
3173 @defvr {Attribute} target
3174 The @code{id} of an element whose style is to be set.
3175 @end defvr
3176
3177 @defvr {Attribute} style
3178 The @code{id} of a @code{style} element that identifies the style to
3179 set on the target.
3180 @end defvr
3181
3182 @node SPV Detail setFormat Element
3183 @subsection The @code{setFormat} Element
3184
3185 @example
3186 setFormat
3187    :target=ref (majorTicks | labeling)
3188    :reset=bool?
3189 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat
3190 @end example
3191
3192 This element sets the format of the target, ``format'' in this case
3193 meaning the SPSS print format for a variable.
3194
3195 The details of this element vary depending on the schema version, as
3196 declared in the root @code{visualization} element's @code{version}
3197 attribute (@pxref{SPV Detail visualization Element}).  A reader can
3198 interpret the content without knowing the schema version.
3199
3200 The @code{setFormat} element itself has the following attributes.
3201
3202 @defvr {Attribute} target
3203 Refers to an element whose style is to be set.
3204 @end defvr
3205
3206 @defvr {Attribute} reset
3207 If this is @code{true}, this format replaces the target's previous
3208 format.  If it is @code{false}, the modifies the previous format.
3209 @end defvr
3210
3211 @menu
3212 * SPV Detail numberFormat Element::
3213 * SPV Detail stringFormat Element::
3214 * SPV Detail dateTimeFormat Element::
3215 * SPV Detail elapsedTimeFormat Element::
3216 * SPV Detail format Element::
3217 * SPV Detail affix Element::
3218 @end menu
3219
3220 @node SPV Detail numberFormat Element
3221 @subsubsection The @code{numberFormat} Element
3222
3223 @example
3224 numberFormat
3225    :minimumIntegerDigits=int?
3226    :maximumFractionDigits=int?
3227    :minimumFractionDigits=int?
3228    :useGrouping=bool?
3229    :scientific=(onlyForSmall | whenNeeded | true | false)?
3230    :small=real?
3231    :prefix?
3232    :suffix?
3233 => affix*
3234 @end example
3235
3236 Specifies a format for displaying a number.  The available options are
3237 a superset of those available from PSPP print formats.  PSPP chooses a
3238 print format type for a @code{numberFormat} as follows:
3239
3240 @enumerate
3241 @item
3242 If @code{scientific} is @code{true}, uses @code{E} format.
3243
3244 @item
3245 If @code{prefix} is @code{$}, uses @code{DOLLAR} format.
3246
3247 @item
3248 If @code{suffix} is @code{%}, uses @code{PCT} format.
3249
3250 @item
3251 If @code{useGrouping} is @code{true}, uses @code{COMMA} format.
3252
3253 @item
3254 Otherwise, uses @code{F} format.
3255 @end enumerate
3256
3257 For translating to a print format, PSPP uses
3258 @code{maximumFractionDigits} as the number of decimals, unless that
3259 attribute is missing or out of the range [0,15], in which case it uses
3260 2 decimals.
3261
3262 @defvr {Attribute} minimumIntegerDigits
3263 Minimum number of digits to display before the decimal point.  Always
3264 observed as @code{0}.
3265 @end defvr
3266
3267 @defvr {Attribute} maximumFractionDigits
3268 @defvrx {Attribute} minimumFractionDigits
3269 Maximum or minimum, respectively, number of digits to display after
3270 the decimal point.  The observed values of each attribute range from 0
3271 to 9.
3272 @end defvr
3273
3274 @defvr {Attribute} useGrouping
3275 Whether to use the grouping character to group digits in large
3276 numbers.
3277 @end defvr
3278
3279 @defvr {Attribute} scientific
3280 This attribute controls when and whether the number is formatted in
3281 scientific notation.  It takes the following values:
3282
3283 @table @code
3284 @item onlyForSmall
3285 Use scientific notation only when the number's magnitude is smaller
3286 than the value of the @code{small} attribute.
3287
3288 @item whenNeeded
3289 Use scientific notation when the number will not otherwise fit in the
3290 available space.
3291
3292 @item true
3293 Always use scientific notation.  Not observed in the corpus.
3294
3295 @item false
3296 Never use scientific notation.  A number that won't otherwise fit will
3297 be replaced by an error indication (see the @code{errorCharacter}
3298 attribute).  Not observed in the corpus.
3299 @end table
3300 @end defvr
3301
3302 @defvr {Attribute} small
3303 Only present when the @code{scientific} attribute is
3304 @code{onlyForSmall}, this is a numeric magnitude below which the
3305 number will be formatted in scientific notation.  The values @code{0}
3306 and @code{0.0001} have been observed.  The value @code{0} seems like a
3307 pathological choice, since no real number has a magnitude less than 0;
3308 perhaps in practice such a choice is equivalent to setting
3309 @code{scientific} to @code{false}.
3310 @end defvr
3311
3312 @defvr {Attribute} prefix
3313 @defvrx {Attribute} suffix
3314 Specifies a prefix or a suffix to apply to the formatted number.  Only
3315 @code{suffix} has been observed, with value @samp{%}.
3316 @end defvr
3317
3318 @node SPV Detail stringFormat Element
3319 @subsubsection The @code{stringFormat} Element
3320
3321 @example
3322 stringFormat => relabel* affix*
3323
3324 relabel :from=real :to => EMPTY
3325 @end example
3326
3327 The @code{stringFormat} element specifies how to display a string.  By
3328 default, a string is displayed verbatim, but @code{relabel} can change
3329 it.
3330
3331 The @code{relabel} element appears as a child of @code{stringFormat}
3332 (and of @code{format}, when it is used to format strings).  It
3333 specifies how to display a given value.  It is used to implement value
3334 labels and to display the system-missing value in a human-readable
3335 way.  It has the following attributes:
3336
3337 @defvr {Attribute} from
3338 The value to map.  In the corpus this is an integer or the
3339 system-missing value @code{-1.797693134862316E300}.
3340 @end defvr
3341
3342 @defvr {Attribute} to
3343 The string to display in place of the value of @code{from}.  In the
3344 corpus this is a wide variety of value labels; the system-missing
3345 value is mapped to @samp{.}.
3346 @end defvr
3347
3348 @node SPV Detail dateTimeFormat Element
3349 @subsubsection The @code{dateTimeFormat} Element
3350
3351 @example
3352 dateTimeFormat
3353    :baseFormat[dt_base_format]=(date | time | dateTime)
3354    :separatorChars?
3355    :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3356    :showYear=bool?
3357    :yearAbbreviation=bool?
3358    :showQuarter=bool?
3359    :quarterPrefix?
3360    :quarterSuffix?
3361    :showMonth=bool?
3362    :monthFormat=(long | short | number | paddedNumber)?
3363    :showWeek=bool?
3364    :weekPadding=bool?
3365    :weekSuffix?
3366    :showDayOfWeek=bool?
3367    :dayOfWeekAbbreviation=bool?
3368    :dayPadding=bool?
3369    :dayOfMonthPadding=bool?
3370    :hourPadding=bool?
3371    :minutePadding=bool?
3372    :secondPadding=bool?
3373    :showDay=bool?
3374    :showHour=bool?
3375    :showMinute=bool?
3376    :showSecond=bool?
3377    :showMillis=bool?
3378    :dayType=(month | year)?
3379    :hourFormat=(AMPM | AS_24 | AS_12)?
3380 => affix*
3381 @end example
3382
3383 This element appears only in schema version 2.5 and earlier
3384 (@pxref{SPV Detail visualization Element}).
3385
3386 Data to be formatted in date formats is stored as strings in legacy
3387 data, in the format @code{yyyy-mm-ddTHH:MM:SS.SSS} and must be parsed
3388 and reformatted by the reader.
3389
3390 The following attribute is required.
3391
3392 @defvr {Attribute} baseFormat
3393 Specifies whether a date and time are both to be displayed, or just
3394 one of them.
3395 @end defvr
3396
3397 Many of the attributes' meanings are obvious.  The following seem to
3398 be worth documenting.
3399
3400 @defvr {Attribute} separatorChars
3401 Exactly four characters.  In order, these are used for: decimal point,
3402 grouping, date separator, time separator.  Always @samp{.,-:}.
3403 @end defvr
3404
3405 @defvr {Attribute} mdyOrder
3406 Within a date, the order of the days, months, and years.
3407 @code{dayMonthYear} is the only observed value, but one would expect
3408 that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as
3409 well.
3410 @end defvr
3411
3412 @defvr {Attribute} showYear
3413 @defvrx {Attribute} yearAbbreviation
3414 Whether to include the year and, if so, whether the year should be
3415 shown abbreviated, that is, with only 2 digits.  Each is @code{true}
3416 or @code{false}; only values of @code{true} and @code{false},
3417 respectively, have been observed.
3418 @end defvr
3419
3420 @defvr {Attribute} showMonth
3421 @defvrx {Attribute} monthFormat
3422 Whether to include the month (@code{true} or @code{false}) and, if so,
3423 how to format it.  @code{monthFormat} is one of the following:
3424
3425 @table @code
3426 @item long
3427 The full name of the month, e.g.@: in an English locale,
3428 @code{September}.
3429
3430 @item short
3431 The abbreviated name of the month, e.g.@: in an English locale,
3432 @code{Sep}.
3433
3434 @item number
3435 The number representing the month, e.g.@: 9 for September.
3436
3437 @item paddedNumber
3438 A two-digit number representing the month, e.g.@: 09 for September.
3439 @end table
3440
3441 Only values of @code{true} and @code{short}, respectively, have been
3442 observed.
3443 @end defvr
3444
3445 @defvr {Attribute} dayType
3446 This attribute is always @code{month} in the corpus, specifying that
3447 the day of the month is to be displayed; a value of @code{year} is
3448 supposed to indicate that the day of the year, where 1 is January 1,
3449 is to be displayed instead.
3450 @end defvr
3451
3452 @defvr {Attribute} hourFormat
3453 @code{hourFormat}, if present, is one of:
3454
3455 @table @code
3456 @item AMPM
3457 The time is displayed with an @code{am} or @code{pm} suffix, e.g.@:
3458 @code{10:15pm}.
3459
3460 @item AS_24
3461 The time is displayed in a 24-hour format, e.g.@: @code{22:15}.
3462
3463 This is the only value observed in the corpus.
3464
3465 @item AS_12
3466 The time is displayed in a 12-hour format, without distinguishing
3467 morning or evening, e.g.@: @code{10;15}.
3468 @end table
3469
3470 @code{hourFormat} is sometimes present for @code{elapsedTime} formats,
3471 which is confusing since a time duration does not have a concept of AM
3472 or PM.  This might indicate a bug in the code that generated the XML
3473 in the corpus, or it might indicate that @code{elapsedTime} is
3474 sometimes used to format a time of day.
3475 @end defvr
3476
3477 For a @code{baseFormat} of @code{date}, PSPP chooses a print format
3478 type based on the following rules:
3479
3480 @enumerate
3481 @item
3482 If @code{showQuarter} is true: @code{QYR}.
3483
3484 @item
3485 Otherwise, if @code{showWeek} is true: @code{WKYR}.
3486
3487 @item
3488 Otherwise, if @code{mdyOrder} is @code{dayMonthYear}:
3489
3490 @enumerate a
3491 @item
3492 If @code{monthFormat} is @code{number} or @code{paddedNumber}: @code{EDATE}.
3493
3494 @item
3495 Otherwise: @code{DATE}.
3496 @end enumerate
3497
3498 @item
3499 Otherwise, if @code{mdyOrder} is @code{yearMonthDay}: @code{SDATE}.
3500
3501 @item
3502 Otherwise, @code{ADATE}.
3503 @end enumerate
3504
3505 For a @code{baseFormat} of @code{dateTime}, PSPP uses @code{YMDHMS} if
3506 @code{mdyOrder} is @code{yearMonthDay} and @code{DATETIME} otherwise.
3507 For a @code{baseFormat} of @code{time}, PSPP uses @code{DTIME} if
3508 @code{showDay} is true, otherwise @code{TIME} if @code{showHour} is
3509 true, otherwise @code{MTIME}.
3510
3511 For a @code{baseFormat} of @code{date}, the chosen width is the
3512 minimum for the format type, adding 2 if @code{yearAbbreviation} is
3513 false or omitted.  For other base formats, the chosen width is the
3514 minimum for its type, plus 3 if @code{showSecond} is true, plus 4 more
3515 if @code{showMillis} is also true.  Decimals are 0 by default, or 3
3516 if @code{showMillis} is true.
3517
3518 @node SPV Detail elapsedTimeFormat Element
3519 @subsubsection The @code{elapsedTimeFormat} Element
3520
3521 @example
3522 elapsedTimeFormat
3523    :baseFormat[dt_base_format]=(date | time | dateTime)
3524    :dayPadding=bool?
3525    :hourPadding=bool?
3526    :minutePadding=bool?
3527    :secondPadding=bool?
3528    :showYear=bool?
3529    :showDay=bool?
3530    :showHour=bool?
3531    :showMinute=bool?
3532    :showSecond=bool?
3533    :showMillis=bool?
3534 => affix*
3535 @end example
3536
3537 This element specifies the way to display a time duration.
3538
3539 Data to be formatted in elapsed time formats is stored as strings in
3540 legacy data, in the format @code{H:MM:SS.SSS}, with additional hour
3541 digits as needed for long durations, and must be parsed and
3542 reformatted by the reader.
3543
3544 The following attribute is required.
3545
3546 @defvr {Attribute} baseFormat
3547 Specifies whether a day and a time are both to be displayed, or just
3548 one of them.
3549 @end defvr
3550
3551 The remaining attributes specify exactly how to display the elapsed
3552 time.
3553
3554 For @code{baseFormat} of @code{time}, PSPP converts this element to
3555 print format type @code{DTIME}; otherwise, if @code{showHour} is true,
3556 to @code{TIME}; otherwise, to @code{MTIME}.  The chosen width is the
3557 minimum for the chosen type, adding 3 if @code{showSecond} is true,
3558 adding 4 more if @code{showMillis} is also true.  Decimals are 0 by
3559 default, or 3 if @code{showMillis} is true.
3560
3561 @node SPV Detail format Element
3562 @subsubsection The @code{format} Element
3563
3564 @example
3565 format
3566    :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
3567    :errorCharacter?
3568    :separatorChars?
3569    :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
3570    :showYear=bool?
3571    :showQuarter=bool?
3572    :quarterPrefix?
3573    :quarterSuffix?
3574    :yearAbbreviation=bool?
3575    :showMonth=bool?
3576    :monthFormat=(long | short | number | paddedNumber)?
3577    :dayPadding=bool?
3578    :dayOfMonthPadding=bool?
3579    :showWeek=bool?
3580    :weekPadding=bool?
3581    :weekSuffix?
3582    :showDayOfWeek=bool?
3583    :dayOfWeekAbbreviation=bool?
3584    :hourPadding=bool?
3585    :minutePadding=bool?
3586    :secondPadding=bool?
3587    :showDay=bool?
3588    :showHour=bool?
3589    :showMinute=bool?
3590    :showSecond=bool?
3591    :showMillis=bool?
3592    :dayType=(month | year)?
3593    :hourFormat=(AMPM | AS_24 | AS_12)?
3594    :minimumIntegerDigits=int?
3595    :maximumFractionDigits=int?
3596    :minimumFractionDigits=int?
3597    :useGrouping=bool?
3598    :scientific=(onlyForSmall | whenNeeded | true | false)?
3599    :small=real?
3600    :prefix?
3601    :suffix?
3602    :tryStringsAsNumbers=bool?
3603    :negativesOutside=bool?
3604 => relabel* affix*
3605 @end example
3606
3607 This element is the union of all of the more-specific format elements.
3608 It is interpreted in the same way as one of those format elements,
3609 using @code{baseFormat} to determine which kind of format to use.
3610
3611 There are a few attributes not present in the more specific formats:
3612
3613 @defvr {Attribute} tryStringsAsNumbers
3614 When this is @code{true}, it is supposed to indicate that string
3615 values should be parsed as numbers and then displayed according to
3616 numeric formatting rules.  However, in the corpus it is always
3617 @code{false}.
3618 @end defvr
3619
3620 @defvr {Attribute} negativesOutside
3621 If true, the negative sign should be shown before the prefix; if
3622 false, it should be shown after.
3623 @end defvr
3624
3625 @node SPV Detail affix Element
3626 @subsubsection The @code{affix} Element
3627
3628 @example
3629 affix
3630    :definesReference=int
3631    :position=(subscript | superscript)
3632    :suffix=bool
3633    :value
3634 => EMPTY
3635 @end example
3636
3637 This defines a suffix (or, theoretically, a prefix) for a formatted
3638 value.  It is used to insert a reference to a footnote.  It has the
3639 following attributes:
3640
3641 @defvr {Attribute} definesReference
3642 This specifies the footnote number as a natural number: 1 for the
3643 first footnote, 2 for the second, and so on.
3644 @end defvr
3645
3646 @defvr {Attribute} position
3647 Position for the footnote label.  Always @code{superscript}.
3648 @end defvr
3649
3650 @defvr {Attribute} suffix
3651 Whether the affix is a suffix (@code{true}) or a prefix
3652 (@code{false}).  Always @code{true}.
3653 @end defvr
3654
3655 @defvr {Attribute} value
3656 The text of the suffix or prefix.  Typically a letter, e.g.@: @code{a}
3657 for footnote 1, @code{b} for footnote 2, @enddots{}  The corpus
3658 contains other values: @code{*}, @code{**}, and a few that begin with
3659 at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
3660 @end defvr
3661
3662 @node SPV Detail interval Element
3663 @subsection The @code{interval} Element
3664
3665 @example
3666 interval :style=ref style => labeling footnotes?
3667
3668 labeling
3669    :style=ref style?
3670    :variable=ref (sourceVariable | derivedVariable)
3671 => (formatting | format | footnotes)*
3672
3673 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*
3674
3675 formatMapping :from=int => format?
3676
3677 footnotes
3678    :superscript=bool?
3679    :variable=ref (sourceVariable | derivedVariable)
3680 => footnoteMapping*
3681
3682 footnoteMapping :definesReference=int :from=int :to => EMPTY
3683 @end example
3684
3685 The @code{interval} element and its descendants determine the basic
3686 formatting and labeling for the table's cells.  These basic styles are
3687 overridden by more specific styles set using @code{setCellProperties}
3688 (@pxref{SPV Detail setCellProperties Element}).
3689
3690 The @code{style} attribute of @code{interval} itself may be ignored.
3691
3692 The @code{labeling} element may have a single @code{formatting} child.
3693 If present, its @code{variable} attribute refers to a variable whose
3694 values are format specifiers as numbers, e.g. value 0x050802 for F8.2.
3695 However, the numbers are not actually interpreted that way.  Instead,
3696 each number actually present in the variable's data is mapped by a
3697 @code{formatMapping} child of @code{formatting} to a @code{format}
3698 that specifies how to display it.
3699
3700 The @code{labeling} element may also have a @code{footnotes} child
3701 element.  The @code{variable} attribute of this element refers to a
3702 variable whose values are comma-delimited strings that list the
3703 1-based indexes of footnote references.  (Cells without any footnote
3704 references are numeric 0 instead of strings.)
3705
3706 Each @code{footnoteMapping} child of the @code{footnotes} element
3707 defines the footnote marker to be its @code{to} attribute text for the
3708 footnote whose 1-based index is given in its @code{definesReference}
3709 attribute.
3710
3711 @node SPV Detail style Element
3712 @subsection The @code{style} Element
3713
3714 @example
3715 style
3716    :color=color?
3717    :color2=color?
3718    :labelAngle=real?
3719    :border-bottom=(solid | thick | thin | double | none)?
3720    :border-top=(solid | thick | thin | double | none)?
3721    :border-left=(solid | thick | thin | double | none)?
3722    :border-right=(solid | thick | thin | double | none)?
3723    :border-bottom-color?
3724    :border-top-color?
3725    :border-left-color?
3726    :border-right-color?
3727    :font-family?
3728    :font-size?
3729    :font-weight=(regular | bold)?
3730    :font-style=(regular | italic)?
3731    :font-underline=(none | underline)?
3732    :margin-bottom=dimension?
3733    :margin-left=dimension?
3734    :margin-right=dimension?
3735    :margin-top=dimension?
3736    :textAlignment=(left | right | center | decimal | mixed)?
3737    :labelLocationHorizontal=(positive | negative | center)?
3738    :labelLocationVertical=(positive | negative | center)?
3739    :decimal-offset=dimension?
3740    :size?
3741    :width?
3742    :visible=bool?
3743 => EMPTY
3744 @end example
3745
3746 A @code{style} element has an effect only when it is referenced by
3747 another element to set some aspect of the table's style.  Most of the
3748 attributes are self-explanatory.  The rest are described below.
3749
3750 @defvr {Attribute} {color}
3751 In some cases, the text color; in others, the background color.
3752 @end defvr
3753
3754 @defvr {Attribute} {color2}
3755 Not used.
3756 @end defvr
3757
3758 @defvr {Attribute} {labelAngle}
3759 Normally 0.  The value -90 causes inner column or outer row labels to
3760 be rotated vertically.
3761 @end defvr
3762
3763 @defvr {Attribute} {labelLocationHorizontal}
3764 Not used.
3765 @end defvr
3766
3767 @defvr {Attribute} {labelLocationVertical}
3768 The value @code{positive} corresponds to vertically aligning text to
3769 the top of a cell, @code{negative} to the bottom, @code{center} to the
3770 middle.
3771 @end defvr
3772
3773 @node SPV Detail labelFrame Element
3774 @subsection The @code{labelFrame} Element
3775
3776 @example
3777 labelFrame :style=ref style => location+ label? paragraph?
3778
3779 paragraph :hangingIndent=dimension? => EMPTY
3780 @end example
3781
3782 A @code{labelFrame} element specifies content and style for some
3783 aspect of a table.  Only @code{labelFrame} elements that have a
3784 @code{label} child are important.  The @code{purpose} attribute in the
3785 @code{label} determines what the @code{labelFrame} affects:
3786
3787 @table @code
3788 @item title
3789 The table's title and its style.
3790
3791 @item subTitle
3792 The table's caption and its style.
3793
3794 @item footnote
3795 The table's footnotes and the style for the footer area.
3796
3797 @item layer
3798 The style for the layer area.
3799
3800 @item subSubTitle
3801 Ignored.
3802 @end table
3803
3804 The @code{style} attribute references the style to use for the area.
3805
3806 The @code{label}, if present, specifies the text to put into the title
3807 or caption or footnotes.  For footnotes, the label has two @code{text}
3808 children for every footnote, each of which has a @code{usesReference}
3809 attribute identifying the 1-based index of a footnote.  The first,
3810 third, fifth, @dots{} @code{text} child specifies the content for a
3811 footnote; the second, fourth, sixth, @dots{} child specifies the
3812 marker.  Content tends to end in a new-line, which the reader may wish
3813 to trim; similarly, markers tend to end in @samp{.}.
3814
3815 The @code{paragraph}, if present, may be ignored, since it is always
3816 empty.
3817
3818 @node SPV Detail Legacy Properties
3819 @subsection Legacy Properties
3820
3821 The detail XML format has features for styling most of the aspects of
3822 a table.  It also inherits defaults for many aspects from structure
3823 XML, which has the following @code{tableProperties} element:
3824
3825 @example
3826 tableProperties
3827    :name?
3828 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties
3829
3830 generalProperties
3831    :hideEmptyRows=bool?
3832    :maximumColumnWidth=dimension?
3833    :maximumRowWidth=dimension?
3834    :minimumColumnWidth=dimension?
3835    :minimumRowWidth=dimension?
3836    :rowDimensionLabels=(inCorner | nested)?
3837 => EMPTY
3838
3839 footnoteProperties
3840    :markerPosition=(superscript | subscript)?
3841    :numberFormat=(alphabetic | numeric)?
3842 => EMPTY
3843
3844 cellFormatProperties => cell_style+
3845
3846 any[cell_style]
3847    :alternatingColor=color?
3848    :alternatingTextColor=color?
3849 => style
3850
3851 style
3852    :color=color?
3853    :color2=color?
3854    :font-family?
3855    :font-size?
3856    :font-style=(regular | italic)?
3857    :font-weight=(regular | bold)?
3858    :font-underline=(none | underline)?
3859    :labelLocationVertical=(positive | negative | center)?
3860    :margin-bottom=dimension?
3861    :margin-left=dimension?
3862    :margin-right=dimension?
3863    :margin-top=dimension?
3864    :textAlignment=(left | right | center | decimal | mixed)?
3865    :decimal-offset=dimension?
3866 => EMPTY
3867
3868 borderProperties => border_style+
3869
3870 any[border_style]
3871    :borderStyleType=(none | solid | dashed | thick | thin | double)?
3872    :color=color?
3873 => EMPTY
3874
3875 printingProperties
3876    :printAllLayers=bool?
3877    :rescaleLongTableToFitPage=bool?
3878    :rescaleWideTableToFitPage=bool?
3879    :windowOrphanLines=int?
3880    :continuationText?
3881    :continuationTextAtBottom=bool?
3882    :continuationTextAtTop=bool?
3883    :printEachLayerOnSeparatePage=bool?
3884 => EMPTY
3885 @end example
3886
3887 The @code{name} attribute appears only in standalone @file{.stt} files
3888 (@pxref{SPSS TableLook STT Format}).