1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
|
<sect1 id="sect-file-textExport">
<title>Exporting Text Files</title>
<!-- TODO: Rewrite this sucker! Use the new screenshots. -->
<para>
&gnum; can export worksheets to structured text files. To create
a text file one chooses the <guimenuitem>Export As Text File...</guimenuitem>
item in the <guimenu>Export Data</guimenu> submenu of the
<guimenu>Data</guimenu> menu. In the dialog, one specifies the file name, and
selects the folder in which to save it, retaining the file format
"Text export (configurable)". Upon clicking <interface>Save</interface> the
<interface>Text Export</interface> druid appears which permits the configuration
of file structure characteristics.
</para>
<tip>
<title>The Text Export Druid.</title>
<para>The steps involved in the text export druid are:</para>
<orderedlist>
<listitem>
<para>
Launch the <interface>Text export</interface> druid using,
in the <guimenuitem>Export As Text File...</guimenuitem>
item in the <guimenu>Export Data</guimenu> submenu of the
<guimenu>Data</guimenu> retaining the "Text export
(configurable)" file format type.
</para>
</listitem>
<listitem>
<para>
Select the worksheets to include in the exported file.
</para>
</listitem>
<listitem>
<para>
Configure the order of the worksheets for the exported file.
</para>
</listitem>
<listitem>
<para>
Go to the second panel.
</para>
</listitem>
<listitem>
<para>
Select the line termination character.
</para>
</listitem>
<listitem>
<para>
Select the value separating character or character sequence
</para>
</listitem>
<listitem>
<para>
Select when values should be surrounded by a text indicating character.
</para>
</listitem>
<listitem>
<para>
Select the character or sequence to use to indicate a text field.
</para>
</listitem>
<listitem>
<para>
Configure the character encoding to use for the file.
</para>
</listitem>
<listitem>
<para>
Select how to handle unknown characters.
</para>
</listitem>
<listitem>
<para>
Select whether to preserve the format of the cell contents.
</para>
</listitem>
<listitem>
<para>
Click on the <guibutton>Finish</guibutton> button to export
the file.
</para>
</listitem>
</orderedlist>
</tip>
<sect2 id="note-file-textExport-druid">
<title>
The Components of the <interface>Text Export</interface> Druid
</title>
<para>
The <interface>Text Export</interface> druid consists of two
panels. The first panel allows the user to select the worksheets
included in the export and their order. The second panel allows
the user to configure the structuring elements, the line
delimiting characters, value separating characters, text indicating
characters, and file encoding.
</para>
<sect3 id="sect-file-textExport-druid-panel1">
<title>
The first panel of the <interface>Text Export</interface> Druid.
</title>
<para>
The first panel of the <interface>Text Export</interface>
Druid allows users to set the file encoding, to determine the
character sequences used to separate lines, configure the type
of structuring being used and select the lines of the file to
import.
</para>
<figure id="fig-file-textExport-druid-panel1">
<title>
The first panel of the <interface>Text Export</interface>
druid with the component areas labeled with callouts.
</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="figures/textguru-export-panel1-withTags.png"
format="PNG" />
</imageobject>
<textobject>
<para>
This screenshot depicts the first panel 'Text Export'
druid with callouts labeling the different areas.
</para>
</textobject>
<caption>
<para>
The different components of the first panel of the
<interface>Text Export</interface> druid with each component
labeled with a callout.
</para>
</caption>
</mediaobject>
</screenshot>
</figure>
<para>
The purpose of each labeled component in <xref
linkend="fig-file-textExport-druid-panel1" /> is
explained below:
<variablelist>
<title>The components of the first panel</title>
<varlistentry>
<term>
<emphasis role="bold">1</emphasis> - The worksheet
selection area.
</term>
<listitem>
<para>
This area allows the user to select the worksheets to
be included in the file. By default, only the top most
sheet will have its checkbox checked and be included in
the export. The user can add sheets by clicking in their
checkboxes to set the check marks.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">2</emphasis> - The worksheet
selection and ordering buttons.
</term>
<listitem>
<para>
The top two buttons allows the user quickly to select
or unselect all the worksheets to be included in the
export file. The bottom two buttons allow the user to
change the order of the worksheets in the file to be
exported.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">3</emphasis> - The button area.
</term>
<listitem>
<para>
These three buttons allow the user to navigate the
druid.
<!-- TODO: bug- text export needs a help button. -->
<!--
The <guibutton>Help</guibutton> button should
open the &gnum; manual to this section.
-->
The <guibutton>Cancel</guibutton> button will dismiss
the dialog and return the user to the worksheet. The
<guibutton>Back</guibutton> button is disable since
this is the first panel of the druid. The
<guibutton>Forward</guibutton> button will dismiss the
first panel and bring up the second panel of the druid.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3 id="sect-file-textExport-druid-panel2">
<title>
The second panel of the <interface>Text Export</interface> Druid.
</title>
<para>
The second panel of the <interface>Text Export</interface>
Druid allows users to select the line termination character,
configure the value separating character, select the text
indicating character and set the character encoding.
</para>
<figure id="fig-file-textExport-druid-panel2">
<title>
The second panel of the <interface>Text Export</interface>
druid with the component areas labeled with callouts.
</title>
<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="figures/textguru-export-panel2-withTags.png" format="PNG" />
</imageobject>
<textobject>
<para>
This screenshot depicts the second panel 'Text Export'
druid with callouts labeling the different areas.
</para>
</textobject>
<caption>
<para>
The different components of the second panel of the
<interface>Text Export</interface> druid with each component
labeled with a callout.
</para>
</caption>
</mediaobject>
</screenshot>
</figure>
<para>
The purpose of each labeled component in <xref
linkend="fig-file-textExport-druid-panel2" /> is
explained below:
<variablelist>
<title>The components of the second panel</title>
<varlistentry>
<term>
<emphasis role="bold">1</emphasis> - The export
characteristic menu buttons.
</term>
<listitem>
<para>
These drop down menus provide to set the different
configuration parameters for the exported file. The
various menus are as follows.
<itemizedlist>
<listitem>
<para>
Line Delimiting Character-
</para>
<para>
This button allows the user to activate a drop
down list from which to select the character
used to indicate the end of a line and beginning
of the next. The three commonly used
alternatives are provided. See <xref
linkend="sect-file-textImport-complex-lineBreak"
/> for more details.
</para>
</listitem>
<listitem>
<para>
Value Separating Character-
</para>
<para>
This button allows the user to select a character
to use as a value separator. The "Custom" type
will active the text entry area to allow the
user to determine a particular character or
character sequence to use to delimit data
values. See <xref
linkend="sect-file-textImport-complex-dataStruct"
/> for more details.
</para>
</listitem>
<listitem>
<para>
Value Separating Character entry area-
</para>
<para>
This entry area allows the user to define
explicitly the character or character sequence
which should be used to separate each value field
on every line. This area is only active if the
"Custom" type has been selected from the list in
the button above.
</para>
</listitem>
<listitem>
<para>
The Text Field Delimiter activity setting-
</para>
<!-- TODO: ask- why does space require quotes in a csv file? -->
<para>
This button activates a list with three choices
for the use of text field delimiters. Text
fields can be delimited only where needed,
meaning that the quote characters will only be
used if the value contains the character used as
a separator or a space. Alternatively the text
field separators can be used around all values
or never applied. See <xref
linkend="sect-file-textImport-complex-dataStruct"
/> for more details.
</para>
</listitem>
<listitem>
<para>
The Text Field Delimiter character entry area and list-
</para>
<para>
This area can be used as a text entry area to
type the character to use to delimit text
fields. Alternatively, three pre-selected
characters, double quotes or single quotes, can
be selected from the drop down list which
appears by clicking on the downward pointing
arrow to the right of the text field.
</para>
</listitem>
<listitem>
<para>
File encoding selection button-
</para>
<para>
This button allows the user to set the encoding
scheme to use for the file. By default, &gnum;
selects the encoding scheme used by the locale
of the user. See <xref
linkend="sect-file-textImport-complex-encoding"
/> for more details.
</para>
</listitem>
<!-- TODO: ask- how is this supposed to work? -->
<listitem>
<para>
The unknown character handling setting button-
</para>
<para>
This button selects whether to escape or
transliterate characters which &gnum; does not
recognize.
</para>
</listitem>
<!-- TODO: ask- is this really what this does? -->
<listitem>
<para>
The format preservation checkbox-
</para>
<para>
This checkbox sets whether to preserve the
number formats for formatted values.
</para>
</listitem>
</itemizedlist>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<emphasis role="bold">2</emphasis> - The button area.
</term>
<listitem>
<para>
These three buttons allow the user to navigate the
druid.
<!-- TODO: bug- text export needs a help button. -->
<!--
The <guibutton>Help</guibutton> button should
open the &gnum; manual to this section.
-->
The <guibutton>Cancel</guibutton> button will dismiss
the dialog and return the user to the worksheet. The
<guibutton>Back</guibutton> button is disable since
this is the first panel of the druid. The
<guibutton>Finish</guibutton> button will dismiss the
druid and cause the file to be saved using the
selected options.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
</sect2>
</sect1>
|
