X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=spv-file-format.texi;h=82afa6de7239ee5e90efc9689aed340bf8d1f013;hb=ebc66e3005143a6feb347e99e2d6e7e900623bf0;hp=1eb9a3ef52822703d22edf1c76502b7150afcb4d;hpb=d756f0a8abc31ab634f9aff532021e3eb88374ab;p=pspp diff --git a/spv-file-format.texi b/spv-file-format.texi index 1eb9a3ef52..82afa6de72 100644 --- a/spv-file-format.texi +++ b/spv-file-format.texi @@ -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 @@ -1810,12 +1810,18 @@ 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 +1829,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 +1876,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} @@ -1879,3 +1885,495 @@ and earlier, @code{setFormat} contains one of a number of child 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. + +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:: +@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}@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. + +@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 +Either @code{dateTime} or @code{elapsedTime}. When this attribute is +omitted, this element is a numeric or string format. +@end defvr + +@noindent +Whether, in the corpus, other attributes are always present (``yes''), +never present (``no''), or sometimes present (``opt'') depends on +@code{baseFormat}: + +@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 +@item @w{ } +@item showYear @tab yes @tab no @tab no @tab no +@item yearAbbreviation @tab yes @tab no @tab no @tab no +@item @w{ } +@item showMonth @tab yes @tab no @tab no @tab no +@item monthFormat @tab yes @tab no @tab no @tab no +@item @w{ } +@item showDay @tab yes @tab opt @tab no @tab no +@item dayPadding @tab yes @tab opt @tab no @tab no +@item dayOfMonthPadding @tab yes @tab no @tab no @tab no +@item dayType @tab yes @tab no @tab no @tab no +@item @w{ } +@item showHour @tab yes @tab opt @tab no @tab no +@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 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 +@item secondPadding @tab no @tab yes @tab no @tab no +@item @w{ } +@item showMillis @tab no @tab yes @tab no @tab no +@item @w{ } +@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 yes @tab no +@item scientific @tab no @tab no @tab yes @tab no +@item small @tab no @tab no @tab opt @tab no +@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 + +@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{.,-:}. +@end defvr + +@defvr {Attribute} mdyOrder +Within a date, the order of the days, months, and years. +@code{dayMonthYear} is the only observed value, but one would expect +that @code{monthDayYear} and @code{yearMonthDay} to be reasonable as +well. +@end defvr + +@defvr {Attribute} showYear +@defvrx {Attribute} yearAbbreviation +Whether to include the year and, if so, whether the year should be +shown abbreviated, that is, with only 2 digits. Each is @code{true} +or @code{false}; only values of @code{true} and @code{false}, +respectively, have been observed. +@end defvr + +@defvr {Attribute} showMonth +@defvrx {Attribute} monthFormat +Whether to include the month (@code{true} or @code{false}) and, if so, +how to format it. @code{monthFormat} is one of the following: + +@table @code +@item long +The full name of the month, e.g.@: in an English locale, +@code{September}. + +@item short +The abbreviated name of the month, e.g.@: in an English locale, +@code{Sep}. + +@item number +The number representing the month, e.g.@: 9 for September. + +@item paddedNumber +A two-digit number representing the month, e.g.@: 09 for September. +@end table + +Only values of @code{true} and @code{short}, respectively, have been +observed. +@end defvr + +@defvr {Attribute} dayPadding +@defvrx {Attribute} dayOfMonthPadding +@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. +@end defvr + +@defvr {Attribute} hourFormat +@code{hourFormat}, if present, is one of: + +@table @code +@item AMPM +The time is displayed with an @code{am} or @code{pm} suffix, e.g.@: +@code{10:15pm}. + +@item AS_24 +The time is displayed in a 24-hour format, e.g.@: @code{22:15}. + +This is the only value observed in the corpus. + +@item AS_12 +The time is displayed in a 12-hour format, without distinguishing +morning or evening, e.g.@: @code{10;15}. +@end table + +@code{hourFormat} is sometimes present for @code{elapsedTime} formats, +which is confusing since a time duration does not have a concept of AM +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