X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=spv-file-format.texi;h=ecc5f8e1b5df4fb3ebe5a9cf25ddbe08bc30b2a2;hb=91e1d822895e84a15e17b15762c6d33629f83342;hp=f4cceb4b4c5c4cb675d22ece46826ff8a92bc375;hpb=ce608320e0b30b4bfa7155acf500852f8783e4a4;p=pspp
diff --git a/spv-file-format.texi b/spv-file-format.texi
index f4cceb4b4c..ecc5f8e1b5 100644
--- a/spv-file-format.texi
+++ b/spv-file-format.texi
@@ -194,7 +194,7 @@ file.
@defvr {Optional} @code{creation-date-time}
The date and time at which the SPV file was written, in a
-locale-specific format, e.g. @code{Friday, May 16, 2014 6:47:37 PM
+locale-specific format, e.g.@: @code{Friday, May 16, 2014 6:47:37 PM
PDT} or @code{lunedì 17 marzo 2014 3.15.48 CET} or even @code{Friday,
December 5, 2014 5:00:19 o'clock PM EST}.
@end defvr
@@ -1773,7 +1773,7 @@ Always set to @code{ticks}.
@subsubheading The @code{facetLevel} Element
-Parent: @code{facetLayout}
+Parent: @code{facetLayout} @*
Contents: @code{axis}
Each @code{facetLevel} describes a @code{variableReference} or
@@ -1804,18 +1804,133 @@ and in a member with four @code{variableReference} elements, a
Always observed as @code{0pt}.
@end defvr
+@subsubheading The @code{axis} Element
+
+Parent: @code{facetLevel} @*
+Contents: @code{label}? @code{majorTicks}
+
+@defvr {Attribute} style
+The @code{id} of a @code{style} element.
+@end defvr
+
+@subsubheading The @code{label} Element
+
+Parent: @code{axis} or @code{labelFrame} @*
+Contents: @code{text}@math{+} @math{|} @code{descriptionGroup}
+
+This element represents a label on some aspect of the table. For example,
+the table's title is a @code{label}.
+
+The contents of the label can be one or more @code{text} elements or a
+@code{descriptionGroup}.
+
+@defvr {Attribute} style
+@defvrx {Optional} textFrameStyle
+Each of these is the @code{id} of a @code{style} element.
+@code{style} is the style of the label text, @code{textFrameStyle} the
+style for the frame around the label.
+@end defvr
+
+@defvr {Optional} purpose
+The kind of entity being labeled, one of @code{title},
+@code{subTitle}, @code{layer}, or @code{footnote}.
+@end defvr
+
+@subsubheading The @code{descriptionGroup} Element
+
+Parent: @code{label} @*
+Contents: (@code{description} @math{|} @code{text})@math{+}
+
+A @code{descriptionGroup} concatenates one or more elements to form a
+label. Each element can be a @code{text} element, which contains
+literal text, or a @code{description} element that substitutes a value
+or a variable name.
+
+@defvr {Attribute} target
+The @code{id} of an element being described. In the corpus, this is
+always @code{faceting}.
+@end defvr
+
+@defvr {Attribute} separator
+A string to separate the description of multiple groups, if the
+@code{target} has more than one. In the corpus, this is always a
+new-line.
+@end defvr
+
+Typical contents for a @code{descriptionGroup} are a value by itself:
+@example
+
+@end example
+@noindent or a variable and its value, separated by a colon:
+@example
+:
+@end example
+
+@subsubheading The @code{description} Element
+
+Parent: @code{descriptionGroup} @*
+Contents: empty
+
+A @code{description} is like a macro that expands to some property of
+the target of its parent @code{descriptionGroup}.
+
+@defvr {Attribute} name
+The name of the property. Only @code{variable} and @code{value}
+appear in the corpus.
+@end defvr
+
+@subsubheading The @code{majorTicks} Element
+
+Parent: @code{axis} @*
+Contents: @code{gridline}?
+
+@defvr {Attribute} labelAngle
+@defvrx {Attribute} length
+Both always defined to @code{0}.
+@end defvr
+
+@defvr {Attribute} style
+@defvrx {Attribute} tickFrameStyle
+Each of these is the @code{id} of a @code{style} element.
+@code{style} is the style of the tick labels, @code{tickFrameStyle}
+the style for the frames around the labels.
+@end defvr
+
+@subsubheading The @code{gridline} Element
+
+Parent: @code{majorTicks} @*
+Contents: empty
+
+Represents ``gridlines,'' which for a table represents the lines
+between the rows or columns of a table (XXX?).
+
+@defvr {Attribute} style
+The style for the gridline.
+@end defvr
+
+@defvr {Attribute} zOrder
+Observed as a number between 28 and 31. Does not seem to be
+important.
+@end defvr
+
@subsubheading The @code{setCellProperties} Element
Parent: @code{facetLayout} @*
Contents: @code{setMetaData} @code{setStyle}* @code{setFormat}@math{+} @code{union}?
This element sets style properties of cells designated by the
-@code{target} attribute of its child elements.
+@code{target} attribute of its child elements, as further restricted
+by the optional @code{union} element if present. The @code{target}
+values often used, e.g.@: @code{graph} or @code{labeling}, actually
+affect every cell, so the @code{union} element is a useful
+restriction.
@defvr {Optional} applyToConverse
If present, always @code{true}. This appears to invert the meaning of
the @code{target} of sub-elements: the selected cells are the ones
-@emph{not} designated by @code{target}.
+@emph{not} designated by @code{target}. This is confusing, given the
+additional restrictions of @code{union}, but in the corpus
+@code{applyToConverse} is never present along with @code{union}.
@end defvr
@subsubheading The @code{setMetaData} Element
@@ -1823,7 +1938,7 @@ the @code{target} of sub-elements: the selected cells are the ones
Parent: @code{setCellProperties} @*
Contents: empty
-It's really not clear what visible effect this element has, if any.
+This element is not known to have any visible effect.
@defvr {Required} target
The @code{id} of an element whose metadata is to be set. In the
@@ -1870,7 +1985,7 @@ Contents:
@end format
This element sets the format of the target, ``format'' in this case
-meaning an the SPSS print format for a variable.
+meaning the SPSS print format for a variable.
The details of this element vary depending on the schema version, as
declared in the root @code{visualization} element's @code{version}
@@ -1880,19 +1995,53 @@ elements that correspond to the different varieties of print formats.
In version 2.7 and later, @code{setFormat} instead always contains a
@code{format} element.
-@subsubheading The @code{format} Element
+XXX reinvestigate the above claim about versions: it appears to be
+incorrect.
+
+The @code{setFormat} element itself has the following attributes.
+
+@defvr {Required} target
+The @code{id} of an element whose style is to be set. In the corpus,
+this is always the @code{id} of an @code{majorTicks} or
+@code{labeling} element.
+@end defvr
+
+@defvr {Optional} reset
+If this is @code{true}, this format overrides the target's previous
+format. If it is @code{false}, the adds to the previous format. In
+the corpus this is always @code{true}. The default behavior is
+unknown.
+@end defvr
+
+@menu
+* SPV Detail format Element::
+* SPV Detail numberFormat Element::
+* SPV Detail stringFormat Element::
+* SPV Detail dateTimeFormat Element::
+* SPV Detail affix Element::
+* SPV Detail relabel Element::
+* SPV Detail union Element::
+@end menu
+
+@node SPV Detail format Element
+@subsubsection The @code{format} Element
Parent: @code{sourceVariable}, @code{derivedVariable}, @code{formatMapping}, @code{labeling}, @code{formatMapping}, @code{setFormat} @*
-Contents: (@code{affix}@math{+} @math{|} @code{relabel})?
+Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
+
+This element appears only in schema version 2.7 (@pxref{SPV Detail
+visualization Element}).
This element determines a format, equivalent to an SPSS print format.
-The following attribute determines the high-level kind of formatting
-in use:
+
+@subsubheading Attributes for All Formats
+
+These attributes apply to all kinds of formats. The most important of
+these attributes determines the high-level kind of formatting in use:
@defvr {Optional} baseFormat
-One of @code{date}, @code{time}, @code{dateTime}, or
-@code{elapsedTime}. When this attribute is omitted, this element is a
-numeric or string format.
+Either @code{dateTime} or @code{elapsedTime}. When this attribute is
+omitted, this element is a numeric or string format.
@end defvr
@noindent
@@ -1903,6 +2052,7 @@ never present (``no''), or sometimes present (``opt'') depends on
@multitable {maximumFractionDigits} {@code{dateTime}} {@code{elapsedTime}} {number} {string}
@headitem Attribute @tab @code{dateTime} @tab @code{elapsedTime} @tab number @tab string
@item errorCharacter @tab yes @tab yes @tab yes @tab opt
+@item @w{ }
@item separatorChars @tab yes @tab no @tab no @tab no
@item @w{ }
@item mdyOrder @tab yes @tab no @tab no @tab no
@@ -1922,7 +2072,7 @@ never present (``no''), or sometimes present (``opt'') depends on
@item hourFormat @tab yes @tab opt @tab no @tab no
@item hourPadding @tab yes @tab yes @tab no @tab no
@item @w{ }
-@item showMinute @tab yes @tab no @tab no @tab no
+@item showMinute @tab yes @tab yes @tab no @tab no
@item minutePadding @tab yes @tab yes @tab no @tab no
@item @w{ }
@item showSecond @tab yes @tab yes @tab no @tab no
@@ -1933,23 +2083,25 @@ never present (``no''), or sometimes present (``opt'') depends on
@item minimumIntegerDigits @tab no @tab no @tab yes @tab no
@item maximumFractionDigits @tab no @tab yes @tab yes @tab no
@item minimumFractionDigits @tab no @tab yes @tab yes @tab no
-@item useGrouping @tab no @tab opt @tab no @tab no
-@item @w{ }
-@item tryStringsAsNumbers @tab no @tab no @tab no @tab no
-@item @w{ }
+@item useGrouping @tab no @tab opt @tab yes @tab no
@item scientific @tab no @tab no @tab yes @tab no
@item small @tab no @tab no @tab opt @tab no
-@item @w{ }
@item suffix @tab no @tab no @tab opt @tab no
+@item @w{ }
+@item tryStringsAsNumbers @tab no @tab no @tab no @tab yes
+@item @w{ }
@end multitable
-Each attribute is described below.
-
@defvr {Attribute} errorCharacter
A character that replaces the formatted value when it cannot otherwise
be represented in the given format. Always @samp{*}.
@end defvr
+@subsubheading Date and Time Attributes
+
+These attributes are used with @code{dateTime} and @code{elapsedTime}
+formats or both.
+
@defvr {Attribute} separatorChars
Exactly four characters. In order, these are used for: decimal point,
grouping, date separator, time separator. Always @samp{.,-:}.
@@ -1995,39 +2147,35 @@ Only values of @code{true} and @code{short}, respectively, have been
observed.
@end defvr
-@defvr {Attribute} showDay
-@defvrx {Attribute} dayPadding
+@defvr {Attribute} dayPadding
@defvrx {Attribute} dayOfMonthPadding
-@defvrx {Attribute} dayType
-When @code{baseFormat} is @code{elapsedTime}, @code{showDay} controls
-whether and how the ``day'' component (e.g.@: the number of elapsed
-24-hour periods) of the elapsed time is displayed. @code{dayPadding}
-presumably controls whether the day is padded with spaces, but the
-details are not understood. The only observed values are @code{true}
-and @code{true}, respectively. @code{dayOfMonthPadding} and
-@code{dayType} are not used.
-
-When @code{baseFormat} is @code{dateTime}, @code{showDay}, which is
-always @code{true} in the corpus, controls whether a day is displayed.
-@code{dayType} is always @code{month} in the corpus, specifying that
+@defvrx {Attribute} hourPadding
+@defvrx {Attribute} minutePadding
+@defvrx {Attribute} secondPadding
+These attributes presumably control whether each field in the output
+is padded with spaces to its maximum width, but the details are not
+understood. The only observed value for any of these attributes is
+@code{true}.
+@end defvr
+
+@defvr {Attribute} showDay
+@defvrx {Attribute} showHour
+@defvrx {Attribute} showMinute
+@defvrx {Attribute} showSecond
+@defvrx {Attribute} showMillis
+These attributes presumably control whether each field is displayed
+in the output, but the details are not understood. The only
+observed value for any of these attributes is @code{true}.
+@end defvr
+
+@defvr {Attribute} dayType
+This attribute is always @code{month} in the corpus, specifying that
the day of the month is to be displayed; a value of @code{year} is
supposed to indicate that the day of the year, where 1 is January 1,
-is to be displayed instead. @code{dayOfMonthPadding} or possibly
-@code{dayPadding} presumably controls whether a 1-digit day of the
-month is padded with a space to occupy two positions; in the corpus
-both are always present and always @code{true}. (A day of the year
-would presumably be padded to 3 positions.)
+is to be displayed instead.
@end defvr
-@defvr {Attribute} showHour
-@defvrx {Attribute} hourFormat
-@defvrx {Attribute} hourPadding
-@code{showHour} controls whether and how the hour component of a date
-or an elapsed time is displayed. @code{hourPadding} presumably
-controls whether the hour is padded with spaces, but the details are
-not understood. The only observed values are @code{true} and
-@code{true}, respectively.
-
+@defvr {Attribute} hourFormat
@code{hourFormat}, if present, is one of:
@table @code
@@ -2051,3 +2199,291 @@ or PM. This might indicate a bug in the code that generated the XML
in the corpus, or it might indicate that @code{elapsedTime} is
sometimes used to format a time of day.
@end defvr
+
+@subsubheading Numeric Attributes
+
+These attributes are used for formats when @code{baseFormat} is
+@code{number}. Attributes @code{maximumFractionDigits}, and
+@code{minimumFractionDigits}, and @code{useGrouping} are also used
+when @code{baseFormat} is @code{elapsedTime}.
+
+@defvr {Attribute} minimumIntegerDigits
+Minimum number of digits to display before the decimal point. Always
+observed as @code{0}.
+@end defvr
+
+@defvr {Attribute} maximumFractionDigits
+@defvrx {Attribute} maximumFractionDigits
+Maximum or minimum, respectively, number of digits to display after
+the decimal point. The observed values of each attribute range from 0
+to 9.
+@end defvr
+
+@defvr {Attribute} useGrouping
+Whether to use the grouping character to group digits in large
+numbers. It would make sense for the grouping character to come from
+the @code{separatorChars} attribute, but that attribute is only
+present when @code{baseFormat} is @code{dateTime} or
+@code{elapsedTime}, in the corpus at least. Perhaps that is because
+this attribute has only been observed as @code{false}.
+@end defvr
+
+@defvr {Attribute} scientific
+This attribute controls when and whether the number is formatted in
+scientific notation. It takes the following values:
+
+@table @code
+@item onlyForSmall
+Use scientific notation only when the number's magnitude is smaller
+than the value of the @code{small} attribute.
+
+@item whenNeeded
+Use scientific notation when the number will not otherwise fit in the
+available space.
+
+@item true
+Always use scientific notation. Not observed in the corpus.
+
+@item false
+Never use scientific notation. A number that won't otherwise fit will
+be replaced by an error indication (see the @code{errorCharacter}
+attribute). Not observed in the corpus.
+@end table
+@end defvr
+
+@defvr {Optional} small
+Only present when the @code{scientific} attribute is
+@code{onlyForSmall}, this is a numeric magnitude below which the
+number will be formatted in scientific notation. The values @code{0}
+and @code{0.0001} have been observed. The value @code{0} seems like a
+pathological choice, since no real number has a magnitude less than 0;
+perhaps in practice such a choice is equivalent to setting
+@code{scientific} to @code{false}.
+@end defvr
+
+@defvr {Optional} prefix
+@defvrx {Optional} suffix
+Specifies a prefix or a suffix to apply to the formatted number. Only
+@code{suffix} has been observed, with value @samp{%}.
+@end defvr
+
+@subsubheading String Attributes
+
+These attributes are used for formats when @code{baseFormat} is
+@code{string}.
+
+@defvr {Attribute} tryStringsAsNumbers
+When this is @code{true}, it is supposed to indicate that string
+values should be parsed as numbers and then displayed according to
+numeric formatting rules. However, in the corpus it is always
+@code{false}.
+@end defvr
+
+@node SPV Detail numberFormat Element
+@subsubsection The @code{numberFormat} Element
+
+Parent: @code{setFormat} @*
+Contents: @code{affix}@math{+}
+
+This element appears only in schema version 2.5 and earlier
+(@pxref{SPV Detail visualization Element}). Possibly this element
+could also contain @code{relabel} elements in a more diverse corpus.
+
+This element has the following attributes.
+
+@defvr {Attribute} maximumFractionDigits
+@defvrx {Attribute} minimumFractionDigits
+@defvrx {Attribute} minimumIntegerDigits
+@defvrx {Optional} scientific
+@defvrx {Optional} small
+@defvrx {Optional} suffix
+@defvrx {Optional} useGroupging
+The syntax and meaning of these attributes is the same as on the
+@code{format} element for a numeric format. @pxref{SPV Detail format
+element}.
+@end defvr
+
+@node SPV Detail stringFormat Element
+@subsubsection The @code{stringFormat} Element
+
+Parent: @code{setFormat} @*
+Contents: (@code{affix}@math{+} @math{|} @code{relabel}@math{+})?
+
+This element appears only in schema version 2.5 and earlier
+(@pxref{SPV Detail visualization Element}).
+
+This element has no attributes.
+
+@node SPV Detail dateTimeFormat Element
+@subsubsection The @code{dateTimeFormat} Element
+
+Parent: @code{setFormat} @*
+Contents: empty
+
+This element appears only in schema version 2.5 and earlier
+(@pxref{SPV Detail visualization Element}). Possibly this element
+could also contain @code{affix} and @code{relabel} elements in a more
+diverse corpus.
+
+The following attribute is required.
+
+@defvr {Attribute} baseFormat
+Either @code{dateTime} or @code{time}.
+@end defvr
+
+When @code{baseFormat} is @code{dateTime}, the following attributes
+are available.
+
+@defvr {Attribute} dayOfMonthPadding
+@defvrx {Attribute} dayPadding
+@defvrx {Attribute} dayType
+@defvrx {Attribute} hourFormat
+@defvrx {Attribute} hourPadding
+@defvrx {Attribute} mdyOrder
+@defvrx {Attribute} minutePadding
+@defvrx {Attribute} monthFormat
+@defvrx {Attribute} separatorChars
+@defvrx {Attribute} showDay
+@defvrx {Attribute} showHour
+@defvrx {Attribute} showMinute
+@defvrx {Attribute} showMonth
+@defvrx {Attribute} showSecond
+@defvrx {Attribute} showYear
+@defvrx {Attribute} yearAbbreviation
+The syntax and meaning of these attributes is the same as on the
+@code{format} element when that element's @code{baseFormat} is
+@code{dateTime}. @pxref{SPV Detail format Element}.
+@end defvr
+
+When @code{baseFormat} is @code{time}, the following attributes are
+available.
+
+@defvr {Attribute} hourFormat
+@defvrx {Attribute} hourPadding
+@defvrx {Attribute} minutePadding
+@defvrx {Attribute} monthFormat
+@defvrx {Attribute} separatorChars
+@defvrx {Attribute} showDay
+@defvrx {Attribute} showHour
+@defvrx {Attribute} showMinute
+@defvrx {Attribute} showMonth
+@defvrx {Attribute} showSecond
+@defvrx {Attribute} showYear
+@defvrx {Attribute} yearAbbreviation
+The syntax and meaning of these attributes is the same as on the
+@code{format} element when that element's @code{baseFormat} is
+@code{elapsedTime}. @pxref{SPV Detail format Element}.
+@end defvr
+
+@node SPV Detail affix Element
+@subsubsection The @code{affix} Element
+
+Parent: @code{format} or @code{numberFormat} or @code{stringFormat} @*
+Contents: empty
+
+Possibly this element could have @code{dateTimeFormat} as a parent in
+a more diverse corpus.
+
+This defines a suffix (or, theoretically, a prefix) for a formatted
+value. It is used to insert a reference to a footnote. It has the
+following attributes:
+
+@defvr {Attribute} definesReference
+This specifies the footnote number as a natural number: 1 for the
+first footnote, 2 for the second, and so on.
+@end defvr
+
+@defvr {Attribute} position
+Position for the footnote label. Always @code{superscript}.
+@end defvr
+
+@defvr {Attribute} suffix
+Whether the affix is a suffix (@code{true}) or a prefix
+(@code{false}). Always @code{true}.
+@end defvr
+
+@defvr {Attribute} value
+The text of the suffix or prefix. Typically a letter, e.g.@: @code{a}
+for footnote 1, @code{b} for footnote 2, @enddots{} The corpus
+contains other values: @code{*}, @code{**}, and a few that begin with
+at least one comma: @code{,b}, @code{,c}, @code{,,b}, and @code{,,c}.
+@end defvr
+
+@node SPV Detail relabel Element
+@subsubsection The @code{relabel} Element
+
+Parent: @code{format} or @code{stringFormat} @*
+Contents: empty
+
+Possibly this element could have @code{numberFormat} or
+@code{dateTimeFormat} as a parent in a more diverse corpus.
+
+This specifies how to display a given value. It is used to implement
+value labels and to display the system-missing value in a
+human-readable way. It has the following attributes:
+
+@defvr {Attribute} from
+The value to map. In the corpus this is an integer or the
+system-missing value @code{-1.797693134862316E300}.
+@end defvr
+
+@defvr {Attribute} to
+The string to display in place of the value of @code{from}. In the
+corpus this is a wide variety of value labels; the system-missing
+value is mapped to @samp{.}.
+@end defvr
+
+@node SPV Detail union Element
+@subsubsection The @code{union} Element
+
+Parent: @code{setCellProperties} @*
+Contents: @code{intersect}@math{+}
+
+This element represents a set of cells, computed as the union of the
+sets represented by each of its children.
+
+@subsubheading The @code{intersect} Element
+
+Parent: @code{union} @*
+Contents: @code{where}@math{+} @math{|} @code{intersectWhere}?
+
+This element represents a set of cells, computed as the intersection
+of the sets represented by each of its children.
+
+Of the two possible children, in the corpus @code{where} is far more
+common, appearing thousands of times, whereas @code{intersectWhere}
+only appears 4 times.
+
+Most @code{intersect} elements have two or more children.
+
+@subsubheading The @code{where} Element
+
+Parent: @code{intersect} @*
+Contents: empty
+
+This element represents the set of cells in which the value of a
+specified variable falls within a specified set.
+
+@defvr {Attribute} variable
+The @code{id} of a variable, e.g.@: @code{dimension0categories} or
+@code{dimension0group0map}.
+@end defvr
+
+@defvr {Attribute} include
+A value, or multiple values separated by semicolons,
+e.g.@: @code{0} or @code{13;14;15;16}.
+@end defvr
+
+@subsubheading The @code{intersectWhere}
+
+Parent: @code{intersect} @*
+Contents: empty
+
+The meaning of this element is unknown.
+
+@defvr {Attribute} variable
+@defvrx {Attribute} variable2
+The meaning of these attributes is unknown. In the four examples in
+the corpus they always take the values @code{dimension2categories} and
+@code{dimension0categories}, respectively.
+@end defvr