@subsubheading The @code{facetLevel} Element
-Parent: @code{facetLayout}
+Parent: @code{facetLayout} @*
Contents: @code{axis}
Each @code{facetLevel} describes a @code{variableReference} or
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
@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}
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
@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 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{.,-:}.
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
projects / pspp / commitdiff