Updated build-system. Does this help you khz?
[pinentry.git] / doc / en / index.docbook
1 <?xml version="1.0" ?>
2 <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.1-Based Variant V1.0//EN" "dtd/kdex.dtd" [
3   <!ENTITY kappname "&kpinentry;"><!-- replace kapp here -->
4   <!ENTITY % addindex "IGNORE">
5   <!ENTITY % English "INCLUDE"><!-- change language only here -->
6   
7   
8   <!-- Do not define any other entities; instead, use the entities
9        from kde-genent.entities and $LANG/user.entities. -->
10 ]>
11 <!-- kdoctemplate v0.8 October 1 1999 
12      Minor update to "Credits and Licenses" section on August 24, 2000
13      Removed "Revision history" section on 22 January 2001   -->
14
15 <!--
16 This template was designed by: David Rugge davidrugge@mindspring.com
17 with lots of help from: Eric Bischoff ebisch@cybercable.tm.fr
18 and Frederik Fouvry fouvry@sfs.nphil.uni-tuebingen.de
19 of the KDE DocBook team.
20
21 You may freely use this template for writing any sort of KDE documentation.
22 If you have any changes or improvements, please let us know.
23
24 In the future, we may want to change from SGML-based DocBook to XML-based
25 DocBook. To make this change easier, please be careful :
26 - in XML, the case of the <tags> and attributes is relevant ;
27 - also, quote all attributes.
28
29 Please don't forget to remove all these comments in your final documentation,
30 thanks ;-).
31 -->
32
33 <!-- ................................................................ -->
34
35 <!-- The language must NOT be changed here. -->
36
37 <book lang="&language;">
38
39 <!-- This header contains all of the meta-information for the document such
40 as Authors, publish date, the abstract, and Keywords -->
41
42 <bookinfo>
43 <title>The Kapp Handbook</title>
44
45 <authorgroup>
46 <author>
47 <firstname>George</firstname>
48 <othername>N.</othername>
49 <surname>Ugnacious</surname>
50 <affiliation>
51 <address><email>gnu@kde.org</email></address>
52 </affiliation>
53 </author>
54 </authorgroup>
55
56
57 <copyright>
58 <year>1999</year>
59 <year>2000</year>
60 <holder>George N. Ugnacious</holder>
61 </copyright>
62 <!-- Translators: put here the copyright notice of the translation -->
63 <!-- Put here the FDL notice.  Read the explanation in fdl-notice.docbook 
64      and in the FDL itself on how to use it. -->
65 <legalnotice>&FDLNotice;</legalnotice>
66
67 <!-- Date and version information of the documentation
68 Don't forget to include this last date and this last revision number, we
69 need them for translation coordination !
70 Please respect the format of the date (DD/MM/YYYY) and of the version
71 (V.MM.LL), it could be used by automation scripts.
72 Do NOT change these in the translation. -->
73
74 <date>03/04/1999</date>
75 <releaseinfo>1.01.00</releaseinfo>
76
77 <!-- Abstract about this handbook -->
78
79 <abstract>
80 <para>
81 &kpinentry; is an application specially designed to do nothing you would
82 ever want.
83 </para>
84 </abstract>
85
86 <!-- This is a set of Keywords for indexing by search engines.
87 Please at least include KDE, the KDE package it is in, the name
88  of your application, and a few relevant keywords. -->
89
90 <keywordset>
91 <keyword>KDE</keyword>
92 <keyword>kdeutils</keyword>
93 <keyword>Kapp</keyword>
94 <keyword>nothing</keyword>
95 <keyword>nothing else</keyword>
96 </keywordset>
97
98 </bookinfo>
99
100 <!-- The contents of the documentation begin here.  Label
101 each chapter so with the id attribute. This is necessary for two reasons: it
102 allows you to easily reference the chapter from other chapters of your
103 document, and if there is no ID, the name of the generated HTML files will vary
104 from time to time making it hard to manage for maintainers and for the CVS
105 system. Any chapter labelled (OPTIONAL) may be left out at the author's
106 discretion. Other chapters should not be left out in order to maintain a
107 consistent documentation style across all KDE apps. -->
108
109 <chapter id="introduction">
110 <title>Introduction</title>
111
112 <!-- The introduction chapter contains a brief introduction for the
113 application that explains what it does and where to report
114 problems. Basically a long version of the abstract.  Don't include a
115 revision history. (see installation appendix comment) -->
116
117 <para>
118 &kpinentry; is a program that lets you do absolutely nothing. Please report
119 any problems or feature requests to the KDE mailing lists.
120 </para>
121 </chapter>
122
123 <chapter id="using-kapp">
124 <title>Using Kapp</title>
125
126 <!-- This chapter should tell the user how to use your app. You should use as
127 many sections (Chapter, Sect1, Sect3, etc...) as is necessary to fully document
128 your application. -->
129
130 <para>
131
132 <!-- Note that all graphics should be in .png format. Use no gifs because of
133 patent issues. -->
134
135 <screenshot>
136 <screeninfo>Here's a screenshot of &kpinentry;</screeninfo>
137         <mediaobject>
138           <imageobject>
139             <imagedata fileref="screenshot.png" format="PNG"/>
140           </imageobject>
141           <imageobject>
142             <imagedata fileref="screenshot.eps" format="EPS"/>
143           </imageobject>
144           <textobject>
145             <phrase>Screenshot</phrase>
146           </textobject>
147         </mediaobject>
148 </screenshot>
149 </para>
150
151
152 <sect1 id="kapp-features">
153 <title>More Kapp features</title>
154
155 <para>It slices! It dices! and it comes with a free toaster!</para>
156 <para>
157 The Squiggle Tool <guiicon><inlinemediaobject>
158           <imageobject>
159             <imagedata fileref="squiggle.png" format="PNG"/>
160           </imageobject>
161           <imageobject>
162             <imagedata fileref="squiggle.eps" format="EPS"/>
163           </imageobject>
164           <textobject>
165             <phrase>Squiggle</phrase>
166           </textobject>
167 </inlinemediaobject></guiicon> is used to draw squiggly lines all over
168 the &kpinentry; main window. It's not a bug, it's a feature!
169 </para>
170
171 </sect1>
172 </chapter>
173
174 <chapter id="commands">
175 <title>Command Reference</title>
176
177 <!-- (OPTIONAL, BUT RECOMMENDED) This chapter should list all of the
178 application windows and their menubar and toolbar commands for easy reference.
179 Also include any keys that have a special function but have no equivalent in the
180 menus or toolbars. This may not be necessary for small apps or apps with no tool
181 or menu bars. -->
182
183 <sect1 id="kapp-mainwindow">
184 <title>The main Kapp window</title>
185 <para></para>
186
187 <sect2>
188 <title>The File Menu</title>
189 <para>
190 <variablelist>
191 <varlistentry>
192 <term><menuchoice>
193 <shortcut>
194 <keycombo><keycap>Ctrl</keycap><keycap>n</keycap></keycombo>
195 </shortcut>
196 <guimenu>File</guimenu>
197 <guimenuitem>New</guimenuitem>
198 </menuchoice></term>
199 <listitem><para><action>Creates a new document</action></para></listitem>
200 </varlistentry>
201 <varlistentry>
202 <term><menuchoice>
203 <shortcut>
204 <keycombo><keycap>Ctrl</keycap><keycap>s</keycap></keycombo>
205 </shortcut>
206 <guimenu>File</guimenu>
207 <guimenuitem>Save</guimenuitem>
208 </menuchoice></term>
209 <listitem><para><action>Saves the document</action></para></listitem>
210 </varlistentry>
211 <varlistentry>
212 <term><menuchoice>
213 <shortcut>
214 <keycombo><keycap>Ctrl</keycap><keycap>q</keycap></keycombo>
215 </shortcut>
216 <guimenu>File</guimenu>
217 <guimenuitem>Quit</guimenuitem>
218 </menuchoice></term>
219 <listitem><para><action>Quits</action> &kpinentry;</para></listitem>
220 </varlistentry>
221 </variablelist>
222 </para>
223
224 </sect2>
225
226 </sect1>
227 </chapter>
228
229 <chapter id="developers">
230 <title>Developer's Guide to Kapp</title>
231
232 <!-- (OPTIONAL) A Programming/Scripting reference chapter should be
233 used for apps that use plugins or that provide their own scripting hooks
234 and/or development libraries. -->
235
236 <para>
237 Programming &kpinentry; plugins is a joy to behold. Just read through the next
238 66 pages of API's to learn how!
239 </para>
240
241 <!-- Use refentries to describe APIs.  Refentries are fairly complicated and you
242 should consult the docbook reference for further details. The example below was
243 taken from that reference and shortened a bit for readability. -->
244
245 <refentry id="re-1007-unmanagechildren-1">
246 <refmeta>
247 <refentrytitle>XtUnmanageChildren</refentrytitle>
248 <refmiscinfo>Xt - Geometry Management</refmiscinfo>
249 </refmeta>
250 <refnamediv>
251 <refname>XtUnmanageChildren
252 </refname>
253 <refpurpose>remove a list of children from a parent widget's managed list.
254 </refpurpose>
255 <indexterm id="ix-1007-unmanagechildren-1"><primary>widgets</primary><secondary>removing</secondary></indexterm>
256 <indexterm id="ix-1007-unmanagechildren-2"><primary>XtUnmanageChildren</primary></indexterm>
257 </refnamediv>
258 <refsynopsisdiv>
259 <refsynopsisdivinfo>
260 <date>4 March 1996</date>
261 </refsynopsisdivinfo>
262 <synopsis>
263 void XtUnmanageChildren(<replaceable class="parameter">children</replaceable>, <replaceable class="parameter">num_children</replaceable>)
264     WidgetList <replaceable class="parameter">children</replaceable>;
265     Cardinal <replaceable class="parameter">num_children</replaceable>;
266 </synopsis>
267
268 <refsect2 id="r2-1007-unmanagechildren-1">
269 <title>Inputs</title>
270 <variablelist>
271 <varlistentry>
272 <term><replaceable class="parameter">children</replaceable>
273 </term>
274 <listitem>
275 <para>Specifies an array of child widgets. Each child must be of
276 class RectObj or any subclass thereof.
277 </para>
278 </listitem>
279 </varlistentry>
280 <varlistentry>
281 <term><replaceable class="parameter">num_children</replaceable>
282 </term>
283 <listitem>
284 <para>Specifies the number of elements in <replaceable class="parameter">children</replaceable>.
285 </para>
286 </listitem>
287 </varlistentry>
288 </variablelist>
289 </refsect2></refsynopsisdiv>
290
291 <refsect1 id="r1-1007-unmanagechildren-1">
292 <title>Description
293 </title>
294 <para><function>XtUnmanageChildren()</function> unmaps the specified widgets
295 and removes them from their parent's geometry management.
296 The widgets will disappear from the screen, and (depending
297 on its parent) may no longer have screen space allocated for
298 them.
299 </para>
300 <para>Each of the widgets in the <replaceable class="parameter">children</replaceable> array must have
301 the same parent.
302 </para>
303 <para>See the &ldquo;Algorithm&rdquo; section below for full details of the
304 widget unmanagement procedure.
305 </para>
306 </refsect1>
307
308 <refsect1 id="r1-1007-unmanagechildren-2">
309 <title>Usage</title>
310 <para>Unmanaging widgets is the usual method for temporarily
311 making them invisible.  They can be re-managed with
312 <function>XtManageChildren()</function>.
313 </para>
314 <para>You can unmap a widget, but leave it under geometry
315 management by calling <function>XtUnmapWidget()</function>.  You can
316 destroy a widget's window without destroying the widget by
317 calling <function>XtUnrealizeWidget()</function>.  You can destroy a
318 widget completely with <function>XtDestroyWidget()</function>.
319 </para>
320 <para>If you are only going to unmanage a single widget, it is
321 more convenient to call <function>XtUnmanageChild()</function>.  It is
322 often more convenient to call <function>XtUnmanageChild()</function>
323 several times than it is to declare and initialize an array
324 of widgets to pass to <function>XtUnmanageChildren()</function>.  Calling
325 <function>XtUnmanageChildren()</function> is more efficient, however,
326 because it only calls the parent's <function>change_managed()</function>
327 method once.
328 </para>
329 </refsect1>
330
331 <refsect1 id="r1-1007-unmanagechildren-3">
332 <title>Algorithm
333 </title>
334 <para><function>XtUnmanageChildren()</function> performs the following:
335 </para>
336 <variablelist>
337 <varlistentry>
338 <term>-
339 </term>
340 <listitem>
341 <para>Ignores the child if it already is unmanaged or is being
342 destroyed.
343 </para>
344 </listitem>
345 </varlistentry>
346 <varlistentry>
347 <term>-
348 </term>
349 <listitem>
350 <para>Otherwise, if the child is realized, it makes it nonvisible
351 by unmapping it.
352 </para>
353 </listitem>
354 </varlistentry>
355 </variablelist>
356 <para>
357 </para>
358 </refsect1>
359
360 <refsect1 id="r1-1007-unmanagechildren-4">
361 <title>Structures</title>
362 <para>The <type>WidgetList</type> type is simply an array of widgets:
363 </para>
364 <screen id="sc-1007-unmanagechildren-1">typedef Widget *WidgetList;
365 </screen>
366 </refsect1>
367 </refentry>
368
369 </chapter>
370
371 <chapter id="faq">
372 <title>Questions and Answers</title>
373
374 <!-- (OPTIONAL but recommended) This chapter should include all of the silly
375 (and not-so-silly) newbie questions that fill up your mailbox. This chapter
376 should be reserved for BRIEF questions and answers! If one question uses more
377 than a page or so then it should probably be part of the
378 "Using this Application" chapter instead. You should use links to
379 cross-reference questions to the parts of your documentation that answer them.
380 This is also a great place to provide pointers to other FAQ's if your users
381 must do some complicated configuration on other programs in order for your
382 application work. -->
383
384 &reporting.bugs;
385 &updating.documentation;
386
387 <qandaset id="faqlist">
388 <qandaentry>
389 <question>
390 <para>My Mouse doesn't work. How do I quit &kpinentry;?</para>
391 </question>
392 <answer>
393 <para>You silly goose! Check out the <link linkend="commands">Commands
394 Section</link> for the answer.</para>
395 </answer>
396 </qandaentry>
397 <qandaentry>
398 <question>
399 <para>Why can't I twiddle my documents?</para>
400 </question>
401 <answer>
402 <para>You can only twiddle your documents if you have the foobar.lib
403 installed.</para>
404 </answer>
405 </qandaentry>
406 </qandaset>
407 </chapter>
408
409 <chapter id="credits">
410
411 <!-- Include credits for the programmers, documentation writers, and
412 contributors here. The license for your software should then be included below
413 the credits with a reference to the appropriate license file included in the KDE
414 distribution. -->
415
416 <title>Credits and License</title>
417
418 <para>
419 &kpinentry;
420 </para>
421 <para>
422 Program copyright 1997 John Q. Hacker <email>jqh@kde.org</email>
423 </para>
424 <para>
425 Contributors:
426 <itemizedlist>
427 <listitem><para>Konqui the KDE Dragon <email>konqui@kde.org</email></para>
428 </listitem>
429 <listitem><para>Tux the Linux Penguin <email>tux@linux.org</email></para>
430 </listitem>
431 </itemizedlist>
432 </para>
433
434 <para>
435 Documentation copyright 1999 George N. Ugnacious <email>gnu@kde.org</email>
436 </para>
437 <para>
438 Translations done by:
439 <itemizedlist>
440 <listitem>
441 <para>Babel D. Fish <email>babelfish@kde.org</email> (Sanskrit)</para>
442 </listitem>
443 </itemizedlist>
444 </para>
445
446 &underFDL;               <!-- FDL: do not remove -->
447
448 <!-- Determine which license your application is licensed under, 
449      and delete all the remaining licenses below:
450
451      (NOTE:  All documentation are licensed under the FDL, 
452      regardless of what license the application uses) -->
453
454 &underGPL;               <!-- GPL License -->
455 &underBSDLicense;        <!-- BSD License -->
456 &underArtisticLicense;   <!-- BSD Artistic License -->
457 &underX11License;        <!-- X11 License  -->
458
459 </chapter>
460
461 <appendix id="installation">
462 <title>Installation</title>
463
464 <sect1 id="getting-kapp">
465 <title>How to obtain Kapp</title>
466
467 <para>
468 &kpinentry; is part of the KDE project
469 <ulink url="http://www.kde.org">http://www.kde.org</ulink>.
470 &kpinentry; can be found in the kdeutils package on
471 <ulink url="ftp://ftp.kde.org/pub/kde/">ftp://ftp.kde.org/pub/kde/</ulink>, the
472 main ftp site of the KDE project. </para>
473 </sect1>
474
475 <sect1 id="requirements">
476 <title>Requirements</title>
477
478 <!--
479 List any special requirements for your application here. This should include:
480 .Libraries or other software that is not included in kdesupport,
481 kdelibs, or kdebase.
482 .Hardware requirements like amount of RAM, disk space, graphics card
483 capabilities, screen resolution, special expansion cards, etc.
484 .Operating systems the app will run on. If your app is designed only for a
485 specific OS, (you wrote a graphical LILO configurator for example) put this
486 information here.
487 -->
488
489 <para>
490 In order to successfully use &kpinentry;, you need KDE 1.1. Foobar.lib is required
491 in order to support the advanced &kpinentry; features. &kpinentry; uses about 5 megs of
492 memory to run, but this may vary depending on your platform and
493 configuration.
494 </para>
495
496 <para>
497 All required libraries as well as &kpinentry; itself can be found
498 on <ulink url="ftp://ftp.kapp.org">The &kpinentry; home page</ulink>.
499 </para>
500
501 <!-- For a list of updates, you may refer to the application web site
502 or the ChangeLog file, or ... -->
503 <para>
504 You can find a list of changes at <ulink
505 url="http://apps.kde.org/kapp">http://apps.kde.org/kapp</ulink>.
506 </para>
507 </sect1>
508
509 <sect1 id="compilation">
510 <title>Compilation and installation</title>
511
512 <para>
513 In order to compile and install KApp on your system, type the following in the base
514 directory of the Icon Editor distribution:
515 <screen width="40">
516 <prompt>%</prompt> <userinput>./configure</userinput>
517 <prompt>%</prompt> <userinput>make</userinput>
518 <prompt>%</prompt> <userinput>make install</userinput>
519 </screen>
520 </para>
521
522 <para>Since KApp uses autoconf and automake you should have not trouble compiling it.
523 Should you run into problems please report them to the KDE mailing lists.</para>
524
525 </sect1>
526
527 <sect1 id="configuration">
528 <title>Configuration</title>
529
530 <para>Don't forget to tell your system to start the <filename>dtd</filename>
531 dicer-toaster daemon first, or KApp won't work !</para>
532
533 </sect1>
534
535 </appendix>
536
537 &documentation.index;
538 </book>
539 <!--
540 Local Variables:
541 mode: sgml
542 sgml-minimize-attributes: nil
543 sgml-general-insert-case: lower
544 End:
545 -->
546