1This is pspp-dev.info, produced by makeinfo version 6.7 from 2pspp-dev.texi. 3 4This manual is for GNU PSPP version 1.4.1, software for statistical 5analysis. 6 7 Copyright (C) 1997, 1998, 2004, 2005, 2007, 2010, 2014, 2015, 2016 8Free Software Foundation, Inc. 9 10 Permission is granted to copy, distribute and/or modify this 11 document under the terms of the GNU Free Documentation License, 12 Version 1.3 or any later version published by the Free Software 13 Foundation; with no Invariant Sections, no Front-Cover Texts, and 14 no Back-Cover Texts. A copy of the license is included in the 15 section entitled "GNU Free Documentation License". 16INFO-DIR-SECTION Math 17START-INFO-DIR-ENTRY 18* PSPP Developers Guide: (pspp-dev). Tutorial and reference for PSPP developers. 19END-INFO-DIR-ENTRY 20 21 22File: pspp-dev.info, Node: SPV Legacy Detail Member XML Format, Prev: SPV Legacy Detail Member Binary Format, Up: SPSS Viewer File Format 23 24D.4 Legacy Detail Member XML Format 25=================================== 26 27The design of the detail XML format is not what one would end up with 28for describing pivot tables. This is because it is a special case of a 29much more general format ("visualization XML" or "VizML") that can 30describe a wide range of visualizations. Most of this generality is 31overkill for tables, and so we end up with a funny subset of a 32general-purpose format. 33 34 An XML Schema for VizML is available, distributed with SPSS binaries, 35under a nonfree license. It contains documentation that is occasionally 36helpful. 37 38 This section describes the detail XML format using the same notation 39already used for the structure XML format (*note SPV Structure Member 40Format::). See 'src/output/spv/detail-xml.grammar' in the PSPP source 41tree for the full grammar that it uses for parsing. 42 43 The important elements of the detail XML format are: 44 45 * Variables. *Note SPV Detail Variable Elements::. 46 47 * Assignment of variables to axes. A variable can appear as columns, 48 or rows, or layers. The 'faceting' element and its sub-elements 49 describe this assignment. 50 51 * Styles and other annotations. 52 53 This description is not detailed enough to write legacy tables. 54Instead, write tables in the light binary format. 55 56* Menu: 57 58* SPV Detail visualization Element:: 59* SPV Detail Variable Elements:: 60* SPV Detail extension Element:: 61* SPV Detail graph Element:: 62* SPV Detail location Element:: 63* SPV Detail faceting Element:: 64* SPV Detail facetLayout Element:: 65* SPV Detail label Element:: 66* SPV Detail setCellProperties Element:: 67* SPV Detail setFormat Element:: 68* SPV Detail interval Element:: 69* SPV Detail style Element:: 70* SPV Detail labelFrame Element:: 71* SPV Detail Legacy Properties:: 72 73 74File: pspp-dev.info, Node: SPV Detail visualization Element, Next: SPV Detail Variable Elements, Up: SPV Legacy Detail Member XML Format 75 76D.4.1 The 'visualization' Element 77--------------------------------- 78 79 visualization 80 :creator 81 :date 82 :lang 83 :name 84 :style[style_ref]=ref style 85 :type 86 :version 87 :schemaLocation? 88 => visualization_extension? 89 userSource 90 (sourceVariable | derivedVariable)+ 91 categoricalDomain? 92 graph 93 labelFrame[lf1]* 94 container? 95 labelFrame[lf2]* 96 style+ 97 layerController? 98 99 extension[visualization_extension] 100 :numRows=int? 101 :showGridline=bool? 102 :minWidthSet=(true)? 103 :maxWidthSet=(true)? 104 => EMPTY 105 106 userSource :missing=(listwise | pairwise)? => EMPTY 107 108 categoricalDomain => variableReference simpleSort 109 110 simpleSort :method[sort_method]=(custom) => categoryOrder 111 112 container :style=ref style => container_extension? location+ labelFrame* 113 114 extension[container_extension] :combinedFootnotes=(true) => EMPTY 115 116 layerController 117 :source=(tableData) 118 :target=ref label? 119 => EMPTY 120 121 The 'visualization' element is the root of detail XML member. It has 122the following attributes: 123 124 -- Attribute: creator 125 The version of the software that created this SPV file, as a string 126 of the form 'xxyyzz', which represents software version xx.yy.zz, 127 e.g. '160001' is version 16.0.1. The corpus includes major 128 versions 16 through 19. 129 130 -- Attribute: date 131 The date on the which the file was created, as a string of the form 132 'YYYY-MM-DD'. 133 134 -- Attribute: lang 135 The locale used for output, in Windows format, which is similar to 136 the format used in Unix with the underscore replaced by a hyphen, 137 e.g. 'en-US', 'en-GB', 'el-GR', 'sr-Cryl-RS'. 138 139 -- Attribute: name 140 The title of the pivot table, localized to the output language. 141 142 -- Attribute: style 143 The base style for the pivot table. In every example in the 144 corpus, the 'style' element has no attributes other than 'id'. 145 146 -- Attribute: type 147 A floating-point number. The meaning is unknown. 148 149 -- Attribute: version 150 The visualization schema version number. In the corpus, the value 151 is one of 2.4, 2.5, 2.7, and 2.8. 152 153 The 'userSource' element has no visible effect. 154 155 The 'extension' element as a child of 'visualization' has the 156following attributes. 157 158 -- Attribute: numRows 159 An integer that presumably defines the number of rows in the 160 displayed pivot table. 161 162 -- Attribute: showGridline 163 Always set to 'false' in the corpus. 164 165 -- Attribute: minWidthSet 166 -- Attribute: maxWidthSet 167 Always set to 'true' in the corpus. 168 169 The 'extension' element as a child of 'container' has the following 170attribute 171 172 -- Attribute: combinedFootnotes 173 Meaning unknown. 174 175 The 'categoricalDomain' and 'simpleSort' elements have no visible 176effect. 177 178 The 'layerController' element has no visible effect. 179 180 181File: 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 182 183D.4.2 Variable Elements 184----------------------- 185 186A "variable" in detail XML is a 1-dimensional array of data. Each 187element of the array may, independently, have string or numeric content. 188All of the variables in a given detail XML member either have the same 189number of elements or have zero elements. 190 191 Two different elements define variables and their content: 192 193'sourceVariable' 194 These variables' data comes from the associated 'tableData.bin' 195 member. 196 197'derivedVariable' 198 These variables are defined in terms of a mapping function from a 199 source variable, or they are empty. 200 201 A variable named 'cell' always exists. This variable holds the data 202displayed in the table. 203 204 Variables in detail XML roughly correspond to the dimensions in a 205light detail member. Each dimension has the following variables with 206stylized names, where N is a number for the dimension starting from 0: 207 208'dimensionNcategories' 209 The dimension's leaf categories (*note SPV Light Member 210 Categories::). 211 212'dimensionNgroup0' 213 Present only if the dimension's categories are grouped, this 214 variable holds the group labels for the categories. Grouping is 215 inferred through adjacent identical labels. Categories that are 216 not part of a group have empty-string data in this variable. 217 218'dimensionNgroup1' 219 Present only if the first-level groups are further grouped, this 220 variable holds the labels for the second-level groups. There can 221 be additional variables with further levels of grouping. 222 223'dimensionN' 224 An empty variable. 225 226 Determining the data for a (non-empty) variable is a multi-step 227process: 228 229 1. Draw initial data from its source, for a 'sourceVariable', or from 230 another named variable, for a 'derivedVariable'. 231 232 2. Apply mappings from 'valueMapEntry' elements within the 233 'derivedVariable' element, if any. 234 235 3. Apply mappings from 'relabel' elements within a 'format' or 236 'stringFormat' element in the 'sourceVariable' or 'derivedVariable' 237 element, if any. 238 239 4. If the variable is a 'sourceVariable' with a 'labelVariable' 240 attribute, and there were no mappings to apply in previous steps, 241 then replace each element of the variable by the corresponding 242 value in the label variable. 243 244 A single variable's data can be modified in two of the steps, if both 245'valueMapEntry' and 'relabel' are used. The following example from the 246corpus maps several integers to 2, then maps 2 in turn to the string 247"Input": 248 249 <derivedVariable categorical="true" dependsOn="dimension0categories" 250 id="dimension0group0map" value="map(dimension0group0)"> 251 <stringFormat> 252 <relabel from="2" to="Input"/> 253 <relabel from="10" to="Missing Value Handling"/> 254 <relabel from="14" to="Resources"/> 255 <relabel from="0" to=""/> 256 <relabel from="1" to=""/> 257 <relabel from="13" to=""/> 258 </stringFormat> 259 <valueMapEntry from="2;3;5;6;7;8;9" to="2"/> 260 <valueMapEntry from="10;11" to="10"/> 261 <valueMapEntry from="14;15" to="14"/> 262 <valueMapEntry from="0" to="0"/> 263 <valueMapEntry from="1" to="1"/> 264 <valueMapEntry from="13" to="13"/> 265 </derivedVariable> 266 267* Menu: 268 269* SPV Detail sourceVariable Element:: 270* SPV Detail derivedVariable Element:: 271* SPV Detail valueMapEntry Element:: 272 273 274File: pspp-dev.info, Node: SPV Detail sourceVariable Element, Next: SPV Detail derivedVariable Element, Up: SPV Detail Variable Elements 275 276D.4.2.1 The 'sourceVariable' Element 277.................................... 278 279 sourceVariable 280 :id 281 :categorical=(true) 282 :source 283 :domain=ref categoricalDomain? 284 :sourceName 285 :dependsOn=ref sourceVariable? 286 :label? 287 :labelVariable=ref sourceVariable? 288 => variable_extension* (format | stringFormat)? 289 290 This element defines a variable whose data comes from the 291'tableData.bin' member that corresponds to this '.xml'. 292 293 This element has the following attributes. 294 295 -- Attribute: id 296 An 'id' is always present because this element exists to be 297 referenced from other elements. 298 299 -- Attribute: categorical 300 Always set to 'true'. 301 302 -- Attribute: source 303 Always set to 'tableData', the 'source-name' in the corresponding 304 'tableData.bin' member (*note SPV Legacy Member Metadata::). 305 306 -- Attribute: sourceName 307 The name of a variable within the source, corresponding to the 308 'variable-name' in the 'tableData.bin' member (*note SPV Legacy 309 Member Numeric Data::). 310 311 -- Attribute: label 312 The variable label, if any. 313 314 -- Attribute: labelVariable 315 The 'variable-name' of a variable whose string values correspond 316 one-to-one with the values of this variable and are suitable for 317 use as value labels. 318 319 -- Attribute: dependsOn 320 This attribute doesn't affect the display of a table. 321 322 323File: pspp-dev.info, Node: SPV Detail derivedVariable Element, Next: SPV Detail valueMapEntry Element, Prev: SPV Detail sourceVariable Element, Up: SPV Detail Variable Elements 324 325D.4.2.2 The 'derivedVariable' Element 326..................................... 327 328 derivedVariable 329 :id 330 :categorical=(true) 331 :value 332 :dependsOn=ref sourceVariable? 333 => variable_extension* (format | stringFormat)? valueMapEntry* 334 335 Like 'sourceVariable', this element defines a variable whose values 336can be used elsewhere in the visualization. Instead of being read from 337a data source, the variable's data are defined by a mathematical 338expression. 339 340 This element has the following attributes. 341 342 -- Attribute: id 343 An 'id' is always present because this element exists to be 344 referenced from other elements. 345 346 -- Attribute: categorical 347 Always set to 'true'. 348 349 -- Attribute: value 350 An expression that defines the variable's value. In theory this 351 could be an arbitrary expression in terms of constants, functions, 352 and other variables, e.g. (VAR1 + VAR2) / 2. In practice, the 353 corpus contains only the following forms of expressions: 354 355 'constant(0)' 356 'constant(VARIABLE)' 357 All zeros. The reason why a variable is sometimes named is 358 unknown. Sometimes the "variable name" has spaces in it. 359 360 'map(VARIABLE)' 361 Transforms the values in the named VARIABLE using the 362 'valueMapEntry's contained within the element. 363 364 -- Attribute: dependsOn 365 This attribute doesn't affect the display of a table. 366 367 368File: pspp-dev.info, Node: SPV Detail valueMapEntry Element, Prev: SPV Detail derivedVariable Element, Up: SPV Detail Variable Elements 369 370D.4.2.3 The 'valueMapEntry' Element 371................................... 372 373 valueMapEntry :from :to => EMPTY 374 375 A 'valueMapEntry' element defines a mapping from one or more values 376of a source expression to a target value. (In the corpus, the source 377expression is always just the name of a variable.) Each target value 378requires a separate 'valueMapEntry'. If multiple source values map to 379the same target value, they can be combined or separate. 380 381 In the corpus, all of the source and target values are integers. 382 383 'valueMapEntry' has the following attributes. 384 385 -- Attribute: from 386 A source value, or multiple source values separated by semicolons, 387 e.g. '0' or '13;14;15;16'. 388 389 -- Attribute: to 390 The target value, e.g. '0'. 391 392 393File: 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 394 395D.4.3 The 'extension' Element 396----------------------------- 397 398This is a general-purpose "extension" element. Readers that don't 399understand a given extension should be able to safely ignore it. The 400attributes on this element, and their meanings, vary based on the 401context. Each known usage is described separately below. The current 402extensions use attributes exclusively, without any nested elements. 403 404'container' Parent Element 405.......................... 406 407 extension[container_extension] :combinedFootnotes=(true) => EMPTY 408 409 With 'container' as its parent element, 'extension' has the following 410attributes. 411 412 -- Attribute: combinedFootnotes 413 Always set to 'true' in the corpus. 414 415'sourceVariable' and 'derivedVariable' Parent Element 416..................................................... 417 418 extension[variable_extension] :from :helpId => EMPTY 419 420 With 'sourceVariable' or 'derivedVariable' as its parent element, 421'extension' has the following attributes. A given parent element often 422contains several 'extension' elements that specify the meaning of the 423source data's variables or sources, e.g. 424 425 <extension from="0" helpId="corrected_model"/> 426 <extension from="3" helpId="error"/> 427 <extension from="4" helpId="total_9"/> 428 <extension from="5" helpId="corrected_total"/> 429 430 More commonly they are less helpful, e.g. 431 432 <extension from="0" helpId="notes"/> 433 <extension from="1" helpId="notes"/> 434 <extension from="2" helpId="notes"/> 435 <extension from="5" helpId="notes"/> 436 <extension from="6" helpId="notes"/> 437 <extension from="7" helpId="notes"/> 438 <extension from="8" helpId="notes"/> 439 <extension from="12" helpId="notes"/> 440 <extension from="13" helpId="no_help"/> 441 <extension from="14" helpId="notes"/> 442 443 -- Attribute: from 444 An integer or a name like "dimension0". 445 446 -- Attribute: helpId 447 An identifier. 448 449 450File: 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 451 452D.4.4 The 'graph' Element 453------------------------- 454 455 graph 456 :cellStyle=ref style 457 :style=ref style 458 => location+ coordinates faceting facetLayout interval 459 460 coordinates => EMPTY 461 462 'graph' has the following attributes. 463 464 -- Attribute: cellStyle 465 -- Attribute: style 466 Each of these is the 'id' of a 'style' element (*note SPV Detail 467 style Element::). The former is the default style for individual 468 cells, the latter for the entire table. 469 470 471File: 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 472 473D.4.5 The 'location' Element 474---------------------------- 475 476 location 477 :part=(height | width | top | bottom | left | right) 478 :method=(sizeToContent | attach | fixed | same) 479 :min=dimension? 480 :max=dimension? 481 :target=ref (labelFrame | graph | container)? 482 :value? 483 => EMPTY 484 485 Each instance of this element specifies where some part of the table 486frame is located. All the examples in the corpus have four instances of 487this element, one for each of the parts 'height', 'width', 'left', and 488'top'. Some examples in the corpus add a fifth for part 'bottom', even 489though it is not clear how all of 'top', 'bottom', and 'height' can be 490honored at the same time. In any case, 'location' seems to have little 491importance in representing tables; a reader can safely ignore it. 492 493 -- Attribute: part 494 The part of the table being located. 495 496 -- Attribute: method 497 How the location is determined: 498 499 'sizeToContent' 500 Based on the natural size of the table. Observed only for 501 parts 'height' and 'width'. 502 503 'attach' 504 Based on the location specified in 'target'. Observed only 505 for parts 'top' and 'bottom'. 506 507 'fixed' 508 Using the value in 'value'. Observed only for parts 'top', 509 'bottom', and 'left'. 510 511 'same' 512 Same as the specified 'target'. Observed only for part 513 'left'. 514 515 -- Attribute: min 516 Minimum size. Only observed with value '100pt'. Only observed for 517 part 'width'. 518 519 -- Dependent: target 520 Required when 'method' is 'attach' or 'same', not observed 521 otherwise. This identifies an element to attach to. Observed with 522 the ID of 'title', 'footnote', 'graph', and other elements. 523 524 -- Dependent: value 525 Required when 'method' is 'fixed', not observed otherwise. 526 Observed values are '0%', '0px', '1px', and '3px' on parts 'top' 527 and 'left', and '100%' on part 'bottom'. 528 529 530File: 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 531 532D.4.6 The 'faceting' Element 533---------------------------- 534 535 faceting => layer[layers1]* cross layer[layers2]* 536 537 cross => (unity | nest) (unity | nest) 538 539 unity => EMPTY 540 541 nest => variableReference[vars]+ 542 543 variableReference :ref=ref (sourceVariable | derivedVariable) => EMPTY 544 545 layer 546 :variable=ref (sourceVariable | derivedVariable) 547 :value 548 :visible=bool? 549 :method[layer_method]=(nest)? 550 :titleVisible=bool? 551 => EMPTY 552 553 The 'faceting' element describes the row, column, and layer structure 554of the table. Its 'cross' child determines the row and column 555structure, and each 'layer' child (if any) represents a layer. Layers 556may appear before or after 'cross'. 557 558 The 'cross' element describes the row and column structure of the 559table. It has exactly two children, the first of which describes the 560table's columns and the second the table's rows. Each child is a 'nest' 561element if the table has any dimensions along the axis in question, 562otherwise a 'unity' element. 563 564 A 'nest' element contains of one or more dimensions listed from 565innermost to outermost, each represented by 'variableReference' child 566elements. Each variable in a dimension is listed in order. *Note SPV 567Detail Variable Elements::, for information on the variables that 568comprise a dimension. 569 570 A 'nest' can contain a single dimension, e.g.: 571 572 <nest> 573 <variableReference ref="dimension0categories"/> 574 <variableReference ref="dimension0group0"/> 575 <variableReference ref="dimension0"/> 576 </nest> 577 578A 'nest' can contain multiple dimensions, e.g.: 579 580 <nest> 581 <variableReference ref="dimension1categories"/> 582 <variableReference ref="dimension1group0"/> 583 <variableReference ref="dimension1"/> 584 <variableReference ref="dimension0categories"/> 585 <variableReference ref="dimension0"/> 586 </nest> 587 588 A 'nest' may have no dimensions, in which case it still has one 589'variableReference' child, which references a 'derivedVariable' whose 590'value' attribute is 'constant(0)'. In the corpus, such a 591'derivedVariable' has 'row' or 'column', respectively, as its 'id'. 592This is equivalent to using a 'unity' element in place of 'nest'. 593 594 A 'variableReference' element refers to a variable through its 'ref' 595attribute. 596 597 Each 'layer' element represents a dimension, e.g.: 598 599 <layer value="0" variable="dimension0categories" visible="true"/> 600 <layer value="dimension0" variable="dimension0" visible="false"/> 601 602'layer' has the following attributes. 603 604 -- Attribute: variable 605 Refers to a 'sourceVariable' or 'derivedVariable' element. 606 607 -- Attribute: value 608 The value to select. For a category variable, this is always '0'; 609 for a data variable, it is the same as the 'variable' attribute. 610 611 -- Attribute: visible 612 Whether the layer is visible. Generally, category layers are 613 visible and data layers are not, but sometimes this attribute is 614 omitted. 615 616 -- Attribute: method 617 When present, this is always 'nest'. 618 619 620File: 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 621 622D.4.7 The 'facetLayout' Element 623------------------------------- 624 625 facetLayout => tableLayout setCellProperties[scp1]* 626 facetLevel+ setCellProperties[scp2]* 627 628 tableLayout 629 :verticalTitlesInCorner=bool 630 :style=ref style? 631 :fitCells=(ticks both)? 632 => EMPTY 633 634 The 'facetLayout' element and its descendants control styling for the 635table. 636 637 Its 'tableLayout' child has the following attributes 638 639 -- Attribute: verticalTitlesInCorner 640 If true, in the absence of corner text, row headings will be 641 displayed in the corner. 642 643 -- Attribute: style 644 Refers to a 'style' element. 645 646 -- Attribute: fitCells 647 Meaning unknown. 648 649The 'facetLevel' Element 650........................ 651 652 facetLevel :level=int :gap=dimension? => axis 653 654 axis :style=ref style => label? majorTicks 655 656 majorTicks 657 :labelAngle=int 658 :length=dimension 659 :style=ref style 660 :tickFrameStyle=ref style 661 :labelFrequency=int? 662 :stagger=bool? 663 => gridline? 664 665 gridline 666 :style=ref style 667 :zOrder=int 668 => EMPTY 669 670 Each 'facetLevel' describes a 'variableReference' or 'layer', and a 671table has one 'facetLevel' element for each such element. For example, 672an SPV detail member that contains four 'variableReference' elements and 673two 'layer' elements will contain six 'facetLevel' elements. 674 675 In the corpus, 'facetLevel' elements and the elements that they 676describe are always in the same order. The correspondence may also be 677observed in two other ways. First, one may use the 'level' attribute, 678described below. Second, in the corpus, a 'facetLevel' always has an 679'id' that is the same as the 'id' of the element it describes with 680'_facetLevel' appended. One should not formally rely on this, of 681course, but it is usefully indicative. 682 683 -- Attribute: level 684 A 1-based index into the 'variableReference' and 'layer' elements, 685 e.g. a 'facetLayout' with a 'level' of 1 describes the first 686 'variableReference' in the SPV detail member, and in a member with 687 four 'variableReference' elements, a 'facetLayout' with a 'level' 688 of 5 describes the first 'layer' in the member. 689 690 -- Attribute: gap 691 Always observed as '0pt'. 692 693 Each 'facetLevel' contains an 'axis', which in turn may contain a 694'label' for the 'facetLevel' (*note SPV Detail label Element::) and does 695contain a 'majorTicks' element. 696 697 -- Attribute: labelAngle 698 Normally 0. The value -90 causes inner column or outer row labels 699 to be rotated vertically. 700 701 -- Attribute: style 702 -- Attribute: tickFrameStyle 703 Each refers to a 'style' element. 'style' is the style of the tick 704 labels, 'tickFrameStyle' the style for the frames around the 705 labels. 706 707 708File: 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 709 710D.4.8 The 'label' Element 711------------------------- 712 713 label 714 :style=ref style 715 :textFrameStyle=ref style? 716 :purpose=(title | subTitle | subSubTitle | layer | footnote)? 717 => text+ | descriptionGroup 718 719 descriptionGroup 720 :target=ref faceting 721 :separator? 722 => (description | text)+ 723 724 description :name=(variable | value) => EMPTY 725 726 text 727 :usesReference=int? 728 :definesReference=int? 729 :position=(subscript | superscript)? 730 :style=ref style 731 => TEXT 732 733 This element represents a label on some aspect of the table. 734 735 -- Attribute: style 736 -- Attribute: textFrameStyle 737 Each of these refers to a 'style' element. 'style' is the style of 738 the label text, 'textFrameStyle' the style for the frame around the 739 label. 740 741 -- Attribute: purpose 742 The kind of entity being labeled. 743 744 A 'descriptionGroup' concatenates one or more elements to form a 745label. Each element can be a 'text' element, which contains literal 746text, or a 'description' element that substitutes a value or a variable 747name. 748 749 -- Attribute: target 750 The 'id' of an element being described. In the corpus, this is 751 always 'faceting'. 752 753 -- Attribute: separator 754 A string to separate the description of multiple groups, if the 755 'target' has more than one. In the corpus, this is always a 756 new-line. 757 758 Typical contents for a 'descriptionGroup' are a value by itself: 759 <description name="value"/> 760or a variable and its value, separated by a colon: 761 <description name="variable"/><text>:</text><description name="value"/> 762 763 A 'description' is like a macro that expands to some property of the 764target of its parent 'descriptionGroup'. The 'name' attribute specifies 765the property. 766 767 768File: 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 769 770D.4.9 The 'setCellProperties' Element 771------------------------------------- 772 773 setCellProperties 774 :applyToConverse=bool? 775 => (setStyle | setFrameStyle | setFormat | setMetaData)* union[union_]? 776 777 The 'setCellProperties' element sets style properties of cells or row 778or column labels. 779 780 Interpreting 'setCellProperties' requires answering two questions: 781which cells or labels to style, and what styles to use. 782 783Which Cells? 784............ 785 786 union => intersect+ 787 788 intersect => where+ | intersectWhere | alternating | EMPTY 789 790 where 791 :variable=ref (sourceVariable | derivedVariable) 792 :include 793 => EMPTY 794 795 intersectWhere 796 :variable=ref (sourceVariable | derivedVariable) 797 :variable2=ref (sourceVariable | derivedVariable) 798 => EMPTY 799 800 alternating => EMPTY 801 802 When 'union' is present with 'intersect' children, each of those 803children specifies a group of cells that should be styled, and the total 804group is all those cells taken together. When 'union' is absent, every 805cell is styled. One attribute on 'setCellProperties' affects the choice 806of cells: 807 808 -- Attribute: applyToConverse 809 If true, this inverts the meaning of the cell selection: the 810 selected cells are the ones _not_ designated. This is confusing, 811 given the additional restrictions of 'union', but in the corpus 812 'applyToConverse' is never present along with 'union'. 813 814 An 'intersect' specifies restrictions on the cells to be matched. 815Each 'where' child specifies which values of a given variable to 816include. The attributes of 'intersect' are: 817 818 -- Attribute: variable 819 Refers to a variable, e.g. 'dimension0categories'. Only 820 "categories" variables make sense here, but other variables, e.g. 821 'dimension0group0map', are sometimes seen. The reader may ignore 822 these. 823 824 -- Attribute: include 825 A value, or multiple values separated by semicolons, e.g. '0' or 826 '13;14;15;16'. 827 828 PSPP ignores 'setCellProperties' when 'intersectWhere' is present. 829 830What Styles? 831............ 832 833 setStyle 834 :target=ref (labeling | graph | interval | majorTicks) 835 :style=ref style 836 => EMPTY 837 838 setMetaData :target=ref graph :key :value => EMPTY 839 840 setFormat 841 :target=ref (majorTicks | labeling) 842 :reset=bool? 843 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat 844 845 setFrameStyle 846 :style=ref style 847 :target=ref majorTicks 848 => EMPTY 849 850 The 'set*' children of 'setCellProperties' determine the styles to 851set. 852 853 When 'setCellProperties' contains a 'setFormat' whose 'target' 854references a 'labeling' element, or if it contains a 'setStyle' that 855references a 'labeling' or 'interval' element, the 'setCellProperties' 856sets the style for table cells. The format from the 'setFormat', if 857present, replaces the cells' format. The style from the 'setStyle' that 858references 'labeling', if present, replaces the label's font and cell 859styles, except that the background color is taken instead from the 860'interval''s style, if present. 861 862 When 'setCellProperties' contains a 'setFormat' whose 'target' 863references a 'majorTicks' element, or if it contains a 'setStyle' whose 864'target' references a 'majorTicks', or if it contains a 'setFrameStyle' 865element, the 'setCellProperties' sets the style for row or column 866labels. In this case, the 'setCellProperties' always contains a single 867'where' element whose 'variable' designates the variable whose labels 868are to be styled. The format from the 'setFormat', if present, replaces 869the labels' format. The style from the 'setStyle' that references 870'majorTicks', if present, replaces the labels' font and cell styles, 871except that the background color is taken instead from the 872'setFrameStyle''s style, if present. 873 874 When 'setCellProperties' contains a 'setStyle' whose 'target' 875references a 'graph' element, and one that references a 'labeling' 876element, and the 'union' element contains 'alternating', the 877'setCellProperties' sets the alternate foreground and background colors 878for the data area. The foreground color is taken from the style 879referenced by the 'setStyle' that targets the 'graph', the background 880color from the 'setStyle' for 'labeling'. 881 882 A reader may ignore a 'setCellProperties' that only contains 883'setMetaData', as well as 'setMetaData' within other 884'setCellProperties'. 885 886 A reader may ignore a 'setCellProperties' whose only 'set*' child is 887a 'setStyle' that targets the 'graph' element. 888 889The 'setStyle' Element 890...................... 891 892 setStyle 893 :target=ref (labeling | graph | interval | majorTicks) 894 :style=ref style 895 => EMPTY 896 897 This element associates a style with the target. 898 899 -- Attribute: target 900 The 'id' of an element whose style is to be set. 901 902 -- Attribute: style 903 The 'id' of a 'style' element that identifies the style to set on 904 the target. 905 906 907File: 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 908 909D.4.10 The 'setFormat' Element 910------------------------------ 911 912 setFormat 913 :target=ref (majorTicks | labeling) 914 :reset=bool? 915 => format | numberFormat | stringFormat+ | dateTimeFormat | elapsedTimeFormat 916 917 This element sets the format of the target, "format" in this case 918meaning the SPSS print format for a variable. 919 920 The details of this element vary depending on the schema version, as 921declared in the root 'visualization' element's 'version' attribute 922(*note SPV Detail visualization Element::). A reader can interpret the 923content without knowing the schema version. 924 925 The 'setFormat' element itself has the following attributes. 926 927 -- Attribute: target 928 Refers to an element whose style is to be set. 929 930 -- Attribute: reset 931 If this is 'true', this format replaces the target's previous 932 format. If it is 'false', the modifies the previous format. 933 934* Menu: 935 936* SPV Detail numberFormat Element:: 937* SPV Detail stringFormat Element:: 938* SPV Detail dateTimeFormat Element:: 939* SPV Detail elapsedTimeFormat Element:: 940* SPV Detail format Element:: 941* SPV Detail affix Element:: 942 943 944File: pspp-dev.info, Node: SPV Detail numberFormat Element, Next: SPV Detail stringFormat Element, Up: SPV Detail setFormat Element 945 946D.4.10.1 The 'numberFormat' Element 947................................... 948 949 numberFormat 950 :minimumIntegerDigits=int? 951 :maximumFractionDigits=int? 952 :minimumFractionDigits=int? 953 :useGrouping=bool? 954 :scientific=(onlyForSmall | whenNeeded | true | false)? 955 :small=real? 956 :prefix? 957 :suffix? 958 => affix* 959 960 Specifies a format for displaying a number. The available options 961are a superset of those available from PSPP print formats. PSPP chooses 962a print format type for a 'numberFormat' as follows: 963 964 1. If 'scientific' is 'true', uses 'E' format. 965 966 2. If 'prefix' is '$', uses 'DOLLAR' format. 967 968 3. If 'suffix' is '%', uses 'PCT' format. 969 970 4. If 'useGrouping' is 'true', uses 'COMMA' format. 971 972 5. Otherwise, uses 'F' format. 973 974 For translating to a print format, PSPP uses 'maximumFractionDigits' 975as the number of decimals, unless that attribute is missing or out of 976the range [0,15], in which case it uses 2 decimals. 977 978 -- Attribute: minimumIntegerDigits 979 Minimum number of digits to display before the decimal point. 980 Always observed as '0'. 981 982 -- Attribute: maximumFractionDigits 983 -- Attribute: minimumFractionDigits 984 Maximum or minimum, respectively, number of digits to display after 985 the decimal point. The observed values of each attribute range 986 from 0 to 9. 987 988 -- Attribute: useGrouping 989 Whether to use the grouping character to group digits in large 990 numbers. 991 992 -- Attribute: scientific 993 This attribute controls when and whether the number is formatted in 994 scientific notation. It takes the following values: 995 996 'onlyForSmall' 997 Use scientific notation only when the number's magnitude is 998 smaller than the value of the 'small' attribute. 999 1000 'whenNeeded' 1001 Use scientific notation when the number will not otherwise fit 1002 in the available space. 1003 1004 'true' 1005 Always use scientific notation. Not observed in the corpus. 1006 1007 'false' 1008 Never use scientific notation. A number that won't otherwise 1009 fit will be replaced by an error indication (see the 1010 'errorCharacter' attribute). Not observed in the corpus. 1011 1012 -- Attribute: small 1013 Only present when the 'scientific' attribute is 'onlyForSmall', 1014 this is a numeric magnitude below which the number will be 1015 formatted in scientific notation. The values '0' and '0.0001' have 1016 been observed. The value '0' seems like a pathological choice, 1017 since no real number has a magnitude less than 0; perhaps in 1018 practice such a choice is equivalent to setting 'scientific' to 1019 'false'. 1020 1021 -- Attribute: prefix 1022 -- Attribute: suffix 1023 Specifies a prefix or a suffix to apply to the formatted number. 1024 Only 'suffix' has been observed, with value '%'. 1025 1026 1027File: pspp-dev.info, Node: SPV Detail stringFormat Element, Next: SPV Detail dateTimeFormat Element, Prev: SPV Detail numberFormat Element, Up: SPV Detail setFormat Element 1028 1029D.4.10.2 The 'stringFormat' Element 1030................................... 1031 1032 stringFormat => relabel* affix* 1033 1034 relabel :from=real :to => EMPTY 1035 1036 The 'stringFormat' element specifies how to display a string. By 1037default, a string is displayed verbatim, but 'relabel' can change it. 1038 1039 The 'relabel' element appears as a child of 'stringFormat' (and of 1040'format', when it is used to format strings). It specifies how to 1041display a given value. It is used to implement value labels and to 1042display the system-missing value in a human-readable way. It has the 1043following attributes: 1044 1045 -- Attribute: from 1046 The value to map. In the corpus this is an integer or the 1047 system-missing value '-1.797693134862316E300'. 1048 1049 -- Attribute: to 1050 The string to display in place of the value of 'from'. In the 1051 corpus this is a wide variety of value labels; the system-missing 1052 value is mapped to '.'. 1053 1054 1055File: pspp-dev.info, Node: SPV Detail dateTimeFormat Element, Next: SPV Detail elapsedTimeFormat Element, Prev: SPV Detail stringFormat Element, Up: SPV Detail setFormat Element 1056 1057D.4.10.3 The 'dateTimeFormat' Element 1058..................................... 1059 1060 dateTimeFormat 1061 :baseFormat[dt_base_format]=(date | time | dateTime) 1062 :separatorChars? 1063 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)? 1064 :showYear=bool? 1065 :yearAbbreviation=bool? 1066 :showQuarter=bool? 1067 :quarterPrefix? 1068 :quarterSuffix? 1069 :showMonth=bool? 1070 :monthFormat=(long | short | number | paddedNumber)? 1071 :showWeek=bool? 1072 :weekPadding=bool? 1073 :weekSuffix? 1074 :showDayOfWeek=bool? 1075 :dayOfWeekAbbreviation=bool? 1076 :dayPadding=bool? 1077 :dayOfMonthPadding=bool? 1078 :hourPadding=bool? 1079 :minutePadding=bool? 1080 :secondPadding=bool? 1081 :showDay=bool? 1082 :showHour=bool? 1083 :showMinute=bool? 1084 :showSecond=bool? 1085 :showMillis=bool? 1086 :dayType=(month | year)? 1087 :hourFormat=(AMPM | AS_24 | AS_12)? 1088 => affix* 1089 1090 This element appears only in schema version 2.5 and earlier (*note 1091SPV Detail visualization Element::). 1092 1093 Data to be formatted in date formats is stored as strings in legacy 1094data, in the format 'yyyy-mm-ddTHH:MM:SS.SSS' and must be parsed and 1095reformatted by the reader. 1096 1097 The following attribute is required. 1098 1099 -- Attribute: baseFormat 1100 Specifies whether a date and time are both to be displayed, or just 1101 one of them. 1102 1103 Many of the attributes' meanings are obvious. The following seem to 1104be worth documenting. 1105 1106 -- Attribute: separatorChars 1107 Exactly four characters. In order, these are used for: decimal 1108 point, grouping, date separator, time separator. Always '.,-:'. 1109 1110 -- Attribute: mdyOrder 1111 Within a date, the order of the days, months, and years. 1112 'dayMonthYear' is the only observed value, but one would expect 1113 that 'monthDayYear' and 'yearMonthDay' to be reasonable as well. 1114 1115 -- Attribute: showYear 1116 -- Attribute: yearAbbreviation 1117 Whether to include the year and, if so, whether the year should be 1118 shown abbreviated, that is, with only 2 digits. Each is 'true' or 1119 'false'; only values of 'true' and 'false', respectively, have been 1120 observed. 1121 1122 -- Attribute: showMonth 1123 -- Attribute: monthFormat 1124 Whether to include the month ('true' or 'false') and, if so, how to 1125 format it. 'monthFormat' is one of the following: 1126 1127 'long' 1128 The full name of the month, e.g. in an English locale, 1129 'September'. 1130 1131 'short' 1132 The abbreviated name of the month, e.g. in an English locale, 1133 'Sep'. 1134 1135 'number' 1136 The number representing the month, e.g. 9 for September. 1137 1138 'paddedNumber' 1139 A two-digit number representing the month, e.g. 09 for 1140 September. 1141 1142 Only values of 'true' and 'short', respectively, have been 1143 observed. 1144 1145 -- Attribute: dayType 1146 This attribute is always 'month' in the corpus, specifying that the 1147 day of the month is to be displayed; a value of 'year' is supposed 1148 to indicate that the day of the year, where 1 is January 1, is to 1149 be displayed instead. 1150 1151 -- Attribute: hourFormat 1152 'hourFormat', if present, is one of: 1153 1154 'AMPM' 1155 The time is displayed with an 'am' or 'pm' suffix, e.g. 1156 '10:15pm'. 1157 1158 'AS_24' 1159 The time is displayed in a 24-hour format, e.g. '22:15'. 1160 1161 This is the only value observed in the corpus. 1162 1163 'AS_12' 1164 The time is displayed in a 12-hour format, without 1165 distinguishing morning or evening, e.g. '10;15'. 1166 1167 'hourFormat' is sometimes present for 'elapsedTime' formats, which 1168 is confusing since a time duration does not have a concept of AM or 1169 PM. This might indicate a bug in the code that generated the XML in 1170 the corpus, or it might indicate that 'elapsedTime' is sometimes 1171 used to format a time of day. 1172 1173 For a 'baseFormat' of 'date', PSPP chooses a print format type based 1174on the following rules: 1175 1176 1. If 'showQuarter' is true: 'QYR'. 1177 1178 2. Otherwise, if 'showWeek' is true: 'WKYR'. 1179 1180 3. Otherwise, if 'mdyOrder' is 'dayMonthYear': 1181 1182 a. If 'monthFormat' is 'number' or 'paddedNumber': 'EDATE'. 1183 1184 b. Otherwise: 'DATE'. 1185 1186 4. Otherwise, if 'mdyOrder' is 'yearMonthDay': 'SDATE'. 1187 1188 5. Otherwise, 'ADATE'. 1189 1190 For a 'baseFormat' of 'dateTime', PSPP uses 'YMDHMS' if 'mdyOrder' is 1191'yearMonthDay' and 'DATETIME' otherwise. For a 'baseFormat' of 'time', 1192PSPP uses 'DTIME' if 'showDay' is true, otherwise 'TIME' if 'showHour' 1193is true, otherwise 'MTIME'. 1194 1195 For a 'baseFormat' of 'date', the chosen width is the minimum for the 1196format type, adding 2 if 'yearAbbreviation' is false or omitted. For 1197other base formats, the chosen width is the minimum for its type, plus 3 1198if 'showSecond' is true, plus 4 more if 'showMillis' is also true. 1199Decimals are 0 by default, or 3 if 'showMillis' is true. 1200 1201 1202File: pspp-dev.info, Node: SPV Detail elapsedTimeFormat Element, Next: SPV Detail format Element, Prev: SPV Detail dateTimeFormat Element, Up: SPV Detail setFormat Element 1203 1204D.4.10.4 The 'elapsedTimeFormat' Element 1205........................................ 1206 1207 elapsedTimeFormat 1208 :baseFormat[dt_base_format]=(date | time | dateTime) 1209 :dayPadding=bool? 1210 :hourPadding=bool? 1211 :minutePadding=bool? 1212 :secondPadding=bool? 1213 :showYear=bool? 1214 :showDay=bool? 1215 :showHour=bool? 1216 :showMinute=bool? 1217 :showSecond=bool? 1218 :showMillis=bool? 1219 => affix* 1220 1221 This element specifies the way to display a time duration. 1222 1223 Data to be formatted in elapsed time formats is stored as strings in 1224legacy data, in the format 'H:MM:SS.SSS', with additional hour digits as 1225needed for long durations, and must be parsed and reformatted by the 1226reader. 1227 1228 The following attribute is required. 1229 1230 -- Attribute: baseFormat 1231 Specifies whether a day and a time are both to be displayed, or 1232 just one of them. 1233 1234 The remaining attributes specify exactly how to display the elapsed 1235time. 1236 1237 For 'baseFormat' of 'time', PSPP converts this element to print 1238format type 'DTIME'; otherwise, if 'showHour' is true, to 'TIME'; 1239otherwise, to 'MTIME'. The chosen width is the minimum for the chosen 1240type, adding 3 if 'showSecond' is true, adding 4 more if 'showMillis' is 1241also true. Decimals are 0 by default, or 3 if 'showMillis' is true. 1242 1243 1244File: pspp-dev.info, Node: SPV Detail format Element, Next: SPV Detail affix Element, Prev: SPV Detail elapsedTimeFormat Element, Up: SPV Detail setFormat Element 1245 1246D.4.10.5 The 'format' Element 1247............................. 1248 1249 format 1250 :baseFormat[f_base_format]=(date | time | dateTime | elapsedTime)? 1251 :errorCharacter? 1252 :separatorChars? 1253 :mdyOrder=(dayMonthYear | monthDayYear | yearMonthDay)? 1254 :showYear=bool? 1255 :showQuarter=bool? 1256 :quarterPrefix? 1257 :quarterSuffix? 1258 :yearAbbreviation=bool? 1259 :showMonth=bool? 1260 :monthFormat=(long | short | number | paddedNumber)? 1261 :dayPadding=bool? 1262 :dayOfMonthPadding=bool? 1263 :showWeek=bool? 1264 :weekPadding=bool? 1265 :weekSuffix? 1266 :showDayOfWeek=bool? 1267 :dayOfWeekAbbreviation=bool? 1268 :hourPadding=bool? 1269 :minutePadding=bool? 1270 :secondPadding=bool? 1271 :showDay=bool? 1272 :showHour=bool? 1273 :showMinute=bool? 1274 :showSecond=bool? 1275 :showMillis=bool? 1276 :dayType=(month | year)? 1277 :hourFormat=(AMPM | AS_24 | AS_12)? 1278 :minimumIntegerDigits=int? 1279 :maximumFractionDigits=int? 1280 :minimumFractionDigits=int? 1281 :useGrouping=bool? 1282 :scientific=(onlyForSmall | whenNeeded | true | false)? 1283 :small=real? 1284 :prefix? 1285 :suffix? 1286 :tryStringsAsNumbers=bool? 1287 :negativesOutside=bool? 1288 => relabel* affix* 1289 1290 This element is the union of all of the more-specific format 1291elements. It is interpreted in the same way as one of those format 1292elements, using 'baseFormat' to determine which kind of format to use. 1293 1294 There are a few attributes not present in the more specific formats: 1295 1296 -- Attribute: tryStringsAsNumbers 1297 When this is 'true', it is supposed to indicate that string values 1298 should be parsed as numbers and then displayed according to numeric 1299 formatting rules. However, in the corpus it is always 'false'. 1300 1301 -- Attribute: negativesOutside 1302 If true, the negative sign should be shown before the prefix; if 1303 false, it should be shown after. 1304 1305 1306File: pspp-dev.info, Node: SPV Detail affix Element, Prev: SPV Detail format Element, Up: SPV Detail setFormat Element 1307 1308D.4.10.6 The 'affix' Element 1309............................ 1310 1311 affix 1312 :definesReference=int 1313 :position=(subscript | superscript) 1314 :suffix=bool 1315 :value 1316 => EMPTY 1317 1318 This defines a suffix (or, theoretically, a prefix) for a formatted 1319value. It is used to insert a reference to a footnote. It has the 1320following attributes: 1321 1322 -- Attribute: definesReference 1323 This specifies the footnote number as a natural number: 1 for the 1324 first footnote, 2 for the second, and so on. 1325 1326 -- Attribute: position 1327 Position for the footnote label. Always 'superscript'. 1328 1329 -- Attribute: suffix 1330 Whether the affix is a suffix ('true') or a prefix ('false'). 1331 Always 'true'. 1332 1333 -- Attribute: value 1334 The text of the suffix or prefix. Typically a letter, e.g. 'a' for 1335 footnote 1, 'b' for footnote 2, ... The corpus contains other 1336 values: '*', '**', and a few that begin with at least one comma: 1337 ',b', ',c', ',,b', and ',,c'. 1338 1339 1340File: 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 1341 1342D.4.11 The 'interval' Element 1343----------------------------- 1344 1345 interval :style=ref style => labeling footnotes? 1346 1347 labeling 1348 :style=ref style? 1349 :variable=ref (sourceVariable | derivedVariable) 1350 => (formatting | format | footnotes)* 1351 1352 formatting :variable=ref (sourceVariable | derivedVariable) => formatMapping* 1353 1354 formatMapping :from=int => format? 1355 1356 footnotes 1357 :superscript=bool? 1358 :variable=ref (sourceVariable | derivedVariable) 1359 => footnoteMapping* 1360 1361 footnoteMapping :definesReference=int :from=int :to => EMPTY 1362 1363 The 'interval' element and its descendants determine the basic 1364formatting and labeling for the table's cells. These basic styles are 1365overridden by more specific styles set using 'setCellProperties' (*note 1366SPV Detail setCellProperties Element::). 1367 1368 The 'style' attribute of 'interval' itself may be ignored. 1369 1370 The 'labeling' element may have a single 'formatting' child. If 1371present, its 'variable' attribute refers to a variable whose values are 1372format specifiers as numbers, e.g. value 0x050802 for F8.2. However, 1373the numbers are not actually interpreted that way. Instead, each number 1374actually present in the variable's data is mapped by a 'formatMapping' 1375child of 'formatting' to a 'format' that specifies how to display it. 1376 1377 The 'labeling' element may also have a 'footnotes' child element. 1378The 'variable' attribute of this element refers to a variable whose 1379values are comma-delimited strings that list the 1-based indexes of 1380footnote references. (Cells without any footnote references are numeric 13810 instead of strings.) 1382 1383 Each 'footnoteMapping' child of the 'footnotes' element defines the 1384footnote marker to be its 'to' attribute text for the footnote whose 13851-based index is given in its 'definesReference' attribute. 1386 1387 1388File: 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 1389 1390D.4.12 The 'style' Element 1391-------------------------- 1392 1393 style 1394 :color=color? 1395 :color2=color? 1396 :labelAngle=real? 1397 :border-bottom=(solid | thick | thin | double | none)? 1398 :border-top=(solid | thick | thin | double | none)? 1399 :border-left=(solid | thick | thin | double | none)? 1400 :border-right=(solid | thick | thin | double | none)? 1401 :border-bottom-color? 1402 :border-top-color? 1403 :border-left-color? 1404 :border-right-color? 1405 :font-family? 1406 :font-size? 1407 :font-weight=(regular | bold)? 1408 :font-style=(regular | italic)? 1409 :font-underline=(none | underline)? 1410 :margin-bottom=dimension? 1411 :margin-left=dimension? 1412 :margin-right=dimension? 1413 :margin-top=dimension? 1414 :textAlignment=(left | right | center | decimal | mixed)? 1415 :labelLocationHorizontal=(positive | negative | center)? 1416 :labelLocationVertical=(positive | negative | center)? 1417 :decimal-offset=dimension? 1418 :size? 1419 :width? 1420 :visible=bool? 1421 => EMPTY 1422 1423 A 'style' element has an effect only when it is referenced by another 1424element to set some aspect of the table's style. Most of the attributes 1425are self-explanatory. The rest are described below. 1426 1427 -- Attribute: color 1428 In some cases, the text color; in others, the background color. 1429 1430 -- Attribute: color2 1431 Not used. 1432 1433 -- Attribute: labelAngle 1434 Normally 0. The value -90 causes inner column or outer row labels 1435 to be rotated vertically. 1436 1437 -- Attribute: labelLocationHorizontal 1438 Not used. 1439 1440 -- Attribute: labelLocationVertical 1441 The value 'positive' corresponds to vertically aligning text to the 1442 top of a cell, 'negative' to the bottom, 'center' to the middle. 1443 1444 1445File: 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 1446 1447D.4.13 The 'labelFrame' Element 1448------------------------------- 1449 1450 labelFrame :style=ref style => location+ label? paragraph? 1451 1452 paragraph :hangingIndent=dimension? => EMPTY 1453 1454 A 'labelFrame' element specifies content and style for some aspect of 1455a table. Only 'labelFrame' elements that have a 'label' child are 1456important. The 'purpose' attribute in the 'label' determines what the 1457'labelFrame' affects: 1458 1459'title' 1460 The table's title and its style. 1461 1462'subTitle' 1463 The table's caption and its style. 1464 1465'footnote' 1466 The table's footnotes and the style for the footer area. 1467 1468'layer' 1469 The style for the layer area. 1470 1471'subSubTitle' 1472 Ignored. 1473 1474 The 'style' attribute references the style to use for the area. 1475 1476 The 'label', if present, specifies the text to put into the title or 1477caption or footnotes. For footnotes, the label has two 'text' children 1478for every footnote, each of which has a 'usesReference' attribute 1479identifying the 1-based index of a footnote. The first, third, fifth, 1480... 'text' child specifies the content for a footnote; the second, 1481fourth, sixth, ... child specifies the marker. Content tends to end in 1482a new-line, which the reader may wish to trim; similarly, markers tend 1483to end in '.'. 1484 1485 The 'paragraph', if present, may be ignored, since it is always 1486empty. 1487 1488 1489File: pspp-dev.info, Node: SPV Detail Legacy Properties, Prev: SPV Detail labelFrame Element, Up: SPV Legacy Detail Member XML Format 1490 1491D.4.14 Legacy Properties 1492------------------------ 1493 1494The detail XML format has features for styling most of the aspects of a 1495table. It also inherits defaults for many aspects from structure XML, 1496which has the following 'tableProperties' element: 1497 1498 tableProperties 1499 => generalProperties footnoteProperties cellFormatProperties borderProperties printingProperties 1500 1501 generalProperties 1502 :hideEmptyRows=bool? 1503 :maximumColumnWidth=dimension? 1504 :maximumRowWidth=dimension? 1505 :minimumColumnWidth=dimension? 1506 :minimumRowWidth=dimension? 1507 :rowDimensionLabels=(inCorner | nested)? 1508 => EMPTY 1509 1510 footnoteProperties 1511 :markerPosition=(superscript | subscript)? 1512 :numberFormat=(alphabetic | numeric)? 1513 => EMPTY 1514 1515 cellFormatProperties => cell_style+ 1516 1517 any[cell_style] 1518 :alternatingColor=color? 1519 :alternatingTextColor=color? 1520 => style 1521 1522 style 1523 :color=color? 1524 :color2=color? 1525 :font-family? 1526 :font-size? 1527 :font-style=(regular | italic)? 1528 :font-weight=(regular | bold)? 1529 :labelLocationVertical=(positive | negative | center)? 1530 :margin-bottom=dimension? 1531 :margin-left=dimension? 1532 :margin-right=dimension? 1533 :margin-top=dimension? 1534 :textAlignment=(left | right | center | decimal | mixed)? 1535 :decimal-offset=dimension? 1536 => EMPTY 1537 1538 borderProperties => border_style+ 1539 1540 any[border_style] 1541 :borderStyleType=(none | solid | dashed | thick | thin | double)? 1542 :color=color? 1543 => EMPTY 1544 1545 printingProperties 1546 :printAllLayers=bool? 1547 :rescaleLongTableToFitPage=bool? 1548 :rescaleWideTableToFitPage=bool? 1549 :windowOrphanLines=int? 1550 :continuationText? 1551 :continuationTextAtBottom=bool? 1552 :continuationTextAtTop=bool? 1553 :printEachLayerOnSeparatePage=bool? 1554 => EMPTY 1555 1556 1557File: pspp-dev.info, Node: Encrypted File Wrappers, Next: q2c Input Format, Prev: SPSS Viewer File Format, Up: Top 1558 1559E Encrypted File Wrappers 1560************************* 1561 1562SPSS 21 and later can package multiple kinds of files inside an 1563encrypted wrapper. The wrapper has a common format, regardless of the 1564kind of the file that it contains. 1565 1566 Warning: The SPSS encryption wrapper is poorly designed. When the 1567 password is unknown, it is much cheaper and faster to decrypt a 1568 file encrypted this way than if a well designed alternative were 1569 used. If you must use this format, use a 10-byte randomly 1570 generated password. 1571 1572* Menu: 1573 1574* Common Wrapper Format:: 1575* Password Encoding:: 1576 1577 1578File: pspp-dev.info, Node: Common Wrapper Format, Next: Password Encoding, Up: Encrypted File Wrappers 1579 1580E.1 Common Wrapper Format 1581========================= 1582 1583An encrypted file wrapper begins with the following 36-byte header, 1584where xxx identifies the type of file encapsulated: 'SAV' for a system 1585file, 'SPS' for a syntax file, 'SPV' for a viewer file. PSPP code for 1586identifying these files just checks for the 'ENCRYPTED' keyword at 1587offset 8, but the other bytes are also fixed in practice: 1588 1589 0000 1c 00 00 00 00 00 00 00 45 4e 43 52 59 50 54 45 |........ENCRYPTE| 1590 0010 44 xx xx xx 15 00 00 00 00 00 00 00 00 00 00 00 |Dxxx............| 1591 0020 00 00 00 00 |....| 1592 1593 Following the fixed header is essentially the regular contents of the 1594encapsulated file in its usual format, with each 16-byte block encrypted 1595with AES-256 in ECB mode. 1596 1597 To make the plaintext an even multiple of 16 bytes in length, the 1598encryption process appends PKCS #7 padding, as specified in RFC 5652 1599section 6.3. Padding appends 1 to 16 bytes to the plaintext, in which 1600each byte of padding is the number of padding bytes added. If the 1601plaintext is, for example, 2 bytes short of a multiple of 16, the 1602padding is 2 bytes with value 02; if the plaintext is a multiple of 16 1603bytes in length, the padding is 16 bytes with value 0x10. 1604 1605 The AES-256 key is derived from a password in the following way: 1606 1607 1. Start from the literal password typed by the user. Truncate it to 1608 at most 10 bytes, then append as many null bytes as necessary until 1609 there are exactly 32 bytes. Call this PASSWORD. 1610 1611 2. Let CONSTANT be the following 73-byte constant: 1612 1613 0000 00 00 00 01 35 27 13 cc 53 a7 78 89 87 53 22 11 1614 0010 d6 5b 31 58 dc fe 2e 7e 94 da 2f 00 cc 15 71 80 1615 0020 0a 6c 63 53 00 38 c3 38 ac 22 f3 63 62 0e ce 85 1616 0030 3f b8 07 4c 4e 2b 77 c7 21 f5 1a 80 1d 67 fb e1 1617 0040 e1 83 07 d8 0d 00 00 01 00 1618 1619 3. Compute CMAC-AES-256(PASSWORD, CONSTANT). Call the 16-byte result 1620 CMAC. 1621 1622 4. The 32-byte AES-256 key is CMAC || CMAC, that is, CMAC repeated 1623 twice. 1624 1625Example 1626------- 1627 1628Consider the password 'pspp'. PASSWORD is: 1629 1630 0000 70 73 70 70 00 00 00 00 00 00 00 00 00 00 00 00 |pspp............| 1631 0010 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 |................| 1632 1633CMAC is: 1634 1635 0000 3e da 09 8e 66 04 d4 fd f9 63 0c 2c a8 6f b0 45 1636 1637The AES-256 key is: 1638 1639 0000 3e da 09 8e 66 04 d4 fd f9 63 0c 2c a8 6f b0 45 1640 0010 3e da 09 8e 66 04 d4 fd f9 63 0c 2c a8 6f b0 45 1641 1642* Menu: 1643 1644* Checking Passwords:: 1645 1646 1647File: pspp-dev.info, Node: Checking Passwords, Up: Common Wrapper Format 1648 1649E.1.1 Checking Passwords 1650------------------------ 1651 1652A program reading an encrypted file may wish to verify that the password 1653it was given is the correct one. One way is to verify that the PKCS #7 1654padding at the end of the file is well formed. However, any plaintext 1655that ends in byte 01 is well formed PKCS #7, meaning that about 1 in 256 1656keys will falsely pass this test. This might be acceptable for 1657interactive use, but the false positive rate is too high for a 1658brute-force search of the password space. 1659 1660 A better test requires some knowledge of the file format being 1661wrapped, to obtain a "magic number" for the beginning of the file. 1662 1663 * The plaintext of system files begins with '$FL2@(#)' or '$FL3@(#)'. 1664 1665 * Before encryption, a syntax file is prefixed with a line at the 1666 beginning of the form '* Encoding: ENCODING.', where ENCODING is 1667 the encoding used for the rest of the file, e.g. 'windows-1252'. 1668 Thus, '* Encoding' may be used as a magic number for system files. 1669 1670 * The plaintext of viewer files begins with 50 4b 03 04 14 00 08 (50 1671 4b is 'PK'). 1672 1673 1674File: pspp-dev.info, Node: Password Encoding, Prev: Common Wrapper Format, Up: Encrypted File Wrappers 1675 1676E.2 Password Encoding 1677===================== 1678 1679SPSS also supports what it calls "encrypted passwords." These are not 1680encrypted. They are encoded with a simple, fixed scheme. An encoded 1681password is always a multiple of 2 characters long, and never longer 1682than 20 characters. The characters in an encoded password are always in 1683the graphic ASCII range 33 through 126. Each successive pair of 1684characters in the password encodes a single byte in the plaintext 1685password. 1686 1687 Use the following algorithm to decode a pair of characters: 1688 1689 1. Let A be the ASCII code of the first character, and B be the ASCII 1690 code of the second character. 1691 1692 2. Let AH be the most significant 4 bits of A. Find the line in the 1693 table below that has AH on the left side. The right side of the 1694 line is a set of possible values for the most significant 4 bits of 1695 the decoded byte. 1696 1697 2 => 2367 1698 3 => 0145 1699 47 => 89cd 1700 56 => abef 1701 1702 3. Let BH be the most significant 4 bits of B. Find the line in the 1703 second table below that has BH on the left side. The right side of 1704 the line is a set of possible values for the most significant 4 1705 bits of the decoded byte. Together with the results of the 1706 previous step, only a single possibility is left. 1707 1708 2 => 139b 1709 3 => 028a 1710 47 => 46ce 1711 56 => 57df 1712 1713 4. Let AL be the least significant 4 bits of A. Find the line in the 1714 table below that has AL on the left side. The right side of the 1715 line is a set of possible values for the least significant 4 bits 1716 of the decoded byte. 1717 1718 03cf => 0145 1719 12de => 2367 1720 478b => 89cd 1721 569a => abef 1722 1723 5. Let BL be the least significant 4 bits of B. Find the line in the 1724 table below that has BL on the left side. The right side of the 1725 line is a set of possible values for the least significant 4 bits 1726 of the decoded byte. Together with the results of the previous 1727 step, only a single possibility is left. 1728 1729 03cf => 028a 1730 12de => 139b 1731 478b => 46ce 1732 569a => 57df 1733 1734Example 1735------- 1736 1737Consider the encoded character pair '-|'. A is 0x2d and B is 0x7c, so 1738AH is 2, BH is 7, AL is 0xd, and BL is 0xc. AH means that the most 1739significant four bits of the decoded character is 2, 3, 6, or 7, and BH 1740means that they are 4, 6, 0xc, or 0xe. The single possibility in common 1741is 6, so the most significant four bits are 6. Similarly, AL means that 1742the least significant four bits are 2, 3, 6, or 7, and BL means they are 17430, 2, 8, or 0xa, so the least significant four bits are 2. The decoded 1744character is therefore 0x62, the letter 'b'. 1745 1746 1747File: pspp-dev.info, Node: q2c Input Format, Next: GNU Free Documentation License, Prev: Encrypted File Wrappers, Up: Top 1748 1749Appendix F 'q2c' Input Format 1750***************************** 1751 1752PSPP statistical procedures have a bizarre and somewhat irregular 1753syntax. Despite this, a parser generator has been written that 1754adequately addresses many of the possibilities and tries to provide 1755hooks for the exceptional cases. This parser generator is named 'q2c'. 1756 1757* Menu: 1758 1759* Invoking q2c:: q2c command-line syntax. 1760* q2c Input Structure:: High-level layout of the input file. 1761* Grammar Rules:: Syntax of the grammar rules. 1762 1763 1764File: pspp-dev.info, Node: Invoking q2c, Next: q2c Input Structure, Up: q2c Input Format 1765 1766F.1 Invoking q2c 1767================ 1768 1769 q2c INPUT.Q OUTPUT.C 1770 1771 'q2c' translates a '.q' file into a '.c' file. It takes exactly two 1772command-line arguments, which are the input file name and output file 1773name, respectively. 'q2c' does not accept any command-line options. 1774 1775 1776File: pspp-dev.info, Node: q2c Input Structure, Next: Grammar Rules, Prev: Invoking q2c, Up: q2c Input Format 1777 1778F.2 'q2c' Input Structure 1779========================= 1780 1781'q2c' input files are divided into two sections: the grammar rules and 1782the supporting code. The "grammar rules", which make up the first part 1783of the input, are used to define the syntax of the statistical procedure 1784to be parsed. The "supporting code", following the grammar rules, are 1785copied largely unchanged to the output file, except for certain escapes. 1786 1787 The most important lines in the grammar rules are used for defining 1788procedure syntax. These lines can be prefixed with a dollar sign ('$'), 1789which prevents Emacs' CC-mode from munging them. Besides this, a bang 1790('!') at the beginning of a line causes the line, minus the bang, to be 1791written verbatim to the output file (useful for comments). As a third 1792special case, any line that begins with the exact characters '/* 1793*INDENT' is ignored and not written to the output. This allows '.q' 1794files to be processed through 'indent' without being munged. 1795 1796 The syntax of the grammar rules themselves is given in the following 1797sections. 1798 1799 The supporting code is passed into the output file largely unchanged. 1800However, the following escapes are supported. Each escape must appear 1801on a line by itself. 1802 1803'/* (header) */' 1804 1805 Expands to a series of C '#include' directives which include the 1806 headers that are required for the parser generated by 'q2c'. 1807 1808'/* (decls SCOPE) */' 1809 1810 Expands to C variable and data type declarations for the variables 1811 and 'enum's input and output by the 'q2c' parser. SCOPE must be 1812 either 'local' or 'global'. 'local' causes the declarations to be 1813 output as function locals. 'global' causes them to be declared as 1814 'static' module variables; thus, 'global' is a bit of a misnomer. 1815 1816'/* (parser) */' 1817 1818 Expands to the entire parser. Must be enclosed within a C 1819 function. 1820 1821'/* (free) */' 1822 1823 Expands to a set of calls to the 'free' function for variables 1824 declared by the parser. Only needs to be invoked if subcommands of 1825 type 'string' are used in the grammar rules. 1826 1827 1828File: pspp-dev.info, Node: Grammar Rules, Prev: q2c Input Structure, Up: q2c Input Format 1829 1830F.3 Grammar Rules 1831================= 1832 1833The grammar rules describe the format of the syntax that the parser 1834generated by 'q2c' will understand. The way that the grammar rules are 1835included in 'q2c' input file are described above. 1836 1837 The grammar rules are divided into tokens of the following types: 1838 1839Identifier ('ID') 1840 1841 An identifier token is a sequence of letters, digits, and 1842 underscores ('_'). Identifiers are _not_ case-sensitive. 1843 1844String ('STRING') 1845 1846 String tokens are initiated by a double-quote character ('"') and 1847 consist of all the characters between that double quote and the 1848 next double quote, which must be on the same line as the first. 1849 Within a string, a backslash can be used as a "literal escape". 1850 The only reasons to use a literal escape are to include a double 1851 quote or a backslash within a string. 1852 1853Special character 1854 1855 Other characters, other than white space, constitute tokens in 1856 themselves. 1857 1858 The syntax of the grammar rules is as follows: 1859 1860 grammar-rules ::= command-name opt-prefix : subcommands . 1861 command-name ::= ID 1862 ::= STRING 1863 opt-prefix ::= 1864 ::= ( ID ) 1865 subcommands ::= subcommand 1866 ::= subcommands ; subcommand 1867 1868 The syntax begins with an ID token that gives the name of the 1869procedure to be parsed. For command names that contain multiple words, 1870a STRING token may be used instead, e.g. '"FILE HANDLE"'. Optionally, 1871an ID in parentheses specifies a prefix used for all file-scope 1872identifiers declared by the emitted code. 1873 1874 The rest of the syntax consists of subcommands separated by 1875semicolons (';') and terminated with a full stop ('.'). 1876 1877 subcommand ::= default-opt arity-opt ID sbc-defn 1878 default-opt ::= 1879 ::= * 1880 arity-opt ::= 1881 ::= + 1882 ::= ^ 1883 sbc-defn ::= opt-prefix = specifiers 1884 ::= [ ID ] = array-sbc 1885 ::= opt-prefix = sbc-special-form 1886 1887 A subcommand that begins with an asterisk ('*') is the default 1888subcommand. The keyword used for the default subcommand can be omitted 1889in the PSPP syntax file. 1890 1891 A plus sign ('+') indicates that a subcommand can appear more than 1892once. A caret ('^') indicate that a subcommand must appear exactly 1893once. A subcommand marked with neither character may appear once or not 1894at all, but not more than once. 1895 1896 The subcommand name appears after the leading option characters. 1897 1898 There are three forms of subcommands. The first and most common form 1899simply gives an equals sign ('=') and a list of specifiers, which can 1900each be set to a single setting. The second form declares an array, 1901which is a set of flags that can be individually turned on by the user. 1902There are also several special forms that do not take a list of 1903specifiers. 1904 1905 Arrays require an additional 'ID' argument. This is used as a 1906prefix, prepended to the variable names constructed from the specifiers. 1907The other forms also allow an optional prefix to be specified. 1908 1909 array-sbc ::= alternatives 1910 ::= array-sbc , alternatives 1911 alternatives ::= ID 1912 ::= alternatives | ID 1913 1914 An array subcommand is a set of Boolean values that can independently 1915be turned on by the user, listed separated by commas (','). If an value 1916has more than one name then these names are separated by pipes ('|'). 1917 1918 specifiers ::= specifier 1919 ::= specifiers , specifier 1920 specifier ::= opt-id : settings 1921 opt-id ::= 1922 ::= ID 1923 1924 Ordinary subcommands (other than arrays and special forms) require a 1925list of specifiers. Each specifier has an optional name and a list of 1926settings. If the name is given then a correspondingly named variable 1927will be used to store the user's choice of setting. If no name is given 1928then there is no way to tell which setting the user picked; in this case 1929the settings should probably have values attached. 1930 1931 settings ::= setting 1932 ::= settings / setting 1933 setting ::= setting-options ID setting-value 1934 setting-options ::= 1935 ::= * 1936 ::= ! 1937 ::= * ! 1938 1939 Individual settings are separated by forward slashes ('/'). Each 1940setting can be as little as an 'ID' token, but options and values can 1941optionally be included. The '*' option means that, for this setting, 1942the 'ID' can be omitted. The '!' option means that this option is the 1943default for its specifier. 1944 1945 setting-value ::= 1946 ::= ( setting-value-2 ) 1947 ::= setting-value-2 1948 setting-value-2 ::= setting-value-options setting-value-type : ID 1949 setting-value-options ::= 1950 ::= * 1951 setting-value-type ::= N 1952 ::= D 1953 ::= S 1954 1955 Settings may have values. If the value must be enclosed in 1956parentheses, then enclose the value declaration in parentheses. Declare 1957the setting type as 'n', 'd', or 's' for integer, floating-point, or 1958string type, respectively. The given 'ID' is used to construct a 1959variable name. If option '*' is given, then the value is optional; 1960otherwise it must be specified whenever the corresponding setting is 1961specified. 1962 1963 sbc-special-form ::= VAR 1964 ::= VARLIST varlist-options 1965 ::= INTEGER opt-list 1966 ::= DOUBLE opt-list 1967 ::= PINT 1968 ::= STRING (the literal word STRING) 1969 ::= CUSTOM 1970 varlist-options ::= 1971 ::= ( STRING ) 1972 opt-list ::= 1973 ::= LIST 1974 1975 The special forms are of the following types: 1976 1977'VAR' 1978 1979 A single variable name. 1980 1981'VARLIST' 1982 1983 A list of variables. If given, the string can be used to provide 1984 'PV_*' options to the call to 'parse_variables'. 1985 1986'INTEGER' 1987 1988 A single integer value. 1989 1990'INTEGER LIST' 1991 1992 A list of integers separated by spaces or commas. 1993 1994'DOUBLE' 1995 1996 A single floating-point value. 1997 1998'DOUBLE LIST' 1999 2000 A list of floating-point values. 2001 2002'PINT' 2003 2004 A single positive integer value. 2005 2006'STRING' 2007 2008 A string value. 2009 2010'CUSTOM' 2011 2012 A custom function is used to parse this subcommand. The function 2013 must have prototype 'int custom_NAME (void)'. It should return 0 2014 on failure (when it has already issued an appropriate diagnostic), 2015 1 on success, or 2 if it fails and the calling function should 2016 issue a syntax error on behalf of the custom handler. 2017 2018 2019File: pspp-dev.info, Node: GNU Free Documentation License, Prev: q2c Input Format, Up: Top 2020 2021Appendix G GNU Free Documentation License 2022***************************************** 2023 2024 Version 1.3, 3 November 2008 2025 2026 Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. 2027 <http://fsf.org/> 2028 2029 Everyone is permitted to copy and distribute verbatim copies 2030 of this license document, but changing it is not allowed. 2031 2032 0. PREAMBLE 2033 2034 The purpose of this License is to make a manual, textbook, or other 2035 functional and useful document "free" in the sense of freedom: to 2036 assure everyone the effective freedom to copy and redistribute it, 2037 with or without modifying it, either commercially or 2038 noncommercially. Secondarily, this License preserves for the 2039 author and publisher a way to get credit for their work, while not 2040 being considered responsible for modifications made by others. 2041 2042 This License is a kind of "copyleft", which means that derivative 2043 works of the document must themselves be free in the same sense. 2044 It complements the GNU General Public License, which is a copyleft 2045 license designed for free software. 2046 2047 We have designed this License in order to use it for manuals for 2048 free software, because free software needs free documentation: a 2049 free program should come with manuals providing the same freedoms 2050 that the software does. But this License is not limited to 2051 software manuals; it can be used for any textual work, regardless 2052 of subject matter or whether it is published as a printed book. We 2053 recommend this License principally for works whose purpose is 2054 instruction or reference. 2055 2056 1. APPLICABILITY AND DEFINITIONS 2057 2058 This License applies to any manual or other work, in any medium, 2059 that contains a notice placed by the copyright holder saying it can 2060 be distributed under the terms of this License. Such a notice 2061 grants a world-wide, royalty-free license, unlimited in duration, 2062 to use that work under the conditions stated herein. The 2063 "Document", below, refers to any such manual or work. Any member 2064 of the public is a licensee, and is addressed as "you". You accept 2065 the license if you copy, modify or distribute the work in a way 2066 requiring permission under copyright law. 2067 2068 A "Modified Version" of the Document means any work containing the 2069 Document or a portion of it, either copied verbatim, or with 2070 modifications and/or translated into another language. 2071 2072 A "Secondary Section" is a named appendix or a front-matter section 2073 of the Document that deals exclusively with the relationship of the 2074 publishers or authors of the Document to the Document's overall 2075 subject (or to related matters) and contains nothing that could 2076 fall directly within that overall subject. (Thus, if the Document 2077 is in part a textbook of mathematics, a Secondary Section may not 2078 explain any mathematics.) The relationship could be a matter of 2079 historical connection with the subject or with related matters, or 2080 of legal, commercial, philosophical, ethical or political position 2081 regarding them. 2082 2083 The "Invariant Sections" are certain Secondary Sections whose 2084 titles are designated, as being those of Invariant Sections, in the 2085 notice that says that the Document is released under this License. 2086 If a section does not fit the above definition of Secondary then it 2087 is not allowed to be designated as Invariant. The Document may 2088 contain zero Invariant Sections. If the Document does not identify 2089 any Invariant Sections then there are none. 2090 2091 The "Cover Texts" are certain short passages of text that are 2092 listed, as Front-Cover Texts or Back-Cover Texts, in the notice 2093 that says that the Document is released under this License. A 2094 Front-Cover Text may be at most 5 words, and a Back-Cover Text may 2095 be at most 25 words. 2096 2097 A "Transparent" copy of the Document means a machine-readable copy, 2098 represented in a format whose specification is available to the 2099 general public, that is suitable for revising the document 2100 straightforwardly with generic text editors or (for images composed 2101 of pixels) generic paint programs or (for drawings) some widely 2102 available drawing editor, and that is suitable for input to text 2103 formatters or for automatic translation to a variety of formats 2104 suitable for input to text formatters. A copy made in an otherwise 2105 Transparent file format whose markup, or absence of markup, has 2106 been arranged to thwart or discourage subsequent modification by 2107 readers is not Transparent. An image format is not Transparent if 2108 used for any substantial amount of text. A copy that is not 2109 "Transparent" is called "Opaque". 2110 2111 Examples of suitable formats for Transparent copies include plain 2112 ASCII without markup, Texinfo input format, LaTeX input format, 2113 SGML or XML using a publicly available DTD, and standard-conforming 2114 simple HTML, PostScript or PDF designed for human modification. 2115 Examples of transparent image formats include PNG, XCF and JPG. 2116 Opaque formats include proprietary formats that can be read and 2117 edited only by proprietary word processors, SGML or XML for which 2118 the DTD and/or processing tools are not generally available, and 2119 the machine-generated HTML, PostScript or PDF produced by some word 2120 processors for output purposes only. 2121 2122 The "Title Page" means, for a printed book, the title page itself, 2123 plus such following pages as are needed to hold, legibly, the 2124 material this License requires to appear in the title page. For 2125 works in formats which do not have any title page as such, "Title 2126 Page" means the text near the most prominent appearance of the 2127 work's title, preceding the beginning of the body of the text. 2128 2129 The "publisher" means any person or entity that distributes copies 2130 of the Document to the public. 2131 2132 A section "Entitled XYZ" means a named subunit of the Document 2133 whose title either is precisely XYZ or contains XYZ in parentheses 2134 following text that translates XYZ in another language. (Here XYZ 2135 stands for a specific section name mentioned below, such as 2136 "Acknowledgements", "Dedications", "Endorsements", or "History".) 2137 To "Preserve the Title" of such a section when you modify the 2138 Document means that it remains a section "Entitled XYZ" according 2139 to this definition. 2140 2141 The Document may include Warranty Disclaimers next to the notice 2142 which states that this License applies to the Document. These 2143 Warranty Disclaimers are considered to be included by reference in 2144 this License, but only as regards disclaiming warranties: any other 2145 implication that these Warranty Disclaimers may have is void and 2146 has no effect on the meaning of this License. 2147 2148 2. VERBATIM COPYING 2149 2150 You may copy and distribute the Document in any medium, either 2151 commercially or noncommercially, provided that this License, the 2152 copyright notices, and the license notice saying this License 2153 applies to the Document are reproduced in all copies, and that you 2154 add no other conditions whatsoever to those of this License. You 2155 may not use technical measures to obstruct or control the reading 2156 or further copying of the copies you make or distribute. However, 2157 you may accept compensation in exchange for copies. If you 2158 distribute a large enough number of copies you must also follow the 2159 conditions in section 3. 2160 2161 You may also lend copies, under the same conditions stated above, 2162 and you may publicly display copies. 2163 2164 3. COPYING IN QUANTITY 2165 2166 If you publish printed copies (or copies in media that commonly 2167 have printed covers) of the Document, numbering more than 100, and 2168 the Document's license notice requires Cover Texts, you must 2169 enclose the copies in covers that carry, clearly and legibly, all 2170 these Cover Texts: Front-Cover Texts on the front cover, and 2171 Back-Cover Texts on the back cover. Both covers must also clearly 2172 and legibly identify you as the publisher of these copies. The 2173 front cover must present the full title with all words of the title 2174 equally prominent and visible. You may add other material on the 2175 covers in addition. Copying with changes limited to the covers, as 2176 long as they preserve the title of the Document and satisfy these 2177 conditions, can be treated as verbatim copying in other respects. 2178 2179 If the required texts for either cover are too voluminous to fit 2180 legibly, you should put the first ones listed (as many as fit 2181 reasonably) on the actual cover, and continue the rest onto 2182 adjacent pages. 2183 2184 If you publish or distribute Opaque copies of the Document 2185 numbering more than 100, you must either include a machine-readable 2186 Transparent copy along with each Opaque copy, or state in or with 2187 each Opaque copy a computer-network location from which the general 2188 network-using public has access to download using public-standard 2189 network protocols a complete Transparent copy of the Document, free 2190 of added material. If you use the latter option, you must take 2191 reasonably prudent steps, when you begin distribution of Opaque 2192 copies in quantity, to ensure that this Transparent copy will 2193 remain thus accessible at the stated location until at least one 2194 year after the last time you distribute an Opaque copy (directly or 2195 through your agents or retailers) of that edition to the public. 2196 2197 It is requested, but not required, that you contact the authors of 2198 the Document well before redistributing any large number of copies, 2199 to give them a chance to provide you with an updated version of the 2200 Document. 2201 2202 4. MODIFICATIONS 2203 2204 You may copy and distribute a Modified Version of the Document 2205 under the conditions of sections 2 and 3 above, provided that you 2206 release the Modified Version under precisely this License, with the 2207 Modified Version filling the role of the Document, thus licensing 2208 distribution and modification of the Modified Version to whoever 2209 possesses a copy of it. In addition, you must do these things in 2210 the Modified Version: 2211 2212 A. Use in the Title Page (and on the covers, if any) a title 2213 distinct from that of the Document, and from those of previous 2214 versions (which should, if there were any, be listed in the 2215 History section of the Document). You may use the same title 2216 as a previous version if the original publisher of that 2217 version gives permission. 2218 2219 B. List on the Title Page, as authors, one or more persons or 2220 entities responsible for authorship of the modifications in 2221 the Modified Version, together with at least five of the 2222 principal authors of the Document (all of its principal 2223 authors, if it has fewer than five), unless they release you 2224 from this requirement. 2225 2226 C. State on the Title page the name of the publisher of the 2227 Modified Version, as the publisher. 2228 2229 D. Preserve all the copyright notices of the Document. 2230 2231 E. Add an appropriate copyright notice for your modifications 2232 adjacent to the other copyright notices. 2233 2234 F. Include, immediately after the copyright notices, a license 2235 notice giving the public permission to use the Modified 2236 Version under the terms of this License, in the form shown in 2237 the Addendum below. 2238 2239 G. Preserve in that license notice the full lists of Invariant 2240 Sections and required Cover Texts given in the Document's 2241 license notice. 2242 2243 H. Include an unaltered copy of this License. 2244 2245 I. Preserve the section Entitled "History", Preserve its Title, 2246 and add to it an item stating at least the title, year, new 2247 authors, and publisher of the Modified Version as given on the 2248 Title Page. If there is no section Entitled "History" in the 2249 Document, create one stating the title, year, authors, and 2250 publisher of the Document as given on its Title Page, then add 2251 an item describing the Modified Version as stated in the 2252 previous sentence. 2253 2254 J. Preserve the network location, if any, given in the Document 2255 for public access to a Transparent copy of the Document, and 2256 likewise the network locations given in the Document for 2257 previous versions it was based on. These may be placed in the 2258 "History" section. You may omit a network location for a work 2259 that was published at least four years before the Document 2260 itself, or if the original publisher of the version it refers 2261 to gives permission. 2262 2263 K. For any section Entitled "Acknowledgements" or "Dedications", 2264 Preserve the Title of the section, and preserve in the section 2265 all the substance and tone of each of the contributor 2266 acknowledgements and/or dedications given therein. 2267 2268 L. Preserve all the Invariant Sections of the Document, unaltered 2269 in their text and in their titles. Section numbers or the 2270 equivalent are not considered part of the section titles. 2271 2272 M. Delete any section Entitled "Endorsements". Such a section 2273 may not be included in the Modified Version. 2274 2275 N. Do not retitle any existing section to be Entitled 2276 "Endorsements" or to conflict in title with any Invariant 2277 Section. 2278 2279 O. Preserve any Warranty Disclaimers. 2280 2281 If the Modified Version includes new front-matter sections or 2282 appendices that qualify as Secondary Sections and contain no 2283 material copied from the Document, you may at your option designate 2284 some or all of these sections as invariant. To do this, add their 2285 titles to the list of Invariant Sections in the Modified Version's 2286 license notice. These titles must be distinct from any other 2287 section titles. 2288 2289 You may add a section Entitled "Endorsements", provided it contains 2290 nothing but endorsements of your Modified Version by various 2291 parties--for example, statements of peer review or that the text 2292 has been approved by an organization as the authoritative 2293 definition of a standard. 2294 2295 You may add a passage of up to five words as a Front-Cover Text, 2296 and a passage of up to 25 words as a Back-Cover Text, to the end of 2297 the list of Cover Texts in the Modified Version. Only one passage 2298 of Front-Cover Text and one of Back-Cover Text may be added by (or 2299 through arrangements made by) any one entity. If the Document 2300 already includes a cover text for the same cover, previously added 2301 by you or by arrangement made by the same entity you are acting on 2302 behalf of, you may not add another; but you may replace the old 2303 one, on explicit permission from the previous publisher that added 2304 the old one. 2305 2306 The author(s) and publisher(s) of the Document do not by this 2307 License give permission to use their names for publicity for or to 2308 assert or imply endorsement of any Modified Version. 2309 2310 5. COMBINING DOCUMENTS 2311 2312 You may combine the Document with other documents released under 2313 this License, under the terms defined in section 4 above for 2314 modified versions, provided that you include in the combination all 2315 of the Invariant Sections of all of the original documents, 2316 unmodified, and list them all as Invariant Sections of your 2317 combined work in its license notice, and that you preserve all 2318 their Warranty Disclaimers. 2319 2320 The combined work need only contain one copy of this License, and 2321 multiple identical Invariant Sections may be replaced with a single 2322 copy. If there are multiple Invariant Sections with the same name 2323 but different contents, make the title of each such section unique 2324 by adding at the end of it, in parentheses, the name of the 2325 original author or publisher of that section if known, or else a 2326 unique number. Make the same adjustment to the section titles in 2327 the list of Invariant Sections in the license notice of the 2328 combined work. 2329 2330 In the combination, you must combine any sections Entitled 2331 "History" in the various original documents, forming one section 2332 Entitled "History"; likewise combine any sections Entitled 2333 "Acknowledgements", and any sections Entitled "Dedications". You 2334 must delete all sections Entitled "Endorsements." 2335 2336 6. COLLECTIONS OF DOCUMENTS 2337 2338 You may make a collection consisting of the Document and other 2339 documents released under this License, and replace the individual 2340 copies of this License in the various documents with a single copy 2341 that is included in the collection, provided that you follow the 2342 rules of this License for verbatim copying of each of the documents 2343 in all other respects. 2344 2345 You may extract a single document from such a collection, and 2346 distribute it individually under this License, provided you insert 2347 a copy of this License into the extracted document, and follow this 2348 License in all other respects regarding verbatim copying of that 2349 document. 2350 2351 7. AGGREGATION WITH INDEPENDENT WORKS 2352 2353 A compilation of the Document or its derivatives with other 2354 separate and independent documents or works, in or on a volume of a 2355 storage or distribution medium, is called an "aggregate" if the 2356 copyright resulting from the compilation is not used to limit the 2357 legal rights of the compilation's users beyond what the individual 2358 works permit. When the Document is included in an aggregate, this 2359 License does not apply to the other works in the aggregate which 2360 are not themselves derivative works of the Document. 2361 2362 If the Cover Text requirement of section 3 is applicable to these 2363 copies of the Document, then if the Document is less than one half 2364 of the entire aggregate, the Document's Cover Texts may be placed 2365 on covers that bracket the Document within the aggregate, or the 2366 electronic equivalent of covers if the Document is in electronic 2367 form. Otherwise they must appear on printed covers that bracket 2368 the whole aggregate. 2369 2370 8. TRANSLATION 2371 2372 Translation is considered a kind of modification, so you may 2373 distribute translations of the Document under the terms of section 2374 4. Replacing Invariant Sections with translations requires special 2375 permission from their copyright holders, but you may include 2376 translations of some or all Invariant Sections in addition to the 2377 original versions of these Invariant Sections. You may include a 2378 translation of this License, and all the license notices in the 2379 Document, and any Warranty Disclaimers, provided that you also 2380 include the original English version of this License and the 2381 original versions of those notices and disclaimers. In case of a 2382 disagreement between the translation and the original version of 2383 this License or a notice or disclaimer, the original version will 2384 prevail. 2385 2386 If a section in the Document is Entitled "Acknowledgements", 2387 "Dedications", or "History", the requirement (section 4) to 2388 Preserve its Title (section 1) will typically require changing the 2389 actual title. 2390 2391 9. TERMINATION 2392 2393 You may not copy, modify, sublicense, or distribute the Document 2394 except as expressly provided under this License. Any attempt 2395 otherwise to copy, modify, sublicense, or distribute it is void, 2396 and will automatically terminate your rights under this License. 2397 2398 However, if you cease all violation of this License, then your 2399 license from a particular copyright holder is reinstated (a) 2400 provisionally, unless and until the copyright holder explicitly and 2401 finally terminates your license, and (b) permanently, if the 2402 copyright holder fails to notify you of the violation by some 2403 reasonable means prior to 60 days after the cessation. 2404 2405 Moreover, your license from a particular copyright holder is 2406 reinstated permanently if the copyright holder notifies you of the 2407 violation by some reasonable means, this is the first time you have 2408 received notice of violation of this License (for any work) from 2409 that copyright holder, and you cure the violation prior to 30 days 2410 after your receipt of the notice. 2411 2412 Termination of your rights under this section does not terminate 2413 the licenses of parties who have received copies or rights from you 2414 under this License. If your rights have been terminated and not 2415 permanently reinstated, receipt of a copy of some or all of the 2416 same material does not give you any rights to use it. 2417 2418 10. FUTURE REVISIONS OF THIS LICENSE 2419 2420 The Free Software Foundation may publish new, revised versions of 2421 the GNU Free Documentation License from time to time. Such new 2422 versions will be similar in spirit to the present version, but may 2423 differ in detail to address new problems or concerns. See 2424 <http://www.gnu.org/copyleft/>. 2425 2426 Each version of the License is given a distinguishing version 2427 number. If the Document specifies that a particular numbered 2428 version of this License "or any later version" applies to it, you 2429 have the option of following the terms and conditions either of 2430 that specified version or of any later version that has been 2431 published (not as a draft) by the Free Software Foundation. If the 2432 Document does not specify a version number of this License, you may 2433 choose any version ever published (not as a draft) by the Free 2434 Software Foundation. If the Document specifies that a proxy can 2435 decide which future versions of this License can be used, that 2436 proxy's public statement of acceptance of a version permanently 2437 authorizes you to choose that version for the Document. 2438 2439 11. RELICENSING 2440 2441 "Massive Multiauthor Collaboration Site" (or "MMC Site") means any 2442 World Wide Web server that publishes copyrightable works and also 2443 provides prominent facilities for anybody to edit those works. A 2444 public wiki that anybody can edit is an example of such a server. 2445 A "Massive Multiauthor Collaboration" (or "MMC") contained in the 2446 site means any set of copyrightable works thus published on the MMC 2447 site. 2448 2449 "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 2450 license published by Creative Commons Corporation, a not-for-profit 2451 corporation with a principal place of business in San Francisco, 2452 California, as well as future copyleft versions of that license 2453 published by that same organization. 2454 2455 "Incorporate" means to publish or republish a Document, in whole or 2456 in part, as part of another Document. 2457 2458 An MMC is "eligible for relicensing" if it is licensed under this 2459 License, and if all works that were first published under this 2460 License somewhere other than this MMC, and subsequently 2461 incorporated in whole or in part into the MMC, (1) had no cover 2462 texts or invariant sections, and (2) were thus incorporated prior 2463 to November 1, 2008. 2464 2465 The operator of an MMC Site may republish an MMC contained in the 2466 site under CC-BY-SA on the same site at any time before August 1, 2467 2009, provided the MMC is eligible for relicensing. 2468 2469ADDENDUM: How to use this License for your documents 2470==================================================== 2471 2472To use this License in a document you have written, include a copy of 2473the License in the document and put the following copyright and license 2474notices just after the title page: 2475 2476 Copyright (C) YEAR YOUR NAME. 2477 Permission is granted to copy, distribute and/or modify this document 2478 under the terms of the GNU Free Documentation License, Version 1.3 2479 or any later version published by the Free Software Foundation; 2480 with no Invariant Sections, no Front-Cover Texts, and no Back-Cover 2481 Texts. A copy of the license is included in the section entitled ``GNU 2482 Free Documentation License''. 2483 2484 If you have Invariant Sections, Front-Cover Texts and Back-Cover 2485Texts, replace the "with...Texts." line with this: 2486 2487 with the Invariant Sections being LIST THEIR TITLES, with 2488 the Front-Cover Texts being LIST, and with the Back-Cover Texts 2489 being LIST. 2490 2491 If you have Invariant Sections without Cover Texts, or some other 2492combination of the three, merge those two alternatives to suit the 2493situation. 2494 2495 If your document contains nontrivial examples of program code, we 2496recommend releasing these examples in parallel under your choice of free 2497software license, such as the GNU General Public License, to permit 2498their use in free software. 2499 2500