X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=spv-file-format.texi;h=e96ce17cb98f54f5eeb389d5fc87388a9f72a396;hb=60e0b4f8a7f3210c94d9d488d7faac3b0d1d16f9;hp=15eef0eedf19814fb4429f93d3cdab04b4f4e1de;hpb=b0ea6e3d2705778be5e6ff8d079c72278d06b7b7;p=pspp diff --git a/spv-file-format.texi b/spv-file-format.texi index 15eef0eedf..e96ce17cb9 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,14 +1880,17 @@ 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 +@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})? 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 @@ -1896,47 +1899,236 @@ numeric or string format. @end defvr @noindent -Whether other attributes are required (``yes''), prohibited (``no''), -or optional (``opt'') depends on @code{baseFormat}: +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 maximumFractionDigits @tab no @tab yes @tab yes @tab no -@item minimumFractionDigits @tab no @tab yes @tab yes @tab no +@item @w{ } @item separatorChars @tab yes @tab no @tab no @tab no -@item -@item useGrouping @tab no @tab opt @tab no @tab no +@item @w{ } @item mdyOrder @tab yes @tab no @tab no @tab no -@item +@item @w{ } @item showYear @tab yes @tab no @tab no @tab no @item yearAbbreviation @tab yes @tab no @tab no @tab no -@item +@item @w{ } @item showMonth @tab yes @tab no @tab no @tab no @item monthFormat @tab yes @tab no @tab no @tab no -@item +@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 +@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 -@item showMinute @tab yes @tab no @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 +@item @w{ } @item showSecond @tab yes @tab yes @tab no @tab no @item secondPadding @tab no @tab yes @tab no @tab no -@item +@item @w{ } @item showMillis @tab no @tab yes @tab no @tab no -@item -@item tryStringsAsNumbers @tab no @tab no @tab no @tab no -@item +@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 @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