From 60e0b4f8a7f3210c94d9d488d7faac3b0d1d16f9 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Sun, 24 Jul 2016 19:26:18 -0700 Subject: [PATCH] spv-file-format: Finish documenting "format". --- spv-file-format.texi | 111 ++++++++++++++++++++++++++++++++++++++----- 1 file changed, 98 insertions(+), 13 deletions(-) diff --git a/spv-file-format.texi b/spv-file-format.texi index ce094484da..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 @@ -1903,6 +1906,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 @@ -1933,23 +1937,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{.,-:}. @@ -2047,3 +2053,82 @@ 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 -- 2.30.2