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
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
|
<?xml version="1.0" encoding="UTF-8" ?>
<chapter id="extending-quanta-3-2">
<chapterinfo>
<title>Extender o &quantaplus;</title>
<authorgroup>
<author><firstname>Christopher</firstname> <surname>Hornbaker</surname> <affiliation> <address><email>[email protected]</email></address>
</affiliation>
</author>
<author><firstname>András</firstname> <surname>Mantia</surname> <affiliation> <address><email>[email protected]</email></address>
</affiliation>
</author>
<othercredit role="translator"><firstname>Pedro</firstname><surname>Morais</surname><affiliation><address><email>[email protected]</email></address></affiliation><contrib>Tradução</contrib></othercredit>
</authorgroup>
</chapterinfo>
<title>Extender o &quantaplus;</title>
<para>Este capítulo descreve como personalizar o &quantaplus; de acordo com as suas necessidades particulares e como pode ajudar o &quantaplus; a tornar-se melhor. </para>
<!--<sect1 id="kommander-3-2">
<title>Using Kommander With &quantaplus;</title>
<para>
Kommander, by Marc Britton.
</para>
</sect1> -->
<sect1 id="dtep-intro-3-2">
<title>Pacote de Edição do Tipo de Documento (&DTEP;)</title>
<para>Os Pacotes de Edição do Tipo de Documentos (&DTEP;s) são usados no &quantaplus; para adicionar o suporte para as linguagens de formatação e de 'scripting', bem como para o &CSS;. Estas permitem ao &quantaplus; oferecer as funcionalidades como a auto-completação e as árvores de nós. A sua simplicidade e flexibilidade são o que tornam o &quantaplus; um &IDE; rápido e amigável para os programadores Web. São também o que fazem do &quantaplus; um ambiente produtivo e simples de utilizar. </para>
<para>Os &DTEP;s vêm em dois formatos: a Família 1, que corresponde às linguagens de formatação e a Família 2, que corresponde ao 'scripting' e ao &CSS;. Os &DTEP;s são compostos por duas partes, a Pasta de Marcas e as Barras de Ferramentas. As Pastas de Marcas são compostas por dois tipos de ficheiros, o &descriptionrc; e os ficheiros de TagXML, os quais contêm a extensão '.tag'. As barras de ferramentas são as páginas de botões úteis e orientados por ícones (por cima da janela de edição) que colocam o texto num documento de forma mais rápida do que o utilizador consegue escrever. </para>
<para>Os &DTEP;s podem ser criados manualmente (veja em baixo), <link linkend="download-resources">obtidos da Internet</link> ou criados automaticamente a partir de uma DTD existente. Veja em <xref linkend="converting-dtd"/> os detalhes da conversão. </para>
<para>Este documento descreve como é possível criar ficheiros TagXML, o &descriptionrc; e as barras de ferramentas. Em resumo, como criar um &DTEP;. </para>
<para>Os ficheiros TagXML (.tag) definem tanto os atributos específicos para uma marca como a disposição e o conteúdo da janela de propriedades que o &quantaplus; irá mostrar para a marca. O ficheiro &descriptionrc; contém as regras e a informação para o próprio &DTEP;. As barras de ferramentas oferecem uma forma rápida de adicionar marcas num documento, sem haver a preocupação com erros de escrita e outros erros do género. </para>
<sect2 id="dtep-packaging-3-2">
<title>Empacotamento</title>
<para>As Pastas de Marcas são isso mesmo - pastas. Estas são compostas apenas pelos ficheiros &descriptionrc; e TagXML. As Pastas de Marcas contêm o nome da linguagem de formatação e a versão, se tal se aplicar. (Por exemplo, html-4.01-strict) </para>
</sect2>
<sect2 id="tagxml-3-2">
<title>TagXML</title>
<para>A tabela em baixo enumera os elementos que são definidos no TagXML e refere se estes são obrigatórios ou não. Embora nem todos sejam necessários, recomenda-se que você use tantos quantos possíveis para que os outros utilizadores possam ter uma melhor experiência e mais informação com que lidar. </para>
<informaltable>
<tgroup cols="3">
<thead>
<row>
<entry>Elemento</entry>
<entry>Utilização Predefinida</entry>
<entry>Caso de Utilização</entry>
</row>
</thead>
<tbody>
<row>
<entry>TAGS</entry>
<entry>necessário</entry>
<entry>sempre</entry>
</row>
<row>
<entry>tag</entry>
<entry>necessário</entry>
<entry>sempre</entry>
</row>
<row>
<entry>label</entry>
<entry>opcional</entry>
<entry>necessário para criar uma janela de propriedades</entry>
</row>
<row>
<entry>attr</entry>
<entry>opcional</entry>
<entry>necessário para definir um atributo</entry>
</row>
<row>
<entry>tooltip</entry>
<entry>opcional</entry>
<entry>necessário para que a janela de propriedades mostre uma dica</entry>
</row>
<row>
<entry>whatsthis</entry>
<entry>opcional</entry>
<entry>necessário para que a janela de propriedades mostre um <quote>O Que é Isto?</quote></entry>
</row>
<row>
<entry>list</entry>
<entry>opcional</entry>
<entry>necessário quando um determinado atributo é do tipo <quote>list</quote> (lista)</entry>
</row>
<row>
<entry>item</entry>
<entry>opcional</entry>
<entry>necessário quando o <list> é usado</entry>
</row>
<row>
<entry>textlocation</entry>
<entry>opcional</entry>
<entry>sempre</entry>
</row>
<row>
<entry>location</entry>
<entry>opcional</entry>
<entry>necessário quando é usada uma legenda</entry>
</row>
<row>
<entry>text</entry>
<entry>opcional</entry>
<entry>necessário quando é usada uma legenda</entry>
</row>
<row>
<entry>children</entry>
<entry>opcional</entry>
<entry>uma lista das marcas que poderão aparecer dentro da marca que está a ser definida</entry>
</row>
<row>
<entry>child</entry>
<entry>necessário</entry>
<entry>um item-filho</entry>
</row>
<row>
<entry>stoppingtags</entry>
<entry>opcional</entry>
<entry>uma lista das marcas que indicam o fim para outra marca</entry>
</row>
<row>
<entry>stoppingtag</entry>
<entry>necessário</entry>
<entry>um item de interrupção da marca</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<sect3 id="dtep-element-descriptions-3-2">
<title>Descrições do Elemento do TagXML</title>
<para>As secções seguintes irão descrever, em detalhe, cada elemento. Tudo desde onde eles poderão estar até o que poderão conter é descrito aqui de uma forma simples de seguir. </para>
<sect4 id="TAGS-3-2">
<title>TAGS</title>
<para>Este é o elemento de raiz (topo) de um documento de TagXML. Só poderá aparecer num documento uma única vez. Poderá conter a definição de várias marcas. Este é um elemento do tipo apenas para elementos. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry><emphasis>NENHUM</emphasis></entry>
<entry>tag</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="tag-3-2">
<title>tag</title>
<para>Uma cobertura para a marca a ser definida. Este é um elemento do tipo apenas para elementos. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>TAGS</entry>
<entry>label, attr, stoppingtags</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="6">
<thead>
<row>
<entry>Atributo</entry><entry>Tipo</entry><entry>Valores</entry>
<entry>Predefinição</entry><entry>Utilização</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>name</entry><entry>string</entry><entry></entry><entry></entry>
<entry>necessário</entry><entry>Indica o nome da marca a ser definida.</entry>
</row>
<row>
<entry>single</entry><entry>boolean</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Indica se a marca necessita de uma 'tag' de fecho ou não (</(nome da marca)>.</entry>
</row>
<row>
<entry>type</entry><entry>string</entry><entry></entry><entry>xmltag</entry>
<entry>opcional</entry><entry>Indica o tipo da marca a ser definida.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>xmltag</entry><entry></entry>
<entry></entry><entry>O tipo da marca baseia-se em XML. (Apenas na Família 1.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>entity</entry><entry></entry>
<entry></entry><entry>A marca descreve uma entidade. (Apenas na Família 1.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>property</entry><entry></entry>
<entry></entry><entry>O tipo da marca relaciona-se com a &CSS; (Apenas Família 2.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>function</entry><entry></entry>
<entry></entry><entry>O tipo da marca é uma função de programação. Quando é usado, os elementos <attr> tornam-se os argumentos da função (apenas na Família 2).</entry>
</row>
<row>
<entry></entry><entry></entry><entry>class</entry><entry></entry>
<entry></entry><entry>O tipo da marca é uma classe de programação. (apenas na Família 2.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>method</entry><entry></entry>
<entry></entry><entry>O tipo da marca é um método da classe. (apenas na Família 2.)</entry>
</row>
<row>
<entry>returnType</entry><entry>string</entry><entry></entry><entry>void </entry>
<entry>opcional</entry><entry>Indica o tipo devolvido pela marca a ser definida. (apenas na Família 2).</entry>
</row>
<row>
<entry></entry><entry></entry><entry>void</entry><entry></entry>
<entry></entry><entry>O tipo da marca não devolve nada ('void').</entry>
</row>
<row>
<entry></entry><entry></entry><entry>int</entry><entry></entry>
<entry></entry><entry>O tipo da marca devolve um inteiro.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>float</entry><entry></entry>
<entry></entry><entry>O tipo da marca devolve um número de vírgula flutuante.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>long</entry><entry></entry>
<entry></entry><entry>O tipo da marca devolve um número longo.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>string</entry><entry></entry>
<entry></entry><entry>O tipo de marca devolve uma cadeia de caracteres.</entry>
</row>
<row>
<entry>version</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Indica a versão da linguagem para a qual esta marca é válida</entry>
</row>
<row>
<entry>extends</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Só é válido se o tipo da marca for o "class". O nome da classe de base desta classe. (Apenas na família 2).</entry>
</row>
<row>
<entry>class</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Só é válido se o tipo for "method". O nome da classe a que este método pertence. (Apenas na família 2).</entry>
</row>
<row>
<entry>common</entry><entry>boolean</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Se for igual a "yes", a marca corresponde a um grupo de atributos comum e os atributos desta marca poderão ser anexados a qualquer outra marca. (Apenas na Família 1.)</entry>
</row>
<row>
<entry>comment</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>o texto do comentário aparece perto do nome da marca na lista de completação</entry>
</row></tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="label-3-2">
<title>label</title>
<para>Coloca uma legenda na janela. O texto é referido na marca <text>. Este é um elemento do tipo apenas para elementos. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>tag</entry>
<entry>text, location</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="attr-3-2">
<title>attr</title>
<para>Define um atributo da marca. Este elemento ocorre uma vez para cada atributo. Define o nome e o tipo do atributo. Também contém as marcas adicionais que indicam como o atributo deverá ser mostrado, etc. Este é um elemento do tipo apenas para elementos. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>tag</entry>
<entry>location, list, tooltip, whatsthis, textlocation</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="6">
<thead>
<row>
<entry>Atributo</entry><entry>Tipo</entry><entry>Valores</entry>
<entry>Predefinição</entry><entry>Utilização</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>name</entry><entry>string</entry><entry></entry><entry></entry>
<entry>necessário</entry><entry>Indica o nome do atributo a ser definido.</entry>
</row>
<row>
<entry>type</entry><entry>string</entry><entry></entry><entry>input</entry>
<entry>necessário</entry><entry>Indica o tipo do atributo a ser definido.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>input</entry><entry></entry>
<entry></entry><entry>O campo suporta a introdução de texto livre (campo de texto).</entry>
</row>
<row>
<entry></entry><entry></entry><entry>check</entry><entry></entry>
<entry></entry><entry>O valor do campo é booleano (opção).</entry>
</row>
<row>
<entry></entry><entry></entry><entry>color</entry><entry></entry>
<entry></entry><entry>O valor do campo é uma cor.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>url</entry><entry></entry>
<entry></entry><entry>O valor do campo é um &URL;. (Ficheiro local que referencia.)</entry>
</row>
<row>
<entry></entry><entry></entry><entry>list</entry><entry></entry>
<entry></entry><entry>O valor do campo é um item de uma lista indicada.</entry>
</row>
<row>
<entry>status</entry><entry>string</entry><entry></entry><entry>opcional</entry>
<entry>necessário</entry><entry>Indica se o argumento é ou não obrigatório. (Apenas na Família 2).</entry>
</row>
<row>
<entry></entry><entry></entry><entry>opcional</entry><entry></entry>
<entry></entry><entry>O argumento é opcional.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>necessário</entry><entry></entry>
<entry></entry><entry>O argumento é necessário.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>implied</entry><entry></entry>
<entry></entry><entry>O argumento é implícito.</entry>
</row>
<row>
<entry>source</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Indica as origens usadas para preencher o item do atributo na janela de edição da marca e na árvore de atributos</entry>
</row>
<row>
<entry></entry><entry></entry><entry>selection</entry><entry></entry>
<entry></entry><entry>O texto seleccionado será usado como origem</entry>
</row>
<row>
<entry></entry><entry></entry><entry>dcop</entry><entry></entry>
<entry></entry><entry>Será usado o resultado de um método de DCOP como origem</entry>
</row>
<row>
<entry>interface</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Necessita do 'source="dcop"'. A interface de DCOP a partir da qual o &quantaplus; irá buscar os dados de origem.</entry>
</row>
<row>
<entry>method</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Necessita do 'source="dcop"' e do nome de uma interface. O nome do método de DCOP a partir do qual o &quantaplus; irá buscar os dados de origem.</entry>
</row>
<row>
<entry>arguments</entry><entry>string</entry><entry></entry><entry></entry>
<entry>opcional</entry><entry>Necessita do 'source="dcop"', de uma interface e de um nome de um método. Os argumentos que são passados ao método. Poderá estar em branco ou aceitar o "%tagname%", que corresponde ao nome actual da marca.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="tooltip-3-2">
<title>tooltip</title>
<para>Define a dica para um campo na janela. Este elemento é apenas de texto. </para>
<note>
<para>De momento só é suportado texto simples (você não pode usar nenhuma formatação). </para>
</note>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>attr</entry>
<entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="whatsthis-3-2">
<title>whatsthis</title>
<para>Define a ajuda 'O Que É Isto?' para um campo da janela. Este elemento contém apenas texto. </para>
<note>
<para>De momento só é suportado texto simples (você não pode usar nenhuma formatação). </para>
</note>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>attr</entry>
<entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="list-3-2">
<title>list</title>
<para>Uma marca que apenas agrupa os itens de uma lista. Só pode aparecer uma vez por cada descrição de um atributo. Este é um elemento do tipo apenas para elementos. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>attr</entry>
<entry>item</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="item-3-2">
<title>item</title>
<para>Define um item da lista. Este elemento contém apenas texto. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>list</entry>
<entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="textlocation-3-2">
<title>textlocation</title>
<para>Indica a posição do atributo de uma marca dentro de uma janela. Esta marca só poderá ocorrer uma vez por cada atributo da janela (&ie; um por cada marca <attr>). Este elemento fica vazio. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry>
<entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>attr</entry>
<entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Atributo</entry><entry>Tipo</entry>
<entry>Utilização</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>row</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Indica a linha na disposição da janela de um campo ou legenda.</entry>
</row>
<row>
<entry>col</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Indica a coluna na disposição da janela para um campo ou uma legenda.</entry>
</row>
<row>
<entry>rowspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Indica o número de linhas que um campo poderá ocupar.</entry>
</row>
<row>
<entry>colspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Indica o número de colunas que um campo poderá ocupar.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="location-3-2">
<title>location</title>
<para>Indica a posição e o tamanho de um campo na janela. Esta marca só deverá aparecer uma vez por cada campo da janela (&ie; um por cada marca de <attr> e <label>). Este elemento fica vazio. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>label, attr</entry><entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Atributo</entry><entry>Tipo</entry>
<entry>Utilização</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>row</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Indica a linha na disposição da janela de um campo ou legenda.</entry>
</row>
<row>
<entry>col</entry><entry>nonNegativeInteger</entry>
<entry>necessário</entry><entry>Indica a coluna na disposição da janela para um campo ou uma legenda.</entry>
</row>
<row>
<entry>rowspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Indica o número de linhas que um campo poderá ocupar.</entry>
</row>
<row>
<entry>colspan</entry><entry>nonNegativeInteger</entry>
<entry>opcional</entry><entry>Indica o número de colunas que um campo poderá ocupar.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="text-3-2">
<title>text</title>
<para>Define o texto para uma legenda ou para uma opção. Este campo contém apenas texto. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>label, attr</entry><entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="children-3-2">
<title>children</title>
<para>Define uma lista dos elementos que podem aparecer dentro da marca a ser criada. Este elemento é do tipo apenas para elementos. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>tag</entry><entry>child</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="child-3-2">
<title>child</title>
<para>Define uma marca-filha. Este elemento fica vazio. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>children</entry><entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Atributo</entry><entry>Tipo</entry><entry>Valores</entry>
<entry>Utilização</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>name</entry><entry>string</entry><entry></entry>
<entry>necessário</entry><entry>Define uma marca que poderá aparecer dentro da marca indicada.</entry>
</row>
<row>
<entry>usage</entry><entry>string</entry><entry></entry>
<entry>opcional</entry><entry>Indica a relação com o pai.</entry>
</row>
<row>
<entry></entry><entry></entry><entry>necessário</entry>
<entry></entry><entry>O pai deverá ter pelo menos um filho com esse nome.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="stoppingtags-3-2">
<title>stoppingtags</title>
<para>Define uma lista dos elementos que obrigam a marca a terminar. Este elemento é do tipo apenas para elementos. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>tag</entry><entry>stoppingtag</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
<sect4 id="stoppingtag-3-2">
<title>stoppingtag</title>
<para>Define uma marca de interrupção ou de fecho. Este elemento fica vazio. </para>
<informaltable>
<tgroup cols="2">
<thead>
<row>
<entry>Pai(s)</entry><entry>Filhos</entry>
</row>
</thead>
<tbody>
<row>
<entry>stoppingtags</entry><entry><emphasis>NENHUM</emphasis></entry>
</row>
</tbody>
</tgroup>
</informaltable>
<informaltable>
<tgroup cols="4">
<thead>
<row>
<entry>Atributo</entry><entry>Tipo</entry>
<entry>Utilização</entry><entry>Descrição</entry>
</row>
</thead>
<tbody>
<row>
<entry>name</entry><entry>string</entry>
<entry>necessário</entry><entry>Indica quais as marcas que obrigam ao fecho de outra marca.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</sect4>
</sect3>
<sect3 id="tagxml-usage-3-2">
<title>Utilização do TagXML</title>
<para>Todos os ficheiros de TagXML deverão começar pela declaração de &XML;: <?xml version="1.0" encoding="UTF-8"?> e deverão estar devidamente aninhados e fechados. </para>
<important>
<para>Os espaços não afectam de facto em nada, mas tenha em atenção os caracteres & e <. Estes deverão ser substituídos provavelmente por &amp; e por &lt;, respectivamente, nos elementos como o <tooltip>, o <whatsthis> e o <text>. Se não o fizer não irá estoirar o programa, mas poderá fazer com que certos pedaços do seu trabalho desapareçam, nesse caso. </para>
</important>
</sect3>
<sect3 id="tagxml-validation-3-2">
<title>Validação do TagXML</title>
<para>Para validar os seus ficheiros TagXML, basta carregar na janela das <quote>Ferramentas</quote> no topo do &quantaplus; e seleccionar <quote>Validar o TagXML.</quote> Irá então aparecer uma janela na qual você terá apenas de seguir as indicações simples. </para>
<note>
<para>Esta funcionalidade de momento não está presente. Actualmente a validação ocorre quando os ficheiros TagXML são carregados no &quantaplus;. </para>
</note>
</sect3>
<sect3 id="tagxml-examples-3-2">
<title>Exemplos de TagXML</title>
<sect4 id="family-one-3-2">
<title>Família 1</title>
<para>O seguinte irá mostrar um ficheiro de TagXML da Família 1 válido. Este ficheiro descreve também o elemento <schema> do &XML; Schema da &W3C;. O nome do ficheiro para este ficheiro TagXML seria então schema.tag. Simples, não é? </para>
<informalexample>
<literallayout><markup>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE TAGS>
<TAGS>
<tag name="schema">
<label>
<text>id</text>
<location col="0" row="0"/>
</label>
<attr name="id" type="input">
<tooltip>Um ID único para o elemento.</tooltip>
<whatsthis>Um ID único para o elemento.</whatsthis>
<location col="1" row="0"/>
</attr>
<label>
<text>version</text>
<location col="0" row="1"/>
</label>
<attr name="version" type="input">
<tooltip>A versão do esquema.</tooltip>
<whatsthis>A versão do esquema.</whatsthis>
<location col="1" row="1"/>
</attr>
<label>
<text>targetNamespace</text>
<location col="0" row="2"/>
</label>
<attr name="targetNamespace" type="input">
<tooltip>Uma referência de &URI; para o espaço de nomes deste esquema.</tooltip>
<whatsthis>Uma referência de &URI; para o espaço de nomes deste esquema.</whatsthis>
<location col="1" row="2"/>
</attr>
<label>
<text>xmlns</text>
<location col="0" row="3"/>
</label>
<attr name="xmlns" type="input">
<tooltip>Uma referência de &URI; para um ou mais espaços de nomes a usar neste esquema.
Se não for usado nenhum prefixo, então as componentes desse espaço de nomes poderão ser usadas sem o prefixo.</tooltip>
<whatsthis>Uma referência de &URI; para um ou mais espaços de nomes a usar neste esquema.
Se não for usado nenhum prefixo, então as componentes desse espaço de nomes poderão ser usadas sem o prefixo.</whatsthis>
<location col="1" row="3"/>
</attr>
<label>
<text>attributeFormDefault</text>
<location col="0" row="4"/>
</label>
<attr name="attributeFormDefault" type="list">
<items>
<item>qualified</item>
<item>unqualified</item>
</items>
<tooltip>O formato por omissão para todos os atributos dentro deste esquema.</tooltip>
<whatsthis>O formato por omissão para todos os atributos dentro deste esquema.</whatsthis>
<location col="1" row="4"/>
</attr>
<label>
<text>elementFormDefault</text>
<location col="0" row="5"/>
</label>
<attr name="elementFormDefault" type="list">
<items>
<item>qualified</item>
<item>unqualified</item>
</items>
<tooltip>O formato por omissão para todos os elementos dentro deste esquema.</tooltip>
<whatsthis>O formato por omissão para todos os elementos dentro deste esquema.</whatsthis>
<location col="1" row="5"/>
</attr>
<label>
<text>blockDefault</text>
<location col="0" row="6"/>
</label>
<attr name="blockDefault" type="input">
<location col="1" row="6"/>
</attr>
<label>
<text>finalDefault</text>
<location col="0" row="7"/>
</label>
<attr name="finalDefault" type="input">
<location col="1" row="7"/>
</attr>
</tag>
</TAGS>
</markup>
</literallayout>
</informalexample>
</sect4>
<sect4 id="family-two-3-2">
<title>Família 2</title>
<para>O seguinte irá mostrar-lhe um ficheiro TagXML da Família 2 válido. Este ficheiro descreve a função 'overload' do &PHP;. O nome do ficheiro TagXML seria overload.tag. </para>
<informalexample>
<literallayout><markup>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE tags>
<tags>
<tag name="overload" type="function" returnType="void">
<attr name="class_name" type="string" status="optional"/>
</tag>
</tags>
</markup>
</literallayout>
</informalexample>
</sect4>
</sect3>
</sect2>
<sect2 id="descriptionrc-3-2">
<title>&descriptionrc;</title>
<para>O ficheiro &descriptionrc; também é bastante simples e existe um editor para ele, acessível através da opção <menuchoice><guimenu>DTD</guimenu><guimenuitem>Editar a Configuração da DTD</guimenuitem></menuchoice>. Isto irá editar o &descriptionrc; de um &DTEP; que você poderá seleccionar numa lista. Para editar o &descriptionrc; para um &DTEP; acabado de criar, deverá criar um único &descriptionrc; com os seguintes itens: </para>
<para>
<informalexample>
<literallayout><markup>
[General]
Version = Use 1 para o &quantaplus; versão <=3.1.2 e 2 para as versões posteriores.
Name = Texto de definição da DTD. (-//&W3C;//DTD HTML 4.01 Transitional//EN)
NickName = O nome bonito da DTD. (HTML 4.01 Transitional). Se não estiver definido, o Name é usado como NickName.
</markup>
</literallayout>
</informalexample>
</para>
<para>Logo que o tenha criado e colocado junto com os ficheiros de marcas, carregue o &DTEP; acabado de criar com a opção <menuchoice><guimenu>DTD</guimenu><guimenuitem>Carregar o Pacote de DTD (DTEP)</guimenuitem></menuchoice> e, depois de carregado, você poderá prosseguir com a edição da configuração do &DTEP;. Verifique as dicas e o texto 'o que é isto' na janela do editor para compreender o significado de cada item. Em alternativa, poderá ler o ficheiro <filename>quanta/data/dtep/dtd-description.txt</filename> do pacote de código, que contém uma descrição do formato. </para>
</sect2>
</sect1>
<sect1 id="user-actions">
<title>Acções Definidas pelo Utilizador</title>
<para>As acções são muito comuns em todas as aplicações. Você necessita delas com frequência quando usa qualquer aplicação. Se carregar num ícone da barra de ferramentas, seleccionar um item do menu ou usar um atalho de teclado irá normalmente executar uma acção. No &quantaplus;, as acções são levadas a um outro nível. Em vez de ter as acções implementadas de forma estanque (criadas pelo programador da aplicação ao nível do código-fonte), é possível para um utilizador normal criar e modificar acções e, deste modo, adicionar novas funcionalidades ao &quantaplus;. Estas são as acções definidas pelo utilizador; muitas das acções normais do &quantaplus; são definidas pelo utilizador (e modificáveis pelo mesmo). </para>
<para>Existem três tipos de acções definidas pelo utilizador: <itemizedlist>
<listitem><para><link linkend="text-actions">Acções de texto</link></para></listitem>
<listitem><para><link linkend="tag-actions">Acções de marcas</link></para></listitem>
<listitem><para><link linkend="script-actions">Acções de programas</link></para></listitem>
</itemizedlist>
</para>
<sect2 id="creating-actions">
<title>Criar acções</title>
<para>Poderá criar uma acção se for a <menuchoice> <guimenu>Configuração</guimenu> <guimenuitem>Configurar as Acções</guimenuitem> </menuchoice>. Carregue em <guibutton>Nova Acção</guibutton> para que lhe apareça uma janela semelhante: <mediaobject> <imageobject>
<imagedata fileref="dtep_doc_img7.png" format="PNG"/>
</imageobject>
</mediaobject>
<variablelist>
<varlistentry>
<term><guilabel>Tipo</guilabel></term>
<listitem><para>Define o tipo da acção (<link linkend="text-actions">Texto</link>, <link linkend="tag-actions">Marca</link>, <link linkend="script-actions">Programa</link>).</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Texto</guilabel></term>
<listitem><para>O nome da acção visível para o utilizador.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>O botão perto da legenda do <guilabel>Texto</guilabel></term>
<listitem><para>O ícone atribuído a esta acção. Carregue nele para mudar o ícone actual.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Dica</guilabel></term>
<listitem><para>Uma breve descrição do que a acção faz.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Atalho</guilabel></term>
<listitem><para>O atalho atribuído a esta acção. Carregue em <guilabel>Personalizado</guilabel> ou no botão perto de <guilabel>Personalizado</guilabel> para atribuir um atalho; carregue em <guilabel>Nenhum</guilabel> para remover o atalho atribuído de momento.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Barras de Ferramentas de Contentores</guilabel></term>
<listitem><para>As barras de ferramentas definidas pelo utilizador onde esta acção irá aparecer. Veja em <xref linkend="creating-toolbars-3-2"/>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Configuração Detalhada</guilabel></term>
<listitem><para>A configuração específica para o tipo diferente de acções. Veja em baixo. </para></listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
<sect2 id="text-actions">
<title>Acções de texto</title>
<para>
<mediaobject><imageobject>
<imagedata fileref="text-action.png" format="PNG"/>
</imageobject></mediaobject> As acções mais simples. Poderá indicar algum texto na <guilabel>Configuração Detalhada</guilabel> e, sempre que a acção for executada, este texto será inserido no seu documento, na posição actual do cursor. Veja o exemplo em baixo. </para>
</sect2>
<sect2 id="tag-actions">
<title>Acções de marcas</title>
<para>É útil para introduzir marcas de XML, mas claro que as poderá usar para outros fins. <mediaobject><imageobject> <imagedata fileref="tag-actions.png" format="PNG"/> </imageobject></mediaobject> <variablelist> <varlistentry> <term><guilabel><marca></guilabel></term> <listitem><para>O nome da marca.</para></listitem> </varlistentry> <varlistentry> <term><guilabel></marca></guilabel></term> <listitem><para>Se estiver assinalado, quando a acção for executada, este texto será inserido como uma marca de fecho. Se existir alguma área seleccionada no documento, antes de você executar a acção, a <marca> será inserida antes da área seleccionada e a </marca> a seguir.</para></listitem> </varlistentry> <varlistentry> <term><guilabel>Correr o "Editar a marca" se disponível</guilabel></term> <listitem><para>Se estiver assinalada e existir um ficheiro tagXML para esta marca, irá aparecer uma janela de edição da marca antes de a introduzir dentro do documento, para que possa definir os atributos da mesma.</para></listitem> </varlistentry> </variablelist> A <marca> e a </marca> serão introduzidas tal e qual as indicou aí. O <, o > ou o sinal de / não serão adicionados automaticamente. </para>
</sect2>
<sect2 id="script-actions">
<title>Acções de programas</title>
<para>
<mediaobject><imageobject>
<imagedata fileref="script-action.png" format="PNG"/>
</imageobject></mediaobject> O tipo de acção mais poderoso. Com a ajuda desta acção, poderá executar aplicações externas (normalmente programas, embora não esteja limitado a estes), que poderão alterar o seu documento ou usá-lo (ou parte deste) como dados de entrada. Os exemplos do próprio &quantaplus; são a janela de <guibutton>Introdução</guibutton> e as várias acções de <guilabel>Ver Em...</guilabel> dos DTEPs de (X)HTML. </para>
<para>Primeiro, terá de introduzir o nome do seu programa, acompanhado do interpretador. Exemplo: <command>sh /home/aMinhaArea/oMeuPrograma.sh</command>. </para>
<para>Ainda que possa usar localizações completas, a forma recomendada será usar a variável <command>%scriptdir</command> na linha de comandos, como por exemplo <command>sh %scriptdir/oMeuPrograma.sh</command>. Desta forma, o &quantaplus; irá tentar localizar o seu programa nos seguintes locais: <itemizedlist> <listitem><para>pasta de programas globais: <filename><envar>$TDEDIR</envar>/share/apps/quanta/scripts</filename></para></listitem> <listitem><para>pasta de programas locais: <filename><envar>$TDEHOME</envar>/share/apps/quanta/scripts</filename></para></listitem> <listitem><para>a sua 'path': <envar>$PATH</envar></para></listitem> </itemizedlist> Existem outras variáveis especiais que poderá usar na linha de comandos: <itemizedlist>
<listitem><para><command>%f</command>: será substituída pelo URL do documento actual. No caso dos documentos locais, o 'file:/' será retirado do documento.</para></listitem>
<listitem><para><command>%input</command>: será substituído pela entrada seleccionada. Veja em baixo.</para></listitem>
<listitem><para><command>%projectbase</command>: será substituído pelo URL do projecto actual. Estará em branco se não estiver nenhum projecto carregado.</para></listitem>
<listitem><para><command>%pid</command>: será substituído pelo PID do processo do &quantaplus; em execução. Se o &quantaplus; estiver a correr em modo único, o texto "único " será colocado antes do número do PID. É útil quando você usa o DCOP para controlar o &quantaplus; a partir do programa externo.</para></listitem>
<listitem><para><command>%userarguments</command>: é útil no caso dos eventos. Este item será substituído pelas propriedades do evento na seguinte ordem: <variablelist>
<varlistentry>
<term>Primeiro argumento</term>
<listitem><para>O identificador único do 'script'</para></listitem>
</varlistentry>
<varlistentry>
<term>Segundo argumento</term>
<listitem><para>o nome do evento</para></listitem>
</varlistentry>
<varlistentry>
<term>Terceiro argumento</term>
<listitem><para>os parâmetros do evento, sendo normalmente o nome do documento actual ou a localização do ficheiro do projecto.</para></listitem>
</varlistentry>
</variablelist>
</para></listitem>
</itemizedlist>
</para>
<para>Para além dos métodos normais, o programa poderá receber dados à entrada do &quantaplus; no 'standard input'. Na lista <guilabel>Entrada</guilabel>, poderá seleccionar o que é enviado para o 'standard input'. As opções são: <itemizedlist>
<listitem><para><guilabel>Nenhum</guilabel>: não é enviado nada para o programa.</para></listitem>
<listitem><para><guilabel>Documento actual</guilabel>: é enviado o documento inteiro para o programa.</para></listitem>
<listitem><para><guilabel>Texto seleccionado</guilabel>: a área seleccionada do documento é enviada para o programa. A utilização da variável <command>%input</command> faz normalmente sentido só quando se usa esta opção.</para></listitem>
</itemizedlist>
</para>
<para>De forma semelhante à <guilabel>Entrada</guilabel>, você poderá capturar o resultado da aplicação executada. Existem dois tipos de saídas: <itemizedlist> <listitem><para>a saída normal, que é impressa no 'standard output';</para> </listitem> <listitem><para>as mensagens de erro, que são impressas no 'standard error'.</para> </listitem> </itemizedlist> Poderá indicar o que deverá acontecer ao texto impresso para o 'standard output'. Isto pode ser feito se modificar o valor da lista da <guilabel>Saída</guilabel>: <itemizedlist>
<listitem><para><guilabel>Nenhum</guilabel>: o resultado da aplicação é ignorado.</para></listitem>
<listitem><para><guilabel>Inserir na posição do cursor</guilabel>: o resultado será inserido no documento actual, mais concretamente na posição do cursor.</para></listitem>
<listitem><para><guilabel>Substituir a selecção</guilabel>: a área seleccionada no documento será substituída pelo resultado.</para></listitem>
<listitem><para><guilabel>Substituir a selecção</guilabel>: a área seleccionada no documento será substituída pelo resultado.</para></listitem>
<listitem><para><guilabel>Criar um novo documento</guilabel>: será criado um novo documento que irá conter o resultado do programa.</para></listitem>
<listitem><para><guilabel>Substituir o documento actual</guilabel>: o documento inteiro será substituído pelo resultado.</para></listitem>
<listitem><para><guilabel>Janela de mensagem</guilabel>: o resultado irá aparecer na área de <guilabel>Mensagens</guilabel>.</para></listitem>
</itemizedlist>
</para>
<para>As escolhas para o resultado do 'standard error' (<guilabel>Erros</guilabel>) são as mesmas que para o resultado normal.</para>
</sect2>
</sect1>
<sect1 id="creating-toolbars-3-2">
<title>Criação de Barras de Ferramentas</title>
<para>O seguinte irá mostrar como criar barras de ferramentas para um &DTEP;. As barras de ferramentas são elementos gráficos que se encontram associados a acções. As acções no &quantaplus; são a base para praticamente todas as extensões que o &quanta; tem e que irá adquirir no futuro. O mesmo mecanismo que define uma acção no &quanta; activa a auto-completação e as janelas de 'tags'. Com as acções, o limite do que poderá fazer é virtualmente nulo. Para poder ver um exemplo, iremos usar o <ulink url="http://tidy.sf.net">&HTML; tidy</ulink> nas nossas páginas Web. </para>
<sect2 id="from-scratch-to-complete-3-2">
<title>Do Zero Até uma Versão Completa</title>
<para>Para começar, você irá precisar de criar uma barra de ferramentas do utilizador. Seleccione a opção <menuchoice> <guimenu>Barras de Ferramentas</guimenu> <guimenuitem>Adicionar uma Barra de Ferramentas do Utilizador</guimenuitem> </menuchoice>. </para>
<para>Se existirem várias marcas para a linguagem de formatação, recomenda-se que você divida as marcas em grupos lógicos. Irá precisar de criar uma nova barra de ferramentas do utilizador para cada grupo. Neste caso, não existem muitas, por isso vamos criar apenas uma barra de ferramentas e dar-lhe o nome da formatação. </para>
<para>Logo que todas as suas barras de ferramentas forem criadas, você precisa adicionar e configurar as acções. Para o fazer, seleccione <menuchoice> <guimenu>Configuração</guimenu> <guimenuitem>Configurar as Acções</guimenuitem> </menuchoice> <emphasis> </emphasis>. </para>
<para>As componentes desta janela são relativamente intuitivas. Carregue no botão <guibutton>Nova acção</guibutton> no fundo da janela para entrar no modo de edição. </para>
<para>Preencha todos os campos necessários e adicione a marca à(s) barra(s) de ferramentas apropriada(s). </para>
<para>Complete o resto e, se a marca tiver atributos e planeia usá-los sempre, assinale a opção <guilabel>Correr a janela "Editar a marca" se disponível </guilabel> de modo a que não tenha de ser avisado de cada vez que a acção é usada. </para>
<para>Agora você deverá ter algo muito semelhante ao seguinte. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img7.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Carregue no botão <guibutton>Aplicar</guibutton> para ver a acção adicionada à barra ou barras de ferramentas que seleccionou. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img8.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Ui! Este é um ícone horrível. Como é que você próprio e os outros irão recordar que aquele ícone corresponde a aquela acção? Vamos substitui-lo antes que haja problemas. </para>
<para>Para criar um ícone que descreva de forma mais adequada essa acção, nós iremos usar o &kiconedit;. Seleccione-o no &kmenu;, <menuchoice> <guisubmenu>Gráficos</guisubmenu> <guisubmenu>Mais Programas</guisubmenu> </menuchoice> (ou onde quer qe a sua distribuição o tenha posto). </para>
<para>O &kiconedit; usa por omissão o tamanho de 32x32 pixels, mas nós precisamos do tamanho 22x22. Para o alterar, seleccione <menuchoice> <guimenu>Editar</guimenu> <guimenuitem>Redimensionar</guimenuitem> </menuchoice>. </para>
<para>Lembre-se que você está a criar um ícone que o irá ajudar não só a si a lembrar o objectivo daquela acção, mas também aos outros utilizadores do &DTEP;. </para>
<para>Dado que a marca para a qual estou a criar o ícone se chama <quote>iniciar,</quote> decidi criar um ícone de <quote>sinal de Iniciar.</quote> Ao usar a cor verde (o verde é normalmente interpretado como <quote>seguir,</quote> <quote>iniciar,</quote> ou <quote>prosseguir</quote>) irá, ou pelo menos é suposto, fornecer ao utilizador uma mensagem de que, se carregar nesta acção, irá colocar a marca de <inicio> no documento actual. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img15.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Agora que terminei a criação do ícone, vou então gravá-lo. </para>
<para>Logo que tenha acabado de criar o ícone ou ícones, você precisa associar o ícone à acção. Para o fazer, abra a <menuchoice> <guimenu>Configuração</guimenu> <guimenuitem>Configurar as Acções</guimenuitem> </menuchoice> de novo (no &quantaplus;) e seleccione a acção para a qual criou o ícone. Para além do campo de <guilabel>Texto</guilabel>, você irá ver um botão; neste momento, carregue no mesmo. </para>
<para>Seleccione <guilabel>Outros Ícones</guilabel> e carregue então no botão <guibutton>Escolher</guibutton>. </para>
<para>Vá para a pasta na qual gravou o ícone, seleccione o mesmo e carregue em <guibutton>OK</guibutton>. </para>
<para>Carregue no botão <guibutton>Aplicar</guibutton> e poderá então continuar a fazer o mesmo com as outras marcas, se existirem, ou poderá então carregar em <guibutton>OK</guibutton> para terminar. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img18.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Digamos que você desejaria adicionar mais algumas funções comuns do &quantaplus; à sua barra de ferramentas ou então acharia que a barra de ferramentas ficaria melhor se ficasse arrumada com alguns separadores para agrupar as acções. Abra a janela de <guilabel>Configurar as Barras de Ferramentas</guilabel> indo à opção <menuchoice> <guimenu>Configuração</guimenu> <guimenuitem>Configurar as Barras de Ferramentas</guimenuitem> </menuchoice>. Certifique-se que a sua barra de ferramentas está seleccionada. </para>
<para>Irei então escolher o separador (em cima na coluna da esquerda) para a minha barra de ferramentas. Logo que você tenha seleccionado o item que deseja adicionar à sua barra de ferramentas, carregue no botão com a seta para a direita. Isto irá adicioná-lo à sua barra de ferramentas. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img21.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Penso que gostaria de uma forma mais rápida de aceder à <guilabel>Antevisão no Konqueror</guilabel>. Irei então seleccioná-la e adicioná-la à barra de ferramentas. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img22.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Repare como o separador ajuda a agrupar. Alguém que não conhecesse bem a minha barra de ferramentas poderia ter pensado que o botão do &konqueror; seria semelhante ou o oposto do botão de início. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img23.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Aplique as suas alterações e, quando tiver terminado, carregue em <guibutton>OK</guibutton> para terminar. </para>
<para>Ah, veja a nova e fantástica barra de ferramentas! Muito mais útil agora. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img24.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Lembre-se de testar a sua barra de ferramentas, carregando em todos os botões, de modo a que saiba que o resultado é o correcto. </para>
<mediaobject>
<imageobject>
<imagedata fileref="dtep_doc_img25.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Agora, para gravar a barra de ferramentas, iremos seleccionar a opção <menuchoice> <guimenu>Barras de Ferramentas</guimenu> <guisubmenu>Gravar as Barras de Ferramentas</guisubmenu> <guimenuitem>Gravar como Barra de Ferramentas Local</guimenuitem> </menuchoice>. </para>
<para>Grave-a na pasta correcta. Dado que a NeXML não existe, irei tê-la apenas na pasta de topo, mas as suas barras de ferramentas deverão ser gravadas na pasta correcta. Certifique-se que ajusta o seu &descriptionrc; para que este carregue as mesmas barras de cada vez que um ficheiro desse tipo é criado. </para>
</sect2>
</sect1>
<sect1 id="creating-quanta-docs-3-2">
<sect1info>
<title>Criar os Seus Próprios Documentos</title>
<authorgroup>
<author><firstname>Robert</firstname> <surname>Nickel</surname> <affiliation> <address><email>[email protected]</email></address>
</affiliation>
</author>
<othercredit role="translator"><firstname>Pedro</firstname><surname>Morais</surname><affiliation><address><email>[email protected]</email></address></affiliation><contrib>Tradução</contrib></othercredit>
</authorgroup>
</sect1info>
<title>Criar os Seus Próprios Documentos</title>
<para>Provavelmente as adições mais notáveis ao &quantaplus; para o utilizador geral serão a inclusão de documentação para a linguagem de formatação ou de 'scripting' que gostar mais. Para tal, este capítulo irá explicar como é que eu crio a árvore de documentação de &PHP; para o meu uso pessoal. </para>
<para>Antes de começar a criar a sua própria documentação, poderá querer ver o <ulink url="http://quanta.sf.net/main1.php?contfile=resource">repositório do &quantaplus;</ulink> para ver se alguém já a criou. </para>
<para>Existem duas partes neste processo. Primeiro, deverá obter a documentação existente para a linguagem em questão que está à procura. Em segundo lugar, terá de criar o ficheiro <filename>docrc</filename>. O primeiro é segundo o seu critério, enquanto o último passo será debatido aqui. </para>
<para>O formato geral do 'docrc' é o seguinte: </para>
<informalexample>
<literallayout>#Ficheiro de Configuração do KDE
[Tree]
Doc dir=<directoria relativa a este ficheiro onde estão os ficheiros de HTML da documentação> p.ex. php42/
#elementos do nível de topo
Top Element=<A sua descrição destes documentos> p.ex. documentação do PHP 4.2
Secção 1=Secção1.html
Secção 2=#Sec2.1,#Sec2.2,#Sec2.3
Sec2.1=Sec2.1.html
Sec2.2=Sec2.2.html
Sec2.3=Sec2.3.html
...
[Context]
ContextList=func1,func2,tag1,tag2,tag3
func1=func1.html
func2=func2.html
tag1=tag1.html
tag2=tag2.html
tag3=tag3.html
</literallayout>
</informalexample>
<para>O <filename>docrc</filename> está repartido em duas secções: Tree (árvore) e Context (contexto). </para>
<para>A secção Tree define o aspecto da apresentação da documentação na página respectiva. Por exemplo, poderá ver na documentação de &PHP; que tem algo do género do seguinte: </para>
<mediaobject>
<imageobject>
<imagedata fileref="doc-view1.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>Relacionando isto com o descrito em cima, o meu ficheiro <filename>docrc</filename> de &PHP; fica semelhante ao seguinte: </para>
<informalexample>
<literallayout>#Ficheiro de Configuração do KDE
[Tree]
Doc dir=php42/
#elementos do nível de topo
Top Element=Documentação do PHP 4.2
documentação do PHP 4.2=Índice,#Introdução,#Referência da Linguagem
Índice=index.html
Introdução=Introduction, ...
Apresentação=introduction.html
...
Referência da Linguagem=Sintaxe básica, ...
Sintaxe básica=linguagem.sintaxe-basica.html
...
</literallayout>
</informalexample>
<para> Repare no <literal>#</literal> antes da <quote>Introdução</quote> e <quote>Referência da Linguagem</quote>. Isto indica que estes são sub-títulos na árvore e que tem conteúdo próprio. Não creio que haja um limite para a profundidade do conjunto (excepto a que é definida pela sanidade) - use segundo o seu critério. </para>
<para>Para o Índice, irá reparar que este referencia directamente um ficheiro (e, como consequência, irá aparecer no fundo da árvore — com as pastas primeiro!). </para>
<important>
<para>Os espaços não afectam de facto em nada, mas tenha em atenção os caracteres & e <. Estes deverão ser substituídos provavelmente por &amp; e por &lt;, respectivamente, em todos os ficheiros de recursos de &XML; do &quantaplus;. </para>
</important>
<para>A secção Context é a secção do ficheiro 'docrc' que é usada para facilitar a ajuda dependente do contexto. Por exemplo, você está a fazer um programa em &PHP; e deseja ver a documentação para a função <function>mysql_fetch_array</function>. Basta você seleccionar a função e carregar então em <keycombo action="simul">&Ctrl;<keycap>H</keycap> </keycombo> para obter a ajuda de contexto. A documentação do <function>mysql_fetch_array</function> irá aparecer imediatamente. Existem apenas dois tipos de itens aqui: o ContextList e as linhas de associações de ficheiros. </para>
<variablelist>
<varlistentry>
<term>ContextList</term>
<listitem>
<para>Muito simplesmente, isto é apenas uma lista separada por vírgulas dos itens de contexto que você deseja ter disponíveis (para o &PHP;, estas serão as funções de &PHP;). </para>
</listitem>
</varlistentry>
<varlistentry>
<term>Linhas de associação de ficheiros</term>
<listitem>
<para>Estas estão no formato de item de contexto=página HTML de documentação, ⪚ acos=funcao.acos.html </para>
</listitem>
</varlistentry>
</variablelist>
<para>Uma versão muito resumida da minha secção Context do <filename>docrc</filename> encontra-se a seguir: </para>
<informalexample>
<literallayout>#Palavras-chave para a ajuda de contexto
[Context]
ContextList=abs,acos,acosh,addcslashes,addslashes,...
abs=funcao.abs.html
acos=funcao.acos.html
acosh=funcao.acosh.html
addcslashes=funcao.addcslashes.html
addslashes=funcao.addslashes.html
...
</literallayout>
</informalexample>
<para>Agora poderá gravar o seu ficheiro <filename>docrc</filename>, colocá-lo na pasta <filename class="directory"> $<envar>HOME</envar>/.trinity/share/apps/quanta/doc</filename> ou em <filename class="directory"> $<envar>TDEDIR</envar>/share/apps/quanta/doc</filename> para o uso local ou global, respectivamente. Crie então uma pasta (a especificada no seu ficheiro 'docrc') na mesma pasta que no seu ficheiro 'docrc' e copie as suas páginas de documentação em &HTML; para lá. </para>
<para>Terá de reiniciar o &quantaplus; para poder então ver a sua documentação. </para>
<para>Logo que tenha a certeza que eles ficaram bem e que vale a pena serem partilhados, envie o ficheiro <filename>docrc</filename> em conjunto com uma descrição com todas as informações pertinentes da documentação que usou no <ulink url="http://quanta.sf.net/main1.php?contfile=resource">repositório do &quantaplus;</ulink> para ser usado pela comunidade do &quanta;. Não irá ficar rico, mas ficará satisfeito de certeza em saber que contribuiu para a melhor plataforma de programação Web existente. </para>
</sect1>
<sect1 id="sharing-resources">
<title>Partilhar Recursos</title>
<para>Com o &quantaplus;, você não está sozinho. É possível partilhar os vários recursos (pacotes DTEP, barras de ferramentas com acções, programas, modelos) com outras pessoas. Existem duas formas de o fazer: </para>
<variablelist>
<varlistentry>
<term>Enviar por E-mail</term>
<listitem><para>Os recursos poderão ser enviados por e-mail para os seus amigos, colegas ou para quem você quiser. Irá ver os itens de menu <guilabel>Enviar por E-mail</guilabel> em vários sítios, como o <menuchoice><guimenu>DTD</guimenu><guimenuitem>Enviar o Pacote de DTD (DTEP) por E-mail</guimenuitem></menuchoice>, <menuchoice><guimenu>Barras de Ferramentas</guimenu><guimenuitem>Enviar a Barra de Ferramentas por E-mail</guimenuitem></menuchoice>, no menu de contexto dos ficheiros e pastas dos e na árvore de <guilabel>Modelos</guilabel> e <guilabel>'Scripts'</guilabel>. </para></listitem>
</varlistentry>
<varlistentry>
<term>Enviar para o servidor principal</term>
<listitem><para>Os recursos podem ser remetidos para o nosso repositório principal, a partir do qual todos os outros utilizadores do &quantaplus; os poderão obter. Os envios são revistos e disponibilizados, se a nossa equipa considerar que estão correctos e são úteis. Para fazer um envio válido, sugere-se que assine os recursos, pelo que irá necessitar de uma chave de GPG/PGP. Esta informação é usada para verificar a origem dos recursos, tanto pela nossa equipa como por quem irá obter os recursos.</para>
<para>Para saber como obter os recursos do servidor principal, veja em <xref linkend="download-resources"/>.</para>
<para>Ao enviar, ser-lhe-á pedido para indicar a senha da sua chave privada de GPG (a senha não será gravada) ou, no caso de ter mais chaves privadas, poderá escolher a que deseja usar. Na janela para <guilabel>Partilhar Coisas Novas</guilabel>, preencha os campos de entrada (o <guilabel>URL de Antevisão</guilabel> poderá ficar em branco) e inicie o envio, carregando para tal em <guilabel>OK</guilabel>.</para>
<para>O envio poderá ser iniciado em <menuchoice><guimenu>DTD</guimenu><guimenuitem>Enviar o Pacote do DTD (DTEP)</guimenuitem></menuchoice>, <menuchoice><guimenu>Barras de Ferramentas</guimenu><guimenuitem>Enviar a Barra de Ferramentas</guimenuitem></menuchoice>, no menu de contexto dos ficheiros e pastas na árvore de <guilabel>Modelos</guilabel> e <guilabel>'Scripts'</guilabel>. </para>
</listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="download-resources">
<title>Obter os Recursos</title>
<para>É possível actualizar o seu &quantaplus; sem obter uma versão nova, obtendo os recursos novos como os pacotes DTEP, as barras de ferramentas com acções, modelos, 'scripts' e documentação. Uma possibilidade será que você obteve os recursos por e-mail ou a partir de um servidor Web; nesses casos, você terá de os instalar manualmente. Se teve sorte, você também obteve um programa de instalação no local de onde transferiu os recursos. Contudo, o &quantaplus; tem um servidor dedicado que mantém os recursos que não foram instalados na distribuição principal, devido aos seus tamanhos ou a utilizações pouco frequentes ou que foram contribuídos posteriormente pelos utilizadores, sendo estes recursos instalados automaticamente. Para obter esses recursos, use os vários itens de menu para <guilabel>Obter</guilabel>. Você poderá encontrá-los em <menuchoice><guimenu>DTD</guimenu><guimenuitem>Obter o Pacote de DTD (DTEP)</guimenuitem></menuchoice>, <menuchoice><guimenu>Barras de Ferramenta</guimenu><guimenuitem>Obter Barra de Ferramentas</guimenuitem></menuchoice>, no menu de contexto ou numa área vazia ou num item de topo nas árvores de <guilabel>Modelos</guilabel>, <guilabel>'Scripts'</guilabel> e <guilabel>Documentação</guilabel>. </para>
<para>Depois de obter um recurso, mas antes de o instalar, o &quantaplus; verifica se o recurso é válido, verificando a integridade e a assinatura. No caso de ocorrerem problemas, ele avisá-lo-á e você poderá decidir se deseja continuar ou não. Por favor reveja as janelas de avisos com cuidado. No caso de a integridade ser correcta e o recurso estar devidamente assinado, você irá obter à mesma uma janela de informação, para que possa ver quem criou o recurso. </para>
<para>
<caution><para>Certifique-se que instala os recursos, principalmente as barras de ferramentas e os 'scripts', apenas a partir de fontes de confiança!</para></caution>
</para>
</sect1>
<sect1 id="converting-dtd">
<title>Converter uma DTD para um &DTEP;</title>
<para>É possível trabalhar em linguagens de XML que não sejam suportadas de momento pelo &quantaplus; se criar um pacote DTEP. Contudo, a criação poderá levar bastante tempo, dado que poderá ter de indicar centenas de ficheiros de marcas no formato <link linkend="tagxml-3-2">tagXML</link>. Obviamente, existe uma forma melhor de o fazer, convertendo a DTD automaticamente para um pacote DTEP. </para>
<para>A conversão poderá ser iniciada a partir da opção do menu <menuchoice><guimenu>DTD</guimenu><guimenuitem>Carregar e Converter a DTD</guimenuitem></menuchoice>. Seleccione o ficheiro <filename>.dtd</filename> que define a DTD que deseja usar, onde irá ver a janela seguinte: <mediaobject> <imageobject>
<imagedata fileref="dtd-conversion.png" format="PNG"/>
</imageobject>
</mediaobject>
</para>
<para>Os itens são:</para>
<itemizedlist>
<listitem><para><guilabel>Nome da pasta-alvo:</guilabel>o &DTEP; acabado de criar irá parar, com este nome, à pasta <filename><envar>$TDEHOME</envar>/share/apps/quanta/dtep</filename>. </para>
</listitem>
<listitem><para><guilabel>Nome:</guilabel>: o nome (texto de definição) da DTD</para></listitem>
<listitem><para><guilabel>Nome alternativo:</guilabel>: o nome visível para o utilizador do &DTEP;</para></listitem>
<listitem><para><guilabel>Linha de definição do !DOCTYPE:</guilabel> o texto que deverá aparecer na marca !DOCTYPE, como por exemplo HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"</para></listitem>
<listitem><para><guilabel>URL da DTD</guilabel>: o URL que aponta para o ficheiro da DTD</para></listitem>
<listitem><para><guilabel>Extensão por omissão:</guilabel> a extensão que será usada normalmente para os ficheiros que foram escritos nesta DTD</para></listitem>
<listitem><para><guilabel>Marcas e atributos com distinção de maiúsculas:</guilabel> esta opção costuma estar assinalada para o caso das variantes da linguagem XML</para></listitem>
<listitem><para><guilabel>Afinar o DTEP após a conversão:</guilabel> se estiver assinalado, após a conversão, o &quantaplus; irá invocar o editor do &descriptionrc;, de modo a que você possa afinar alguns detalhes do &DTEP; acabado de criar. Recomenda-se que deixe esta opção assinalada.</para></listitem>
</itemizedlist>
</sect1>
</chapter>
|