This is pspp-dev.info, produced by makeinfo version 6.7 from
pspp-dev.texi.

This manual is for GNU PSPP version 1.4.1, software for statistical
analysis.

   Copyright (C) 1997, 1998, 2004, 2005, 2007, 2010, 2014, 2015, 2016
Free Software Foundation, Inc.

     Permission is granted to copy, distribute and/or modify this
     document under the terms of the GNU Free Documentation License,
     Version 1.3 or any later version published by the Free Software
     Foundation; with no Invariant Sections, no Front-Cover Texts, and
     no Back-Cover Texts.  A copy of the license is included in the
     section entitled "GNU Free Documentation License".
INFO-DIR-SECTION Math
START-INFO-DIR-ENTRY
* PSPP Developers Guide: (pspp-dev). Tutorial and reference for PSPP developers.
END-INFO-DIR-ENTRY


File: pspp-dev.info,  Node: SPV Legacy Detail Member XML Format,  Prev: SPV Legacy Detail Member Binary Format,  Up: SPSS Viewer File Format

D.4 Legacy Detail Member XML Format
===================================

The design of the detail XML format is not what one would end up with
for describing pivot tables.  This is because it is a special case of a
much more general format ("visualization XML" or "VizML") that can
describe a wide range of visualizations.  Most of this generality is
overkill for tables, and so we end up with a funny subset of a
general-purpose format.

   An XML Schema for VizML is available, distributed with SPSS binaries,
under a nonfree license.  It contains documentation that is occasionally
helpful.

   This section describes the detail XML format using the same notation
already used for the structure XML format (*note SPV Structure Member
Format::).  See 'src/output/spv/detail-xml.grammar' in the PSPP source
tree for the full grammar that it uses for parsing.

   The important elements of the detail XML format are:

   * Variables.  *Note SPV Detail Variable Elements::.

   * Assignment of variables to axes.  A variable can appear as columns,
     or rows, or layers.  The 'faceting' element and its sub-elements
     describe this assignment.

   * Styles and other annotations.

   This description is not detailed enough to write legacy tables.
Instead, write tables in the light binary format.

* Menu:

* SPV Detail visualization Element::
* SPV Detail Variable Elements::
* SPV Detail extension Element::
* SPV Detail graph Element::
* SPV Detail location Element::
* SPV Detail faceting Element::
* SPV Detail facetLayout Element::
* SPV Detail label Element::
* SPV Detail setCellProperties Element::
* SPV Detail setFormat Element::
* SPV Detail interval Element::
* SPV Detail style Element::
* SPV Detail labelFrame Element::
* SPV Detail Legacy Properties::


File: pspp-dev.info,  Node: SPV Detail visualization Element,  Next: SPV Detail Variable Elements,  Up: SPV Legacy Detail Member XML Format

D.4.1 The 'visualization' Element
---------------------------------

     visualization
        :creator
        :date
        :lang
        :name
        :style[style_ref]=ref style
        :type
        :version
        :schemaLocation?
     => visualization_extension?
        userSource
        (sourceVariable | derivedVariable)+
        categoricalDomain?
        graph
        labelFrame[lf1]*
        container?
        labelFrame[lf2]*
        style+
        layerController?

     extension[visualization_extension]
        :numRows=int?
        :showGridline=bool?
        :minWidthSet=(true)?
        :maxWidthSet=(true)?
     => EMPTY

     userSource :missing=(listwise | pairwise)? => EMPTY

     categoricalDomain => variableReference simpleSort

     simpleSort :method[sort_method]=(custom) => categoryOrder

     container :style=ref style => container_extension? location+ labelFrame*

     extension[container_extension] :combinedFootnotes=(true) => EMPTY

     layerController
        :source=(tableData)
        :target=ref label?
     => EMPTY

   The 'visualization' element is the root of detail XML member.  It has
the following attributes:

 -- Attribute: creator
     The version of the software that created this SPV file, as a string
     of the form 'xxyyzz', which represents software version xx.yy.zz,
     e.g. '160001' is version 16.0.1.  The corpus includes major
     versions 16 through 19.

 -- Attribute: date
     The date on the which the file was created, as a string of the form
     'YYYY-MM-DD'.

 -- Attribute: lang
     The locale used for output, in Windows format, which is similar to
     the format used in Unix with the underscore replaced by a hyphen,
     e.g. 'en-US', 'en-GB', 'el-GR', 'sr-Cryl-RS'.

 -- Attribute: name
     The title of the pivot table, localized to the output language.

 -- Attribute: style
     The base style for the pivot table.  In every example in the
     corpus, the 'style' element has no attributes other than 'id'.

 -- Attribute: type
     A floating-point number.  The meaning is unknown.

 -- Attribute: version
     The visualization schema version number.  In the corpus, the value
     is one of 2.4, 2.5, 2.7, and 2.8.

   The 'userSource' element has no visible effect.

   The 'extension' element as a child of 'visualization' has the
following attributes.

 -- Attribute: numRows
     An integer that presumably defines the number of rows in the
     displayed pivot table.

 -- Attribute: showGridline
     Always set to 'false' in the corpus.

 -- Attribute: minWidthSet
 -- Attribute: maxWidthSet
     Always set to 'true' in the corpus.

   The 'extension' element as a child of 'container' has the following
attribute

 -- Attribute: combinedFootnotes
     Meaning unknown.

   The 'categoricalDomain' and 'simpleSort' elements have no visible
effect.

   The 'layerController' element has no visible effect.


File: pspp-dev.info,  Node: SPV Detail Variable Elements,  Next: SPV Detail extension Element,  Prev: SPV Detail visualization Element,  Up: SPV Legacy Detail Member XML Format

D.4.2 Variable Elements
-----------------------

A "variable" in detail XML is a 1-dimensional array of data.  Each
element of the array may, independently, have string or numeric content.
All of the variables in a given detail XML member either have the same
number of elements or have zero elements.

   Two different elements define variables and their content:

'sourceVariable'
     These variables' data comes from the associated 'tableData.bin'
     member.

'derivedVariable'
     These variables are defined in terms of a mapping function from a
     source variable, or they are empty.

   A variable named 'cell' always exists.  This variable holds the data
displayed in the table.

   Variables in detail XML roughly correspond to the dimensions in a
light detail member.  Each dimension has the following variables with
stylized names, where N is a number for the dimension starting from 0:

'dimensionNcategories'
     The dimension's leaf categories (*note SPV Light Member
     Categories::).

'dimensionNgroup0'
     Present only if the dimension's categories are grouped, this
     variable holds the group labels for the categories.  Grouping is
     inferred through adjacent identical labels.  Categories that are
     not part of a group have empty-string data in this variable.

'dimensionNgroup1'
     Present only if the first-level groups are further grouped, this
     variable holds the labels for the second-level groups.  There can
     be additional variables with further levels of grouping.

'dimensionN'
     An empty variable.

   Determining the data for a (non-empty) variable is a multi-step
process:

  1. Draw initial data from its source, for a 'sourceVariable', or from
     another named variable, for a 'derivedVariable'.

  2. Apply mappings from 'valueMapEntry' elements within the
     'derivedVariable' element, if any.

  3. Apply mappings from 'relabel' elements within a 'format' or
     'stringFormat' element in the 'sourceVariable' or 'derivedVariable'
     element, if any.

  4. If the variable is a 'sourceVariable' with a 'labelVariable'
     attribute, and there were no mappings to apply in previous steps,
     then replace each element of the variable by the corresponding
     value in the label variable.

   A single variable's data can be modified in two of the steps, if both
'valueMapEntry' and 'relabel' are used.  The following example from the
corpus maps several integers to 2, then maps 2 in turn to the string
"Input":

     <derivedVariable categorical="true" dependsOn="dimension0categories"
                      id="dimension0group0map" value="map(dimension0group0)">
       <stringFormat>
         <relabel from="2" to="Input"/>
         <relabel from="10" to="Missing Value Handling"/>
         <relabel from="14" to="Resources"/>
         <relabel from="0" to=""/>
         <relabel from="1" to=""/>
         <relabel from="13" to=""/>
       </stringFormat>
       <valueMapEntry from="2;3;5;6;7;8;9" to="2"/>
       <valueMapEntry from="10;11" to="10"/>
       <valueMapEntry from="14;15" to="14"/>
       <valueMapEntry from="0" to="0"/>
       <valueMapEntry from="1" to="1"/>
       <valueMapEntry from="13" to="13"/>
     </derivedVariable>

* Menu:

* SPV Detail sourceVariable Element::
* SPV Detail derivedVariable Element::
* SPV Detail valueMapEntry Element::


File: pspp-dev.info,  Node: SPV Detail sourceVariable Element,  Next: SPV Detail derivedVariable Element,  Up: SPV Detail Variable Elements

D.4.2.1 The 'sourceVariable' Element
....................................

     sourceVariable
        :id
        :categorical=(true)
        :source
        :domain=ref categoricalDomain?
        :sourceName
        :dependsOn=ref sourceVariable?
        :label?
        :labelVariable=ref sourceVariable?
     => variable_extension* (format | stringFormat)?

   This element defines a variable whose data comes from the
'tableData.bin' member that corresponds to this '.xml'.

   This element has the following attributes.

 -- Attribute: id
     An 'id' is always present because this element exists to be
     referenced from other elements.

 -- Attribute: categorical
     Always set to 'true'.

 -- Attribute: source
     Always set to 'tableData', the 'source-name' in the corresponding
     'tableData.bin' member (*note SPV Legacy Member Metadata::).

 -- Attribute: sourceName
     The name of a variable within the source, corresponding to the
     'variable-name' in the 'tableData.bin' member (*note SPV Legacy
     Member Numeric Data::).

 -- Attribute: label
     The variable label, if any.

 -- Attribute: labelVariable
     The 'variable-name' of a variable whose string values correspond
     one-to-one with the values of this variable and are suitable for
     use as value labels.

 -- Attribute: dependsOn
     This attribute doesn't affect the display of a table.


File: pspp-dev.info,  Node: SPV Detail derivedVariable Element,  Next: SPV Detail valueMapEntry Element,  Prev: SPV Detail sourceVariable Element,  Up: SPV Detail Variable Elements

D.4.2.2 The 'derivedVariable' Element
.....................................

     derivedVariable
        :id
        :categorical=(true)
        :value
        :dependsOn=ref sourceVariable?
     => variable_extension* (format | stringFormat)? valueMapEntry*

   Like 'sourceVariable', this element defines a variable whose values
can be used elsewhere in the visualization.  Instead of being read from
a data source, the variable's data are defined by a mathematical
expression.

   This element has the following attributes.

 -- Attribute: id
     An 'id' is always present because this element exists to be
     referenced from other elements.

 -- Attribute: categorical
     Always set to 'true'.

 -- Attribute: value
     An expression that defines the variable's value.  In theory this
     could be an arbitrary expression in terms of constants, functions,
     and other variables, e.g. (VAR1 + VAR2) / 2.  In practice, the
     corpus contains only the following forms of expressions:

     'constant(0)'
     'constant(VARIABLE)'
          All zeros.  The reason why a variable is sometimes named is
          unknown.  Sometimes the "variable name" has spaces in it.

     'map(VARIABLE)'
          Transforms the values in the named VARIABLE using the
          'valueMapEntry's contained within the element.

 -- Attribute: dependsOn
     This attribute doesn't affect the display of a table.


File: pspp-dev.info,  Node: SPV Detail valueMapEntry Element,  Prev: SPV Detail derivedVariable Element,  Up: SPV Detail Variable Elements

D.4.2.3 The 'valueMapEntry' Element
...................................

     valueMapEntry :from :to => EMPTY

   A 'valueMapEntry' element defines a mapping from one or more values
of a source expression to a target value.  (In the corpus, the source
expression is always just the name of a variable.)  Each target value
requires a separate 'valueMapEntry'.  If multiple source values map to
the same target value, they can be combined or separate.

   In the corpus, all of the source and target values are integers.

   'valueMapEntry' has the following attributes.

 -- Attribute: from
     A source value, or multiple source values separated by semicolons,
     e.g. '0' or '13;14;15;16'.

 -- Attribute: to
     The target value, e.g. '0'.


File: pspp-dev.info,  Node: SPV Detail extension Element,  Next: SPV Detail graph Element,  Prev: SPV Detail Variable Elements,  Up: SPV Legacy Detail Member XML Format

D.4.3 The 'extension' Element
-----------------------------

This is a general-purpose "extension" element.  Readers that don't
understand a given extension should be able to safely ignore it.  The
attributes on this element, and their meanings, vary based on the
context.  Each known usage is described separately below.  The current
extensions use attributes exclusively, without any nested elements.

'container' Parent Element
..........................

     extension[container_extension] :combinedFootnotes=(true) => EMPTY

   With 'container' as its parent element, 'extension' has the following
attributes.

 -- Attribute: combinedFootnotes
     Always set to 'true' in the corpus.

'sourceVariable' and 'derivedVariable' Parent Element
.....................................................

     extension[variable_extension] :from :helpId => EMPTY

   With 'sourceVariable' or 'derivedVariable' as its parent element,
'extension' has the following attributes.  A given parent element often
contains several 'extension' elements that specify the meaning of the
source data's variables or sources, e.g.

     <extension from="0" helpId="corrected_model"/>
     <extension from="3" helpId="error"/>
     <extension from="4" helpId="total_9"/>
     <extension from="5" helpId="corrected_total"/>

   More commonly they are less helpful, e.g.

     <extension from="0" helpId="notes"/>
     <extension from="1" helpId="notes"/>
     <extension from="2" helpId="notes"/>
     <extension from="5" helpId="notes"/>
     <extension from="6" helpId="notes"/>
     <extension from="7" helpId="notes"/>
     <extension from="8" helpId="notes"/>
     <extension from="12" helpId="notes"/>
     <extension from="13" helpId="no_help"/>
     <extension from="14" helpId="notes"/>

 -- Attribute: from
     An integer or a name like "dimension0".

 -- Attribute: helpId
     An identifier.


File: pspp-dev.info,  Node: SPV Detail graph Element,  Next: SPV Detail location Element,  Prev: SPV Detail extension Element,  Up: SPV Legacy Detail Member XML Format

D.4.4 The 'graph' Element
-------------------------

     graph
        :cellStyle=ref style
        :style=ref style
     => location+ coordinates faceting facetLayout interval

     coordinates => EMPTY

   'graph' has the following attributes.

 -- Attribute: cellStyle
 -- Attribute: style
     Each of these is the 'id' of a 'style' element (*note SPV Detail
     style Element::).  The former is the default style for individual
     cells, the latter for the entire table.


File: pspp-dev.info,  Node: SPV Detail location Element,  Next: SPV Detail faceting Element,  Prev: SPV Detail graph Element,  Up: SPV Legacy Detail Member XML Format

D.4.5 The 'location' Element
----------------------------

     location
        :part=(height | width | top | bottom | left | right)
        :method=(sizeToContent | attach | fixed | same)
        :min=dimension?
        :max=dimension?
        :target=ref (labelFrame | graph | container)?
        :value?
     => EMPTY

   Each instance of this element specifies where some part of the table
frame is located.  All the examples in the corpus have four instances of
this element, one for each of the parts 'height', 'width', 'left', and
'top'.  Some examples in the corpus add a fifth for part 'bottom', even
though it is not clear how all of 'top', 'bottom', and 'height' can be
honored at the same time.  In any case, 'location' seems to have little
importance in representing tables; a reader can safely ignore it.

 -- Attribute: part
     The part of the table being located.

 -- Attribute: method
     How the location is determined:

     'sizeToContent'
          Based on the natural size of the table.  Observed only for
          parts 'height' and 'width'.

     'attach'
          Based on the location specified in 'target'.  Observed only
          for parts 'top' and 'bottom'.

     'fixed'
          Using the value in 'value'.  Observed only for parts 'top',
          'bottom', and 'left'.

     'same'
          Same as the specified 'target'.  Observed only for part
          'left'.

 -- Attribute: min
     Minimum size.  Only observed with value '100pt'.  Only observed for
     part 'width'.

 -- Dependent: target
     Required when 'method' is 'attach' or 'same', not observed
     otherwise.  This identifies an element to attach to.  Observed with
     the ID of 'title', 'footnote', 'graph', and other elements.

 -- Dependent: value
     Required when 'method' is 'fixed', not observed otherwise.
     Observed values are '0%', '0px', '1px', and '3px' on parts 'top'
     and 'left', and '100%' on part 'bottom'.


File: pspp-dev.info,  Node: SPV Detail faceting Element,  Next: SPV Detail facetLayout Element,  Prev: SPV Detail location Element,  Up: SPV Legacy Detail Member XML Format

D.4.6 The 'faceting' Element
----------------------------

     faceting => layer[layers1]* cross layer[layers2]*

     cross => (unity | nest) (unity | nest)

     unity => EMPTY

     nest => variableReference[vars]+

     variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY

     layer
        :variable=ref (sourceVariable | derivedVariable)
        :value
        :visible=bool?
        :method[layer_method]=(nest)?
        :titleVisible=bool?
     => EMPTY

   The 'faceting' element describes the row, column, and layer structure
of the table.  Its 'cross' child determines the row and column
structure, and each 'layer' child (if any) represents a layer.  Layers
may appear before or after 'cross'.

   The 'cross' element describes the row and column structure of the
table.  It has exactly two children, the first of which describes the
table's columns and the second the table's rows.  Each child is a 'nest'
element if the table has any dimensions along the axis in question,
otherwise a 'unity' element.

   A 'nest' element contains of one or more dimensions listed from
innermost to outermost, each represented by 'variableReference' child
elements.  Each variable in a dimension is listed in order.  *Note SPV
Detail Variable Elements::, for information on the variables that
comprise a dimension.

   A 'nest' can contain a single dimension, e.g.:

     <nest>
       <variableReference ref="dimension0categories"/>
       <variableReference ref="dimension0group0"/>
       <variableReference ref="dimension0"/>
     </nest>

A 'nest' can contain multiple dimensions, e.g.:

     <nest>
       <variableReference ref="dimension1categories"/>
       <variableReference ref="dimension1group0"/>
       <variableReference ref="dimension1"/>
       <variableReference ref="dimension0categories"/>
       <variableReference ref="dimension0"/>
     </nest>

   A 'nest' may have no dimensions, in which case it still has one
'variableReference' child, which references a 'derivedVariable' whose
'value' attribute is 'constant(0)'.  In the corpus, such a
'derivedVariable' has 'row' or 'column', respectively, as its 'id'.
This is equivalent to using a 'unity' element in place of 'nest'.

   A 'variableReference' element refers to a variable through its 'ref'
attribute.

   Each 'layer' element represents a dimension, e.g.:

     <layer value="0" variable="dimension0categories" visible="true"/>
     <layer value="dimension0" variable="dimension0" visible="false"/>

'layer' has the following attributes.

 -- Attribute: variable
     Refers to a 'sourceVariable' or 'derivedVariable' element.

 -- Attribute: value
     The value to select.  For a category variable, this is always '0';
     for a data variable, it is the same as the 'variable' attribute.

 -- Attribute: visible
     Whether the layer is visible.  Generally, category layers are
     visible and data layers are not, but sometimes this attribute is
     omitted.

 -- Attribute: method
     When present, this is always 'nest'.


File: pspp-dev.info,  Node: SPV Detail facetLayout Element,  Next: SPV Detail label Element,  Prev: SPV Detail faceting Element,  Up: SPV Legacy Detail Member XML Format

D.4.7 The 'facetLayout' Element
-------------------------------

     facetLayout => tableLayout setCellProperties[scp1]*
                    facetLevel+ setCellProperties[scp2]*

     tableLayout
        :verticalTitlesInCorner=bool
        :style=ref style?
        :fitCells=(ticks both)?
     => EMPTY

   The 'facetLayout' element and its descendants control styling for the
table.

   Its 'tableLayout' child has the following attributes

 -- Attribute: verticalTitlesInCorner
     If true, in the absence of corner text, row headings will be
     displayed in the corner.

 -- Attribute: style
     Refers to a 'style' element.

 -- Attribute: fitCells
     Meaning unknown.

The 'facetLevel' Element
........................

     facetLevel :level=int :gap=dimension? => axis

     axis :style=ref style => label? majorTicks

     majorTicks
        :labelAngle=int
        :length=dimension
        :style=ref style
        :tickFrameStyle=ref style
        :labelFrequency=int?
        :stagger=bool?
     => gridline?

     gridline
        :style=ref style
        :zOrder=int
     => EMPTY

   Each 'facetLevel' describes a 'variableReference' or 'layer', and a
table has one 'facetLevel' element for each such element.  For example,
an SPV detail member that contains four 'variableReference' elements and
two 'layer' elements will contain six 'facetLevel' elements.

   In the corpus, 'facetLevel' elements and the elements that they
describe are always in the same order.  The correspondence may also be
observed in two other ways.  First, one may use the 'level' attribute,
described below.  Second, in the corpus, a 'facetLevel' always has an
'id' that is the same as the 'id' of the element it describes with
'_facetLevel' appended.  One should not formally rely on this, of
course, but it is usefully indicative.

 -- Attribute: level
     A 1-based index into the 'variableReference' and 'layer' elements,
     e.g. a 'facetLayout' with a 'level' of 1 describes the first
     'variableReference' in the SPV detail member, and in a member with
     four 'variableReference' elements, a 'facetLayout' with a 'level'
     of 5 describes the first 'layer' in the member.

 -- Attribute: gap
     Always observed as '0pt'.

   Each 'facetLevel' contains an 'axis', which in turn may contain a
'label' for the 'facetLevel' (*note SPV Detail label Element::) and does
contain a 'majorTicks' element.

 -- Attribute: labelAngle
     Normally 0.  The value -90 causes inner column or outer row labels
     to be rotated vertically.

 -- Attribute: style
 -- Attribute: tickFrameStyle
     Each refers to a 'style' element.  'style' is the style of the tick
     labels, 'tickFrameStyle' the style for the frames around the
     labels.


File: pspp-dev.info,  Node: SPV Detail label Element,  Next: SPV Detail setCellProperties Element,  Prev: SPV Detail facetLayout Element,  Up: SPV Legacy Detail Member XML Format

D.4.8 The 'label' Element
-------------------------

     label
        :style=ref style
        :textFrameStyle=ref style?
        :purpose=(title | subTitle | subSubTitle | layer | footnote)?
     => text+ | descriptionGroup

     descriptionGroup
        :target=ref faceting
        :separator?
     => (description | text)+

     description :name=(variable | value) => EMPTY

     text
        :usesReference=int?
        :definesReference=int?
        :position=(subscript | superscript)?
        :style=ref style
     => TEXT

   This element represents a label on some aspect of the table.

 -- Attribute: style
 -- Attribute: textFrameStyle
     Each of these refers to a 'style' element.  'style' is the style of
     the label text, 'textFrameStyle' the style for the frame around the
     label.

 -- Attribute: purpose
     The kind of entity being labeled.

   A 'descriptionGroup' concatenates one or more elements to form a
label.  Each element can be a 'text' element, which contains literal
text, or a 'description' element that substitutes a value or a variable
name.

 -- Attribute: target
     The 'id' of an element being described.  In the corpus, this is
     always 'faceting'.

 -- Attribute: separator
     A string to separate the description of multiple groups, if the
     'target' has more than one.  In the corpus, this is always a
     new-line.

   Typical contents for a 'descriptionGroup' are a value by itself:
     <description name="value"/>
or a variable and its value, separated by a colon:
     <description name="variable"/><text>:</text><description name="value"/>

   A 'description' is like a macro that expands to some property of the
target of its parent 'descriptionGroup'.  The 'name' attribute specifies
the property.


File: pspp-dev.info,  Node: SPV Detail setCellProperties Element,  Next: SPV Detail setFormat Element,  Prev: SPV Detail label Element,  Up: SPV Legacy Detail Member XML Format

D.4.9 The 'setCellProperties' Element
-------------------------------------

     setCellProperties
        :applyToConverse=bool?
     => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]?

   The 'setCellProperties' element sets style properties of cells or row
or column labels.

   Interpreting 'setCellProperties' requires answering two questions:
which cells or labels to style, and what styles to use.

Which Cells?
............

     union => intersect+

     intersect => where+ | intersectWhere | alternating | EMPTY

     where
        :variable=ref (sourceVariable | derivedVariable)
        :include
     => EMPTY

     intersectWhere
        :variable=ref (sourceVariable | derivedVariable)
        :variable2=ref (sourceVariable | derivedVariable)
     => EMPTY

     alternating => EMPTY

   When 'union' is present with 'intersect' children, each of those
children specifies a group of cells that should be styled, and the total
group is all those cells taken together.  When 'union' is absent, every
cell is styled.  One attribute on 'setCellProperties' affects the choice
of cells:

 -- Attribute: applyToConverse
     If true, this inverts the meaning of the cell selection: the
     selected cells are the ones _not_ designated.  This is confusing,
     given the additional restrictions of 'union', but in the corpus
     'applyToConverse' is never present along with 'union'.

   An 'intersect' specifies restrictions on the cells to be matched.
Each 'where' child specifies which values of a given variable to
include.  The attributes of 'intersect' are:

 -- Attribute: variable
     Refers to a variable, e.g. 'dimension0categories'.  Only
     "categories" variables make sense here, but other variables, e.g.
     'dimension0group0map', are sometimes seen.  The reader may ignore
     these.

 -- Attribute: include
     A value, or multiple values separated by semicolons, e.g. '0' or
     '13;14;15;16'.

   PSPP ignores 'setCellProperties' when 'intersectWhere' is present.

What Styles?
............

     setStyle
        :target=ref (labeling | graph | interval | majorTicks)
        :style=ref style
     => EMPTY

     setMetaData :target=ref graph :key :value => EMPTY

     setFormat
        :target=ref (majorTicks | labeling)
        :reset=bool?
     => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat

     setFrameStyle
        :style=ref style
        :target=ref majorTicks
     => EMPTY

   The 'set*' children of 'setCellProperties' determine the styles to
set.

   When 'setCellProperties' contains a 'setFormat' whose 'target'
references a 'labeling' element, or if it contains a 'setStyle' that
references a 'labeling' or 'interval' element, the 'setCellProperties'
sets the style for table cells.  The format from the 'setFormat', if
present, replaces the cells' format.  The style from the 'setStyle' that
references 'labeling', if present, replaces the label's font and cell
styles, except that the background color is taken instead from the
'interval''s style, if present.

   When 'setCellProperties' contains a 'setFormat' whose 'target'
references a 'majorTicks' element, or if it contains a 'setStyle' whose
'target' references a 'majorTicks', or if it contains a 'setFrameStyle'
element, the 'setCellProperties' sets the style for row or column
labels.  In this case, the 'setCellProperties' always contains a single
'where' element whose 'variable' designates the variable whose labels
are to be styled.  The format from the 'setFormat', if present, replaces
the labels' format.  The style from the 'setStyle' that references
'majorTicks', if present, replaces the labels' font and cell styles,
except that the background color is taken instead from the
'setFrameStyle''s style, if present.

   When 'setCellProperties' contains a 'setStyle' whose 'target'
references a 'graph' element, and one that references a 'labeling'
element, and the 'union' element contains 'alternating', the
'setCellProperties' sets the alternate foreground and background colors
for the data area.  The foreground color is taken from the style
referenced by the 'setStyle' that targets the 'graph', the background
color from the 'setStyle' for 'labeling'.

   A reader may ignore a 'setCellProperties' that only contains
'setMetaData', as well as 'setMetaData' within other
'setCellProperties'.

   A reader may ignore a 'setCellProperties' whose only 'set*' child is
a 'setStyle' that targets the 'graph' element.

The 'setStyle' Element
......................

     setStyle
        :target=ref (labeling | graph | interval | majorTicks)
        :style=ref style
     => EMPTY

   This element associates a style with the target.

 -- Attribute: target
     The 'id' of an element whose style is to be set.

 -- Attribute: style
     The 'id' of a 'style' element that identifies the style to set on
     the target.


File: pspp-dev.info,  Node: SPV Detail setFormat Element,  Next: SPV Detail interval Element,  Prev: SPV Detail setCellProperties Element,  Up: SPV Legacy Detail Member XML Format

D.4.10 The 'setFormat' Element
------------------------------

     setFormat
        :target=ref (majorTicks | labeling)
        :reset=bool?
     => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat

   This element sets the format of the target, "format" in this case
meaning the SPSS print format for a variable.

   The details of this element vary depending on the schema version, as
declared in the root 'visualization' element's 'version' attribute
(*note SPV Detail visualization Element::).  A reader can interpret the
content without knowing the schema version.

   The 'setFormat' element itself has the following attributes.

 -- Attribute: target
     Refers to an element whose style is to be set.

 -- Attribute: reset
     If this is 'true', this format replaces the target's previous
     format.  If it is 'false', the modifies the previous format.

* Menu:

* SPV Detail numberFormat Element::
* SPV Detail stringFormat Element::
* SPV Detail dateTimeFormat Element::
* SPV Detail elapsedTimeFormat Element::
* SPV Detail format Element::
* SPV Detail affix Element::


File: pspp-dev.info,  Node: SPV Detail numberFormat Element,  Next: SPV Detail stringFormat Element,  Up: SPV Detail setFormat Element

D.4.10.1 The 'numberFormat' Element
...................................

     numberFormat
        :minimumIntegerDigits=int?
        :maximumFractionDigits=int?
        :minimumFractionDigits=int?
        :useGrouping=bool?
        :scientific=(onlyForSmall | whenNeeded | true | false)?
        :small=real?
        :prefix?
        :suffix?
     => affix*

   Specifies a format for displaying a number.  The available options
are a superset of those available from PSPP print formats.  PSPP chooses
a print format type for a 'numberFormat' as follows:

  1. If 'scientific' is 'true', uses 'E' format.

  2. If 'prefix' is '$', uses 'DOLLAR' format.

  3. If 'suffix' is '%', uses 'PCT' format.

  4. If 'useGrouping' is 'true', uses 'COMMA' format.

  5. Otherwise, uses 'F' format.

   For translating to a print format, PSPP uses 'maximumFractionDigits'
as the number of decimals, unless that attribute is missing or out of
the range [0,15], in which case it uses 2 decimals.

 -- Attribute: minimumIntegerDigits
     Minimum number of digits to display before the decimal point.
     Always observed as '0'.

 -- Attribute: maximumFractionDigits
 -- Attribute: minimumFractionDigits
     Maximum or minimum, respectively, number of digits to display after
     the decimal point.  The observed values of each attribute range
     from 0 to 9.

 -- Attribute: useGrouping
     Whether to use the grouping character to group digits in large
     numbers.

 -- Attribute: scientific
     This attribute controls when and whether the number is formatted in
     scientific notation.  It takes the following values:

     'onlyForSmall'
          Use scientific notation only when the number's magnitude is
          smaller than the value of the 'small' attribute.

     'whenNeeded'
          Use scientific notation when the number will not otherwise fit
          in the available space.

     'true'
          Always use scientific notation.  Not observed in the corpus.

     'false'
          Never use scientific notation.  A number that won't otherwise
          fit will be replaced by an error indication (see the
          'errorCharacter' attribute).  Not observed in the corpus.

 -- Attribute: small
     Only present when the 'scientific' attribute is 'onlyForSmall',
     this is a numeric magnitude below which the number will be
     formatted in scientific notation.  The values '0' and '0.0001' have
     been observed.  The value '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 'scientific' to
     'false'.

 -- Attribute: prefix
 -- Attribute: suffix
     Specifies a prefix or a suffix to apply to the formatted number.
     Only 'suffix' has been observed, with value '%'.


File: pspp-dev.info,  Node: SPV Detail stringFormat Element,  Next: SPV Detail dateTimeFormat Element,  Prev: SPV Detail numberFormat Element,  Up: SPV Detail setFormat Element

D.4.10.2 The 'stringFormat' Element
...................................

     stringFormat => relabel* affix*

     relabel :from=real :to => EMPTY

   The 'stringFormat' element specifies how to display a string.  By
default, a string is displayed verbatim, but 'relabel' can change it.

   The 'relabel' element appears as a child of 'stringFormat' (and of
'format', when it is used to format strings).  It 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:

 -- Attribute: from
     The value to map.  In the corpus this is an integer or the
     system-missing value '-1.797693134862316E300'.

 -- Attribute: to
     The string to display in place of the value of 'from'.  In the
     corpus this is a wide variety of value labels; the system-missing
     value is mapped to '.'.


File: pspp-dev.info,  Node: SPV Detail dateTimeFormat Element,  Next: SPV Detail elapsedTimeFormat Element,  Prev: SPV Detail stringFormat Element,  Up: SPV Detail setFormat Element

D.4.10.3 The 'dateTimeFormat' Element
.....................................

     dateTimeFormat
        :baseFormat[dt_base_format]=(date | time | dateTime)
        :separatorChars?
        :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
        :showYear=bool?
        :yearAbbreviation=bool?
        :showQuarter=bool?
        :quarterPrefix?
        :quarterSuffix?
        :showMonth=bool?
        :monthFormat=(long | short | number | paddedNumber)?
        :showWeek=bool?
        :weekPadding=bool?
        :weekSuffix?
        :showDayOfWeek=bool?
        :dayOfWeekAbbreviation=bool?
        :dayPadding=bool?
        :dayOfMonthPadding=bool?
        :hourPadding=bool?
        :minutePadding=bool?
        :secondPadding=bool?
        :showDay=bool?
        :showHour=bool?
        :showMinute=bool?
        :showSecond=bool?
        :showMillis=bool?
        :dayType=(month | year)?
        :hourFormat=(AMPM | AS_24 | AS_12)?
     => affix*

   This element appears only in schema version 2.5 and earlier (*note
SPV Detail visualization Element::).

   Data to be formatted in date formats is stored as strings in legacy
data, in the format 'yyyy-mm-ddTHH:MM:SS.SSS' and must be parsed and
reformatted by the reader.

   The following attribute is required.

 -- Attribute: baseFormat
     Specifies whether a date and time are both to be displayed, or just
     one of them.

   Many of the attributes' meanings are obvious.  The following seem to
be worth documenting.

 -- Attribute: separatorChars
     Exactly four characters.  In order, these are used for: decimal
     point, grouping, date separator, time separator.  Always '.,-:'.

 -- Attribute: mdyOrder
     Within a date, the order of the days, months, and years.
     'dayMonthYear' is the only observed value, but one would expect
     that 'monthDayYear' and 'yearMonthDay' to be reasonable as well.

 -- Attribute: showYear
 -- 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 'true' or
     'false'; only values of 'true' and 'false', respectively, have been
     observed.

 -- Attribute: showMonth
 -- Attribute: monthFormat
     Whether to include the month ('true' or 'false') and, if so, how to
     format it.  'monthFormat' is one of the following:

     'long'
          The full name of the month, e.g. in an English locale,
          'September'.

     'short'
          The abbreviated name of the month, e.g. in an English locale,
          'Sep'.

     'number'
          The number representing the month, e.g. 9 for September.

     'paddedNumber'
          A two-digit number representing the month, e.g. 09 for
          September.

     Only values of 'true' and 'short', respectively, have been
     observed.

 -- Attribute: dayType
     This attribute is always 'month' in the corpus, specifying that the
     day of the month is to be displayed; a value of 'year' is supposed
     to indicate that the day of the year, where 1 is January 1, is to
     be displayed instead.

 -- Attribute: hourFormat
     'hourFormat', if present, is one of:

     'AMPM'
          The time is displayed with an 'am' or 'pm' suffix, e.g.
          '10:15pm'.

     'AS_24'
          The time is displayed in a 24-hour format, e.g. '22:15'.

          This is the only value observed in the corpus.

     'AS_12'
          The time is displayed in a 12-hour format, without
          distinguishing morning or evening, e.g. '10;15'.

     'hourFormat' is sometimes present for '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 'elapsedTime' is sometimes
     used to format a time of day.

   For a 'baseFormat' of 'date', PSPP chooses a print format type based
on the following rules:

  1. If 'showQuarter' is true: 'QYR'.

  2. Otherwise, if 'showWeek' is true: 'WKYR'.

  3. Otherwise, if 'mdyOrder' is 'dayMonthYear':

       a. If 'monthFormat' is 'number' or 'paddedNumber': 'EDATE'.

       b. Otherwise: 'DATE'.

  4. Otherwise, if 'mdyOrder' is 'yearMonthDay': 'SDATE'.

  5. Otherwise, 'ADATE'.

   For a 'baseFormat' of 'dateTime', PSPP uses 'YMDHMS' if 'mdyOrder' is
'yearMonthDay' and 'DATETIME' otherwise.  For a 'baseFormat' of 'time',
PSPP uses 'DTIME' if 'showDay' is true, otherwise 'TIME' if 'showHour'
is true, otherwise 'MTIME'.

   For a 'baseFormat' of 'date', the chosen width is the minimum for the
format type, adding 2 if 'yearAbbreviation' is false or omitted.  For
other base formats, the chosen width is the minimum for its type, plus 3
if 'showSecond' is true, plus 4 more if 'showMillis' is also true.
Decimals are 0 by default, or 3 if 'showMillis' is true.


File: pspp-dev.info,  Node: SPV Detail elapsedTimeFormat Element,  Next: SPV Detail format Element,  Prev: SPV Detail dateTimeFormat Element,  Up: SPV Detail setFormat Element

D.4.10.4 The 'elapsedTimeFormat' Element
........................................

     elapsedTimeFormat
        :baseFormat[dt_base_format]=(date | time | dateTime)
        :dayPadding=bool?
        :hourPadding=bool?
        :minutePadding=bool?
        :secondPadding=bool?
        :showYear=bool?
        :showDay=bool?
        :showHour=bool?
        :showMinute=bool?
        :showSecond=bool?
        :showMillis=bool?
     => affix*

   This element specifies the way to display a time duration.

   Data to be formatted in elapsed time formats is stored as strings in
legacy data, in the format 'H:MM:SS.SSS', with additional hour digits as
needed for long durations, and must be parsed and reformatted by the
reader.

   The following attribute is required.

 -- Attribute: baseFormat
     Specifies whether a day and a time are both to be displayed, or
     just one of them.

   The remaining attributes specify exactly how to display the elapsed
time.

   For 'baseFormat' of 'time', PSPP converts this element to print
format type 'DTIME'; otherwise, if 'showHour' is true, to 'TIME';
otherwise, to 'MTIME'.  The chosen width is the minimum for the chosen
type, adding 3 if 'showSecond' is true, adding 4 more if 'showMillis' is
also true.  Decimals are 0 by default, or 3 if 'showMillis' is true.


File: pspp-dev.info,  Node: SPV Detail format Element,  Next: SPV Detail affix Element,  Prev: SPV Detail elapsedTimeFormat Element,  Up: SPV Detail setFormat Element

D.4.10.5 The 'format' Element
.............................

     format
        :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)?
        :errorCharacter?
        :separatorChars?
        :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)?
        :showYear=bool?
        :showQuarter=bool?
        :quarterPrefix?
        :quarterSuffix?
        :yearAbbreviation=bool?
        :showMonth=bool?
        :monthFormat=(long | short | number | paddedNumber)?
        :dayPadding=bool?
        :dayOfMonthPadding=bool?
        :showWeek=bool?
        :weekPadding=bool?
        :weekSuffix?
        :showDayOfWeek=bool?
        :dayOfWeekAbbreviation=bool?
        :hourPadding=bool?
        :minutePadding=bool?
        :secondPadding=bool?
        :showDay=bool?
        :showHour=bool?
        :showMinute=bool?
        :showSecond=bool?
        :showMillis=bool?
        :dayType=(month | year)?
        :hourFormat=(AMPM | AS_24 | AS_12)?
        :minimumIntegerDigits=int?
        :maximumFractionDigits=int?
        :minimumFractionDigits=int?
        :useGrouping=bool?
        :scientific=(onlyForSmall | whenNeeded | true | false)?
        :small=real?
        :prefix?
        :suffix?
        :tryStringsAsNumbers=bool?
        :negativesOutside=bool?
     => relabel* affix*

   This element is the union of all of the more-specific format
elements.  It is interpreted in the same way as one of those format
elements, using 'baseFormat' to determine which kind of format to use.

   There are a few attributes not present in the more specific formats:

 -- Attribute: tryStringsAsNumbers
     When this is '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 'false'.

 -- Attribute: negativesOutside
     If true, the negative sign should be shown before the prefix; if
     false, it should be shown after.


File: pspp-dev.info,  Node: SPV Detail affix Element,  Prev: SPV Detail format Element,  Up: SPV Detail setFormat Element

D.4.10.6 The 'affix' Element
............................

     affix
        :definesReference=int
        :position=(subscript | superscript)
        :suffix=bool
        :value
     => EMPTY

   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:

 -- Attribute: definesReference
     This specifies the footnote number as a natural number: 1 for the
     first footnote, 2 for the second, and so on.

 -- Attribute: position
     Position for the footnote label.  Always 'superscript'.

 -- Attribute: suffix
     Whether the affix is a suffix ('true') or a prefix ('false').
     Always 'true'.

 -- Attribute: value
     The text of the suffix or prefix.  Typically a letter, e.g. 'a' for
     footnote 1, 'b' for footnote 2, ...  The corpus contains other
     values: '*', '**', and a few that begin with at least one comma:
     ',b', ',c', ',,b', and ',,c'.


File: pspp-dev.info,  Node: SPV Detail interval Element,  Next: SPV Detail style Element,  Prev: SPV Detail setFormat Element,  Up: SPV Legacy Detail Member XML Format

D.4.11 The 'interval' Element
-----------------------------

     interval :style=ref style => labeling footnotes?

     labeling
        :style=ref style?
        :variable=ref (sourceVariable | derivedVariable)
     => (formatting | format | footnotes)*

     formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping*

     formatMapping :from=int => format?

     footnotes
        :superscript=bool?
        :variable=ref (sourceVariable | derivedVariable)
     => footnoteMapping*

     footnoteMapping :definesReference=int :from=int :to => EMPTY

   The 'interval' element and its descendants determine the basic
formatting and labeling for the table's cells.  These basic styles are
overridden by more specific styles set using 'setCellProperties' (*note
SPV Detail setCellProperties Element::).

   The 'style' attribute of 'interval' itself may be ignored.

   The 'labeling' element may have a single 'formatting' child.  If
present, its 'variable' attribute refers to a variable whose values are
format specifiers as numbers, e.g.  value 0x050802 for F8.2.  However,
the numbers are not actually interpreted that way.  Instead, each number
actually present in the variable's data is mapped by a 'formatMapping'
child of 'formatting' to a 'format' that specifies how to display it.

   The 'labeling' element may also have a 'footnotes' child element.
The 'variable' attribute of this element refers to a variable whose
values are comma-delimited strings that list the 1-based indexes of
footnote references.  (Cells without any footnote references are numeric
0 instead of strings.)

   Each 'footnoteMapping' child of the 'footnotes' element defines the
footnote marker to be its 'to' attribute text for the footnote whose
1-based index is given in its 'definesReference' attribute.


File: pspp-dev.info,  Node: SPV Detail style Element,  Next: SPV Detail labelFrame Element,  Prev: SPV Detail interval Element,  Up: SPV Legacy Detail Member XML Format

D.4.12 The 'style' Element
--------------------------

     style
        :color=color?
        :color2=color?
        :labelAngle=real?
        :border-bottom=(solid | thick | thin | double | none)?
        :border-top=(solid | thick | thin | double | none)?
        :border-left=(solid | thick | thin | double | none)?
        :border-right=(solid | thick | thin | double | none)?
        :border-bottom-color?
        :border-top-color?
        :border-left-color?
        :border-right-color?
        :font-family?
        :font-size?
        :font-weight=(regular | bold)?
        :font-style=(regular | italic)?
        :font-underline=(none | underline)?
        :margin-bottom=dimension?
        :margin-left=dimension?
        :margin-right=dimension?
        :margin-top=dimension?
        :textAlignment=(left | right | center | decimal | mixed)?
        :labelLocationHorizontal=(positive | negative | center)?
        :labelLocationVertical=(positive | negative | center)?
        :decimal-offset=dimension?
        :size?
        :width?
        :visible=bool?
     => EMPTY

   A 'style' element has an effect only when it is referenced by another
element to set some aspect of the table's style.  Most of the attributes
are self-explanatory.  The rest are described below.

 -- Attribute: color
     In some cases, the text color; in others, the background color.

 -- Attribute: color2
     Not used.

 -- Attribute: labelAngle
     Normally 0.  The value -90 causes inner column or outer row labels
     to be rotated vertically.

 -- Attribute: labelLocationHorizontal
     Not used.

 -- Attribute: labelLocationVertical
     The value 'positive' corresponds to vertically aligning text to the
     top of a cell, 'negative' to the bottom, 'center' to the middle.


File: pspp-dev.info,  Node: SPV Detail labelFrame Element,  Next: SPV Detail Legacy Properties,  Prev: SPV Detail style Element,  Up: SPV Legacy Detail Member XML Format

D.4.13 The 'labelFrame' Element
-------------------------------

     labelFrame :style=ref style => location+ label? paragraph?

     paragraph :hangingIndent=dimension? => EMPTY

   A 'labelFrame' element specifies content and style for some aspect of
a table.  Only 'labelFrame' elements that have a 'label' child are
important.  The 'purpose' attribute in the 'label' determines what the
'labelFrame' affects:

'title'
     The table's title and its style.

'subTitle'
     The table's caption and its style.

'footnote'
     The table's footnotes and the style for the footer area.

'layer'
     The style for the layer area.

'subSubTitle'
     Ignored.

   The 'style' attribute references the style to use for the area.

   The 'label', if present, specifies the text to put into the title or
caption or footnotes.  For footnotes, the label has two 'text' children
for every footnote, each of which has a 'usesReference' attribute
identifying the 1-based index of a footnote.  The first, third, fifth,
... 'text' child specifies the content for a footnote; the second,
fourth, sixth, ... child specifies the marker.  Content tends to end in
a new-line, which the reader may wish to trim; similarly, markers tend
to end in '.'.

   The 'paragraph', if present, may be ignored, since it is always
empty.


File: pspp-dev.info,  Node: SPV Detail Legacy Properties,  Prev: SPV Detail labelFrame Element,  Up: SPV Legacy Detail Member XML Format

D.4.14 Legacy Properties
------------------------

The detail XML format has features for styling most of the aspects of a
table.  It also inherits defaults for many aspects from structure XML,
which has the following 'tableProperties' element:

     tableProperties
     => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties

     generalProperties
        :hideEmptyRows=bool?
        :maximumColumnWidth=dimension?
        :maximumRowWidth=dimension?
        :minimumColumnWidth=dimension?
        :minimumRowWidth=dimension?
        :rowDimensionLabels=(inCorner | nested)?
     => EMPTY

     footnoteProperties
        :markerPosition=(superscript | subscript)?
        :numberFormat=(alphabetic | numeric)?
     => EMPTY

     cellFormatProperties => cell_style+

     any[cell_style]
        :alternatingColor=color?
        :alternatingTextColor=color?
     => style

     style
        :color=color?
        :color2=color?
        :font-family?
        :font-size?
        :font-style=(regular | italic)?
        :font-weight=(regular | bold)?
        :labelLocationVertical=(positive | negative | center)?
        :margin-bottom=dimension?
        :margin-left=dimension?
        :margin-right=dimension?
        :margin-top=dimension?
        :textAlignment=(left | right | center | decimal | mixed)?
        :decimal-offset=dimension?
     => EMPTY

     borderProperties => border_style+

     any[border_style]
        :borderStyleType=(none | solid | dashed | thick | thin | double)?
        :color=color?
     => EMPTY

     printingProperties
        :printAllLayers=bool?
        :rescaleLongTableToFitPage=bool?
        :rescaleWideTableToFitPage=bool?
        :windowOrphanLines=int?
        :continuationText?
        :continuationTextAtBottom=bool?
        :continuationTextAtTop=bool?
        :printEachLayerOnSeparatePage=bool?
     => EMPTY


File: pspp-dev.info,  Node: Encrypted File Wrappers,  Next: q2c Input Format,  Prev: SPSS Viewer File Format,  Up: Top

E Encrypted File Wrappers
*************************

SPSS 21 and later can package multiple kinds of files inside an
encrypted wrapper.  The wrapper has a common format, regardless of the
kind of the file that it contains.

     Warning: The SPSS encryption wrapper is poorly designed.  When the
     password is unknown, it is much cheaper and faster to decrypt a
     file encrypted this way than if a well designed alternative were
     used.  If you must use this format, use a 10-byte randomly
     generated password.

* Menu:

* Common Wrapper Format::
* Password Encoding::


File: pspp-dev.info,  Node: Common Wrapper Format,  Next: Password Encoding,  Up: Encrypted File Wrappers

E.1 Common Wrapper Format
=========================

An encrypted file wrapper begins with the following 36-byte header,
where xxx identifies the type of file encapsulated: 'SAV' for a system
file, 'SPS' for a syntax file, 'SPV' for a viewer file.  PSPP code for
identifying these files just checks for the 'ENCRYPTED' keyword at
offset 8, but the other bytes are also fixed in practice:

     0000  1c 00 00 00 00 00 00 00  45 4e 43 52 59 50 54 45  |........ENCRYPTE|
     0010  44 xx xx xx 15 00 00 00  00 00 00 00 00 00 00 00  |Dxxx............|
     0020  00 00 00 00                                       |....|

   Following the fixed header is essentially the regular contents of the
encapsulated file in its usual format, with each 16-byte block encrypted
with AES-256 in ECB mode.

   To make the plaintext an even multiple of 16 bytes in length, the
encryption process appends PKCS #7 padding, as specified in RFC 5652
section 6.3.  Padding appends 1 to 16 bytes to the plaintext, in which
each byte of padding is the number of padding bytes added.  If the
plaintext is, for example, 2 bytes short of a multiple of 16, the
padding is 2 bytes with value 02; if the plaintext is a multiple of 16
bytes in length, the padding is 16 bytes with value 0x10.

   The AES-256 key is derived from a password in the following way:

  1. Start from the literal password typed by the user.  Truncate it to
     at most 10 bytes, then append as many null bytes as necessary until
     there are exactly 32 bytes.  Call this PASSWORD.

  2. Let CONSTANT be the following 73-byte constant:

          0000  00 00 00 01 35 27 13 cc  53 a7 78 89 87 53 22 11
          0010  d6 5b 31 58 dc fe 2e 7e  94 da 2f 00 cc 15 71 80
          0020  0a 6c 63 53 00 38 c3 38  ac 22 f3 63 62 0e ce 85
          0030  3f b8 07 4c 4e 2b 77 c7  21 f5 1a 80 1d 67 fb e1
          0040  e1 83 07 d8 0d 00 00 01  00

  3. Compute CMAC-AES-256(PASSWORD, CONSTANT).  Call the 16-byte result
     CMAC.

  4. The 32-byte AES-256 key is CMAC || CMAC, that is, CMAC repeated
     twice.

Example
-------

Consider the password 'pspp'.  PASSWORD is:

     0000  70 73 70 70 00 00 00 00  00 00 00 00 00 00 00 00  |pspp............|
     0010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|

CMAC is:

     0000  3e da 09 8e 66 04 d4 fd  f9 63 0c 2c a8 6f b0 45

The AES-256 key is:

     0000  3e da 09 8e 66 04 d4 fd  f9 63 0c 2c a8 6f b0 45
     0010  3e da 09 8e 66 04 d4 fd  f9 63 0c 2c a8 6f b0 45

* Menu:

* Checking Passwords::


File: pspp-dev.info,  Node: Checking Passwords,  Up: Common Wrapper Format

E.1.1 Checking Passwords
------------------------

A program reading an encrypted file may wish to verify that the password
it was given is the correct one.  One way is to verify that the PKCS #7
padding at the end of the file is well formed.  However, any plaintext
that ends in byte 01 is well formed PKCS #7, meaning that about 1 in 256
keys will falsely pass this test.  This might be acceptable for
interactive use, but the false positive rate is too high for a
brute-force search of the password space.

   A better test requires some knowledge of the file format being
wrapped, to obtain a "magic number" for the beginning of the file.

   * The plaintext of system files begins with '$FL2@(#)' or '$FL3@(#)'.

   * Before encryption, a syntax file is prefixed with a line at the
     beginning of the form '* Encoding: ENCODING.', where ENCODING is
     the encoding used for the rest of the file, e.g. 'windows-1252'.
     Thus, '* Encoding' may be used as a magic number for system files.

   * The plaintext of viewer files begins with 50 4b 03 04 14 00 08 (50
     4b is 'PK').


File: pspp-dev.info,  Node: Password Encoding,  Prev: Common Wrapper Format,  Up: Encrypted File Wrappers

E.2 Password Encoding
=====================

SPSS also supports what it calls "encrypted passwords."  These are not
encrypted.  They are encoded with a simple, fixed scheme.  An encoded
password is always a multiple of 2 characters long, and never longer
than 20 characters.  The characters in an encoded password are always in
the graphic ASCII range 33 through 126.  Each successive pair of
characters in the password encodes a single byte in the plaintext
password.

   Use the following algorithm to decode a pair of characters:

  1. Let A be the ASCII code of the first character, and B be the ASCII
     code of the second character.

  2. Let AH be the most significant 4 bits of A.  Find the line in the
     table below that has AH on the left side.  The right side of the
     line is a set of possible values for the most significant 4 bits of
     the decoded byte.

          2  => 2367
          3  => 0145
          47 => 89cd
          56 => abef

  3. Let BH be the most significant 4 bits of B.  Find the line in the
     second table below that has BH on the left side.  The right side of
     the line is a set of possible values for the most significant 4
     bits of the decoded byte.  Together with the results of the
     previous step, only a single possibility is left.

          2  => 139b
          3  => 028a
          47 => 46ce
          56 => 57df

  4. Let AL be the least significant 4 bits of A.  Find the line in the
     table below that has AL on the left side.  The right side of the
     line is a set of possible values for the least significant 4 bits
     of the decoded byte.

          03cf => 0145
          12de => 2367
          478b => 89cd
          569a => abef

  5. Let BL be the least significant 4 bits of B.  Find the line in the
     table below that has BL on the left side.  The right side of the
     line is a set of possible values for the least significant 4 bits
     of the decoded byte.  Together with the results of the previous
     step, only a single possibility is left.

          03cf => 028a
          12de => 139b
          478b => 46ce
          569a => 57df

Example
-------

Consider the encoded character pair '-|'.  A is 0x2d and B is 0x7c, so
AH is 2, BH is 7, AL is 0xd, and BL is 0xc.  AH means that the most
significant four bits of the decoded character is 2, 3, 6, or 7, and BH
means that they are 4, 6, 0xc, or 0xe.  The single possibility in common
is 6, so the most significant four bits are 6.  Similarly, AL means that
the least significant four bits are 2, 3, 6, or 7, and BL means they are
0, 2, 8, or 0xa, so the least significant four bits are 2.  The decoded
character is therefore 0x62, the letter 'b'.


File: pspp-dev.info,  Node: q2c Input Format,  Next: GNU Free Documentation License,  Prev: Encrypted File Wrappers,  Up: Top

Appendix F 'q2c' Input Format
*****************************

PSPP statistical procedures have a bizarre and somewhat irregular
syntax.  Despite this, a parser generator has been written that
adequately addresses many of the possibilities and tries to provide
hooks for the exceptional cases.  This parser generator is named 'q2c'.

* Menu:

* Invoking q2c::                q2c command-line syntax.
* q2c Input Structure::         High-level layout of the input file.
* Grammar Rules::               Syntax of the grammar rules.


File: pspp-dev.info,  Node: Invoking q2c,  Next: q2c Input Structure,  Up: q2c Input Format

F.1 Invoking q2c
================

     q2c INPUT.Q OUTPUT.C

   'q2c' translates a '.q' file into a '.c' file.  It takes exactly two
command-line arguments, which are the input file name and output file
name, respectively.  'q2c' does not accept any command-line options.


File: pspp-dev.info,  Node: q2c Input Structure,  Next: Grammar Rules,  Prev: Invoking q2c,  Up: q2c Input Format

F.2 'q2c' Input Structure
=========================

'q2c' input files are divided into two sections: the grammar rules and
the supporting code.  The "grammar rules", which make up the first part
of the input, are used to define the syntax of the statistical procedure
to be parsed.  The "supporting code", following the grammar rules, are
copied largely unchanged to the output file, except for certain escapes.

   The most important lines in the grammar rules are used for defining
procedure syntax.  These lines can be prefixed with a dollar sign ('$'),
which prevents Emacs' CC-mode from munging them.  Besides this, a bang
('!') at the beginning of a line causes the line, minus the bang, to be
written verbatim to the output file (useful for comments).  As a third
special case, any line that begins with the exact characters '/*
*INDENT' is ignored and not written to the output.  This allows '.q'
files to be processed through 'indent' without being munged.

   The syntax of the grammar rules themselves is given in the following
sections.

   The supporting code is passed into the output file largely unchanged.
However, the following escapes are supported.  Each escape must appear
on a line by itself.

'/* (header) */'

     Expands to a series of C '#include' directives which include the
     headers that are required for the parser generated by 'q2c'.

'/* (decls SCOPE) */'

     Expands to C variable and data type declarations for the variables
     and 'enum's input and output by the 'q2c' parser.  SCOPE must be
     either 'local' or 'global'.  'local' causes the declarations to be
     output as function locals.  'global' causes them to be declared as
     'static' module variables; thus, 'global' is a bit of a misnomer.

'/* (parser) */'

     Expands to the entire parser.  Must be enclosed within a C
     function.

'/* (free) */'

     Expands to a set of calls to the 'free' function for variables
     declared by the parser.  Only needs to be invoked if subcommands of
     type 'string' are used in the grammar rules.


File: pspp-dev.info,  Node: Grammar Rules,  Prev: q2c Input Structure,  Up: q2c Input Format

F.3 Grammar Rules
=================

The grammar rules describe the format of the syntax that the parser
generated by 'q2c' will understand.  The way that the grammar rules are
included in 'q2c' input file are described above.

   The grammar rules are divided into tokens of the following types:

Identifier ('ID')

     An identifier token is a sequence of letters, digits, and
     underscores ('_').  Identifiers are _not_ case-sensitive.

String ('STRING')

     String tokens are initiated by a double-quote character ('"') and
     consist of all the characters between that double quote and the
     next double quote, which must be on the same line as the first.
     Within a string, a backslash can be used as a "literal escape".
     The only reasons to use a literal escape are to include a double
     quote or a backslash within a string.

Special character

     Other characters, other than white space, constitute tokens in
     themselves.

   The syntax of the grammar rules is as follows:

     grammar-rules ::= command-name opt-prefix : subcommands .
     command-name ::= ID
                  ::= STRING
     opt-prefix ::=
                ::= ( ID )
     subcommands ::= subcommand
                 ::= subcommands ; subcommand

   The syntax begins with an ID token that gives the name of the
procedure to be parsed.  For command names that contain multiple words,
a STRING token may be used instead, e.g. '"FILE HANDLE"'.  Optionally,
an ID in parentheses specifies a prefix used for all file-scope
identifiers declared by the emitted code.

   The rest of the syntax consists of subcommands separated by
semicolons (';') and terminated with a full stop ('.').

     subcommand ::= default-opt arity-opt ID sbc-defn
     default-opt ::=
                 ::= *
     arity-opt ::=
               ::= +
               ::= ^
     sbc-defn ::= opt-prefix = specifiers
              ::= [ ID ] = array-sbc
              ::= opt-prefix = sbc-special-form

   A subcommand that begins with an asterisk ('*') is the default
subcommand.  The keyword used for the default subcommand can be omitted
in the PSPP syntax file.

   A plus sign ('+') indicates that a subcommand can appear more than
once.  A caret ('^') indicate that a subcommand must appear exactly
once.  A subcommand marked with neither character may appear once or not
at all, but not more than once.

   The subcommand name appears after the leading option characters.

   There are three forms of subcommands.  The first and most common form
simply gives an equals sign ('=') and a list of specifiers, which can
each be set to a single setting.  The second form declares an array,
which is a set of flags that can be individually turned on by the user.
There are also several special forms that do not take a list of
specifiers.

   Arrays require an additional 'ID' argument.  This is used as a
prefix, prepended to the variable names constructed from the specifiers.
The other forms also allow an optional prefix to be specified.

     array-sbc ::= alternatives
               ::= array-sbc , alternatives
     alternatives ::= ID
                  ::= alternatives | ID

   An array subcommand is a set of Boolean values that can independently
be turned on by the user, listed separated by commas (',').  If an value
has more than one name then these names are separated by pipes ('|').

     specifiers ::= specifier
                ::= specifiers , specifier
     specifier ::= opt-id : settings
     opt-id ::=
            ::= ID

   Ordinary subcommands (other than arrays and special forms) require a
list of specifiers.  Each specifier has an optional name and a list of
settings.  If the name is given then a correspondingly named variable
will be used to store the user's choice of setting.  If no name is given
then there is no way to tell which setting the user picked; in this case
the settings should probably have values attached.

     settings ::= setting
              ::= settings / setting
     setting ::= setting-options ID setting-value
     setting-options ::=
                     ::= *
                     ::= !
                     ::= * !

   Individual settings are separated by forward slashes ('/').  Each
setting can be as little as an 'ID' token, but options and values can
optionally be included.  The '*' option means that, for this setting,
the 'ID' can be omitted.  The '!' option means that this option is the
default for its specifier.

     setting-value ::=
                   ::= ( setting-value-2 )
                   ::= setting-value-2
     setting-value-2 ::= setting-value-options setting-value-type : ID
     setting-value-options ::=
                           ::= *
     setting-value-type ::= N
                        ::= D
                        ::= S

   Settings may have values.  If the value must be enclosed in
parentheses, then enclose the value declaration in parentheses.  Declare
the setting type as 'n', 'd', or 's' for integer, floating-point, or
string type, respectively.  The given 'ID' is used to construct a
variable name.  If option '*' is given, then the value is optional;
otherwise it must be specified whenever the corresponding setting is
specified.

     sbc-special-form ::= VAR
                      ::= VARLIST varlist-options
                      ::= INTEGER opt-list
                      ::= DOUBLE opt-list
                      ::= PINT
                      ::= STRING (the literal word STRING)
                      ::= CUSTOM
     varlist-options ::=
                     ::= ( STRING )
     opt-list ::=
              ::= LIST

   The special forms are of the following types:

'VAR'

     A single variable name.

'VARLIST'

     A list of variables.  If given, the string can be used to provide
     'PV_*' options to the call to 'parse_variables'.

'INTEGER'

     A single integer value.

'INTEGER LIST'

     A list of integers separated by spaces or commas.

'DOUBLE'

     A single floating-point value.

'DOUBLE LIST'

     A list of floating-point values.

'PINT'

     A single positive integer value.

'STRING'

     A string value.

'CUSTOM'

     A custom function is used to parse this subcommand.  The function
     must have prototype 'int custom_NAME (void)'.  It should return 0
     on failure (when it has already issued an appropriate diagnostic),
     1 on success, or 2 if it fails and the calling function should
     issue a syntax error on behalf of the custom handler.


File: pspp-dev.info,  Node: GNU Free Documentation License,  Prev: q2c Input Format,  Up: Top

Appendix G GNU Free Documentation License
*****************************************

                     Version 1.3, 3 November 2008

     Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc.
     <http://fsf.org/>

     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     functional and useful document "free" in the sense of freedom: to
     assure everyone the effective freedom to copy and redistribute it,
     with or without modifying it, either commercially or
     noncommercially.  Secondarily, this License preserves for the
     author and publisher a way to get credit for their work, while not
     being considered responsible for modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.  We
     recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work, in any medium,
     that contains a notice placed by the copyright holder saying it can
     be distributed under the terms of this License.  Such a notice
     grants a world-wide, royalty-free license, unlimited in duration,
     to use that work under the conditions stated herein.  The
     "Document", below, refers to any such manual or work.  Any member
     of the public is a licensee, and is addressed as "you".  You accept
     the license if you copy, modify or distribute the work in a way
     requiring permission under copyright law.

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter section
     of the Document that deals exclusively with the relationship of the
     publishers or authors of the Document to the Document's overall
     subject (or to related matters) and contains nothing that could
     fall directly within that overall subject.  (Thus, if the Document
     is in part a textbook of mathematics, a Secondary Section may not
     explain any mathematics.)  The relationship could be a matter of
     historical connection with the subject or with related matters, or
     of legal, commercial, philosophical, ethical or political position
     regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in the
     notice that says that the Document is released under this License.
     If a section does not fit the above definition of Secondary then it
     is not allowed to be designated as Invariant.  The Document may
     contain zero Invariant Sections.  If the Document does not identify
     any Invariant Sections then there are none.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.  A
     Front-Cover Text may be at most 5 words, and a Back-Cover Text may
     be at most 25 words.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, that is suitable for revising the document
     straightforwardly with generic text editors or (for images composed
     of pixels) generic paint programs or (for drawings) some widely
     available drawing editor, and that is suitable for input to text
     formatters or for automatic translation to a variety of formats
     suitable for input to text formatters.  A copy made in an otherwise
     Transparent file format whose markup, or absence of markup, has
     been arranged to thwart or discourage subsequent modification by
     readers is not Transparent.  An image format is not Transparent if
     used for any substantial amount of text.  A copy that is not
     "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and standard-conforming
     simple HTML, PostScript or PDF designed for human modification.
     Examples of transparent image formats include PNG, XCF and JPG.
     Opaque formats include proprietary formats that can be read and
     edited only by proprietary word processors, SGML or XML for which
     the DTD and/or processing tools are not generally available, and
     the machine-generated HTML, PostScript or PDF produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

     The "publisher" means any person or entity that distributes copies
     of the Document to the public.

     A section "Entitled XYZ" means a named subunit of the Document
     whose title either is precisely XYZ or contains XYZ in parentheses
     following text that translates XYZ in another language.  (Here XYZ
     stands for a specific section name mentioned below, such as
     "Acknowledgements", "Dedications", "Endorsements", or "History".)
     To "Preserve the Title" of such a section when you modify the
     Document means that it remains a section "Entitled XYZ" according
     to this definition.

     The Document may include Warranty Disclaimers next to the notice
     which states that this License applies to the Document.  These
     Warranty Disclaimers are considered to be included by reference in
     this License, but only as regards disclaiming warranties: any other
     implication that these Warranty Disclaimers may have is void and
     has no effect on the meaning of this License.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow the
     conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies (or copies in media that commonly
     have printed covers) of the Document, numbering more than 100, and
     the Document's license notice requires Cover Texts, you must
     enclose the copies in covers that carry, clearly and legibly, all
     these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the title
     equally prominent and visible.  You may add other material on the
     covers in addition.  Copying with changes limited to the covers, as
     long as they preserve the title of the Document and satisfy these
     conditions, can be treated as verbatim copying in other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a machine-readable
     Transparent copy along with each Opaque copy, or state in or with
     each Opaque copy a computer-network location from which the general
     network-using public has access to download using public-standard
     network protocols a complete Transparent copy of the Document, free
     of added material.  If you use the latter option, you must take
     reasonably prudent steps, when you begin distribution of Opaque
     copies in quantity, to ensure that this Transparent copy will
     remain thus accessible at the stated location until at least one
     year after the last time you distribute an Opaque copy (directly or
     through your agents or retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of copies,
     to give them a chance to provide you with an updated version of the
     Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with the
     Modified Version filling the role of the Document, thus licensing
     distribution and modification of the Modified Version to whoever
     possesses a copy of it.  In addition, you must do these things in
     the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of previous
          versions (which should, if there were any, be listed in the
          History section of the Document).  You may use the same title
          as a previous version if the original publisher of that
          version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has fewer than five), unless they release you
          from this requirement.

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section Entitled "History", Preserve its Title,
          and add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on the
          Title Page.  If there is no section Entitled "History" in the
          Document, create one stating the title, year, authors, and
          publisher of the Document as given on its Title Page, then add
          an item describing the Modified Version as stated in the
          previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in the
          "History" section.  You may omit a network location for a work
          that was published at least four years before the Document
          itself, or if the original publisher of the version it refers
          to gives permission.

       K. For any section Entitled "Acknowledgements" or "Dedications",
          Preserve the Title of the section, and preserve in the section
          all the substance and tone of each of the contributor
          acknowledgements and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document, unaltered
          in their text and in their titles.  Section numbers or the
          equivalent are not considered part of the section titles.

       M. Delete any section Entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section to be Entitled
          "Endorsements" or to conflict in title with any Invariant
          Section.

       O. Preserve any Warranty Disclaimers.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option designate
     some or all of these sections as invariant.  To do this, add their
     titles to the list of Invariant Sections in the Modified Version's
     license notice.  These titles must be distinct from any other
     section titles.

     You may add a section Entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end of
     the list of Cover Texts in the Modified Version.  Only one passage
     of Front-Cover Text and one of Back-Cover Text may be added by (or
     through arrangements made by) any one entity.  If the Document
     already includes a cover text for the same cover, previously added
     by you or by arrangement made by the same entity you are acting on
     behalf of, you may not add another; but you may replace the old
     one, on explicit permission from the previous publisher that added
     the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination all
     of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice, and that you preserve all
     their Warranty Disclaimers.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections Entitled
     "History" in the various original documents, forming one section
     Entitled "History"; likewise combine any sections Entitled
     "Acknowledgements", and any sections Entitled "Dedications".  You
     must delete all sections Entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the documents
     in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow this
     License in all other respects regarding verbatim copying of that
     document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of a
     storage or distribution medium, is called an "aggregate" if the
     copyright resulting from the compilation is not used to limit the
     legal rights of the compilation's users beyond what the individual
     works permit.  When the Document is included in an aggregate, this
     License does not apply to the other works in the aggregate which
     are not themselves derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one half
     of the entire aggregate, the Document's Cover Texts may be placed
     on covers that bracket the Document within the aggregate, or the
     electronic equivalent of covers if the Document is in electronic
     form.  Otherwise they must appear on printed covers that bracket
     the whole aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License, and all the license notices in the
     Document, and any Warranty Disclaimers, provided that you also
     include the original English version of this License and the
     original versions of those notices and disclaimers.  In case of a
     disagreement between the translation and the original version of
     this License or a notice or disclaimer, the original version will
     prevail.

     If a section in the Document is Entitled "Acknowledgements",
     "Dedications", or "History", the requirement (section 4) to
     Preserve its Title (section 1) will typically require changing the
     actual title.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense, or distribute it is void,
     and will automatically terminate your rights under this License.

     However, if you cease all violation of this License, then your
     license from a particular copyright holder is reinstated (a)
     provisionally, unless and until the copyright holder explicitly and
     finally terminates your license, and (b) permanently, if the
     copyright holder fails to notify you of the violation by some
     reasonable means prior to 60 days after the cessation.

     Moreover, your license from a particular copyright holder is
     reinstated permanently if the copyright holder notifies you of the
     violation by some reasonable means, this is the first time you have
     received notice of violation of this License (for any work) from
     that copyright holder, and you cure the violation prior to 30 days
     after your receipt of the notice.

     Termination of your rights under this section does not terminate
     the licenses of parties who have received copies or rights from you
     under this License.  If your rights have been terminated and not
     permanently reinstated, receipt of a copy of some or all of the
     same material does not give you any rights to use it.

  10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     <http://www.gnu.org/copyleft/>.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If the
     Document does not specify a version number of this License, you may
     choose any version ever published (not as a draft) by the Free
     Software Foundation.  If the Document specifies that a proxy can
     decide which future versions of this License can be used, that
     proxy's public statement of acceptance of a version permanently
     authorizes you to choose that version for the Document.

  11. RELICENSING

     "Massive Multiauthor Collaboration Site" (or "MMC Site") means any
     World Wide Web server that publishes copyrightable works and also
     provides prominent facilities for anybody to edit those works.  A
     public wiki that anybody can edit is an example of such a server.
     A "Massive Multiauthor Collaboration" (or "MMC") contained in the
     site means any set of copyrightable works thus published on the MMC
     site.

     "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0
     license published by Creative Commons Corporation, a not-for-profit
     corporation with a principal place of business in San Francisco,
     California, as well as future copyleft versions of that license
     published by that same organization.

     "Incorporate" means to publish or republish a Document, in whole or
     in part, as part of another Document.

     An MMC is "eligible for relicensing" if it is licensed under this
     License, and if all works that were first published under this
     License somewhere other than this MMC, and subsequently
     incorporated in whole or in part into the MMC, (1) had no cover
     texts or invariant sections, and (2) were thus incorporated prior
     to November 1, 2008.

     The operator of an MMC Site may republish an MMC contained in the
     site under CC-BY-SA on the same site at any time before August 1,
     2009, provided the MMC is eligible for relicensing.

ADDENDUM: How to use this License for your documents
====================================================

To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       Permission is granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version 1.3
       or any later version published by the Free Software Foundation;
       with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
       Texts.  A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have Invariant Sections, Front-Cover Texts and Back-Cover
Texts, replace the "with...Texts."  line with this:

         with the Invariant Sections being LIST THEIR TITLES, with
         the Front-Cover Texts being LIST, and with the Back-Cover Texts
         being LIST.

   If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of free
software license, such as the GNU General Public License, to permit
their use in free software.

