Handle multiple postcomputes.
[pspp] / doc / dev / tlo-file-format.texi
1 @c PSPP - a program for statistical analysis.
2 @c Copyright (C) 2020 Free Software Foundation, Inc.
3 @c Permission is granted to copy, distribute and/or modify this document
4 @c under the terms of the GNU Free Documentation License, Version 1.3
5 @c or any later version published by the Free Software Foundation;
6 @c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
7 @c A copy of the license is included in the section entitled "GNU
8 @c Free Documentation License".
9 @c
10
11 @node SPSS TableLook File Formats
12 @appendix SPSS TableLook File Formats
13
14 SPSS has a concept called a TableLook to control the styling of pivot
15 tables in output.  SPSS 15 and earlier used @file{.tlo} files with a
16 special binary format to save TableLooks to disk; SPSS 16 and later
17 use @file{.stt} files in an XML format to save them.  Both formats
18 expose roughly the same features, although the older @file{.tlo}
19 format does have some features that @file{.stt} does not.
20
21 This appendix describes both formats.
22
23 @menu
24 * SPSS TableLook STT Format::
25 * SPSS TableLook TLO Format::
26 @end menu
27
28 @node SPSS TableLook STT Format
29 @section The @file{.stt} Format
30
31 The @file{.stt} file format is an XML file that contains a subset of
32 the SPV structure member format (@pxref{SPV Structure Member Format}).
33 Its root element is a @code{tableProperties} element (@pxref{SPV
34 Detail Legacy Properties}).
35
36 @node SPSS TableLook TLO Format
37 @section The @file{.tlo} Format
38
39 A @file{.tlo} file has a custom binary format.  This section describes
40 it using the syntax used previously for SPV binary members (@pxref{SPV
41 Light Detail Member Format}).  There is one new convention: TLO files
42 express colors as @code{int32} values in which the low 8 bits are the
43 red component, the next 8 bits are green, and next 8 bits are blue,
44 and the high bits are zeros.
45
46 TLO files support various features that SPV files do not.  PSPP
47 implements the SPV feature set, so it mostly ignores the added TLO
48 features.  The details of this mapping are explained below.
49
50 At the top level, a TLO file consists of five sections.  The first
51 four are always present and the last one is optional:
52
53 @example
54 TableLook =>
55    PTTableLook[tl]
56    PVSeparatorStyle[ss]
57    PVCellStyle[cs]
58    PVTextStyle[ts]
59    V2Styles?
60 @end example
61
62 Each section is described below.
63
64 @menu
65 * PTTableLook in SPSS TLO Files::
66 * PVSeparatorStyle in SPSS TLO Files::
67 * PVCellStyle and PVTextStyle in SPSS TLO Files::
68 * V2Styles in SPSS TLO Files::
69 @end menu
70
71 @node PTTableLook in SPSS TLO Files
72 @subsection @code{PTTableLook}
73
74 @example
75 PTTableLook =>
76    ff ff 00 00 "PTTableLook" (00|02)[version]
77    int16[flags]
78    00 00
79    bool[nested-row-labels] 00
80    bool[footnote-marker-subscripts] 00
81    i54 i18
82 @end example
83
84 In PTTableLook, @code{version} is 00 or 02.  The only difference is
85 that version 00 lacks V2Styles (@pxref{V2Styles in SPSS TLO Files})
86 and that version 02 includes it.  Both TLO versions are seen in the
87 wild.
88
89 @code{flags} is a bit-mapped field.  Its bits have the following
90 meanings:
91
92 @table @asis
93 @item 0x2
94 If set to 1, hide empty rows and columns; otherwise, show them.
95
96 @item 0x4
97 If set to 1, use numeric footnote markers; otherwise, use alphabetic
98 footnote markers.
99
100 @item 0x8
101 If set to 1, print all layers; otherwise, print only the current
102 layer.
103
104 @item 0x10
105 If set to 1, scale the table to fit the page width; otherwise, break
106 it horizontally if necessary.
107
108 @item 0x20
109 If set to 1, scale the table to fit the page length; otherwise, break
110 it vertically if necessary.
111
112 @item 0x40
113 If set to 1, print each layer on a separate page (only if all layers
114 are being printed); otherwise, paginate layers naturally.
115
116 @item 0x80
117 If set to 1, print a continuation string at the top of a table that is
118 split between pages.
119
120 @item 0x100
121 If set to 1, print a continuation string at the bottom of a table that
122 is split between pages.
123 @end table
124
125 When @code{nested-row-labels} is 1, row dimension labels appear
126 nested; otherwise, they are put into the upper-left corner of the
127 pivot table.
128
129 When @code{footnote-marker-subscripts} is 1, footnote markers are
130 shown as subscripts; otherwise, they are shown as superscripts.
131
132 @node PVSeparatorStyle in SPSS TLO Files
133 @subsection @code{PVSeparatorStyle}
134
135 @example
136 PVSeparatorStyle =>
137    ff ff 00 00 "PVSeparatorStyle" 00
138    Separator*4[sep1]
139    03 80 00
140    Separator*4[sep2]
141
142 Separator =>
143    case(
144        00 00
145      | 01 00 int32[color] int16[style] int16[width]
146    )[type]
147 @end example
148
149 PVSeparatorStyle contains eight Separators, in two groups.  Each
150 Separator represents a border between pivot table elements.  TLO and
151 SPV files have the same concepts for borders.  @xref{SPV Light Member
152 Borders}, for the treatment of borders in SPV files.
153
154 A Separator's @code{type} is 00 if the border is not drawn, 01
155 otherwise.  For a border that is drawn, @code{color} is the color that
156 it is drawn in.  @code{style} and @code{width} have the following
157 meanings:
158
159 @table @asis
160 @item @code{style} = 0 and 0 @leq{} @code{width} @leq{} 3
161 An increasingly thick single line.  SPV files only have three line
162 thicknesses.  PSPP treats @code{width} 0 as a thin line, @code{width}
163 1 as a solid (normal width) line, and @code{width} 2 or 3 as a thick
164 line.
165
166 @item @code{style} = 1 and 0 @leq{} @code{width} @leq{} 1
167 A doubled line, composed of normal-width (0) or thick (1) lines.  SPV
168 files only have ``normal'' width double lines, so PSPP maps both
169 variants the same way.
170
171 @item @code{style} = 2
172 A dashed line.
173 @end table
174
175 The first group, @code{sep1}, represents the following borders within
176 the pivot table, by index:
177
178 @enumerate 0
179 @item Horizontal dimension rows
180 @item Vertical dimension rows
181 @item Horizontal category rows
182 @item Vertical category rows
183 @end enumerate
184
185 The second group, @code{sep2}, represents the following borders within
186 the pivot table, by index:
187
188 @enumerate 0
189 @item Horizontal dimension columns
190 @item Vertical dimension columns
191 @item Horizontal category columns
192 @item Vertical category columns
193 @end enumerate
194
195 @node PVCellStyle and PVTextStyle in SPSS TLO Files
196 @subsection @code{PVCellStyle} and @code{PVTextStyle}
197
198 @example
199 PVCellStyle =>
200    ff ff 00 00 "PVCellStyle"
201    AreaColor[title-color]
202
203 PVTextStyle =>
204    ff ff 00 00 "PVTextStyle" 00
205    AreaStyle[title-style] MostAreas*7[most-areas]
206
207 MostAreas =>
208    06 80
209    AreaColor[color] 08 80 00 AreaStyle[style]
210 @end example
211
212 These sections hold the styling and coloring for each of the 8 areas
213 in a pivot table.  They are conceptually similar to the area style
214 information in SPV light members (@pxref{SPV Light Member Areas}).
215
216 The styling and coloring for the title area is split between
217 PVCellStyle and PVTextStyle: the former holds @code{title-color}, the
218 latter holds @code{title-style}.  The style for the remaining 7 areas
219 is in @code{most-areas} in PVTextStyle, in the following order:
220 layers, corner, row labels, column labels, data, caption, and footer.
221
222 @example
223 AreaColor =>
224    00 01 00 int32[color10] int32[color0] byte[shading] 00
225 @end example
226
227 AreaColor represents the background color of an area.  TLO files, but
228 not SPV files, describe backgrounds that are a shaded combination of
229 two colors: @code{shading} of 0 is pure @code{color0}, @code{shading}
230 of 10 is pure @code{color10}, and value in between mix pixels of the
231 two different colors in linear degree.  PSPP does not implement
232 shading, so for 1 @leq{} @code{shading} @leq{} 9 it interpolates RGB
233 values between colors to arrive at an intermediate shade.
234
235 @example
236 AreaStyle =>
237    int16[valign] int16[halign] int16[decimal-offset]
238    int16[left-margin] int16[right-margin] int16[top-margin] int16[bottom-margin]
239    00 00 01 00
240    int32[font-size] int16[stretch]
241    00*2
242    int32[rotation-angle]
243    00*4
244    int16[weight]
245    00*2
246    bool[italic] bool[underline] bool[strikethrough]
247    int32[rtf-charset-number]
248    byte[x]
249    byte[font-name-len] byte*[font-name-len][font-name]
250    int32[text-color]
251    00*2
252 @end example
253
254 AreaStyle represents style properties of an area.
255
256 @code{valign} is 0 for top alignment, 1 for bottom alginment, 2 for
257 center.
258
259 @code{halign} is 0 for left alignment, 1 for right, 2 for center, 3
260 for mixed, 4 for decimal.  For decimal alignment,
261 @code{decimal-offset} is the offset of the decimal point in 20ths of a
262 point.
263
264 @code{left-margin}, @code{right-margin}, @code{top-margin}, and
265 @code{bottom-margin} are also measured in 20ths of a point.
266
267 @code{font-size} is negative 96ths of an inch, e.g. 9 point is -12 or
268 0xfffffff3.
269
270 @code{stretch} has something to do with font size or stretch.  The
271 usual value is 01 and values larger than that do weird things.  A
272 reader can safely ignore it.
273
274 @code{rotation-angle} is a font rotation angle.  A reader can safely
275 ignore it.
276
277 @code{weight} is 400 for a normal-weight font, 700 indicates bold.
278 (This is a Windows API convention.)
279
280 @code{italic} and @code{underline} have the obvious meanings.  So does
281 @code{strikethrough}, which PSPP ignores.
282
283 @code{rtf-charset-number} is a character set number from RTF.  A
284 reader can safely ignore it.
285
286 The meaning of @code{x} is unknown.  Values 12, 22, 31, and 32 have
287 been observed.
288
289 The @code{font-name} is the name of a font, such as @code{Arial}.
290 Only US-ASCII characters have been observed here.
291
292 @code{text-color} is the color of the text itself.
293
294 @node V2Styles in SPSS TLO Files
295 @subsection @code{V2Styles}
296
297 @example
298 V2Styles =>
299    Separator*11[sep3]
300    byte[continuation-len] byte*[continuation-len][continuation]
301    int32[min-col-width] int32[max-col-width]
302    int32[min-row-height] int32[max-row-height]
303 @end example
304
305 This final, optional, part of the TLO file format contains some
306 additional style information.  It begins with @code{sep3}, which
307 represents the following borders within the pivot table, by index:
308
309 @table @asis
310 @item 0
311 Title.
312 @item 1@dots{}4
313 Left, right, top, and bottom inner frame.
314 @item 5@dots{}8
315 Left, right, top, and bottom outer frame.
316 @item 9, 10
317 Left and top of data area.
318 @end table
319
320 When V2Styles is absent, the inner frame borders default to a solid
321 line and the others listed above to no line.
322
323 @code{continuation} is the string that goes at the top or bottom
324 of a table broken across pages.  When V2Styles is absent, the
325 default is @code{(Cont.)}.
326
327 @code{min-col-width} is the minimum width that a column will be
328 assigned automatically.  @code{max-col-width} is the maximum width
329 that a column will be assigned to accommodate a long column label.
330 @code{min-row-width} and @code{max-row-width} are a similar range for
331 the width of row labels.  All of these measurements are in points.
332 When V2Styles is absent, the defaults are 36 for @code{min-col-width} and
333 @code{min-row-height}, 72 for @code{max-col-width}, and 120 for
334 @code{max-row-height}.