« back to all changes in this revision
Viewing changes to doc/quanta/adv-quanta.docbook
- browse files at revision 27
- compare with another revision
- download diff
- download tarball
- view history from revision 27
- Committer: Bazaar Package Importer
- Author(s): Jonathan Thomas
- Date: 2009-02-27 16:13:02 UTC
- mfrom: (1.1.14 upstream)
- Revision ID: james.westby@ubuntu.com-20090227161302-1wc2m5nyuthzuxrv
Tags: 4:4.2.1-0ubuntu1
* New upstream release:
- Bump versions of build-depends
- Update an install file
- Bump versions of build-depends
- Update an install file
- files removed:
- doc/quanta
- files modified:
- CMakeLists.txt
added
removed
doc/quanta/adv-quanta.docbook
1
<?xml version="1.0" encoding="UTF-8" ?>
2
3
<chapter id="advanced-quanta-3-2">
4
<chapterinfo>
5
<title>Advanced Features</title>
6
<authorgroup>
7
<author>
8
<firstname>Christopher</firstname>
9
<surname>Hornbaker</surname>
10
<affiliation>
11
<address><email>chrishornbaker@earthlink.net</email></address>
12
</affiliation>
13
14
</author>
15
16
<!-- TRANS:ROLES_OF_TRANSLATORS -->
17
18
</authorgroup>
19
</chapterinfo>
20
21
<title>Advanced Features</title>
22
23
<para>
24
This chapter outlines the advanced features of &quantaplus; and how to use
25
them.
26
</para>
27
28
<sect1 id="xml-tools-3-2">
29
<title>&XML; Tools</title>
30
31
<para>
32
The 3.2 release of &quantaplus; brings with it many new &XML; tools and
33
features. The tools are unique in their integration within &quantaplus;.
34
All of these tools use <application>Kommander</application> as a front-end and
35
<application>libxml2</application> and <application>libxslt</application>
36
as a back-end. The combination of these makes for fast, efficient,
37
productive, and complete tools.
38
</para>
39
40
<sect2 id="kde-db-3-2">
41
<title>&kde; Documentation Tools</title>
42
43
<para>
44
&quantaplus; supports &kde;'s two main documentation tools:
45
<command>meinproc</command> and <command>checkXML</command>.
46
</para>
47
48
<sect3 id="meinproc-3-2">
49
<title><command>meinproc</command></title>
50
51
<para>
52
Anyone who has worked with &kde; documentation knows
53
<command>meinproc</command> and how superb it is. Well, take it up a notch
54
with a great graphical interface! No longer resort to a shell; just click
55
the icon that resembles a processor and you are done!
56
</para>
57
58
<variablelist>
59
<varlistentry>
60
<term><guilabel>Current Working Folder</guilabel></term>
61
<listitem>
62
<para>
63
This application expects an <filename>index.docbook</filename>
64
file to be present in a folder. If <filename>index.docbook</filename>
65
is in the current working folder, then simply leave <guilabel>Current Working
66
Folder</guilabel> checked. If it is not, then uncheck <guilabel>Current Working Folder</guilabel>
67
and enter the folder you wish to process in the <guilabel>Other Folder</guilabel> field.
68
</para>
69
</listitem>
70
</varlistentry>
71
</variablelist>
72
73
<note>
74
<para>
75
Outputted files are placed in the same folder as the sources files.
76
All &HTML; files are removed each time
77
<command>meinproc</command> is ran.
78
</para>
79
</note>
80
81
</sect3>
82
83
<sect3 id="checkxml-3-2">
84
<title><command>checkXML</command></title>
85
86
<para>
87
Again, anyone who has worked with &kde; documentation knows this
88
helpful application. Again, &quantaplus; provides a great little graphical
89
front-end to this one.
90
</para>
91
92
<variablelist>
93
<varlistentry>
94
<term><guilabel>Current Working Folder</guilabel></term>
95
<listitem>
96
<para>
97
If the currently opened file is the <filename>index.docbook</filename>
98
file, then simply leave <guilabel>Current Working Folder</guilabel> checked.
99
If it is not, then uncheck <guilabel>Current Working Folder</guilabel> and
100
enter the folder of where <filename>index.docbook</filename> can be found.
101
</para>
102
</listitem>
103
</varlistentry>
104
</variablelist>
105
106
<note>
107
<title>Output</title>
108
<para>
109
If there is output, then your file is invalid. Please correct the reported
110
errors and try again.
111
</para>
112
</note>
113
</sect3>
114
</sect2>
115
116
<sect2 id="xmlval-3-2">
117
<title>&XML; Validation</title>
118
119
<para>
120
&quantaplus; has a great &XML; validation tool, which uses a
121
<command>xmllint</command> back-end.
122
</para>
123
124
<variablelist>
125
<varlistentry>
126
<term><guilabel>Current File</guilabel></term>
127
<listitem>
128
<para>
129
If the file to be validated is currently focused on in &quantaplus;, then
130
simply leave <guilabel>Current File</guilabel> checked. If it is not, then
131
uncheck <guilabel>Current File</guilabel> and select the file to be
132
validated from the Other File file selector.
133
</para>
134
</listitem>
135
</varlistentry>
136
137
<varlistentry>
138
<term><guilabel>Well-formed Checking</guilabel></term>
139
<listitem>
140
<para>
141
If you only wish to know only if the file is well-formed, click the
142
<guilabel>Well-formed Checking Only</guilabel> check box.
143
</para>
144
</listitem>
145
</varlistentry>
146
147
<varlistentry>
148
<term><guilabel>Definition &URI;</guilabel></term>
149
<listitem>
150
<para>
151
If you are using a &DTD; and it is specified within the &XML; file, then
152
select &DTD; (Internal) (default), else select &DTD; (External) and locate
153
the &DTD; with the Definition &URI; file selector. Both &W3C; &XML;
154
Schema and RelaxNG validation are required to be
155
externally defined via the <guilabel>Definition &URI;</guilabel> file selector.
156
</para>
157
</listitem>
158
</varlistentry>
159
</variablelist>
160
</sect2>
161
162
<sect2 id="xsltproc-3-2">
163
<title>&XSL; Processing</title>
164
165
<para>
166
Yep, &quantaplus; has a &XSL; processing tool, too! This uses the
167
<command>xsltproc</command> tool provided with
168
<application>libxml2</application>.
169
</para>
170
171
<variablelist>
172
<varlistentry>
173
<term><guilabel>Current File</guilabel></term>
174
<listitem>
175
<para>
176
If the file to be processed is currently focused on in &quantaplus;, then
177
simply leave <guilabel>Current File</guilabel> checked. If it is not,
178
then uncheck <guilabel>Current File</guilabel> and select the file to be
179
processed from the <guilabel>Other File</guilabel> selector.
180
</para>
181
</listitem>
182
</varlistentry>
183
184
<varlistentry>
185
<term>Stylesheet</term>
186
<listitem>
187
<para>
188
Select the &XSL; file that you wish to be used.
189
</para>
190
</listitem>
191
</varlistentry>
192
193
<varlistentry>
194
<term><guilabel>Output file name</guilabel></term>
195
<listitem>
196
<para>
197
Enter the name of the file that you want the resulting file to be called.
198
File is outputed to your home folder by default.
199
</para>
200
</listitem>
201
</varlistentry>
202
</variablelist>
203
204
<note>
205
<para>
206
This application lacks flexibility. Sorry, we will do better next time.
207
</para>
208
</note>
209
</sect2>
210
211
</sect1>
212
213
<!-- <sect1 id="kfilereplace-3-2">
214
<title>KFileReplace</title>
215
216
<para>
217
KFileReplace is a terrific new addition to &quantaplus;. It allows one to
218
quickly replace strings over multiple files in only a few clicks of the
219
mouse. Imagine you have converted all your GIF images to PNG images
220
(hasn't everyone done this already?), only the extension has changed, and
221
you have the <img /> tag scattered throughout 50 XHTML files. Are you
222
going to do a Find & Replace on every file? Surely not when you can do
223
them all at the same time! This is only one of the many situations where
224
you will find KFileReplace a seriously helpful tool. This section will show
225
you how to use this wonderful feature.
226
</para>
227
228
<sect2 id="using-kfr-3-2">
229
<title>Using KFileReplace</title>
230
231
<para>
232
With all these wonderful features KFileReplace has, surely you are
233
incredibly interested in how to use it! Well, make sure your swim suit
234
is on tight, because we are about to dive in!
235
</para>
236
237
<sect3 id="start-kfr-3-2">
238
<title>Starting KFileReplace</title>
239
240
<para>
241
You will find KFileReplace in two places: &quantaplus;' main toolbar and the
242
menubar (Plugins -> KFileReplace). It is represented by this icon:
243
<inlinemediaobject>
244
<imageobject>
245
<imagedata fileref="kfr-icon.png" format="PNG" />
246
</imageobject>
247
</inlinemediaobject>.
248
By executing it from either location, you will be presented with the New
249
Search & Replace Project dialog.
250
</para>
251
252
<mediaobject>
253
<imageobject>
254
<imagedata fileref="kfr-new-dialog.png" format="PNG" />
255
</imageobject>
256
<caption><para>KFileReplace's New Search & Replace Project dialog.</para></caption>
257
</mediaobject>
258
259
</sect3>
260
261
<sect3 id="replace-string-kfr-3-2">
262
<title>Replacing Strings in Files Over Multiple Folders</title>
263
264
265
<para>
266
Your boss just gave word that:
267
268
<orderedlist numeration="arabic">
269
<listitem>
270
<para>all image formats will be PNG from now on;</para>
271
</listitem>
272
<listitem>
273
<para>all current images must be converted to PNG;</para>
274
</listitem>
275
<listitem>
276
<para>and it all needs to be done in one hour.</para>
277
</listitem>
278
</orderedlist>
279
280
<quote>One hour!?!?</quote> you think to yourself. <quote>It'll take at
281
least 45 minutes to convert the images!</quote> Calm down. Convert
282
the images, load up your project, and fire up KFileReplace. Filter for
283
only the file types you want to change. Press the <inlinemediaobject>
284
<imageobject><imagedata format="PNG" fileref="" /></imageobject>
285
</inlinemediaobject> and for, say GIF images, .gif for the string to
286
replace and .png for the replacement string.
287
</para>
288
289
</sect3>
290
</sect2>
291
</sect1> -->
292
293
<sect1 id="kparts-3-2">
294
<sect1info>
295
<title>Using Plugins</title>
296
<authorgroup>
297
<author>
298
<firstname>Mathieu</firstname>
299
<surname>Kooiman</surname>
300
<affiliation>
301
<address><email>quanta@map-is.nl</email></address>
302
</affiliation>
303
</author>
304
305
<!-- TRANS:ROLES_OF_TRANSLATORS -->
306
307
</authorgroup>
308
</sect1info>
309
310
<title>Using Plugins</title>
311
312
<sect2 id="what-is-a-plugin-3-2">
313
<title>What is a Plugin?</title>
314
315
<para>
316
&quantaplus; is able to load plugins, which are KParts. The
317
KPart framework is another very powerfull framework of &kde;. A KPart is a
318
relatively small, reusable container of functionality. It allows &kde;
319
developers to easily build on the work of other programmers. One
320
example of this is &quantaplus; itself. The editor &quantaplus; uses is
321
the &kate; KPart. The &kate; KPart already had a bunch of functionality that
322
&quantaplus; needed, like syntax highlighting. Integrating it into
323
&quantaplus; allowed the &quantaplus; developers to focus on what
324
&quantaplus; should be able to do, rather than facing the many problems
325
that developing a new editor KPart/component from scratch would bring.
326
</para>
327
328
<para>
329
The plugins &quantaplus; loads might have nothing to do with &quantaplus;
330
itself. This makes it a very powerful plugin system. You can benefit from
331
extra functionality and need not to wait until someone integrates it into
332
&quantaplus;! The plugins can be loaded into a number of &GUI; elements.
333
More on this below.
334
</para>
335
336
</sect2>
337
338
<sect2 id="plugin-dialog-3-2">
339
<title>Understanding the Edit Plugin Dialog</title>
340
341
<para>To install a Plugin or KPart we will work from the
342
<menuchoice>
343
<guimenu>Plugins</guimenu>
344
<guimenuitem>Edit</guimenuitem>
345
</menuchoice> menu. This will bring up the following dialog:
346
</para>
347
348
<mediaobject>
349
<imageobject>
350
<imagedata format="PNG" fileref="plugin-edit.png" />
351
</imageobject>
352
<caption><para>The Edit Plugin dialog.</para></caption>
353
</mediaobject>
354
355
<para>
356
This dialog lets you manage all defined plugins and lets you add new ones.
357
We will describe each &GUI; element in here:
358
359
<variablelist>
360
<varlistentry>
361
<term><guilabel>Search paths</guilabel></term>
362
<listitem>
363
<para>
364
Here you can fill in a search path. When adding a plugin without a
365
<guilabel>Location</guilabel>, &quantaplus; will search these paths to
366
find the plugin.
367
</para>
368
</listitem>
369
</varlistentry>
370
371
<varlistentry>
372
<term><guilabel>Add</guilabel></term>
373
<listitem>
374
<para>
375
This will bring up a dialog which allows you to add a new plugin.
376
</para>
377
</listitem>
378
</varlistentry>
379
380
<varlistentry>
381
<term><guilabel>Configure</guilabel></term>
382
<listitem>
383
<para>
384
This will allow you to change the settings of a particular plugin.
385
</para>
386
</listitem>
387
</varlistentry>
388
389
<varlistentry>
390
<term><guilabel>Remove</guilabel></term>
391
<listitem>
392
<para>
393
Removes the currently selected plugin.
394
</para>
395
</listitem>
396
</varlistentry>
397
398
<varlistentry>
399
<term><guilabel>Refresh</guilabel></term>
400
<listitem>
401
<para>
402
Refreshes the dialog's contents.
403
</para>
404
</listitem>
405
</varlistentry>
406
</variablelist>
407
</para>
408
<para>Read <xref linkend="configure-plugins" /> to learn more about plugins.</para>
409
</sect2>
410
</sect1>
411
<sect1 id="team-members">
412
<title>Team Development</title>
413
<para>Often a project has more than one people working on it and there is some kind of hierarchical relationsship between them. &quantaplus; supports the notion of team members and they are configurable in the
414
<menuchoice>
415
<shortcut>
416
<keycombo action="simul">&Shift;<keycap>F7</keycap></keycombo>
417
</shortcut>
418
<guimenu>Project</guimenu>
419
<guimenuitem>Project Properties</guimenuitem>
420
</menuchoice> dialog.
421
</para>
422
<mediaobject>
423
<imageobject>
424
<imagedata format="PNG" fileref="team-editing.png" />
425
</imageobject>
426
<caption><para>The team member editor dialog</para></caption>
427
</mediaobject>
428
<para>
429
The <guilabel>Name</guilabel>, <guilabel>Email</guilabel> entries are self explaining. <guilabel>Nickname</guilabel> is the nick of the user and acts as an unique identifier.
430
</para>
431
<para><guilabel>Role</guilabel> specifies the role of the member in the project and can be one of the following:
432
<itemizedlist>
433
<listitem><para>
434
<guilabel>Team leader</guilabel>
435
</para></listitem>
436
<listitem><para>
437
<guilabel>Subproject Leader</guilabel>
438
</para></listitem>
439
<listitem><para>
440
<guilabel>Task Leader</guilabel>
441
</para></listitem>
442
<listitem><para>
443
<guilabel>Simple Member</guilabel>
444
</para></listitem>
445
</itemizedlist>
446
</para>
447
<para><guilabel>Task</guilabel> is a description of the task assigned to this member.</para>
448
<para><guilabel>Subproject</guilabel>: you can select a list of subproject. Subprojects can be configured and created by pressing the <guilabel>Edit subprojects</guilabel> button. Each subproject has a user visible name and a location entry, the later specifying a relative path to a directory under the project tree. This means that a subproject is a directory under the main project. For example the main project can be the website of your company, while a subproject can be the website for the intranet, located under the <filename path="intranet">intranet</filename> folder in the project.</para>
449
<para>One member can have more than one role in the project, like both team leader and subproject leader.</para>
450
<para>The user should select who is himself from the list of the team members. This is possible by selecting a team member from the list and pressing the <guilabel>Set to Yourself</guilabel> button. The currently selected member (your identity) appears in bold after the <guilabel>You are:</guilabel> text.</para>
451
<para>Nicknames and setting yourself is important regarding messaging and annotations. See <xref linkend="annotations"/> to learn more about annotations.</para>
452
<para>Aside of keeping track of your team, there is one more benefit of setting up the team members: you can configure an event to inform the team leaders when some action happens. See <xref linkend="event-actions"/> about how to do it.</para>
453
</sect1>
454
<sect1 id="event-actions">
455
<title>Event Actions</title>
456
<para>Event actions are actions executed when some event happens in the project. An example would be logging when the project was opened and closed, so it can be later reviewed how much one worked on it, or sending a mail when a file is saved, or adding the file to the CVS with the help of a script when the file is added to the project and the list could continue.</para>
457
<para>On the <guilabel>Event Configuration</guilabel> page of the
458
<menuchoice>
459
<shortcut>
460
<keycombo action="simul">&Shift;<keycap>F7</keycap></keycombo>
461
</shortcut>
462
<guimenu>Project</guimenu>
463
<guimenuitem>Project Properties</guimenuitem>
464
</menuchoice> dialog you can create, edit and delete the event actions.
465
</para>
466
<mediaobject>
467
<imageobject>
468
<imagedata format="PNG" fileref="event-editing.png" />
469
</imageobject>
470
<caption><para>The event editor dialog</para></caption>
471
</mediaobject>
472
<para>The entries in the dialog are:</para>
473
<variablelist>
474
<varlistentry>
475
<term><guilabel>Event</guilabel></term>
476
<listitem><para>the action is executed when the event selected from the list happens. The event names are self explanatory.</para></listitem>
477
</varlistentry>
478
<varlistentry>
479
<term><guilabel>Action</guilabel></term>
480
<listitem><para>
481
the type of the executed action. The possible choices are
482
</para>
483
<variablelist>
484
<varlistentry>
485
<term><guilabel>Non-script action</guilabel></term>
486
<listitem><para>an action that is not a user defined script action. See <xref linkend="user-actions" /> for user action.
487
</para>
488
<para><guilabel>Action name</guilabel> specifies the action to be executed when the event happens.</para>
489
</listitem>
490
</varlistentry>
491
<varlistentry>
492
<term><guilabel>Send email</guilabel></term>
493
<listitem><para>an email is sent when the action happens to the recipient selected in the <guilabel>Receiver</guilabel> list. The recipient can be a team or subproject leader. See <xref linkend="team-members" /> for defining such leaders.
494
</para>
495
</listitem>
496
</varlistentry>
497
<varlistentry>
498
<term><guilabel>Log event</guilabel></term>
499
<listitem><para>the event is logged in a file. The arguments for this action are:
500
</para>
501
<variablelist>
502
<varlistentry>
503
<term><guilabel>Log file</guilabel></term>
504
<listitem><para>the filename with full path</para></listitem>
505
</varlistentry>
506
<varlistentry>
507
<term>Detail</term>
508
<listitem><para>How much information will the log contain</para></listitem>
509
</varlistentry>
510
<varlistentry>
511
<term><guilabel>Behavior</guilabel></term>
512
<listitem><para>Whether to create/overwrite the existing log file or append the new logged event to it.</para></listitem>
513
</varlistentry>
514
</variablelist>
515
</listitem>
516
</varlistentry
517
>
518
<varlistentry>
519
<term><guilabel>Script action</guilabel></term>
520
<listitem><para>an user defined script action. See <xref linkend="user-actions" /> for user action.
521
</para>
522
<para><guilabel>Action name</guilabel> specifies the action to be executed when the event happens.</para>
523
</listitem>
524
</varlistentry>
525
526
</variablelist>
527
</listitem>
528
</varlistentry>
529
</variablelist>
530
<para>The other entries depend on the <guilabel>Action</guilabel> type as they were described.
531
</para>
532
</sect1>
533
534
<sect1 id="annotations">
535
<title>Annotations</title>
536
<para>Annotations are special comments in the documents. They differ from regular comments by the following things:
537
<itemizedlist>
538
<listitem><para>
539
the information is collected by Quanta and shown in the <guilabel>Annotations</guilabel> toolview.
540
</para></listitem>
541
<listitem><para>
542
the information can be addressed to a team member
543
</para></listitem>
544
</itemizedlist>
545
</para>
546
<para>Entering annotations is simple. You can either use the <guilabel>Annotate</guilabel> entry from the editor context menu or enter the <emphasis>@annotation</emphasis> keyword in a comment area followed by the annotation text.
547
<example><title>Annotation example in XML</title><screen>
548
<!-- @annotation It is possible that this code is wrong. --></screen>
549
<screen>
550
<!-- @annotation
551
Multiline
552
annotation.
553
--></screen></example>
554
<example><title>Annotation example in PHP</title><screen>
555
/* @annotation
556
Use PHP comments when annotating a PHP area
557
*/</screen>
558
559
</example>
560
</para>
561
<para>Annotations can be addressed for a specific member of your team. The syntax in this case is <emphasis>@annotation(nickname)</emphasis> or <emphasis>@annotation(role)</emphasis>, where <emphasis>nickname</emphasis> is the nickname of a team member, while <emphasis>role</emphasis> is a project role from the following items:
562
<itemizedlist>
563
<listitem><para>
564
team leader
565
</para></listitem>
566
<listitem><para>
567
task leader
568
</para></listitem>
569
<listitem><para>
570
subproject leader
571
</para></listitem>
572
</itemizedlist>
573
The task and subproject leaders should be followed by the corresponding task and subproject name, like it is shown in the below examples.
574
</para>
575
<para>
576
<example><title>Make a note to a team member with the nickname <emphasis>eric</emphasis></title>
577
<screen><-- @annotation(eric) Eric, please look at this. Andras --></screen>
578
</example>
579
<example><title>Inform the team leader</title>
580
<screen><-- @annotation(team leader) This is very important for the team --></screen>
581
</example>
582
<example><title>Inform the <emphasis>PHP</emphasis> subproject leader</title>
583
<screen>// @annotation(subproject leader:PHP) What do you think about it?</screen>
584
</example>
585
</para>
586
<para>Nicknames and role names are case insensitive, but spaces around brackets and the <emphasis>:</emphasis> make the annotation invalid.</para>
587
<para>More about team members, roles and nicknames can be found in <xref linkend="team-members"/>.</para>
588
<para>
589
The annotations found in the project can be inspected in the <guilabel>Annotations</guilabel> view. It consists of tree tabs:
590
<variablelist>
591
<varlistentry>
592
<term><guilabel>Current File</guilabel></term>
593
<listitem><para>
594
The annotation found in the current file.</para></listitem>
595
</varlistentry>
596
597
<varlistentry>
598
<term><guilabel>For You</guilabel></term>
599
<listitem><para>
600
Annotations in the project addressed for you. The entries are groupped per file.
601
</para></listitem>
602
</varlistentry>
603
604
<varlistentry>
605
<term><guilabel>All Files</guilabel></term>
606
<listitem><para>
607
The annotations found in all the project files, groupe dy files
608
</para></listitem>
609
</varlistentry>
610
</variablelist>
611
The annotations are scanned on project and file load for external modifications. This way even is somebody adds an annotation outside of &quantaplus;, it will be recognized. As scanning can take some time, the information dialog about new annotations addressed for you might appear after some seconds of the project loading.
612
</para>
613
</sect1>
614
<!--<sect1 id="cvs-3-2">
615
<title>Using CVS</title>
616
617
<para>
618
&quantaplus; uses Cervisia for CVS. Explain its usage within &quantaplus;.
619
</para>
620
</sect1> -->
621
622
&debugging-quanta;
623
</chapter>
Loggerhead is a web-based interface for Breezy
Version: 2.0.1