X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=spv-file-format.texi;h=a530ec9add14d0682ea14d87b7e6ff4602e9dd63;hb=acbc23b06be71e6341fe9434c2f2e55e76ddb282;hp=f4cceb4b4c5c4cb675d22ece46826ff8a92bc375;hpb=ce608320e0b30b4bfa7155acf500852f8783e4a4;p=pspp diff --git a/spv-file-format.texi b/spv-file-format.texi index f4cceb4b4c..a530ec9add 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 @@ -1823,7 +1823,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 +1870,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 +1880,37 @@ 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. + +@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})? +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 +1921,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 +1941,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 +1952,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 +2016,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 +2068,236 @@ 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