diff options
Diffstat (limited to 'doc')
500 files changed, 67064 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 000000000..6812bd2d1 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +SUBDIRS = $(AUTODIRS) + diff --git a/doc/faq/Makefile.am b/doc/faq/Makefile.am new file mode 100644 index 000000000..9c7a6607a --- /dev/null +++ b/doc/faq/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/faq + diff --git a/doc/faq/TODO b/doc/faq/TODO new file mode 100644 index 000000000..42a37ca29 --- /dev/null +++ b/doc/faq/TODO @@ -0,0 +1,35 @@ +TODO: + +- Cull any questions that are specific to KDE =< 3.4 +- Look into reorganising sections to make finding things much easier. + + + +I'm keeping this in here for the amusement factor. Every time I look at it I rememeber that while I'm not a very good FAQ maintainer, physos wasn't much better ;) + +Last modified by physos 2002-12-27 + +Before 3.2 release +_________________________________________________ + +- Split up the monolith docbook (done) +- Get rid of 1.1.2 stuff (confusion) +- check if things are still working + * compile tutorials for the various OS's + * workarounds still needed? + * workarounds still working? + * answers are still valid? + * easier solutions? +- complete revision ? +- New structure ? +- Find maintiners for single parts +- what needs to be added ? + +[22:15:47] <lauri> 1: move the faq (and other kdebase docs) up to kdebase/doc/<subdir> +so that docs.kde.org will pick them up and generate them +[22:16:05] <lauri> then remove the copies on www.kde.org, put in redirects to the new +location, and have one, autogenerated and searchable copy all the time +[22:16:17] <physos> sounds nice +[22:16:24] <physos> will look into it + + diff --git a/doc/faq/about.docbook b/doc/faq/about.docbook new file mode 100644 index 000000000..89c7b6033 --- /dev/null +++ b/doc/faq/about.docbook @@ -0,0 +1,72 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="about"> +<title>About this <acronym>FAQ</acronym></title> + +<qandaset> +<qandaentry> +<question> +<para>What can I do to help out with this <acronym>FAQ</acronym>?</para> +</question> + +<answer> + +<para>First, send us any errors that you may find. Also, any +suggestions that you might have, are appreciated. Better yet, send us +everything that you think is unclear, and if possible, send us what +you think would be a clearer solution. The email address of the current maintainer is <email>[email protected]</email>. +</para> + +<para>Second, send us your solutions of those frequently-asked +questions which are still not in this <acronym>FAQ</acronym>. We will +put them in as soon as possible.</para> + +<para>Last but not least, please make full use of this +<acronym>FAQ</acronym>. Read this <acronym>FAQ</acronym> (and other +relevant documentation) well before asking questions on the various +&kde; mailing lists or newsgroups.</para> + +<note><para> You might also want to consider becoming a +<acronym>FAQ</acronym> maintainer. Please refer to <xref +linkend="FAQ-maintainer-HOWTO"/> for more details. </para></note> + +</answer> +</qandaentry> + +<qandaentry> +<question id="FAQ-maintainer-HOWTO"> +<para>How do I become a <acronym>FAQ</acronym> maintainer?</para> +</question> + +<answer> +<para>Actually, it is very easy to become an <acronym>FAQ</acronym> +maintainer, and we are always in need of fresh blood. :-) Just send +us an email at <email>[email protected]</email>. +</para> +</answer> +</qandaentry> +</qandaset> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> + diff --git a/doc/faq/configkde.docbook b/doc/faq/configkde.docbook new file mode 100644 index 000000000..f0cb4d2be --- /dev/null +++ b/doc/faq/configkde.docbook @@ -0,0 +1,250 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd"> +--> +<chapter id="configure"> +<title>Configuring &kde;</title> + +<qandaset> +<qandaentry> +<question> +<para>How do I set the language used by &kde;?</para> +</question> + +<answer> +<para>There are two ways to set the language &kde; uses in the +messages it will display:</para> + +<variablelist> +<varlistentry><term>Using the <application>&kde; Control Center</application></term> +<listitem><para>Fire up the <application>&kde; Control Center</application> and select +<guimenu>Regional & Accessibility</guimenu> followed by +<guimenuitem>Country/Region & Language</guimenuitem>. You can select your language and location +here. If &kde; cannot find a translation in the first language +chosen, it will fall back on the default language. This is usually +(American) English by default.</para> +<note><para>Using the <application>&kde; Control Center</application> is the preferred way of choosing +languages in &kde;.</para></note></listitem> +</varlistentry> +<varlistentry><term>Using the <envar>LANG</envar> environment variable</term> +<listitem><para>The second method uses the standard locale setting on +your system. To change the language, simply set the environment +variable <envar>LANG</envar> accordingly. For example, if your shell +is <application>bash</application>, execute +<userinput><command>export</command> <envar>LANG</envar>=de</userinput> +to set German as the language used.</para></listitem> +</varlistentry> +</variablelist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is there any keyboard switcher for international keyboards for +&kde;?</para> +</question> +<answer> +<para> +Yes, you can configure it using the <application>&kde; Control Center</application> +<guimenu>Regional & Accessibility</guimenu> +<guimenuitem>Keyboard Layout</guimenuitem> + configuration page. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I replace the standard text login screen with the +&kde; login screen?</para> +</question> +<answer> +<note><para>Your distribution/&UNIX; flavor may have its own setup tools to +change this (⪚ <application>YaST</application> on &SuSE; &Linux;). This will +be the safest way to enable the &kde; login screen. However, if for some reason +you do not wish to use these tools, the following instructions may be useful.</para></note> +<para>First, you need to change to the <quote>xdm runlevel</quote> (runlevel 5 on +&RedHat; and &SuSE; systems) by editing your +<filename>/etc/inittab</filename> file. In the file, you should have +a line saying <userinput>id:3:initdefault:</userinput>. Change it to +<userinput>id:5:initdefault:</userinput>. Now, at the end of the file, +comment out the following line: +<literal>x:5:respawn:/usr/bin/X11/xdm -nodaemon</literal> and +replace it with +<userinput>x:5:respawn:<replaceable>/opt/kde/</replaceable>bin/kdm +-nodaemon</userinput>. +<note><para>The location of &kdm; may differ on your +system.</para></note></para> +<para>For changes to take effect immediately, type <command>init +5</command> (for &RedHat; systems) at the shell prompt. +<caution><para>It is risky to initiate a graphical login without +checking beforehand whether it works. If it fails to work, you would +be in for a hard time getting back....</para></caution></para> +</answer> +<answer> +<para> +For FreeBSD, you should edit the file <filename>/etc/ttys</filename> +and change one of the lines that look like +<programlisting>ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting> +to instead say <userinput>ttyv8 "/usr/local/bin/kdm -nodaemon" xterm +off secure</userinput>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> + +<para>I would like to click the &LMB; anywhere on the +desktop and have the <guimenu>K</guimenu> menu displayed.</para> +</question> +<answer> +<para>Open the <application>&kde; Control Center</application> and +choose <menuchoice><guisubmenu>Desktop</guisubmenu> +<guisubmenu>Behavior</guisubmenu></menuchoice>. You +can now choose the behavior of mouse clicks on the desktop. To have +the <guimenu>K</guimenu> menu open from a single &LMB; click, change +the entry labeled <guilabel>Left button</guilabel> to say +<guilabel>Application Menu</guilabel>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Where do I find information regarding &kde; themes?</para> +</question> +<answer> +<para>Go to <ulink +url="http://kde.themes.org/">http://kde.themes.org/</ulink> or <ulink +url="http://www.kde-look.org">http://www.kde-look.org</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I change &MIME; Types?</para> +</question> +<answer> +<para>If you are using &konqueror;, do this instead: first, open a +&konqueror; window and choose +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Konqueror</guimenuitem></menuchoice>, then <guilabel>File Associations</guilabel>. Find the type you want to change +(⪚ <literal>text/english</literal> or +<literal>image/gif</literal>), and set the application preference order +to whatever you want.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>&kde; (&kdm;) does not read my +<filename>.bash_profile</filename>!</para> +</question> +<answer> +<para>The login managers<application>xdm</application> and &kdm; do +not run a login shell, so <filename>.profile</filename>, +<filename>.bash_profile</filename>, &etc; are not +sourced. When the user logs in, <application>xdm</application> runs +<command>Xstartup</command> as root and then +<command>Xsession</command> as user. So the normal practice is to add +statements in <filename>Xsession</filename> to source the user +profile. Please edit your <filename>Xsession</filename> and +<filename>.xsession</filename> files.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I use &TrueType; fonts in &kde;?</para> +</question> +<answer> + +<para>You need to install &TrueType; font support into your &X-Window; configuration. +Please take a look at <ulink +url="http://x.themes.org/">x.themes.org</ulink> for the fonts, and +<ulink url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">xfsft: +&TrueType; Font Support For X11</ulink> or <ulink +url="http://X-TT.dsl.gr.jp/">X-&TrueType; Server Project Home +Page</ulink> for the font servers.</para> + +<para>If you have a bunch of &TrueType; fonts from &Microsoft; +&Windows;, edit the <filename>XF86Config</filename> file to get the +fonts from the font folder. Then just tell &kde; to use these new +fonts with the font administrator utility.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is it possible to enter, show and work with the Euro Symbol in +&kde;?</para> +</question> +<answer> +<para>Yes and no. For details, look here: <ulink +url="http://www.koffice.org/kword/euro.php">http://www.koffice.org/kword/euro.php</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>How do I run a program at &kde; startup?</para></question> + +<answer><para>There are many ways to do that. If what you want to do +is to run some scripts that would set some environment variables (for +example, to start <command>gpg-agent</command>, <command>ssh-agent</command> and others), you can put +these scripts into <filename class="directory">$<envar>KDEHOME</envar>/env/</filename> and make sure their names end in +<literal role="extension">.sh</literal>. $<envar>KDEHOME</envar> is +usually a folder named <filename class="directory">.kde</filename> +(note the period at the beginning) in your home +folder. If you want scripts to be executed for all &kde; users, you can +put them under <filename class="directory">$<envar>KDEDIR</envar>/env/</filename>, where $<envar>KDEDIR</envar> is the prefix &kde; was +installed to (you can find this out using the command +<userinput><command>kde-config</command> --prefix</userinput>).</para> +<para>If you wish to start a program after &kde; has started, you may want to use the +<filename class="directory">Autostart</filename> folder. To add +entries to the <filename class="directory">Autostart</filename> folder: +<orderedlist> +<listitem><para>Open &konqueror;.</para> +</listitem> +<listitem><para>Select <menuchoice><guimenu>Go</guimenu><guimenuitem>Autostart</guimenuitem> +</menuchoice> from the menubar.</para> +</listitem> +<listitem><para>Right-click in the window view area and select <menuchoice><guisubmenu>Create New</guisubmenu><guisubmenu>File</guisubmenu><guimenuitem>Link to +Application</guimenuitem> +</menuchoice></para> +</listitem> +<listitem><para>Click on the <guilabel>Application</guilabel> tab in +the window that appears and enter the name of the command to run in +the <guilabel>Command</guilabel> text box.</para> +</listitem> +</orderedlist> +</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How can I allow more than one user to be logged in a at a time? Can &kde; do <quote>fast user switching</quote>?</para> +</question> +<answer> + +<para>To enable more than one user to log in at one time on the same +computer (sometimes referred to as <quote>fast user switching</quote>) you +need to tell the program that logs you in that it can use more than one +session (or, in &X-Window; terms, <quote>display</quote>) at a time.</para> + +<para>In &kde;, this program is called &kdm; which stands for <quote>&kde; +Display Manager</quote>. If you are not using &kdm; as your login screen +then you will need to consult the documentation for the software you are using on how to +accomplish multiple sessions.</para> + +<para>By default, this will be configured at installation time automatically +if &kdm; supports virtual terminals on your system (currently Linux only). +If it was not configured automatically, consult the &kdm; manual, section +<ulink url="help:/kdm/kdmrc-xservers">Specifying permanent &X-Server;s</ulink>. +After modifying kdmrc, you will have to let &kdm; know about it; just +invoke <command>killall -HUP kdm</command>.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> diff --git a/doc/faq/contrib.docbook b/doc/faq/contrib.docbook new file mode 100644 index 000000000..807050ba7 --- /dev/null +++ b/doc/faq/contrib.docbook @@ -0,0 +1,164 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + + +<chapter id="contribute"> +<title>Contributing</title> + +<qandaset> +<qandaentry> +<question> +<para>How can I contribute to &kde;?</para> +</question> +<answer> +<para>&kde; is a free software project that lives from voluntary +contributions. Everybody is encouraged to contribute to &kde;. Not +only programmers are welcome. There are many ways in which you can +help to improve &kde;:</para> +<itemizedlist> +<listitem><para>Test the software.</para></listitem> +<listitem><para>Send in bug reports. For more information on this, +see <link linkend="bug-report">How do I submit a bug +report?</link>.</para></listitem> +<listitem><para>Write documentation or help files. You can get some +information by visiting the <ulink +url="http://i18n.kde.org/doc/">&kde; Editorial Team +Home Page</ulink>.</para></listitem> +<listitem><para>Translate programs, documentation, and help files. +For more information on this, you should visit <ulink +url="http://i18n.kde.org">The &kde; Translators' and Documenters' Web +Site</ulink>.</para></listitem> +<listitem><para>Draw nice icons or compose sound effects. You can +visit the <ulink url="http://artist.kde.org/">&kde; +artists page</ulink> to find out more.</para></listitem> +<listitem><para>Write articles and books about &kde;. If you want to +help spread the word about &kde;, simply send an email to +<email>[email protected]</email>. This will get you in touch +with the &kde; public relations volunteers.</para></listitem> +<listitem><para>Program new &kde; applications. Please refer to <xref +linkend="programming"/> for more information.</para></listitem> +<listitem><para> Of course, sponsors are also +welcome. :-)</para></listitem> +</itemizedlist> +<para>There are several places to look for more information if you +want to get involved in the development. The first step is to +subscribe to some of the <ulink url="http://www.kde.org/mailinglists/">mailing +lists</ulink>. You will soon see something +that can be improved or added.</para> +</answer> +</qandaentry> + +<qandaentry> +<question id="bug-report"> +<para>How do I submit a bug report?</para> +</question> +<answer> +<para>There is a bug tracking system available at <ulink +url="http://bugs.kde.org">http://bugs.kde.org</ulink>. The +system features a wizard to submit new bug reports and a +list of all known bugs.</para> +<para>The easiest way to submit a bug is to select +<menuchoice><guimenu>Help</guimenu><guimenuitem>Report +Bug...</guimenuitem></menuchoice> from the menu bar of the application +with the bug. This will open a small dialog box with a link +to the bug tracking system. Please make sure to follow the +instructions of the bug reporting wizard.</para> +</answer> +</qandaentry> + +<qandaentry> +<question id="programming"> +<para>I want to program for &kde;. What should I do first?</para> +</question> +<answer> +<para>Everybody is encouraged to develop software for &kde;. What you +should do first depends strongly on your experience, ⪚ whether you have +already learned C++ or have experience with the &Qt; toolkit and so +on.</para> +<para>To get into &kde; programming, you will need some basic tools: +<application>automake</application>, +<application>autoconf</application>, and +<application>egcs</application>. You should look to <ulink +url="http://developer.kde.org/">http://developer.kde.org/</ulink> +for more tips.</para> +<para>Another excellent resource for learning &kde; +programming is the &Qt; +online tutorials. These are installed along with &Qt;. To view them, +open <filename>$<envar>QTDIR</envar>/doc/html/index.html</filename> in +&konqueror; and bookmark it. The tutorials +can be found under "Using +Qt". The source code for each lesson can be found in the <filename +class="directory">$<envar>QTDIR</envar>/tutorial</filename> +directory.</para> +<para>There is, however, one thing that everybody interested in +programming for &kde; should do: <emphasis>subscribe to the developers +mailing list</emphasis>. To subscribe, you have to send an email to +<ulink +url="mailto:[email protected]">[email protected]</ulink> +with the subject <userinput>subscribe +<replaceable>your_email_address</replaceable></userinput>. +<important><para>Please read <link linkend="subscribe">How to +subscribe/unsubscribe to these lists</link> carefully. Everything +said there applies to the development list as +well.</para></important></para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I get access to &kde; <acronym>SVN</acronym>?</para> +</question> +<answer> +<para>The &kde; project uses <acronym>SVN</acronym> to develop the +core parts of the software. Usually, when you have changed one of the +parts (⪚ fixed a bug), and you want to commit this change, the best +way is to create a patch against a current snapshot and send this +patch to the developer/maintainer of the respective program.</para> +<para>If you are doing this more or less regularly, there are instructions here on how to get write access to the <acronym>SVN</acronym> repository: <ulink url="http://developer.kde.org/documentation/other/developer-faq.html#q1.8"> +http://developer.kde.org/documentation/other/developer-faq.html#q1.8</ulink>. But be aware that more users will slow +down <acronym>SVN</acronym> access for all developers, so we want to +keep the number of people with direct <acronym>SVN</acronym> access +reasonably small. But feel free to ask!</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can I have read-only access to the <acronym>SVN</acronym> repository?</para> +</question> +<answer> +<para>Yes. Instructions on how to get anonymous, read-only <acronym>SVN</acronym> access are here: <ulink url="http://developer.kde.org/source/anonsvn.html"> +http://developer.kde.org/source/anonsvn.html</ulink> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Are there any <acronym>SVN</acronym> mirror sites for &kde;?</para> +</question> +<answer> +<para>No, there are currently no anonymous <acronym>SVN</acronym> mirror sites for &kde;. If you're interested in setting one up, please contact <email>[email protected]</email> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I go about translating &kde; programs into my native +language?</para> +</question> +<answer> +<para>Look at the <ulink url="http://i18n.kde.org">The &kde; +Translators' and Documenters' Web Site</ulink> to see whether your +program is already translated (most are). Otherwise you will find +information there on how to do it yourself.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> + + diff --git a/doc/faq/desktop.docbook b/doc/faq/desktop.docbook new file mode 100644 index 000000000..da3de1608 --- /dev/null +++ b/doc/faq/desktop.docbook @@ -0,0 +1,97 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="desktop"> +<title>The desktop</title> + +<qandaset> +<qandaentry> +<question> +<para>How do I add an application to the desktop?</para> +</question> +<answer> + +<para>Just choose the desired application from the <guimenu>K</guimenu> menu and drag and drop it to the Desktop. +</para> +<para>For applications not listed in the <guimenu>K</guimenu> menu, +use the &RMB; on the desktop and choose <menuchoice><guimenuitem>Create New</guimenuitem><guisubmenu>File</guisubmenu> +<guimenuitem>Link to Application...</guimenuitem></menuchoice> and fill in the configuration for the application you want to link to. +</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I mount/unmount a device from the desktop?</para> +</question> +<answer> + +<para>First, make sure you are allowed to <command>mount</command>/<command>umount</command> the relevant device as a user. +</para> +<para>Then you can add any device via &RMB; on the desktop and then choosing <menuchoice><guimenu>Create New</guimenu><guimenuitem>Link to Device</guimenuitem></menuchoice> and then selecting the device of the type you wish to control from the desktop. Fill in the settings for the device in the dialog that appears and click <guilabel>OK</guilabel>. You can use the resulting desktop icon to mount/unmount the device from the desktop. +</para> + +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>Where are the icons kept?</para> +</question> +<answer> +<para>The icons can be found only in <filename +class="directory">$<envar>KDEDIRS</envar>/share/icons</filename> or <filename +class="directory">$<envar>HOME</envar>/.kde/share/icons</filename> or +<filename class="directory">$<envar>HOME</envar>/.kde2/share/icons</filename>. To use icons +stored in other locations, you must either copy them into one of the +above-mentioned fixed &kde; locations or make symlinks.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I use the mouse scroll wheel in &kde;?</para> +</question> +<answer> +<para>Mouse wheel support comes with &Qt; 2.0 and above, so &kde; based on +that will automatically support the use of the mouse scroll wheel if your system is configured correctly. Check your &X-Server; settings support the use of a scrollwheel if it is not working.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I launch applications in a particular desktop?</para> +</question> +<answer> +<para>&kde; comes with a program called &kstart;. +To start an <application>xterm</application> on the second desktop and then activate it use: + +<userinput><command>kstart</command> <option>--desktop +2 --activate --window "xterm" </option>xterm</userinput>.</para> +<para>Note that the <option>--window</option> option is important. It takes an +argument which is a regular expression matching the title of the window to +apply the settings to.</para> +<para>Please read <command>kstart</command> <option>--help-all</option> for more magic +available with &kstart; (and there is an abundance). +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Where do I save my files if I want them to appear directly on +the desktop?</para> +</question> +<answer> +<para><filename +class="directory">$<envar>HOME</envar>/Desktop</filename>. You might +need to refresh your desktop after you have saved your files.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> diff --git a/doc/faq/filemng.docbook b/doc/faq/filemng.docbook new file mode 100644 index 000000000..bfe6d1e98 --- /dev/null +++ b/doc/faq/filemng.docbook @@ -0,0 +1,207 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> --> + +<chapter id="filemanager"> +<title>The File Manager</title> + +<para>&kde;'s file manager is &konqueror;. The +&konqueror; home page is located at <ulink +url="http://www.konqueror.org">http://www.konqueror.org</ulink> where a +&konqueror; specific <acronym>FAQ</acronym> can be found.</para> + +<qandaset> + + +<qandaentry> +<question> +<para>How can I change the appearance of a folder in +&konqueror;?</para> +</question> +<answer> +<para>Right-click the folder, select <guimenuitem>Properties</guimenuitem>, +click on the large icon in the dialog which appears, and choose another +icon.</para> <para>To change the icon displayed for entries in the +<guimenu>K Menu</guimenu>, use the <application>Menu Editor</application>, +located at <menuchoice><guisubmenu>Settings</guisubmenu><guimenuitem>Menu +Editor</guimenuitem></menuchoice>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How can I do non-anonymous &FTP; transfers with &konqueror;?</para> +</question> +<answer> +<para>Normally, if you enter a &URL; like +<userinput>ftp://<replaceable>ftp.somehost.com</replaceable></userinput>, +&konqueror; will attempt an anonymous login to the &FTP; server. If you +want to login as a particular user, enter a &URL; like +<userinput>ftp://<replaceable>[email protected]</replaceable></userinput> +instead. &konqueror; will ask for your password and connect to the +server.</para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>How do I specify the startup folder for &konqueror;?</para> +</question> +<answer> + +<para>Using the &RMB;, click on the Home icon and choose +<guimenuitem>Properties</guimenuitem>. Under the +<guilabel>Application</guilabel> tab you will probably find something like +<command>kfmclient openProfile filemanagement</command>; just append +<filename class="directory">file:/whereever/you/want</filename> with the +folder you would like &konqueror; to start in.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I rename files?</para> +</question> +<answer> +<para>Simply <mousebutton>right</mousebutton> click on the file and select +<guimenuitem>Rename</guimenuitem> or press the keyboard shortcut <keycap>F2</keycap> with a file selected.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Where did the delete entry from my right-click context menu go?</para> +</question> +<answer> +<para>In &kde; 3.4 the delete context menu entries that bypass the +trashcan are no longer displayed by default. To enable them, go to +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&konqueror;</guimenuitem></menuchoice > and select +<guilabel>Behaviour</guilabel> in the iconbar to the left. Tick the checkbox +<guilabel>Show 'Delete' context menu entries which bypass the +trashcan</guilabel>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>How do I configure the programs that &konqueror; uses to +open different types of files?</para></question> +<answer> +<para>In order to configure file associations, you should go to the +&kcontrolcenter; and choose the item <guimenuitem>File +Associations</guimenuitem> under the category <guimenu>KDE +Components</guimenu>.</para> +<para> +Suppose the default <acronym>PDF</acronym> viewer is now &kghostview; and +you would prefer to use <application>KPDF</application> as a viewer. You +would simply type <userinput>pdf</userinput> in the search box at the top of +the dialog, choose <guimenuitem>pdf</guimenuitem> in the +<guimenu>application</guimenu> group and move +<application>KPDF</application> up. In the <guilabel>Embedding</guilabel> +tab you can also choose which component other applications will use to +display files (for example, when viewing files in &konqueror; or using +&ark;'s embedded viewer). +</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>When I try to click on a folder in &konqueror;, I get the +message: <quote>There appears to be a configuration error. You have +associated Konqueror with inode/directory, but it cannot handle this file +type.</quote></para> +</question> +<answer> +<para>You need to make sure that the embedding settings for inode/directory +are correct: +<orderedlist> +<listitem><para>In &konqueror;, go to +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Konqueror</guimenuitem></menuchoice> and then to the <guilabel>File +Associations</guilabel> page.</para></listitem> <listitem><para>Open +inode->directory in the tree view.</para></listitem> <listitem><para>Click on +the +<guilabel>Embedding</guilabel> tab. Make sure that <guilabel>Left Click +Action</guilabel> is set to <guilabel>Show file in embedded +viewer</guilabel>, and by default <guilabel>Icon View (konq_iconview)</guilabel> +is at the top +of <guilabel>Services Preference Order.</guilabel></para></listitem> +</orderedlist> +</para> +</answer> +</qandaentry> + +<qandaentry> <question> <para>What are <option>%i</option> and +<option>%m</option> in the Execute line?</para> </question> <answer> +<para>They are used by all &kde; applications (since they are implemented in +<classname>KApplication</classname> and all good &kde; programs create a +<classname>KApplication</classname> object before they even look at the +command line arguments).</para> <para>A standard line for a &kde; +application looks like this: <userinput><command>foo</command> +<option>... %i %m -caption \"%c\"</option></userinput>. Pretty confusing, +-but it has been designed in that way so that it can integrate legacy, +non-&kde; applications as smoothly as possible. &konqueror;, when executing +the line above, will extend the command to +<userinput><command><replaceable>foo</replaceable></command> <option>-icon +something.png -miniicon something_mini.png -caption \"The +Foo\"</option></userinput>. Both the icon and the mini-icon as well as "The +Foo" are properties defined in the <filename>.desktop</filename> file. If +the icons are not defined, they simply default to the executable name +<replaceable>foo</replaceable>.</para> + +<para>This way a user can change these things in &kmenuedit; for his or her +applications. The <option>-caption</option> option is important, because no +user will accept that the menu item <guimenuitem>Editor</guimenuitem> starts +something called <guilabel>kedit-0.9pl4-build47</guilabel>. Instead, he +expects a window called <guilabel>Editor</guilabel>. Furthermore these +names are localized, <abbrev>i.e.</abbrev> an American user launches +<guimenuitem>CD-Player</guimenuitem> and gets a window called +<guilabel>CD-Player</guilabel> while a German user launches +<guimenuitem>CD-Spieler</guimenuitem> and gets a window called +<guilabel>CD-Spieler</guilabel>.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question><para>How do I make &konqueror; start up without a menu bar? +I can't save a view profile when the menu bar is invisible!</para> +</question> + +<answer><para>The easiest way to do this is to edit &konqueror;'s +configuration file manually. Add the following lines to +<filename>~/.kde/share/config/konquerorrc</filename>: +<programlisting> +[KonqMainWindow] +MenuBar=Disabled +</programlisting> +</para> + +<para>On restarting &konqueror;, the menubar should be hidden.</para> + +</answer> +</qandaentry> + +</qandaset> +</chapter> + +<!--Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/faq/getkde.docbook b/doc/faq/getkde.docbook new file mode 100644 index 000000000..ceabb2561 --- /dev/null +++ b/doc/faq/getkde.docbook @@ -0,0 +1,79 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="getting-kde"> +<title>Getting &kde;</title> + +<qandaset> +<qandaentry> +<question id="where-to-get-kde"> +<para>Where do I get &kde;?</para> +</question> +<answer> +<!-- This needs a rewrite including informations about the latest version (link to the info page?)--> +<para>The easiest way to get &kde; is to install a &Linux; distribution or another UNIX-like OS that ships with &kde;. +You can find an up-to-date list of distributions that ship +with &kde; <ulink url="http://www.kde.org/download/distributions.php">here</ulink>. For alternative methods of +trying &kde; that do not require you to be running &Linux;, please see +<ulink url="http://kde.org/try_kde">Try &kde;</ulink></para> + +<para>The main distribution site for &kde; is +<ulink url="ftp://ftp.kde.org/">ftp.kde.org</ulink>. However, this site is +often under heavy load, so you might prefer to use +<ulink url="http://download.kde.org/">download.kde.org</ulink> which automatically +redirects you to the mirror nearest to you. +You can also have a look at the list of <ulink url="http://www.kde.org/ftpmirrors.html"> &kde; mirror sites</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What is the current version?</para> +</question> +<answer> + +<para>Currently, the latest stable version is 3.5.5</para> + +<para>The <ulink url="http://www.kde.org/info/3.5.5.php">&kde; 3.5.5 Info +Page</ulink> contains a lot of information specific to this +release.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Where do I find &kde; snapshots?</para> +</question> +<answer> +<para>You can get the latest snapshots from <ulink +url="ftp://ftp.kde.org/pub/kde/unstable/snapshots">ftp://ftp.kde.org/pub/kde/unstable/snapshots</ulink>. +You might also want to consider setting up your own <acronym>SVN</acronym> client in order to +maintain the latest snapshot at all times. Please refer to <ulink +url="http://developer.kde.org/source/anonsvn.html">Anonymous <acronym>SVN</acronym> and &kde;</ulink> for further +information. +</para> + +</answer> +</qandaentry> + +<qandaentry> +<question id="where-to-get-qt"> +<para>Where do I get &Qt;?</para> +</question> +<answer> +<para>&Qt; is a product of the Norwegian company Trolltech. You can +always get the latest &Qt; version from their +<ulink url="ftp://ftp.trolltech.com">&FTP; server</ulink>.</para> +<para> +And with most up-to-date &Linux; distributions, &Qt; is already +included. Please see <xref linkend="prerequisites"/> for the version +of &Qt; you need.</para> +</answer> +</qandaentry> + + +</qandaset> +</chapter> diff --git a/doc/faq/index.docbook b/doc/faq/index.docbook new file mode 100644 index 000000000..f114e3993 --- /dev/null +++ b/doc/faq/index.docbook @@ -0,0 +1,136 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd" [ + <!ENTITY kappname "&kde; Frequently Asked Questions"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY faq-about SYSTEM "about.docbook"> + <!ENTITY faq-intro SYSTEM "intro.docbook"> + <!ENTITY faq-getkde SYSTEM "getkde.docbook"> + <!ENTITY faq-install SYSTEM "install.docbook"> + <!ENTITY faq-panel SYSTEM "panel.docbook"> + <!ENTITY faq-desktop SYSTEM "desktop.docbook"> + <!ENTITY faq-winmng SYSTEM "winmng.docbook"> + <!ENTITY faq-filemng SYSTEM "filemng.docbook"> + <!ENTITY faq-webbrowse SYSTEM "webbrowse.docbook"> + <!ENTITY faq-configkde SYSTEM "configkde.docbook"> + <!ENTITY faq-kdeapps SYSTEM "kdeapps.docbook"> + <!ENTITY faq-nonkdeapps SYSTEM "nonkdeapps.docbook"> + <!ENTITY faq-tips SYSTEM "tips.docbook"> + <!ENTITY faq-misc SYSTEM "misc.docbook"> + <!ENTITY faq-notrelated SYSTEM "notrelated.docbook"> + <!ENTITY faq-moreinfo SYSTEM "moreinfo.docbook"> + <!ENTITY faq-contrib SYSTEM "contrib.docbook"> + <!ENTITY faq-questions SYSTEM "questions.docbook" > + <!ENTITY faq-credits SYSTEM "credits.docbook"> + <!ENTITY faq-sound SYSTEM "sound.docbook"> + <!ENTITY faq-qt SYSTEM "qt.docbook"> + +]> +<!--Time-stamp: "2001-09-03 00:10:00 endres"--> +<book lang="&language;"> + +<bookinfo> +<title>&kde; Frequently Asked Questions</title> + +<authorgroup> +<author> +<surname>The &kde; Team</surname> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>1997</year> +<year>1998</year> +<year>1999</year> +<year>2000</year> +<year>2001</year> +<year>2003</year> +<year>2004</year> +<year>2005</year> +<holder>The &kde; Team</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-01-19</date> +<releaseinfo>3.4</releaseinfo> + +<abstract> <para>This is a compilation of the most frequently asked +questions about the K Desktop Environment. Please report any bugs, +inconsistencies, or omissions you find in this &FAQ; to +<email>[email protected]</email>. Please do not mail your questions +to this list. Post them to the &kde; mailing lists and newsgroups +instead. They are monitored for this &FAQ;.</para> </abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>FAQ</keyword> +<keyword>question</keyword> +<keyword>answer</keyword> +</keywordset> +</bookinfo> + +&faq-about; +&faq-intro; +&faq-getkde; +&faq-install; +&faq-panel; +&faq-desktop; +&faq-winmng; +&faq-filemng; +&faq-webbrowse; +&faq-configkde; +&faq-kdeapps; +&faq-sound; +&faq-nonkdeapps; +&faq-tips; +&faq-misc; +&faq-qt; +&faq-moreinfo; +&faq-questions; +&faq-contrib; + +<chapter id="credits"> +<title>Credits and License</title> + +<para>The current &FAQ; maintainers are:</para> + +<itemizedlist> +<listitem><para>J Hall +<email>[email protected]</email></para></listitem> +</itemizedlist> + +<para>Many of the answers in this &FAQ; are taken +from the various &kde; mailing lists and newsgroups. Here is a +<emphasis>big</emphasis> thank you to all of you who have contributed +answers that eventually appear in this &FAQ;.</para> + +<para>Special thanks go to the former &FAQ; +maintainers, Rainer Endres and Mr. Lee Wee Tiong </para> + + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +</chapter> + +&documentation.index; +</book> + +<!-- +Local Variables: +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-omittag:t +sgml-shorttag:t +sgml-namecase-general:t +sgml-always-quote-attributes:t +sgml-indent-step:2 +sgml-indent-data:nil +sgml-parent-document:nil +sgml-exposed-tags:nil +End: +--> diff --git a/doc/faq/install.docbook b/doc/faq/install.docbook new file mode 100644 index 000000000..6ab33ef78 --- /dev/null +++ b/doc/faq/install.docbook @@ -0,0 +1,726 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="install"> +<title>Installation instructions</title> + +<para>These are the generic installation instructions for the K +Desktop Environment. Please complement your reading with the +<filename>README</filename>s and <filename>INSTALL</filename>s that +come along with the package. Please read them carefully and try to +help yourself out if anything goes wrong. If you need further +assistance, consider joining the &kde; mailing lists +(see our web site instructions for joining the &kde; +<ulink url="http://www.kde.org/mailinglists/">mailing +lists</ulink>) or newsgroups.</para> + + +<qandaset> + + +<qandaentry> +<question> +<para>To the would-be converts</para> +</question> +<answer> + +<para>So you have heard the rumors. Or you have seen the screenshots. +And you are dying to get hold of &kde;. But you know next to nothing +about this whole <quote>alternative OS</quote> business. Don't worry! +You only need to do some (well, maybe not some) reading, that's +all!</para> + +<para>&kde; does not run on any version of &Microsoft; &Windows; or OS/2 (yet). To run +&kde;, you need to have a &UNIX; system. Please refer to <xref +linkend="platform"/> for more details.</para> + +<para>Decide on a platform and set it up for your system. This +<acronym>FAQ</acronym> can not help you with this, since &kde;<ulink +url="http://www.kde.org"> runs on many &UNIX;</ulink> platforms. </para> + +<!-- Taken out because we can not help with all platforms and KDEisnotLINUX --> + +<para>Finally, you are ready to commence the &kde; installation. +Please start reading from the next section. To get &kde;, please +refer to <xref linkend="where-to-get-kde"/>. Last but not least, if +you encounter any problems while installing &kde;, please do not +hesitate to make use of the &kde; <link +linkend="mailing-lists">mailing lists</link> and <link +linkend="newsgroups">newsgroups</link>. But do bear this in mind: no +question is too silly to ask, but some are too silly to answer, +especially when they are already answered in this <acronym>FAQ</acronym>.</para> +<para>Good luck and have fun!</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What kind of hardware do I need to run &kde; ?</para> +</question> +<answer> +<para>To run &kde; it is recommended that you have at least a pentium II processor, 64MB of memory and 500MB of free disk space for a basic installation. While &kde; may run on slower configurations than this, performance can be severely impaired. Generally, if your computer runs an &X-Server; already with other desktop environments or window managers it's probably fast enough to run &kde;.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Available package formats</para> +</question> +<answer> + + +<para>You can find several kinds of binary and source packages for +different distributions and operating systems on the &kde-ftp;. The +binary packages are not made by the &kde; Team, but by the +distributors themselves, or some dedicated individuals. Please refer to +<ulink url="http://dot.kde.org/986933826/">&kde; Package Policy +Explained</ulink> for information about the &kde; Package Policy. The +only <quote>official</quote> release is the source tar.bz2 +packages. Please refer to the <filename>README</filename>s and +<filename>INSTALL</filename>s in the several binaries folders. For +a list of the available packages for a release, refer to the relevant +info page. For the latest release this is the <ulink +url="http://www.kde.org/info/3.4.1.php">&kde; 3.4.1 Info +Page</ulink>.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question id="prerequisites"> +<para>Prerequisites</para> +</question> +<answer> + +<!-- rewrite to make it more general, pointing to the according webpages? --> + +<para>For &kde; 3.4.1, you need the &Qt; library version 3.3 or greater. +Please make sure you download the correct &Qt;. You will +also need the header files, if you want to compile &kde; +yourself. They are all available, at no cost, from <ulink +url="http://www.trolltech.com/products/download">http://www.trolltech.com/download</ulink>. +In addition, there are optional libraries that might improve &kde; if +installed on your system. An example is OpenSSL which will enable +&konqueror; to browse web pages securely and is needed in a version +>=0.9.6. These should be provided by your distributor; if not, ask +for an update.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Description of the base packages</para> +</question> +<answer> +<para>The base distribution currently consists of twenty +packages. Some are required, while others are optional. Each package +is available in each of the aforementioned package formats.</para> +<variablelist> +<varlistentry> +<term>kdelibs</term> +<listitem> +<para>Required</para> +<para>This package contains shared libraries that are needed by all +&kde; applications.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdebase</term> +<listitem> +<para>Required</para> +<para>This package contains the base applications that form the core +of the K Desktop Environment like the window manager, the terminal +emulator, the control center, the file manager, and the panel.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>&arts;</term> +<listitem> +<para>Required</para> +<para>The &arts; sound server. A powerful, network transparent sound +server.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdeaddons</term> +<listitem> +<para>Optional</para> +<para>Various plugins for &kate;, &kicker;, &knewsticker;, &konqueror; and &noatun; </para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdeartwork</term> +<listitem> +<para>Optional</para> +<para>Additional wallpapers, themes, styles, sounds ...</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdebindings</term> +<listitem> +<para>Optional</para> +<para>Various bindings for other languages, including &Java;, Perl, Python, ...</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdegames</term> +<listitem> +<para>Optional</para> +<para>Various games like &kmahjongg;, &ksnake;, &kasteroids;, and +&kpatience;.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdegraphics</term> +<listitem> +<para>Optional</para> +<para>Various graphics-related programs like &PostScript; previewer, +&DVI; previewer, and a drawing program.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdeutils</term> +<listitem> +<para>Optional</para> +<para>Various desktop tools like a calculator, an editor and other +nifty stuff.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdemultimedia</term> +<listitem> +<para>Optional</para> +<para>Multimedia applications like a &CD; player and a mixer.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdenetwork</term> +<listitem> +<para>Optional</para> +<para>Network applications. Currently contains the instant messaging client &kopete;, the +download manager &kget;, and several other network-related programs.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdepim</term> +<listitem> +<para>Optional</para> +<para>Personal information management tools. Contains the email client &kmail;, the newsreader &knode; and other related programs.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdeadmin</term> +<listitem> +<para>Optional</para> +<para>System administration programs.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdeedu</term> +<listitem> +<para>Optional</para> +<para> +Educational and entertaining applications for &kde;'s younger users. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdeaccessibility</term> +<listitem> +<para>Optional</para> +<para> +KDE accessibility programs such as a screen magnifier and speech synthesizer front end. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdetoys</term> +<listitem> +<para>Optional</para> +<para>Toys!</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdevelop</term> +<listitem> +<para>Optional</para> +<para>A complete Integrated Development Environment for &kde; and Qt</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdewebdev</term> +<listitem> +<para>Optional</para> +<para>Web development applications. Contains such applications as &quanta;, an integrated web development environment and other applications useful in web development</para> +</listitem> +</varlistentry> +<varlistentry> +<term>kdesdk</term> +<listitem> +<para>Optional</para> +<para>KDE Software Development Kit. Contains a collection of applications and tools used by KDE Developers.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>&arts; and then kdelibs should be installed before everything +else, and kdeaddons last. The other packages can be installed in any +arbitrary order.</para> + +<para>Most package management tools will let you put all these +packages in one folder and install them all at once, figuring out +the dependencies as they go.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Installation instructions for the different package +formats</para> +</question> +<answer> +<para><important> +<para>Please do not forget to read the <filename>README</filename> and <filename>INSTALL</filename> files if they are available.</para> +</important></para> +<variablelist> +<varlistentry> +<term>Installation of the Debian packages</term> +<listitem> +<para>The Debian packages install in accordance with the upcoming <acronym>FHS</acronym> (File +Hierarchy Standard).</para> +<procedure> +<step performance="required"><para>become superuser</para></step> +<step performance="required"><para>run <command>dpkg <option>-i +<replaceable>packagename.deb</replaceable></option></command> for +every package you want to install.</para></step> +</procedure> +</listitem> +</varlistentry> +<varlistentry> +<term>Installation of the <acronym>RPM</acronym> packages</term> +<listitem> +<procedure> +<title>To install binary <acronym>RPM</acronym>s</title> +<step performance="required"><para>become superuser</para></step> +<step performance="required"><para>execute <command>rpm <option>-ivh +<replaceable>packagename.rpm</replaceable></option></command></para></step> +</procedure> +</listitem> +</varlistentry> +<varlistentry> +<term>Installation of the source <filename>.tar.bz2</filename> files</term> +<listitem> +<para>Since there are always changes and updates to the way &kde; is compiled, please +refer to <ulink url="http://developer.kde.org/build/index.html">Download and Install from Source</ulink> for the most up to date installation instructions for the source packages. +</para> +<para>The general approach should work in most cases though. +</para> +<para>The source <filename>.tar.bz2</filename> package installs into <filename +class="directory">/usr/local/kde</filename> by default. You can +override this setting by using the <option>--prefix</option> option of +the <filename>configure</filename> script.</para> +<procedure> +<step performance="required"><para>unpack the packages with <command>tar <option>jxvf +<replaceable>packagename.tar.bz2</replaceable></option></command></para></step> +<step performance="required"><para>change folder to the package folder: <command>cd +<replaceable>packagename</replaceable></command></para></step> +<step performance="required"><para>configure the package: <command>./configure</command> +<note><para>Some packages (notably kdebase) have special configuration +options that might be applicable to your installation. Type +<command>./configure <option>--help</option></command> to see the +available options.</para></note></para></step> +<step performance="required"><para>build the package: <command>make</command></para></step> +<step performance="required"><para>install the package: <command>su <option>-c "make +install"</option></command> (if you aren't already root). If you +already are, just type <command>make +<option>install</option></command>.</para></step> +</procedure> +</listitem> +</varlistentry> +</variablelist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Post-installation procedures</para> +</question> +<answer> +<para>First of all, please make sure that you have added &kde;'s binary +installation folder (⪚ <filename +class="directory">/usr/local/kde/bin</filename>) to your <envar>PATH</envar> +and &kde;'s +library installation folder to your <envar>LD_LIBRARY_PATH</envar> (only +necessary on systems that do not support rpath; on &Linux; &ELF;, it +should work without). This environment variable may be called +differently on some systems, ⪚ it is called +<envar>SHLIB_PATH</envar> on &IRIX;. Then set the environment variable +<envar>KDEDIR</envar> to the base of your &kde; tree, ⪚ <filename +class="directory">/usr/local/kde</filename>. +<caution> +<para>Please bear in mind that it is unwise to set +<envar>LD_LIBRARY_PATH</envar> blindly. In the vast majority of cases it is +unnecessary and can do more harm than good. There is a web page +written by <ulink url="mailto:[email protected]">Dave +Barr</ulink> explaining the evils of <envar>LD_LIBRARY_PATH</envar> and it can be +found at <ulink +url="http://www.cis.ohio-state.edu/~barr/ldpath.html">http://www.cis.ohio-state.edu/~barr/ldpath.html</ulink>.</para> +</caution> +</para> +<para>Even though you can use most of the &kde; applications simply by +calling them, you can only benefit fully from &kde;'s advanced +features if you use the &kde; window manager and its helper +programs.</para> +<para>In order to make it easy for you, we have provided a simple +script called <filename>startkde</filename> which gets installed in <filename +class="directory">$<envar>KDEDIR</envar>/bin</filename> and is therefore in your +path.</para> +<para>Edit the file <filename>.xinitrc</filename> in your home folder (make a backup +copy first!), remove everything that looks like calling a window +manager, and insert <command>startkde</command> instead. Restart the &X-Server;. If you use +&kdm;/<application>xdm</application>, you will have to edit the file <filename>.xsession</filename> instead of +<filename>.xinitrc</filename>. And if there is no <filename>.xinitrc</filename> or <filename>.xsession</filename> in your home +folder, simply create a new one with just one line containing +<command>startkde</command>. +<note> +<para>Some systems (notably &RedHat; &Linux;) use <filename>.Xclients</filename> +instead.</para> +</note></para> +<para>This should present you with a new shining &kde; desktop. You +can now start to explore the wonderful world of &kde;. In case you +want to read some documentation first, there is a highly recommended +<ulink +url="http://www.kde.org/documentation/quickstart/index.html">Quick Start +guide</ulink> available. Furthermore, every application has an online +help that is available via the <guimenu>help</guimenu> menu.</para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>Should I remove old version xyz before installing a new +one?</para> +</question> +<answer> +<para>In principle, this is not necessary. <acronym>RPM</acronym> and Debian packages +should take care of all dependencies.</para> +<para>If you compile the source code yourself, you should take more care. +Instructions for running two different versions of &kde; on the same system are +given at <ulink +url="http://developer.kde.org/build/kde2-and-kde3.html">http://developer.kde.org/build/kde2-and-kde3.html</ulink>. +However, please note that running two different versions of &kde; from source +can lead to problems if you are not careful. </para> +</answer> +</qandaentry> + +<qandaentry> +<question id="startkde"> +<para>How do I start &kde;?</para> +</question> +<answer> +<para>The most comfortable method to start &kde; is to use the +<filename>startkde</filename> script. Simply put the line +<command>startkde</command> at the end of your <filename>.xsession</filename> +file (or your <filename>.xinitrc</filename> or <filename>.Xclients</filename> +file if you are not using &kdm; or <application>xdm</application>). Please +also remove the lines that start your previous window manager. If there is no +<filename>.xsession</filename>, <filename>.xinitrc</filename>, or +<filename>.Xclients</filename> in your home folder, simply create a new one +that contains just one line: <command>startkde</command>.</para> +</answer> +</qandaentry> +<!-- Still needed? +<qandaentry> +<question> +<para>Whenever I start &kde;, it complains about "shadow passwords". +Why?</para> +</question> +<answer> +<para>When your system uses shadow passwords, the screensaver can only +run properly if the suid bit is set. This bit gives the screensavers +root privileges, which are needed to access the shadow passwords. +<caution><para>The screensavers might be configured to secure the +machine until the password is entered.</para></caution></para> +<procedure> +<title>Setting the suid bit on the screensavers</title> +<step performance="required"><para>become root</para></step> +<step performance="required"><para><command>chown root +$<envar>KDEDIR</envar>/bin/*.kss</command></para></step> +<step performance="required"><para><command>chmod u+s +$<envar>KDEDIR</envar>/bin/*.kss</command></para></step> +</procedure> +<para>Alternatively, if you compile &kde; from source, you can use +<command>./configure <option>with-shadow</option></command> to +configure kdebase. Then the suid bit is set automatically during +<command>make install</command>.</para> +</answer> +</qandaentry> +--> +<qandaentry> +<question> +<para>Is it possible to install &kde; in my home directory?</para> +</question> +<answer> +<para>Yes, you can install &kde; in any folder you want. What you +have to do depends on the kind of packages you want to install:</para> +<procedure><title>Source packages</title> +<step performance="required"><para>Configure and install the package using <command>configure +<option>--prefix=<replaceable>/home/me</replaceable></option>; +make; make install</command> to install into <filename +class="directory">/home/me</filename>. Replace <replaceable>/home/me</replaceable> with your home directory, generally defined in <envar>$HOME</envar></para></step> +<step performance="required"><para>Add the following to your init files. Please note that if +it is not necessary for you to set <envar>LD_LIBRARY_PATH</envar>, it +is better to leave it out.</para> + +<para>For csh or tcsh:</para> +<programlisting> +setenv KDEDIR /home/me + +if ( $?LD_LIBRARY_PATH ) then + setenv LD_LIBRARY_PATH $KDEDIR/lib:$LD_LIBRARY_PATH +else + setenv LD_LIBRARY_PATH $KDEDIR/lib +endif + +if ( ! $?LIBRARY_PATH ) then + setenv LIBRARY_PATH $LD_LIBRARY_PATH +endif +</programlisting> +<para>For <application>bash</application>:</para> +<programlisting> +KDEDIR=/home/me +PATH=$KDEDIR/bin:$PATH +LD_LIBRARY_PATH=$KDEDIR/lib:$LD_LIBRARY_PATH +LIBRARY_PATH=$LD_LIBRARY_PATH +export KDEDIR PATH LD_LIBRARY_PATH LIBRARY_PATH +</programlisting></step> +</procedure> +<procedure><title><acronym>RPM</acronym> packages</title> +<step performance="required"><para><command>rpm</command> allows you to use the +<option>--prefix</option> option to select the folder you want to +install to. For example, executing <command>rpm <option>-i +--prefix=<replaceable>/home/me +package.rpm</replaceable></option></command> will install the package +to <filename +class="directory">/home/me</filename>.</para></step> +</procedure> +<para><note> +<para>Although &kde; will run from a user folder, there are some +problems with programs that require suid root, ⪚ the programs in +the kdeadmin package. But since they are not meant to be run by users +in the first place, this is nothing to worry about.</para> +<para>However, on systems using shadow passwords, the screensavers +have to be suid root to enable password access for unlocking the +screen, so this option will not work.</para> +</note></para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para><command>startkde</command> fails with <errorname>can not connect to X +server</errorname>. What is wrong?</para> +</question> +<answer> +<para>You probably tried to start the X server with <command>startkde</command>. The X +server is started with <command>startx</command>. +<command>startkde</command> is the +script that should be run from your <filename>.xinitrc</filename>, <filename>.xsession</filename>, or +<filename>.Xclients</filename> to activate the window manager and the necessary server +daemons for &kde;. See also <xref linkend="startkde"/>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>&kde; on &AIX;?</para> +</question> +<answer> +<para> +<!-- +<para>If you have trouble building &kde; on +&AIX; check out Stefan Westerfeld's <ulink +url="http://space.twc.de/~stefan/kde/aix.html">Running &kde; on +Aix</ulink> page for lots of help on building &kde; on this +exceptional &UNIX; variant.</para> +--> +<acronym>IBM</acronym> now officially support &kde; on &AIX;. You can find +details at <ulink +url="http://www.ibm.com/servers/aix/products/aixos/linux/index.html">http://www.ibm.com/servers/aix/products/aixos/linux/index.html</ulink>. +There is also some older information at <ulink url="http://space.twc.de/~stefan/kde/aix.html">http://space.twc.de/~stefan/kde/aix.html</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>&kde; on a laptop?</para> +</question> +<answer> +<para>If you can get &X-Window; to run on your laptop, you should not have any problem +getting &kde; to run on it. In addition, you might find the following +links helpful:</para> +<itemizedlist> +<listitem> +<para><ulink url="http://www.linux-laptop.net/">http://www.linux-laptop.net/</ulink></para> +</listitem> +<listitem> +<para><ulink url="http://www.sanpei.org/Laptop-X/note-list.html">http://www.sanpei.org/Laptop-X/note-list.html</ulink></para> +</listitem> +</itemizedlist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>I do not like the default &kde; folder after installation. How +do I move it without breaking anything?</para> +</question> +<answer> +<para>Assuming the default is <filename +class="directory">/opt/kde</filename> and you want to move it to +<filename class="directory">/usr/local/kde</filename>, here's what +you have to do:</para> +<procedure> +<step performance="required"><para>change to superuser if you aren't already</para></step> +<step performance="required"><para><command>mv /opt/kde /usr/local/kde</command></para></step> +<step performance="required"><para><command>ln -s /usr/local/kde +/opt/kde</command></para></step> +</procedure> +<para>This will put all your &kde; files in <filename +class="directory">/usr/local/kde</filename> but everything is +still accessible from <filename +class="directory">/opt/kde</filename>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What files can I delete from my &kde; install folder? Can all the +<filename>*.h</filename>, <filename>*.c</filename> and <filename>*.o</filename> +files be safely removed?</para> +</question> +<answer> +<para>There should not be any need to keep the <filename>.c</filename> and +<filename>.o</filename> files, but you might want to keep the +<filename>.h</filename> files, as they are used by includes if you ever want to +compile your own &kde; programs. But if you wish to add patches to the source +programs as they become available (rather than downloading everything again), +then they should stay.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Will I lose my current settings when I upgrade &kde;?</para> +</question> +<answer> + +<para>No. In most cases &kde; will be able to transport your settings +intact. You may need to reenter passwords in some applications (such +as &kmail; or &knode;) but most other settings will be safe.</para> + +<para>There were mixed reports of results between some previous +versions of &kde;. To be safe, you may like to back up your entire +&kde; configuration. </para> + +<para>Settings are kept in the <filename +class="directory">$<envar>HOME</envar>/.kde</filename> or <filename +class="directory">$<envar>HOME</envar>/.kde2</filename> subfolder in your home +folder. Copy your +old <filename class="directory">.kde</filename>/<filename +class="directory">.kde2</filename> folder to a backup location, +install &kde; 3.2, and then copy back any necessary mail and news +settings. That said, most people can make a direct upgrade, without +removing the old <filename class="directory">.kde</filename> folder, + without a hitch.</para> +<para>You can override the use of <filename +class="directory">$<envar>HOME</envar>/.kde</filename> by setting the +$<envar>KDEHOME</envar> variable.</para> +</answer> +</qandaentry> + +<qandaentry id="greyscreen"> +<question> +<para>I upgraded &kde; and it seemed to go fine, but when I start it, +I get a blank gray screen, and nothing happens. There are errors in +the console about DCOPserver. What's going on?</para> +</question> + +<answer> +<para> +&kde; uses several temporary files during its operation. +These are usually to be found in the following locations:</para> +<itemizedlist> +<listitem><para><filename>~/.DCOPserver-*</filename> (there are usually two of these; one is a symlink to the other)</para></listitem> +<listitem><para><filename>~/.kde/socket-<replaceable>hostname</replaceable></filename></para></listitem> +<listitem><para><filename>~/.kde/tmp-<replaceable>hostname</replaceable></filename> which is normally a symlink to the next file:</para></listitem> +<listitem><para><filename>/tmp/tmp-kde-<replaceable>USER</replaceable></filename></para></listitem> +<listitem><para><filename>~/.kde/socket-<replaceable>hostname</replaceable></filename> which is also normally a symlink to:</para></listitem> +<listitem><para><filename>/tmp/ksocket-<replaceable>USER</replaceable></filename></para></listitem> +</itemizedlist> + +<para>If the symlinks get broken, usually because a +<command>cron</command> or shutdown script is emptying out the +<filename class="directory">/tmp</filename> folder, then strange +things will happen. These files, and the symlinks, will all be +created automatically at the start of &kde; so you can safely remove +them <emphasis>while &kde; is not running</emphasis>.</para> + +<para>If you are only getting a gray screen when you start &kde;, or if you get an error message telling you to <errorname>Check your installation</errorname>, then shut down X and delete all the files listed above, then try to restart X.</para> + +<para>Normally (&ie; when not upgrading between &kde; versions) it's +quite safe to leave these files intact, and you may shave a few +seconds off your &kde; startup time by doing so.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Compiling kdebase gives me a <errorname>bin/sh: msgfmt: command +not found</errorname> error!</para> +</question> +<answer> +<para>You need the &GNU; <application>msgfmt</application> which is +part of the &GNU; i18n package <application>gettext</application>. +You should be able to download it from any +&GNU; mirror.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I uninstall &kde; applications compiled from +source?</para> +</question> +<answer> +<para>You can uninstall your programs by typing <command>make +uninstall</command> in the folder where you did <command>make +install</command>. If you have already deleted that folder, +then there is only one way, and it is not good: go to <filename +class="directory">$<envar>KDEDIR</envar>/bin</filename> and start deleting files +one by one.</para> +<para>If you expect to find yourself in this situation, you might want to +consider a program such as &GNU; <application>stow</application>, found at +<ulink url="http://www.gnu.org/software/stow/stow.html">http://www.gnu.org/software/stow/stow.html</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question id="gif"> +<para>What is up with &GIF; support?</para> +</question> +<answer> +<para>This has to do with issues with Unisys' &LZW; patent. &GIF; +support is turned off from &Qt; 1.44 onwards by default. When you want to use +&GIF;s and have the relevant license, recompile &Qt; with &GIF; support. +<command>./configure <option>-gif</option></command>.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> diff --git a/doc/faq/intro.docbook b/doc/faq/intro.docbook new file mode 100644 index 000000000..6f9546791 --- /dev/null +++ b/doc/faq/intro.docbook @@ -0,0 +1,93 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="introduction"> +<title>Introduction</title> + +<qandaset> +<qandaentry> +<question> +<para>What is &kde;?</para> +</question> +<answer> +<para>&kde; is the K Desktop Environment. It is a project initiated +by <ulink url="mailto:[email protected]">Matthias Ettrich</ulink> in +1996. The aim of the &kde; project is to connect the +power of the &UNIX; operating systems with the comfort of a modern user +interface.</para> +<para>In short, &kde; will bring &UNIX; to the desktop!</para> +<para>If you want further information about &kde;, have a look at +<ulink url="http://www.kde.org/whatiskde">What is +&kde;?</ulink></para> +</answer> +</qandaentry> + +<qandaentry> +<question id="platform"> +<para>On which platforms can I expect &kde; to work?</para> +</question> +<answer> +<para>&kde; is a Desktop Environment for all flavors of &UNIX;. While +it is true that most &kde; developers use &Linux;, &kde; runs smoothly +on a wide range of systems. You may, however, need to tweak the +source code a bit to get &kde; to compile on a not-so-popular variant +of &UNIX;, or if you are not using the &GNU; development tools, in +particular the &gcc; compiler.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is &kde; a window manager?</para> +</question> +<answer> +<para>No, &kde; is not a window manager. While &kde; includes a very +sophisticated window manager (&kwin;), &kde; is much more than that. +It is a full-blown Integrated Desktop Environment.</para> +<para>&kde; provides a complete desktop environment, including a web +browser, a file manager, a window manager, a help system, a +configuration system, uncountable tools and utilities, and an ever +increasing number of applications, including but not limited to mail +and news clients, drawing programs, a &PostScript; and a &DVI; viewer +and so forth.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is &kde; a <acronym>CDE</acronym>, &Windows; or &Mac; +<acronym>OS</acronym> clone?</para> +</question> +<answer> +<para>No, &kde; is not a clone. Specifically &kde; is not a +<acronym>CDE</acronym> or &Windows; clone. While the &kde; developers +have and will continue to glean the best features from all existing +desktop environments, &kde; is a truly unique environment that has and +will continue to go its own way.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is &kde; free software?</para> +</question> +<answer> +<para>Yes, &kde; is free software according to the &GNU; General +Public License. All &kde; libraries are available under the +<acronym>LGPL</acronym> making commercial software development for the +&kde; desktop possible, but all &kde; applications are licensed under +the <acronym>GPL</acronym>.</para> +<para>&kde; uses the <link linkend="qt">&Qt; C++ crossplatform +toolkit</link>, which is also released (since version 2.2) under the +<acronym>GPL</acronym>.</para> +<para>It is absolutely legal to make &kde; and &Qt; available on +&CD-ROM; free of charge. No runtime fees of any kind are +incurred.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> + diff --git a/doc/faq/kdeapps.docbook b/doc/faq/kdeapps.docbook new file mode 100644 index 000000000..95ff1355b --- /dev/null +++ b/doc/faq/kdeapps.docbook @@ -0,0 +1,158 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="applications"> +<title>&kde; applications</title> + +<qandaset> +<qandaentry> +<question> +<para>&kppp;</para> +</question> +<answer> + +<para>Many &kde; users report problems using &kppp;. But before you +complain about &kppp;, make sure you have already checked the +following:</para> + +<itemizedlist> +<listitem><para>Can you dialup to your <acronym>ISP</acronym> without using &kppp;? If you cannot, then perhaps &kppp; is not the culprit after +all.</para></listitem> +<listitem><para>Have you gone through the &kppp; documentation at +least three times and followed its instructions and trouble-shooting +suggestions?</para></listitem> +</itemizedlist> +<para>The &kppp; documentation can be accessed through the +<application>&kde; Help Center</application>. + Last, but not least, the &kppp; homepage is at <ulink + url="http://ktown.kde.org/~kppp/">http://ktown.kde.org/~kppp/</ulink>.</para> +<para>Now, if you still encounter problems, here's what might help you +solve them:</para> +<variablelist> +<varlistentry><term>How do I change the &MTU; setting in &kppp;?</term> +<listitem><para>Open up the &kppp; dialog box and select +<guibutton>Setup</guibutton>. Choose an existing account and click +<guibutton>Edit</guibutton>, or <guibutton>New</guibutton> to create a +new dialup account. Select the <guilabel>Dial</guilabel> tab and +click <guibutton>Arguments</guibutton>. Type what you want to change +in the Argument textbox (⪚ <userinput>mtu 296</userinput>) and +click <guibutton>Add</guibutton>. When you are satisfied, click +<guibutton>Close</guibutton>.</para> +<para>To check whether the options <quote>took</quote>, do one of the following:</para> +<itemizedlist> +<listitem> +<para>In a terminal window, run +<userinput><command>/sbin/ifconfig</command> ppp0</userinput> and look +at the reported &MTU; in the output. It should match your +request.</para> +</listitem> +<listitem><para>Add <option>debug</option> and <option>kdebug</option> +(each on a separate line) to your +<filename>/etc/ppp/options</filename> file and restart your +&PPP; session. You will find debugging messages in +<filename>/var/log/messages</filename>, including &MRU; and &MTU; +settings.</para></listitem> +</itemizedlist> +<para>If you want, the &MRU; and &MTU; settings can be added to the +<filename>options</filename> file, one complete setting per line, no +quotes or dashes.</para></listitem> +</varlistentry> +<varlistentry> +<term>&kppp; connects at a slower speed than +normal.</term> +<listitem><para>The following might do the trick:</para> +<itemizedlist> +<listitem><para>Try executing <command>setserial +spd_hi</command>.</para></listitem> +<listitem><para>The default &MTU; value is 1500, +which maybe too large +for a dialup connection. Try changing it to a smaller value like +<userinput>296</userinput> +or <userinput>576</userinput>.</para></listitem> +<listitem><para>Check in your <filename +class="directory">$<envar>HOME</envar>/.kde/share/config</filename> for the +<filename>kppprc</filename>. Ensure the correct modem speed is +actually defined there.</para></listitem> +</itemizedlist></listitem> +</varlistentry> +</variablelist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>&konsole;</para> +</question> +<answer> +<variablelist> + +<varlistentry> +<term>How do I page-up or page-down?</term> +<listitem><para>Use <keycombo action="simul"> +<keycap>Shift</keycap><keycap>Page Up</keycap></keycombo> +and <keycombo action="simul"><keycap>Shift</keycap><keycap>Pg +Dn</keycap></keycombo>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term>How do I perform a simple <quote>copy</quote> from &konsole; to +anything else?</term> +<listitem><para>When I do a <command>ls</command>, first I select with +the mouse the desired text, press +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo>, +then I make the target application active, point the mouse to the +relevant part and press <keycombo +action="simul">&Ctrl;<keycap>V</keycap></keycombo>. +Alternatively, highlight the text by dragging with the &LMB; down and +paste by clicking with the &MMB; (or both buttons if you are using a +2 button mouse with 3 button emulation). +</para></listitem> +</varlistentry> + +<varlistentry> +<term>Why can't &konsole; find the <quote>9x15</quote> and the 2 +<quote>console</quote> bitmap fonts installed with &kde;?</term> +<listitem> + +<para><application>FontConfig</application> must find the three fonts +installed in: <filename +class="directory">$<envar>KDEDIR</envar>/share/fonts</filename>. + If +the &kde; install does not install these fonts in a directory that +already exists (⪚ <filename +class="directory">/usr/share/fonts</filename>) then you must add this +directory to the configuration file <filename +class="directory">/etc/fonts/local.conf</filename>. This should be +the first line after <quote><fontconfig></quote>. For example: +<programlisting> +<fontconfig> +<dir>/usr/kde3/share/fonts</dir> +</fontconfig> +</programlisting> +After adding the directory, run (as root): +<userinput><command>fc-cache</command> -v</userinput> and check that +it found the directory.</para> +</listitem> +</varlistentry> + +</variablelist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>&kmail;</para> +</question> +<answer> +<para>&kmail; has its own home page at <ulink +url="http://kmail.kde.org">http://kmail.kde.org</ulink> where an +<acronym>FAQ</acronym> is available.</para> +</answer> +</qandaentry> + +</qandaset> +</chapter> diff --git a/doc/faq/misc.docbook b/doc/faq/misc.docbook new file mode 100644 index 000000000..61d2950f3 --- /dev/null +++ b/doc/faq/misc.docbook @@ -0,0 +1,219 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="misc"> +<title>Miscellaneous questions</title> + +<qandaset> + + +<qandaentry> +<question> +<para>Does &kde; support transparency and other visual effects provided by the new composite extension to X.org?</para> +</question> +<answer> +<para> Yes! An exciting new feature for &kde; 3.4 is support for the new X composite extension. This allows for effects such as translucency and drop shadows for all windows, easily configurable through &kwin;'s configuration dialog. This requires you to be using X.org version 6.8.0 or newer and have: + +<screen> +Section "Extensions" +Option "Composite" "Enable" +EndSection +</screen> + +In your <filename>xorg.conf</filename>. If you have an nvidia graphics card and use the nvidia driver you can improve the performance of these effects by also adding the RenderAccel option to the Device section for your graphics card: + +<screen> +Section "Device" + Identifier "nvidia-fx5200" + Driver "nvidia" + Option "RenderAccel" "true" +</screen> +Once you have configured X.org correctly, transparency and other effects can be enabled through the <menuchoice><guimenu>Desktop</guimenu><guimenuitem>Window Behavior</guimenuitem></menuchoice> &kcontrolcenter; module, under the <guilabel>Translucency</guilabel> tab. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What about &kde; programs that do not have icons? How do I get +them into the menu?</para> +</question> +<answer> +<para>Use &kmenuedit;. To access it use the &RMB; on the +<guibutton>K</guibutton> button and select <guimenu>Menu Editor</guimenu>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Does &kde; have a graphical &FTP; client?</para> +</question> +<answer> +<para>Yes, and it is none other than your favorite file +manager, &konqueror;. You can drag and drop remote files into local +folders.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I exit &kde;?</para> +</question> +<answer> +<para>Simply click on the <guibutton>K</guibutton> button and select +<guimenu>Logout</guimenu>. In addition, if you +<mousebutton>right</mousebutton> click on an +empty area of the desktop, you will be presented with a menu +containing logout as one of the options. +<note><para>Depending on your configuration of the &X-Window;, <keycombo +action="simul">&Ctrl;&Alt;&Backspace;</keycombo> +might also do the trick by killing the X server, but its use prevents +session management and cannot be recommended.</para></note></para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is there a program that checks for new mails at my +<acronym>ISP</acronym> if and only if I am online?</para> +</question> +<answer> +<para>&korn; will do the job. If you are not +connected, it will just sit there (idling).</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is it really necessary to upgrade to the latest version?</para> +</question> +<answer> +<para>We recommend to always use the latest stable release. If you +don't, it will probably be difficult to get answers to your +questions. If you have a problem with an old version, the answer will +probably be <quote>Please upgrade and try again</quote>. Note that +new versions also sometimes fix security problems.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I copy and paste in &kde;?</para> +</question> +<answer> +<para>The simplest method is to use your mouse:</para> +<procedure> +<step performance="required"><para>Highlight the text you want to copy by holding down the +&LMB; and dragging across the text. This adds the selected text to the clipboard.</para></step> +<step performance="required"><para>Go to the destination area; depending on your configuration, +you might need to click it using the &LMB; to give it +focus.</para></step> +<step performance="required"><para>Click the &MMB; to paste. If you have a two +button mouse and are emulating a three button mouse, push both buttons +simultaneously.</para></step> +</procedure> + +<para>For more information about using the clipboard in &kde; please see the &klipper; hand book, accessed by typing <userinput><command>help:/klipper</command></userinput> +into the &konqueror; address bar. </para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I convert the default &RedHat; menus into a menu in the +<guimenu>K</guimenu> menu?</para> +</question> +<answer> +<para>Click on the <guibutton>K</guibutton> button and select +<menuchoice><guimenu>System</guimenu><guimenuitem>Appfinder</guimenuitem></menuchoice>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question id="CVS"> +<para>What is <acronym>CVS</acronym>?</para> +</question> +<answer> +<para>It stands for Concurrent Versions System. It is a version +control system and is based on <acronym>RCS</acronym> (Revision +Control System), but +offers more functionality. It is used to maintain source code under +development. It will keep multiple versions of things (handy if you +broke something and have to back up and get a clean old version), and +allows people remote access over the Net to pick up the latest source +code and even to check in new files if they have permission. It is +also open source (you pay for support if you want it), and since it is +free it is the system of choice for people writing more free products, +such as &kde;.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Does &kde; support dual screen (Xinerama)?</para> +</question> +<answer> +<para>Yes, you need to have a multi-headed X server +(⪚ MetroX or XFree86 4.0 and above) and a &kde; >= 2.2.1 +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why does Drag and Drop not work with Xinerama?</para> +</question> +<answer> +<para>You should upgrade to XFree86 4.2.0 for this to work properly.</para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>How do I check which version of &kde; I am using?</para> +</question> +<answer> +<para>Fire up your <application>&kde; Control +Center</application>. It comes up with an Info Screen including the version of &kde; +The &kde; version is also included in the application's +<guimenuitem>About</guimenuitem> dialog. +</para> +</answer> +</qandaentry> + + + +<qandaentry> +<question> +<para>How do I go about creating themes and icons?</para> +</question> +<answer> +<para>Go see <ulink +url="http://artist.kde.org">http://artist.kde.org</ulink>. +There is also a more informal community of &kde; related artists and +artwork at <ulink url="http://kde-look.org">http://kde-look.org</ulink>. +</para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>How can I get to know about development updates?</para> +</question> +<answer> +<para>You might want to subscribe to the various &kde; mailing lists +available, especially kde-cvs, which lists all commits done to the +&kde; <acronym>CVS</acronym> repository. Check <ulink +url="http://lists.kde.org">http://lists.kde.org</ulink> if you want to +read without subscribing.</para> +</answer> +</qandaentry> +</qandaset> +</chapter> + diff --git a/doc/faq/moreinfo.docbook b/doc/faq/moreinfo.docbook new file mode 100644 index 000000000..9b28db3a2 --- /dev/null +++ b/doc/faq/moreinfo.docbook @@ -0,0 +1,154 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="more-info"> +<title>Getting more information</title> + +<qandaset> +<qandaentry> +<question> +<para>Where is the &kde; homepage?</para> +</question> +<answer> +<para>The &kde; homepage is located at <ulink +url="http://www.kde.org">http://www.kde.org</ulink>. If you prefer a +local mirror, there are several to choose from. For a current list of +web site mirrors sorted by location, please visit <ulink +url="http://www.kde.org/mirrors/web.php">http://www.kde.org/mirrors/web.php</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question id="mailing-lists"> +<para>Is there a &kde; mailing list?</para> +</question> +<answer> +<para>There are several &kde; mailing lists. Each focuses on a different +aspect of &kde;. Some are for developers, so they are not +discussed in detail. Some of the more important lists that users +might be interested in are:</para> +<variablelist> +<varlistentry><term>kde</term> +<listitem><para>This is the main &kde; mailing list for general +discussions.</para></listitem> +</varlistentry> +<varlistentry><term>kde-announce</term> +<listitem><para>This list is used to announce new versions of &kde; as +well as new tools and applications.</para></listitem> +</varlistentry> +<varlistentry><term>kde-look</term> +<listitem><para>This is the list that deals with questions about look and +feel, and general user interface considerations.</para></listitem> +</varlistentry> +</variablelist> +<para>For the complete list of mailing lists available, please refer +to <ulink +url="http://www.kde.org/mailinglists/">http://www.kde.org/mailinglists/</ulink>.</para> +<para>Please note that it is not a good idea to ask questions which are +already answered in this &FAQ;.</para> +</answer> +</qandaentry> + +<qandaentry> +<question id="subscribe"> +<para>How do I subscribe/unsubscribe to these lists?</para> +</question> +<answer> +<para>To subscribe, send an email to list-request, that is:</para> +<itemizedlist> +<listitem><para><ulink +url="mailto:[email protected]">[email protected]</ulink></para></listitem> +<listitem><para><ulink url="mailto:[email protected]">[email protected]</ulink></para></listitem> +<listitem><para><ulink url="mailto:[email protected]">[email protected]</ulink></para></listitem> +</itemizedlist> +<para>The email must contain <userinput>subscribe +<replaceable>your_email_address</replaceable></userinput> in the +subject.</para> +<para>To unsubscribe, send an email to list-request, that is:</para> +<itemizedlist> +<listitem><para><ulink url="mailto:[email protected]">[email protected]</ulink></para></listitem> +<listitem><para><ulink url="mailto:[email protected]">[email protected]</ulink></para></listitem> +<listitem><para><ulink url="mailto:[email protected]">[email protected]</ulink></para></listitem> +</itemizedlist> +<para>The email must contain <userinput>unsubscribe +<replaceable>your_email_address</replaceable></userinput> in the +subject. +<important><para>Never send subscribe/unsubscribe request to the +mailing lists directly! Use the list-request +instead.</para></important></para> +<para>There is also a complete list of all &kde;-related mailing +lists, and a web interface for subscribing and unsubscribing located +at <ulink url="http://master.kde.org/mailman/listinfo">http://master.kde.org/mailman/listinfo</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is there a mailing list archive?</para> +</question> +<answer> + +<para>Yes, there is a searchable mailing list archive hosted by <ulink +url="http://www.progressive-comp.com">Progressive Computer +Concepts</ulink>. The &URL; is <ulink +url="http://lists.kde.org">http://lists.kde.org</ulink>. There you +will see a folder listing of the mailing lists. Note that you can +only do a subject/author search at this level. You probably will not +find what you want doing this kind of search.</para> + +<para>To do a body search, you have to enter one of the mailing lists. +Just click on the folder you want to search (⪚ <quote>kde</quote> +or <quote>kde-devel</quote>) and then the pull-down menu by the search +box will default to <quote>Body</quote> searches. To be thorough, you +should probably search the <quote>kde</quote>, <quote>kde-linux</quote>, and <quote>kde-devel</quote> folders. </para> + +</answer> +</qandaentry> + +<qandaentry> +<question id="newsgroups"> +<para>Is there a newsgroup about &kde;?</para> +</question> +<answer> +<para>Yes, there is! It is at <literal>comp.windows.x.kde</literal>. +In addition, there is also a German newsgroup at +<literal>de.alt.comp.kde</literal>. Please note that it is not a good +idea to ask questions which are already answered in this +&FAQ;.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Are there any other &kde;-related +&FAQ;s?</para> +</question> +<answer> +<para>Yes. Here is a list of them:</para> +<itemizedlist> +<listitem><para><ulink +url="http://www.kde.org/info/faq.php">&kde; &FAQ;</ulink></para></listitem> +<listitem><para><ulink +url="http://konqueror.org/faq/">&konqueror; +&FAQ;</ulink></para></listitem> +<listitem><para><ulink +url="http://www.arts-project.org/doc/manual/index.html">aRts +sound server documentation</ulink></para></listitem> + +<!-- Removed because the kmail FAQ is part of the KMail manual and not a --> +<!-- separate document +<listitem><para><ulink +url="http://kmail.kde.org/manual/faq.html">&kmail; +&FAQ;</ulink></para></listitem> +--> + +</itemizedlist> +</answer> +</qandaentry> + +</qandaset> +</chapter> + diff --git a/doc/faq/nonkdeapps.docbook b/doc/faq/nonkdeapps.docbook new file mode 100644 index 000000000..e0e732548 --- /dev/null +++ b/doc/faq/nonkdeapps.docbook @@ -0,0 +1,106 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="non-kde-apps"> +<title>&kde; with non-&kde; applications</title> + +<!-- FIXME: This seems to be obsolete. The only similar option is "Apply +*colors* to --> + +<!-- non-kde apps" --> +<qandaset> +<qandaentry> +<question> +<para>My non-&kde; applications like &Emacs; and +<application>kterm</application> are running amok with strange +colors!</para> +</question> +<answer> +<para>Start the <application>&kde; Control Center</application> and in +<menuchoice><guimenu>Appearance & Themes</guimenu><guimenuitem> +Colors</guimenuitem></menuchoice> uncheck the <guilabel>Apply colors to +non-KDE applications</guilabel> checkbox and click +<guibutton>Apply</guibutton>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>How can I set my default web browser to be something other +than &konqueror;?</para></question> +<answer> +<para>If you are using &kde; 3.3 or later, open up the &kcontrolcenter; and +navigate to the <menuchoice><guimenu>KDE +Components</guimenu><guimenuitem>Component +Chooser</guimenuitem></menuchoice> panel. Select <guilabel>Web +Browser</guilabel> from the list on the left, then select <guilabel>Open +http and https URLs in the following browser:</guilabel> and type in the +name of the browser (⪚ <application>mozilla</application>, +<application>firefox</application>, <application>opera</application>, &etc;) +in the textbox.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How can I configure the style and fonts of <acronym>GTK</acronym> +applications within &kde; ? +</para> +</question> +<answer> +<para> +The simplest way to achieve this is to download and compile the +<acronym>gtk-qt</acronym> theme engine from <ulink +url="http://www.freedesktop.org/Software/gtk-qt"> +http://www.freedesktop.org/Software/gtk-qt</ulink>. This theme engine makes +your <acronym>GTK</acronym> applications look like your &kde; widget style +by calling functions from &Qt; instead of drawing the styles itself. Once +the theme engine has been installed, there will be a &kcontrolcenter; module +under <menuchoice><guimenu>Appearance & Themes</guimenu><guimenuitem>GTK +Styles and Fonts</guimenuitem></menuchoice>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>I have been hearing about this gecko kpart or &Qt; Mozilla, how do I +get these?</para> +</question> +<answer> +<para> +Good luck! The &Qt; Mozilla code is in Mozilla cvs, and not very stable as +of yet. In order to use it, you'll have to check out Mozilla from cvs +according to these instructions: +<ulink url="http://www.mozilla.org/cvs.html"> +http://www.mozilla.org/cvs.html</ulink>. Then, configure either the Mozilla +suite or the Firefox browser with the option +<command>--enable-default-toolkit=qt</command> in addition to any other +options you would like to enable. More instructions on building Mozilla can +be found <ulink url="http://www.mozilla.org/build">here</ulink>. +</para> +</answer> +</qandaentry> + +</qandaset> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +-->
\ No newline at end of file diff --git a/doc/faq/notrelated.docbook b/doc/faq/notrelated.docbook new file mode 100644 index 000000000..fd66e1a6c --- /dev/null +++ b/doc/faq/notrelated.docbook @@ -0,0 +1,232 @@ +<!-- if you want to validate this file separately, uncomment this prolog: + +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> + +--> + +<chapter id="not-kde"> +<title>Not really &kde;-related, but frequently asked nevertheless.</title> + +<qandaset> +<qandaentry> +<question> +<para>How do I change the screen resolution?</para> +</question> +<answer> +<para>Use <keycombo +action="simul">&Ctrl;&Alt;<keycap>+</keycap></keycombo> and <keycombo +action="simul">&Ctrl;&Alt;<keycap>-</keycap></keycombo> to cycle through +the resolutions you have defined in <filename>XF86Config</filename> (maybe under +<filename class="directory">/etc/X11</filename>; poke around first). +If you prefer to get your hands dirty, you can always edit the file +directly. By placing your favorite resolution at the beginning (or +making it the only one listed), &X-Window; will always start up with that +resolution. +<caution><para>Always make a backup copy of your <filename>XF86Config</filename> file +<emphasis>before</emphasis> you start editing it. Errors in this file +can render &X-Window; unusable.</para></caution> +<note><para>These instructions are only valid if you are running +version 3.3.x of the XFree86 server. If you are running XFree86 4.x, +you must consult with the <ulink url="http://xfree.org">XFree86(TM): +Home Page</ulink>.</para></note></para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I change the color depth?</para> +</question> +<answer> +<para>There is no way you can do this on the fly. You can either +start &X-Window; using <command>startx <option> -bpp +<replaceable>number</replaceable></option></command> where +<replaceable>number</replaceable> can be 8, 16, 24 or 32, depending on +the depth you want. Alternatively, if you are using +<application>xdm</application>/&kdm;, you +need to edit +<filename>/etc/X11/xdm/Xservers</filename> (may vary) and enter +<userinput>:0 local /usr/X11R6/bin/X -bpp 16</userinput> for 16 bit color +depth.</para> +<para>You can also edit the <filename>XF86Config</filename> file and add a line +like <userinput>DefaultColorDepth +<replaceable>number</replaceable></userinput> to Section "Screen". +The next time you start X, it will run with the newly-configured color +depth.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What can I do if I am using a 2-button mouse?</para> +</question> +<answer> +<para>Go buy a 3-button one, or use third button emulation. The third +button is emulated by pressing both the &LMB; and the &RMB; +together. You would need to enable <option>Emulate3Buttons</option> +in your <filename>XF86Config</filename> file. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What is a "sticky" window?</para> +</question> +<answer> +<para>In a virtual desktop environment with multiple virtual desktops, a +"sticky" window will stay put on the screen when you switch between +desktops, as if sticking to the glass of the screen. +<application>Xclock</application> is a typical candidate for sticking, +as you need to run only one instance of it, and it always stays with +you. </para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I replace the "X" mouse pointer with an arrow?</para> +</question> +<answer> +<para>The various types of cursor available in X are defined in +<filename class="headerfile">X11/cursorfont.h</filename>. You can +change it using <command>xsetroot -cursor_name +<replaceable>name_of_cursor</replaceable></command>. For example, I +have the following in my <filename>.Xclients</filename>:</para> +<screen> +xsetroot -cursor_name left_ptr +</screen> +<para>This will create the common left-angled pointer. To see other +alternatives, type <command>xfd -fn cursor</command>. And of course, +do not forget that <command>man xsetroot</command> is your +friend.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I extract/install diff files?</para> +</question> +<answer> +<para>To generate a context-diff suitable for patching, use +<command>diff -u <replaceable>old-file new-file</replaceable> > +<replaceable>patchfile</replaceable></command>. To apply the diff to +a file (<abbrev>i.e.</abbrev> "patch the file"), execute +<command>patch < <replaceable>patchfile</replaceable></command>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I get &Linux; to mount the floppy device for use with both +DOS and ext2 formatted floppies?</para> +</question> +<answer> +<para>Just specify the filesystem type as auto in +<filename>/etc/fstab</filename>. Auto detection works fine for DOS and +ext2.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I start &kde; with the <keycap>Num Lock</keycap> on?</para> +</question> +<answer> +<para>Have you tried <command>man setleds</command>? In addition, you +might want to edit your +<filename>$<envar>HOME</envar>/.Xmodmap</filename> and put the +following lines in:</para> +<screen> +! redefines numeric keypad to be used without NumLock +keycode 79 = 7 +keycode 80 = 8 +keycode 81 = 9 + +keycode 83 = 4 +keycode 84 = 5 +keycode 85 = 6 + +keycode 87 = 1 +keycode 88 = 2 +keycode 89 = 3 + +keycode 90 = 0 +keycode 91 = comma +keycode 86 = plus + +! deactivates NumLock key +keycode 77 = +</screen> +<para>Other possible alternatives:</para> +<itemizedlist> +<listitem><para><application>xkeycaps</application>: +<mousebutton>right</mousebutton> clicking should allow edits. You may +have to do this as root.</para></listitem> +<listitem><para><command>man XF86Config</command> and look under +section Keyboard.</para></listitem> +<listitem><para>Install <application>NumLockX</application>, which is +available from <ulink +url="http://dforce.sh.cvut.cz/~seli/en/numlockx">http://dforce.sh.cvut.cz/~seli/en/numlockx</ulink>.</para></listitem> +</itemizedlist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I take window or desktop screenshots?</para> +</question> +<answer> +<para>Use &ksnapshot;.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Is there a tool to make webpages?</para> +</question> +<answer> +<para>Yes, and there are a lot of them out there, including +<application>StarOffice</application>, <application>&Netscape; Composer</application>, and +<application>XEmacs</application>. +There are also many &kde; applications. To find the most current +list, go to <ulink url="http://kde-apps.org">kde-apps.org: The +Latest in &kde; Applications</ulink> and search for <emphasis>web +development</emphasis>. Try as many as possible and choose the one +most suitable to your needs.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What do all those acronyms like AFAIK mean?</para> +</question> +<answer> +<para><screen> +AAMOF: as a matter of fact +AFAIK: as far as I know +AISE: as I see it +BFN: bye for now +BION: believe it or not +BRB: be right back +BTW: by the way +CMIIW: correct me if I am wrong +FUD: fear, uncertainty, and doubt +FWIW: for what it's worth +FYI: for your information +HTH: hope this helps +IIRC: if I recall correctly +IMHO: in my humble opinion +LOL: laughing out loud +MYOB: mind your own business +PITA: pain in the ass +ROTFL: rolling on the floor laughing +RTFM: read the fine manual +SOP: standard operating procedure +TIA: thanks in advance +YMMV: your mileage may vary +</screen></para> +</answer> +</qandaentry> +</qandaset> +</chapter> diff --git a/doc/faq/panel.docbook b/doc/faq/panel.docbook new file mode 100644 index 000000000..5814dc613 --- /dev/null +++ b/doc/faq/panel.docbook @@ -0,0 +1,193 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + + +<chapter id="panel"> +<title>The panel</title> + + +<qandaset> +<qandaentry> +<question> +<para>How do I add applications to the &kde; panel (&kicker;)?</para> +</question> +<answer> +<para>There are several ways to add an application to the panel, of +which the easiest is to right-click on the panel, and from the context +menu which appears, select <menuchoice><guimenu>Panel +Menu</guimenu><guisubmenu>Add to +Panel</guisubmenu><guisubmenu>Application +Button</guisubmenu></menuchoice> and then the application for which +you want to add a link.</para> <para>For more ways of adding buttons +to the panel, refer to the &kicker; Handbook.</para> + +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>Is it possible to change the <guibutton>K</guibutton> button of +the panel to another picture?</para> +</question> +<answer> +<para>The simplest way is to download a new icon theme with a &kmenu; icon +you prefer from +<ulink url="http://www.kde-look.org">http://www.kde-look.org</ulink> and +install it using the &kcontrolcenter;.</para> +<para>In order to change only the &kmenu; icon you can overwrite the +<filename>kmenu.png</filename> image for every size in an icon theme set. +So, for &kde; default icons this would be <filename>$<envar>KDEDIR</envar>/share/icons/default.kde/<replaceable>size</replaceable>/apps/kmenu.png</filename>, +where <replaceable>size</replaceable> is one of the sizes included in the +&kde; icon theme. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +After an upgrade my &kmenu; appears to be empty! How can I get my menu back? +</para> +</question> +<answer> +<para> +In &kde; 3.2 and later local modifications to the &kmenu; are stored +in +<filename>$<envar>HOME</envar>/.config/menus/applications-kmenuedit.menu +</filename>. Try moving this file out of the way and then issuing the +command <userinput><command>kbuildsycoca</command> +<option>--noincremental</option></userinput>. This should restore you to the +default system menus. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>My desktop panel has disappeared. How can I get it +back?</para> +</question> + +<answer> + +<para>The panel disappearing is usually due to it crashing. This is +most often caused by loading an applet that has a fatal bug or due to +a bad installation of &kde; and/or the panel.</para> + +<para>The easiest way to get the panel back is to launch the +<guilabel>Run Command</guilabel> window by pressing <keycombo +action="simul">&Alt;<keycap>F2</keycap> </keycombo> and entering +<userinput><command>kicker</command></userinput> and then pressing the +<guibutton>OK</guibutton> button.</para> + +<para>If the panel continues to disappear, you may wish to either +remove or edit by hand your +<filename>$<envar>KDEHOME</envar>/share/config/kickerrc</filename> +file, where <filename +class="directory">$<envar>KDEHOME</envar></filename> is usually +<filename class="directory">~/.kde</filename>. If you choose to edit +it by hand, start by removing the applet entry groups.</para> + +</answer> +</qandaentry> + +<qandaentry><question> +<para>Where did the Icon Zooming option that used to be in &kicker; go? +</para></question> +<answer><para> +Icon zooming was not actively maintained and had caused severe bugs and usability issues. It was replaced in &kde; 3.4 by the new mouse over effects, which combine esthetics with useful information. +</para></answer> + +</qandaentry> + +<qandaentry> +<question><para>How can I start an application minimized to the system +tray?</para> +</question> +<answer> +<para>Use <command>ksystraycmd</command>. For example, to start a &konsole; hidden +in the system tray, run <userinput><command>ksystraycmd </command> +<option>--hidden</option> <command>konsole</command></userinput>. For +more information about <command>ksystraycmd</command>, see the section +<quote>Advanced Window Management</quote> in the &kde; +User Guide.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>How do I use the &Windows; key to open the &kmenu;?</para> +</question> + +<answer><para>Previous versions of &kde; provided a trick to allow you to +use the &Windows; key both as a modifier (so you could have shortcuts +like <keycombo action="simul"><keysym>Win</keysym><keycap>R</keycap> +</keycombo>), and as a regular key (so that pressing +<keysym>Win</keysym> on its own could open the &kmenu;). This feature +was removed for reasons of usability and accessibility, as well as +keeping the code clean. For current versions of &kde;, you have two +options: either use a different shortcut to open the &kmenu; (the +default is <keycombo action="simul">&Alt;<keycap>F1</keycap> +</keycombo>), or remap the <keysym>Win</keysym> key to be a regular +key, rather than a modifier.</para> + +<para>If you choose to do the second, here's one way: + +<orderedlist> +<listitem><para>Find the keycode for your <keysym>Win</keysym> key +using <command>xev</command>: Run the command +<userinput><command>xev</command></userinput> in a &konsole;, and +press the <keysym>Win</keysym> key. Look in the output of +<command>xev</command> for +<computeroutput>keycode <replaceable>n</replaceable></computeroutput>, +where <replaceable>n</replaceable> is the keycode of the +<keysym>Win</keysym> key.</para> +</listitem> + +<listitem><para>Use <command>xmodmap</command> to remap the +<keysym>Win</keysym> key. An appropriate command is <userinput><command>xmodmap +<option>-e</option> 'keycode +<replaceable>n</replaceable>=Menu'</command></userinput>.</para> +</listitem> + +<listitem><para>In the &kcontrolcenter;, go to +<menuchoice><guimenu>Regional & +Accessibility</guimenu><guimenuitem>Keyboard Shortcuts</guimenuitem> +</menuchoice> and set the shortcut for <guilabel>Popup Launch +Menu</guilabel> to the <keysym>Win</keysym> key. You should now be +able to popup the &kmenu; by pressing the <keysym>Win</keysym> key.</para> +</listitem> + +<listitem><para>One more step is required to save the changes across +settings: Create a file <filename>~/.kde/env/win-key.sh</filename> +(create the directory if it doesn't exist), and add the +<command>xmodmap</command> command you used previously to it. The +change should now be applied every time you start &kde;.</para> +</listitem> +</orderedlist> +</para> +</answer> +</qandaentry> + +</qandaset> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/faq/qt.docbook b/doc/faq/qt.docbook new file mode 100644 index 000000000..446089edc --- /dev/null +++ b/doc/faq/qt.docbook @@ -0,0 +1,76 @@ +<chapter id="licensing"> +<title>&Qt; and Licensing questions</title> + +<qandaset> + +<qandaentry> +<question id="qt"> +<para>What is &Qt;, by the way?</para> +</question> +<answer> +<para>&Qt; is a C++-based class library to build user interfaces. It +also includes many utility classes like string classes and classes +to handle input and output. It +provides most of the widgets you will see in a &kde; application: +menus, buttons, sliders, &etc;. &Qt; is a cross-platform library that +allows you to write code that will compile on &UNIX; systems as well as +&Windows; and embedded devices. You can learn more about &Qt; at <ulink +url="http://www.trolltech.com">http://www.trolltech.com</ulink>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why does &kde; use &Qt;?</para> +</question> +<answer> +<para>&Qt; is a very sophisticated toolkit that provides everything that +is needed to build a modern user interface. &Qt; is written in C++, thus +allowing object-oriented development which ensures efficiency and +code reuse in a project the size and scope of &kde;. In our opinion +there is no better toolkit available for &UNIX; systems and that it +would have been a grave mistake to try to build &kde; on anything but +the best.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why does &kde; not use gtk, xforms, xlib, whatever?</para> +</question> +<answer> +<para>There are a number of toolkits available. To provide a +consistent user interface and to keep used resources such as memory to +a minimum, &kde; can use only one of them. &Qt; was selected for the +reasons mentioned above.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>But &Qt; isn't free, is it?</para> +</question> +<answer> +<para>It is! As of September 4, 2000, version 2.2 of the &Qt; +libraries were licensed under the <acronym>GPL</acronym>, thereby +fulfiling all aspects of <quote>free software</quote>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can I write commercial software for &kde;?</para> +</question> +<answer> +<para>You can use the &kde; libraries to write <quote>commercial and +closed source</quote> as well as <quote>commercial and open +source</quote> software. If you write open source software you can +use the &Qt; free edition. But if you write closed source software +you may not use the &Qt; free edition; you need to obtain the &Qt; +professional edition from Troll Tech. </para> <para>If you want more +information, please contact <ulink +url="http://www.trolltech.com">Troll Tech</ulink> directly.</para> +</answer> +</qandaentry> +</qandaset> +</chapter>
\ No newline at end of file diff --git a/doc/faq/questions.docbook b/doc/faq/questions.docbook new file mode 100644 index 000000000..1f7db6b63 --- /dev/null +++ b/doc/faq/questions.docbook @@ -0,0 +1,160 @@ + +<chapter id="questions"> + +<title>Asking Questions</title> + +<para>Chances are, you have been linked to this document from IRC or a +mailing list. You've asked a question, and someone has told you that you +need how to ask more effectively. In order to get an appropriate, clear +answer you need to ask an appropriate, clear question in a manner that's +going to provide an incentive for people to take their time to help you. If +you appear to be rude, lazy or use bad or unclear language then chances are +your question will be ignored</para> + +<qandaset> +<qandaentry> + +<question><para>What do I do before I ask?</para></question> + +<answer><para>Read the documentation and &FAQ; for the application. There is +a wealth of &kde; documentation availible both in the help center and +online. A lot of time and effort has gone into this documentation, and +quite often the answer to your question is here. The general &kde; userguide +can be found by typing +<userinput><command>help:/userguide</command></userinput> into your +&konqueror; addressbar.</para> + +<para>Search the web: Usually googling for a specific error message or +searching mailing list archives can come up with a solution for you.</para> + +<para>Try it and see! Look through all the application options, read the +What's this? and tooltips for the ones you're not sure about. If you're +really unsure about an option save your data and then try it. As long as you +use some common sense, you are very unlikely to break anything by clicking +buttons.</para> + +<para>Above all, don't be lazy. If you show the people who you are asking +that you are able to troubleshoot and research in a logical manner, you're +showing them you're a reasonable person who is worth their time to +help. It's your problem and not theirs so the legwork is yours to do. Save +your helpers as much time as you can, they're busy people.</para> </answer> +</qandaentry> + +<qandaentry> +<question><para>Where do I ask?</para></question> + +<answer><para>Usually the best place to ask a question is on the +<acronym>IRC</acronym> channels and mailing lists devoted to user +questions. Don't post simple questions about using &kde; to the devel +channels and mailing lists, these are for technical discussions. Some good +places are #kde on irc.freenode.net, and the &kde; mailing +lists.</para></answer> </qandaentry> + +<qandaentry> +<question><para>How do I ask?</para></question> + +<answer><para>Try to word your questions in a manner that gives the most +information possible and is polite and courteous. Don't ask to ask, just +ask!</para> + +<para>Q: &kde; sucks, it's being slow</para> + +<para>Is not a question that is likely to get you a useful answer. It does +not give any useful information about troubleshooting the problem, and it +starts out attacking the software in a way that isn't productive.</para> + +<para>Q: Since upgrading &kde; on Slackware &Linux; from version 3.2.3 to +3.3.2 using sources, I have noticed it's being really slow — sometimes +applications take up to 20 seconts to launch. I am using the same user +configuration as I had with the previous version, and I have tried as a new +user. I can't find anything about this on the mailing lists or by a google +search. Could anyone point me to some information that could help?</para> + +<para>This question is polite, contains information to help people +troubleshoot the problem and shows your helpers what avenues you have +already tried.</para> + +<para>Don't assume automatically that the problem is the fault of +&kde;. Proceed as though this is your error, otherwise you will quickly +annoy people if it does indeed turn out to be your problem and not +&kde;.</para> + +<para>Use clear language with correct spelling. Watch out for any +ambiguities and make sure you think about what you say before you write +it. If you are asked for clarification, give it as best you can. &kde; is a +project where many of the users and developers are not native english +speakers and if you don't use correct english, misunderstandings may +ensue. Use the language appropriate to the channel or mailing list you are +in — if you don't, people who might have been able to help you may +ignore your message because it is not in a language they understand.</para> + +<para>Include all information that could be relevant, even if you're not +sure. Have you upgraded other software or hardware on your system, +particularly system libraries or a new kernel? These things could affect how +&kde; performs. Even if you cannot see a link, someone else might.</para> + +<para>Don't paraphrase error messages. Paste in the exact error, and if it's +more than a line or two don't paste them directly into an +<acronym>IRC</acronym> channel. Use a paste service like <ulink +url="http://www.rafb.net/paste/"> http://www.rafb.net/paste</ulink>. If you +must type them in by hand, be sure you are 100% accurate. When you provide +faulty information, your helpers cannot help you as easily. </para> + +<para>Follow up on your solution! Tell us if it worked, or if you have +solved it yourself in the meantime. This helps us know for sure if our +solution worked, and helps other users who may be searching mailing list +archives for a solution to the problem themselves.</para> </answer> +</qandaentry> + +<qandaentry> +<question><para>What do I do when told to look elsewhere?</para></question> + +<answer><para>When you're told <quote>google knows</quote> or <quote>google +is your friend</quote> then chances are, you have not followed the above +advice. You've not done your research, and the solution is probably one the +helper knows very well to be easy to find. When you're linked to a +<acronym>FAQ</acronym> or a usermanual don't ever say, <quote>No, I don't +want to have to read this I want you to just tell me</quote>. This is very +bad manners. If you cannot put in the effort to read the document, what is +the incentive for your helper to put in the time and effort to help you? If +you're told to go use google, take it graciously and do so.</para> </answer> +</qandaentry> </qandaset> + +<para>Above all, use common courtesy. &kde; users and developers are usually +volunteering their time out of an already very busy schedule, and like to +know that you are appreciating that they are helping you for free. Be +polite, say please and thank you and try to be pleasant and +friendly. </para> + +<para> Does this seem like a lot of trouble to ask a question? If you want +to be able to feel that people owe you an answer or support, then you're +quite welcome to pay for commercial support from companies that support +&kde; on &UNIX; platforms. If you don't want to pay money, then pay the +people who do this for free with your politeness and appreciation :)</para> + + +<para>If you think the answer to your question should be included in the +&kde; &FAQ; please feel free to submit any patches or suggestions to the +&kde; &FAQ; Maintainer, at <email>[email protected]</email></para> + + + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/faq/sound.docbook b/doc/faq/sound.docbook new file mode 100644 index 000000000..d7db604bc --- /dev/null +++ b/doc/faq/sound.docbook @@ -0,0 +1,55 @@ +<chapter id="sound"> +<title>Troubleshooting sound problems</title> + +<para>&kde; uses the &arts; sound system which is complex and powerful, +making it difficult for some users to troubleshoot when things go +wrong. Here are some tips to help you diagnose what it's doing when your +sound misbehaves :</para> + +<qandaset> +<qandaentry> +<question> +<para>How can I troubleshoot sound related problems in &kde;?</para> +</question> + +<answer><para> To check that sound is working independently of &arts;, make +sure that <command>artsd</command> isn't running and then try playing sound +through <application>XMMS</application> or another multimedia application +that isn't a part of &kde;. If that application doesn't play sound, then +your general sound setup is probably broken and it's not a &kde; +problem.</para> + +<para>Try playing sound with +<userinput><command>artsplay</command><option><replaceable> +/path/to/some/soundfile</replaceable></option></userinput>. Try various +formats, ogg, mp3 and wav. Any error messages there might be useful in +pointing you in the right direction.</para> + +<para>Try setting the &arts; output method to <acronym>OSS</acronym>. In the +&kcontrolcenter; go to <menuchoice><guimenu>Sound & Multimedia</guimenu> +<guimenuitem>Sound System</guimenuitem></menuchoice>. On the +<guilabel>Hardware</guilabel> tab, under <guilabel>Select the audio +device</guilabel> choose <guilabel>Open Sound System</guilabel>. If you are +running <acronym>alsa</acronym> this will use the <acronym>OSS</acronym> +emulation, which may give better or worse results.</para> + +<para>Running <userinput><command>artsd</command><option> -l +0</option></userinput> from a terminal will give you a lot of debug output, +some of which might help you to diagnose the problem. Trying this in +conjunction with using <command>artsplay</command> in a second terminal can give a wealth of information. If an <application>artsd</application> instance is already running, exit it with <userinput><command>artsshell +</command><parameter>terminate</parameter></userinput></para> +</answer> +</qandaentry> +<qandaentry> +<question><para> +I've upgraded to the latest version of &kde; keeping my old configuration, and my system sounds don't work anymore!</para></question> +<answer><para> +Assuming you've installed &arts; correctly and you still have the codecs installed your previous &kde; installation needed, chances are this is a small problem with your <filename>knotifyrc</filename>. To confirm this, try creating an entirely new user and seeing if system notifications work under the new account. If they do, try moving your <filename>$<envar>KDEHOME</envar>/share/config/knotifyrc</filename> out of the way for your original user to see if this solves the problem. +</para></answer> +</qandaentry> + + +</qandaset> + +</chapter> + diff --git a/doc/faq/tips.docbook b/doc/faq/tips.docbook new file mode 100644 index 000000000..d47709095 --- /dev/null +++ b/doc/faq/tips.docbook @@ -0,0 +1,137 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + +<chapter id="tips"> +<title>Useful tips</title> + +<qandaset> +<qandaentry> +<question> +<para>Reading documentation in &kde;</para> +</question> +<answer> +<para>Pop up the <guilabel>Run Command</guilabel> window (<keycombo +action="simul">&Alt;<keycap>F2</keycap></keycombo> by +default) and type: +<itemizedlist> +<listitem> +<para><command>man:<replaceable>command</replaceable></command> for man pages. It +even unpacks on the fly if the man pages are gzipped.</para> +</listitem> + +<listitem> +<para><command>info:<replaceable>command</replaceable></command> for info +pages.</para> +</listitem> + +<listitem> +<para><command>help:<replaceable>kdeappname</replaceable></command> for &kde; +application help pages.</para> +</listitem> + +</itemizedlist> +</para> + +<para>You can also enter any of these in the <guilabel>Location</guilabel> text +box in &konqueror;.</para> +<para>Or you can use the <application>&kde; Help Center</application> if you are using &kde; +2. Simply start the <application>&kde; Help Center</application> by clicking on the icon (the blue +book with the yellow key) on the toolbar. Once the <application>&kde; Help Center</application> has +loaded, the window on the left will contain an entry called +<guilabel>Unix manual pages</guilabel>. Click once on this entry, and +you can browse through all the installed manual pages on your +system.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Move or resize windows quickly</para> +</question> +<answer> +<para>To move a window, use <keycombo +action="simul">&Alt;<mousebutton>left</mousebutton></keycombo> mouse +button. <keycombo +action="simul">&Alt;<mousebutton>right</mousebutton></keycombo> mouse +button will resize the window. Last but not least, <keycombo +action="simul">&Alt;<mousebutton>middle</mousebutton></keycombo> mouse button +raises/lowers the window. The <application>&kde; Control Center</application> +allows you to change these mouse bindings.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Killing windows in &kde;</para> +</question> +<answer> +<para>There is a standard keybinding (<keycombo +action="simul">&Ctrl;&Alt;&Esc;</keycombo>) +that gives you a skull & crossbones cursor. Click that cursor on a +window to kill it. The keybindings are viewable/changeable from the +<application>&kde; Control Center</application>. + +<caution><para>Using this option kills the program forcibly. Data may be lost, +and some processes related to the program may remain active. Use only as a +last resort.</para></caution> +<!-- fixme: use only if necessary; processes might remain --></para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What if something is so wrong that I can't even get the skull +& crossbones cursor? How do I get out of a total lockup?</para> +</question> +<answer> +<para>These kind of locks tend to occur when an application locks up +while it has a so called <quote>mouse/keyboard grab</quote>. When that +happens you can try to select a virtual text console with <keycombo +action="simul">&Ctrl;&Alt;<keycap>F1</keycap></keycombo> and login. With the +following command you will get a list of all running processes:</para> + +<screen><userinput> <command>ps</command> <option>-aux</option> | <command>more</command></userinput></screen> + +<para>By killing the process that has the mousegrab, your desktop will +come to life again. Unfortunately you can't see which process that is, +so you will have to find out through trial and error. To kill a process +use:</para> + +<screen><userinput> <command>kill</command> <option>-9</option> <replaceable>pid</replaceable></userinput></screen> + +<para>Here <replaceable>pid</replaceable> is the process id of the +process, which is the first number on each line reported by +<command>ps</command> <option>-aux</option>.</para> + +<para>You can switch back to the desktop with <keycombo +action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo> (or +<keycap>F8</keycap> through <keycap>F9</keycap> depending on your +operating system) to see if things work again. When you press +<keycombo action="simul">&Alt;<keycap>Tab</keycap></keycombo> you should get a +response from the window manager. If not, you need to get back to the +text console and try to kill another process.</para> + +<para>Good candidates to kill are: the application you were working +with, &kicker;, &klipper; and &kdesktop;.</para> +</answer> +</qandaentry> + +<!-- fixme: how to do in KDE2.x +<qandaentry> +<question> +<para>Switching window managers on the fly in &kde; 1.x</para> +</question> +<answer> +<para>If you want to switch your window manager on the fly, type the +following into a terminal window: <command>kwmcom +go:<replaceable>blackbox</replaceable></command>. This switches to +Blackbox, but you can substitute any window manager you like.</para> +</answer> +</qandaentry> +--> + +</qandaset> +</chapter> diff --git a/doc/faq/webbrowse.docbook b/doc/faq/webbrowse.docbook new file mode 100644 index 000000000..b80c7ae1a --- /dev/null +++ b/doc/faq/webbrowse.docbook @@ -0,0 +1,222 @@ +<!-- <?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> --> + +<chapter id="webbrowser"> +<title>Webbrowsing with &konqueror;</title> +<para>&konqueror; is &kde;'s open source, standards compliant webbrowser. +It's home page is +<ulink +url="http://www.konqueror.org">http://www.konqueror.org</ulink> where a +&konqueror; specific <acronym>FAQ</acronym> can be found.</para> + +<qandaset> + +<qandaentry> +<question><para>Where does the name &konqueror; come from?</para></question> +<answer><para>It's a word play on the other browsers' names. After the Navigator and the Explorer comes the Conqueror; it's spelled with a K to show that it's part of &kde;. The name change also moves away from <quote>kfm</quote> (the &kde; file manager, &konqueror;'s predecessor) which represented only file management.</para></answer> +</qandaentry> + +<qandaentry> +<question><para>Can I run &konqueror; without running &kde;?</para></question> +<answer><para>Yes. Just install &Qt;, kdelibs and kdebase, and from your favorite window manager just launch &konqueror;. It should work just fine, but if it doesn't (&kde; developers don't test that case often), report it to http://bugs.kde.org and try running "kdeinit" before running &konqueror;, it usually helps. +This is of course the same for any other &kde; application. </para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>Why doesn't &konqueror; show the contents of an image's <sgmltag class="attribute">ALT</sgmltag> attribute in a tooltip?</para></question> +<answer><para> +There is no standard that states the <sgmltag class="attribute">ALT</sgmltag> attribute should appear as a tooltip. The specification calls for <sgmltag class="attribute">ALT</sgmltag> to be displayed in place of the image, as in text-mode only browsers such at lynx or w3m. Abusing the <sgmltag class="attribute">ALT</sgmltag> attribute is bad for accessibility. Tooltips are supposed to come from the <sgmltag class="attribute">TITLE</sgmltag> attribute and this is implemented in &konqueror; +</para></answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I use &konqueror; as a web browser with a proxy?</para> +</question> +<answer> +<para>&konqueror; can be used with &HTTP; and &FTP; proxies. To set +up the proxy server in &konqueror;, just select +<menuchoice><guimenu>Settings</guimenu><guisubmenu>Configure +&konqueror;...</guisubmenu></menuchoice> from the &konqueror; menu and +go to the <guilabel>Proxy</guilabel> tab.</para> +</answer> +</qandaentry> + +<qandaentry> +<question id="nsbookmark"> +<para>How do I import bookmarks from another browser into &konqueror; ?</para> +</question> +<answer> +<para>To import bookmarks from another browser into &konqueror; select +<guimenu>Bookmarks</guimenu><guimenuitem>Edit Bookmarks</guimenuitem> +and then in the <application>Bookmark Editor</application> select +<guimenu>File</guimenu><guimenuitem>Import</guimenuitem>. Then select +the browser you would like to import bookmarks from. In the Open dialog, +navigate to the location of the folder or file your bookmarks are +contained in and click <guilabel>Open</guilabel> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>How can I make &konqueror; only show certain bookmarks in the bookmarks toolbar?</para></question> +<answer><para>In &konqueror; go to <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &konqueror;...</guimenuitem></menuchoice>. Then select <guilabel>Web Behaviour</guilabel> from the icon list. Under the <guilabel>Bookmarks</guilabel> heading, place a check in the box next to <guilabel>Show only marked bookmarks in bookmark toolbar</guilabel>. Now in the <application>Bookmark Editor</application> an option to <guilabel>Show in Toolbar</guilabel> appears on clicking with the &RMB; on any bookmark entry or in the <guimenu>Edit</guimenu> menu when the entry is highlighted. Folders can also be shown in the bookmarks toolbar in much the same way.</para></answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I fool a site into believing &konqueror; is &Netscape; or +some other browser?</para> +</question> +<answer> +<para>In &konqueror;, select +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Konqueror...</guimenuitem></menuchoice> and in the configuration +dialog, select <guilabel>Browser Identification</guilabel>. Default +and site-specific browser identifications can be set from here.</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>&konqueror; is taking a really long time to load webpages, what +could cause this?</para></question> +<answer> +<para>Quite often &konqueror; loading webpages slowly is caused by +<acronym>DNS</acronym> servers with broken <acronym>IPV6</acronym> +support. Adding the following to <filename>/etc/profile</filename> or any +other script that is sourced on login should solve this problem: +<screen> +export KDE_NO_IPV6=true +</screen> +for bourne compatible shells, and for C-style shells: +<screen> +setenv KDE_NO_IPV6 true +</screen> +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I configure &konqueror; to run &Java; applets?</para> +</question> +<answer> +<para>Choose +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&konqueror;...</guimenuitem></menuchoice> from &konqueror;'s menubar +and then select <guilabel>Java & Javascript</guilabel>. Set the +<guilabel>Path to Java executable</guilabel> correctly. If it doesn't +work, please check the <ulink +url="http://www.konqueror.org/javahowto/">Konqueror + Java +HOWTO</ulink>.</para> +</answer> +</qandaentry> + + +<qandaentry> +<question> +<para>How do I block unrequested popup windows in &konqueror;?</para> +</question> +<answer> +<para>&konqueror; has a new 'smart' policy for JavaScript popups. From the +&konqueror; main window, select <menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &konqueror;...</guimenuitem></menuchoice> and then +<guilabel>Java & JavaScript</guilabel>. On the +<guilabel>JavaScript</guilabel> tab, under <guilabel>Global JavaScript +Policies</guilabel> set the radio button beside <guilabel>Open new +windows:</guilabel> to <guilabel>Smart</guilabel>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why doesn't my banking site work with &konqueror;? It pops up a new +window with the login screen in other browsers, but not in +&konqueror;.</para> +</question> +<answer> +<para> +Make sure you have Javascript enabled, and the default JavaScript web popups +policy set to <guilabel>Ask</guilabel> or <guilabel>Allow</guilabel>. The +<guilabel>Smart</guilabel> policy is not always sufficient for some banks. +Many banks also require &Java; support. You can find more help on enabling +this at <ulink +url="http://www.konqueror.org/">http://www.konqueror.org/</ulink>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can &konqueror; use user-specified stylesheets, like those in the +Firefox adblock extention?</para> +</question> +<answer> +<para>Yes, you can set &konqueror; to use any kind of valid +<acronym>css</acronym> stylesheet to filter webcontent or improve accessibility. +From the &konqueror; main window simply click +<menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure &konqueror;...</guimenuitem></menuchoice> and select +<guilabel>Stylesheets</guilabel>. Set the radio button to +<guilabel>Use user-defined stylesheet</guilabel> and browse to where the +stylesheet you want to use is located. Alternatively, you can select +<guilabel>Use accessibility stylesheet defined in "Customize" +tab</guilabel> and then set your own options.</para> +<para> +An example of <acronym>css</acronym> rules that implement ad blocking can be +found at: +<ulink url="http://www.mozilla.org/support/firefox/adblock"> +http://www.mozilla.org/support/firefox/adblock</ulink>. +</para> +</answer> +</qandaentry> +<qandaentry> +<question><para> +Why does &konqueror; display a plain grey square when I try to view flash animations, even though the flash plugin is installed? +</para></question> +<answer><para> +Under the latest versions of X.org, having the composite extension loaded can cause problems with the flash plugin. Try disabling the composite extension and see if normal flash operation is restored. +</para></answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why can't &konqueror; render &GIF; images?</para> +</question> +<answer> +<para>It is because you did not enable &GIF; support in &Qt;. Please see +<xref linkend="gif"/> for more details.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>When I try to open a web page with &konqueror;, I get the +message: <quote>There appears to be a configuration error. You have +associated Konqueror with text/html, but it cannot handle this file +type.</quote></para> +</question> +<answer> +<para>You need to make sure that the embedding settings for the text/html +<acronym>MIME</acronym> type are correct: +<orderedlist> +<listitem><para>In &konqueror;, go to +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&konqueror;...</guimenuitem></menuchoice> and then to the <guilabel>File +Associations</guilabel> page.</para></listitem> <listitem><para>Open +text->html in the tree view.</para></listitem> <listitem><para>Click on the +<guilabel>Embedding</guilabel> tab. Make sure that <guilabel>Left Click +Action</guilabel> is set to <guilabel>Show file in embedded +viewer</guilabel>, and that <guilabel>KHTML (khtml)</guilabel> is at the top +of <guilabel>Services Preference Order</guilabel>.</para></listitem> +</orderedlist> +</para> +</answer> +</qandaentry> + +</qandaset> +</chapter> + + diff --git a/doc/faq/winmng.docbook b/doc/faq/winmng.docbook new file mode 100644 index 000000000..f32384754 --- /dev/null +++ b/doc/faq/winmng.docbook @@ -0,0 +1,134 @@ +<!-- +<?xml version="1.0" ?> +<!DOCTYPE chapter PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd"> +--> + + + +<chapter id="windowmanager"> +<title>The window manager</title> + +<para>The default window manager provided by &kde; is the K Window +Manager (&kwin;). Please read <quote>The +K Window Manager Handbook</quote> (which should be accessible from the +<application>&kde; Help Center</application>) for usage information.</para> + +<qandaset> +<qandaentry> +<question> +<para>Are there keyboard shortcuts for &kwin; operations?</para> +</question> +<answer> +<para>Yes. Please refer to "The K Window Manager Handbook" for the +list of shortcuts available.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Can I define my own set of keyboard shortcuts?</para> +</question> +<answer> +<para>Yes. Launch the +<application>&kde; Control Center</application> and select +<menuchoice><guimenu>Regional & Accessibility</guimenu><guimenuitem>Keyboard Shortcuts</guimenuitem></menuchoice> to +configure window manager bindings like maximizing windows, &etc;. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>When I "iconify" a window, it disappears. Where does it +go?</para> +</question> +<answer> +<para>With many &X-Window; &GUI;s, the minimize button (a little dot) will +erase the window that the program is running in and create, instead, +an icon on the desktop. &kde; does not do this. Instead, when a +window is iconified it is simply hidden (but the program is still +running).</para> +<para>There are a few ways to access <quote>disappeared</quote> windows:</para> +<itemizedlist> +<listitem> +<para>If you are running the taskbar part of &kicker;, +you can choose to have a list of tasks displayed on your desktop. +Iconified tasks will have their names displayed in gray.</para> +</listitem> +<listitem> +<para>If you click the &MMB; on the root window (&ie;, +the background of the desktop), &kwin; will give you a list +of all available tasks.</para> +</listitem> +</itemizedlist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I maximize windows only vertically or horizontally?</para> +</question> +<answer> +<para>Provided your window is not already maximized, clicking on the +maximize button with the &LMB;/&MMB;/&RMB; will +maximize fully/vertically/horizontally respectively.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>What is <quote>shading</quote> a window?</para> +</question> +<answer> +<para>By <quote>shading</quote> a window we mean <quote>rolling up</quote> the window leaving just +the title bar visible. You can do this by double clicking on the +window title bar.</para> +</answer> +</qandaentry> + +<!-- This is kinda covered in desktop.docbook, but the question here --> +<!-- is different, even if the answer is nearly the same --> +<qandaentry> +<question> +<para>How can I start an application with special window options, like +maximized/minimized/to stay on top?</para> +</question> +<answer> +<para>Use the <command>kstart</command> command. As an example, to +open &kcalc; with the <quote>Stay on Top</quote> option, use: +<screen><prompt>%</prompt> <userinput><command>kstart</command> <option>--ontop</option> <option>kcalc</option></userinput></screen> +</para> +<para>For maximized windows, use the <option>--maximize</option> +option, for minimized windows, use <option>--iconify</option>. You can +see a full list of <command>kstart</command> options with +<userinput><command>kstart</command> +<option>--help-all</option></userinput>.</para> + +<warning><para>If you're using <command>kstart</command> to start +applications at &kde; startup, you should use the +<option>--window</option> option. See the &kde; User Guide, section +<quote>Advanced Window Management</quote> for more information about +this feature.</para> +</warning> + +</answer> +</qandaentry> + +<!-- Not sure this is still applicable +<qandaentry> +<question> +<para>Is it possible to have FVWM2-like shadow frameworks for the +placement of windows?</para> +</question> +<answer> +<para>Yes. Run <application>&kde; Control Center</application> and select <guimenu>Look and Feel</guimenu> +followed by <guisubmenu>Window Behavior</guisubmenu> and finally +<guimenuitem>Advanced</guimenuitem>. There is a dialog option that +allows you to set the placement policy you want.</para> +</answer> +</qandaentry> +--> +</qandaset> +</chapter> + diff --git a/doc/glossary/Makefile.am b/doc/glossary/Makefile.am new file mode 100644 index 000000000..e79a46842 --- /dev/null +++ b/doc/glossary/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = khelpcenter/glossary diff --git a/doc/glossary/checkxrefs b/doc/glossary/checkxrefs new file mode 100755 index 000000000..6da64c184 --- /dev/null +++ b/doc/glossary/checkxrefs @@ -0,0 +1,10 @@ +#!/bin/sh +DEFINED_ENTRIES=`sed -ne "s^.*<glossentry id=\"\(.*\)\">.*^\1^p" *.docbook` +REFERENCED_ENTRIES=`sed -ne "s^.*<glossseealso otherterm=\"\(.*\)\">.*^\1^p" *.docbook | unique` + +# Check for entries which are referenced but not defined. +for ENTRY in $REFERENCED_ENTRIES; do + if ! echo $DEFINED_ENTRIES | grep $ENTRY - > /dev/null 2>&1; then + echo "'$ENTRY' referenced but not defined!" + fi +done diff --git a/doc/glossary/index.docbook b/doc/glossary/index.docbook new file mode 100644 index 000000000..4aba44c53 --- /dev/null +++ b/doc/glossary/index.docbook @@ -0,0 +1,296 @@ +<?xml version="1.0" ?> +<!DOCTYPE glossary PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE"> +<!ENTITY glossary-kdeprinting SYSTEM "kdeprintingglossary.docbook"> + + +]> + + +<glossary id="glossary"> + +&glossary-kdeprinting; + + <glossdiv id="glossdiv-technologies"> + <title>Technologies</title> + <glossentry id="gloss-ioslave"> + <glossterm><acronym>IO</acronym> Slave</glossterm> + <glossdef><para><acronym>IO</acronym> Slaves enable &kde; applications to + access remote resources as easily as local resources (making them + <quote>network transparent</quote>). Remote resources (⪚ files) might + be stored on <acronym>SMB</acronym> shares or similar.</para> + <glossseealso otherterm="gloss-smb"><acronym>SMB</acronym></glossseealso> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-kio"> + <glossterm><acronym>KIO</acronym></glossterm> + <glossdef><para>The &kde; Input/Output system which makes use of so-called + <quote><acronym>IO</acronym> Slaves</quote>.</para> + <glossseealso otherterm="gloss-ioslave"><acronym>IO</acronym> +Slave</glossseealso> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-kparts"> + <glossterm>KParts</glossterm> + <glossdef><para>KParts is an embedding technology which allows &kde; + applications to embed other &kde; applications. For example, the text + view used by &konqueror; is a KPart.</para> + <glossseealso otherterm="gloss-konqueror">&konqueror;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-ksycoca"> + <glossterm><acronym>KSycoca</acronym></glossterm> + <glossdef><para><acronym>KSycoca</acronym> (&kde; <emphasis>Sy</emphasis>stem + <emphasis>Co</emphasis>nfiguration <emphasis>Ca</emphasis>che) is a + configuration cache which, for example, guarantees fast access to the menu + entries.</para> + <glossseealso +otherterm="gloss-kbuildsycoca"><application>KBuildSycoca</application></glossseealso> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="glossdiv-xfree86"> + <title>XFree86</title> + <glossentry id="gloss-antialiasing"> + <glossterm>Antialiasing</glossterm> + <glossdef><para>If mentioned in context with &kde;, antialiasing often means + the smoothing of the fonts visible on the screen. &Qt; version 2.3.0 + or higher used together with XFree86 4.x makes this possible under &kde; + as well.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + <glossseealso otherterm="gloss-qt">&Qt;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-xserver"> + <glossterm>&X-Server;</glossterm> + <glossdef><para>The &X-Server; represents a basic layer upon which the + various &GUI;s like &kde; are built. It manages the + basic mouse and keyboard input (from the local host as well as from + remote hosts) and provides elementary graphic routines to draw + rectangles and other primitives.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + <glossseealso otherterm="gloss-gui">&GUI;</glossseealso> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="glossdiv-applications"> + <title>Applications</title> + <glossentry id="gloss-kbuildsycoca"> + <glossterm><application>KBuildSycoca</application></glossterm> + <glossdef><para><application>KBuildSycoca</application> is a command line +program and regenerates the + so-called <acronym>KSycoca</acronym>. This is useful, for example, if some +or all modules in + &kcontrol; are missing.</para> + <glossseealso +otherterm="gloss-ksycoca"><acronym>KSycoca</acronym></glossseealso> + <glossseealso otherterm="gloss-kcontrol">&kcontrol;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-kcontrol"> + <glossterm>&kcontrol;</glossterm> + <glossdef><para>This is the project and filename of the &kde; control + center. &kcontrol; allows you to customize virtually + every configuration option of &kde;.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-kicker"> + <glossterm>&kicker;</glossterm> + <glossdef><para>&kicker; is the nickname as well as project name of the + &kde; panel.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + <glossseealso otherterm="gloss-panel">Panel</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-konqueror"> + <glossterm>&konqueror;</glossterm> + <glossdef><para>&konqueror; is a filemanager, web browser, picture viewer + and more, and a core part of the &kde; project. You can + find more information about &konqueror; at <ulink + url="http://www.konqueror.org">www.konqueror.org</ulink>.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-ksirc"> + <glossterm>&ksirc;</glossterm> + <glossdef><para>&ksirc; is the default <acronym>IRC</acronym> client, + which is shipped with &kde;. You can use &ksirc; to chat with anyone on + an <acronym>IRC</acronym> network.</para> + <glossseealso otherterm="gloss-irc"><acronym>IRC</acronym></glossseealso> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="glossdiv-desktop-terminology"> + <title>Desktop Terminology</title> + <glossentry id="gloss-draganddrop"> + <glossterm>Drag and Drop</glossterm> + <glossdef><para>This concept tries to replace many actions like copying + files from one place to another by a certain mouse movement, ⪚ + clicking on an icon in a &konqueror; window, moving the mouse to another + window while keeping the mouse button pressed, and releasing the mouse + button (<quote>dropping</quote> the object) copies files.</para> + <glossseealso otherterm="gloss-konqueror">&konqueror;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-gui"> + <glossterm>&GUI;</glossterm> + <glossdef><para>Abbreviation for <emphasis>G</emphasis>raphical + <emphasis>U</emphasis>ser <emphasis>I</emphasis>nterface. Every desktop + environment (like &kde;) is a &GUI;. Most + &GUI;s feature mouse support and/or windows to manage + the programs.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-kde"> + <glossterm>&kde;</glossterm> + <glossdef><para>Abbreviation for <quote>K Desktop Environment</quote>, a + leading &GUI; for &UNIX;-based systems. You can find more + detailled information at <ulink + url="http://www.kde.org">www.kde.org</ulink>.</para> + <glossseealso otherterm="gloss-gui">&GUI;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-gnome"> + <glossterm><acronym>GNOME</acronym></glossterm> + <glossdef> + <para><emphasis>G</emphasis>NU <emphasis>N</emphasis>etwork <emphasis>O</emphasis>bject + <emphasis>M</emphasis>odel <emphasis>E</emphasis>nvironment, one of the + leading &UNIX; &GUI;s.</para> + <glossseealso otherterm="gloss-gui">&GUI;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-panel"> + <glossterm>Panel</glossterm> + <glossdef><para>Refers to the panel (also known as + <quote>&kicker;</quote>) which often resides at the bottom of the + screen.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + <glossseealso otherterm="gloss-kicker">&kicker;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-ripping"> + <glossterm>ripping</glossterm> + <glossdef><para>The process of reading audio data from a &cdrom; and + storing it on the hard disk.</para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="kde-development"> + <title>&kde; Development</title> + <glossentry id="gloss-qt"> + <glossterm>&Qt;</glossterm> + <glossdef><para>The &GUI; of &kde; is built on top of + the &Qt; toolkit, which provides many graphical elements (so-called + <quote>Widgets</quote>) which are used to construct the desktop. You + can find more information about &Qt; at <ulink + url="http://www.trolltech.com">www.trolltech.com</ulink>.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + <glossseealso otherterm="gloss-gui">&GUI;</glossseealso> + <glossseealso otherterm="gloss-widget">Widget</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-i18n"> + <glossterm>i18n</glossterm> + <glossdef><para>Abbreviation for <quote>internationalization</quote>. &kde; + supports many different languages, and several i18n techniques make it + easy to translate the &GUI; as well as the accompanying + documents of &kde; into all these languages. More information about the + i18n process is available at <ulink + url="http://i18n.kde.org">i18n.kde.org</ulink>.</para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + <glossseealso otherterm="gloss-gui">&GUI;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-l10n"> + <glossterm>l10n</glossterm> + <glossdef><para>Abbreviation for <quote>localization</quote>, the process + of adapting a program to the local environment. This includes ⪚ the + currency used for monetary values or the time format.</para> + <glossseealso otherterm="gloss-i18n">i18n</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-widget"> + <glossterm>Widget</glossterm> + <glossdef><para>Graphical elements like scrollbars, buttons or input + fields which are used by &kde; to construct the &GUI;. + </para> + <glossseealso otherterm="gloss-kde">&kde;</glossseealso> + <glossseealso otherterm="gloss-gui">&GUI;</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-cvs"> + <glossterm><acronym>CVS</acronym></glossterm> + <glossdef> + <para><emphasis>C</emphasis>oncurrent <emphasis>V</emphasis>ersion +<emphasis>S</emphasis>ystem. + The <acronym>CVS</acronym> is a very elegant way of managing file +versions that allow more than one developer + to easily work on the same project. You can find a description of how to +get the latest (developer) version of the + &kde; sources via anonymous <acronym>CVS</acronym> on + <ulink +url="http://www.kde.org/anoncvs.html">http://www.kde.org/anoncvs.html</ulink>. + More about <acronym>CVS</acronym> is available at <ulink +url="http://www.cvshome.org">www.cvshome.org</ulink>. + + </para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="glossdiv-misc"> + <title>Miscellaneous</title> + <glossentry id="gloss-rfc"> + <glossterm><acronym>RFC</acronym></glossterm> + <glossdef><para><emphasis>R</emphasis>equest <emphasis>F</emphasis>or + <emphasis>C</emphasis>omment. A common way to publish new protocol + ideas or procedures for evaluation of the Internet community. Though + <acronym>RFC</acronym>s are not mandatory, many applications try to + adhere to them, once they have been approved by the community. More + information about <acronym>RFC</acronym>s can be found at the + <ulink url="http://www.rfc-editor.org">RFC Homepage</ulink>.</para> + </glossdef> + </glossentry> + </glossdiv> + + <glossdiv id="glossdiv-protocols"> + <title>Various protocols</title> + <glossentry id="gloss-smb"> + <glossterm><acronym>SMB</acronym></glossterm> + <glossdef><para><emphasis>S</emphasis>erver <emphasis>M</emphasis>essage + <emphasis>B</emphasis>lock. A network protocol used in &Microsoft; &Windows; + networks to access the filesystems of other computers.</para> + <glossseealso otherterm="gloss-ioslave"><acronym>IO</acronym> +Slave</glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-irc"> + <glossterm><acronym>IRC</acronym></glossterm> + <glossdef><para><emphasis>I</emphasis>nternet <emphasis>R</emphasis>elay + <emphasis>C</emphasis>hat. A protocol defined in <acronym>RFC</acronym> + 1459, which handles the specification to enable real time text chat.</para> + <glossseealso otherterm="gloss-rfc"><acronym>RFC</acronym></glossseealso> + </glossdef> + </glossentry> + <glossentry id="gloss-host"> + <glossterm>host</glossterm> + <glossdef><para>This can either be a name from your + <filename>/etc/hosts</filename> file + (<systemitem class="systemname">mycomputer</systemitem>), + an Internet name (<systemitem +class="systemname">www.kde.org</systemitem>) or an IP-Address + (<systemitem>192.168.0.10</systemitem>). + </para> + </glossdef> + </glossentry> + </glossdiv> +</glossary> diff --git a/doc/glossary/kdeprintingglossary.docbook b/doc/glossary/kdeprintingglossary.docbook new file mode 100644 index 000000000..7a9311c73 --- /dev/null +++ b/doc/glossary/kdeprintingglossary.docbook @@ -0,0 +1,1387 @@ + +<!-- +<?xml version="1.0" ?> +<!DOCTYPE glossary PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"customization/dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE"> +<!ENTITY glossary-kdeprinting SYSTEM "kdeprintingglossary.docbook"> + +]> +<glossary id="glossary"> +--> + <glossdiv id="glossdiv-printing"> + <title>Printing</title> + + + <glossentry id="gloss-acl"> + <glossterm><acronym>ACLs</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>A</emphasis>ccess + <emphasis>C</emphasis>ontrol <emphasis>L</emphasis>ists; + ACLs are used to check for the access by a given + (authenticated) user. A first rough support for ACLs + for printing is available from &CUPS;; this will be refined + in future versions. </para> + <glossseealso otherterm="gloss-authentication">Authentication</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-appsocketprotocol"> + <glossterm>AppSocket Protocol</glossterm> + <glossdef><para>AppSocket is a protocol for the transfer of + print data, also frequently called "Direct TCP/IP Printing". + &Hewlett-Packard; have taken AppSocket, added a few minor + extensions around it and been very successful in renaming + and marketing it under the brand "&HP; JetDirect"...</para> + <glossseealso otherterm="gloss-hpjetdirectprotocol">&HP; JetDirect Protocol</glossseealso> + <glossseealso otherterm="gloss-directtcpipprinting">Direct TCP/IP Printing</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-apsfilter"> + <glossterm>APSfilter</glossterm> + <glossdef><para>APSfilter is used mainly in the context of "classical" + &UNIX; printing (BSD-style LPD). It is a sophisticated shell script, + disguised as an "all-in-one" filtering program. In reality, + APSfilter calls "real filters" to do the jobs needed. It sends + printjobs automatically through these other filters, based on an + initial file-type analysis of the printfile. + It is written and maintained by Andreas Klemm. +<!-- + </para> + <para> +--> + It is + similar to Magicfilter and mostly uses Ghostscript for file conversions. + Some Linux Distributions (like &SuSE;) use APSfilter, others + Magicfilter (like &RedHat;), some have both for preference selection + (like *BSD). +<!-- + </para> + <para> +--> + &CUPS; has <emphasis>no</emphasis> need for APSfilter, + as it runs its own file type recognition (based on &MIME; types) + and applies its own filtering logic.</para> + <glossseealso otherterm="gloss-ghostscript">Ghostscript</glossseealso> + <glossseealso otherterm="gloss-magicfilter">Magicfilter</glossseealso> + <glossseealso otherterm="gloss-mimetypes">&MIME;-Types</glossseealso> + <glossseealso otherterm="gloss-printcap">printcap</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-authentication"> + <glossterm>Authentication</glossterm> + <glossdef><para>Proving the identity of a certain person (maybe via username/password + or by means of a certificate) is often called authentication. Once you are + authenticated, you may or may not get access to a requested ressource, + possibly based on ACLs.</para> + <glossseealso otherterm="gloss-acl">ACLs</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-bidirectionalcommunication"> + <glossterm>Bi-directional communication</glossterm> + <glossdef><para>In the context of printing, a server or a host may receive additional + information sent back from the printer (status messages &etc;), either + upon a query or unrequested. AppSocket ( = &HP; JetDirect), &CUPS; and IPP + support bi-directional communication, LPR/LPD and BSD-style printing + do not...</para> + <glossseealso otherterm="gloss-appsocketprotocol">AppSocket Protocol</glossseealso> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-directtcpipprinting">Direct TCP/IP Printing</glossseealso> + <glossseealso otherterm="gloss-hpjetdirectprotocol">&HP; JetDirect</glossseealso> + <glossseealso otherterm="gloss-ipp">IPP</glossseealso> + <glossseealso otherterm="gloss-lprlpd">LPR/LPD</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-bsdstyleprinting"> + <glossterm>BSD-style Printing</glossterm> + <glossdef><para>Generic term for different variants of the traditional &UNIX; + printing method. Its first version appeared in the early 70s on + BSD &UNIX; and was formally described in <ulink url="http://www.rfc.net/rfc1179.html">RFC 1179</ulink> only as late + as 1990. +<!-- + </para> + <para> +--> + At the time when BSD "remote" printing was first designed, printers + were serially or otherwise directly connected devices to a host + (with the Internet hardly consisting of more than 100 nodes!); printers + used hole-punched, continuous paper, fed through by a tractor + mechanism, with simple rows of ASCII text mechanically hammered on to + the medium, drawn from a cardboard box beneath the table. It came out + like a zig-zag folded paper "snake". Remote printing consisted of a + neighboring host in the next room sending a file + asking for printout. +<!-- + </para> + <para> +--> + How technology has changed! Printers generally use cut-sheet media, they have + built-in intelligence to compute the raster images of pages after pages + that are sent to them using one of the powerful page description + languages (PDL). Many are network nodes in their own right, + with CPU, RAM, a hard disk and their own Operation System, and + are hooked to a net with potentially millions of users... +<!-- + </para> + <para> +--> + It is a vast proof of the flexible &UNIX; concept for doing things, + that it made "Line Printing" reliably work even under these modern + conditions. But time has finally come now to go for something new + -- the IPP. + + It is strong proof of the flexibility of &UNIX;; that "Line Printing" works + reliably, even under these modern conditions. But time has finally come now + to go for something new -- the IPP. + + </para> + <glossseealso otherterm="gloss-ipp">IPP</glossseealso> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-lprlpd">LPR/LPD printing</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-cups"> + <glossterm>&CUPS;</glossterm> + <glossdef><para>Abbreviation for <emphasis>C</emphasis>ommon + <emphasis>U</emphasis>NIX <emphasis>P</emphasis>rinting + <emphasis>S</emphasis>ystem; &CUPS; is the most modern &UNIX; and Linux + printing system, also providing cross-platform print services + to &Microsoft; &Windows; and Apple &MacOS; clients. Based on IPP, it does + away with all the pitfalls of old-style BSD printing, + providing authentication, encryption and ACLs, plus many more + features. At the same time it is backward-compatible enough + to serve all legacy clients that are not yet up to IPP, via + LPR/LPD (BSD-style). +<!-- + </para> + <para> +--> + &CUPS; is able to control any &PostScript; printer by + utilizing the vendor-supplied PPD (PostScript Printer + Description file), targeted originally for &Microsoft; Windows NT + printing only. &kde; Printing is most powerful if based on + &CUPS;.</para> + <glossseealso otherterm="gloss-acl">ACLs</glossseealso> + <glossseealso otherterm="gloss-authentication">Authentication</glossseealso> + <glossseealso otherterm="gloss-bsdstyleprinting">BSD-style printing</glossseealso> + <glossseealso otherterm="gloss-ipp">IPP</glossseealso> + <glossseealso otherterm="gloss-kdeprint">KDEPrint</glossseealso> + <glossseealso otherterm="gloss-lprlpd">LPR/LPD</glossseealso> + <glossseealso otherterm="gloss-ppd">PPD</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-cupsfaq"> + <glossterm><acronym>&CUPS;-FAQ</acronym></glossterm> + <glossdef><para>Currently only available in German (translation is on the way), + the <ulink url="http://www.danka.de/printpro/faq.html">&CUPS;-FAQ</ulink> + is a valuable resource to answer many questions that anyone new to + &CUPS; printing might have at first. + </para> + <glossseealso otherterm="gloss-kdeprinthandbook">KDEPrint Handbook</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-cups-o-matic"> + <glossterm>&CUPS;-O-Matic</glossterm> + <glossdef><para>&CUPS;-O-Matic was the first "Third Party" plugin for + the &CUPS; printing software. It is available on the <ulink + url="http://www.linuxprinting.org/cups-doc.html">Linuxprinting.org + website</ulink> to provide an online PPD-generating service. +<!-- + </para> + <para> +--> + + Together with the companion <application>cupsomatic</application> Perl-Script, + that needs to be installed as an additional &CUPS; backend, + it redirects output from the native <application>pstops</application> filter into + a chain of suitable Ghostscript filters. Upon completion, it + passes the resulting data back to a &CUPS; "backend" for sending + to the printer. +<!-- + </para> + <para> +--> + In this way, &CUPS;-O-Matic enables support for any printer known to + have worked previously in a "classical" Ghostscript environment. + If no native &CUPS; support for that printer is in sight... &CUPS;-O-Matic + is now replaced by the more capable PPD-O-Matic.</para> + <glossseealso otherterm="gloss-cupsomatic">cupsomatic</glossseealso> + <glossseealso otherterm="gloss-PPD-O-Matic">PPD-O-Matic</glossseealso> + <glossseealso otherterm="gloss-foomatic">Foomatic</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-cupsomatic"> + <glossterm>cupsomatic</glossterm> + <glossdef><para>The Perl script <application>cupsomatic</application> (plus a working Perl installation + on your system) is needed to make any &CUPS;-O-Matic (or PPD-O-Matic) + generated PPD work with &CUPS;. It was written by Grant Taylor, author of + the Linux Printing HOWTO and Maintainer of the <ulink + url="http://www.linuxprinting.org/printer_list.cgi">printer + database</ulink> at the Linuxprinting.org website.</para> + <glossseealso otherterm="gloss-cups-o-matic">&CUPS;-O-Matic</glossseealso> + <glossseealso otherterm="gloss-foomatic">Foomatic</glossseealso> + <glossseealso otherterm="gloss-cupsomatic">cupsomatic</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-daemon"> + <glossterm><acronym>Daemon</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>D</emphasis>isk + <emphasis>a</emphasis>nd <emphasis>e</emphasis>xecution + <emphasis>mon</emphasis>itor; <acronym>Daemons</acronym> are present + on all &UNIX; systems to perform tasks independent of user + intervention. Readers more familiar with &Microsoft; &Windows; might + want to compare daemons and the tasks they are responsible + with "services". +<!-- + </para> + <para> +--> + One example of a daemon present on most + legacy &UNIX; systems is the LPD (Line Printer Daemon); &CUPS; is + widely seen as the successor to LPD in the &UNIX; world and + it also operates through a daemon. </para> + <glossseealso otherterm="gloss-spooling">SPOOLing</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-databaselinuxprinting"> + <glossterm>Database, Linuxprinting.org</glossterm> + <glossdef><para>Already years ago, when Linux printing was still really difficult + (only command line printing was known to most Linux users, no device + specific print options were available for doing the jobs), Grant Taylor, + author of the "Linux Printing HOWTO", collected most of the available + information about printers, drivers and filters in his database. +<!-- + </para> + <para> +--> + With the emerging + &CUPS; concept, extending the use of PPDs even to non-PostScript printers, + he realized the potential of this database: if one puts the different + datablobs (with content that could be described along the lines + "Which device prints with which Ghostscript or other + filter?", "How well?", and "What command line switches are available?") into + PPD-compatible files, he could have all the power of &CUPS; on top of + the traditional printer "drivers". +<!-- + </para> + <para> +--> + This has now developed into a broader + concept, known as "Foomatic". Foomatic extends the capabilities + of spoolers other than &CUPS; (LPR/LPD, LPRng, PDQ, PPR) to a certain + degree ("stealing" some concepts from &CUPS;). The Linuxprinting + Database is not a Linux-only stop -- people running other &UNIX; + based OSes (like *BSD or &MacOS; X) will also find valuable information + and software there. + </para> + <glossseealso otherterm="gloss-foomatic">Foomatic</glossseealso> + <glossseealso otherterm="gloss-linuxprintingdatabase">Linuxprinting database</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-directtcpipprinting"> + <glossterm>Direct TCP/IP Printing</glossterm> + <glossdef><para>This is a method that often uses TCP/IP port 9100 to connect + to the printer. It works with many modern network printers and has + a few advantages over LPR/LPD, as it is faster and provides some + "backchannel feedback data" from the printer to the host sending + the job.</para> + <glossseealso otherterm="gloss-appsocketprotocol">AppSocket Protocol</glossseealso> + <glossseealso otherterm="gloss-hpjetdirectprotocol">&HP; JetDirect Protocol</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-drivers"> + <glossterm>Drivers, Printer Drivers</glossterm> + <glossdef><para>The term "printer drivers", used in the same sense + as on the &Microsoft; &Windows; platform, is not entirely applicable + to a Linux or &UNIX; platform. A "driver" functionality + is supplied on &UNIX; by different modular components working + together. At the core of the printer drivers are "filters". Filters convert + print files from a given input format to another format that is acceptable + to the target printer. In many cases filters may be connected to a whole + filter "chain", where only the result of the last conversion is sent to the + printer. The actual transfer of the print data to the device is performed by + a "backend". + </para> + <glossseealso otherterm="gloss-filter">Filter</glossseealso> + <glossseealso otherterm="gloss-ppd">PPDs</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-easysoftwareproducts"> + <glossterm>Easy Software Products</glossterm> + <glossdef><para>Mike Sweet's company, which has contributed a few substantial + software products towards the Free Software community; amongst + them the initial version of <ulink + url="http://gimp-print.sf.net/">Gimp-Print,</ulink> the <ulink + url="http://www.easysw.com/epm/">EPM software packaging</ulink> tool + and <ulink url="http://www.easysw.com/htmldoc/">HTMLDOC</ulink> + (used by the "Linux Documentation Project" to build the PDF versions + of the HOWTOs) -- but most importantly: <ulink + url="http://www.cups.org/">&CUPS;</ulink> (the 'Common &UNIX; Printing + System'). +<!-- + </para> + <para> +--> + ESP finance themselves by selling a commercial version + of &CUPS;, called <ulink url="http://www.easysw.com/">ESP PrintPro,</ulink> + that includes some professional enhancements. + </para> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-espprintpro">ESP PrintPro</glossseealso> + <glossseealso otherterm="gloss-esp">ESP</glossseealso> + <glossseealso otherterm="gloss-gimpprint">Gimp-Print</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-encryption"> + <glossterm>Encryption</glossterm> + <glossdef><para>Encryption of confidential data is an all-important issue if + you transfer it over the Internet or even within intranets. +<!-- + </para> + <para> +--> + Printing + via traditional protocols is not encrypted at all -- it is very easy + to tap and eavesdrop ⪚ into &PostScript; or PCL data transfered + over the wire. +<!-- + </para> + <para> +--> + Therefore, in the design of IPP, provision was made for the easy + plugin of encryption mechanisms (which can be provided by the same + means as the encryption standards for HTTP traffic: SSL and TLS).</para> + <glossseealso otherterm="gloss-authentication">Authentication</glossseealso> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-ipp">IPP</glossseealso> + <glossseealso otherterm="gloss-ssl">SSL</glossseealso> + <glossseealso otherterm="gloss-tls">TLS</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-epson"> + <glossterm><acronym>Epson</acronym></glossterm> + <glossdef><para>Epson inkjets are among the best supported models by Free software + drivers, as the company was not necessarily as secretive about their + devices and handed technical specification documents to developers. + The excellent print quality achieved by Gimp-Print on the Stylus + series of printers can be attributed to this openness. +<!-- + </para> + <para> +--> + They have also + contracted Easy Software Products to maintain an enhanced version + of Ghostscript ("ESP GhostScript") for improved support of their + printer portfolio. + </para> + <glossseealso otherterm="gloss-ghostscript">ESP Ghostscript</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-escapesequence"> + <glossterm>Escape Sequences</glossterm> + <glossdef><para>The first ever printers printed ASCII data only. To + initiate a new line, or eject a page, they included special + command sequences, often carrying a leading [ESC]-character. + &HP; evolved this concept through its series of PCL language + editions until today, having now developed a full-blown + Page Description Language (PDL) from these humble beginnings. + </para> + <glossseealso otherterm="gloss-pcl">PCL</glossseealso> + <glossseealso otherterm="gloss-pdl">PDL</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-escp"> + <glossterm><acronym>ESC/P</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>E</emphasis>pson + <emphasis>S</emphasis>tandard <emphasis>C</emphasis>odes for + <emphasis>P</emphasis>rinters. Besides &PostScript; and PCL, Epson's ESC/P + printer language is one of the best known.</para> + <glossseealso otherterm="gloss-pcl">PCL</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + <glossseealso otherterm="gloss-hpgl">hpgl</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-esp"> + <glossterm><acronym>ESP</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>E</emphasis>asy + <emphasis>S</emphasis>oftware <emphasis>P</emphasis>roducts; + the company that developed &CUPS; (the "Common &UNIX; Printing System"). + </para> + <glossseealso otherterm="gloss-easysoftwareproducts">Easy Software Products</glossseealso> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-espprintpro">ESP PrintPro</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-espghostscript"> + <glossterm><acronym>ESP</acronym> Ghostscript</glossterm> + <glossdef><para>A Ghostscript version that is maintained by Easy Software + Products. It includes pre-compiled Gimp-Print drivers for + many inkjets (plus some other goodies). ESP Ghostscript + will produce photographic quality prints in many cases, especially + with the Epson Stylus model series. ESP Ghostscript is GPL-software. + </para> + <glossseealso otherterm="gloss-easysoftwareproducts">Easy Software Products</glossseealso> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-espprintpro">ESP PrintPro</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-espprintpro"> + <glossterm><acronym>ESP</acronym> PrintPro</glossterm> + <glossdef><para> This professional enhancement to &CUPS; (the "Common &UNIX; + Printing System") is sold by the developers + of &CUPS; complete with more than 2,300 printer drivers for several commercial + &UNIX; platforms. <ulink url="http://www.easysw.com/printpro/">ESP PrintPro</ulink> + is supposed to work "out of the box" with little or no configuration + for users or admins. ESP also sell support contracts for + &CUPS; and PrintPro. These sales help to feed the programmers who + develop the Free version of &CUPS;. + </para> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-filter"> + <glossterm>Filter</glossterm> + <glossdef><para>Filters, in general, are programs that take some input + data, work on it and pass it on as their output data. Filters + may or may not change the data. +<!-- + </para> + <para> +--> + Filters in the context of printing, are programs that convert + a given file (destined for printing, but not suitable in the + format it is presently) into a printable format. Sometimes + whole "filter chains" have to be constructed to achieve the + goal, piping the output of one filter as the input to the next. + </para> + <glossseealso otherterm="gloss-ghostscript">Ghostscript</glossseealso> + <glossseealso otherterm="gloss-rip">RIP</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-foomatic"> + <glossterm>Foomatic</glossterm> + <glossdef><para>Foomatic started out as the wrapper name for a set of + different tools available from <ulink + url="http://www.linuxprinting.org/">Linuxprinting.org</ulink> + These tools aimed to make the usage of traditional + Ghostscript and other print filters easier for users and + extend the filters' capabilities by adding more command line + switches or explain the driver's execution data. +<!-- + </para> + <para> +--> + Foomatic's different incarnations are &CUPS;-O-Matic, PPD-O-Matic, + PDQ-O-Matic, LPD-O-Matic, PPR-O-Matic, MF-O-Matic and + Direct-O-Matic. All of these allow the generation + of appropriate printer configuration files online, by simply + selection the suitable model and suggested (or alternate) driver + for that machine. +<!-- + </para> + <para> +--> + More recently, Foomatic gravitated towards becoming a "meta-spooling" + system, that allows configuration of the underlying print subsystem + through a unified set of commands (however, this is much more + complicated than KDEPrint's &GUI; interface, which performs a similar + task with regards to different print subsystems). </para> + <glossseealso otherterm="gloss-cups-o-matic">&CUPS;-O-Matic</glossseealso> + <glossseealso otherterm="gloss-PPD-O-Matic">PPD-O-Matic</glossseealso> + <glossseealso otherterm="gloss-cupsomatic">cupsomatic</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-ghostscript"> + <glossterm>Ghostscript</glossterm> + <glossdef><para>Ghostscript is a &PostScript; Raster Image Processor (RIP) in software, originally + developed by L. Peter Deutsch. There is always a <acronym>GPL</acronym> version + of Ghostscript available for free usage and distribution + (mostly 1 year old) while + the current version is commercially sold under another license. +<!-- + </para> + <para> +--> + Ghostscript is widely used inside the Linux and &UNIX; world + for transforming &PostScript; into raster data suitable + for sending to non-&PostScript; devices.</para> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + <glossseealso otherterm="gloss-rip">RIP</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-gimpprint"> + <glossterm>Gimp-Print</glossterm> + <glossdef><para>Contrary to its name, Gimp-Print is no longer + just the plugin to be used for printing from the popular + Gimp program -- its codebase can also serve to be compiled + into... + <!-- + </para> + <para> +--> + *...a set of PPDs and associated filters that integrate seamlessly + into &CUPS;, supporting around 130 different printer models, providing + photographic output quality in many cases; +<!-- + </para> + <para> +--> + + *...a Ghostscript filter that can be used with any other + program that needs a software-RIP; +<!-- + </para> + <para> +--> + + *...a library that can be used by other software applications + in need of rasterization functions. + + +<!-- +after 4 hours fiddling, I +could not get those s!@*#? +<itemizedlist> to pass +through the meinproc checks. +For the time being I gave up +on it and handle it differently +now. + <itemizedlist> + <listitem>...a set of PPDs and associated filters that integrate seamlessly + into &CUPS;, supporting around 130 different printer models, providing + photografic output quality in many cases;</listitem> + <listitem>...a Ghostscript filter that can be used with any other + program that needs a software-RIP;</listitem> + <listitem>...a library that can be used by other software applications + in need of rasterization functions.</listitem> + </itemizedlist> +--> + </para> + <glossseealso otherterm="gloss-lexmark">Lexmark Drivers</glossseealso> + <glossseealso otherterm="gloss-rip">RIP</glossseealso> + <glossseealso otherterm="gloss-ghostscript">Ghostscript</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-hp"> + <glossterm><acronym>&HP;</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>H</emphasis>ewlett-<emphasis>Packard</emphasis>; + one of the first companies to distribute their own Linux printer + drivers. -- More recently, the Company has released their + "HPIJS" package of drivers, including source code and a Free license. + This is the first printer manufacturer to do so. HPIJS supports most + current models of HP Ink- and DeskJets. + </para> + </glossdef> + </glossentry> + + + <glossentry id="gloss-hpgl"> + <glossterm><acronym>&HP;/GL</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>&HP;</emphasis> + <emphasis>G</emphasis>raphical <emphasis>L</emphasis>anguage; + a &HP; printer language mainly used for plotters; many CAD + (Computer Aided Design) software programs output &HP;/GL files for + printing.</para> + <glossseealso otherterm="gloss-escp">ESC/P</glossseealso> + <glossseealso otherterm="gloss-pcl">PCL</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-hpjetdirectprotocol"> + <glossterm>&HP; JetDirect Protocol</glossterm> + <glossdef><para>A term branded by &HP; to describe their implementation + of print data transfer to the printer via an otherwise "AppSocket" or + "Direct TCP/IP Printing" named protocol.</para> + <glossseealso otherterm="gloss-appsocketprotocol">AppSocket Protocol</glossseealso> + <glossseealso otherterm="gloss-directtcpipprinting">Direct TCP/IP Printing</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-ietf"> + <glossterm><acronym>IETF</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>I</emphasis>nternet + <emphasis>E</emphasis>ngineering <emphasis>T</emphasis>ask + <emphasis>F</emphasis>orce; an assembly of Internet, software + and hardware experts that discuss + new networking technologies and very often arrive at + conclusions that are regarded by many as standards. "TCP/IP" + is the most famous example. +<!-- + </para> + <para> +--> + + IETF standards, as well as + drafts, discussions, ideas and useful tutorials, are + put in writing in the famous series of "RFCs", which + are available to the public and included in most Linux and + BSD distributions.</para> + <glossseealso otherterm="gloss-ipp">IPP</glossseealso> + <glossseealso otherterm="gloss-pwg">PWG</glossseealso> + <glossseealso otherterm="gloss-rfc">RFC</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-ipp"> + <glossterm><acronym>IPP</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>I</emphasis>nternet + <emphasis>P</emphasis>rinting <emphasis>P</emphasis>rotocol; + defined in a series of RFCs accepted by the IETF with + status "proposed standard"; was designed + by the PWG. -- IPP is a completely new design for network printing, + but it utilizes a very well-known and proven method for the + actual data transfer: HTTP 1.1! By not "re-inventing the wheel", + and basing itself on an existing and robust Internet standard, + IPP is able to relatively easily bolt other HTTP-compatible standard + mechanisms into its framework: +<!-- + </para> + <para> +--> + * Basic, Digest or Certificate authentication + mechanisms; +<!-- + </para> + <para> +--> + * SSL or TLS for encryption of transferred + data; +<!-- + </para> + <para> +--> + * LDAP for directory services (to publish + data on printers, device-options, drivers, costs or + also to the network; or to check for passwords while + performing authentication). +<!-- + </para> + <para> +--> + +<!-- + </para> + <itemizedlist> + <listitem>Basic, Digest or Certificate authentication + mechanisms</listitem> + <listitem>SSL or TLS for encryption of transferred + data</listitem> + <listitem>LDAP for directory services (to publish + data on printers, device-options, drivers, costs or + elso to the network; or to check for passwords while + conducting authentication)</listitem> + </itemizedlist> +--> + </para> + + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-pwg">PWG</glossseealso> + <glossseealso otherterm="gloss-ietf">IETF</glossseealso> + <glossseealso otherterm="gloss-rfc">RFC</glossseealso> + <glossseealso otherterm="gloss-tls">TLS</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-kdeprint"> + <glossterm><acronym>KDEPrint</acronym></glossterm> + <glossdef><para>The new printing functionality of &kde; since version 2.2 + consists of several modules that translate the features and settings + of different available print subsystems (&CUPS;, BSD-style LPR/LPD, RLPR...) + into nice &kde; desktop &GUI; windows and dialogs to ease their + usage. +<!-- + </para> + <para> +--> + Most important for day-to-day usage is "kprinter", the new + &GUI; print command. -- Note: KDEPrint does <emphasis>not</emphasis> implement its own + spooling mechanism or its own &PostScript; processing; for this it + relies on the selected <emphasis>print subsystem</emphasis> + -- however it does add some functionality of its own on top of this + foundation... + </para> + <glossseealso otherterm="gloss-bsdstyleprinting">BSD-style printing</glossseealso> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-kprinter">kprinter</glossseealso> + <glossseealso otherterm="gloss-kdeprinthandbook">KDEPrint Handbook</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-kdeprinthandbook"> + <glossterm><acronym>KDEPrint Handbook...</acronym></glossterm> + <glossdef><para>...is the name of the reference document that describes KDEPrint + functions to users and administrators. You can load it into Konqueror by + typing "help:/kdeprint" into the address field. The <ulink + url="http://printing.kde.org/">KDEPrint website</ulink> + is the resource for updates to this documentation, as well as PDF + versions suitable for printing it. It is authored and maintained by Kurt + Pfeifle. + </para> + <glossseealso otherterm="gloss-cupsfaq">&CUPS;-FAQ</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-kprinter"> + <glossterm>kprinter</glossterm> + <glossdef><para><emphasis>kprinter</emphasis> is the new powerful + print utility that is natively used by all &kde; applications. +<!-- + </para> + <para> +--> + Contrary to some common misconceptions, + <emphasis>kprinter</emphasis> is <emphasis>not</emphasis> a &CUPS;-only tool, + but supports different print subsystems. You can even switch + to a different print subsystem "on the fly", in between two jobs, + without re-configuration. Of course, due to the powerful + features of &CUPS;, <emphasis>kprinter</emphasis> is + best suited for use with a &CUPS; frontend. +<!-- + </para> + <para> +--> + <emphasis>kprinter</emphasis> is the successor + to "qtcups", which is no longer being actively maintained. It has + inherited all the best features of qtcups and added several new ones. +<!-- + </para> + <para> +--> + + MOST IMPORTANT: you can use <emphasis>kprinter</emphasis> + with all its features in all non-&kde; applications that allow + a customized print command, like gv, Acrobat Reader, Netscape, + Mozilla, Galeon, StarOffice, OpenOffice and all GNOME programs. +<!-- + </para> + <para> +--> + <emphasis>kprinter</emphasis> can act as a "standalone" + utility, started from an X-Terminal or a "Mini-CLI" to + print many different files, from different folders, with different + formats, in one job and simultaneously, without the need to first open the + files in the applications! (File formats supported this way are &PostScript;, + PDF, International and ASCII Text, as well as many different popular graphic + formats, such as PNG, TIFF, JPEG, PNM, Sun RASTER, &etc;) + </para> + <glossseealso otherterm="gloss-qtcups">QtCUPS</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-lexmark"> + <glossterm><acronym>Lexmark</acronym></glossterm> + <glossdef><para>was one of the first companies to distribute their own Linux printer + drivers for some of their models. However, those drivers are binary only + (no source code available), and therefore cannot be used to integrate into + other Free printing software projects. + </para> + </glossdef> + </glossentry> + + <glossentry id="gloss-linuxprintingorg"> + <glossterm>Linuxprinting.org</glossterm> + <glossdef><para>Linuxprinting.org = not just for Linux; all &UNIX;-like OS-es, + like *BSD and commercial Unices may find useful printing + information on this site. This web site is the home for the interesting + Foomatic project, that strives to develop the "Meta Print Spool and Driver + Configuration Toolset" (being able to configure, through one common + interface, different print subsystems and their required drivers) with the + ability to transfer all queues, printers and configuration files seamlessly + to another spooler without new configuration effort. -- Also, they maintain + the Printing Database; a collection of driver and device information that + enables everybody to find the most current information about printer models, + and also generate online the configuration files for any + spooler/driver/device combo known to work with one of the common Linux or + &UNIX; print subsystems. + </para> + <glossseealso otherterm="gloss-linuxprintingdatabase">Linuxprinting database</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-linuxprintingdatabase"> + <glossterm><acronym>Linuxprinting.org Database</acronym></glossterm> + <glossdef><para>....Database containing printers and drivers that are suitable + for them... ...a lot of information and documentation to be found... ...it + is now also providing some tools and utilities for easing the integration + of those drivers into a given system... ...the "Foomatic" family + of utilities; being the toolset to make use of the database + for most of the commonly used print subsystems, for generating "on the fly" + working configurations for your printer model. + </para> + <glossseealso otherterm="gloss-foomatic">Foomatic</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-lprlpd"> + <glossterm><acronym>LPR/LPD</acronym> printing</glossterm> + <glossdef><para>LPR == some people translate <emphasis>L</emphasis>ine + <emphasis>P</emphasis>rinting <emphasis>R</emphasis>equest, others: + <emphasis>L</emphasis>ine <emphasis>P</emphasis>rinter + <emphasis>R</emphasis>emote.</para> + <glossseealso otherterm="gloss-bsdstyleprinting">BSD-style printing</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-magicfilter"> + <glossterm>Magicfilter</glossterm> + <glossdef><para>Similarly to the APSfilter program, Magicfilter + provides automatic file type recognition functions and, base + on that, automatic file conversion to a printable format, + depending on the target printer.</para> + <glossseealso otherterm="gloss-apsfilter">APSfilter</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-mimetypes"> + <glossterm>&MIME;-Types</glossterm> + <glossdef><para>Abbreviation for <emphasis>M</emphasis>ultipurpose (or + Multimedia) <emphasis>I</emphasis>nternet <emphasis>M</emphasis>ail + <emphasis>E</emphasis>xtensions; &MIME;-Types were first used to allow + the transport of binary data (like mail attachments containing + graphics) over mail connections that were normally only transmitting + ASCII characters: the data had to be encoded into an ASCII representation. +<!-- + </para> + <para> +--> + Later this concept was extended to describe a data format in + a platform independent, but at the same time non-ambiguous, way. + From &Windows; everybody knows the .doc extensions for &Microsoft; Word files. + This is handled ambiguously on the &Windows; platform: .doc extensions are also + used for simple text files or for Adobe Framemaker files. And if a real + Word file is renamed with a different extension, it can no longer be + opened by the program. +<!-- + </para> + <para> +--> + &MIME; typed files carry a recognition string with them, describing + their file format based on <emphasis>main_category/sub_category</emphasis>. + Inside IPP, print files are also described using the &MIME; type scheme. + &MIME; types are registered with the IANA (Internet Assigning Numbers + <emphasis>Association</emphasis>) to keep them unambiguous. +<!-- + </para> + <para> +--> + &CUPS; has some &MIME; types of its own registered, like + <emphasis>application/vnd.cups-raster</emphasis> (for the &CUPS;-internal + raster image format). + + </para> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-easysoftwareproducts">Easy Software Products</glossseealso> + <glossseealso otherterm="gloss-espprintpro">ESP PrintPro</glossseealso> + <glossseealso otherterm="gloss-gimpprint">Gimp-Print</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-pcl"> + <glossterm><acronym>PCL</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>P</emphasis>rinter + <emphasis>C</emphasis>ontrol <emphasis>L</emphasis>anguage; + developed by &HP;. PCL started off in version 1 as a simple + command set for ASCII printing; now, + in its versions PCL6 and PCL-X, it is capable of printing graphics + and color -- but outside the &Microsoft; &Windows; realm and &HP-UX; + (&HP;'s own brand of &UNIX;), it is not commonly used...</para> + <glossseealso otherterm="gloss-escp">ESC/P</glossseealso> + <glossseealso otherterm="gloss-hpgl">&HP;/GL</glossseealso> + <glossseealso otherterm="gloss-pdl">PDL</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-pdl"> + <glossterm><acronym>PDL</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>P</emphasis>age + <emphasis>D</emphasis>escription <emphasis>L</emphasis>anguage; + PDLs describe, in an abstract way, the graphical representation + of a page. - Before it is actually transferred into + toner or ink laid down on to paper, a PDL needs to be + "interpreted" first. In &UNIX;, the most important PDL + is &PostScript;. + </para> + <glossseealso otherterm="gloss-escp">ESC/P</glossseealso> + <glossseealso otherterm="gloss-hpgl">&HP;/GL</glossseealso> + <glossseealso otherterm="gloss-pcl">PCL</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-pixel"> + <glossterm>Pixel</glossterm> + <glossdef><para>Abbreviation for <emphasis>Pic</emphasis>ture + <emphasis>El</emphasis>ement; this term describes the smallest + part of a raster picture (either as printed on paper + or as displayed on a monitor by cathode rays or LCD elements). As + any graphical or image representation on those types of output + devices is composed of pixels, the values of "ppi" (pixel per inch) + and &dpi; (dots per inch) are one important parameter for the + overall quality and resolution of an image.</para> + <glossseealso otherterm="gloss-filter">Filter</glossseealso> + <glossseealso otherterm="gloss-ghostscript">Ghostscript</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + <glossseealso otherterm="gloss-raster">Raster</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-pjl"> + <glossterm><acronym>PJL</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>P</emphasis>rint + <emphasis>J</emphasis>ob <emphasis>L</emphasis>anguage; + developed by &HP; to control and influence default and per-job + settings of a printer. It may not only be used + for &HP;'s own (PCL-)printers; also many &PostScript; + and other printers understand PJL commands sent to them + inside a print job, or in a separate signal.</para> + <glossseealso otherterm="gloss-pcl">PCL</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-postscript"> + <glossterm>&PostScript;</glossterm> + <glossdef><para>&PostScript; (often shortened to "PS") is the de-facto + standard in the &UNIX; world for printing files. It was + developed by Adobe and licensed to printer manufacturers + and software companies. +<!-- + </para> + <para> +--> + As the &PostScript; specifications were + published by Adobe, there are also "Third Party" implementations + of &PostScript; generating and &PostScript; interpreting software + available (one of the best-known in the Free software world + being Ghostscript, a powerful PS-interpreter). + </para> + <glossseealso otherterm="gloss-escp">ESC/P</glossseealso> + <glossseealso otherterm="gloss-hpgl">&HP;/GL</glossseealso> + <glossseealso otherterm="gloss-pcl">PCL</glossseealso> + <glossseealso otherterm="gloss-ppd">PPD</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-ppd"> + <glossterm><acronym>PPD</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>P</emphasis>ostScript + <emphasis>P</emphasis>rinter <emphasis>D</emphasis>escription; + PPDs are ASCII files storing all information about the special + capabilities of a printer, plus definitions of the (PostScript- + or PJL-) commands to call on a certain capability (like print + duplexing). +<!-- + </para> + <para> +--> + + As the explanation of the acronym reveals, PPDs were originally + only used for &PostScript; printers. &CUPS; has extended the + PPD concept to all types of printers. +<!-- + </para> + <para> +--> + + PPDs for &PostScript; printers are provided by the printer + vendors. They can be used with &CUPS; and KDEPrint to have access + to the full features of any &PostScript; printer. The KDEPrint Team + recommends using a PPD originally intended for use with + &Microsoft; Windows NT. +<!-- + </para> + <para> +--> + + PPDs for non-PostScript printers <emphasis>need</emphasis> a + companion "filter" to process the &PostScript; print files into + a format digestible for the non-PostScript target device. Those + PPD/filter combos are not (yet) available from the vendors. After + the initiative by the &CUPS; developers to utilize PPDs, the Free + Software community was creative enough to quickly come up with + support for most of the currently used printer models, through + PPDs and classical Ghostscript filters. But note: the printout + quality varies from "hi-quality photographic output" (using + Gimp-Print with most Epson inkjets) to "hardly readable" (using + Foomatic-enabled Ghostscript filters for models rated as + "paperweight" in the Linuxprinting.org database). + </para> + <glossseealso otherterm="gloss-cups">&CUPS;</glossseealso> + <glossseealso otherterm="gloss-linuxprintingorg">Linuxprinting.org</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-PPD-O-Matic"> + <glossterm>PPD-O-Matic</glossterm> + <glossdef><para>PPD-O-Matic is a set of Perl scripts that run on the Linuxprinting.org + web server and can be used online to generate PPDs for any printer that is known + to print with Ghostscript. +<!-- + </para> + <para> +--> + + These PPDs can be hooked up to &CUPS;/KDEPrint, as well as + used inside PPD-aware applications like StarOffice to determine all different + parameters of your printjobs. It is now recommended, in most cases, to + use "PPD-O-Matic" instead of the older &CUPS;-O-Matic. +<!-- + </para> + <para> +--> + + To generate a PPD, go to the <ulink + url="http://www.linuxprinting.org/printer_list.cgi">printer + database</ulink>, select your printer model, follow + the link to show the available Ghostscript filters for that printer, select + one, click "generate" and finally save the file to your local system. + Be sure to read the instructions. Make sure that your local system + does indeed have Ghostscript and the filter, which you chose + before generating the PPD, installed. + </para> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + <glossseealso otherterm="gloss-cups-o-matic">&CUPS;-O-Matic</glossseealso> + <glossseealso otherterm="gloss-linuxprintingorg">Linuxprinting.org</glossseealso> + <glossseealso otherterm="gloss-foomatic">Foomatic</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-printcap"> + <glossterm>printcap</glossterm> + <glossdef><para>In BSD-style print systems, the "printcap" file holds + the configuration information; the printing daemon reads this file + to determine which printers are available, what filters are to be + user for each, where the spooling folder is located, + if there are banner pages to be used, and so on... + Some applications also depend on read access to the printcap + file, to obtain the names of available printers. </para> + <glossseealso otherterm="gloss-bsdstyleprinting">BSD-style printing</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-printermib"> + <glossterm>Printer-<acronym>MIB</acronym></glossterm> + <glossdef><para>Abbreviation for + <emphasis>Printer</emphasis>-<emphasis>M</emphasis>anagement + <emphasis>I</emphasis>nformation <emphasis>B</emphasis>ase; the + Printer-MIB defines a set of parameters that are to be + stored inside the printer for access + through the network. This is useful if many (in some cases, literally + thousands) network printers are managed centrally + with the help of SNMP (Simple Network Management Protocol).</para> + <glossseealso otherterm="gloss-pwg">PWG</glossseealso> + <glossseealso otherterm="gloss-snmp">SNMP</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-pwg"> + <glossterm><acronym>PWG</acronym></glossterm> + <glossdef><para>Abbreviation for + <emphasis>P</emphasis>rinter <emphasis>W</emphasis>orking + <emphasis>G</emphasis>roup; the PWG is a loose grouping of + representatives of the printer industry that has, in the past + years, developed different standards + in relation to network printing. These were later accepted by the + IETF as RFC standards, like the "Printer-MIB" and the IPP.</para> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + <glossseealso otherterm="gloss-ipp">IPP</glossseealso> + <glossseealso otherterm="gloss-printermib">Printer-MIB</glossseealso> + <glossseealso otherterm="gloss-snmp">SNMP</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-printkioslave"> + <glossterm>print:/ KIO Slave</glossterm> + <glossdef><para>You can use a syntax of "print:/..." to get quick access + to KDEPrint resources. Typing "print:/manager" as a Konqueror URL + address gives administrative access to KDEPrint. Konqueror uses &kde;'s + famous "KParts" technology to achieve that. </para> + <glossseealso otherterm="gloss-ioslave">IO Slave</glossseealso> + <glossseealso otherterm="gloss-kparts">KParts</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-printerdatabase"> + <glossterm>Printer Database</glossterm> + <glossdef><para>.</para> + <glossseealso otherterm="gloss-linuxprintingdatabase">Linuxprinting Database</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-qtcups"> + <glossterm><acronym>Qt&CUPS;</acronym></glossterm> + <glossdef><para>Qt&CUPS; and KUPS were the predecessors of KDEPrint; they are now + deprecated and no longer maintained. What was good in qtcups is all inherited + by "kprinter", the new KDE print dialog (which is much improved over qtcups); + what you liked about kups is now all in the KDEPrint Manager (accessible + via the KDE Control Center or via the URL "print:/manager" from Konqueror) -- + with more functionality and less bugs... Its former developer, Michael Goffioul, is now + the developer of KDEPrint -- a very nice and productive guy and quick bug fixer... + </para> + <glossseealso otherterm="gloss-kprinter">kprinter</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-raster"> + <glossterm>Raster Image</glossterm> + <glossdef><para>Every picture on a physical medium + is composed of a pattern of discrete dots in different colors and (maybe) + sizes. This is called a "raster image". +<!-- + </para> + <para> +--> + + This is as opposed to a "vector image" + where the graphic is described in terms of continuous curves, shades, + forms and filled areas, represented by mathematical formula. Vector images + normally have a smaller file size and may be scaled in size + without any loss of information and quality --- but they cannot be + output directly, but always have to be "rendered" or "rasterized" + first to the given resolution that the output device is capable of... +<!-- + </para> + <para> +--> + + + The rasterization is done by a Raster Image Processor (RIP, + often the Ghostscript software) or some other filtering + instance.</para> + <glossseealso otherterm="gloss-pixel">Pixel</glossseealso> + <glossseealso otherterm="gloss-ghostscript">Ghostscript</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + <glossseealso otherterm="gloss-filter">Filter</glossseealso> + <glossseealso otherterm="gloss-rip">RIP</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-rip"> + <glossterm><acronym>RIP</acronym></glossterm> + <glossdef><para>Abbreviation for + <emphasis>R</emphasis>aster <emphasis>I</emphasis>mage + <emphasis>P</emphasis>rocess(or); if used in the context of + printing, "RIP" means a hardware or software + instance that converts &PostScript; (or other print formats + that are represented in one of the non-Raster PDLs) into a + raster image format in such a way that it is acceptable + for the "marking engine" of the printer. +<!-- + </para> + <para> +--> + + &PostScript; printers + contain their own PostScript-RIPs. A RIP may or may not be located + inside a printer. +<!-- + </para> + <para> +--> + + For many &UNIX; systems, Ghostscript is the package that provides + a "RIP in software", running on the host computer, and pre-digesting + the &PostScript; or other data to become ready to be sent to the + printing device (hence you may perceive a "grain of truth" in the + slogan "Ghostscript turns your printer into a &PostScript; + machine", which of course is not correct in the true sense of the + meaning).</para> + <glossseealso otherterm="gloss-filter">Filter</glossseealso> + <glossseealso otherterm="gloss-ghostscript">Ghostscript</glossseealso> + <glossseealso otherterm="gloss-postscript">&PostScript;</glossseealso> + <glossseealso otherterm="gloss-pdl">PDL</glossseealso> + <glossseealso otherterm="gloss-raster">Raster</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-rlpr"> + <glossterm><acronym>RLPR</acronym> (Remote LPR)</glossterm> + <glossdef><para>Abbreviation for <emphasis>R</emphasis>emote + <emphasis>L</emphasis>ine <emphasis>P</emphasis>rinting + <emphasis>R</emphasis>equest; this is a BSD-style printing system, + that needs no root privileges to be installed, and no "printcap" to + work: all parameters may be specified on the command + line. +<!-- + </para> + <para> +--> + + RLPR comes in handy for many laptop users who are + working in frequently changing environments. This is because it + may be installed concurrently with every other printing + sub system, and allows a very flexible and quick + way to install a printer for direct access via LPR/LPD. +<!-- + </para> + <para> +--> + + KDEPrint + has an "Add Printer Wizard" to make RLPR usage even easier. + The kprinter command allows switching to RLPR "on + the fly" at any time.</para> + <glossseealso otherterm="gloss-kdeprint">KDEPrint</glossseealso> + <glossseealso otherterm="gloss-kprinter">kprinter</glossseealso> + <glossseealso otherterm="gloss-printcap">printcap</glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-snmp"> + <glossterm><acronym>SNMP</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>S</emphasis>imple + <emphasis>N</emphasis>etwork <emphasis>M</emphasis>anagement + <emphasis>P</emphasis>rotocol; SNMP is widely used to control + all types of network node (Hosts, Routers, Switches, Gateways, + Printers...) remotely.</para> + <glossseealso otherterm="gloss-pwg">PWG</glossseealso> + <glossseealso otherterm="gloss-printermib">Printer-MIB</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-ssl"> + <glossterm><acronym>SSL(3)</acronym> encryption</glossterm> + <glossdef><para>Abbreviation for <emphasis>S</emphasis>ecure + <emphasis>S</emphasis>ocket <emphasis>L</emphasis>ayer; + <acronym>SSL</acronym> is a proprietary encryption method for data + transfer over HTTP that was developed by Netscape. It is now being + replaced by an IETF standard named TLS. + </para> + <glossseealso otherterm="gloss-tls"><acronym>TLS</acronym></glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-spooling"> + <glossterm><acronym>SPOOL</acronym>ing</glossterm> + <glossdef><para>Abbreviation for <emphasis>S</emphasis>ynchronous + <emphasis>P</emphasis>eripheral <emphasis>O</emphasis>perations + <emphasis>O</emphasis>n<emphasis>L</emphasis>ine; + <acronym>SPOOL</acronym>ing enables printing applications + (and users) to continue their work + as the job is being taken care of by a system <acronym>daemon</acronym>, + which stores the file at a temporary location until the printer is ready + to print. </para> + <glossseealso otherterm="gloss-daemon"><acronym>Daemon</acronym></glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-tls"> + <glossterm><acronym>TLS</acronym> encryption</glossterm> + <glossdef><para>Abbreviation for <emphasis>T</emphasis>ransport + <emphasis>L</emphasis>ayer <emphasis>S</emphasis>ecurity; + <acronym>TLS</acronym> is an encryption standard for + data transfered over HTTP 1.1; it is defined in RFC 2246; + although based on the former SSL development + (from Netscape) it is not fully compatible with it. + </para> + <glossseealso otherterm="gloss-ssl"><acronym>SSL(3)</acronym></glossseealso> + </glossdef> + </glossentry> + + + <glossentry id="gloss-systemVstyleprinting"> + <glossterm>System V-style printing</glossterm> + <glossdef><para>This is the second flavor of traditional &UNIX; + printing (as opposed to BSD-style printing). It uses + a different command set (lp, lpadmin,...) to BSD, + but is not fundamentally different from it. However, the + gap between the two is big enough to make the two + incompatible, so that a BSD-client cannot simply print + to a System V style print server without additional + tweaking... IPP is supposed to resolve this weakness + and more. + </para> + <glossseealso otherterm="gloss-bsdstyleprinting"><acronym>BSD-style printing</acronym></glossseealso> + <glossseealso otherterm="gloss-ipp"><acronym>IPP</acronym></glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-turboprint"> + <glossterm>TurboPrint</glossterm> + <glossdef><para>Shareware software providing photo quality printing for many + inkjet printers. It is useful if you are unable to find a driver for your + printer and may be hooked into either a traditional Ghostscript system + or a modern &CUPS; system.</para> + <glossseealso otherterm="gloss-gimpprint">Gimp-Print</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-xpp"> + <glossterm><acronym>XPP</acronym></glossterm> + <glossdef><para>Abbreviation for <emphasis>X</emphasis> + <emphasis>P</emphasis>rinting <emphasis>P</emphasis>anel; + <acronym>XPP</acronym> was the first Free + graphical print command for &CUPS;, written by Till Kamppeter, + and in some ways a model for the "kprinter" utility in &kde;.</para> + </glossdef> + </glossentry> +<!-- + <glossentry id="gloss-1"> + <glossterm>xxxx</glossterm> + <glossdef><para>.</para> + <glossseealso otherterm="gloss-1">xyz</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-3"> + <glossterm>xxxx</glossterm> + <glossdef><para>.</para> + <glossseealso otherterm="gloss-1">xyz</glossseealso> + </glossdef> + </glossentry> + + <glossentry id="gloss-4"> + <glossterm>xxxx</glossterm> + <glossdef><para>.</para> + <glossseealso otherterm="gloss-1">xyz</glossseealso> + </glossdef> + </glossentry> +--> + </glossdiv> + + +<!-- +</glossary> +--> diff --git a/doc/kappfinder/Makefile.am b/doc/kappfinder/Makefile.am new file mode 100644 index 000000000..3f20a1e1b --- /dev/null +++ b/doc/kappfinder/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + +KDE_MANS = AUTO diff --git a/doc/kappfinder/man-kappfinder.1.docbook b/doc/kappfinder/man-kappfinder.1.docbook new file mode 100644 index 000000000..1c0fdb681 --- /dev/null +++ b/doc/kappfinder/man-kappfinder.1.docbook @@ -0,0 +1,81 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<author><personname><firstname>Jan</firstname><surname>Schaumann</surname></personname> +<email>[email protected]</email></author> +<date>April 8, 2003</date> +</refentryinfo> + +<refmeta> +<refentrytitle><command>kappfinder</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>kappfinder</command></refname> +<refpurpose>An app to add installed applications to the &kde; menu.</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>kappfinder</command> +<group><option>--dir</option> <replaceable> directory</replaceable></group> +<group><option>KDE Generic Options</option></group> +<group><option>Qt Generic Options</option></group> + +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> + +<para>The KDE application findern (&kappfinder;) looks for legacy and +third party applications that are installed on your system and adds +them to the KDE menu system. </para> + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>--dir</option> <replaceable>directory</replaceable></term> +<listitem> +<para> +Install <filename>.desktop</filename> files into directory <replaceable>directory</replaceable> +</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>More detailed user documentation is available from <ulink +url="help:/kappfinder">help:/kappfinder</ulink> (either enter this +<acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kappfinder</parameter></userinput>).</para> + +</refsect1> + +<refsect1> +<title>Authors</title> + +<para>&kappfinder; was written by &Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail;</para> + +<para>This man page was prepared by Jan Schaumann +<email>[email protected]</email> for the <quote>Missing Man +Pages Project</quote> ( <ulink +url="http://www.netmeister.org/misc/m2p2/index.html">http://www.netmeister.org/misc/m2p2/index.html</ulink>.</para> + +</refsect1> + +</refentry> diff --git a/doc/kate/Makefile.am b/doc/kate/Makefile.am new file mode 100644 index 000000000..17a314c39 --- /dev/null +++ b/doc/kate/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/kate/TODO b/doc/kate/TODO new file mode 100644 index 000000000..d41ed4b80 --- /dev/null +++ b/doc/kate/TODO @@ -0,0 +1,6 @@ +Fill empty sections. +Rewrite intro chapter. +Write regexp appendix. +Add Misc Tools chapter, ao Find in Files. +Go over everything and make sure it reflects the practial truuth ;) +Add links to foreign documentation. diff --git a/doc/kate/advanced.docbook b/doc/kate/advanced.docbook new file mode 100644 index 000000000..b9b0cda91 --- /dev/null +++ b/doc/kate/advanced.docbook @@ -0,0 +1,1242 @@ +<chapter id="advanced-editing-tools"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Advanced Editing Tools</title> + +<sect1 id="advanced-editing-tools-comment"> + +<title>Comment/Uncomment</title> + +<para>The Comment and Uncomment commands, available from the +<guimenu>Tools</guimenu> menu allow you to add or remove comment +markers to the selection, or the current line if no text is selected, +if comments are supported by the format of the text you are +editing.</para> + +<para>The rules for how commenting is done are defined in the syntax +definitions, so if syntax highlighting is not used, commenting/uncommenting +is not possible. </para> + +<para>Some formats define single line comment markers, some multiline +markers and some both. If multiline markers are not available, +commenting out a selection that does not fully include its last line +is not possible.</para> + +<para>If a single line marker is available, commenting single lines is +preferred where applicable, as this helps to avoid problems with +nested comments.</para> + +<para>When removing comment markers, no uncommented text should be +selected. When removing multiline comment markers from a selection, +any whitespace outside the comment markers is ignored.</para> + +<para><indexterm><primary>comment</primary></indexterm> +To place comment markers, use the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice> +menu item or the related keyboard shortcut sequence, default is +<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo>.</para> + +<para><indexterm><primary>uncomment</primary></indexterm> +To remove comment markers, use the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice> +menu item or the related keyboard shortcut, default is <keycombo +action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo>.</para> + +</sect1> + +<sect1 id="advanced-editing-tools-commandline"> +<title>The Editor Component Command Line</title> + +<para>Kate's editor component has an internal command line, allowing you to +perform various actions from a minimal GUI. The command line is a text entry +in the bottom of the editor area, to show it select +<menuchoice><guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem></menuchoice> +or use the shortcut (default is +<keycombo action="simul"><keycap>F7</keycap></keycombo>). The editor provides +a set of commands as documented below, and additional commands can be provided +by plugins.</para> + +<para>To execute a command, type the comand then press the return key. The +command line will indicate wether it succeded and possibly display a message. If +you entered the command line by pressing <keycap>F7</keycap> it will +automatically hide after a few seconds. To clear the message and enter a new +command, press <keycap>F7</keycap> again.</para> + +<para>The command line has a built-in help system, issue the command +<command>help</command> to get started. To see a list of all available commands +issue <command>help list</command>, to view help for a specific command, do +<command>help <replaceable>command</replaceable></command>.</para> + +<para>The command line has a built in history, so you can reuse commands already +typed. To navigate the history, use the <keycap>Up</keycap> and +<keycap>Down</keycap> keys. When showing historical commands, the argument part +of the command will be selected, allowing you to easily overwrite the +arguments.</para> + +<sect2 id="advanced-editing-tools-commandline-commands"> +<title>Standard Command Line Commands</title> + +<sect3 id="advanced-editing-tools-commandline-commands-configure"> +<title>Commands for Configuring the Editor</title> + +<para>These commands are provided by the editor component, and allows you to +configure the active document and view only. This is handy if you want to use +a setting different from the default settings, for example for indentation. +</para> + +<variablelist> +<title>Argument types</title> + +<varlistentry> +<term>BOOLEAN</term> +<listitem><para>This is used with commands that turns things on or off. +Legal values are <userinput>on</userinput>, <userinput>off</userinput>, +<userinput>true</userinput>, <userinput>false</userinput>, +<userinput>1</userinput> or <userinput>0</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term>INTEGER</term> +<listitem><para>An integer number</para></listitem> +</varlistentry> + +<varlistentry> +<term>STRING</term> +<listitem><para>A string</para></listitem> +</varlistentry> + +</variablelist> + +<variablelist> + +<varlistentry> +<term><cmdsynopsis><command>set-tab-width</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the tab width to the number <userinput>width</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-width</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the indentation width to the number +<userinput>width</userinput>. Used only if you are indenting with +spaces.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-word-wrap-column</command><arg>INTEGER width</arg></cmdsynopsis></term> +<listitem><para>Sets the line width for hard wrapping to +<userinput>width</userinput>. This is used if you are having your text wrapped +automatically.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-icon-border</command><arg>BOOLEAN enable</arg> +</cmdsynopsis></term> +<listitem><para>Sets the visibility of the icon border.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-folding-markers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>Sets the visibility of the folding markers pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-line-numbers</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>Sets the visibility of the line numbers pane.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-replace-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, tabs are replaced with spaces as you type. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-remove-trailing-space</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, trailing whitespace are removed whenever the cursor +leaves a line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-show-tabs</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, TAB characters and trailing whitespace will be +visualized by a small dot.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-spaces</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, the editor will indent with +<option>indent-width</option> spaces for each indentation level, rather than +with one TAB character.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-mixed-indent</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>If enabled, kate will use a mix of TAB and spaces for +indentation. Each indentation level will be <option>indent-width</option> wide, +and more indentation levels will be optimized to use as many TAB characters as +possible.</para> +<para>When executed, this command will additionally set space indentation enabled, +and if the indent width is unspecified it will be set to half of the +<option>tab-width</option> for the document at the time of execution.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-word-wrap</command><arg>BOOLEAN +enable</arg></cmdsynopsis></term> +<listitem><para>Enables dynamic word wrap according to +<userinput>enable</userinput></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-replace-tabs-save</command><arg>BOOLEAN enable +</arg></cmdsynopsis></term> +<listitem><para>When enabled, tabs will be replaced with whitespace whenever + the document is saved.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-remove-trailing-space-save</command><arg>BOOLEAN enable</arg></cmdsynopsis></term> +<listitem><para>When enabled, trailing space will be removed from each line +whenever the document is saved.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-indent-mode</command><arg>name</arg></cmdsynopsis></term> +<listitem><para>Sets the autoindentation mode to <userinput>name</userinput>. +If <userinput>name</userinput> is not known, the mode is set to 'none'. Valid +modes are 'cstyle', 'csands', 'xml', 'python', 'varindent' and 'none'.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>set-highlight</command><arg>highlight</arg></cmdsynopsis></term> +<listitem><para>Sets the syntax highlighting system for the document. The +argument must be a valid highlight name, as seen in the +<menuchoice><guimenu>Tools</guimenu><guisubmenu>Highlighting</guisubmenu></menuchoice> +menu. This command provides an autocompletion list for its +argument.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="advanced-editing-tools-commandline-commands-edit"> +<title>Commands for editing</title> + +<para>These commands modify the current document.</para> + +<variablelist> +<varlistentry> +<term><cmdsynopsis><command>indent</command></cmdsynopsis></term> +<listitem><para>Indents the selected lines or the current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>unindent</command></cmdsynopsis></term> +<listitem><para>Unindents the selected lines or current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>cleanindent</command></cmdsynopsis></term> +<listitem><para>Cleans up the indentation of the selected lines or current line +according to the indentation settings in the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>comment</command></cmdsynopsis></term> +<listitem><para>Inserts comment markers to make the selection or selected lines +or current line a comment according to the text format as defined by the syntax +highlight definition for the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>uncomment</command></cmdsynopsis></term> +<listitem><para>Removes comment markers from the selection or selected lines +or current line according to the text format as defined by the syntax highlight +definition for the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>kill-line</command></cmdsynopsis></term> +<listitem><para>Deletes the current line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace</command><arg>pattern</arg><arg>replacement</arg></cmdsynopsis></term> +<listitem><para>Replaces text matching <userinput>pattern</userinput> with +<userinput>replacement</userinput>. If you want to include whitespace in the +<userinput>pattern</userinput>, you must quote both the <userinput>pattern</userinput> +and <userinput>replacement</userinput> with single or double quotes. If the +arguments are unquoted, the first word is used as <userinput>pattern</userinput> +and the rest for <userinput>replacement</userinput>. If +<userinput>replacement</userinput> is empty, each occurrence of +<userinput>pattern</userinput> is removed.</para> +<para>You can set flags to configure the search by adding a colon, followed +by one or more letters each representing a configuration, giving the form +<userinput>replace:options pattern replacement</userinput>. Available options +are: + +<variablelist> + +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>e</userinput></term> +<listitem><para>Search in the selection only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search. If set, you may use +<userinput>\N</userinput> where N is a number to represent captures in the +replacement string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>p</userinput></term> +<listitem><para>Prompt for permission to replace the next occurence.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>w</userinput></term> +<listitem><para>Match whole words only.</para></listitem> +</varlistentry> + +</variablelist> + +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>date</command><arg>format</arg></cmdsynopsis></term> +<listitem><para>Inserts a date/time string as defined by the specified +<userinput>format</userinput>, or the format <quote>yyyy-MM-dd hh:mm:ss</quote> +if none is specified. The following translations are done when interpreting +<userinput>format</userinput>: + +<informaltable> +<tgroup cols="2"> +<tbody> +<row><entry><literal>d</literal></entry><entry>The day as number without a leading zero (1-31).</entry></row> +<row><entry><literal>dd</literal></entry><entry>The day as number with a leading zero (01-31).</entry></row> +<row><entry><literal>ddd</literal></entry><entry>The abbreviated localized day name (e.g. 'Mon'..'Sun').</entry></row> +<row><entry><literal>dddd</literal></entry><entry>The long localized day name (e.g. 'Monday'..'Sunday').</entry></row> +<row><entry><literal>M</literal></entry><entry>The month as number without a leading zero (1-12).</entry></row> +<row><entry><literal>MM</literal></entry><entry>The month as number with a leading zero (01-12).</entry></row> +<row><entry><literal>MMM</literal></entry><entry>The abbreviated localized month name (e.g. 'Jan'..'Dec').</entry></row> +<row><entry><literal>yy</literal></entry><entry>The year as two digit number +(00-99).</entry></row> +<row><entry><literal>yyyy</literal></entry><entry>The year as four digit number (1752-8000).</entry></row> +<row><entry><literal>h</literal></entry><entry>The hour without a leading zero (0..23 or 1..12 if AM/PM display).</entry></row> +<row><entry><literal>hh</literal></entry><entry>The hour with a leading zero (00..23 or 01..12 if AM/PM display).</entry></row> +<row><entry><literal>m</literal></entry><entry>The minute without a leading zero (0..59).</entry></row> +<row><entry><literal>mm</literal></entry><entry>The minute with a leading zero (00..59).</entry></row> +<row><entry><literal>s</literal></entry><entry>The second without a leading zero (0..59).</entry></row> +<row><entry><literal>ss</literal></entry><entry>The second with a leading zero (00..59).</entry></row> +<row><entry><literal>z</literal></entry><entry>The milliseconds without leading zeroes (0..999).</entry></row> +<row><entry><literal>zzz</literal></entry><entry>The milliseconds with leading zeroes (000..999).</entry></row> +<row><entry><literal>AP</literal></entry><entry>Use AM/PM display. AP will be replaced by either "AM" or "PM".</entry></row> +<row><entry><literal>ap</literal></entry><entry>Use am/pm display. ap will be replaced by either "am" or "pm".</entry></row> + +</tbody> +</tgroup> +</informaltable> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>char</command><arg>identifier</arg></cmdsynopsis></term> +<listitem> +<para>This command allows you to insert literal characters by their +numerical identifier, in decimal, octal or hexadecimal form. +To use it launch the Editing Command dialog and type <userinput>char: +[number]</userinput> in the entry box, then hit +<guibutton>OK</guibutton>.</para> + +<example> +<title><command>char</command> examples</title> + +<para>Input: <userinput>char:234</userinput></para> +<para>Output: <computeroutput>ê</computeroutput></para> +<para>Input: <userinput>char:0x1234</userinput></para> +<para>Output: <computeroutput>ሴ</computeroutput></para> +</example> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<indexterm><primary>replace, sed style</primary> +<secondary>search, sed style</secondary></indexterm> +<command>s///[ig]</command> <command>%s///[ig]</command></term> + +<listitem> +<para>This command does a sed-like search/replace operation on the +current line, or on the whole file (<command>%s///</command>).</para> + +<para>In short, the text is searched for text matching the +<emphasis>search pattern</emphasis>, the regular expression between +the first and the second slash, and when a match is found, the +matching part of the text is replaced with the expression between the +middle and last part of the string. Parentheses in the search pattern +create <emphasis>back references</emphasis>, that is the command +remembers which part of the match matched in the parentheses; these +strings can be reused in the replace pattern, referred to as +<userinput>\1</userinput> for the first set of parentheses, +<userinput>\2</userinput> for the second and so on.</para> + +<para>To search for a literal <literal>(</literal> or +<literal>)</literal>, you need to <emphasis>escape</emphasis> it using +a backslash character: <userinput>\(\)</userinput></para> + +<para>If you put an <userinput>i</userinput> at the end of the +expression, the matching will be case insensitive. If you put a +<userinput>g</userinput> at the end, all occurrences of the pattern will be +replaced, otherwise only the first occurrence is replaced.</para> + +<example> + +<title>Replacing text in the current line</title> + +<para>Your friendly compiler just stopped, telling you that the class +<classname>myClass</classname> mentioned in line 3902 in your source file +is not defined.</para> + +<para>"Buckle!" you think, it is of course +<classname>MyClass</classname>. You go to line 3902, and instead of trying +to find the word in the text, you launch the Editing Command Dialog, +enter <userinput>s/myclass/MyClass/i</userinput>, hit the +<guibutton>OK</guibutton> button, save the file and compile – +successfully without the error.</para> + +</example> + +<example> +<title>Replacing text in the whole file</title> + +<para>Imagine that you have a file, in which you mention a <quote>Miss +Jensen</quote> several times, when someone comes in and tells you that +she just got married to <quote>Mr Jones</quote>. You want, of course, +to replace each and every occurrence of <quote>Miss Jensen</quote> +with <quote>Ms Jones</quote>.</para> + +<para>Enter the command line and issue the command +<userinput>%s/Miss Jensen/Ms Jones/</userinput> and hit return, you +are done.</para> + +</example> + +<example> +<title>A More Advanced Example</title> + +<para>This example makes use of <emphasis>back references</emphasis> +as well as a <emphasis>character class</emphasis> (if you do not know what +that is, please refer to the related documentation mentioned +below).</para> + +<para>Suppose you have the following line: + +<programlisting>void MyClass::DoStringOps( String &foo, String &bar String *p, int &a, int &b )</programlisting> +</para> +<para>Now you realize that this is not nice code, and decide that you +want to use the <constant>const</constant> keyword for all +<quote>address of</quote> arguments, those characterized by the & +operator in front of the argument name. You would also like to +simplify the white space, so that there is only 1 whitespace character +between each word.</para> + +<para>Launch the Editing Command Dialog, and enter: +<userinput>s/\s+(\w+)\s+(&)/ const \1 \2/g</userinput> and hit the +<guibutton>OK</guibutton> button. The <userinput>g</userinput> at the end of the expression makes +the regular expression recompile for each match to save the <emphasis>backreferences</emphasis>.</para> + +<para>Output: + +<computeroutput>void MyClass::DoStringOps( const String &foo, const String &bar String *p, const int &a, const int &b )</computeroutput></para> + +<para>Mission completed! Now, what happened? Well, we looked for some +white space (<literal>\s+</literal>) followed by one or more +alphabetic characters (<literal>\w+</literal>) followed by some more +whitespace (<literal>\s+</literal>) followed by an ampersand, and in +the process saved the alphabetic chunk and the ampersand for reuse in +the replace operation. Then we replaced the matching part of our line +with one whitespace followed by <quote>const</quote> followed by one +whitespace followed by our saved alphabetical chunk +(<literal>\1</literal>) followed by one whitespace followed by our +saved ampersand (<literal>\2</literal>)</para> + +<para>Now in some cases the alphabetical chunk was +<quote>String</quote>, in some <quote>int</quote>, so using the +character class <literal>\w</literal> and the <literal>+</literal> +quantifier proved a valuable asset.</para> + +</example> + +</listitem> + +</varlistentry> + +</variablelist> + +</sect3> + +<sect3 id="advanced-editing-tools-commandline-commands-navigation"> +<title>Commands for navigation</title> + +<variablelist> + +<varlistentry> +<term><cmdsynopsis><command>goto</command><arg>INT line</arg></cmdsynopsis></term> +<listitem><para>This command navigates to the specified line.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>find</command><arg>pattern</arg></cmdsynopsis></term> +<listitem><para>This command navigates to the first occurrence of +<userinput>pattern</userinput> according to the configuration. Following +occurrences can be found using +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice> +(the default shortcut is <keycap>F3</keycap>).</para> +<para>The find command can be configured by appending a colon followed by one or +more options, the form is +<userinput>find:options pattern</userinput>. The +following options are supported: + +<variablelist> + +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>e</userinput></term> +<listitem><para>Search in the selection only.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search. If set, you may use +<userinput>\N</userinput> where N is a number to represent captures in the +replacement string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>w</userinput></term> +<listitem><para>Match whole words only.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +</listitem> + +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>ifind</command><arg>pattern</arg></cmdsynopsis></term> +<listitem><para>This command provides <quote>as-you-type</quote> searching. You +can configure the behavior of the search by appending a colon +followed by one or more options, like this: +<userinput>ifind:options pattern</userinput>. Allowed options are + +<variablelist> +<varlistentry> +<term><userinput>b</userinput></term> +<listitem><para>Search backwards.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>r</userinput></term> +<listitem><para>Do regular expression search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>s</userinput></term> +<listitem><para>Do case sensitive search.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>c</userinput></term> +<listitem><para>Search from cursor position.</para></listitem> +</varlistentry> + +</variablelist> +</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +</sect1> + +<sect1 id="advanced-editing-tools-code-folding"> +<title>Using Code Folding</title> + +<para>Code folding allows you to hide parts of a document in the editor, making +it easier to overview large documents. In &kate; the foldable regions are +calculated using rules defined in the syntax highlight definitions, and +therefore it is only available in some formats - typically program source code, +XML markup and similar. Most highlight definitions supporting code folding +also lets you manually define foldable regions, typically using the +<userinput>BEGIN</userinput> and <userinput>END</userinput> keywords.</para> + +<para>To use the code folding feature, activate the folding markers using +<menuchoice><guimenu>View</guimenu><guimenuitem>Show Folding +Markers</guimenuitem></menuchoice> menu item if they are not already visible. +The Folding Markers Pane in the left side of the screen displays a graphical +view of the foldable regions, with +/- signs to indicate the possible operation +on a given region: a - means that the region is expanded, clicking the - will +collapse the region and a + will be displayed instead.</para> + +<para>Four commands are provided to manipulate the state of folding regions, +see the <link linkend="view-code-folding">menu documentation</link>. +</para> + +<para>If you do not want to use the code folding feature, you can disable +the <guilabel>Show folding markers (if available)</guilabel> option in the +<link linkend="config-dialog-editor-appearance">Appearance page of the editor +configuration</link></para> + +</sect1> + +<sect1 id="advanced-editing-tools-scripting"> + +<title>Scripting the editor component with Javascript</title> + +<sect2 id="advanced-editing-tools-scripting-introduction"> + +<title>Introduction</title> + +<para>Starting with version 2.5, the &kate; editor component supports +scripting with ECMA script, also known as JavaScript.</para> + +<para>Scripts can be used through <link +linkend="advanced-editing-tools-commandline">the built in command line</link> +only. The requirements is that the script is placed in a folder where &kate; +can find it, along with an optional .desktop file that defines the related +properties. The valid folder are named <filename>katepart/scripts</filename> +in the &kde; data folders. You can find the data folders by running the command +<command>kde-config <option>--path</option> <parameter>data</parameter></command> +You will usually have at least a system and a personal data folder. Of course +scripts in the system data folder are available to all users on the system, +while those in the personal folder are available for you only.</para> + +<note><para>This feature is experimental and will most likely change during +future development.</para> +<para>We know that many of you will be disappointed because you can't add +your scripts to the menu or assign shortcuts to them. Sorry, sometime +in the future that will likely be possible.</para> +<para>It is also not possible to pass any arguments to your scripts yet. Be +patient, and that may be added in the bright future ;)</para> +</note> + +</sect2> + +<sect2 id="advanced-editing-tools-scripting-reference"> + +<title>The Kate JavaScript API</title> + +<para>Here is listed the complete set of functions and properties available +in the <type>document</type> and <type>view</type> objects. +In addition you can of course use all the standard objects such as +<type>Math</type>, <type>String</type> <type>Regex</type> and so forth.</para> + +<para>When a script is run, the <classname>document</classname> object is the +current document, and the <classname>view</classname> object is the current +view.</para> + +<note><para>The types of arguments are of course not used in JavaScript at +this time, they are there solely to indicate what sort of value the funcitons +expect.</para></note> + +<variablelist id="advanced-editing-tools-scripting-global"> +<title>Global Functions</title> +<varlistentry> +<term><function>debug( <parameter><replaceable>string</replaceable></parameter>) +[function]</function></term> +<listitem> +<itemizedlist> +<title>parameters</title> +<listitem><para><parameter>string</parameter> the string to output</para> +</listitem> +</itemizedlist> +<para>Outputs the string to <acronym>STDERR</acronym> using +<function>kdDebug()</function>. A dedicated output area is used for the output, +which will be prefixed <computeroutput>Kate (KJS Scripts):</computeroutput> +</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist id="advanced-editing-tools-scripting-document"> +<title>The <classname>document</classname> API</title> + +<varlistentry> +<term><function>document.attribute( <parameter><replaceable>line</replaceable> +</parameter>, <parameter><replaceable>column</replaceable></parameter> ); + [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>uint line</parameter> The line of the position for which +to find the attribute.</para></listitem> +<listitem><para><parameter>uint column</parameter> The column of the position for +which to find the attribute.</para></listitem> +</itemizedlist> +<para>Returns the numeric ID of the attribute for the document position +[<parameter>line</parameter>,<parameter>column</parameter>]. The attribute +represents the visual appearance or style of the text, and is also used to +calculate the syntax highlight for a specific part of the text in mixed formats +like HTML or PHP.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.canBreakAt( <parameter>Char c</parameter>, +<parameter>uint attribute</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>c</parameter> The character to test</para></listitem> +<listitem><para><parameter>attribute</parameter> The attribute at the position +of <parameter>c</parameter>.</para></listitem> +</itemizedlist> +<para>Returns whether it is allowed to break the line at a character c with +attribute attribute. The result is decided by querying the highlight owning +attribute for which characters allow breaking the line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.canComment( <parameter>uint start_attribute</parameter>, +<parameter>uint end_attribute</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>start_attribute</parameter> The attribute at the +start of the range to turn into a comment.</para></listitem> +<listitem><para><parameter>end_attribute</parameter> The attribute at end of +the range to turn into a comment.</para></listitem> +</itemizedlist> +<para>Returns whether start_attribute and end_attribute belongs to the same +syntax highlight system. If they do, it is sane. +</para> +<example> +<title>using canComment</title> +<programlisting> +if ( document.canComment( document.attribute(1,0), document.attribute(5,0) ) ) { + // 1,0 and 5,0 belongs to the same syntax highlighting system +} +</programlisting> +</example> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.clear(); [function]</function></term> +<listitem><para>Clears the document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentStart( <parameter>uint attribute</parameter> ); +[function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attribute</parameter> The attribute of the text for +which to get the commentStart string.</para></listitem> +</itemizedlist> +<para>Returns the string required to start a multiline comment for a text with +attribute, or an empty string if multiline comments are not supported for that +text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentMarker( <parameter>uint attribute</parameter> ); +[function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attribute</parameter> The attribute of the text for +which to get the commentMarker string</para></listitem> +</itemizedlist> +<para>Returns the string used to mark the rest of the line as a comment for a +text with attribute or an empty string if single line comments are not supported +for that text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.commentEnd( <parameter>uint attribute</parameter> ); +[function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>attribute</parameter> The attribute of the text for +which to get the commentEnd string</para></listitem> +</itemizedlist> +<para>Returns the string required to end a multiline comment for a text with +attribute, or an empty string if multiline comments are not supported for that +text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.editBegin(); [function]</function></term> +<listitem> +<para>Start an editing group. All actions done until the call of editEnd() will +be grouped as one undo-action.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.editEnd(); [function]</function></term> +<listitem> +<para>Finish an editing group.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.highlightMode; [property:read only]</function></term> +<listitem> +<para>The name of the document's highlight mode, such as JavaScript or C++. +If no syntax highlight mode is set for the document, the value is None. Notice +that you need to use the English name in cases where it differs from the +translated one.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.indentMode; [property:read only]</function></term> +<listitem> +<para>The name of the document indent mode, such as +<literal>normal</literal> or <literal>cstyle</literal>. +Remember that if no indent mode is set, the value is <literal>none</literal>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.indentWidth; [property:read only]</function></term> +<listitem> +<para>The indentation width set for the document. This is used if space +indenting is enabled.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.insertLine( <parameter>uint line</parameter>, +<parameter>string text</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> document line number</para> +</listitem> +<listitem><para><parameter>text</parameter> text to insert</para></listitem> +</itemizedlist> +<para>Inserts a new line with the text <parameter>text</parameter> at the +line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.insertText( <parameter>uint line</parameter>, +<parameter>uint column</parameter>, <parameter>string text</parameter> ); +[function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line number</para></listitem> +<listitem><para><parameter>column</parameter> the column</para></listitem> +<listitem><para><parameter>text</parameter> the text which is to be +inserted</para></listitem> +</itemizedlist> +<para>Inserts the text <parameter>text</parameter> in line +<parameter>line</parameter> and column <parameter>column</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.length(); [function]</term> +<listitem> +<para>Returns the document's size in bytes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.lines(); [function]</function></term> +<listitem> +<para>Returns the number of lines in the document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.mixedIndent; [property:read only]</term> +<listitem> +<para>A boolean telling whether the mixed-indent setting is enabled for the +document. If so, indentation is optimized to contain a mix of tab characters and +spaces like used by the Emacs editor.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>document.removeLine( <parameter>uint line</parameter> ); [function]</term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> line number</para></listitem> +</itemizedlist> +<para>Removes the document line line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.removeText( <parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning +line</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning +column</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending +line</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending +column</para></listitem> +</itemizedlist> +<para>Removes the text range from line <parameter>startLine</parameter> and +column <parameter>startColumn</parameter> up to line +<parameter>endLine</parameter> and column <parameter>endColumn</parameter>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.setText( <parameter>string text</parameter> ); +[function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>text</parameter> document text</para></listitem> +</itemizedlist> +<para>Sets the entire document content to <parameter>text</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.spaceIndent; [property:read only]</function></term> +<listitem> +<para>A boolean telling whether space-indent is enabled for the document. +If so, the document is indented with indentWidth spaces pr level, otherwise +indentation is one tab character pr. level.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textFull(); [function]</function></term> +<listitem> +<para>Returns the full document text. If the text spans over multiple lines the +linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textLine( uint line ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> the line</para></listitem> +</itemizedlist> +<para>Returns the text of line <parameter>line</parameter>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>document.textRange( <parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning +line</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning +column</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line</para> +</listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending +column</para></listitem> +</itemizedlist> +<para>Returns the specified text range. If the range spans over multiple lines +the linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +</variablelist><!--/ document API --> + +<variablelist id="advanced-editing-tools-scripting-view"> +<title>The <classname>view</classname> API</title> + +<varlistentry> +<term><function>view.clearSelection(); [function]</function></term> +<listitem> +<para>Deselects all text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorColumn(); [function]</function></term> +<listitem> +<para>Returns the current cursor column (TAB characters are expanded).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorColumnReal(); [function]</function></term> +<listitem> +<para>Returns the current real cursor column (TAB characters counts one).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.cursorLine(); [function]</function></term> +<listitem> +<para>Returns the current cursor line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.hasSelection(); [function]</function></term> +<listitem> +<para>Returns <constant>true</constant> if the view contains selected text, +otherwise <constant>false</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.removeSelectedText(); [function]</function></term> +<listitem> +<para>Removes the selected text, if the view has a selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectAll(); [function]</function></term> +<listitem> +<para>Selects all text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selection(); [function]</function></term> +<listitem> +<para>Returns the selected text. If the selection spans over multiple lines the +linefeed character is <constant>\n</constant>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionEndColumn; [property:read only]</function></term> +<listitem> +<para>Returns the ending column of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionEndLine; [property:read only]</function></term> +<listitem> +<para>Returns the ending line of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionStartColumn; [property:read only]</function></term> +<listitem> +<para>Returns the starting column of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.selectionStartLine; [property:read only]</function></term> +<listitem> +<para>Returns the starting line of the selection.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setCursorPosition( <parameter>uint line</parameter>, +<parameter>uint column</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> Specifies the line for the +cursor.</para></listitem> +<listitem><para><parameter>column</parameter> Specifies the column for the +cursor.</para></listitem> +</itemizedlist> +<para>Sets the input cursor position in the view to [<parameter>line</parameter>, +<parameter>col</parameter>]. This sets the cursor position by visual means, +that is the a TAB character counts up to <replaceable>tabwidth</replaceable> +depending on the position inside the line. The cursor position is made visible. +Both line and column are zero-based.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setCursorPositionReal( <parameter>uint line</parameter>, +<parameter>uint column</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>line</parameter> Specifies the line for the +cursor.</para></listitem> +<listitem><para><parameter>column</parameter> Specifies the column for the +cursor.</para></listitem> +</itemizedlist> +<para>Sets the input cursor position to [<parameter>line</parameter>, +<parameter>col</parameter>]. This sets the string position, that is a TAB +character counts for 1. The cursor position is made visible. Both line and +column are zero-based.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><function>view.setSelection( <parameter>uint startLine</parameter>, +<parameter>uint startColumn</parameter>, <parameter>uint endLine</parameter>, +<parameter>uint endColumn</parameter> ); [function]</function></term> +<listitem> +<itemizedlist> +<title>Parameters</title> +<listitem><para><parameter>startLine</parameter> specifies the beginning line</para></listitem> +<listitem><para><parameter>startColumn</parameter> specifies the beginning column</para></listitem> +<listitem><para><parameter>endLine</parameter> specifies the ending line</para></listitem> +<listitem><para><parameter>endColumn</parameter> specifies the ending column</para></listitem> +</itemizedlist> +<para>Sets a selection from line <parameter>startLine</parameter> and column +<parameter>startColumn</parameter> up to line <parameter>endLine</parameter> +and column <parameter>endColumn</parameter>.</para> +</listitem> +</varlistentry> + +</variablelist> + +<example id="advanced-editing-tools-scripting-example"> + +<title>A sample script</title> +<para>As an example we will create a small script that uppercases the selection. +It is obvious that we first need to check whether a selection exists, if so we +get the text, change the case and then replace it with the new one. An +implementation could look like this:</para> + +<programlisting> +if ( view.hasSelection() ) +{ + // uppercase selection + column = view.selectionStartColumn; + line = view.selectionStartLine; + + selection = view.selection().toUpperCase(); + + document.editBegin(); + view.removeSelectedText(); + document.insertText( line, column, selection ); + document.editEnd(); +} +</programlisting> + +<para>To group this action together so that they will be reverted by a single +activation of <guimenuitem>Undo</guimenuitem> we encapsulate the lines +<programlisting>view.removeSelectedText()</programlisting> and +<programlisting>document.insertText()</programlisting> with a +<programlisting>document.editBegin()</programlisting> and +<programlisting>document.editEnd()</programlisting>.</para> + +</example> + +<example id="advanced-editing-tools-desktop-example"> +<title>A sample <filename>.desktop</filename> file</title> + +<para>Here is a sample .desktop file that accompanies the above script.</para> + +<programlisting> +# Example of a .desktop file +[Desktop Entry] +Encoding=UTF-8 +Name=Kate Part JavaScript Uppercase +Comment=Script to uppercase the selection +X-Kate-Command=uppercase-selection +X-Kate-Help=<p>Usage: <code>uppercase-selection</code></p> +</programlisting> + +<para>As you can see you can define the Encoding, set a Name, a Comment, a help +text using X-Kate-Help and the command line name via X-Kate-Command. The entries +Name, Comment and X-Kate-Help are automatically translated into other languages +by the KDE translation teams, if the files are in KDE's SVN repository.</para> + +</example> + +<sect3> +<title>Putting it togeather</title> + +<para>&kate; will search the script folders (see <link +linkend="advanced-editing-tools-scripting-introduction">above</link>) for +<filename>*.js</filename> files. For every file it checks whether there is a +corresponding <filename>.desktop</filename> file, like for uppercase.js it +would look for uppercase.desktop. </para> +<para>If a <filename>.desktop</filename> file can not be found the script will +be registered in katepart's command line with the filename without the ending +.js, so in our example this would be <literal>uppercase</literal>. If the +command-name is fine and you don't need the extra features a +<filename>.desktop</filename> file provides you do not need a +<filename>.desktop</filename> file at all. </para> +<para>If a <filename>.desktop</filename> file exists katepart will read the name +under which the script will be registered from the .desktop-entry +X-Kate-Command, for example X-Kate-Command=uppercase-selection.</para> + +</sect3> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kate/configdialog01.png b/doc/kate/configdialog01.png Binary files differnew file mode 100644 index 000000000..751066792 --- /dev/null +++ b/doc/kate/configdialog01.png diff --git a/doc/kate/configdialog02.png b/doc/kate/configdialog02.png Binary files differnew file mode 100644 index 000000000..70a7ecaed --- /dev/null +++ b/doc/kate/configdialog02.png diff --git a/doc/kate/configuring.docbook b/doc/kate/configuring.docbook new file mode 100644 index 000000000..14642c74c --- /dev/null +++ b/doc/kate/configuring.docbook @@ -0,0 +1,1595 @@ +<chapter id="configuring-kate"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Configuring &kate;</title> + +<sect1 id="configuring-overview"> +<title>Overview</title> +<para> +<indexterm> +<primary>configure</primary> +<secondary>settings</secondary> +<tertiary>preferences</tertiary></indexterm> +<anchor id="find"/> +<anchor id="find-again"/> +<!-- <anchor id="print"/> --> +<anchor id="replace"/> +<!-- <anchor id="save"/> --> +<anchor id="undo"/> +<anchor id="redo"/> +&kate; offers several means of tweaking the application to behave as desired. +The most important ones are: +</para> + +<variablelist> +<varlistentry> +<term id="configure">The Configuration Dialog</term> +<listitem><para>The main configuration tool, allowing you to configure the &kate; application, +the editor component and the usage of plugins.</para></listitem> +</varlistentry> +<varlistentry> +<term id="settings">The <guimenu>Settings</guimenu> Menu</term> +<listitem><para>Allows you to change often used settings, and to +launch the configuration dialogs.</para></listitem> +</varlistentry> +<varlistentry> +<term>The <guimenu>View</guimenu> Menu</term> +<listitem><para>Allows you to split the current frame, as well as to +display the icons and line numbers pane for the currently edited +document.</para></listitem> +</varlistentry> +</variablelist> + +<para>The embedded &konsole; is using the configuration defined in the +&kcontrolcenter;, and may be configured by clicking the +<mousebutton>right</mousebutton> mouse button and choosing from the +<guimenuitem>Settings</guimenuitem> sub menu.</para> + +</sect1> + +<sect1 id="configuring-kate-configdialog"> +<title>The Main Configuration Dialog</title> + +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="configdialog01.png"/> +</imageobject> +</mediaobject> + +<para>The &kate; configuration dialog displays a tree of topics on the +left, and a configuration page corresponding to the selected topic on +the right.</para> + +<para>The configuration is divided into two groups, namely +<itemizedlist> +<listitem><para><link linkend="config-dialog">Application configuration</link> +</para></listitem> +<listitem><para><link linkend="config-dialog-editor">Editor component configuration</link></para></listitem> + +</itemizedlist> + +</para> + +</sect1> + +<sect1 id="config-dialog"> +<title>The &kate; Application Configuration</title> +<para>This group contains pages to configure the main &kate; application</para> + +<sect2 id="config-dialog-general"> +<title>The General Page</title> +<para>This section contains a few global options for &kate;</para> + +<variablelist> + +<varlistentry> +<term><anchor id="config-dialog-general-show-full-path" /> +<guilabel>Show Full Path in Title</guilabel></term> +<listitem><para>When enabled, Kate will display the full URL of your +current document in the window title, rather than just the file name.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="config-general-behavior"/> +<guilabel>Behavior</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term> +<anchor id="config-dialog-general-sync-konsole"/> +<guibutton>Sync Konsole with Active Document</guibutton></term> +<listitem><para>This will cause the built-in &konsole; to +<command>cd</command> into the directory of the active document when +launched and when a new document gets the focus. If not enabled, you +have to do all your navigation in the &konsole; on your own. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="config-dialog-general-warn-mod"/> +<guilabel>Warn about files modified by foreign processes</guilabel></term> +<listitem><para>When enabled, &kate; will notify you about files modified +from outside the application whenever the main window receives input focus. +You will be able to deal with several modified files at once, you +can reload, save or discard changed files in groups.</para> +<para>If not enabled, &kate; will prompt you for action when a externally +modified file receives focus within the application.</para> +</listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry><!-- /behavior group --> + +<varlistentry> +<term><anchor id="config-general-meta-data"/> +<guilabel>Meta Data</guilabel></term> +<listitem> + +<variablelist> +<varlistentry> +<term><anchor id="config-general-keep-meta-information"/> +<guilabel>Keep meta-information past sessions</guilabel></term> +<listitem><para>When enabled, &kate; will store meta data such as bookmarks +and session configuration even when you close your documents. The data +will be used if the document is unchanged when reopened.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="config-general-delete-meta-information-after"/> +<guilabel>Delete unused meta information after</guilabel></term> +<listitem><para>Set the maximum number of days to keep meta information +for unopen files. This helps keeping the database of meta information +reasonably sized.</para></listitem> +</varlistentry> + +</variablelist> + +</listitem> +</varlistentry><!-- /meta data group --> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-sessions"> +<title>The Sessions Page</title> + +<para>This section contains options related to <link +linkend="fundamentals-using-sessions">using sessions</link>.</para> + +<variablelist> + +<varlistentry> +<term><anchor id="config-dialog-sessions-elements"/> +<guilabel>Elements of Sessions</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Include window configuration</guilabel></term> +<listitem><para>If enabled, &kate; will save the window configuration +with each session.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry><!-- /elements of sessions --> + +<varlistentry> +<term><anchor id="config-dialog-sessions-startup-behavior"/> +<guilabel>Behavior on Application Startup</guilabel></term> +<listitem> +<para>Select how you want &kate; to behave at startup. This setting can be +overridden by specifying what to do on the <link +linkend="command-line-options">command line</link>.</para> +<variablelist> +<varlistentry> +<term><guilabel>Start new session</guilabel></term> +<listitem><para>With this option, &kate; will start a new, unnamed session +when you start it.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Load last used session</guilabel></term> +<listitem><para>&kate; will use the most recently opened session at +startup. This is good if you want to use the same session always or switch +rarely.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Manually choose a session</guilabel></term> +<listitem><para>&kate; will display a small dialog that lets you choose +your preferred session. This is the default behavior. Nice if you use a lot of +different sessions frequently.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry><!-- /startup behavior --> + +<varlistentry> +<term><anchor id="config-dialog-sessions-exit-behavior"/> +<guilabel>Behavior on Application Exit or Session Switch</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Do not save session</guilabel></term> +<listitem><para>The changes to the session data (open files and if enabled, +window configuration) will not be saved. You will of course be prompted if you +have unsaved files. With this option, your can configure your sessions once, and +not worry about closing extra files that you opened and do not want to see +next time you use the session.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Save Session</guilabel></term> +<listitem><para>&kate; will save session data, except if the session is unnamed. +With this option, your sessions are allways restored just like you left them. +This is the default behavior. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Ask user</guilabel></term> +<listitem><para>You will be asked if you want to save the session every time a +named session is closed.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry><!-- /exit/switch behavior --> + +</variablelist> + +</sect2> + +<sect2 id="config-dialog-fileselector"> +<title>The <guilabel>Filesystem Browser</guilabel> Page</title> + +<variablelist> +<varlistentry> +<term><guilabel>Toolbar</guilabel></term> +<listitem><para>Configure the buttons on the file system browser toolbar +by moving the ones you want enabled to the <guilabel>Selected Actions</guilabel> +list, and order them using the arrow buttons at the side of the list.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Auto Synchronization</guilabel></term> +<listitem><para>You can have the filesystem browser automatically navigate to +the directory containing the current document on certain events: +<itemizedlist> +<listitem><para>When a new document becomes the active one.</para></listitem> +<listitem><para>When the filesystem browser becomes visible.</para></listitem> +</itemizedlist> +Even if you select not to use this feature, you can manually synchronize the +browser with the current document by pressing the +<guilabel>Synchronize</guilabel> toolbar button. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remember locations</guilabel></term> +<listitem><para>Select how long a browsing history you want. The browser does +only remember individual locations, duplicates are removed.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remember filters</guilabel></term> +<listitem><para>Select how many filters you want remembered. Only individually +distinct filters are remembered, duplicates are removed.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Session</guilabel></term> +<listitem> +<para>Configure wether the file system browser should remember its location and +filter over sessions.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="config-dialog-documentlist"> +<title>The <guilabel>Doucment List</guilabel> Page</title> + +<variablelist> +<varlistentry> +<term><guilabel>Backgound Shading</guilabel></term> +<listitem><para>This section allows you to enable or disable the background +shading visualization of your recent activity, and chose which colors to use if +enabled. See the section about <link +linkend="kate-mdi-tools-file-list">The Document List</link> for more about +this feature.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Sort By</guilabel></term> +<listitem><para>Set how you want the document list sorted. This can be set +from the &RMB; menu in the document list as well.</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="config-dialog-plugins"> +<title>The <guilabel>Plugins</guilabel> Page</title> + +<para>This page provides a list of installed plugins for the &kate; +application. Each plug-in is represented with its name and a short description. +You can check the checkbox with an item to enable the plug-in it represents. +</para> + +<para>If a plug-in provides configuration options, a section to access those +will appear as a child of this page.</para> + +</sect2> + + +<sect2 id="config-dialog-externaltools"> +<title>External Tools</title> + +<para>In the <guimenu>Tools</guimenu> menu you will find a submenu labeled +<guisubmenu>External Tools</guisubmenu>. These tools invokes external +applications with data related to the current document, for example its URL, +directory, text or selection. This page allows you to manage the menu and edit, +remove or add new tools.</para> + +<para>Each external tool is a shell command which contains macros representing +the document data. When activated, the macros are substituted with data from the +active document.</para> + +<variablelist> +<title>External Tools Properties</title> +<varlistentry> +<term>Label</term> +<listitem><para>A friendly label for the External Tools menu.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Script</term> +<listitem><para>The script to execute when the tool is activated. Before passing +the script to the shell, the following macros are substituted: + +<variablelist> +<varlistentry> +<term>%URL</term> +<listitem><para>The full URL of the current document, or an empty string if the +document is unsaved.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%URLS</term> +<listitem><para>A space seperated list of the URLs of all open documents +(except unsaved ones).</para></listitem> +</varlistentry> + +<varlistentry> +<term>%directory</term> +<listitem><para>The directory part of the current documents URL or an empty +string if the current document is unsaved.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%filename</term> +<listitem><para>the filename of the current document without the path, or an +empty string if the current document is unsaved.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%line</term> +<listitem><para>The line number of the insertion cursor is in the current +document.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%column</term> +<listitem><para>The column number of the insertion cursor in the current +document.</para></listitem> +</varlistentry> + +<varlistentry> +<term>%selection</term> +<listitem><para>The selected text in the current document, or an empty string +if no text is selected</para></listitem> +</varlistentry> + +<varlistentry> +<term>%text</term> +<listitem><para>The full text of the current document. Beware that this will +potentially exceed the maximum command length allowed on your system. +Use with care.</para></listitem> +</varlistentry> + +</variablelist> + +</para></listitem> +</varlistentry> + +<varlistentry> +<term>Executable</term> +<listitem><para>The main executable is the script. This is mandatory, and is used +to test if the command can be run at all. A fully qualified path is allowed +in case the executable is not in your <envar>PATH</envar> variable.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Mimetypes</term> +<listitem><para>A semicolon separated list of mimetypes for which this command +should be enabled. This is currently unused.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Save</term> +<listitem><para>You can optionally select to have the current or all documents +saved prior to executing the script. This is handy if your script reads the file +from disk.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Command Line Name</term> +<listitem><para>If you fill this, the tool will be available in the +<link linkend="advanced-editing-tools-commandline">editors command line</link> as +<command>exttool-<replaceable>Command Line Name</replaceable></command> +(the string you enter here prepended <quote>exttool-</quote>).</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="config-dialog-editor"> +<title>The Editor Component Configuration</title> +<para>This group contains all pages related to the editor component of +&kate;. Most of the settings here are defaults, they can be overridden by +<link linkend="config-dialog-editor-filetypes">defining a filetype</link>, +by <link linkend="config-variables">Document Variables</link> or by changing +them pr. document during an editing session.</para> + + +<sect2 id="config-dialog-editor-appearance"> +<title>Appearance</title> + +<variablelist> +<varlistentry> +<term><guilabel>Word Wrap</guilabel></term> +<listitem> +<variablelist> +<varlistentry id="appearance-settings"> +<term><guilabel>Dynamic word wrap</guilabel></term> +<listitem><para>If this option is checked, the text lines +will be wrapped at the view border on the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Dynamic word wrap indicators</guilabel></term> +<listitem><para>Choose when the Dynamic word wrap indicators +should be displayed. +</para></listitem></varlistentry> +<varlistentry> +<term><guilabel>Vertically align dynamically wrapped lines +to indentation depth: +</guilabel></term> +<listitem><para>Enables the start of dynamically wrapped +lines to be aligned vertically to the indentation level of the first +line. This can help to make code and markup more +readable.</para><para>Additionally, this allows you to +set a maximum width of the screen, as a percentage, +after which dynamically wrapped lines will no longer be vertically aligned. +For example, at 50%, lines whose indentation levels are deeper than 50% of the +width of the screen will not have vertical alignment applied to subsequent +wrapped lines.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Code Folding</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Show folding markers (if available) +</guilabel></term> +<listitem><para>If this option is checked, the current view will display marks +for code folding, if code folding is available.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Borders</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Show icon border +</guilabel></term> +<listitem><para>If this is checked, you will see an icon border on the left +hand side. The icon border shows bookmark signs for instance.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show line numbers +</guilabel></term> +<listitem><para>If this is checked, you will see line numbers on the left +hand side.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show scrollbar marks +</guilabel></term> +<listitem><para>If this option is checked the current view +will show marks on the vertical scrollbar. These marks will +for instance show bookmarks.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Sort Bookmarks Menu +</guilabel></term> +<listitem><para> +<variablelist> +<varlistentry> +<term><guilabel>By position +</guilabel></term> +<listitem><para>The bookmarks will be ordered by the line +numbers they are placed at.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>By creation +</guilabel></term> +<listitem><para>Each new bookmark will be added to the bottom, +independently from where it is placed in the document.</para></listitem> +</varlistentry> +</variablelist> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show identation lines +</guilabel></term> +<listitem><para>If this is checked, the editor wil display +vertical lines to help identifying indent lines.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-colors"> +<title>Fonts & Colors</title> + +<para>This section of the dialog lets you configure all fonts and colors in +any color scheme you have, as well creating new schemes or deleting existing +ones. Each scheme has settings for colors, fonts and normal and highlight text +styles. +</para> + +<para>&kate; will preselect the currently active scheme for you, if you want to +work on a different scheme start by selecting that from the +<guilabel>Schema</guilabel> combobox.</para> + +<sect3 id="config-dialog-editor-colors-colors"> +<title>Colors</title> + +<variablelist> +<varlistentry id="config-dialog-editor-colors-colors-text-background"> +<term><guilabel>Text Area Background</guilabel></term> +<listitem> + +<variablelist> + +<varlistentry id="config-dialog-editor-colors-normal-text"> +<term><guilabel>Normal text</guilabel></term> +<listitem><para>This is the default background for the editor area, it will be +the dominant color on the editor area.</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-selected-text"> +<term><guilabel>Selected Text</guilabel></term> +<listitem><para>This is the background for selected text. The default is +the global selection color, as set in your &kde; color preferences. +</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-current-line"> +<term><guilabel>Current Line</guilabel></term> +<listitem><para>Set the color for the current line. Setting this a bit different +from the Normal text background helps to keep focus on the current line. +</para></listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-marks"> +<term><guilabel>Bookmark</guilabel></term> +<listitem><para>This combo lets you set overlay colors for various mark types. +The color is mixed into the background color of a marked line, so that a line +with more marks or a marked line that is current has a background that is a mix +of more colors. The mark colors are also used if you enable display of scrollbar +marks.</para></listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +<varlistentry id="config-dialog-editor-colors-colors-other-elements"> +<term><guilabel>Other Elements</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Left Border Background</guilabel></term> +<listitem><para>This color is used for the marks, line numbers and folding +marker borders in the left side of the editor view when they are displayed. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Line Numbers</guilabel></term> +<listitem><para>This color is used to draw the line numbers on the left side of +the view when displayed.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Bracket Highlight</guilabel></term> +<listitem><para>This color is used to draw the background of matching brackets. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Word Wrap Markers</guilabel></term> +<listitem><para>This color is used to draw a pattern to the left of dynamically +wrapped lines when those are aligned vertically, as well as for the static word +wrap marker.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Tab Markers</guilabel></term> +<listitem><para>This color is used to draw white space indicators when enabled. +</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect3> + +<sect3 id="config-dialog-editor-colors-fonts"> +<title>Fonts</title> +<para> +Here you can choose the font for the schema. You can choose from +any font available on your system, and set a default size. A sample text +displays at the bottom of the dialog, so you can see the effect of your choices. +</para> +</sect3> + +<sect3 id="config-dialog-editor-colors-normal-text-styles"> +<title>Normal Text Styles</title> +<para>The normal text styles are inherited by the highlight text styles, +allowing the editor to present text in a very consistent way, for example comment +text is using the same style in allmost all of the text formats that kate can +highlight.</para> +<para>The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. +</para> +<para>Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu.</para> +</sect3> + +<sect3 id="config-dialog-editor-colors-highlighting-text-styles"> +<title>Highlighting Text Styles</title> +<para>Here you can edit the text styles used by a specific highlight definition. +The editor preselects the highlight used by your current document. To work on a +different highlight, select one in the <guilabel>Highlight</guilabel> combobox +above the style list. +</para> +<para>The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. +</para> +<para>Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu. In addition you can see if a style is equal to the default style +used for the item, and set it to that if not.</para> +<para>You will notice that many highlights contain other highlights represented +by groups in the style list. For example most highlights import the Alert +highlight, and many source code formats imports the Doxygen highlight. Editing +colors in those groups only affects the styles when used in the edited highlight +format. +</para> +</sect3> + +</sect2> + +<sect2 id="config-dialog-editor-cursor-selection"> +<title>Cursor & Selection</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Text Cursor Movement</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Smart home</guilabel></term> +<listitem> +<para>When selected, pressing the home key will cause the cursor to +skip white space and go to the start of a line's text.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Wrap cursor</guilabel></term> +<listitem> +<para>When on, moving the insertion cursor using the <emphasis +role="bold">Left</emphasis> and <emphasis role="bold">Right</emphasis> keys will +go on to previous/next line at beginning/end of the line, similar to most +editors.</para><para>When off, the insertion cursor cannot be moved left of the +line start, but it can be moved off the line end, which can be very handy for +programmers. When this option is chosen, moving the cursor with the arrow keys +off the end of a line (to the right) causes it to jump down to the beginning of +the next line. Likewise when the cursor is moved past the beginning of a line +(to the left) it jumps up to the end of the preceding line. When this option is +not selected, moving the cursor right past the end of a line merely causes it to +continue horizontally in the same line and trying to move it left past the +beginning does nothing.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Page Up/Page Down moves cursor</guilabel></term> +<listitem> +<para>This option changes the behavior of the cursor when the user presses +the <keycap>Page Up</keycap> or <keycap>Page Down</keycap> key. If unselected +the text cursor will maintain its relative position within the visible text in +&kate; as new text becomes visible as a result of the operation. So if the +cursor is in the middle of the visible text when the operation occurs it will +remain there (except when one reaches the beginning or end.) With this option +selected, the first key press will cause the cursor to move to either the top or +bottom of the visible text as a new page of text is displayed.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Autocenter cursor (lines):</guilabel></term> +<listitem> +<para>Sets the number of lines to maintain visible above and below the cursor +when possible.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Selection Mode</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Normal</guilabel></term> +<listitem> +<para>Selections will be overwritten by typed text and will be lost on +cursor movement.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Persistent</guilabel></term> +<listitem> +<para>Selections will stay even after cursor movement and typing.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-edit"> +<title>Editing</title> +<variablelist> + +<varlistentry> +<term><guilabel>Tabulators</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Insert spaces instead of tabulators</guilabel></term> +<listitem> +<para>When this is enabled the editor will insert a calculated number of spaces +according to the position in the text and the <option>tab-width</option> setting +when you press the <keycap>TAB</keycap> key.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show tabulators</guilabel></term> +<listitem> +<para>When this is enabled &kate; will display a small dot as a visual +representation of tabulator characters.</para> +<note><para>This also causes dots to be drawn to indicate trailing white space. +This will be fixed in a future version of &kate;</para></note> +</listitem> +</varlistentry> +<varlistentry> +<term id="config-dialog-editor-tab-width">Tab Width</term> <listitem><para>If the +<link linkend="config-dialog-editor-word-wrap"><guilabel>Replace Tabs By +Spaces</guilabel></link> +option is selected this entry determines the number of +spaces with which the editor will automatically replace +tabs.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="config-dialog-editor-word-wrap"><guilabel>Static Word Wrap</guilabel></term> +<listitem><para> +Word wrap is a feature that causes the editor to automatically start a new line +of text and move (wrap) the cursor to the beginning of that new line. &kate; +will automatically start a new line of text when the current line reaches the +length specified by the <link linkend="config-dialog-editor-wrap-words-at">Wrap Words +At:</link> option.</para> +<variablelist> +<varlistentry> +<term><guilabel>Enable static word wrap</guilabel></term> +<listitem> +<para>Turns static word wrap on or off.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show static word wrap markers +(if applicable)</guilabel></term> +<listitem> +<para>If this option is checked, a vertical line will be drawn at the word wrap +column as defined in the <menuchoice> <guimenu>Settings</guimenu> +<guimenuitem>Configure Editor...</guimenuitem></menuchoice> in the Editing tab. +Please note that the word wrap marker is only drawn if you use a fixed pitch +font.</para> +</listitem> +</varlistentry> +<varlistentry id="config-dialog-editor-wrap-words-at"> +<term><guilabel>Wrap words at:</guilabel></term> +<listitem> +<para>If the <link linkend="config-dialog-editor-word-wrap">Word Wrap</link> option is selected +this entry determines the length (in characters) at which the editor will +automatically start a new line.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remove Trailing Spaces</guilabel></term> +<listitem><para>&kate; will automatically eliminate extra spaces +at the ends of lines of text.</para></listitem> </varlistentry> + +<varlistentry> +<term><guilabel>Auto Brackets</guilabel></term> <listitem><para>When +the user types a left bracket ([, (, or {) &kate; automatically enters the +right bracket (}, ), or ]) to the right of the cursor.</para></listitem> +</varlistentry> + +<varlistentry> <term>Maximum <link linkend="undo">undo</link> steps:</term> +<listitem><para>Here the user may specify the number of steps &kate; will +retain in memory for purposes of undoing entries and actions. This means that +the higher the number of steps set the more memory &kate; will use for this. +Setting this entry to 10 would mean that the user would be be able reverse the +last ten operations, <abbrev>i.e.</abbrev> click the <guibutton>undo</guibutton> +button 10 times and obtain results.</para></listitem> </varlistentry> + +<varlistentry> <term>Smart search text from:</term> +<listitem><para>This determines where &kate; will get the search +text from (this will be automatically entered into the Find Text +dialog): +<itemizedlist> +<listitem><para><emphasis role="bold">Nowhere:</emphasis> Don't guess the search +text.</para></listitem> +<listitem><para><emphasis role="bold">Selection Only:</emphasis> Use + the current text selection, if available. </para></listitem> +<listitem><para><emphasis role="bold">Selection, then Current Word:</emphasis> +Use the current selection if available, otherwise use the current word. +</para></listitem> +<listitem><para><emphasis role="bold">Current Word +Only:</emphasis> Use the word that the cursor is currently resting on, if +available. </para></listitem> +<listitem><para><emphasis role="bold">Current Word, then Selection:</emphasis> +Use the current word if available, otherwise use the current selection. +</para></listitem> +</itemizedlist> +Note that, in all the above modes, if a +search string has not been or cannot be determined, then the Find Text Dialog +will fall back to the last search text. +</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-indent"> +<title>Indentation</title> +<variablelist> +<varlistentry> +<term><guilabel>Automatic indentation</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Indentation mode:</guilabel></term> +<listitem> +<para>Select the automatic indentation mode you want to use as default. It is +strongly recommended to use <userinput>None</userinput> or +<userinput>Normal</userinput>here, and use filetype configurations to set other +indentation modes for text formats like C/C++ code or &XML;.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Insert leading Doxygen "*" when typing</guilabel></term> +<listitem> +<para>Automatically insert a leading "*" while typing within a doxygen +style comment. This setting is only enabled when applicable.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Indentation with Spaces</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Use spaces instead of tabs to indent</guilabel></term> +<listitem> +<para>This replaces tabs with the number of spaces set in <guilabel>Number of +spaces:</guilabel> below.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Emacs style mixed mode</guilabel></term> +<listitem> +<para>Use a mix of tabs and space characters for indentation.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Number of spaces:</guilabel></term> +<listitem> +<para>Set the number of spaces you want to use for indentation when you +check <guilabel>Use spaces instead of tabs to indent</guilabel> +above.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep Indent Profile</guilabel></term> +<listitem><para>When this is enabled, the editor will not unindent lines in a +selection further when the line with the least indentation becomes unindented. +If you sometimes unindent blocks of indented code, this may be helpful. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep Extra Spaces</guilabel></term> +<listitem><para>Indentations of more than the selected number of spaces +will not be shortened.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keys to use</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Tab key indents</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>tab</keycap></keycombo> key to be used to indent.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Backspace key indent</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>backspace</keycap></keycombo> key to be used to +indent.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Tab Key Mode if Nothing Selected</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Insert indent characters</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key insert indent +characters.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Insert tab character</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key insert a tab.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Indent current line</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key indent the current +line.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-open-save"> +<title>Open & Save</title> + +<variablelist> + +<varlistentry> +<term><guilabel>File Format</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Encoding:</guilabel></term> +<listitem> +<para>This sets the default character encoding for your files.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>End of line:</guilabel></term> +<listitem> +<para>Choose your prefered end of line mode for your active +document. You have the choice between &UNIX;, DOS/&Windows; or Macintosh.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Automatic end of line detection</guilabel></term> +<listitem> +<para>Check this if you want the editor to autodetect the end of line +type. The first found end of line type will be used for the whole file.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Memory Usage</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Maximum loaded blocks per file:</guilabel></term> +<listitem> +<para>The editor will load given number of blocks (of around 2048 lines) of +text into memory; if the filesize is bigger than this the other blocks +are swapped to disk and loaded transparently as-needed.</para> +<para>This can cause little delays while navigating in the document; a +larger block count increases the editing speed at the cost of memory. +</para><para>For normal usage, just choose the highest possible block count: +limit it only if you have problems with the memory usage.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Automatic Cleanups on Load/Save</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Remove trailing spaces</guilabel></term> +<listitem> +<para>The editor will automatically eliminate extra spaces at the ends of lines +of text while loading/saving the file.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Folder Config File</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Search depth for config file:</guilabel></term> +<listitem> +<para>The editor will search the given number of folder levels upwards +for &kate; config file and load the settings line from it.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Backup on Save</guilabel></term> +<listitem><para>Backing up on save will cause &kate; to copy the disk file to +<prefix><filename><suffix>' before saving changes. +The suffix defaults to <emphasis role="bold">~</emphasis> and prefix is empty by +default. </para> +<variablelist> +<varlistentry> +<term><guilabel>Local files</guilabel></term> +<listitem> +<para>Check this if you want backups of local files when +saving.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Remote files</guilabel></term> +<listitem> +<para>Check this if you want backups of remote files when saving.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Prefix</guilabel></term> +<listitem> +<para>Enter the prefix to prepend to the backup file names.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Suffix</guilabel></term> +<listitem> +<para>Enter the suffix to add to the backup file names.</para> +</listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-highlighting"> +<title>Highlighting</title> +<para>This group of options is used to customize the highlighting styles for +each programming language type. Any changes you made in other areas of this +dialog apply only to this type.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Highlight:</guilabel></term> +<listitem><para>This is used to choose the language type to +configure.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Informations</guilabel></term> +<listitem> +<para> +View the properties of the chosen language highlighting rules: +author name and license. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Properties</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>File extensions:</guilabel></term> +<listitem><para>This is the list of file extensions used to determine which +files to highlight using the current syntax highlight mode.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>MIME types:</guilabel></term> +<listitem><para>Clicking the wizard button will display a dialog with a list of +all available mime types to choose from.</para><para>The <emphasis +role="bold">File Extensions</emphasis> entry will automatically be edited as +well.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Priority:</guilabel></term> +<listitem><para>Set the priority of the highlight rule.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Download...</guibutton></term> +<listitem> +<para> +Click this button to download new or updated syntax highlight descriptions +from the &kate; website. +</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-filetypes"> +<title>Filetypes</title> +<para>This page allows you to override the default configuration for documents +of specified mimetypes. When the editor loads a document, it will try if it +matches the file masks or mimetypes for one of the defined filetypes, and if so +apply the variables defined. If more filetypes match, the one with the highest +priority will be used. +</para> +<variablelist> +<varlistentry> +<term><guilabel>Filetype:</guilabel></term> +<listitem><para>The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are +also listed.</para> +<variablelist> +<varlistentry> +<term><guilabel>New</guilabel></term> +<listitem><para>This is used to create a new filetype. After +you click on this button, the fields below get empty and you +can fill the properties you want for the new filetype.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Delete</guilabel></term> +<listitem><para>To remove an existing filetype, select it from the drop down +box and press the Delete button.</para></listitem> +</varlistentry> +</variablelist> +</listitem> </varlistentry> + +<varlistentry> +<term><guilabel>Properties of current filetype</guilabel></term> +<listitem><para>The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are also +listed.</para> +<variablelist> +<varlistentry> +<term><guilabel>Name:</guilabel></term> +<listitem><para>The name of the filetype will be the text of the corresponding +menu item. This name is displayed in the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem> +</menuchoice ></para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Section:</guilabel></term> +<listitem><para>The section name is used to organize the file types in +menus. This is also used in the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem> +</menuchoice> menu.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Variables:</guilabel></term> +<listitem><para>This string allows you to configure &kate;'s settings for the +files selected by this mimetype using &kate; variables. You can set almost any +configuration option, such as highlight, indent-mode, encoding, +etc.</para><para>For a full list of known variables, see the +manual.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>File extensions:</guilabel></term> +<listitem><para>The wildcards mask allows you to select files by filename. A +typical mask uses an asterisk and the file extension, for example +<filename>*.txt; *.text</filename>. The string is a semicolon-separated list of +masks.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>MIME types:</guilabel></term> +<listitem><para>Displays a wizard that helps you easily select +mimetypes.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Priority:</guilabel></term> +<listitem><para>Sets a priority for this file type. If more than one file type +selects the same file, the one with the highest priority will be +used.</para></listitem> +</varlistentry> +</variablelist> +</listitem> </varlistentry> + +</variablelist> +</sect2> + +<sect2 id="config-dialog-editor-shortcuts"> +<title>Shortcuts</title> +<para>You can change here the shortcut keys configuration. Select an +action and click on <guilabel>Custom</guilabel> if you want a different shortcut +for this action.</para> +<para>The search line alllows you to look for a specific action and see +its associated shortcut.</para> +</sect2> + +<sect2 id="config-dialog-editor-plugins"> +<title>Plugins</title> +<para>This tab lists all available plugins and you can check those you +want to use. Once a plugin is checked, the +<guibutton>Configure</guibutton> button is enabled and you can click it +in order to configure the highlighted plugin.</para> +</sect2> + +</sect1> + + + +<sect1 id="config-variables"> + +<title>Configuring With Document Variables</title> + +<para>Kate variables is kateparts implementation of document variables, similar +to emacs and vi modelines. In katepart, the lines have the format + +<userinput>kate: VARIABLENAME VALUE; [ VARIABLENAME VALUE; ... ]</userinput> + +the lines can of course be in a comment, if the file is in a format with comments. +Variable names are single words (no whitespace), and anything up to the next +semicolon is the value. The semicolon is required.</para> + +<para>Here is an example variable line, forcing indentation settings for a C++, +java or javascript file: + +<programlisting>// kate: space-indent on; indent-width 4; mixedindent off; indent-mode cstyle;</programlisting> +</para> + +<note><para>Only the first and last 10 lines are searched for variable lines.</para></note> + +<para>There are variables to support almost all configurations in katepart, and +aditionally plugins can use variables, in which case it should be documented in +the plugin's documentation.</para> + +<sect2 id="config-variables-howto"> +<title>How kate uses variables</title> + +<para>When reading configuration, katepart looks in the following places +(in that order): + +<itemizedlist> +<listitem><para>The global configuration.</para></listitem> +<listitem><para>Optional session data.</para></listitem> +<listitem><para>The "Filetype" configuration.</para></listitem> +<listitem><para>Document variables in the document itself.</para></listitem> +<listitem><para>Settings made during editing from menu or command line.</para></listitem> +</itemizedlist> + +As you can understand document variables has the next highest precedence. +Whenever a document is saved, the document variables are reread, and will +overwrite changes made using menu items or the command line.</para> + +<para>Any variable not listed below is stored in the document and can be queried +by other objects such as plugins, which can use them for their own purpose. +For example the variable indent mode uses document variables for its +configuration.</para> + +<para>The variables listed here documents &kate; version 2.4. More variables +may be added in the future. There are 3 possible types of values for variables, +with the following valid expressions: +<itemizedlist> +<listitem><para>BOOL - on|off|true|false|1|0</para></listitem> +<listitem><para>INTEGER - any integer number</para></listitem> +<listitem><para>STRING - anything else</para></listitem> +</itemizedlist> +</para> + +<variablelist> +<title>Available Variables</title> + +<varlistentry> +<term><cmdsynopsis><command>auto-brackets</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set auto insertion of brackets on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>auto-center-lines</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the number of autocenter lines.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>auto-insert-doxygen</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turn insertion of the leading asterisk in doxygen comments on or +off. This has no effect unless you use the cstyle auto-indenter. </para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>background-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the document background color. The value must be something +that can be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>backspace-indents</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turn backspace indenting on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>block-selection</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turn block selection on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>bracket-highlight-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the color for the bracket highlight. The value must be +something that can be evaluated to a valid color, for example "#ff0000" </para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>current-line-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the color for the current line. The value must be +something that can be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>dynamic-word-wrap</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Turns dynamic word wrap on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>eol | end-of-line</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the end of line mode. Valid settings are +<quote>unix</quote>, <quote>mac</quote> and <quote>dos</quote></para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>encoding</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the document encoding. The value must be a valid encoding +name, like <quote>utf-8</quote>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>font-size</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the point size of the document font.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>font</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the font of the document. The value should be a valid font +name, for example <quote>courier</quote>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>icon-bar-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the icon bar color. The value must be something that can +be evaluated to a valid color, for example <literal>#ff0000</literal>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>icon-border</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the display of the icon border on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>folding-markers</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the display of folding markers on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>indent-mode</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the auto-indentation mode. The options <quote>none</quote>, +<quote>normal</quote>, <quote>cstyle</quote>, <quote>csands</quote>, +<quote>python</quote>, <quote>xml</quote> are recognized. See the section +<xref linkend="kate-part-autoindent"/> for details.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>indent-width</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the indentation width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>keep-extra-spaces</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set wheather to keep extra spaces when calculating indentation width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>keep-indent-profile</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>If enabled, prevents unindenting a block if at least one line +has no indentation.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>line-numbers</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the display of line numbers on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>mixed-indent</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set mixed indentation ala Emacs on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>overwrite-mode</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set overwrite mode on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>persistent-selection</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set persistent selection on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>remove-trailing-space</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set dynamic end of line cleanup on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace-tabs-save</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set tab->space conversion on save on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace-tabs</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set dynamic tab->space conversion on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>replace-trailing-space-save</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set end of line cleanup on save on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>scheme</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the color scheme. The string must be the name of a color +scheme that exists in your configuration to have any effect.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>selection-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the selection color. The value must be something that can +be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>show-tabs</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the visual TAB character on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>smart-home</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set smart home navigation on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>space-indent</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set indentation with spaces on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>tab-indents</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set the TAB key indentation on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>tab-width</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the tab display width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>undo-steps</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the number of undo steps to remember.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>word-wrap-column</command><arg>INT</arg></cmdsynopsis></term> +<listitem><para>Set the hard word wrap width.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>word-wrap-marker-color</command><arg>STRING</arg></cmdsynopsis></term> +<listitem><para>Set the word wrap marker color. The value must be something +that can be evaluated to a valid color, for example "#ff0000".</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>word-wrap</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set hard word wrapping on or off.</para></listitem> +</varlistentry> + +<varlistentry> +<term><cmdsynopsis><command>wrap-cursor</command><arg>BOOL</arg></cmdsynopsis></term> +<listitem><para>Set cursor wrapping on or off.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kate/fundamentals.docbook b/doc/kate/fundamentals.docbook new file mode 100644 index 000000000..e6beaac58 --- /dev/null +++ b/doc/kate/fundamentals.docbook @@ -0,0 +1,621 @@ +<chapter id="fundamentals"> +<chapterinfo> +<authorgroup> +<author><personname><firstname></firstname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>The Fundamentals</title> + +<para> +If you have ever used a text editor, you will have no problem using +&kate;. In the next two sections, <link linkend="starting-kate">Starting +&kate; </link> and in <link linkend="working-with-kate">Working with +&kate;</link>, we'll show you everything you need to get up and running +quickly. +</para> + +<sect1 id="starting-kate"> +<title>Starting &kate;</title> + +<para> +You can start &kate; from the <guimenu>K menu</guimenu> or from the +command line. +</para> + +<sect2 id="starting-from-the-menu"> +<title>From the Menu</title> +<para> +Open the &kde; program menu by clicking on the +<guiicon>big K</guiicon> icon on the toolbar at the bottom left of your +screen. This will raise the <guimenu>program menu</guimenu>. Move your +cursor up the menu to the <menuchoice><guimenu>Utilities</guimenu> +<guimenuitem>Editors</guimenuitem></menuchoice> menu item. A list +of available editors will appear. Choose +<guimenuitem>&kate;</guimenuitem>. +</para> + +<para> +Unless you configure &kate; not to, it will load the last files you +edited. See <link linkend="configure">Configuring &kate;</link> to learn +how to toggle this feature on and off. +</para> + +</sect2> + +<sect2 id="starting-from-the-command-line"> +<title>From the Command Line</title> + +<para> +You can start &kate; by typing its name on the command line. If you give +it a file name, as in the example below, it will open or create that +file. +</para> + +<informalexample> +<screen> +<prompt>%</prompt><userinput><command>kate</command> <option><replaceable>myfile.txt</replaceable></option></userinput> +</screen> +</informalexample> + +<para> +If you have an active connection, and permission, you can take advantage +of &kde;'s network transparency to open files on the internet. +</para> + +<informalexample> +<screen> +<prompt>%</prompt><userinput><command>kate</command> <option><replaceable>ftp://ftp.kde.org/pub/kde/README_FIRST</replaceable></option></userinput> +</screen> +</informalexample> + +<sect3 id="command-line-options"> +<title>Command Line Options</title> +<para>&kate; accepts following command line options:</para> + +<variablelist> +<varlistentry> +<term><userinput><command>kate</command> <option>--help</option></userinput></term> +<listitem> +<para> +This lists the most basic options available at the command line. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--help-qt</option></userinput></term> +<listitem> +<para> +This lists the options available for changing the way &kate; interacts +with &Qt;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> <option>--help-kde</option></userinput></term> +<listitem> +<para> +This lists the options available for changing the way &kate; interacts +with &kde;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-s</option> <option>--start</option> <parameter>name</parameter></userinput></term> +<listitem> +<para> +Starts kate with the session <parameter>name</parameter>. The session is created +if it does not exist already. If a &kate; instance running the specified session +exists, the specified files are loaded in that instance. When used with the +<option>--use</option> option, an instance running this session will be used as +well. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-u</option> <option>--use</option> <parameter>URL</parameter></userinput></term> +<listitem> +<para> +Causes &kate; to use and existing instance if there is one. If you want all +documents to open in one kate instance, you can add this option to the default +command in your kde application configuration, as well as create a shell alias +in your command intepreter if it supports that. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-p</option> <option>--pid</option> <parameter>PID</parameter></userinput></term> +<listitem> +<para> +Only reuses an instance with the specified PID (Process ID). Used with the +<option>--use</option> option. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--encoding</option> <parameter>encoding</parameter> +<parameter>URL</parameter></userinput></term> +<listitem><para>Uses the specified encoding for the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--line</option> <parameter>line</parameter> +<parameter>URL</parameter></userinput></term> +<listitem><para>Navigates to the specified line after opening the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--column</option> <parameter>column</parameter> +<parameter>URL</parameter></userinput></term> +<listitem><para>Navigates to the specified column after opening the document. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--stdin</option></userinput></term> +<listitem><para>Reads the document content from STDIN. This +is similar to the common option <option>-</option> used in many command line +programs, and allows you to pipe command output into &kate;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--tempfile</option></userinput></term> +<listitem><para>Since &kate; 2.5.1 this standard &kde; option is supported. +When used, the specified files are treated as temporary files and +deleted (if they are local files and you have sufficient permissions) when +closed, unless they are modified since they were opened.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--help-all</option></userinput></term> +<listitem> +<para> +This lists all of the command line options. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--author</option></userinput></term> +<listitem> +<para> +Lists &kate;'s authors in the terminal window. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>-v</option> <option>--version</option></userinput></term> +<listitem> +<para> +Lists version information for &Qt;, &kde;, and &kate;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput><command>kate</command> +<option>--license</option></userinput></term> +<listitem> +<para> +Shows license information. +</para> +</listitem> +</varlistentry> +</variablelist> +</sect3> +</sect2> + +<sect2 id="drag-and-drop"> +<title>Drag and Drop</title> +<para> +&kate; uses the &kde; Drag and Drop protocol. Files may be dragged and +dropped onto &kate; from the Desktop, &konqueror; or some remote ftp +site opened in one of &konqueror;'s windows. +</para> +</sect2> +</sect1> + +<sect1 id="working-with-kate"> +<title>Working with &kate;</title> +<para> +<link linkend="quick-start">Quick Start</link> will show you how to +toggle four simple options that will let you configure some of &kate;'s +more powerful features right away. <link linkend="keystroke-commands"> +Shortcuts</link> lays out some of the default keystroke +shortcuts for those who can't or don't want to use a mouse. +</para> + +<sect2 id="quick-start"> +<title>Quick Start</title> + +<para> +This section will describe some of the items on the +<guimenu>Settings</guimenu> menu so that you can quickly configure +&kate; to work the way you want it. +</para> + +<para> When you start &kate; for the first time you'll see two windows +with white backgrounds. Above the two windows is a toolbar with the +usual labeled icons. And above that, a menubar. +</para> + +<para> +The left-hand window is a side bar. It combines the Documents +and Filesystem Browser windows. Switch between the two by clicking on the tabs +to the left of the window. </para> + +<para> +If you've started &kate; with a file, the right-hand window will show +the file you are editing and the Documents on the side bar will show the +name of the file. Use the Filesystem Browser window to open files. +</para> + +<para> +You can toggle the Documents and Filesystem Browser window on and off in +<menuchoice><guimenu>Window</guimenu><guimenu>Tool Views</guimenu></menuchoice> +menu. This menu offers you your first glimpse into &kate;'s power and +flexibility. In this section we'll look at three items: +</para> + +<variablelist> + +<varlistentry> +<term> +<menuchoice> +<guimenuitem>Show/Hide Documents</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Toggles the Documents on and off. If the Documents/Filesystem Browser window is +not open, &kate; launches the side bar as a separate, undocked, +window. To dock the window grab the two thin parallel lines above the +tabs by clicking on them with your &LMB; and holding the button +down. Drag the the window into &kate;'s editing window and release the +&LMB; when you have positioned the Documents/Filesystem Browser window as you +prefer. +</para> + +<tip> +<para> +If you have grabbed the two parallel lines successfully your mouse +pointer will turn into two crossed arrows as you drag. +</para> +</tip> + +</listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenuitem>Show/Hide +Filesystem Browser</guimenuitem></menuchoice></term> +<listitem> +<para> +Toggles the Filesystem Browser on and off. This menu item is the same as +<guimenuitem>Show Documents</guimenuitem> with one difference. Toggling +it on launches the window with the Filesystem Browser on top. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Show/Hide +Terminal</guimenuitem></menuchoice></term> +<listitem> +<para> +Toggles a terminal emulator on and off at the bottom of &kate;'s +window. In other words, it gives you a command line within the +application. +</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="keystroke-commands"> +<title>Shortcuts</title> + +<para> +Many of &kate;'s keystroke commands (shortcuts) are configurable by +way of the <link linkend="settings">Settings</link> menu. By default +&kate; honors the following key bindings. +</para> + +<informaltable> +<tgroup cols="2"> +<tbody> + +<row><entry><para><keycap>Insert</keycap></para></entry> +<entry><para> +Toggle between Insert and Overwrite mode. When in insert mode the editor +will add any typed characters to the text and push any previously typed +data to the right of the text cursor. Overwrite mode causes the entry of +each character to eliminate the current character.</para></entry> +</row> +<row> +<entry><para><keycombo><keycap>Left Arrow</keycap></keycombo></para></entry> +<entry><para>Move the cursor one character to the left </para></entry> +</row> +<row> +<entry><para><keycombo><keycap>Right Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor one character to the right </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Up Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor up one line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Down Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor down one line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Page Up</keycap></keycombo></para></entry> +<entry><para> Move the cursor up one page </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Page Down</keycap></keycombo></para></entry> +<entry><para>Move the cursor down one page </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Backspace</keycap></keycombo></para></entry> +<entry><para> Delete the character to the left of the cursor </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Home</keycap></keycombo></para></entry> +<entry><para> Move the cursor to the beginning of the line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>End</keycap></keycombo></para></entry> +<entry><para> Move the cursor to the end of the line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Delete</keycap></keycombo></para></entry> +<entry><para>Delete the character to the right of the cursor (or any selected +text)</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Left Arrow</keycap></keycombo></para></entry> +<entry><para> Mark text one character to the left </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Right Arrow</keycap></keycombo></para></entry> +<entry><para> Mark text one character to the right </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>F1</keycap></keycombo></para></entry> +<entry><para> Help</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo></para></entry> +<entry><para><link linkend="whats-this">What's this?</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></para></entry> +<entry><para><link linkend="find"> Find</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>F3</keycap></keycombo></para></entry> +<entry><para><link linkend="find-again"> Find again</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo></para></entry> +<entry><para>Set a Bookmark</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></para></entry> +<entry><para> Copy the marked text to the clipboard. </para></entry> +</row> + +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo></para></entry> +<entry><para> <link linkend="new">New</link> document</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo></para></entry> +<entry><para><link linkend="print">Print</link> </para></entry> +</row> +<row> + +<entry><para><keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo></para></entry> +<entry><para>Quit - close active copy of editor </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></para></entry> +<entry><para><link linkend="replace"> Replace</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo></para></entry> +<entry><para>Save your file.</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo></para></entry> +<entry><para> Paste.</para></entry> +</row> + +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo></para></entry> +<entry><para>Delete the marked text and copy it to the clipboard. </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></para></entry> +<entry><para><link linkend="undo">Undo</link></para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></para></entry> +<entry><para><link linkend="redo">Redo</link></para></entry> +</row> +</tbody> +</tgroup> +</informaltable> +</sect2> + +</sect1> + +<sect1 id="fundamentals-using-sessions"> +<title>Using Sessions</title> + +<para>Sessions is how &kate; lets you keep more than one list of files and +GUI configuration around. You can have as many named sessions as you want, +and you can use unnamed or anonymous sessions for files you want to use only +once. Currently &kate; can save the list of open files, and the general window +configuration in the session, future versions of &kate; may add more features +that can be saved in sessions. With the introduction of sessions, &kate; also +allows you to open any number of instances of the application instead of just +one as it used to do as the default behavior.</para> + +<para>Sessions are supported in three areas: + +<itemizedlist> +<listitem><para><link linkend="command-line-options"><emphasis>Command line +options</emphasis></link> that lets you select and start sessions when launching +kate from the command line.</para> +</listitem> +<listitem><para><link linkend="sessions-menu"><emphasis>The Sessions +menu</emphasis></link> that lets you switch, save, start and manage your +sessions</para></listitem> +<listitem><para><link linkend="config-dialog-sessions"><emphasis>Configuration +options</emphasis></link> that lets you decide how sessions generally should +behave.</para></listitem> +</itemizedlist> + +</para> + +<para>When starting a new session, the GUI configuration of <guilabel>Default +Session</guilabel> is loaded. To save window configuration in the default +session, you need to enable saving window configuration in the sessions +configuration page of the configuration dialog and then load the default +session, set up the window as desired and save the session again.</para> + +<para>When a named session is loaded, &kate; will display the session name at +the start of the window title, which then have the form +"<replaceable>Session Name</replaceable>: <replaceable>Document name or +&URL;</replaceable> - &kate;"</para> + +<para>When opening files on the command line with <option>--start +<replaceable>name</replaceable></option> or if a session is selected using the +session chooser, the specified session is loaded prior to the files specified +on the command line. To open files from the commandline in a new, unnamed +session, configure kate to start a new session pr default in the session page of +the configuration dialog or use <option>--start</option> with an empty string: +<replaceable>''</replaceable>.</para> + +<para>Since &kate; 2.5.1 the <acronym>PID</acronym> of the current instance is +exported to the environment variable <envar>KATE_PID</envar>. When opening files +from the built in terminal Kate will automatically select the current instance +if nothing else is indicated on the command line.</para> + +<sect2 id="old-behavior"> +<title>Restoring old style &kate; behavior</title> + +<para>When you get used to using sessions you will hopefully see that they +provide a very simple and efficient tool for working in different areas. +However, if you prefer the old &kate; behavior (one instance opens all files), +you can easily achieve that by following this simple strategy: + +<itemizedlist> +<listitem><para>Make kate allways start with the <option>--use</option> +parameter by adding that to the command in the application preferences, +and additionally using a shell alias.</para></listitem> +<listitem><para>Configure &kate; to load the last used session at startup.</para> +</listitem> +<listitem><para>Configure &kate; to save the file list when closing a session. +</para></listitem> +<listitem><para>Load the default session once</para></listitem> +</itemizedlist> +</para> + +</sect2> + +</sect1> + +<sect1 id="fundamentals-getting-help"> + +<title>Getting Help</title> + +<sect2> + +<title>With &kate;</title> +<variablelist> + +<varlistentry> +<term>This manual</term> + +<listitem> +<para>Offers detailed documentation on all menu commands, +configuration options, tools, dialogs, plugins &etc; as well as +descriptions of of the &kate; window, the editor and various concepts +used in the application.</para> + +<para>Press <keycap>F1</keycap> or use the +<menuchoice><guimenu>Help</guimenu></menuchoice> +<guisubmenu>Contents</guisubmenu> menu topic to view this +manual.</para></listitem> + +</varlistentry> + +<varlistentry id="whats-this"> +<term>What's This Help</term> +<listitem> +<para>What's This help offers immediate help with single elements of +graphical windows, such as buttons or other window areas.</para> + +<para>We strive to provide What's This help for any elements for which +it makes sense. It is available throughout the configuration dialog, +and in many other dialogs as well.</para> + +<para>To employ What's This help, press +<keycombo>&Shift;<keycap>F1</keycap></keycombo> or use the +<menuchoice><guimenu>Help</guimenu><guimenuitem>What's +This</guimenuitem></menuchoice> menu item to enable What's This +mode. The cursor will turn into an arrow with a question mark, and you +can now click any element in the window to read the What's This help +for that element, if it is available.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Help Buttons in Dialogs</term> +<listitem> +<para>Some dialogs have a <guibutton>Help</guibutton> Button. Pressing +it will start the &khelpcenter; and open the relevant +documentation.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2> +<title>With Your Text Files</title> + +<para>&kate; does not (yet!) provide any means for reading document +related documentation. Depending on the file you are editing, you may +find the <link linkend="kate-mdi-tools-konsole">Built in +&konsole;</link> helpful for viewing related &UNIX; manual pages or +info documentation, or you can use &konqueror;.</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kate/highlighted.png b/doc/kate/highlighted.png Binary files differnew file mode 100644 index 000000000..ffb95ec48 --- /dev/null +++ b/doc/kate/highlighted.png diff --git a/doc/kate/highlighting.docbook b/doc/kate/highlighting.docbook new file mode 100644 index 000000000..76952d26a --- /dev/null +++ b/doc/kate/highlighting.docbook @@ -0,0 +1,931 @@ +<appendix id="highlight"> +<appendixinfo> +<authorgroup> +<author><personname><firstname></firstname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</appendixinfo> +<title>Working with Syntax Highlighting</title> + +<sect1 id="highlight-overview"> + +<title>Overview</title> + +<para>Syntax Highlighting is what makes the editor automatically +display text in different styles/colors, depending on the function of +the string in relation to the purpose of the file. In program source +code for example, control statements may be rendered bold, while data +types and comments get different colors from the rest of the +text. This greatly enhances the readability of the text, and thus +helps the author to be more efficient and productive.</para> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="highlighted.png"/></imageobject> +<textobject><phrase>A Perl function, rendered with syntax +highlighting.</phrase></textobject> +<caption><para>A Perl function, rendered with syntax highlighting.</para> +</caption> +</mediaobject> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="unhighlighted.png"/></imageobject> +<textobject><phrase>The same Perl function, without +highlighting.</phrase></textobject> +<caption><para>The same Perl function, without highlighting.</para></caption> +</mediaobject> + +<para>Of the two examples, which is easiest to read?</para> + +<para>&kate; comes with a flexible, configurable and capable system +for doing syntax highlighting, and the standard distribution provides +definitions for a wide range of programming, scripting and markup +languages and other text file formats. In addition you can +provide your own definitions in simple &XML; files.</para> + +<para>&kate; will automatically detect the right syntax rules when you +open a file, based on the &MIME; Type of the file, determined by its +extension, or, if it has none, the contents. Should you experience a +bad choice, you can manually set the syntax to use from the +<menuchoice><guimenu>Documents</guimenu><guisubmenu>Highlight +Mode</guisubmenu></menuchoice> menu.</para> + +<para>The styles and colors used by each syntax highlight definition +can be configured using the <link +linkend="config-dialog-editor-appearance">Appearance</link> page of the +<link linkend="config-dialog">Config Dialog</link>, while the &MIME; Types +it should be used for, are handeled by the <link +linkend="config-dialog-editor-highlighting">Highlight</link> +page.</para> + +<note> +<para>Syntax highlighting is there to enhance the readability of +correct text, but you cannot trust it to validate your text. Marking +text for syntax is difficult depending on the format you are using, +and in some cases the authors of the syntax rules will be proud if 98% +of text gets correctly rendered, though most often you need a rare +style to see the incorrect 2%.</para> +</note> + +<tip> +<para>You can download updated or additional syntax highlight +definitions from the &kate; website by clicking the +<guibutton>Download</guibutton> button in the <link +linkend="config-dialog-editor-highlighting">Highlight Page</link> of the <link +linkend="config-dialog">Config Dialog</link>.</para> +</tip> + +</sect1> + +<sect1 id="katehighlight-system"> + +<title>The &kate; Syntax Highlight System</title> + +<para>This section will discuss the &kate; syntax highlighting +mechanism in more detail. It is for you if you want to know about +it, or if you want to change or create syntax definitions.</para> + +<sect2 id="katehighlight-howitworks"> + +<title>How it Works</title> + +<para>Whenever you open a file, one of the first things the &kate; +editor does is detect which syntax definition to use for the +file. While reading the text of the file, and while you type away in +it, the syntax highlighting system will analyze the text using the +rules defined by the syntax definition and mark in it where different +contexts and styles begin and end.</para> + +<para>When you type in the document, the new text is analyzed and marked on the +fly, so that if you delete a character that is marked as the beginning or end +of a context, the style of surrounding text changes accordingly.</para> + +<para>The syntax definitions used by the &kate; Syntax Highlighting System are +&XML; files, containing +<itemizedlist> +<listitem><para>Rules for detecting the role of text, organized into context blocks</para></listitem> +<listitem><para>Keyword lists</para></listitem> +<listitem><para>Style Item definitions</para></listitem> +</itemizedlist> +</para> + +<para>When analyzing the text, the detection rules are evaluated in +the order in which they are defined, and if the beginning of the +current string matches a rule, the related context is used. The start +point in the text is moved to the final point at which that rule +matched and a new loop of the rules begins, starting in the context +set by the matched rule.</para> + +</sect2> + +<sect2 id="highlight-system-rules"> +<title>Rules</title> + +<para>The detection rules are the heart of the highlighting detection +system. A rule is a string, character or <link +linkend="regular-expressions">regular expression</link> against which +to match the text being analyzed. It contains information about which +style to use for the matching part of the text. It may switch the +working context of the system either to an explicitly mentioned +context or to the previous context used by the text.</para> + +<para>Rules are organized in context groups. A context group is used +for main text concepts within the format, for example quoted text +strings or comment blocks in program source code. This ensures that +the highlighting system does not need to loop through all rules when +it is not necessary, and that some character sequences in the text can +be treated differently depending on the current context. +</para> + +<para>Contexts may be generated dynamically to allow the usage of instance +specific data in rules.</para> + +</sect2> + +<sect2 id="highlight-context-styles-keywords"> +<title>Context Styles and Keywords</title> + +<para>In some programming languages, integer numbers are treated +differently than floating point ones by the compiler (the program that +converts the source code to a binary executable), and there may be +characters having a special meaning within a quoted string. In such +cases, it makes sense to render them differently from the surroundings +so that they are easy to identify while reading the text. So even if +they do not represent special contexts, they may be seen as such by +the syntax highlighting system, so that they can be marked for +different rendering.</para> + +<para>A syntax definition may contain as many styles as required to +cover the concepts of the format it is used for.</para> + +<para>In many formats, there are lists of words that represent a +specific concept. For example in programming languages, the control +statements is one concept, data type names another, and built in +functions of the language a third. The &kate; Syntax Highlighting +System can use such lists to detect and mark words in the text to +emphasize concepts of the text formats.</para> + +</sect2> + +<sect2 id="kate-highlight-system-default-styles"> +<title>Default Styles</title> + +<para>If you open a C++ source file, a &Java; source file and an +<acronym>HTML</acronym> document in &kate;, you will see that even +though the formats are different, and thus different words are chosen +for special treatment, the colors used are the same. This is because +&kate; has a predefined list of Default Styles which are employed by +the individual syntax definitions.</para> + +<para>This makes it easy to recognize similar concepts in different +text formats. For example comments are present in almost any +programming, scripting or markup language, and when they are rendered +using the same style in all languages, you do not have to stop and +think to identify them within the text.</para> + +<tip> +<para>All styles in a syntax definition use one of the default +styles. A few syntax definitions use more styles that there are +defaults, so if you use a format often, it may be worth launching the +configuration dialog to see if some concepts are using the same +style. For example there is only one default style for strings, but as +the Perl programming language operates with two types of strings, you +can enhance the highlighting by configuring those to be slightly +different. All <link linkend="kate-highlight-default-styles">available default styles</link> +will be explained later.</para> +</tip> + +</sect2> + +</sect1> + +<sect1 id="katehighlight-xml-format"> +<title>The Highlight Definition &XML; Format</title> + +<sect2> +<title>Overview</title> + +<para>This section is an overview of the Highlight Definition &XML; +format. Based on a small example it will describe the main components +and their meaning and usage. The next section will go into detail with +the highlight detection rules.</para> + +<para>The formal definition, aka the <acronym>DTD</acronym> is stored +in the file <filename>language.dtd</filename> which should be +installed on your system in the folder +<filename>$<envar>KDEDIR</envar>/share/apps/katepart/syntax</filename>. +</para> + +<variablelist> +<title>Main sections of &kate; Highlight Definition files</title> + +<varlistentry> +<term>A highlighting file contains a header that sets the XML version and the doctype:</term> +<listitem> +<programlisting> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd"> +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term>The root of the definition file is the element <userinput>language</userinput>. +Available attributes are:</term> + +<listitem> +<para>Required attributes:</para> +<para><userinput>name</userinput> sets the name of the language. It appears in the menus and dialogs afterwards.</para> +<para><userinput>section</userinput> specifies the category.</para> +<para><userinput>extensions</userinput> defines file extensions, like "*.cpp;*.h"</para> + +<para>Optional attributes:</para> +<para><userinput>mimetype</userinput> associates files &MIME; Type based.</para> +<para><userinput>version</userinput> specifies the current version of the definition file.</para> +<para><userinput>kateversion</userinput> specifies the latest supported &kate; version.</para> +<para><userinput>casesensitive</userinput> defines, whether the keywords are casesensitiv or not.</para> +<para><userinput>priority</userinput> is necessary if another highlight definition file uses the same extensions. The higher priority will win.</para> +<para><userinput>author</userinput> contains the name of the author and his email-address.</para> +<para><userinput>license</userinput> contains the license, usually LGPL, Artistic, GPL and others.</para> +<para><userinput>hidden</userinput> defines, whether the name should appear in &kate;'s menus.</para> +<para>So the next line may look like this:</para> +<programlisting> +<language name="C++" version="1.00" kateversion="2.4" section="Sources" extensions="*.cpp;*.h" /> +</programlisting> +</listitem> +</varlistentry> + + +<varlistentry> +<term>Next comes the <userinput>highlighting</userinput> element, which +contains the optional element <userinput>list</userinput> and the required +elements <userinput>contexts</userinput> and <userinput>itemDatas</userinput>.</term> +<listitem> +<para><userinput>list</userinput> elements contain a list of keywords. In +this case the keywords are <emphasis>class</emphasis> and <emphasis>const</emphasis>. +You can add as many lists as you need.</para> +<para>The <userinput>contexts</userinput> element contains all contexts. +The first context is by default the start of the highlighting. There are +two rules in the context <emphasis>Normal Text</emphasis>, which match +the list of keywords with the name <emphasis>somename</emphasis> and a +rule that detects a quote and switches the context to <emphasis>string</emphasis>. +To learn more about rules read the next chapter.</para> +<para>The third part is the <userinput>itemDatas</userinput> element. It +contains all color and font styles needed by the contexts and rules. +In this example, the <userinput>itemData</userinput> <emphasis>Normal Text</emphasis>, +<emphasis>String</emphasis> and <emphasis>Keyword</emphasis> are used. +</para> +<programlisting> + <highlighting> + <list name="somename"> + <item> class </item> + <item> const </item> + </list> + <contexts> + <context attribute="Normal Text" lineEndContext="#pop" name="Normal Text" > + <keyword attribute="Keyword" context="#stay" String="somename" /> + <DetectChar attribute="String" context="string" char="&quot;" /> + </context> + <context attribute="String" lineEndContext="#stay" name="string" > + <DetectChar attribute="String" context="#pop" char="&quot;" /> + </context> + </contexts> + <itemDatas> + <itemData name="Normal Text" defStyleNum="dsNormal" /> + <itemData name="Keyword" defStyleNum="dsKeyword" /> + <itemData name="String" defStyleNum="dsString" /> + </itemDatas> + </highlighting> +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term>The last part of a highlight definition is the optional +<userinput>general</userinput> section. It may contain information +about keywords, code folding, comments and indentation.</term> + +<listitem> +<para>The <userinput>comment</userinput> section defines with what +string a single line comment is introduced. You also can define a +multiline comments using <emphasis>multiLine</emphasis> with the +additional attribute <emphasis>end</emphasis>. This is used if the +user presses the corresponding shortcut for <emphasis>comment/uncomment</emphasis>.</para> +<para>The <userinput>keywords</userinput> section defines whether +keyword lists are casesensitive or not. Other attributes will be +explained later.</para> +<programlisting> + <general> + <comments> + <comment name="singleLine" start="#"/> + </comments> + <keywords casesensitive="1"/> + </general> +</language> +</programlisting> +</listitem> +</varlistentry> + +</variablelist> + + +</sect2> + +<sect2 id="kate-highlight-sections"> +<title>The Sections in Detail</title> +<para>This part will describe all available attributes for contexts, +itemDatas, keywords, comments, code folding and indentation.</para> + +<variablelist> +<varlistentry> +<term>The element <userinput>context</userinput> belongs into the group +<userinput>contexts</userinput>. A context itself defines context specific +rules like what should happen if the highlight system reaches the end of a +line. Available attributes are:</term> + + +<listitem> +<para><userinput>name</userinput> the context name. Rules will use this name +to specify the context to switch to if the rule matches.</para> +<para><userinput>lineEndContext</userinput> defines the context the highlight +system switches to if it reaches the end of a line. This may either be a name +of another context, <userinput>#stay</userinput> to not switch the context +(eg. do nothing) or <userinput>#pop</userinput> which will cause to leave this +context. It is possible to use for example <userinput>#pop#pop#pop</userinput> +to pop three times.</para> +<para><userinput>lineBeginContext</userinput> defines the context if a begin +of a line is encountered. Default: #stay.</para> +<para><userinput>fallthrough</userinput> defines if the highlight system switches +to the context specified in fallthroughContext if no rule matches. +Default: <emphasis>false</emphasis>.</para> +<para><userinput>fallthroughContext</userinput> specifies the next context +if no rule matches.</para> +<para><userinput>dynamic</userinput> if <emphasis>true</emphasis>, the context +remembers strings/placeholders saved by dynamic rules. This is needed for HERE +documents for example. Default: <emphasis>false</emphasis>.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>itemData</userinput> is in the group +<userinput>itemDatas</userinput>. It defines the font style and colors. +So it is possible to define your own styles and colors, however we +recommend to stick to the default styles if possible so that the user +will always see the same colors used in different languages. Though, +sometimes there is no other way and it is necessary to change color +and font attributes. The attributes name and defStyleNum are required, +the other optional. Available attributes are:</term> + +<listitem> +<para><userinput>name</userinput> sets the name of the itemData. +Contexts and rules will use this name in their attribute +<emphasis>attribute</emphasis> to reference an itemData.</para> +<para><userinput>defStyleNum</userinput> defines which default style to use. +Available default styles are explained in detail later.</para> +<para><userinput>color</userinput> defines a color. Valid formats are +'#rrggbb' or '#rgb'.</para> +<para><userinput>selColor</userinput> defines the selection color.</para> +<para><userinput>italic</userinput> if <emphasis>true</emphasis>, the text will be italic.</para> +<para><userinput>bold</userinput> if <emphasis>true</emphasis>, the text will be bold.</para> +<para><userinput>underline</userinput> if <emphasis>true</emphasis>, the text will be underlined.</para> +<para><userinput>strikeout</userinput> if <emphasis>true</emphasis>, the text will be stroked out.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>keywords</userinput> in the group +<userinput>general</userinput> defines keyword properties. Available attributes are:</term> + +<listitem> +<para><userinput>casesensitive</userinput> may be <emphasis>true</emphasis> +or <emphasis>false</emphasis>. If <emphasis>true</emphasis>, all keywords +are matched casesensitive</para> +<para><userinput>weakDeliminator</userinput> is a list of characters that +do not act as word delimiters. For example the dot <userinput>'.'</userinput> +is a word delimiter. Assume a keyword in a <userinput>list</userinput> contains +a dot, it will only match if you specify the dot as a weak delimiter.</para> +<para><userinput>additionalDeliminator</userinput> defines additional delimiters.</para> +<para><userinput>wordWrapDeliminator</userinput> defines characters after which a +line wrap may occur.</para> +<para>Default delimiters and word wrap delimiters are the characters +<userinput>.():!+,-<=>%&*/;?[]^{|}~\</userinput>, space (<userinput>' '</userinput>) +and tabulator (<userinput>'\t'</userinput>).</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>comment</userinput> in the group +<userinput>comments</userinput> defines comment properties which are used +for <menuchoice><guimenu>Tools</guimenu><guimenuitem>Comment</guimenuitem></menuchoice> and +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Uncomment</guimenuitem></menuchoice>. +Available attributes are:</term> + +<listitem> +<para><userinput>name</userinput> is either <emphasis>singleLine</emphasis> +or <emphasis>multiLine</emphasis>. If you choose <emphasis>multiLine</emphasis> +the attributes <emphasis>end</emphasis> and <emphasis>region</emphasis> are +required.</para> +<para><userinput>start</userinput> defines the string used to start a comment. +In C++ this would be "/*".</para> +<para><userinput>end</userinput> defines the string used to close a comment. +In C++ this would be "*/".</para> +<para><userinput>region</userinput> should be the name of the the foldable +multiline comment. Assume you have <emphasis>beginRegion="Comment"</emphasis> +... <emphasis>endRegion="Comment"</emphasis> in your rules, you should use +<emphasis>region="Comment"</emphasis>. This way uncomment works even if you +do not select all the text of the multiline comment. The cursor only must be +in the multiline comment.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>folding</userinput> in the group +<userinput>general</userinput> defines code folding properties. +Available attributes are:</term> + +<listitem> +<para><userinput>indentationsensitive</userinput> if <emphasis>true</emphasis>, the code folding markers +will be added indentation based, like in the scripting language Python. Usually you +do not need to set it, as it defaults to <emphasis>false</emphasis>.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The element <userinput>indentation</userinput> in the group +<userinput>general</userinput> defines which indenter will be used, however we strongly +recommend to omit this element, as the indenter usually will be set by either defining +a File Type or by adding a mode line to the text file. If you specify an indenter though, +you will force a specific indentation on the user, which he might not like at all. +Available attributes are:</term> + +<listitem> +<para><userinput>mode</userinput> is the name of the indenter. Available indenters +right now are: <emphasis>normal, cstyle, csands, xml, python</emphasis> and +<emphasis>varindent</emphasis>.</para> +</listitem> +</varlistentry> + + +</variablelist> + + +</sect2> + +<sect2 id="kate-highlight-default-styles"> +<title>Available Default Styles</title> +<para>Default Styles were <link linkend="kate-highlight-system-default-styles">already explained</link>, +as a short summary: Default styles are predefined font and color styles.</para> +<variablelist> +<varlistentry> +<term>So here only the list of available default styles:</term> +<listitem> +<para><userinput>dsNormal</userinput>, used for normal text.</para> +<para><userinput>dsKeyword</userinput>, used for keywords.</para> +<para><userinput>dsDataType</userinput>, used for data types.</para> +<para><userinput>dsDecVal</userinput>, used for decimal values.</para> +<para><userinput>dsBaseN</userinput>, used for values with a base other than 10.</para> +<para><userinput>dsFloat</userinput>, used for float values.</para> +<para><userinput>dsChar</userinput>, used for a character.</para> +<para><userinput>dsString</userinput>, used for strings.</para> +<para><userinput>dsComment</userinput>, used for comments.</para> +<para><userinput>dsOthers</userinput>, used for 'other' things.</para> +<para><userinput>dsAlert</userinput>, used for warning messages.</para> +<para><userinput>dsFunction</userinput>, used for function calls.</para> +<para><userinput>dsRegionMarker</userinput>, used for region markers.</para> +<para><userinput>dsError</userinput>, used for error highlighting and wrong syntax.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="kate-highlight-rules-detailled"> +<title>Highlight Detection Rules</title> + +<para>This section describes the syntax detection rules.</para> + +<para>Each rule can match zero or more characters at the beginning of +the string they are test against. If the rule matches, the matching +characters are assigned the style or <emphasis>attribute</emphasis> +defined by the rule, and a rule may ask that the current context is +switched.</para> + +<para>A rule looks like this:</para> + +<programlisting><RuleName attribute="(identifier)" context="(identifier)" [rule specific attributes] /></programlisting> + +<para>The <emphasis>attribute</emphasis> identifies the style to use +for matched characters by name, and the <emphasis>context</emphasis> +identifies the context to use from here.</para> + +<para>The <emphasis>context</emphasis> can be identified by:</para> + +<itemizedlist> +<listitem> +<para>An <emphasis>identifier</emphasis>, which is the name of the other +context.</para> +</listitem> +<listitem> +<para>An <emphasis>order</emphasis> telling the engine to stay in the +current context (<userinput>#stay</userinput>), or to pop back to a +previous context used in the string (<userinput>#pop</userinput>).</para> +<para>To go back more steps, the #pop keyword can be repeated: +<userinput>#pop#pop#pop</userinput></para> +</listitem> +</itemizedlist> + +<para>Some rules can have <emphasis>child rules</emphasis> which are +then evaluated only if the parent rule matched. The entire matched +string will be given the attribute defined by the parent rule. A rule +with child rules looks like this:</para> + +<programlisting> +<RuleName (attributes)> + <ChildRuleName (attributes) /> + ... +</RuleName> +</programlisting> + + +<para>Rule specific attributes varies and are described in the +following sections.</para> + + +<itemizedlist> +<title>Common attributes</title> +<para>All rules have the following attributes in common and are +available whenever <userinput>(common attributes)</userinput> appears. +<emphasis>attribute</emphasis> and <emphasis>context</emphasis> +are required attributes, all others are optional. +</para> + +<listitem> +<para><emphasis>attribute</emphasis>: An attribute maps to a defined <emphasis>itemData</emphasis>.</para> +</listitem> +<listitem> +<para><emphasis>context</emphasis>: Specify the context to which the highlighting system switches if the rule matches.</para> +</listitem> +<listitem> +<para><emphasis>beginRegion</emphasis>: Start a code folding block. Default: unset.</para> +</listitem> +<listitem> +<para><emphasis>endRegion</emphasis>: Close a code folding block. Default: unset.</para> +</listitem> +<listitem> +<para><emphasis>lookAhead</emphasis>: If <emphasis>true</emphasis>, the +highlighting system will not process the matches length. +Default: <emphasis>false</emphasis>.</para> +</listitem> +<listitem> +<para><emphasis>firstNonSpace</emphasis>: Match only, if the string is +the first non-whitespace in the line. Default: <emphasis>false</emphasis>.</para> +</listitem> +<listitem> +<para><emphasis>column</emphasis>: Match only, if the column matches. Default: unset.</para> +</listitem> +</itemizedlist> + +<itemizedlist> +<title>Dynamic rules</title> +<para>Some rules allow the optional attribute <userinput>dynamic</userinput> +of type boolean that defaults to <emphasis>false</emphasis>. If dynamic is +<emphasis>true</emphasis>, a rule can use placeholders representing the text +matched by a <emphasis>regular expression</emphasis> rule that switched to the +current context in its <userinput>string</userinput> or +<userinput>char</userinput> attributes. In a <userinput>string</userinput>, +the placeholder <replaceable>%N</replaceable> (where N is a number) will be +replaced with the corresponding capture <replaceable>N</replaceable> +from the calling regular expression. In a +<userinput>char</userinput> the placeholer must be a number +<replaceable>N</replaceable> and it will be replaced with the first character of +the corresponding capture <replaceable>N</replaceable> from the calling regular +expression. Whenever a rule allows this attribute it will contain a +<emphasis>(dynamic)</emphasis>.</para> + +<listitem> +<para><emphasis>dynamic</emphasis>: may be <emphasis>(true|false)</emphasis>.</para> +</listitem> +</itemizedlist> + +<sect2 id="highlighting-rules-in-detail"> +<title>The Rules in Detail</title> + +<variablelist> +<varlistentry> +<term>DetectChar</term> +<listitem> +<para>Detect a single specific character. Commonly used for example to +find the ends of quoted strings.</para> +<programlisting><DetectChar char="(character)" (common attributes) (dynamic) /></programlisting> +<para>The <userinput>char</userinput> attribute defines the character +to match.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Detect2Chars</term> +<listitem> +<para>Detect two specific characters in a defined order.</para> +<programlisting><Detect2Chars char="(character)" char1="(character)" (common attributes) (dynamic) /></programlisting> +<para>The <userinput>char</userinput> attribute defines the first character to match, +<userinput>char1</userinput> the second.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>AnyChar</term> +<listitem> +<para>Detect one character of a set of specified characters.</para> +<programlisting><AnyChar String="(string)" (common attributes) /></programlisting> +<para>The <userinput>String</userinput> attribute defines the set of +characters.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>StringDetect</term> +<listitem> +<para>Detect an exact string.</para> +<programlisting><StringDetect String="(string)" [insensitive="true|false"] (common attributes) (dynamic) /></programlisting> +<para>The <userinput>String</userinput> attribute defines the string +to match. The <userinput>insensitive</userinput> attribute defaults to +<emphasis>false</emphasis> and is passed to the string comparison +function. If the value is <emphasis>true</emphasis> insensitive +comparing is used.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>RegExpr</term> +<listitem> +<para>Matches against a regular expression.</para> +<programlisting><RegExpr String="(string)" [insensitive="true|false"] [minimal="true|false"] (common attributes) (dynamic) /></programlisting> +<para>The <userinput>String</userinput> attribute defines the regular +expression.</para> +<para><userinput>insensitive</userinput> defaults to +<emphasis>false</emphasis> and is passed to the regular expression +engine.</para> +<para><userinput>minimal</userinput> defaults to +<emphasis>false</emphasis> and is passed to the regular expression +engine.</para> +<para>Because the rules are always matched against the beginning of +the current string, a regular expression starting with a caret +(<literal>^</literal>) indicates that the rule should only be +matched against the start of a line.</para> +<para>See <link linkend="regular-expressions">Regular Expressions</link> +for more information on those.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>keyword</term> +<listitem> +<para>Detect a keyword from a specified list.</para> +<programlisting><keyword String="(list name)" (common attributes) /></programlisting> +<para>The <userinput>String</userinput> attribute identifies the +keyword list by name. A list with that name must exist.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Int</term> +<listitem> +<para>Detect an integer number.</para> +<para><programlisting><Int (common attributes) (dynamic) /></programlisting></para> +<para>This rule has no specific attributes. Child rules are typically +used to detect combinations of <userinput>L</userinput> and +<userinput>U</userinput> after the number, indicating the integer type +in program code. Actually all rules are allowed as child rules, though, +the <acronym>DTD</acronym> only allowes the child rule <userinput>StringDetect</userinput>.</para> +<para>The following example matches integer numbers follows by the character 'L'. +<programlisting> +<Int attribute="Decimal" context="#stay" > + <StringDetect attribute="Decimal" context="#stay" String="L" insensitive="true"/> +</Int> +</programlisting></para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Float</term> +<listitem> +<para>Detect a floating point number.</para> +<para><programlisting><Float (common attributes) /></programlisting></para> +<para>This rule has no specific attributes. <userinput>AnyChar</userinput> is +allowed as a child rules and typically used to detect combinations, see rule +<userinput>Int</userinput> for reference.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCOct</term> +<listitem> +<para>Detect an octal point number representation.</para> +<para><programlisting><HlCOct (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCHex</term> +<listitem> +<para>Detect a hexadecimal number representation.</para> +<para><programlisting><HlCHex (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCStringChar</term> +<listitem> +<para>Detect an escaped character.</para> +<para><programlisting><HlCStringChar (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> + +<para>It matches literal representations of characters commonly used in +program code, for example <userinput>\n</userinput> +(newline) or <userinput>\t</userinput> (TAB).</para> + +<para>The following characters will match if they follow a backslash +(<literal>\</literal>): +<userinput>abefnrtv"'?\</userinput>. Additionally, escaped +hexadecimal numbers like for example <userinput>\xff</userinput> and +escaped octal numbers, for example <userinput>\033</userinput> will +match.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>HlCChar</term> +<listitem> +<para>Detect an C character.</para> +<para><programlisting><HlCChar (common attributes) /></programlisting></para> +<para>This rule has no specific attributes.</para> + +<para>It matches C characters enclosed in a tick (Example: <userinput>'c'</userinput>). +So in the ticks may be a simple character or an escaped character. +See HlCStringChar for matched escaped character sequences.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>RangeDetect</term> +<listitem> +<para>Detect a string with defined start and end characters.</para> +<programlisting><RangeDetect char="(character)" char1="(character)" (common attributes) /></programlisting> +<para><userinput>char</userinput> defines the character starting the range, +<userinput>char1</userinput> the character ending the range.</para> +<para>Usefull to detect for example small quoted strings and the like, but +note that since the highlighting engine works on one line at a time, this +will not find strings spanning over a line break.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>LineContinue</term> +<listitem> +<para>Matches at end of line.</para> +<programlisting><LineContinue (common attributes) /></programlisting> +<para>This rule has no specific attributes.</para> +<para>This rule is useful for switching context at end of line, if the last +character is a backslash (<userinput>'\'</userinput>). This is needed for +example in C/C++ to continue macros or strings.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>IncludeRules</term> +<listitem> +<para>Include rules from another context or language/file.</para> +<programlisting><IncludeRules context="contextlink" [includeAttrib="true|false"] /></programlisting> + +<para>The <userinput>context</userinput> attribute defines which context to include.</para> +<para>If it a simple string it includes all defined rules into the current context, example: +<programlisting><IncludeRules context="anotherContext" /></programlisting></para> + +<para> +If the string begins with <userinput>##</userinput> the highlight system +will look for another language definition with the given name, example: +<programlisting><IncludeRules context="##C++" /></programlisting></para> +<para>If <userinput>includeAttrib</userinput> attribute is +<emphasis>true</emphasis>, change the destination attribute to the one of +the source. This is required to make for example commenting work, if text +matched by the included context is a different highlight than the host +context. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>DetectSpaces</term> +<listitem> +<para>Detect whitespaces.</para> +<programlisting><DetectSpaces (common attributes) /></programlisting> + +<para>This rule has no specific attributes.</para> +<para>Use this rule if you know that there can several whitespaces ahead, +for example in the beginning of indented lines. This rule will skip all +whitespace at once, instead of testing multiple rules and skipping one at the +time due to no match.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>DetectIdentifier</term> +<listitem> +<para>Detect identifier strings (as a regular expression: [a-zA-Z_][a-zA-Z0-9_]*).</para> +<programlisting><DetectIdentifier (common attributes) /></programlisting> + +<para>This rule has no specific attributes.</para> +<para>Use this rule to skip a string of word characters at once, rather than +testing with multiple rules and skipping one at the time due to no match.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2> +<title>Tips & Tricks</title> + +<itemizedlist> +<para>Once you have understood how the context switching works it will be +easy to write highlight definitions. Though you should carefully check what +rule you choose in what situation. Regular expressions are very mighty, but +they are slow compared to the other rules. So you may consider the following +tips. +</para> + +<listitem> +<para>If you only match two characters use <userinput>Detect2Chars</userinput> +instead of <userinput>StringDetect</userinput>. The same applies to +<userinput>DetectChar</userinput>.</para> +</listitem> +<listitem> +<para>Regular expressions are easy to use but often there is another much +faster way to achieve the same result. Consider you only want to match +the character <userinput>'#'</userinput> if it is the first character in the +line. A regular expression based solution would look like this: +<programlisting><RegExpr attribute="Macro" context="macro" String="^\s*#" /></programlisting> +You can achieve the same much faster in using: +<programlisting><DetectChar attribute="Macro" context="macro" char="#" firstNonSpace="true" /></programlisting> +If you want to match the regular expression <userinput>'^#'</userinput> you +can still use <userinput>DetectChar</userinput> with the attribute <userinput>column="0"</userinput>. +The attribute <userinput>column</userinput> counts character based, so a tabulator still is only one character. +</para> +</listitem> +<listitem> +<para>You can switch contexts without processing characters. Assume that you +want to switch context when you meet the string <userinput>*/</userinput>, but +need to process that string in the next context. The below rule will match, and +the <userinput>lookAhead</userinput> attribute will cause the highlighter to +keep the matched string for the next context. +<programlisting><Detect2Chars attribute="Comment" context="#pop" char="*" char1="/" lookAhead="true" /></programlisting> +</para> +</listitem> +<listitem> +<para>Use <userinput>DetectSpaces</userinput> if you know that many whitespaces occur.</para> +</listitem> +<listitem> +<para>Use <userinput>DetectIdentifier</userinput> instead of the regular expression <userinput>'[a-zA-Z_]\w*'</userinput>.</para> +</listitem> +<listitem> +<para>Use default styles whenever you can. This way the user will find a familiar environment.</para> +</listitem> +<listitem> +<para>Look into other XML-files to see how other people implement tricky rules.</para> +</listitem> +<listitem> +<para>You can validate every XML file by using the command +<command>xmllint --dtdvalid language.dtd mySyntax.xml</command>.</para> +</listitem> +<listitem> +<para>If you repeat complex regular expression very often you can use +<emphasis>ENTITIES</emphasis>. Example:</para> +<programlisting> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE language SYSTEM "language.dtd" +[ + <!ENTITY myref "[A-Za-z_:][\w.:_-]*"> +]> +</programlisting> +<para>Now you can use <emphasis>&myref;</emphasis> instead of the regular +expression.</para> +</listitem> +</itemizedlist> +</sect2> + +</sect1> + +</appendix> diff --git a/doc/kate/index.docbook b/doc/kate/index.docbook new file mode 100644 index 000000000..fe409a83d --- /dev/null +++ b/doc/kate/index.docbook @@ -0,0 +1,293 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kate;"> + <!ENTITY package "kdebase"> + <!ENTITY configuring-chapter SYSTEM "configuring.docbook"> + <!ENTITY highlighting-appendix SYSTEM "highlighting.docbook"> + <!ENTITY advanced-chapter SYSTEM "advanced.docbook"> + <!ENTITY fundamentals-chapter SYSTEM "fundamentals.docbook"> + <!ENTITY mdi-chapter SYSTEM "mdi.docbook"> + <!ENTITY menu-chapter SYSTEM "menus.docbook"> + <!ENTITY part-chapter SYSTEM "part.docbook"> + <!ENTITY plugins-chapter SYSTEM "plugins.docbook"> + <!ENTITY regexp-appendix SYSTEM "regular-expressions.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> +<title>The &kate; Handbook</title> + +<bookinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<author>&Seth.Rothberg; &Seth.Rothberg.mail;</author> +<author>&Dominik.Haumann; &Dominik.Haumann.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2000</year> +<year>2001</year> +<holder>&Seth.Rothberg;</holder> +</copyright> +<copyright> +<year>2002</year><year>2003</year><year>2005</year> +<holder>&Anders.Lund;</holder> +</copyright> +<copyright> +<year>2005</year> +<holder>&Dominik.Haumann;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-12-29</date> +<releaseinfo>2.5.0</releaseinfo> + +<abstract> +<para>&kate; is a programmer's text editor for &kde; 2.2 and above.</para> + +<para>This handbook documents &kate; Version 2.5.0</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdebase</keyword> +<keyword>Kate</keyword> +<keyword>text</keyword> +<keyword>editor</keyword> +<keyword>programmer</keyword> +<keyword>programming</keyword> +<keyword>projects</keyword> +<keyword>MDI</keyword> +<keyword>Multi</keyword> +<keyword>Document</keyword> +<keyword>Interface</keyword> +<keyword>terminal</keyword> +<keyword>console</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +Welcome to &kate;, a programmer's text editor for &kde; version 2.2 and +above. Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +<acronym>HTML</acronym> to bash scripts, the ability to create and +maintain projects, a multiple document interface +(<acronym>MDI</acronym>), and a self-contained terminal emulator. +</para> + +<para> +But &kate; is more than a programmer's editor. Its ability to open +several files at once makes it ideal for editing &UNIX;'s many +configuration files. This document was written in &kate;. +</para> + +<para> +<mediaobject> +<imageobject><imagedata format="PNG" fileref="kate.png"/></imageobject> +<caption><para>Editing this manual...</para></caption> +</mediaobject> +</para> + +</chapter> + +&fundamentals-chapter; + +&mdi-chapter; + +&part-chapter; + +&plugins-chapter; + +&advanced-chapter; + +&menu-chapter; + +&configuring-chapter; + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kate;. Program copyright 2000, 2001, 2002 - 2005 by the &kate; developer team. +</para> + +<variablelist> +<title>The &kate; team:</title> +<varlistentry> +<term>&Christoph.Cullmann; &Christoph.Cullmann.mail;</term> +<listitem><para>Project Manager & Core Developer</para></listitem> +</varlistentry> +<varlistentry> +<term>&Anders.Lund; &Anders.Lund.mail;</term> +<listitem><para>Core Developer, Perl syntax highlighting, +documentation</para></listitem> +</varlistentry> +<varlistentry> +<term>&Joseph.Wenninger; &Joseph.Wenninger.mail;</term> +<listitem><para>Core Developer, syntax highlighting</para></listitem> +</varlistentry> +<varlistentry> +<term>Michael Bartl <email>[email protected]</email></term> +<listitem><para>Core Developer</para></listitem> +</varlistentry> +<varlistentry> +<term>Phlip <email>[email protected]</email></term> +<listitem><para>The project compiler</para></listitem> +</varlistentry> +<varlistentry> +<term>&Waldo.Bastian; &Waldo.Bastian.mail;</term> +<listitem><para>The cool buffer system</para></listitem> +</varlistentry> +<varlistentry> +<term>Matt Newell <email>[email protected]</email></term> +<listitem><para>Testing...</para></listitem> +</varlistentry> +<varlistentry> +<term>Michael McCallum <email>[email protected]</email></term> +<listitem><para>Core Developer</para></listitem> +</varlistentry> +<varlistentry> +<term>Jochen Wilhemly <email>[email protected]</email></term> +<listitem><para>KWrite Author</para></listitem> +</varlistentry> +<varlistentry> +<term>&Michael.Koch; &Michael.Koch.mail;</term> +<listitem><para>KWrite port to KParts</para></listitem> +</varlistentry> +<varlistentry> +<term>Christian Gebauer <email>[email protected]</email></term> +<listitem><para>Unspecified</para></listitem> +</varlistentry> +<varlistentry> +<term>&Simon.Hausmann; &Simon.Hausmann.mail;</term> +<listitem><para>Unspecified</para></listitem> +</varlistentry> +<varlistentry> +<term>Glen Parker <email>[email protected]</email></term> +<listitem><para>KWrite Undo History, KSpell integration</para></listitem> +</varlistentry> +<varlistentry> +<term>Scott Manson <email>[email protected]</email></term> +<listitem><para>KWrite XML syntax highlighting support</para></listitem> +</varlistentry> +<varlistentry> +<term>&John.Firebaugh; &John.Firebaugh.mail;</term> +<listitem><para>Various Patches</para></listitem> +</varlistentry> +<varlistentry> +<term>&Dominik.Haumann; &Dominik.Haumann.mail;</term> +<listitem><para>Developer, Highlight wizard</para></listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>Many other people have contributed:</title> +<varlistentry> +<term>Matteo Merli <email>[email protected]</email></term> +<listitem><para>Highlighting for RPM Spec-Files, Diff and more</para></listitem> +</varlistentry> +<varlistentry> +<term>Rocky Scaletta <email>[email protected]</email></term> +<listitem><para>Highlighting for VHDL</para></listitem> +</varlistentry> +<varlistentry> +<term>Yury Lebedev </term> +<listitem><para>Highlighting for SQL</para></listitem> +</varlistentry> +<varlistentry> +<term>Chris Ross</term> +<listitem><para>Highlighting for Ferite</para></listitem> +</varlistentry> +<varlistentry> +<term>Nick Roux</term> +<listitem><para>Highlighting for ILERPG</para></listitem> +</varlistentry> +<varlistentry> +<term>John Firebaugh</term> +<listitem><para>Highlighting for Java, and much more</para></listitem> +</varlistentry> +<varlistentry> +<term>Carsten Niehaus</term> +<listitem><para>Highlighting for LaTeX</para></listitem> +</varlistentry> +<varlistentry> +<term>Per Wigren</term> +<listitem><para>Highlighting for Makefiles, Python</para></listitem> +</varlistentry> +<varlistentry> +<term>Jan Fritz</term> +<listitem><para>Highlighting for Python</para></listitem> +</varlistentry> +<varlistentry> +<term>&Daniel.Naber;</term> +<listitem><para>Small bugfixes, XML plugin</para></listitem> +</varlistentry> +</variablelist> + +<para>Documentation copyright 2000,2001 &Seth.Rothberg; +&Seth.Rothberg.mail;</para> + +<para>Documentation copyright 2002, 2003, 2005 &Anders.Lund; +&Anders.Lund.mail;</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> +&underGPL; <!-- GPL License --> + +</chapter> + +&highlighting-appendix; + +®exp-appendix; + +<appendix id="installation"> +<title>Installation</title> + +&install.intro.documentation; + +&install.compile.documentation; + +</appendix> + +&documentation.index; + +<!-- +Index Word List: +menu - context - syntax - markup - shortcuts - highlighting +embedded terminal - editing - search - replace - regexp -> Regular Expression +split window - selection - insert overwrite - selection - +configure/customize/preferences - insert/overwrite - non-printing characters +font - unicode - wordwrap/linewrap - project - bookmarks - docks - plugins +block selection / rectangles - view - indenting - editor - word processor +copy - paste - find - spelling - language (both kinds) - encoding - +pretty printing - formatting - line numbers - icon border - +folding - insert time - sed + +done +comment / uncomment +configure / settings / preferences + +--> + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-namecase-general: t +sgml-namecase-entity: nil +sgml-general-insert-case: lower +sgml-minimize-attributes: nil +sgml-omittag: nil +End: +--> diff --git a/doc/kate/kate.png b/doc/kate/kate.png Binary files differnew file mode 100644 index 000000000..dc1ee4c40 --- /dev/null +++ b/doc/kate/kate.png diff --git a/doc/kate/man-kate.1.docbook b/doc/kate/man-kate.1.docbook new file mode 100644 index 000000000..80899a4fb --- /dev/null +++ b/doc/kate/man-kate.1.docbook @@ -0,0 +1,165 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<title>KDE User's Manual</title> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<date>June 07, 2005</date> +<productname>K Desktop Environment</productname> +</refentryinfo> + +<refmeta> +<refentrytitle><command>kate</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>kate</command></refname> +<refpurpose>Advanced text editor for &kde;</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>kate</command> +<group choice="opt"><option>-s, --start</option> <replaceable> +name</replaceable> </group> +<group choice="opt"><option>-u, --use</option></group> +<group choice="opt"><option>-p, --pid</option><replaceable> +pid</replaceable></group> +<group choice="opt"><option>-e, --encoding</option> <replaceable> +name</replaceable></group> +<group choice="opt"><option>-l, --line</option> <replaceable> +line</replaceable></group> +<group choice="opt"><option>-c, --column</option> +<replaceable> column</replaceable></group> +<group choice="opt"><option>-i, --stdin</option></group> +<arg choice="opt">KDE Generic Options</arg> +<arg choice="opt">Qt Generic Options</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para>&kate; is the &kde; Advanced Text Editor. </para> +<para>&kate; also provides the editor part for various applications, under +the name &kwrite;.</para> +<para>Some of &kate;'s many features include configurable syntax +highlighting for languages ranging from C and C++ to +<acronym>HTML</acronym> to bash scripts, the ability to create and +maintain projects, a multiple document interface +(<acronym>MDI</acronym>), and a self-contained terminal emulator. +</para> + +<para> +But &kate; is more than a programmer's editor. Its ability to open +several files at once makes it ideal for editing &UNIX;'s many +configuration files. This document was written in &kate;. +</para> + + +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>-s</option>, <option>--start</option> <replaceable>name</replaceable></term> + +<listitem><para>Start &kate; with a given session.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-u, --use</option></term> +<listitem><para>Use an already running &kate;</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-p, --pid</option> <replaceable> +pid</replaceable></term> +<listitem><para>Only try to reuse kate instance with this +<replaceable>pid</replaceable></para></listitem> +</varlistentry> +<varlistentry> +<term><option>-e, --encoding</option> <replaceable> +name</replaceable></term> +<listitem><para>Set encoding for the file to open</para><para>You can use +this to force a file opened in utf-8 format, for instance. (The command +<command>iconv -l</command> provides a list of encodings, which may be +helpful to you.)</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-l, --line</option> <replaceable> line</replaceable></term> +<listitem><para>Navigate to this line</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-c, --column</option> <replaceable> +column</replaceable></term> +<listitem><para>Navigate to this column</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-i, --stdin</option></term> +<listitem><para>Read the contents of +<filename>stdin</filename></para></listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>kwrite(1)</para> + +<para>More detailed user documentation is available from <ulink +url="help:/kate">help:/kate</ulink> +(either enter this <acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kate</parameter></userinput>).</para> + +<para>There is also further information available at <ulink +url="http://kate.kde.org/">the &kate; website</ulink>.</para> +</refsect1> + +<refsect1> +<title>Examples</title> + +<para>To open a file named <filename>source.cpp</filename> at column 15, +line 25, in an existing &kate; window, you could use:</para> +<screen><userinput><command>kate</command> <option>-c 15</option> <option>-l +25</option> <option>-u</option> <filename>source.cpp</filename></userinput> </screen> + +<para>If you have an active internet connection, you can take advantage of +&kde;'s network transparency to open a file from an ftp site. If you do not +have write permission on the remote server, the file will be opened read +only and you will be prompted for a local filename to save to if you make +changes. If you do have write permission, changes will be saved +transparently over the network.</para> +<screen><userinput><command>kate</command> <option><replaceable>ftp://ftp.kde.org/pub/kde/README_FIRST</replaceable></option></userinput></screen> + +<!-- FIXME: Some more useful examples would be cool, how about this snagged --> +<!-- from a mail of anders (slightly edited /line/l to remove the double --> +<!-- dashes: + +> /some/file/path/file.name:lineno +> it would rock if Kate could understand that and not only open up file.name, +> but jump to lineno after the file is opened. + +How bad is it to have to convert that into +-l lineno /some/file/path/file.name + +sed s,([^:]*):(\d+),-l \2 \1, + +will do that, for example.--> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para>The maintainer of &kate; is &Christoph.Cullmann; +&Christoph.Cullmann.mail;. A comprehensive list of authors and contributors +is available in the complete user manual mentioned above.</para> +</refsect1> + +</refentry> diff --git a/doc/kate/mdi.docbook b/doc/kate/mdi.docbook new file mode 100644 index 000000000..a6c6854db --- /dev/null +++ b/doc/kate/mdi.docbook @@ -0,0 +1,266 @@ +<chapter id="kate-mdi"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Working With the &kate; <acronym>MDI</acronym></title> + +<sect1 id="kate-mdi-overview"> +<title>Overview</title> + +<para>Window, View, Document, Frame, Editor... What are they all in +the terminology of &kate;, and how do you get the most out of it? This +chapter will explain all of that, and even more.</para> + +<sect2 id="kate-mdi-overview-mainwindow"> + +<title>The Main Window</title> + +<para><indexterm><primary>Main window</primary></indexterm> +The &kate; Main Window is a standard &kde; application window, +with the addition of side bars containing tool views. It has a +Menubar with all the common menus, and some more, and a toolbar +providing access to commonly used commands.</para> + +<para>The most important part of the window is the Editing Area, by +default displaying a single text editor component, in which you can +work with your documents.</para> + +<para>The docking capabilities of the window is used for the tool +windows:</para> + +<itemizedlist> +<listitem><para><link linkend="kate-mdi-tools-file-list">The File List</link></para></listitem> +<listitem><para><link linkend="kate-mdi-tools-file-selector">The Filesystem +Browser</link></para></listitem> +<listitem><para><link linkend="kate-mdi-tools-konsole">The Built in Terminal Emulator</link></para></listitem> +</itemizedlist> + +<para>And possibly other tool views, for example provided by +plugins.</para> + +<para>Tool views can be positioned in any sidebar, to move a tool right click +its sidebar button and select from the &RMB; menu</para> + +<para>A tool view can be marked as <emphasis>persistent</emphasis> in the &RMB; +menu for its sidebar button. The sidebar can contain +more tools at one time so that when a tool is persistant other tools can be +shown simultaneously.</para> + +</sect2> + + +</sect1> + +<sect1 id="kate-mdi-editor"> + +<title>The Editor area</title> + +<para><indexterm><primary>Editing Area</primary></indexterm> +&kate; is capable of having more than one document open at the +same time, and also of splitting the editing area into any number of +frames, similar to how for example &konqueror; or the popular +<application>emacs</application> text editor works. This way you can +view several documents at the same time, or more instances of the same +document, handy for example if your document contains definitions in +the top that you want to see often for reference. Or you could view a +program source header in one frame, while editing the implementation +file in another.</para> + +<para>When a document is available in more than one editor, changes +made in one editor will immediately be reflected in the others as +well. This includes changing the text as well as selecting +text. Search operations or cursor movement is only reflected in the +current editor.</para> + +<para>It is currently not possible to have more instances of the same +document open in the sense that one instance will be edited while the +other will not.</para> + +<para>When splitting an editor into two frames, it is divided into two +equally sized frames, both displaying the current document of that +editor. The new frame will be at the bottom (in the case of a +horizontal split) or at the right (for a vertical split). The new +frame gets the focus, which is visualized by a small green led in the +focused frame.</para> + +</sect1> + +<sect1 id="kate-mdi-tools-file-list"> +<title>The Document List</title> + +<para><indexterm><primary>File list</primary></indexterm> +The file list displays a list of all documents currently open in +&kate;. Modified files will have a small <guiicon>floppy +disk</guiicon> icon on their left to indicate that state.</para> + +<para>If two or more files with the same name (located in different +folders) are open, the names of the second will be prepended +<quote><2></quote> and so on. The tool-tip for the file will +display its full name including the path, allowing you to choose the +desired one.</para> <para>To display a document in the currently +active frame, click the document name in the list.</para> + +<para>You can sort the list in a few different ways by rightclicking the +list and selecting from the <guisubmenu>Sort By</guisubmenu> menu. + +The options are +<variablelist> + +<varlistentry> +<term><guimenuitem>Opening Order</guimenuitem></term> +<listitem><para>Lists the documents in the order of opening</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Document Name</guimenuitem></term> +<listitem><para>Lists the documents alphabetically by their name.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>URL</guimenuitem></term> +<listitem><para>Lists the documents alphabetically by URL.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +<para>The document list will pr default visualize your history by shading the +entries for the most recent documents with a background color. If the document +was edited, an extra color is blended in. The most recent document has the +strongest color, so that you can easily find the documents you are working on. +This feature can be disabled in +<link linkend="config-dialog-documentlist">The Document List Page</link> +of the configuration dialog.</para> + +<para>The default location in the &kate; window is to the left of the +editing area.</para> +</sect1> + +<sect1 id="kate-mdi-tools-file-selector"> +<title>The Filesystem Browser</title> + +<para><indexterm><primary>Filesystem Browser</primary></indexterm> +The Filesystem Browser is a folder viewer, allowing you to open +files from a displayed folder in the current frame.</para> + +<para>From top down, the Filesystem Browser consist of the following +elements:</para> + +<variablelist> +<varlistentry> +<term>A Toolbar</term> +<listitem> +<para>This contains standard navigations tool buttons:</para> +<variablelist> +<varlistentry> +<term><guibutton>Home</guibutton></term> +<listitem><para>Pressing it will cause the folder view to <command>cd</command> to your home folder.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Up</guibutton></term> +<listitem><para>This will cause the folder view to <command>cd</command> to the immediate parent of the currently displayed +folder if possible.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Back</guibutton></term> +<listitem><para>Causes the folder view to <command>cd</command> to the previously displayed folder in the history. +This button is disabled, if there is no previous item.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Forward</guibutton></term> +<listitem><para>Causes the folder view to <command>cd</command> to the next folder in the history. +This button is disabled, if there is no next folder.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Sync</guibutton></term> +<listitem><para>This button will cause the folder view to +<command>cd</command> to the folder of the currently active +document if possible. This button is disabled, if the active document +is a new, unsaved file, or the folder in which it resides can not +be decided.</para></listitem> +</varlistentry> +</variablelist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>A &URL; entry</term> +<listitem> +<para>Here you can type the path of a folder to browse. The &URL; +entry maintains a list of previously typed paths. To choose one use +the arrow button to the right of the entry.</para> +<tip><para>The &URL; entry has folder auto-completion. The completion +method can be set using the &RMB; menu of the text +entry.</para></tip> +</listitem> +</varlistentry> + +<varlistentry> +<term>A Folder View</term> +<listitem><para>This is a standard &kde; folder view.</para></listitem> +</varlistentry> + +<varlistentry> +<term>A Filter Entry</term> +<listitem> +<para>The Filter entry allows you to enter a filter for the files +displayed in the folder view. The filter uses standard globs; patterns +must be separated by white space. Example: <userinput>*.cpp *.h +*.moc</userinput></para> +<para>To display all files, enter a single asterisk +<userinput>*</userinput>.</para> +<para>The filter entry saves the last 10 filters entered between +sessions, to use one, press the arrow button on the right of the entry +and select the desired filter string.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + + +<sect1 id="kate-mdi-tools-konsole"> +<title>The Built in Terminal Emulator</title> + +<para><indexterm><primary>Terminal emulator</primary></indexterm> +The built in Terminal Emulator is a copy of the &kde; &konsole; +terminal application, for your convenience. It is available from the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Show Terminal +Emulator</guimenuitem></menuchoice> menu item or by pressing the <keycombo +action="simul"><keycap>F7</keycap></keycombo> key, and will get the focus +whenever displayed. Additionally, if the <link +linkend="config-dialog-general-sync-konsole">Sync &konsole; with +active document</link> option is enabled, it will +change into the directory of the current document if +possible when it is displayed, or when the current document +changes.</para> + +<para>The default location in the &kate; window is at the bottom, +below the editing area.</para> + +<para>You can configure the &konsole; using its &RMB; menu, for more +information, see the &konsole; manual.</para> + +</sect1> + +<sect1 id="kate-mdi-tools-externaltools"> +<title>External Tools</title> + +<para>In the <guimenu>Tools</guimenu> menu you will find a submenu labeled +<guisubmenu>External Tools</guisubmenu>. These tools invokes external +applications with data related to the current document, for example its URL, +directory, text or selection.</para> + +<para>External tools are user defined, you can add, edit or remove tools using +the <link linkend="config-dialog-externaltools">External Tools configuration panel</link>. +</para> + +</sect1> + +</chapter> diff --git a/doc/kate/menus.docbook b/doc/kate/menus.docbook new file mode 100644 index 000000000..26ae7551e --- /dev/null +++ b/doc/kate/menus.docbook @@ -0,0 +1,1438 @@ +<chapter id="menu-entries"> +<chapterinfo> +<authorgroup> +<author><personname><firstname></firstname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Menu Entries</title> + +<sect1 id="file-menu"> +<title>The <guimenu>File</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term> +<anchor id="new"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>starts a new document</action> in the editing +window. In the <guibutton>Documents</guibutton> list on the left the new file +is named <emphasis>Untitled</emphasis>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="open"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launches &kde;'s open file dialog box to let you open one or more files. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="open-recent"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Open Recent</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command allows you to <action>open a file</action> from a submenu +that contains a list of recently edited files. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="open-with"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Open With</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This submenu presents a list of applications known to handle the mime type +of your current document. Activating an entry will open the current document +with that application.</para> +<para>In addition, a entry <guimenuitem>Other...</guimenuitem> command launches +the open with dialog box that allows you to <action>select another application +to open the active file</action>. Your file will still be open in &kate;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="save"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>saves your file</action>. Use it often. If the file is +<emphasis>Untitled</emphasis> then +<guimenuitem>Save</guimenuitem> becomes +<guimenuitem>Save As</guimenuitem>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="save-as"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Name and rename files</action> with this command. +It launches the save file dialog box. This dialog works just as +the open file dialog box does. You can use it to navigate through +your file system, preview existing files, or filter your file +view with file masks. +</para> + +<para> +Type the name you want to give the file you are saving in the +Location combo box and press the +<guibutton>OK</guibutton> button. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="save-all"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>L</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>saves all modified open files</action>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="reload"/> +<menuchoice> +<shortcut> +<keycombo action="simul"><keycap>F5</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Reload</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Reloads the active file</action>. This command is +useful if another program or process has changed the file while you have +it open in &kate; +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="print"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Print the active file</action>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="export-as-html"> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Export as HTML...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Export your file in HTML format so your document can be viewed as a +web page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="mail"> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Mail...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Open your mail client and attach the file in the mail. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="close"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Close</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Close the active file</action> with this command. If you +have made unsaved changes, you will be prompted to save +the file before &kate; closes it. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="close-all"/> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Close All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>closes all the files you have open</action> +in &kate;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="quit"/> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command <action>closes &kate;</action> and any files you were +editing. If you have made unsaved changes to any of the files you were +editing, you will be prompted to save them. +</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="edit-menu"> +<title>The <guimenu>Edit</guimenu> Menu</title> +<para>The <guimenu>Edit</guimenu> menu contains a host of commands, +all to work with the currently active document.</para> + +<variablelist> +<title>Menu Entries</title> +<varlistentry> +<term> +<anchor id="edit-undo"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Undo</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Undo the last editing command (typing, copying, cutting etc.)</para> +<note><para>If grouped undo is enabled, this may undo several editing commands of the same type, like typing in characters.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-redo"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Redo</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Redo the last undo step.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-cut"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Cut</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Removes selected text if any, and places a copy of the removed text in the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-copy"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Copies selected text, if any, to the clipboard.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-copy-as-html"/> +<menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Copy as HTML</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Copies selected text with the syntax highlight as HTML text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-paste" /> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Copies the first item in the clipboard into the editor at cursor position.</para> +<note><para>If Overwrite Selection is enabled, the pasted text will overwrite the selection, if any.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-select-all"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Select All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Selects all text in the editor.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-deselect"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Deselect</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Deselects the selected text in the editor if any.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-toggle-block-selection"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>Shift</keycap> +<keycap>B</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Block Selection Mode</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggles Selection Mode. When the Selection Mode is <quote>BLOCK</quote>, you can make vertical selections, +ie select column 5 to 10 in lines 9 to 15.</para> +<para>The status bar shows the current state of the Selection Mode, either <quote>NORM</quote> or <quote>BLK</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-find"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launch the Find Dialog to allow you to search for text in the edited document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-find-next"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F3</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find Next</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Go to the nearest downwards match of the last text or regular expression searched for, starting from cursor position</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-find-previous"/> +<menuchoice> +<shortcut><keycombo action="simul">&Shift;<keycap>F3</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find Previous</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Go to the nearest upwards match of the last text or regular expression searched for, starting from cursor position</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-replace"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Replace...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launch the Replace Dialog to replace one or more instances of a defined text with something else.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="edit-go-to-line"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Go to line...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launches the Go To Line Dialog, allowing you to enter the number of a line to find in +the document</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="document-menu"> +<title>The <guimenu>Document</guimenu> Menu</title> +<para>The Document menu provides a menu entry for each open document. +Clicking one of these will bring the requested document to focus. If you have +multiple frames, an editor for that document will be displayed in the currently +active frame.</para> +<para>In addition, commands to browse your open documents are provided: +<variablelist> +<title>Menu items</title> + +<varlistentry> +<term> +<anchor id="document-back"/> +<menuchoice> +<shortcut><keycombo action="simul">&Alt;<keycap>Left</keycap></keycombo></shortcut> +<guimenu>Document</guimenu> +<guimenuitem>Back</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This will bring the previous document in the stack in focus. If you have +multiple frames, an editor for the document will be displayed in the currently +active frame.</para> <para>The order is the order in which documents were +opened, rather than a logical history. This behavior may change in future +versions of &kate;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="document-forward"/> +<menuchoice> +<shortcut><keycombo action="simul">&Alt;<keycap>Right</keycap></keycombo></shortcut> +<guimenu>Document</guimenu> +<guimenuitem>Forward</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This will bring the next document in the stack in focus. If you have +multiple frames, an editor for the document will be displayed in the currently +active frame.</para> +<para>The order is the order in which the documents were opened, +rather than a logical history. This behavior may change in future versions of +&kate;.</para> +</listitem> +</varlistentry> +</variablelist> +</para> +</sect1> + +<sect1 id="view-menu"> +<title>The <guimenu>View</guimenu> menu</title> + +<para>The <guimenu>View</guimenu> menu allows you to manage settings +specific to the active editor, and to manage frames.</para> + +<variablelist> +<title>Menu Items</title> + +<varlistentry> +<term><menuchoice><shortcut><keycap>F7</keycap></shortcut> +<guimenu>View</guimenu><guimenuitem>Switch to Command Line</guimenuitem> +</menuchoice></term> +<listitem><para>This command will toggle the display of the +<link linkend="advanced-editing-tools-commandline">built in command line</link>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guisubmenu>Schema</guisubmenu> +</menuchoice></term> +<listitem><para>This menu lists the available schemas. You can change the schema +for the current view here, to change the default schema you need to +use the <link linkend="config-dialog-editor-colors">config dialog</link></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>F10</keycap> +</keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Dynamic Word Wrap</guimenuitem></menuchoice> +</term> +<listitem><para>Toggles dynamic word wrap in the current view. Dynamic word +wrap makes all the text in a view visible without the need for horizontal +scrolling by rendering one actual line on more visual lines as needed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Show/Hide Static Word +Wrap Marker</guimenuitem></menuchoice></term> +<listitem><para>Toggles the display of a vertical line indicating the position +of the wrap width as configured in the <link +linkend="config-dialog-editor-wrap-words-at">config dialog</link>. This +feature requires that you use a true fixed-width font.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-show-icon-border"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F6</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Show/Hide Icon Border</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This is a toggle item. Setting it on checked will make the Icon Border +visible in the left side of the active editor, and vice versa.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-show-line-numbers"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F11</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Show/Hide Line Numbers</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This is a toggle Item. Setting it on checked will make a pane displaying +the line numbers of the document visible in the left border of the active editor, +and vice versa.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Show/Hide Scrollbar +Marks</guimenuitem></menuchoice></term> +<listitem><para>Toggles the visualization of bookmarks (and other marks) on the +vertical scrollbar. When enabled, marks are represented by a thin line in the +mark color at the scrollbar, middleclicking on the lines will scroll the view +to a position near the mark.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>F9</keycap> +</keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Show/Hide Folding Markers</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the display of the folding marker pane in the left +side of the view. See <link linkend="advanced-editing-tools-code-folding">Using +Code Folding</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-code-folding"/> +<menuchoice> +<guimenuitem>Code Folding</guimenuitem> +</menuchoice> +</term> + +<listitem> +<variablelist> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>Shift</keycap><keycap>-</keycap></keycombo></shortcut> +<guimenuitem>Collapse Toplevel</guimenuitem></menuchoice> +</term> +<listitem><para>Collapse all toplevel regions in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>Shift</keycap><keycap>+</keycap></keycombo></shortcut> +<guimenuitem>Expand Toplevel</guimenuitem></menuchoice> +</term> +<listitem><para>Expand all toplevel regions in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>-</keycap></keycombo></shortcut> +<guimenuitem>Collapse One Local Level</guimenuitem></menuchoice> +</term> +<listitem><para>Collapse the region closest to the cursor.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl; +<keycap>+</keycap></keycombo></shortcut> +<guimenuitem>Expand One Local Level</guimenuitem></menuchoice> +</term> +<listitem><para>Expand the region closest to the cursor.</para></listitem> +</varlistentry> +</variablelist> +</listitem> + +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="bookmarks-menu"> +<title>The <guimenu>Bookmarks</guimenu> Menu</title> + +<para>The <guimenu>Bookmarks</guimenu> menu allows you to work with +the bookmarks in the currently active document.</para> + +<para>Below the entries described here, one entry for each bookmark in +the active document will be available. The text will be the first few +words of the marked line. Choose an item to move the cursor to the +start of that line. The editor will scroll as necessary to make that +line visible.</para> + +<variablelist> + +<title>Menu Items</title> + +<varlistentry> +<term> +<anchor id="bookmarks-toggle-bookmark"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Set/Clear Bookmark</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Sets or removes a bookmark in the current line of the active document. +(If it's there, it is removed, otherwise one is set.)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="bookmarks-clear-bookmarks"/> +<menuchoice> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Clear All Bookmarks</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Clears (removes) all bookmarks in the active document.</para> +</listitem> +</varlistentry> + +<varlistentry id="bookmarks-previous"> +<term><menuchoice><shortcut><keycombo action="simul">&Alt; +<keycap>Page Up</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu><guimenuitem>Previous</guimenuitem></menuchoice> +</term> +<listitem><para>This will move the cursor to beginning of the first above line +with a bookmark. The menuitem text will include the line number and the first +piece of text on the line. This item is only available when there is a bookmark +in a line above the cursor.</para></listitem> +</varlistentry> + +<varlistentry id="bookmarks-next"> +<term><menuchoice><shortcut><keycombo action="simul">&Alt; +<keycap>Page Down</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu><guimenuitem>Next</guimenuitem></menuchoice></term> +<listitem><para>This will move the cursor to beginning of the next line with a +bookmark. The menuitem text will include the line number and the first piece of +text on the line. This item is only available when there is a bookmark in a line +below the cursor.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="tools-menu"> + +<title>The <guimenu>Tools</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice><guimenu>Tools</guimenu><guimenuitem>Pipe to +Console</guimenuitem></menuchoice></term> +<listitem><para>Feed the currently selected text ito the built in terminal +emulator. No newline is added after the text.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Tools</guimenu><guisubmenu>External +Tools</guisubmenu></menuchoice></term> +<listitem><para>This submenu contains all the <link +linkend="kate-mdi-tools-externaltools">external tools</link>you have +configured.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-read-only"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Read Only Mode</guimenuitem></menuchoice></term> +<listitem> +<para>Set the current document to Read Only mode. This prevents any text +addition and any changes in the document formatting.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-filetype"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Filletype</guimenuitem></menuchoice></term> +<listitem> +<para>Choose the filetype scheme you prefer for the active document. This +overwrites the global <link linkend="config-dialog-editor-filetypes">filetype</link> +mode set in <menuchoice> <guimenu>Settings</guimenu> <guimenuitem>Configure +Editor...</guimenuitem></menuchoice> in the Filetypes tab for your current +document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-highlighting"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Highlighting</guimenuitem></menuchoice></term> + <listitem> +<para>Choose the Highlighting scheme you prefer for the active document. This +overwrites the global highlighting mode set in <menuchoice> +<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem> +</menuchoice> for your current document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-indentation"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Indentation</guimenuitem></menuchoice></term> +<listitem> +<para>Choose the <link linkend="kate-part-autoindent">style of +indentation</link> you want for your active document. +This overwrites the global indentation mode set in <menuchoice> +<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem> +</menuchoice> for your current document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-encoding"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Encoding</guimenuitem></menuchoice></term> +<listitem> +<para>You can overwrite the default encoding set in <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure +Editor...</guimenuitem></menuchoice> in the <guilabel>Open/Save</guilabel> tab +to set a different encoding for your current document. The encoding you +set here will be only valid for your current document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-end-of-line"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>End of Line</guimenuitem></menuchoice></term> +<listitem> +<para>Choose your prefered end of line mode for your active +document. This overwrites the global end of line mode set in <menuchoice> +<guimenu>Settings</guimenu> <guimenuitem>Configure Editor...</guimenuitem> +</menuchoice> for your current document only.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-spelling"/><menuchoice> +<guimenu>Tools</guimenu><guimenuitem>Spelling...</guimenuitem></menuchoice> +</term> + +<listitem><para><action>This initiates the spellchecking program - a program +designed to help the user catch and correct any spelling errors.</action> +Clicking on this entry will start the checker and bring up the speller dialog +box through which the user can control the process. There are four settings +lined up vertically in the center of the dialog with their corresponding labels +just to the left. Starting at the top they are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Unknown word:</guilabel></term> +<listitem><para>Here, the spellchecker indicates the word currently under +consideration. This happens when the checker encounters a word not in its +dictionary - a file containing a list of correctly spelled words against which +it compares each word in the editor.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Replace with:</guilabel></term> +<listitem><para> If the checker has any similar words in its dictionary the +first one will be listed here. The user can accept the suggestion, type in his +or her own correction, or choose a different suggestion from the next +box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Suggested Words:</guilabel></term> +<listitem><para> The checker may list here a number of possible replacements for +the word under consideration. Clicking on any one of the suggestions will cause +that word to be entered in the <guilabel>Replacement:</guilabel> box, +above.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Language:</guilabel></term> +<listitem><para> If you have installed multiple dictionaries, here you can +select which dictionary/language should be used.</para></listitem> +</varlistentry> +</variablelist> + +<para>On the right side of the dialog box are 5 buttons that allow the user to +control the spellcheck process. They are:</para> + +<variablelist> +<varlistentry> +<term><guibutton>Add to Dictionary</guibutton></term> +<listitem><para>Pressing this button adds the word in the <guilabel>Misspelled +Word:</guilabel> box to the checker's dictionary. This means that in the future +the checker will always consider this word to be correctly +spelled.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Replace</guibutton></term> +<listitem><para> This button has the checker replace the word under +consideration in the document with the word in the +<guilabel>Replacement:</guilabel> box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Replace All</guibutton></term> +<listitem><para> This button causes the checker to replace not only the current +<guilabel>Unknown word:</guilabel> but to automatically make the same +substitution for any other occurrences of this <guilabel>Misspelled +Word:</guilabel> in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Ignore</guibutton></term> +<listitem><para>Activating this button will have the checker move on without +making any changes.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Ignore All</guibutton></term> +<listitem><para> This button tells the checker to do nothing with the current +<guilabel>Unknown word:</guilabel> and to pass over any other instances of +the same word.</para> <note><para>This only applies to the current spellcheck +run. If the checker is run again later it will stop on this same +word.</para></note></listitem> +</varlistentry> +</variablelist> + +<para>Three more buttons are located horizontally along the bottom of the +spellcheck dialog. They are:</para> + +<variablelist> +<varlistentry> +<term><guibutton>Help</guibutton></term> +<listitem><para> This invokes the &kde; help system starting at the &kate; help +pages (this document).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Finished</guibutton></term> +<listitem><para> This button ends the spellcheck process, and returns to the +document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Cancel</guibutton></term> +<listitem><para> This button cancels the spellcheck process, all modifications +are reverted, and you will return to your document.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<varlistentry> +<term><anchor id="tools-spelling-from-cursor"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Spelling (from cursor)...</guimenuitem></menuchoice></term> + <listitem> +<para>This initiates the spellchecking program but it starts where your cursor +is instead of at the beginning of the document.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-spellcheck-selection"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Spellcheck Selection...</guimenuitem></menuchoice></term> + <listitem> +<para>Spellchecks the current selection.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="indent"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu><guimenuitem>Indent</guimenuitem></menuchoice></term> +<listitem> +<para>This increases the paragraph's indentation by one step. The size of the +step depends on the <link linkend="config-dialog-editor-indent">indentation +settings</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-unindent"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>I</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu><guimenuitem>Unindent</guimenuitem></menuchoice></term> + +<listitem> +<para>This reduces the paragraph's indentation by one step. The size of the step + +depends on the <link linkend="config-dialog-editor-indent">indentation settings</link>.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-cleanindent"/><menuchoice> +<guimenu>Tools</guimenu><guimenuitem>Clean +Indentation</guimenuitem></menuchoice></term> <listitem> +<para>This cleans the indentation for the current selection or for the +line the cursor is currently in. Cleaning the indentation ensures that +all your selected text follows the indentation mode you choose.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-align"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Align</guimenuitem> +</menuchoice></term> +<listitem> +<para>Causes a realign of the current line or selected lines using the +indentation mode and indentation settings in the doucment.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-comment"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Comment</guimenuitem> +</menuchoice></term> +<listitem><para>This adds one space to the beginning of the line +where the text cursor is located or to the beginning of any +selected lines.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-uncomment"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Uncomment</guimenuitem> +</menuchoice></term> +<listitem><para>This removes one space (if any exist) from the beginning of the +line where the text cursor is located or from the beginning of any +selected lines.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-uppercase"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Uppercase</guimenuitem> +</menuchoice></term> +<listitem><para>Put the selected text or the letter after the cursor in +uppercase.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-lowercase"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Lowercase</guimenuitem> +</menuchoice></term> +<listitem><para>Put the selected text or the letter after the cursor in +lowercase.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-capitalize"/><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Capitalize</guimenuitem> +</menuchoice></term> +<listitem><para>Capitalize the selected text or the current +word.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-join-lines"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Join Lines</guimenuitem> +</menuchoice></term> +<listitem><para>Joins the selected lines, or the current line and the line below +with one white space character as a separator. Leading/trailing white space on +joined lines is removed in the affected ends.</para></listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-word-wrap-document"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Word Wrap Document</guimenuitem> +</menuchoice></term> +<listitem><para>Apply static word wrapping on all the document. That means that +a new line of text will automatically start when the current +line exceeds the length specified by the Wrap words at: option +in the Editing tab in <menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure +Editor...</guimenuitem></menuchoice></para></listitem> +</varlistentry> + +</variablelist> + + +</sect1> + +<sect1 id="sessions-menu"> +<title>The <guimenu>Sessions</guimenu> Menu</title> + +<para>This menu contains entries for using and managing &kate; sessions. +For more information, read <link +linkend="fundamentals-using-sessions">Using Sessions</link>.</para> + +<variablelist> + +<varlistentry id="sessions-new"> +<term><menuchoice><guimenu>Sessions</guimenu> +<guimenuitem>New</guimenuitem></menuchoice></term> +<listitem><para>Creates a new empty session. All currently open files will +be closed.</para></listitem> + +</varlistentry> + +<varlistentry id="sessions-open"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Open...</guimenuitem> +</menuchoice></term> +<listitem><para>Open an existing session. The Session Chooser dialog is +displayed to let you choose one.</para></listitem> +</varlistentry> + +<varlistentry id="sessions-quick-open"> +<term><menuchoice><guimenu>Sessions</guimenu><guisubmenu>Quick Open</guisubmenu> +</menuchoice></term> +<listitem><para>This submenu lets you open an existing session.</para> +</listitem> +</varlistentry> + +<varlistentry id="sessions-save"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save</guimenuitem> +</menuchoice></term> +<listitem><para>Save the current session. If the session is anonymous, you will +be prompted for a session name.</para></listitem> +</varlistentry> + +<varlistentry id="sessions-save-as"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Save +As...</guimenuitem></menuchoice></term> +<listitem><para>Save the current session under a new name. You are prompted for +a name to use.</para></listitem> +</varlistentry> + +<varlistentry id="sessions-manage"> +<term><menuchoice><guimenu>Sessions</guimenu><guimenuitem>Manage...</guimenuitem> +</menuchoice></term> +<listitem><para>Displays the Session Manager dialog which allows you to rename +and delete sessions.</para></listitem> +</varlistentry> + + +</variablelist> + +</sect1> + +<sect1 id="settings-menu"> + +<title>The <guimenu>Settings</guimenu> Menu</title> + +<para>The <guimenu>Settings</guimenu> menu allows you to change the properties +of the main window, such as showing/hiding toolbars, and provides +access to the configuration dialogs.</para> + +<variablelist> + +<varlistentry> +<term> +<anchor id="settings-toolbars"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Toolbars</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>This submenu lists the available toolbars, each item toggles the display +of the associated toolbar.</para> +</listitem> +</varlistentry> + +<varlistentry id="settings-fullscreen"> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Full Screen +Mode</guimenuitem></menuchoice></term> +<listitem><para>Toggles full screen display.</para> +<note><para>This commmand will be moved to the Window menu in a future +version of &kate;</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="settings-configure-shortcuts"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Display the familiar &kde; Keyboard Shortcut Configuration +Dialog.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term> +<anchor id="settings-configure-toolbars"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Display the familiar &kde; Toolbar Configuration Dialog.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="settings-configure-kate"/> +<menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure &kate;...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Launch the <link linkend="config-dialog">Main Configuration Dialog</link></para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="window-menu"> +<title>the <guimenu>Window</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term> +<anchor id="window-new"/> +<menuchoice> +<guimenu>Window</guimenu> +<guimenuitem>New Window</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +<action>Opens another instance of &kate;</action>. +The new instance will be identical to your previous instance. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-split-vertical"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>L</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Split Vertical</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This will split the frame (which may be the main editing area) in two equally sized frames, +the new one to the left of the current one. The new frame gets the focus, and will display the +same document as the old one.</para> +<para>See also <link linkend="kate-mdi">Working with the &kate; MDI</link></para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-split-horizontal"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>T</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Split Horizontal</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Splits the current frame (which may be the main editing area) in two equally sized frames, +the new one at the bottom half. The new frame gets the focus, and displays the same document as +the old one.</para> +<para>See also <link linkend="kate-mdi">Working with the &kate; MDI</link></para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-close-current"/> +<menuchoice> +<shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Close Current</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Closes the active frame. This is disabled, if there is only one frame +(the main editing area).</para> <para>No documents get closed by closing a +frame – they will still be available in the <link +linkend="document-menu"><guimenu>Documents</guimenu> Menu</link> as well as in +the File List.</para> <para>See also <link linkend="kate-mdi">Working with the +&kate; MDI</link></para> +</listitem> +</varlistentry> + +<varlistentry id="window-next-view"> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>F8</keycap> +</keycombo></shortcut><guimenu>Window</guimenu><guimenuitem>Next +View</guimenuitem></menuchoice></term> +<listitem><para>Focus the next document view, if you have split the editor area +in more views.</para></listitem> +</varlistentry> + +<varlistentry id="window-previous-view"> +<term><menuchoice><shortcut><keycombo action="simul">&Shift;<keycap>F8</keycap> +</keycombo></shortcut><guimenu>Window</guimenu><guimenuitem>Previous +View</guimenuitem></menuchoice></term> +<listitem><para>Focus the previous document view, if you have split the editor +area in more views.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +</menuchoice></term> +<listitem> +<variablelist> +<varlistentry> +<term><anchor id="window-toolviews-show-sidebars"/> +<menuchoice><guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Sidebars</guimenuitem></menuchoice></term> +<listitem><para>Toggles the display of the sidebar button rows. This command +does not affect the display of the sidebar content widgets, any sidebar that +is visible will stay visible, and if you assigned shortcuts to the below +commands those will of course continue to work.</para></listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-show-filelist"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show Documents</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggle the display of &kate;'s Documents list</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-show-fileselector"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Filesystem Browser</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggle the display of &kate;'s Filesystem Browser</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-greptool"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Find in Files</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggle the display of &kate;'s <guilabel>Find in Files</guilabel> tool. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="window-toolviews-show-konsole"/> +<menuchoice> +<guimenu>Window</guimenu><guisubmenu>Tool Views</guisubmenu> +<guimenuitem>Show/Hide Terminal</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Toggles the display of the built in terminal emulator.</para> +<para>When activated the first time, the terminal will be created.</para> +<para>When the terminal emulator is displayed, it will get the focus, so that +you can start typing in commands immediately. If the <link +linkend="config-dialog-general-sync-konsole">Sync Konsole with Active +Document</link> option is enabled in the <link +linkend="config-dialog-general">General Page</link> of the <link +linkend="config-dialog">Main configuration dialog</link> the shell session will +change to the directory of the active document, if it is a local file.</para> +</listitem> +</varlistentry> + +</variablelist> + +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="help-menu"> + +<title>The <guimenu>Help</guimenu> Menu</title> + +<para>Apart from standard &kde; <guimenu>Help</guimenu> menu items +described below you will have menu entries to show the +Plugins User Manuals for installed plugins.</para> + +&help.menu.documentation; + +</sect1> + +</chapter> diff --git a/doc/kate/mimetypechooser.png b/doc/kate/mimetypechooser.png Binary files differnew file mode 100644 index 000000000..45220f8a4 --- /dev/null +++ b/doc/kate/mimetypechooser.png diff --git a/doc/kate/part.docbook b/doc/kate/part.docbook new file mode 100644 index 000000000..e09725b31 --- /dev/null +++ b/doc/kate/part.docbook @@ -0,0 +1,671 @@ +<chapter id="kate-part"> +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> +<title>Working with the &kate; editor</title> + +<sect1 id="kate-part-overview"> + +<title>Overview</title> + +<para>The &kate; editor is the editing area of the &kate; window. This +editor is also used by &kwrite;, and it can be used in &konqueror; for +displaying text files from your local computer, or from the +network.</para> + +<para>The editor is composed of the following components:</para> + +<variablelist> + +<varlistentry> +<term>The editing area</term> +<listitem><para>This is where the text of your document is located.</para></listitem> +</varlistentry> + +<varlistentry> +<term>The Scroll bars</term> +<listitem> +<para>The scroll bars indicate the position of the visible part of +the document text, and can be used to move around the +document. Dragging the scrollbars will not cause the insertion cursor +to be moved.</para> +<para>The scroll bars are displayed and hidden as required.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Icon Border</term> +<listitem> +<para>The icon border is a small pane on the left side of the editor, +displaying a small icon next to marked lines.</para> +<para>You can set or remove a <link +linkend="kate-part-bookmarks">bookmark</link> in a visible line by +clicking the &LMB; in the icon border next to that line.</para> +<para>The display of the icon border can be toggled using the +<menuchoice><guimenu>View</guimenu> <guimenuitem>Show Icon +Border</guimenuitem></menuchoice> menu item.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Line Numbers Pane</term> +<listitem> +<para>The Line numbers pane shows the line numbers of all visible +lines in the document.</para> +<para>The display of the Line Numbers Pane can be toggled using the +<menuchoice><guimenu>View</guimenu> <guimenuitem>Show Line +Numbers</guimenuitem></menuchoice> menu item.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Folding Pane</term> +<listitem> +<para>The folding pane allows you to collapse or expand foldable blocks +of lines. The calculation of the foldable regions are done according to +rules in the syntax highlight definition for the document.</para> +</listitem> +</varlistentry> + +</variablelist> + +<itemizedlist> +<title>Also in this Chapter:</title> +<listitem><para><link linkend="kate-part-navigation">Navigating in the +Text</link> </para></listitem> +<listitem><para><link linkend="kate-part-selection">Working with the +Selection</link></para></listitem> +<listitem><para><link linkend="kate-part-copy-and-paste">Copying and +Pasting Text</link></para></listitem> +<listitem><para><link linkend="kate-part-find-replace">Finding and +Replacing Text</link></para></listitem> +<listitem><para><link linkend="kate-part-bookmarks">Using +Bookmarks</link></para></listitem> +<listitem><para><link linkend="kate-part-auto-wrap">Automatically +Wrapping Text</link></para></listitem> +<listitem><para><link linkend="kate-part-autoindent">Using automatic indenting</link></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="kate-part-navigation"> +<title>Navigating in the Text</title> + +<para>Moving around in the text in &kate; is like in most graphical text +editors. You move the cursor using the arrow keys and the +<keycap>Page Up</keycap>, <keycap>Page Down</keycap>, <keycap>Home</keycap> and +<keycap>End</keycap> keys in combination with the <keycap>Ctrl</keycap> and +<keycap>Shift</keycap> modifiers. The <keycap>Shift</keycap> key is always used +to generate a selection, while the <keycap>Ctrl</keycap> key have different +effects on different keys: +<itemizedlist> +<listitem><para>For the <keycap>Up</keycap> and <keycap>Down</keycap> keys it +means scroll rather than move the cursor.</para></listitem> +<listitem><para>For the <keycap>Left</keycap> and <keycap>Right</keycap> +keys it means skip words rather than characters.</para></listitem> +<listitem><para>for the <keycap>Page Up</keycap> and <keycap>Page Down</keycap> +keys it means move to the visible edge of the view rather than browse.</para> +</listitem> +<listitem><para>For the <keycap>Home</keycap> and <keycap>End</keycap> keys it +means move to the beginning or end of the document rather than the beginning or +end of the line.</para></listitem> +</itemizedlist> +</para> + +<para>&kate; also provides you with a way to quickly jump to a matching brace +or paranthese: Place the cursor on the inside of a parenthese or brace +character, and press <keycombo><keycap>Ctrl</keycap><keycap>6</keycap></keycombo> +to jump to the matching parenthese or brace.</para> + +<para>In addition you can use +<link linkend="kate-part-bookmarks">bookmarks</link> to quickly jump to +positions that you define on your own.</para> + +</sect1> + +<sect1 id="kate-part-selection"> +<title>Working with the Selection</title> + +<para>There are two basic ways of selecting text in &kate;: using the +mouse, and using the keyboard.</para> + +<para>To select using the mouse, hold down the &LMB; while dragging +the mouse cursor from where the selection should start, to the desired +end point. The text gets selected as you drag.</para> + +<para>Double-clicking a word will select that word.</para> + +<para>Triple-clicking in a line will select the entire line.</para> + +<para>If &Shift; is held down while clicking, text will be +selected:</para> + +<itemizedlist> +<listitem><para>If nothing is already selected, from the text cursor +position to the mouse cursor position.</para></listitem> +<listitem><para>If there is a selection, from and including that +selection to the mouse cursor position</para></listitem> +</itemizedlist> + +<note> +<para>When selecting text by dragging the mouse, the +selected text is copied to the clipboard, and can be pasted by +clicking the middle mouse button in the editor, or in any other +application to which you want to paste the text. +</para> +</note> + +<para>To select using the keyboard, hold down the &Shift; key while +using the navigation keys (The Arrow keys, <keycap>Page Up</keycap>, +<keycap>Page Down</keycap>, <keycap>Home</keycap> and +<keycap>End</keycap>, possibly in combination with &Ctrl; to extend +the move of the text cursor).</para> + +<para>See also the section <link +linkend="kate-part-navigation">Navigating in the Text</link> in this +Chapter.</para> + +<para>To <action>Copy</action> the current selection, use the +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem></menuchoice> menu item or the keyboard +shortcut (defaults to <keycombo +action="simul">&Ctrl;<keycap>C</keycap></keycombo>).</para> + +<para>To <action>Deselect</action> the current selection, use the +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Deselect</guimenuitem></menuchoice> menu item, or the +keyboard shortcut (default is <keycombo +action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo>), or click +with the &LMB; in the editor.</para> + +<sect2 id="kate-part-selection-block"> +<title>Using Block Selection</title> + +<para>When Block Selection is enabled, you can make <quote>vertical +selections</quote> in the text, meaning selecting limited columns from +multiple lines. This is handy for working with tab separated lines for +example.</para> + +<para>Block Selection can be toggled using the +<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Toggle Block +Selection</guimenuitem></menuchoice> menu item. The default keyboard +shortcut is <keycap>F4</keycap></para> + +</sect2> + +<sect2 id="kate-part-seleciton-overwrite"> + +<title>Using Overwrite Selection</title> + +<para>If Overwrite Selection is enabled, typing or pasting text into +the selection will cause the selected text to be replaced. If not +enabled, new text will be added at the position of the text +cursor.</para> + +<para>Overwrite Selection is enabled by default.</para> + +<para>To change the setting for this option, use the <link +linkend="config-dialog-editor-cursor-selection">Select Page</link> of the <link +linkend="config-dialog">Configuration Dialog</link>.</para> + +</sect2> + +<sect2 id="kate-part-selection-persistent"> + +<title>Using Persistent Selection</title> + +<para>When Persistent selection is enabled, typing characters or +moving the cursor will not cause the Selection to become +deselected. This means that you can move the cursor away from the +selection and type text.</para> + +<para>Persistent Selection is disabled by default.</para> + +<para>Persistent Selection can be enabled in the <link +linkend="config-dialog-editor-cursor-selection">Select Page</link> of the <link +linkend="config-dialog">Configuration Dialog</link>.</para> + +<warning> +<para>If Persistent Selection and Overwrite Selection are both +enabled, typing or pasting text when the text cursor is inside the +selection will cause it to be replaced and deselected.</para> +</warning> + +</sect2> + +</sect1> + +<sect1 id="kate-part-copy-and-paste"> + +<title>Copying and Pasting Text</title> + +<para>To copy text, select it and use the +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem></menuchoice> menu item. Additionally, +selecting text with the mouse will cause selected text to be copied to +the X selection.</para> + +<para>To paste the text currently in the clipboard, use the +<menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem></menuchoice> +menu item.</para> + +<para>Additionally, text selected with the mouse may be pasted by +clicking the <mousebutton>middle</mousebutton> mouse button at the +desired position.</para> + +<tip> +<para>If you are using the &kde; desktop, you can retrieve earlier +copied text from any application using the &klipper; icon in the +&kicker; icon tray.</para> +</tip> + +</sect1> + +<sect1 id="kate-part-find-replace"> +<title>Finding and Replacing Text</title> + +<sect2 id="find-replace-dialog"> +<title>The <guilabel>Find Text</guilabel> and <guilabel>Replace +Text</guilabel> Dialogs</title> + + +<para>The Find and Replace Text dialogs in &kate; are very much the +same, except the Replace Text dialog offers the means of entering a +replacement string along with a few extra options.</para> + +<para>The dialogs offer the following common options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Text to Find</guilabel></term> +<listitem><para>This is where to enter the search string. The interpretation of the string +depends on some of the options described below.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Regular Expression</guilabel></term> +<listitem> +<para>If checked, the search string is interpreted as a regular +expression. A button for using a graphical tool to create or edit the +expression will be enabled.</para> +<para>See <link linkend="regular-expressions">Regular +Expressions</link> for more on these.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Case Insensitive</guilabel></term> +<listitem> +<para>If enabled, the search will be case insensitive.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Whole Words Only</guilabel></term> +<listitem> +<para>If checked, the search will only match if there is a word +boundary at both ends of the string matching, meaning not an +alphanumeric character - either some other visible character or a line +end.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>From cursor</guilabel></term> +<listitem> +<para>If checked, the search will start at cursor position, otherwise it will +start at the beginning of the first line in the document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Find Backwards</guilabel></term> +<listitem> +<para>If checked, the search will look for the first match above the +starting point, either cursor position or the beginning of the +document, if the <guilabel>From Beginning</guilabel> option is +enabled.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>The <guilabel>Replace Text</guilabel> Dialog offers some +additional options:</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Replace With</guilabel></term> +<listitem><para>This is where to enter the replacement +string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Selected Text</guilabel></term> +<listitem> +<para>This option is disabled if no text is selected, or if the +<guilabel>Prompt on Replace</guilabel> +option is enabled. If checked, all matches of the search string within +the selected text will be replaced with the replace string.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Prompt on Replace</guilabel></term> +<listitem><para>If checked, a small dialog will prompt you for what to +do for each time a match is found. It offers the following options: +<variablelist> + +<varlistentry> +<term><guibutton>Yes</guibutton></term> +<listitem><para>Activate this to replace the current match (which is +selected in the editor).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>No</guibutton></term> +<listitem><para>Activate to skip the current match, and try to find another one.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>All</guibutton></term> +<listitem><para>Activate to cancel prompting, and just replace all +matches.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Close</guibutton></term> +<listitem><para>Activate this to skip the current match and end the +searching.</para></listitem> +</varlistentry> + +</variablelist> + +</para></listitem> +</varlistentry> + +</variablelist> + +<note> +<para>There is currently no way to use minimal matching when searching +for a regular expression. This will be added in a future version of +&kate;</para> +</note> + +</sect2> + +<sect2 id="finding-text"> +<title>Finding Text</title> + +<para>To find text, launch the <guilabel>Find Text</guilabel> Dialog +with <keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo>or +from the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Find...</guimenuitem></menuchoice> menu item, enter a +search string, set the <link +linkend="find-replace-dialog">options</link> as desired and hit +<guibutton>Ok</guibutton>. If the search was started at cursor position and no +match was found before reaching the end (or beginning if you are searching +backward) of the document, you will be asked if you want to wrap the search. +</para> + +<para>If a match is found it is selected and the <guilabel>Find +Text</guilabel> Dialog is hidden, but stay tuned, finding further +matches is very easy:</para> + +<para>To find the next match in the search direction, use the +<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find +Next</guimenuitem></menuchoice> command or press +<keycap>F3</keycap>.</para> + +<para>To find the next match in the opposite direction, use the +<menuchoice><guimenu>Edit</guimenu> <guimenuitem>Find +Previous</guimenuitem></menuchoice> command or press <keycombo +action="simul">&Shift;<keycap>F3</keycap></keycombo>.</para> + +<para>If no match is found before reaching the document end (or beginning if you +are searching backward) , you will be asked if you want to wrap the search. +</para> + +</sect2> + +<sect2> +<title>Replacing Text</title> + +<para>To replace text, launch the <guilabel>Replace text</guilabel> +Dialog using the <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Replace</guimenuitem></menuchoice> command, or the +<keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo> shortcut, +enter a search string and optionally a replace string (if the replace +string is empty, each match will be removed), set +the <link linkend="find-replace-dialog">options</link> as desired and +hit the <guibutton>Ok</guibutton> button.</para> + +<tip> +<para>If you are using a regular expression to find the text to replace, you can +employ backreferences to reuse text captured in parenthesized subpatterns of the expression.</para> +<para>See <xref linkend="regular-expressions"/><!-- xref to reg-exp appendix --> for more +on those.</para> +</tip> + +<tip><para>You can do <command>find</command>, <command>replace</command> and +<command>ifind</command> (incremental search) from the +<link linkend="advanced-editing-tools-commandline">command line</link>.</para> +</tip> + +</sect2> + +</sect1> + +<sect1 id="kate-part-bookmarks"> +<title>Using Bookmarks</title> + +<para>The bookmarks feature allows you to mark certain lines, to be +able to easily find them again.</para> + +<para>You can set or remove a bookmark in a line in two ways:</para> + +<itemizedlist> +<listitem> +<para>Move the insertion cursor to the line and activate the +<menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Toggle +Bookmark</guimenuitem></menuchoice> (<keycombo +action="simul">&Ctrl;<keycap>B</keycap></keycombo>) command.</para> +</listitem> +<listitem> +<para>Click in the Icon Border next to the line.</para> +</listitem> +</itemizedlist> + + +<para>Bookmarks are available in the <guimenu>Bookmarks</guimenu> +menu. The individual bookmarks are available as menu items, labeled +with the line number of the line with the bookmark, and the first few +characters of the text in the line. To move the insertion cursor to +the beginning of a bookmarked line, open the menu and select the +bookmark.</para> + +<para>To quickly move between bookmarks or to the next/previous bookmark, +use the <menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Next</guimenuitem> +</menuchoice> (<keycombo action="simul"><keycap>Ctrl</keycap> +<keycap>Page Down</keycap></keycombo>) or <menuchoice> +<guimenu>Bookmarks</guimenu><guimenuitem>Previous</guimenuitem></menuchoice> +(<keycombo action="simul"><keycap>Ctrl</keycap><keycap>Page Up</keycap> +</keycombo>) commands.</para> + +</sect1> + +<sect1 id="kate-part-auto-wrap"> + +<title>Automatically Wrapping text</title> + +<para>This feature allows you to have the text formatted in a very simple way: the text will be wrapped, +so that no lines exceed a maximum number of characters per line, unless there is a longer string of +non-whitespace characters.</para> + +<para>To enable/disable it, check/uncheck the <guibutton>Word Wrap</guibutton> checkbox in the +<link linkend="config-dialog-editor-edit">edit page</link> of the <link linkend="config-dialog">configuration dialog</link>.</para> + +<para>To set the maximum line width (maximum characters per line), use the +<link linkend="config-dialog-editor-wrap-words-at"><guibutton>Wrap Words At</guibutton></link> +option in the <link linkend="config-dialog-editor-edit">edit page</link> of the <link linkend="config-dialog">configuration +dialog</link>.</para> + +<para>If enabled, +it has the following effects: + +<itemizedlist> +<listitem><para>While typing, the editor will automatically insert a hard line break after +the last whitespace character at a position before the maximum line width is reached.</para></listitem> +<listitem><para>While loading a document, the editor will wrap the text in a similar way, so that +no lines are longer than the maximum line width, if they contain any whitespace allowing that.</para></listitem> +</itemizedlist> + +</para> + +<note><para>There is currently no way to set word wrap for document types, or even to enable or disable +the feature on document level. This will be fixed in a future version of &kate;</para></note> + +</sect1> + +<sect1 id="kate-part-autoindent"> +<title>Using automatic indenting</title> + +<para>&kate;s editor component supports a variation of autoindenting modes, +designed for different text formats. You can pick from the available modes using +the <menuchoice><guimenu>Tools</guimenu><guisubmenu>Indentation</guisubmenu></menuchoice> +menu. The autoindent modules also provides a function +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Align</guimenuitem></menuchoice> +which will recalculate the indentation of the selected or current line. Thus, +you may reindent your entire document by selecting all the text and activating +that action.</para> + +<para>All the indent modes use the indentation related settings in the active +document.</para> + +<tip><para>You can set all sorts of configuration variables, including +those related to indentation using <link linkend="config-variables">Document +Variables</link> and <link linkend="config-dialog-editor-filetypes">File +types</link>.</para></tip> + +<variablelist> + +<title>Available Autoindent Modes</title> + +<varlistentry> +<term>None</term> +<listitem><para>Selecting this mode turns automatic indenting off entirely.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Normal</term> +<listitem><para>This indenter simply keeps the indentation similar to the +previous line with any content other than whitespace. You can combine this +with using the indent and unindent actions for indenting to your own taste. +</para></listitem> +</varlistentry> + +<varlistentry><term>C Style</term> +<listitem><para>An indenter for C and similar languages, such as +C++, C#, java, javascript and so on. This indenter will not work with scripting +languages such as Perl or PHP.</para></listitem> +</varlistentry> + +<varlistentry> +<term>SS C Style</term> +<listitem><para>An alternative indenter for C and similar languages, with the +same constraints.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Python Style</term> +<listitem><para>An indenter specifically for the python scripting language. +</para></listitem> +</varlistentry> + +<varlistentry> +<term>XML</term> +<listitem><para>A very nice XML auto-indenter. However tempting, do not try to +use this with HTML other than XHTML, because it fails with the old style +HTML tags (open tags like for example <br>)</para></listitem> +</varlistentry> + +<varlistentry> +<term>Variable Indenter</term> +<listitem> + +<note> +<para>The variable indenter is experimental, and may change behavior or +disappear in future versions.</para> +</note> + +<para> +The variable indenter is special in that it can be configured using variables in +the document (or in a filetype configuration). The followwing variables are +read: + +<variablelist> +<varlistentry> +<term>var-indent-indent-after</term> +<listitem> +<para>A regular expression which will cause a line to +be indented by one unit, if the first non-whitespace-only line above matches. +var-indent-indent: A regular expression, which will cause a matching line +to be indented by one unit.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>var-indent-unindent</term> +<listitem> +<para>A regular expression which will cause the line to be +unindented by one unit if matching.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>var-indent-triggerchars</term> +<listitem> +<para>A list of characters that should cause the +indention to be recalculated immediately when typed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>var-indent-handle-couples</term> +<listitem> +<para>A list of parenthese sets to handle. Any combination +of 'parens' 'braces' and 'brackets'. Each set type is handled +the following way: If there are unmatched opening instances on the above line, +one indent unit is added, if there are unmatched closing instances on the +current line, one indent unit is removed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><literal>var-indent-couple-attribute</literal></term> +<listitem> +<para>When looking for unmatched couple openings/closings, +only characters with this attribute are considered. The value must be the +attribute name from the syntax xml file, for example "Symbol". If it's not +specified, attribute 0 is used (usually 'Normal Text').</para> +</listitem> +</varlistentry> + +</variablelist> + +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +</chapter> diff --git a/doc/kate/plugins.docbook b/doc/kate/plugins.docbook new file mode 100644 index 000000000..a097cb526 --- /dev/null +++ b/doc/kate/plugins.docbook @@ -0,0 +1,28 @@ +<chapter id="plugins"> + +<chapterinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</chapterinfo> + +<title>Working with Plug-ins</title> + +<para>Kate is using two different forms of plug-ins, namely plug-ins for the +&kate; application and plug-ins for the &kate; editor component. The latter are +available to any application using the editor component, such as KDevelop, +Quanta, Kile, Kwrite and many others, while application plug-ins are specific +to the &kate; application.</para> + +<para>You can enable both types of plug-ins in the <link +linkend="configuring-kate-configdialog">configuration dialog</link>, which also +provides access to additional configuration options for plug-ins that requires +that.</para> + +<para>There are many plugins for various purposes available in the kdeaddons +module, and you can search the web for more. A few plugins are shipped with the +editor component, for doing word completion, automatic bookmarks, insert files, +thesaurus and word spell checking and incremental search.</para> + +</chapter> diff --git a/doc/kate/regular-expressions.docbook b/doc/kate/regular-expressions.docbook new file mode 100644 index 000000000..c15685d75 --- /dev/null +++ b/doc/kate/regular-expressions.docbook @@ -0,0 +1,664 @@ +<appendix id="regular-expressions"> +<appendixinfo> +<authorgroup> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</appendixinfo> + +<title>Regular Expressions</title> + +<synopsis> This Appendix contains a brief but hopefully sufficient and +covering introduction to the world of <emphasis>regular +expressions</emphasis>. It documents regular expressions in the form +available within &kate;, which is not compatible with the regular +expressions of perl, nor with those of for example +<command>grep</command>.</synopsis> + +<sect1> + +<title>Introduction</title> + +<para><emphasis>Regular Expressions</emphasis> provides us with a way +to describe some possible contents of a text string in a way +understood by a small piece of software, so that it can investigate if +a text matches, and also in the case of advanced applications with the +means of saving pieces or the matching text.</para> + +<para>An example: Say you want to search a text for paragraphs that +starts with either of the names <quote>Henrik</quote> or +<quote>Pernille</quote> followed by some form of the verb +<quote>say</quote>.</para> + +<para>With a normal search, you would start out searching for the +first name, <quote>Henrik</quote> maybe followed by <quote>sa</quote> +like this: <userinput>Henrik sa</userinput>, and while looking for +matches, you would have to discard those not being the beginning of a +paragraph, as well as those in which the word starting with the +letters <quote>sa</quote> was not either <quote>says</quote>, +<quote>said</quote> or so. And then of cause repeat all of that with +the next name...</para> + +<para>With Regular Expressions, that task could be accomplished with a +single search, and with a larger degree of preciseness.</para> + +<para>To achieve this, Regular Expressions defines rules for +expressing in details a generalization of a string to match. Our +example, which we might literally express like this: <quote>A line +starting with either <quote>Henrik</quote> or <quote>Pernille</quote> +(possibly following up to 4 blanks or tab characters) followed by a +whitespace followed by <quote>sa</quote> and then either +<quote>ys</quote> or <quote>id</quote></quote> could be expressed with +the following regular expression:</para> <para><userinput>^[ +\t]{0,4}(Henrik|Pernille) sa(ys|id)</userinput></para> + +<para>The above example demonstrates all four major concepts of modern +Regular Expressions, namely:</para> + +<itemizedlist> +<listitem><para>Patterns</para></listitem> +<listitem><para>Assertions</para></listitem> +<listitem><para>Quantifiers</para></listitem> +<listitem><para>Back references</para></listitem> +</itemizedlist> + +<para>The caret (<literal>^</literal>) starting the expression is an +assertion, being true only if the following matching string is at the +start of a line.</para> + +<para>The stings <literal>[ \t]</literal> and +<literal>(Henrik|Pernille) sa(ys|id)</literal> are patterns. The first +one is a <emphasis>character class</emphasis> that matches either a +blank or a (horizontal) tab character; the other pattern contains +first a subpattern matching either <literal>Henrik</literal> +<emphasis>or</emphasis> <literal>Pernille</literal>, then a piece +matching the exact string <literal> sa</literal> and finally a +subpattern matching either <literal>ys</literal> +<emphasis>or</emphasis> <literal>id</literal></para> + +<para>The string <literal>{0,4}</literal> is a quantifier saying +<quote>anywhere from 0 up to 4 of the previous</quote>.</para> + +<para>Because regular expression software supporting the concept of +<emphasis>back references</emphasis> saves the entire matching part of +the string as well as sub-patterns enclosed in parentheses, given some +means of access to those references, we could get our hands on either +the whole match (when searching a text document in an editor with a +regular expression, that is often marked as selected) or either the +name found, or the last part of the verb.</para> + +<para>All together, the expression will match where we wanted it to, +and only there.</para> + +<para>The following sections will describe in details how to construct +and use patterns, character classes, assertions, quantifiers and +back references, and the final section will give a few useful +examples.</para> + +</sect1> + +<sect1 id="regex-patterns"> + +<title>Patterns</title> + +<para>Patterns consists of literal strings and character +classes. Patterns may contain sub-patterns, which are patterns enclosed +in parentheses.</para> + +<sect2> +<title>Escaping characters</title> + +<para>In patterns as well as in character classes, some characters +have a special meaning. To literally match any of those characters, +they must be marked or <emphasis>escaped</emphasis> to let the regular +expression software know that it should interpret such characters in +their literal meaning.</para> + +<para>This is done by prepending the character with a backslash +(<literal>\</literal>).</para> + + +<para>The regular expression software will silently ignore escaping a +character that does not have any special meaning in the context, so +escaping for example a <quote>j</quote> (<userinput>\j</userinput>) is +safe. If you are in doubt whether a character could have a special +meaning, you can therefore escape it safely.</para> + +<para>Escaping of cause includes the backslash character it self, to +literally match a such, you would write +<userinput>\\</userinput>.</para> + +</sect2> + +<sect2> +<title>Character Classes and abbreviations</title> + +<para>A <emphasis>character class</emphasis> is an expression that +matches one of a defined set of characters. In Regular Expressions, +character classes are defined by putting the legal characters for the +class in square brackets, <literal>[]</literal>, or by using one of +the abbreviated classes described below.</para> + +<para>Simple character classes just contains one or more literal +characters, for example <userinput>[abc]</userinput> (matching either +of the letters <quote>a</quote>, <quote>b</quote> or <quote>c</quote>) +or <userinput>[0123456789]</userinput> (matching any digit).</para> + +<para>Because letters and digits have a logical order, you can +abbreviate those by specifying ranges of them: +<userinput>[a-c]</userinput> is equal to <userinput>[abc]</userinput> +and <userinput>[0-9]</userinput> is equal to +<userinput>[0123456789]</userinput>. Combining these constructs, for +example <userinput>[a-fynot1-38]</userinput> is completely legal (the +last one would match, of cause, either of +<quote>a</quote>,<quote>b</quote>,<quote>c</quote>,<quote>d</quote>, +<quote>e</quote>,<quote>f</quote>,<quote>y</quote>,<quote>n</quote>,<quote>o</quote>,<quote>t</quote>, +<quote>1</quote>,<quote>2</quote>,<quote>3</quote> or +<quote>8</quote>).</para> + +<para>As capital letters are different characters from their +non-capital equivalents, to create a caseless character class matching +<quote>a</quote> or <quote>b</quote>, in any case, you need to write it +<userinput>[aAbB]</userinput>.</para> + +<para>It is of cause possible to create a <quote>negative</quote> +class matching as <quote>anything but</quote> To do so put a caret +(<literal>^</literal>) at the beginning of the class: </para> + +<para><userinput>[^abc]</userinput> will match any character +<emphasis>but</emphasis> <quote>a</quote>, <quote>b</quote> or +<quote>c</quote>.</para> + +<para>In addition to literal characters, some abbreviations are +defined, making life still a bit easier: + +<variablelist> + +<varlistentry> +<term><userinput>\a</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> bell character (BEL, 0x07).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\f</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> form feed character (FF, 0x0C).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\n</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> line feed character (LF, 0x0A, Unix newline).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\r</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> carriage return character (CR, 0x0D).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\t</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> horizontal tab character (HT, 0x09).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\v</userinput></term> +<listitem><para> This matches the <acronym>ASCII</acronym> vertical tab character (VT, 0x0B).</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>\xhhhh</userinput></term> + +<listitem><para> This matches the Unicode character corresponding to +the hexadecimal number hhhh (between 0x0000 and 0xFFFF). \0ooo (&ie;, +\zero ooo) matches the <acronym>ASCII</acronym>/Latin-1 character +corresponding to the octal number ooo (between 0 and +0377).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>.</userinput> (dot)</term> +<listitem><para> This matches any character (including newline).</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\d</userinput></term> +<listitem><para> This matches a digit. Equal to <literal>[0-9]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\D</userinput></term> +<listitem><para> This matches a non-digit. Equal to <literal>[^0-9]</literal> or <literal>[^\d]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\s</userinput></term> +<listitem><para> This matches a whitespace character. Practically equal to <literal>[ \t\n\r]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\S</userinput></term> +<listitem><para> This matches a non-whitespace. Practically equal to <literal>[^ \t\r\n]</literal>, and equal to <literal>[^\s]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\w</userinput></term> +<listitem><para>Matches any <quote>word character</quote> - in this case any letter or digit. Note that +underscore (<literal>_</literal>) is not matched, as is the case with perl regular expressions. +Equal to <literal>[a-zA-Z0-9]</literal></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\W</userinput></term> +<listitem><para>Matches any non-word character - anything but letters or numbers. +Equal to <literal>[^a-zA-Z0-9]</literal> or <literal>[^\w]</literal></para></listitem> +</varlistentry> + + +</variablelist> + +</para> + +<para>The abbreviated classes can be put inside a custom class, for +example to match a word character, a blank or a dot, you could write +<userinput>[\w \.]</userinput></para> + +<note> <para>The POSIX notation of classes, <userinput>[:<class +name>:]</userinput> is currently not supported.</para> </note> + +<sect3> +<title>Characters with special meanings inside character classes</title> + +<para>The following characters has a special meaning inside the +<quote>[]</quote> character class construct, and must be escaped to be +literally included in a class:</para> + +<variablelist> +<varlistentry> +<term><userinput>]</userinput></term> +<listitem><para>Ends the character class. Must be escaped unless it is the very first character in the +class (may follow an unescaped caret)</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>^</userinput> (caret)</term> +<listitem><para>Denotes a negative class, if it is the first character. Must be escaped to match literally if it is the first character in the class.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>-</userinput> (dash)</term> +<listitem><para>Denotes a logical range. Must always be escaped within a character class.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>\</userinput> (backslash)</term> +<listitem><para>The escape character. Must always be escaped.</para></listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +<sect2> + +<title>Alternatives: matching <quote>one of</quote></title> + +<para>If you want to match one of a set of alternative patterns, you +can separate those with <literal>|</literal> (vertical bar character).</para> + +<para>For example to find either <quote>John</quote> or <quote>Harry</quote> you would use an expression <userinput>John|Harry</userinput>.</para> + +</sect2> + +<sect2> + +<title>Sub Patterns</title> + +<para><emphasis>Sub patterns</emphasis> are patterns enclosed in +parentheses, and they have several uses in the world of regular +expressions.</para> + +<sect3> + +<title>Specifying alternatives</title> + +<para>You may use a sub pattern to group a set of alternatives within +a larger pattern. The alternatives are separated by the character +<quote>|</quote> (vertical bar).</para> + +<para>For example to match either of the words <quote>int</quote>, +<quote>float</quote> or <quote>double</quote>, you could use the +pattern <userinput>int|float|double</userinput>. If you only want to +find one if it is followed by some whitespace and then some letters, +put the alternatives inside a subpattern: +<userinput>(int|float|double)\s+\w+</userinput>.</para> + +</sect3> + +<sect3> + +<title>Capturing matching text (back references)</title> + +<para>If you want to use a back reference, use a sub pattern to have +the desired part of the pattern remembered.</para> + +<para>For example, it you want to find two occurrences of the same +word separated by a comma and possibly some whitespace, you could +write <userinput>(\w+),\s*\1</userinput>. The sub pattern +<literal>\w+</literal> would find a chunk of word characters, and the +entire expression would match if those were followed by a comma, 0 or +more whitespace and then an equal chunk of word characters. (The +string <literal>\1</literal> references <emphasis>the first sub pattern +enclosed in parentheses</emphasis>)</para> + +<!-- <para>See also <link linkend="backreferences">Back references</link>.</para> --> + +</sect3> + +<sect3 id="lookahead-assertions"> +<title>Lookahead Assertions</title> + +<para>A lookahead assertion is a sub pattern, starting with either +<literal>?=</literal> or <literal>?!</literal>.</para> + +<para>For example to match the literal string <quote>Bill</quote> but +only if not followed by <quote> Gates</quote>, you could use this +expression: <userinput>Bill(?! Gates)</userinput>. (This would find +<quote>Bill Clinton</quote> as well as <quote>Billy the kid</quote>, +but silently ignore the other matches.)</para> + +<para>Sub patterns used for assertions are not captured.</para> + +<para>See also <link linkend="assertions">Assertions</link></para> + +</sect3> + +</sect2> + +<sect2 id="special-characters-in-patterns"> +<title>Characters with a special meaning inside patterns</title> + +<para>The following characters have meaning inside a pattern, and +must be escaped if you want to literally match them: + +<variablelist> + +<varlistentry> +<term><userinput>\</userinput> (backslash)</term> +<listitem><para>The escape character.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>^</userinput> (caret)</term> +<listitem><para>Asserts the beginning of the string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>$</userinput></term> +<listitem><para>Asserts the end of string.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>()</userinput> (left and right parentheses)</term> +<listitem><para>Denotes sub patterns.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{}</userinput> (left and right curly braces)</term> +<listitem><para>Denotes numeric quantifiers.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>[]</userinput> (left and right square brackets)</term> +<listitem><para>Denotes character classes.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>|</userinput> (vertical bar)</term> +<listitem><para>logical OR. Separates alternatives.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>+</userinput> (plus sign)</term> +<listitem><para>Quantifier, 1 or more.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>*</userinput> (asterisk)</term> +<listitem><para>Quantifier, 0 or more.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>?</userinput> (question mark)</term> +<listitem><para>An optional character. Can be interpreted as a quantifier, 0 or 1.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +</sect2> + +</sect1> + +<sect1 id="quantifiers"> +<title>Quantifiers</title> + +<para><emphasis>Quantifiers</emphasis> allows a regular expression to +match a specified number or range of numbers of either a character, +character class or sub pattern.</para> + +<para>Quantifiers are enclosed in curly brackets (<literal>{</literal> +and <literal>}</literal>) and have the general form +<literal>{[minimum-occurrences][,[maximum-occurrences]]}</literal> +</para> + +<para>The usage is best explained by example: + +<variablelist> + +<varlistentry> +<term><userinput>{1}</userinput></term> +<listitem><para>Exactly 1 occurrence</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{0,1}</userinput></term> +<listitem><para>Zero or 1 occurrences</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{,1}</userinput></term> +<listitem><para>The same, with less work;)</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{5,10}</userinput></term> +<listitem><para>At least 5 but maximum 10 occurrences.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>{5,}</userinput></term> +<listitem><para>At least 5 occurrences, no maximum.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +<para>Additionally, there are some abbreviations: + +<variablelist> + +<varlistentry> +<term><userinput>*</userinput> (asterisk)</term> +<listitem><para>similar to <literal>{0,}</literal>, find any number of occurrences.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>+</userinput> (plus sign)</term> +<listitem><para>similar to <literal>{1,}</literal>, at least 1 occurrence.</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>?</userinput> (question mark)</term> +<listitem><para>similar to <literal>{0,1}</literal>, zero or 1 occurrence.</para></listitem> +</varlistentry> + +</variablelist> + +</para> + +<sect2> + +<title>Greed</title> + +<para>When using quantifiers with no maximum, regular expressions +defaults to match as much of the searched string as possible, commonly +known as <emphasis>greedy</emphasis> behavior.</para> + +<para>Modern regular expression software provides the means of +<quote>turning off greediness</quote>, though in a graphical +environment it is up to the interface to provide you with access to +this feature. For example a search dialog providing a regular +expression search could have a check box labeled <quote>Minimal +matching</quote> as well as it ought to indicate if greediness is the +default behavior.</para> + +</sect2> + +<sect2> +<title>In context examples</title> + +<para>Here are a few examples of using quantifiers</para> + +<variablelist> + +<varlistentry> +<term><userinput>^\d{4,5}\s</userinput></term> +<listitem><para>Matches the digits in <quote>1234 go</quote> and <quote>12345 now</quote>, but neither in <quote>567 eleven</quote> +nor in <quote>223459 somewhere</quote></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\s+</userinput></term> +<listitem><para>Matches one or more whitespace characters</para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>(bla){1,}</userinput></term> +<listitem><para>Matches all of <quote>blablabla</quote> and the <quote>bla</quote> in <quote>blackbird</quote> or <quote>tabla</quote></para></listitem> +</varlistentry> + +<varlistentry> +<term><userinput>/?></userinput></term> +<listitem><para>Matches <quote>/></quote> in <quote><closeditem/></quote> as well as +<quote>></quote> in <quote><openitem></quote>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="assertions"> +<title>Assertions</title> + +<para><emphasis>Assertions</emphasis> allows a regular expression to +match only under certain controlled conditions.</para> + +<para>An assertion does not need a character to match, it rather +investigates the surroundings of a possible match before acknowledging +it. For example the <emphasis>word boundary</emphasis> assertion does +not try to find a non word character opposite a word one at its +position, instead it makes sure that there is not a word +character. This means that the assertion can match where there is no +character, &ie; at the ends of a searched string.</para> + +<para>Some assertions actually does have a pattern to match, but the +part of the string matching that will not be a part of the result of +the match of the full expression.</para> + +<para>Regular Expressions as documented here supports the following +assertions: + +<variablelist> + +<varlistentry> +<term><userinput>^</userinput> (caret: beginning of +string)</term> +<listitem><para>Matches the beginning of the searched +string.</para> <para>The expression <userinput>^Peter</userinput> will +match at <quote>Peter</quote> in the string <quote>Peter, hey!</quote> +but not in <quote>Hey, Peter!</quote> </para> </listitem> +</varlistentry> + +<varlistentry> +<term><userinput>$</userinput> (end of string)</term> +<listitem><para>Matches the end of the searched string.</para> + +<para>The expression <userinput>you\?$</userinput> will match at the +last you in the string <quote>You didn't do that, did you?</quote> but +nowhere in <quote>You didn't do that, right?</quote></para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>\b</userinput> (word boundary)</term> +<listitem><para>Matches if there is a word character at one side and not a word character at the +other.</para> +<para>This is useful to find word ends, for example both ends to find +a whole word. The expression <userinput>\bin\b</userinput> will match +at the separate <quote>in</quote> in the string <quote>He came in +through the window</quote>, but not at the <quote>in</quote> in +<quote>window</quote>.</para></listitem> + +</varlistentry> + +<varlistentry> +<term><userinput>\B</userinput> (non word boundary)</term> +<listitem><para>Matches wherever <quote>\b</quote> does not.</para> +<para>That means that it will match for example within words: The expression +<userinput>\Bin\B</userinput> will match at in <quote>window</quote> but not in <quote>integer</quote> or <quote>I'm in love</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>(?=PATTERN)</userinput> (Positive lookahead)</term> +<listitem><para>A lookahead assertion looks at the part of the string following a possible match. +The positive lookahead will prevent the string from matching if the text following the possible match +does not match the <emphasis>PATTERN</emphasis> of the assertion, but the text matched by that will +not be included in the result.</para> +<para>The expression <userinput>handy(?=\w)</userinput> will match at <quote>handy</quote> in +<quote>handyman</quote> but not in <quote>That came in handy!</quote></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>(?!PATTERN)</userinput> (Negative lookahead)</term> + +<listitem><para>The negative lookahead prevents a possible match to be +acknowledged if the following part of the searched string does match +its <emphasis>PATTERN</emphasis>.</para> +<para>The expression <userinput>const \w+\b(?!\s*&)</userinput> +will match at <quote>const char</quote> in the string <quote>const +char* foo</quote> while it can not match <quote>const QString</quote> +in <quote>const QString& bar</quote> because the +<quote>&</quote> matches the negative lookahead assertion +pattern.</para> +</listitem> +</varlistentry> + +</variablelist> + +</para> + +</sect1> + +<!-- TODO sect1 id="backreferences"> + +<title>Back References</title> + +<para></para> + +</sect1 --> + +</appendix> diff --git a/doc/kate/unhighlighted.png b/doc/kate/unhighlighted.png Binary files differnew file mode 100644 index 000000000..6361032f3 --- /dev/null +++ b/doc/kate/unhighlighted.png diff --git a/doc/kcontrol/Makefile.am b/doc/kcontrol/Makefile.am new file mode 100644 index 000000000..930c270cd --- /dev/null +++ b/doc/kcontrol/Makefile.am @@ -0,0 +1,6 @@ + +SUBDIRS = $(AUTODIRS) + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kcontrol/arts/Makefile.am b/doc/kcontrol/arts/Makefile.am new file mode 100644 index 000000000..093f0a698 --- /dev/null +++ b/doc/kcontrol/arts/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/arts diff --git a/doc/kcontrol/arts/index.docbook b/doc/kcontrol/arts/index.docbook new file mode 100644 index 000000000..4fbfa3bff --- /dev/null +++ b/doc/kcontrol/arts/index.docbook @@ -0,0 +1,201 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY midi-kcontrol SYSTEM "midi.docbook"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride;</author> +<author>&Jost.Schenck;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-20</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>sound server</keyword> +<keyword>sound</keyword> +<keyword>aRts</keyword> +</keywordset> +</articleinfo> + +<sect1 id="sndserver"> +<title>Sound System</title> + +<para>This control module is used to configure the settings for the +&arts; sound server (the &kde; sound server).</para> + +<sect2 id="sndserver-general"> +<title>&arts;</title> + +<para>The top option, labeled <guilabel>Enable the sound system</guilabel>, +enables (or disables) the &arts; sound server entirely.</para> + +<tip> +<para>You can find out more about &arts; in general by typing +<userinput>help:/artsbuilder</userinput> into the &konqueror; location +bar, or by finding the &arts-builder; documentation in &khelpcenter;. +</para> +</tip> + +<para>The rest of the panel consists of options for the &arts; +sound server.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Enable networked sound</guilabel></term> +<listitem> +<para>If this option is enabled, then sound requests from the network +will be honored by the sound server. If this option is disabled, the sound +server will only honor requests from the local computer.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Run with the highest possible priority (realtime priority)</guilabel></term> +<listitem><para>Enabling this option will give the sound server priority over +other applications, which will help alleviate any problems delivering +uninterrupted sound.</para> +<note><para>This option may require permissions you do not have as a regular +user.</para> +<para>This option also relies on certain real time support from your +system which may not be available.</para> +<para>If you do not have the necessary permissions, or your system does +not have the real time support necessary, enabling this option will not +cause problems.</para></note></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Sound buffer:</guilabel></term> +<listitem><para>This slider determines how quickly the sound server can use your +computer's resources. The faster the response time, the higher the +<acronym>CPU</acronym> load will be.</para> +<tip><para>I would recommend that you start with the sound server set at +250 ms, and use &kde; for a while. If you notice that the sound does +not work correctly, increase the responsiveness one step at a time until +the problems disappear.</para></tip> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Auto-suspend if idle after:</guilabel></term> +<listitem> +<para>Normally &arts; locks the sound card device, so that other +applications cannot use it. If you enable this option, then if &arts; +has been idle for the amount of time you set, it will suspend itself, +allowing any application access to the sound hardware. If &arts; +receives another request, it will unsuspend, and continue as normal. +Enabling this option may cause a small delay when you start an &arts; +application.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>At the bottom of this page are two buttons to allow you to test your +settings, labelled <guibutton>Test Sound</guibutton> and <guilabel>Test +MIDI</guilabel> respectively.</para> + +</sect2> + +<sect2 id="sndserver-soundio"> +<title>Hardware</title> + +<para>The first option you can configure in the +<guilabel>Hardware</guilabel> panel is <guilabel>Select the audio +device:</guilabel>. It tells &arts; which sound system to use for input and +output of sound. Current choices are <acronym>ALSA</acronym> (Advanced +&Linux; Sound Architecture), <acronym>OSS</acronym> (Open Sound System), +<acronym>ESD</acronym> (Enlightenment Sound Daemon), no audio at all and +autodetect. In most cases <quote>Autodetect</quote> will be perfect for +you.</para> + +<para>Other options are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Full duplex</guilabel></term> +<listitem><para>This option allows the sound server to play and record sound at +the same time. This option should be enabled if you use applications (such as +Internet telephones) which require simultaneous record and +playback.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Use custom sampling rate:</guilabel></term> +<listitem> +<para>Normally, the sound server defaults to using a sampling rate of +44100 Hz (<acronym>CD</acronym> quality), which is supported on almost all +hardware. If you are using certain Yamaha soundcards, you might need to +configure this to 48000 Hz here; if you are using old SoundBlaster cards, like +SoundBlaster Pro, you might need to change this to 22050 Hz. All other values +are possible too and may make sense in certain contexts (&ie; professional +studio equipment).</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Quality:</guilabel></term> +<listitem> +<para>These settings allow you to configure the quality of the sounds that +will be played.</para> +<tip> +<para>Note that a higher sound quality causes a higher <acronym>CPU</acronym> +usage.</para> +<para>If you find sound is slow, or using too much +<acronym>CPU</acronym>, try reducing this setting.</para> +</tip> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Override device location:</guilabel></term> +<listitem> +<para>Normally, the sound server defaults to using the device called +<filename class="devicefile">/dev/dsp</filename> for sound output. This +should work in most cases. An exception is, for instance, if you are using +devfs, then you should use <filename +class="devicefile">/dev/sound/dsp</filename> instead. Other alternatives +are things like <filename class="devicefile">/dev/dsp0</filename> or +<filename class="devicefile">/dev/dsp1</filename> if you have a +soundcard that supports multiple outputs or you have multiple +soundcards.</para> +<tip> +<para>If you often use non-&arts; aware applications, and you have a +soundcard that supports it, try setting &arts; to use a different +device than <filename class="devicefile">/dev/dsp</filename>. This +way, other applications will be able to use the default device, while +&arts; is still running, without giving any error messages.</para> +</tip> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Other custom options:</guilabel></term> +<listitem><para>There are some options offered by +&arts; which may not be available in this control module, so you can add +command line options here which will be passed directly to +<application>artsd</application>. The options will be appended, so they +will override the choices made in the +<acronym>GUI</acronym>. To see the possible choices, open a &konsole; +window, and type <userinput><command>artsd</command> +<option>-h</option></userinput>.</para> +</listitem> +</varlistentry> + + +</variablelist> + +</sect2> + +&midi-kcontrol; + +</sect1> + +</article> diff --git a/doc/kcontrol/arts/midi.docbook b/doc/kcontrol/arts/midi.docbook new file mode 100644 index 000000000..b92fdffb3 --- /dev/null +++ b/doc/kcontrol/arts/midi.docbook @@ -0,0 +1,24 @@ +<sect2 id="midi"> +<sect2info> +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</sect2info> +<title><acronym>MIDI</acronym> Configuration</title> + +<para>This section is used to determine which <acronym>MIDI</acronym> device +&kde; should use. You can also install a <acronym>MIDI</acronym> wrapper around +the device if you want.</para> + +<para>The use of this module is simple. Click once on the +<acronym>MIDI</acronym> device that you would like to use from the +list.</para> + +<para>If you want to use a <acronym>MIDI</acronym> mapper, simply mark +the checkbox below the list labeled <guilabel>Use MIDI +Mapper</guilabel>. This will allow you to select the map in the text +box below. You can click on the folder icon to browse your filesystem +to find the map if you need it.</para> + +</sect2>
\ No newline at end of file diff --git a/doc/kcontrol/background/Makefile.am b/doc/kcontrol/background/Makefile.am new file mode 100644 index 000000000..2a68936db --- /dev/null +++ b/doc/kcontrol/background/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/background diff --git a/doc/kcontrol/background/index.docbook b/doc/kcontrol/background/index.docbook new file mode 100644 index 000000000..5241462c0 --- /dev/null +++ b/doc/kcontrol/background/index.docbook @@ -0,0 +1,383 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mark.Donohoe;</author> +<author>&Martin.R.Jones;</author> +<!-- <author>&Duncan.H;</author> --> +<author>&Mike.McBride;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-01-18</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>background</keyword> +<keyword>wallpaper</keyword> +</keywordset> +</articleinfo> + +<sect1 id="background"> + +<title>Background</title> + +<para>The Background module allows you to configure colors or wallpapers for +your desktop background.</para> + +<para>It is comprised of four areas:</para> + +<orderedlist> +<listitem> +<para>Desktop selection area</para> +</listitem> +<listitem> +<para>An area for selecting background images</para> +</listitem> +<listitem> +<para>The background Preview Monitor</para> +</listitem> +<listitem> +<para>An area for determining the background color</para> +</listitem> +</orderedlist> + +<variablelist> +<varlistentry> +<term>Selecting the desktop</term> +<listitem> +<para>The drop down box labeled <guilabel>Setting for +desktop:</guilabel> is used to select the desktop you want to +configure. You can select any of the desktops individually, or you +can select <guilabel>All Desktops</guilabel> and the changes you make +will be applied to all desktops.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Preview Monitor</term> +<listitem> +<para>This is a preview window. It will give you a sense of what to +expect with each change.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Background</guilabel></term> +<listitem> +<para>This section allows you to load a wallpaper on top of the color +gradient chosen in the section below.</para> + +<para>There are three choices available here:</para> + +<variablelist> +<varlistentry> +<term><guilabel>No Picture</guilabel></term> +<listitem> +<para>No picture background will be shown. The color and pattern +choices below will still take effect.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Picture</guilabel></term> +<listitem> +<para>A single picture will be used as the background for the selected +desktops.</para> +<para>How this picture is positioned and scaled can be fine tuned +below.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Slide show</guilabel></term> +<listitem> +<para>&kde; allows you to have an automatic slide show of wallpaper +images. To enable this option, press the <guibutton>Setup...</guibutton> +button. In the resulting dialog you may choose any +image or folder of images available on your computer, using the +<guibutton>Add...</guibutton> button to navigate your file system. +<guibutton>Remove</guibutton> will remove the currently selected +entry from the list.</para> + +<para>You may choose the length of time any image is displayed in the +<guilabel>Change picture after:</guilabel> box, and you may choose +<guibutton>Show pictures in random order</guibutton> if you don't want +them displayed in the order they are listed.</para> + +<tip><para>Displaying wallpaper requires that the image be kept in +memory. If you are low on memory, using a small, tiled image or none +at all is recommended.</para> + +<para>Scaling or centering a small image still requires an image the +size of your display to be maintained in memory.</para></tip> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Options</guilabel></term> +<listitem> + +<variablelist><!-- Positioning --> +<title><guilabel>Position:</guilabel></title> +<varlistentry> +<term>Centered</term> +<listitem><para>The image will be centered on the screen without changing the +size of the image. The background colors will be present anywhere the image +does not cover.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Tiled</term> +<listitem><para>The image will be duplicated until it fills the entire +desktop. The first image will be placed in the upper left corner of the screen, +and duplicated downward and to the right.</para></listitem> +</varlistentry> +<varlistentry> +<term>Center Tiled</term> +<listitem><para>The image will be duplicated until it +fills the entire desktop. The first image will be placed in the center of the +screen, and duplicated upward, downward to the right, and to the left.</para> +</listitem></varlistentry> +<varlistentry> +<term>Centered Maxpect</term> +<listitem><para>The image will be placed in the center of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio of the +original image. This will provide you with an image that is not distorted. +</para></listitem> +</varlistentry> +<varlistentry> +<term>Tiled Maxpect</term> +<listitem> +<para>The image will be placed in the corner of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio +of the original image. This will provide you with an image that is +not distorted. If there is any space over, the image will be +duplicated to fill it. </para> +</listitem> +</varlistentry> +<varlistentry> +<term>Scaled</term> +<listitem><para>The image will be scaled to fit the desktop. It will be +stretched to fit to all four corners. This may distort the image.</para></listitem> +</varlistentry> +<varlistentry> +<term>Centered Auto fit</term> +<listitem> +<para>If the picture fits the desktop size, this mode works like the +centered option. If the picture is larger than the desktop then it is +scaled down to fit while keeping the aspect ratio. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Scale and Crop</term> +<listitem> +<para>Magnify the picture without distorting it until it fills both the +width and height of the desktop (cropping the picture if necessary), and +then center it on the desktop.</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist><!-- Colors --> +<varlistentry> +<term><guilabel>Colors:</guilabel></term> +<listitem> +<para>The first drop down box allows you to choose the type of color, +gradient, or pattern to display under (or in place of) wallpaper.</para> +<tip><para>If you are going to be using a picture as a wallpaper, you +can skip this section of the dialog box.</para> +<para>However, if your chosen wallpaper does not cover the entire +desktop, the chosen colors will still show in the remaining +space.</para></tip> + +<variablelist> +<varlistentry> +<term><guilabel>Single Color</guilabel></term> +<listitem><para>By choosing this mode, you select one color using the +first color bar, and the entire background is covered with this one +color.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Horizontal Gradient</guilabel></term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Primary +Color</guilabel> on the left edge of the screen, and slowly transform into the +color selected by <guilabel>Blend Color</guilabel> by the time it gets to the +right edge of the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Vertical Gradient</guilabel></term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Primary +Color</guilabel> on the top edge of the screen, and slowly transform into the +color selected by <guilabel>Blend Color</guilabel> as it moves to the bottom of +the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Pyramid Gradient</guilabel></term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by +<guilabel>Primary Color</guilabel> in each +corner of the screen, and slowly transform into the color selected by +<guilabel>Blend Color</guilabel> as it moves to the center of the +screen.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Pipecross Gradient</guilabel></term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by +<guilabel>Primary Color</guilabel> in each corner of the screen, and slowly +transform into the color selected by <guilabel>Blend Color</guilabel> +as it moves to the center of the screen. The shape of +this gradient is different than the pyramid gradient.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Elliptic Gradient</guilabel></term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by +<guilabel>Blend Color</guilabel> in the center of the screen, and slowly +transform into the color selected by <guilabel>Primary Color</guilabel> +as it moves to the edges, in an elliptical pattern.</para></listitem> +</varlistentry> + +<varlistentry> +<term><replaceable>Pattern</replaceable></term> +<listitem> +<para>The rest of the list are the names of various patterns +or textures you can choose.</para> +<para>Click on +<guibutton>OK</guibutton>, and &kde; will render the pattern you +selected using the two colors you selected. For more on patterns, see +the section <link linkend="bkgnd-patterns">Adding, Removing and +Modifying Patterns</link>.</para> + +<para>Select the primary color with the first color bar. If you have +chosen a pattern that requires two colors to be set the secondary +color can be set by pressing the appropriate button.</para> +</listitem> +</varlistentry> +</variablelist> + +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<varlistentry> +<term><guilabel>Blending:</guilabel></term> +<listitem> +<para>The drop down box labeled <guilabel>Blending:</guilabel> contains the +options to make a smooth transition (blend) from the wallpaper as it +changes to the background.</para> + +<orderedlist> +<listitem><para>A drop down box allows you to select the blending mode. +Many of the modes are similar to blending modes for background colors. Select +your mode from the list, and the preview window shows you what it will look +like.</para></listitem> +<listitem><para>The <guilabel>Balance</guilabel> slider adjusts the +blending. The results can be seen immediately in the preview +window.</para></listitem> +<listitem><para>The <guilabel>Reverse roles</guilabel> can reverse the +role of the picture and the background for some types of +blending.</para> +</listitem> +</orderedlist> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> +</variablelist> + +<sect2 id="bkgnd-advanced"> +<title>Advanced options</title> +<para>Located below the preview monitor is a button labeled +<guibutton>Advanced Options</guibutton>.</para> + +<para>To use an external program to determine and change the +background of &kde;, simply select <guilabel>Use the following program +for drawing the background</guilabel>. Available &kde; programs are +listed, select one to enable it. To modify your choice, for example +to change the refresh times, you may press the +<guibutton>Modify...</guibutton> button.</para> + +<para>To add a third party application (⪚ +<application>XEarth</application>) you may use the +<guibutton>Add...</guibutton> button. A dialog will open allowing you +to choose your application, and fill in other data about it. You may +remove any entries from this list by selecting it and pressing the +<guibutton>Remove</guibutton> button.</para> + +<para>Using third party external programs to modify or change the +background is beyond the scope of this document, see their respective +documentation for the format of command-line switches and other +configuration information.</para> + +<para>Also in this section you may choose to set the color of text +that is used for icons on the desktop. If you find icon text +difficult to read against a wallpaper or pattern, you can choose a +solid color to show beneath text, or enable a shadow under the text to +enhance its appearance.</para> + +<para>It is possible to set how many lines of text will be shown beneath each icon with the <guilabel>Lines for icon text:</guilabel> If the text is longer than can be shown in the configured number of lines, it will be truncated. You can also set a value for the <guilabel>Width for icon text:</guilabel> option. The value is in pixels, and the default is <guilabel>Auto</guilabel>, which is a default calculated based on the current font. +<!-- TODO: Find out what the actual calculation here is, in case someone needs it --> +</para> + +<para>Finally you can set the <guilabel>Size of the background +cache:</guilabel>. The default (2048 KB) is usually a safe +choice.</para> + +</sect2> + +<sect2 id="bkgnd-patterns"> +<title>Adding, Removing and Modifying Wallpapers and Patterns</title> + +<para>There is a button under the preview monitor labelled <guibutton>Get +New Wallpapers</guibutton> that helps you fetch new wallpaper images from a +selection of popular images from the <ulink +url="http://www.kde-look.org">KDE-Look</ulink> website. You can of course +select any image you have available to use as wallpaper, and it may be +stored in any location on your hard drive. To have a wallpaper show up in +the list automatically for all users, you should save it to the <filename +class="directory">$<envar>KDEDIR</envar>/share/wallpapers</filename> +folder.</para> + +<para>A pattern is a picture file which &kde; uses as a template to +draw your background. The picture file provides the shapes, but &kde; +provides the colors. &kde; is packaged with several patterns, and you also +can add new patterns.</para> + +<para>To add a new pattern that is available to every user on your +computer, simply place the file in <filename +class="directory">$<envar>KDEDIR</envar>/share/apps/kdesktop/patterns/</filename>.</para> + +<para>Copy a <literal role="extension">.desktop</literal> file from +this folder, and name it the same as your new pattern image file. +Modify the contents to suit your new pattern.</para> + +<para>To add a new pattern for a single user, add the files to +<filename +class="directory">$<envar>KDEHOME</envar>/share/apps/kdesktop/patterns/</filename>.</para> + +<para>For best results, the pattern should be a grayscale PNG file.</para> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/bell/Makefile.am b/doc/kcontrol/bell/Makefile.am new file mode 100644 index 000000000..dbbc3935c --- /dev/null +++ b/doc/kcontrol/bell/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/bell diff --git a/doc/kcontrol/bell/index.docbook b/doc/kcontrol/bell/index.docbook new file mode 100644 index 000000000..2974c0707 --- /dev/null +++ b/doc/kcontrol/bell/index.docbook @@ -0,0 +1,74 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> +<authorgroup> +<author> +<firstname>Pat</firstname> +<surname>Dowler</surname> +</author> + +<author> +<firstname>Matthias</firstname> +<surname>Hoelzer</surname> +</author> + +<author> +<firstname>Mike</firstname> +<surname>McBride</surname> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +<date>2003-10-16</date> +<releaseinfo>3.2</releaseinfo> +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>Bell</keyword> +<keyword>Settings</keyword> +</keywordset> +</articleinfo> + +<sect1 id="bell"> +<title>System bell</title> + +<para>The system bell or beep is a feature of the X server, which +attempts to make good use of the available hardware. </para> + +<para>&kde; normally doesn't use the system bell; instead using its +own system notifications, which could include log entries, message +popups, or its own beep. You can configure these in the +<guilabel>System Notifications</guilabel> &kcontrol; module.</para> + +<note><para>It isn't always possible for the X server to actually make +a beep sound with exactly the parameters selected due to hardware +limitations. For example, on most PCs, volume control is not very good +so the X server seems to fake low volume with a reduced duration of +the sound. Thus, if the settings don't seem to do anything, this is +because the X server and/or the hardware don't support anything +better.</para></note> + +<para>Users are able to set the following parameters for the bell:</para> + +<itemizedlist> +<listitem> <para>volume (percentage of <quote>maximum</quote> volume)</para> </listitem> +<listitem> <para>pitch (in Hz)</para> </listitem> +<listitem> <para>duration (in milliseconds)</para> </listitem> +</itemizedlist> + +<para>You can use the <guibutton>test</guibutton> button to hear how +the current settings will sound.</para> + +<sect2 id="bell-author"><title>Section Authors</title> +<para>Pat Dowler, Matthias Hoelzer <email>[email protected]</email></para> +<para>Converted to KDE 2.0 by Mike McBride <email>[email protected]</email></para> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> +</sect2> +</sect1> + +</article> diff --git a/doc/kcontrol/cache/Makefile.am b/doc/kcontrol/cache/Makefile.am new file mode 100644 index 000000000..12a7570f3 --- /dev/null +++ b/doc/kcontrol/cache/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/cache diff --git a/doc/kcontrol/cache/index.docbook b/doc/kcontrol/cache/index.docbook new file mode 100644 index 000000000..7392d63fc --- /dev/null +++ b/doc/kcontrol/cache/index.docbook @@ -0,0 +1,69 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author><firstname></firstname><surname></surname></author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-12</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>Konqueror</keyword> +<keyword>Cache</keyword> +</keywordset> +</articleinfo> + +<sect1 id="cache"> +<title>Cache</title> + +<para>This module allows you to control the size of the local cache +folder used by &konqueror;. Note that each user account on your +computer has a separate cache folder, and this folder is not +shared with other web browsers such as &Netscape;.</para> + +<para>Storing local copies of web pages that you have visited allows +&konqueror; to quickly load their contents on subsequent visits. It +will only be necessary to reload the contents from the original site +if they have changed since your last visit, or if you click the reload +button in &konqueror;.</para> + +<para>If you really don't want any of the web pages you visit to be +stored on your computer, you can disable &konqueror;'s disk cache by +clearing the checkbox labeled <guilabel>Use cache</guilabel>.</para> + +<para>You can set here how aggressively &konqueror; keeps the cache up +to date. <guilabel>Keep cache in sync</guilabel> means that &konqueror; +will hit the cache for all objects, downloading them if they are not +there, and then display the item from the cache. <guilabel>Use cache +whenever possible</guilabel> means that &konqueror; will try the cache, +and if an object is not there, it will directly download it for display. +<guilabel>Offline browsing mode</guilabel> means that &konqueror; will +try the cache, and if an object is not there, it will not attempt to +download it from the Internet.</para> + +<para>You can control the size of the cache by typing a number into the +text box labeled <guilabel>Disk cache size</guilabel>. This is the +average amount of space in kilobytes that the cache folder is allowed +to use. When the cache grows too large, &konqueror; will delete older +files to reduce the size of the cache folder.</para> + +<para>This is however, only an average, and during a browsing session +the cache could become substantially larger.</para> + +<para>You can use the <guibutton>Clear Cache</guibutton> button to empty +the cache at any time.</para> +</sect1> + +</article> diff --git a/doc/kcontrol/clock/Makefile.am b/doc/kcontrol/clock/Makefile.am new file mode 100644 index 000000000..a38969bfe --- /dev/null +++ b/doc/kcontrol/clock/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/clock diff --git a/doc/kcontrol/clock/index.docbook b/doc/kcontrol/clock/index.docbook new file mode 100644 index 000000000..88fd8c317 --- /dev/null +++ b/doc/kcontrol/clock/index.docbook @@ -0,0 +1,74 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-19</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>clock</keyword> +<keyword>date</keyword> +<keyword>time</keyword> +<keyword>set</keyword> +<keyword>configure</keyword> +</keywordset> +</articleinfo> + +<sect1 id="datetime"> + +<title>Date & Time</title> + +<para>You can use this module to alter the system date and time, using a +convenient graphical interface.</para> + +<note><para>You must have system administrator (<systemitem +class="username">root</systemitem>) access to change the system date and +time. If you do not have this access level, this module will only show +you the current settings.</para></note> + +<para>When you first start, you are in display mode only. To modify +your settings, click on <guibutton>Administrator Mode</guibutton>. If +you are logged in as <systemitem class="username">root</systemitem>, +you will go straight to the change dialog. If not, &kde; will ask for +a superuser password.</para> + +<sect2 id="date-change"> +<title>Modifying your settings</title> + +<para>You set the date using the left half of the module. Simply +choose your month (the drop down box at the top), year (the spin box +at the top), and the day of the month (simply click on the day in the +calendar).</para> + +<para>You set the time using the spin boxes at the bottom of the clock. +You can also directly enter your value.</para> + +<note><para>The time is represented in 24 hour format. If you want +the system time to be set to 8:00 PM, you need to set the hour spinbox +to <guilabel>20</guilabel> (8 + 12). If you want the system time set +to 8:00 AM, you should set the hour spinbox to +<guilabel>8</guilabel>.</para></note> + +<para>To set a new time zone, simply select one from +the drop down box at the bottom.</para> + +<para>When you have set the correct date and time, simply click +<guibutton>Apply</guibutton> to make the changes permanent.</para> +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/colors/Makefile.am b/doc/kcontrol/colors/Makefile.am new file mode 100644 index 000000000..ec7030b15 --- /dev/null +++ b/doc/kcontrol/colors/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/colors diff --git a/doc/kcontrol/colors/index.docbook b/doc/kcontrol/colors/index.docbook new file mode 100644 index 000000000..c47912da9 --- /dev/null +++ b/doc/kcontrol/colors/index.docbook @@ -0,0 +1,132 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Mark.Donohoe; &Mark.Donohoe.mail;</author> +<author>&Martin.R.Jones; &Martin.R.Jones.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-09-22</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>color</keyword> +</keywordset> +</articleinfo> + +<sect1 id="color"> + +<title>Colors</title> +<sect2 id="color-intro"> +<title>Introduction</title> + +<para>The Color Selection module is comprised of 4 sections:</para> + +<orderedlist> +<listitem><para><link linkend="kcmdisplay-preview">The color scheme +preview</link>.</para></listitem> +<listitem><para><link linkend="kcmdisplay-widget-color">The current +<guilabel>Widget Color</guilabel></link>.</para> +</listitem> +<listitem><para><link linkend="kcmdisplay-color-schemes">The available Color +Schemes</link>.</para></listitem> +<listitem><para><link linkend="kcmdisplay-contrast">The contrast +slider</link>.</para></listitem> +</orderedlist> + +<note><para>A <emphasis>Widget</emphasis> is a commonly-used +programmer's term for referring to User Interface elements such as +buttons, menus, and scroll bars. You can think of them as the +fundamental pieces that are assembled to make your +application.</para></note> + +<sect3 id="kcmdisplay-preview"> +<title>Preview</title> + +<para>This section of the dialog demonstrates how a color scheme applies +to a sample selection of widgets. It provides you with a +<guilabel>preview</guilabel> of your current color choices.</para> + +<para>A color scheme consists of a set of 18 colors. </para> + +<para>Each of the widgets is labeled to help you identify how your +changes will impact the color scheme.</para> + +</sect3> + +<sect3 id="kcmdisplay-widget-color"> +<title><guilabel>Widget Color</guilabel></title> + +<para>The currently selected member of the color scheme is shown in the +combo box. This widget color can be changed by clicking on the colored +box below the combo box. A color selection dialog will then appear, from +which you may select a new color. When you are happy with your color +selection, press <guibutton>OK</guibutton> in the color selection +dialog. The color will be updated in the Preview Area.</para> + +<para>You may select any member of the color scheme from the +color combination box.</para> + +</sect3> + +<sect3 id="kcmdisplay-contrast"> +<title><guilabel>Contrast</guilabel> Slider</title> + +<para>The <guilabel>Contrast</guilabel> slider allows you to change the +contrast between different shadings of the selected colors.</para> + +<para>The preview area instantly updates to show the effect of your +change.</para> + +</sect3> + +<sect3 id="kcmdisplay-color-schemes"> +<title><guilabel>Color Scheme</guilabel></title> + +<para>Various color schemes are supplied with &kde;, and you are free to +define your own.</para> + +<para>The three major color components of each scheme are shown beside +the name in the list. To preview a scheme in the larger preview area, +click on its name in the list box. </para> + +<para>You can use the &kde;-supplied Color Schemes as a starting point +to devise your own Scheme. Click on the <guibutton>Save +Scheme...</guibutton> button to store the color scheme under a new name, +then modify it. </para> + +<para>When such a user-created Color Scheme is selected, changes to it +(as shown in the Preview) can be saved with the <guibutton>Save +Scheme...</guibutton> button; it can also be deleted with the +<guibutton>Remove Scheme</guibutton> button.</para> + +<note><para>The &kde;-supplied Schemes themselves cannot be changed or +deleted.</para></note> + +<para>You can use the <guibutton>Import Scheme...</guibutton> button to +add new entries to the list. This might be color schemes that you +have created on another computer and saved, or color schemes you have +downloaded from a website.</para> + +<para>You can choose if you want &kde; to apply the color scheme even +to non-&kde; applications by enabling the <guilabel>Apply colors to +non-KDE applications</guilabel>. Not all applications will allow +this, but most do.</para> + +</sect3> +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/cookies/Makefile.am b/doc/kcontrol/cookies/Makefile.am new file mode 100644 index 000000000..ed988eefc --- /dev/null +++ b/doc/kcontrol/cookies/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/cookies diff --git a/doc/kcontrol/cookies/index.docbook b/doc/kcontrol/cookies/index.docbook new file mode 100644 index 000000000..a1ea6fdd7 --- /dev/null +++ b/doc/kcontrol/cookies/index.docbook @@ -0,0 +1,211 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-12</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>cookie</keyword> +</keywordset> + +</articleinfo> + +<sect1 id="cookie"> +<title>Cookies</title> + +<para>Cookies are a mechanism used by web sites to store and retrieve +information using your browser. For example, a web site may allow you +to customize the content and layout of the pages you see, so that your +choices are persistent across different visits to that web site.</para> + +<para>The web site is able to remember your preferences by storing a +cookie on your computer. Then, on future visits, the web site retrieves +the information stored in the cookie to format the content of the site +according to your previously specified preferences.</para> + +<para>Thus, cookies play a very useful role in web browsing. +Unfortunately, web sites often store and retrieve information in cookies +without your explicit knowledge or consent. Some of this information may +be quite useful to the web site owners, for example, by allowing them to +collect summary statistics on the number of visits different areas of +the web sites get, or to customize banner advertising.</para> + +<para>The cookies module of the &kcontrol; allows you to set policies +for the use of cookies when you are browsing the web with the +&konqueror; web browser. </para> + +<warning><para>Note that the policies that you set using this control +module will <emphasis>not</emphasis> apply to other web browsers such +as &Netscape;.</para></warning> + +<sect2 id="cookie-policy"> + +<title>Policy</title> + +<para>Using the <guilabel>Policy</guilabel> tab, you can configure the +&kde; applications that will handle cookies. You can do this by specifying a +general cookie policy as well as special cookie policies for certain +domains or hosts.</para> + +<para>The top of the policy tab has a checkbox labeled <guilabel>Enable +cookies</guilabel>. If you leave this unchecked, cookies will be +completely disabled. However, this may make browsing rather +inconvenient, especially as some web sites require the use of browsers +with cookies enabled.</para> + +<para>You will probably want to enable cookies and then set +specific policies on how you want them to be handled.</para> + +<para>The first group of options create settings that apply to all cookies.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Only accept cookies from originating server</guilabel></term> +<listitem> +<para>Some pages try to set cookies from servers other than the one +you are seeing the <acronym>HTML</acronym> page from. For example, +they show you advertisements, and the advertisements are from another +computer, often one that belongs to a large advertising group. These +advertisements may try to set a cookie which would allow them to +track the pages you view across multiple web sites.</para> +<para>Enabling this option will mean only cookies that come from the +same web server as you are explicitly connecting to will be +accepted.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Automatically accept session cookies</guilabel></term> +<listitem> + +<para>An increasingly common use for cookies is not to track your +movements across many visits to a web site, but to just follow what you +do during one single visit. Session cookies are saved as long as you +are looking at the site, and deleted when you leave it.</para> + +<para>Web sites can use this information for various things, most +commonly it is a convenience so that you do not have to keep logging in +to view pages. For example, on a webmail site, without some kind of +session <acronym>ID</acronym>, you would have to give your password +again for each email you want to read. There are other ways to +achieve this, but cookies are simple and very common.</para> + +<para>Enabling this option means that session cookies are always +accepted, even if you don't accept any other kind, and even if you +choose to reject cookies from a particular site, session cookies from +that site will be accepted.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Treat all cookies as session cookies</guilabel></term> +<listitem> +<para>If this option is enabled, all cookies are treated as session +cookies. That is, they are not kept when you leave the +web site.</para> +<note> +<para>The definition of <quote>leave the web site</quote> is vague. +Some cookies may hang around for a little while after you are no +longer viewing any pages on a particular web site. This is +normal.</para> +</note> +</listitem> +</varlistentry> +</variablelist> + +<para>The section for <guilabel>Default Policy</guilabel> sets some +further options that are mutually exclusive — you can choose only one +of these options as the default, but you are free to set a different +option for any specific web server.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Ask for confirmation</guilabel></term> +<listitem> +<para>If this option is selected, you will be asked for confirmation +every time a cookie is stored or retrieved. You can selectively accept +or reject each cookie. The confirmation dialog will also allow you to +set a domain specific policy, if you do not want to confirm each +cookie for that domain.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Accept all cookies</guilabel></term> +<listitem> +<para>If this option is selected, all cookies will be accepted without +asking for confirmation.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Reject all cookies</guilabel></term> +<listitem> +<para>If this option is selected, all cookies will be rejected without +asking for confirmation.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>In addition to the default policy for handling of cookies, which you can +set by selecting one of the three options described above, you can also set +policies for specific host domains using the controls in the <guilabel>Domain +Specific</guilabel> group.</para> + +<para>The Ask, Accept, or Reject policy can be applied to a specific +domain by clicking on the <guibutton>New...</guibutton> button, which +brings up a dialog. In this dialog, you can type the name of the +domain (with a leading dot), then select the policy you want to apply +to this domain. Note that entries may also get added while you are +browsing, if the default policy is to ask for confirmation, and you +choose a general policy for a specific host (for example, by selecting +<guilabel>Reject all cookies from this domain</guilabel> when asked to +confirm a cookie).</para> + +<para>You can also select a specific host domain from the list and click the +<guibutton>Change</guibutton> button to choose a different policy for that +domain than the one shown in the list.</para> + +<para>To delete a domain specific policy, choose a domain from the list, and +then click the <guibutton>Delete</guibutton> button. The default policy will +apply to domains which have been deleted from the list.</para> + +</sect2> + +<sect2 id="cookie-management"> +<title>Management</title> + +<para>In the <guilabel>Management</guilabel> tab you can browse and selectively +delete cookies that have been set in the past.</para> + +<para>In the upper part of this dialog, you can see a list of domains displayed +as a tree. Click on the little <guiicon>+</guiicon> next to a domain to see all +cookies that have been set for this particular target domain. If you select one +of these cookies, you will notice that its contents will show up in the frame +<guilabel>Cookie Details</guilabel> below.</para> + +<para>By clicking the <guibutton>Delete</guibutton> button you can now delete the selected +cookie. Click <guibutton>Delete All</guibutton> to delete all cookies stored.</para> + +<para>Choose <guibutton>Reload List</guibutton> to reload the list +from your hard disk. You might want to do this if you have had the +module open and are testing web sites, or have made many changes in the +module itself.</para> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/crypto/Makefile.am b/doc/kcontrol/crypto/Makefile.am new file mode 100644 index 000000000..3911417ea --- /dev/null +++ b/doc/kcontrol/crypto/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/crypto diff --git a/doc/kcontrol/crypto/index.docbook b/doc/kcontrol/crypto/index.docbook new file mode 100644 index 000000000..1d43131d1 --- /dev/null +++ b/doc/kcontrol/crypto/index.docbook @@ -0,0 +1,205 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-10-17</date> +<releaseinfo>3.1</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>crypto</keyword> +<keyword>SSL</keyword> +<keyword>encryption</keyword> + +</keywordset> +</articleinfo> + +<sect1 id="crypto"> + +<title>Encryption Configuration</title> + +<sect2 id="crypto-intro"> +<title>Introduction</title> +<para>Many applications within &kde; are capable of exchanging information using +encrypted files and/or network transmissions.</para> +</sect2> + +<sect2 id="crypto-use"> +<title>Use</title> + +<warning><para>All encryption schemes are only as strong as their +weakest link. In general, unless you have some previous +training/knowledge, it is better to leave this module +unchanged.</para></warning> + +<para>The options within this module can be divided into two +groups:</para> + +<para>Two options along the bottom of the module, <guilabel>Warn on +entering SSL Mode</guilabel> and <guilabel>Warn on leaving SSL +mode</guilabel>, allow you to determine if &kde; should inform you when +you enter or leave SSL encryption.</para> + +<para>The remainder of the options are about determining which +encryption methods to use, and which should not be used. Once you have +selected the appropriate encryption protocols, simply click +<guibutton>Apply</guibutton> to commit your changes.</para> + +<tip><para>Only make changes to this module if specific information +about the strength or weakness of a particular encryption method is +given to you from <emphasis>a reliable source</emphasis>.</para></tip> + +</sect2> + +<!-- Ugh.. write a bunch of stuff about the rest of it --> +<sect2 id="ssl_tab"> +<title>The <guilabel>SSL</guilabel> Tab</title> + +<para>The first option is <guilabel>Enable TLS support if supported by +the server</guilabel>. <acronym>TLS</acronym> is Transport Layer +Security, and is the newest version of <acronym>SSL</acronym>. It +integrates better than <acronym>SSL</acronym> with other protocols, +and it has replaced <acronym>SSL</acronym> in protocols such as POP3 +and <acronym>SMTP</acronym>.</para> + +<para>Then next options are <guilabel>Enable SSL v2</guilabel> and +<guilabel>Enable SSL v3</guilabel>. These are the second and third +revision of the <acronym>SSL</acronym> protocol, and it is normal to +enable both.</para> + +<para>There are several different <firstterm>Ciphers</firstterm> +available, and you can enable these separately in the lists labeled +<guilabel>SSL v2 Ciphers to Use</guilabel> and <guilabel>SSL v3 +Ciphers to Use</guilabel>. The actual protocol to use is negotiated +by the application and the server when the connection is +created.</para> + +<para>There are several <guilabel>Cipher Wizards</guilabel> to help +you choose a set that is suitable for your use.</para> + +<variablelist> +<varlistentry> +<term><guibutton>Most Compatible</guibutton></term> +<listitem> +<para>Select the settings found to be most compatible with the most +servers.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guibutton>US Ciphers Only</guibutton></term> +<listitem> +<para>Select only the US <quote>strong</quote> (128 bit or greater) +ciphers.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Export Ciphers Only</guibutton></term> +<listitem> +<para>Select only the weak (56 bit or less) ciphers.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Enable All</guibutton></term> +<listitem> +<para>Select all ciphers and methods.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Finally, there are some general <acronym>SSL</acronym> settings.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Use EGD</guilabel></term> +<listitem> +<para>If selected, <application>OpenSSL</application> will be asked to +use the entropy gathering daemon (<acronym>EGD</acronym>) for +initializing the pseudo-random number generator.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use entropy file</guilabel></term> +<listitem> +<para>If selected, <application>OpenSSL</application> will be asked to +use the given file as entropy for initializing the pseudo-random number +generator.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Warn on entering SSL mode</guilabel></term> +<listitem> +<para>If selected, you will be notified when entering an +<acronym>SSL</acronym> enabled site.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Warn on leaving SSL mode</guilabel></term> +<listitem> +<para>If selected, you will be notified when leaving an +<acronym>SSL</acronym> based site.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Warn on sending unencrypted data</guilabel></term> +<listitem> +<para>If selected, you will be notified before sending unencrypted +data via a web browser.</para> +</listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="openssl"> +<title>The <guilabel>OpenSSL</guilabel> Tab</title> + +<para>Here you can test if your <application>OpenSSL</application> +libraries have been detected correctly by &kde;, with the +<guibutton>Test</guibutton> button.</para> + +<para>If the test is unsuccessful, you can specify a path to the +libraries in the field labelled <guilabel>Path to OpenSSL Shared +Libraries</guilabel>.</para> + +</sect2> + +<sect2 id="your-certificates"> +<title>The <guilabel>Your Certificates</guilabel> Tab</title> + +<para>The list shows which certificates of yours &kde; knows about. +You can easily manage them from here.</para> + +</sect2> + +<sect2 id="authentication"> +<title>The <guilabel>Authentication</guilabel> Tab</title> + +<para>Not yet documented<!-- No "what's this" to get any info from --></para> +</sect2> + +<sect2 id="peer-ssl-certificates"> +<title>The <guilabel>Peer SSL Certificates</guilabel> Tab</title> + +<para>The list box shows which site and personal certificates &kde; +knows about. You can easily manage them from here.</para> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/desktop/Makefile.am b/doc/kcontrol/desktop/Makefile.am new file mode 100644 index 000000000..545365a4a --- /dev/null +++ b/doc/kcontrol/desktop/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/desktop diff --git a/doc/kcontrol/desktop/index.docbook b/doc/kcontrol/desktop/index.docbook new file mode 100644 index 000000000..070ae0d72 --- /dev/null +++ b/doc/kcontrol/desktop/index.docbook @@ -0,0 +1,84 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-20</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>desktop</keyword> +</keywordset> +</articleinfo> + +<sect1 id="desktop"> + +<title>Desktop</title> + +<sect2 id="desktop-appearance"> +<title><guilabel>Appearance Tab</guilabel></title> + +<para>Here you can configure how icons on your desktop appear.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Standard font:</guilabel></term> +<listitem><para>This option can be used to change the typeface used on the +desktop. Simply select your typeface from the dropdown box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Font size:</guilabel></term> +<listitem><para>You can change the relative size of the text on the Desktop. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Normal text color:</guilabel></term> +<listitem><para>This option lets you select the color of normal (or +unhighlighted) text.</para></listitem> +</varlistentry> +<varlistentry><term><guilabel>Text background color:</guilabel></term> +<listitem><para>This option lets you select the background color of +normal text. If left unchecked, the text has a transparent +background. If selected, you can choose the color by pressing the button. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Underline filenames:</guilabel></term> +<listitem><para>Determines if file names are underlined on the +Desktop.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="desktop-number"> +<title><guilabel>Multiple Desktops</guilabel></title> + +<para>&kde; offers you the possibility to have several virtual +desktops. In this tab you can configure the number of desktops as well +as their names. Just use the slider to adjust the number of +desktops. You can assign names to the desktops by entering text into the +text fields below.</para> + +<para>If you enable <guilabel>Mouse wheel over desktop switches +desktop</guilabel> then scrolling the wheel over an empty space on the +desktop will change the the next virtual desktop numerically, in the +direction you scrolled (either up or down).</para> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/desktopbehavior/Makefile.am b/doc/kcontrol/desktopbehavior/Makefile.am new file mode 100644 index 000000000..9ff6d953a --- /dev/null +++ b/doc/kcontrol/desktopbehavior/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/desktopbehavior diff --git a/doc/kcontrol/desktopbehavior/index.docbook b/doc/kcontrol/desktopbehavior/index.docbook new file mode 100644 index 000000000..9011f265d --- /dev/null +++ b/doc/kcontrol/desktopbehavior/index.docbook @@ -0,0 +1,198 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-20</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>desktop</keyword> +</keywordset> +</articleinfo> + +<sect1 id="desktop"> + +<title>Desktop Behavior</title> + +<sect2 id="desktop-desktop"> +<title><guilabel>Desktop</guilabel> Tab</title> + +<variablelist> +<varlistentry> +<term><guilabel>Show icons on desktop</guilabel></term> +<listitem> +<para>Uncheck this option if you do not want to have icons on the +desktop. Without icons the desktop may be somewhat faster, but you +will no longer be able to drag files to the desktop.</para> +<para>This will not remove any files already stored on the desktop, +they will instead be hidden.</para> + +<para>If this is enabled, you may also enable the ability to <guilabel>Allow programs in desktop window</guilabel>.</para> + +<para>Enabling this option allows you to set a program as your desktop +background, for example <command>xearth</command>, or &kworldclock;</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show tooltips</guilabel></term> +<listitem> +<para>Check this option if you would like to see tooltips for icons on +the desktop as you hover the mouse over them. These tooltips display +information about the file represented by the icon. Depending on the +type of file, the information can range from simple file size and +creation dates for unfamiliar file types, to complete meta information +such as the content of tags for music files.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Menu Bar at Top of Screen:</guilabel></term> +<listitem> +<para>This option determines whether there is a menu across +the top of the &kde; Desktop similar to the style of &MacOS;.</para> + +<para>The default is <guilabel>None</guilabel>. If you select +<guilabel>Desktop menu bar</guilabel> one static menu is shown at the +top of the screen, displaying the desktop menu. Finally there is +<guilabel>Current application's menu bar (Mac OS-style)</guilabel>. +If this option is selected, applications won't have their menu bar +attached to their own window anymore. Instead, there is one menu bar +at the top of the screen which shows the menus of the currently active +application. You might recognize this behavior from &MacOS;. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mouse button actions:</guilabel></term> +<listitem> + +<para>The mouse button section allows you to determine what happens when +you click one of the three mouse buttons on the Desktop (where there is +no window).</para> + +<note><para>Not all mice have three buttons. Two button mice can +usually activate the <mousebutton>Middle</mousebutton> button by +pressing both the <mousebutton>Left</mousebutton> and +<mousebutton>Right</mousebutton> mouse buttons at the same +time.</para></note> + +<para>For each of the three mouse buttons, you can select:</para> + +<variablelist> +<varlistentry> +<term>No Action</term> +<listitem><para>When you use this mouse button, nothing +happens.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Window list menu</term> +<listitem><para>This brings up a submenu with all the virtual desktops. +Under each virtual desktop, you can select any window currently located +on that desktop. Once selected, &kde; will switch to that desktop, and +place the focus on that window.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Desktop Menu.</term> +<listitem><para>This brings up a submenu with commands specific to +&kde;. You can create icons, edit bookmarks, cut and paste, +run commands, configure &kde;, arrange icons, lock the session and log +out of &kde;. The exact content of the menu varies depending on the +current status of &kde;. </para></listitem> +</varlistentry> + +<varlistentry> +<term>Application Menu</term> +<listitem><para>This brings up the <guimenu>Application</guimenu> Menus +(also know as the <guimenu>K</guimenu> Menus), so you can start a new +application.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Custom Menu 1</term> +<term>Custom Menu 2</term> +<listitem> +<para>You may also configure up to two custom menus. If you choose either of these, the <guibutton>Edit...</guibutton> becomes available, allowing you to edit the contents of the custom menus.</para> +<!-- FIXME: Need to find out what else can be added here (for instance, it lets me type 'emacsclient' which isn't available in the K menu) --> +</listitem> +</varlistentry> +</variablelist> + +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="desktop-behavior-file-icons"> +<title><guilabel>File Icons</guilabel></title> + +<para>First are two options regarding the placement of icons:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Automatically line up icons</guilabel></term> +<listitem><para>If this option is enabled, &kde; will align icons on a +grid on the desktop. If it is not enabled, you may drop icons +anywhere, and they will not be aligned for you.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show hidden files</guilabel></term> +<listitem><para>If this option is enabled, then all hidden files will +appear on the desktop. Generally this only clutters your desktop area, +but if you are often working with hidden files or folders, this can +be useful.</para> +<warning><para>Be very careful when deleting or modifying hidden files. +Many of these files are configuration files and are essential for the +correct operation of your computer.</para></warning> +</listitem> +</varlistentry> +</variablelist> + +<para>The &kde; desktop has a preview feature for many file types, +including <acronym>HTML</acronym> files, images, &PostScript; and +<acronym>PDF</acronym>, sound, web archives (if you have the +appropriate &konqueror; plugin installed) and text files.</para> + +<para>if you enable previews for one of these, files of that particular +file type will not be represented by standard icons on the desktop, but +will instead be shown as miniature previews. On slow computers, the +previews can take some time to show up, so you might not want to enable +this feature.</para> + +</sect2> + +<sect2 id="desktop-behavior-device-icons"> +<title><guilabel>Device Icons</guilabel></title> + +<para>On some operating systems (&Linux; and FreeBSD, so far) &kde; can +dynamically display icons for each <firstterm>mountable</firstterm> +device you have available. This could be &CD-ROM; drives, floppy disk +drives, or network shares.</para> + +<para>If you enable this, you can choose what kind, if any, of these +devices you would like quick access icons to be displayed for.</para> + +</sect2> +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/ebrowsing/Makefile.am b/doc/kcontrol/ebrowsing/Makefile.am new file mode 100644 index 000000000..4d7741915 --- /dev/null +++ b/doc/kcontrol/ebrowsing/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/ebrowsing diff --git a/doc/kcontrol/ebrowsing/index.docbook b/doc/kcontrol/ebrowsing/index.docbook new file mode 100644 index 000000000..da9167f6e --- /dev/null +++ b/doc/kcontrol/ebrowsing/index.docbook @@ -0,0 +1,156 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<author>&Yves.Arrouye; &Yves.Arrouye.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-10-16</date> +<releaseinfo>3.1</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>enhanced browsing</keyword> +<keyword>web shortcuts</keyword> +<keyword>browsing</keyword> +</keywordset> + +</articleinfo> +<sect1 id="ebrowse"> + +<title>Web Shortcuts</title> + +<sect2 id="ebrowse-intro"> + +<title>Introduction</title> + +<para>&konqueror; offers some features to enhance your browsing +experience. One such feature is <emphasis>Web Shortcuts</emphasis>.</para> + +<para>You may already have noticed that &kde; is very Internet friendly. +For example, you can click on the <guimenuitem>Run</guimenuitem> menu +item or type the keyboard shortcut assigned to that command (<keycombo +action="simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, +unless you have changed it) and type in a <acronym>URI</acronym>. +<footnote><para>Uniform Resource Identifier. A standardized way of +referring to a resource such as a file on your computer, a World Wide +Web address, an email address, +<abbrev>etc...</abbrev>.</para></footnote></para> + +<para>Web shortcuts, on the other hand, let you come up with new pseudo +<acronym>URL</acronym> schemes, or shortcuts, that basically let you +<emphasis>parameterize</emphasis> commonly used +<acronym>URI</acronym>s. For example, if you like the Google search +engine, you can configure KDE so that a pseudo <acronym>URL</acronym> +scheme like <emphasis>gg</emphasis> will trigger a search on +Google. This way, typing <userinput>gg:<replaceable>my +query</replaceable></userinput> will search for <replaceable>my +query</replaceable> on Google.</para> + +<note><para>One can see why we call these pseudo <acronym>URL</acronym> +schemes. They are used like a <acronym>URL</acronym> scheme, but the +input is not properly <acronym>URL</acronym> encoded, so one will type +<userinput>google:kde apps</userinput> and not +<userinput>google:kde+apps</userinput>.</para></note> + +<para>You can use web +shortcuts wherever you would normally use +<acronym>URI</acronym>s. Shortcuts for several search engines should +already be configured on your system, but you can add new keywords, and +change or delete existing ones in the enhanced browsing control +module. </para> + +</sect2> + +<sect2 id="ebrowse-use"> + +<title>Use</title> + +<para>There is a single tab in this control module. The title of the tab +is <guilabel>Keywords</guilabel>. This tab features two main boxes, one +for Internet Keywords and one for web shortcuts.</para> + +<sect3 id="ebrowse-srch-use"> + +<title>Web Shortcuts</title> + +<para>The descriptive names of defined web shortcuts are shown in a +listbox. As with other lists in &kde;, you can click on a column +heading to toggle the sort order between ascending and +descending, and you can resize the columns.</para> + +<para>If you double-click on a specific entry in the list of defined +search providers, the details for that entry are shown in a popup +dialog. In addition to the descriptive name for the item, you can +also see the <acronym>URI</acronym> which is used, as well as the +associated shortcuts which you can type anywhere in &kde; where +<acronym>URI</acronym>s are expected. A given search provider can have +multiple shortcuts, each separated by a comma.</para> + +<para> The text boxes are used not only for displaying information +about an item in the list of web shortcuts, but also for modifying or +adding new items.</para> + +<para>You can change the contents of either the <guilabel>Search +URI</guilabel> or the <guilabel>URI Shortcuts</guilabel> text box. +Click <guibutton>OK</guibutton> to save your changes or +<guibutton>Cancel</guibutton> to exit the dialog with no +changes.</para> + +<para>If you examine the contents of the <guilabel>Search +URI</guilabel> text box, you will find that most, if not all of the +entries have a <option>\{@}</option> in them. This sequence of two +characters acts as a parameter, which is to say that they are replaced +by whatever you happen to type after the colon character that is +between a shortcut and its parameter. Let's consider some examples to +clarify this idea.</para> + +<para>Suppose that the <acronym>URI</acronym> is +<userinput>http://www.google.com/search?q=\{@}</userinput>, and +<userinput>gg</userinput> is a shortcut to this +<acronym>URI</acronym>. Then, typing +<userinput>gg:<replaceable>alpha</replaceable></userinput> is +equivalent to +<userinput>http://www.google.com/search?q=<replaceable>alpha</replaceable></userinput>. +You could type anything after the <userinput>:</userinput> character; +whatever you have typed simply replaces the <option>\{@}</option> +characters, after being converted to the appropriate character set for +the search provider and then properly +<acronym>URL</acronym>-encoded. Only the <option>\{@}</option> part of +the search <acronym>URI</acronym> is touched, the rest of it is +supposed to be properly <acronym>URL</acronym>-encoded already and is +left as is.</para> + +<para>You can also have shortcuts without parameters. Suppose the +<acronym>URI</acronym> was +<emphasis>file:/home/me/mydocs/kofficefiles/kword</emphasis> and the +shortcut was <emphasis>mykword</emphasis>. Then, typing +<userinput>mykword:</userinput> is the same as typing the complete +<acronym>URI</acronym>. Note that there is nothing after the colon +when typing the shortcut, but the colon is still required in order for +the shortcut to be recognized as such.</para> + +<para>By now, you will have understood that even though these shortcuts +are called web shortcuts, they really are shortcuts to parameterized +<acronym>URI</acronym>s, which can point not only to web sites like +search engines but also to anything else that can be pointed to by a +<acronym>URI</acronym>. Web shortcuts are a very powerful feature of +navigation in &kde;.</para> + +</sect3> + +</sect2> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/email/Makefile.am b/doc/kcontrol/email/Makefile.am new file mode 100644 index 000000000..137c9a103 --- /dev/null +++ b/doc/kcontrol/email/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/email diff --git a/doc/kcontrol/email/index.docbook b/doc/kcontrol/email/index.docbook new file mode 100644 index 000000000..b34e44b13 --- /dev/null +++ b/doc/kcontrol/email/index.docbook @@ -0,0 +1,103 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-09-01</date> +<releaseinfo>3.1.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>email</keyword> +<keyword>e-mail</keyword> +</keywordset> + +</articleinfo> +<sect1 id="e-mail"> +<title>Email</title> + + +<sect2 id="email-intro"> +<title>Introduction</title> + +<para>The email module of the &kcontrol; allows you to enter and save some +basic email information. This information is used when performing functions +related to email within &kde;, for example, when sending bug reports from the +&kde; crash handler application.</para> + +<para>Programs such as &kmail;, which are used for reading and sending +email, may offer many more options for customizing the way in which +email is handled. These options depend upon the specific program being +used. &kmail;, for instance, offers its own configuration +facilities.</para> + +<para>Some of the information needed for configuring email should have +been provided by your internet service provider +(<acronym>ISP</acronym>). If you are connected to a local network, then +the system administrator of your network should be able to help +you.</para> + +</sect2> + +<sect2 id="email-use"> +<title>Use</title> + +<para>&kde; automatically establishes some of the information for this control module +using the +login information on the system. You will need to enter the remaining information.</para> +<para>Looking at the page from top to +bottom, the options are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Full name</guilabel></term> +<listitem><para>Type your full name as you would like it to appear in the email +messages that you send. </para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Organization</guilabel></term> +<listitem><para>If you work for a company or +organization, you can enter its name in this text box.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Email address</guilabel></term> +<listitem><para>To be able to use email, you must enter your email +address here.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reply-to address</guilabel></term> +<listitem><para>If replies to your email messages should be sent to a different +address, you can enter that address in this text box.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +</sect1> + +</article> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-indent-step:0 +sgml-indent-data:nil +sgml-parent-document:index.docbook +End: +--> + diff --git a/doc/kcontrol/energy/Makefile.am b/doc/kcontrol/energy/Makefile.am new file mode 100644 index 000000000..b45cc2539 --- /dev/null +++ b/doc/kcontrol/energy/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/energy diff --git a/doc/kcontrol/energy/index.docbook b/doc/kcontrol/energy/index.docbook new file mode 100644 index 000000000..94d7a2745 --- /dev/null +++ b/doc/kcontrol/energy/index.docbook @@ -0,0 +1,110 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>energy</keyword> +</keywordset> +</articleinfo> + +<sect1 id="energy"> +<title>Energy</title> + +<sect2 id="energy-intro"> +<title>Introduction</title> + +<para>This module is useful for any computer having a monitor labeled +Energy Star Compliant. (Energy Star Compliant equipment is equipment +that can be configured to automatically enter a power saving mode when +appropriate, without human intervention.)</para> + +<tip><para>Energy Star Compliance can be applied to nearly any +electrical device. This module, however, does not spin down hard +drives, does not shutdown printers, &etc; These settings only affect +the behavior of your monitor.</para> + +<para>For information on shutting down components on a laptop, do not +use this module. Instead, install kdeutils, and refer to the module +entitled <ulink url="help://kcontrol/powerctrl/index.html">Laptop +Power Control Center</ulink>, for details.</para></tip> + +<para>In the case of computer monitors, the computer can control the +monitor, switching it between four states: On, Standby, Suspend, and +Off.</para> + +<note><para>The following list of states is a generalization, and you +may find that your monitor will differ from the descriptions +below.</para></note> + +<para><quote>ON</quote> is the normal operation of your monitor while you are using +it.</para> + +<para><quote>STANDBY</quote> is usually a minor power saving level. +This setting usually involves blanking the screen, and not firing the +electron gun, but keeping the electron gun <quote>energized</quote> +and ready to go. When you need to use the monitor again, the monitor +will come back on very quickly.</para> + +<para><quote>SUSPEND</quote> is a very low power mode alternative. +With most monitors the screen is blanked, the electron +gun is shut down and the magnets that control the electron gun are +powered down. While the power saving is substantial, to reactivate +the monitor may take up to 10-15 seconds. The computer should always +be able to return the monitor to On or Standby while in suspend +mode.</para> + +<para><quote>OFF</quote>, usually means just that. The computer +monitor is turned off. This usually means that the computer will not +be able to turn the monitor back on by itself. Obviously, this keeps +power consumption to a bare minimum (zero).</para> + +</sect2> +<sect2 id="energy-use"> +<title>Use</title> + +<para>Using this module is very simple:</para> + +<para>If your monitor is Energy Star Compliant, then you should put a +mark in the check box labeled <guilabel>Enable Display Energy +Saving</guilabel>. This will activate the energy saving +commands. </para> + +<para>The next three slider bars, tell the computer how many minutes of +inactivity before automatically switching to a new state. These numbers +can be adjusted with either the sliders, or the spin boxes.</para> + +<note><para>These times are not additive, but all start counting at +zero.</para> + +<para>As an example:</para> + +<para>If you set the Standby Mode to 10 minutes, the Suspend mode to 20 +minutes, and the Power off at 30 minutes, and you stop using your +computer at 9:00, then the monitor will:</para> <para>Enter Standby mode +at 9:10, enter Suspend mode at 9:20, and shut the power off at +9:30.</para></note> + +<para>When you are happy with the settings, click +<guibutton>OK</guibutton>.</para> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/filemanager/Makefile.am b/doc/kcontrol/filemanager/Makefile.am new file mode 100644 index 000000000..8e045365e --- /dev/null +++ b/doc/kcontrol/filemanager/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/filemanager diff --git a/doc/kcontrol/filemanager/index.docbook b/doc/kcontrol/filemanager/index.docbook new file mode 100644 index 000000000..be620a8cf --- /dev/null +++ b/doc/kcontrol/filemanager/index.docbook @@ -0,0 +1,297 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-10-16</date> +<releaseinfo>3.1</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>file manager</keyword> +</keywordset> +</articleinfo> +<sect1 id="file-manager"> +<title>File Manager</title> + +<para>In this module, you can configure various aspects of +&konqueror;'s file manager functionality. </para> + +<note><para>&konqueror;'s web browser functionality has its <ulink +url="help:/kcontrol/khtml/index.html">own configuration +modules</ulink>.</para></note> + +<sect2 id="fileman-use"> +<title>Use</title> + +<para> The configuration options for the file manager are +organized under tabs as follows:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Appearance</guilabel></term> +<listitem><para>This tab contains options for customizing the appearance of +&konqueror; windows, such as the default font +text color.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Behavior</guilabel></term> +<listitem><para>This tab contains a couple of &konqueror; +global options.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Previews</guilabel></term> +<listitem> +<para>On this tab, you can customize when &konqueror; should show +previews.</para> +</listitem> +</varlistentry> +</variablelist> + +<sect3 id="fileman-appearance"> +<title>Appearance</title> + +<para>The following settings determine how text and colors are displayed in +&konqueror; File Manager mode windows.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Standard font:</guilabel></term> +<listitem> +<para>This is the font used to display text such as file names in +&konqueror; windows.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Font size:</guilabel></term> +<listitem> + +<para>Lets you control the size of text, while the <guilabel>Standard +Font</guilabel> setting determines the font face used.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Normal text color:</guilabel></term> +<listitem> +<para>Determines the standard text color.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Height for icon text:</guilabel></term> +<listitem> +<para>The maximum number of lines that can be used to draw icon text. Long lines are truncated at the end of the last line.</para> +<tip> <para>You can still see word-wrapped filenames by pausing the mouse pointer over the icon.</para></tip> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Width for icon text:</guilabel></term> +<listitem> +<para>The maximum width for the icon text when &konqueror; is in multi-column view mode.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Underline filenames:</guilabel></term> +<listitem> +<para>When <guilabel>Underline filenames</guilabel> is checked, + filenames will be underlined so that they look like links on a web + page.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Display file sizes in bytes:</guilabel></term> +<listitem> +<para>The final check box on this page determines how &konqueror; +displays file sizes, when you are in one of the file manager modes +that normally shows this information. If you check the +<guilabel>Display file sizes in bytes</guilabel> box then file sizes +are always shown in bytes. If you leave it unchecked then file sizes +are shown in bytes, kilobytes or megabytes, depending on their +size.</para> +</listitem> +</varlistentry> +</variablelist> +</sect3> + +<sect3 id="fileman-behav"> +<title>Behavior</title> + +<variablelist> +<title><guilabel>Misc Options</guilabel></title> +<varlistentry> +<term>Open folders in separate windows</term> +<listitem> <para>If this option is checked, a new +&konqueror; window will be created when you open a +folder, rather than simply showing that folder's contents in the + current +window.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Show network operations in a single window</term> +<listitem> +<para>If unchecked, and you download a +file, a dialog box will appear that shows the status of the +download.</para> + +<screenshot> + <screeninfo>Download Dialog Box</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="kfileman2.png" + format="PNG"/></imageobject> + <textobject> <phrase>Download Dialog Box</phrase> </textobject> + <caption> + <para>Individual Download Dialog Box</para> + </caption> + </mediaobject> +</screenshot> + +<para>If you start a new transfer, another dialog box will +appear. (&Netscape; users will be familiar with +this behavior) </para> + +<para>If checked, all transfer status windows will be grouped +together under a single dialog box.</para> +<screenshot> + <screeninfo>Download Dialog Box</screeninfo> + <mediaobject> + <imageobject><imagedata fileref="kfileman1.png" + format="PNG"/></imageobject> + <textobject><phrase>Download Dialog Box</phrase></textobject> + <caption> + <para>Collected Download Dialog Box</para> + </caption> + </mediaobject> +</screenshot> + +<para>If you choose to use the Collected download dialog box, you can +delete transfers by clicking once on the transfer you want to cancel, +then clicking the <guibutton>Delete</guibutton> Button on the +left.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show file tips</guilabel></term> +<listitem> +<para> Here you can control if, when moving the mouse over a file, you +want to see a small popup window with additional information about +that file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show previews in file tips</guilabel></term> +<listitem> +<para>Here you can control if the file tip should show a +thumbnail preview of the file. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Home URL</guilabel></term> +<listitem><para>This is the &URL; (⪚ a +folder or a web page) where &konqueror; will jump to +when the <guibutton>Home</guibutton> button is pressed.</para><para>The +default is the users home folder, indicated with a +<literal>~</literal>.</para></listitem> +</varlistentry> +</variablelist> + +<para>You can set a path that is your <guilabel>Home URL</guilabel> by +typing into the text field, or using the <guiicon>browse</guiicon> +icon. The default is <literal>~</literal> which is a standard +shortcut for your $<envar>HOME</envar> folder. When you choose the +<guiicon>home</guiicon> icon on your panel, in a file open or save +dialog, or from within &konqueror; in file manager mode, this is the +folder you will be shown.</para> + +<para>The <guilabel>Ask confirmation for</guilabel> setting tells +&konqueror; what to do when you choose to <quote>Delete</quote>, +<quote>Trash</quote>, or <quote>Shred</quote> a file in a &konqueror; +window. If any box is checked, &konqueror; asks for confirmation before +performing the corresponding action.</para> + +</sect3> + +<sect3> +<title>Previews</title> + +<para>&konqueror; has a +preview feature for many file types, including <acronym>HTML</acronym> +files, images, &PostScript; and <acronym>PDF</acronym>, sound, web +archives (if you have the appropriate &konqueror; plugin installed) +and text files.</para> + +<para>If you enable previews for one of these, files of that particular +file type will not be represented by standard icons in the filemanager, but +will instead be shown as miniature previews. On slow computers, the +previews can take some time to show up, so you might not want to enable +this feature.</para> + +<para>In this module you can specify which <quote>protocols</quote> +you wish the previews to be available for. Creating the previews +requires that &konqueror; download at least part of the file, in order +to create the preview. &konqueror;, like the rest of &kde; is +entirely network transparent, and will treat a remote &FTP; folder +just as if it was on your local hard drive. This can result in a +delay, especially if you are viewing, for example, a folder full of +images over a slow network connection.</para> + +<para>For each protocol, you can independently enable or disable +previews. For example, you might enable previews for +<acronym>NFS</acronym> mounted drives if you have a fast network, but +disable them for &FTP; because your Internet connection is via a +modem.</para> + +<para>You can further refine the maximum size file that &konqueror; +will attempt to show a preview for. The default is 1 MB. In other +words, by default, if a file is 900 kB in size, and the protocol you +are viewing the folder with is enabled, then &konqueror; will +create a preview icon for it. If the file is 1.1 MB in size, +&konqueror; will not make a preview, even if the protocol is +enabled.</para> + +<para>You can turn on and off previews <quote>on the fly</quote> from +within &konqueror;, using the <guimenu>View</guimenu> menu. For +example, if you normally want to see image previews on every protocol, +but find a particular server is very slow to send you the data, you +might turn it off for the present, and turn it on again later.</para> + +<para>You may also like to enable the checkbox <guilabel>Increase size +of previews relative to icons</guilabel>, in order to see more +information in the thumbnails.</para> + +<para>Many image files already contain a thumbnail. You can enable +the <guilabel>Use thumbnails embedded in files</guilabel> to make use +of these. This will save time waiting for thumbnails to be created +when viewing a folder full of images you have not previously seen in +&konqueror;.</para> + +</sect3> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/filemanager/kfileman1.png b/doc/kcontrol/filemanager/kfileman1.png Binary files differnew file mode 100644 index 000000000..0505d604d --- /dev/null +++ b/doc/kcontrol/filemanager/kfileman1.png diff --git a/doc/kcontrol/filemanager/kfileman2.png b/doc/kcontrol/filemanager/kfileman2.png Binary files differnew file mode 100644 index 000000000..6c8d17d75 --- /dev/null +++ b/doc/kcontrol/filemanager/kfileman2.png diff --git a/doc/kcontrol/filetypes/Makefile.am b/doc/kcontrol/filetypes/Makefile.am new file mode 100644 index 000000000..ae43c3018 --- /dev/null +++ b/doc/kcontrol/filetypes/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/filetypes diff --git a/doc/kcontrol/filetypes/index.docbook b/doc/kcontrol/filetypes/index.docbook new file mode 100644 index 000000000..a838156db --- /dev/null +++ b/doc/kcontrol/filetypes/index.docbook @@ -0,0 +1,338 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<title>File Associations</title> +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-13</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>files association</keyword> +<keyword>association</keyword> +</keywordset> +</articleinfo> +<sect1 id="file-assoc"> +<title>File Associations</title> + +<sect2 id="file-assoc-intro"> +<title>Introduction</title> + +<para>One of the most convenient aspects of &kde;, is its ability to +automatically match a data file, with its application. As an example, +when you click on your favorite &kword; document in &konqueror;, &kde; +automatically starts &kword;, and automatically loads that file into +&kword; so you can begin working on it.</para> + +<para>In the example above, the &kword; Data file is +<emphasis>associated</emphasis> with &kword; (the application). These +file associations are crucial to the functioning of &kde;.</para> + +<para>When &kde; is installed, it automatically creates hundreds of file +associations to many of the most common data types. These initial +associations are based on the most commonly included software, and the +most common user preferences.</para> + +<para>Unfortunately, &kde; can not:</para> + +<itemizedlist> +<listitem><para>predict every possible combination of software and data files</para></listitem> +<listitem><para>prepare for file formats not yet invented</para></listitem> +<listitem><para>or predict everyone's favorite application for certain file formats</para></listitem> +</itemizedlist> + +<para>You can change your current file associations or add new file +associations using this module.</para> + +<para>Each file association is recorded as a mime type. +&MIME; stands for <quote>Multipurpose Internet Mail +Extensions</quote>. It allows a computer to determine the type of file, +without opening and analyzing the format of each and every file.</para> + +</sect2> + +<sect2 id="file-assoc-use"> +<title>How to use this module</title> + +<para>The file associations are organized into several categories, and +at a minimum you will have:</para> + +<orderedlist> +<listitem><para>Application</para></listitem> +<listitem><para>Audio</para></listitem> +<listitem><para>Image</para></listitem> +<listitem><para>Inode</para></listitem> +<listitem><para>Message</para></listitem> +<listitem><para>Multipart</para></listitem> +<listitem><para>Print</para></listitem> +<listitem><para>Text</para></listitem> +<listitem><para>Video</para></listitem> +</orderedlist> + +<para>All of the file associations are sorted into one of these +categories.</para> + +<para>There is also an overview category <quote>All</quote>, which +displays all the file types in one list, without categorizing +them.</para> + +<note><para>There is no functional difference between any of the +categories. These categories are designed to help organize your file +associations, but they do not alter the associations in any way. +</para></note> + +<para>The categories are listed in the box labeled <guilabel>Known +Types</guilabel>.</para> + +<para>You can explore each of these categories, and see the file +associations contained within each one, by simply double-clicking on the +category name. You will be presented with a list of the associated +mime-types under that category.</para> + +<tip><para>You can also search for a particular &MIME; type by using the +search box. The search box is labeled <guilabel>Find filename +pattern</guilabel> and is located above the category list.</para> + +<para>Simply type the first letter of the &MIME; type you are interested +in. The categories are automatically expanded, and only the mime-types +that include that letter are displayed.</para> + +<para>You can then enter a second character and the mime-types will be +further limited to mime types containing those two +characters.</para></tip> + +<sect3 id="file-assoc-use-add"> +<title>Adding a new mime type</title> + +<para>If you want to add a new &MIME; type to your file associations, +you can click on the <guibutton>Add...</guibutton> button. A small +dialog box will appear. You select the category from the drop down +box, and type the &MIME; name in the blank labeled <guilabel>Type +name</guilabel>. Click <guibutton>OK</guibutton> to add the new mime +type, or click <guibutton>Cancel</guibutton> to not add any new +mime-types.</para> + +</sect3> + +<sect3 id="file-assoc-use-del"> +<title>Removing a mime type</title> + +<para>If you want to remove a &MIME; type, simply select the &MIME; +type you want to delete by clicking once with the mouse on the &MIME; +type name. Then click the button labeled +<guibutton>Remove</guibutton>. The &MIME; type will be deleted +immediately.</para> + +</sect3> + +<sect3 id="file-assoc-use-edit"> +<title>Editing a mime types properties</title> + +<para>Before you can edit a &MIME; types property, you must first +specify which &MIME; type. Simply browse through the categories until +you find the &MIME; type you want to edit, then click once on it with +the mouse.</para> + +<para>As soon as you have selected the &MIME; type, the current values of +the &MIME; type will appear in the module window.</para> + +<para>You will notice the current values are split into two tabs: +<guilabel>General</guilabel> and <guilabel>Embedding</guilabel></para> + +<variablelist> +<varlistentry> +<term><guilabel>General</guilabel></term> +<listitem> +<para>There are 4 properties for each &MIME; type in this tab:</para> + +<orderedlist> +<listitem><para><guilabel>Mime Type Icon</guilabel> is the icon that +will be visible when using &konqueror; as a file +manager.</para></listitem> +<listitem><para><guilabel>Filename Patterns</guilabel> is a search +pattern which &kde; will use to determine the &MIME; type.</para></listitem> +<listitem><para><guilabel>Description</guilabel> is a short description +of the file type. This is for your benefit only.</para></listitem> +<listitem><para><guilabel>Application Preference Order</guilabel> +determines which applications will be associated with the specified +&MIME; type.</para></listitem> +</orderedlist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Embedding Tab</guilabel></term> +<listitem> +<para>The Embedding tab allows you to determine if an file will be +viewed within a &konqueror; window, or by starting the +application.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3 id="file-assoc-use-icon"> +<title>Changing the Icon</title> + +<para>To change the icon, simply click on the Icon button. A dialog box +will appear, which will show you all available icons. Simply click once +with the mouse on the icon of your choice, and click +<guibutton>OK</guibutton>.</para> + +</sect3> + +<sect3 id="file-assoc-use-pattern"> +<title>Editing the mime-type patterns</title> + +<para>The box labeled <guilabel>Filename Patterns</guilabel>, determines +what files will be included within this mime-type.</para> + +<para>Usually, files are selected based on their suffix. (Examples: +Files that end with <literal role="extension">.wav</literal> are sound +files, using the WAV format and files that end in <literal +role="extension">.c</literal> are program files written in C).</para> + +<para>You should enter your filename mask in this combo box.</para> + +<para>The asterisk (<literal>*</literal>) is a wildcard character that +will be used with nearly every mime type mask. A complete discussion +of wildcards is beyond the scope of this manual, but it is important +to understand that the asterisk (in this context), +<quote>matches</quote> any number of characters. As an example: +<userinput>*.pdf</userinput> will match +<filename>Datafile.pdf</filename>, <filename>Graphics.pdf</filename> +and <filename>User.pdf</filename>, but not <filename>PDF</filename>, +<filename>Datafile.PDF</filename>, or +<filename>.pdf</filename>.</para> + +<tip><para>It is very beneficial to have multiple masks. One for lower +case, one for upper case, &etc; This will help ensure that &kde; can +determine the file type more accurately.</para></tip> + +</sect3> + +<sect3 id="file-assoc-use-desc"> +<title>Editing a mime types description.</title> + +<para>You can type a short description of the &MIME; type in the text +box labeled <guilabel>Description</guilabel>. This label is to help +you, it does not affect the function of the &MIME; type.</para> + +</sect3> + +<sect3 id="file-assoc-use-app"> +<title>Editing the application associations</title> + +<para>There are four buttons (<guibutton>Move Up</guibutton>, +<guibutton>Move Down</guibutton>, <guibutton>Add</guibutton> and +<guibutton>Remove</guibutton>) and a combo box (which lists the +applications) which are used to configure the applications.</para> + +<para>The combo box lists all of the applications associated with a +specific &MIME; type. The list is in a specific order. The top +application is the first application tried. The next application down +the list is the second, etc.</para> + +<note><para>What do you mean there is more than one application per +&MIME; type? Why is this necessary?</para> + +<para>We started out by saying that &kde; comes preconfigured with +hundreds of file associations. The reality is, each system that &kde; +is installed on has a different selection of applications. By +allowing multiple associations per &MIME; type, &kde; can continue to +operate when a certain application is not installed on the +system.</para> + +<para>As an example:</para> +<para>For the &MIME; type <literal>pdf</literal>, there are two +applications associated with this file type. The first program is +called <application>PS Viewer</application>. If your system does not +have <application>PS Viewer</application> installed, then &kde; +automatically starts the second application <application>Adobe Acrobat +Reader</application>. As you can see, this will help keep &kde; running +strong as you add and subtract applications.</para></note> + +<para>We have established that the order is important. You can change +the order of the applications by clicking once with the mouse on the +application you want to move, and then clicking either <guibutton>Move +Up</guibutton> or <guibutton>Move Down</guibutton>. This will shift +the currently selected application up or down the list of +applications. </para> + +<para>You can add new applications to the list by clicking the button +labeled <guibutton>Add</guibutton>. A dialog box will appear. Using the +dialog box, you can select the application you want to use for this mime +type. Click <guibutton>OK</guibutton> when you are done, and the +application will be added to the current list.</para> + +<para>You can remove an application (thereby ensuring that the +application will never run with this &MIME; type by clicking once on the +name of the application, and clicking the <guibutton>Remove</guibutton> +button.</para> + +<tip><para>It is a good idea to use the <guibutton>Move Up</guibutton> +and <guibutton>Move Down</guibutton> buttons to adjust the unwanted +application to a lower position in the list, rather than deleting the +application from the list entirely. Once you have deleted an +application, if your preferred application should become compromised, +there will not be an application to view the data document.</para></tip> + +</sect3> + +<sect3 id="file-assoc-embedding"> +<title>Embedding</title> +<para>By clicking on the <guilabel>Embedding</guilabel> tab, you are +presented with three radio buttons in the <guilabel>Left click +action</guilabel> group. These determine how &konqueror; views the selected +&MIME; type:</para> + +<variablelist> +<varlistentry><term>Show file in embedded viewer</term> +<listitem><para>If this is selected, the file will be shown <emphasis>within</emphasis> the &konqueror; window.</para></listitem></varlistentry> +<varlistentry><term>Show file in separate viewer</term> +<listitem><para>This will cause a separate window to be created when showing this mime-type.</para></listitem></varlistentry> +<varlistentry><term>Use group settings.</term> +<listitem><para>This will cause the mime-type to use the settings for the mime-type group. +(if you are editing an audio mime type, then the settings for the audio group are used).</para></listitem></varlistentry> +</variablelist> + +<para>Below this is a listbox labeled <guilabel>Services Preference +Order</guilabel>.</para> + +<para>When you are in &konqueror;, you can +<mousebutton>right</mousebutton> mouse click, and a menu will with an +entry labeled <guimenu>Preview with...</guimenu> will appear. This box +lists the applications that will appear, in the order they will +appear, under this menu.</para> + +<para>You can use the <guibutton>Move Up</guibutton> and +<guibutton>Move Down</guibutton> buttons to change the order.</para> + +</sect3> + +<sect3 id="file-assoc-use-done"> +<title>Making changes permanent</title> + +<para>When you are done making any changes to mime types, you can click +<guibutton>Apply</guibutton> to make your changes permanent, but keep +you in this module.</para> + +</sect3> +</sect2> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/fonts/Makefile.am b/doc/kcontrol/fonts/Makefile.am new file mode 100644 index 000000000..b79d06618 --- /dev/null +++ b/doc/kcontrol/fonts/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/fonts diff --git a/doc/kcontrol/fonts/index.docbook b/doc/kcontrol/fonts/index.docbook new file mode 100644 index 000000000..cfe34bab7 --- /dev/null +++ b/doc/kcontrol/fonts/index.docbook @@ -0,0 +1,121 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-09-22</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>fonts</keyword> +</keywordset> +</articleinfo> + +<sect1 id="fonts"> + +<title>Fonts</title> + +<para>This module is designed to allow you to easily select different +fonts for different parts of the &kde; Desktop.</para> + +<para>The panel consists of different font groups to give you a lot of +flexibility in configuring your fonts: </para> + +<itemizedlist> +<listitem><para><guilabel>General:</guilabel> Used everywhere the other font +groups don't apply</para></listitem> + +<listitem><para><guilabel>Fixed width:</guilabel> Anywhere a +non-proportional font is specified</para></listitem> + +<!-- <listitem><para><guilabel>File Manager</guilabel> (Font to use in the +&kde; file manager)</para></listitem> --> + +<listitem><para><guilabel>Toolbar:</guilabel> Font used in &kde; application +toolbars</para></listitem> + +<listitem><para><guilabel>Menu:</guilabel> Font used in &kde; application +menus</para></listitem> + +<listitem><para><guilabel>Window title:</guilabel> Font used in the window +title</para></listitem> + +<listitem><para><guilabel>Taskbar:</guilabel> Font used in the taskbar +panel applet</para></listitem> + +<listitem><para><guilabel>Desktop:</guilabel> Font used on the desktop +to label icons</para></listitem> + +</itemizedlist> + +<para>Each font has a corresponding <guibutton>Choose...</guibutton> +button. By clicking on this button, a dialog box appears. You can +use this dialog box to choose a new font, font style, size and +character set. Then press <guibutton>OK</guibutton>.</para> + +<para>An example of the font you have chosen will be displayed in the space +between the font group name and the <guibutton>Choose...</guibutton> +button.</para> + +<para>When you are done, simply click <guibutton>OK</guibutton>, and +all necessary components of &kde; will be restarted so your changes +can take affect immediately.</para> + +<para>The <guibutton>Adjust All Fonts...</guibutton> button allows you to +quickly set properties for all the fonts selected +above. A font selection dialog similar to the standard one will +appear, but you will notice checkboxes that allow you to change the +<guilabel>Font</guilabel>, <guilabel>Font style</guilabel> or +<guilabel>Size</guilabel> independently of each other. You can +choose any one, two, or three of these options, and they will be +applied to all the font groups.</para> + +<para>For example, if you have selected several different font faces +above, and realize they are all a size too big (this often happens +when you change screen resolution, for instance), you can apply a new +font size to all the fonts, without affecting your customized font +faces and styles.</para> + +<sect2 id="fonts-aa"> +<title>Anti-alias text</title> + +<para>To use anti-aliasing, simply place a mark in the checkbox labeled +<guilabel>Use anti-aliasing for fonts</guilabel>.</para> + +<para>Placing a mark in the checkbox will allow you to specify which range of +fonts will <emphasis>not</emphasis> be anti-aliased. This range is specified +with the two combo boxes on the same line.</para> + +<para>You can also choose the method that &kde; uses to create an anti-alias +look to your fonts, and how strongly it should be applied. If you are not +familiar with the individual methods, you should leave this option +alone.</para> + +<!-- FIXME: Cop-out, I need to write a 'hinting and AA for beginners' +paragraph in here --> + +<note><para> +The ability to use anti-aliased fonts and icons requires that you have +support in both X and the &Qt; toolkit, that you have suitable fonts +installed, and that you are using the built-in font serving capabilities +of the X server. If you still are having problems, please contact the +appropriate &kde; mailing list, or check the +<acronym>FAQ</acronym>.</para></note> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/helpindex/Makefile.am b/doc/kcontrol/helpindex/Makefile.am new file mode 100644 index 000000000..0529b36f5 --- /dev/null +++ b/doc/kcontrol/helpindex/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/helpindex.html diff --git a/doc/kcontrol/helpindex/index.docbook b/doc/kcontrol/helpindex/index.docbook new file mode 100644 index 000000000..ba7acdc80 --- /dev/null +++ b/doc/kcontrol/helpindex/index.docbook @@ -0,0 +1,144 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-10-17</date> +<releaseinfo>3.1</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>Help Index</keyword> +<keyword>Index</keyword> +</keywordset> +</articleinfo> + +<sect1 id="help-index"> + +<title>Help Index</title> + +<note><para>At the time of writing, for most installations of &kde; the entire search engine function in &khelpcenter; is disabled, and settings made in this &kcontrol; module will have no effect. We hope to have it back in a future release.</para></note> + +<para>&kde; comes with a lot of documentation for applications and +components. While it is possible to just browse the manuals until you +find that piece of information you're looking for, this may be a very +time-consuming task. To make this easier for you, &kde; offers +fulltext search using a program called +<application>ht://dig</application>. It works quite similar to search +engines on the web, in fact some search engines you know might even use +it. Just click on the <guilabel>Search</guilabel> tab in the +&khelpcenter;, enter the word you are looking for, click +<guibutton>Search</guibutton> and enjoy!</para> + +<para>However, to make use of this feature, +<application>ht://dig</application> has to be installed on your system +and &kde; has to be configured to make use of it. This control module +tries to help you doing the latter. If you haven't installed +<application>ht://dig</application> and it wasn't shipped with your +operating system you have to get ht://dig yourself. Have a look at +<ulink url="http://www.htdig.org">the ht://dig homepage</ulink> on how +to download and install it.</para> + +<para>When you first start, you are in display mode only. To modify +your settings, click on <guibutton>Administrator Mode</guibutton>. If +you are logged in as <systemitem class="username">root</systemitem>, +you will go straight to the change dialog. If not, &kde; will ask for +a superuser password.</para> +<sect2 id="help-index-use"> + +<title>Use</title> + +<para>There are two important things to tell &kde; so it can make use of the +fulltext search engine:</para> + +<itemizedlist> +<listitem><para>where to find the <application>ht://dig</application> programs +KDE uses for fulltext search</para></listitem> +<listitem><para>where to search</para></listitem> +</itemizedlist> + +<sect3 id="help-index-use-progs"> + +<title>The <application>ht://dig</application> Programs</title> + +<para> There are three programs &kde; needs that come with +<application>ht://dig</application>: <command>htdig</command>, +<command>htsearch</command> and <command>htmerge</command>. For each program you +have to provide the full path including the program name, for example: <filename +class="directory">/usr/bin/htdig</filename>.</para> + +<para>Where exactly these programs are installed depends on your operating +system or your distribution. However, there are some good guesses you might want +to try:</para> + +<itemizedlist> + +<listitem><para><command>htdig</command> and <command>htmerge</command> are +often found in <filename class="directory">/usr/bin/</filename> or in something +like <filename +class="directory">/usr/local/www/htdig/bin/</filename>.</para></listitem> + +<listitem><para>the <command>htsearch</command> command is often found in a sub +folder called <filename class="directory">cgi-bin</filename>, for example +<filename class="directory">/usr/local/httpd/cgi-bin/</filename>.</para> + +</listitem> +</itemizedlist> + +<tip><para>To find out where for example <command>htdig</command> is installed +you can always type <command>whereis htdig</command> on the +console. <command>whereis</command> will look for the specified command in the +standard execution path folders. However, folders like <filename +class="directory">cgi-bin</filename> are often not in the standard execution +path.</para></tip> + +</sect3> + +<sect3 id="help-index-use-scope"> +<title>Scope and Search Paths</title> + +<para>In this section you can choose which help resources should be indexed, +&ie; made available to the search engine.</para> + +<para>In the <guilabel>Scope</guilabel> frame you can select some +typical resources you want to be indexed, &ie; the &kde; help files, +and the information offered by the <command>man</command> and +<command>info</command> commands. Note that some of those may still be +disabled, which means that support for them has not been added +yet.</para> + +<para>Maybe you have additional files you want to access using the +&khelpcenter; fulltext search feature. For example, you might have an +<acronym>HTML</acronym> reference installed in +<filename>/home/jdoe/docs/selfhtml</filename>. By adding this path to +the list of additional search paths you make this documentation +available to &khelpcenter;'s fulltext search, too. Just click on the +<guibutton>Add</guibutton> button and a file dialog will ask you for +an additional search folder. Select +<filename class="directory">/home/jdoe/docs/selfhtml</filename> and click +<guibutton>OK</guibutton>. To remove an additional search path, just +select it and click <guibutton>Delete</guibutton>.</para> + +<important><para>Your changes to the scope and additional search paths +will not take effect if you don't click on the <guibutton>Generate +index</guibutton> button.</para></important> +</sect3> + +</sect2> + +</sect1> +</article> + diff --git a/doc/kcontrol/icons/Makefile.am b/doc/kcontrol/icons/Makefile.am new file mode 100644 index 000000000..9de711f69 --- /dev/null +++ b/doc/kcontrol/icons/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/icons diff --git a/doc/kcontrol/icons/index.docbook b/doc/kcontrol/icons/index.docbook new file mode 100644 index 000000000..199a35275 --- /dev/null +++ b/doc/kcontrol/icons/index.docbook @@ -0,0 +1,233 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-09-22</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>icon</keyword> +</keywordset> +</articleinfo> +<sect1 id="icons"> +<title>Icons</title> + +<sect2 id="icons-intro"> +<title>Introduction</title> + +<para>&kde; comes with a full set of icons in several sizes. These icons +are being used all over &kde;: the desktop, the panel, the &konqueror; file +manager, in every toolbar of every &kde; application, etc. The icons +control module offers you very flexible ways of customizing the way &kde; +handles icons. You can:</para> + +<itemizedlist> +<listitem><para>install and choose icon themes</para></listitem> +<listitem><para>choose different icon sizes</para></listitem> +<listitem><para>assign effects to icons (for example make them +semi-transparent or colorize them) </para></listitem> +<listitem><para>configure these settings for each of the different places +icons will be used in: for example the desktop, toolbars &etc; +</para></listitem> +</itemizedlist> + +<important><para>Please note that some of these settings may depend on +your selected icon theme. &kde; comes with two icon themes by default, +&kde;-Classic (HiColor) and Crystal SVG. There is also a low color theme +in the kdeartwork package, along with others.</para></important> + +</sect2> + +<sect2 id="icon-theme"> +<title><guilabel>Theme</guilabel></title> + +<para>Starting at the top, you can see some example icons. These change +in appearance depending on the icon theme you select. Most default +installations will have only one icon theme available, the &kde; default +Crystal SVG theme. There are others contained separately in the +kdeartwork package, and you can download more from the Internet.</para> + +<para>Use the <guibutton>Install New Theme...</guibutton> to browse to the +location of newly downloaded themes, and they will then become available +to select from above.</para> + +</sect2> + +<sect2 id="icons-use"> +<title>Advanced</title> + +<para>Looking at this second page of the icons control module, you +will see two areas:</para> + +<itemizedlist> +<listitem> +<para>An area labelled <guilabel>Use of Icon</guilabel>. Here you can +choose which particular usage of icons you want to configure, for +example <guilabel>Toolbar</guilabel> or <guilabel>Panel</guilabel>.</para> +</listitem> + +<listitem> <para>A preview area where you can see how +icons of the selected kind will look using the current +settings. Note that the state of this preview also depends on the icon +state selected in the effects below (do not worry +about that now, we will explain that below). </para> </listitem> +</itemizedlist> + +<para>When you want to configure icons, first select the usage of icons +you want to configure. Change the settings until you like the +preview. You can then choose a different icon usage and configure +that. At the end, if you are satisfied with your settings, click +<guibutton>OK</guibutton> or <guibutton>Apply</guibutton> to take the +changes in effect.</para> + +<para>There are two further options to consider, +<guilabel>Size</guilabel> and <guilabel>Effects</guilabel>. </para> + +<sect3 id="icons-use-size"> +<title>Icon Size</title> + +<para>You have two options relating to icon sizes. First, you can choose +from a list of icon sizes. Second, you can tell &kde; to draw all icons +using double sized pixels. The largest icon sizes are especially useful +for visually impaired people.</para> + +<para>Which sizes will be offered by the icon size listbox depends on +the icon theme you have selected in the icon themes control module. For +example, the low color icon theme only offers the sizes 16 and 32 for +desktop icons and 16, 22 and 32 for toolbar icons. The HiColor theme +offers icon sizes 16, 32 and 48 as well as sizes from 64 to 128. +However, as &kde; can not have all these icon sizes in store, icons +using size 64 to 128 will be automatically generated which may result in +a loss of quality.</para> + +<para>If the icon sizes offered by your chosen icon theme are not enough +for you, there is still the option <guilabel>Double-sized +pixels</guilabel>. If this option is selected, all icons will have +double sized pixels, &ie; a 2x2 block instead of normal pixels. While +this makes it possible to achieve very large icon sizes, the quality is +poor: icons will look <quote>blocky</quote>, an effect you may remember +if you've grown up using a Sinclair ZX Spectrum or similar. If this is +an option for you, using the large sizes offered by &kde;'s HiColor +icon theme will always result in a much better quality than using the +low color icon theme with double sized pixels.</para> +<!-- +<para>You can also choose to have smoothed icons, an effect similar to +anti-aliasing of fonts. Enable the checkbox <guilabel>Blend alpha +channel</guilabel> to see this in action, but note that it will slow +down graphics on a slower computer.</para> +--> + +<para>You can also choose animated icons. Many of the icons have +animations associated with them. Enable the checkbox labelled +<guilabel>Animate Icons</guilabel>, to enable this effect, but note +that it may appear slow or jerky if your graphics card is old or you +are low on memory.</para> + +</sect3> + +<sect3 id="icons-use-effects"> +<title>Effects</title> + +<para>Finally you can configure certain <quote>filters</quote> to be +applied on icons which are in one of three states:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Default</guilabel></term> +<listitem><para>This is how the icon will look normally.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Active</guilabel>:</term> +<listitem><para>This is how the icon will look when the mouse cursor is over the icon.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Disabled</guilabel>:</term> +<listitem><para>This is how the icon will look if its corresponding action is +disabled, &ie; clicking on it will not lead to any +result.</para></listitem> +</varlistentry> +</variablelist> + +<para>Select one of these states, and press the <guibutton>Set +Effect...</guibutton> button to configure a corresponding icon effect. +Please note that this configuration will only affect icons of the +currently selected <guilabel>Use of Icon</guilabel> category (see +above): configuring an effect for active icons, while +<guilabel>Toolbar</guilabel> icon usage is selected, will +<emphasis>not</emphasis> affect active icons used in other +places.</para> + +<para>Below the list of icon states there are two options: you can +configure an effect and you can select the +<guilabel>Semi-transparent</guilabel> option, which will make the +background <quote>shine through</quote> the icon. To the right of the +effects list box there is a slider button to pass additional parameters to +a filter for colours and <guilabel>Amount</guilabel>.</para> +<!-- TODO: Figure out what 'amount' really means --> + +<para>The following effects can be applied to icons:</para> + +<variablelist> +<varlistentry> +<term><guilabel>No Effect</guilabel>:</term> +<listitem><para>Icons will be used without applying any +effect.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>To Gray</guilabel>:</term> +<listitem><para>This filter will apply a grayish look to the icon. Click +<guibutton>Setup...</guibutton> to configure the intensity of this filter. Note +that it is customary for most user interfaces to use this effect for disabled +icons only.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Colorize</guilabel>:</term> +<listitem><para>Icons will be colorized using a custom color. For example, you +may configure active icons (&ie; the icon the mouse cursor is over) to +shine golden. Use the color and <guilabel>Amount</guilabel> buttons to configure the used color and the intensity of the colorization.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Gamma</guilabel>:</term> +<listitem><para>A different gamma value will be applied to all icons. If you're +no photographer and don't know what Gamma is: it's quite similar to what people +call contrast. Just play around with the gamma settings by clicking on +<guibutton>Setup...</guibutton> to get a feeling for this +effect.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Desaturate</guilabel>:</term> +<listitem><para>Icons will be drawn desaturated. This is quite similar to the +<quote>Color</quote> setting on your television. Click +<guibutton>Setup...</guibutton> to configure the amount of desaturation. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>To Monochrome:</guilabel></term> +<listitem> +<para>Icons will be drawn using only the two colours selected.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/index.docbook b/doc/kcontrol/index.docbook new file mode 100644 index 000000000..cdaa3390f --- /dev/null +++ b/doc/kcontrol/index.docbook @@ -0,0 +1,637 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &kcontrolcenter;</title> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-03-05</date> +<releaseinfo>3.4.0</releaseinfo> + +<abstract> +<para>This documentation describes &kde;'s control center.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kcontrol</keyword> +<keyword>configuration</keyword> +<keyword>settings</keyword> +<keyword>module</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>The &kcontrolcenter;</title> + +<para> +The &kcontrolcenter; (from now on referred to simply as <quote>the +control center</quote>) provides you with a centralized and convenient +way to configure all of your &kde; settings. +</para> + +<para> +The control center is made up of multiple modules. Each module is a +separate application, but the control center organizes all of these +programs into a convenient location. +</para> + +<tip> +<para> +Each control center module can be executed individually +</para> + +<para> +See section entitled <link linkend="control-center-run-indiv">Running +individual control center modules</link> for more information. +</para> +</tip> + +<para> +The control center groups the configuration modules into categories, so +they are easy to locate. Within each category, the control center shows +all the modules in a list, so it is easier to find the right +configuration module. +</para> +</chapter> + +<chapter id="control-center"> +<title>Using the &kcontrolcenter;</title> + +<para> +This next section details the use of the control center itself. For +information on individual modules, please see <link linkend="module">Control +Center Modules</link> +</para> + +<sect1 id="control-center-starting"> +<title>Starting the &kcontrol;</title> + +<para>The &kcontrolcenter; can be started in 3 ways: +</para> + +<orderedlist> +<listitem> +<para> +By selecting <menuchoice><guimenu>K Button</guimenu><guimenuitem>Control +Center</guimenuitem></menuchoice> from the &kde; Panel. +</para> +</listitem> +<listitem> +<para> +By pressing <keycombo +action="simul">&Alt;<keycap>F2</keycap></keycombo>. +</para> + +<para> +This will bring up a dialog box. Type +<userinput><command>kcontrol</command></userinput>, and click +<guibutton>Run</guibutton>. +</para> +</listitem> + +<listitem> +<para> +You can type <command>kcontrol &</command> at any command prompt. +</para> +</listitem> +</orderedlist> + +<para> +All three of these methods are equivalent, and produce the same result. +</para> + +</sect1> + +<sect1 id="control-center-screen"> +<title>The &kcontrolcenter; Screen</title> + +<para> +When you start the control center, you are presented with a window, +which can be divided into 3 functional parts. +</para> + +<screenshot> +<screeninfo>Screenshot</screeninfo> +<mediaobject> +<imageobject> <imagedata fileref="screenshot.png" format="PNG"/> +</imageobject> +<textobject> <phrase>Screenshot</phrase> </textobject> +<caption> +<para>The &kde; Control Center Screen</para> +</caption> +</mediaobject> +</screenshot> + +<para> +Across the top is a menubar. The menubar will provide you with quick +access to most of &kcontrolcenter;'s features. The menus are detailed in +<link linkend="control-center-menus">The &kde; Control Center +Menus</link>. +</para> + +<para> +Along the left hand side, is a icon tree. Here you can choose which +module to configure. +</para> + +<para> +The main panel shows you some system information. +</para> + +<para> +In this example, we are running &kde; 3.4.0, we started &kcontrolcenter; +as user <systemitem class="username">newkde</systemitem>, the computer is +named <systemitem class="systemname">turtle</systemitem>, it is a +&Linux; system running the 2.6 kernel, on a i686 processor. +</para> + +</sect1> + +<sect1 id="control-center-menus"> +<title>The &kcontrolcenter; Menus</title> + +<para> +This next section gives you a brief description of what each menu item +does. +</para> + +<sect2 id="control-center-menu-file"> +<title><guimenu>File</guimenu> Menu</title> + +<para> +The <guimenu>File</guimenu> menu has a single entry. +</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem> +<para> +<action>Closes the control center.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="control-center-menu-view"> +<title><guimenu>View</guimenu> Menu</title> + +<para> +These options determine how the module selection looks and behaves. +</para> + +<variablelist> +<varlistentry> +<term><menuchoice><guimenu>View</guimenu> <guimenuitem>Mode</guimenuitem> +</menuchoice></term> + +<listitem> +<para> +Determines whether to use <guimenuitem>Tree</guimenuitem> view, +or <guimenuitem>Icon</guimenuitem> view for your modules. +</para> + +<para> +With <guimenuitem>Tree</guimenuitem> view, each submenu appears as an +indented list. +</para> + +<para> +With <guimenuitem>Icon</guimenuitem> view, when you click on a category, +the categories disappear and are replaced with the module list. You +then use the <guiicon>Back</guiicon> button to return to the categories. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu><guisubmenu>Icon size</guisubmenu> +</menuchoice></term> + +<listitem> +<para> +Using this option, you can choose +<guimenuitem>Small</guimenuitem>, <guimenuitem>Medium</guimenuitem>, or +<guimenuitem>Large</guimenuitem> icons to select your modules. +</para> + +<note><para> +This menu item only controls the icon size if you are in +<guimenuitem>Icon View</guimenuitem>. If you choose +<guimenuitem>Tree View</guimenuitem>, the <guimenuitem>Small</guimenuitem> +icon size will be used, no matter what size was previously selected in +<guimenuitem>Icon View</guimenuitem>. +</para> +</note> +</listitem> + +</varlistentry> +</variablelist> +</sect2> + +<sect2 id="control-center-menu-settings"> +<title><guimenu>Settings</guimenu> Menu</title> + +<para> + The <guimenu>Settings</guimenu> menu has a single entry, +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice>. From here you can map keyboard shortcuts to the +other menu options. +</para> + +</sect2> + +<sect2 id="control-center-menu-help"> +<title><guimenu>Help</guimenu> Menu</title> + +&help.menu.documentation; + +</sect2> + +</sect1> + +<sect1 id="control-center-exiting"> +<title>Exiting The &kde; Control Center</title> + +<para> +You can exit the control center one of three ways: +</para> + +<itemizedlist> +<listitem> +<para> +Select <menuchoice><guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem></menuchoice> from the menu bar. +</para> +</listitem> + +<listitem> +<para>Type <keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +on the keyboard. +</para> +</listitem> + +<listitem> +<para> +Click on the <guiicon>Close</guiicon> button on the frame surrounding +the control center. +</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="control-center-run-indiv"> +<title>Running Individual Modules</title> + +<para> +You can run individual modules without running kcontrol using the command <command>kcmshell</command> from &konsole;. Type <userinput> <command>kcmshell</command><option> --list</option></userinput> to see a list of the available &kcontrolcenter; modules. You can also access individual &kcontrolcenter; modules through adding the <guilabel>Preferences</guilabel> button to either &kicker; or the &kmenu; through their respective configuration dialogs. +</para> + +</sect1> + +</chapter> + +<!--*****************************************************************--> + +<chapter id="module"> +<title>The &kcontrolcenter; Modules</title> + +<para> +In order to make it as easy as possible, the &kcontrolcenter; has organized +similar options into groups. Each group is called a module. When you +click on the name of a module in the left window, you will be presented +with the options of the module on the right. +</para> + +<para> +Each module will have some or all of the following buttons: +</para> + +<variablelist> + +<varlistentry> +<term>Help</term> +<listitem> +<para> +This button will give you help specific to the current module. The +button will show you a short summary help page in the left window. At +the bottom of that window, you can click on a link to get more detailed +help. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Defaults</guilabel></term> +<listitem> +<para> +This button will restore this module to its default values. You must +click <guibutton>OK</guibutton> to save the options. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Apply</guibutton></term> +<listitem> +<para> +Clicking this button will save all changes to &kde;. If you have +changed anything, clicking <guibutton>Apply</guibutton> will cause the +changes to take effect. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Reset</guibutton></term> +<listitem> +<para> +This button will <quote>Reset</quote> the module to the previous settings. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<note> +<para> +You must save the options of the current module using +<guibutton>Apply</guibutton> before you can change to a different +module. +</para> +<para> +If you try to change without saving your options, you will be asked if +you want to save your changes, or discard them. +</para> +</note> +</chapter> +<!-- + Commented until fixed arrangement is made +<sect1 id="module-intro"> +<title>Navigating Modules</title> + +<para> +This is a list of the <emphasis>standard</emphasis> configuration +modules (sorted by category) provided by the <application +role="package">KDE base</application> package. Please note that there +may be many more modules on your system if you have installed additional +software. +</para> + +<variablelist> +<varlistentry> +<term>File Browsing</term> +<listitem> +<para> +<link linkend="file-assoc">File Associations</link>, +<link linkend="file-manager">File Manager</link>, +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Look and Feel</term> +<listitem> +<para> +<link linkend="background">Background</link>, +<!- - <link linkend="borders">Borders</link>,- -> +<link linkend="color">Colors</link>, +<link linkend="desktop">Desktop</link>, +<link linkend="fonts">Fonts</link>, +<link linkend="icons">Icons</link>, +<!- - <link linkend="iconstyle">Icon Style</link>, - -> +<link linkend="key-bindings">Key Bindings</link>, +<link linkend="launch-feedback">Launch feedback</link>, +<link linkend="panel">Panel</link>, +<link linkend="screensaver">Screensaver</link>, +<link linkend="style">Style</link>, +<link linkend="sys-notify">System Notifications</link>, +<link linkend="taskbar">Taskbar</link>, +<link linkend="theme-manager">Theme Manager</link>, +<!- - <link linkend="numbername">Virtual Desktops</link>,- -> +<link linkend="window-behavior">Window Behavior</link>, +<link linkend="window-deco">Window Decoration</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Network</term> +<listitem> +<para> +<link linkend="e-mail">E-Mail</link>, +<link linkend="lan-browsing">LAN Browsing</link>, +<link linkend="timeouts">Preferences</link>, <!- - FIXME - -> +<link linkend="socks">SOCKS</link>, +<link linkend="talk">Talk Configuration</link> +<link linkend="windows-shares">Windows Shares</link> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Peripherals</term> +<listitem> +<para> +<link linkend="kbd">Keyboard</link>, +<link linkend="mouse">Mouse</link> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Personalization</term> +<listitem> +<para> +<link linkend="accessibility">Accessibility</link>, +<link linkend="locale">Country & Language</link>, +<link linkend="crypto">Crypto</link>, +<!- - <link linkend="kblayout">Keyboard Layout</link>, - -> +<link linkend="passwords">Passwords</link> +<link linkend="spell-checking">Spell Checking</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Power Control</term> +<listitem> +<para> +<link linkend="battery-monitor">Battery Monitor</link>, +<link linkend="energy">Energy</link>, +<link linkend="powerctrl">Laptop Power Control</link>, +<link linkend="lowbatcrit">Low Battery Critical</link>, +<link linkend="lowbatwarn">Low Battery Warning</link> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Sound</term> +<listitem> +<para> +<link linkend="midi">Midi</link>, +<link linkend="mixer">Mixer</link>, +<link linkend="sndserver">Sound Server</link>, +<link linkend="bell">System Bell</link> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>System</term> +<listitem> +<para> +<link linkend="datetime">Date and Time</link>, +<link linkend="konsole">&konsole;</link>, +<link linkend="login-manager">Login Manager</link>, +<link linkend="print-manager">Printing Manager</link>, +<link linkend="sessions">Session Manager</link>, +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Web Browsing</term> +<listitem> +<para> +<link linkend="cookie">Cookies</link>, +<link linkend="ebrowse">Enhanced Browsing</link>, +<link linkend="konq-browsing">Konqueror Browser</link>, +<link linkend="nsplugins">Netscape Plugins</link>, +<link linkend="proxies">Proxies & Cache</link>, +<link linkend="stylesheets">Stylesheets</link>, +<link linkend="user-agent">User Agent</link>, +</para> +</listitem> +</varlistentry> + +</variablelist> +</sect1> +</chapter> +--> + +<!-- commenting this section out until I figure out what to do with it :) +<chapter id="laptop"> +<title>Laptop Modules Notes</title> + +<para> +In order to use the laptop modules, you must have the kernel +<acronym>APM</acronym> package installed in your kernel. Useful information + +on +how to do this can be found at +<ulink url="http://www.cs.utexas.edu/users/kharker/linux-laptop/apm.html"> +http://www.cs.utexas.edu/users/kharker/linux-laptop/apm.html</ulink> and +in the Battery Powered Linux mini-HOWTO at <ulink +url="http://metalab.unc.edu/LDP/HOWTO/mini/Battery-Powered.html"> +http://metalab.unc.edu/LDP/HOWTO/mini/Battery-Powered.html</ulink>. +</para> + +<para> +If you want the <guimenuitem>suspend</guimenuitem> and +<guimenuitem>standby</guimenuitem> menu commands to work then you should +install the &Linux; <application>apmd</application> package (version 2.4 +or later). If you want to use them from non-root accounts you must mark +the <application>apm</application> command <quote>set uid root</quote>. +</para> + +<para> +To do this, log on as <systemitem class="username">root</systemitem> and +enter: +</para> + +<screen> +<prompt>%</prompt><userinput><command>chown</command> <option>root +/usr/bin/apm</option>;<command>chmod</command> <option>+s +/usr/bin/apm</option></userinput> +</screen> + +<warning> +<para> +By doing this you will allow any user of your system to put it into suspend +or +standby states - if you are the only user, this should not be a problem. +</para> + +<para> +Also note that any program which has <systemitem +class="username">root</systemitem> access, can be a potential security +problem. You should carefully determine if there are any security +concerns <emphasis>before</emphasis> giving any program <systemitem +class="username">root</systemitem> permissions. +</para> +</warning> +</chapter> +--> + +<chapter id="credits"> +<title>Credits and License</title> + +<para>&kcontrol;</para> +<para>Program copyright 1997-2001 The &kcontrolcenter; Developers</para> +<para>Contributors:</para> + +<itemizedlist> +<listitem><para>&Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail;</para></listitem> +<listitem><para>&Matthias.Elter; &Matthias.Elter.mail;</para></listitem> +</itemizedlist> + +<para>Documentation <trademark class="copyright">copyright 2000 &Mike.McBride;</trademark> &Mike.McBride.mail;</para> + +<para>Contributors:</para> + +<itemizedlist> +<listitem><para>&Paul.Campbell; &Paul.Campbell.mail;</para></listitem> +<listitem><para>&Helge.Deller; &Helge.Deller.mail;</para></listitem> +<listitem><para>&Mark.Donohoe; </para></listitem> +<listitem><para>&Patrick.Dowler; </para></listitem> +<listitem><para>&Duncan.Haldane; <email>[email protected]</email></para></listitem> +<listitem><para>&Steffen.Hansen; <email>[email protected]</email>.</para></listitem> +<listitem><para>&Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail;</para></listitem> +<listitem><para>&Martin.R.Jones; &Martin.R.Jones.mail;</para></listitem> +<listitem><para>&Jost.Schenck; &Jost.Schenck.mail;</para></listitem> +<listitem><para>&Jonathan.Singer; &Jonathan.Singer.mail;</para></listitem> +<listitem><para>&Thomas.Tanghus; &Thomas.Tanghus.mail;</para></listitem> +<listitem><para>&Krishna.Tateneni; &Krishna.Tateneni.mail;</para></listitem> +<listitem><para>Ellis Whitehead <email>[email protected]</email></para></listitem> +</itemizedlist> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; +</chapter> + +</book> + +<!-- +Local Variables: +mode: sgml +End: +--> + diff --git a/doc/kcontrol/kcmaccess/Makefile.am b/doc/kcontrol/kcmaccess/Makefile.am new file mode 100644 index 000000000..c0d281754 --- /dev/null +++ b/doc/kcontrol/kcmaccess/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = kcontrol/kcmaccess + diff --git a/doc/kcontrol/kcmaccess/index.docbook b/doc/kcontrol/kcmaccess/index.docbook new file mode 100644 index 000000000..25ccf55c2 --- /dev/null +++ b/doc/kcontrol/kcmaccess/index.docbook @@ -0,0 +1,179 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-12-21</date> +<releaseinfo>3.01.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>accessibility</keyword> +</keywordset> +</articleinfo> + +<sect1 id="accessibility"> +<title>Accessibility</title> +<sect2 id="accessibility-intro"> + +<title>Introduction</title> + +<para>This module is designed to help users who have difficulty hearing +audible cues, or who have difficulty using a keyboard. </para> + +<para> +The module is divided into two tabs: <link +linkend="access-bell"><guilabel>Bell</guilabel></link> and <link +linkend="access-kb"><guilabel>Keyboard</guilabel></link>. +</para> + +<sect3 id="access-bell"> +<title><guilabel>Bell</guilabel></title> + +<para> +This panel is divided into an <guilabel>Audible Bell</guilabel> section +and a <guilabel>Visible Bell</guilabel> section. +</para> + +<para> +The top check box labeled <guilabel>Use System Bell</guilabel>, determines +whether the normal System bell rings. If this option is disabled, the +System bell will be silenced. +</para> + +<para> +The next check box down can be used to play a different sound whenever +the system bell is triggered. To activate, place a mark in the check +box labeled <guilabel>Use customized bell</guilabel>, and enter the +complete pathname to the sound file in the text box labeled +<guilabel>Sound to Play</guilabel>. If you want, you can select the +<guibutton>Browse</guibutton> button to navigate through your filesystem +to find the exact file. +</para> + +<para> +For those users who have difficulty hearing the System bell, or those +users who have a silent computer, &kde; offers the <emphasis>visible bell</emphasis>. This +provides a visual signal (inverting the screen or flashing a color +across it) when the system bell would normally sound. +</para> + +<para> +To use the visible bell, first place a mark in the check box labeled +<guilabel>Use visible bell</guilabel>. +</para> + +<para> +You can then select between <guilabel>Invert screen</guilabel>, or +<guilabel>Flash screen</guilabel>. If you select <guilabel>Invert +screen</guilabel>, all colors on the screen will be reversed. If you +choose <guilabel>Flash screen</guilabel>, you can choose the color by +clicking the button to the right of the <guilabel>Flash +screen</guilabel> selection. +</para> + +<para> +The slider bar can be used to adjust the duration of the visible +bell. The default value is 500ms, or half a second. +</para> + +</sect3> + +<sect3 id="access-kb"> +<title><guilabel>Keyboard</guilabel></title> + +<para>There are three sections to this panel.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Use Sticky Keys</guilabel></term> +<listitem> +<para> +If this option is enabled, you can press and release the &Shift;, +&Alt; or &Ctrl; keys, and then press another key to get a key combo +(example: <keycombo action="simul">&Ctrl; &Alt; +<keycap>Del</keycap></keycombo> could be done with &Ctrl; then &Alt; +then <keycap>Del</keycap>). +</para> + +<para> +Also in this section is a check box labeled <guilabel>Lock Sticky +Keys</guilabel>. If this check box is enabled, the &Alt;, &Ctrl; +and &Shift; keys stay <quote>selected</quote> until you +<quote>de-selected</quote> them. +</para> + +<para> +As an example: +</para> +<variablelist> +<varlistentry> +<term>With <guilabel>Lock Sticky Keys</guilabel> disabled:</term> +<listitem> +<para>If you press the &Shift; key then press the +<keycap>F</keycap> key, the computer interprets this as <keycombo +action="simul">&Shift;<keycap>F</keycap></keycombo>. Now if you +type a <keycap>P</keycap>, the computer interprets this as the letter p +(no shift). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>With <guilabel>Lock Sticky Keys</guilabel> enabled:</term> +<listitem> +<para> +If you press the &Shift; key <emphasis>twice</emphasis> then press the <keycap>F</keycap> key, +the computer interprets this as <keycombo +action="simul">&Shift;<keycap>F</keycap></keycombo>. Now if you +type a <keycap>p</keycap>, the computer interprets this as the letter P +(<keycombo action="simul">&Shift;<keycap>P</keycap></keycombo>). To +de-select the &Shift; key, press it again. +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Slow keys</guilabel></term> +<listitem> +<para> +If this option is enabled, you must hold the key down for a +specified length of time (adjustable with the slider) before the +keystroke will be accepted. This helps prevent accidental key strokes. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bounce keys</guilabel></term> +<listitem> +<para> +If this option is enabled, you must wait for a specified length of time +(configurable with the slider) before the next key press can be +accepted. This prevents accidental multiple key strokes. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/kcmcss/Makefile.am b/doc/kcontrol/kcmcss/Makefile.am new file mode 100644 index 000000000..fc406ca64 --- /dev/null +++ b/doc/kcontrol/kcmcss/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG= en +KDE_DOCS = kcontrol/kcmcss diff --git a/doc/kcontrol/kcmcss/index.docbook b/doc/kcontrol/kcmcss/index.docbook new file mode 100644 index 000000000..106cc38d8 --- /dev/null +++ b/doc/kcontrol/kcmcss/index.docbook @@ -0,0 +1,257 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article> +<articleinfo> + +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-12</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>CSS</keyword> +<keyword>Stylesheets</keyword> +<keyword>Accessibility</keyword> +</keywordset> + +</articleinfo> + +<sect1 id="stylesheets"> + +<title>Stylesheets</title> + +<sect2> +<title>Introduction</title> + +<para><acronym>CSS</acronym> style sheets affect the way web pages +appear. <acronym>CSS</acronym> stands for +<emphasis>C</emphasis>ascading <emphasis>S</emphasis>tyle +<emphasis>S</emphasis>heets.</para> + +<para>&kde; can use its own stylesheet, based on simple defaults and +the color scheme you are using for your desktop. &kde; can also use a +stylesheet that you have written yourself. Finally, you can specify a +stylesheet in this module. The options presented in this module are +tuned for accessibility purposes, especially for people with reduced +vision.</para> + +<para>Your choices here affect every &kde; application that renders HTML +with &kde;'s own renderer, which is called khtml. These include +&kmail;, &khelpcenter; and of course &konqueror;. Choices here do not +affect other browsers such as &Netscape;.</para> + +<para>The module has two pages, <guilabel>General</guilabel>, where you +can choose which stylesheet to use, and <guilabel>Customize</guilabel> +where you can design an accessibility stylesheet.</para> + +</sect2> + +<sect2 id="css-general"> +<title>General</title> + +<para>This page contains the following options:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Use default stylesheet</guilabel></term> +<listitem> +<para>&kde; will use the default stylesheet. Some of the colors will +default to those defined in your chosen color scheme. Most settings are +easily overridden by the page you are viewing.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use user-defined stylesheet</guilabel></term> +<listitem> +<para>&kde; will use a stylesheet that you have written yourself. You +can use the browse button to locate the stylesheet on your system. +<acronym>CSS</acronym> files traditionally have a <literal +role="extension">.css</literal> extension, but this is not +required.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use accessibility stylesheet defined in +"Customize"-tab</guilabel></term> +<listitem> +<para>Use the settings defined in the <guilabel>Customize</guilabel> +tab. Enabling this option will enable the options on the +<guilabel>Customize</guilabel> page.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="css-customize"> +<title>Customize</title> + +<para>Here you can set up a user stylesheet. The options available are +only a subset of the instructions you can add in a stylesheet, and they +are geared towards people with reduced vision, to allow users to create +a stylesheet that makes web pages and the &kde; help files more +readable.</para> + +<para>The options on this page are disabled unless you chose +<guilabel>Use accessibility stylesheet defined in +"Customize"-tab</guilabel> on the previous page.</para> + +<sect3> +<title><guilabel>Font Family</guilabel></title> + +<variablelist> +<varlistentry> +<term><guilabel>Base family</guilabel></term> +<listitem> +<para>Choose a font family to use for body text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use same family for all text</guilabel></term> +<listitem> +<para>If you enable this, then the same font family will be used for all +text, regardless of the settings on the page you are viewing. This is +useful for pages which have used a decorative or hard to read font for +headlines.</para> +</listitem> +</varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>Font Size</title> + +<variablelist> +<varlistentry> +<term><guilabel>Base Font Size</guilabel></term> +<listitem> +<para>This is the default size for text on the page. Many web sites set +their font sizes relative to this default, using <quote>larger</quote> +or <quote>+1</quote> to make the text bigger, and <quote>smaller</quote> +or <quote>-1</quote> to make the text smaller.</para> +<para>Many people design their web pages on platforms where the ordinary +default text size is too large for the average user to read, so it is +very common to come across web pages that have forced the font smaller +in this way.</para> +<para>This setting will allow you to set the default font to a +comfortable size, so that the relative sizes are also enlarged enough to +be comfortable.</para> +<para>Do not forget you can also have &konqueror; enforce a minimum size, +so that text is <emphasis>never</emphasis> too small to read. Set that +under Behavior, in the Web Browser section in &kcontrol;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use same size for all elements</guilabel></term> +<listitem> +<para>If you enable this option, then all text will be rendered at your +specified font size, regardless of the instructions the page contains. +Relative font sizes as discussed earlier, and even specific instructions +that text should be rendered at a certain size will be overridden +here.</para> +</listitem> +</varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>Colors</title> + +<variablelist> +<varlistentry> +<term><guilabel>Black on White</guilabel></term> +<listitem> +<para>Many people with reduced vision find black text on a white screen +gives the most contrast, and is easiest to read. If this applies to +you, you can set this here.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>White on Black</guilabel></term> +<listitem> +<para>Many other people with reduced vision find the opposite to be +true, that white text on a black screen is easier to read.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Custom</guilabel></term> +<listitem> +<para>Still other people find that pure black and white, in either +order, is difficult to read. You can set custom colors here for both +the <guilabel>Background</guilabel> and the +<guilabel>Foreground</guilabel>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use same color for all text</guilabel></term> +<listitem> +<para>Many web sites use a different, often contrasting color for +headings or other flourishes. If this interferes with your ability to +read the content, you can enable this checkbox to have &kde; use the +colors you have set above for all text.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3> +<title>Images</title> + +<variablelist> +<varlistentry> +<term><guilabel>Suppress images</guilabel></term> +<listitem> +<para>If you do not want to view images, you can turn this off +here.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Suppress background images</guilabel></term> +<listitem> +<para>One major problem for reduced vision users is that background +images do not give sufficient contrast to allow them to read the text. +You can disable background images here, independently of your choice +above to view all images.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> + +<sect3> +<title>Preview</title> + +<para>The <guibutton>Preview</guibutton> allows you to see the effect of +your changes. A window will pop up, showing how several types of +headings will appear with your stylesheet, and a sentence in the default +body text.</para> + +<para>This should allow you to fine tune your stylesheet until you have +something that you can comfortably read.</para> + +<para>Happy surfing!</para> + +</sect3> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/kcmfontinst/Makefile.am b/doc/kcontrol/kcmfontinst/Makefile.am new file mode 100644 index 000000000..16be3161e --- /dev/null +++ b/doc/kcontrol/kcmfontinst/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmfontinst diff --git a/doc/kcontrol/kcmfontinst/index.docbook b/doc/kcontrol/kcmfontinst/index.docbook new file mode 100644 index 000000000..a46a8ee0f --- /dev/null +++ b/doc/kcontrol/kcmfontinst/index.docbook @@ -0,0 +1,76 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> +<authorgroup> +<author>&Craig.Drummond; &Craig.Drummond.Mail;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-22</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>fonts</keyword> +</keywordset> +</articleinfo> +<sect1 id="fontinst"> +<title>Font Installer</title> + +<para>This module is responsible for installing (and uninstalling) +fonts. The installer will configure X (X.org, XFree86), XRender, +(anti-aliasing), fontconfig, and <application>Ghostscript</application> (printing), +for any TrueType +(<literal role="extension">.ttf</literal>) and Type1 (<literal +role="extension">.pfa</literal>, <literal +role="extension">.pfb</literal>) fonts that you care to install - +bitmap (<literal role="extension">.bdf</literal>, <literal +role="extension">.pcf</literal>) fonts will also be installed, but +these can only used by X.</para> + +<para>When the module is started by a normal (non-root) user, then the +settings will refer to their personal configuration, and installed +fonts will be available to them only. For <systemitem +class="username">root</systemitem>, the settings will usually refer to +the system-wide configuration, and as such any installed fonts should +be available to all users.</para> +<para>If you install fonts as a normal user and notice the fonts used for +display (and for print preview) do not match those of the printed output +- then you should re-install the fonts system-wide (i.e. as <systemitem +class="username">root</systemitem>). This can occur because when printing +the output is sent to a printer queue - and when the system comes to actually +send the information to the printer, it is running as a different user (usually +<systemitem class="username">lp</systemitem>), and cannot find the font files.</para> +<para>To install fonts, simply select the "Add Fonts" button - this will +produce a file dialog, then just locate the fonts to install. Likewise, to +remove a font, simply highlight a font and press the "Delete" button.</para> +<sect2 id="using-konqueror"> +<title>Using Konqueror</title> +<para>You can also use Konqueror to install fonts via drag-and-drop. +To do this just type <ulink url="fonts:/">fonts:/</ulink> into Konqueror's Location bar.</para> +<para>As a normal (non-root) user, this will produce 2 top-level folders:</para> +<orderedlist> +<listitem> +<para><ulink url="fonts:/Personal">Personal</ulink> - this will display your personal fonts.</para> +</listitem> +<listitem> +<para><ulink url="fonts:/System">System</ulink> - this will display the system wide fonts. If you drag-n-drop a font +on to the folders here, you will be asked for the root password in order +to install the font.</para> +</listitem> +</orderedlist> +<para>If you drop a font over <ulink url="fonts:/">fonts:/</ulink>, then you will be asked whether this +should go into "Personal", or "System".</para> +<para>As root, just the contents of the system font folder will be displayed +- as root does not have any "personal" fonts.</para> +</sect2> +</sect1> +</article> diff --git a/doc/kcontrol/kcmkonsole/Makefile.am b/doc/kcontrol/kcmkonsole/Makefile.am new file mode 100644 index 000000000..6b3d56240 --- /dev/null +++ b/doc/kcontrol/kcmkonsole/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmkonsole diff --git a/doc/kcontrol/kcmkonsole/index.docbook b/doc/kcontrol/kcmkonsole/index.docbook new file mode 100644 index 000000000..0a4367115 --- /dev/null +++ b/doc/kcontrol/kcmkonsole/index.docbook @@ -0,0 +1,177 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + + +<authorgroup> +<author>&Jonathan.Singer; &Jonathan.Singer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>konsole</keyword> +<keyword>terminal</keyword> +</keywordset> +</articleinfo> + +<sect1 id="konsole"> +<title>&konsole;</title> + +<para>In this module, you can configure basic settings for &konsole;, +the &kde; terminal. You can also easily create new schemata (appearance +files) for &konsole;.</para> + +<para>This module contains several tab pages: +<guilabel>General</guilabel>, <guilabel>Schema</guilabel>, +<guilabel>Session</guilabel> and <guilabel>Write +Daemon</guilabel>.</para> + +<sect2> +<title><guilabel>General</guilabel></title> + +<para>This tab page allows you to configure aspects of &konsole;'s +functions. It contains the following options:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Use Konsole as default terminal +application</guilabel></term> +<listitem> +<para>If you wish to have &kde; use another terminal application by +default, uncheck this box and enter the preferred application +(<application>wterm</application>, <application>rxvt</application>, +&etc;) in the text field below.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Terminal Size when Resizing</guilabel></term> +<listitem> +<para>By default, &konsole; will show the size (in characters) of the +window when you are resizing, allowing you to make the window a +specific size. Uncheck this box to turn off this +behavior.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Frame</guilabel></term> +<listitem> +<para>Draw an inner frame around the inside of the &konsole; window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Confirm quit with open sessions</guilabel></term> +<listitem> +<para>When set, a warning appears when you try to close a &konsole; +window with multiple sessions.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Blinking Cursor</guilabel></term> +<listitem><para>If you have trouble spotting the cursor in the +&konsole; window, you can have it blink to draw your +attention.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Line Spacing</guilabel></term> +<listitem><para>Change the space between lines of text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Consider the following characters part of a word when +double clicking</guilabel></term> +<listitem><para>It is a common &UNIX; behavior to select a whole word +when you double click on it, however, the computer's idea of a word may +differ from yours. Add characters here that you would like to be +considered always to be <quote>part of a word</quote>. For example, +adding the <literal>@</literal> character will allow you to double +click to select an entire email address.</para></listitem> +</varlistentry> +</variablelist> +</sect2> + +<sect2> +<title>Schema</title> + +<para>The <guilabel>Schema</guilabel> page will allow you to easily +create, edit and save schemata, with text and background coloring, +transparency and background images.</para> + + +<!-- +<variablelist> +<varlistentry> +<term><guilabel>Font</guilabel></term> +<listitem> +<para>Use the drop-down box to select the default font size. Use the +<guibutton>Custom...</guibutton> button to select your own combination +of font, size, and style.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Full Screen</guilabel></term> +<listitem> +<para>Check the box to make &konsole; windows full-screen by +default.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bars</guilabel></term> +<listitem> + +<variablelist> +<varlistentry> +<term><guilabel>Show menubar</guilabel></term> +<listitem> +<para>Check to show the menubar by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show toolbar</guilabel></term> +<listitem> +<para>Check to show the toolbar by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show frame</guilabel></term> +<listitem> +<para>Check to show the frame by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Scrollbar position</guilabel></term> +<listitem> +<para>Select the default position of the scrollbar: +<guilabel>Hide</guilabel> (no scrollbar), <guilabel>Left</guilabel>, or +<guilabel>Right</guilabel>.</para> +</listitem> +</varlistentry> +</variablelist> +--> +</sect2> + +</sect1> +</article>
\ No newline at end of file diff --git a/doc/kcontrol/kcmlaunch/Makefile.am b/doc/kcontrol/kcmlaunch/Makefile.am new file mode 100644 index 000000000..f6c3bce75 --- /dev/null +++ b/doc/kcontrol/kcmlaunch/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmlaunch diff --git a/doc/kcontrol/kcmlaunch/index.docbook b/doc/kcontrol/kcmlaunch/index.docbook new file mode 100644 index 000000000..78bf7008f --- /dev/null +++ b/doc/kcontrol/kcmlaunch/index.docbook @@ -0,0 +1,70 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2006-06-24</date> +<releaseinfo>3.5.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>launch feedback</keyword> +<keyword>cursor</keyword> +<keyword>busy</keyword> +</keywordset> + +</articleinfo> + +<sect1 id="launch-feedback"> +<title><guilabel>Launch Feedback</guilabel></title> + +<para>Sometimes it is reassuring to know that your computer didn't just +ignore your command, and something is happening behind the scenes. In +this module you can configure visible feedback to help you know if you +really hit that icon or not.</para> + +<para>The traditional way to indicate that your computer is busy is to +modify the cursor, and you can turn this on by choosing a +<guilabel>Busy Cursor</guilabel>.</para> + +<para>With this option enabled, your cursor will have an icon attached +to it for a short time, when a new application is being launched. You +can configure how long this icon is displayed beside your cursor with the +<guilabel>Startup indication timeout:</guilabel> spinbox. The +default is 30 seconds.</para> + +<para>There are several variations of busy cursor available, including +a <guilabel>Blinking Cursor</guilabel>, a <guilabel>Bouncing Cursor</guilabel> +or a <guilabel>Passive Busy Cursor</guilabel> icon with no animation.</para> + +<para>Traditional &kde; launch notification has taken another form, +which you can also enable and disable here. Normally when you start an +application, it gets an immediate entry in the taskbar, with the icon +replaced by a spinning hourglass to let you know something is +happening. You can toggle this behavior on and off with the +<guilabel>Enable taskbar notification</guilabel> checkbox, and when it's +enabled, you can set a time in the <guilabel>Startup indication timeout +:</guilabel> spinbox.</para> + +<para>Not all applications that you start will eventually show a +window, or an entry in the taskbar. Some of them, for example, are +docked into the &kde; system tray. Alternatively, it might be that you +sent it off to a different virtual desktop, and <guilabel>Show windows +from all desktops</guilabel> is unchecked in the &kcontrolcenter; module +<guimenuitem>Taskbar</guimenuitem>. Setting a timeout ensures that, +even in these cases, you can still get launch feedback, but also that +it will go away when the job is done.</para> + +</sect1> +</article>
\ No newline at end of file diff --git a/doc/kcontrol/kcmnotify/Makefile.am b/doc/kcontrol/kcmnotify/Makefile.am new file mode 100644 index 000000000..40efdecdc --- /dev/null +++ b/doc/kcontrol/kcmnotify/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmnotify diff --git a/doc/kcontrol/kcmnotify/index.docbook b/doc/kcontrol/kcmnotify/index.docbook new file mode 100644 index 000000000..cf77945f7 --- /dev/null +++ b/doc/kcontrol/kcmnotify/index.docbook @@ -0,0 +1,151 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-03-04</date> +<releaseinfo>3.4.0</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>system notification</keyword> +<keyword>notification</keyword> +</keywordset> +</articleinfo> + +<sect1 id="sys-notify"> +<title>System Notification Settings</title> + +<para>&kde;, like all applications, needs to inform the user when a +problem occurs, a task is completed, or something has happened. &kde; +uses a set of <quote>System Notifications</quote> to keep the user +informed on what is happening.</para> + +<para>Using this module, you can determine what &kde; does to communicate +each event.</para> + +<para>The panel consists of a large list of specific events which need +to be communicated to the user. This list is organized into groups by applications.</para> + +<para>To configure a notification, simply select the application from the drop down box at the top +of the dialog labeled <guilabel>Event source:</guilabel>. This will lead to a list of +all configurable notifications for the application. The list of notifications includes 6 columns to +the left of the notification name. These columns (from left to right) are:</para> + +<variablelist> +<varlistentry> +<term><guiicon>Execute a program</guiicon></term> +<listitem><para>If an icon is present in this column, a seperate program will be executed when this notification is performed. This can be used to execute a program to help restore data, shutdown a potentially compromised system or email another user to alert them to a problem.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Print to standard error output</guiicon></term> +<listitem><para>If an icon is present in this column, &kde; will send a message to the computers standard output.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Display a message box</guiicon></term> +<listitem><para>If an icon is present in this column, &kde; will open a message box and inform the user of the notification. This is probably the most commonly selected option for alerting users to an error.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Log to a file</guiicon></term> +<listitem><para>If an icon is present in this column, &kde; will write certain information to a file on disk for later retrieval. This is useful for tracking problems or important system changes.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Play a sound</guiicon></term> +<listitem><para>This does exactly what you think it does. If an icon is present in this column, &kde; will play a specific sound over the speakers. This is commonly used by games in &kde; for starting a new game, or other action within the game.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Flash the taskbar entry</guiicon></term> +<listitem><para>If an icon is present in this column, &kde; will cause the taskbar to flash until the user has clicked the taskbar entry. This is most useful when you want the user to look at the program (such as a new email message was received, or the users name was said on an IRC channel).</para></listitem> +</varlistentry> +</variablelist> + +<sect2><title>Change a single notification</title> +<para>To make a change to a notification, click on the name of the notification once with the &LMB;. The notification will be highlighted. +Now click on the button labeled +<guibutton>More options</guibutton> so you can see all the checkboxes. </para> + +<tip><para>You can have more than one event triggered by a single notification. As an example, it is easy to have a sound played and +a message box appear in response to a system notification. One notification does not prevent other notifications from operating.</para></tip> +<para>The following list details each of the notification types and how to use them. </para> + +<variablelist> +<varlistentry> +<term><guilabel>Play a sound</guilabel></term> +<listitem><para>If a mark is in this checkbox, &kde; will play a sound everytime this notification is initiated. To specify the sound, use the text box to the right of the checkbox to enter the folder location of the sound file you want &kde; to play. You can use the folder button (located to the far right of the dialog box) to browse your directory tree. To hear a test of your sound, simply click on the play button (small button directly to the right of <guilabel>Play a sound</guilabel>.)</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Log to a file</guilabel></term> +<listitem><para>If a mark is in this checkbox, &kde; will write certain information to a file on disk for later retrieval. To specify the log file to use, enter the pathname in the text box to the right of the checkbox. You can use the folder button (located to the far right of the dialog box) to browse your directory tree. </para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Execute a program</guilabel></term> +<listitem><para>If a mark is in this checkbox, a separate program will be executed when this notification is performed. To specify the program to execute, enter the pathname in the text box to the right of the checkbox. You can use the folder button (located to the far right of the dialog box) to browse your directory tree. </para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show a message in a pop up window</guilabel></term> +<listitem><para>If a mark is in this checkbox, &kde; will open a message box and inform the user of the notification. The text of the box can not be changed from this dialog. If you place a mark in the checkbox labeled <guilabel>Use a passive window that does not interrupt other work</guilabel>, &kde; will open the message box, but it will not change desktops and the message box will not appear until the user returns to the program sending the notification. If that box is left empty, the user must respond to the message box even if it means they have to stop working on another program.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Print a message to standard error output</guilabel></term> +<listitem><para>If a mark is in this checkbox, &kde; will send a message to the computer's standard output.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mark taskbar entry</guilabel></term> +<listitem><para>If a mark is in this checkbox, &kde; will cause the taskbar of the program sending the notification to flash until the user has clicked the taskbar entry.</para></listitem> +</varlistentry> +</variablelist> + +<tip><para>You can use the icon columns (located to the left of the notifications) to quickly select or deselect the options. Clicking in the column with the &LMB; will toggle the notification on and off.</para></tip> + +</sect2> +<sect2><title>Change all notifications in all &kde; applications</title> +<para>You can alter more than one notification at a time by using the section of the dialog labeled <guilabel>Quick Controls</guilabel>.</para> +<para>The first item in this section is a checkbox labeled <guilabel>Apply to all applications</guilabel>. If there is a mark in this checkbox, any changes made in the <guilabel>Quick Controls</guilabel> area are applied to all applications (not just the selected application). If there is no mark in this checkbox, any changes are limited to the application selected at the top of the dialog.</para> +<para>The next line consists of a button and a drop down box. This is used to enable every notification of a single type. Simply select the notification type from the drop down box (on the right) and click the button labeled <guibutton>Turn On All</guibutton>. This will enable all notifications of that type.</para> +<para>The bottom line operates the same, but when you select the button labeled <guibutton>Turn Off All</guibutton>, all the notifications of the selected type will be disabled.</para> +</sect2> +<sect2><title>Change sound player options</title> +<para>If you click the button labeled <guibutton>Player settings</guibutton>, a small dialog box will appear with three radio buttons:</para> +<variablelist> +<varlistentry> +<term><guilabel>Use the &kde; sound system</guilabel></term> +<listitem><para>If a mark is in this radio button, &kde; will play all sound notifications through the &kde; sound system (&arts;). You can adjust the volume of system notifications using the slider.</para> +<note><para>The slider only affects &kde; system notifications. Changes to this slider will not affect other sounds on your computer.</para></note></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Use external player</guilabel></term> +<listitem><para>If a mark is in this radio button, &kde; will not use the &kde; sound system to play the sound. This is a good choice if the sound format you want to use is not supported by the &kde; notification system or if you don't use the &arts; sound daemon. After checking the radio box, enter the full path and name of the program you want to use into the text field. You can use the folder button (located along the right side) to browse the directory tree.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>No audio output</guilabel></term> +<listitem><para>Disables all sound notifications.</para></listitem> +</varlistentry> +</variablelist> +<para>When you have made your selection, click <guibutton>Apply</guibutton> to save changes but keep the dialog box open. Click +<guibutton>OK</guibutton> to save changes and close dialog box. Click <guibutton>Cancel</guibutton> to close the dialog box without +making any changes.</para> +</sect2> +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/kcmsmserver/Makefile.am b/doc/kcontrol/kcmsmserver/Makefile.am new file mode 100644 index 000000000..cf4388a52 --- /dev/null +++ b/doc/kcontrol/kcmsmserver/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmsmserver diff --git a/doc/kcontrol/kcmsmserver/index.docbook b/doc/kcontrol/kcmsmserver/index.docbook new file mode 100644 index 000000000..65cb9423f --- /dev/null +++ b/doc/kcontrol/kcmsmserver/index.docbook @@ -0,0 +1,109 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-13</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>session</keyword> +</keywordset> +</articleinfo> + +<sect1 id="sessions"> +<title>Session Manager</title> + +<sect2 id="sessions-use"> +<title>Use</title> + +<para>In this control module you can configure &kde;'s session +manager.</para> + +<para>Session management refers to &kde;'s ability to save the state +of applications and windows when you log out of &kde; and restore them +when you log back in.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Confirm logout</guilabel></term> +<listitem> +<para>If this option is checked, when logging out, &kde; will display a +dialog asking for confirmation. In this dialog you can also choose +whether you want to restore your current session when you login the next +time.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Offer shutdown options</guilabel></term> +<listitem> +<para>If this option is checked, &kde; will offer a choice of actions during +logout. These include simply ending the current session (the +action performed if shutdown options are not enabled) turning off the +computer, or restarting the computer.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>You may choose one of three options on what should happen when +you log into &kde;:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Restore previous session</guilabel></term> +<listitem><para>If this option is checked, &kde; will save your current +session's state when you logout. &kde; will restore your session on the +next login, so you can continue to work with a desktop just like you +left it.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Restore manually saved session</guilabel></term> +<listitem><para>Instead of restoring &kde; to the state it was when +you logged out last, it will be restored to a specific state that you +have saved manually. <!-- FIXME: How do you *save* the session in the +first place? --></para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Start with an empty session</guilabel></term> +<listitem> +<para>If you choose this option, &kde; will never restore sessions that it has saved.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>You can configure what should happen by default when you log out of +&kde;. These options are not possible on all operating systems, and some of +them may not appear unless you are using &kdm; as your login manager.</para> + +<para>The options available are self explanatory, if you are in doubt, +leave the default settings. They are:</para> + +<itemizedlist> +<listitem><para><guilabel>End current session</guilabel> (this is the default)</para></listitem> +<listitem><para><guilabel>Turn off computer</guilabel></para></listitem> +<listitem><para><guilabel>Restart computer</guilabel></para></listitem> +</itemizedlist> + +<para>Finally, you can enter a colon (<literal>:</literal>) +separated list of applications that should not be saved in sessions, +and therefore won't be started when restoring a session. For example +<userinput>xterm:konsole</userinput>.</para> + +</sect2> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/kcmstyle/Makefile.am b/doc/kcontrol/kcmstyle/Makefile.am new file mode 100644 index 000000000..067f33e6c --- /dev/null +++ b/doc/kcontrol/kcmstyle/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmstyle diff --git a/doc/kcontrol/kcmstyle/index.docbook b/doc/kcontrol/kcmstyle/index.docbook new file mode 100644 index 000000000..4d38cf2fc --- /dev/null +++ b/doc/kcontrol/kcmstyle/index.docbook @@ -0,0 +1,189 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-20</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>style</keyword> +</keywordset> +</articleinfo> +<sect1 id="style"> +<title>Style</title> + +<sect2 id="style-intro"> +<title>Introduction</title> + +<para>This module is used to configure how the individual widgets are +drawn by &kde;.</para> + +<note><para>A <emphasis>Widget</emphasis> is a commonly-used +programmer's term for referring to User Interface elements such as +buttons, menus, and scroll bars. You can think of them as the +fundamental pieces that are assembled to make your +application.</para></note> + +<para>You can configure how the widgets are drawn with this module, +but to change the color of the widgets, you should refer to the +section entitled <ulink +url="help:/kcontrol/color/index.html">Colors</ulink>.</para> + +<para>This panel is divided into three tabs: <guilabel>Style</guilabel>, +<guilabel>Effects</guilabel>, <guilabel>Toolbar</guilabel>.</para> + +<sect3 id="style-style"> +<title><guilabel>Style</guilabel> tab</title> + +<para>The top list box, labeled <guilabel>Widget Style</guilabel> +contains a list of the pre-defined styles. +Each style has a name, and a brief description.</para> + +<para>To change styles, simply click on the style name, and a preview +of the style will be displayed in the preview box below the style list.</para> + +<para>The other options available here are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Show icons on buttons</guilabel></term> +<listitem> +<para>If this option is selected, action buttons (like <guibutton>OK</guibutton> and +<guibutton>Apply</guibutton>) will have a small icon located within them to act +as a visual reference. If this option is not selected, then only text +will appear on the button.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Enable tooltips</guilabel></term> +<listitem> +<para>This will toggle tooltips off and on.</para> +</listitem> +</varlistentry> +</variablelist> +<!-- +<varlistentry> +<term><guilabel>Menubar on the top of +the screen in the style of MacOS</guilabel></term> +<listitem> +<para>This will turn on a menubar at the top of the screen. +This menubar will reflect the menu options of the active +application.</para> +</listitem> +</varlistentry> +</variablelist> +--> +</sect3> + +<sect3 id="style-effects"> +<title><guilabel>Effects</guilabel> tab</title> + +<para>If you click on the <guilabel>Effects</guilabel> tab, you will see the panel is divided +into two sections.</para> +<para>At the top of the first section, is a checkbox labeled <guilabel>Enable +GUI effects</guilabel>. If there is no mark in front of this checkbox, then all +visual effects of this panel are disabled. To edit any of these effects, simply +place a mark in this checkbox.</para> + +<para>Below that checkbox, are the following choices: </para> +<variablelist> +<varlistentry> +<term><guilabel>Combobox effect:</guilabel></term> +<listitem><para>This combobox has two options. If this option is set to <guilabel>Animate</guilabel> +then when a combo box is selected, it will appear to scroll down. If <guilabel>Disable</guilabel> +is selected, then the combobox list appears instantly.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Tool tip effect:</guilabel></term> +<listitem><para>This combobox has three options. If this option is set to <guilabel>Animate</guilabel> +then when a tool tip appears, it will have a short animation. If <guilabel>Fade</guilabel> is +selected, the tool tip appears to fade from the background. If <guilabel>Disable</guilabel> +is selected, then the tool tip appears instantly.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Menu effect:</guilabel></term> +<listitem><para>This combobox has four options. If this option is set to <guilabel>Animate</guilabel> +then when a menu list appears, it will appear to scroll downward. If <guilabel>Fade</guilabel> is +selected, the menu list appears to fade from the background. If <guilabel>Make Transparent</guilabel> +is selected, the menu list will have a transparent look to it. The details of that transparency is +configured in the next part of the dialog. If <guilabel>Disable</guilabel> +is selected, then the menu list appears instantly.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Menu tear-off handles:</guilabel></term> +<listitem><para>If this option is set to <guilabel>Disable</guilabel>, then no menus can be separated +from the application. If <guilabel>Application Level</guilabel> is selected, then it is left up +to each individual application to determine which menus can be torn separated from the application.</para> +<note><para>Many applications do not have tear off menus. You cannot tell &kde; to force an +application to allow tear off menus. This is determined by the authors of the application.</para></note></listitem> +</varlistentry> +</variablelist> + +<para>The next checkbox, labeled <guilabel>Menu drop shadow</guilabel> is used to toggle the drop shadow behind all +&kde; menus. A drop shadow is a dark, soft line on the bottom and right sides of the menu, which give the menus the +appearance that the menu is lifted off the application, and the menu is creating a shadow on the application.</para> + +<para>The next section only applies if the combobox labeled <guilabel>Menu Effect</guilabel> is set to +<guilabel>Make Transparent</guilabel>. You can use the combo box labeled <guilabel>Menu transparency type:</guilabel> +to select the method &kde; uses to generate the transparency. You can use the slider to determine the level of +transparency in menus. A preview is visible on the right side of this section.</para> + +</sect3> + +<sect3 id="style-misc"> +<title><guilabel>Toolbar</guilabel> tab</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Highlight buttons under mouse.</guilabel></term> +<listitem> +<para>If there is a mark in this checkbox, when the mouse pointer is above a toolbar +button, that button will be highlighted with a square around the button. This is a good visual +indicator of which button will be selected with a mouse click.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Transparent toolbars when moving</guilabel></term> +<listitem> +<para>As the title suggests, if this option is selected, the toolbars will be transparent when +you are moving them around on the screen.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Text position</guilabel></term> +<listitem> +<para>This combo box lets you determine where on the button the text name of the button will appear as the default. +If <guilabel>Icon Only</guilabel> is selected, then there is no text on the toolbar buttons. If <guilabel>Text Only</guilabel> is selected, then the button's icon is replaced with a text name of the button. If <guilabel>Text Alongside Icons</guilabel> is selected, then the name of the button will be placed to the <emphasis>right</emphasis> of the icon. If <guilabel>Text Under Icons</guilabel> is selected, the default will be to have the text of the button <emphasis>below</emphasis> the icon.</para> +<tip><para>This option only specifies the <emphasis>default</emphasis> location. Each application can override the setting used in this panel.</para></tip> +</listitem> +</varlistentry> + +</variablelist> + +</sect3> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/kcmtaskbar/Makefile.am b/doc/kcontrol/kcmtaskbar/Makefile.am new file mode 100644 index 000000000..756585015 --- /dev/null +++ b/doc/kcontrol/kcmtaskbar/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kcmtaskbar diff --git a/doc/kcontrol/kcmtaskbar/index.docbook b/doc/kcontrol/kcmtaskbar/index.docbook new file mode 100644 index 000000000..3f73691a3 --- /dev/null +++ b/doc/kcontrol/kcmtaskbar/index.docbook @@ -0,0 +1,142 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2006-06-24</date> +<releaseinfo>3.5.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>taskbar</keyword> +<keyword>configure</keyword> +</keywordset> +</articleinfo> + +<sect1 id="taskbar"> +<title>Taskbar</title> + +<sect2> +<title><guilabel>Taskbar</guilabel></title> + +<para>The taskbar is a quick way to switch between applications. The taskbar +can be located in the panel (default), or outside the panel on the +desktop.</para> + +<para>This module has options to control how the taskbar operates:</para> + +<para><guilabel>Show windows from all desktops</guilabel>, determines +if all open windows are included in the taskbar or not. By default, +the taskbar only shows the open windows <emphasis>on the current +desktop</emphasis>. If this option is enabled, the taskbar will show +all open windows <emphasis>on all desktops</emphasis>. +<guilabel>Sort windows by desktop</guilabel> changes the +sort order of the icons on the taskbar, so that windows on virtual +desktop 1 are shown first (to the left, or at the top of the taskbar), +followed by windows on virtual desktop 2, and so on.</para> + +<para><guilabel>Sort alphabetically by application name</guilabel> shows +the icons in an alphabetical sort order on the taskbar.</para> + +<para>You can have the taskbar <guilabel>Show only minimized +windows</guilabel>. In this case, when you minimize a window, it will +show up on the taskbar, and when you open it again, its taskbar entry +will disappear.</para> + +<para>You can disable <guilabel>Show application icons</guilabel>, and show just the +text. You might want to do this to save space on your taskbar, for +example.</para> + +<para>Using the <guilabel>Show window list button</guilabel> option, +you can enable a little button to be shown in the taskbar: this button +will open a popup menu offering access to applications on other desktops +as well as some useful actions, like <guilabel>Unclutter +Windows</guilabel> or <guilabel>Cascade Windows</guilabel>.</para> + +<para><guilabel>Group similar tasks</guilabel> allows +you to save some space on your taskbar, by only showing one icon for +each running application, no matter how many windows are shown. You can +click on the icon to display a menu of all the windows that are +available. This is most useful when you have enabled <guilabel>Show windows +from all desktops</guilabel>.</para> + +<para>The next option allows you to set the <guilabel>Appearance</guilabel> to <guilabel>Elegant</guilabel>, <guilabel>Classic</guilabel> or <guilabel>For Transparency</guilabel>.</para> + +</sect2> + +<sect2> +<title><guilabel>Actions</guilabel></title> + +<para>The next set of options allow you to customize the actions +performed with different mouse clicks on taskbar icons.</para> + +<para>You can select any action from the list for the <guilabel>Left button</guilabel>, +the <guilabel>Middle button</guilabel> and the <guilabel>Right button</guilabel>.</para> + +<para>The options available are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Show Task List</guilabel></term> +<listitem> +<para>Show the list of tasks grouped under the icon you have clicked +on. If there is only one task or window for that icon, it will become +the active window.</para> +<para>This is the default action for the &LMB;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Cycle Through Windows</guilabel></term> +<listitem> +<para>If there is more than one task grouped under the icon, switch +from one to the next, until you release the button (&ie; when you have +reached the window you are looking for). If there is only one task or +window for that icon, it will become the active window.</para> + +<para>This is the default action for the &MMB; if window grouping is +enabled.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Operations Menu</guilabel></term> +<listitem> +<para>Show the operations menu for the application. This allows you +to minimize, maximize, &etc;, move windows between desktops, and close +windows. You can perform these actions on all windows grouped under +that icon, or on any single window, by choosing it from the +submenu.</para> +<para>This is the default action for the &RMB;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Raise Task</guilabel>, <guilabel>Lower +Task</guilabel>, <guilabel>Minimize Task</guilabel></term> +<listitem> +<para>These three options make sense only if window grouping is +disabled. They are fairly self-explanatory. Raise means to make +active, bring to the front, and give focus. Lower means, send to the +back, and give focus to whichever window is now on top.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/kdm/Makefile.am b/doc/kcontrol/kdm/Makefile.am new file mode 100644 index 000000000..511936b0f --- /dev/null +++ b/doc/kcontrol/kdm/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kdm diff --git a/doc/kcontrol/kdm/index.docbook b/doc/kcontrol/kdm/index.docbook new file mode 100644 index 000000000..8f00db2f3 --- /dev/null +++ b/doc/kcontrol/kdm/index.docbook @@ -0,0 +1,518 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Thomas.Tanghus; &Thomas.Tanghus.mail;</author> +<author>&Steffen.Hansen; &Steffen.Hansen.mail;</author> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-13</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>KDM configuration</keyword> +<keyword>login manager</keyword> +<keyword>login</keyword> +</keywordset> +</articleinfo> + +<sect1 id="login-manager"> +<title>Login Manager</title> + +<para>Using this module, you can configure the &kde; graphical login +manager, &kdm;. You can change how the login screen looks, who has +access using the login manager and who can shutdown the +computer.</para> + +<para>In order to organize all of these options, this module is +divided into six sections: <link +linkend="kdmconfig-appearance"><guilabel>Appearance</guilabel></link>, +<link linkend="kdmconfig-font"><guilabel>Font</guilabel></link>, <link +linkend="kdmconfig-background"><guilabel>Background</guilabel></link>, +<link +linkend="kdmconfig-sessions"><guilabel>Sessions</guilabel></link>, +<link linkend="kdmconfig-users"><guilabel>Users</guilabel></link> and +<link +linkend="kdmconfig-convenience"><guilabel>Convenience</guilabel></link>.</para> + +<para>You can switch between the sections using the tabs at the top of +the window.</para> + +<note><para>If you are not currently logged in as a superuser, you +will need to click the <guibutton>Administrator Mode</guibutton> +Button. You will then be asked for a superuser password. Entering a +correct password will allow you to modify the settings of this +module.</para></note> + +<sect2 id="kdmconfig-appearance"> +<title>Appearance</title> + +<para>From this page you can change the visual appearance of &kdm;, +&kde;'s graphical login manager.</para> + +<para>The greeting string is the title of the login screen. If the +string contains the word <computeroutput>HOSTNAME</computeroutput> it +will be translated to the domainless name of the machine &kdm; is +installed on.</para> + +<para>You can then choose to show either the current system time, a logo +or nothing special in the login box. Make your choice in the radio +buttons labeled <guilabel>Logo area</guilabel>. Using the +<guilabel>Positions</guilabel> setting, you can choose to either center +the content of the logo area or to position it using fixed +coordinates.</para> + +<para>If you chose <guilabel>Show logo</guilabel> you can now choose a +logo:</para> + +<itemizedlist> +<listitem> +<para>Drop an image file on the image button.</para> +</listitem> +<listitem> +<para>Click on the image button and select a new image from the image chooser +dialog.</para> +</listitem> +</itemizedlist> + +<para>If you do not specify a logo the default +<filename>$<envar>KDEDIR</envar>/share/apps/kdm/pics/kdelogo.png</filename> +will be displayed.</para> + +<para>While &kde;'s style depends on the settings of the user logged in, +the style used by &kdm; can be configured using the <guilabel>GUI +Style</guilabel> option.</para> + +<para>Below that, you have two dropdown boxes to choose the language and the +country for your login box.</para> + +</sect2> + +<sect2 id="kdmconfig-font"> +<title>Font</title> + +<para>From this section of the module you can change the fonts used in +the login window.</para> + +<para>You can select three different font styles from the drop down box +(<guilabel>Greeting</guilabel>, <guilabel>Fail</guilabel>, +<guilabel>Standard</guilabel>). When you click on the <guibutton>Change +font</guibutton> button a dialog appears from which you can select the +new characteristics for the font style.</para> + +<itemizedlist> +<listitem> +<para>The <guilabel>Greeting</guilabel> font is the font used for the title +(Greeting String).</para> +</listitem> +<listitem> +<para>The <guilabel>Fail</guilabel> font is used when a login fails.</para> +</listitem> +<listitem> +<para>The <guilabel>Standard</guilabel> font is used in all other places in the +login window.</para> +</listitem> +</itemizedlist> + +<para>An example of each font can be seen in the +<guilabel>Example</guilabel> Box.</para> + +</sect2> + +<sect2 id="kdmconfig-background"> +<title>Background</title> + +<para>Here you can change the desktop background which will be displayed +when a user logs in. You can have a single color or an image as a +background. If you have an image as the background and select center, the +selected background color will be used around the image if it isn't +large enough to cover the entire desktop.</para> + +<para>The background colors and effects are controlled by the options on +the tab labeled <guilabel>Background</guilabel> and you select a +background image and its placement from the options on the tab labeled +<guilabel>Wallpaper</guilabel>.</para> + +<para>To change the default background color(s) simply click either of +the color buttons and select a new color.</para> + +<para>The dropdown box above the color buttons provides you with several +different blend effects. Choose one from the list, and it will be +previewed on the small monitor at the top of the window. Your choices +are:</para> + +<variablelist> +<varlistentry> +<term>Flat</term> +<listitem><para>By choosing this mode, you select one color (using the color +button labeled <guibutton>Color 1</guibutton>), and the entire background is +covered with this one color.</para></listitem> +</varlistentry> +<varlistentry> +<term>Pattern</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). </para> <para>You then select a pattern by clicking +<guilabel>Setup</guilabel>. This opens a new dialog window, which gives you +the opportunity to select a pattern. Simply click once on the pattern of your +choice, then click on <guilabel>OK</guilabel>, and &kde; will render the pattern +you selected using the two colors you selected. For more on patterns, see the +section <ulink url="help:/kcontrol/background/index.html#bkgnd-patterns">Background: Adding, Removing and Modifying +Patterns</ulink>.</para></listitem> +</varlistentry> +<varlistentry> +<term>Background Program</term> +<listitem><para>By selecting this option, you can have &kde; use an external +program to determine the background. This can be any program of your choosing. +For more information on this option, see the section entitled <ulink +url="help:/kcontrol/background/index.html#bkgnd-programs">Background: Using an external program</ulink>.</para></listitem> +</varlistentry> +<varlistentry> +<term>Horizontal Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> on the left edge of the screen, and slowly transform into the +color selected by <guilabel>Color 2</guilabel> by the time it gets to the +right edge of the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term>Vertical Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> on the top edge of the screen, and slowly transform into the color +selected by <guilabel>Color 2</guilabel> as it moves to the bottom of the +screen.</para></listitem> +</varlistentry> +<varlistentry> +<term>Pyramid Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> in each corner of the screen, and slowly transform into the color +selected by <guilabel>Color 2</guilabel> as it moves to the center of the +screen.</para></listitem> +</varlistentry> +<varlistentry> +<term>Pipecross Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> in each corner of the screen, and slowly transform into the color +selected by <guilabel>Color 2</guilabel> as it moves to the center of the +screen. The <quote>shape</quote> of this gradient is different then the pyramid +gradient.</para></listitem> +</varlistentry> +<varlistentry> +<term>Elliptic Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +2</guilabel> in the center of the screen, and slowly transform into the color +selected by <guilabel>Color 1</guilabel> as it moves to the edges, in an +elliptical pattern.</para></listitem> +</varlistentry> +</variablelist> + +<para>The setup button is only needed for if you select <guilabel>Background +program</guilabel> or <guilabel>Patterns</guilabel>. In these instances, +another window will appear to configure the specifics.</para> +<para><emphasis>Wallpaper</emphasis></para> +<para>To select a new background image first, click on the +<guilabel>Wallpapers</guilabel> tab, then you can either select an image from the +drop-down list labeled <guilabel>Wallpaper</guilabel> or select +<guibutton>Browse...</guibutton> and select an image file from a file +selector.</para> + +<para>The image can be displayed in six different ways:</para> +<variablelist> +<varlistentry> +<term>No wallpaper</term> +<listitem><para>No image is displayed. Just the background colors.</para> +</listitem></varlistentry> +<varlistentry> +<term>Centered</term> +<listitem><para>The image will be centered on the screen. The background colors +will be present anywhere the image does not cover.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Tiled</term> +<listitem><para>The image will be duplicated until it fills the entire +desktop. The first image will be placed in the upper left corner of the screen, +and duplicated downward and to the right.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Center Tiled</term> +<listitem><para>The image will be duplicated until it fills the entire +desktop. The first image will be placed in the center of the screen, and +duplicated upward, downward to the right, and to the left.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Centered Maxpect</term> +<listitem><para>The image will be placed in the center of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio of the +original image. This will provide you with an image that is not distorted. +</para> </listitem> +</varlistentry> +<varlistentry> +<term>Scaled</term> +<listitem><para>The image will be scaled to fit the desktop. It will be +stretched to fit all four corners.</para> </listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="kdmconfig-sessions"> +<title>Sessions</title> + +<para><guilabel>Allow to shutdown</guilabel></para> +<para>Use this dropdown box to choose who is allowed to shut down:</para> +<itemizedlist> +<listitem> +<para><guilabel>None</guilabel>: No one can shutdown the computer using &kdm;. +You must be logged in, and execute a command.</para> +</listitem> +<listitem> +<para><guilabel>All</guilabel>: Everyone can shutdown the computer using +&kdm;.</para> +</listitem> +<listitem><para><guilabel>Root only</guilabel>: &kdm; requires that the +<systemitem>root</systemitem> password be entered before shutting down the +computer.</para></listitem> +<listitem><para><guilabel>Console only</guilabel>: The user must be at this +console, to shut down the computer.</para></listitem> +</itemizedlist> + +<para><emphasis>Commands</emphasis></para> +<para>Use these 3 blanks to define the exact shutdown command.</para> +<para>The shutdown command defaults to:</para> + +<para><command>/sbin/shutdown</command></para> + +<para>The restart command defaults to:</para> + +<para><command>/sbin/reboot</command></para> + +<para>The Console mode (which restarts the computer as a console only terminal) +defaults to:</para> + +<para><command>/sbin/init <option>3</option></command></para> + +<para>When <guilabel>Show boot options</guilabel> is enabled, &kdm; will on reboot +offer you options for the lilo boot manager. For this feature to work, you will +need to supply the correct paths to your <command>lilo</command> command and to +lilo's map file.</para> + + +<sect3 id="kdmconfig-sess"> +<title>Session types</title> + +<para>Define which session types should be accessible from the login +window.</para> + +<para> For more information on this subject, look at <filename +class="directory">/etc/X11/xdm/Xsession</filename> to find your +<application>xdm</application> setup files. Also review the <ulink +url="man:xdm">xdm man pages</ulink>, especially under the SESSION +PROGRAM section.</para> + +<para>To add a session, type its name in the +blank entitled <guilabel>New types</guilabel>, and click +<guibutton>Add new</guibutton>. </para> + +<para>To remove a session, select the session from the list and click +<guibutton>Remove</guibutton>.</para> + +</sect3> + +</sect2> + + +<sect2 id="kdmconfig-users"> +<title>Users</title> + +<para>From here you can change the way users are represented in the +login window.</para> + +<para>As you look on this window, you will see three lists (All users, +selected users, and no-show users). You also see an image box, and a +set of options along the right side of the window.</para> + +<para>The first thing you must decide, is if you are going to show users +or not.</para> + + +<para>If you choose to show users, then the login window will show +images (which you select), of a list of users. When someone is ready to +login, they select their user name/image, enter their password, and they +are granted access. </para> + +<para>If you choose not to show users, then the login window will be +more traditional. Users will need to type their username, and password +to gain entrance. This is the preferred way if you have many users on +this terminal.</para> + +<sect3 id="kdmconfig-showusers"> +<title>To show (and sort) or not to show users</title> + +<para>Along the right edge of the window are two check boxes:</para> + +<para>If <guilabel>Show users</guilabel> is selected, you have chosen to +show images of users, instead of making them type their login +name.</para> + +<para>If <guilabel>Sort users</guilabel> is selected, then the list of +users will be sorted alphabetically in the login window. If unchecked, +users will be listed in the same order as they are on this page. If +<guilabel>Show users</guilabel> is not checked, this has no +effect.</para> + +</sect3> + +<sect3 id="kdmconfig-whichusers"> +<title>How to determine which users to show and which users to hide</title> + +<para>Below the user image box, and above the <guilabel>Show +users</guilabel> check box, is a set of two radio buttions:</para> + +<itemizedlist> +<listitem><para>Show only selected users: If this option is selected, only the +users contained in the list labelled <guilabel>Selected Users</guilabel>, will +be displayed in the login window. If <guilabel>Show users</guilabel> is not +checked, this has no effect.</para></listitem> +<listitem><para>Show all users but no-show users: If this option is selected, +all users will be listed, <emphasis>except</emphasis> those users contained in +the list entitled <guilabel>No show users</guilabel>. If <guilabel>Show +users</guilabel> is not checked, this has no effect. </para></listitem> +</itemizedlist> + +</sect3> + +<sect3 id="kdmconfig-select"> +<title>Select users</title> + +<para>This page contains three listboxes. The large listbox on the left +shows all the users on the system which might be a genuine user.</para> + +<para>The top rightmost listbox shows the selected users and the bottom +rightmost listbox shows the users we don't want displayed in the login +window.</para> + +<para>To move a user from one listbox to another you click on the +username in the listbox and click <guibutton>>></guibutton> to +move the user from the leftmost box the the rightmost box or +<guibutton><<</guibutton> to move the user from the rightmost box +to the leftmost box.</para> + +</sect3> + +<sect3 id="kdmconfig-image"> +<title>Images</title> + +<note><para>This section of the manual only applies if <guilabel>Show +users</guilabel> is selected. If it is not, this image box has no +effect.</para></note> + +<para>Every user on the system can be represented by a image. The image +for the user is kept in a file called +<filename>$<envar>KDEDIR</envar>/share/apps/kdm/pics/users/$<envar>USER</envar>.xpm.</filename> +If the user doesn't have such a file the file +<filename>$<envar>KDEDIR</envar>/share/apps/kdm/pics/users/default.xpm</filename> +will be used instead.</para> + +<para>To assign a new image to a user just select the user in one of the +listboxes and either drop an imagefile on the image button to the right +or click on the image button and select a new image from the image +selector.</para> + +<para>If no user is currently selected you will be asked if you want to change +the default image.</para> + +<para>The replacement is performed by a &konqueror; process so if the +image file already exists you will be prompted by &konqueror; if you +want to replace it. If you confirm the image will be replaced - you will +<emphasis>not</emphasis> have to press the <guibutton>Apply</guibutton> +button.</para> + +</sect3> +</sect2> + + +<sect2 id="kdmconfig-convenience"> +<title>Convenience</title> + +<para>In the <guilabel>convenience</guilabel> tab you can configure some +options that make life easier for lazy people, like auto login or +disabling passwords.</para> + +<important><para>Please think more than twice before using these +options. Every option in the <guilabel>convenience</guilabel> tab is +well-suited to seriously compromise your system security. Practically, +these options are only to be used in a completely non-critical +environment, ⪚ a private computer at home. </para></important> + +<sect3 id="loginmanager-convenience-autologin"> +<title>Automatic Login</title> + +<para>Automatic login will give anyone access to a certain account on +your system without doing any authentication. You can enable it using +the option <guilabel>Enable auto-login</guilabel>.</para> + +<para>Automatic login comes in two flavors: <guilabel>truly automatic +login</guilabel> acts like you would expect automatic login to, &ie; +&kdm; will automatically login without expecting any input from the +user. Enable this using the <guilabel>Truly automatic login</guilabel> +option. If this option is not enabled, &kdm; will start normally, +enabling you to login as any user, and will only perform automatic login +if you kill the X server, ⪚ by pressing <keycombo +action="simul">&Ctrl;&Alt;<keycap>Backspace</keycap></keycombo>.</para> + +<para>You can choose the account to be used for automatic login in the +list below.</para> + +</sect3> + +<sect3 id="loginmanager-convenience-nopasswd"> +<title>Password-less Login</title> + +<para>Using this feature, you can allow certain users to login without +having to provide their password. Enable this feature using the +<guilabel>Enable password-less logins</guilabel> option.</para> + +<para>Below this option you will see a list of users for which a password +is required, as well as a (by default, empty) list of users that do not +need to provide a password. When <guilabel>Enable password-less +logins</guilabel> is enabled, you can move users from one list into the +other, by selecting them and then clicking the +<guibutton>>></guibutton> and <guibutton><<</guibutton> +buttons.</para> + +<important><para>Again, this option should only be used in a safe +environment. If you enable it on a rather public system you should take +care that only users with heavy access restrictions are granted +password-less login, ⪚ +<systemitem>guest</systemitem>.</para></important> + +<para>The <guilabel>Automatically login after X server crash</guilabel> +option allows you to skip the authentication procedure when your X +server accidentally crashed. <guilabel>Show previous user</guilabel> +will show the name of the last login already entered into the login +field in &kdm;. Some site administrators would consider even this a +possible security weakness, because potential attackers then know at +least one valid login.</para> + + +</sect3> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/keyboard/Makefile.am b/doc/kcontrol/keyboard/Makefile.am new file mode 100644 index 000000000..16b3221e1 --- /dev/null +++ b/doc/kcontrol/keyboard/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/keyboard diff --git a/doc/kcontrol/keyboard/index.docbook b/doc/kcontrol/keyboard/index.docbook new file mode 100644 index 000000000..489443264 --- /dev/null +++ b/doc/kcontrol/keyboard/index.docbook @@ -0,0 +1,90 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>keyboard</keyword> +</keywordset> +</articleinfo> +<sect1 id="kbd"> +<title>Keyboard</title> + +<para>This module allows you to choose how your keyboard works.</para> + +<para>The actual effect of setting these options depends upon the +features provided by your keyboard hardware and the X server on which +&kde; is running. As an example, you may find that changing the key +click volume has no effect because that feature is not available on your +system. </para> + +<sect2 id="kbd-use"> +<title>Advanced</title> + +<variablelist> +<varlistentry> +<term><guilabel>Enable keyboard repeat</guilabel></term> +<listitem> +<para>When this option is selected, pressing and holding down a key +emits the same character repeatedly until the key is released. Pressing +and holding the key will have the same effect as pressing it multiple +times in succession. </para> +<tip><para> Almost all users will want to have this option enabled, because it +makes navigating through documents with the arrow keys significantly +easier. </para></tip> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>NumLock on KDE Startup</guilabel></term> +<listitem> +<para>You can choose to either always <guilabel>Turn on</guilabel> or +<guilabel>Turn off</guilabel> the NumLock when &kde; starts, or you can +choose to have &kde; leave NumLock at whatever it was set to before KDE +started up.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Key click volume:</guilabel></term> +<listitem> +<para>If supported, this option allows you to hear audible clicks from +your computer's speakers when you press the keys on your keyboard. In +essence, this simulates the <quote>click</quote> of a mechanical +type-writer. You can change the loudness of the key click feedback by +dragging the slider button or by clicking the up/down arrows on the +spin-button. Setting the volume to 0% turns off the key +click.</para> +<para>Many computers won't support this function.</para> +<tip><para>Very few people would choose to enable this option, since it +generally annoys everyone else in the room. However, if your heart +yearns for the pre-soft-key era, this may help you to re-experience the +warm sentimentality of days-gone-by.</para> +</tip> +</listitem> +</varlistentry> + + +</variablelist> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/keys/Makefile.am b/doc/kcontrol/keys/Makefile.am new file mode 100644 index 000000000..5b4b56825 --- /dev/null +++ b/doc/kcontrol/keys/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/keys diff --git a/doc/kcontrol/keys/index.docbook b/doc/kcontrol/keys/index.docbook new file mode 100644 index 000000000..6b7d04a6e --- /dev/null +++ b/doc/kcontrol/keys/index.docbook @@ -0,0 +1,191 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-13</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>key bindings</keyword> +<keyword>bindings</keyword> +<keyword>shortcuts</keyword> +</keywordset> +</articleinfo> + +<sect1 id="key-bindings"> +<title>Shortcuts</title> + +<sect2 id="key-bindings-intro"> +<title>Introduction</title> + +<para>While most of the functionality offered by &kde; can be accessed +using a simple <quote>point and click</quote> interface, many people +prefer using the keyboard for some tasks. Pressing something like +<keycombo action="simul"> &Ctrl;<keycap>F</keycap></keycombo> is often +just faster than moving your hands off the keyboard to the mouse, +opening the <guimenu>Edit</guimenu> menu and selecting +<guimenuitem>Find</guimenuitem>.</para> + +<para> As different people have different preferences about keyboard +shortcuts, &kde; offers full customization of <quote>key +bindings.</quote> A key binding or shortcut is a combination of an +action with a key or a combination of keys.</para> + +</sect2> + +<sect2 id="key-bindings-use"> +<title>Use</title> + +<para>In the Shortcuts control module you'll see a list of <quote>key +schemes,</quote> a list of key bindings in the currently selected +scheme and a frame where you can customize the currently selected key +binding. Also, you'll see a tab for <guilabel>Global +shortcuts</guilabel> and one for <guilabel>Application +shortcuts</guilabel>.</para> + +<sect3 id="key-bindings-use-globapp"> +<title>Global Shortcuts and Application Shortcuts</title> + +<para><guilabel>Global shortcuts</guilabel> and <guilabel>application +shortcuts</guilabel> work just the same. Actually, in a certain way +application shortcuts are <quote>global</quote> as well. The only +difference is:</para> + +<itemizedlist> +<listitem><para><quote>Global shortcuts</quote> are shortcuts for +actions that make sense even when no application is opened. These +shortcuts usually refer to actions like switching desktops, manipulating +windows etc. </para></listitem> +<listitem><para><quote>Application shortcuts</quote> refer to actions +that are often available in applications, such as Save, Print, Copy +etc.</para></listitem> +</itemizedlist> + +<para>Please note, that the application shortcuts configured here are +<emphasis>only</emphasis> the standard actions often found in +applications. Most applications will define their own actions as well, +for which you have to customize key bindings using the application's +key bindings dialog.</para> + +</sect3> + +<sect3 id="key-bindings-use-confkeys"> +<title>Configuring Key Bindings</title> + +<para>Configuring key bindings is pretty easy. In the middle of the +key bindings control module you'll find a list of available +actions. If there's a key binding configured for that action you'll +find it right next to it. Just select the action you want to +configure.</para> + +<para>After you've selected an action you'll notice that most of the +controls below the action list are enabled. There you can configure a +combination of keys or maybe no key binding at all for the selected +action. </para> + +<itemizedlist> +<listitem><para><guilabel>No key</guilabel>: the selected action will not +be associated with any key.</para></listitem> + +<listitem><para><guilabel>Default key</guilabel>: the selected action +will be associated with &kde;'s default value. This is a good choice +for most actions, as &kde; comes with reasonable key bindings we have +thought about. </para></listitem> + +<listitem><para><guilabel>Custom key</guilabel>: if this option is +enabled, you can create a key combination for the selected +action. Just select any modifiers (&ie; &Shift;, &Ctrl;, or &Alt;) and +then select a key: just click on the key symbol and after that press +the key you want to assign to this key combination.</para></listitem> + +</itemizedlist> + +<para>As with all control modules, your changes won't take in effect +until you click <guibutton>OK</guibutton> or +<guibutton>Apply</guibutton>. Click <guibutton>Cancel</guibutton> to +discard all changes.</para> + +</sect3> + +<sect3 id="key-bindings-use-confschemes"> +<title>Configuring Schemes</title> + +<para>A key binding scheme is a set of key bindings that you can +select by name. &kde; comes with several pre-defined key binding +schemes. In addition to these bundled schemes, you will always see a scheme named +<guilabel>Current scheme</guilabel> that represents the set of key +bindings you are using right now (&ie; not the current settings you +are playing with, but what you've been using up to now). </para> + +<para>When you are playing with the key bindings for the first time +you don't have to be afraid of changing the default bindings: &kde; +won't let you overwrite the defaults, so you can always switch back to +the factory presets. By choosing <guilabel>Current scheme</guilabel> +you can return to the set of key bindings you've been using up to +now. However, be careful not to select a scheme when you've made +changes to the key bindings you don't want to lose.</para> + +<para>When you are satisfied with a set of key bindings you've +created, you may want to save them to a scheme of your own, so that +you can still experiment with the bindings and always return to a +certain scheme. You can always do this by clicking on the +<guibutton>Add</guibutton> button. You will be prompted for a name +and then the new scheme will appear in the key schemes listbox. You +can remove your own schemes again by selecting a scheme and clicking +the <guibutton>Remove</guibutton> button. Click the <guibutton>Save +changes</guibutton> button to save any changes you have made to the +currently selected scheme. Note that you can not remove or save +changes to <guilabel>KDE default</guilabel> or to <guilabel>Current +scheme</guilabel>.</para> + +<important><para>If you want to save your changes while a read-only +scheme is selected, you always have to add a new scheme first! If you +select one of your own schemes because you want to save the changes to +that one, the control module will switch to the key bindings of that +scheme, discarding your changes.</para></important> </sect3> + +</sect2> + +<sect2> +<title>Modifier Keys</title> + +<para>Different keyboards offer different sets of modifier keys. A +&Mac; keyboard, for example, does not have a &Ctrl; key, and instead +has an <keycap>Option</keycap> key. Here you can see what the +available modifier keys for the current keyboard are.</para> + +<para>If you enable <guilabel>Macintosh keyboard</guilabel> the list +of modifiers will change.</para> + +<para>If you have enabled the &Mac; keyboard, you can further enable +<guilabel>MacOS-style modifier usage</guilabel>, to make &kde; behave +more like &MacOS;.</para><!-- FIXME: well, that's rather non-explanatory, more here would be good --> + +<para>Finally, you can change what a keypress sends to the &X-Server; +in the <guilabel>X Modifier Mapping</guilabel> section. A common +example is to reconfigure the <keycap>Caps Lock</keycap> key, which is +rarely used, to be another &Ctrl; key. This is especially nice if you +are a touch typist, as <keycap>Caps Lock</keycap> is much easier to +reach than either of the &Ctrl; keys on a standard keyboard.</para> + +<!-- FIXME: what exactly is going on here... --> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/khtml/Makefile.am b/doc/kcontrol/khtml/Makefile.am new file mode 100644 index 000000000..c54c99e96 --- /dev/null +++ b/doc/kcontrol/khtml/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/khtml diff --git a/doc/kcontrol/khtml/index.docbook b/doc/kcontrol/khtml/index.docbook new file mode 100644 index 000000000..9f204f075 --- /dev/null +++ b/doc/kcontrol/khtml/index.docbook @@ -0,0 +1,352 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY nsplugins-kcontrol SYSTEM "nsplugin.docbook"> +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-12</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>konqueror</keyword> +<keyword>browsing</keyword> +</keywordset> + +</articleinfo> +<sect1 id="konq-browsing"> +<title>Browsing With &konqueror;</title> + +<para>The &konqueror; Browser module of &kcontrol; allows you to select +various options for the appearance and behavior of &konqueror;, the +integrated web browser of &kde;.</para> + +<sect2 id="kbrowse-html"> + +<title>Behavior</title> + +<para>The first option you can enable on this page is <guilabel>Enable +completion of forms</guilabel>. If you check this box, &konqueror; will +try to remember what you answer to form questions, and will try to fill +in forms for you with the answers you previously used.</para> + +<para>You can configure the number of form items &konqueror; remembers +with the slider below labelled <guilabel>Maximum +completions</guilabel></para> + +<note><para>Of course, anything &konqueror; fills in a form with, you +can still edit before submitting the form!</para></note> + +<para>The next option is <guilabel>Change cursor over +links</guilabel>. If this option is selected, the shape of the cursor +will change (usually to a hand) whenever it moves over a +hyperlink. This makes it easy to identify links, especially when they +are in the form of images.</para> + +<para>&konqueror; defaults to a single window per page, but has the +capability to open multiple <firstterm>tabs</firstterm> inside a +single window. &konqueror; also, by default, has a &MMB; shortcut to +open any link in a new window. If you enable <guilabel>Open links in +new tab instead of in new window</guilabel> you can &MMB; click on a +link to have it open in a new tab.</para> + +<para>If you are using tabbed browsing, you can choose if a newly +opened tab becomes the active (<quote>front</quote>) tab, or goes to +the back. On a slow internet connection, or while browsing a page +that has a list of headlines or other links in a list, you may like to +have the new tabs load in the background while you continue reading. +In this case, leave this setting disabled. If you prefer to go +straight to the new page, leaving the old one in the background to +return to later, enable it.</para> + +<para>If you close a window in &konqueror; that has multiple tabs +open, &konqueror; will ask you if you're sure that you meant to close +it. You can toggle on and off this behavior with the +<guilabel>Confirm when closing windows with multiple tabs</guilabel> +checkbox.</para> + +<para>As a convenience feature, if you enable <guilabel>Right click +goes back in history</guilabel>, then clicking an empty area (&ie; not +a link) in the &konqueror; window will act as if you pressed the +<guiicon>Back</guiicon> button on the toolbar.</para> + +<para>The checkbox labeled <guilabel>Automatically load +images</guilabel>, allows you to control whether images on web pages are +loaded by default. Unless you have a very slow connection, you will +probably want to leave this option selected, as there are many web pages +that are difficult to use without images. If you don't select the option +to automatically load images, you can still view the text on the page, +and then load the images if you need them.</para> + +<para>Enabling <guilabel>Allow automatic delayed +reloading/redirecting</guilabel> allows websites to send you to +another page without your interaction. In many cases, this is a +convenience. For example, the website has moved to a new +<acronym>URL</acronym>. Many webmasters in this situation will put up +a page on the old site, telling you that it has moved and you may like +to change your bookmark, and then automatically move you along to the +new website. However, such features can be confusing, or annoying, +when misused, and so you may wish to disable it.</para> + +<para>The next setting is <guilabel>Underline links:</guilabel>. You can +choose to underline links <guilabel>Always</guilabel>. If this option +is selected, any text on web pages that acts as a link will be shown in +an underlined font. While many web pages do use color to distinguish +text that acts as a link, underlining makes it very easy to spot +links.</para> + +<para>If you don't like underlined links, you can choose +<guilabel>Never</guilabel>, so that no links are underlined. Or you +can choose a middle ground, <guilabel>Hover</guilabel>, so that links +are underlined when the mouse cursor is resting over them, and not +underlined the rest of the time.</para> + +<para>Many web pages use animated gif images, and these can be very +annoying, and in some cases, quite a drain on your system resources. +The <guilabel>Animations</guilabel> option lets you choose when +animations are enabled. The default is enabled, but you can set this +to disabled, or to run the animation only once, even if the file +itself contains instructions that the animation should run more times, +or continuously.</para> + +</sect2> + +<sect2 id="kbrowse-appearance"> + +<title>Fonts</title> + +<para>Under this tab, you can select various options related to the use +of fonts. Although the shapes and sizes of fonts are often part of the +design of a web page, you can select some default settings for +&konqueror; to use.</para> + +<para>The first thing you can set here is the font size. There are two +settings which work together to allow you a comfortable browsing +experience.</para> + +<para>Firstly, you can set a <guilabel>Minimum Font Size</guilabel>. +This means, even if the font size is set specifically in the page you +are viewing, &konqueror; will ignore that instruction and never show +smaller fonts than you set here.</para> + +<para>Next you can set a <guilabel>Medium Font Size</guilabel>. This is +not only the default size of text, used when the page doesn't specify +sizes, but it is also used as the base size that relative font sizes are +calculated against. That is, the <acronym>HTML</acronym> instruction +<quote>smaller</quote>, it means smaller than the size you set for this +option.</para> + +<para>For either option, you can select the exact font size in points by +using the up/down spin control (or just typing) next to the option +label.</para> + +<para>These options are independent of each other. Pages that do not +set a font size, or ask for the default, will display with the size +you set from <guilabel>Medium Font Size</guilabel>, while any pages +that ask for a size smaller than your <guilabel>Minimum Font +Size</guilabel> setting will instead show that size. The one does not +affect the other.</para> + +<para>The remaining options are for the fonts to be associated with +different types of markup used in <acronym>HTML</acronym> pages. Note +that many web pages may override these settings. If you click anywhere +on a control which shows a font name, a list of font names appears, and +you can select a different font if you like. (If there are a lot of +fonts, a vertical scrollbar appears in the list to allow you to scroll +through all of the fonts.)</para> +<!-- +<para>You can set a font for each <quote>type</quote> of markup, for +each <guilabel>Charset</guilabel>, by changing the character set in the +first drop down box, and then selecting a font for each category below. +This would take quite some time, so you may just want to set up the +fonts for your default character set. Most English speaking users will +use iso8859-1</para> +--> +<para>Below this, you can set a <guilabel>Font size adjustment for this +encoding</guilabel>. Sometimes the fonts you want to use for a +particular encoding or language are much larger or smaller than average, +so you can use this setting to bring them into line.</para> + +<para>You can set a default encoding that &konqueror; should assume +pages are when rendering them. The default setting is <guilabel>Use +language encoding</guilabel>, but you can change it to any encoding +available in the list.</para> + +</sect2> + +<sect2 id="kbrowse-java"> +<title>&Java; and JavaScript</title> + +<para>&Java; allows applications to be downloaded and run by a web +browser, provided you have the necessary software installed on your +machine. Many web sites make use of &Java; (for example, online +banking services or interactive gaming sites). You should be aware +that running programs from unknown sources could pose a threat to the +security of your computer, even if the potential extent of the damage +is not great.</para> + +<para>The checkboxes under <guilabel>Global Settings</guilabel> allows +you to turn &Java; support on for all web sites by default. You can +also select to turn &Java; on or off for specific hosts. To add a +policy for a specific host, click the <guilabel>Add...</guilabel> +button to bring up a dialog in which you can type the host name and +then choose to accept or reject &Java; code from that particular host, +which will add the domain to the list on the left of the page.</para> + +<para>You can select a host in the list, and click the +<guilabel>Change...</guilabel> button to choose a different policy for +that host. Clicking the <guilabel>Delete</guilabel> button removes the +policy for the selected host; after deletion, the global settings will +then apply to that host. You can import policies from a file by clicking +the <guilabel>Import...</guilabel> button. To save the current list to a +compressed archive file, click the <guilabel>Export...</guilabel> +button.</para> + +<para>Finally, the group of controls labeled <guilabel>Java Runtime +Settings</guilabel> allows you to set some options for the way in +which &Java; should run. These options are useful for diagnosing +problems, or if you are a &Java; developer, and should not normally +need adjusting.</para> + +<para>If you select the <guilabel>Show Java +Console</guilabel> option, &konqueror; will open a console window from +which &Java; applications can read and write text. While most &Java; +applications will not require such a console, it could be helpful in +diagnosing problems with &Java; applications.</para> + +<para><guilabel>Use KIO</guilabel> will cause the +<acronym>JVM</acronym>to use &kde;'s own <acronym>KIO</acronym> +transports for network connections.</para> + +<para><guilabel>Use security +manager</guilabel> is normally enabled by default. This setting will +cause the <acronym>JVM</acronym> to run with a Security Manager in place. This will keep +applets from being able to read and write to your file system, creating +arbitrary sockets, and other actions which could be used to compromise +your system. Disable this option at your own risk. You can modify your <filename>$<envar>HOME</envar>/.java.policy</filename> file with the +&Java; policytool utility to give code downloaded from certain sites +more permissions.</para> + +<para>The <guilabel>Shutdown Applet Server when inactive</guilabel> +checkbox allows you to save resources by closing the &Java; Applet +Server when it is not in use, rather than leaving it running in the +background. Leaving this disabled may make &Java; applets start up +faster, but it will use system resources when you are not using a +&Java; applet. If you enable this, you can set a timeout.</para> + +<para>You can either opt to have &konqueror; automatically detect the +&Java; installation on your system, or specify the path to the +installation yourself by selecting <guilabel>Use user-specified +Java</guilabel>. You may want to choose the latter method, for +instance, if you have multiple &Java; installations on your system, +and want to specify which one to use. If the &Java; Virtual Machine +you are using requires any special startup options, you can type them +in the text box labeled <guilabel>Additional Java +Arguments</guilabel>.</para> + +</sect2> + +<sect2 id="kbrowse-javascript"> +<title>JavaScript</title> + +<para>Despite the name, JavaScript is not related at all to +&Java;.</para> + +<para>The first part of this page works the same as the &Java; page +settings.</para> + +<para>The checkboxes under <guilabel>Global Settings</guilabel> allow +you to turn JavaScript support on for all web sites by default. You +can also select to turn JavaScript on or off for specific hosts. To +add a policy for a specific host, click the +<guilabel>Add...</guilabel> button to bring up a dialog in which you +can type the host name and then choose to accept or reject JavaScript +code from that particular host, which will add the domain to the list +on the left of the page.</para> + +<para>You can select a host in the list, and click the +<guilabel>Change...</guilabel> button to choose a different policy for +that host. Clicking the <guilabel>Delete</guilabel> button removes the +policy for the selected host; after deletion, the global settings will +then apply to that host. You can import policies from a file by +clicking the <guilabel>Import...</guilabel> button. To save the +current list to a compressed archive file, click the +<guilabel>Export...</guilabel> button.</para> + +<para>The final set of options on this page determine what happens +when a page uses JavaScript for specific actions.</para> + +<para>You can individually enable or disable the ability of JavaScript +to manipulate your windows by moving, resizing or changing focus. You +can also disable JavaScript from changing the status bar text, so that +for instance, you can always see where links will take you when +clicked.The choices for these options are <guilabel>Allow</guilabel> and +<guilabel>Ignore</guilabel>.</para> + +<para>For opening a new window, there is even more control. You can +set &konqueror; to <guilabel>Allow</guilabel> all such requests, +<guilabel>Ask</guilabel> each time a request is made, or +<guilabel>Deny</guilabel> all popup requests.</para> + +<para>The <guilabel>Smart</guilabel> setting will only allow +JavaScript popup windows when you have explicitly chosen a link that +creates one.</para> + +</sect2> + +<sect2 id="khtml-adblock"> +<title>AdBlocK</title> + +<para>&konqueror; AdBlocK can be configured to replace or remove +images or frames from web pages that match a series of filters.</para> + +<para>The setting <guilabel>Enable filters</guilabel> enables or +disables the use of list of URL filters.</para> +<para>If <guilabel>Hide filtered images</guilabel> is enabled then +blocked images are completely removed from the page and the space they +occupied is reclaimed. If the option is disabled then a placeholder +image is used in place of filtered images.</para> + +<para><guilabel>URL expressions to filter</guilabel> is a list of +URLs that will be compared against image and frame names to decide +on fitlering actions. The wildcards can be given as filename style +regular expressions.</para> + +<para>Each filter can either be expressed as a file style wildcard +string (e.g. http://www.site.com/ads/*) or as a full regular expression +by enclosing the filter with forward slashes (e.g. //(ads|dclk)\./).</para> + +<para>Import and export will save or read the current filter list to a +plain text file. Lines prefixed with an exclamation mark (!) are treated +as comments and can be used to clarify or label a set of filters.</para> +</sect2> + +<sect2 id="kbrowse-plugins"> +<title>Plugins</title> + +<para>The first setting here is <guilabel>Enable Plugins +globally</guilabel>. If you disable this checkbox, then &konqueror; +will not use any plugins. If you enable it, then any installed and +configured plugins that it can find will be used by &konqueror;</para> + +<para>You can also restrict &konqueror; to <guilabel>Only allow HTTP +and HTTPS URLs for plugins</guilabel> by checking the box.</para> + +</sect2> + +&nsplugins-kcontrol; + +</sect1> + +</article> diff --git a/doc/kcontrol/khtml/nsplugin.docbook b/doc/kcontrol/khtml/nsplugin.docbook new file mode 100644 index 000000000..1f8547461 --- /dev/null +++ b/doc/kcontrol/khtml/nsplugin.docbook @@ -0,0 +1,91 @@ +<sect2 id="nsplugins"> +<title>&Netscape; Plugins</title> + +<sect3 id="nsplugins-intro"> +<title>Introduction</title> + +<para>As &Netscape;'s <application>Navigator</application> has been a +web browsing standard for many years, so-called &Netscape; plugins have +appeared that allow rich web content. Using those plugins, web sites +can contain <acronym>PDF</acronym> files, flash animations, video, &etc; +With &konqueror;, you can still use these plugins to take advantage of +rich web content.</para> + +<note><para>&Netscape; plugins should not be confused with &konqueror; +plugins. The latter ones specifically extend &konqueror;'s +functionality; they are normally not used to display rich web +content.</para></note> + +</sect3> + +<sect3 id="nsplugins-scan"> +<title>Scan</title> + +<para>&konqueror; has to know where your &Netscape; plugins are +installed. This can be in several places, &ie; you might have +system-wide plugins in <filename +class="directory">/opt/netscape/plugins</filename> and your personal +plugins in <filename +class="directory">$<envar>HOME</envar>/.netscape/plugins</filename>. +However, &konqueror; will not automatically use the installed plugins: +it first has to scan a list of folders. You can initiate the scan +by clicking <guibutton>Scan for new plugins</guibutton>. Alternatively, +you can enable <guilabel>Scan for new plugins at &kde; startup</guilabel> +so &konqueror; will scan the appropriate folders every time &kde; +starts up, to see whether new plugins have been installed.</para> + +<note><para>Enabling <guilabel>Scan for new plugins at &kde; +startup</guilabel> can considerably slow down the startup procedure, +and is known to give difficulty on certain installations. Turn this +option off if you experience problems.</para></note> + +<para>To find plugins, &konqueror; will look in the folders +specified in the <guilabel>Scan Folders</guilabel> frame. When you +use this control module for the first time, this list will already be +filled with reasonable paths that should work on most operating systems. +If you need to provide a new path, click the <guibutton>New</guibutton> +button; then you can either enter the new path in the text edit box to +the left, or choose a folder using the file dialog by clicking the +<guibutton>New...</guibutton> button. As scanning the folders can take +a little time, you might want to remove folders from the list where +you know that no plugins are installed: do this by selecting a folder +and clicking <guibutton>Remove</guibutton>. Using the +<guibutton>Up</guibutton> and <guibutton>Down</guibutton> buttons you +can change the order in which folders will be scanned by moving the +selected folder up or down.</para> + +<para>As usual, click <guibutton>Apply</guibutton> to save your changes +permanently.</para> + +</sect3> + +<sect3 id="nsplugins-plugins"> +<title>Plugins</title> + +<para>In this tab, you can see a list of the &Netscape; plugins found by +&konqueror;, displayed as a tree. Double click on a plugin to fold it +out and you'll see that the different mime types this plugin can handle +will be displayed as branches. Fold out a mime type to see its +info.</para> + +<para>This tab is mostly for informational purposes. The only +configurable option is <guilabel>Use artsdsp to pipe plugin sound +through aRts</guilabel>, which is enabled by default. Disable this if +you wish plugins to use their own method for sounds, and you have +configured &arts; in such a way that third-party applications can do +so (for example, by having it exit when idle, or by having it use a +custom sound device on modern soundcards which allow this.)</para> + +</sect3> + +<sect3 id="nsplugins-author"> +<title>Section Author</title> + +<para>This section written by: Jost Schenck +<email>[email protected]</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +</sect3> + +</sect2> diff --git a/doc/kcontrol/kwindecoration/Makefile.am b/doc/kcontrol/kwindecoration/Makefile.am new file mode 100644 index 000000000..ad89ecd92 --- /dev/null +++ b/doc/kcontrol/kwindecoration/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/kwindecoration diff --git a/doc/kcontrol/kwindecoration/index.docbook b/doc/kcontrol/kwindecoration/index.docbook new file mode 100644 index 000000000..c6bfd5276 --- /dev/null +++ b/doc/kcontrol/kwindecoration/index.docbook @@ -0,0 +1,98 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Rik.Hemsley; &Rik.Hemsley.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-09-28</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>kwin</keyword> +<keyword>window</keyword> +<keyword>border</keyword> +<keyword>theme</keyword> +<keyword>style</keyword> +</keywordset> +</articleinfo> +<sect1 id="window-deco"> +<title>Window Decoration</title> + +<sect2> +<title>General</title> + +<para>This module allows you to select a style for the borders around +windows.</para> + +<para>Each style has a different look, but also a different +<quote>feel</quote>. Some have (sometimes invisible) +<quote>resize</quote> borders all around the edge, which make resizing +easier but moving more difficult. Some have no borders on certain +edges. One (<quote>BII</quote>) even has a dynamically sized and +positioned title element.</para> + +<para>You are encouraged to experiment with the different styles until +you find one which best suits your pattern of work.</para> + +<para>Choose a window decoration style from the drop down box at the +top of the screen to see a preview of it in the lower pane.</para> + +<para>If there are any configurable options for the theme you chose on +the first page, they will become available below the preview...</para> + +<!-- +<para>In particular, if you chose to use the IceWM theme, you can choose +here which of the many IceWM themes to use. The IceWM theme has +instructions on the page as to where you should copy the theme files, +and once this is done, you can simply select the theme you want to +use.</para> +--> + +</sect2> + +<sect2> +<title>Buttons</title> + +<para>This page has instructions directly on it - just drag around the +buttons until you have the order that makes you comfortable.</para> + +<note> +<para>Not all the window decorations are able to comply with your custom +set button order. The ones that cannot are being converted, but at the +time of this release they have not been all been changed.</para> +</note> + +<para>Apart from choosing the window decoration itself, you can choose +here two further options: If there should be a tooltip while you hover +your mouse over a window decoration button, and if the window +decoration should attempt to use a custom set button order.</para> + +<tip> +<para>The tooltips can be quite useful if you have set a custom button +order, and then changed to an unfamiliar window decoration.</para> +</tip> + +<tip> +<para>For accessibility purposes, some window decorations support +extra wide borders. If this is available, you can also choose a +border size here. These large borders are easier to see for low +vision users, and easier to grab for people with limited mobility or +difficulty using a mouse.</para> +</tip> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/language/Makefile.am b/doc/kcontrol/language/Makefile.am new file mode 100644 index 000000000..ab4abf365 --- /dev/null +++ b/doc/kcontrol/language/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/language diff --git a/doc/kcontrol/language/index.docbook b/doc/kcontrol/language/index.docbook new file mode 100644 index 000000000..c93c16190 --- /dev/null +++ b/doc/kcontrol/language/index.docbook @@ -0,0 +1,218 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<sect1 id="locale"> + +<sect1info> +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> + </authorgroup> + + <date>2003-10-14</date> + <releaseinfo>3.2</releaseinfo> + + <keywordset> + <keyword>KDE</keyword> + <keyword>KControl</keyword> + <keyword>locale</keyword> + <keyword>country</keyword> + <keyword>language</keyword> + </keywordset> + + </sect1info> + + +<title>Country and Language</title> + +<para>This module of the &kde; control center allows you select +customization options that depend on the region of the world that you +happen to live in. There are five different pages in this module, each +of which is described in detail in the following sections.</para> + +<para>In most cases, you can simply select the country you live in, and +the other options will be set in an appropriate manner.</para> + +<para>Below the pages of this module, you can see a preview of what the +settings look like. In addition to positive and negative numbers, you +can see how positive and negative currency values, long and short dates, +and times are displayed. When you change any of the settings, the +preview shows the effects of the changes before you apply them.</para> + +<sect2 id="locale-locale"> +<title>Locale</title> + +<para>On this page, there are two lists, from which you can +select the country and languages that you want +to use.</para> + +<para>When you click on the <guilabel>Country</guilabel> list, +a menu pops up showing major groups of countries. You can select +one of these regions and see a list of the countries that are +available for that region.</para> + +<para>If the language for the country you have selected is available on your +system, it will be selected automatically. For instance, choosing +<guilabel>Germany</guilabel> as the country will select +<guilabel>German</guilabel> as the language, if it is available.</para> + +</sect2> + +<sect2 id="locale-numbers"> +<title>Numbers</title> + +<para>On this page, you can select options for how numbers are +displayed. The defaults are selected automatically based on the country +which is currently selected.</para> + +<para>In the text box labeled <guilabel>Decimal symbol</guilabel>, you +can type the character that you want to use to separate the decimal +portion of numbers. You could put anything here you wanted to, but +really, <userinput>.</userinput> and <userinput>,</userinput> are the +two characters that make the most sense.</para> + +<para>Similarly, you can choose the character which is used to group +units of thousands in numbers. If no character, not even a space, is +present, then there will be no separator for thousands.</para> + +<para>Finally, you can choose what character should be prefixed to +positive and negative numbers respectively. For example, the default +for English is not to have any prefix for positive numbers, and a +<userinput>-</userinput> for negative numbers.</para> + +</sect2> + +<sect2 id="locale-money"> + +<title>Money</title> + +<para>Unlike the display of ordinary numbers, conventions for +currency values do vary from region to region. However, you will +find that the defaults are probably fine.</para> + +<para>The character or characters representing the currency symbol +are based on the country that is currently selected. The decimal +symbol and thousands separator work as they do for numbers. The +text box labeled <guilabel>Fract digits</guilabel> allows you +to specify the number of fractional digits used in displaying +currency values.</para> + +<para>For both positive and negative currency values, you can +control whether the currency symbol appears before or after the +numeric value, and how the sign of the value is distinguished +in the display. Note that the symbols used for the sign of +currency values are the same as those used for other numeric +values.</para> + +<para>If the checkbox labeled <guilabel>Prefix currency +symbol</guilabel> is selected, the currency symbol appears +before the numeric value. If this checkbox is cleared, then the +currency symbol appears after the numeric value.</para> + +<para>There are five choices for the way in which the sign of the +currency value is handled:</para> +<itemizedlist> +<listitem><para>The <guilabel>Parens around</guilabel> +option displays the numeric value within a pair of +parentheses.</para></listitem> +<listitem><para>The <guilabel>Before quantity money</guilabel> +option displays the sign before the numeric value, but after any +currency symbol that may be present.</para></listitem> +<listitem><para>The <guilabel>After quantity money</guilabel> +option displays the sign after the numeric value, but before any +currency symbol that may be present.</para></listitem> +<listitem><para>The <guilabel>Before money</guilabel> option +displays the sign before the numeric value as well as any +currency symbol that may be present.</para></listitem> +<listitem><para>The <guilabel>After money</guilabel> option +displays the sign after the numeric value as well as any +currency symbol that may be present.</para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="locale-datetime"> +<title>Time and Dates</title> + +<para>If you use a different calendar system than Gregorian, you can +choose this from the first dropdown box.</para> + +<para>On the rest of this page, there are text boxes for the time, long +date, and short date, in which you can type format strings to control +the way in which times and dates are displayed.</para> + +<para>Except for the special codes described below, any other characters in the +format strings are displayed literally. The special codes consist of a +<parameter>%</parameter> sign followed by a character, as shown in the list of +codes below:</para> + +<itemizedlist> +<listitem><para>Time format codes:</para> + <itemizedlist> + + <listitem><para><parameter>HH</parameter> - The hour according to a 24-hour + clock, using two digits (00 to 23).</para></listitem> + <listitem><para><parameter>hH</parameter> - The hour according to a 24-hour + clock, using one or two digits (0 to 23).</para></listitem> + <listitem><para><parameter>PH</parameter> (uppercase <quote>p</quote>) - The hour according + to a 12-hour clock, using two digits (01 to 12).</para></listitem> + <listitem><para><parameter>pH</parameter> (lowercase <quote>p</quote>) - The hour according + to a 12-hour clock, using one or two digits (1 to 12).</para></listitem> + <listitem><para><parameter>MM</parameter> - The current minute using two digits + (00 to 59).</para></listitem> + <listitem><para><parameter>SS</parameter> - The current second using two digits + (00 to 59).</para></listitem> + <listitem><para><parameter>AMPM</parameter> - Either <quote>am</quote> or <quote>pm</quote> depending on the hour. + Useful with <parameter>PH</parameter> or + <parameter>pH</parameter>.</para></listitem> + </itemizedlist> +</listitem> + +<listitem><para>Date format codes:</para> + <itemizedlist> + <listitem><para><parameter>YYYY</parameter> - The year, using 4 + digits.</para></listitem> + <listitem><para><parameter>YY</parameter> - The year, using 2 + digits.</para></listitem> + <listitem><para><parameter>MM</parameter> - The month, using 2 digits (01 to + 12).</para></listitem> + <listitem><para><parameter>mM</parameter> - The month, using 1 or 2 digits (1 + to 12).</para></listitem> + <listitem><para><parameter>MONTH</parameter> - The name of the + month.</para></listitem> + <listitem><para><parameter>SHORTMONTH</parameter> - The abbreviated name of the + month.</para></listitem> + <listitem><para><parameter>DD</parameter> - The day, using 2 digits (01 to + 31).</para></listitem> + <listitem><para><parameter>dD</parameter> - The day, using 1 or 2 digits (1 to + 31).</para></listitem> + <listitem><para><parameter>WEEKDAY</parameter> - The name of the + weekday.</para></listitem> + <listitem><para><parameter>SHORTWEEKDAY</parameter> - The abbreviated name of the + weekday.</para></listitem> + </itemizedlist> +</listitem> +</itemizedlist> + +<para>Finally, there's a combobox labeled <guilabel>First day +of the week</guilabel> which lets you select which day is the first +one of the week in your country.</para> + +</sect2> +<sect2 id="locale-other"> +<title>Other</title> +<para>You can select the default paper format with the combo box labeled <guilabel>Paper Format</guilabel>.</para> + +<para>Use the drop down box labeled <guilabel>Measure system</guilabel> to select Imperial or +Metric systems of measurement.</para> + +</sect2> + +</sect1> +</article> diff --git a/doc/kcontrol/mouse/Makefile.am b/doc/kcontrol/mouse/Makefile.am new file mode 100644 index 000000000..b0a8d6b17 --- /dev/null +++ b/doc/kcontrol/mouse/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/mouse diff --git a/doc/kcontrol/mouse/index.docbook b/doc/kcontrol/mouse/index.docbook new file mode 100644 index 000000000..62d223de1 --- /dev/null +++ b/doc/kcontrol/mouse/index.docbook @@ -0,0 +1,493 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Brad.Hards; &Brad.Hards.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2004-10-09</date> +<releaseinfo>3.03.00</releaseinfo> + +<abstract> +<para>This is the documentation for the &kde; &kcontrol; module that configures mice and other pointing devices. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>mouse</keyword> +</keywordset> +</articleinfo> + +<sect1 id="mouse"> +<title>Mouse</title> + +<para>This module allows you to configure your pointing device. Your +pointing device may be a mouse, a track ball, a touch-pad, or another piece +of hardware that performs a similar function.</para> + +<para>This module is divided into several tabs: +<link linkend="mouse-general">General</link>, +<link linkend="cursor-theme">Cursor Theme</link>, +<link linkend="mouse-advanced">Advanced</link> and +<link linkend="mouse-navigation">Mouse Navigation</link>. +There may also be one or more additional tabs if you have a Logitech mouse +or trackball, providing access to special features. +</para> + +<sect2 id="mouse-general"> +<title><guilabel>General</guilabel></title> + +<variablelist> +<varlistentry> +<term><guilabel>Button Order</guilabel></term> +<listitem><para> +If you are left-handed, you may +prefer to swap the functions of the <mousebutton>left</mousebutton> and +<mousebutton>right</mousebutton> buttons on your pointing device by choosing the +<quote>Left handed</quote> option. If your pointing device has more than two +buttons, only those that function as the <mousebutton>left</mousebutton> and +<mousebutton>right</mousebutton> buttons are affected. For example, if you have +a three-button mouse, the <mousebutton>middle</mousebutton> button is +unaffected.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Reverse scroll direction</guilabel></term> +<listitem><para> +With this checkbox selected, the scroll wheel (if any) will work in the opposite direction (so that if rolling the top of the scroll wheel towards you previously causes a scroll down, then it will now cause a scroll up). This may be useful to handle a unusual setup of the X server. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Double-click to open files and folders (select icons on first click)</guilabel></term> +<listitem> +<para> If this option is not checked, icons/files will be opened with a +single click of the <mousebutton>left</mousebutton> mouse-button. This +default behavior is consistent with what you would expect when you click +links in most web browsers. If checked however, icons/files will be +opened with a double click, while a single click will only select the +icon or file. This is the behavior you may know from other desktops or +operating systems.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Single-click to open files and folders</guilabel></term> +<listitem> +<para>This is the default setting for &kde;. Clicking once on an icon +will open it. To select you can drag around the icon(s) or <keycombo +action="simul">&Ctrl;<mousebutton>Right</mousebutton></keycombo> click, +or simply click and hold to drag it. You can also enable automatic selection of icons using the <guilabel>Automatically select icons</guilabel> checkbox, discussed below.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Change pointer shape over icons</guilabel></term> +<listitem> +<para>When this option is checked, the shape of the mouse pointer +changes whenever it is over an icon.</para> + +<tip><para>This option should be checked in most situations. It gives +more visual feedback and says, in essence, if you click here, something +will happen.</para></tip> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Automatically select icons</guilabel></term> +<listitem> +<para> +As noted above, if you have <guilabel>Single-click to open files and folders</guilabel> selected, you can select icons by dragging around them, or by using <keycombo +action="simul">&Ctrl;<mousebutton>Right</mousebutton></keycombo> click. If you routinely need to select icons, you may want to enable this checkbox, which will allow icons to be selected automatically by pausing over the icon. The <guilabel>Delay:</guilabel> slider determines how long is required before the automatic selection takes effect. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Visual feedback on activation</guilabel></term> +<listitem> +<para>When this option is +checked, &kde; gives you visual feedback whenever you click on something and activate it.</para></listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="cursor-theme"> +<title><guilabel>Cursor Theme</guilabel></title> + +<para> +This tab allows you to select from a number of cursor themes. A preview of the cursor display is shown above the listbox. +</para> + +<note><para>The features provided by this tab may not be available on some systems. Your system may need to be updated to support cursor themes. +</para></note> + +<para> +If you have additional cursor themes available to you, you can install and remove them using the buttons below the listbox. Note that you cannot remove the default themes. +</para> + +</sect2> + +<sect2 id="mouse-advanced"> +<title>Advanced</title> + +<variablelist> +<varlistentry> +<term id="peripherals-mouse-acceleration"> +<guilabel>Pointer acceleration</guilabel></term> +<listitem> +<para>This option allows you to change the relationship +between the distance that the mouse pointer moves on the +screen and the relative movement of the physical device +itself (which may be a mouse, track-ball, or some other +pointing device.)</para> + +<para>A high value for the acceleration multiplier will lead to large +movements of the mouse pointer on the screen, even when +you only make a small movement with the physical device.</para> + +<tip><para>A multiplier between <guilabel>1x</guilabel> and +<guilabel>3x</guilabel> will works well for many systems. With a multiplier +over <guilabel>3x</guilabel> the mouse pointer may become difficult to +control.</para></tip> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Pointer threshold</guilabel></term> +<listitem> +<para>The threshold is the smallest distance that the mouse pointer must +move on the screen before acceleration has any effect. If the movement +is within the threshold, the mouse pointer moves as if the acceleration +were set to <guilabel>1x</guilabel>.</para> + +<para>Thus, when you make small movements with the physical device (⪚ +mouse), you still have fine control of the mouse pointer on the screen, +whereas larger movements of the physical device will move the mouse +pointer rapidly to different areas on the screen.</para> + +<para>You can set the threshold value by dragging the slider button or +by clicking the up/down arrows on the spin-button to the left of the +slider.</para> + +<tip><para>In general, the higher you set the <guilabel>Pointer +acceleration</guilabel> value, the higher you will want to set the +<guilabel>Pointer threshold</guilabel> value. For example, A +<guilabel>Pointer threshold</guilabel> of 4 pixels may +be appropriate for a <guilabel>Pointer Acceleration</guilabel> of +2x, but 10 pixels might be +better for 3x.</para></tip> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Double click interval</guilabel></term> +<listitem> +<para>This is the maximum amount of time between clicks for &kde; to +register a double click. If you click twice, and the time between those +two clicks is less than this number, &kde; recognizes that as a double +click. If the time between these two clicks is greater than this +number, &kde; recognizes those as two <emphasis>separate</emphasis> +single clicks.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Drag start time</guilabel> and <guilabel>Drag start +distance</guilabel></term> + +<listitem> +<para>If you +<itemizedlist> +<listitem><para>click with the mouse</para></listitem> +<listitem><para>drag within the time specified in <guilabel>Drag start +time</guilabel>, and </para></listitem> +<listitem><para>move a distance equal to or greater than the number (of +pixels) specified in <guilabel>Drag start distance</guilabel></para> +</listitem> +</itemizedlist> + +&kde; will drag the selected item.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mouse wheel scrolls by</guilabel></term> +<listitem> +<para>If you have a wheel mouse, use the slider to determine how many +lines of text one <quote>step</quote> of the mouse wheel will +scroll.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="mouse-navigation"> +<title><guilabel>Mouse Navigation</guilabel></title> + +<para> +This tab allows you to configure the keyboard number pad keys as a mouse-type device. This may be useful when you are working on a device without another pointing device, or where you have no other use for the number pad. +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Move pointer with keyboard (using the num pad)</guilabel></term> +<listitem> +<para> +To enable keyboard mouse mode, you need to select the checkbox labelled <guilabel>Move pointer with keyboard (using the num pad)</guilabel>. When you do this, the other settings will become enabled, and you can customize the keyboard pointer behavior further, if required. +</para> +<para> +The various keys on the number pad move in the direction you would expect. Note that you can move diagonally as well as up, down, left and right. The <keycap>5</keycap> key emulates a click to a pointer button, typically &LMB;. You change which button is emulated by using the <keycap>/</keycap> key (which makes it &LMB;), <keycap>*</keycap> key (which makes it &MMB;) and <keycap>-</keycap> (which makes it &RMB;). Using the <keycap>+</keycap> emulates a doubleclick to the selected pointer button. You can use the <keycap>0</keycap> key to emulate holding down the selected pointer button (for easy dragging), and then use the <keycap>.</keycap> to emulate releasing the selected pointer button. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Acceleration delay</guilabel></term> +<listitem> +<para> +This is the time (in milliseconds) between the initial key press and the first repeated motion event for mouse key acceleration. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Repeat interval</guilabel></term> +<listitem> +<para> +This is the time in milliseconds between repeated motion events for mouse key acceleration. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Acceleration time</guilabel></term> +<listitem> +<para> +This is the number of key events before the pointer reaches a maximum speed for mouse key acceleration. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Maximum speed</guilabel></term> +<listitem> +<para> +This is the maximum speed in pixels per key event the pointer can reach for mouse key acceleration. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Acceleration profile</guilabel></term> +<listitem> +<para> +This is the slope of the acceleration curve for mouse key acceleration. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="logitech-mouse"> +<title><guilabel>Logitech Support</guilabel></title> + +<para> +Some Logitech USB mice support special features, such as switching to a higher resolution, or +providing cordless status. If KDE was built with libusb support, then you will get an additional +tab for each supported mouse that is plugged in. +</para> + +<para> +The supported devices are: +</para> +<orderedlist> +<listitem><para>Wheel Mouse Optical</para></listitem> +<listitem><para>MouseMan Traveler</para></listitem> +<listitem><para>MouseMan Dual Optical</para></listitem> +<listitem><para>MX310 Optical Mouse</para></listitem> +<listitem><para>MX510 Optical Mouse</para></listitem> +<listitem><para>MX300 Optical Mouse</para></listitem> +<listitem><para>MX500 Optical Mouse</para></listitem> +<listitem><para>iFeel Mouse</para></listitem> +<listitem><para>Mouse Receiver</para></listitem> +<listitem><para>Dual Receiver</para></listitem> +<listitem><para>Cordless Freedom Optical</para></listitem> +<listitem><para>Cordless Elite Duo</para></listitem> +<listitem><para>MX700 Optical Mouse</para></listitem> +<listitem><para>Cordless Optical Trackman</para></listitem> +<listitem><para>Cordless MX Duo Receiver</para></listitem> +<listitem><para>MX100 Laser Mouse</para></listitem> +<listitem><para>Receiver for Cordless Presenter</para></listitem> +</orderedlist> + +<para> +Not all devices support all capabilities (typically cordless devices do not +provide resolution switching, and of course only cordless devices support +cordless status reporting), so some parts of the tab will not be enabled for +some mouse types. +</para> + +<para> +If the mouse supports resolution switching, the <guilabel>Sensor Resolution</guilabel> +radio button group will be enabled, and you can switch from <guilabel>400 counts per +inch</guilabel> to <guilabel>800 counts per inch</guilabel> and back. If you use +<guilabel>800 counts per inch</guilabel>, the same physical movement of the mouse +will cause a greater (roughly double) amount of motion of the cursor. This tends +to be popular amongst gamers. +</para> + +<para> +If the mouse supports cordless reporting, the <guilabel>Battery Level</guilabel> +and <guilabel>RF Channel</guilabel> widgets will be enabled. You can only change +the <guilabel>RF Channel</guilabel> if your mouse has two channel support. +</para> + +<sect3 id="logitech-perms"> +<title>Fixing permission problems on Logitech mice</title> + +<para> +Because of the way USB devices work, the code that accesses the current +status on Logitech mice needs to be able to write to the mouse. This +should be handled by your distribution, but if not, you may need to do some +configuration yourself. +</para> + +<para> +On a Linux system, you should use the hotplug system to change the ownership +and permissions on the mouse entry in <filename>/proc/bus/usb</filename>. One +way to do this is to create a short script +(<filename>/etc/hotplug/usb/consoleUserPerms</filename>) that changes the ownership +and permissions, as shown below: +</para> + +<informalexample> +<programlisting> +<![CDATA[ +#!/bin/bash +# +# /etc/hotplug/usb/consoleUserPerms +# +# Sets up newly plugged in USB device so that the user who owns +# the console according to pam_console can access it from user space +# +# Note that for this script to work, you'll need all of the following: +# a) a line in the file /etc/hotplug/usb.usermap or another usermap file +# in /etc/hotplug/usb/ that corresponds to the device you are using. +# b) a setup using pam_console creates the respective lock files +# containing the name of the respective user. You can check for that +# by executing "echo `cat /var/{run,lock}/console.lock`" and +# verifying the appropriate user is mentioned somewhere there. +# c) a Linux kernel supporting hotplug and usbdevfs +# d) the hotplug package (http://linux-hotplug.sourceforge.net/) +# +# In the usermap file, the first field "usb module" should be named +# "consoleUserPerms" to invoke this script. +# + +if [ "${ACTION}" = "add" ] && [ -f "${DEVICE}" ] +then +# New code, using lock files instead of copying /dev/console permissions +# This also works with non-kdm logins (e.g. on a virtual terminal) +# Idea and code from Nalin Dahyabhai <[email protected]> + if [ -f /var/run/console.lock ] + then + CONSOLEOWNER=`cat /var/run/console.lock` + elif [ -f /var/lock/console.lock ] + then + CONSOLEOWNER=`cat /var/lock/console.lock` + else + CONSOLEOWNER= + fi + if [ -n "$CONSOLEOWNER" ] + then + chmod 0000 "${DEVICE}" + chown "$CONSOLEOWNER" "${DEVICE}" + chmod 0600 "${DEVICE}" + fi +fi +]]> +</programlisting> +</informalexample> + +<para> +The usermap file that goes with this is +<filename>/etc/hotplug/usb/logitechmouse.usermap</filename>, as +shown below: +</para> + +<informalexample> +<programlisting> +<![CDATA[ +# script match_flags idVendor idProduct bcdDevice_lo bcdDevice_hi bDeviceClass bDeviceSubClass bDeviceProtocol bInterfaceClass bInterfaceSubClass bInterfaceProtocol driver_info +# Wheel Mouse Optical +consoleUserPerms 0x0003 0x046d 0xc00e 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MouseMan Traveler +consoleUserPerms 0x0003 0x046d 0xc00f 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MouseMan Dual Optical +consoleUserPerms 0x0003 0x046d 0xc012 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MX310 Optical Mouse +consoleUserPerms 0x0003 0x046d 0xc01b 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MX510 Optical Mouse +consoleUserPerms 0x0003 0x046d 0xc01d 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MX300 Optical Mouse +consoleUserPerms 0x0003 0x046d 0xc024 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MX500 Optical Mouse +consoleUserPerms 0x0003 0x046d 0xc025 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# iFeel Mouse +consoleUserPerms 0x0003 0x046d 0xc031 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# Mouse Receiver +consoleUserPerms 0x0003 0x046d 0xc501 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# Dual Receiver +consoleUserPerms 0x0003 0x046d 0xc502 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# Cordless Freedom Optical +consoleUserPerms 0x0003 0x046d 0xc504 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# Cordless Elite Duo +consoleUserPerms 0x0003 0x046d 0xc505 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MX700 Optical Mouse +consoleUserPerms 0x0003 0x046d 0xc506 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# Cordless Optical Trackman +consoleUserPerms 0x0003 0x046d 0xc508 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# Cordless MX Duo Receiver +consoleUserPerms 0x0003 0x046d 0xc50b 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# MX100 Laser Mouse +consoleUserPerms 0x0003 0x046d 0xc50e 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +# Receiver for Cordless Presenter +consoleUserPerms 0x0003 0x046d 0xc702 0x0000 0xffff 0x00 0x00 0x00 0x00 0x00 0x00 0x00000000 +]]> +</programlisting> +</informalexample> + +<para> +That should be all that is needed on Linux - just copy the files into +<filename>/etc/hotplug/usb/</filename>, and when the mouse is +plugged in, the ownership and permissions should be changed +so that the user at the console can access the mouse. +</para> +</sect3> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/netpref/Makefile.am b/doc/kcontrol/netpref/Makefile.am new file mode 100644 index 000000000..8dacf4438 --- /dev/null +++ b/doc/kcontrol/netpref/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/netpref diff --git a/doc/kcontrol/netpref/index.docbook b/doc/kcontrol/netpref/index.docbook new file mode 100644 index 000000000..f97b30b36 --- /dev/null +++ b/doc/kcontrol/netpref/index.docbook @@ -0,0 +1,109 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-10-16</date> +<releaseinfo>3.1</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdebase</keyword> +<keyword>kcontrol</keyword> +<keyword>network</keyword> +<keyword>timeouts</keyword> +</keywordset> + +</articleinfo> + +<sect1 id="timeouts"> + +<title>Preferences</title> + +<para>Here you can set timeout values. You might want to tweak them +if your connection is very slow, but the default settings are +appropriate for most users.</para> + +<para>Here <guilabel>Timeout Values</guilabel> are the length of time +an application should wait for an answer from a network operation.</para> + +<para>You can configure the following timeouts:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Socket read:</guilabel></term> +<listitem> +<para> Some applications use <firstterm>sockets</firstterm> to +communicate. You can think of a socket as a water tap; while it is +open, water (or in our case, data) comes out, without any interaction. +If something stops this flow of data, the application will wait for +more to come. This could be a very long time, but you can configure a +maximum time for an application to wait with this option.</para> +<para>This setting will only apply to &kde; applications, of course.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Proxy connect:</guilabel></term> +<listitem> +<para> +Sets how long to wait for a connection to a proxy server, if one is configured. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server connect:</guilabel></term> +<listitem> +<para> +Sets how long to wait for a connection to a remote server. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server response:</guilabel></term> +<listitem> +<para> +Sets how long to wait for a reply from a remote server. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>You can configure <guilabel>FTP Options</guilabel> here. At +present there is just two options:</para> +<variablelist> +<varlistentry> +<term><guilabel>Enable passive mode (PASV)</guilabel></term> +<listitem><para>Passive &FTP; is often required when you are behind a firewall. +Many firewalls only permit connections that were initiated from +<quote>the inside</quote>. Passive &FTP; is controlled by the client, +which makes it usable through firewalls.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Mark partially uploaded files</guilabel></term> +<listitem><para>When a mark is placed in this box, partially uploaded files will +have a <literal role="extension">.part</literal> extension added to the end +of the file. This extension is removed once the file download is complete. </para></listitem> +</varlistentry> + +</variablelist> + + + +</sect1> +</article>
\ No newline at end of file diff --git a/doc/kcontrol/panel/Makefile.am b/doc/kcontrol/panel/Makefile.am new file mode 100644 index 000000000..06524aebe --- /dev/null +++ b/doc/kcontrol/panel/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/panel diff --git a/doc/kcontrol/panel/index.docbook b/doc/kcontrol/panel/index.docbook new file mode 100644 index 000000000..722c6ed9d --- /dev/null +++ b/doc/kcontrol/panel/index.docbook @@ -0,0 +1,244 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-20</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>panel</keyword> +</keywordset> +</articleinfo> + +<sect1 id="panel"> +<title>Panel</title> + +<para> The &kde; panel (often referred to as &kicker;) is the bar that +you'll usually find at the bottom of the screen when you start up &kde; +for the first time. For detailed help on &kicker;'s usage you can type + <ulink url="help:/kicker">help:/kicker</ulink> in &konqueror; to read +the user manual.</para> + +<para>The panel gives you quick access to applications and makes it +easier for you to organize your desktop. Using the &kde; panel you +can:</para> + +<itemizedlist> +<listitem><para>launch applications using the <guimenu>K</guimenu> menu or +the application buttons</para></listitem> +<listitem><para>switch desktops using the panel's pager applet</para> +</listitem> +<listitem><para>switch active windows, and minimize or maximize them</para> +</listitem> +<listitem><para>browse folder using the browser menu functionality +</para></listitem> +<listitem><para>access panel applets that extend the panel's functionality, +offering for example mixers, clocks or a system monitor</para> </listitem> +</itemizedlist> + +<sect2 id="panel-position"> +<title><guilabel>Arrangement</guilabel></title> + +<para>In the <guilabel>Arrangement</guilabel> tab you can configure the size and +position of the panel.</para> + +<para>If you have more than one panel on screen, you can select at the +top of the window which panel you wish to configure.</para> + +<para>In the section labeled <guilabel>Position</guilabel> is a set of +12 small buttons arranged in a square. Each button corresponds to a +location for the panel. Click on a button and notice where the panel +is located on the preview monitor to the right.</para> + +<tip><para>Generally, the available space in kicker is used more +efficiently if the panel is aligned horizontally, &ie; attached to the +top or bottom screen border.</para></tip> + +<para>In the section labeled <guilabel>Length</guilabel>, you can use +the combo box and slider to adjust the <emphasis>minimum</emphasis> +length of the panel. If you place a mark in the checkbox labeled +<guilabel>Expand as required to fit contents</guilabel>, the panel +will become longer if more space is needed. When less space is +required on the panel, the panel will shrink down to the minimum size. +If there is no mark in the checkbox, then the panel is fixed to the +length specified in this section.</para> + +<para>The final section of this table is labeled +<guilabel>Size</guilabel>, and refers to the +<emphasis>height</emphasis> of the panel. The panel's size can be +<guilabel>Tiny</guilabel>, <guilabel>Small</guilabel>, +<guilabel>Medium</guilabel>, <guilabel>Large</guilabel> or +<guilabel>Custom</guilabel>. If you choose +<guilabel>Custom</guilabel> mode, you can resize &kicker; by +specifying a height in the combobox.</para> + +<para>If you have multiple monitors, you can configure the panel for +each screen entirely independently. If you are not sure which screen +is which, Press the <guibutton>Identify</guibutton> and a number will +appear centred on each screen.</para> +<!-- TODO: It's not centered on dual head non-xinerama, they both +appear on the primarey head, file a bug --> + +<para>Then simply choose the screen you wish to configure from the +drop down box labelled <guilabel>Xinerama screen</guilabel>, or choose +<guilabel>All Screens</guilabel> to have identical configurations on +each.</para> + +</sect2> + +<sect2 id="panel-hiding"> +<title>Hiding</title> + +<para>Depending on your screen resolution you may find that the panel +takes away too much of your precious screen real estate. To save +screen space, the panel offers manual hiding of the panel, an auto +hide feature, and the ability to allow other windows to lay on top of +the panel. These features are selected in the section entitled +<guilabel>Hide Mode</guilabel>.</para> + +<para>The <guilabel>Hide Mode</guilabel> section has three options:</para> +<variablelist> +<varlistentry> +<term><guilabel>Only hide when panel-hiding button is clicked</guilabel></term> +<listitem><para>When this option is selected, the panel will remain visible at +the location you defined unless you click on the button at the far right (for horizontally +oriented) or bottom (for vertically oriented) button. This button has an arrow on it pointed +to the edge of the screen.</para> + +<para>Once clicked, the panel will disappear. If the button is clicked again, the panel will re-appear +at the same location.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Hide automatically</guilabel></term> +<listitem><para>If this option is selected, then the panel will automatically disappear after +the number of seconds specified in the combo box below the option. To make the panel reappear, +simply move the mouse pointer to the edge of the screen where the panel is located, and the +panel will reappear immediately.</para> + +<para>If you place a mark in the checkbox labeled <guilabel>Show panel when switching +desktops</guilabel>, the panel will automatically reappear when you switch desktops. (The panel +will disappear again after the specified number of seconds.)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Allow other windows to cover the panel</guilabel></term> +<listitem><para>As this option's label implies, the panel is always on the desktop when +this option is selected. It is now possible, however, for application windows to lay +on top of the panel.</para> + +<para>To restore the panel, simply move the mouse cursor to the screen +location specified in the drop box labeled <guilabel>Raise when the pointer touches +the screen's:</guilabel>. You can change this value by selecting one of the choices +provided in the drop down box.</para> + +<para>Once the panel has moved back on top of the application window, it will stay there +until an application window becomes active again.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>The next section down is labeled <guilabel>Panel-Hiding Buttons</guilabel>. It +consists of two check boxes: <guilabel>Show left panel-hiding button</guilabel> and +<guilabel>Show left panel-hiding button</guilabel>. Use these checkboxes to show and +hide the left and right manual panel hiding buttons.</para> + +<para>If there is no mark in the checkbox labeled <guilabel>Animate +panel hiding</guilabel>, then whenever the toolbar is hidden, is simply disappears. If there +is a mark in the check box, then the panel appears to slide off the edge of the screen.</para> + +<para>You can determine how quickly the panel appears to move by adjusting the slider from +<guilabel>Fast</guilabel> to <guilabel>Slow</guilabel>.</para> +</sect2> + +<sect2 id="panel-menus"> +<title>Menus</title> + +<para>In the <guilabel>Menus</guilabel> tab you can configure the panel +menu's behavior. This affects the K menu you will often use to launch +applications, the browser menus you can use to access folders and other +menus like the recent documents menu.</para> + +<para>The <guilabel>K Menu</guilabel> frame offers you some options to +configure the <guimenu>K</guimenu> menu's functionality. This frame consists +of 4 items:</para> + +<itemizedlist> +<listitem><para>The <guilabel>Menu item format:</guilabel> radio +buttons have three options. This determines how the application name +(&ie; &konqueror;, &kword;, &etc;) and the description (&ie; Web +Browser, Word Processor, &etc;) are displayed on the &kmenu;. +</para></listitem> + +<listitem><para>The <guilabel>Optional Menus</guilabel> checkboxes allow +you to +determine which special menu items appear in the &kmenu;.</para> +<para>The <guilabel>Bookmarks</guilabel> +menu allows you to quickly select from the same bookmarks that are available in &konqueror;. </para> +<para>The <guilabel>Find</guilabel> menu offers access to the &kfind; application to search for local files, and a quick link to a search engine to search for things on the Internet.</para> +<para>The <guilabel>Konqueror Profiles</guilabel> menu allows you to +launch &konqueror; with any of your configured profiles.</para> +<para>The <guilabel>Network Folders</guilabel> menu can launch a +&konqueror; file manager window displaying any of your configured +network folders.</para> +<para>The <guilabel>Preferences</guilabel> menu allows you to launch each &kcontrol; module +directly from the K menu.</para> +<para>The <guilabel>Print System</guilabel> menu provides several menu entries to help manage +the printer(s) attached to your system.</para> +<para>The <guilabel>Quick Browser</guilabel> menu gives you quick links to locations on your hard drive.</para> +<para>The <guilabel>Recent Documents</guilabel> menu lists the most recently edited documents and will automatically +launch the application to edit or view this document. </para> +<para>The <guilabel>System</guilabel> menu allows you quick access to +some commonly visited places, including your Home folder, and the +Trash. You may find this useful instead of having a separate entry for +each of these in the &kmenu;</para> +<para>The <guilabel>Terminal Sessions</guilabel> menu provides menu items to launch several different types of +terminal programs (command line interfaces).</para> +</listitem> + +<listitem><para><guilabel>Show side image</guilabel> will add a small +image to the side of the menu. This is purely decorative.</para></listitem> + +<listitem><para>The <guibutton>Edit K Menu</guibutton> button launches the &kde; +menu editor.</para></listitem> +</itemizedlist> + +<para> In the <guilabel>QuickBrowser Menus</guilabel> area you can configure +whether the panel's browser menus will show hidden files or not (hidden +files on &UNIX; systems are those whose filenames begin with a dot) as +well as how many files at most will be shown in a browser menu. The +latter option may be especially useful if you have a rather small screen +resolution, as then the browser menus will quickly fill up your screen +when you browse folders containing many files.</para> + +<para>The quick start section in the K menu offers quick access to +programs you have used often or recently. In the <guilabel>Quick Start Menu Items</guilabel> +frame you can choose whether +this section will show the most recently or the most frequently used +programs. Using the option <guilabel>Maximum number of entries</guilabel> +combo box, you can configure how many programs the quick start +section will remember.</para> + +</sect2> + + + +</sect1> + +</article> diff --git a/doc/kcontrol/panelappearance/Makefile.am b/doc/kcontrol/panelappearance/Makefile.am new file mode 100644 index 000000000..1a92a45e8 --- /dev/null +++ b/doc/kcontrol/panelappearance/Makefile.am @@ -0,0 +1,3 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/panelappearance + diff --git a/doc/kcontrol/panelappearance/index.docbook b/doc/kcontrol/panelappearance/index.docbook new file mode 100644 index 000000000..1619c3f12 --- /dev/null +++ b/doc/kcontrol/panelappearance/index.docbook @@ -0,0 +1,122 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author> +<firstname>Mike</firstname> +<surname>McBride</surname> +</author> +<author> +<firstname>Jost</firstname> +<surname>Schenck</surname> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-06</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>panel</keyword> +</keywordset> +</articleinfo> + +<sect1 id="panel"> +<title>Panel</title> + +<para>Here you can configure the panel's overall appearance.</para> + +<para>You can also have the icons themselves zoom out when the +mouse is over them, with the <guilabel>Enable icon zooming</guilabel> +option. You can choose to have tooltips appear when your mouse button is +over an icon, by enabling the <guilabel>Show tooltips</guilabel> +option.</para> + +<sect2 id="button-backgrounds"> +<title>Button Backgrounds</title> + +<para>The &kde; panel supports so-called <guilabel>Button +Backgrounds</guilabel>. This means that the buttons shown on the panel +will be drawn using configurable images. To enable button backgrounds, +simply choose the button type from the list, and change the drop down +box to the color image you would like to use. Choose +<guilabel>Default</guilabel> to return to an unstyled button. If you +choose <guilabel>Custom color</guilabel>, the color button next to the +drop down list will be enabled. Click on it to select a custom color +to use.</para> + +</sect2> + +<sect2 id="panel-background"> +<title><guilabel>Panel Background</guilabel></title> + +<para><guilabel>Enable transparency</guilabel> to turn the entire +panel transparent. The desktop background will show through instead +of a background image or color.</para> + +<para>There will still be small handles beside each applet, to allow +you to locate, move, and configure them. These can be turned off in +the <guilabel>Advanced Options</guilabel></para> + +<para>If you check <guilabel>Enable background image</guilabel> a +picture will be used to draw the panel's background, just as you +can use a picture for the desktop background. You can specify an image +file in the line edit box below or choose one by clicking on the +<guibutton>Browse</guibutton> button. You'll see a preview of the +selected picture on the right.</para> + +<para>The image can be tinted on-the-fly by enabling the option +<guilabel>Colorize to match the desktop color scheme</guilabel>. You +might use a grayscale texture that is tinted in this manner, to create +a particular effect.</para> +</sect2> + +<sect2 id="advanced-options"> +<title><guilabel>Advanced Options</guilabel></title> + +<para>The <guilabel>Hide button size:</guilabel> option allows you to +choose a width in pixels for the hide buttons, if they are +visible.</para> + +<para>The panel itself has several default sizes set, which you can +switch between by simply dragging the edge of it, or by &RMB; clicking +on an empty space in the panel, choosing <guisubmenu>Size</guisubmenu> +and selecting the desired size from the submenu. If you enable +<guilabel>Allow Drag and Drop resizing of panels</guilabel> then by +choosing <guimenuitem>Custom</guimenuitem> in the panel menu, you can +drag the panel edge to any size you like.</para> + +<para>Applet handles are normally visible beside each applet on the panel, so that it is clear where to click to configure them, or to get to the panel menu. You can instead have them <guilabel>Fade out</guilabel>, or hide unless you hover the mouse over them, or you can choose to <guilabel>Hide</guilabel> them completely.</para> + +<para>Finally, if the panel is transparent, you can tint it with a +color of your choice. The slider allows you to choose how opaque the +tint is. At the lowest end, there is no tint visible, while at the +highest, the panel is not transparent at all.</para> + +</sect2> + +<sect2 id="panel-author"> +<title>Section Author</title> +<para>This section written by: Jost Schenck <email>[email protected]</email></para> +<para>Minor update by Mike McBride +<email>[email protected]</email></para> + +<para>Some new options added by Lauri Watts +<email>[email protected]</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/passwords/Makefile.am b/doc/kcontrol/passwords/Makefile.am new file mode 100644 index 000000000..6c8d0b013 --- /dev/null +++ b/doc/kcontrol/passwords/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/passwords diff --git a/doc/kcontrol/passwords/index.docbook b/doc/kcontrol/passwords/index.docbook new file mode 100644 index 000000000..3aa2ed0bc --- /dev/null +++ b/doc/kcontrol/passwords/index.docbook @@ -0,0 +1,84 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-16</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>password</keyword> +</keywordset> + +</articleinfo> +<sect1 id="passwords"> + +<title>Passwords</title> + +<sect2 id="passwords-intro"> +<title>Introduction</title> + +<para>This module of the &kcontrol; gives you options for configuring the way in +which the &kdesu; program treats passwords. &kdesu; will ask you for a password +when you try to carry out some privileged actions, such as changing the +date/time stored in your system clock, or adding new users on your +computer.</para> + +<para>Privileged actions such as those described above can only be +carried out by <systemitem class="username">root</systemitem> or a +user with administrator permissions on your system. You will need to +enter the password for the root account when you want to carry out +such actions.</para> + +<important><para>The options in this module do not affect the behavior of +passwords in other programs such as &kmail;.</para> +</important> + +</sect2> + +<sect2 id="passwords-use"> +<title>Use</title> + +<para>There are two configuration options for passwords. The first is +to control the visual feedback that you receive when you type a +password. The actual characters in the password are never shown on the +screen. You can choose to have each character represented by a +<token>*</token> character. If you want to make it harder for someone +who might be watching your screen to figure out how many characters +there are in the password, you can choose to have each character in +the password be represented by three asterisks rather than just +one. Still another option is not to have any visual feedback at all, +so nothing appears on the screen when you type a password.</para> + +<para>If you work in a reasonably secure environment, you can check +the option labeled <guilabel>Remember Passwords</guilabel>, and then +choose a time period in minutes using the spinner labeled +<guilabel>Timeout</guilabel>. (You can either type a number between 5 +and 1200 minutes, or use the arrows on the spinner.)</para> + +<para>If the <guilabel>Remember passwords</guilabel> option has been selected, +<application>kdesu</application> will not ask you for a password for the length +of time specified, after you have given the password once. Keep in mind, +however, that this makes your workstation less secure.</para> + +<important><para>You should avoid selecting the <guilabel>Remember +passwords</guilabel> option if you are working in an insecure area, such as a +publicly accessible workstation. Also, note that choosing a shorter timeout may +be better if you are in a less secure environment.</para></important> + +</sect2> + +</sect1> +</article>
\ No newline at end of file diff --git a/doc/kcontrol/performance/Makefile.am b/doc/kcontrol/performance/Makefile.am new file mode 100644 index 000000000..194fae838 --- /dev/null +++ b/doc/kcontrol/performance/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/performance diff --git a/doc/kcontrol/performance/index.docbook b/doc/kcontrol/performance/index.docbook new file mode 100644 index 000000000..b0acf0685 --- /dev/null +++ b/doc/kcontrol/performance/index.docbook @@ -0,0 +1,102 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-03-04</date> +<releaseinfo>3.4.0</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>system performance</keyword> +<keyword>performance</keyword> +<keyword>preload</keyword> +</keywordset> +</articleinfo> + +<sect1 id="sys-performance"> +<title>Performance Settings</title> + +<para>&kde;, is used on a wide variety of computers by a wide variety of users. Under the category of +performance, this dialog box allows each user to adjust options which may make the computer that &kde; is +installed on feel more responsive. </para> + +<para>This module is divided into two tabs.</para> + + +<sect2><title>&konqueror; performance options</title> +<sect3><title>&konqueror; instances</title> +<para>The first section of this dialog is labeled <guilabel>Minimize Memory Usage</guilabel> and has three options which determine maximum number of instances of &konqueror; that can be open on one machine at any one time.</para> + +<note><para>Do not confuse &konqueror; instances, with &konqueror; windows or tabs. The number of konqueror instances is determined by &kde; not by the user. You can think of instances as the hidden data of your &konqueror; windows and tabs. One &konqueror; instance can contain the data for multiple windows or tabs. Your choice on the following radio buttons does not limit the number of windows you can open at one time, but rather, how many instances of &konqueror; you can have open. </para> +<para>The reason the choices you make in this dialog box are important is evident when something goes wrong and &konqueror; is forced to close an instance. <emphasis>All &konqueror; windows associated with a &konqueror; instance must be closed immediatly (without time to save data or bookmark locations).</emphasis> Therefore, the more instances you can have open at one time, the less likely a problem in one instance will affect all of your work. Each instance requires more memory which can be a problem on systems with less system memory. </para></note> + +<para>Your options are:</para> + +<variablelist> +<varlistentry> +<term>Never</term> +<listitem><para>There are no restraints. Any number of &konqueror; instances can be open at any one time. The advantage of this option is if any &konqueror; instance crashes the remaining will be unaffected. The disadvantage is that each &konqueror; instance uses more memory.</para></listitem> +</varlistentry> + +<varlistentry> +<term>For file browsing only (recommended)</term> +<listitem><para>If this option is selected, you can have as many as you want &konqueror; instances open that are browsing the web, but only one instance of &konqueror; for file management. </para></listitem> +</varlistentry> + +<varlistentry> +<term>Always (use with care)</term> +<listitem><para>If this option is selected, you can only have one instance of &konqueror; running at any one time. This saves system memory, but if your &konqueror; window crashes, all your browsing windows close immediatly without warning. This should only be used for seriously memory limited systems.</para></listitem> +</varlistentry> +</variablelist> +</sect3> +<sect3><title>Preloading</title> +<para>The subsection labeled <guilabel>Preloading</guilabel> also makes a tradeoff between memory and performance.</para> + +<para><emphasis>Preloading</emphasis> refers to loading an instance of &konqueror; into memory before a user asks to start &konqueror;. The positive effect of this is that when a user asks &kde; to load &konqueror; the window appears instantly + because most of the application has been preloaded. The negative effect is that this instance of &konqueror; uses memory that +could be used by other programs. By default, when a user closes &konqueror;, &kde; does not close the instance. +This means that the next time a user wants &konqueror; loaded, it is nearly instantanous again.</para> +<para>The spinbox labeled <guilabel>Maximum number of instances kept preloaded:</guilabel> can be used to adjust the maximum number of preloaded instances. This option does not affect instances when they are loaded. It also does not limit the number of instances that can be used by active windows. It only affects the number of preloaded instances.</para> +<para>The checkbox labeled <guilabel>Preload an instance after &kde; startup</guilabel> does just what it says. It tells +&kde; to preload one instance of &konqueror; at the startup of &kde;.</para> +<note><para>This does extend the startup time for &kde;.</para></note> +<para>The final checkbox labeled <guilabel>Always try to have at least one preloaded instance</guilabel> signals to &kde; that you always want &kde; to have one preloaded, but not used, instance of &konqueror; available. This option will actually decrease performance on some machines (especially those with limited physical memory).</para> +</sect3> +</sect2> +<sect2><title>&kde; system performance options</title> +<para>Click on the tab labeled <guilabel>System</guilabel>.</para> +<para>Currently there is only one option labeled <guilabel>Disable system configuration startup check</guilabel>. +</para> +<para>When &kde; starts, it checks several directories for changes to configuration. Most of these changes relate to installation and uninstalling applications to the computer. This scan extends the startup time for &kde; and many times this scan is not needed as the configuration is current from the last time &kde; was started. When the configuration has changed &kde; uses this scan to update various datafiles to ensure a smooth user experience. </para> +<warning><para>You are given the option to skip this initial scan during startup. &kde; developers strongly suggest you do not disable this scan because of the potential to introduce instability into your system.</para> +<para>If you do select this option:</para> +<itemizedlist> +<listitem><para>&kde; will wait to perform the scan until after &kde; has started. This scan will be performed after the desktop is loaded.</para></listitem> +<listitem><para>In the event of a crash, &kde; will not perform a backtrace because your problem may be related to the delayed scan.</para></listitem> +<listitem><para>Switch this option off if any application is crashing as a delayed scan may be responsible for the crash.</para></listitem> +</itemizedlist> + + + + +</warning> + + + +</sect2> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/proxy/Makefile.am b/doc/kcontrol/proxy/Makefile.am new file mode 100644 index 000000000..ce9c3748a --- /dev/null +++ b/doc/kcontrol/proxy/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/proxy diff --git a/doc/kcontrol/proxy/index.docbook b/doc/kcontrol/proxy/index.docbook new file mode 100644 index 000000000..0a47cec36 --- /dev/null +++ b/doc/kcontrol/proxy/index.docbook @@ -0,0 +1,197 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY socks-kcontrol SYSTEM "socks.docbook"> +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + + +<authorgroup> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-11</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>proxy</keyword> +<keyword>proxies</keyword> +</keywordset> + +</articleinfo> +<sect1 id="proxies"> +<title>Proxies</title> + +<sect2 id="proxies-intro"> + +<title>Introduction</title> + +<para>Proxies are programs running on a computer that acts a server on +the network you are connected to (whether by modem or other +means). These programs receive &HTTP; and &FTP; requests, retrieve the +relevant files from the internet, and pass them on to the client +computer that made the requests.</para> + +<para>When you have configured a proxy, &HTTP; and/or &FTP; requests +are re-routed through the computer that is acting as a proxy server. +However, you can also select specific hosts which should be contacted +directly, rather than through the proxy server. If you are on a local +network, for example, access to local hosts probably doesn't need to +go through a proxy server.</para> + +<para>You should only need to configure a proxy server if your network +administrator requires it (if you are a dial-up user, that would be +your internet service provider or <acronym>ISP</acronym>). Otherwise, +especially if you are feeling a bit confused about this proxy +business, but everything seems to be fine with your internet +connection, you don't need to change anything.</para> + +<para>Please note that using proxy servers is optional, but has the +benefit or advantage of giving you faster access to data on the +internet.</para> + +<para>If you are uncertain whether or not you need to use a proxy +server to connect to the internet, please consult with your internet +service provider's setup guide or your system administrator.</para> + +</sect2> + +<sect2 id="proxies-use"> + +<title>Use</title> + +<variablelist> +<varlistentry> +<term><guilabel>Connect to the Internet directly</guilabel></term> +<listitem> + +<para>Select this option if you do <emphasis>not</emphasis> want to use a proxy server.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>If you have decided to use a proxy, you have several methods to +configure the settings for it.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Automatically detected script file</guilabel></term> +<listitem> + +<para>Select this option if you want the proxy setup configuration +script file to be automatically detected and downloaded.</para> +<para>This option only differs from the next choice in that it +<emphasis>does not</emphasis> require you to supply the location of +the configuration script file. Instead, it will be automatically +downloaded using <quote>Web Access Protocol Discovery</quote> +(<acronym>WAPD</acronym>).</para> + +<note><para>If you have a problem using this setup, please consult the +<acronym>FAQ</acronym> section at <ulink +url="http://www.konqueror.org">http://www.konqueror.org</ulink> for +more information.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Specified script file</guilabel></term> +<listitem> +<para>Select this option if your proxy support is provided through a +script file located at a specific address. You can then enter the +address in the location text box, or use the <guiicon>folder</guiicon> +icon to browse to it.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Preset environment variables</guilabel></term> +<listitem> +<para>Some systems are setup with $<envar>HTTP_PROXY</envar> to allow +graphical as well as non-graphical applications to share the same +proxy configuration information.</para> +<para>If you know this applies to you, select this option and click on +the <guibutton>Setup...</guibutton> button to provide the environment +variable names used to set the address of the proxy server(s).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Manually specified settings</guilabel></term> +<listitem> +<para>Select this option, and click on the +<guibutton>Setup...</guibutton> to manually setup the location of the +proxy servers to be used.</para> + +<para>If you choose this option, another dialog will pop up.</para> + +<para>The complete addressing information for the proxy includes both +the internet address and a port number. You should enter these into +the relevant text boxes. The <guiicon>arrow</guiicon> button copies +the information from the <guilabel>HTTP</guilabel> line to the +<guilabel>FTP</guilabel> line, in order to help save some +typing.</para> + +<para>If there are hosts which you can connect to without going +through the proxy server, you can press <guibutton>Add</guibutton> to +add the names of these hosts, separated by in the text box labeled +<guilabel>No Proxy For:</guilabel>. For example, hosts that are on +your local network can probably be contacted directly.</para> + +<para>You can also choose <guilabel>Only use proxy for entries in this +list</guilabel>.</para> + +<para>Check this box to reverse the use of the exception list, &ie; +the proxy servers will only be used when the requested &URL; matches +one of the addresses listed here.</para> + +<para>This features is useful if all you need is a proxy to access a +few specific sites, for example, an internal intranet. If you have +more complex requirements you might want to use a configuration +script.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="authorization"> +<title><guilabel>Authorization</guilabel></title> + +<para>Here you can choose between two types of authentication, if your +proxy requires it. You can have <guilabel>Prompt as +needed</guilabel>, the default, in which case &konqueror; will only +ask for a username or password if it needs to.</para> + +<para>The other option is <guilabel>Use automatic login</guilabel>. +Select this option if you have already set up a login entry for your +proxy server in the +<filename>$<envar>KDEDIR</envar>/share/config/kionetrc</filename> +file.</para> + +</sect2> + +<sect2 id="options"> +<title><guilabel>Options</guilabel></title> +<variablelist> +<varlistentry> +<term><guilabel>Use persistent connections to proxy</guilabel></term> +<listitem> +<para>Use persistent connection to your proxy server. Keeps connection to proxy open, helps lower bandwidth/speed up connection. Enabling this option will require the proxy server's cooperation, if the proxy server does not support this, it will bring your internet to a stop. </para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +&socks-kcontrol; + +</sect1> + +</article> diff --git a/doc/kcontrol/proxy/socks.docbook b/doc/kcontrol/proxy/socks.docbook new file mode 100644 index 000000000..73c5e2ec6 --- /dev/null +++ b/doc/kcontrol/proxy/socks.docbook @@ -0,0 +1,56 @@ +<sect2 id="socks"> +<sect2info> +<authorgroup> +<author>&Lauri.Watts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</sect2info> + +<title>SOCKS</title> + +<para>SOCKS is a protocol to execute proxy requests for a client. SOCKS +is capable of authentication and encryption of traffic, and is often +found in corporate settings, as opposed to home users. For more +information about SOCKS, see the <ulink +url="http://www.socks.nec.com">NEC</ulink> website</para> + +<para>With this module you can enable most of the network aware &kde; +applications to transparently use SOCKS.</para> + +<para>Setting up of a SOCKS client is outside the scope of this +document, and the differences between the commonly used ones are very +large. If you already have a working SOCKS implementation, allowing you +to use commandline clients (for example, if <command>lynx</command> or +<command>ftp</command> are already working) then you can simply check +the <guilabel>Enable SOCKS support</guilabel> checkbox.</para> + +<para>When this box is checked, several further options become available +to you.</para> + +<para>First, you should select which of the various SOCKS clients you +have installed on your computer. &kde; will attempt to find this out by +itself, if you choose <guilabel>Auto detect</guilabel>. If you know the +client you have, you could choose either <guilabel>NEC +Socks</guilabel> or <guilabel>Dante</guilabel>. If you have a +custom built SOCKS library to use, you can select <guilabel>Use custom +library</guilabel> and then enter the path to it in the +<guilabel>Path</guilabel> field.</para> + +<para>If you want &kde; to auto detect the SOCKS library in use, but you +suspect it isn't looking in the right places or you have installed it in +a non-standard location, then you can add further paths to be searched in +the bottom of this panel. Use the <guibutton>Add</guibutton> and +<guibutton>Remove</guibutton> to add or remove paths.</para> + +<para>At any time while filling in this module, you can press the +<guibutton>Test</guibutton> button, and &kde; will report immediately +with a message box to tell you if it could find and initialize SOCKS or +not.</para> + +<para>Changes made here will not affect any applications that are +already open. You will need to close and restart them before they are +able to connect via SOCKS.</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +</sect2> diff --git a/doc/kcontrol/screensaver/Makefile.am b/doc/kcontrol/screensaver/Makefile.am new file mode 100644 index 000000000..d9412ca98 --- /dev/null +++ b/doc/kcontrol/screensaver/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/screensaver diff --git a/doc/kcontrol/screensaver/index.docbook b/doc/kcontrol/screensaver/index.docbook new file mode 100644 index 000000000..67cb99411 --- /dev/null +++ b/doc/kcontrol/screensaver/index.docbook @@ -0,0 +1,203 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-20</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>screensaver</keyword> +<keyword>screen saver</keyword> +</keywordset> +</articleinfo> + +<sect1 id="screensaver"> + +<title>Screen Saver</title> + +<para>Using this module, you can choose your screen saver, determine +how much time must pass before the screen saver is activated, and add +or remove password protection to your screen saver.</para> + +<sect2 id="ss-choose"> +<title>Choosing the screen saver, and configuring its options</title> + +<para>In the <guilabel>Settings</guilabel> box is a check box +labeled <guilabel>Start screen saver automatically</guilabel>. This +box must have a mark in it, or &kde; will not launch any screen saver +and it will not allow you to adjust the settings of your screen +saver.</para> + +<para>Along the left side is a list of all available screen savers. You can +select a screen saver by simply clicking on its name. Once +you have selected a screen saver, you will see a small preview on the +monitor on the right.</para> + +<note><para>The preview monitor will often show the screen saver +larger than it is when the screen saver is activated. This is done on +purpose, since many of the details of the screen savers would be +unintelligible if actually scaled down to such a small +size.</para></note> + +<para>Each screen saver has a different set of setup options. By +clicking on <guilabel>Setup...</guilabel>, a dialog box will appear with +all available options. As you adjust the options, the preview box in +the dialog box will show you what effect you will achieve with the +current settings.</para> + +<para>When you are done setting up your screen saver, click +<guibutton>OK</guibutton>.</para> <para>Clicking <guibutton>Cancel</guibutton> +will erase any changes you made in this dialog box, and return you to the +screen saver module.</para> + +<para>Clicking the <guibutton>About</guibutton> button will give you +the Copyright and Author information if you are interested.</para> + +<para>When you think you have all the options set the way you want, +simply click on <guibutton>Test</guibutton> to immediately start the +screen saver <emphasis>exactly</emphasis> as it will appear.</para> + +</sect2> + +<sect2 id="ss-options"> +<title>Setting the time, priority and passwords for screen +savers.</title> + +<para>Below the screensaver list is a check box to have the screen saver <guilabel>Start automatically</guilabel> check box, and a spin box which determines the period of inactivity before the screen saver should be started. You can enter any postive number of minutes in this box.</para> + +<para>Below that is a check box labeled <guilabel>Require password to +stop screen saver</guilabel>. If it is checked, when you click a key +or click a mouse button to end the screen saver and return to your +work, you must enter a password. The password used is the same +password you used to login to your machine. If there is no mark in +the check box, no password is required to return to your +desktop.</para> + +<para>Enable the check box <guilabel>Make aware of +power management</guilabel> if you don't want the screensaver to start +while you watch TV or movies on your monitor.</para> + +</sect2> + +<sect2 id="ss-other"><title>Using a non-&kde; screen saver</title> + +<para>&kde; does not prevent another screen saver from working. To use a +different screen saver, such as <application>xscreensaver</application>, simply +disable the &kde; Screen Saver, and set up your other screen saver program +normally. </para> + +</sect2> + +<sect2 id="screensaver-remove"> +<title>Removing and restoring a screen saver from your system</title> + +<para>If you want to remove a screen saver from the list in this +Control Center Module, you will need to rename a file on your +system.</para> + +<caution><para>Working as a <systemitem +class="username">root</systemitem> user is a potentially dangerous +situation. While unlikely, it is entirely possible to do permanent +damage to your system while working as +<emphasis>root</emphasis>.</para> + +<para>Be very careful following the next set of +directions</para></caution> + +<para>To delete a screen saver, type the following commands:</para> + +<screen> +<prompt>bash$</prompt> <command>cd +$KDEDIR/share/applnk/System/ScreenSavers</command> +<prompt>bash$</prompt> <command>ls</command> +</screen> + +<para>This will give you a list of files. You will notice +similarities between some of the file names and that of the screen saver you +want to remove. Simply rename the file of similarly named desktop +file to a name which does not end in +<emphasis>desktop</emphasis>.</para> + +<para>Example:</para> +<screen> +<prompt>bash$</prompt> <command>cd +$KDEDIR/share/applnk/System/ScreenSavers</command> +<prompt>bash$</prompt> <command>mv KSpace.desktop KSpace.backup</command> +</screen> + +<para>Will remove Space (GL) from the list</para> + +<note><para>You must close the &kcontrolcenter; entirely and restart it before +the changes will be seen.</para></note> + +<para>To restore the disabled screen saver, simply rename the file back to its +original name:</para> + +<screen> +<prompt>bash$</prompt> <command>cd +$KDEDIR/share/applnk/System/ScreenSavers</command> +<prompt>bash$</prompt> <command>mv KSpace.backup KSpace.desktop</command> +</screen> + +<para>Restart the &kcontrolcenter;, and the screen saver is back in the +list.</para> + +</sect2> + +<sect2 id="grace"> +<title>Advanced Settings: Grace period</title> + +<para>There is a five second grace period after the screen saver +begins before a password is required even if <guilabel>Require +password</guilabel> is checked.</para> +<para>Locking the desktop manually, by clicking the lock icon +in the &kde; panel, causes the password protection to engage immediately with +no grace period.</para> +<para>To alter the grace period setting, you need to manually edit the +configuration file. To do so:</para> +<para> +<prompt>$</prompt> <command>cd <filename>~/.kde/share/config</filename> +</command> +</para> +<para>Now, using a text editor (the example uses &kate;, the &kde; text editor), +load the <filename>kdesktoprc</filename>.</para> +<para> +<prompt>$</prompt> <command>kate <filename>kdesktoprc</filename> +</command> +</para> +<para>Search through the file for the section labeled +<emphasis>[Screensaver]</emphasis>.</para> +<para>Look through all lines in the section for an entry entitled +<emphasis>LockGrace</emphasis>.</para> +<para>If the entry exists, you can edit the value of the entry. </para> +<screen>[Screensaver] +LockGrace=3000</screen> +<para>The value of the entity represents the duration of the grace period +in milliseconds. An entry of 3000, would change the grace period to 3 seconds. +You can set the value of the entry to any number between zero (no grace period) +and 300000 (5 minutes). +</para> +<para>If the entry does not exist, simply add the entry to the end of the +section.</para> + +<para>Any changes to the configuration entry take effect +immediately.</para> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kcontrol/screenshot.png b/doc/kcontrol/screenshot.png Binary files differnew file mode 100644 index 000000000..f73f380cf --- /dev/null +++ b/doc/kcontrol/screenshot.png diff --git a/doc/kcontrol/smb/Makefile.am b/doc/kcontrol/smb/Makefile.am new file mode 100644 index 000000000..9f75f1d22 --- /dev/null +++ b/doc/kcontrol/smb/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/smb diff --git a/doc/kcontrol/smb/index.docbook b/doc/kcontrol/smb/index.docbook new file mode 100644 index 000000000..3d3a0ea6a --- /dev/null +++ b/doc/kcontrol/smb/index.docbook @@ -0,0 +1,106 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +<author>&Jost.Schenck; &Jost.Schenck.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>Windows shares</keyword> +</keywordset> +</articleinfo> +<sect1 id="windows-shares"> +<title>Windows Shares</title> + +<sect2 id="windows-shares-intro"> +<title>Introduction</title> + +<para>In many small local area networks, the <acronym>SMB</acronym> +protocol is used to offer network services. Names like +<quote>&Windows; Network</quote> or <quote>&Windows; for Workgroups +Network</quote> or <quote>LanManager</quote> are often used as +well. Using <acronym>SMB</acronym> you can access so-called +<quote>shares</quote> (&ie; folders made available by the server) +as well as printers. </para> + +<para>&kde; comes with built-in support for the <acronym>SMB</acronym> +protocol. As &kde; is network-transparent that means you can access +<acronym>SMB</acronym> shares from everywhere you can access your +local files, for example in the &konqueror; file manager and in the +file dialog. To make use of this you should provide &kde; with some +information on your <acronym>SMB</acronym> network. But don't worry, +this is normally pretty simple as, for example, all the Windows +clients in your network need and have the same information.</para> + +<!-- Don't know if the following info should go in the base +documentation --> + +<!-- this smb-ioslave doesn't support showing a list +of hosts (like e.g. smb:/), for this you need the lan or rlan-ioslave, +very cool thing (TM) btw. If you want to write some documentation for +this one too, have a look at kdenetwork/lanbrowsing/lisa/README and +contact me if you have questions. --> + +<note><para>For the <acronym>SMB</acronym> protocol to work, it is +required to have <application>Samba</application> correctly +installed. If you have an NT domain controller, you will need at least +<application>Samba</application> version 2.0 or higher. If you want to +access &Windows; 2000 shares, you will need +<application>Samba</application> version 2.0.7 or higher. Older +versions may work too, but have not been tested.</para></note> + +<!-- TODO: link to some place which explains USING SMB, i.e. konqueror +or file dialog manual --> + +</sect2> + +<sect2 id="windows-shares-use"> +<title>Use</title> + +<para>Although there are a lot of insecure <acronym>SMB</acronym> +networks out there which allow access to anyone, in principle you have +to authenticate yourself to access the services of an +<acronym>SMB</acronym> server. By default, &kde; will use the data +entered in the <guilabel>Default user name</guilabel> and +<guilabel>Default password</guilabel> fields to authenticate itself on +<acronym>SMB</acronym> hosts. If you leave the field <guilabel>Default +user name</guilabel> empty, &kde; will try to access +<acronym>SMB</acronym> hosts without a username. If you leave the +default password empty, it will try without a password. If &kde; is +unsuccessful accessing the host using these settings, you will be +asked for a username and a password.</para> + +<important><para>While it makes things more comfortable if &kde; +stores your <acronym>SMB</acronym> password, this may be a security +problem. If you are using <acronym>SMB</acronym> in a security +conscious environment, you should not store your password here but +rather enter it anew every time you need to access an +<acronym>SMB</acronym> host.</para></important> + +<para>In the <guilabel>Workgroup</guilabel> field, you can enter your +workgroup name. If you don't know it, ask your system administrator +or have a look at other already configured machines in your network. +However, in most cases providing the workgroup name is not required, +so you probably can also leave this empty.</para> + +<para>If the option <guilabel>Show hidden shares</guilabel> is +checked, shares ending with a <quote>$</quote> will be shown.</para> +</sect2> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/spellchecking/Makefile.am b/doc/kcontrol/spellchecking/Makefile.am new file mode 100644 index 000000000..7eb60d12b --- /dev/null +++ b/doc/kcontrol/spellchecking/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/spellchecking diff --git a/doc/kcontrol/spellchecking/index.docbook b/doc/kcontrol/spellchecking/index.docbook new file mode 100644 index 000000000..87279d41b --- /dev/null +++ b/doc/kcontrol/spellchecking/index.docbook @@ -0,0 +1,88 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-13</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Spelling</keyword> +<keyword>dictionary</keyword> +</keywordset> + +</articleinfo> + +<sect1 id="spell-checking"> + +<title>Spell Checker</title> + +<para>The configuration options available here are used by all &kde; +applications that use &kspell;, which is a front end to +<command>ispell</command> or <command>aspell</command>.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Create root/affix combinations not in +dictionary</guilabel></term> +<listitem> +<para>Selecting this option allows the spell checker to register as <quote>correct</quote> combinations of root words with suffixes or prefixes even if the particular combination is not listed in its dictionary database of words.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Consider run-together words as spelling +errors</guilabel></term> +<listitem><para>If this is selected, then words that appear in the +dictionary separately, but have been run together, are considered to be +spelling errors. For example, even though <quote>alarm</quote> and +<quote>clock</quote> might be in your dictionary, if +<quote>alarmclock</quote> is not, it will be flagged as a spelling +error.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Dictionary:</guilabel></term> +<listitem> +<para>Choose from the available dictionaries, which one to use for +&kspell;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Encoding:</guilabel></term> +<listitem> +<para>You should select the one that matches the character set you are +using. In some cases, dictionaries will support more than one encoding. +A dictionary might, for example, accept accented characters when +<emphasis>Latin1</emphasis> is selected, but accept email-style +character combinations (like <userinput>'a</userinput> for an accented +<emphasis>a</emphasis>) when <emphasis>7-Bit-ASCII</emphasis> is +selected. Please see your dictionary's distribution for more +information.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Client:</guilabel></term> +<listitem> +<para>You can choose which of the installed client applications on your +system to use. For example, you can choose <command>ispell</command>.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +</article>
\ No newline at end of file diff --git a/doc/kcontrol/useragent/Makefile.am b/doc/kcontrol/useragent/Makefile.am new file mode 100644 index 000000000..c7efa77d7 --- /dev/null +++ b/doc/kcontrol/useragent/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/useragent diff --git a/doc/kcontrol/useragent/index.docbook b/doc/kcontrol/useragent/index.docbook new file mode 100644 index 000000000..14be0fcf2 --- /dev/null +++ b/doc/kcontrol/useragent/index.docbook @@ -0,0 +1,117 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Browser Identification</title> +<articleinfo> +<authorgroup> +<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-12</date> +<releaseinfo>3.2</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>user agent</keyword> +<keyword>browser</keyword> +<keyword>identification</keyword> +</keywordset> + +</articleinfo> + +<sect1 id="user-agent"> +<title>Browser Identification</title> + + +<sect2 id="user-agent-intro"> +<title>Introduction</title> + +<para>When &konqueror; connects to a web site to retrieve information, +some basic identifying information is sent to the web site in the form +of a <quote>User Agent</quote> header.</para> + +<para>Because of minor differences in the way that different web +browsers function, web sites that rely too much on a single browser may +sometimes not display as intended when viewed using another +browser. Some web sites are smart enough to examine the contents of the +user agent header and incorporate this information in the +<acronym>HTML</acronym> code so that the content is displayed correctly +regardless of the browser used.</para> + +<para>However, you may find that some web sites refuse to function +correctly unless you are using a browser recognized as +<quote>proper</quote> by that site. In these cases, you may find it +necessary to fool the web site by having &konqueror; report itself to be +another browser by means of the user agent header.</para> + +</sect2> + +<sect2 id="user-agent-use"> +<title>Use</title> + +<para>In this module you can configure the +type of browser that &konqueror; will report itself to be. You can +control this information by web site. Usually, the list box that is +labeled <guilabel>Site/Domain Specific Identification</guilabel> will be +empty, so that &konqueror; will always use its default useragent +string.</para> + +<para>You can disable the sending of a user agent entirely, by +unchecking the <guilabel>Send identification</guilabel> +checkbox. This may cause strange behavior on some sites, and may even +deny you access to some websites, so disable this with caution.</para> + +<para>To configure a new agent binding, press the +<guibutton>New...</guibutton> button. Type the name of the server or +a domain in the text box at the top of the dialog that pops up, which +is labeled <guilabel>When browsing the following +site</guilabel>.</para> + +<para>Note that you can <emphasis>not</emphasis> use the wildcard +character <token>*</token> in this text box. However, the string +<userinput>kde.org</userinput> will match all hosts in the domain +<systemitem>kde.org</systemitem></para> + +<para>After typing the name of the server, type in the identifying +string in the next combo box, which is labeled <guilabel>Use the +following identity:</guilabel>, or choose a string from the list. If +you don't choose a string from the list, you will need to know what a +valid string from the browser looks like. For example, you could type +<userinput>Mozilla/4.0 (compatible; MSIE 4.0)</userinput>. </para> + +<para>In the field labeled <guilabel>Alias (description)</guilabel> +you can enter a descriptive name for the configured binding, ⪚ +<userinput>Netscape Navigator 4.75 on Linux</userinput> for the +useragent string <userinput>Mozilla/4.75 (X11; U; Linux 2.2.14 +i686)</userinput>.</para> + +<para>You can click on an existing entry in the <guilabel>Configured +agent bindings</guilabel> list, and then modify the contents of the +text boxes, followed by clicking <guibutton>Change...</guibutton>.</para> + +<para>The <guibutton>Delete</guibutton> button can be used to delete +the selected entry in the list of configured agent bindings. The +<guibutton>Delete All</guibutton> will remove all the configured user +agent strings. Click the <guibutton>Apply</guibutton> to take your +changes in effect.</para> + +<para>You can use the checkboxes at the top of the screen to build a +user agent that is uniquely yours, by choosing your own combination of +operating system name and version, platform, processor type, and +language.</para> + +<para>In all cases, the user agent that is being sent by default is +displayed in bold text at the top of the page.</para> + +</sect2> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kcontrol/windowmanagement/Makefile.am b/doc/kcontrol/windowmanagement/Makefile.am new file mode 100644 index 000000000..3e5215103 --- /dev/null +++ b/doc/kcontrol/windowmanagement/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = kcontrol/windowmanagement diff --git a/doc/kcontrol/windowmanagement/index.docbook b/doc/kcontrol/windowmanagement/index.docbook new file mode 100644 index 000000000..650b8d2aa --- /dev/null +++ b/doc/kcontrol/windowmanagement/index.docbook @@ -0,0 +1,63 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<articleinfo> + +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-21</date> +<releaseinfo>3.4</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>window settings</keyword> +<keyword>window placement</keyword> +<keyword>window size</keyword> +</keywordset> +</articleinfo> +<sect1 id="window-specific"> +<title>Window Specific Settings</title> + +<para>Here you can constomize window settings specifically only for +some windows.</para> + +<note> +<para>Please note that this configuration will not take effect if you +do not use &kwin; as your window manager. If you do use a different +window manager, please refer to its documentation for how to customize +window behavior.</para> +</note> + +<para>Many of the settings you can configure here are those you can +configure on a global basis in the <guilabel>Window Behavior</guilabel> +&kcontrol; module, however some of them are even more detailed.</para> + +<para>They encompass geometry, placement, whether a window should be +kept above or below others, focus stealing prevention, and translucency +settings.</para> + +<para>You can access this module in two ways: from the titlebar of the +application you wish to configure, or from &kcontrol;. If you +start it from within &kcontrol; you can use the +<guibutton>New...</guibutton> to create a window profile, and the +<guibutton>Detect</guibutton> button on the resulting dialog to +partially fill in the required information for the application +you wish to configure.</para> + +<para>You can also at any time <guibutton>Modify...</guibutton> or +<guibutton>Delete</guibutton> any stored settings profile, and +reorder the list. Reordering the list is a convenience to help you sort +the profiles, and has no effect on how they are applied.</para> + +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kdcop/Makefile.am b/doc/kdcop/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kdcop/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kdcop/index.docbook b/doc/kdcop/index.docbook new file mode 100644 index 000000000..f92de1232 --- /dev/null +++ b/doc/kdcop/index.docbook @@ -0,0 +1,78 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "&kdcop;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kdcop; Handbook</title> + +<authorgroup> +<author> +<firstname></firstname> +<othername></othername> +<surname></surname> +<affiliation> +<address><email></email></address> +</affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<legalnotice>&FDLNotice;</legalnotice> + +<!-- Date and version information of the documentation +Don't forget to include this last date and this last revision number, we +need them for translation coordination ! +Please respect the format of the date (DD/MM/YYYY) and of the version +(Major.minor.lesser), it could be used by automation scripts --> + +<date>2002-12-16</date> +<releaseinfo>0.00.00</releaseinfo> + +<!-- Abstract about this handbook --> + +<abstract> +<para> +&kdcop; is a program to help you browse available dcop functions. +</para> +</abstract> + + +<keywordset> +<keyword>KDE</keyword> +<keyword>Kompare</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> <title>Introduction</title> <para> +The documentation for &kappname; was not finished when &kde; was installed on +this computer.</para> <para>If you need help, please check <ulink +url="http://www.kde.org">The &kde; Website</ulink> for updates, or by +submitting your question to <ulink url="mailto:[email protected]">The +&kde; User Mailing list</ulink>.</para> <para><emphasis>The &kde; +Team</emphasis></para> + +&underFDL; + +</chapter> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +// vim:ts=2:sw=2:tw=78:noet +--> diff --git a/doc/kdebugdialog/Makefile.am b/doc/kdebugdialog/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kdebugdialog/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kdebugdialog/index.docbook b/doc/kdebugdialog/index.docbook new file mode 100644 index 000000000..72634224d --- /dev/null +++ b/doc/kdebugdialog/index.docbook @@ -0,0 +1,134 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kdebugdialog "<application>KDebugDialog</application>"> + <!ENTITY kappname "&kdebugdialog;"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + + +]> + +<book lang="&language;"> +<bookinfo> +<title>The &kdebugdialog; Handbook</title> + +<authorgroup> +<author>&David.Faure; &David.Faure.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2001-02-13</date> +<releaseinfo>0.03.00</releaseinfo> + +<abstract> +<para>This document describes &kdebugdialog;.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KDebugdialog</keyword> +</keywordset> +</bookinfo> + +<chapter id="Introduction"> +<title>What is KDebugDialog?</title> + +<para>It is a dialog box for managing diagnostic messages at runtime. +</para> + +<para>If you simply start <command>kdebugdialog</command>, you will +see a list of <quote>areas</quote>, that can be disabled or enabled. A +<function>kdDebug(area)</function> call in the code will show +something in the debug output only if the area is enabled.</para> + +<note><para>Note that kdWarning, kdError and kdFatal always appear, +they are NOT controlled by this setting. </para></note> + +<variablelist> +<varlistentry> +<term><guilabel>Area</guilabel></term> +<listitem> +<para>The areas which should only be output. Every message +that is not mentioned here will simply not be output (unless +this field remains empty, which is the default, and means that all +messages should be output). You can enter several areas +separated by commas here, and you can also use area ranges with +the syntax start-end. Thus a valid entry could be: +117,214-289,356-359,221. Do not use whitespaces.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>If you start <command>kdebugdialog</command> +<option>--fullmode</option>, then for every severity level you can +define separately what should be done with the diagnostic messages of +that level, and the same for each debug area.</para> + +<para>In full mode, first you should select the debug area you are +interested in from the drop down list at the top.</para> + +<para>You may independently set the output for various types of +messages:</para> + +<itemizedlist> +<listitem><para><guilabel>Information</guilabel></para></listitem> +<listitem><para><guilabel>Warning</guilabel></para></listitem> +<listitem><para><guilabel>Error</guilabel></para></listitem> +<listitem><para><guilabel>Fatal Error</guilabel></para></listitem> +</itemizedlist> + +<para>For each of these types, you can set the following:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Output to:</guilabel></term> +<listitem> +<para>In this Combobox, you can choose where the messages +should be output. The choices are: <quote>File</quote>, <quote>Message +Box</quote>, <quote>Shell</quote> (meaning stderr) and +<quote>Syslog</quote>. Please do not direct fatal messages to syslog +unless you are the system administrator yourself. The default is +<quote>Message Box</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Filename:</guilabel></term> +<listitem><para>This is only enabled when you have chosen +<quote>File</quote> as the output and provides the name of that file +(which is interpreted as relative to the current folder). The +default is <filename>kdebug.dbg</filename>.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Apart from this, you can also tick the checkbox <guilabel>Abort +on fatal errors</guilabel>. In this case, if a diagnostic message with +the severity level <computeroutput>KDEBUG_FATAL</computeroutput> is +output, the application aborts with a SIGABRT after outputting the +message.</para> + +<para>When you close the dialog by pressing <guibutton>OK</guibutton>, +your entries apply immediately and are saved in +<filename>kdebugrc</filename>. When you press +<guibutton>Cancel</guibutton>, your entries are discarded and the old +ones are restored.</para> + +<para>Credits to Kalle Dalheimer for the original version of +&kdebugdialog;</para> + +</chapter> + +&documentation.index; +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-general-insert-case: lower +sgml-shorttag: t +End: +--> + + diff --git a/doc/kdeprint/Makefile.am b/doc/kdeprint/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kdeprint/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kdeprint/add-printer-wiz.docbook b/doc/kdeprint/add-printer-wiz.docbook new file mode 100644 index 000000000..6b6ada4ea --- /dev/null +++ b/doc/kdeprint/add-printer-wiz.docbook @@ -0,0 +1,290 @@ +<chapter id="add-printer-wizard-2"> +<title>The <quote>Add Printer Wizard</quote> for &CUPS;</title> + +<para>Clicking on the leftmost icon on the toolbar +<inlinemediaobject><imageobject> <imagedata +fileref="cr32-action-wizard.png" format="PNG"/></imageobject> +</inlinemediaobject> in the upper part of the window starts the +<quote>Add Printer Wizard</quote>.</para> + +<para>This wizard steps you through various screens to install a new +printer. At present this Wizard works for &CUPS; and the +<acronym>RLPR</acronym> environment module. The number of steps depend +on the actual print-subsystem which is active and available to you on +your box.</para> + +<sect1> +<title>Starting</title> + +<para>The welcome screen informs you that you can go back any time to +change a setting. </para> + +<screenshot> +<screeninfo>The &kdeprint; wizard introduction screen</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsaddprinterwizard1.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The introduction screen of the printer wizard</phrase></textobject> +</mediaobject> +</screenshot> + +</sect1> +<sect1 id="backend-selection"> +<title>Backend Selection</title> + +<para>Choose the <quote>backend</quote> protocol that &CUPS; is supposed to +use with your new printer. There are:</para> + +<itemizedlist> +<listitem> +<para>local printer (serial, parallel, <acronym>USB</acronym>)</para> +</listitem> +<listitem> +<para>remote <acronym>LPD</acronym> queue</para> +</listitem> +<listitem> +<para><acronym>SMB</acronym> shared printer (&Windows;)</para> +</listitem> +<listitem> +<para>Network Printer (<acronym>TCP</acronym>, &HP; JetDirect, +AppSocket)</para> +</listitem> +<listitem> +<para>Network printer with &IPP; (&IPP;/<acronym>HTTP</acronym>)</para> +</listitem> +<listitem> +<para>File printer</para> +</listitem> +<listitem> +<para>serial fax /modem printer</para> +</listitem> +<listitem> +<para>Class of Printers</para> +</listitem> +</itemizedlist> + +<para>If some choices are grayed out, they are not available. For +example, you may have no FAX backend software or no modem installed to +use it.</para> + +<screenshot> +<screeninfo>Choosing your Printer system</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsaddprinterwizard2_backendselection.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Choosing your Printer System</phrase></textobject> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="direct-network-settings"> +<title>Direct Network Setting</title> + +<para>The contents of your next screen is dependent on your choice in +the previous screen. If you know the details, just type them in to +configure your network settings directly.</para> + +<para>In other cases the wizard can scan the network for you, to help you +decide which setting could be useful. </para> + +<screenshot> +<screeninfo>&kdeprint; wizard network scan</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsaddprinterwizard3_networkscan.png" +format="PNG"/></imageobject> +<textobject> +<phrase>In the &kdeprint; wizard, you can enter network details +directly, or you can scan the network +automatically.</phrase></textobject> +</mediaobject> +</screenshot> + +</sect1> +<sect1 id="information-retrieval-by-network-scanning"> +<title>Information Retrieval by Scanning the Network</title> + +<para>If you use one of the network connections (remote +<acronym>LPD</acronym>, <acronym>SMB</acronym>, remote &CUPS;, network +printer with &IPP;), you have an option for scanning the network. Be careful +when applying this; in some environments network scanning is considered +to be hostile and harmful!</para> + +<para>In the case of <acronym>SMB</acronym>, &kdeprint; will use the +Samba utilities <command>nmblookup</command> and +<command>smbclient</command> (which need to be installed for this to +work) to retrieve the information it presents in a tree +structure.</para> + +<para>In the case of &IPP; (Port 631) and <acronym>TCP</acronym> +Network/AppSocket (Port 9100) &kdeprint; will try to open the port and, +if successful, send an <command>ipp-get-printer-attribute</command> +request to the printer. For newer &HP; printers the latter usually +works, because they support both AppSocket and &IPP;.</para> + +<para>Some printers or manufacturers use other port numbers for direct +TCP/IP printing. You may need to look up which one to use. The +<guilabel>Settings</guilabel> button in the dialog lets you configure +your scan, including <acronym>IP</acronym> addresses, ports and +timeout to use.</para> + +<para>Once again: be careful not to be mistaken for an intruder on +your network, if you use the scanning technique.</para> + +<screenshot> +<screeninfo>&kdeprint; wizard network configuration dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsaddprinterwizard4_networkscan_config.png" +format="PNG"/></imageobject> +<textobject> +<phrase>In the &kdeprint; wizard, you can enter parameters to have the +wizard scan parts of your network.</phrase></textobject> +</mediaobject> +</screenshot> + +</sect1> +<sect1 id="printer-model-selection"> +<title>Printer Model Selection</title> + +<para>The hardest part is probably the <quote>Printer Model +Selection</quote>. In former years the situation was difficult, because +there were hardly any drivers to find. The difficulty now is there are too +many; though some of them are very good, many are quite broken. </para> + +<para>If you have a current <quote>database</quote> of available drivers +on your system, select the manufacturer in the left part of the window +first, then the device model in the right part. This split window shows +all &PPD;s found by &CUPS; in its standard repository of installable +&PPD;s. This repository normally is <filename +class="directory">/usr/share/cups/model/</filename>. If you want your +driver to be found automatically by &CUPS; and &kdeprint;, place it in +there.</para> + +<!-- Insert Screenshot here: --> + +</sect1> + +<sect1 id="driver-selection"> +<title>Driver Selection</title> + +<para>On the next screen you will see a description of the driver +selected previously. This description is extracted from the actual &PPD; +used.</para> + +<warning> +<para>For a real &PostScript; printer <emphasis>never</emphasis> try to +install a <quote>Foomatic</quote> or <quote>Gimp-Print</quote> &PPD;, +even if it is offered. You won't be happy with it. Instead find the +original &PPD; from the manufacturer, preferably the one written for +&Windows; NT and use it. </para> +</warning> + +<para>Some &Linux; distributions have supplied for &CUPS; every +possible combination of <application>Ghostscript</application> filters +and <quote>foomatic</quote> &PPD; files they could find on the net. +Many of these are quite useless; they were generated a year ago, when +the people at <ulink +url="http://www.linuxprinting.org">www.linuxprinting.org</ulink> began +their first experiments with supplying third party &PPD;s for +&CUPS;. Although dubbed <quote>Alpha</quote> at the time, these +started to take on a life of their own and can now be found at various +places on the net, doing &CUPS; no favors.</para> + +<para>If you are not sure which ones to use go to:</para> + +<itemizedlist> +<listitem> +<para><ulink +url="http://www.linuxprinting.org">http://www.linuxprinting.org</ulink> +</para> +</listitem> + +<listitem> +<para> +<ulink url="http://www.cups.org">http://www.cups.org</ulink> +</para> +</listitem> +</itemizedlist> + +<para>And ask for help. At a later stage, a document detailing the +differences between the different driver and &PPD; models will appear at +<ulink +url="http://kdeprint.sourceforge.net">http://kdeprint.sourceforge.net/</ulink> +Watch out for this!</para> + +<para>Via the <guibutton>Other...</guibutton> button you are able to +retrieve any &PPD; located somewhere on your available file +system.</para> + +<!-- Insert Screenshot here: --> + +</sect1> +<sect1 id="printer-test-and-finding-settings"> +<title>Printer Test and Finding the Right Settings</title> + +<para>Specify your first driver settings now. The most important one is the +default paper size. In many cases this is set to +<quote>Letter</quote>. If you live in an <quote>A4</quote> +country and don't want your first test page to jam: now is the time to +prevent this. </para> + +<para>You are ready to start a test print. Hit the +<guibutton>Test</guibutton> button.</para> + +<!-- Insert Screenshot here: --> + +</sect1> + +<sect1 id="banner-selection"> +<title>Banner Selection</title> + +<para>The last but one screen lets you select whether you want banners, and +which ones you want to use, to mark the beginning and/or end of every printjob +on that printer. You can also select and deselect banners before printing +in the job options dialogs.</para> + +<para>If you need to use custom banners, copy them into <filename +class="directory">/usr/share/cups/banners/</filename> to make them +available for selection. They must be &PostScript; files, +however.</para> + +<!-- Insert Screenshot here: --> + +</sect1> + +<sect1 id="baptizing-your-printer"> +<title>Finally: Baptizing Your New Printer</title> + +<para>The last screen lets you insert a name for your new +printer.</para> + +<para>The name must start with a letter and may contain numbers and +underscores with a maximum size of 128 characters. Conform to this if you +want to avoid erratic behavior of your &CUPS; daemon. The printer +names in &CUPS; are <emphasis>not</emphasis> case sensitive! This is a +requirement of &IPP;. So the names <systemitem +class="resource">DANKA_infotec</systemitem>, <systemitem +class="resource">Danka_Infotec</systemitem> and <systemitem +class="resource">danka_infotec</systemitem> all represent the same +printer.</para> + +<!-- Insert Screenshot here: --> + +</sect1> + +<sect1 id="final-confirmation-screen"> +<title>The Final Confirmation Screen</title> + +<para> +<!-- Insert Screenshot here: --> +</para> + +</sect1> + +</chapter> diff --git a/doc/kdeprint/cr32-action-wizard.png b/doc/kdeprint/cr32-action-wizard.png Binary files differnew file mode 100644 index 000000000..b00db2499 --- /dev/null +++ b/doc/kdeprint/cr32-action-wizard.png diff --git a/doc/kdeprint/cups-config.docbook b/doc/kdeprint/cups-config.docbook new file mode 100644 index 000000000..ff286e632 --- /dev/null +++ b/doc/kdeprint/cups-config.docbook @@ -0,0 +1,2072 @@ +<chapter id="cups-configuration"> +<title>Print Server Configuration: CUPS</title> + +<para>Start the print server configuration (now that you have chosen +&CUPS;, this is equivalent to the configuration of the &CUPS; daemon) by +clicking on the appropriate button. You can find it by moving the mouse +slowly over the buttons and reading the tooltips. It should be the 11th +from the left , or third from the right; its icon is a +<guiicon>wrench</guiicon>.</para> + +<para>The &CUPS; Server Configuration window pops up. It gives you a +structured view of all the settings that apply to the &CUPS; daemon. The +configuration file for that daemon is normally located in +<filename>/etc/cups/cupsd.conf</filename>. This is a plain +<acronym>ASCII</acronym> file with a syntax similar to the configuration +file of the <application>Apache</application> web server. It is a good +idea to create a backup copy, just in case something goes wrong with the +configuration through &kdeprint;/&CUPS; Server Configuration +dialogs:</para> + +<screen><userinput><command>cp</command> <filename>/etc/cups/cupsd.conf</filename> <filename>/etc/cups/cupsd.conf.bak</filename></userinput></screen> + +<para>As this graphical user interface to edit the configuration file is +such a new feature, you should have the second chance of resorting to +the original file. So back it up, please.</para> + +<sect1 id="quick-help"> +<title>Quick Help</title> + +<para>One very nice feature is the <quote>Quick Help</quote> +available. If you click on the little question mark (<guiicon>What's +this?</guiicon>) on your window title bar, you'll see the cursor +changing its form. Now click on a <command>cupsd</command> +configuration setting field to find out what it means and what your +options are. In most cases you should understand the meaning +immediately, otherwise turn to the excellent &CUPS; documentation. (If +your &CUPS; Daemon is running, you have it online on your own host at +<ulink +url="http://localhost:631/documentation.html">http://localhost:631/documentation.html</ulink>.</para> +<para>If &CUPS; is not running, but installed on your system you could +find it in your own host's file system. The exact location depends on +your &OS;, but on &Linux; the default is <filename +class="directory">/usr/share/doc/cups/</filename> or +<filename class="directory"> +/usr/share/doc/cups/documentation.html</filename>.</para> + +</sect1> +<sect1 id="longer-help"> +<title>Longer Help</title> + +<para>For the best, most detailed and most recent information you should +always refer to the original &CUPS; documentation. &CUPS; is, much like +&kde; in a rapid development process. There are constantly new features +being added. New features might for times be only configurable by +directly editing the configuration files. The &kdeprint; &GUI; might not +have caught up with &CUPS; development.</para> + +<para>Just in case you want to look at the original configuration files +of your &CUPS; system -- they are here:</para> + +<note> +<para>These paths are based on the default installation. Your &OS; +may have installed them to a different prefix, for example, <filename +class="directory">/usr/local/</filename>, but the hierarchy should +still match that shown below.</para> +</note> + +<variablelist> +<varlistentry> +<term><filename class="directory">/etc/cups/</filename></term> +<listitem> +<para>The folder with the configuration files</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>/etc/cups/cupsd.conf</filename></term> +<listitem> +<para>The configuration file for the &CUPS; daemon</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>/etc/cups/printers.conf</filename></term> +<listitem> +<para>The configuration file that contains the information about your +locally installed printers.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">/etc/cups/ppd/</filename></term> +<listitem> +<para>The folder with &PPD; files of your installed +printers.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>The following links only work if your &CUPS; daemon is up and +running. To access all the original &CUPS; documentation, go +to:</para> + +<variablelist> +<varlistentry> +<term><ulink url="http://localhost:631/documentation.html"> +http://localhost:631/documentation.html</ulink></term> +<listitem> +<para>A page with all the links to the other documents.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://localhost:631/sam.html"> +http://localhost:631/sam.html</ulink></term> +<listitem> +<para>Direct access to the &CUPS; Software Administrator Manual +in <acronym>HTML</acronym> format.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://localhost:631/sam.pdf"> +http://localhost:631/sam.pdf</ulink></term> +<listitem> +<para>Direct access to the &CUPS; Software Administrator Manual in +<acronym>PDF</acronym> format.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://www.cups.org/documentation.html"> +http://www.cups.org/documentation.html</ulink></term> +<listitem> +<para>The latest on line documentation from the &CUPS; web +site.</para> +</listitem> +</varlistentry> +</variablelist> +<para>The following links give you access to the same files (probably +icons and graphics will be missing) even if your CUPS daemon is not up +and running. You need, however, CUPS installed on your system. (Some +distributions might place the files somewhere else -- you're on your +own then to find out where...) To access all the original CUPS +documentation, go to:</para> + +<para>This documentation is available even when the &CUPS; daemon is +not installed, although you may find images and icons are missing when +you view the <acronym>HTML</acronym> files.</para> + +<para>As noted above, the hierarchy below should be intact, but your +&OS; may have installed &CUPS; to a different location.</para> + +<variablelist> +<varlistentry> +<term><filename>/usr/share/doc/cups/documentation.html</filename></term> +<listitem> +<para>A page with all the links to the other documents.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>/usr/share/doc/cups/sam.html</filename></term> +<listitem> +<para>Direct access to the &CUPS; Software Administrator Manual in +<acronym>HTML</acronym> format.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>/usr/share/doc/cups/sam.pdf</filename></term> +<listitem> +<para>Direct access to the &CUPS; Software Administrator Manual in +<acronym>PDF</acronym> format.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>There are a few WebSites and Newsgroups discussing &CUPS; (and +&Linux; Printing in General) and giving help to newbies at:</para> + +<variablelist> +<varlistentry> +<term><ulink url="http://www.cups.org/newsgroups.php"> +http://www.cups.org/newsgroups.php</ulink></term> +<listitem> +<para>The &CUPS; website.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://www.linuxprinting.org/newsportal/"> +http://www.linuxprinting.org/newsportal/</ulink></term> +<listitem> +<para>LinuxPrinting.org, the home of the Linuxprinting HOWTO and the +&Linux; Printer Database</para> +</listitem> +</varlistentry> +</variablelist> + +<para>And finally, there will be a WebSite for &kdeprint; and related +documentation, at <ulink url="http://kdeprint.sourceforge.net/"> +http://kdeprint.sourceforge.net/</ulink></para> + +<para>In the next section I will step you through most of the +configuration options of &kdeprint; with &CUPS;.</para> + +</sect1> +<sect1 id="explaining-different-gui-elements"> +<title>Explaining different elements of the &GUI;</title> + +<sect2> +<title>Upper Window: View on Printers, both Real and Virtual</title> + +<para>This section is not yet complete</para> + +<itemizedlist> +<listitem> +<para>Tree view, icon view and list view</para> +</listitem> +<listitem> +<para>The icons of the task bar</para> +</listitem> +<listitem> +<para>Different fonts for different printers</para> +</listitem> +<listitem> +<para>Different printer icons mean different things</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Lower Window: Tabbed View of Details</title> + +<para>This section is not yet complete.</para> + +<itemizedlist> +<listitem> +<para>The icons of the task bar</para> +</listitem> +<listitem> +<para>The Tabs</para> +</listitem> +<listitem> +<para>Changing printer settings</para> +</listitem> +</itemizedlist> + +</sect2> + +</sect1> + + +<sect1 id="welcome-to-cups-server-configuration"> +<title>Welcome to the &CUPS; Server Configuration</title> + +<para>This is the Welcome Screen for your server configuration +dialogs. Clicking onto one of the items of the tree view on left +side of the screen opens the appropriate part of the configuration +settings.</para> + +<para>Every setting has a default value. The defaults let &CUPS; +normally work as a fully functional client. The clients listen on +TCP/IP Port 631 for infos broadcast by &CUPS; servers on the +<acronym>LAN</acronym>. This information let the clients print +immediately after receiving them, without installing any driver or +configuring any printer on the clients.</para> + +<para>To configure a &CUPS; server (which is broadcasting its service +to the <acronym>LAN</acronym>) you need to change settings from the +defaults.</para> + +<para>The dialog to configure the &CUPS; server: welcome screen. </para> +<screenshot> +<screeninfo>CUPS server configuration dialog: welcome screen</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration1_welcome.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The dialog to configure the &CUPS; server: welcome +screen</phrase></textobject> +<caption><para>The dialog to configure the &CUPS; server: welcome +screen</para></caption> +</mediaobject> +</screenshot> + +<para>To select the default setting of any item just enable the +checkbox on the right side of the screen. To set an item to a +different value, disable the checkbox and then go on to do the setting +you want on the left side of the screen.</para> + +<para>The complete server configuration includes:</para> + +<itemizedlist> +<listitem> +<para><link linkend="server-general-configuration"><guilabel>Server</guilabel> +General Configuration</link></para> +</listitem> +<listitem> +<para><link linkend="server-logging-configuration">Server +<guilabel>Log</guilabel>ging Configuration</link></para> +</listitem> +<listitem> +<para><link +linkend="server-directories-configuration">Server +<guilabel>Folders</guilabel> and Path Definitions</link></para> +</listitem> +<listitem> +<para><link linkend="server-configuration">Server +<guilabel>HTTP</guilabel> Configuration</link></para> +</listitem> +<listitem> +<para><link linkend="server-encryption-support-configuration">Server +<guilabel>Encryption</guilabel> and Certificate Support +Configuration</link></para> +</listitem> +<listitem> +<para><link linkend="server-miscellaneous-configuration">Server +<guilabel>Misc</guilabel>ellaneous Configuration</link></para> +</listitem> +<listitem> +<para><guilabel>Network</guilabel> General Configuration</para> +</listitem> +<listitem> +<para><link linkend="network-clients-configuration">Network +<guilabel>Clients</guilabel> Configuration</link></para> +</listitem> +<listitem> +<para><link +linkend="browsing-general-configuration"><guilabel>Browsing</guilabel> +General Configuration</link></para> +</listitem> +<listitem> +<para><link linkend="browsing-connection-configuration">Browsing +<guilabel>Connection</guilabel> Configuration</link></para> +</listitem> +<listitem> +<para><link +linkend="browsing-masks-configuration">Browsing +<guilabel>Masks</guilabel> Configuration</link></para> +</listitem> +<listitem> +<para><link linkend="browsing-timeouts-configuration">Browsing +<guilabel>Timeouts</guilabel> Configuration</link></para> +</listitem> +<listitem> +<para><link linkend="browsing-relay-configuration">Browsing +<guilabel>Relay</guilabel> Configuration</link></para> +</listitem> +<listitem> +<para><link +linkend="security-configuration"><guilabel>Security</guilabel> +Configuration</link></para> +</listitem> +</itemizedlist> + +<para>Each of these configuration items will be described in the +following sections of the manual.</para> + +</sect1> + +<sect1 id="server-general-configuration"> +<title>Server General Configuration</title> + +<para>The server general configuration is done on this screen. It +includes:</para> + +<itemizedlist> +<listitem><para><guilabel>Server name</guilabel></para></listitem> +<listitem><para><guilabel>Administrators email</guilabel></para></listitem> +<listitem><para><guilabel>Server user</guilabel></para></listitem> +<listitem><para><guilabel>Server group</guilabel></para></listitem> +<listitem><para><guilabel>Remote user name</guilabel></para></listitem> +</itemizedlist> + +<para>The tab window to configure the &CUPS; server general settings +lets you the change the default values. Click on the little question +mark and then on one of the fields to get a <quote>Quick Help</quote> +about the meaning of the setting.</para> + +<para>If you are unsure, leave alone and turn to the original &CUPS; +documentation first. If your &CUPS; daemon is already running, it is +readable from the &konqueror; by pointing it to &URL; <ulink +url="http://localhost:631/documentation.html"> +http://localhost:631/documentation.html</ulink>.</para> + +<para>There, first <quote>make friends</quote> with the Software +Administrator Manual. Otherwise, for example, if the &CUPS; daemon is +not running, try looking in your local file system, by default at +<filename class="directory">/usr/share/doc/cups/</filename> or +<filename>/usr/share/doc/cups/documentation.html</filename>.</para> + +<screenshot> +<screeninfo>&CUPS; server general configuration dialog: ServerName, AdminMail, +ServerUser, ServerGroup, RemoteUserName</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration2_general.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The dialog to configure the &CUPS; server general settings: +ServerName, AdminMail, ServerUser, ServerGroup, RemoteUserName +</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Server Name</guilabel></term> +<listitem> +<para>The hostname of your server, as advertised to the world. By +default, &CUPS; will use the hostname of the system. To set the +default server usd by clients, see the +<filename>client.conf</filename> file.</para> + +<informalexample> +<para>For example, enter <userinput>myhost.domain.com</userinput></para> +</informalexample> + +<para>This is the hostname that is reported to clients. Should you +ever encounter strange problems in accessing the server, put here its +<acronym>IP</acronym> address for troubleshooting. This way you +eliminate any potential name resolution problems; and you can more +easily nail the real problem down.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Administrators email</guilabel></term> +<listitem> +<para>This is the email address to send all complaints or problems +to. By default &CUPS; will use <quote>root@hostname</quote>.</para> + +<informalexample> +<para>For example, enter +<userinput>[email protected]</userinput>.</para> +</informalexample> + +<note> +<para>Contrary to what the quickhelp suggests, it is also legal to +send an email full of praise and enthusiasm about &CUPS; and +&kdeprint; to the server administrator.</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server User</guilabel></term> +<listitem> +<para>The user the server runs under. Normally this must be +<systemitem class="username">lp</systemitem>, however you can +configure things for another user if needed.</para> + +<note> +<para>The server must be initially run as root to support the default +<acronym>IPP</acronym> port of 631. It changes users whenever an +external program is run.</para> +</note> + +<informalexample> +<para>Enter for example <userinput>lp</userinput>.</para> +</informalexample> + +<para>This is the &UNIX; user account for filters and +<acronym>CGI</acronym> programs to run under. <acronym>CGI</acronym> +programs are responsible for showing you the nice web administration +interface accessible via <ulink +url="http://localhost:631/">http://localhost:631/</ulink>).</para> + +<warning> +<para>There is no need to set the <guilabel>User</guilabel> directive +to <systemitem class="username">root</systemitem>, so never do this, +as it only involves dangers. Should anyone discover security +vulnerabilities in one of the used file filters, printer drivers or +<acronym>CGI</acronym> programs, he could remotely execute arbitrary +commands on your system with root user privileges. Always use an +unprivileged account for the server directive +<guilabel>User</guilabel>.</para> +</warning> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server group</guilabel></term> +<listitem> +<para>The group the server runs under. Normally this must be +<systemitem class="groupname">sys</systemitem>, however you can +configure things for another group as needed.</para> + +<informalexample> +<para>Enter for example <userinput>sys</userinput>.</para> +</informalexample> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remote user name</guilabel></term> +<listitem> +<para>The name of the user assigned to unauthenticated accesses from +remote systems. By default <userinput>remroot</userinput>.</para> + +<para>This name will appear in log files and in queries about the job +owner &etc;, for all resources and locations of the &CUPS; server that +are configured to allow access <emphasis>without</emphasis> +authentication. Authenticated entries will carry the authenticated +names.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="server-logging-configuration"> +<title>Server Logging Configuration</title> + +<para>The server logging configuration is done on this screen. It +includes:</para> + +<itemizedlist> +<listitem><para><guilabel>Access log file</guilabel> setting</para></listitem> +<listitem><para><guilabel>Error log file</guilabel> setting</para></listitem> +<listitem><para><guilabel>Page log</guilabel> file setting</para></listitem> +<listitem><para><guilabel>Log level</guilabel> setting</para></listitem> +<listitem><para><guilabel>Max log file size</guilabel> +setting</para></listitem> +</itemizedlist> + +<para>This is an important screen for you. Should you ever encounter +problems: here is the place to set the Log level to +<quote>debug</quote>, restart the &CUPS; daemon and then look at the +Error log file defined here for entries that might give you an insight +to the trouble.</para> + +<screenshot> +<screeninfo>&CUPS; server configuration dialog: <guilabel>Server +logging</guilabel> </screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration3_logging.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The dialog to configure the &CUPS; server: <guilabel>Server +logging</guilabel></phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Access log file</guilabel></term> +<listitem> +<para>This is where accesses to the server are logged. If this does +not start with a leading <literal>/</literal>, then it is assumed to +be relative to the server root.</para> + +<para>You can also use the special name <userinput>syslog</userinput> +to send the output to the syslog file or daemon.</para> + +<informalexample> +<para>Enter a path, for example +<userinput><filename>/var/log/cups/acces_log</filename></userinput>.</para> +</informalexample> + +<para>The format of this file is stored in the so-called <quote>Common +Log Format</quote>. This way you can use programs such as +<application>Webalyzer</application> or any other Web access reporting +tool to generate reports on the &CUPS; server activities.</para> + +<para>To include the server name in the file name use a +<token>%s</token> in the name. Example: +<userinput><filename>/var/log/cups/access_log-%s</filename></userinput>.</para> + +<screen><prompt>kurt@transmeta:~ ></prompt><userinput><command>tail</command> <parameter>/var/log/cups/access_log</parameter></userinput> +<computeroutput> +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST /printers/ HTTP/1.1" 200 109 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST /admin/ HTTP/1.1" 401 0 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST / HTTP/1.1" 200 210 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "GET /ppd/DANKA_P450.ppd HTTP/1.1" 200 51021 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST /jobs/ HTTP/1.1" 200 246 +10.160.16.45 - - [04/Aug/2001:20:11:39 +0100] "GET /printers/DANKA_P450 HTTP/1.0" 200 0 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST / HTTP/1.1" 200 80 +127.0.0.1 - - [04/Aug/2001:20:11:39 +0100] "POST / HTTP/1.1" 200 139 +10.160.16.45 - - [04/Aug/2001:20:11:40 +0100] "GET /cups.css HTTP/1.0" 200 198 +127.0.0.1 - - [04/Aug/2001:20:11:40 +0100] "POST / HTTP/1.1" 200 139 +10.160.16.45 - - [04/Aug/2001:20:11:39 +0100] "GET /printers/DANKA_P450 HTTP/1.0" 200 7319 +10.160.16.45 - - [04/Aug/2001:20:11:40 +0100] "GET /images/title-logo.gif HTTP/1.0" 200 5729 +</computeroutput></screen> + +<para>You see a separate line for each single access, showing the +<acronym>IP</acronym> address of the accessing client, date and time +of access, method of access (<command>POST</command> or +<command>GET</command>), the requested ressource, the &HTTP; version +used by the client, status code and the number of transferred +bytes. Status code <errorcode>200</errorcode> means +<errorname>successful-OK</errorname> the <errorcode>401</errorcode> in +the above example was an <errorname>unauthorized access</errorname> +which was denied. For a detailed explanation of the log format go to +<ulink url="http://localhost:631/sam.html#7_6_1">the &CUPS; Software +Administrator Manual</ulink>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Error log file</guilabel></term> +<listitem> +<para>If this does not start with a leading <literal>/</literal>, then +it is assumed to be relative to the server root. The default setting +is <filename>/var/log/cups/error_log</filename>.</para> + +<para>You can also use the special name <userinput>syslog</userinput> +to send the output to the syslog file or daemon.</para> + +<informalexample> +<para>Enter the path, for example +<userinput><filename>/var/log/cups/error_log</filename></userinput>.</para> +</informalexample> + +<para>The error log excerpt below shows you the part logged for printing the test page +with the default setting of <guilabel>Log level</guilabel> to +<quote>info</quote>. For an explanation of the <guilabel>Log +Level</guilabel> setting see further below.</para> + +<screen><prompt>kurt@transmeta:~ ></prompt><userinput><command> tail </command> <parameter>/var/log/cups/error_log</parameter></userinput> +<computeroutput> +I [04/Aug/2001:23:15:10 +0100] Job 213 queued on 'DANKA_P450' by 'root' +I [04/Aug/2001:23:15:10 +0100] Started filter /usr/lib/cups/filter/pstops (PID 18891) for job 213. +I [04/Aug/2001:23:15:10 +0100] Started backend /usr/lib/cups/backend/lpd (PID 18892) for job 213. +</computeroutput></screen> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Page log file</guilabel></term> +<listitem> +<para>If this does not start with a leading <literal>/</literal> then +it is assumed to be relative to the server root. The default is +<filename>/var/log/cups/page_log</filename></para> + +<para>You can also use the special name <userinput>syslog</userinput> +to send the output to the syslog file or daemon.</para> + +<informalexample> +<para>Enter the path, for example +<userinput><filename>/var/log/cups/page_log</filename></userinput>.</para> +</informalexample> +<para>The page log file has a line for every single page of every job +printed.</para> + +<para> Here is what some entries look like:</para> + +<screen><prompt>kurt@transmeta:~ ></prompt><userinput><command> tail </command> <parameter>/var/log/cups/page_log</parameter></userinput> +<computeroutput> +GIMP_print_stp_HP kdetest 201 [03/Aug/2001:03:18:03 +0100] 4 1 +GIMP_print_stp_HP kdetest 201 [03/Aug/2001:03:18:03 +0100] 5 1 +GIMP_print_stp_HP kdetest 202 [03/Aug/2001:11:46:49 +0100] 1 1 +GIMP_print_stp_HP kdetest 203 [03/Aug/2001:11:46:54 +0100] 1 1 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 1 33 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 2 33 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 3 33 +DANKA_infotec_P450 kurt 204 [04/Aug/2001:03:29:00 +0100] 4 33 +DANKA_infotec_P450 root 205 [04/Aug/2001:19:12:34 +0100] 1 14 +DANKA_infotec_P450 root 206 [04/Aug/2001:19:15:20 +0100] 1 1 +</computeroutput></screen> + +<para>In this excerpt of the file you find information on the name of +the printers (<systemitem +class="resource">GIMP_print_stp_HP</systemitem> and <systemitem +class="resource">DANKA_infotec_P450</systemitem>) used through this +server, the user names (<systemitem +class="username">kdetest</systemitem>, <systemitem +class="username">kurt</systemitem> and <systemitem +class="username">root</systemitem>), the job-IDs (<quote>201</quote> +to <quote>205</quote>), time of printing, page number inside the job +and the number of copies for the pages. For example, job-ID 204 had 4 +pages and 33 copies printed, job-ID 205 had 14 copies of just 1 page) +.</para> + +<note> +<para>&CUPS; is dependent (for its calculation of the number of pages +in a job) on passing the &PostScript; through the +<quote>pstops</quote> filter. See the <link +linkend="architecture-diagram">&kivio; Flowchart</link> on the &CUPS; +filter architecture for an idea about were this filter fits into the +whole printing process). More, <command>pstops</command> depends for +the counting on a <acronym>DSC</acronym> conforming +(<acronym>DSC</acronym> is Document Structuring Conventions, a +standard defined by Adobe) to be sent by the client. In most cases +this is working.</para> + +<para>However, this page accounting does not work for any +<quote>raw</quote> printer queues (as those, by definition, don't use +any filtering on the &CUPS; host and are by-passing +<command>pstops</command>.) Every job going through a +<quote>raw</quote> queue is counted as a 1-page-job (with possibly +multiple copies). This is especially true for all Jobs send from +&Microsoft; &Windows; clients via <application>Samba</application> to +the &CUPS; server, as those jobs are already arriving in the correct +format for the printer, because the clients use the original printer +driver.</para> +</note> + +<note> +<para>I am still looking for someone who will write a nice &CUPS; page +log analysing tool. It should generate a report with a graphical +output similar to the <application>Webalizer</application>'s access +log reports. This way you could have nice statistics to be used for +accounting about usage of printers, load dependent on daytime or +weekday, users &etc; Anyone?</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Log level</guilabel></term> +<listitem> +<para>This setting controls the number of messages logged to the error +log file. It can be one of the following:</para> + +<variablelist> +<varlistentry> +<term>debug2</term> +<listitem> +<para>Log everything.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>debug</term> +<listitem> +<para>Log almost everything.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>info</term> +<listitem> +<para>Log all requests and state changes.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>warn</term> +<listitem> +<para>Log errors and warnings.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>error</term> +<listitem> +<para>Log only errors.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>none</term> +<listitem> +<para>Log nothing.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>If you need to troubleshoot (or if you want to study the inner +workings of &CUPS;), set the log level to debug or debug2. Then the +error_log will have a lot more entries (not just errors, but also +informational entries).</para> + +<para>You can use this to watch <quote>live</quote> what &CUPS; is +doing when you send a print job. In a &konsole; type:</para> + +<screen><prompt>kurt@transmeta:~ ></prompt><userinput><command>tail</command> <option>-f</option> <option>-n</option><parameter>100</parameter> <parameter>/var/log/cups/error_log</parameter></userinput></screen> + +<para>This will give you the last 100 lines (<option>-n</option> +<parameter>100</parameter>) of the file onto the screen and a +<quote>realtime</quote> update (<option>-f</option>)of what is +happening. The following listing shows the printing of a test page +(some pieces have been cut off for space reasons... Try it yourself if +you need more info):</para> + +<screen><computeroutput> +I [04/Aug/2001:23:15:12 +0100] Job 214 queued on 'DANKA_P450' by 'root' +D [04/Aug/2001:23:15:12 +0100] StartJob(214, 08426fe0) +D [04/Aug/2001:23:15:12 +0100] StartJob() id = 214, file = 0/1 +D [04/Aug/2001:23:15:12 +0100] job-sheets=none,none +D [04/Aug/2001:23:15:12 +0100] banner_page = 0 +D [04/Aug/2001:23:15:12 +0100] StartJob: argv = "DANKA_P450","214","root","KDE Print Test", +[....] +D [04/Aug/2001:23:15:12 +0100] StartJob: envp = "PATH=/usr/lib/cups/filter:/bin:/usr/bin", [....] +D [04/Aug/2001:23:15:12 +0100] StartJob: statusfds = 5, 6 +D [04/Aug/2001:23:15:12 +0100] StartJob: filterfds[1] = 7, -1 +D [04/Aug/2001:23:15:12 +0100] StartJob: filter = "/usr/lib/cups/filter/pstops" +D [04/Aug/2001:23:15:12 +0100] StartJob: filterfds[0] = 8, 9 +D [04/Aug/2001:23:15:12 +0100] start_process("/usr/lib/cups/filter/pstops", [....] +I [04/Aug/2001:23:15:12 +0100] Started filter /usr/lib/cups/filter/pstops (PID 18991) for job 214. +D [04/Aug/2001:23:15:12 +0100] StartJob: backend = "/usr/lib/cups/backend/lpd" +D [04/Aug/2001:23:15:12 +0100] StartJob: filterfds[1] = -1, 7 +D [04/Aug/2001:23:15:12 +0100] start_process("/usr/lib/cups/backend/lpd", [....] +I [04/Aug/2001:23:15:12 +0100] Started backend /usr/lib/cups/backend/lpd (PID 18992) for job 214. +D [04/Aug/2001:23:15:12 +0100] Page = 595x842; 15,16 to 580,833 [....] </computeroutput></screen> + +<para>The lines tagged <quote>D</quote> at the beginning are debug +level entries, the ones tagged <quote>I</quote> are there in +<quote>info</quote> level.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Max log file size</guilabel></term> +<listitem> + +<para>Controls the maximum size of each log file before they are +rotated. Defaults to 1048576 (1 Mb). Set this to 0 to disable log +rotation.</para> + +<informalexample> +<para>Enter an size in bytes, for example <userinput>1048576</userinput></para> +</informalexample> + +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="server-directories-configuration"> +<title>Server Folders Configuration</title> + +<para>The dialog to configure the &CUPS; server. Different +folders are to be set here. Normally you don't need to change +anything in this section. In case you play around with fancy +(TrueType, &PostScript; or other) fonts on your system, this qis the +place to do the settings for using those fonts when printing. Server +folder settings include:</para> + +<itemizedlist> +<listitem> +<para><guilabel>Executables</guilabel>: where to find the server +executables</para> +</listitem> +<listitem> +<para><guilabel>Configuration</guilabel>: where to find the server +configuration files</para> +</listitem> +<listitem> +<para><guilabel>Data</guilabel>: where to find the server data +files</para> +</listitem> +<listitem> +<para><guilabel>Temporary files</guilabel>: where to put the server +temporary print files </para> +</listitem> +<listitem> +<para><guilabel>Temporary Requests</guilabel>: where to find the +server </para> +</listitem> +<listitem> +<para><guilabel>Font Path</guilabel>: where to find the +server fonts</para> +</listitem> +</itemizedlist> +<screenshot> +<screeninfo>&CUPS; server configuration dialog: &HTTP; configuration</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration4_directories.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The dialog to configure the &CUPS; server: &HTTP; configuration</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Executables</guilabel></term> +<listitem> +<para>The root folder for the scheduler executables. By default +this is <filename class="directory">/usr/lib/cups</filename> (or +<filename class="directory">/usr/lib32/cups</filename> on IRIX +6.5)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Configuration</guilabel></term> +<listitem> +<para>The root folder for the scheduler. By default, <filename +class="directory">/etc/cups</filename>.</para> +<para>On the authors SuSE system, this is <filename +class="directory">/usr/share/doc/cups</filename>. It contains all the +<acronym>HTML</acronym> or <acronym>PDF</acronym> documentation for +&CUPS; which is available through the Web interface at <ulink +url="http://localhost:631/documentation.html"> +http://localhost:631/documentation.html</ulink></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Data</guilabel></term> +<listitem> +<para>The root folder for the &CUPS; data files. By default this +is <filename class="directory">/usr/share/cups</filename></para> +<para>It contains such things as banners, charsets, data, drivers, +fonts, and <command>pstoraster</command> templates.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Temporary files</guilabel></term> +<listitem> +<para>The folder to put temporary files in. This folder must be +writable by the user defined on the previous screen. This defaults to +either <filename class="directory">/var/spool/cups/tmp</filename> or +the value of the <envar>TMPDIR</envar> environment variable.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Temporary Requests</guilabel></term> +<listitem> +<para>The folder where request files are stored. By default this +is <filename class="directory">/var/spool/cups</filename></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Font path</guilabel></term> +<listitem> +<para>The place to configure the &CUPS; server for handling your fancy +fonts (TrueType or &PostScript;). &CUPS; will look here for fonts to +embed in printfiles. This currently only affects the +<command>pstoraster</command> filter, and the default is <filename +class="directory">/usr/share/cups/fonts</filename>.</para> + +<para>To specify more than one folder, list them with double colons as +separator. Do it like this:</para> + +<informalexample> +<para><userinput>/path/to/first/fontdir/:/path/to/second/fontdir/:/path/to/last/fontdir/</userinput></para> +</informalexample> + +<para>For the Font path directive to work as intended, the application +that wants to print needs to:</para> + +<itemizedlist> +<listitem> +<para>Either correctly reference its desired fonts in the header of the +generated &PostScript;</para> +</listitem> +<listitem> +<para>Or embed the font into the &PostScript; file.</para> +</listitem> +</itemizedlist> + +<para><emphasis>Referencing</emphasis> the font by name leaves it up +to the <acronym>RIP</acronym> and print device to respect and actually +use it. <acronym>RIP</acronym> or printer <emphasis>can</emphasis> +only use the desired font, if it is available on the system.</para> + +<para> In the case of a &PostScript; printer, this needs to be a +printer-resident font. If the printers doesn't have this font, it will +try and replace it by an adequately similar font.</para> + +<para>In the case of a non &PostScript; printer, this is done by +&CUPS; and its <acronym>RIP</acronym>-ing filtering system. &CUPS; +will use the font path directive to grab the correct font when +<acronym>RIP</acronym>-ing the &PostScript; in the +<command>pstoraster</command> filter. </para> + +<para>In the case of a &PostScript; output device, &CUPS; is just +spooling the file (actually, it is passing it through the +<command>pstops</command> filter for accounting or n-up purposes), not +<quote>working</quote> on it. Therefore, if you print to a +&PostScript; printer it is solely the printer's responsibility to use +the font asked for. It can't, if the font is neither loaded into the +printer nor embedded in the &PostScript;. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +<sect1 id="server-configuration"> +<title>Server <acronym>HTTP</acronym> +Configuration</title> + +<para>The dialog to configure the &CUPS; server &HTTP; settings +is shown here. </para> +<para>&CUPS; server &HTTP; settings are the following ones: </para> +<itemizedlist> +<listitem><para>the <guilabel>Document folder</guilabel></para></listitem> +<listitem><para>the <guilabel>Default Language</guilabel></para></listitem> +<listitem><para>the <guilabel>Default Charset</guilabel></para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server &HTTP; settings +</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration5_HTTP.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; server &HTTP; settings +</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Document folder</guilabel></term> +<listitem> +<para>The root folder for &HTTP; documents that are served. By +default the compiled in folder, <filename +class="directory">/usr/share/cups/doc</filename></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default Language</guilabel></term> +<listitem> +<para>The default language, if not specified by the browser. If not +specified, the current locale is used.</para> +<informalexample> +<para>Use the two letter locale codes, for example +<userinput>en</userinput> or <userinput>de</userinput>.</para> +</informalexample> +<!-- available languages? --> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Default charset</guilabel></term> +<listitem> +<para>The default character set to use. If not specified, this +defaults to UTF-8. This can also be overridden directly in the +<acronym>HTML</acronym> documents.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="server-encryption-support-configuration"> +<title><guilabel>Server encryption support configuration</guilabel></title> + +<para>This is the dialog to configure the &CUPS; server security +settings. The server encryption support settings are these: </para> + +<itemizedlist> +<listitem><para><guilabel>Server certificate</guilabel>: the file to +read containing the server's certificate</para></listitem> +<listitem><para>Server key: the file to read containing the server's +key</para></listitem> +</itemizedlist> +<screenshot> +<screeninfo>&CUPS; server configuration dialog: security overview</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration6_encryption.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The dialog to configure the &CUPS; server: security settings</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Server certificate</guilabel></term> +<listitem> +<para>The file to read containing the server's certificate. Defaults +to <filename>/etc/cups/ssl/server.crt</filename>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server key</guilabel></term> +<listitem> +<para>The file to read containing the server's key. Defaults to +<filename>/etc/cups/ssl/server.key</filename></para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="server-miscellaneous-configuration"> +<title>Server Miscellaneous Configuration</title> + +<para>The dialog to configure the &CUPS; server miscellaneous settings +is shown here. The following server settings are done through this +screen:</para> + +<itemizedlist> +<listitem><para><guilabel>Preserve job history</guilabel>: whether to +preserve a job history for later re-view</para></listitem> +<listitem><para><guilabel>Preserve job files</guilabel>: whether to +preserve fully <acronym>RIP</acronym>-ed job files for later +re-print</para></listitem> +<listitem><para><guilabel>Printcap file</guilabel>: setting the name +of and the path to a printcap file</para></listitem> +<listitem><para><guilabel>RIP Cache</guilabel>: setting the size of +the <acronym>RIP</acronym> cache in memory</para></listitem> +<listitem><para><guilabel>Filter Limit</guilabel>: defining a filter +limit</para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server miscellaneous settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration7_miscellanious.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; server miscellaneous +settings</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Preserve job history (after completion)</guilabel></term> +<listitem> +<para>Whether or not to preserve the job history after a job is +completed, canceled, or stopped. The default is yes</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Preserve job file (after completion)</guilabel></term> +<listitem> +<para>Whether or not to preserve the job files after a job is +completed, canceled, or stopped. The default is no.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Printcap file</guilabel></term> +<listitem> +<para>The name of the printcap file. The default is no filename. +Leave this blank, to disable printcap file generation.</para> +<para>The printcap setting is only needed to satisfy older +applications in need of such a file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>RIP cache</guilabel></term> +<listitem> +<para>The amount of memory that each <acronym>RIP</acronym> should use +to cache bitmaps. The value can be any real number, followed by +<quote>k</quote> for kilobytes, <quote>m</quote> for megabytes, +<quote>g</quote>for gigabytes, or <quote>t</quote> for tiles, where +one tile is 256 x 256 pixels. The default value is 8m.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Filter limit</guilabel></term> +<listitem> +<para>Sets the maximum cost of all job filters that can be run at the +same time. A limit of 0 means no limit. A typical job may need a +filter limit of at least 200. Limits less than the minimum required +by a job force a single job to be printed at any time. The default +limit is 0 (unlimited).</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="network-general-configuration"> +<title>Network General Configuration</title> + +<para>The dialog to configure the &CUPS; server network settings is +shown here. It includes:</para> + +<itemizedlist> +<listitem><para><guilabel>Look for hostname on IP +addresses</guilabel></para></listitem> +<listitem><para><guilabel>Port</guilabel></para></listitem> +<listitem><para><guilabel>Max request size</guilabel></para></listitem> +<listitem><para><guilabel>Timeout</guilabel></para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server network settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration8_networkgeneral.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; server network +settings</phrase></textobject> +</mediaobject> +</screenshot> +<variablelist> +<varlistentry> +<term><guilabel>Look for hostname on IP addresses</guilabel></term> +<listitem> +<para>Whether or not to do lookups on <acronym>IP</acronym> addresses +to get a fully-qualified hostname. This defaults to off, for +performance reasons.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Port</guilabel></term> +<listitem> +<para>Enter here Ports and addresses that the server will listen to. +The default port 631 is reserved for the Internet Printing Protocol, +and is what we use here.</para> +<para>You can have multiple entries, to listen to more than one port +or address, or to restrict access.</para> +<note> +<para>Unfortunately, most web browsers don't support +<acronym>TLS</acronym> or &HTTP; upgrades for encryption. If you want +to support web-based encryption, you'll probably need to listen on +port 443, the <acronym>HTTPS</acronym> port.</para> +</note> +<para>Use the <guibutton>Add</guibutton> and +<guibutton>Remove</guibutton> buttons to add and remove entries from +the list.</para> +<informalexample> +<para>You can enter ports on their own, ⪚ +<userinput>631</userinput>, or hostnames with ports, ⪚ +<userinput>myhost:80</userinput> or <userinput>1.2.3.4:631</userinput>.</para> +</informalexample> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Max request size</guilabel></term> +<listitem> +<para>Controls the maximum size of &HTTP; requests and print files. +The default setting is 0, which disables this feature.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Timeout</guilabel></term> +<listitem> +<para>The timeout (in seconds) before requests time out. The default +is 300 seconds.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="network-clients-configuration"> +<title>Network Clients Configuration</title> + +<para>The dialog to configure the &CUPS; network client settings is +shown here. It includes:</para> + +<itemizedlist> +<listitem><para><guilabel>Accept "Keep Alive" +requests</guilabel></para></listitem> +<listitem><para>KeepAliveTimeout:</para> </listitem> +<listitem><para>MaxClients: </para></listitem> +</itemizedlist> +<screenshot> +<screeninfo>dialog to configure the &CUPS; network client settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration9_networkclients.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; network client settings</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Accept "Keep Alive" requests</guilabel></term> +<listitem> +<para>Whether or not to support the Keep-Alive connection option. The +default is on.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep alive timeout</guilabel></term> +<listitem> +<para>The timeout (in seconds) before Keep-Alive connections are +automatically closed. The default is 60 seconds.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Max number of clients</guilabel></term> +<listitem> +<para>Controls the maximum number of simultaneous clients that will be +handled. Defaults to 100.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="browsing-general-configuration"> +<title>Browsing General Configuration</title> + +<para>The dialog to configure the &CUPS; browsing general settings +is shown here. It includes: </para> + +<itemizedlist> +<listitem><para><guilabel>Enable browsing</guilabel></para></listitem> +<listitem><para><guilabel>Use short names when +possible</guilabel></para></listitem> +<listitem><para><guilabel>Use implicit +classes</guilabel></para></listitem> +</itemizedlist> + + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; browsing general +settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration10_browsinggeneral.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; browsing general +settings</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Enable browsing</guilabel></term> +<listitem> +<para>Whether or not to broadcast printer information to other &CUPS; +servers. Enabled by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use short names when possible</guilabel></term> +<listitem> +<para>Whether or not to use <quote>short</quote> names for remote +printers when possible (⪚ <systemitem +class="resource">printer</systemitem> instead of <systemitem +class="resource">printer@host</systemitem>). Enabled by +default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Use implicit classes</guilabel></term> +<listitem> +<para>Whether or not to use implicit classes.</para> +<para>Printer classes can be specified explicitly, in the +<filename>classes.conf</filename> file, implicitly based upon the +printers available on the <acronym>LAN</acronym>, or both.</para> +<para>When Implicit classes are enabled, printers on the +<acronym>LAN</acronym> with the same name (⪚ <systemitem +class="resource">Acme-LaserPrint-1000</systemitem>) will be put into +a class with the same name. This allows you to setup multiple +redundant queues on a <acronym>LAN</acronym> without a lot of +administrative difficulties. If a user sends a job to <systemitem +class="resource">Acme-LaserPrint-1000</systemitem>, the job will go to +the first available queue.</para> +<para>This option is enabled by default.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +<sect1 id="browsing-connection-configuration"> +<title>Browsing Connection Configuration</title> + +<para>The dialog to configure the &CUPS; server browsing connection is +shown here. Browsing connection settings include:</para> + +<itemizedlist> +<listitem><para><guilabel>Broadcast addresses</guilabel>: The +(<acronym>UDP</acronym>) broadcast address to transmit printer +information to</para></listitem> +<listitem><para><guilabel>Broadcast Port</guilabel>: The port number +to use for broadcasting</para></listitem> +<listitem><para><guilabel>Poll addresses</guilabel>: The address(es) +to poll for information about printers on servers that might not +broadcast (or whose broadcasts might not reach your +<acronym>LAN</acronym> due to routers in between).</para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server browsing +connection</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration11_browsingconnections.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; server browsing +connection</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Broadcast addresses</guilabel></term> +<listitem> +<para>After pressing the <guibutton>Add</guibutton> button, you will +see the following dialog to enter a new value for outgoing +broadcasting browse packets. It is the same kind of dialog as for +adding other &CUPS; server addresses to be polled for printer +information.</para> + +<screenshot> +<screeninfo>Dialog to enter a new value for broadcasting browse +packets to</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfig_browsingmasks_add_button.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to enter a new value for broadcasting browse packets +to</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This option specifies a broadcast address to be used. By +default, browsing information is broadcast to all active +interfaces.</para> + +<note> +<para>&HP-UX; 10.20 and earlier do not properly handle broadcast +unless you have a Class A, B, C or D netmask (&ie;, there is no +<acronym>CIDR</acronym> support).</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Broadcast port</guilabel></term> +<listitem> +<para>The port used for <acronym>UDP</acronym> broadcasts. By default +this is the <acronym>IPP</acronym> port; if you change this, you need +to do it on all servers. Only one BrowsePort is recognized.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Poll addresses</guilabel></term> +<listitem> +<para>Poll the named server(s) for printers.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +<sect1 id="browsing-masks-configuration"> +<title>Browsing Masks Configuration</title> + +<para>The dialog to configure the &CUPS; server allowed and/or denied browse +packets from other servers is shown here. </para> + +<itemizedlist> +<listitem><para><guilabel>Browse allow</guilabel>: </para></listitem> +<listitem><para><guilabel>Browse deny</guilabel>: </para></listitem> +<listitem><para><guilabel>Browse order</guilabel>: </para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server allowed and/or +denied browse packets from other servers</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration11_browsingmasks.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; server allowed and/or denied +browse packets from other servers</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Add Browse Address</guilabel> dialog</term> +<listitem> +<para>The dialog to enter a new value for the address of another +&CUPS; server to accept browse packets from is shown here. It is opened +by clicking on the <guibutton>Add...</guibutton> button beside the +field named <guilabel>Browse Allow:</guilabel>. It is the same dialog +as for adding <quote>denied</quote> broadcast sending +addresses.</para> + +<para>The dialog to enter a new value for the address of another +&CUPS; server to accept browse packets from is shown here.</para> + +<screenshot> +<screeninfo>Dialog to enter a new value for the address of another +&CUPS; server to accept browse packets from</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfig_browsingmasks_add_button.png" +format="PNG" /></imageobject> +<textobject> +<phrase>Dialog to enter a new value for the address of another &CUPS; +server to accept browse packets from</phrase></textobject> +</mediaobject> +</screenshot> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Browse allow</guilabel> and <guilabel>Browse +deny</guilabel></term> +<listitem> +<para><guilabel>Browse allow</guilabel> specifies an address mask to +allow for incoming browser packets. The default is to allow packets +from all addresses.</para> +<para><guilabel>Browse deny</guilabel> specifies an address mask to +deny for incoming browser packets. The default is to deny packets +from no addresses.</para> +<para>Both <guilabel>Browse allow</guilabel> and <guilabel>Browse +deny</guilabel> accept the following notations for addresses:</para> + +<informalexample> +<itemizedlist> +<listitem> +<para><userinput>All</userinput></para> +</listitem> +<listitem> +<para><userinput>None</userinput></para> +</listitem> +<listitem> +<para><userinput>*.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>host.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn/mmm</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm</userinput></para> +</listitem> +</itemizedlist> +</informalexample> + +<para>The hostname/domain name restrictions will only work if you have +turned hostname lookups on!</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Browse order</guilabel></term> +<listitem> +<para>Specifies the order of the allow/deny comparisons.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="browsing-timeouts-configuration"> +<title>Browsing Timeouts Configuration</title> + +<para>The dialog to configure the &CUPS; server browse timeout settings +is shown here. Browse timeout settings include:</para> +<itemizedlist> +<listitem><para><guilabel>Browse Interval</guilabel></para></listitem> +<listitem><para><guilabel>Browse Timeout</guilabel></para></listitem> +</itemizedlist> +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server browse timeout +settings</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration12_browsingtimeouts.png" +format="PNG"/></imageobject> +<textobject> +<phrase>dialog to configure the &CUPS; server browse timeout +settings</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Browse interval</guilabel></term> +<listitem> +<para>The time between browsing updates in seconds. The default is 30 +seconds.</para> +<para>Note that browsing information is sent whenever a printer's +state changes as well, so this represents the maximum time between +updates.</para> +<para>Set this to 0 to disable outgoing broadcasts so your local +printers are not advertised, but you can still see printers on other +hosts.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Browse timeouts</term> +<listitem> +<para>The timeout (in seconds) for network printers - if we don't get +an update within this time, the printer will be removed from the +printer list.</para> +<para>This number definitely should not be less than the browse +interval period, for obvious reasons. Defaults to 300 seconds.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +<sect1 id="browsing-relay-configuration"> +<title>Browsing Relay Configuration</title> + +<para>The dialog to configure the &CUPS; server as a browsing relay is +shown here. Browsing relay settings include:</para> + +<itemizedlist> +<listitem><para><guilabel>Browser packets relay</guilabel></para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server as a browsing +relay</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration14_browsingrelay.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; server as a browsing +relay</phrase></textobject> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term>Add Browse Relay dialog</term> +<listitem> +<para>The dialog to enter a new value for an address pair to define +browsing relaying between a &CUPS; server and a network is shown +here.</para> + +<screenshot> +<screeninfo>The dialog to enter a new value for an address pair to +define browsing relaying between a &CUPS; server and a +network</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfig_browse_relay_add_button.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The dialog to enter a new value for an address pair to define +browsing relaying between a &CUPS; server and a +network</phrase></textobject> +</mediaobject> +</screenshot> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Browser packets relay</guilabel></term> +<listitem> +<para>Relay browser packets from one address or network to +another.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="security-configuration"> +<title>Security Configuration</title> + +<para>The dialog to configure the &CUPS; server security settings for +any of the defined server locations is shown here. It contains the +following settings, which may be defined separately for any valid +resource (or location) of the &CUPS; server:</para> + +<itemizedlist> +<listitem><para>System Group:</para></listitem> +<listitem><para>Access Permissions: </para></listitem> +<listitem><para>Auth Type:</para></listitem> +<listitem><para>Auth Class:</para></listitem> +<listitem><para>Auth Group Name:</para></listitem> +<listitem><para>Encryption:</para></listitem> +<listitem><para>Allow:</para></listitem> +<listitem><para>Deny:</para></listitem> +<listitem><para>Order:</para></listitem> +</itemizedlist> + +<para>Valid resources (or locations) of the &CUPS; server are:</para> + +<itemizedlist> +<listitem><para>Server Root Location: <systemitem +class="resource">/</systemitem> </para></listitem> +<listitem><para>Server Administration Location: <systemitem +class="resource">/admin</systemitem></para></listitem> +<listitem><para>All printers on the server: <systemitem +class="resource">/printers</systemitem></para></listitem> +<listitem><para>Any individual printer on the server: +⪚ <systemitem +class="resource">/printers/infotec_P320</systemitem></para></listitem> +<listitem><para>All printer classes on the server: <systemitem +class="resource">/classes</systemitem>:</para></listitem> +<listitem><para>Any individual printer class on the server: +⪚ <systemitem +class="resource">/classes/all_infotecs_P320_or_P450</systemitem></para></listitem> +</itemizedlist> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server security settings +for any of the defined server locations</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration_securityoverview.png" +format="PNG"/></imageobject> +<textobject> +<phrase>dialog to configure the &CUPS; server security settings for +any of the defined server locations</phrase></textobject> + +</mediaobject> +</screenshot> + +<note> +<para>For all locations that are not defined separately the setting of +the location <quote>above</quote> it is valid.</para> + +<para>For example, you have a printer named <systemitem +class="resource">infotec_P450</systemitem> with no set security +options. Then the security of the location <systemitem +class="resource">/printers</systemitem> will take the responsibility +for this printer as it is a sub-location of<systemitem +class="resource">/printers</systemitem>. If, in turn there is no +security set for <systemitem class="resource">/printers</systemitem>, +then the security for <systemitem class="resource">/</systemitem> (the +general security) of the server takes responsibility. Either you have +set this for your purpose or the compiled-in default value takes +over.</para> +</note> + +<variablelist> +<varlistentry> +<term>SystemGroup</term> +<listitem> +<para>The group name for <systemitem +class="groupname">System</systemitem> or printer administration +access. The default varies depending on the operating system, but +will be <systemitem class="groupname">sys</systemitem>, <systemitem +class="groupname">system</systemitem> or <systemitem +class="groupname">root</systemitem> (checked for in that order).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Access Permissions</term> +<listitem> +<para>Access permissions for each folder served by the scheduler. +Locations are relative to the document root.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Authorization Type</term> +<listitem> +<para>The authorization to use:</para> + +<variablelist> +<varlistentry> +<term>None</term> +<listitem> +<para>Perform no authentication.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Basic</term> +<listitem> +<para>Perform authentication using the &HTTP; Basic method.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Digest</term> +<listitem> +<para>Perform authentication using the &HTTP; Digest method.</para> +</listitem> +</varlistentry> +</variablelist> + +<note> +<para>Local certificate authentication can be substituted by the +client for Basic or Digest, when connecting to the localhost +interface.</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term>Authorization Class</term> +<listitem> +<para>The authorization class. Currently only +<quote>Anonymous</quote>, <quote>User</quote>, <quote>System</quote> +(valid user belonging to the group set as system group), and +<quote>group</quote> (valid user belonging to the specified group) are +supported.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Authorization Group Name</term> +<listitem> +<para>The group name for <quote>Group</quote> authorization</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Encryption</term> +<listitem> +<para>Whether or not to use encryption. This depends on having the +<application>OpenSSL</application> linked into the &CUPS; library and +scheduler.</para> +<para>Possible values are:</para> +<variablelist> +<varlistentry> +<term>Always</term> +<listitem> +<para>Always use encryption (<acronym>SSL</acronym>)</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Never</term> +<listitem> +<para>Never use encryption.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Required</term> +<listitem> +<para>Use <acronym>TLS</acronym> encryption upgrade.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>IfRequested</term> +<listitem> +<para>Use encryption if the server requests it.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Allow</guilabel></term> +<listitem> +<para>Allows access from the specified hostname, domain, +<acronym>IP</acronym> address or network. Possible values are:</para> + +<informalexample> +<itemizedlist> +<listitem> +<para><userinput>All</userinput></para> +</listitem> +<listitem> +<para><userinput>None</userinput></para> +</listitem> +<listitem> +<para><userinput>*.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>host.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn/mmm</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm</userinput></para> +</listitem> +</itemizedlist> +</informalexample> + +<para>The host and domain address require that you enable hostname +lookups, as described earlier.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Deny</guilabel></term> +<listitem> +<para>Denies access from the specified hostname, domain, +<acronym>IP</acronym> address or network. Possible values are:</para> +<informalexample> +<itemizedlist> +<listitem> +<para><userinput>All</userinput></para> +</listitem> +<listitem> +<para><userinput>None</userinput></para> +</listitem> +<listitem> +<para><userinput>*.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>host.domain.com</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.*</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn/mmm</userinput></para> +</listitem> +<listitem> +<para><userinput>nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm</userinput></para> +</listitem> +</itemizedlist> +</informalexample> +<para>The host and domain address require that you enable hostname +lookups, as described earlier.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Order</term> +<listitem> +<para>The order of the allow and deny processing.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="example-how-define-security-for-all-printers"> +<title>Example: How To Define The Security For All Printers</title> + +<para>The dialog to configure the &CUPS; server security settings is +discussed here. We use the example to add security definitions other +than the default ones for the resource named <systemitem +class="resource">all printers</systemitem>. For the &CUPS; web server, +this is the location you access through <ulink +url="http://localhost:631/printers/"> +http://localhost:631/printers/</ulink> or (remotely) through <ulink +url="http://cups.server.name:631/printers/"> +http://cups.server.name:631/printers/</ulink></para> + +<para>The first screenshot shows the general location for this +setting. <guilabel>Select</guilabel> <guibutton>Add</guibutton> or +<guibutton>Modify</guibutton> a resource for which you want to decide +about its security settings.</para> + +<screenshot> +<screeninfo>Dialog to configure the &CUPS; server security +settings</screeninfo><mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration15a_resourceallprinters_defineaccess.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to configure the &CUPS; server security +settings</phrase></textobject> +</mediaobject> +</screenshot> + +<para>This dialog is to add a new resource. It looks similar if you +want to modify an already existing resource. Here are the general +options:</para> + +<screenshot> +<screeninfo>Dialog to add a new resource.</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration15b_resourceallprinters_defineaccess.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to add a new resource.</phrase></textobject> +</mediaobject> +</screenshot> + +<para>.This is the second part or the dialog is to add a new +ressource. It looks similar if you want to modify an already existing +resource. Here you define the actual access masks for the resource in +question. </para> + +<screenshot> +<screeninfo>Dialog to add a new resource.</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration15c_resourceallprinters_defineaccess.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Dialog to add a new resource.</phrase></textobject> +</mediaobject> +</screenshot> +<screenshot> +<screeninfo>Resource dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration_resourceadminaccessmasks.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Resource dialog</phrase></textobject> +</mediaobject> +</screenshot> + +<screenshot> +<screeninfo>Resource dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration_resourceadminaddprinters.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Resource dialog</phrase></textobject> +</mediaobject> +</screenshot> + +<screenshot> +<screeninfo>Resource dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration_resourceadminaddprinters_defineaccess.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Resource dialog</phrase></textobject> +</mediaobject> +</screenshot> + +<screenshot> +<screeninfo>Resource dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsserverconfiguration_resourceadminauthorization.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Resource dialog</phrase></textobject> +</mediaobject> +</screenshot> + +</sect1> + +</chapter> diff --git a/doc/kdeprint/cups-filterarchitecture-kivio-70Percent-scaled.png b/doc/kdeprint/cups-filterarchitecture-kivio-70Percent-scaled.png Binary files differnew file mode 100644 index 000000000..9f5a73d39 --- /dev/null +++ b/doc/kdeprint/cups-filterarchitecture-kivio-70Percent-scaled.png diff --git a/doc/kdeprint/cupsaddprinterwizard1.png b/doc/kdeprint/cupsaddprinterwizard1.png Binary files differnew file mode 100644 index 000000000..cf20e087c --- /dev/null +++ b/doc/kdeprint/cupsaddprinterwizard1.png diff --git a/doc/kdeprint/cupsaddprinterwizard2_backendselection.png b/doc/kdeprint/cupsaddprinterwizard2_backendselection.png Binary files differnew file mode 100644 index 000000000..3e4b2f126 --- /dev/null +++ b/doc/kdeprint/cupsaddprinterwizard2_backendselection.png diff --git a/doc/kdeprint/cupsaddprinterwizard3_networkscan.png b/doc/kdeprint/cupsaddprinterwizard3_networkscan.png Binary files differnew file mode 100644 index 000000000..160834ee9 --- /dev/null +++ b/doc/kdeprint/cupsaddprinterwizard3_networkscan.png diff --git a/doc/kdeprint/cupsaddprinterwizard3_networkscan_results.png b/doc/kdeprint/cupsaddprinterwizard3_networkscan_results.png Binary files differnew file mode 100644 index 000000000..aa6cd87f1 --- /dev/null +++ b/doc/kdeprint/cupsaddprinterwizard3_networkscan_results.png diff --git a/doc/kdeprint/cupsaddprinterwizard4_networkscan_config.png b/doc/kdeprint/cupsaddprinterwizard4_networkscan_config.png Binary files differnew file mode 100644 index 000000000..7fff7de52 --- /dev/null +++ b/doc/kdeprint/cupsaddprinterwizard4_networkscan_config.png diff --git a/doc/kdeprint/cupsoptions.docbook b/doc/kdeprint/cupsoptions.docbook new file mode 100644 index 000000000..dc886d21c --- /dev/null +++ b/doc/kdeprint/cupsoptions.docbook @@ -0,0 +1,602 @@ +<chapter id="cupsoptions-presently-outside-kcontrol"> +<title>&CUPS; options presently not available through &kcontrol;</title> + +<para>This chapter gives you some hints about further configuration +possibilities which may not be available through the &kdeprint; &GUI; +interface to &CUPS;.</para> + +<sect1> +<title>Overview of provided features</title> + +<para>All of the most often used features and functions &CUPS; provides +are supported in &kdeprint;.</para> + +<itemizedlist> +<listitem> +<para>Printer management is supported: add, remove, modify, configure, +test, disable, enable ...</para> +</listitem> +<listitem> +<para>Job management is supported: cancel, hold, release, move to +different printer</para> +</listitem> +<listitem> +<para>Print options: for full control as provided by &CUPS;.</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="where-to-find-further-chupshelp"> +<title>Where to find help when using &CUPS;</title> + +<para>A lot of information about the inner workings of &CUPS; is +available through the web interface, which &CUPS; will always +support. It works with any browser (yes, even text-based ones). Just go +to <ulink url="http://localhost:631/">http://localhost:631/</ulink> for +a start. There you find a link to locally available &CUPS; documentation +in <acronym>HTML</acronym> and <acronym>PDF</acronym> if you are new to +&CUPS;.</para> + +<para>&CUPS; is accessible through other means than &kdeprint;: +commandline and browser are two native &CUPS; interfaces. The many +commandline utilities add up to the most complete control you have on +&CUPS;. The web interface is only a subset of all available +configuration or control options. </para> + +<para>This is also true for &kdeprint;. Generally, as &CUPS; develops, +most new features will first be implemented through the commandline. Be +sure to check the latest versions of the man pages for &CUPS; to stay +up-to-date with new features after you install a new version.</para> + +<tip> +<para>Depending on your update method for &CUPS;, your active +configuration file might not have been re-placed by a new one; thus your +new, more capable &CUPS;-daemon might not have been told by the old +configuration file about the new features to use.</para> +</tip> + +<para>A complete list of available files and man pages should always be +in the &CUPS; Software Administrator Manual (<ulink +url="http://localhost:631/sam.html#FILES">http://localhost:631/sam.html#FILES</ulink>. +In the &konqueror; &URL;/location field, type +<userinput>man:/lpadmin</userinput> and +<userinput>man:/cupsd.conf</userinput> to find out about the most +important command and configuration file. You knew already about +&konqueror;'s nice abilities to show you the traditional &UNIX; man +pages, didn't you? Read this. From there you find more interesting +hints and links to other man pages and documentation.</para> + +<sect2> +<title>How to find &CUPS; related man pages</title> + +<para>Here is a way to find out which &CUPS; related man pages there +are on your system: </para> + +<screen><prompt>kurt@transmeta:~ ></prompt> <userinput><command>apropos</command> <parameter>cups</parameter></userinput> +<computeroutput> +cups-calibrate (8)- ESP Printer Calibration Tool +lpstat (1) - print cups status information +cups-lpd (8) - receive print jobs + report printer status to lpd clients +classes.conf (5) - class configuration file for cups +backend (1) - cups backend transmission interfaces +filter (1) - cups file conversion filter interfaces +cups-polld (8) - cups printer polling daemon +mime.types (5) - mime type description file for cups +cupsd (8) - common unix printing system daemon +lpadmin (8) - configure cups printers and classes +cupsd.conf (5) - server configuration file for cups +mime.convs (5) - mime type conversion file for cups +printers.conf (5) - printer configuration file for cups +mime.convs (5) - mime type conversion file for cups +cups-polld (8) - cups printer polling daemon +lpstat (1) - print cups status information +backend (1) - cups backend transmission interfaces +mime.types (5) - mime type description file for cups +cupsd (8) - common unix printing system daemon +lpadmin (8) - configure cups printers and classes +printers.conf (5) - printer configuration file for cups +cupsd.conf (5) - server configuration file for cups +filter (1) - cups file conversion filter interfaces +</computeroutput></screen> +</sect2> +</sect1> + +<sect1 id="tips-and-tricks-for-cups"> +<title>Outside &kdeprint;: Hints & Tips Tricks with &CUPS; on the +Commandline</title> + +<para>Here are a few examples of options that are presently only +available if you use the commandline. </para> + +<sect2> +<title>Allowing or denying printer access for certain users</title> + +<para>When installing (or modifying) a printer through the command line, +you can either deny or allow the usage of that printer to certain +users:</para> + +<screen><userinput><command>lpadmin</command> <option>-p</option><parameter>HeidelbergDigimaster9110</parameter> <option>-v</option> <parameter>lpd:/10.160.16.99/mqueue</parameter> <option>-u</option> <parameter>allow:kurt,sylvi,hansjoerg</parameter> <option>-E</option> <option>-P</option> <parameter>/home/kurt/PPDs/DVHV.ppd</parameter></userinput></screen> + +<para>will allow the usage of this (believe me: very nice and also very +professional) printer to only the three mentioned users and at the same +time deny it to all others. If another user wants to print on the +DigiMaster via this &CUPS; server, he will receive an error message +along the lines <errortype>client-error-not-possible</errortype>.</para> + +<screen><userinput><command>lpadmin</command> <option>-p</option> <parameter>HeidelbergDigimaster9110</parameter> <option>-v</option> <parameter>lpd:/10.160.16.99/mqueue</parameter> <option>-u</option> <parameter>deny:tackat,boss,waba</parameter> <option>-E</option> <option>-P</option> <parameter>/home/kurt/PPDs/DVHV.ppd</parameter></userinput></screen> + +<para>will deny the usage of this same printer to the three mentioned +users and at the same time allow it to all others. If +<quote>denied</quote> user wants to print on the DigiMaster via this +&CUPS; server, he will receive an error message along the lines +<errortype>client-error-not-possible</errortype>.</para> + +<note> +<para>Only one of the two options may be used at one time; at present +there is no support to have a similar option in a per-group based +way. This will be implemented in the future.</para> +</note> + +</sect2> +<sect2> +<title>Imposing Quotas for certain printers</title> + +<para>Sometimes you want to impose quotas for certain printers. With +quotas you can set upper limits for the number of pages or the amount of +data to be printed over a certain period to a certain printer.</para> + +<para>Quotas can be set with the <option>-o</option> option when +installing a printer with the <command>lpadmin</command> command, or +afterwards for an already existing printer. Following are some +guidelines (which are missing at the time of writing in the, official +&CUPS; documentation):</para> + +<itemizedlist> +<listitem> +<para>With &CUPS; you may have pagecount- and filesize-based quotas for +individual printers.</para> +</listitem> + +<listitem> +<para>Quotas are calculated for each user individually (so a single set +of limits applies to all users for the printer concerned).</para> +</listitem> + +<listitem> +<para>Quotas include banner pages (if those are used).</para> +</listitem> + +<listitem> +<para>This means: you can limit every user to 20 pages per day on an +expensive printer, but you cannot limit every user except <systemitem +class="username">Kurt</systemitem> or <systemitem +class="username">root</systemitem>.</para> +</listitem> + +<listitem> +<para>There are <option>job-k-limit</option>, +<option>job-page-limit</option>, and <option>job-quota-period</option> +options to give when setting up a printer.</para> +</listitem> + +<listitem> +<para><option>job-quota-period</option> sets a time interval for quota +computing (intervals are determined in seconds; so a day is +60x60x24=86.400, a week is 60x60x24x7=604,800, and a month is +60x60x24x30=2.592.000 seconds.)</para> +</listitem> + +<listitem> +<para>For quotas to be enforced, the time-period +<emphasis>plus</emphasis> at least one job-limit must be set to +non-zero.</para> +</listitem> + +<listitem> +<para>The default value of 0 for <option>job-k-limit</option> specifies +that there is no limit.</para> +</listitem> + +<listitem> +<para>The default value of 0 for <option>job-page-limit</option> +specifies that there is no limit.</para> +</listitem> + +<listitem> +<para>The default value of 0 for <option>job-quota-period</option> +specifies that the limits apply to all jobs that have been printed by a +user that are still known to the system.</para> +</listitem> +</itemizedlist> + +<sect3> +<title>Working Examples:</title> + +<para>Working, as both, time-period <emphasis>plus</emphasis> one or +both job-limits are defined</para> + +<screen><userinput><command>lpadmin</command> <option>-p</option> <parameter>danka_infotec_4850</parameter> <option>-o</option> <parameter>job-quota-period=604800</parameter> <option>-o</option> <parameter>job-k-limit=1024</parameter></userinput></screen> + +<para>This sets a limit of a file size of 1 MB (in total) for each user +of existing printer <systemitem +class="resource">danka_infotec_4850</systemitem> during one week.</para> + +<screen><userinput><command>lpadmin</command> <option>p</option> <parameter>danka_infotec_4105</parameter> <option>-o</option> <parameter>job-quota-period=604800</parameter> <option>-o</option> <parameter>job-page-limit=100</parameter></userinput></screen> + +<para>This sets a limit of 100 pages (in total) for each user of +existing printer <systemitem +class="resource">danka_infotec_4105</systemitem> during one week.</para> + +<screen><userinput><command>lpadmin</command> <option>-p</option> <parameter>danka_infotec_P450</parameter> <option>-o</option> <parameter>job-quota-period=604800</parameter> <option>-o</option> <parameter>job-k-limit=1024</parameter> <option>-o</option> <parameter>job-page-limit=100</parameter></userinput></screen> + +<para>This sets a combined limit of 1 MB (in total) and 100 pages (in +total) for each user of existing printer <systemitem +class="resource">danka_infotec_P450</systemitem> during one +week. Whichever limit is reached first will take effect.</para> + +</sect3> + +<sect3> +<title>Not working examples</title> + +<para><emphasis>NOT</emphasis> working, as only +<emphasis>one</emphasis>, time-period <emphasis>or</emphasis> job-limit +is defined)</para> + +<screen><userinput><command>lpadmin</command> <option>-p</option> <parameter>danka_infotec_P320</parameter> <option>-o</option> <parameter>job-quota-period=604800</parameter></userinput> + +<userinput><command>lpadmin</command> <option>-p</option> <parameter>danka_infotec_FullColor</parameter> <option>-o</option> <parameter>job-page-limit=100</parameter></userinput> + +<userinput><command>lpadmin</command> <option>-p</option> <parameter>danka_infotec_HiSpeed</parameter> <option>-o</option> <parameter>job-k-limit=1024</parameter></userinput></screen> + +</sect3> + +<sect3> +<title>Related Error Messages</title> + +<para>Once a user reaches his quota limit, he'll get a +<errortype>client-error-not-possible</errortype> message, if he wants to +print.</para> + +</sect3> + +</sect2> + +<sect2> +<title>Installing a <quote>raw</quote> printer</title> + +<para>There are different ways to define a <quote>raw</quote> +printer. One comfortable one is to use the <command>lpadmin</command> +command. Just don't define a &PPD; file to be used for that printer and +it will be a raw one:</para> + +<screen><userinput><command>lpadmin</command> <option>-p</option> <parameter>Raw_Danka_infotec</parameter> <option>-E</option> <option>-v</option> <parameter>lpd://10.160.16.137/PORT1</parameter></userinput></screen> + +<para>Raw printer queues are those which don't touch the print file to +transform it to a different file format. You need this for example when +printing from &Windows; clients via Samba through a &CUPS; server to a +<acronym>PCL</acronym> printer: in this case the &Windows; side printer +driver would generate the finished print file format for the target +printer and filtering it through &CUPS; filters would only harm the +purpose. Under certain circumstances (if you want to make sure that the +file goes to the printer <quote>unfiltered</quote> by &CUPS;) the +<quote><command>lpadmin</command> without a &PPD;</quote> comes in +handy.</para> + +</sect2> + +</sect1> +<sect1 id="troubleshooting-cups"> +<title>Troubleshooting &CUPS; in &kdeprint;</title> + +<para>This section of the &kdeprint; Handbook will live from the +readers' feedback. Here is just a small beginning.</para> + +<sect2> +<title>Error Messages</title> + +<qandaset> +<qandaentry> +<question> +<para>What does the error +<errortype>client-error-bad-request</errortype> mean?</para> +</question> +<answer> +<para>The user sent a file to the &CUPS; which the server could not +process. You get this also upon sending an <quote>empty</quote> +file.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>And <errortype>client-error-not-possible</errortype>?</para> +</question> +<answer> +<para>User is either not allowed to print to a certain printer or has +achieved his quota (based on file size and/or page number)</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How about <errortype>client-error-not-found</errortype>?</para> +</question> +<answer> +<para>The user tried to access a nonexistent resource on the &CUPS; +server, such as trying to print a nonexistent file, or one that you are +denied permission to read.</para> +</answer> + +</qandaentry> +</qandaset> + +</sect2> + +<sect2> +<title>Questions and Answers</title> + +<qandaset> +<qandaentry> +<question> +<para>Why can't I re-start my jobs?</para> +</question> +<answer> +<para>To be able to re-start your <quote>completed</quote> jobs from the +web interface, you need a setting in the +<filename>/etc/cups/cupsd.conf</filename> file: set +<userinput>PreserveJobFiles True</userinput>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I get rid of the long list of completed jobs in the web +interface?</para> +</question> +<answer> +<para>TODO</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How does page accounting work?</para> +</question> +<answer> +<para>&CUPS; does the <quote>print accounting</quote> by passing nearly +every job through the <quote>pstops</quote> filter. This one does, +amongst other things, the page counting. Output of this filter there may +be piped into other filters (like pstoraster --> rastertopcl) or sent to +the printer directly (if it is a &PostScript; printer).</para> + +<para>In any case, this works for network, parallel, serial or +<acronym>USB</acronym> printers the same. For pstops to work, it needs +<acronym>DSC</acronym>, Document Structuring Convention compliant +&PostScript; (or near-equivalent) as input. So it calculates the pages +during filtering on the print server and writes info about every single +page (what time, which user, which job-ID and -name, which printer, how +many copies of which pages of the document, how many kilo-bytes?) into +<filename>/var/log/cups/page_log</filename>.</para> + +<para>By the way: on my personal <quote>wishlist</quote> is a hack of +<quote>webalizer</quote> to read and analyze the page_log and give a +similar output. Anyone?</para> + +<para>However, it is <emphasis>not</emphasis> giving correct results in +the following cases:</para> + +<itemizedlist> +<listitem> +<para>The printer jams and maybe therefor throw away the job (real live +experience; or maybe throwing away the job because of problems with the +data format)</para> +</listitem> +<listitem> +<para>Jobs printed as <quote>raw</quote> are always counted as size of 1 +page (and maybe multiple copies).</para> +</listitem> +</itemizedlist> + +<para>Therefore the page accounting of &CUPS; is <quote>only</quote> +an approximation (in many cases an excellent or at least good one, in +others a quite poor one). The only reliable print count is the one +done by the internal printer counter. (Because this is the one you pay +for, if you are on a <quote>click price</quote> or similar.) Some, by +far not most, printers can be queried remotely for that information +via <acronym>SNMP</acronym> (Simple Network Management Protocol). That +means, in a bigger network with many different printers there +<emphasis>is</emphasis> just no completely reliable and accurate page +accounting tool!</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why doesn't page-accounting work with &Windows; clients?</para> +</question> +<answer> +<para>From &Windows; clients jobs nearly always need to be sent as +<quote>raw</quote>. Why? If &CUPS; works as a print server for &Windows; +clients using the original native &Windows; driver for the target print +device, this guarantees the correct formatting of the job on the clients +already; therefor the server should not touch it and print +<quote>raw</quote>; therefor no filtering is started (and this is not +even possible as the input from the clients is not &PostScript; as +pstops expects; hence no page-count other than the default +<quote>1</quote>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I get a list of available options for a given printer or a +&PPD; file?</para> +</question> +<answer> +<para>See the man page for the <command>lpoptions</command> command. You +may investigate a &CUPS;-enabled box about any option of its available +printers. There is no need to have the printer installed locally. As +long as the printer is available locally (through the &CUPS; +<quote>printer browsing</quote> feature), it will also work +remote.</para> + +<para>To query for a printers' option typing +<userinput><command>lpoptions</command> <option>-p</option> +<parameter>HitachiDDP70MicroPress</parameter> +<option>-l</option></userinput> will give a long listing of all +available options as read from the &PPD; file for the given +Hitachi-Printer (in my case installed on remote server +transmeta). Remote server <systemitem +class="systemname">Transmeta</systemitem> and its &CUPS; daemon as well +as the localhost's &CUPS; daemon need to be up and running for this to +succeed.</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I read the listing retrieved by the +<command>lpoptions</command> command?</para> +</question> + +<answer> +<para>You know that for &PostScript; printer manufacturers it is +<quote>legal</quote> to define their own internal names and procedures +even for standard &PostScript; options. As long as the driver is able to +retrieve the option from the &PPD; and show it to the user in a way that +he understands it everything is OK. But what do <emphasis>you</emphasis> +do, if you want to use some obscure printer options on the command line? +How do you find out its exact syntax?</para> + +<para>Let's take an example. Looking at Hitachi's DDP70 printer and how +it implements duplex printing is revealing somehow. How do you tell how +to print double sided? duplex or Duplex? Or another name altogether?.</para> + +<screen><userinput><command>lpoptions</command> <option>-h</option> <parameter>transmeta</parameter> <option>-p</option> <parameter>Hitachi_DDP70_ClusterPrintingSystem</parameter> <option>-l</option> | <command>grep</command> <parameter>uplex</parameter></userinput></screen> + +<para>This leads to the output</para> + +<screen><computeroutput>TR-Duplex/Duplex: False *True</computeroutput></screen> + +<para>This is to be interpreted like follows:</para> + +<itemizedlist> +<listitem> +<para>The name of the investigated option is +<option>TR-Duplex</option>;</para> +</listitem> +<listitem> +<para>Behind the slash you see the translation of the option, as it +should be shown in a &GUI; or Web interface +(<quote>Duplex</quote>);</para> +</listitem> +<listitem> +<para>The option may take one of the two values +<parameter>False</parameter> or <parameter>True</parameter>;</para> +</listitem> +<listitem> +<para>The present setting is <parameter>True</parameter> to be +recognized by the marking with a star <literal>*</literal>.</para> +</listitem> +</itemizedlist> + +<para>To override the present default setting (duplex) and print a job +in simplex, you need to use the following command: </para> + +<screen><userinput><command>lpr</command> <option>-P</option> <parameter>Hitachi_DDP70_ClusterPrintingSystem</parameter> <option>-o</option> <parameter>TR-Duplex=False</parameter> <parameter>/path/to/your/printjob</parameter></userinput></screen> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>How do I get a nicely formatted listing of available options for a +given printer or &PPD;?</para> +</question> +<answer> +<para>Use the <command>lphelp</command> command which may be installed +on your system locally. There is not yet a man page for +<command>lphelp</command>.</para> + +<screen><userinput><command>lphelp</command> <parameter>infotecP450</parameter></userinput></screen> + +<para>This lists the available options for the named printer. It is +nicely formatted and does explain every available option and how to use +it. You can query different printers' options at once:</para> + +<screen><userinput><command>lphelp</command> <parameter>infotec7410color</parameter> <parameter>DANKA_fullcolor_D2000</parameter> <parameter>HP_ColorLaserJet8550</parameter></userinput></screen> + +<para>It also works for &PPD; files. Just specify the path to the +&PPD;:</para> + +<screen><userinput><command>lphelp</command> <filename>/home/kurt/PPDs/HP-ColorLaserJet8550.ppd</filename></userinput></screen> +</answer> +</qandaentry> +</qandaset> + +</sect2> +<sect2> +<title>Solving Problems</title> + +<para>No system is perfect. Here are some commonly seen traps people +have fallen into.</para> + +<qandaset> +<qandaentry> +<question> +<para>My printer named <quote>3-lp-duplex</quote> shows erratic +behavior. What's wrong?</para> +</question> +<answer> +<para>The printer names used in &CUPS; shall start with a letter and may +contain up to 128 letters, numbers or underscores. Using dashes may lead +to problems. Speaking about naming: printer names in &CUPS; are not case +sensitive. So a printer named <systemitem +class="resource">Best_of_Danka</systemitem> will be the same as +<systemitem class="resource">best_of_danka</systemitem> or <systemitem +class="resource">BEST_OF_DANKA</systemitem>. (This is a requirement of +&IPP;, which &CUPS; is fully compliant with).</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Why do I get <errortype>Unable to connect to SAMBA host: +Success</errortype> with my printer shares from &Windows; accessed via +Samba?</para> +</question> +<answer> +<para>Are the rights on the remote &Windows; box set correctly for you? +Are you actually allowed to print on the &Windows; shared +printer?</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>My files for printer <systemitem class="resource">lp</systemitem> +sometimes mysteriously disappear and two days later I am told they got +printed on a printer three floors below my office. What is going on?</para> +</question> +<answer> +<para>Believe me, it is very unlikely that your printer is the only one +with the name <systemitem class="resource">lp</systemitem>. Maybe +&CUPS; is playing a trick on you. As you might have the setting +<quote>ImplicitClasses On</quote> activated, &CUPS; tries to stuff all +printers it sees on the network into a <quote>Class</quote> name lp. All +jobs destined to lp are sent to this class and the first available +member prints it. So if you had this nice fellow (who listened closely +when you raved about &CUPS; and &kdeprint;) install &CUPS; and poke +around the system...get the idea?</para> + +<para>Take my advice: choose a unique name for any network printer! +(Mind you, the one on your parallel port also turns out to be a network +printer for the rest of the world if you don't take care of your +settings).</para> +</answer> +</qandaentry> +</qandaset> +</sect2> +</sect1> +</chapter> diff --git a/doc/kdeprint/cupsserverconfig_browse_relay_add_button.png b/doc/kdeprint/cupsserverconfig_browse_relay_add_button.png Binary files differnew file mode 100644 index 000000000..391cf06ee --- /dev/null +++ b/doc/kdeprint/cupsserverconfig_browse_relay_add_button.png diff --git a/doc/kdeprint/cupsserverconfig_browsingmasks_add_button.png b/doc/kdeprint/cupsserverconfig_browsingmasks_add_button.png Binary files differnew file mode 100644 index 000000000..f5767faad --- /dev/null +++ b/doc/kdeprint/cupsserverconfig_browsingmasks_add_button.png diff --git a/doc/kdeprint/cupsserverconfiguration10_browsinggeneral.png b/doc/kdeprint/cupsserverconfiguration10_browsinggeneral.png Binary files differnew file mode 100644 index 000000000..3775f4d2a --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration10_browsinggeneral.png diff --git a/doc/kdeprint/cupsserverconfiguration11_browsingconnections.png b/doc/kdeprint/cupsserverconfiguration11_browsingconnections.png Binary files differnew file mode 100644 index 000000000..d3ca6971f --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration11_browsingconnections.png diff --git a/doc/kdeprint/cupsserverconfiguration11_browsingmasks.png b/doc/kdeprint/cupsserverconfiguration11_browsingmasks.png Binary files differnew file mode 100644 index 000000000..a662dd117 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration11_browsingmasks.png diff --git a/doc/kdeprint/cupsserverconfiguration12_browsingtimeouts.png b/doc/kdeprint/cupsserverconfiguration12_browsingtimeouts.png Binary files differnew file mode 100644 index 000000000..d9e9528d6 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration12_browsingtimeouts.png diff --git a/doc/kdeprint/cupsserverconfiguration14_browsingrelay.png b/doc/kdeprint/cupsserverconfiguration14_browsingrelay.png Binary files differnew file mode 100644 index 000000000..0030b4d7c --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration14_browsingrelay.png diff --git a/doc/kdeprint/cupsserverconfiguration15a_resourceallprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration15a_resourceallprinters_defineaccess.png Binary files differnew file mode 100644 index 000000000..fab7bc65b --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration15a_resourceallprinters_defineaccess.png diff --git a/doc/kdeprint/cupsserverconfiguration15b_resourceallprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration15b_resourceallprinters_defineaccess.png Binary files differnew file mode 100644 index 000000000..2cc4bf8ae --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration15b_resourceallprinters_defineaccess.png diff --git a/doc/kdeprint/cupsserverconfiguration15c_resourceallprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration15c_resourceallprinters_defineaccess.png Binary files differnew file mode 100644 index 000000000..cfd09e543 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration15c_resourceallprinters_defineaccess.png diff --git a/doc/kdeprint/cupsserverconfiguration1_welcome.png b/doc/kdeprint/cupsserverconfiguration1_welcome.png Binary files differnew file mode 100644 index 000000000..50bd9ba3a --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration1_welcome.png diff --git a/doc/kdeprint/cupsserverconfiguration2_general.png b/doc/kdeprint/cupsserverconfiguration2_general.png Binary files differnew file mode 100644 index 000000000..c8e8b01c0 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration2_general.png diff --git a/doc/kdeprint/cupsserverconfiguration3_logging.png b/doc/kdeprint/cupsserverconfiguration3_logging.png Binary files differnew file mode 100644 index 000000000..300c31943 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration3_logging.png diff --git a/doc/kdeprint/cupsserverconfiguration4_directories.png b/doc/kdeprint/cupsserverconfiguration4_directories.png Binary files differnew file mode 100644 index 000000000..e55ab35fc --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration4_directories.png diff --git a/doc/kdeprint/cupsserverconfiguration5_HTTP.png b/doc/kdeprint/cupsserverconfiguration5_HTTP.png Binary files differnew file mode 100644 index 000000000..3e46eb17b --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration5_HTTP.png diff --git a/doc/kdeprint/cupsserverconfiguration6_encryption.png b/doc/kdeprint/cupsserverconfiguration6_encryption.png Binary files differnew file mode 100644 index 000000000..aca75adf0 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration6_encryption.png diff --git a/doc/kdeprint/cupsserverconfiguration7_miscellanious.png b/doc/kdeprint/cupsserverconfiguration7_miscellanious.png Binary files differnew file mode 100644 index 000000000..6a30d103e --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration7_miscellanious.png diff --git a/doc/kdeprint/cupsserverconfiguration8_networkgeneral.png b/doc/kdeprint/cupsserverconfiguration8_networkgeneral.png Binary files differnew file mode 100644 index 000000000..a0a40da20 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration8_networkgeneral.png diff --git a/doc/kdeprint/cupsserverconfiguration9_networkclients.png b/doc/kdeprint/cupsserverconfiguration9_networkclients.png Binary files differnew file mode 100644 index 000000000..89b30dfe9 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration9_networkclients.png diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminaccessmasks.png b/doc/kdeprint/cupsserverconfiguration_resourceadminaccessmasks.png Binary files differnew file mode 100644 index 000000000..147830184 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration_resourceadminaccessmasks.png diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters.png b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters.png Binary files differnew file mode 100644 index 000000000..295a0970a --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters.png diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters_defineaccess.png b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters_defineaccess.png Binary files differnew file mode 100644 index 000000000..3b3b4eb04 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration_resourceadminaddprinters_defineaccess.png diff --git a/doc/kdeprint/cupsserverconfiguration_resourceadminauthorization.png b/doc/kdeprint/cupsserverconfiguration_resourceadminauthorization.png Binary files differnew file mode 100644 index 000000000..1b388a6cb --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration_resourceadminauthorization.png diff --git a/doc/kdeprint/cupsserverconfiguration_securityoverview.png b/doc/kdeprint/cupsserverconfiguration_securityoverview.png Binary files differnew file mode 100644 index 000000000..bed1d3df6 --- /dev/null +++ b/doc/kdeprint/cupsserverconfiguration_securityoverview.png diff --git a/doc/kdeprint/extensions.docbook b/doc/kdeprint/extensions.docbook new file mode 100644 index 000000000..3995272c2 --- /dev/null +++ b/doc/kdeprint/extensions.docbook @@ -0,0 +1,57 @@ +<chapter id="extensions-to-all-printsubsystems"> +<title>&kdeprint; Extensions To All Print Subsystems</title> + +<sect1> +<title><quote>Virtual</quote> Printers</title> + +<sect2> +<title>The <quote>Fax</quote> Printer</title> + +<para>To be written</para> + +</sect2> + +<sect2> +<title>The <quote>File</quote> Printer</title> + +<para>To be written</para> + +</sect2> + +<sect2> +<title>The <quote><acronym>PDF</acronym></quote> Printer</title> + +<para>To be written</para> + +</sect2> + +</sect1> + +<sect1 id="external-filters"> +<title><quote>External</quote> Filters</title> + +<sect2> +<title>The <command>enscript</command> Filter for Text Files</title> + +<para>To be written</para> + +</sect2> + +<sect2> +<title>The <quote>n-up</quote> Filter for Any File</title> + +<para>To be written</para> + +</sect2> + +<sect2> +<title>Three different <quote>Make Pamphlet</quote> Filters for +&PostScript; Files</title> + +<para>To be written</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kdeprint/external-command.docbook b/doc/kdeprint/external-command.docbook new file mode 100644 index 000000000..1a1135d7c --- /dev/null +++ b/doc/kdeprint/external-command.docbook @@ -0,0 +1,25 @@ +<chapter id="external-printcommand-module"> +<title>Module For External Print Command (&Netscape;-like) </title> + +<para>This module allows the print command to be specified completely +(&Netscape;-like). An edit line is added in the print dialog for that +purpose. Can be used in many cases, for example with a self-made print +program. </para> + +<sect1> +<title>Overview of provided features</title> + +<itemizedlist> +<listitem> +<para>Printer management: not supported</para> +</listitem> +<listitem> +<para>Job management: not supported.</para> +</listitem> +<listitem> +<para>Print options: basic control, depending on your knowledge of the +print command</para> +</listitem> +</itemizedlist> +</sect1> +</chapter> diff --git a/doc/kdeprint/final-word.docbook b/doc/kdeprint/final-word.docbook new file mode 100644 index 000000000..ed2ae029a --- /dev/null +++ b/doc/kdeprint/final-word.docbook @@ -0,0 +1,117 @@ +<chapter id="final-word-from-author"> +<title>Final word from the Author</title> + +<sect1 id="who-am-i"> +<title>Who am I, what is my business? </title> + +<para> +My employer is Danka Deutschland GmbH, a leading and +manufacturer-independent provider of professional and hi-speed digital +printing systems, black-and-white as well as color. Danka provides +hardware, software, service, maintenance, consumables and customized +solutions for the products in its portfolio. I work there as a +System Engineer. Amongst the brands Danka offers are Heidelberg +(formerly Kodak), Canon, &Hewlett-Packard;, Hitachi, Infotec and +EfI.</para> + +<para> +My acquaintance with &Linux; and the Free Software community is not +too old. When I started to play around with &Linux; at the beginning +of 1999, my deepest disappointment was the poor support for +printing. True, I made all our machines spit out simplex prints -- but +what about duplex? What about punching the output? How to make sorting +work? Or stapling, cover sheets and all the other beautiful finishing +options our engines offer to customers? No way -- at least for me as a +non-geek!</para> + +<para> +I began a search on the Internet for a solution. Fortunately not +much later, in May 1999, Mike Sweet, principal developer of &CUPS;, +announced the first Beta release of this superb piece of printing +software. After trying it briefly, I knew this was it!</para> + +<para> +Next thing I attempted: to make &Linux; distributions interested in +this new stuff. Believe me -- it was more than tenacious! They seemed +to think they already had the best thing they could get in +printing. One reason probably was that they (and many &Linux; +developers) never had to think about how to best support a printer +duplexer -- because one had never come near their own +desks...</para> + +<para> +Finally, my attempts to make some &Linux; print publications +interested in &CUPS; <quote>backfired</quote> on me - one editor +squeezed me into writing a series on the subject myself. And this is +how some people started to give me the nickname <quote>CUPS +Evangelist</quote>. I will not get rid of this nick anytime soon, now +that even the &kde; people wedged me into their timeframe of +releases. Oh, boy...</para> + +<para>Anyway, &CUPS; is now making its way around the world and it +might well become a triumphal one: I am a little bit proud to have +supported and contributed to this from near the beginning.</para> + +<para>It should encourage you: even if some more experienced &Linux; +users than you are skeptical about it, and even if your programming +skills are next to zero (like mine) - there are a lot of tasks and +jobs and ideas, and talent that you can contribute to the Free Software +community. Not least within the &kde; project... ;-) +</para> + +</sect1> + +<sect1 id="credits"> +<title>Credits</title> + +<para>I'd like to thank...</para> +<itemizedlist> +<listitem> +<para>Mike Sweet for developing &CUPS; in the first place</para> +</listitem> +<listitem> +<para>Jean-Eric Cuendet for starting <application>kups</application> +and <application>qtcups</application>, the predecessors of +&kdeprint;</para> +</listitem> +<listitem> +<para>Michael Goffioul for doing all the hard work recently</para> +</listitem> +<listitem> +<para>Martin Konold for thinking twice</para> +</listitem> +<listitem> +<para>Sven Guckes for teaching me a few things about the art of <quote>survival +on the terminal</quote> (just in case &kde; is not there ;-) )</para> +</listitem> +<listitem> +<para>...too numerous others to mention who also let me snatch bits +and bytes of knowledge +off them</para> +</listitem> +<listitem> +<para> and last, but not least: Tom Schwaller for encouraging me +to get into <quote>documentation +writing</quote></para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="caveats"> +<title>Caveats</title> + +<para>&kdeprint; has been developed on a system using &CUPS; 1.1.6. +&kdeprint; has been tested on other versions of &CUPS; and so +far no incompatibilities are known. By the time of writing +this Handbook, &CUPS; 1.1.9 is out with a few new features +not yet supported by &kdeprint;. Of course you are able to +access these features, but you will need to bypass &kdeprint; +and use the &CUPS; command-line tools or edit configuration +files manually. &kdeprint;'s development will go on and this +Handbook strives to always be the best available user documentation +resource for it.</para> + +</sect1> + +</chapter> diff --git a/doc/kdeprint/getting-started.docbook b/doc/kdeprint/getting-started.docbook new file mode 100644 index 000000000..cb360379f --- /dev/null +++ b/doc/kdeprint/getting-started.docbook @@ -0,0 +1,143 @@ +<chapter id="getting-started"> +<title>Getting Started</title> + +<para>This chapter of the &kdeprint; Handbook will walk you through most +of the configuration or selection options of &kdeprint;. It will mainly +deal with &CUPS; in this version, as the author is most familiar with +it, and also because &kdeprint; started off with supporting &CUPS; +best. Later versions of the &kdeprint; software and editions of this +handbook will support and explore other printing +systems more closely.</para> + +<sect1 id="selecting-your-print-subsystem"> +<title>Selecting Your Print Subsystem</title> + +<para>You need to define your print subsystem, before you are able to +install any printer with the &kdeprint; framework. There are two areas +where you can define this: either in &kcontrol; (The <guilabel>Printing +Manager</guilabel> section), or directly and <quote>on the fly</quote> +from the print dialog.</para> + +<para>Navigate to <menuchoice><guimenu>K Menu</guimenu> +<guisubmenu>Preferences</guisubmenu> <guisubmenu>System</guisubmenu> +<guimenuitem>Printing Manager</guimenuitem></menuchoice>. At the bottom +you can see a button that lets you select which printing subsystem you +want to use. In &kde; 2.2 you can choose from the following +alternatives:</para> + +<itemizedlist> +<listitem> +<para>&CUPS; (Common &UNIX; Printing System)</para> +</listitem> +<listitem> +<para>Print through an external program (generic)</para> +</listitem> +<listitem> +<para><acronym>LPR</acronym> (Standard <acronym>BSD</acronym> Print +System)</para> +</listitem> +<listitem> +<para>Generic &UNIX; <acronym>LPD</acronym> print system (the +default)</para> +</listitem> +<listitem> +<para><acronym>RLPR</acronym> environment (print to remote +<acronym>LPD</acronym> servers from the command line)</para> +</listitem> +</itemizedlist> + +<para>Of course, the chosen system must be installed, and up and running on +your box prior to your selection, or before it takes effect. <!-- The --> +<!-- authors personal recommendation is &CUPS; --> +</para> + +<para>On it's first startup, &kdeprint; will try an autodetection. This +only works for:</para> + +<itemizedlist> +<listitem> +<para>&CUPS;, as it is checking first for a running &CUPS; daemon</para> +</listitem> +<listitem> +<para><acronym>LPD</acronym>, as it is checking for a running +<acronym>LPD</acronym> daemon, plus a <filename>printcap</filename> +file.</para> +</listitem> +</itemizedlist> + +<!-- <para> +Go to System->XY->ABC. Now you can choose from the following +alternatives: +</para>--> + +<para>The system you choose must be installed on your system prior to +your selection. The author's personal recommendation is +&CUPS;.</para> + +<para>Once autodetected, chosen, or changed, the active print +subsystem will take effect for all &kde; applications. Different +users may have different print subsystems in use, if those do exist on +the computer and are compliant with each other. Their settings are +stored in the <filename>kdeprintrc</filename>. This file is unique to +every user, and is normally installed in +<filename>$<envar>HOME</envar>/.kde/share/config/kdeprintrc</filename>.</para> + +<warning> +<para>This file is not intended to be directly editable, and all +available options can be set from the &kdeprint; &GUI;.</para> +</warning> + +<para>You may even select a different printer subsystem, on the fly, from +the &kprinter; dialog box.</para> + +</sect1> + +<sect1 id="working-with-printing-manger"> +<title>Working with the Printing Manager</title> + +<para>Once you have chosen your preferred and installed print subsystem, +you are ready to investigate, configure administer and work with this +system through the &kdeprint; framework.</para> + +<para>Navigate to <menuchoice><guimenu>K Menu</guimenu> +<guisubmenu>Preferences</guisubmenu> <guisubmenu>System</guisubmenu> +<guimenuitem>Printing Manager</guimenuitem></menuchoice>. In the right +part of the window you will see at least 4 printers predefined. These +are the virtual or special purpose printers, explained in section <!-- <xref +linkend="FIXME"/> -->. You will probably see a toolbar with 13 icons at the +top of the window, and at least 4 tabs in the lower half of the window, +labeled <guilabel>Information</guilabel>, <guilabel>Jobs</guilabel>, +<guilabel>Properties</guilabel> and +<guilabel>Instances</guilabel>.</para> + +<!-- Not needed: the default view is as described, this can be mentioned --> +<!-- elsewhere <para>If you start the <guilabel>Printing --> +<!-- Manager</guilabel> module for the first time, you may be missing --> +<!-- Icons or tabs. <mousebutton>Right</mousebutton>-clicking the mouse --> +<!-- on the white background of the right part of the window opens a --> +<!-- Menu to select your viewing preferences. To get the same view as in --> +<!-- most screenshots, select: <guimenuitem>View Toolbar</guimenuitem> --> +<!-- and <guimenuitem>View Printer Information</guimenuitem> and --> +<!-- <guimenuitem>View Icons</guimenuitem> and <guimenuitem>Orientation --> +<!-- Vertical</guimenuitem>. Moving the mouse over one Button and --> +<!-- waiting a second gives you a tooltip hint about its functions. --> + +<!-- + +3.3 Selection: &CUPS; or other? + +If your selection of the print system is &CUPS;, you will have more +choices at your fingertips than with any other printing +system. &CUPS; is new to most Linux users (even the senior +hackers amongst us), and it is quite easy to use. But it +is at the same time very different from other printing systems. +Therfor the &CUPS; part in the &kdeprint; Handbook is naturally +the most detailed. + +Future editions of the &kdeprint; handbook will describe in +more detail the other systems. +--> + +</sect1> + +</chapter> diff --git a/doc/kdeprint/highlights.docbook b/doc/kdeprint/highlights.docbook new file mode 100644 index 000000000..85e0e348f --- /dev/null +++ b/doc/kdeprint/highlights.docbook @@ -0,0 +1,518 @@ +<chapter id="kdeprint-highlights"> +<title>&kdeprint;'s Highlights</title> + +<para>The new &kdeprint; system includes more than one highlight. +Having worked in an environment in the past that is not exactly +sophisticated, as far as printing is concerned, take a look at some of +the benefits that come with &kdeprint;</para> + +<sect1 id="add-printer-wizard"> +<title>The <quote>Add Printer</quote> Wizard</title> + +<para>&kdeprint; has an <quote>Add Printer Wizard</quote>. The Add +Printer Wizard helps you with adding and configuring a new printer. Of +course, you may do this manually as well.</para> + +<para>&kdeprint; helps you <quote>discover</quote> printers. It is able +to scan the environment for available devices and queues. This works for +network connections using <acronym>TCP</acronym> (AppSocket, +<acronym>aka</acronym> &HP; <trademark +class="registered">JetDirect</trademark>, or <acronym>IPP</acronym>) or +<acronym>SMB</acronym>/Samba (<quote>shared</quote> &Windows;) printers +and partially for directly attached printers over parallel, serial, or +<acronym>USB</acronym> connections.</para> + +<screenshot> +<screeninfo>A screenshot of the new <quote>Add Printer +Wizard</quote></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cupsaddprinterwizard1.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Here's a screenshot of the <quote>Add Printer Wizard</quote> +(this one is not very exciting yet; but...)</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>The wizard makes the installation and handling of the drivers +<quote>a snap</quote>. Selecting, configuring and testing should be easy +as never before on any &Linux;-like system.</para> + +<!-- LW: needs some info where to find it, or a pointer to where in this --> +<!-- doc that is covered --> + +</sect1> + +<sect1 id="print-job-control"> +<title>Full Print Job Control</title> + +<para>The Print Job Viewer is automatically started by &kprinter;. It +may be docked into the &kde; panel (in the system tray). The Print Job +Viewer allows full job management, if supported by the print +subsystem.</para> + +<para>You can:</para> + +<itemizedlist> +<listitem> +<para>Hold and release jobs,</para> +</listitem> +<listitem> +<para>Move pending jobs to another printer,</para> +</listitem> +<listitem> +<para>Cancel pending or processing jobs.</para> +</listitem> +</itemizedlist> + +<para>A screenshot of the &kdeprint; PrintJob Viewer shows the information +you get: Job-ID, target printer, job name, job owner, job status and job +size. In the next &kdeprint; release you will also see information about the +number of pages (as &CUPS; calculates it; see chapter on page accounting +for more information about its merits and limitations).</para> + +<screenshot> +<screeninfo>A screenshot of the &kdeprint; PrintJob Viewer</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kdeprint-jobviewer.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Here's a screenshot of the &kdeprint; PrintJob Viewer.</phrase> +</textobject> +<caption><para>A screenshot of the &kdeprint; PrintJob +Viewer.</para></caption> +</mediaobject> +</screenshot> + +<para>An alternative way to looking at the same information (and having the +same amount of control is through the <inlinemediaobject><imageobject> +<imagedata fileref="kcontrol-icon.png" format="PNG"/></imageobject> +</inlinemediaobject> &kcontrolcenter; selecting +<menuchoice><guilabel>System</guilabel><guilabel>Printing +Manager</guilabel></menuchoice>. If you don't see the +<guilabel>Printer Information</guilabel>, +<mousebutton>right</mousebutton> click on the window +background and select <guilabel>View Printer +Information</guilabel>. Then go to the <guilabel>Jobs</guilabel> tab +to see this:</para> + +<screenshot> +<screeninfo></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kcontrolcenter-printmanager-jobcontrol-2.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Here's a screenshot of the &kdeprint; PrintJob Viewer.</phrase> +</textobject> +</mediaobject> +</screenshot> + +</sect1> + +<sect1 id="modules-for-different-subsystems"> +<title>Modules for different print subsystems</title> + +<para>&kdeprint; uses different modules to realize the interface to the +possible print subsystems. Not all the modules are yet developed fully, +but you will have basic printing functionality with:</para> + +<itemizedlist> +<listitem> +<para><acronym>LPD</acronym> (<acronym>BSD</acronym> style)</para> +</listitem> +<listitem> +<para><acronym>LPRng</acronym> (&RedHat;, if you just use it's +<acronym>BSD</acronym> style subset),</para> +</listitem> +<listitem> +<para><acronym>RLPR</acronym> (a command-line <acronym>LPR</acronym> +utility, which doesn't need a <filename>printcap</filename> file.</para> +</listitem> +<listitem> +<para><quote>external</quote> print commands (&Netscape; like).</para> +</listitem> +</itemizedlist> + +<para>Most importantly, full support for &CUPS; is already there. +Modules for other print subsystems, such as <acronym>PLP</acronym>, +<acronym>PPR</acronym> and <acronym>PDQ</acronym> may be available +later.</para> + +<para>&kdeprint; makes &kde; much more flexible. It gives freedom of +choice to &kde; 2.2 users. To use different available print subsystems, +these must, of course, be installed independently from &kde;. In +former versions, users were stuck with the old <acronym>LPD</acronym> +style print subsystems. Now they can even use &CUPS;. In the future, +there will be easy integration of new subsystems, as they +appear on the scene.</para> + +</sect1> + +<sect1 id="kdeprint-goodies"> +<title>More &kdeprint; <quote>Goodies</quote></title> +<subtitle>Benefitting all Print SubSystems.</subtitle> + +<para>Some specific features of &kdeprint; depend on the chosen print +subsystem. This dependency might exist because those features are only +implemented there; remember, &kdeprint; is an intermediate layer between +&kde; applications, and the print subsystem, but it's no replacement for +any print subsystem by itself. Such dependency may exist for another +reason: that &kdeprint; has not yet implemented an interface to all the +features of all the subsystems.</para> + +<para>Other features include benefits from &kdeprint; that are +independent of the chosen print subsystem, and are available with all of +them. At present there are <quote>special</quote> or +<quote>virtual</quote> printers, and some generic +<quote>pre-filters</quote>.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Print Preview</guilabel></term> +<listitem> +<para>From the Print Dialog, you can select to look at a preview. For +this, the print file is passed through filters which make it suitable for +displaying on screen using &kghostview;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Special Printers</guilabel></term> +<listitem> +<para>Amongst these additional &kdeprint; features are a few +<quote>special</quote> or <quote>virtual</quote> printers:</para> + +<para>These special printers may:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Print to PDF</guilabel></term> +<listitem> +<para>Convert your document into a <acronym>PDF</acronym> file with the +help of an external program.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Print to email</guilabel></term> +<listitem> +<para>Send your document as an email attached <acronym>PDF</acronym> +file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Print to PS file</guilabel></term> +<listitem> +<para>Save your document as a &PostScript; file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Print to Fax</guilabel></term> +<listitem> +<para>Send it through an available backend, such as +<application>Hylafax</application> as a fax.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para>These <quote>special</quote> printers appear in the user print +dialog just like <quote>normal</quote> printers. They are entirely +configurable on a per-user basis.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Generic Pre-Filtering</guilabel></term> +<listitem> +<para>&kdeprint; provides you with a framework to define and configure +your own <quote>pre-filters</quote>. These pre-filters may take effect +<emphasis>before</emphasis> they are passed to your print subsystem for +further processing, but <emphasis>after</emphasis> the (&PostScript;, +plain text or other) print files have been generated by your +application.</para> + +<para>There are a few useful filters already predefined. These +are:</para> + +<itemizedlist> +<listitem> +<para>The <quote>multiple pages per sheet</quote> filter,</para> +</listitem> + +<listitem> +<para>the <quote>enscript</quote> text filter,</para> +</listitem> + +<listitem> +<para>and three filters to help print pamphlets.</para> +</listitem> +</itemizedlist> + +<para>You may create your own filters based on any third party program +that is able to process &PostScript;, plain text or image files, and output +any one of those formats.</para> + +<para>These filters are configured through <acronym>XML</acronym> files. +This makes an extension of the concept very easy for experienced developers, +but end-user configuration is also done through an intuitive graphical +user interface. So, fear not, you don't need to learn +<acronym>XML</acronym> because of &kdeprint;!</para> + +<variablelist> +<varlistentry> +<term><guilabel>Multiple Pages Per Sheet Filter</guilabel></term> +<listitem> +<para>This is a predefined filter that installs with &kdeprint;. It +allows you to create a modified &PostScript; output, from &PostScript; +input, that prints 1, 2, or 4 logical pages on a single sheet of +paper.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Enscript Text Filter</guilabel></term> +<listitem> +<para>This is a predefined filter that installs with &kdeprint;. It +allows you to create &PostScript; output from any text file input, that +includes syntax highlighting for program listings, pretty-printing, and +nice configurable page frames and headers.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Pamphlet Printing Filters</guilabel></term> +<listitem> +<para>If your printer is able to produce duplex output, using either +one-pass or two-pass technology, you may be able to use one, or a +combination, of the <quote>pamphlet</quote> filters.</para> + +<para>For duplexing printers, make sure you use the duplex option that +<quote>turns</quote> the output along the short paper edge. Folding the +printed paper along the middle turns your document into a nice pamphlet.</para> + +<para>If you are stuck with using a simplex-only device, you can do the +same, using two different filters and a few additional steps.</para> + +<para>Depending on your model, first use the filter for printing the +<quote>odd</quote> pages, then insert the paper in the correct order +back into the paper tray to get the even pages printed on the reverse +side. These can then be folded to make a pamphlet.</para> +</listitem> +</varlistentry> + +</variablelist> + +</listitem> +</varlistentry> +</variablelist> +</sect1> +<sect1 id="cups-plugin"> +<title>&CUPS; Support: the Most Important Module in &kdeprint;</title> + +<para>&kdeprint; contains a module for &CUPS;. &CUPS;, the +<quote>Common &UNIX; Printing System</quote> (<ulink +url="http://www.cups.org">http://www.cups.org/</ulink>), is the most +advanced, powerful and flexible of all print subsystems on &UNIX; and +other &UNIX;-like operating systems. It is still quite new on the +horizon, but is based on <acronym>IPP</acronym>, the Internet Printing +Protocol, the newly emerging standard for the future of network +printing. &CUPS; is clearly the print system of choice for Michael +Goffioul, the principal &kdeprint; developer.</para> + +<para>Experienced &kde; users may already be familiar with Michael's +utilities <application>qtcups</application> and +<application>kups</application> (co-developed with Jean-Eric Cuendet). +These were, up until now, the graphical +&GUI; front ends for &CUPS; with a strong relation to &kde;.</para> + +<sect2> +<title><application>qtcups</application> and +<application>kups</application> — The Predecessors</title> + +<para>Both utilities are probably still widely used. For those +not familiar with them, +here are brief explanations.</para> + +<para><application>qtcups</application> was a graphical front end for +the <command>lp</command> or <command>lpr</command> print commands as +installed by &CUPS;. Using <application>qtcups</application> opened a +dialog. This dialog let you comfortably select your printer and the +print job options. <application>qtcups</application> +worked from the command line, or from +within applications, when the application in question had a configurable +print command.</para> + +<para><application>kups</application> was a graphical wrapper to do the +administration tasks for your &CUPS; server, and the &CUPS; daemon at +the heart of it. You could add, delete, modify, configure, start, and +stop printers. You could cancel, delete, move, stop and restart print +jobs, and you could change the settings of the daemon, start, stop, and +restart it.</para> + +</sect2> + +<sect2> +<title>&kdeprint; — The Heir</title> + +<para>The &CUPS; Module in &kdeprint; now contains all (and more) +functions that were provided by <application>qtcups</application> and +<application>kups</application> in former &kde; versions.</para> + +<para>Instead of <command>qtcups</command> you can now use the +<command>kprinter</command> command. And in place of +<command>kups</command> you will probably use +<command>kcmshell printers</command> from now on. +</para> + +<para>The &kdeprint; module for &CUPS; also lets you fully administer +the print subsystem, just like <application>kups</application> did +before. It can start, stop and configure your &CUPS; daemon. It can also +start, stop, add and delete <quote>printers</quote> (&ie; printer +queues) and printer <quote>instances</quote>. Printer instances are +printer queues that point to the same physical output device but with a +different default setting of print options.</para> + +</sect2> + +<sect2> +<title>&kprinter; — Graphical Print Command</title> + +<para>&kdeprint;'s &CUPS; module gives you access to a <quote>graphical +print command</quote>, like <application>qtcups</application> did +before.</para> + +<para>Use &kprinter; in any application, even a non-&kde; +application, that lets you configure your print command. Examples of +these are &Netscape; and <application>StarOffice</application>, but +<emphasis>not</emphasis> most pre-&kde; 2.2 programs.</para> + +<para>A screenshot how to use the new <command>kprinter</command> +print command instead of the old-fashioned <command>lpr</command>... +Of course you need to have <command>kprinter</command> in your +$<envar>PATH</envar>, or give the full path in the dialog; ⪚ +<userinput><filename>/opt/kde/bin/kprinter</filename></userinput>. +&Netscape; will remember this and with further print jobs you will get +the <command>kprinter</command> dialog to configure your printouts.</para> + +<screenshot> +<screeninfo>A screenshot of the <command>kprinter</command> print +command in action.</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kprinter-as-netscape-printcommand.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Here's a screenshot showing how to use the new +<command>kprinter</command> print command +instead of the old-fashioned <command>lp</command> or +<command>lpr</command> in &Netscape;.</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>You can also use <command>&kprinter;</command> from the +command line and see the resulting dialog box pop up:</para> + +<screenshot> +<screeninfo>Screenshot of the <command>kprinter</command> command</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kprinter.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Screenshot showing use of the <command>kprinter</command> command +from the command line.</phrase></textobject> +</mediaobject> +</screenshot> + +<note><para>Just make sure you give at least the file to be printed +from the command line as well: <userinput><command>kprinter</command> +<option>/usr/share/doc/packages/cups/sam.pdf</option></userinput>. +This will hand over the &CUPS; Software Administrator Manual to the +<command>kprinter</command> dialog, which will then pop up with the +default printer pre-selected.</para> + +<para>To pre-select a specific printer from the command line, use the +<option>-d</option> option, ⪚: +<userinput><command>kprinter</command> <option>-d +DANKAcolorC2000</option> +<option>/home/kurt/linuxtag2001-paper.ps</option></userinput>. You +can still de-select the printer <option>DANKAcolorC2000</option> and +choose a different one.</para> + +<para> You <emphasis>cannot</emphasis> however call +<userinput><command>kprinter</command></userinput> +without a print file and hope to open a file selection +dialog box from the &kprinter; window. This is a feature that will be +implemented only in the next version.</para> +</note> + +<para>Using <command>kprinter</command> you are able to <quote>ring +all the bells and blow all the whistles</quote> of your printer. You +will need a device-specific so-called &PPD; (&PostScript; Printer +Description) to enable &CUPS; to make this nice tandem team do this +for you. Read more about this in <xref linkend="ppd-files"/>.</para> + +</sect2> + +</sect1> + +<sect1 id="future-plans"> +<title>Plans for Future Development</title> + +<para>What you have now is the first, already very feature-rich +version of &kdeprint;. This version is, of course, fully usable for +printing. You might even think that <quote>it was never so +easy</quote> (not even back in the days when you had to use +&Microsoft; &Windows;).</para> + +<para> In the future, &kdeprint; will become even better. It will do a +better job of <quote>detecting</quote> your installed print subsystem +itself. Already &kdeprint; is doing quite well in automatically +sensing if you have &CUPS; on your system. But in many cases you will +have to tell &kdeprint; what you are using, if you want to keep a +legacy print system.</para> + +<para>The most important improvement in the near future will be a +completion of the <application>LPRng</application> plugin. This at +present is still very basic. It is restricted to the pure classical +<acronym>LPD</acronym> part of +<application>LPRng</application>.</para> + +<para>Also, you may be able to add printers directly from the print +dialog to your system <quote>just in time</quote>, without going to +&kcontrol; first.</para> + +<para>Some smaller improvements already planned are:</para> + +<itemizedlist> +<listitem><para>add a file selection dialog from the &kprinter; window +to allow combining of additional files to the present +printjob</para></listitem> <listitem><para>add a +<quote>history</quote> button to the +<application>KJobViewer</application> window and also a column to show +the number of pages &CUPS; calculates for the job.</para></listitem> +</itemizedlist> + +<para>Finally, there will be an <quote>IO slave</quote> that will give +you access to your print subsystem, via &konqueror; for example. With +this you will soon be able to browse your print subsystem from +&konqueror; through a &URL; like shortcut such as +<userinput>print://printers/printername</userinput>. A KPart will add +a virtual folder to the services section of the &konqueror; navigation +panel, giving a nice integrated way to browse and manage your print +system via the &URL; <userinput>print:/manager</userinput>.</para> + +<para>Please contact Michael Goffioul at <email>[email protected]</email> +with any further user or developer suggestions.</para> + +</sect1> +</chapter> diff --git a/doc/kdeprint/index.docbook b/doc/kdeprint/index.docbook new file mode 100644 index 000000000..79ef27770 --- /dev/null +++ b/doc/kdeprint/index.docbook @@ -0,0 +1,200 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY CUPS "<acronym>CUPS</acronym>"> + <!ENTITY PPD "<acronym>PPD</acronym>"> + <!ENTITY IPP "<acronym>IPP</acronym>"> + <!ENTITY ghostscript "<application>ghostscript</application>"> + <!ENTITY tech-overview-doc SYSTEM "tech-overview.docbook"> + <!ENTITY highlights-doc SYSTEM "highlights.docbook"> + <!ENTITY getting-started-doc SYSTEM "getting-started.docbook"> + <!ENTITY theory-doc SYSTEM "theory.docbook"> + <!ENTITY cups-configuration-doc SYSTEM "cups-config.docbook"> + <!ENTITY add-printer-wizard-2-doc SYSTEM "add-printer-wiz.docbook"> + <!ENTITY cupsoptions-presently-outside-kcontrol-doc SYSTEM +"cupsoptions.docbook"> + <!ENTITY rlpr-doc SYSTEM "rlpr.docbook"> + <!ENTITY lpd-doc SYSTEM "lpd.docbook"> + <!ENTITY lpr-bsd-doc SYSTEM "lpr-bsd.docbook"> + <!ENTITY lprng-doc SYSTEM "lprng.docbook"> + <!ENTITY external-command-doc SYSTEM "external-command.docbook"> + <!ENTITY extensions-doc SYSTEM "extensions.docbook"> + <!ENTITY final-word-doc SYSTEM "final-word.docbook"> + <!ENTITY kappname "&kdeprint;"><!-- replace kapp here --> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"><!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kdeprint; Handbook</title> + +<authorgroup> +<author> +<firstname>Kurt</firstname> +<surname>Pfeifle</surname> +<affiliation> +<address><email>[email protected]</email></address> +</affiliation> +</author> + +<othercredit role="developer"> +<firstname>Michael</firstname> +<surname>Goffioul</surname> +<affiliation> +<address><email>[email protected]</email></address> +</affiliation> +<contrib>Developer</contrib> +</othercredit> + +<othercredit role="reviewer"> +<firstname>Lauri</firstname> +<surname>Watts</surname> +<affiliation> +<address><email>[email protected]</email></address> +</affiliation> +<contrib>Reviewer</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2001</year> +<holder>Kurt Pfeifle</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2001-08-09</date> +<releaseinfo>1.00.04</releaseinfo> + +<abstract> +<para>This handbook describes &kdeprint;. &kdeprint; is not a standalone +program. It is the new printing framework for &kde; 2.2. &kdeprint; +is an intermediate layer between &kde; (or other) applications and the selected +(and installed) print subsystem of your OS (&OS;).</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdebase</keyword> +<keyword>kdeprint</keyword> +<keyword>print</keyword> +<keyword>printing</keyword> +<keyword>CUPS</keyword> +<keyword>LPR</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>This handbook describes &kdeprint;. &kdeprint; is not a standalone +program. It is the new printing framework for &kde; 2.2. &kdeprint; +is an intermediate layer between &kde; (or other) applications and the selected +(and installed) print subsystem of your OS (&OS;).</para> + +<para>It should be noted that both the developer of this application, +and the author of this document are most familiar with &CUPS; as a +printing system. At the time of writing, &CUPS; is the best supported +printing subsystem, and it is the best documented.</para> + +<para>This handbook is a work in progress, and later versions of the +&kdeprint; software and editions of this handbook will support and +explore more closely other printing systems.</para> + +<para>In the meantime, even if your printing subsystem is not yet well +covered, you are encouraged to explore the <guilabel>Printing +Manager</guilabel> module in &kcontrol;, and you will find its +operation to hopefully be fairly self evident, no matter what printing +subsystem you use.</para> + +<para>Lauri Watts, &kde; documentation team</para> + +<!-- Insert here screenshot : <steinbruch_scaled.png> --> + +<sect1> +<title>To configure your printing subsystem from &kcontrol;</title> + +<para>To configure your printing subsystem from &kcontrol;, go to +<menuchoice><guilabel>System</guilabel><guilabel>Printing +Manager</guilabel></menuchoice> and select your subsystem. Or you can +let &kdeprint; try to determine it... </para> + +<screenshot> +<screeninfo>&CUPS; Printing Manager dialog: overview via &kcontrol;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="steinbruch_scaled.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The dialog to configure the &CUPS; server: security +settings</phrase></textobject> +<caption><para>Configuration of printing subsystem from +&kcontrol;</para></caption> +</mediaobject> +</screenshot> +</sect1> + +</chapter> + +&tech-overview-doc; + +&highlights-doc; + +&theory-doc; + +&getting-started-doc; + +&cups-configuration-doc; + +&add-printer-wizard-2-doc; + +&cupsoptions-presently-outside-kcontrol-doc; + +&rlpr-doc; + +&lpd-doc; + +&lpr-bsd-doc; + +&lprng-doc; + +&external-command-doc; + +&extensions-doc; + +&final-word-doc; + +<chapter id="credits-and-license"> +<title>Credits And Licenses</title> + +<para>&kdeprint; copyright 2001, Michael Goffioul +<email>[email protected]</email></para> +&underGPL; + +<para>Documentation copyright 2001, Kurt Pfeifle, +<email>[email protected]</email></para> +&underFDL; + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +</chapter> + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +// vim:ts=2:sw=2:tw=78:noet +--> diff --git a/doc/kdeprint/kcontrol-icon.png b/doc/kdeprint/kcontrol-icon.png Binary files differnew file mode 100644 index 000000000..8fbaacd79 --- /dev/null +++ b/doc/kdeprint/kcontrol-icon.png diff --git a/doc/kdeprint/kcontrolcenter-printmanager-jobcontrol-2.png b/doc/kdeprint/kcontrolcenter-printmanager-jobcontrol-2.png Binary files differnew file mode 100644 index 000000000..d7132b1cd --- /dev/null +++ b/doc/kdeprint/kcontrolcenter-printmanager-jobcontrol-2.png diff --git a/doc/kdeprint/kcron_to_be_printed.png b/doc/kdeprint/kcron_to_be_printed.png Binary files differnew file mode 100644 index 000000000..114b26b3c --- /dev/null +++ b/doc/kdeprint/kcron_to_be_printed.png diff --git a/doc/kdeprint/kdeprint-jobviewer.png b/doc/kdeprint/kdeprint-jobviewer.png Binary files differnew file mode 100644 index 000000000..8182e4317 --- /dev/null +++ b/doc/kdeprint/kdeprint-jobviewer.png diff --git a/doc/kdeprint/kprinter-as-netscape-printcommand.png b/doc/kdeprint/kprinter-as-netscape-printcommand.png Binary files differnew file mode 100644 index 000000000..0780e2a80 --- /dev/null +++ b/doc/kdeprint/kprinter-as-netscape-printcommand.png diff --git a/doc/kdeprint/kprinter-kivio.png b/doc/kdeprint/kprinter-kivio.png Binary files differnew file mode 100644 index 000000000..b36b49b89 --- /dev/null +++ b/doc/kdeprint/kprinter-kivio.png diff --git a/doc/kdeprint/kprinter.png b/doc/kdeprint/kprinter.png Binary files differnew file mode 100644 index 000000000..f83cfcd4b --- /dev/null +++ b/doc/kdeprint/kprinter.png diff --git a/doc/kdeprint/kprinter_called_from_run_command.png b/doc/kdeprint/kprinter_called_from_run_command.png Binary files differnew file mode 100644 index 000000000..b02070c1d --- /dev/null +++ b/doc/kdeprint/kprinter_called_from_run_command.png diff --git a/doc/kdeprint/kprinter_with_kcron_developer_special.png b/doc/kdeprint/kprinter_with_kcron_developer_special.png Binary files differnew file mode 100644 index 000000000..dc9b785cf --- /dev/null +++ b/doc/kdeprint/kprinter_with_kcron_developer_special.png diff --git a/doc/kdeprint/lpd.docbook b/doc/kdeprint/lpd.docbook new file mode 100644 index 000000000..cc555e399 --- /dev/null +++ b/doc/kdeprint/lpd.docbook @@ -0,0 +1,18 @@ +<chapter id="lpd-module"> +<title>Generic <acronym>LPD</acronym> Module (&UNIX;)</title> + + +<sect1> +<title>Overview of Provided Features</title> + +<para>Module used by default (on first start for example).</para> + +<para>Generic module that only allows sending of print jobs. No printer or +job management supported. It is made to work on a wide variety of &UNIX; +flavors: &Linux;/<acronym>LPR</acronym>, &HP-UX;, Solaris, &IRIX;. +It also supports some <application>LPRng</application> extensions (like +the absence of continuation character <literal>\</literal> in +<filename>printcap</filename> files).</para> + +</sect1> +</chapter> diff --git a/doc/kdeprint/lpr-bsd.docbook b/doc/kdeprint/lpr-bsd.docbook new file mode 100644 index 000000000..007fbc6e5 --- /dev/null +++ b/doc/kdeprint/lpr-bsd.docbook @@ -0,0 +1,25 @@ +<chapter id="lpr-bsd-style-module"> +<title><acronym>LPR</acronym> (<acronym>BSD</acronym>)</title> + +<para>Plain (old?) <acronym>LPR</acronym> support. An +<acronym>LPRng</acronym> module is in development, and hopefully +available for 2.3 release.</para> + +<sect1> +<title>Overview of Provided Features</title> + +<itemizedlist> +<listitem> +<para>Printer management: basic support to add/remove/configure a +printer, compatible with &RedHat;-6.x systems +(<command>printtool</command> + rhs-printfilers packages).</para> +</listitem> +<listitem> +<para>Job management: not supported</para> +</listitem> +<listitem> +<para>Print options: basic control</para> +</listitem> +</itemizedlist> +</sect1> +</chapter> diff --git a/doc/kdeprint/lprng.docbook b/doc/kdeprint/lprng.docbook new file mode 100644 index 000000000..5117664e0 --- /dev/null +++ b/doc/kdeprint/lprng.docbook @@ -0,0 +1,7 @@ +<chapter id="lprng-module"> +<title><application>LPRng</application></title> + +<para>An <application>LPRng</application> module for &kdeprint; is in +development, and hopefully available for the &kde; 2.3 release.</para> + +</chapter> diff --git a/doc/kdeprint/ps-boxes.png b/doc/kdeprint/ps-boxes.png Binary files differnew file mode 100644 index 000000000..a24f845a7 --- /dev/null +++ b/doc/kdeprint/ps-boxes.png diff --git a/doc/kdeprint/rlpr.docbook b/doc/kdeprint/rlpr.docbook new file mode 100644 index 000000000..fab48d7bb --- /dev/null +++ b/doc/kdeprint/rlpr.docbook @@ -0,0 +1,18 @@ +<chapter id="rlpr-module"> +<title>Module Built Around <application>rlpr</application> +Utility</title> + +<sect1> +<title>Overview of provided features</title> + +<para>Printer management: basic operations are supported +(add/remove/modify).</para> + +<para>Each user can predefine the printers he wants to use by specifying +the host and related printer queues. Printers are stored on a <quote>per +user basis</quote>. This module is built around the +<application>rlpr</application> utility <ulink +url="http://truffula.com/rlpr/">rlpr</ulink></para> + +</sect1> +</chapter> diff --git a/doc/kdeprint/steinbruch_scaled.png b/doc/kdeprint/steinbruch_scaled.png Binary files differnew file mode 100644 index 000000000..57e6fde76 --- /dev/null +++ b/doc/kdeprint/steinbruch_scaled.png diff --git a/doc/kdeprint/tech-overview.docbook b/doc/kdeprint/tech-overview.docbook new file mode 100644 index 000000000..96b3888e9 --- /dev/null +++ b/doc/kdeprint/tech-overview.docbook @@ -0,0 +1,280 @@ +<chapter id="technical-overview"> +<title>Technical Overview</title> + +<para>This chapter aims to give a technical overview of &kdeprint; which +non-programmers can comprehend.</para> + +<para>&kdeprint; is a new and revolutionary tool to give easy access to +printing services for both &kde; users and &kde; developers.</para> + +<sect1 id="brief-description"> +<title>A Brief Description of &kdeprint;</title> + +<para>You can access the functions of &kdeprint; in different ways: +through the Printing Manger in the &kcontrol;, through the +<command>kprinter</command> command or through the dialog that pops up +if you want to print.</para> + +<sect2 id="what-kdeprint-is-not"> +<title>What it is <emphasis>not</emphasis></title> + +<para>&kdeprint; is <emphasis>not</emphasis> a replacement for the +printing subsystem itself. &kdeprint; does <emphasis>not</emphasis> +therefore give provision for spooling, and it does +<emphasis>not</emphasis> do the basic processing of &PostScript; or +other print data.</para> + +</sect2> + +<sect2 id="what-kde-print-is"> +<title>What it <emphasis>is</emphasis></title> +<para>&kdeprint; is an intermediate layer between the spooling and the +data processing print subsystem (as installed), and the application that +seeks to print. &kdeprint; provides a common interface for &kde; +developers and &kde; users, to various supported print subsystems. At +the same time, it is customizable, and highly configurable.</para> + +<para>&kdeprint; is easy to use for both &kde; developers and end-users. +Developers can port their applications, with minimal changes, to use +&kdeprint; instead of the old &Qt; print <quote>system</quote>. Users +can easily choose and configure their print subsystem.</para> + +<para>For a reference to new &kde; users: &Qt; is the basic library and +graphical toolkit, which is used by all &kde; applications; &Qt; is +developed by TrollTech, a Norwegian software company.</para> + +</sect2> + +</sect1> + +<sect1 id="different-users"> +<title>&kdeprint; -- Different Usage for Different People</title> + +<para>&kdeprint; has different faces for different people.</para> + +<sect2 id="what-users-can-do"> +<title>What users and administrators can do with &kdeprint;</title> + +<para>&kdeprint; allows users and/or administrators, depending on their +rights, access to printing subsystems (&CUPS;, <acronym>LPD</acronym>, +<acronym>RLPR</acronym>, <application>LPRng</application>, +<application>PDQ</application> &etc;) through a &kde; graphical user +interface (&GUI;). Using &kdeprint;, they can print, administer jobs, +printers and the printing daemon, all in a comfortable manner.</para> + +<para>Experienced users will like the capability to plug any working +filter for the print data between the output of their application and +the input, into the chosen print subsystem. Some examples for this +already ship with <quote>plain vanilla</quote> &kdeprint;. Read +on.</para> + +</sect2> + + +<sect2 id="what-developers-can-do"> +<title>What &kde; developers can do with it...</title> + +<para>If a &kde; developer needs printing access for his application, he +does not code the printing functions from scratch. Before &kde; 2.2 this +service was provided by the <classname>QPrinter</classname> class, a +library function of the &Qt; Toolkit. The +<classname>QPrinter</classname> class relied on the out-moded +<quote>Line Printer Daemon</quote> (<acronym>LPD</acronym>). The +&kdeprint; library bases itself firmly on the more modern Common &UNIX; +Printing System (&CUPS;), while at the same time keeping backward +compatibility with <acronym>LPD</acronym> and other legacy, or less +elaborate, print systems. It also <quote>leaves the door open</quote> +for any new development that might occur.</para> + +<para>For &kde; developers to use the new &kdeprint; class in their +applications, they require only minimal changes to their code: for every +call of <classname>QPrinter</classname>, they just need to change this to +<classname>KPrinter</classname>. Replacing one (!) letter in a few +spots, and automatically they are done; their application can then use +all of the features of the new &kdeprint; library.</para> + +<para>More ambitious developers, or ones with special requirements, can +do more: despite &kdeprint;'s feature-rich framework, they are still able +to customize the print dialog of their application +by creating an additional <quote>Tab</quote>, where their +extensions to the standard &kdeprint; will feel right at home.</para> + + +<para>This last mentioned feature has not been used widely inside +&kde; so far, as developers are not yet fully aware of &kdeprint;'s +power. Expect more of this in the near future. One example I +discovered is the &kcron; application. It lets you edit the crontab +through a &GUI;. The developers have implemented a printing feature +that lets you (or <systemitem class="username">root</systemitem>) +choose if you want to print the whole of crontab (for all users) or +just the part that is marked. You can see the effects on &kdeprint; +in the following screenshots.</para> + +<para>This shot shows a sample from the &kcron; utility. +<screenshot> +<screeninfo>&kcron; utility: a small sample of a system's cronjobs as +shown through the &kde; <acronym>GUI</acronym>&GUI;.</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kcron_to_be_printed.png" +format="PNG"/></imageobject> +<textobject> +<phrase>The &kcron; developers let you choose to print the whole of the +cron table or just the marked part of it.</phrase></textobject> +</mediaobject> +</screenshot> +</para> + +<para>The dialog to configure &kcron;'s printing options: the +additional tab titled <guilabel>Cron Options</guilabel> is from inside +&kcron;, not &kdeprint;; it is a special extension added by the +&kcron; developers for printing purposes, not originating from, but +executed by &kdeprint;. Developers of other applications are free +to implement their own goodies, if they feel need for it.</para> + + +<screenshot> +<screeninfo>&kcron;'s addition to the &kdeprint; dialog.</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kprinter_with_kcron_developer_special.png" +format="PNG"/></imageobject> +<textobject> +<phrase>&kcron;'s addition to the &kdeprint; dialog.</phrase></textobject> +<caption> +<para>&kcron;'s addition to the &kdeprint; dialog.</para> +</caption> +</mediaobject> +</screenshot> + +</sect2> + +<sect2> +<title>What &kdeprint; offers to everybody...</title> + +<para>&kdeprint;'s easy-to-use interface for all supported print subsystems +of course does not eliminate basic traditional weaknesses of some of +those systems. But it smooths some rough edges. Different users may use +different printing systems on the same box. A user is free to even +switch <quote>on the fly</quote>, from the print dialog, the print +subsystem to be used for the next job. (This is possible if different +systems are installed in a way that they don't <quote>get in each +other's way</quote>.)</para> + +<para>Most &UNIX; users are used to +<acronym>LPD</acronym> printing. <acronym>LPD</acronym> provides only +basic printing functions, is very inflexible and does not utilize the +many options of more modern print systems like &CUPS;. While also +working remotely over any distance (like every TCP/IP based protocol), +<acronym>LPD</acronym> lacks bi-directional communication, +authentication, access control and encryption support.</para> + +<para>&kdeprint; can use &CUPS; to support:</para> + +<itemizedlist> +<listitem> +<para>Querying the <acronym>LAN</acronym> for available printers,</para> +</listitem> +<listitem> +<para>Basic, Digest, and Certificate Authentication,</para> +</listitem> +<listitem> +<para>Access Control based on <acronym>IP</acronym> addresses, net +addresses, netmasks, host- and domain names,</para> +</listitem> +<listitem> +<para>and 128-Bit TLS or SSL3 encryption of print data, to prevent +eavesdropping, or at least make it much more difficult.</para> +</listitem> +</itemizedlist> + +<para>This makes &kdeprint; a much more robust and reliable solution +than using the venerable <acronym>LPD</acronym>.</para> + +</sect2> +<sect2> +<title>How to access &kdeprint; </title> + +<para>You get access to &kdeprint;, or parts of it, in four different +ways:</para> + +<itemizedlist> +<listitem><para>through your applications: if you call the printing +dialog (either <menuchoice><guilabel>File</guilabel> +<guilabel>Print...</guilabel></menuchoice>) or the button with the +little printer icon on it; this opens the printing +dialog.</para></listitem> + +<listitem><para>through the typed command <command>kprinter</command> +in a <application>terminal</application> or a &konsole; window or from +the <guilabel>Run Command...</guilabel> mini-<acronym>CLI</acronym> +window: this also opens the printing dialog.</para></listitem> + +<listitem><para>from the <inlinemediaobject><imageobject> <imagedata +fileref="kcontrol-icon.png" format="PNG"/></imageobject> +</inlinemediaobject> button, starting &kcontrol;, and then go to +<menuchoice><guilabel>System</guilabel><guilabel>Printing +Manager</guilabel></menuchoice>. This opens the &kdeprint; +administration which is part of the &kcontrolcenter; and also lets +you switch to other parts of the &kcontrol;</para></listitem> + +<listitem><para>from a command line (&konsole; or +mini-<acronym>CLI</acronym>) type <userinput> +<command>kcmshell</command> <option>printers</option></userinput>. +This opens just the &kdeprint; part of &kcontrol; to change your settings +</para></listitem> +</itemizedlist> +<screenshot> +<screeninfo>&kprinter; dialog to be started from <guilabel>Run Command...</guilabel> window</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kprinter_called_from_run_command.png" +format="PNG"/></imageobject> +<textobject> +<phrase>Starting the &kprinter; dialog from +a <guilabel>Run Command...</guilabel> window.</phrase></textobject> +<caption><para>Starting the &kprinter; dialog from a <guilabel>Run +Command...</guilabel> window.</para></caption> +</mediaobject> +</screenshot> + +<!-- TODO: This one ought to be a screenshot LW. --> <para>Here is a +&kivio; drawing of the &kprinter; dialog as it pops up after being +started... You can always add a new printer by clicking on the small +<guiicon>Wizard</guiicon> button (marked red/yellow in this +drawing).</para> + +<screenshot> +<screeninfo>&kprinter; dialog started (&kivio; draft drawing) +</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kprinter-kivio.png" +format="PNG"/></imageobject> +<textobject> +<phrase>&kprinter; dialog started (&kivio; draft drawing)</phrase></textobject> +<caption><para>&kprinter; dialog started (&kivio; draft +drawing)</para></caption> +</mediaobject> +</screenshot> + +</sect2> + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:"index.docbook" "book" +End: +--> diff --git a/doc/kdeprint/theory.docbook b/doc/kdeprint/theory.docbook new file mode 100644 index 000000000..a90aa2755 --- /dev/null +++ b/doc/kdeprint/theory.docbook @@ -0,0 +1,690 @@ +<chapter id="theory"> +<title>Some Theoretical Background: &CUPS;, <acronym>IPP</acronym>, +&PostScript; and <application>Ghostscript</application></title> + +<para>This chapter aims to give a bit of theoretical background to +printing in general, and to &CUPS; especially. If you are not in need +of this, you might like to skip ahead to the <link +linkend="getting-started">next chapter</link>. Chances are you will +come back to this chapter at some point anyway, because sometimes one +needs extra theory to solve a practical problem.</para> + +<sect1 id="basics-of-printing"> +<title>Basics About Printing</title> + +<para>Printing is one of the more complicated chapters in +<acronym>IT</acronym> technology.</para> + + +<para>Earlier on in history, every developer of a program that was +capable of producing printable output had to write his own printer +drivers too. That was quite complicated, because different programs +have different file formats. Even programs with the same purpose, for +example: word processors, often do not understand each other's formats. +There was therefore no common interface to all printers, hence the +programmers often supported only a few selected models.</para> + +<para>A new device appearing on the market required the program authors +to write a new driver if they wanted their program to support it. Also +for manufacturers, it was impossible to make sure their device was +supported by any program known to the world (although there were far +fewer than today).</para> + +<para>Having to support ten application programs and a dozen printers, +meant a system administrator had to deal with 120 drivers. So the +development of unified interfaces between programs and printers became +an urgent need.</para> + +<para>The appearance of <quote>Page Description Languages</quote>, +describing the graphical representation of ink and toner on sheets of +paper (or other output devices, like monitors, photo typesetters, &etc;) +in a common way, was a move that filled a big gap. <!-- FIXME --></para> + +<para>One such development was &PostScript; by Adobe. It meant that an +application programmer could concentrate on making his program generate +a &PostScript; language description of his printable page, while +printing device developers could focus on making their devices +&PostScript; literate.</para> + +<para>Of course, over time, there came the development of other description +methods. The most important competitors to &PostScript; were +<acronym>PCL</acronym> (<quote>Print Control Language</quote>, from +&Hewlett-Packard;), <quote>ESC/P</quote> (from Epson) and +<acronym>GDI</acronym> (<quote>Graphical Device Interface</quote> from +&Microsoft;).</para> + +<para>The appearance of these page description languages made life easier, +and facilitated further development for everybody. Yet the fact that there +still remained different, incompatible, and competing page description +languages keeps life for users, administrators, developers and +manufacturers difficult enough.</para> + +<sect2> +<title>&PostScript; in memory - Bitmaps on Paper</title> + +<para>&PostScript; is most heavily used in professional printing +environments such as PrePress and printing service industries. In the +&UNIX; and &Linux; domains, &PostScript; is the predominant standard +as a <acronym>PDL</acronym>. Here, nearly every program generates a +&PostScript; representation of its pages once you push the +<quote>Print</quote> button. Let us look at a simple example of +(hand-made) &PostScript; code. The following listing describes two +simple drawings:</para> + +<example id="coded-postscript"> +<title>&PostScript; Code</title> +<screen>%!PS +100 100 moveto +0 50 rlineto +50 0 rlineto +0 -50 rlineto +closepath +.7 setgray fill +% first box over; next +160 100 moveto +0 60 rlineto +45 10 rlineto +0 -40 rlineto +closepath +.2 setgray fill</screen> +</example> + +<para>This tells the imaginary &PostScript; <quote>pen</quote> to draw +a path of a certain shape, and then fill it with different shades of +gray. The first part translates into more comprehensive English as +<quote>Go to coordinate (100,100), draw a line with length 50 upward; +then one from there to the right, then down again, and finally close +this part. Now fill the drawn shape with 70% darkness gray.</quote></para> + +<example id="rendered-postscript"> +<title>Rendered &PostScript;</title> +<mediaobject> +<imageobject> +<imagedata fileref="ps-boxes.png" format="PNG"/> +</imageobject> +<textobject> +<phrase><xref linkend="coded-postscript"/> example rendered as an +image.</phrase> +</textobject> +</mediaobject> +</example> + +<para>Of course, &PostScript; can be much more complicated than this +simplistic example. It is a fully fledged programming language with +many different operators and functions. You may even write +&PostScript; programs to compute the value of Pi, format a hard disk or +write to a file. The main value and strength of &PostScript; however +lies in the field to describe the layout of graphical objects on a +page: it also can scale, mirror, translate, transform, rotate and +distort everything you can imagine on a piece of paper -- such as +letters in different font representations, figures, shapes, shades, +colors, lines, dots, raster...</para> + +<para>A &PostScript; file is a representation of one or more pages +to be printed, in a relatively abstract way. Ideally, it is meant +to describe the pages in a device-independent way. &PostScript; is +not directly <quote>visible</quote>; it only lives on hard disks +and in <acronym>RAM</acronym> as a coded representation of +future printouts.</para> + +</sect2> + +<sect2> +<title>Raster Images on Paper Sheets</title> + +<para>What you see on a piece of paper is nearly always a +<quote>raster image</quote>. Even if your brain suggests to you that +your eyes see a line: take a good magnifying glass and you will +discover lots of small dots... (One example to the contrary are +lines that have been drawn by <quote>pen plotters</quote>). And that +is the only thing that the <quote>marking engines</quote> of today's +printers can put on paper: simple dots of different colors, size and +resolution, to make up a complete <quote>page image</quote> composed of +different bitmap patterns.</para> + +<para>Different printers need the raster image prepared in different +ways. Thinking about an inkjet device: depending on its resolution, +the number of inks used (the very good ones need 7 different inks, while +cheaper ones might only use 3), the number of available jets (some print +heads have more than 100!) dispensing ink simultaneously, the +<quote>dithering algorithm</quote> used, and many other things, the +final raster format and transfer order to the marking engine is heavily +dependent on the exact model used.</para> + +<para>Back in the early life of the <quote>Line Printer Daemon</quote>, +printers were machines that hammered rows of <acronym>ASCII</acronym> +text mechanically on to long media, folded as a zig-zag paper +<acronym>snake</acronym>, drawn from a cardboard box beneath the +table... What a difference from today!</para> + +</sect2> + + +<sect2> +<title><acronym>RIP</acronym>: From &PostScript; to Raster</title> + +<para>Before the final raster images are put on paper cut-sheets, they +have to be calculated somehow out of their abstract &PostScript; +representation. This is a very computing-intensive process. It is called +the <quote>Raster Imaging Process</quote>, more commonly +<quote><acronym>RIP</acronym></quote>).</para> + +<para>With &PostScript; printers the <acronym>RIP</acronym>-ping is +taken care of by the device itself. You just send the &PostScript; +file to it. The <quote>Raster Imaging Processor</quote> (also called the +<acronym>RIP</acronym>) inside the printer is responsible (and +specialized) to fulfill quite well this task of interpreting the +&PostScript;-page descriptions and put the raster image on paper.</para> + +<para>Smaller &PostScript; devices have a +hardware-<acronym>RIP</acronym> built in; it is etched in silicon, on a +special chip. Big professional printers often have their +<acronym>RIP</acronym> implemented as a software-<acronym>RIP</acronym> +inside a dedicated fast &UNIX; run computer, often a Sun SPARC Solaris +or a &SGI; &IRIX; machine.</para> + +</sect2> + +<sect2> +<title><application>Ghostscript</application> as a Software +<acronym>RIP</acronym></title> + +<para>But what happens, if you are not lucky enough to have a +&PostScript; printer available?</para> + +<para>You need to do the <acronym>RIP</acronym>-ing before you send +the print data to the marking engine. You need to digest the &PostScript; +generated by your application on the host machine (the print client) +itself. You need to know how the exact raster format of the target +printer's marking engine must be composed.</para> + +<para>In other words, as you can't rely on the printer to understand +and interpret the &PostScript; itself, the issue becomes quite a bit +more complicated. You need software that tries to solve for you the +issues involved.</para> + +<para>This is exactly what the omnipresent &ghostscript; package is +doing for many &Linux;, *BSD and other &UNIX; boxes that need to print +to non-&PostScript; printers: &ghostscript; is a &PostScript; +interpreter, a software <acronym>RIP</acronym> capable of running many +different devices.</para> + +</sect2> + +<sect2> +<title><quote>Drivers</quote> and <quote>Filters</quote> in General</title> + +<para>To produce rasterized bitmaps from &PostScript; input, the +concept of <quote>filters</quote> is used by &ghostscript;. There are +many different filters in &ghostscript;, some of them specialized for +a certain model of printer. &ghostscript; filterspecializedin devices +have often been developed without the consent or support of the +manufacturer concerned. Without access to the specifications and +documentation, it was a very painstaking process to reverse engineer +protocols and data formats.</para> + +<para>Not all &ghostscript; filters work equally well for their +printers. Yet, some of the newer ones, like the +<application>stp</application> Filter of the +<application>Gimp</application> Print project, produce excellent +results leading to photographic quality on a par or even superior to +their &Microsoft; &Windows; driver counterparts.</para> + +<para>&PostScript; is what most application programs produce for +printing in &UNIX; and &Linux;. Filters are the true workhorses of +any printing system there. Essentially they produce the right bitmaps +from any &PostScript; input for non-&PostScript; target +engines.</para> + +</sect2> + +<sect2> +<title>Drivers and Filters and Backends in CUPS</title> + +<para>&CUPS; uses its own filters, though the filtering system is +based on Ghostscript. Namely the pstoraster and the imagetoraster +filters are directly derived from Ghostscript code. &CUPS; has +reorganized and streamlined the whole mechanics of this legacy code +and organized it into a few clear and distinct modules.</para> + +<para>This next drawing (done with the help of &kivio;) gives an +overview of the filters and backends inside &CUPS; and how they fit +together. The <quote>flow</quote> is from top to bottom. Backends +are special filters: they don't convert date to a different format, +but they send the ready files to the printer. There are different +backends for different transfer protocols.</para> + +<screenshot id="architecture-diagram"> +<screeninfo>&kprinter; dialog started (&kivio; draft drawing) +</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="cups-filterarchitecture-kivio-70Percent-scaled.png" +format="PNG"/></imageobject> +<textobject> +<phrase>&kprinter; dialog started (&kivio; draft +drawing)</phrase></textobject> +</mediaobject> +</screenshot> + +</sect2> +<sect2> +<title>Spoolers and Printing Daemons</title> + +<para>Besides the heavy part of the filtering task to generate a +print-ready bitmap, any printing software needs to use a SPOOLing +mechanism: this is to line up different jobs from different users for +different printers and different filters and send them accordingly to +the destinations. The printing daemon takes care of all this.</para> + +<para>This daemon is keeping the house in order: it is also +responsible for the job control: users should be allowed to cancel, +stop, restart, &etc; their jobs (but not other peoples's jobs) and so +on.</para> + +</sect2> + +</sect1> + + + +<sect1 id="cups-and-ppd"> +<title>Excursion: How <quote>CUPS</quote> uses the power of +&PPD;s</title> + +<para>Now that you know how a &PostScript; language file (which +describes the page layout in a largely device independent way) is +transformed into a Raster Image, you might ask: +<quote>Well, there are different kinds of raster output devices: first +they differ in their resolution; then there are the different paper +sizes; it goes on with many finishing options (duplex prints, +pamphlets, punched and stapled output with different sheets of colored +paper being drawn from different trays, &etc;). How does this fit into +our model of device-independent &PostScript;?</quote></para> + +<para>The answer comes with so called &PostScript; Printer Description +(&PPD; files. A &PPD; describes all the device dependent features +which can be utilized by a certain printer model. It also contains +the coded commands that must be used to call certain features of the +device. But &PPD;s are not a closed book, they are simple +<acronym>ASCII</acronym> text files.</para> + +<para>&PPD;s were <quote>invented</quote> by Adobe to make it easy for +manufacturers to implement their own features into &PostScript; +printers, and at the same time retain a standard way of doing so. +&PPD;s are well documented and described by Adobe. Their +specification is a de-facto open standard.</para> + +<sect2 id="ppd-files"> +<title>Device Dependent Print Options</title> + +<para>Remember, advanced &PostScript; printing was originally only +developed for use on &Microsoft; &Windows; and Apple &Mac; systems. +For a long time, all of the feature rich printing on modern devices +was simply unavailable for &Linux; and &UNIX;. &CUPS; changes this +decisively. &CUPS; is closely tied with &PPD;s, and therefore existing +&PPD;s can be utilized to the full by all systems powered by +&CUPS;.</para> + +<para>Using &PPD;s, printer manufacturers were able to insert +device-specific hardware features into their products, for features such +as duplexing, stapling, punching, finishing, &etc;. The printer drivers +load this &PPD; just like an additional configuration file. Thus the +printer driver learns about the available device options and how to +call them; the driver also presents them in a &GUI; to the user. Through +this mechanism you are still able to print +<quote>device-independent</quote> &PostScript; page description +language files and specify device-dependent finishing options on top, +which are added to the application-generated &PostScript;.</para> + +</sect2> + +<sect2> +<title>Where to get the &PPD;s for &PostScript; Printers</title> + +<para>&PPD;s originally were not used routinely in &UNIX; and &Linux; +systems. The vendors providing those &PPD;s never intended them for +anything other than the originally supported &OS;s: &Microsoft; &Windows; and +&MacOS;. Through its brilliant move to fully support and utilize +the existing &PPD; specification, &CUPS; now gives the power to use +all features of modern printers to users of &Linux; and &Linux;-like +systems. &kdeprint; makes its usage even more comfortable than the +&CUPS; developers ever dreamed of.</para> + +<para>&CUPS; can use original &Windows; &PPD;s, distributed by the +vendors in the case of &PostScript; printers. Those normally don't +cost any money, and they can be grabbed from any &Windows; computer +with an installed &PostScript; driver for the model concerned, or from +the disks provided with the printer. There are also several places on +the web to download them.</para> + +</sect2> + +<sect2> +<title>How Special &PPD;s are Now Useful Even For Non-&PostScript; +Printers.</title> + +<para>Now you know how &PostScript;-Printers can use &PPD;s. But what +about non-&PostScript; printers? &CUPS; has done a very good trick: by +using the same format and data structure as the &PostScript; Printer +Descriptions (&PPD;s) in the &PostScript; world, it can describe the +available print job options for non-&PostScript; printers just the +same. For its own special purposes &CUPS; just added a few special +options (namely the line which defines the filter to be used for +further processing of the &PostScript; file).</para> + +<para>So, the developers could use the same software engine to parse +the Printer Description Files for available options for all sorts of +printers. Of course the &CUPS; developers could not rely on the +non-&PostScript; hardware manufacturers to suddenly develop &PPD;s. +They had to do the difficult start themselves and write them from +scratch. More than 1000 of these are available through the commercial +version of &CUPS;, called <application>ESP +PrintPro</application>.</para> + +<para>Meanwhile there are a lot of &CUPS;-specific &PPD;s available. +Even now those are in most cases not originating from the printer +manufacturers, but from Free software developers. The &CUPS; folks +proofed it, and others followed suit: where &Linux; and &UNIX; +printing one or two years ago still was a kludge, it is now able to +support a big range of printers, including 7-color inkjets capable of +pushing them to Photo Quality output.</para> + +</sect2> + +<sect2> +<title>Different Ways to get &PPD;s for non-&PostScript; +Printers</title> + +<para>You can get &PPD;s to be used with &CUPS; and non-&PostScript; +printers from different areas in the Web:</para> + +<itemizedlist> +<listitem> +<para> first, there is the repository at <ulink +url="http://www.linuxprinting.org">www.linuxprinting.org</ulink>, +which lets you generate a <quote>CUPS-O-Matic</quote>-&PPD; online for +any printer that had been supported by traditional &ghostscript; +printing already. This helps you to switch over to &CUPS; with little +effort, if you wish so. If your printer was doing well with the +traditional way of &ghostscript; printing, take CUPS-O-Matic to plug +your driver into th e &CUPS; system and you'll have the best of both +worlds.</para> +</listitem> + +<listitem> +<para>second, there are &CUPS;-&PPD;s for the more than 120 printer +models, which are driven by the new universal +<application>stp</application> driver. <application>stp</application> +(stood originally for Stylus Photo) is now developed by the gimp-print +project; it was started by Mike Sweet, the leading &CUPS; developer +and is now available through <ulink +url="http://gimp-print.sourceforge.net">gimp-print.sourceforge.net</ulink>. +This driver prints real Photo quality on many modern inkjets and can +be configured to make 120 &CUPS;-&PPD;s along its own +compilation. &HP; Laser- and DeskJet, <trademark +class="registered">Epson</trademark> Stylus and Photo Color models as +well as some <trademark class="registered">Canon</trademark> and +<trademark class="registered">Lexmark</trademark> are covered.</para> +</listitem> + +<listitem> +<para>third, there is the commercial extension to &CUPS; from the +&CUPS; developers themselves: it is called <application>ESP +PrintPro</application> and comes with more than 2.300 printer +drivers. There are even improved imagetoraster and pstoraster filters +included.</para> +</listitem> +</itemizedlist> + +<para>&CUPS; makes it really easy for manufacturers to start +supporting &Linux; and &UNIX; printing for their models at reasonably +low cost. The modular framework of &CUPS; facilitates to plug in any +filter (=driver) with minimal effort and to access and utilize the +whole printing framework that &CUPS; is creating.</para> + +<para>Read more about the exciting &CUPS; features in the available +&CUPS; documentation at <ulink +url="http://www.cups.org/documentation.html">http://www.cups.org/documentation.html</ulink> +and <ulink +url="http://wwww.danka.de/printpro/faq.html">http://www.danka.de/printpro/faq.html</ulink>. +Also at <ulink +url="http://www.linuxprinting.org">http://www.linuxprinting.org/</ulink> +is a universal repository for all issues related to &Linux; and &UNIX; +printing.</para> + +</sect2> + +</sect1> + +<sect1 id="cups-ipp-support"> +<title>How &IPP; Support Makes &CUPS; the Best Choice Around</title> + +<sect2> +<title><quote><acronym>LPD</acronym> Must Die!</quote></title> + +<para>For a long time many developers were deeply dissatisfied with good +old <acronym>LPD</acronym>. Quite a few new projects were started to +improve printing: <application>LPRng</application> is the best known +example. Others are <acronym>PDQ</acronym>, <acronym>PPR</acronym>, +<acronym>PLP</acronym>, <acronym>GNUlpr</acronym> and +<acronym>RLPR</acronym>. But none of the new programs were seen as a +<quote>big shot</quote>; most of them are just implementing the same old +<acronym>LPD</acronym> specification with a few (or many) new +extensions, which again make them incompatible with each other.</para> + +<para>Having seen the development of not just one, but different +viable alternatives to venerable <acronym>BSD</acronym>-style +<acronym>LPD</acronym>, Grant Taylor, author of the <citetitle>Linux +Printing HOWTO</citetitle>, finally rallied the call <citetitle>LPD +Must Die!</citetitle> in his <quote>Campaign To Abolish The Line +Printer Daemon</quote>.</para> + +<!-- FIXME: look up URLs for the above --> + +</sect2> + +<sect2> +<title>How the &IPP; Came to Be</title> + +<para>Along with the above, on the industry side of things, there were +efforts to overcome the well-known weaknesses of +<acronym>LPD</acronym>. It started with proprietary extensions to +plain old <acronym>LPD</acronym>, and stretched as far as +&Hewlett-Packard;'s attempt to establish &HP; JetDirect as a new +standard for a network printing protocol. The result were even more +incompatibilities.</para> + +<para>In the end, an initiative to define a new common industry and +<acronym>IETF</acronym> standard took shape. The <quote>Printer +Working Group</quote> or <acronym>PWG</acronym>, a loose aggregation +of vendors in hardware, software, and operating systems, drafted the +new <quote>Internet Printing Protocol</quote>, &IPP;. &IPP; v1.1 has +now been approved by the <acronym>IETF</acronym> (Internet Engineering +Task Force) as a proposed standard, and now enjoys the unanimous +support throughout the industry in Europe, USA and Japan. Most +current network printer models have now built in &IPP; support on top +of traditional <acronym>LPR</acronym>/<acronym>LPD</acronym> or +JetDirect Printing.</para> + +</sect2> + +<sect2> +<title>Why &IPP; is Solving Many Problems</title> + +<para>&IPP; promises to solve a lot of problems network administrators +face. This trade normally deals with heterogeneous network +environments and spends more than half of its working hours dealing +with printing problems.</para> + +<para>By creating a unified set of query functions for &IPP; enabled +printers and servers, for transferring files and setting job-control +attributes &etc;, &IPP; is destined to work across all &OS; platforms. +It's rollout however, will not happen overnight, as many legacy print +devices will still be in use for many years to come. Therefore, in +&IPP; there is a provision made for backwards compatibility of all +&IPP; implementations. &CUPS; is proving the viability of &IPP; +printing in all environments.</para> + +<para>The most striking advantage will be it's integration into the +existing set of other robust <acronym>IP</acronym> protocols. Being +an extension of the proven and robust <acronym>HTTP</acronym> 1.1 +protocol, for the special task of handling print file and related +data, it is also very easy to plug in other standards as they are +being developed and deployed:</para> + +<itemizedlist> +<listitem> +<para>Basic, Digest, and Certificate Authentication for users seeking +access to print services.</para> +</listitem> +<listitem> +<para>SSL3 and <acronym>TLS</acronym> encryption for transferring +data.</para> +</listitem> +<listitem> +<para>Bi directional communication of clients with print devices, using +the <acronym>HTTP</acronym>/&IPP; <command>GET</command> and +<command>POST</command> mechanism.</para> +</listitem> +<listitem> +<para>LDAP directory service integration to keep a consistent database +of available printers, their capabilities and page-costs, &etc;, as well +as user passwords, <acronym>ACL</acronym>s &etc;.</para> +</listitem> +<listitem> +<para><quote>Pull</quote> (as opposed to the usual <quote>Push</quote> +model) printing, where a server or printer just needs to be told the +&URL; of a document, whereupon it is retrieved from the resource on the +internet and printed.</para> +</listitem> +</itemizedlist> + +</sect2> + +<!-- +<sect2> +<title>&CUPS;, &IPP; and &kde;</title> + +<para>&CUPS; is the most advanced implementation of &IPP; on all &OS; +platforms. That makes &CUPS; a crucial ally to help "conquer the +desktop" for projects like &kde;. &kdeprint; is the best utility to +make &CUPS; core functionality available to &kde; Desktop +users.</para> + +</sect2> --> + +<sect2> +<title>Printer <quote>Plug'n'Play</quote> for Clients</title> + +<para>Have you ever seen a demonstration about &CUPS; capabilities in +the network? You must have been quite impressed if you didn't know in +advance what to expect.</para> + +<para>Imagine you as the administrator of a <quote>LAN</quote>. For +testing purposes you fully installed one &kde;/&CUPS; box on your net, +complete with a dozen printers configured and functional: +&PostScript;, LaserJets, InkJets and BubbleJets, and so on. Your +&kde; users on that box are very happy, they can print like never +before, <quote>ringing all the bells and whistles</quote> of every +printer. It took you 2 hours to make everything run perfectly... and +now all the other 100 users on the network want the same. Two hours +again for every box? No way you could do that before next year, you +think?</para> + +<para>Wrong. Just change one setting in the original &CUPS; box to +make it a <quote>server</quote>. Install &CUPS; on five other boxes, +as <quote>clients</quote>. By the time you turn back to your first +client, you find the users happily playing with the settings for the +dozen printers you had defined earlier on the <quote>server</quote>. +Somehow magically the printers had appeared on all the +<quote>Print</quote> dialogs of the five new &CUPS; client +boxes.</para> + +<para>Your users print, but not a single driver had been installed on +the clients, nor a printer queue defined.</para> + +<para>So, how does this magic work?</para> + +</sect2> + +<sect2> +<title><quote>Seeing</quote> Printers Not Installed Locally?</title> + +<para>The answer is not complicated at all.</para> + +<para>If a &CUPS; server is on the <acronym>LAN</acronym>, it +broadcasts the names of all available printers to the +<acronym>LAN</acronym>, using the <acronym>UDP</acronym> protocol and +port 631. Port 631 is reserved as a <quote>well-known port</quote> by +<acronym>IANA</acronym> (the <quote>Internet Assigning Numbers +Authority</quote>) for &IPP; purposes. All &CUPS; clients listen to +&CUPS; server info sent to their port 631. That's how they know about +available printers, and that's how they learn about the +<quote>path</quote> to the printers as well.</para> + +<para>Using &IPP;, which is really a clever extension to +<acronym>HTTP</acronym> v1.1, &CUPS; is able to address all objects +related to the printing system via <quote>Universal Resource +Locators</quote> or <acronym>URL</acronym>s. Print jobs to be deleted +or restarted, printers to be queried or modified, admin tasks to be +performed on the server, with &IPP; and &CUPS;, everything is +addressable by a certain <acronym>URL</acronym>. Many important +things can be done through the web interface to &CUPS;, accessible for +example with &konqueror;.</para> + +</sect2> + +<sect2> +<title>Printing Without Installing a Driver</title> + +<para>And more, the clients basically can <quote>administer</quote> +and <quote>use</quote> any printer they see, just as if it was a +locally installed one. Of course, you can set restrictions on it with +access control lists &etc;, so that not <emphasis>any</emphasis> +clients may use <emphasis>any</emphasis> printer as it likes.</para> + +<para>The clients even are able to print without the appropriate filter +(or driver) installed locally.</para> + +<para>So how does this work? If a client wants to know about and +select printer-specific options, it sends a request (called +<command>CUPS-get-ppd</command>) to the server. The server tells the +client all about all printer-specific options, as read from the server +side &PPD;. The user on the client side can see the options and +select the required ones. He then sends the print file, usually +unfiltered <quote>raw</quote> &PostScript;, spiced up with the +printer-options to the printer server, using &IPP; as the transport +protocol. All further processing, especially the filtering to +generate the final format for the target printer, is then done by the +server. The server has the necessary programs (<quote>drivers</quote> +or <quote>filters</quote>) to do this.</para> + +<para>This way a client prints without needing to install a driver +locally.</para> + +<para>Any change on the server, such as adding or modifying a printer, +is instantly <quote>known</quote> to the clients with no further +configuration.</para> + +</sect2> + +<sect2> +<title><quote>Zero Administration</quote>, Load Balancing, and +<quote>Failover Switching</quote></title> + +<para>Some other advanced features built into &CUPS; are the capacity to +do <quote>load balancing</quote>.</para> + +<para>If you define the same printer queues on two or more different +servers, the clients will send their jobs to the first responding or +available server. This implies an automatic load balancing amongst +servers. If you have to take one server off the network for +maintenance, the others will just take over its tasks without the users +even noticing the difference.</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kdesu/Makefile.am b/doc/kdesu/Makefile.am new file mode 100644 index 000000000..bafa3f6c3 --- /dev/null +++ b/doc/kdesu/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO + diff --git a/doc/kdesu/index.docbook b/doc/kdesu/index.docbook new file mode 100644 index 000000000..800d20b10 --- /dev/null +++ b/doc/kdesu/index.docbook @@ -0,0 +1,320 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kdesu;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> + +<title>The &kdesu; handbook</title> + +<authorgroup> +<author>&Geert.Jansen; &Geert.Jansen.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2000</year> +<holder>&Geert.Jansen;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-06-07</date> +<releaseinfo>1.00.00</releaseinfo> + + +<abstract><para>&kdesu; is a graphical front end for the &UNIX; +<command>su</command> command.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>su</keyword> +<keyword>password</keyword> +<keyword>root</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>Welcome to &kdesu;! &kdesu; is a graphical front end for the +&UNIX; <command>su</command> command for the K Desktop Environment. +It allows you to run a program as different user by supplying the +password for that user. &kdesu; is an unprivileged program; it uses +the system's <command>su</command>.</para> + +<para>&kdesu; has one additional feature: it can remember passwords +for you. If you are using this feature, you only need to enter the +password once for each command. See <xref +linkend="sec-password-keeping"/> for more information on this and a +security analysis.</para> + +<para>This program is meant to be started from the command line or +from <filename>.desktop</filename> files. Although it asks for the +<systemitem class="username">root</systemitem> password using a &GUI; +dialog, I consider it to be more of a command line <-> &GUI; +glue instead of a pure &GUI; program.</para> + +</chapter> + +<chapter id="using-kdesu"> +<title>Using &kdesu;</title> + +<para>Usage of &kdesu; is easy. The syntax is like this:</para> + +<cmdsynopsis> +<command>kdesu</command> + +<group choice="opt"><option>-c</option></group> +<group choice="opt"><option>-d</option></group> +<group choice="opt"><option>-f</option> <replaceable> file</replaceable></group> +<group choice="opt"><option>-i</option> <replaceable> icon name</replaceable></group> +<group choice="opt"><option>-n</option></group> +<group choice="opt"><option>-p</option> <replaceable> priority</replaceable></group> +<group choice="opt"><option>-r</option></group> +<group choice="opt"><option>-s</option></group> +<group choice="opt"><option>-t</option></group> +<group choice="opt"><option>-u</option> <replaceable> +user</replaceable></group> +<group choice="opt"><option>--nonewdcop</option></group> + +<group><arg choice="req"><replaceable>command</replaceable> <arg><replaceable>arg1</replaceable></arg> + <arg><replaceable>arg2</replaceable></arg> + <arg rep="repeat"><replaceable></replaceable></arg></arg></group> +</cmdsynopsis> +<cmdsynopsis> +<command>kdesu</command> +<arg choice="opt">&kde; Generic Options</arg> +<arg choice="opt">Qt Generic Options</arg> +</cmdsynopsis> + +<para>The command line options are explained below.</para> + +<variablelist> +<varlistentry> +<term><option>-c <replaceable>program</replaceable></option></term> +<listitem><para>This specifies the program to run as root. It has to be passed +in one argument. So if, for example, you want to start a new file manager, you +would enter at the prompt: <userinput><command>kdesu <option>-c <replaceable>kfm +-sw</replaceable></option></command></userinput></para></listitem> +</varlistentry> +<varlistentry> +<term><option>-d</option></term> +<listitem><para>Show debug information.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-f <replaceable>file</replaceable></option></term> +<listitem><para>This option allow efficient use of &kdesu; in +<filename>.desktop</filename> files. It tells &kdesu; to examine the +file specified by <parameter>file</parameter>. If this file is +writable by the current user, &kdesu; will execute the command as the +current user. If it is not writable, the command is executed as user +<parameter>user</parameter> (defaults to root).</para> +<para><parameter>file</parameter> is evaluated like this: if +<parameter>FILE</parameter> starts with a <literal>/</literal>, it is +taken as an absolute filename. Otherwise, it is taken as the name of a +global &kde; configuration file. For example: to configure the K display +manager, <application>kdm</application>, you could issue +<command>kdesu <option>-c kdmconfig -f +kdmrc</option></command></para></listitem> +</varlistentry> +<varlistentry> +<term><option>-i</option> <replaceable>icon name</replaceable></term> +<listitem><para>Specify icon to use in the password dialog. You may specify +just the name, without any extension.</para> +<para>For instance to run <command>kfmclient</command> and show the +&konqueror; icon in the password dialog:</para> +<screen><userinput><command>kdesu</command> <option>-i konqueror</option> <command>kfmclient</command></userinput></screen> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-n</option></term> +<listitem><para>Do not keep the password. This disables the <guilabel>keep +password</guilabel> checkbox in the password dialog.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-p</option> <replaceable>priority</replaceable></term> +<listitem> +<para>Set priority value. The priority is an arbitrary number between 0 and +100, where 100 means highest priority, and 0 means lowest. The default is +50.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>-r</option></term> +<listitem><para>Use realtime scheduling.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-s</option></term> +<listitem><para>Stop the kdesu daemon. See <xref +linkend="sec-password-keeping"/>.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-t</option></term> +<listitem><para>Enable terminal output. This disables password keeping. This is +largely for debugging purposes; if you want to run a console mode app, use the +standard <command>su</command> instead.</para> </listitem> +</varlistentry> +<varlistentry> +<term><option>-u</option> <replaceable> user</replaceable></term> +<listitem><para>While the most common use for &kdesu; is to run a command as +the superuser, you can supply any user name and the appropriate +password.</para> +</listitem> +</varlistentry> + +</variablelist> + +</chapter> + +<chapter id="Internals"> +<title>Internals</title> + +<sect1 id="x-authentication"> +<title>X authentication</title> + +<para>The program you execute will run under the root user id and will +generally have no authority to access your X display. &kdesu; gets +around this by adding an authentication cookie for your display to a +temporary <filename>.Xauthority</filename> file. After the command +exits, this file is removed. </para> + +<para>If you don't use X cookies, you are on your own. &kdesu; will +detect this and will not add a cookie but you will have to make sure +that root is allowed to access to your display.</para> + +</sect1> + +<sect1 id="interface-to-su"> +<title>Interface to <command>su</command></title> + +<para>&kdesu; uses the sytem's <command>su</command> for acquiring +priviliges. In this section, I explain the details of how &kdesu; does +this. </para> + +<para>Because some <command>su</command> implementations (&ie; the one +from &RedHat;) don't want to read the password from +<literal>stdin</literal>, &kdesu; creates a pty/tty pair and executes +<command>su</command> with it's standard filedescriptors connected to +the tty.</para> + +<para>To execute the command the user selected, rather than an +interactive shell, &kdesu; uses the <option>-c</option> argument with +<command>su</command>. This argument is understood by every shell that +I know of so it should work portably. <command>su</command> passes +this <option>-c</option> argument to the target user's shell, and the +shell executes the program. Example command: <command>su <option>root +-c <replaceable>the_program</replaceable></option></command>.</para> + +<para>Instead of executing the user command directly with +<command>su</command>, &kdesu; executes a little stub program called +<application>kdesu_stub</application>. This stub (running as the +target user), requests some information from &kdesu; over the pty/tty +channel (the stub's stdin and stdout) and then executes the user's +program. The information passed over is: the X display, an X +authentication cookie (if available), the <envar>PATH</envar> and the +command to run. The reason why a stub program is used is that the X +cookie is private information and therefore cannot be passed on the +command line.</para> + +</sect1> + +<sect1 id="password-checking"> +<title>Password Checking</title> + +<para>&kdesu; will check the password you entered and gives an error +message if it is not correct. The checking is done by executing a test +program: <filename>/bin/true</filename>. If this succeeds, the +password is assumed to be correct.</para> + +</sect1> + +<sect1 id="sec-password-keeping"> +<title>Password Keeping</title> + +<para>For your comfort, &kdesu; implements a <quote>keep +password</quote> feature. If you are interested in security, you +should read this paragraph.</para> + +<para>Allowing &kdesu; to remember passwords opens up a (small) +security hole in your system. Obviously, &kdesu; does not allow +anybody but your user id to use the passwords, but, if done without +caution, this would lowers <systemitem +class="username">root</systemitem>'s security level to that of a +normal user (you). A hacker who breaks into your account, would get +<systemitem class="username">root</systemitem> access. &kdesu; tries +to prevent this. The security scheme it uses is, in my opinion at +least, reasonably safe and is explained here.</para> + +<para>&kdesu; uses a daemon, called +<application>kdesud</application>. The daemon listens to a &UNIX; +socket in <filename>/tmp</filename> for commands. The mode of the +socket is 0600 so that only your user id can connect to it. If +password keeping is enabled, &kdesu; executes commands through this +daemon. It writes the command and <systemitem +class="username">root</systemitem>'s password to the socket and the +daemon executes the command using <command>su</command>, as describe +before. After this, the command and the password are not thrown +away. Instead, they are kept for a specified amount of time. This is +the timeout value from in the control module. If another request for +the same command is coming within this time period, the client does +not have to supply the password. To keep hackers who broke into your +account from stealing passwords from the daemon (for example, by +attaching a debugger), the daemon is installed set-group-id +nogroup. This should prevent all normal users (including you) from +getting passwords from the <application>kdesud</application> +process. Also, the daemon sets the <envar>DISPLAY</envar> environment +variable to the value it had when it was started. The only thing a +hacker can do is execute an application on your display.</para> + +<para>One weak spot in this scheme is that the programs you execute +are probably not written with security in mind (like setuid +<systemitem class="username">root</systemitem> programs). This means +that they might have buffer overruns or other problems and a hacker +could exploit those.</para> + +<para>The use of the password keeping feature is a tradeoff between +security and comfort. I encourage you to think it over and decide for +yourself if you want to use it or not.</para> + +</sect1> +</chapter> + +<chapter id="Author"> +<title>Author</title> + +<para>&kdesu;</para> + +<para>Copyright 2000 &Geert.Jansen;</para> + +<para>&kdesu; is written by &Geert.Jansen;. It is somewhat based on +Pietro Iglio's &kdesu;, version 0.3. Pietro and I agreed that I will +maintain this program in the future.</para> + +<para>The author can be reached through email at &Geert.Jansen.mail;. +Please report any bugs you find to me so that I can fix them. If you +have a suggestion, feel free to contact me.</para> + +&underFDL; +&underArtisticLicense; + +</chapter> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/kdesu/man-kdesu.1.docbook b/doc/kdesu/man-kdesu.1.docbook new file mode 100644 index 000000000..b9c5ac4ca --- /dev/null +++ b/doc/kdesu/man-kdesu.1.docbook @@ -0,0 +1,179 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<title>KDE User's Manual</title> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<date>Jun 7, 2005</date> +<productname>K Desktop Environment</productname> +</refentryinfo> + +<refmeta> +<refentrytitle><command>kdesu</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>kdesu</command></refname> +<refpurpose>Runs a program with elevated privileges</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>kdesu</command> + +<group choice="opt"><option>-c</option></group> +<group choice="opt"><option>-d</option></group> +<group choice="opt"><option>-f</option> <replaceable> file</replaceable></group> +<group choice="opt"><option>-i</option> <replaceable> icon name</replaceable></group> +<group choice="opt"><option>-n</option></group> +<group choice="opt"><option>-p</option> <replaceable> priority</replaceable></group> +<group choice="opt"><option>-r</option></group> +<group choice="opt"><option>-s</option></group> +<group choice="opt"><option>-t</option></group> +<group choice="opt"><option>-u</option> <replaceable> +user</replaceable></group> +<group choice="opt"><option>--nonewdcop</option></group> + +<group><arg choice="req"><replaceable>command</replaceable> <arg><replaceable>arg1</replaceable></arg> + <arg><replaceable>arg2</replaceable></arg> + <arg rep="repeat"><replaceable></replaceable></arg></arg></group> +</cmdsynopsis> +<cmdsynopsis> +<command>kdesu</command> +<arg choice="opt">KDE Generic Options</arg> +<arg choice="opt">Qt Generic Options</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para>&kdesu; is a graphical front end for the +&UNIX; <command>su</command> command for the K Desktop Environment. +It allows you to run a program as different user by supplying the +password for that user. &kdesu; is an unprivileged program; it uses +the system's <command>su</command>.</para> + +<para>&kdesu; has one additional feature: it can optionally remember passwords +for you. If you are using this feature, you only need to enter the +password once for each command.</para> + +<para>This program is meant to be started from the command line or +from <filename>.desktop</filename> files.</para> +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>-c <replaceable>program</replaceable></option></term> +<listitem><para>This specifies the program to run as root. It has to be passed +in one argument. So if, for example, you want to start a new file manager, you +would enter at the prompt: <userinput><command>kdesu <option>-c <replaceable>kfm +-sw</replaceable></option></command></userinput></para></listitem> +</varlistentry> +<varlistentry> +<term><option>-d</option></term> +<listitem><para>Show debug information.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-f <replaceable>file</replaceable></option></term> +<listitem><para>This option allow efficient use of &kdesu; in +<filename>.desktop</filename> files. It tells &kdesu; to examine the +file specified by <parameter>file</parameter>. If this file is +writable by the current user, &kdesu; will execute the command as the +current user. If it is not writable, the command is executed as user +<parameter>user</parameter> (defaults to root).</para> +<para><parameter>file</parameter> is evaluated like this: if +<parameter>file</parameter> starts with a <literal>/</literal>, it is +taken as an absolute filename. Otherwise, it is taken as the name of a +global &kde; configuration file. For example: to configure the K display +manager, <application>kdm</application>, you could issue +<command>kdesu <option>-c kdmconfig -f +kdmrc</option></command></para></listitem> +</varlistentry> +<varlistentry> +<term><option>-i</option> <replaceable>icon name</replaceable></term> +<listitem><para>Specify icon to use in the password dialog. You may specify +just the name, without any extension.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-n</option></term> +<listitem><para>Do not keep the password. This disables the <guilabel>keep +password</guilabel> checkbox in the password dialog.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-p</option> <replaceable>priority</replaceable></term> +<listitem> +<para>Set priority value. The priority is an arbitrary number between 0 and +100, where 100 means highest priority, and 0 means lowest. The default is +50.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>-r</option></term> +<listitem><para>Use realtime scheduling.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>-s</option></term> +<listitem><para>Stop the kdesu daemon. This is the daemon that caches +successful passwords in the background. This feature may also be disabled with +<option>-n</option> when &kdesu; is initially run.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>-t</option></term> +<listitem><para>Enable terminal output. This disables password keeping. This is +largely for debugging purposes; if you want to run a console mode app, use the +standard <command>su</command> instead.</para> </listitem> +</varlistentry> +<varlistentry> +<term><option>-u</option> <replaceable> user</replaceable></term> +<listitem><para>While the most common use for &kdesu; is to run a command as +the superuser, you can supply any user name and the appropriate +password.</para> +</listitem> +</varlistentry> + +</variablelist> + +</refsect1> + +<refsect1> +<title>See Also</title> +<para>su(1)</para> + +<para>More detailed user documentation is available from <ulink +url="help:/kdesu">help:/kdesu</ulink> +(either enter this <acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kdesu</parameter></userinput>).</para> + +</refsect1> + +<refsect1> +<title>Examples</title> +<para>Run <command>kfmclient</command> as user <systemitem +class="username">jim</systemitem>, and show the &konqueror; icon in the +password dialog:</para> +<screen><userinput><command>kdesu</command> <option>-u jim</option> <option>-i konqueror</option> <command>kfmclient</command></userinput></screen> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para>&kdesu; was written by +<personname><firstname>Geert</firstname><surname>Jansen</surname></personname> <email>[email protected]</email> +and <personname><firstname>Pietro</firstname><surname>Iglio</surname></personname> +<email>[email protected]</email>. +</para> +</refsect1> + +</refentry> diff --git a/doc/kdm/Makefile.am b/doc/kdm/Makefile.am new file mode 100644 index 000000000..c04fe0908 --- /dev/null +++ b/doc/kdm/Makefile.am @@ -0,0 +1,6 @@ +conf_def = $(top_srcdir)/kdm/config.def +ref: $(conf_def) $(top_srcdir)/kdm/confproc.pl + $(PERL) -w $(top_srcdir)/kdm/confproc.pl --doc $(conf_def) kdmrc-ref.docbook + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kdm/index.docbook b/doc/kdm/index.docbook new file mode 100644 index 000000000..1a127a506 --- /dev/null +++ b/doc/kdm/index.docbook @@ -0,0 +1,1472 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kdm;"> + <!ENTITY package "kdebase"> + <!ENTITY kdmrc "<filename>kdmrc</filename>"> + <!ENTITY ksmserver "<application>ksmserver</application>"> + <!ENTITY kdesktop "<application>kdesktop</application>"> + <!ENTITY XDMCP "<acronym>XDMCP</acronym>"> + <!ENTITY xdm "<application>xdm</application>"> + <!ENTITY kdmrc-ref SYSTEM "kdmrc-ref.docbook"> + <!ENTITY % addindex "INCLUDE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &kdm; Handbook</title> + +<authorgroup> +<author> +&Oswald.Buddenhagen; &Oswald.Buddenhagen.mail; +</author><!-- +<othercredit role="developer"> +&Oswald.Buddenhagen; &Oswald.Buddenhagen.mail; +<contrib>Developer</contrib> +</othercredit> +<othercredit role="reviewer"> +&Lauri.Watts; &Lauri.Watts.mail; +<contrib>Reviewer</contrib> +</othercredit> --> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year> +<holder>&Neal.Crook;</holder> +</copyright> + +<copyright> +<year>2002</year> +<holder>&Oswald.Buddenhagen;</holder> +</copyright> + +<copyright> +<year>2003</year> +<holder>&Lauri.Watts;</holder> +</copyright> + +<date>2003-03-01</date> +<releaseinfo>0.05.02</releaseinfo> + +<abstract> +<para>This document describes &kdm; the &kde; Display Manager. &kdm; +is also known as the <quote>Login Manager</quote>.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdm</keyword> +<keyword>xdm</keyword> +<keyword>display manager</keyword> +<keyword>login manager</keyword> +</keywordset> +</bookinfo> + +<!-- ********************************************************************** --> +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kdm; provides a graphical interface that allows you to log in to a +system. It prompts for login (username) and password, authenticates the user +and starts a <quote>session</quote>. &kdm; is superior to &xdm;, the X +Display Manager, in a number of ways.</para> + +</chapter> + +<!-- Chapters to write --> +<!-- * Just enough config to get it to run and login to KDE + * Adding more session types (GNOME, etc) + * Adding other customizations to XSession (ssh/gpg-agent, etc) + * Further customization to KDM (via the kcontrol module, and by + hand) + * XDMCP by query + * XDMCP by broadcast + * Sound transparency (if Ade can tell me how!) + * Document all Keys in the Config File + * Pull in all options from the KControl Module + * More resources +--> + +<chapter id="quickstart"> +<title>Quick Start Guide</title> + +<para>This is a quick start guide for users who fit the following +pattern:</para> + +<itemizedlist> +<listitem> +<para>X is configured and works with the command +<command>startx</command> from the commandline.</para> +</listitem> +<listitem> +<para>Each user will generally only use a single window manager or +desktop environment, and does not change this choice very +often, or is comfortable editing a single text file in order to change +their choice.</para> +</listitem> +</itemizedlist> + +<para>This scenario will be sufficient for many environments where a single +user or several users normally boot the computer and log into their +preferred environment.</para> + +<procedure> +<title>Setting up a Default Session</title> +<step> +<para>Create or open the file <filename>~/.xinitrc</filename></para> +<para>If you already have a working <filename>~/.xinitrc</filename>, go to +the next step</para> +</step> +<step> +<para>If one does not already exist, add a line to the +<filename>~/.xinitrc</filename> to start your preferred window manager +or desktop environment.</para> +<para>For &kde; you should enter:</para> +<screen><userinput>startkde</userinput></screen> +<para>For other window managers or desktop environments, you should +look in their documentation for the correct command.</para> +</step> +<step><para>Make a link as follows:</para> +<screen><userinput><command>ln</command> <option>-s</option> <parameter>~/.xinitrc ~/.xsession</parameter></userinput></screen> +</step> +</procedure> + +<para>At this point, typing <userinput><command>startx</command></userinput> +on the commandline should start X, with a &kde; session. The next task is +to try &kdm;.</para> + +<para>As <systemitem class="username">root</systemitem>, type +<userinput><command>kdm</command></userinput> at the prompt.</para> + +<para>You should see a login window, which is described more fully in <xref +linkend="login" />.</para> + +<para>Typing your normal username and password in the fields provided, and +leaving <option>default</option> selected as the session type should now +open a &kde; session for your user.</para> + +<para>If you have other users to configure, you should repeat the procedure +above for each of them.</para> + +<note> +<para>This is a quick guide to getting up and running only. You probably +will want to customize &kdm; further, for example, to hide the names of the +system accounts, to allow further sessions, and much more. Please read +through the rest of this manual to find out how to do these things.</para> +</note> + +</chapter> + +<chapter id="login"> +<title>The Login Window</title> + +<para> The user interface to &kdm; consists of two dialog boxes. The main +dialog box has these controls:</para> + +<itemizedlist> +<listitem> +<para>A <guilabel>Username:</guilabel> field for you to enter your +username.</para> +</listitem> + +<listitem> +<para>A <guilabel>Password:</guilabel> field for you to enter your +password.</para> +</listitem> + +<listitem> +<para>(Optionally) a graphical image of each user (for example, a digitized +photograph). Clicking on an image is equivalent to typing the associated +username into the <guilabel>Username:</guilabel> field. (This feature is an +imitation of the login box on &IRIX;).</para> +</listitem> + +<listitem> +<para>A <guilabel>Menu</guilabel> drop down box that allows &kdm; to be used +to start sessions with various different window managers or desktop +environments installed on the system.</para> +</listitem> + +<listitem> +<para>(Optionally) a region to the right of the +<guilabel>Username:</guilabel>, <guilabel>Password:</guilabel> and +<guilabel>Session Type:</guilabel> fields which can be used to display +either a static image or an analog clock.</para> +</listitem> + +<listitem> +<para>A <guibutton>Login</guibutton> button that validates the +username/password combination and attempts to start a session of the +selected type.</para> +</listitem> + +<listitem> +<para>A <guibutton>Clear</guibutton> button that clears the text from +the <guilabel>Login</guilabel> and <guilabel>Pass</guilabel> +fields.</para> +</listitem> + +<listitem> +<para>A <guibutton>Menu</guibutton> button that opens an action menu +with the following items:</para> + +<itemizedlist> +<listitem> +<para>(On local displays) A <guimenuitem>Restart X Server</guimenuitem> item +that terminates the currently running &X-Server;, starts a new one and +displays the login dialog again. You can use this if the display content +seems to be broken somehow.</para> +</listitem> + +<listitem> +<para>(On remote displays) A <guimenuitem>Close Connection</guimenuitem> +item that closes the connection to the &XDMCP; server you are currently +connected to. If you got to this server through a host chooser, this will +bring you back to the chooser, otherwise it will only reset the &X-Server; +and bring up the login dialog again.</para> +</listitem> + +<listitem> +<para>(Optionally on local displays) A <guimenuitem>Console +Mode</guimenuitem> item that terminates the currently running &X-Server; and +leaves you alone with a console login. &kdm; will resume the graphical login +if nobody is logged in at the console for some time.</para> +</listitem> +</itemizedlist> +</listitem> + +<listitem> +<para>(Optionally) A <guibutton>Shutdown</guibutton> button that displays +the <guilabel>Shutdown</guilabel> dialog box.</para> +</listitem> +</itemizedlist> + +<para>The <guilabel>Shutdown</guilabel> dialog box presents a set of +radio buttons that allow one of these options to be selected:</para> + +<variablelist> +<varlistentry> +<term>Shutdown</term> +<listitem> +<para>Shut the system down in a controlled manner, ready for +power-down.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Restart</term> +<listitem> +<para>Shut the system down and reboot. For systems that use +<application>Lilo</application>, an optional drop down box allows you to +select a particular operating-system kernel to be used for the +reboot.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Restart X Server</term> +<listitem> +<para>Stop and then restart the X-server. Typically, you might need to use +this option if you have changed your X11 configuration in some way.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Console Mode</term> +<listitem> +<para>Stop the &X-Server; and return the system to console mode. This is +achieved by bringing the system down to runlevel 3. Typically, the system +manager might need to use this option before upgrading or re-configuring X11 +software.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Pressing the <guibutton>OK</guibutton> button initiates the selected +action; pressing the <guibutton>Cancel</guibutton> button returns to the +main &kdm; dialog box. </para> + +</chapter> + +<!-- *********************************************************************** --> +<chapter id="configuring-kdm"> +<title>Configuring &kdm;</title> + +<para>This chapter assumes that &kdm; is already up and running on your +system, and that you simply want to change its behavior in some way.</para> + +<para>When &kdm; starts up, it reads its configuration from the folder +<filename class="directory">$KDEDIR/share/config/kdm/</filename> (this may +be <filename class="directory">/etc/kde3/kdm/</filename> or something else +on your system).</para> + +<para>The main configuration file is &kdmrc;; all other files are +referenced from there and could be stored under any name anywhere on +the system - but usually that would not make much sense for obvious +reasons (one particular exception is referencing configuration files +of an already installed &xdm; - however when a new &kdm; is installed, +it will import settings from those files if it finds an already installed +&xdm;).</para> + +<para>Since &kdm; must run before any user is logged in, it is not +associated with any particular user. Therefore, it is not possible to have +user-specific configuration files; all users share the common &kdmrc;. It +follows from this that the configuration of &kdm; can only be altered by +those users that have write access to +<filename>$<envar>KDEDIR</envar>/share/config/kdm/kdmrc</filename> (normally +restricted to system administrators logged in as <systemitem +class="username">root</systemitem>).</para> + +<para>You can view the &kdmrc; file currently in use on your system, and you +can configure &kdm; by editing this file. Alternatively, you can use the +graphical configuration tool provided by the &kcontrolcenter; (under +<menuchoice><guisubmenu>System Administration</guisubmenu><guimenuitem>Login +Manager</guimenuitem></menuchoice>), which is described in <ulink +url="help:/kcontrol/login-manager.html">the &kcontrolcenter; help files</ulink>. +</para> + +<para>The remainder of this chapter describes configuration of &kdm; +via the &kcontrolcenter; module, and the <link linkend="kdm-files">next +chapter</link> describes the options available in &kdmrc; itself. If +you only need to configure for local users, the &kcontrolcenter; module +should be sufficient for your needs. If you need to configure remote +logins, or have multiple &kdm; sessions running, you will need to read +on.</para> + +<sect1 id="kdm-kcontrol-module"> +<sect1info> +<authorgroup> +<author>&Thomas.Tanghus; &Thomas.Tanghus.mail;</author> +<author>&Steffen.Hansen; &Steffen.Hansen.mail;</author> +<author>&Mike.McBride; &Mike.McBride.mail;</author> +</authorgroup> +</sect1info> + +<title>The Login Manager &kcontrolcenter; Module</title> + +<para>Using this module, you can configure the &kde; graphical login +manager, &kdm;. You can change how the login screen looks, who has +access using the login manager and who can shutdown the +computer.</para> + +<note><para>All settings will be written to the configuration file +&kdmrc;, which in its original state has many comments to help you +configure &kdm;. Using this &kcontrolcenter; module will strip these +comments from the file. All available options in &kdmrc; are covered +in <xref linkend="kdm-files"/>.</para> + +<para>The options listed in this chapter are cross referenced with +their equivalents in &kdmrc;. All options available in the &kcontrol; +module are also available directly in &kdmrc; but the reverse is not +true.</para></note> + +<para>In order to organize all of these options, this module is +divided into several sections: <link +linkend="kdmconfig-appearance"><guilabel>Appearance</guilabel></link>, +<link linkend="kdmconfig-font"><guilabel>Font</guilabel></link>, <link +linkend="kdmconfig-background"><guilabel>Background</guilabel></link>, +<link +linkend="kdmconfig-shutdown"><guilabel>Shutdown</guilabel></link>, +<link linkend="kdmconfig-users"><guilabel>Users</guilabel></link> and +<link +linkend="kdmconfig-convenience"><guilabel>Convenience</guilabel></link>.</para> + +<para>You can switch between the sections using the tabs at the top of +the window.</para> + +<note><para>If you are not currently logged in as a superuser, you +will need to click the <guibutton>Administrator Mode...</guibutton> +Button. You will then be asked for a superuser password. Entering a +correct password will allow you to modify the settings of this +module.</para></note> + +<sect2 id="kdmconfig-appearance"> +<title>Appearance</title> + +<para>From this page you can change the visual appearance of &kdm;, +&kde;'s graphical login manager.</para> + +<para>The <guilabel>Greeting:</guilabel> is the title of the login + screen. Setting this is especially useful if you have many servers users + may log in to. You may use various placeholders, which are described + along with the corresponding key + <link linkend="option-greetstring"><option>GreetString</option></link> + in &kdmrc;. +</para> + +<para>You can then choose to show either the current system time, a logo or +nothing special in the login box. Make your choice in the radio buttons +labeled <guilabel>Logo area:</guilabel>. This corresponds to <link +linkend="option-logoarea"><option>LogoArea</option></link> in &kdmrc;</para> + +<para>If you chose <guilabel>Show logo</guilabel> you can now choose a +logo:</para> + +<itemizedlist> +<listitem> +<para>Drop an image file on the image button.</para> +</listitem> +<listitem> +<para>Click on the image button and select a new image from the image chooser +dialog.</para> +</listitem> +</itemizedlist> + +<para>If you do not specify a logo the default +<filename>$<envar>KDEDIR</envar>/share/apps/kdm/pics/kdelogo.xpm</filename> +will be displayed.</para> + +<para>Normally the login box is centered on the screen. Use the +<guilabel>Position:</guilabel> options if you want it to appear +elsewhere on the screen. You can specify the relative position +(percentage of the screen size) for the center of the login window, +relative to the top left of the display, in the fields labeled +<guilabel>X:</guilabel> and <guilabel>Y:</guilabel> respectively. +These correspond to the key +<link linkend="option-greeterpos"><option>GreeterPos</option></link> +in &kdmrc;.</para> + +<para>While &kde;'s style depends on the settings of the user logged +in, the style used by &kdm; can be configured using the <guilabel>GUI +Style:</guilabel> and <guilabel>Color Scheme:</guilabel> options. +These correspond to the keys <link +linkend="option-guistyle"><option>GUIStyle</option></link> and <link +linkend="option-colorscheme"><option>ColorScheme</option></link> in +&kdmrc; respectively.</para> + +<para>Below that, you have a drop down box to choose the language for +your login box, corresponding to setting <option>Language</option> in +&kdmrc;.</para> + +</sect2> + +<sect2 id="kdmconfig-font"> +<title>Font</title> + +<para>From this section of the module you can change the fonts used in the +login window. Only fonts available to all users are available here, not +fonts you have installed on a per user basis.</para> + +<para>You can select three different font styles from the drop down box +(<guilabel>General:</guilabel>, <guilabel>Failures:</guilabel>, +<guilabel>Greeting:</guilabel>). When you click on the +<guibutton>Choose...</guibutton> button a dialog appears from which you can +select the new characteristics for the font style.</para> + +<itemizedlist> +<listitem> +<para>The <guilabel>General:</guilabel> font is used in all other places in the +login window.</para> +</listitem> +<listitem> +<para>The <guilabel>Failures:</guilabel> font is used when a login +fails.</para> +</listitem> +<listitem> +<para>The <guilabel>Greeting:</guilabel> font is the font used for the title +(Greeting String).</para> +</listitem> +</itemizedlist> + +<para>You can also check the box labeled <guilabel>Use anti-aliasing for +fonts</guilabel> if you want smoothed fonts in the login dialog.</para> + +</sect2> + +<sect2 id="kdmconfig-background"> +<title>Background</title> + +<para>Here you can change the desktop background which will be displayed +before a user logs in. You can have a single color or an image as a +background. If you have an image as the background and select center, the +selected background color will be used around the image if it is not +large enough to cover the entire desktop.</para> + +<para>The background colors and effects are controlled by the options on +the tab labeled <guilabel>Background</guilabel> and you select a +background image and its placement from the options on the tab labeled +<guilabel>Wallpaper</guilabel>.</para> + +<para>To change the default background color(s) simply click either of +the color buttons and select a new color.</para> + +<para>The drop down box above the color buttons provides you with several +different blend effects. Choose one from the list, and it will be +previewed on the small monitor at the top of the window. Your choices +are:</para> + +<variablelist> +<varlistentry> +<term>Flat</term> +<listitem><para>By choosing this mode, you select one color (using the color +button labeled <guibutton>Color 1</guibutton>), and the entire background is +covered with this one color.</para></listitem> +</varlistentry> +<varlistentry> +<term>Pattern</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). </para> <para>You then select a pattern by clicking +<guilabel>Setup</guilabel>. This opens a new dialog window, which gives you +the opportunity to select a pattern. Simply click once on the pattern of your +choice, then click on <guilabel>OK</guilabel>, and &kde; will render the pattern +you selected using the two colors you selected. For more on patterns, see the +section <ulink url="help:/kcontrol/background/index.html#bkgnd-patterns">Background: Adding, Removing and Modifying +Patterns</ulink>.</para></listitem> +</varlistentry> +<varlistentry> +<term>Background Program</term> +<listitem><para>By selecting this option, you can have &kde; use an external +program to determine the background. This can be any program of your choosing. +For more information on this option, see the section entitled <ulink +url="help:/kcontrol/background/index.html#bkgnd-programs">Background: Using an external program</ulink>.</para></listitem> +</varlistentry> +<varlistentry> +<term>Horizontal Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> on the left edge of the screen, and slowly transform into the +color selected by <guilabel>Color 2</guilabel> by the time it gets to the +right edge of the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term>Vertical Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> on the top edge of the screen, and slowly transform into the color +selected by <guilabel>Color 2</guilabel> as it moves to the bottom of the +screen.</para></listitem> +</varlistentry> +<varlistentry> +<term>Pyramid Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> in each corner of the screen, and slowly transform into the color +selected by <guilabel>Color 2</guilabel> as it moves to the center of the +screen.</para></listitem> +</varlistentry> +<varlistentry> +<term>Pipecross Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +1</guilabel> in each corner of the screen, and slowly transform into the color +selected by <guilabel>Color 2</guilabel> as it moves to the center of the +screen. The <quote>shape</quote> of this gradient is different then the pyramid +gradient.</para></listitem> +</varlistentry> +<varlistentry> +<term>Elliptic Gradient</term> +<listitem><para>By choosing this mode, you select two colors (using both color +buttons). &kde; will then start with the color selected by <guilabel>Color +2</guilabel> in the center of the screen, and slowly transform into the color +selected by <guilabel>Color 1</guilabel> as it moves to the edges, in an +elliptical pattern.</para></listitem> +</varlistentry> +</variablelist> + +<para>The setup button is only needed for if you select <guilabel>Background +program</guilabel> or <guilabel>Patterns</guilabel>. In these instances, +another window will appear to configure the specifics.</para> +<para><emphasis>Wallpaper</emphasis></para> +<para>To select a new background image first, click on the +<guilabel>Wallpapers</guilabel> tab, then you can either select an image from the drop down list labeled <guilabel>Wallpaper</guilabel> or select +<guibutton>Browse...</guibutton> and select an image file from a file +selector.</para> + +<para>The image can be displayed in six different ways:</para> +<variablelist> +<varlistentry> +<term>No wallpaper</term> +<listitem><para>No image is displayed. Just the background colors.</para> +</listitem></varlistentry> +<varlistentry> +<term>Centered</term> +<listitem><para>The image will be centered on the screen. The background colors +will be present anywhere the image does not cover.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Tiled</term> +<listitem><para>The image will be duplicated until it fills the entire +desktop. The first image will be placed in the upper left corner of the screen, +and duplicated downward and to the right.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Center Tiled</term> +<listitem><para>The image will be duplicated until it fills the entire +desktop. The first image will be placed in the center of the screen, and +duplicated upward, downward to the right, and to the left.</para> </listitem> +</varlistentry> +<varlistentry> +<term>Centered Maxpect</term> +<listitem><para>The image will be placed in the center of the screen. It will +be scaled to fit the desktop, but it will not change the aspect ratio of the +original image. This will provide you with an image that is not distorted. +</para> </listitem> +</varlistentry> +<varlistentry> +<term>Scaled</term> +<listitem><para>The image will be scaled to fit the desktop. It will be +stretched to fit all four corners.</para> </listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="kdmconfig-shutdown"> +<title><guilabel>Shutdown</guilabel></title> + +<para><guilabel>Allow Shutdown</guilabel></para> +<para>Use this drop down box to choose who is allowed to shut down:</para> +<itemizedlist> +<listitem> +<para><guilabel>Nobody</guilabel>: No one can shutdown the computer using +&kdm;. You must be logged in, and execute a command.</para> +</listitem> +<listitem> +<para><guilabel>Everybody</guilabel>: Everyone can shutdown the computer using +&kdm;.</para> +</listitem> +<listitem><para><guilabel>Only Root</guilabel>: &kdm; requires that the +<systemitem>root</systemitem> password be entered before shutting down the +computer.</para></listitem> +</itemizedlist> + +<para>You can independently configure who is allowed to issue a +shutdown command for the <guilabel>Local:</guilabel> and +<guilabel>Remote:</guilabel> users.</para> + +<para><emphasis>Commands</emphasis></para> <para>Use these text fields to +define the exact shutdown command.</para> <para>The +<guilabel>Halt:</guilabel> command defaults to <!-- Are these defaults still +correct? they disagree with what's in --> <!-- kdmrc --> +<command>/sbin/halt</command>. The <guilabel>Restart:</guilabel> command +defaults to +<command>/sbin/reboot</command>.</para> + +<para>When <guilabel>Show boot options</guilabel> is enabled, &kdm; +will on reboot offer you options for the lilo boot manager. For this +feature to work, you will need to supply the correct paths to your +<command>lilo</command> command and to lilo's map file. Note that this +option is not available on all operating systems.</para> + +</sect2> + +<sect2 id="kdmconfig-users"> +<title>Users</title> + +<para>From here you can change the way users are represented in the +login window.</para> + +<para>You may disable the user list in &kdm; entirely in the +<guilabel>Show Users</guilabel> section. You can choose from:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Show List</guilabel></term> +<listitem> +<para>Only show users you have specifically enabled in the list +alongside</para> +<para>If you do not check this box, no list will be shown. This is the most secure setting, since an +attacker would then have to guess a valid login name as well as a +password. It's also the preferred option if you have more than a +handful of users to list, or the list itself would become +unwieldy.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Inverse selection</guilabel></term> +<listitem> +<para>Allows you to intead select a list of users that should +<emphasis>not</emphasis> be shown, and all other users will be +listed.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Independently of the users you specify by name, you can use the +<guilabel>System UIDs</guilabel> to specify a range of valid +<acronym>UID</acronym>s that are shown in the list. By default user +id's under 1000, which are often system or daemon users, and user id's +over 65000, are not shown.</para> + +<para>You can also enable the <guilabel>Sort users</guilabel> +checkbox, to have the user list sorted alphabetically. If this is +disabled, users will appear in the order they are listed in the +password file. &kdm; will also autocomplete user names if you enable the +<guilabel>Autocompletion</guilabel> option.</para> + +<para>If you choose to show users, then the login window will show +images (which you select), of a list of users. When someone is ready +to login, they may select their user name/image, enter their password, +and they are granted access.</para> + +<para>If you permit a user image, then you can configure the source +for those images.</para> + +<para>You can configure the admin picture here, for each user on the +system. Depending on the order selected above, users may be able to +override your selection.</para> + +<para>If you choose not to show users, then the login window will be +more traditional. Users will need to type their username and password +to gain entrance. This is the preferred way if you have many users on +this terminal.</para> + +</sect2> + +<sect2 id="kdmconfig-convenience"> +<title>Convenience</title> + +<para>In the <guilabel>convenience</guilabel> tab you can configure +some options that make life easier for lazy people, like automatic +login or disabling passwords.</para> + +<important><para>Please think more than twice before using these +options. Every option in the <guilabel>Convenience</guilabel> tab is +well-suited to seriously compromise your system security. Practically, +these options are only to be used in a completely non-critical +environment, ⪚ a private computer at home. </para></important> + +<sect3 id="loginmanager-convenience-autologin"> +<title>Automatic Login</title> + +<para>Automatic login will give anyone access to a certain account on +your system without doing any authentication. You can enable it using +the option <guilabel>Enable Auto-login</guilabel>.</para> + +<para>You can choose the account to be used for automatic login from +the list labeled <guilabel>User:</guilabel>.</para> + +</sect3> + +<sect3 id="loginmanager-convenience-nopasswd"> +<title><guilabel>Password-Less Login</guilabel></title> + +<para>Using this feature, you can allow certain users to login without +having to provide their password. Enable this feature using the +<guilabel>Enable Password-less logins</guilabel> option.</para> + +<para>Below this option you'll see a list of users on the system. +Enable password-less login for specific users by checking the checkbox +next to the login names. By default, this feature is disabled for +all users.</para> + +<important><para>Again, this option should only be used in a safe +environment. If you enable it on a rather public system you should +take care that only users with heavy access restrictions are granted +password-less login, ⪚ +<systemitem>guest</systemitem>.</para></important> + +<para>You can also choose which user is <quote>preselected</quote> +when &kdm; starts. The default is <guilabel>None</guilabel>, but you +can choose <guilabel>Previous</guilabel> to have &kdm; default to the +last successfully logged in user, or you can +<guilabel>Specify</guilabel> a particular user to always be selected +from the list. You can also have &kdm; set the focus to the password +field, so that when you reach the &kdm; login screen, you can type the +password immediately.</para> + +<para>The <guilabel>Automatically login after X server crash</guilabel> +option allows you to skip the authentication procedure when your X +server accidentally crashed.</para> + +</sect3> + +</sect2> + +</sect1> + +</chapter> + +&kdmrc-ref; + +<!-- ************************************************************ --> +<chapter id="configuring-your-system-for-kdm"> +<title>Configuring your system to use &kdm;</title> + +<para>This chapter assumes that your system is already configured to +run the &X-Window;, and that you only need to reconfigure it to +allow graphical login.</para> + +<sect1 id="setting-up-kdm"> +<title>Setting up &kdm;</title> + +<para>The fundamental thing that controls whether your computer boots to a +terminal prompt (console mode) or a graphical login prompt is the default +runlevel. The runlevel is set by the program <application> <ulink +url="man:init">/sbin/init</ulink></application> under the control of the +configuration file <filename>/etc/inittab</filename>. The default runlevels +used by different &UNIX; systems (and different &Linux; distributions) vary, +but if you look at <filename>/etc/inittab</filename> the start of it should +be something like this:</para> + +<screen># Default runlevel. The runlevels used by RHS are: +# 0 - halt (Do NOT set initdefault to this) +# 1 - Single user mode +# 2 - Multiuser, without NFS +# 3 - Full multiuser mode +# 4 - unused +# 5 - X11 +# 6 - reboot (Do NOT set initdefault to this) + +id:3:initdefault: +</screen> + +<para>All but the last line of this extract are comments. The comments +show that runlevel 5 is used for X11 and that runlevel 3 is used for +multi-user mode without X11 (console mode). The final line specifies +that the default runlevel of the system is 3 (console mode). If your +system currently uses graphical login (for example, using &xdm;) its +default runlevel will match the runlevel specified for X11.</para> + +<para>The runlevel with graphical login (&xdm;) for some common &Linux; +distributions is:</para> + +<itemizedlist> +<listitem><para>5 for &RedHat; 3.x and later, and for &Mandrake;</para></listitem> +<listitem><para>4 for Slackware</para></listitem> +<listitem><para>3 for &SuSE;. 4.x and 5.x</para></listitem> +</itemizedlist> + +<para>The first step in configuring your system is to ensure that you +can start &kdm; from the command line. Once this is working, you can +change your system configuration so that &kdm; starts automatically +each time you reboot your system.</para> + +<para>To test &kdm;, you must first bring your system to a runlevel +that does not run &xdm;. To do so, issue a command like this:</para> + +<screen><command>/sbin/init <option>3</option></command></screen> + +<para>Instead of the number <option>3</option> you should specify the +appropriate runlevel for console mode on your system.</para> + +<para>If your system uses Pluggable Authentication Modules +(<abbrev>PAM</abbrev>), which is normal with recent &Linux; and &Solaris; +systems, you should check that your <abbrev>PAM</abbrev> configuration permits +login through the service named <literal>kde</literal>. If you previously used +&xdm; successfully, you should not need to make any +changes to your <abbrev>PAM</abbrev> configuration in order to use +&kdm;. <filename>/etc/pam.conf</filename> or +<filename>/etc/pam.d/kde</filename>. Information on configuring +<abbrev>PAM</abbrev> is beyond the scope of this handbook, but +<abbrev>PAM</abbrev> comes with comprehensive documentation (try looking in +<filename>/usr/share/doc/*pam*/html/</filename>).</para> + +<para>Now it's time for you to test &kdm; by issuing the following +command:</para> + +<screen><command>kdm <option>-nodaemon</option></command> +</screen> + +<para>If you get a &kdm; login dialog and you are able to log in, +things are going well. The main thing that can go wrong here is that +the run-time linker might not find the shared &Qt; or &kde; libraries. +If you have a binary distribution of the &kde; libraries, make sure +&kdm; is installed where the libraries believe &kde; is installed and +try setting some environment variables to point to your &kde; and &Qt; +libraries.</para> + +<para>For example:</para> + +<screen><command>export +<option>KDEDIR=<replaceable>/opt/kde</replaceable></option></command> +<command>export +<option>QTDIR=<replaceable>/usr/lib/qt2</replaceable></option></command> +<command>export +<option>PATH=<replaceable>$KDEDIR/bin:$QTDIR/bin:$PATH</replaceable></option></command> +<command>export +<option>LD_LIBRARY_PATH=<replaceable>$KDEDIR/lib:$QTDIR/lib</replaceable></option></command> +</screen> + +<para>If you are still unsuccessful, try starting &xdm; instead, to +make sure that you are not suffering from a more serious X +configuration problem.</para> + +<para>When you are able to start &kdm; successfully, you can start to +replace &xdm; by &kdm;. Again, this is distribution-dependent.</para> + +<itemizedlist> +<listitem> +<para>For &RedHat;, edit <filename>/etc/inittab</filename>, look for this + line:</para> +<screen>x:5:respawn:/usr/X11/bin/xdm -nodaemon</screen> +<para>and replace with:</para> +<screen>x:5:respawn:/opt/kde/bin/kdm</screen> +<para>This tells <command>init</command>(8) to respawn &kdm; when the +system is in run level 5. Note that &kdm; does not need the + <option>-nodaemon</option> option.</para> +</listitem> +<listitem> +<para>For &Mandrake;, the X11 runlevel in +<filename>/etc/inittab</filename> invokes the shell script +<filename>/etc/X11/prefdm</filename>, which is set up to select from +amongst several display managers, including &kdm;. Make sure that all +the paths are correct for your installation.</para> +</listitem> +<listitem> +<para>For &SuSE;, edit <filename>/sbin/init.d/xdm</filename> to add a +first line:</para> + +<screen>. /etc/rc.config +DISPLAYMANAGER=kdm +export DISPLAYMANAGER</screen> +</listitem> +<listitem><para>For FreeBSD, edit <filename>/etc/ttys</filename> and find +the line like this:</para> +<screen>ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</screen> +<para>and edit it to this:</para> +<screen>ttyv8 "/usr/local/bin/kdm" xterm on secure</screen> +</listitem> + +<listitem><para>Most other distributions are a variation of one of +these.</para></listitem> +</itemizedlist> + +<para>At this stage, you can test &kdm; again by bringing your system +to the runlevel that should now run &kdm;. To do so, issue a command +like this:</para> + +<screen><command>/sbin/init <option>5</option></command> +</screen> + +<para>Instead of the number <option>5</option> you should specify the +appropriate runlevel for running X11 on your system.</para> + +<para>The final step is to edit the <parameter>initdefault</parameter> +entry in <filename>/etc/inittab</filename> to specify the appropriate +runlevel for X11.</para> + +<warning><para>Before you make this change, ensure that you have a way +to reboot your system if a problem occurs. This might be a +<quote>rescue</quote> floppy-disk provided by your operating system +distribution or a specially-designed <quote>rescue</quote> +floppy-disk, such as <literal>tomsrtbt</literal>. Ignore this advice +at your peril.</para></warning> + +<para>This usually involves changing the line:</para> +<screen>id:3:initdefault:</screen> +<para>to</para> +<screen>id:5:initdefault:</screen> + +<para>When you reboot your system, you should end up with the +graphical &kdm; login dialog.</para> + +<para>If this step is unsuccessful the most likely problem is that the +environment used at boot time differs from the environment that you used for +testing at the command line. If you are trying to get two versions of &kde; +to co-exist, be particularly careful that the settings you use for your +<envar>PATH</envar> and <envar>LD_LIBRARY_PATH</envar> environment variables +are consistent, and that the startup scripts are not over-riding them in +some way.</para> + +</sect1> + +</chapter> + +<chapter id="different-window-managers-with-kdm"> +<title>Supporting multiple window managers</title> + +<para>&kdm; detects most available window manager and desktop environments when +it is run. Installing a new one should make it automatically available in +the &kdm; main dialog <guilabel>Session Type:</guilabel>.</para> + +<para>If you have a very new window manager, or something that &kdm; does +not support, the first thing you should check is that the application to be +run is in the <envar>PATH</envar> and has not been renamed during the +install into something unexpected.</para> + +<para>If the case is that the application is too new and not yet supported +by &kdm;, you can quite simply add a new session.</para> + +<para>The sessions are defined in <firstterm>.desktop</firstterm> files in +<filename +class="directory">$<envar>KDEDIR</envar>/share/apps/kdm/sessions</filename>. +You can simply add an appropriately named <literal +role="extension">.desktop</literal> file in this directory. The fields +are:</para> + +<programlisting>[Desktop Entry] +Encoding=UTF-8 <lineannotation>This is fixed to <option>UTF-8</option> and +may be omitted</lineannotation> +Type=XSession <lineannotation>This is fixed to <option>XSession</option> and +may be omitted</lineannotation> +Exec=<replaceable>executable name</replaceable> <lineannotation>Passed to +<command>eval exec</command> in a Bourne shell</lineannotation> +TryExec=<replaceable>executable name</replaceable> <lineannotation>Supported +but not required</lineannotation> +Name=<replaceable>name to show in the &kdm; session list</replaceable></programlisting> + +<para>There are also three <quote>magic</quote>:</para> + +<variablelist> +<varlistentry> +<term>default</term> +<listitem> +<para> +The default session for &kdm; is normally &kde; but can be configured by the +system administrator. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>custom</term> +<listitem> +<para> +The Custom session will run the users ~/.xsession if it exists. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>failsafe</term> +<listitem> +<para> +Failsafe will run a very plain session, and is useful only for debugging +purposes. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para>To override a session type, copy the .desktop file from the data dir +to the config dir and edit it at will. Removing the shipped session types +can be accomplished by <quote>shadowing</quote> them with .desktop files +containing Hidden=true. For the magic session types no .desktop files exist +by default, but &kdm; pretends they would, so you can override them like any +other type. I guess you already know how to add a new session type by +now. ;-)</para> + +</chapter> + +<chapter id="xdmcp-with-kdm"> +<title>Using &kdm; for Remote Logins (&XDMCP;)</title> + +<para>&XDMCP; is the Open Group standard, the <quote>X Display Manager +Control Protocol</quote>. This is used to set up connections between +remote systems over the network.</para> + +<para>&XDMCP; is useful in multiuser situations where there are users +with workstations and a more powerful server that can provide the +resources to run multiple X sessions. For example, &XDMCP; is a good +way to reuse old computers - a Pentium or even 486 computer with 16 Mb +RAM is sufficient to run X itself, and using &XDMCP; such a computer can +run a full modern &kde; session from a server. For the server part, +once a single &kde; (or other environment) session is running, running +another one requires very few extra resources.</para> + +<para>However, allowing another method of login to your machine +obviously has security implications. You should run this service only +if you need to allow remote X Servers to start login sessions on your +system. Users with a single &UNIX; computer should not need to run +this.</para> + +</chapter> + +<chapter id="advanced-topics"> +<title>Advanced Topics</title> + +<sect1 id="command-sockets"> +<title>Command Sockets</title> + +<para>This is a feature you can use to remote-control &kdm;. It's mostly +intended for use by &ksmserver; and &kdesktop; from a running session, but +other applications are possible as well.</para> + +<para>The sockets are &UNIX; domain sockets which live in subdirectories of the +directory specified by <option>FifoDir</option>=. The subdir is the key to +addressing and security; the sockets all have the file name +<filename>socket</filename> and file permissions +<literal>rw-rw-rw-</literal> (0666). This is because some systems don't care +for the file permission of the socket files.</para> + +<para>There are two types of sockets: the global one (dmctl) and the +per-display ones (dmctl-<display>).</para> + +<para>The global one's subdir is owned by root, the subdirs of the per-display +ones' are owned by the user currently owning the session (root or the +logged in user). Group ownership of the subdirs can be set via FifoGroup=, +otherwise it is root. The file permissions of the subdirs are rwxr-x--- +(0750).</para> + +<para>The fields of a command are separated by tabs (<token>\t</token>), the +fields of a list are separated by spaces, literal spaces in list fields are +denoted by <token>\s</token>.</para> + +<para>The command is terminated by a newline (<token>\n</token>).</para> + +<para>The same applies to replies. The reply on success is +<returnvalue>ok</returnvalue>, possibly followed by the requested +information. The reply on error is an errno-style word (⪚ +<returnvalue>perm</returnvalue>, <returnvalue>noent</returnvalue>, &etc;) +followed by a longer explanation.</para> + +<variablelist> +<title>Global commands:</title> +<varlistentry> +<term><command>login</command> <option>display</option> +(<parameter>now</parameter> | <parameter>schedule</parameter>) <parameter>user</parameter> <parameter>password</parameter> +[session_arguments]</term> +<listitem> +<para>login user at specified display. if <parameter>now</parameter> is +specified, a possibly running session is killed, otherwise the login is done +after the session exits. session_arguments are printf-like escaped contents +for .dmrc. Unlisted keys will default to previously saved values.</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>Per-display commands:</title> +<varlistentry> +<term><command>lock</command></term> +<listitem> +<para>The display is marked as locked. If the &X-Server; crashes in this +state, no auto-relogin will be performed even if the option is on.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><command>unlock</command></term> +<listitem> +<para>Reverse the effect of <command>lock</command>, and re-enable +auto-relogin.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><command>suicide</command></term> +<listitem> +<para>The currently running session is forcibly terminated. No auto-relogin +is attempted, but a scheduled "login" command will be executed.</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<title>Commands for all sockets</title> +<varlistentry> +<term><command>caps</command></term> +<listitem> +<para>Returns a list of this socket's capabilities:</para> + +<variablelist> +<varlistentry> +<term><returnvalue>&kdm;</returnvalue></term> +<listitem> +<para>identifies &kdm;, in case some other DM implements this protocol, +too</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>list</returnvalue>, <returnvalue>lock</returnvalue>, +<returnvalue>suicide</returnvalue>, <returnvalue>login</returnvalue></term> +<listitem> +<para>The respective command is supported</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>bootoptions</returnvalue></term> +<listitem> +<para>The <command>listbootoptions</command> command and the +<option>=</option> to <command>shutdown</command> are supported</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>shutdown <list></returnvalue></term> +<listitem> +<para><command>shutdown</command> is supported and allowed for the listed +users (a comma separated list.) <returnvalue>*</returnvalue> means all +authenticated users.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>nuke <list></returnvalue></term> +<listitem> +<para>Forced shutdown may be performed by the listed users.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>nuke</returnvalue></term> +<listitem> +<para>Forced shutdown may be performed by everybody</para> +</listitem> +</varlistentry> +<varlistentry> +<term><returnvalue>reserve <number></returnvalue></term> +<listitem> +<para>Reserve displays are configured, and <returnvalue>number</returnvalue> +are available at this time</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>list</command> [<parameter>all</parameter> | +<parameter>alllocal</parameter>]</term> +<listitem> +<para>Return a list of running sessions. By default all active sessions are +listed. if <parameter>all</parameter> is specified, passive sessions are +listed as well. If <parameter>alllocal</parameter> is specified, passive +sessions are listed as well, but all incoming remote sessions are +skipped.</para> +<para>Each session entry is a comma separated tuple of:</para> +<itemizedlist> +<listitem><para>Display or TTY name</para></listitem> +<listitem><para>VT name for local sessions</para></listitem> +<listitem><para>Logged in user's name, empty for passive sessions and +outgoing remote sessions (local chooser mode)</para></listitem> +<listitem><para>Session type or <quote><remote></quote> for outgoing +remote sessions, empty for passive sessions.</para></listitem> +<listitem><para>A Flag field:</para> +<itemizedlist><listitem><para><literal>*</literal> for the display belonging +to the requesting socket.</para></listitem> +<listitem><para><literal>!</literal> for sessions that cannot be killed by the +reqeusting socket.</para></listitem> +</itemizedlist> +</listitem> +</itemizedlist> +<para>New fields may be added in the future.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>reserve</command> [<parameter>timeout in +seconds</parameter>]</term> +<listitem> +<para>Start a reserve login screen. If nobody logs in within the specified +amount of time (one minute by default), the display is removed again. When +the session on the display exits, the display is removed, too.</para> +<para>Permitted only on sockets of local displays and the global +socket.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>activate</command> +(<parameter>vt</parameter>|<parameter>display</parameter>)</term> +<listitem> +<para>Switch to a particular VT (virtual terminal). The VT may be specified +either directly (⪚ <parameter>vt3</parameter>) or by a display using it +(eg; <parameter>:2</parameter>).</para> +<para>Permitted only on sockets of local displays and the global +socket.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>listbootoptions</command></term> +<listitem> +<para>List available boot options.</para> +<!--FIXME: "ok" list default current + default and current are indices into the list and are -1 if unset or + undeterminable. --> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>shutdown</command> (<parameter>reboot</parameter> | +<parameter>halt</parameter>) +[<parameter>=<replaceable>bootchoice</replaceable></parameter>] +(<parameter>ask</parameter>|<parameter>trynow</parameter>|<parameter>forcenow</parameter>|<parameter>schedule</parameter>|<parameter>start +(<parameter>-1</parameter>|<parameter>end +(<parameter>force</parameter>|<parameter>forcemy</parameter>|<parameter>cancel)</parameter>)</parameter>)</parameter>)</term> +<listitem> +<para>Request a system shutdown, either a reboot or a halt/poweroff.</para> +<para>An OS choice for the next boot may be specified from the list returned +by <command>listbootoptions</command></para> +<para>Shutdowns requested from per-display sockets are executed when the +current sessino on that display exits. Such a request may pop up a dialog +asking for confirmation and/or authentication</para> +<para><parameter>start</parameter> is the time for which the shutdown is +scheduled. If it starts with a plus-sign, the current time is added. Zero +means immediately.</para> +<para><parameter>end</parameter> is the latest time at which the shutdown +should be performed if active sessions are still running. If it starts with +a plus-sign, the start time is added. -1 means wait infinitely. If end is +through and active sessions are still running, &kdm; can do one of the +following:</para> +<itemizedlist> +<listitem><para><parameter>cancel</parameter> - give up the +shutdown</para></listitem> +<listitem><para><parameter>force</parameter> - shut down +nonetheless</para></listitem> +<listitem><para><parameter>forcemy</parameter> - shut down nonetheless if +all active sessions belong to the requesting user. Only for per-display sockets.</para></listitem> +</itemizedlist> +<para><parameter>start</parameter> and <parameter>end</parameter> are +specified in seconds since the &UNIX; epoch.</para> +<para><parameter>trynow</parameter> is a synonym for <parameter>0 0 +cancel</parameter>, <parameter>forcenow</parameter> for <parameter>0 0 +force</parameter> and <parameter>schedule</parameter> for <parameter>0 +-1</parameter>.</para> +<para><parameter>ask</parameter> attempts an immediate shutdown and +interacts with the user if active sessions are still running. Only for +per-display sockets.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>shutdown cancel</command> +[<parameter>local</parameter>|<parameter>global</parameter>}</term> +<listitem> +<para>Cancel a scheduled shutdown. The global socket always cancels the +currently pending shutdown, while per-display sockets default to cancelling +their queued request.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>shutdown status</command></term> +<listitem> +<para>Return a list with information about shutdowns.</para> +<para>The entries are a comma-separated tuples of:</para> +<itemizedlist> +<listitem> +<para>(<returnvalue>global</returnvalue>|<returnvalue>local</returnvalue>) - +pending vs. queued shutdown. A local entry can be returned only by a +per-display socket.</para> +</listitem> +<listitem><para>(<returnvalue>halt</returnvalue>|<returnvalue>reboot</returnvalue>)</para></listitem> +<listitem><para>start</para></listitem> +<listitem><para>end</para></listitem> +<listitem><para>("ask"|"force"|"forcemy"|"cancel")</para></listitem> +<listitem><para>Numeric user ID of the requesting user, -1 for the global +socket.</para></listitem> +<listitem><para>The next boot OS choice or "-" for none.</para></listitem> +</itemizedlist> +<para>New fields might be added later</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> +</variablelist> +<para>There are two ways of using the sockets:</para> +<itemizedlist> +<listitem> +<para>Connecting them directly. FifoDir is exported as +$<envar>DM_CONTROL</envar>; the name of per-display sockets can be derived +from $<envar>DISPLAY</envar>.</para> +</listitem> +<listitem> +<para>By using the <command>kdmctl</command> command (⪚ from within a +shell script). Try <command>kdmctl</command> <option>-h</option> to find out +more.</para> +</listitem> +</itemizedlist> + +<para>Here is an example bash script <quote>reboot into FreeBSD</quote>:</para> + +<programlisting>if kdmctl | grep -q shutdown; then + IFS=$'\t' + set -- `kdmctl listbootoptions` + if [ "$1" = ok ]; then + fbsd=$(echo "$2" | tr ' ' '\n' | sed -ne 's,\\s, ,g;/freebsd/I{p;q}') + if [ -n "$fbsd" ]; then + kdmctl shutdown reboot "=$fbsd" ask > /dev/null + else + echo "FreeBSD boot unavailable." + fi + else + echo "Boot options unavailable." + fi +else + echo "Cannot reboot system." +fi</programlisting> + +</sect1> +<!-- Riddell: so there's no GUI you need to edit kdmrc to say UseTheme=true and Theme=/path/to/theme.xml +[13:31] <Riddell> jriddell.org/programs has an example theme + +<sect1 id="dm-themes"> +<title>Themes</title> + +&kdm; has limited support for desktop manager themes. You may enable them +by adding <userinput>UseTheme=true</userinput> to <filename>kdmrc</filename> +and <userinput>Theme=/path/to/theme.xml</userinput>. +</sect1> +--> +</chapter> + +<chapter id="Other-Information"> +<title>Other sources of information</title> + +<para>Since &kdm; is descended from &xdm;, the <ulink +url="man:xdm">&xdm; man page</ulink> may provide useful background +information. For X-related problems try the man pages <ulink +url="man:X">X</ulink> and <ulink url="man:startx">startx</ulink>. If you have +questions about &kdm; that are not answered by this handbook, take advantage of +the fact the &kdm; is provided under the terms of the <abbrev>&GNU;</abbrev> +General Public License: look at the source code. +</para> + +</chapter> + + +<chapter id="credits"><title>Credits and License</title> + +<para>&kdm; is derived from, and includes code from, +&xdm; (C) Keith Packard, MIT X Consortium.</para> + +<para>&kdm; 0.1 was written by &Matthias.Ettrich;. Later versions till &kde; +2.0.x were written by &Steffen.Hansen;. Some new features for &kde; 2.1.x and +a major rewrite for &kde; 2.2.x made by &Oswald.Buddenhagen;.</para> + +<para>Other parts of the &kdm; code are copyright by the authors, and +licensed under the terms of the <ulink url="common/gpl-license.html">&GNU; +GPL</ulink>. Anyone is allowed to change &kdm; and redistribute the result +as long as the names of the authors are mentioned.</para> + +<para>&kdm; requires the &Qt; library, which is copyright Troll Tech AS.</para> + +<para>Documentation contributors: +<itemizedlist> + +<listitem><para>Documentation written by &Steffen.Hansen; +<email>[email protected]</email></para></listitem> + +<listitem><para>Documentation extended by Gregor +Zumstein<email>[email protected]</email>. Last update August 9, +1998</para></listitem> + +<listitem><para>Documentation revised for &kde; 2 by &Neal.Crook; &Neal.Crook.mail;. Last update August 6, 2000</para></listitem> + +<listitem><para>Documentation extended and revised for &kde; 2.2 by &Oswald.Buddenhagen; &Oswald.Buddenhagen.mail;. Last update August, +2001</para></listitem> + +</itemizedlist></para> + +<para>Documentation copyright &Steffen.Hansen;, Gregor Zumstein, &Neal.Crook; +and &Oswald.Buddenhagen;. This document also includes large parts of the &xdm; +man page, which is © Keith Packard.</para> + +<!--TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +<glossary id="glossary"> +<title>Glossary</title> + +<glossentry id="gloss-greeter"> +<glossterm>greeter</glossterm> +<glossdef><para>The greeter is the login dialog, &ie; the part of &kdm; +which the user sees.</para> +</glossdef> +</glossentry> + +<glossentry> +<glossterm id="gloss-entropy">entropy</glossterm> +<glossdef><para>The entropy of a system is the measure of its +unpredictability. This is used during the generation of random numbers.</para></glossdef> +</glossentry> + +</glossary> +</book> +<!-- +Local Variables: +mode: xml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/kdm/kdmrc-ref.docbook b/doc/kdm/kdmrc-ref.docbook new file mode 100644 index 000000000..9ebcfbdd3 --- /dev/null +++ b/doc/kdm/kdmrc-ref.docbook @@ -0,0 +1,2316 @@ +<!-- generated from ../../kdm/config.def - DO NOT EDIT! --> + +<chapter id="kdm-files"> +<title>The Files &kdm; Uses for Configuration</title> + +<para>This chapter documents the files that control &kdm;'s behavior. +Some of this can be also controlled from the &kcontrol; module, but +not all.</para> + +<sect1 id="kdmrc"> +<title>&kdmrc; - The &kdm; master configuration file</title> + +<para>The basic format of the file is <quote>INI-like</quote>. +Options are key/value pairs, placed in sections. +Everything in the file is case sensitive. +Syntactic errors and unrecognized key/section identifiers cause &kdm; to +issue non-fatal error messages.</para> + +<para>Lines beginning with <literal>#</literal> are comments; empty lines +are ignored as well.</para> + +<para>Sections are denoted by +<literal>[</literal><replaceable>Name of Section</replaceable><literal>]</literal>. +</para> + +<para>You can configure every X-display individually.</para> +<para>Every display has a display name, which consists of a host name +(which is empty for local displays specified in <option>StaticServers</option> +or <option>ReserveServers</option>), a colon, and a display number. +Additionally, a display belongs to a +display class (which can be ignored in most cases).</para> + +<para>Sections with display-specific settings have the formal syntax +<literal>[X-</literal> <replaceable>host</replaceable> [ <literal>:</literal> <replaceable>number</replaceable> [ <literal>_</literal> <replaceable>class</replaceable> ] ] <literal>-</literal> <replaceable>sub-section</replaceable> <literal>]</literal> +</para> +<para>All sections with the same <replaceable>sub-section</replaceable> +make up a section class.</para> + +<para>You can use the wildcard <literal>*</literal> (match any) for +<replaceable>host</replaceable>, <replaceable>number</replaceable>, +and <replaceable>class</replaceable>. You may omit trailing components; +they are assumed to be <literal>*</literal> then. The host part may be a +domain specification like <replaceable>.inf.tu-dresden.de</replaceable> +or the wildcard <literal>+</literal> (match non-empty).</para> + +<para>From which section a setting is actually taken is determined by +these rules:</para> + +<itemizedlist> +<listitem> +<para>An exact match takes precedence over a partial match (for the +host part), which in turn takes precedence over a wildcard +(<literal>+</literal> taking precendence over <literal>*</literal>).</para> +</listitem> + +<listitem> +<para>Precedence decreases from left to right for equally exact matches.</para> +</listitem> + +<listitem> + +<para> +Example: display name <quote>myhost.foo:0</quote>, class <quote>dpy</quote> +</para> +<itemizedlist> +<listitem> +<para>[X-myhost.foo:0_dpy] precedes</para> +</listitem> +<listitem> +<para>[X-myhost.foo:0_*] (same as [X-myhost.foo:0]) precedes</para> +</listitem> +<listitem> +<para>[X-myhost.foo:*_dpy] precedes</para> +</listitem> +<listitem> +<para>[X-myhost.foo:*_*] (same as [X-myhost.foo]) precedes</para> +</listitem> +<listitem> +<para>[X-.foo:*_*] (same as [X-.foo]) precedes</para> +</listitem> +<listitem> +<para>[X-+:0_dpy] precedes</para> +</listitem> +<listitem> +<para>[X-*:0_dpy] precedes</para> +</listitem> +<listitem> +<para>[X-*:0_*] (same as [X-*:0]) precedes</para> +</listitem> +<listitem> +<para>[X-*:*_*] (same as [X-*]).</para> +</listitem> +<listitem> +<para>These sections do <emphasis>not</emphasis> match this display:</para> +<para>[X-hishost], [X-myhost.foo:0_dec], [X-*:1], [X-:*]</para> +</listitem> +</itemizedlist> + +</listitem> + +</itemizedlist> + +<para>Common sections are [X-*] (all displays), [X-:*] (all local displays) +and [X-:0] (the first local display).</para> + +<para>The format for all keys is +<userinput><option><replaceable>key</replaceable></option> <literal>=</literal> <parameter>value</parameter></userinput>. +Keys are only valid in the section class they are defined for. +Some keys do not apply to particular displays, in which case they are ignored. +</para> + +<para>If a setting is not found in any matching section, the default +is used.</para> + +<para>Special characters need to be backslash-escaped (leading and trailing +spaces (<literal>\s</literal>), tab (<literal>\t</literal>), linefeed +(<literal>\n</literal>), carriage return (<literal>\r</literal>) and the +backslash itself (<literal>\\</literal>)).</para> +<para>In lists, fields are separated with commas without whitespace in between. +</para> +<para>Some command strings are subject to simplified sh-style word splitting: +single quotes (<literal>'</literal>) and double quotes (<literal>"</literal>) +have the usual meaning; the backslash quotes everything (not only special +characters). Note that the backslashes need to be doubled because of the +two levels of quoting.</para> + +<note><para>A pristine &kdmrc; is very thoroughly commented. +All comments will be lost if you change this file with the +kcontrol frontend.</para></note> + + +<sect2 id="kdmrc-general"> +<title>The [General] section of &kdmrc;</title> + +<para> +This section contains global options that do not fit into any specific section. +</para> + +<variablelist> + +<varlistentry> +<term id="option-configversion"><option>ConfigVersion</option></term> +<listitem> +<para> +This option exists solely for the purpose of clean automatic upgrades. +<emphasis>Do not</emphasis> change it, you may interfere with future +upgrades and this could result in &kdm; failing to run. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-staticservers"><option>StaticServers</option></term> +<listitem> +<para> +List of displays (&X-Server;s) permanently managed by &kdm;. Displays with a +hostname are foreign displays which are expected to be already running, +the others are local displays for which &kdm; starts an own &X-Server;; +see <option>ServerCmd</option>. Each display may belong to a display class; +append it to the display name separated by an underscore. +See <xref linkend="kdmrc-xservers"/> for the details. +</para> +<para>The default is <quote>:0</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-reserveservers"><option>ReserveServers</option></term> +<listitem> +<para> +List of on-demand displays. See <option>StaticServers</option> for syntax. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-servervts"><option>ServerVTs</option></term> +<listitem> +<para> +List of Virtual Terminals to allocate to &X-Server;s. For negative numbers the +absolute value is used, and the <acronym>VT</acronym> will be allocated only +if the kernel says it is free. If &kdm; exhausts this list, it will allocate +free <acronym>VT</acronym>s greater than the absolute value of the last entry +in this list. +Currently Linux only. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-consolettys"><option>ConsoleTTYs</option></term> +<listitem> +<para> +This option is for operating systems (<acronym>OS</acronym>s) with support +for virtual terminals (<acronym>VT</acronym>s), by both &kdm; and the +<acronym>OS</acronym>s itself. +Currently this applies only to Linux. +</para><para> +When &kdm; switches to console mode, it starts monitoring all +<acronym>TTY</acronym> lines listed here (without the leading +<literal>/dev/</literal>). +If none of them is active for some time, &kdm; switches back to the X login. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-pidfile"><option>PidFile</option></term> +<listitem> +<para> +The filename specified will be created to contain an ASCII representation +of the process ID of the main &kdm; process; the PID will not be stored +if the filename is empty. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-lockpidfile"><option>LockPidFile</option></term> +<listitem> +<para> +This option controls whether &kdm; uses file locking to keep multiple +display managers from running onto each other. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-authdir"><option>AuthDir</option></term> +<listitem> +<para> +This names a directory under which &kdm; stores &X-Server; authorization +files while initializing the session. &kdm; expects the system to clean up +this directory from stale files on reboot. +</para><para> +The authorization file to be used for a particular display can be +specified with the <option>AuthFile</option> option in [X-*-Core]. +</para> +<para>The default is <quote>/var/run/xauth</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autorescan"><option>AutoRescan</option></term> +<listitem> +<para> +This boolean controls whether &kdm; automatically re-reads its +configuration files if it finds them to have changed. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-exportlist"><option>ExportList</option></term> +<listitem> +<para> +Additional environment variables &kdm; should pass on to all programs it runs. +<envar>LD_LIBRARY_PATH</envar> and <envar>XCURSOR_THEME</envar> are good candidates; +otherwise, it should not be necessary very often. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-randomfile"><option>RandomFile</option></term> +<listitem> +<para> +If the system has no native entropy source like /dev/urandom (see +<option>RandomDevice</option>) and no entropy daemon like EGD (see +<option>PrngdSocket</option> and <option>PrngdPort</option>) is running, +&kdm; will fall back to its own pseudo-random number generator +that will, among other things, successively checksum parts of this file +(which, obviously, should change frequently). +</para><para> +This option does not exist on Linux and various BSDs. +</para> +<para>The default is <quote>/dev/mem</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-prngdsocket"><option>PrngdSocket</option></term> +<listitem> +<para> +If the system has no native entropy source like /dev/urandom (see +<option>RandomDevice</option>), read random data from a Pseudo-Random +Number Generator Daemon, +like EGD (http://egd.sourceforge.net) via this UNIX domain socket. +</para><para> +This option does not exist on Linux and various BSDs. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-prngdport"><option>PrngdPort</option></term> +<listitem> +<para> +Same as <option>PrngdSocket</option>, only use a TCP socket on localhost. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-randomdevice"><option>RandomDevice</option></term> +<listitem> +<para> +The path to a character device which &kdm; should read random data from. +Empty means to use the system's preferred entropy device if there is one. +</para><para> +This option does not exist on OpenBSD, as it uses the arc4_random +function instead. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-fifodir"><option>FifoDir</option></term> +<listitem> +<para> +The directory in which the command <acronym>FiFo</acronym>s should +be created; make it empty to disable them. +</para> +<para>The default is <quote>/var/run/xdmctl</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-fifogroup"><option>FifoGroup</option></term> +<listitem> +<para> +The group to which the global command <acronym>FiFo</acronym> should belong; +can be either a name or a numerical ID. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-datadir"><option>DataDir</option></term> +<listitem> +<para> +The directory in which &kdm; should store persistent working data; such data +is, for example, the previous user that logged in on a particular display. +</para> +<para>The default is <quote>/var/lib/kdm</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-dmrcdir"><option>DmrcDir</option></term> +<listitem> +<para> +The directory in which &kdm; should store users' <filename>.dmrc</filename> files. This is only +needed if the home directories are not readable before actually logging in +(like with AFS). +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + + +<sect2 id="kdmrc-xdmcp"> +<title>The [Xdmcp] section of &kdmrc;</title> + +<para> +This section contains options that control &kdm;'s handling of +&XDMCP; requests. +</para> + +<variablelist> + +<varlistentry> +<term id="option-enable"><option>Enable</option></term> +<listitem> +<para> +Whether &kdm; should listen to incoming &XDMCP; requests. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-port"><option>Port</option></term> +<listitem> +<para> +This indicates the UDP port number which &kdm; uses to listen for incoming +&XDMCP; requests. Unless you need to debug the system, leave this with its +default value. +</para> +<para>The default is <quote>177</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-keyfile"><option>KeyFile</option></term> +<listitem> +<para> +XDM-AUTHENTICATION-1 style &XDMCP; authentication requires a private +key to be shared between &kdm; and the terminal. This option specifies +the file containing those values. Each entry in the file consists of a +display name and the shared key. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-xaccess"><option>Xaccess</option></term> +<listitem> +<para> +To prevent unauthorized &XDMCP; service and to allow forwarding of &XDMCP; +IndirectQuery requests, this file contains a database of hostnames which +are either allowed direct access to this machine, or have a list of hosts +to which queries should be forwarded to. The format of this file is +described in <xref linkend="kdmrc-xaccess"/>. +</para> +<para>The default is <quote>${<envar>kde_confdir</envar>}/kdm/Xaccess</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-choicetimeout"><option>ChoiceTimeout</option></term> +<listitem> +<para> +Number of seconds to wait for the display to respond after the user has +selected a host from the chooser. If the display sends an &XDMCP; +IndirectQuery within this time, the request is forwarded to the chosen +host; otherwise, it is assumed to be from a new session and the chooser +is offered again. +</para> +<para>The default is <quote>15</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-removedomainname"><option>RemoveDomainname</option></term> +<listitem> +<para> +When computing the display name for &XDMCP; clients, the name resolver will +typically create a fully qualified host name for the terminal. As this is +sometimes confusing, &kdm; will remove the domain name portion of the host +name if it is the same as the domain name of the local host when this option +is enabled. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-sourceaddress"><option>SourceAddress</option></term> +<listitem> +<para> +Use the numeric IP address of the incoming connection on multihomed hosts +instead of the host name. This is to avoid trying to connect on the wrong +interface which might be down at this time. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-willing"><option>Willing</option></term> +<listitem> +<para> +This specifies a program which is run (as +<systemitem class="username">root</systemitem>) when an &XDMCP; +DirectQuery or BroadcastQuery is received and this host is configured +to offer &XDMCP; display management. The output of this program may be +displayed in a chooser window. If no program is specified, the string +<quote>Willing to manage</quote> is sent. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + + +<sect2 id="kdmrc-shutdown"> +<title>The [Shutdown] section of &kdmrc;</title> + +<para> +This section contains global options concerning system shutdown. +</para> + +<variablelist> + +<varlistentry> +<term id="option-haltcmd"><option>HaltCmd</option></term> +<listitem> +<para> +The command (subject to word splitting) to run to halt/poweroff the system. +</para><para> +The default is something reasonable for the system on which &kdm; was built, like +<command>/sbin/shutdown <option>-h</option> <parameter>now</parameter></command>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-rebootcmd"><option>RebootCmd</option></term> +<listitem> +<para> +The command (subject to word splitting) to run to reboot the system. +</para><para> +The default is something reasonable for the system &kdm; on which was built, like +<command>/sbin/shutdown <option>-r</option> <parameter>now</parameter></command>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allowfifo"><option>AllowFifo</option></term> +<listitem> +<para> +Whether it is allowed to shut down the system via the global command <acronym>FiFo</acronym>. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allowfifonow"><option>AllowFifoNow</option></term> +<listitem> +<para> +Whether it is allowed to abort active sessions when shutting down the +system via the global command <acronym>FiFo</acronym>. +</para><para> +This will have no effect unless <option>AllowFifo</option> is enabled. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-bootmanager"><option>BootManager</option></term> +<listitem> +<para> +The boot manager &kdm; should use for offering boot options in the +shutdown dialog. +</para> +<variablelist> +<varlistentry> +<term><parameter>None</parameter></term> +<listitem><para>no boot manager</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Grub</parameter></term> +<listitem><para>Grub boot manager</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Lilo</parameter></term> +<listitem><para>Lilo boot manager (Linux on i386 & x86-64 only)</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>None</quote>.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + + +<sect2 id="kdmrc-core"> +<title>The [X-*-Core] section class of &kdmrc;</title> + +<para> +This section class contains options concerning the configuration +of the &kdm; backend (core). +</para> + +<variablelist> + +<varlistentry> +<term id="option-opendelay"><option>OpenDelay</option></term> +<listitem> +<para> +See <option>OpenRepeat</option>. +</para> +<para>The default is <quote>15</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-opentimeout"><option>OpenTimeout</option></term> +<listitem> +<para> +See <option>OpenRepeat</option>. +</para> +<para>The default is <quote>120</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-openrepeat"><option>OpenRepeat</option></term> +<listitem> +<para> +These options control the behavior of &kdm; when attempting to open a +connection to an &X-Server;. <option>OpenDelay</option> is the length +of the pause (in seconds) between successive attempts, +<option>OpenRepeat</option> is the number of attempts to make and +<option>OpenTimeout</option> is the amount of time to spend on a +connection attempt. After <option>OpenRepeat</option> attempts have been +made, or if <option>OpenTimeout</option> seconds elapse in any particular +connection attempt, the start attempt is considered failed. +</para> +<para>The default is <quote>5</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-startattempts"><option>StartAttempts</option></term> +<listitem> +<para> +How many times &kdm; should attempt to start a <literal>foreign</literal> +display listed in <option>StaticServers</option> before giving up +and disabling it. +Local displays are attempted only once, and &XDMCP; displays are retried +indefinitely by the client (unless the option <option>-once</option> +was given to the &X-Server;). +</para> +<para>The default is <quote>4</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-serverattempts"><option>ServerAttempts</option></term> +<listitem> +<para> +How many times &kdm; should attempt to start up a local &X-Server;. +Starting up includes executing it and waiting for it to come up. +</para> +<para>The default is <quote>1</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-servertimeout"><option>ServerTimeout</option></term> +<listitem> +<para> +How many seconds &kdm; should wait for a local &X-Server; to come up. +</para> +<para>The default is <quote>15</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-servercmd"><option>ServerCmd</option></term> +<listitem> +<para> +The command line to start the &X-Server;, without display number and VT spec. +This string is subject to word splitting. +</para><para> +The default is something reasonable for the system on which &kdm; was built, +like <command>/usr/X11R6/bin/X</command>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-serverargslocal"><option>ServerArgsLocal</option></term> +<listitem> +<para> +Additional arguments for the &X-Server;s for local sessions. +This string is subject to word splitting. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-serverargsremote"><option>ServerArgsRemote</option></term> +<listitem> +<para> +Additional arguments for the &X-Server;s for remote sessions. +This string is subject to word splitting. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-servervt"><option>ServerVT</option></term> +<listitem> +<para> +The VT the &X-Server; should run on. +<option>ServerVTs</option> should be used instead of this option. +Leave it zero to let &kdm; assign a <acronym>VT</acronym> automatically. +Set it to <literal>-1</literal> to avoid assigning a <acronym>VT</acronym> +alltogether - this is required for setups with multiple physical consoles. +Currently Linux only. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-servertty"><option>ServerTTY</option></term> +<listitem> +<para> +This option is for <acronym>OS</acronym>s without support for +<acronym>VT</acronym>s, either by &kdm; or the <acronym>OS</acronym> itself. +Currently this applies to all <acronym>OS</acronym>s but Linux. +</para><para> +When &kdm; switches to console mode, it starts monitoring this +<acronym>TTY</acronym> line (specified without the leading +<literal>/dev/</literal>) for activity. If the line is not used for some time, +&kdm; switches back to the X login. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-pinginterval"><option>PingInterval</option></term> +<listitem> +<para> +See <option>PingTimeout</option>. +</para> +<para>The default is <quote>5</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-pingtimeout"><option>PingTimeout</option></term> +<listitem> +<para> +To discover when <emphasis>remote</emphasis> displays disappear, &kdm; +regularly pings them. +<option>PingInterval</option> specifies the time (in minutes) between the +pings and <option>PingTimeout</option> specifies the maximum amount of +time (in minutes) to wait for the terminal to respond to the request. If +the terminal does not respond, the session is declared dead and terminated. +</para><para> +If you frequently use X terminals which can become isolated from +the managing host, you may wish to increase the timeout. The only worry +is that sessions will continue to exist after the terminal has been +accidentally disabled. +</para> +<para>The default is <quote>5</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-terminateserver"><option>TerminateServer</option></term> +<listitem> +<para> +Whether &kdm; should restart the local &X-Server; after session exit instead +of resetting it. Use this if the &X-Server; leaks memory or crashes the system +on reset attempts. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-resetsignal"><option>ResetSignal</option></term> +<listitem> +<para> +The signal number to use to reset the local &X-Server;. +</para> +<para>The default is <quote>1 (SIGHUP)</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-termsignal"><option>TermSignal</option></term> +<listitem> +<para> +The signal number to use to terminate the local &X-Server;. +</para> +<para>The default is <quote>15 (SIGTERM)</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-authorize"><option>Authorize</option></term> +<listitem> +<para> +Controls whether &kdm; generates and uses authorization for +<emphasis>local</emphasis> &X-Server; connections. +For &XDMCP; displays the authorization requested by the display is used; +foreign non-&XDMCP; displays do not support authorization at all. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-authnames"><option>AuthNames</option></term> +<listitem> +<para> +If <option>Authorize</option> is true, use the authorization mechanisms +listed herein. The MIT-MAGIC-COOKIE-1 authorization is always available; +XDM-AUTHORIZATION-1, SUN-DES-1 and MIT-KERBEROS-5 might be available as well, +depending on the build configuration. +</para> +<para>The default is <quote>DEF_AUTH_NAME</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-resetforauth"><option>ResetForAuth</option></term> +<listitem> +<para> +Some <emphasis>old</emphasis> &X-Server;s re-read the authorization file +at &X-Server; reset time, instead of when checking the initial connection. +As &kdm; generates the authorization information just before connecting to +the display, an old &X-Server; would not get up-to-date authorization +information. This option causes &kdm; to send SIGHUP to the &X-Server; +after setting up the file, causing an additional &X-Server; reset to occur, +during which time the new authorization information will be read. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-authfile"><option>AuthFile</option></term> +<listitem> +<para> +This file is used to communicate the authorization data from &kdm; to +the &X-Server;, using the <option>-auth</option> &X-Server; command line +option. It should be kept in a directory which is not world-writable +as it could easily be removed, disabling the authorization mechanism in +the &X-Server;. If not specified, a random name is generated from +<option>AuthDir</option> and the name of the display. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-resources"><option>Resources</option></term> +<listitem> +<para> +This option specifies the name of the file to be loaded by +<command>xrdb</command> as the resource database onto the root window +of screen 0 of the display. KDE programs generally do not use +X-resources, so this option is only needed if the <option>Setup</option> +program needs some X-resources. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-xrdb"><option>Xrdb</option></term> +<listitem> +<para> +The <command>xrdb</command> program to use to read the X-resources file +specified in <option>Recources</option>. +The command is subject to word splitting. +</para> +<para>The default is <quote>${<envar>x_bindir</envar>}/xrdb</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-setup"><option>Setup</option></term> +<listitem> +<para> +This string is subject to word splitting. +It specifies a program which is run (as +<systemitem class="username">root</systemitem>) before offering the +greeter window. This may be used to change the appearance of the screen +around the greeter window or to put up other windows (e.g., you may want +to run <command>xconsole</command> here). +The conventional name for a program used here is <command>Xsetup</command>. +See <xref linkend="kdmrc-xsetup"/>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-startup"><option>Startup</option></term> +<listitem> +<para> +This string is subject to word splitting. +It specifies a program which is run (as +<systemitem class="username">root</systemitem>) after the user +authentication process succeeds. +The conventional name for a program used here is <command>Xstartup</command>. +See <xref linkend="kdmrc-xstartup"/>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-reset"><option>Reset</option></term> +<listitem> +<para> +This string is subject to word splitting. +It specifies a program which is run (as +<systemitem class="username">root</systemitem>) after the session +terminates. +The conventional name for a program used here is <command>Xreset</command>. +See <xref linkend="kdmrc-xreset"/>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-session"><option>Session</option></term> +<listitem> +<para> +This string is subject to word splitting. +It specifies the session program to be executed (as the user owning +the session). +The conventional name for a program used here is <command>Xsession</command>. +See <xref linkend="kdmrc-xsession"/>. +</para> +<para>The default is <quote>${<envar>x_bindir</envar>}/xterm -ls -T</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-failsafeclient"><option>FailsafeClient</option></term> +<listitem> +<para> +If the <option>Session</option> program fails to execute, &kdm; will +fall back to this program. This program is executed with no arguments, +but executes using the same environment variables as the session would +have had (see <xref linkend="kdmrc-xsession"/>). +</para> +<para>The default is <quote>${<envar>x_bindir</envar>}/xterm</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-userpath"><option>UserPath</option></term> +<listitem> +<para> +The <envar>PATH</envar> environment variable for +non-<systemitem class="username">root</systemitem> <option>Session</option>s. +</para><para> +The default depends on the system &kdm; was built on. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-systempath"><option>SystemPath</option></term> +<listitem> +<para> +The <envar>PATH</envar> environment variable for all programs but +non-<systemitem class="username">root</systemitem> +<option>Session</option>s. Note that it is good practice not to include +<literal>.</literal> (the current directory) into this entry. +</para><para> +The default depends on the system &kdm; was built on. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-systemshell"><option>SystemShell</option></term> +<listitem> +<para> +The <envar>SHELL</envar> environment variable for all programs but the +<option>Session</option>. +</para> +<para>The default is <quote>/bin/sh</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-userauthdir"><option>UserAuthDir</option></term> +<listitem> +<para> +When &kdm; is unable to write to the usual user authorization file +($<envar>HOME</envar>/.Xauthority), it creates a unique file name in this +directory and points the environment variable <envar>XAUTHORITY</envar> +at the created file. +</para> +<para>The default is <quote>/tmp</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autorelogin"><option>AutoReLogin</option></term> +<listitem> +<para> +If enabled, &kdm; will automatically restart a session after an &X-Server; +crash (or if it is killed by Alt-Ctrl-BackSpace). Note that enabling this +feature opens a security hole: a secured display lock can be circumvented +(unless &kde;'s built-in screen locker is used). +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allowrootlogin"><option>AllowRootLogin</option></term> +<listitem> +<para> +If disabled, do not allow <systemitem class="username">root</systemitem> +(and any other user with UID = 0) to log in directly. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allownullpasswd"><option>AllowNullPasswd</option></term> +<listitem> +<para> +If disabled, only users that have passwords assigned can log in. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allowshutdown"><option>AllowShutdown</option></term> +<listitem> +<para> +Who is allowed to shut down the system. This applies both to the +greeter and to the command <acronym>FiFo</acronym>. +</para> +<variablelist> +<varlistentry> +<term><parameter>None</parameter></term> +<listitem><para>no <guilabel>Shutdown...</guilabel> menu entry is shown at all</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Root</parameter></term> +<listitem><para>the <systemitem class="username">root</systemitem> password must be entered to shut down</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>All</parameter></term> +<listitem><para>everybody can shut down the machine</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>All</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allowsdforcenow"><option>AllowSdForceNow</option></term> +<listitem> +<para> +Who is allowed to abort active sessions when shutting down. +</para> +<variablelist> +<varlistentry> +<term><parameter>None</parameter></term> +<listitem><para>no forced shutdown is allowed at all</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Root</parameter></term> +<listitem><para>the <systemitem class="username">root</systemitem> password must be entered to shut down forcibly</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>All</parameter></term> +<listitem><para>everybody can shut down the machine forcibly</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>All</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-defaultsdmode"><option>DefaultSdMode</option></term> +<listitem> +<para> +The default choice for the shutdown condition/timing. +</para> +<variablelist> +<varlistentry> +<term><parameter>Schedule</parameter></term> +<listitem><para>shut down after all active sessions exit (possibly at once)</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>TryNow</parameter></term> +<listitem><para>shut down, if no active sessions are open; otherwise, do nothing</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>ForceNow</parameter></term> +<listitem><para>shut down unconditionally</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>Schedule</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-scheduledsd"><option>ScheduledSd</option></term> +<listitem> +<para> +How to offer shutdown scheduling options: +</para> +<variablelist> +<varlistentry> +<term><parameter>Never</parameter></term> +<listitem><para>not at all</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Optional</parameter></term> +<listitem><para>as a button in the simple shutdown dialogs</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Always</parameter></term> +<listitem><para>instead of the simple shutdown dialogs</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>Never</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-nopassenable"><option>NoPassEnable</option></term> +<listitem> +<para> +Enable password-less logins on this display. <emphasis>Use with extreme care!</emphasis> +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-nopassusers"><option>NoPassUsers</option></term> +<listitem> +<para> +The users that do not need to provide a password to log in. +Items which are prefixed with <literal>@</literal> represent all users in the +user group named by that item. +<literal>*</literal> means all users but +<systemitem class="username">root</systemitem> +(and any other user with UID = 0). +<emphasis>Never</emphasis> list <systemitem class="username">root</systemitem>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autologinenable"><option>AutoLoginEnable</option></term> +<listitem> +<para> +Enable automatic login. <emphasis>Use with extreme care!</emphasis> +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autologinagain"><option>AutoLoginAgain</option></term> +<listitem> +<para> +If true, auto-login after logout. If false, auto-login is performed only +when a display session starts up. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autologindelay"><option>AutoLoginDelay</option></term> +<listitem> +<para> +The delay in seconds before automatic login kicks in. This is also known as +<quote>Timed Login</quote>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autologinuser"><option>AutoLoginUser</option></term> +<listitem> +<para> +The user to log in automatically. <emphasis>Never</emphasis> specify <systemitem class="username">root</systemitem>! +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autologinpass"><option>AutoLoginPass</option></term> +<listitem> +<para> +The password for the user to log in automatically. This is <emphasis>not</emphasis> required +unless the user is logged into a <acronym>NIS</acronym> or Kerberos domain. If you use this +option, you should <command>chmod <option>600</option> <filename>kdmrc</filename></command> for obvious reasons. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-autologinlocked"><option>AutoLoginLocked</option></term> +<listitem> +<para> +Immediately lock the automatically started session. This works only with +KDE sessions. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-sessionsdirs"><option>SessionsDirs</option></term> +<listitem> +<para> +A list of directories containing session type definitions. +</para> +<para>The default is <quote>${<envar>kde_datadir</envar>}/kdm/sessions</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-clientlogfile"><option>ClientLogFile</option></term> +<listitem> +<para> +The file (relative to the user's home directory) to redirect the session +output to. One occurrence of <parameter>%s</parameter> in this string will be +substituted with the display name. Use <parameter>%%</parameter> to obtain a +literal <literal>%</literal>. +</para> +<para>The default is <quote>.xsession-errors</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-usesessreg"><option>UseSessReg</option></term> +<listitem> +<para> +Specify whether &kdm;'s built-in utmp/wtmp/lastlog registration should +be used. If it is not, the tool <command>sessreg</command> should be used +in the <option>Startup</option> and <option>Reset</option> scripts, or, +alternatively, the pam_lastlog module should be used on +<acronym>PAM</acronym>-enabled systems. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + + +<sect2 id="kdmrc-greeter"> +<title>The [X-*-Greeter] section class of &kdmrc;</title> + +<para> +This section class contains options concerning the configuration +of the &kdm; frontend (greeter). +</para> + +<variablelist> + +<varlistentry> +<term id="option-guistyle"><option>GUIStyle</option></term> +<listitem> +<para> +Specify the widget style for the greeter. Empty means to use the +built-in default which currently is <literal>Plastik</literal>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-colorscheme"><option>ColorScheme</option></term> +<listitem> +<para> +Specify the widget color scheme for the greeter. Empty means to use +the built-in default which currently is yellowish grey with some light +blue and yellow elements. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-logoarea"><option>LogoArea</option></term> +<listitem> +<para> +What should be shown in the greeter righthand of the input lines (if +<option>UserList</option> is disabled) or above them (if +<option>UserList</option> is enabled): +</para> +<variablelist> +<varlistentry> +<term><parameter>None</parameter></term> +<listitem><para>nothing</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Logo</parameter></term> +<listitem><para>the image specified by <option>LogoPixmap</option></para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Clock</parameter></term> +<listitem><para>a neat analog clock</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>Clock</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-logopixmap"><option>LogoPixmap</option></term> +<listitem> +<para> +The image to show in the greeter if <option>LogoArea</option> is +<literal>Logo</literal>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-greeterpos"><option>GreeterPos</option></term> +<listitem> +<para> +The relative coordinates (percentages of the screen size; X,Y) at which +the center of the greeter is put. &kdm; aligns the greeter to the edges +of the screen it would cross otherwise. +</para> +<para>The default is <quote>50,50</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-greeterscreen"><option>GreeterScreen</option></term> +<listitem> +<para> +The screen the greeter should be displayed on in multi-headed and Xinerama +setups. The numbering starts with 0. For Xinerama, it corresponds to the +listing order in the active ServerLayout section of XF86Config; -1 means +to use the upper-left screen, -2 means to use the upper-right screen. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-greetstring"><option>GreetString</option></term> +<listitem> +<para> +The headline in the greeter. An empty greeting means none at all. +</para><para> +The following character pairs are replaced by their value: +<variablelist> +<varlistentry> +<term><parameter>%d</parameter></term> +<listitem><para>name of the current display</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>%h</parameter></term> +<listitem><para>local host name, possibly with the + domain name</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>%n</parameter></term> +<listitem><para>local node name, most probably the host name without the + domain name</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>%s</parameter></term> +<listitem><para>operating system</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>%r</parameter></term> +<listitem><para>operating system version</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>%m</parameter></term> +<listitem><para>machine (hardware) type</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>%%</parameter></term> +<listitem><para>a single <literal>%</literal></para></listitem> +</varlistentry> +</variablelist> +</para> +<para>The default is <quote>Welcome to %s at %n</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-antialiasing"><option>AntiAliasing</option></term> +<listitem> +<para> +Whether the fonts used in the greeter should be antialiased. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-greetfont"><option>GreetFont</option></term> +<listitem> +<para> +The font for the greeter headline. +</para> +<para>The default is <quote>Serif,20,bold</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-stdfont"><option>StdFont</option></term> +<listitem> +<para> +The normal font used in the greeter. +</para> +<para>The default is <quote>Sans Serif,10</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-failfont"><option>FailFont</option></term> +<listitem> +<para> +The font used for the <quote>Login Failed</quote> message. +</para> +<para>The default is <quote>Sans Serif,10,bold</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-numlock"><option>NumLock</option></term> +<listitem> +<para> +What to do with the Num Lock modifier for the time the greeter is running: +</para> +<variablelist> +<varlistentry> +<term><parameter>Off</parameter></term> +<listitem><para>turn off</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>On</parameter></term> +<listitem><para>turn on</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Keep</parameter></term> +<listitem><para>do not change the state</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>Keep</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-language"><option>Language</option></term> +<listitem> +<para> +Language and locale to use in the greeter, encoded like $<envar>LC_LANG</envar>. +</para> +<para>The default is <quote>en_US</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-usercompletion"><option>UserCompletion</option></term> +<listitem> +<para> +Enable autocompletion in the username line edit. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-userlist"><option>UserList</option></term> +<listitem> +<para> +Show a user list with unix login names, real names, and images in the greeter. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-showusers"><option>ShowUsers</option></term> +<listitem> +<para> +This option controls which users will be shown in the user view +(<option>UserList</option>) and/or offered for autocompletion +(<option>UserCompletion</option>). +If it is <literal>Selected</literal>, <option>SelectedUsers</option> contains +the final list of users. +If it is <literal>NotHidden</literal>, the initial user list contains all users +found on the system. Users contained in <option>HiddenUsers</option> are +removed from the list, just like all users with a UID greater than specified +in <option>MaxShowUID</option> and users with a non-zero UID less than +specified in <option>MinShowUID</option>. +Items in <option>SelectedUsers</option> and <option>HiddenUsers</option> +which are prefixed with <literal>@</literal> represent all users in the +user group named by that item. +Finally, the user list will be sorted alphabetically, if +<option>SortUsers</option> is enabled. +</para> +<para>The default is <quote>NotHidden</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-selectedusers"><option>SelectedUsers</option></term> +<listitem> +<para> +See <option>ShowUsers</option>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-hiddenusers"><option>HiddenUsers</option></term> +<listitem> +<para> +See <option>ShowUsers</option>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-minshowuid"><option>MinShowUID</option></term> +<listitem> +<para> +See <option>ShowUsers</option>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-maxshowuid"><option>MaxShowUID</option></term> +<listitem> +<para> +See <option>ShowUsers</option>. +</para> +<para>The default is <quote>65535</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-sortusers"><option>SortUsers</option></term> +<listitem> +<para> +See <option>ShowUsers</option>. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-facesource"><option>FaceSource</option></term> +<listitem> +<para> +If <option>UserList</option> is enabled, this specifies where &kdm; gets the +images from: +</para> +<variablelist> +<varlistentry> +<term><parameter>AdminOnly</parameter></term> +<listitem><para>from <filename><<option>FaceDir</option>>/$<envar>USER</envar>.face[.icon]</filename></para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>PreferAdmin</parameter></term> +<listitem><para>prefer <<option>FaceDir</option>>, fallback on $<envar>HOME</envar></para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>PreferUser</parameter></term> +<listitem><para>... and the other way round</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>UserOnly</parameter></term> +<listitem><para>from the user's <filename>$<envar>HOME</envar>/.face[.icon]</filename></para></listitem> +</varlistentry> +</variablelist> + +<para> +The images can be in any format Qt recognizes, but the filename +must match &kdm;'s expectations: <literal>.face.icon</literal> should be a +48x48 icon, while <literal>.face</literal> should be a 300x300 image. +Currently the big image is used only as a fallback and is scaled down, +but in the future it might be displayed full-size in the logo area or a +tooltip. +</para> +<para>The default is <quote>AdminOnly</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-facedir"><option>FaceDir</option></term> +<listitem> +<para> +See <option>FaceSource</option>. +</para> +<para>The default is <quote>${<envar>kde_datadir</envar>}/kdm/faces</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-preselectuser"><option>PreselectUser</option></term> +<listitem> +<para> +Specify, if/which user should be preselected for log in: +</para> +<variablelist> +<varlistentry> +<term><parameter>None</parameter></term> +<listitem><para>do not preselect any user</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Previous</parameter></term> +<listitem><para>the user which successfully logged in last time</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>Default</parameter></term> +<listitem><para>the user specified in the <option>DefaultUser</option> option</para></listitem> +</varlistentry> +</variablelist> + +<para> +If <option>FocusPasswd</option> is enabled and a user was preselected, +the cursor is placed in the password input field automatically. +</para> +<note><para>Enabling user preselection can be considered a security hole, +as it presents a valid login name to a potential attacker, so he +<quote>only</quote> needs to guess the password. On the other hand, +one could set <option>DefaultUser</option> to a fake login name.</para></note> +<para> +</para> +<para>The default is <quote>None</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-defaultuser"><option>DefaultUser</option></term> +<listitem> +<para> +See <option>PreselectUser</option>. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-focuspasswd"><option>FocusPasswd</option></term> +<listitem> +<para> +See <option>PreselectUser</option>. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-echomode"><option>EchoMode</option></term> +<listitem> +<para> +The password input fields cloak the typed in text. Specify, how to do it: +</para> +<variablelist> +<varlistentry> +<term><parameter>OneStar</parameter></term> +<listitem><para><literal>*</literal> is shown for every typed +character</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>ThreeStars</parameter></term> +<listitem><para><literal>***</literal> is shown for every typed +character</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>NoEcho</parameter></term> +<listitem><para>nothing is shown at all, the cursor does not move</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>OneStar</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-usebackground"><option>UseBackground</option></term> +<listitem> +<para> +If enabled, &kdm; will automatically start the <command>krootimage</command> +program to set up the background; otherwise, the <option>Setup</option> +program is responsible for the background. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-backgroundcfg"><option>BackgroundCfg</option></term> +<listitem> +<para> +The configuration file to be used by <command>krootimage</command>. +It contains a section named <literal>[Desktop0]</literal> like +<filename>kdesktoprc</filename> does. Its options are not described +herein; guess their meanings or use the control center. +</para> +<para>The default is <quote>${<envar>kde_confdir</envar>}/kdm/backgroundrc</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-grabserver"><option>GrabServer</option></term> +<listitem> +<para> +To improve security, the greeter grabs the &X-Server; and then the keyboard +when it starts up. This option specifies if the &X-Server; grab should be held +for the duration of the name/password reading. When disabled, the &X-Server; +is ungrabbed after the keyboard grab succeeds; otherwise, the &X-Server; is +grabbed until just before the session begins. +</para> +<note><para>Enabling this option disables <option>UseBackground</option> and +<option>Setup</option>.</para></note> +<para> +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-grabtimeout"><option>GrabTimeout</option></term> +<listitem> +<para> +This option specifies the maximum time &kdm; will wait for the grabs to +succeed. A grab may fail if some other X-client has the &X-Server; or the +keyboard grabbed, or possibly if the network latencies are very high. You +should be cautious when raising the timeout, as a user can be spoofed by +a look-alike window on the display. If a grab fails, &kdm; kills and +restarts the &X-Server; (if possible) and the session. +</para> +<para>The default is <quote>3</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-authcomplain"><option>AuthComplain</option></term> +<listitem> +<para> +Warn, if a display has no X-authorization. This will be the case if +<itemizedlist> + <listitem><para> + the authorization file for a local &X-Server; could not be created, + </para></listitem> + <listitem><para> + a remote display from &XDMCP; did not request any authorization or + </para></listitem> + <listitem><para> + the display is a <quote>foreign</quote> display specified in + <option>StaticServers</option>. + </para></listitem> +</itemizedlist> +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-loginmode"><option>LoginMode</option></term> +<listitem> +<para> +Specify whether the greeter of local displays should start up in host chooser +(remote) or login (local) mode and whether it is allowed to switch to the +other mode. +</para> +<variablelist> +<varlistentry> +<term><parameter>LocalOnly</parameter></term> +<listitem><para>only local login possible</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>DefaultLocal</parameter></term> +<listitem><para>start up in local mode, but allow switching to remote mode</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>DefaultRemote</parameter></term> +<listitem><para>... and the other way round</para></listitem> +</varlistentry> +<varlistentry> +<term><parameter>RemoteOnly</parameter></term> +<listitem><para>only choice of remote host possible</para></listitem> +</varlistentry> +</variablelist> +<para>The default is <quote>LocalOnly</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-chooserhosts"><option>ChooserHosts</option></term> +<listitem> +<para> +A list of hosts to be automatically added to the remote login menu. +The special name <literal>*</literal> means broadcast. +Has no effect if <option>LoginMode</option> is <literal>LocalOnly</literal>. +</para> +<para>The default is <quote>*</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-forgingseed"><option>ForgingSeed</option></term> +<listitem> +<para> +Use this number as a random seed when forging saved session types, etc. of +unknown users. This is used to avoid telling an attacker about existing users +by reverse conclusion. This value should be random but constant across the +login domain. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-showlog"><option>ShowLog</option></term> +<listitem> +<para> +Enable &kdm;'s built-in <command>xconsole</command>. +Note that this can be enabled for only one display at a time. +This option is available only if &kdm; was <command>configure</command>d +with <option>--enable-kdm-xconsole</option>. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-logsource"><option>LogSource</option></term> +<listitem> +<para> +The data source for &kdm;'s built-in <command>xconsole</command>. +If empty, a console log redirection is requested from +<filename>/dev/console</filename>. +Has no effect if <option>ShowLog</option> is disabled. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-pluginslogin"><option>PluginsLogin</option></term> +<listitem> +<para> +Specify conversation plugins for the login dialog; the first in the list +is selected initially. +Each plugin can be specified as a base name (which expands to +<filename>$<envar>kde_modulesdir</envar>/kgreet_<replaceable>base</replaceable></filename>) +or as a full pathname. +</para><para> +Conversation plugins are modules for the greeter which obtain authentication +data from the user. Currently only the <literal>classic</literal> plugin is +shipped with &kde;; it presents the well-known username and password form. +</para> +<para>The default is <quote>classic</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-pluginsshutdown"><option>PluginsShutdown</option></term> +<listitem> +<para> +Same as <option>PluginsLogin</option>, but for the shutdown dialog. +</para> +<para>The default is <quote>classic</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-pluginoptions"><option>PluginOptions</option></term> +<listitem> +<para> +A list of options of the form +<replaceable>Key</replaceable><literal>=</literal><replaceable>Value</replaceable>. +The conversation plugins can query these settings; it is up to them what +possible keys are. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allowconsole"><option>AllowConsole</option></term> +<listitem> +<para> +Show the <guilabel>Console Login</guilabel> action in the greeter (if <option>ServerTTY</option>/<option>ConsoleTTYs</option> +is configured). +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-allowclose"><option>AllowClose</option></term> +<listitem> +<para> +Show the <guilabel>Restart X Server</guilabel>/<guilabel>Close Connection</guilabel> action in the greeter. +</para> +<para>The default is <quote>true</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-preloader"><option>Preloader</option></term> +<listitem> +<para> +A program to run while the greeter is visible. It is supposed to preload +as much as possible of the session that is going to be started (most +probably). +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-usetheme"><option>UseTheme</option></term> +<listitem> +<para> +Whether the greeter should be themed. +</para> +<para>The default is <quote>false</quote>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="option-theme"><option>Theme</option></term> +<listitem> +<para> +The theme to use for the greeter. Can point to either a directory or an XML +file. +</para> +<para>Empty by default.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + + + +</sect1> + +<sect1 id="kdmrc-xservers"> +<title>Specifying permanent &X-Server;s</title> + +<para>Each entry in the <option>StaticServers</option> list indicates a +display which should constantly be +managed and which is not using &XDMCP;. This method is typically used only for +local &X-Server;s that are started by &kdm;, but &kdm; can manage externally +started (<quote>foreign</quote>) &X-Server;s as well, may they run on the +local machine or rather remotely.</para> + +<para>The formal syntax of a specification is +<screen> +<userinput><replaceable>display name</replaceable> [<literal>_</literal><replaceable>display class</replaceable>]</userinput> +</screen> +for all &X-Server;s. <quote>Foreign</quote> displays differ in having +a host name in the display name, may it be <literal>localhost</literal>.</para> + +<para>The <replaceable>display name</replaceable> must be something that can +be passed in the <option>-display</option> option to an X program. This string +is used to generate the display-specific section names, so be careful to match +the names. +The display name of &XDMCP; displays is derived from the display's address by +reverse host name resolution. For configuration purposes, the +<literal>localhost</literal> prefix from locally running &XDMCP; displays is +<emphasis>not</emphasis> stripped to make them distinguishable from local +&X-Server;s started by &kdm;.</para> + +<para>The <replaceable>display class</replaceable> portion is also used in the +display-specific sections. This is useful if you have a large collection of +similar displays (such as a corral of X terminals) and would like to set +options for groups of them. +When using &XDMCP;, the display is required to specify the display class, +so the manual for your particular X terminal should document the display +class string for your device. If it does not, you can run &kdm; in debug +mode and <command>grep</command> the log for <quote>class</quote>.</para> + +<para>The displays specified in <option>ReserveServers</option> will not be +started when &kdm; starts up, but when it is explicitly requested via +the command socket (or <acronym>FiFo</acronym>). +If reserve displays are specified, the &kde; menu will have a +<guilabel>Start New Session</guilabel> item near the bottom; use that to +activate a reserve display with a new login session. The monitor will switch +to the new display, and you will have a minute to login. If there are no more +reserve displays available, the menu item will be disabled.</para> + +<para>When &kdm; starts a session, it sets up authorization data for the +&X-Server;. For local servers, &kdm; passes +<command><option>-auth</option> <filename><replaceable>filename</replaceable></filename></command> +on the &X-Server;'s command line to point it at its authorization data. +For &XDMCP; displays, &kdm; passes the authorization data to the &X-Server; +via the <quote>Accept</quote> &XDMCP; message.</para> + +</sect1> + +<sect1 id="kdmrc-xaccess"> +<title>&XDMCP; access control</title> + +<para>The file specified by the <option>AccessFile</option> option provides +information which &kdm; uses to control access from displays requesting service +via &XDMCP;. +The file contains four types of entries: entries which control the response +to <quote>Direct</quote> and <quote>Broadcast</quote> queries, entries which +control the response to <quote>Indirect</quote> queries, macro definitions for +<quote>Indirect</quote> entries, and entries which control on which network +interfaces &kdm; listens for &XDMCP; queries. +Blank lines are ignored, <literal>#</literal> is treated as a comment +delimiter causing the rest of that line to be ignored, and <literal>\</literal> +causes an immediately following newline to be ignored, allowing indirect host +lists to span multiple lines. +</para> + +<para>The format of the <quote>Direct</quote> entries is simple, either a +host name or a pattern, which is compared against the host name of the display +device. +Patterns are distinguished from host names by the inclusion of one or more +meta characters; <literal>*</literal> matches any sequence of 0 or more +characters, and <literal>?</literal> matches any single character. +If the entry is a host name, all comparisons are done using network addresses, +so any name which converts to the correct network address may be used. Note +that only the first network address returned for a host name is used. +For patterns, only canonical host names are used in the comparison, so ensure +that you do not attempt to match aliases. +Host names from &XDMCP; queries always contain the local domain name +even if the reverse lookup returns a short name, so you can use +patterns for the local domain. +Preceding the entry with a <literal>!</literal> character causes hosts which +match that entry to be excluded. +To only respond to <quote>Direct</quote> queries for a host or pattern, +it can be followed by the optional <literal>NOBROADCAST</literal> keyword. +This can be used to prevent a &kdm; server from appearing on menus based on +<quote>Broadcast</quote> queries.</para> + +<para>An <quote>Indirect</quote> entry also contains a host name or pattern, +but follows it with a list of host names or macros to which the queries +should be forwarded. <quote>Indirect</quote> entries can be excluding as well, +in which case a (valid) dummy host name must be supplied to make the entry +distinguishable from a <quote>Direct</quote> entry. +If compiled with IPv6 support, multicast address groups may also be included +in the list of addresses the queries are forwarded to. +<!-- Not actually implemented! +Multicast addresses may be followed by an optional <literal>/</literal> +character and hop count. If no hop count is specified, the multicast hop count +defaults to 1, keeping the packet on the local network. For IPv4 multicasting, +the hop count is used as the TTL. +--> +If the indirect host list contains the keyword <literal>CHOOSER</literal>, +<quote>Indirect</quote> queries are not forwarded, but instead a host chooser +dialog is displayed by &kdm;. The chooser will send a <quote>Direct</quote> +query to each of the remaining host names in the list and offer a menu of +all the hosts that respond. The host list may contain the keyword +<literal>BROADCAST</literal>, to make the chooser send a +<quote>Broadcast</quote> query as well; note that on some operating systems, +UDP packets cannot be broadcast, so this feature will not work. +</para> + +<para>When checking access for a particular display host, each entry is scanned +in turn and the first matching entry determines the response. +<quote>Direct</quote> and <quote>Broadcast</quote> entries are ignored when +scanning for an <quote>Indirect</quote> entry and vice-versa.</para> + +<para>A macro definition contains a macro name and a list of host names and +other macros that the macro expands to. To distinguish macros from hostnames, +macro names start with a <literal>%</literal> character.</para> + +<para>The last entry type is the <literal>LISTEN</literal> directive. +The formal syntax is +<screen> +<userinput> <literal>LISTEN</literal> [<replaceable>interface</replaceable> [<replaceable>multicast list</replaceable>]]</userinput> +</screen> +If one or more <literal>LISTEN</literal> lines are specified, &kdm; listens +for &XDMCP; requests only on the specified interfaces. +<replaceable>interface</replaceable> may be a hostname or IP address +representing a network interface on this machine, or the wildcard +<literal>*</literal> to represent all available network interfaces. +If multicast group addresses are listed on a <literal>LISTEN</literal> line, +&kdm; joins the multicast groups on the given interface. For IPv6 multicasts, +the IANA has assigned ff0<replaceable>X</replaceable>:0:0:0:0:0:0:12b as the +permanently assigned range of multicast addresses for &XDMCP;. The +<replaceable>X</replaceable> in the prefix may be replaced by any valid scope +identifier, such as 1 for Node-Local, 2 for Link-Local, 5 for Site-Local, and +so on (see IETF RFC 2373 or its replacement for further details and scope +definitions). &kdm; defaults to listening on the Link-Local scope address +ff02:0:0:0:0:0:0:12b to most closely match the IPv4 subnet broadcast behavior. +If no <literal>LISTEN</literal> lines are given, &kdm; listens on all +interfaces and joins the default &XDMCP; IPv6 multicast group (when +compiled with IPv6 support). +To disable listening for &XDMCP; requests altogether, a +<literal>LISTEN</literal> line with no addresses may be specified, but using +the <literal>[Xdmcp]</literal> <option>Enable</option> option is preferred. +</para> + +</sect1> + +<sect1 id="kdm-scripts"> +<title>Supplementary programs</title> + +<para> +The following programs are run by &kdm; at various stages of a session. +They typically are shell scripts. +</para> + +<para> +The Setup, Startup and Reset programs are run as +<systemitem class="username">root</systemitem>, so they should be careful +about security. +Their first argument is <literal>auto</literal> if the session results +from an automatic login; otherwise, no arguments are passed to them. +</para> + +<sect2 id="kdmrc-xsetup"> +<title>Setup program</title> + +<para> +The <filename>Xsetup</filename> program is run after the &X-Server; is +started or reset, but before the greeter is offered. +This is the place to change the root background (if +<option>UseBackground</option> is disabled) or bring up other windows that +should appear on the screen along with the greeter. +</para> + +<para> +In addition to any specified by <option>ExportList</option>, +the following environment variables are passed:</para> +<variablelist> + <varlistentry> + <term>DISPLAY</term> + <listitem><para>the associated display name</para></listitem> + </varlistentry> + <varlistentry> + <term>PATH</term> + <listitem><para>the value of <option>SystemPath</option></para></listitem> + </varlistentry> + <varlistentry> + <term>SHELL</term> + <listitem><para>the value of <option>SystemShell</option></para></listitem> + </varlistentry> + <varlistentry> + <term>XAUTHORITY</term> + <listitem><para>may be set to an authority file</para></listitem> + </varlistentry> + <varlistentry> + <term>DM_CONTROL</term> + <listitem><para>the value of <option>FifoDir</option></para></listitem> + </varlistentry> +</variablelist> + +<para> Note that since &kdm; grabs the keyboard, any other windows will not be +able to receive keyboard input. They will be able to interact with the mouse, +however; beware of potential security holes here. If <option>GrabServer</option> +is set, <filename>Xsetup</filename> will not be able to connect to the display +at all. Resources for this program can be put into the file named by +<option>Resources</option>. +</para> + +</sect2> + +<sect2 id="kdmrc-xstartup"> +<title>Startup program</title> + +<para>The <filename>Xstartup</filename> program is run as +<systemitem class="username">root</systemitem> when the user logs in. +This is the place to put commands which add entries to +<filename>utmp</filename> (the <command>sessreg</command> program +may be useful here), mount users' home directories from file servers, +or abort the session if some requirements are not met (but note that on +modern systems, many of these tasks are already taken care of by +<acronym>PAM</acronym> modules).</para> + +<para>In addition to any specified by <option>ExportList</option>, +the following environment variables are passed:</para> +<variablelist> + <varlistentry> + <term>DISPLAY</term> + <listitem><para>the associated display name</para></listitem> + </varlistentry> + <varlistentry> + <term>HOME</term> + <listitem><para>the initial working directory of the user</para></listitem> + </varlistentry> + <varlistentry> + <term>LOGNAME</term> + <listitem><para>the username</para></listitem> + </varlistentry> + <varlistentry> + <term>USER</term> + <listitem><para>the username</para></listitem> + </varlistentry> + <varlistentry> + <term>PATH</term> + <listitem><para>the value of <option>SystemPath</option></para></listitem> + </varlistentry> + <varlistentry> + <term>SHELL</term> + <listitem><para>the value of <option>SystemShell</option></para></listitem> + </varlistentry> + <varlistentry> + <term>XAUTHORITY</term> + <listitem><para>may be set to an authority file</para></listitem> + </varlistentry> + <varlistentry> + <term>DM_CONTROL</term> + <listitem><para>the value of <option>FifoDir</option></para></listitem> + </varlistentry> +</variablelist> + +<para>&kdm; waits until this program exits before starting the user session. +If the exit value of this program is non-zero, &kdm; discontinues the session +and starts another authentication cycle.</para> + +</sect2> + +<sect2 id="kdmrc-xsession"> +<title>Session program</title> + +<para>The <filename>Xsession</filename> program is the command which is run +as the user's session. It is run with the permissions of the authorized user. +One of the keywords <literal>failsafe</literal>, <literal>default</literal> +or <literal>custom</literal>, or a string to <command>eval</command> by a +Bourne-compatible shell is passed as the first argument.</para> + +<para>In addition to any specified by <option>ExportList</option>, +the following environment variables are passed:</para> +<variablelist> + <varlistentry> + <term>DISPLAY</term> + <listitem><para>the associated display name</para></listitem> + </varlistentry> + <varlistentry> + <term>HOME</term> + <listitem><para>the initial working directory of the user</para></listitem> + </varlistentry> + <varlistentry> + <term>LOGNAME</term> + <listitem><para>the username</para></listitem> + </varlistentry> + <varlistentry> + <term>USER</term> + <listitem><para>the username</para></listitem> + </varlistentry> + <varlistentry> + <term>PATH</term> + <listitem><para>the value of <option>UserPath</option> + (or <option>SystemPath</option> for + <systemitem class="username">root</systemitem> user sessions)</para> + </listitem> + </varlistentry> + <varlistentry> + <term>SHELL</term> + <listitem><para>the user's default shell</para></listitem> + </varlistentry> + <varlistentry> + <term>XAUTHORITY</term> + <listitem><para>may be set to a non-standard authority file</para></listitem> + </varlistentry> + <varlistentry> + <term>KRBTKFILE</term> + <listitem><para>may be set to a Kerberos4 credentials cache name</para> + </listitem> + </varlistentry> + <varlistentry> + <term>KRB5CCNAME</term> + <listitem><para>may be set to a Kerberos5 credentials cache name</para> + </listitem> + </varlistentry> + <varlistentry> + <term>DM_CONTROL</term> + <listitem><para>the value of <option>FifoDir</option></para></listitem> + </varlistentry> + <varlistentry> + <term>XDM_MANAGED</term> + <listitem><para>will contain a comma-separated list of parameters the + session might find interesting, like the location of the command + <acronym>FiFo</acronym> and its capabilities, and which conversation + plugin was used for the login</para> + </listitem> + </varlistentry> + <varlistentry> + <term>DESKTOP_SESSION</term> + <listitem><para>the name of the session the user has chosen to run</para> + </listitem> + </varlistentry> +</variablelist> + +</sect2> + +<sect2 id="kdmrc-xreset"> +<title>Reset program</title> + +<para>Symmetrical with <filename>Xstartup</filename>, the +<filename>Xreset</filename> program is run after the user session has +terminated. Run as <systemitem class="username">root</systemitem>, it should +contain commands that undo the effects of commands in +<filename>Xstartup</filename>, removing entries from <filename>utmp</filename> +or unmounting directories from file servers.</para> + +<para>The environment variables that were passed to +<filename>Xstartup</filename> are also passed to <filename>Xreset</filename>. +</para> + +</sect2> + +</sect1> + +</chapter> diff --git a/doc/kfind/Makefile.am b/doc/kfind/Makefile.am new file mode 100644 index 000000000..da8216ae4 --- /dev/null +++ b/doc/kfind/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/kfind/index.docbook b/doc/kfind/index.docbook new file mode 100644 index 000000000..ecfa5921d --- /dev/null +++ b/doc/kfind/index.docbook @@ -0,0 +1,363 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kfind;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kfind; Handbook</title> + +<authorgroup> +<author>&Dirk.Doerflinger; &Dirk.Doerflinger.mail;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2001</year> +<holder>&Dirk.Doerflinger;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-04-11</date> +<releaseinfo>1.20.01</releaseinfo> + +<abstract> +<para> +&kfind; is &kde;'s file find utility. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdeutils</keyword> +<keyword>kfind</keyword> +<keyword>find</keyword> +<keyword>search</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&kfind; is the &kde; file find utility. +</para> + +<sect1 id="starting"> +<title>Launching &kfind;</title> + +<para> +The Find Files tool is a useful method of searching for specific files on your +computer, or for searching for files that match a pattern. An example of +this could include searching for files of a particular type or with certain +letters in the filename. + +You can load this utility by clicking on <guimenuitem>Find Files</guimenuitem>. This will +launch &kfind;. +</para> + +</sect1> +</chapter> + +<chapter id="kfind"> +<title>Finding Files</title> + +<sect1 id="name-tab"> +<title>The Name/Location Tab</title> + +<para> +When starting &kfind;, you will see a quite simple window. Type in the +name of the file you are searching in the textbox labeled +<guilabel>Named:</guilabel>. Choose a folder where you want to search +by typing it in the field <guilabel>Look in:</guilabel> +or by clicking <guibutton>Browse...</guibutton> and press +<keycap>Enter</keycap> or click <guibutton>Find</guibutton>. If +<guilabel>Include subfolders</guilabel> is checked all +subfolders starting from your chosen folder will be searched +too. The results will be displayed in the box below. +</para> + +<para> +You can use the following wildcards: +</para> + +<variablelist> +<varlistentry> +<term>The Asterisk <quote><keycap>*</keycap></quote></term> +<listitem> +<para> +The asterisk stands for any number of missing characters (even zero), +that means ⪚ searching for <userinput>marc*</userinput> may find the +files <filename>marc</filename>, <filename>marc.png</filename> and +<filename> marc_must_not_read_this.kwd</filename>. +<userinput>mar*.kwd</userinput> may find +<filename>marketplace.kwd</filename> and +<filename>marc_must_not_read_this.kwd</filename>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Question Mark <quote><keycap>?</keycap></quote></term> +<listitem> +<para> +In contrast to the asterisk, the question mark stands for exactly one +character, so <userinput>mar?</userinput> will find +<filename>marc</filename>, but <userinput>marc?</userinput> will not find +anything, as our files are called <filename>marc</filename> and +<filename>marc.png</filename>. You can put as many question marks in the +term as you want, it will find exactly that number of characters. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<para> +Of course you can combine those two wildcard symbols in a search term. +</para> + +</sect1> + +<sect1 id="kfind-date-range"> +<title>The Contents Tab</title> + +<variablelist> +<varlistentry> +<term><guilabel>File type</guilabel></term> +<listitem> +<para> +Here you can specify the type of file you are searching for. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Containing text</guilabel></term> +<listitem> +<para> +Type in the word or phrase the files you are searching for must +contain. Note: If you do this in a large folder or checked +<guilabel>Include subfolders</guilabel> in the +<guilabel>Name/Location</guilabel> tab, this may take a long time. +</para> + +<note> +<para>This option will <emphasis>not</emphasis> work for all files listed +under <guilabel>File type</guilabel>. Only the following file types +are supported: + +<itemizedlist> +<listitem><para>Text files, ⪚ source code and <filename>README</filename> files</para></listitem> +<listitem><para>KWord >= 1.2</para></listitem> +<listitem><para>KPresenter >= 1.2</para></listitem> +<listitem><para>KSpread >= 1.2</para></listitem> +<listitem><para>OpenOffice.org Writer</para></listitem> +<listitem><para>OpenOffice.org Impress</para></listitem> +<listitem><para>OpenOffice.org Calc</para></listitem> +</itemizedlist> + +</para> +</note> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Case sensitive</guilabel></term> +<listitem> +<para> +If you enable this option, &kfind; will +only find files with the exact case matching, ⪚ +<userinput>MARC</userinput> will only match +<quote>MARC</quote>, not <quote>Marc</quote>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Regular expression</guilabel></term> +<listitem><para>If you have installed the &kregexpeditor; tool from +the kdeutils package, you will have this additional option. Enabling +it will allow you to search for a <firstterm>regexp</firstterm> or +regular expression. A regexp is a way to specify conditions for your +search, and they can be very complex, and equally they can be very +powerful. If you are unfamiliar with regular expressions, you can +choose <guilabel>Edit Regular Expression</guilabel> to open +&kregexpeditor;. This tool allows you to construct your set of +conditions graphically, and then generates the expression for +you.</para> + +<para>&kregexpeditor; is a very useful tool, and can be used from within +many &kde; applications other than &kfind;. You can find more +information from within its own help file.</para> +</listitem> +</varlistentry> + +<!-- TODO: "Search metainfo sections" --> + +</variablelist> + +</sect1> + +<sect1 id="kfind-advanced"> +<title>The Properties Tab</title> + +<para> +Here you can refine your search. These are the special refinements +you can choose: +</para> + +<variablelist> + +<varlistentry> +<term><guilabel>Find all files created or modified</guilabel></term> +<listitem> +<para> +Here you can either enter two dates, between which the +files were created or modified, or specify a time period. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>File size is</guilabel></term> +<listitem> +<para>Here you can specify if the file has to be at least or as most as +big as the size you entered in the following box. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Files owned by user, Files owned by group</guilabel></term> +<listitem> +<para>Here you can specify user and group names. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +</chapter> + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kfind; +</para> + +<para> +Program copyright: +</para> + +<itemizedlist> +<title>Developers</title> +<listitem> +<para>Martin Hartig</para> +</listitem> + +<listitem> +<para>Stephan Kulow <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Mario Weilguni <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Alex Zepeda <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Miroslav Flídr <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Harri Porten <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Dima Rogozin <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Carsten Pfeiffer <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Hans Petter Bieker <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Waldo Bastian <email>[email protected]</email></para> +</listitem> + +</itemizedlist> + +<para> +Documentation copyright 2001 &Dirk.Doerflinger; +&Dirk.Doerflinger.mail;</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> +&underBSDLicense; <!-- BSD License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kfind"> +<title>How to obtain &kfind;</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para> +In order to successfully use &kfind;, you need &kde; 3.x. +</para> + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</sect1> + +</appendix> + +&documentation.index; + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +// vim:ts=0:sw=2:tw=78:noet +--> diff --git a/doc/kfind/man-kfind.1.docbook b/doc/kfind/man-kfind.1.docbook new file mode 100644 index 000000000..bab220749 --- /dev/null +++ b/doc/kfind/man-kfind.1.docbook @@ -0,0 +1,79 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<title>KDE User's Manual</title> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<date>June 07, 2005</date> +<productname>K Desktop Environment</productname> +</refentryinfo> + +<refmeta> +<refentrytitle><command>kfind</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>kfind</command></refname> +<refpurpose>file find utility for &kde;</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>kfind</command> +<group choice="opt"><option>searchpath</option></group> +<arg choice="opt">KDE Generic Options</arg> +<arg choice="opt">Qt Generic Options</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para>The Find Files tool is a useful method of searching for specific files +on your computer, or for searching for files that match a pattern. An +example of this could include searching for files of a particular type or +with certain letters in the filename, or that contain a certain piece of +text in their contents.</para> +<para>&kfind; is a graphical tool, and not normally run from the command +line.</para> + +</refsect1> + +<refsect1> +<title>Options</title> +<variablelist> +<varlistentry> +<term><option>searchpath</option></term> +<listitem><para>You may optionally supply a colon separated path to prefill +the dialog. You might use this ability to set up different icons on your +panel or desktop to quickly run searches in different locations.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>App options, in a variablelist</para> + +</refsect1> + +<refsect1> +<title>See Also</title> +<para>More detailed user documentation is available from <ulink +url="help:/kfind">help:/kfind</ulink> +(either enter this <acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kfind</parameter></userinput>).</para> +</refsect1> + +<refsect1> +<title>Authors</title> +<para>The current maintainer of &kfind; is <!-- FIXME: Who? -->. A list of +previous contributors is available in the complete user manual available in +khelpcenter.</para> +<para>This documentation was prepared by &Lauri.Watts; +&Lauri.Watts.mail;</para> +</refsect1> + +</refentry> diff --git a/doc/khelpcenter/Makefile.am b/doc/khelpcenter/Makefile.am new file mode 100644 index 000000000..251280f85 --- /dev/null +++ b/doc/khelpcenter/Makefile.am @@ -0,0 +1,6 @@ + +SUBDIRS = $(AUTODIRS) + +KDE_LANG= en +KDE_DOCS = AUTO + diff --git a/doc/khelpcenter/background.png b/doc/khelpcenter/background.png Binary files differnew file mode 100644 index 000000000..2dda48e23 --- /dev/null +++ b/doc/khelpcenter/background.png diff --git a/doc/khelpcenter/bgtable.png b/doc/khelpcenter/bgtable.png Binary files differnew file mode 100644 index 000000000..b52f2e6f2 --- /dev/null +++ b/doc/khelpcenter/bgtable.png diff --git a/doc/khelpcenter/contact.docbook b/doc/khelpcenter/contact.docbook new file mode 100644 index 000000000..0c6609186 --- /dev/null +++ b/doc/khelpcenter/contact.docbook @@ -0,0 +1,138 @@ +<chapter id="contact-the-kde-team"> +<chapterinfo> +<date>2002-10-29</date> +<releaseinfo>3.5.5</releaseinfo> +</chapterinfo> +<title>Contact the &kde; team</title> +<anchor id="contact"/> + +<sect1 id="contact-mailinglists"> +<title>Mailing lists</title> + +<para> &kde; has several mailing lists up. See below for some of the +most useful. Older articles can be found in the <ulink +url="http://lists.kde.org">mailing list archive</ulink>.</para> + +<variablelist> + +<varlistentry> +<term><ulink url="http://mail.kde.org/mailman/listinfo/kde">kde</ulink></term> +<listitem><para>For general discussion, users helping each other.</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://mail.kde.org/mailman/listinfo/kde-announce">kde-announce</ulink></term> +<listitem><para>Announcements of new &kde; applications</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://mail.kde.org/mailman/listinfo/kde-devel">kde-devel</ulink></term> +<listitem><para>For developers.</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://mail.kde.org/mailman/listinfo/kde-artists">kde-artists</ulink></term> +<listitem><para>Creating icons and other artwork</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://mail.kde.org/mailman/listinfo/kde-doc-english">kde-doc-english</ulink></term> +<listitem><para>For people interested in writing documentation for &kde;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://mail.kde.org/mailman/listinfo/kde-i18n-doc">kde-i18n-doc</ulink></term> +<listitem><para>Internationalization and documentation issues</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://l10n.kde.org/teams/">http://l10n.kde.org/teams/</ulink></term> +<listitem><para>For localized information, which may include user +email lists and websites, check the translation teams page at the +above &URL;.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="contact-developers"> +<title>Contacting the &kde; developers</title> + +<para>On this page, you can find links to &kde; related web sites.</para> + +<para>The K Desktop Environment is developed by a large group of people +around the world. Our main communication channel is the Internet. For +general questions, you will be best served by asking on the mailing +lists mentioned in the <link linkend="contact-mailinglists">previous +section</link>, and contact addresses for individual developers can be +found in the documentation of their individual application.</para> + +<para>Please visit our <ulink +url="http://www.kde.org/contact/representatives.php">Official +Representatives</ulink> page for official enquiries regarding &kde; +(⪚ interviews).</para> + +<para>More information about &kde; is available at &kde-http;.</para> + +<para><anchor id="links" />Other &kde; websites include:</para> + +<variablelist> +<varlistentry> +<term><ulink url="http://www.kde.org">www.kde.org</ulink></term> +<listitem><para>&kde;'s official website</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://developer.kde.org">developer.kde.org</ulink></term> +<listitem><para>The &kde; developers center</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://websvn.kde.org">websvn.kde.org</ulink></term> +<listitem><para>A web interface to the &kde; Subversion repository</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://l10n.kde.org">l10n.kde.org</ulink></term> +<listitem><para>&kde;'s internationalization and documentation server</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="ftp://ftp.kde.org">ftp.kde.org</ulink></term> +<listitem><para>The main &kde; &FTP; server. Please have a look at the link +below to find a mirror site in your geographic region.</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink +url="http://www.kde.org/mirrors">www.kde.org/mirrors</ulink></term> +<listitem><para>&kde; web and &FTP; mirror sites</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://www.kde-apps.org">www.kde-apps.org</ulink></term> +<listitem><para>A directory of &kde; applications.</para></listitem> +</varlistentry> + +<varlistentry> +<term><ulink url="http://www.kde-look.org">www.kde-look.org</ulink></term> +<listitem><para>&kde; themes, icons, and other items to change the +look of your desktop.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> +</chapter> +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:nil +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-always-quote-attributes:t +sgml-parent-document:index.docbook +End: +--> + diff --git a/doc/khelpcenter/help.docbook b/doc/khelpcenter/help.docbook new file mode 100644 index 000000000..98536e1f5 --- /dev/null +++ b/doc/khelpcenter/help.docbook @@ -0,0 +1,740 @@ +<chapter id="help-system-user-manual"> +<chapterinfo> +<date>2002-02-03</date> +<releaseinfo>0.08.00</releaseinfo> +</chapterinfo> +<title>&kde; Help System User Manual</title> +<anchor id="help"/> + +<sect1 id="help-introduction"> +<title>&kde; Help System</title> + +<para>The &kde; help system is designed to make accessing the common +&UNIX; help systems (<application>man</application> and +<application>info</application>) simple, as well as the native &kde; +documentation (&XML;). +</para> + +<para> All base &kde; applications come fully documented, thanks to +the efforts of the Documentation team. If you would like to help, +please write to the Documentation coordinator, Lauri Watts, at +<email>[email protected]</email> for information. No experience is +required, just enthusiasm and patience. +</para> + +<para> +If you would like to help translating &kde; documentation to your native +language, the Translation coordinator is Thomas Diehl, +<email>[email protected]</email>, and he would also welcome the help. More +information, including the coordinators for each language team, can be +found on the <ulink url="http://i18n.kde.org">Internationalization web +site</ulink>, and in the <link linkend="contact">Contact</link> section +of this document. +</para> + +<sect2 id="installation"> +<title>Installation</title> + +<para> +&khelpcenter; is an integral part of the &kde; Base installation, and +is installed with every copy of &kde;. It can be found in the kdebase +package, and is available from the &kde-ftp;, or will be found in your +operating system kdebase package. +</para> + +</sect2> +</sect1> + +<sect1 id="invoking-help"> +<title>Invoking Help</title> + +<para> +&khelpcenter; can be called in several ways: +</para> + +<variablelist> +<varlistentry> +<term>From the <guimenu>Help</guimenu> menu</term> +<listitem> +<para> +The most common will probably be from within an application. Choose +<menuchoice><guimenu>Help</guimenu> +<guimenuitem>Contents</guimenuitem></menuchoice> to open that +application's help file, at the contents page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>From the <guimenu>K</guimenu> menu</term> +<listitem> +<para> +Choose the big <guiicon>K</guiicon> in your panel, and select +<guimenuitem>Help</guimenuitem> to open &khelpcenter;, starting at the +default welcome page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>From the panel</term> +<listitem> +<para> +By default, the &kicker; panel contains an icon to call &khelpcenter;. +Again, the default welcome page is displayed. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>From the command line</term> +<listitem> +<para> +&khelpcenter; may be started using a &URL; to display a +file. &URL;s have been added for +<command>info</command> and <command>man</command> pages +also. You can use them as follows: +</para> + +<variablelist> +<varlistentry> +<term>An application help file</term> +<listitem> +<para> +<command>khelpcenter</command> +<option>help:/<replaceable>kedit</replaceable></option> +</para> +<para> +Opens the &kedit; help file, at the contents page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>A local &URL;</term> +<listitem><para> +<command>khelpcenter</command> +<option>file:/ +<replaceable>usr/local/src/qt/html/index.html</replaceable></option> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>A Man page</term> +<listitem> +<para> +<command>khelpcenter</command> +<option>man:/<replaceable>strcpy</replaceable></option> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>An Info page</term> +<listitem> +<para> +<command>khelpcenter</command> +<option>info:/<replaceable>gcc</replaceable></option> +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +Invoking <command>khelpcenter</command> with no parameters opens the +default welcome page. +</para> +</listitem> +</varlistentry> + +</variablelist> +</sect1> + +<sect1 id="interface-basics"> +<title>The &khelpcenter; interface</title> + +<para> +The &khelpcenter; interface consists of two panes of information. +</para> + +<para> +The toolbar and menus are explained further in <xref + linkend="menu-and-toolbar-ref"/>. +</para> + +<para> +Documents contain their own navigation tools, enabling you to move +either sequentially through a document, using +<guilabel>Next</guilabel>, <guilabel>Previous</guilabel>, and +<guilabel>Home</guilabel> links, or to move around in a less +structured manner, using hyperlinks. +</para> + +<para> +Links can take you to other parts of the same document, or to a +different document, and you can use the <guiicon>Back</guiicon> (Left +pointing arrow) or <guiicon>Forward</guiicon> (Right pointing arrow) +icons on the toolbar to move through the documents you have viewed in +this session. +</para> + +<para> +The two panes display the contents of the help system, and the help +files themselves, on the left and right respectively. +</para> + +<sect2 id="contents-pane"> +<title>The <guilabel>Contents</guilabel> pane</title> + +<para> +The <guilabel>Contents</guilabel> pane in &khelpcenter; is +displayed on the left hand side of the window. As you might expect, you +can move the splitter bar, to make sure you can comfortably read the +contents of either pane. +</para> + +<para> +The <guilabel>Contents</guilabel> pane is further divided into two +tabs, one containing a <link linkend="contents-menu">menu</link> +showing all the help information &khelpcenter; is aware of, and the +other contains the &kde; <link linkend="kde-glossary">glossary</link> +of terms. +</para> + +<sect3 id="contents-menu"> +<title>The <guilabel>Contents</guilabel> Menu</title> + +<para> +The <guilabel>Contents</guilabel> contains the following default +entries: +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Introduction</guilabel></term> +<listitem><para>Welcome to &kde; - an introduction to the K Desktop +Environment.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Introduction to &kde;</guilabel></term> +<listitem> +<para> +The &kde; Quickstart guide. Contains a tour of the &kde; +Interface and specific help and tips on how to work smarter with &kde;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>&kde; User's manual</guilabel></term> +<listitem> +<para> +The &kde; User's manual is an in-depth exploration of &kde;, including +installation, configuration and customization, and use. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Application manuals</guilabel></term> +<listitem> +<para> +Native &kde; application documentation. All &kde; applications have +documentation in &XML; format, which are converted to +<acronym>HTML</acronym> when you view them. This section lists all the +&kde; applications with a brief description and a link to the full +application documentation. +</para> +<para> +The applications are displayed in a tree structure that echoes the default +structure of the <guimenu>K</guimenu> menu, making it easy to find the +application you are looking for. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>&UNIX; manual pages</guilabel></term> +<listitem> +<para> +&UNIX; man pages are the traditional on-line documentation format for +&UNIX; systems. Most programs on your system will have a man page. In +addition, man pages exist for programming functions and file +formats. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Browse info pages</guilabel></term> +<listitem> +<para> +TeXinfo documentation is used by many &GNU; applications, +including <command>gcc</command> (the C/C++ compiler), +<command>emacs</command>, and many others. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Tutorials</guilabel></term> +<listitem> +<para> +Short, task based or informational tutorials. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>The &kde; FAQ</guilabel></term> +<listitem> +<para> +Frequently asked questions about &kde;, and their answers. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>&kde; on the web</guilabel></term> +<listitem> +<para> +Links to &kde; on the web, both the official &kde; website, and other +useful sites. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Contact Information</guilabel></term> +<listitem> +<para> +Information on how to contact &kde; developers, and how to join the +&kde; mailing lists. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Supporting &kde;</guilabel></term> +<listitem> +<para> +How to help, and how to get involved. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect3> +<!-- +<sect3 id="search"> +<title>The <guilabel>Search</guilabel> tab</title> + +<para> +Searching requires you have the <application>ht://Dig</application> +application installed. Information on installing and configuring the +search index is available in the document. Configuration of the search +index is performed in the &kcontrol;, by choosing +<menuchoice><guisubmenu>Help</guisubmenu><guimenuitem>Index</guimenuitem></menuchoice>, +and detailed help is available from this module. +</para> + +<para> +For the purposes of this document, we'll assume you already have this set +up and configured. +</para> + +<para> +Searching the help files is fairly intuitive, enter the word(s) you wish +to search for in the text box, choose your options (if any), and press +<guibutton>Search</guibutton>. The results display in the viewer pane +to the right. +</para> + +<para>The options available are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Method</guilabel></term> +<listitem> +<para> +Choose how to search for multiple words. If you choose +<guilabel>and</guilabel>, results are returned only if all your search +terms are included in the page. <guilabel>or</guilabel> returns results +if <emphasis>any</emphasis> of the search terms are found, and +<guilabel>boolean</guilabel> lets you search using a combination. +</para> +<para> +Boolean syntax lets you use the operators <literal>AND</literal>, +<literal>OR</literal> and <literal>NOT</literal> to create complex +searches. Some examples:</para> +<variablelist> +<varlistentry> +<term><userinput>cat and dog</userinput></term> +<listitem><para>Searches for pages which have both the words +<userinput>cat</userinput> and <userinput>dog</userinput> in them. Pages with +only one or the other will not be returned.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>cat not dog</userinput></term> +<listitem><para>Searches for pages with <userinput>cat</userinput> in them, but +only returns the ones that don't have the word <userinput>dog</userinput> in +them.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput>cat or (dog not nose)</userinput></term> +<listitem><para>Searches for pages which contain <userinput>cat</userinput>, and +for pages which contain <userinput>dog</userinput> but don't contain +<userinput>nose</userinput>. Pages which contain both +<userinput>cat</userinput> and <userinput>nose</userinput> would be returned, +pages containing all three words would not.</para></listitem> +</varlistentry> +</variablelist> +<para>If your searches are not returning the results you expect, check +carefully you haven't excluded the wrong search term with an errand +<literal>NOT</literal> or a stray brace.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Max. results</guilabel></term> +<listitem><para>Determines the maximum number of results returned from your +search.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Format</guilabel></term> +<listitem><para>Decide if you want just a short link to the page +containing your search terms, or do you want a longer +summary.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Sort</guilabel></term> +<listitem><para>Sort the results in order of <guilabel>Score</guilabel> (how +closely your search terms were matched,) alphabetically by +<guilabel>Title</guilabel> or by <guilabel>Date</guilabel>. Selecting the +<guilabel>Reverse order</guilabel> check box, naturally enough, reverses the +sort order of the results.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Update index</guilabel></term> +<listitem><para>Update the search index, to incorporate new documents, +or if you think your database is incomplete or damaged. This may take +some time.</para></listitem> +</varlistentry> +</variablelist> +</sect3> +--> + +</sect2> + +<sect2 id="man-and-info"> +<title>The <application>Man</application> and <application>Info</application> +sections</title> + +<para>Man pages are the standard &UNIX; manual pages, and have been in +use for many years on many operating systems. They are extremely +thorough, and are the very best place to get information about most +&UNIX; commands and applications. When people say +<quote>RTFM</quote>, the Manual they are referring to is very often the +man page.</para> + +<para>The man pages are not perfect. They tend to be in depth, but +also extremely technical, often written by developers, and for +developers. In some cases this makes them somewhat unfriendly, if not +downright impossible for many users to understand. They are, however, +the best source of solid information on most command line +applications, and very often the only source.</para> + +<para>If you've ever wondered what the number is when people write +things like man(1) it means which section of the manual the item is +in. You will see &khelpcenter; uses the numbers to divide the very many +man pages into their own sections, making it easier for you to find +the information you're looking for, if you're just browsing.</para> + +<para>Also available are the Info pages, intended to be a replacement +for the man pages. The maintainer of some applications no longer +update the man pages, so if there is both a man page and an info page +available, the info page is probably the most recent. Most +applications have one or the other though. If the application you are +looking for help on is a &GNU; utility, you will most likely find it +has an info page, not a man page.</para> + +<sect3 id="navigation"> +<title>Navigating inside the <application>Info</application> pages</title> + +<para>Info documents are arranged hierarchically with each page called +a node. All info documents have a <guilabel>Top</guilabel> node, +&ie; the opening page. You can return to the +<guilabel>Top</guilabel> of an info document by pressing +<guilabel>Top</guilabel>.</para> + +<para><guibutton>Prev</guibutton> & <guibutton>Next</guibutton> +are used to move to the previous/next page at the current level of the +hierarchy.</para> + +<para>Clicking on a menu item within a document moves you to a lower +level in the hierarchy. You may move up the hierarchy by pressing +<guibutton>Up</guibutton>.</para> + +<para>Man is treated similarly to info, with the section index being +the Top node and each man page on the level below. Man entries are +one page long.</para> + +</sect3> +</sect2> + +<sect2 id="kde-glossary"> +<title>The &kde; glossary</title> + +<para> +The glossary provides a quick reference point, where you can look up +the definitions of words that may be unfamiliar to you. These range +from &kde; specific applications and technologies, through to general +&UNIX; computing terms. +</para> + +<para> +In the left hand pane you will see a tree view, with two choices: +<guilabel>Alphabetically</guilabel> or <guilabel>By topic</guilabel>. +Both contain the same entries, sorted differently, to allow you to +quickly find the item of interest. +</para> + +<para> +Navigate down the tree views to the left, and items you select will be +displayed on the right. +</para> + +</sect2> + +<sect2 id="menu-and-toolbar-ref"> +<title>The menus and toolbar</title> + +<para> +&khelpcenter; has a very minimal interface, allowing you to concentrate +on getting help rather than learning how to use the help browser. +</para> + +<para> +The icons available to you in the toolbar are as follows: +</para> + +<variablelist> +<title>Toolbar Icons</title> + +<varlistentry> + +<term><guiicon>Back</guiicon></term> +<listitem> +<para>Go to the previous page you viewed.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Forward</guiicon></term> +<listitem> +<para>Go forward one page. This icon is only active if you have +already used the <guiicon>Back</guiicon> icon.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Print</guiicon></term> +<listitem> +<para> +Print the contents of the currently visible page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Find</guiicon></term> +<listitem> +<para> +Find a word or words within the currently visible page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Increase Font</guiicon></term> +<listitem> +<para> +Increase the size of the text in the viewer pane. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guiicon>Decrease Font</guiicon></term> +<listitem> +<para> +Decrease the size of the text in the viewer pane. This icon is only +enabled if you have previously enlarged the text. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<para> +The menus contain the following entries: +</para> + +<variablelist> +<varlistentry> +<term><guimenu>File</guimenu></term> +<listitem> + +<variablelist> +<varlistentry> +<term> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Print the contents of the currently visible page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Close and exit &khelpcenter; +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>Edit</guimenu></term> +<listitem> + +<variablelist> +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Select All</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Select all the text in the current page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut> +<keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Find a word or words in the currently visible page. +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenu>View</guimenu></term> +<listitem> +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>View Document Source</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +View the <acronym>HTML</acronym> source of the page you are currently + viewing. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu> +<guisubmenu>Set Encoding</guisubmenu> +</menuchoice> +</term> +<listitem> +<para> +Change the encoding of the current page. Normally, the default setting +of <guimenuitem>Auto</guimenuitem> should be sufficient, but if you are +having problems viewing pages written in languages other than English, +you may need to choose a specific encoding in this menu. +</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Go</guimenu> +<guimenuitem>Back</guimenuitem></menuchoice></term> +<listitem> +<para>Go back to the previous page you were viewing.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Go</guimenu> +<guimenuitem>Forward</guimenuitem> +</menuchoice></term> +<listitem> +<para>If you have previously moved back with the back icon or menu +entry, you can work your way forward again with this menu +entry.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Go</guimenu> +<guimenuitem>...</guimenuitem> +</menuchoice></term> +<listitem> +<para>At the bottom of the <guimenu>Go</guimenu> menu, you will find a +history list, of the last few pages you have looked at. Selecting one +will take you directly back to that page.</para> +</listitem></varlistentry></variablelist> + +</sect2> + +</sect1> + +<sect1 id="credits"> +<title>Credits and Licenses</title> + +<para>&khelpcenter;</para> + +<para>Originally developed by &Matthias.Elter; &Matthias.Elter.mail;</para> +<para>The current maintainer is &Cornelius.Schumacher; &Cornelius.Schumacher.mail;</para> + +&underFDL; +&underGPL; + +</sect1> +</chapter> + diff --git a/doc/khelpcenter/index.docbook b/doc/khelpcenter/index.docbook new file mode 100644 index 000000000..b6997f7f3 --- /dev/null +++ b/doc/khelpcenter/index.docbook @@ -0,0 +1,82 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"customization/dtd/kdex.dtd" [ + <!ENTITY contact SYSTEM "contact.docbook"> + <!ENTITY help SYSTEM "help.docbook"> + <!ENTITY support SYSTEM "support.docbook"> + <!ENTITY whatiskde SYSTEM "whatiskde.docbook"> + <!ENTITY welcome SYSTEM "welcome.docbook"> + <!ENTITY quickstart SYSTEM "quickstart/index.docbook" NDATA SGML> + <!ENTITY userguide SYSTEM "userguide/index.docbook" NDATA SGML> + <!ENTITY faq SYSTEM "faq/index.docbook" NDATA SGML> + <!ENTITY kpanel SYSTEM "../kpanel/index.html" NDATA SGML> + <!ENTITY kcontrolcenter SYSTEM "../kcontrol/index.html" NDATA SGML> + <!ENTITY kfm SYSTEM "../konqueror/index.html" NDATA SGML> + <!ENTITY kwm SYSTEM "../kwm/index.html" NDATA SGML> + <!ENTITY kde-quickstart-doc SYSTEM "quickstart/index.docbook" NDATA SGML> + <!ENTITY kde-userguide-doc SYSTEM "userguide/index.docbook" NDATA SGML> + <!ENTITY kde-faq-doc SYSTEM "faq/index.docbook" NDATA SGML> + <!-- HTML files will probably only work when they have an olink equivalent +available, unless only references to the top page are needed, which is doubtful. + + To be continued. (FF) --> + <!ENTITY kde-kpanel-doc SYSTEM "../kpanel/index.html" NDATA SGML> + <!ENTITY kde-kcontrol-doc SYSTEM "../kcontrol/index.html" NDATA SGML> + <!ENTITY kde-kfm-doc SYSTEM "../konqueror/index.html" NDATA SGML> + <!ENTITY kde-kwm-doc SYSTEM "../kwm/index.html" NDATA SGML> + <!-- ENTITY man SYSTEM "." NDATA LINESPECIFIC > - to be changed ; should be +the reference to the apropos file in this case, but I cannot really imagine +putting all manual pages into FPIs or system identifiers, so we'll have to find +a way round it. (FF) --> + <!ENTITY kappname "&khelpcenter;"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &khelpcenter;</title> +<authorgroup> +<corpauthor>The &kde; Team</corpauthor> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +<date>2002-01-18</date> +<releaseinfo>3.00.00</releaseinfo> + +<abstract> +<para>&kde; is a powerful graphical desktop environment for &UNIX; +workstations. A &kde; desktop combines ease of use, contemporary +functionality and outstanding graphical design with the technological +superiority of the &UNIX; operating system.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdebase</keyword> +<keyword>khelpcenter</keyword> +<keyword>kdehelp</keyword> +<keyword>help</keyword> +<keyword>help center</keyword> +<keyword>KDE help center</keyword> +</keywordset> +</bookinfo> + +&welcome; +&help; +&whatiskde; +&contact; +&support; + +</book> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:t +sgml-shorttag:nil +sgml-namecase-general:t +sgml-general-insert-case:lower +sgml-always-quote-attributes:t +End: +--> + diff --git a/doc/khelpcenter/kdelogo2.png b/doc/khelpcenter/kdelogo2.png Binary files differnew file mode 100644 index 000000000..aa0ff56e8 --- /dev/null +++ b/doc/khelpcenter/kdelogo2.png diff --git a/doc/khelpcenter/khelpcenter.png b/doc/khelpcenter/khelpcenter.png Binary files differnew file mode 100644 index 000000000..e30c35825 --- /dev/null +++ b/doc/khelpcenter/khelpcenter.png diff --git a/doc/khelpcenter/konq.css b/doc/khelpcenter/konq.css new file mode 100644 index 000000000..ee75f658f --- /dev/null +++ b/doc/khelpcenter/konq.css @@ -0,0 +1,68 @@ +body {background-color: #3679AD; + color: #000000; + margin-left: 0; + margin-right: 0; + margin-top: 5; + padding: 0; + background-image: url(background.png); + background-repeat: no-repeat; + background-position: top-center;} + +.caption { + color: black; + font-family: sans-serif; + font-size: 23pt; + font-style: italic; + font-weight: bolder; + margin-left: 3pt; +} + +td.trans {background-image: url(bgtable.png); + background-repeat: no-repeat;} +td.end {background-image: url(lines2.png); + background-repeat: x-repeat;} +td.shadow1 {background-image: url(shadow1.png); + background-repeat: x-repeat;} + +table.vnice { font-family: sans-serif; + font-size: x-small;} + +a:link {background-color: transparent; + color: #191970; + text-decoration:none;} +a:visited {background-color: transparent; + color: #551a8a; + text-decoration:none;} +a:active {background-color: transparent; + color: #fe0000; + text-decoration:none;} +a:hover {background-color: transparent; + color: #1919aa; + text-decoration:underline;} + +tr.menurow {background-color: #505050; + color: #000000; + vertical-align: middle;} + +td.deco {color: #ffffff; + background-color: #505050; + font-family: sans-serif; + font-size: small;} + +td.menuactive {color: #ffcc00; + background-color: #777777; + font-family: sans-serif; + font-size: small;} + +td.menu {color: #ffffff; + background-color: #505050; + font-family: sans-serif; + font-size: small;} + +a.menu {color: #eeeeee; + font-family: sans-serif; + font-size: small;} + +a.menu:hover {color: #ffffff; + text-decoration:none;} + diff --git a/doc/khelpcenter/lines.png b/doc/khelpcenter/lines.png Binary files differnew file mode 100644 index 000000000..498330c38 --- /dev/null +++ b/doc/khelpcenter/lines.png diff --git a/doc/khelpcenter/lines2.png b/doc/khelpcenter/lines2.png Binary files differnew file mode 100644 index 000000000..02a8c05b5 --- /dev/null +++ b/doc/khelpcenter/lines2.png diff --git a/doc/khelpcenter/pointers.png b/doc/khelpcenter/pointers.png Binary files differnew file mode 100644 index 000000000..17bfb2eb8 --- /dev/null +++ b/doc/khelpcenter/pointers.png diff --git a/doc/khelpcenter/shadow1.png b/doc/khelpcenter/shadow1.png Binary files differnew file mode 100644 index 000000000..b57787697 --- /dev/null +++ b/doc/khelpcenter/shadow1.png diff --git a/doc/khelpcenter/support.docbook b/doc/khelpcenter/support.docbook new file mode 100644 index 000000000..9099aa392 --- /dev/null +++ b/doc/khelpcenter/support.docbook @@ -0,0 +1,102 @@ +<chapter id="supporting-kde"> +<chapterinfo> +<date>2002-03-04</date> +<releaseinfo>2.02.00</releaseinfo> +</chapterinfo> +<title>Supporting &kde;</title> +<anchor id="support"/> + +<sect1 id="supporting-kde-introduction"> +<title>Supporting &kde;</title> + +<para> If you are new to &kde;, the &kde; project might look like big +machinery to you. Undoubtedly, &kde; is no longer a small project, +nevertheless it is very important to realize that it is easy to +<quote>make a difference</quote> in the &kde; world. </para> + +<para> There is always a need for dedicated developers, graphic +artists, sound engineers, translators and documentation +writers. Consider jumping aboard this exciting international project +and make yourself a name in the software world.</para> + +<para> Along the way you will make countless friends and acquaintances +all over the world. Also, the satisfaction that stems from doing +actual hands-on work, that will benefit an uncountable number of users +world-wide, and from seeing an unparalleled project grow, is hard to +beat. Please consider joining and supporting &kde; and hop aboard this +exciting journey towards a free and open alternative computing +platform. </para> + +</sect1> + +<sect1 id="supporting-kde-get-started"> +<title>How to get started</title> + +<itemizedlist> + +<listitem><para> +Subscribe to the <link linkend="contact">&kde; mailing lists</link> +that interest you. +</para></listitem> + +<listitem><para> +Read the <ulink url="http://lists.kde.org">mailing list</ulink> archives in +order to get a feel for &kde; development. +</para></listitem> + +<listitem><para> +Learn how to program using the &kde; application framework and join the +friendly &kde; developers' community. +</para></listitem> + +</itemizedlist> + +</sect1> + +<sect1 id="supporting-kde-financial-support"> +<title>Supporting financially</title> + +<para> The &kde; team is working very hard on providing you with the +best desktop available for the &UNIX; operating system. &kde; is +available for free and will always be available for free, including +each and every line of its source code, for everyone to modify and +distribute. If you enjoy and use &kde; please consider supporting the +&kde; Project financially. &kde; is in constant need of funds in +order to finance its operations. </para> + +<para> If your busy schedule or skills do not permit you to be +actively involved in &kde; development, please consider supporting +&kde; financially by sending a donation to: </para> + +<para> You can send regular US checks to the following address: </para> + +<literallayout> +K Desktop Environment e.V. +Mirko Boehm +2029 Chadds Ford Drive +Reston, VA 20191 +USA +</literallayout> + +<para> Use "KDE e.V. - Mirko Boehm" in the "Pay to the order of..." line. +</para> + +<para> +From Europe, you may remit your donation to (be aware of a fee if wiring from outside of Germany): +</para> + +<literallayout> +K Desktop Environment e.V. +Account-Nr. 0 66 64 46 +BLZ 200 700 24 +Deutsche Bank 24 +</literallayout> + +<para> Please contact Mirko Boehm +<email>[email protected]</email> if you have any questions. </para> + +<para> Your contribution is very much appreciated. Thank you! </para> + +</sect1> +</chapter> + diff --git a/doc/khelpcenter/welcome.docbook b/doc/khelpcenter/welcome.docbook new file mode 100644 index 000000000..6f1859311 --- /dev/null +++ b/doc/khelpcenter/welcome.docbook @@ -0,0 +1,60 @@ +<chapter id="welcome-to-kde"> +<chapterinfo> +<date>2002-01-18</date> +<releaseinfo>3.00.00</releaseinfo> +</chapterinfo> +<title>Welcome to &kde;</title> +<anchor id="welcome"/> + +<para> <emphasis>The &kde; team welcomes you to user-friendly &UNIX; +computing.</emphasis> </para> + +<sect1 id="welcome-page"> +<title>Welcome to the K Desktop Environment</title> + +<sect2 id="welcome-information-about-kde"> +<title>Information about &kde;</title> + +<para>&kde; is a powerful graphical desktop environment for &UNIX; +workstations. A &kde; desktop combines ease of use, contemporary +functionality and outstanding graphical design with the technological +superiority of the &UNIX; operating system. </para> + +<para><link linkend="what-is-kde">What is the K Desktop Environment?</link></para> + +<para><link linkend="contact">Contacting the &kde; Project</link></para> + +<para><link linkend="support">Supporting the &kde; Project</link></para> + +<para><link linkend="links">Useful links</link></para> + +</sect2> + +<sect2 id="welcome-getting-the-most-out-of-kde"> +<title>Getting the most out of &kde;</title> + +<sect3 id="welcome-general-documentation"> +<title>General documentation</title> + +<para><ulink url="help:/khelpcenter/quickstart">A Quick Start Guide to the Desktop</ulink></para> + +<para><ulink url="help:/khelpcenter/userguide">&kde; User's guide</ulink></para> + +<para><ulink url="help:/khelpcenter/faq">Frequently asked questions</ulink></para> + +</sect3> + +<sect3 id="welcome-basic-applications"> +<title>Basic applications</title> + +<para><ulink url="help:/kicker">Desktop Panel</ulink></para> + +<para><ulink url="help:/kcontrol">Control Center</ulink></para> + +<para><ulink url="help:/konqueror">File Manager</ulink></para> + +</sect3> +</sect2> +</sect1> +</chapter> + diff --git a/doc/khelpcenter/whatiskde.docbook b/doc/khelpcenter/whatiskde.docbook new file mode 100644 index 000000000..d63213eee --- /dev/null +++ b/doc/khelpcenter/whatiskde.docbook @@ -0,0 +1,129 @@ +<chapter id="what-is-kde"> +<chapterinfo> +<date>2002-01-18</date> +<releaseinfo>3.00.00</releaseinfo> +</chapterinfo> +<title>What is &kde;?</title> +<anchor id="whatiskde"/> + +<sect1 id="what-is-kde-introduction"> +<title>What is &kde;?</title> + +<para>&kde; is a desktop environment. In other words, &kde; is a +collection of programs, technologies and documentation that attempt to +make life easier for computer users. &kde; is targeted at &UNIX; +workstations. It features network transparency and a contemporary work +philosophy. </para> + +<para>The creators of the K Desktop Environment are a world-wide group of +software engineers. This group's major goal in free software development is to +provide high quality software that empowers the user with easy control of his +computer's resources.</para> + +<para>&kde; seeks to fill the need for an easy to use desktop for +&UNIX; workstations, similar to the desktop environments found under +&MacOS; or &Windows; 95/NT. &kde; meets the requirement +of users for an easy to use work environment. Tools used to reach +this end are: enhanced inter-application communication, component +reuse, generalized drag and drop, uniform look and feel and many +more. Thus, &kde; offers much more than the traditional &UNIX; window +managers.</para> + +<para>Stability, scaleability and openness are qualities which have +made &UNIX; the undisputed choice for the information technology +professional for many years. &kde; builds on top of this excellent +base framework and brings new, much needed qualities: usability, user +friendliness and beauty! &kde; was the first, and stays the forefront +player in bringing these qualities to &UNIX;, which constituted for +years, the premier platform for server computers and scientific +institutions, but wasn't very attractive for desktop users.</para> + +<para>Without &UNIX; the Internet would not exist, or at least would +have a vastly different form. &UNIX; has not, until now, addressed the +needs of the average computer user. This fact is particularly +unfortunate, since a number of implementations of &UNIX; (<ulink +url="http://www.linux.org">&Linux;</ulink>, <ulink +url="http://www.freebsd.org">FreeBSD</ulink>, <ulink +url="http://www.netbsd.org">NetBSD</ulink>, &etc;) are freely +available on the Internet, all of which are of exceptional quality and +stability. </para> + +</sect1> + +<sect1 id="what-is-kde-the-desktop"> +<title>&kde; The Desktop Environment</title> + +<para>In combination with a free implementation of &UNIX;, &kde; +provides to the world an open and completely free desktop computing +platform either at home or at work.</para> + +<para> This platform is available to anyone free of charge including +its source code for anyone to modify.</para> + +<para>While there will always be room for improvement we believe we +have now delivered a viable alternative to some of the more commonly +found and commercial operating systems/desktops combinations available +today. It is our hope that the combination of &UNIX; and &kde; will +finally bring the same open, reliable, stable, and monopoly free +computing to the average computer user that scientists and computing +professionals world-wide have enjoyed for years. </para> + +</sect1> + +<sect1 id="what-is-kde-the-development-framework"> +<title>&kde; The Application Development Framework</title> + +<para>&kde; focuses on the user's needs, but it's obvious that this +focus is more easily achieved by also giving developers the best +tools. &kde; code contains, and comes with, some of the best +development technologies of the modern computing age.</para> + +<para>Authoring applications under &UNIX;/X11 used to be an extremely +tedious and labor intensive process. &kde; recognizes the fact that a +computing platform is only as good as the number of first class +applications available to the users of that particular +platform.</para> + +<para>&kde; defines new technologies in &DCOP; and KParts, created to +offer a component document model and technology. Together with the +complete &kde; libraries programming interface, &DCOP;/KParts are set +in direct competition with other similar technologies like &Microsoft; +<abbrev>MFC</abbrev>/<abbrev>COM</abbrev>/ActiveX technologies. The +excellent quality and the high level of refinement of &kde;'s +application programming interface (<acronym>API</acronym>) enables +developers to focus on original and interesting issues and avoid +reinventing the wheel.</para> + +</sect1> + +<sect1 id="what-is-kde-the-office-suite"> +<title>&kde; The Office Application Suite</title> + +<para>In its current form, &kde; provides, apart from the essential desktop +component applications, a suite of powerful office programs known to the +world by the name &koffice;.</para> + +<para>&koffice; is based on the &kde; &DCOP;/KParts +technologies. It currently contains: a word processor with desktop +publishing capabilities (&kword;), a spreadsheet application (&kspread;) +and accompanying charting program (&kchart;), a presentation program +(&kpresenter;) and a vector drawing program (&kontour;). Tying things +together is the <application>KOffice Workspace</application>, an +integrated shell to ease the use of the &koffice; components in +conjunction with each other. Additional components include an email +client, a news reader, and a powerful <abbrev>PIM</abbrev> (Personal +Information Manager - an organizer).</para> + +<para>While some of those components are still in alpha development, +others are already extremely powerful. For example, &kpresenter;, +&kde;'s presentation application, was successfully used at the 5th +International &Linux; Congress in Cologne, Germany to deliver a &kde; +presentation. </para> + +<para>We would like to invite you to <ulink +url="http://www.kde.org">learn more about &kde;</ulink> and <ulink +url="http://koffice.kde.org">&koffice;</ulink>.</para> + +</sect1> +</chapter> + diff --git a/doc/kicker/Makefile.am b/doc/kicker/Makefile.am new file mode 100644 index 000000000..3f20a1e1b --- /dev/null +++ b/doc/kicker/Makefile.am @@ -0,0 +1,5 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + +KDE_MANS = AUTO diff --git a/doc/kicker/bookmarks_icon.png b/doc/kicker/bookmarks_icon.png Binary files differnew file mode 100644 index 000000000..aa335b286 --- /dev/null +++ b/doc/kicker/bookmarks_icon.png diff --git a/doc/kicker/desktop_icon.png b/doc/kicker/desktop_icon.png Binary files differnew file mode 100644 index 000000000..5055c7df8 --- /dev/null +++ b/doc/kicker/desktop_icon.png diff --git a/doc/kicker/index.docbook b/doc/kicker/index.docbook new file mode 100644 index 000000000..bc7333c72 --- /dev/null +++ b/doc/kicker/index.docbook @@ -0,0 +1,2434 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY package "kdebase"> + <!ENTITY kappname "&kicker;"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<!-- The language must NOT be changed here. --> + +<book lang="&language;"> + +<bookinfo> +<title>The &kicker; Handbook</title> + +<authorgroup> +<author>&Orville.Bennett; &Orville.Bennett.mail;</author> +<author>&Dirk.Doerflinger; &Dirk.Doerflinger.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2001</year><year>2002</year> +<holder>&Dirk.Doerflinger;</holder> +</copyright> +<copyright> +<year>2004</year> +<holder>&Orville.Bennett;</holder> +</copyright> +<copyright> +<year>2005</year> +<holder>Titus Laska</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2006-06-15</date> +<releaseinfo>3.5.2</releaseinfo> + +<abstract> +<para> +&kicker; is the &kde; application starter panel and is also capable of +some useful applets and extensions. It usually resides on the bottom of +the desktop. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Kicker</keyword> +<keyword>kdebase</keyword> +<keyword>panel</keyword> +<keyword>application</keyword> +<keyword>starter</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + + +<para> +&kicker; is the application launcher panel of the K Desktop Environment. +Besides the <guimenu>K</guimenu> Menu, where you can start applications, +&kicker; is also capable of running docked applets like the pager, the +taskbar or the clock, and extensions, such as child panels. +</para> + +<para> +&kicker; usually resides on the bottom of the desktop, but it can also +be moved to any other border. Please report any problems or feature +requests to the &kde; mailing lists. +</para> + +</chapter> + +<chapter id="using-kicker"> +<title>Using &kicker;</title> + +<para> +This is what you see on a freshly installed &kde;, assuming that you +skipped <application>KPersonalizer</application>. If you are using +lower resolution, some of the icons may not appear immediately. To +cater for those smaller resolutions, the screenshot below is divided +in two parts. +</para> + +<screenshot> +<screeninfo>Here is a screenshot of the left side of &kicker;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot_left.png" format="PNG"/></imageobject> +<textobject> +<phrase>Screenshot Left</phrase> +</textobject> +<caption> +<para> +This is a screenshot of the left side of &kicker; +</para> +</caption> +</mediaobject> +</screenshot> + +<screenshot> +<screeninfo>And here is the right side</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot_right.png" format="PNG"/></imageobject> +<textobject> +<phrase>Screenshot Right</phrase> +</textobject> +<caption> +<para> +This is the right side of &kicker; +</para> +</caption> +</mediaobject> +</screenshot> + +<para> +Of course, this is only one way &kicker; might appear on the +screen. There are many more configurations available. +</para> + +<sect1 id="newbie"> +<title>A quick tour for new &kde; users</title> + +<para> +If you are experienced with this kind of application launcher, you can +ignore this chapter and move on to <link linkend="basics">&kicker; +basics</link>. +</para> + +<para> +The main use of &kicker; is starting applications. This is +done by clicking icons, either from the panel or from the +<guimenu>K</guimenu> Menu. &kicker; shows some more things too, so let's +see. +</para> + +<para> +Having a look at the screenshots above, there are from left to right: +</para> + +<variablelist> + +<varlistentry> +<term>The <guimenu>K</guimenu> Menu</term> +<listitem> +<para> +It is used for launching applications and some other useful +things. Refer to <link linkend="k-menu">The <guimenu>K</guimenu> Menu +</link>for more information. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Application start icons</term> +<listitem> +<para> +Here are some icons of commonly used applications. They can be moved and +removed and others can be added. Some of them have a special meaning, +which you can read more about in <link linkend="basics">&kicker; +basics</link>. Resting the mouse over an icon without clicking shows the +name and a short description of that application, if you have set that in +the <link linkend="configuring">Settings Dialog</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Pager applet</term> +<listitem> +<para> +This displays a small view of the virtual desktops. Clicking one section +of it will activate that desktop. Please refer to <link +linkend="applets">Applets</link>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The Taskbar</term> +<listitem> +<para> +All running applications are displayed as buttons in the +taskbar. Clicking an application's button will bring this application on +top. If it was on top before, it will be iconified. More +information is available in the <link linkend="applets">Applets</link> +section. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>System Tray</term> +<listitem> +<para> +The system tray is able to swallow some kind of applications like - in +this case - &klipper; and the &korganizer; Reminder Daemon. There are +many other applications that dock in the system tray, for example &juk; +and &kopete;. Clicking the icons with the +<mousebutton>left</mousebutton> or the <mousebutton>right</mousebutton> +mousebutton performs specific actions defined for each +application. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Clock</term> +<listitem> +<para> +The Clock applet is - of course - a small, useful clock. It can have +various styles, have a look at the <link +linkend="applets">applets</link> section for more information. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guibutton>Hide panel</guibutton> button</term> +<listitem> +<para> +This button lets you fade out &kicker; for having more space on the +screen. When &kicker; is faded out, only the <guibutton>Hide panel</guibutton> button +will remain in order to fade in &kicker; again. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +This was only the description of &kicker; on its initial launch. It can +be configured in many ways and styles and more applets can be +added. There are even some extensions like the external taskbar you can +add. See <link linkend="basics">&kicker; basics</link>, <link +linkend="applets">Applets </link> and <link +linkend="extensions">Extensions </link>for more information. +</para> + +</sect1> + +</chapter> + +<chapter id="basics"> + +<title>&kicker; basics</title> + +<sect1 id="general-usage"> +<title>General usage</title> + +<para> +As mentioned before, there are a lot of things that can be added to +&kicker;. This section will tell you everything about application +starting, folder browsing and adding some kinds of applets and +extensions. Lots of things can be done from the context +menu with <guimenuitem>Configure Panel...</guimenuitem> or via the &kcontrolcenter;'s section <menuchoice><guimenu>Desktop</guimenu> <guisubmenu>Panels</guisubmenu></menuchoice>. +</para> + +<sect2 id="adding-apps"> +<title>Adding applications</title> + +<para> +There are three different ways to add an application to &kicker;: +</para> + +<variablelist> +<varlistentry> +<term>Drag and Drop</term> +<listitem> +<para> +Simply drag any file from &konqueror; into &kicker; and it's there. Dragging +also works from the <guimenu>K</guimenu> Menu with any entry. You can +change the attributes like optional command line parameters or the icon +by clicking it with the &RMB; and choosing <guimenuitem>Configure +<replaceable>applicationname</replaceable> Button...</guimenuitem> from the +context menu. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Using the context menu to add a &kde; application</term> +<listitem> +<para> +Click the &RMB; on any free space +in &kicker; and choose <guisubmenu>Add Application to Panel</guisubmenu>. +There you can choose an application +which will then be added to &kicker;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Using the context menu to add a +non-&kde;-application</term> +<listitem> +<para> +Non-&kde;-applications ⪚ +<application>xosview</application> or <application>xemacs</application>. +</para> + +<para> +Click the &RMB; on any free space +in &kicker; and choose <guisubmenu>Add Application to +Panel</guisubmenu> and then <guimenuitem>Add Non-KDE +Application</guimenuitem>. In the newly appearing window, enter <guilabel>Button title</guilabel> +and a <guilabel>Description</guilabel> of the application in the first two text boxes. Then fill +in the command of the application you +wish to add in the <guilabel>Executable:</guilabel> text box. You can +also append command line arguments, have +the application start from a terminal, and choose the icon which will +appear in &kicker; by clicking the <guiicon>gear</guiicon>. If you don't +choose an icon, the application will use the gear as a default. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +Applications can be moved or removed by &RMB; click and choosing +<guimenuitem>Move <replaceable>application name</replaceable> Button</guimenuitem> or +<guimenuitem>Remove <replaceable>application name</replaceable> Button</guimenuitem>. +You can also move icons using the &MMB; if you have one. To do this click on an icon using the &MMB;, hold for a second and then drag the icon to its new position. +Another way to remove an application is by clicking the &RMB; on any free space +and then choosing <menuchoice><guimenu>Remove from Panel</guimenu> +<guisubmenu>Application</guisubmenu></menuchoice> and then the application you want to be +removed. +</para> + +<!-- NOTE: Lauri: I'd say it would confuse users if I'd mention Non-KDE-Apps --> +<!-- explicitly here. Please add them if you think there's a need. --> + +</sect2> + +<sect2 id="adding-folders"> +<title>Adding Folders</title> + +<para> +Folders can be added by simply dragging a folder to any free space of +&kicker;. Quick Browsers can also be added from the context +menu or the <guimenu>K</guimenu> Menu. +</para> + +<para> +There are two different ways to have a folder in &kicker;, you can +choose between them in the menu appearing after dropping. +</para> + +<variablelist> +<varlistentry> +<term><guimenuitem>Add as File Manager &URL;</guimenuitem></term> +<listitem> +<para>Choosing this will add a link to the selected folder. Clicking +this <guiicon>folder</guiicon> icon will open &konqueror; displaying the +contents of this folder. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Add as Quick Browser</guimenuitem></term> +<listitem> +<para>If you add a folder this way, it will be displayed as a submenu of +&kicker;. This submenu contains <guimenuitem>Open in File +Manager</guimenuitem>, which does the same as a file manager &URL;, and +<guimenuitem>Open in Terminal</guimenuitem>, which opens a terminal with +this folder as the working path. Also, this submenu contains the contents of +that folder. Sub-folders are displayed as new submenus like the Quick +Browser itself. The maximum number of displayed elements can be set in +the <link linkend="configuring">Settings Dialog</link>. +Quick Browsers can also be added from the context menu of +&kicker; and then choosing <guimenuitem>Add Applet to Panel...</guimenuitem> and +then <guilabel>Special Buttons</guilabel> on the right top of the +<guilabel>Add Applet</guilabel> dialog. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<para> +Both kinds of folders can be moved or removed by &RMB; click and +choosing <guimenuitem>Move <replaceable>application name</replaceable> Button</guimenuitem> or +<guimenuitem>Remove <replaceable>application name</replaceable> Button</guimenuitem>. +You can also move icons using the &MMB; if you have one. To do this click on an icon using the &MMB;, hold for a second and then drag the icon to its new position. +Another way to remove a folder is by clicking the &RMB; on any free space +and then choosing <menuchoice><guimenu>Remove from Panel</guimenu> +<guisubmenu>Applet</guisubmenu></menuchoice> and then the applet you want to be +removed. +</para> + +<para> +File manager &URL;s can also be configured from the +context menu, just like any other folder anywhere in +&kde;. +</para> + +</sect2> + +<sect2 id="adding-special-icons"> +<title>Special Icons</title> + +<para> +Some icons in &kicker; have a special meaning. They are added by +choosing <guimenuitem>Add Applet to Panel...</guimenuitem> and +then <guilabel>Special Buttons</guilabel> on the right top of the +<guilabel>Add Applet</guilabel> dialog. +</para> + +<variablelist> +<varlistentry> +<term>The <guilabel>K Menu</guilabel> Icon</term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="k_menu_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon> The +<guiicon>K Menu icon</guiicon> is one of the most necessary icons in +&kicker;. As you might guess, it opens the <guimenu>K</guimenu> Menu, +which you can learn more about in <link linkend="k-menu">The K +Menu</link>. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The <guilabel>Window List Menu</guilabel></term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="windowlist_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon> Clicking this +<guiicon>icon</guiicon> will show the <guimenu>Window +list</guimenu>. Its first entry, <guimenuitem>Unclutter +Windows</guimenuitem>, tries to move the windows on your active desktop +in a way to see as many as possible. +</para> + +<para> +<guimenuitem>Cascade Windows</guimenuitem> puts all windows on the +active desktop over each others, the most recently on top and the others +sorted by the time they where last used.</para> <para>Below those +entries is a list of all currently running applications, grouped by the +desktops on which they are running. Clicking on an application will activate it. +</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Bookmarks Menu</guilabel></term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="bookmarks_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon> The +<guiicon>Bookmarks</guiicon> icon provides fast access to your +bookmarks. They appear in the same way as if you click the +<guimenu>Bookmarks</guimenu> menu in &konqueror;. Clicking a bookmark in +the menu will launch &konqueror; with the &URL; which +is behind that bookmark. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Recent Documents</guilabel> Icon</term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="recent_docs_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon> +This menu shows the most recently used documents. Clicking the element +<guimenuitem>Clear History</guimenuitem> will remove those entries, +which may be useful for privacy reasons. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Show Access</guilabel> Icon</term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="desktop_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon> The +<guiicon>Show desktop</guiicon> icon lets you have quick access to all +the things you have on your desktop by minimizing all currently open +applications. Clicking it once will toggle it to show the desktop. The +icon will remain pressed until you either click it +again, which will restore your minimized apps, or reactivate an +application from the taskbar. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Quick File Browser</guilabel> Item</term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="quickbrowser_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon>Adding a +<guiicon>Browse</guiicon> icon will open a dialog which will +let you choose a path and an icon, which will appear as a +<guimenu>Quick File Browser</guimenu> menu. Refer to the <link +linkend="adding-folders">Adding Folders</link> section for more information +about quick browsers. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Non-&kde; Application Launcher</guilabel></term> +<listitem> +<para> +<!-- <guiicon><inlinemediaobject><imageobject><imagedata --> +<!-- fileref="nonkdeapp_icon.png" format="PNG"/></imageobject> --> +<!-- </inlinemediaobject></guiicon> --> +The <guilabel>Non-&kde; Application Launcher</guilabel> lets you add an +application which doesn't appear in the <guimenu>K</guimenu> menu to &kicker;. +Refer to <link linkend="adding-apps">Adding Applications</link> for more +information about Non-&kde; Applications. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term>The <guilabel>Terminal Sessions</guilabel> Icon</term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="terminals_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon> This icon +provides a menu of the available Terminal sessions, just as &konsole; does +when you click and hold its <guiicon>New Session</guiicon> button. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Print System</guilabel> Icon</term> +<listitem> +<para> +<guiicon><inlinemediaobject><imageobject><imagedata +fileref="printsys_icon.png" +format="PNG"/></imageobject></inlinemediaobject></guiicon>This icon gives +direct access to &kde;'s printing system. &kde; is able to utilize various printing +systems according to users' wishes. The options shown below will vary depending +on the printing system in use. Clicking the &LMB; on the icon opens +a menu which gives the following options: + +<itemizedlist> +<listitem><para> +<guimenuitem>Add Printer...</guimenuitem> This will start &kde;'s Add Printer +Wizard which allows you to simply add a new printer to your system.</para> +</listitem> +<listitem><para> +<guimenuitem>&kde; Print Settings</guimenuitem> This item will open the &kde; Print +Configuration dialog.</para> +</listitem> + +<listitem> +<para><guimenuitem>Configure Server</guimenuitem> This item allows configuration +of a &CUPS; Server. An authorization dialog, requiring validation, will be presented +to you before allowing any changes. +</para> +</listitem> + +<listitem><para> +<guimenuitem>Print Manager</guimenuitem> This item starts the Printing Manager, +&kde;'s main printing control center.</para> +</listitem> + +<listitem><para> +<guimenuitem>Print Browser (&konqueror;)</guimenuitem> This item will +start &konqueror; with the <literal>print:/</literal> io-slave to +browse all kinds of printers.</para> +</listitem> + +<listitem><para> +<guimenuitem>Print File...</guimenuitem> This item opens a dialog which lets +you easily print one or more files.</para> +</listitem> + +<listitem><para> +The next items with the names of all your printers open the KJobviewer window for each printer.</para> +</listitem> + +</itemizedlist> + +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="removing-icons"> +<title>Removing all kinds of icons</title> + +<para> +Clicking the &RMB; on any icon, whether it's an application, +folder or special icon and then choosing +<guimenuitem>Remove <replaceable>name</replaceable></guimenuitem> from the appearing context +menu will remove the icon from &kicker;. +</para> +<para> +Another way of removing icons is clicking the &RMB; on any free space in +&kicker; and choosing <guimenuitem>Remove From Panel</guimenuitem> and then +<guimenuitem>Applet</guimenuitem>, <guimenuitem>Application</guimenuitem> or <guimenuitem>All</guimenuitem>. You can then choose the button you want to remove in +the submenu.</para> + +<note> +<para> +Please note that removing an icon from &kicker; won't remove the +application on the disk! +</para> +</note> + +</sect2> + +<sect2 id="adding-applets"> +<title>Adding Applets</title> + +<para> +&kicker; comes with a set of applets like the taskbar or the +mini-pager. They can be added by choosing <guisubmenu>Add +Applet to Panel...</guisubmenu> from the context menu, +which can be opened by +clicking the &RMB; on any free space in &kicker;. In the upcoming +dialog, choose an applet to add and click the <guibutton>Add to +Panel</guibutton> button. +</para> + +<para> +Applets can be moved by dragging them on their handle with holding the +&LMB;, or the &MMB;, or by choosing +<guimenuitem>Move</guimenuitem> from the context menu. +</para> + +<para> +You can learn more about the applets in the section <link +linkend="applets">Applets</link>. +</para> + +</sect2> +<sect2 id="removing-applets"> +<title>Removing Applets</title> +<para> +Applets can be removed by choosing the <guimenuitem>Remove <replaceable>applet name</replaceable></guimenuitem> option from the context menu, which appears when the +&RMB; is clicked on the applet's handle (left or top side of the applet) or on the icon itself. +</para> + + +</sect2> + +<sect2 id="adding-extensions"> +<title>Adding Extensions</title> + +<para> +There is also the possibility to add external extensions to &kicker;, +like the <guimenuitem>External Taskbar</guimenuitem>, the <guimenuitem>Dock +Application Bar</guimenuitem> for WindowMaker +dock-applications, <guimenuitem>Kasbar</guimenuitem>, an iconic kind of +taskbar, an <guimenuitem>Universal Sidebar</guimenuitem> and even child <guimenuitem>Panel</guimenuitem>s which behave like new instances of +&kicker;. +</para> + +<para> +Extensions can be added by selecting them from the +submenu <guisubmenu>Add New Panel</guisubmenu> in the context +menu of &kicker;. +Most of the extensions can be moved to any border of the screen by +dragging them with the &LMB; on a free space. If that does not work, +open the context menu on any free space in &kicker;, +choose <guimenuitem>Configure Panel...</guimenuitem> and set up the panel +positions in the appearing dialog. +</para> + +<para> +More about extensions can be read in the <link +linkend="extensions">extensions</link> section. +</para> + +</sect2> + +<sect2 id="removing-extensions"> +<title>Removing Extensions</title> + +<para> +You can remove extensions by clicking <guimenuitem>Remove</guimenuitem> +in their context menu, usually located in the +fade-out handles or by selecting them from the <guisubmenu>Remove +Panel</guisubmenu> submenu of the &kicker; context +menu. +</para> +</sect2> + +</sect1> + +<sect1 id="configuring-apps"> +<title>Configuring Application Buttons</title> + +<para> +Every <guiicon>application starter</guiicon> has some preferences you +can set from their context menu with <guimenuitem>Configure <replaceable>application name</replaceable>Button...</guimenuitem>. Usually applications +and folders have the same preferences as in &konqueror;. Only the +applications which are located in the <guimenu>K</guimenu> Menu (for +experienced users: those which have a <literal +role="extension">.desktop</literal> extension in the <filename +class="directory">applnk</filename> folder) have a special kind of config +dialog. +</para> + +<sect2 id="general-tab"> +<title>The <guilabel>General</guilabel> Tab</title> + +<para> +Here you can see some information about the application link. You can also +choose an icon by clicking on the <guibutton>icon button</guibutton> +<!-- and change the filename of the link file -->. +This may be useful if you want the icon on the panel behave different +to the analog one in the <guimenu>K</guimenu> Menu. +</para> +<!-- Note: illogic-al: Modification not possible from Kicker's Properties menu +as root usually owns these .desktop files--> + +</sect2> + +<sect2 id="permissions-tab"> +<title>The <guilabel>Permissions</guilabel> Tab</title> + +<para> +Here you can see the permissions of the link file. Please refer to the +manuals or handbooks of your operating system for more about +permissions. +</para> + +</sect2> + +<sect2 id="application-tab"> +<title>The <guilabel>Application</guilabel> Tab</title> + +<para> +You can set the behavior of the application when it's executed on this page. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Name</guilabel></term> +<listitem> +<para> +Here you can set the name of the application which will be shown in the tooltip. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Description</guilabel></term> +<listitem> +<para> +Here you can set an informative title which will be shown in the tooltip. +</para> + +<note> +<para> +Once the <guilabel>Description</guilabel> is set however, it alone will be +shown in the tooltip. +</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Comment</guilabel></term> +<listitem> +<para> +See <guilabel>Description</guilabel>. +</para> + +<note> +<para> +If you set a <guilabel>Name</guilabel> and a <guilabel>Comment</guilabel>, they will +be shown as tooltips of the start icons in the style <quote>Name - Comment</quote>. +</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Command</guilabel></term> +<listitem> +<para> +Usually, there is only the name of the binary that has to be started +when clicking on the icon. You can search for another application to be +started by clicking the <guibutton>Browse...</guibutton> button and/or add +special command line parameters to the application. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Work path</guilabel></term> +<listitem> +<para> +Not yet written +</para> +</listitem> +</varlistentry> + +<!--<varlistentry> +<term><guilabel>Panel Embedding</guilabel></term> +<listitem> +<para> +This feature is not implemented yet. +</para> +</listitem> +<listitem><para>&kicker; has the possibility to swallow some applications +like <abbrev>e.g.</abbrev> <application>XOSView</application>. This means that +the application will show up directly in the panel. Therefore you have to +insert the exact title of the application window in the <guilabel>Window +Title</guilabel> Textfield. You can also specify an application that will be +executed when clicking on the swallowed application by typing it's name in the +<guilabel>Execute on click</guilabel> field.</para></listitem> +</varlistentry>--> + +<varlistentry> +<term><guilabel>Supported file types:</guilabel></term> +<listitem> +<para> +In this section you can choose what kinds of filetypes are handled by +this application. Please refer to &konqueror; handbook for more about this. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Advanced Options</guilabel></term> +<listitem> +<para> +This button allows for further configuration of the application to be run. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Run in terminal</guilabel></term> +<listitem> +<para> +If this box is checked, the application will be executed in a terminal +window. You can also add special Terminal options. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Run as different user</guilabel></term> +<listitem> +<para> +Checking this option will let the application start with the permission +of the user you typed in the field <guilabel>Username</guilabel>. You +will be prompted for the user's password on application start. This +option may be very useful if you want to start some applications as +superuser. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Enable launch feedback</guilabel></term> +<listitem> +<para> +If this box is checked, this will display feedback when an application icon is clicked +with the &LMB;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Place in system tray</guilabel></term> +<listitem> +<para> +When checked, the application's icon will show up in the panel system tray. +You will then be able to hide or show the application by clicking on the system +tray icon. Clicking on it using the &RMB; will allow also you to undock, or quit the +application. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>DCOP registration</guilabel></term> +<listitem> +<para> +Not yet written +</para> +</listitem> +</varlistentry> +</variablelist> + +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +</sect1> + +</chapter> + +<chapter id="configuring"> +<title>Configuring &kicker;</title> + +<para> +This section describes the ways &kicker; can be configured. It's only +about the basic &kicker; settings, configuration of the applets are +described in their <link linkend="applets">sections</link> +</para> + +<para> +You can change the settings by either clicking +<guimenuitem>Configure Panel...</guimenuitem> in the context +menu of &kicker;, or in &kcontrolcenter; by +going to <guilabel>Desktop</guilabel> and then selecting the +<guilabel>Panels</guilabel> or the <guilabel>Taskbar</guilabel> module. +</para> + + +<sect1 id="panel"> +<title>The Panel Section</title> + +<sect2 id="panel-extensions"> +<title>Extensions</title> +<para> +Panels and panel <link linkend="extensions">extensions</link> are configured +on the same page. Simply choose one of your extensions (⪚ +Child Panel) from the <guilabel>Settings for:</guilabel> listbox. You will then +be adjust its settings rather than that of the Main Panel. +</para> + +</sect2> + +<sect2 id="panel-arrangement"> +<title><guilabel>Arrangement</guilabel></title> + +<para> +In the <guilabel>Arrangement</guilabel> tab you can configure some basic +functionality of the &kde; panel (&ie; functionality you'd find in other +panel applications as well; later we'll come to the more interesting +features). +</para> + +<para> +In the <guilabel>Position</guilabel> frame you can choose which +screen border the panel should be attached to. Please note that usually +the available space is used more efficiently if the panel is aligned +horizontally, &ie; attached to the top or bottom screen border. If you +want to play around with different settings you can change the panel's +position even easier by dragging the panel from one border to the other. +</para> + +<para> +The <guilabel>Length</guilabel> frame lets you define how much space a panel +will occupy on the side of the screen which it resides. By default this is on the +bottom so changing this value will affect a panel's width. The value can be anywhere +from 1% to 100%. +Checking the check box <guilabel>Expand as required to fit contents</guilabel> +makes sure that a panel is at least as big as needed to show every icon and +applet. +</para> + +<para> +The <guilabel>Size</guilabel> frame lets you define how large a panel will be. +The panel's size can be tiny, small, medium, large or custom. Depending on +which applets you use you may find that some applets work better at +different panel sizes. +<!--You can also change the size by clicking the &RMB; on any free space +and choosing a size from the <guimenu>Size</guimenu> menu.--> +</para> +</sect2> + +<sect2 id="panel-hiding"> +<title><guilabel>Hiding</guilabel></title> + +<para> +Depending on your screen resolution you may find that the panel takes +away too much of your precious screen real estate. To save screen space, +the panel offers an auto hide feature. When this feature is enabled, the +panel will hide when the mouse cursor has not been moved over it for a +configurable amount of time. If you move the mouse to the panel's screen +border it will show up again. Select the <guilabel>Hide automatically</guilabel> +option in the <guilabel>Hide Mode</guilabel> frame to enable this feature. +You can also configure the amount of time the panel will wait before +it hides here. The check box <guilabel>Show panel when switching +desktops</guilabel> makes sure that the panel will be shown on the new +chosen desktop. Otherwise, if there are too many applets and icons on +&kicker;, two small scroll buttons will be displayed to scroll the whole +panel. +</para> + +<para> +When the panel's hide buttons are enabled you'll see buttons on both +sides of the panel, with arrows showing to the screen border. If you +click on one of these buttons, the panel will slide away in that +direction. After that, you'll see a remaining show button in that +corner, which will make the panel show again. Check the appropriate +checkbox if you want the hide buttons to show up on any side of +&kicker;. Using the slider you can change the width of the buttons. +</para> + +<para> +You can toggle which hide buttons the chosen panel should have with +the check boxes in the group <guilabel>Panel-Hiding Buttons</guilabel>. +</para> + +<para> +The <guilabel>Panel Animation</guilabel> frame allows you to choose +whether the panel will softly slide away or just disappear. +Checking the <guilabel>Animate panel hiding</guilabel> will allow you +to configure the speed of the animation using the sliders. Unchecking, +naturally, disables the panel animations. +</para> + +</sect2> + +<sect2 id="panel-menus"> +<title>Menus</title> + +<para> +In the <guilabel>Menus</guilabel> tab you can configure the panel menu's +behavior. This affects the <guimenu>K</guimenu> menu you will often use +to launch applications, the browser menus you can use to access +folders and other menus like the recent documents menu. +</para> + +<para> +The <guilabel>K Menu</guilabel> frame offers you some options to +configure the <guimenu>K</guimenu> menu's functionality. The +<guilabel>Bookmarks</guilabel> and <guilabel>Recent Documents</guilabel> options +will enable submenus showing your <application>konqueror</application> +bookmarks and the last documents you've opened using &kde; applications +respectively. The <guilabel>Quick Browser</guilabel> option will enable a browser menu. +Enabling the <guilabel>Show side image</guilabel> check box will display a neat +image on the left side of the <guimenu>K</guimenu> menu. +The <guilabel>Menu item format</guilabel> entry allows you to set how +detailed the <guimenu>K</guimenu> menu entries will be. +The <guilabel>Name only</guilabel> option simply shows the application's name in the menu. +The <guilabel>Name (Description)</guilabel> option will show a small description +besides the name of the application. +The <guilabel>Description (Name)</guilabel> and <guilabel>Name +(Description)</guilabel> options will show both name and description in +the KMenu. +</para> + +<para> +In the <guilabel>QuickBrowser Menus</guilabel> frame you can configure +whether the panel's browser menus will show hidden files or not (hidden +files on &UNIX; systems are those whose filenames begin with a dot) as +well as how many files at most will be shown in a browser menu; the +latter option may be especially useful if you have a rather small screen +resolution, as the browser menus would otherwise quickly fill up your screen +when you browse folders containing many files. +</para> + +<para> +The quick start section in the <guimenu>K</guimenu> menu offers quick +access to programs you have used often or recently. In the +<guilabel>QuickStart Menu Items</guilabel> frame you +can choose whether this section will show the most recently or the most +frequently used programs. Using the option <guilabel>Maximum number of +entries</guilabel> you can configure how many +programs the quick start section will remember. +</para> + +</sect2> + +<sect2 id="panel-appearance"> +<title><guilabel>Appearance</guilabel></title> + +<para> +Using the <guilabel>Appearance</guilabel> tab you can configure the +panel's overall appearance. +</para> + +<para> +The check box <guilabel>Enable icon mouseover effects</guilabel> +toggles the large animated tooltips of &kicker;. They show name and +description of the icons and applets the mousepointer is positioned on. +</para> + +<para> +If <guilabel>Show tooltips</guilabel> is checked, the classical small +tooltips with descriptions of the icons and applets will be shown if the +mousepointer rests over an icon for some seconds. Note that this +has no effect as long as the option to <guilabel>Enable icon mouseover +effects</guilabel> is enabled. +</para> + +<para> +The &kde; panel supports so-called <quote>tiled buttons</quote>. This +means that the buttons shown on the panel will be drawn using +configurable images/colors. +</para> + +<para> +For every kind of panel button there is a combo box offering a custom +color option and tiled images. When the value is changed from "Default", +tiles are enabled for this kind of button. You can also see a preview of a tile +before use via the combo box. +</para> + +<para> +The different kinds of buttons are: +</para> + +<variablelist> +<varlistentry> +<term><guilabel>K Menu</guilabel> tiles</term> +<listitem> +<para> +The icon for the <guiicon>K Menu</guiicon> will be displayed as a tile +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Applications</guilabel> tiles</term> +<listitem> +<para> +The icons which start applications will be displayed as tiles +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Desktop access</guilabel> tiles</term> +<listitem> +<para> +The <guiicon>Desktop Access</guiicon> icon will be displayed as a tile +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>QuickBrowser menus</guilabel> Tiles</term> +<listitem> +<para> +The icons for <guiicon>Quickbrowsers</guiicon> will be displayed as +tiles +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Window list</guilabel> Tiles</term> +<listitem> +<para> +The <guiicon>Window List</guiicon> icon will be displayed as a tile +</para> +</listitem> +</varlistentry> +</variablelist> + +<para> +The <guilabel>Enable transparency</guilabel> option, when checked, allows the +panel to appear transparent. +</para> + +<para> +The background image is a picture that will be used +to draw the panel's background, just like you can use a picture for the +desktop background. Check the <guilabel>Enable background +image</guilabel> option to enable this feature. You can specify an image +file in the edit box below or choose one by clicking on the +<guiicon>Open file dialog</guiicon> button. You may also check the +<guilabel>Colorize to match the desktop color scheme</guilabel> box to +modify the background image's colors. You'll see a preview of the selected +picture on the right. +</para> + + + +</sect2> + +<!-- This section seems deprecated... + +<sect2 id="panel-applets"> +<title>Applets</title> + +<para> +Applets are small plugins that extend the panel's functionality. &kde; +comes with some applets but they may be provided by third parties as +well.</para> + +<para> +Panel applets can be started using two different ways: internally or +externally. While <quote>internal</quote> is the preferred way to load +applets, this can raise stability or security problems when you are +using poorly programmed third-party applets. To address these problems, +applets can be marked <quote>trusted</quote>. You might want to +configure the panel to treat trusted applets different from untrusted +ones. Your options are: +</para> + +<itemizedlist> +<listitem> +<para> +<guilabel>Load only trusted applets internal</guilabel>: All applets but +the ones marked <quote>trusted</quote> will be loaded using an external +wrapper application. +</para> +</listitem> + +<listitem> +<para> +<guilabel>Load startup config applets internal</guilabel>: The applets +shown on &kde; startup will be loaded internally, others will be loaded +using an external wrapper application.</para></listitem> +<listitem><para><guilabel>Load all applets internal</guilabel>: will +load all applets internally, regardless of whether they are trusted or +not. +</para> +</listitem> +</itemizedlist> + +<para> +For stability and security reasons, we recommend using one of the first +two options and that you mark only those applets as 'trusted' that come +with the &kde; base packages. +</para> + +<para> +To mark applets <quote>trusted</quote> or <quote>untrusted</quote> you +can move them from one of the shown listboxes to the other. Just try +selecting an applet in the list of trusted applets and click the +<guibutton>>></guibutton> button. This will move the selected +applet to the other list, while clicking the +<guibutton><<</guibutton> button will move the selected applet of +the list of available applets to the list of trusted ones. +</para> + +</sect2> +--> + +</sect1> + +<sect1 id="taskbar-settings"> +<title>The <guilabel>Taskbar</guilabel> Section</title> + +<para> +This section changes the settings of the taskbar. Changes affect the +external taskbar and also taskbar applets on &kicker; or child-panels. +</para> + +<variablelist> +<varlistentry> +<term>Show windows from all desktops</term> +<listitem> +<para> +If this box is checked, the taskbar will show all running apps of every +desktop. Otherwise, only the applications of the current desktop are +shown. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Sort windows by desktop</term> +<listitem> +<para> +Checking this box will sort all <guibutton>taskbar buttons</guibutton> +in a group for each desktop, otherwise they are sorted by the order they +are started. This will not affect grouped tasks if they are spread over +more than one desktop. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Sort alphabetically by window name</term> +<listitem> +<para> +To be written</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Show only minimized windows</term> +<listitem> +<para> +If this box is checked, only windows which have been minimized will be +shown in the taskbar. If <guilabel>Show windows from all desktops</guilabel> +has been checked then all minimized windows will be shown. Otherwise, only the +minimized windows of the current virtual desktop will be shown. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Show application icons</term> +<listitem> +<para> +If this box is checked, every <guibutton>taskbar button</guibutton> will +have the icon of the running application beside its title. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Show window list button</term> +<listitem> +<para>Checking this box will show the small <guibutton>window list +button</guibutton>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Group similar tasks</term> +<listitem> +<para> +<inlinemediaobject><imageobject><imagedata fileref="taskbar_group.png" +format="PNG"/></imageobject></inlinemediaobject> +</para> + +<para> +This is an option which helps you if you often lack space in your +taskbar. If it is set to <guilabel>Always</guilabel>, several +instances of the same application are grouped together in one taskbar +button. Select <guilabel>When Taskbar Full</guilabel> to make &kicker; +only group similar tasks if there is not much space left in the taskbar. +</para> + +</listitem> +</varlistentry> + +</variablelist> + +<para> +You can define the mouse actions of the taskbar buttons with the settings in +the <guilabel>Actions</guilabel> frame. Each action can be one of the +following:</para> + +<variablelist> +<varlistentry> +<term> +<guilabel>Show Task List</guilabel> +</term> +<listitem><para>Clicking with the +mouse button will open a menu displaying all +tasks in that group. If you click an entry of that menu with any mouse +button, the corresponding application will become active.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Operations Menu</guilabel></term> +<listitem> + +<para>Clicking with the mousebutton will open a menu with all +applications of that group, where every application has its window +menu as a submenu and there are some group specific entries like +<guimenuitem>Close All</guimenuitem> which closes all applications of +that group, <guisubmenu>All to Desktop</guisubmenu> which lets you +define on which desktop the whole group appears and +<guimenuitem>Maximize All</guimenuitem>, <guimenuitem>Minimize +All</guimenuitem> and <guimenuitem>Restore All</guimenuitem> which +appends those actions to all applications of that group. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Cycle Through Windows</guilabel></term> +<listitem><para>If this action is chosen, each +click with the mousebutton on the <guibutton>taskbar button</guibutton> will +activate one of that group's applications, one after each others.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Activate Task</guilabel></term> +<listitem> +<para> +<guilabel>Activate Task</guilabel>: Clicking with the mousebutton will activate +the first application in that group without opening the group menu. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Raise Task</guilabel></term> +<listitem> +<para>The first application of that group will be +put in the foreground without giving focus to it.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Lower Task</guilabel></term> +<listitem> +<para> +The first application of that group will be +put in the background. It won't lose the focus. </para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Minimize Task</guilabel></term> +<listitem> +<para>The first application of that group will be +minimized. If it is already minimized, it will be restored again.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Please note that some of these settings only have effect if a +taskbar button contains more than one application. +</para> + +</sect1> + +</chapter> + +<chapter id="k-menu"> +<title>The <guimenu>K</guimenu> Menu</title> + +<para> +The <guimenu>K</guimenu> Menu is one of the central elements of +&kicker;. +</para> + +<para> +There are five main groups in the <guimenu>K</guimenu> Menu which will +be described now from bottom to top. +</para> + +<sect1 id="kde-group"> +<title>The &kde; Group</title> + +<para> +This group is for the common &kde; things in the <guimenu>K</guimenu> +Menu. +</para> + +<variablelist> +<varlistentry> +<term><guimenuitem>Log Out...</guimenuitem></term> +<listitem> +<para> +This entry is used to finish the &kde; session. It also shuts down the +&X-Window; session. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Lock Session</guimenuitem></term> +<listitem> +<para> +With this entry you can lock your session if you don't want anybody else +to access your desktop. If you have set a screensaver, it will appear when +locked, otherwise the screen will turn black. If you hit any key, you +will be prompted for your user password. This is independent from the +screensaver's password settings. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Special Configuration</term> +<listitem> +<para> +Clicking with the &RMB; on the <guimenu>K</guimenu> Menu, will produce a +special submenu. In this submenu is the <guisubmenu>Panel Menu</guisubmenu>. +Here you can change the settings of &kicker;, described in the +<link linkend="configuring">Configuring &kicker;</link> section, add +things to &kicker; (see in <link linkend="basics">&kicker; Basics</link> +for more), or reach the <guisubmenu>Help</guisubmenu> Menu, but as you are +reading this, you probably found it yourself. +You can also start the <application>Menu Editor</application> via this submenu. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="run-command"> +<title><guilabel>Run Command...</guilabel></title> + +<para> +This will bring up a small but powerful application start dialog. +</para> + +<para> +In the standard case, you just type in a command and press +<keycap>Enter</keycap> or click <guibutton>Run</guibutton>. But there +is also an <guibutton>Options >></guibutton> button which will bring up +some starting options to the command window. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Run in terminal window</guilabel></term> +<listitem> +<para> +Checking this box will let the application start in a terminal which means that +you will be able to see any command-line messages the application may give. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Run as a different user</guilabel></term> +<listitem> +<para> +If this box is checked, you can specify a user with whose permission the +application should run in the <guilabel>Username</guilabel> textfield. +If you specify another user, you will have to give a password at the box +below. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Run with different priority</guilabel></term> +<listitem> +<para> +Check this option to run with a different priority. A higher priority +will tell the operating system to give more processing time to the +applications. You can use the slider to change the priority. If you +want to give your app a higher priority than the default one (middle +position), you will need to enter the root password below. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Run with realtime scheduling</guilabel></term> +<listitem> +<para> +The Scheduler is the part of the operating system which processes will +run and which have to wait. Usually, an application will run with normal +schedule, which means it can use the processing time it gets from the +operating system, but you can also set it to +realtime. This means that the application has all +the process time until it gives it away. You will need to enter the root +password to use <guilabel>Run with realtime scheduling</guilabel>. +</para> + +<warning> +<para> +This can be dangerous. If the application hangs and cannot give up the +processor, the complete system might hang. +</para> +</warning> + +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + + +<sect1 id="actions"> +<title>The Actions Group</title> + +<para> +This group contains some very useful dynamic menus as described in the +<link linkend="panel-menus">Menus</link> section of &kicker;'s settings. +</para> + +<variablelist> +<varlistentry> +<term><guisubmenu>Quick Browser</guisubmenu></term> +<listitem> +<para> +This submenu contains quick browsers for three very useful folders: +home, root, and system configuration. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guisubmenu>Recent Documents</guisubmenu></term> +<listitem> +<para> +This menu shows the most recently used documents (works only with &kde; +applications for the moment). Clicking the element <guimenuitem>Clear +History</guimenuitem> will remove those entries, what may be useful for +privacy reasons. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guisubmenu>Bookmarks</guisubmenu></term> +<listitem> +<para> +This submenu shows your personal bookmarks just like &konqueror; +does. Refer to the &konqueror; Handbook for more help on this. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="application-group"> +<title>The All Applications Group</title> + +<para> +The submenus for application starting are located in this group. You can +use &kmenuedit; to add, remove or move the entries. Applications will have a +short description if either the <guilabel>Name (Description)</guilabel> or +<guilabel>Description (Name)</guilabel> option is enabled in the settings. +</para> +</sect1> + +<sect1 id="most-recently-group"> +<title>The Most Used Applications Group</title> + +<para> +This group holds either the most recently or the most frequently used +applications. See the <link linkend="panel-menus">Menus +Configuration</link> section for more about that. +</para> +</sect1> + +</chapter> + +<chapter id="applets"> +<title>Applets</title> + +<para> +Applets are small applications running inside of &kicker;. Almost +everything besides the <guiicon>application starter buttons</guiicon> +are applets. They can be added from the context menu +by choosing<guisubmenu>Add Applet to Panel</guisubmenu>. Every +applet contains a small arrow in its handle. Clicking it will bring up a menu +which lets you move or remove it, set the Preferences, if there are any and set +the preferences of &kicker;. +</para> + +<sect1 id="taskbar-applet"> +<title>The Taskbar Applet</title> + +<para> +The taskbar applet shows buttons for the running applications. The +application, which has the focus, is shown as a pressed button. If an +application is minimized, the title displayed in the taskbar will fade +to gray. +</para> + +<tip> +<para> +If you click on the button of the active application, it will be +minimized. This means also that if you click twice on an inactive +application, it will also be minimized. +</para> +</tip> + +<para> +A click with the &RMB; on a button will show the standard application +menu. Only the entry <guimenuitem>To Current Desktop</guimenuitem> +differs: if you have set the taskbar to show the applications of all +desktops, you can move this app to the current desktop. +</para> + +<para> +There is also a small icon on the left or top side of the taskbar, which +opens a menu. This is called the <guibutton>windows list +icon</guibutton>. The menu's first entry, <guimenuitem>Unclutter +Windows</guimenuitem>, tries to move the windows on your active desktop +in a way to see as many as possible. <guimenuitem>Cascade +Windows</guimenuitem> puts all windows on the active desktop over each +others, the most recently on top and the others sorted by the time they +where last used. +</para> + +<para> +Below those entries is a list of all currently running applications, +grouped by the desktops on which they are running. Clicking on the name +of a desktop will switch to that one, clicking an application will also +activate it. You can specify the mouse behavior. Please refer to <link +linkend="taskbar-settings">Taskbar</link> settings for more about that. +</para> + + +<sect2 id="configure-taskbar-applet"> +<title>Configuring the Taskbar Applet</title> + +<para> +You can configure the taskbar by clicking the &RMB; on the small move +handle. +</para> +<para> +Please refer to <xref linkend="taskbar-settings"/> for details about the +preferences of the taskbar. +</para> + +</sect2> + +</sect1> + +<sect1 id="pager-applet"> +<title>The Mini-Pager Applet</title> + +<para> +This little applet shows a preview of the virtual desktops, lets you +switch between virtual desktops and gives you the ability to move windows +from one desktop to another by dragging them. +</para> + +<para> +There is also a very useful context menu used to +configure this applet: +</para> + +<variablelist> +<varlistentry> +<term><guimenuitem>Configure Desktops...</guimenuitem></term> +<listitem> +<para> +This opens the configuration dialog for virtual desktops. There you can +specify how many desktops you want to have and give them names. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guisubmenu>Pager Options</guisubmenu></term> +<listitem> +<para> +In this submenu you can configure the appearance of the Mini-Pager. It +provides the following functionality: +</para> + +<variablelist> + +<varlistentry> +<term><guimenuitem>Pager Layout</guimenuitem></term> +<listitem> +<para> +In this section you can choose in how many <guimenuitem>Rows</guimenuitem> +or <guimenuitem>Columns</guimenuitem> the desktop previews are arranged, +if you want to see which windows are currently visible on the desktops +and if icons should indicate the applications running on the different +vitual desktops. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Text Label</guimenuitem></term> +<listitem> +<para> +Here you can choose if the desktop previews should be labeled by their +numbers, their names or if you you don't want them to be labeled at all. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Background</guimenuitem></term> +<listitem> +<para> +You can set the background of the pager to +<guimenuitem>Elegant</guimenuitem>, <guimenuitem>Transparent</guimenuitem> +or equivalent to the <guimenuitem>Desktop Wallpaper</guimenuitem>. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Launch Pager</guimenuitem></term> +<listitem> +<para> +This launches the application &kpager;, which provides functions similar +to those offered by the Mini-Pager applet. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="clock-applet"> +<title>The Clock Applet</title> + +<para> +As you might already guess, the clock applet is a small clock which +resides in &kicker;. +</para> + +<para> +A click with the &LMB; on the clock will show a small calendar. You can +use the <guibutton>single arrows</guibutton> to switch the months or the +<guibutton>double arrows</guibutton> for switching years. This won't +have any effect of your date settings, it's just for your information. +</para> + +<para> +There are some things you can do with the clock applet. This can be done +from the context menu. +</para> + +<sect2 id="clock-type"> +<title><guisubmenu>Type</guisubmenu></title> + +<para> +There are four ways the clock can appear: +</para> + +<variablelist> +<varlistentry> +<term>Plain</term> +<listitem> +<para> +This lets the clock appear as a simple text that shows the time in plain text. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Digital</term> +<listitem> +<para> +This lets the clock appear as a digital clock showing the time in the +well known seven segment style. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Analog</term> +<listitem> +<para> +If this is set, the clock will be displayed as an old styled analog +clock. +</para> +<note> +<para>This may only be useful if you set &kicker; to normal or large +size. +</para> +</note> +</listitem> +</varlistentry> + +<varlistentry> +<term>Fuzzy</term> +<listitem> +<para> +This is a very unorthodox style of time display. Try it out, it is +really funny! +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="show-timezone"> +<title><guimenuitem>Show Timezone</guimenuitem></title> + +<para> +Select available timezones or open the <guilabel>Timezones</guilabel> +tab of <guilabel>Configure</guilabel> dialog of the clock applet with +<guimenuitem>Configure Timezones...</guimenuitem>.</para> + +</sect2> + +<sect2 id="adjust-time"> +<title><guimenuitem>Adjust Date & Time</guimenuitem></title> + +<para> +This option starts the <guilabel>Date & Time</guilabel> +configuration module in the section <guilabel>System Administration</guilabel> of the &kcontrolcenter;.</para> + +<note> +<para> +You will need the super user password for adjusting date and time. +</para> +</note> + +</sect2> + +<sect2 id="date-format"> +<title><guimenuitem>Date & Time Format</guimenuitem></title> + +<para> +This will open the <guilabel>Country/Region & Language</guilabel> module in the section <guilabel>Regional & Accessibility</guilabel> of the &kcontrolcenter; +where you can set your formats on the page <guilabel>Times & Dates</guilabel>. There aren't any special permissions needed for that. +</para> + +</sect2> + +<sect2 id="copy-date"> +<title><guisubmenu>Copy to Clipboard</guisubmenu></title> + +<para> +If you need to paste the actual date and/or time in another application +(⪚ in a text editor), you can copy it to the clipboard with this +function. After selecting one of the available formats, the actual date +and/or time is placed in the clipboard using the appropriate format. +</para> + +</sect2> + +<sect2 id="clock-preferences"> +<title><guimenuitem>Configure Clock...</guimenuitem></title> + +<para> +Here you can set some general preferences of the clock applet. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Appearence</guilabel></term> +<listitem> +<para> +In the <guilabel>Clock Type</guilabel> settings you can choose between +the clock styles like in the context menu. +</para> + +<!--para> +The <guilabel>Date</guilabel> group lets you pick font and color of the +date, which is shown when activated for the specific clock type. +</para>--> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Plain Clock</guilabel> options</term> +<listitem> +<para>In the <guilabel>Display</guilabel> section you can check if you +want to have the date and/or the seconds shown. In +<guilabel>Time</guilabel> you can choose if you want the common &kde; +look or your own custom colors and font. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Digital Clock</guilabel> options</term> +<listitem> +<para>In the <guilabel>Display</guilabel> section you can check if you +want to have the date, the seconds and/or blinking dots shown. In +<guilabel>Time</guilabel> you can choose if you want the common +<acronym>LCD</acronym>-Look or your own custom colors. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Analog Clock</guilabel> options</term> +<listitem> +<para> +In the <guilabel>Display</guilabel> section you can check if you want to +have the date and/or seconds shown. In <guilabel>Time</guilabel> you +can choose if you want the common <acronym>LCD</acronym>-Look or your +own custom colors. +You can also set the level of antialiasing, which means that lines will get +blurred a little bit to prevent steps in the drawing. High quality antialiasing +may catch some system load on low-end systems. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The <guilabel>Fuzzy Clock</guilabel> options</term> +<listitem> +<para> +In the <guilabel>Display</guilabel> section you can check if you want to +have the date shown. In <guilabel>Time</guilabel> +you can choose the colors and the font of the fuzzy clock. There is also a slider to set the +<guilabel>Fuzziness</guilabel>. This cannot be described in the +documents, just do your own experiments. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="launcher-applet"> +<title>The Quick Launcher Applet</title> + +<para> +This is a compressed application launcher. It is very useful especially +if the panel is set to normal or large size. You can add applications by +drag and drop or from the context menu. The +context menu is also used to remove an application. +</para> +</sect1> + +<sect1 id="systemtray-applet"> +<title>The System Tray Applet</title> + +<para> +The System Tray is used to dock some special applications ⪚ +&klipper; or &juk;. The applications shown in the system tray all +provide individual funtionality. If you need help concerning these +options, please refer to the application handbooks. +</para> + +<para> +The System Tray's context menu provides the option +<guimenuitem>Configure System Tray...</guimenuitem> . If you click on it, +a dialog pops up which lets you choose applications that should not be +permanently visible in the System Tray. Hidden icons can be made visible +by clicking on the small arrow appearing on the left or top side of the +applet. +</para> +</sect1> + +<sect1 id="lockout-applet"> +<title>Lock/Logout Applet</title> +<para> +This little applet contains two buttons. +The <guibutton>Lock the session</guibutton> is used to lock the session if you +ever want to leave your &kde; unattended and don't want anybody to access it. +The <guibutton>Log out</guibutton> is used to close your &kde; session. +</para> +</sect1> + +<sect1 id="run-applet"> +<title>The Application Launcher Applet</title> + +<para> +This applet provides a simple command line embedded in &kicker;. Nothing +more, nothing less. +</para> + +</sect1> + +<sect1 id="naughty-applet"> +<title>The Runaway Process Catcher Applet</title> + +<para> +This applet shows a smiley which will get angry when any process catches +up too much system resources. If an application uses too much, a +messagebox will appear and ask you how to handle that application. +</para> + +<para> +Clicking it with the &LMB; will show a configuration dialog. Here you +can set the <guilabel>Update interval</guilabel>, which is set in +seconds, and the <guilabel>CPU load threshold</guilabel>. At the +moment, there is no real advice for setting this up, you will have to do +some experimenting. These settings will probably change in a future +release. There is also a section <guilabel>Programs to ignore</guilabel> +where you can add applications that use many resources naturally, +⪚ compilers or 3D renderers. +</para> + +</sect1> + +<sect1 id="klipper-applet"> +<title>&klipper; Applet</title> + +<para> +This applet does exactly the same like the &klipper; residing in the system +tray. It has the advantage, that it consumes a little bit less system +resources, which only matters on really slow systems, but has the +disadvantage, that it uses more space than &klipper; in the system +tray. You can read more about that in the manual for +<ulink url="help:/klipper/index.html">&klipper;</ulink>. +</para> +</sect1> + +</chapter> + +<chapter id="extensions"> +<title>Panel Extensions</title> + +<para> +There are also some features that run outside of &kicker;, the +extensions. They are added from the +context menu by choosing <guisubmenu>Add New Panel</guisubmenu>. You can move them to any +screenborder by dragging them at the small applet +handle on their side and remove it by right clicking on an empty space and choose <guimenuitem>Remove Panel</guimenuitem>. +</para> + +<para> +The style of the extensions can be configured in the <xref +linkend="panel-extensions"/> section of &kicker;'s preferences. +</para> + + +<sect1 id="external-taskbar-extension"> +<title>The External Taskbar Panel Extension</title> + +<para> +The external taskbar is just the same as the taskbar applet with the +only difference that it provides its own panel. Refer to the <link +linkend="taskbar-applet">taskbar applet section</link> for help about +it. +</para> + +</sect1> + +<sect1 id="child-panel-extension"> +<title>The Child Panel Extension</title> + +<para> +This is just a panel like &kicker; itself, where you can add all the +stuff &kicker; is also capable. So you can have as many &kicker;s as you +want. Just add a child panel and add applications and applets to it. +</para> + +</sect1> + +<sect1 id="kasbar-extension"> +<title>The <application>KasBar</application> Extension</title> + +<para> +The <application>KasBar</application> is an iconic replacement of the +taskbar. It always shows the icons of all currently running applications +on any desktop, they can be chosen by clicking with the &LMB;. The +active window is highlighted, minimized windows will show a little +triangle pointing downwards instead of the square in the lower right of +the icons. A triangle pointing to the right indicates that the +application is shaded. +</para> +</sect1> + +<sect1 id="dock-application-bar-extension"> +<title>The Dock Application Bar Extension</title> + +<para> +The Dock Application Bar is an external bar which lets WindowMaker +applications be docked. Just run your dockable WindowMaker programs, if +the Dock Application Bar is running, they will be automatically docked. +</para> +</sect1> + +</chapter> + +<chapter id="commands"> +<title>Command Reference</title> + +<sect1 id="keybinding"> +<title>The Panel</title> + +<para> +There is only one standard shortcut available in &kicker;: +</para> + +<variablelist> +<varlistentry> +<term><keycombo action="simul">&Alt;<keycap>F1</keycap></keycombo></term> +<listitem> +<para> +Opens the <guimenu>K</guimenu> Menu +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +<qandaset> +<qandaentry> +<question> +<para> +How can I add applications, applets or anything else to the panel? +</para> +</question> +<answer> +<para> +Click the &RMB; on any free space in &kicker; and choose +what you want to add. See in <link linkend="basics">&kicker; Basics</link> +for more about that. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Can I have an external Taskbar just like in &kde; 1? +</para> +</question> +<answer> +<para> +Yes, you can just click the &RMB; on any empty space in &kicker; and +then choose <guisubmenu>Add</guisubmenu>, +<guisubmenu>Panel</guisubmenu> and the <guimenuitem>External +Taskbar</guimenuitem>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +How can I move &kicker; to another screen border? +</para> +</question> + +<answer> +<para> +Simply drag it by holding the &LMB; on any empty space in &kicker; to +any screen border. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +How can I move extensions to another screen border? +</para> +</question> + +<answer> +<para> +Just drag them by holding the &LMB; on the small +<guibutton>handles</guibutton> on the left or the top of the extension. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +I want the taskbar to show all applications I am running, independent on +which desktop they are. Is that possible? +</para> +</question> +<answer> +<para> +It is. Click the &RMB; on the small <guibutton>handle</guibutton> of the +taskbar, then choose <guimenuitem>Configure Taskbar...</guimenuitem> and check +<guilabel>Show windows from all desktops</guilabel> in the appearing dialog. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +How can I access the <guimenu>K</guimenu> Menu without using the mouse? +</para> +</question> +<answer> +<para> +Simply press <keycombo +action="simul">&Alt;<keycap>F1</keycap></keycombo> and it will appear. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Is there a way to add a menu containing all desktop icons to &kicker;? +</para> +</question> +<answer> +<para> +Just start &konqueror;, go to your home folder and drag the +<guiicon>Desktop</guiicon> icon to any free space of &kicker;, then +choose <guimenuitem>Add as Quick Browser</guimenuitem> from the +appearing menu. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +How can I change the color and style of &kicker;? +</para> +</question> +<answer> +<para> +You can change the colors of the panel with the global color module of +the <application>Control Center</application> or you can style the panel +itself, see in <xref linkend="panel-appearance"/> for more about that. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Why is the clock showing the wrong time? +</para> +</question> +<answer> +<para> +On some &RedHat;systems, the clock always shows the time in +&GMT;. This is a bug in the system setup, and not +directly related to &kicker;. However, to solve it, just create this +symbolic link: <userinput><command>ln</command> <option>-s</option> +<filename>/usr/share/zoneinfo</filename> +<filename>/usr/lib/zoneinfo</filename></userinput>. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Is it possible to change the <guiicon>K</guiicon> button of the panel to +another picture? +</para> +</question> +<answer> +<para> +Look for <filename>$HOME/.kde/share/apps/kicker/pics/go.png</filename> +and <filename>$HOME/.kde/share/apps/kicker/pics/mini/go.png</filename> +and replace them. Do not forget to flatten the replacements to one +layer, or else you will not see anything. Create the folders if +they do not already exist. Then restart &kicker;. +</para> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> +Why is my <guisubmenu>Settings</guisubmenu> menu not working? +</para> +</question> +<answer> +<para> +Your menu entries may be mixed up for some reason. Simply run +<command>kbuildsycoca</command> on a commandline. +</para> +</answer> +</qandaentry> +</qandaset> + +&reporting.bugs; +<!-- &updating.documentation; --> + +</chapter> + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kicker; +</para> + +<para> +Program copyright 1999-2000 The &kde; Team <ulink +url="http://www.kde.org"> (www.kde.org)</ulink>. +</para> + +<itemizedlist> +<listitem> +<para>&Matthias.Elter; &Matthias.Elter.mail; +</para> +</listitem> + +<listitem> +<para>&Matthias.Ettrich; &Matthias.Ettrich.mail; +</para> +</listitem> + +<listitem> +<para>&Wilco.Greven; &Wilco.Greven.mail; +</para> +</listitem> + +<listitem> +<para>&Rik.Hemsley; &Rik.Hemsley.mail; +</para> +</listitem> + +<listitem> +<para>&Daniel.M.Duley; &Daniel.M.Duley.mail; +</para> +</listitem> + +<listitem> +<para>&Preston.Brown; &Preston.Brown.mail; +</para> +</listitem> + +</itemizedlist> + +<para>Original documentation copyright 2001, 2002 &Dirk.Doerflinger; +&Dirk.Doerflinger.mail;</para> +<para>Portions copyright 2004 &Orville.Bennett; +<email>&Orville.Bennett.mail;</email></para> +<para>Portions copyright 2005 Titus Laska +<email>[email protected]</email></para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> +&underBSDLicense; <!-- BSD License --> + +</chapter> + +&documentation.index; + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-intent-step:0 +sgml-indent-data:nil +End: +--> + + diff --git a/doc/kicker/k_menu_icon.png b/doc/kicker/k_menu_icon.png Binary files differnew file mode 100644 index 000000000..b3ca6b647 --- /dev/null +++ b/doc/kicker/k_menu_icon.png diff --git a/doc/kicker/man-appletproxy.1.docbook b/doc/kicker/man-appletproxy.1.docbook new file mode 100644 index 000000000..4081f6c19 --- /dev/null +++ b/doc/kicker/man-appletproxy.1.docbook @@ -0,0 +1,101 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<title>KDE User's Manual</title> +<author><personname> +<firstname>Lauri</firstname> +<surname>Watts</surname> +</personname> +&Lauri.Watts.mail;</author> +<date>Feb 25, 2005</date> +<productname>K Desktop Environment</productname> +</refentryinfo> + +<refmeta> +<refentrytitle><command>appletproxy</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>appletproxy</command></refname> +<refpurpose>&kde; panel applet proxy</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>appletproxy</command> +<arg choice="req">desktopfile</arg> +<arg choice="opt">--configfile <replaceable>file</replaceable></arg> +<arg choice="opt">--callbackid <replaceable>id</replaceable></arg> +<arg choice="opt">KDE Generic Options</arg> +<arg choice="opt">Qt Generic Options</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para><application>appletproxy</application> is a small application that +allows you to run a &kicker; (&kde; panel) applet outside of &kicker; +itself. The applet will appear in it's own window, making this a convenient +way to debug panel applets.</para> +</refsect1> + +<refsect1> +<title>Options</title> + +<variablelist> +<varlistentry> +<term><option>desktopfile</option></term> +<listitem><para>The applet's desktop file</para></listitem> +</varlistentry> +<varlistentry> +<term><option>--configfile +<replaceable>file</replaceable></option></term> +<listitem><para>The config file to be used</para></listitem> +</varlistentry> +<varlistentry> +<term><option>--callback <replaceable>id</replaceable></option></term> +<listitem> +<para>&DCOP; callback id of the applet container.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + + +<refsect1> +<title>See Also</title> + +<para>kicker(1)</para> + +</refsect1> + +<refsect1> +<title>Examples</title> + +<variablelist> +<varlistentry> +<term><userinput><command>appletproxy</command> <parameter>knewsticker</parameter></userinput></term> +<listitem> +<para>Run &knewsticker; in a standalone window.</para> +</listitem> +</varlistentry> +</variablelist> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para>&kappname; was written by &Matthias.Elter; and &Matthias.Ettrich; and +is maintained by &Aaron.J.Seigo; &Aaron.J.Seigo.mail;</para> + +<para>This man page was written for &kde; 3.4 by &Lauri.Watts; +&Lauri.Watts.mail;</para> +</refsect1> + +</refentry> diff --git a/doc/kicker/man-kicker.1.docbook b/doc/kicker/man-kicker.1.docbook new file mode 100644 index 000000000..99f984670 --- /dev/null +++ b/doc/kicker/man-kicker.1.docbook @@ -0,0 +1,88 @@ +<?xml version="1.0" ?> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY % English "INCLUDE"> + <!ENTITY kappname "&kicker;"> +]> + +<refentry lang="&language;"> +<refentryinfo> +<title>KDE User's Manual</title> +<author>&Lauri.Watts;&Lauri.Watts.mail;</author> +<date>February 27, 2005</date> +<productname>K Desktop Environment</productname> +</refentryinfo> + +<refmeta> +<refentrytitle><command>kicker</command></refentrytitle> +<manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> +<refname><command>kicker</command></refname> +<refpurpose>&kicker; is the &kde; panel</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> +<command>kicker</command> +<arg choice="opt">KDE Generic Options</arg> +<arg choice="opt">Qt Generic Options</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para>&kicker; is the &kde; panel. It normally contains application +starters, applets, and a clock.</para> +<!-- FIXME: Well that's a pretty lame description. --> +</refsect1> + +<refsect1> +<title>Files</title> + +<variablelist> +<varlistentry> +<term><filename>$<envar>KDEHOME</envar>/share/apps/kickerrc</filename></term> +<listitem> +<para>User specific configuration file. This file is not normally intended +to be edited directly; Most configuration items can be controlled from +&kcontrol;. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><filename>$<envar>PREFIX</envar>/share/apps/kickerrc</filename></term> +<listitem> +<para>Global configuration file. This file is not normally intended to be +edited directly; Most configuration items can be controlled from &kcontrol;. +Global settings may be configured by the system administrator to either set +defaults, or lock down options that may not be altered by the users of the +system. +</para> +</listitem> +</varlistentry> +</variablelist> +</refsect1> + +<refsect1> +<title>See Also</title> + +<para>More detailed user documentation is available from <ulink +url="help:/kicker">help:/kicker</ulink> +(either enter this <acronym>URL</acronym> into &konqueror;, or run +<userinput><command>khelpcenter</command> +<parameter>help:/kicker</parameter></userinput>).</para> + +</refsect1> + +<refsect1> +<title>Authors</title> +<para>&kappname; was written by &Matthias.Elter; and &Matthias.Ettrich; and +is maintained by &Aaron.J.Seigo; &Aaron.J.Seigo.mail;</para> + +<para>This man page was written for &kde; 3.4 by &Lauri.Watts; +&Lauri.Watts.mail;</para> + +</refsect1> + +</refentry> diff --git a/doc/kicker/printsys_icon.png b/doc/kicker/printsys_icon.png Binary files differnew file mode 100644 index 000000000..13adbd006 --- /dev/null +++ b/doc/kicker/printsys_icon.png diff --git a/doc/kicker/quickbrowser_icon.png b/doc/kicker/quickbrowser_icon.png Binary files differnew file mode 100644 index 000000000..fbc259e95 --- /dev/null +++ b/doc/kicker/quickbrowser_icon.png diff --git a/doc/kicker/recent_docs_icon.png b/doc/kicker/recent_docs_icon.png Binary files differnew file mode 100644 index 000000000..21f079bf4 --- /dev/null +++ b/doc/kicker/recent_docs_icon.png diff --git a/doc/kicker/screenshot_left.png b/doc/kicker/screenshot_left.png Binary files differnew file mode 100644 index 000000000..8b29998ca --- /dev/null +++ b/doc/kicker/screenshot_left.png diff --git a/doc/kicker/screenshot_right.png b/doc/kicker/screenshot_right.png Binary files differnew file mode 100644 index 000000000..b5bcee61c --- /dev/null +++ b/doc/kicker/screenshot_right.png diff --git a/doc/kicker/taskbar_group.png b/doc/kicker/taskbar_group.png Binary files differnew file mode 100644 index 000000000..e5484fe96 --- /dev/null +++ b/doc/kicker/taskbar_group.png diff --git a/doc/kicker/terminals_icon.png b/doc/kicker/terminals_icon.png Binary files differnew file mode 100644 index 000000000..de458c184 --- /dev/null +++ b/doc/kicker/terminals_icon.png diff --git a/doc/kicker/windowlist_icon.png b/doc/kicker/windowlist_icon.png Binary files differnew file mode 100644 index 000000000..ca164a12a --- /dev/null +++ b/doc/kicker/windowlist_icon.png diff --git a/doc/kinfocenter/Makefile.am b/doc/kinfocenter/Makefile.am new file mode 100644 index 000000000..251280f85 --- /dev/null +++ b/doc/kinfocenter/Makefile.am @@ -0,0 +1,6 @@ + +SUBDIRS = $(AUTODIRS) + +KDE_LANG= en +KDE_DOCS = AUTO + diff --git a/doc/kinfocenter/cdinfo/Makefile.am b/doc/kinfocenter/cdinfo/Makefile.am new file mode 100644 index 000000000..e4070c171 --- /dev/null +++ b/doc/kinfocenter/cdinfo/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/cdinfo diff --git a/doc/kinfocenter/cdinfo/index.docbook b/doc/kinfocenter/cdinfo/index.docbook new file mode 100644 index 000000000..6048e5873 --- /dev/null +++ b/doc/kinfocenter/cdinfo/index.docbook @@ -0,0 +1,51 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>CD-ROM Information/Capabilities</title> +<articleinfo> + +<authorgroup> +<author> +<firstname>Jahshan</firstname> +<surname>Bhatti</surname> +<affiliation><address><email>[email protected]</email></address></affiliation> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2006-06-13</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>cd-rom</keyword> +<keyword>capabilities information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title>CD-ROM Information/Capabilities</title> + +<para> +This page displays information about the attached CD-ROM drives and their capabilites, +</para> + +<para> +On &Linux;, this information is read from <filename +class="devicefile">/proc/sys/dev/cdrom/info</filename>, which are only available if +the <filename class="directory">/proc</filename> pseudo-filesystem is +compiled into the kernel. +</para> + +<para> +The user cannot modify any settings on this page. +</para> + +</sect1> +</article> diff --git a/doc/kinfocenter/devices/Makefile.am b/doc/kinfocenter/devices/Makefile.am new file mode 100644 index 000000000..dc255fa48 --- /dev/null +++ b/doc/kinfocenter/devices/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/devices diff --git a/doc/kinfocenter/devices/index.docbook b/doc/kinfocenter/devices/index.docbook new file mode 100644 index 000000000..43eac4de9 --- /dev/null +++ b/doc/kinfocenter/devices/index.docbook @@ -0,0 +1,60 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Device Information</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>device</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title>Device Information</title> + +<para> +This page displays information about the available devices, +</para> + +<note> +<para> +The exact information displayed is system-dependent. On some systems, +device information cannot be displayed yet. +</para> +</note> + +<para> +On &Linux;, this information is read from <filename +class="devicefile">/proc/devices</filename> and <filename +class="devicefile">/proc/misc</filename>, which are only available if +the <filename class="directory">/proc</filename> pseudo-filesystem is +compiled into the kernel. Devices are listed by group (Character, Block, +or Miscellaneous). The device major number is listed, followed by an +identifying label. +</para> + +<para> +The user cannot modify any settings on this page. +</para> + +</sect1> +</article> diff --git a/doc/kinfocenter/dma/Makefile.am b/doc/kinfocenter/dma/Makefile.am new file mode 100644 index 000000000..0e2aa88e7 --- /dev/null +++ b/doc/kinfocenter/dma/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/dma diff --git a/doc/kinfocenter/dma/index.docbook b/doc/kinfocenter/dma/index.docbook new file mode 100644 index 000000000..75fb55c75 --- /dev/null +++ b/doc/kinfocenter/dma/index.docbook @@ -0,0 +1,64 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title><acronym>DMA</acronym> Channel Information</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>DMA</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title><acronym>DMA</acronym> Channel Information</title> + +<para> This page displays information about the <acronym>DMA</acronym> +(Direct Memory Access) Channels. A <acronym>DMA</acronym> channel is a +direct connection that allows devices to transfer data to and from +memory without going through the processor. Typically, i386-architecture +systems (<acronym>PC</acronym>'s) have eight <acronym>DMA</acronym> +channels (0-7). </para> + +<note> <para> The exact information displayed is system-dependent. On +some systems, <acronym>DMA</acronym> Channel information cannot be +displayed yet. </para> </note> + +<para> On &Linux;, this information is read from <filename +class="devicefile">/proc/dma</filename>, which is only available if the +<filename class="directory">/proc</filename> pseudo-filesystem is +compiled into the kernel. </para> + +<para> A list of all currently-registered (<acronym>ISA</acronym> bus) +<acronym>DMA</acronym> channels that are in use is shown. The first +column shows the <acronym>DMA</acronym> channel, and the second column +shows the device which uses that channel. </para> + +<para> +Unused <acronym>DMA</acronym> channels are not listed. +</para> + +<para> +The user cannot modify any settings on this page. +</para> + +</sect1> +</article> diff --git a/doc/kinfocenter/index.docbook b/doc/kinfocenter/index.docbook new file mode 100644 index 000000000..a62ca655d --- /dev/null +++ b/doc/kinfocenter/index.docbook @@ -0,0 +1,341 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY kappname "&kinfocenter;"> +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &infocenter;</title> + +<authorgroup> +<author> +<firstname>Michael</firstname> +<surname>McBride</surname> +<affiliation><address><email>[email protected]</email></address></affiliation> +</author> +</authorgroup> + +<date>2002-07-03</date> +<releaseinfo>3.10.00</releaseinfo> + +<abstract> +<para>This documentation describes &kde;'s information center.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kinfocenter</keyword> +<keyword>system</keyword> +<keyword>information</keyword> +<keyword>module</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>The &infocenter;</title> + +<para> +The &infocenter; (from now on referred to simply as <quote>the +information center</quote>) provides you with a centralized and convenient +overview of your &kde; and system settings. +</para> + +<para> +The information center is made up of multiple modules. Each module is a +separate application, but the information center organizes all of these +programs into a convenient location. +</para> + +</chapter> + +<chapter id="info-center"> +<title>Using The &infocenter;</title> + +<para> +This next section details the use of the information center itself. For +information on individual modules, please see <link linkend="module">Info +Center Modules</link> +</para> + +<sect1 id="information-center-starting"> +<title>Starting the &infocenter;</title> + +<para> +The &infocenter; can be started 3 ways: +</para> + +<orderedlist> +<listitem> +<para> +By selecting <menuchoice><guimenu>K +Button</guimenu><guisubmenu>System</guisubmenu><guimenuitem>Info +Center</guimenuitem></menuchoice> from the &kde; Panel. + +</para> +</listitem> +<listitem> +<para> +By pressing <keycombo +action="simul">&Alt;<keycap>F2</keycap></keycombo>. +</para> + +<para> +This will bring up a dialog box. Type +<userinput><command>kinfocenter</command></userinput>, and click +<guibutton>Run</guibutton> or press <keycap>Enter</keycap>. +</para> +</listitem> + +<listitem> +<para> +You can type <command>kinfocenter &</command> at any command prompt. +</para> +</listitem> +</orderedlist> + +<para> +All three of these methods are equivalent, and produce the same result. +</para> + +</sect1> + +<sect1 id="information-center-screen"> +<title>The &infocenter; Screen</title> + +<para> +When you start the information center, you are presented with a window, +which can be divided into 3 functional parts. +</para> + +<para> +Across the top is a menubar. The menubar will provide you with quick +access to most of &infocenter;'s features. The menus are detailed in +<link linkend="info-center-menus">The &kde; Info Center +Menus</link>. +</para> + +<para> +Along the left hand side, is a column. This is a where you choose which +module to investigate. You can learn how to navigate through the modules +in the section called <link linkend="module-intro">Navigating +Modules</link>. +</para> + +<para> +The main panel shows you some system information. +</para> + +<!-- +<para> +In this example, we are running &kde; 2.99, we started &infocenter; +as user <systemitem class="username">adridg</systemitem>, the computer is +named <systemitem class="systemname">aramis</systemitem>, it is a +FreeBSD system, Version 4.4-RELEASE, on a Pentium. +</para> --> + +</sect1> + +<sect1 id="info-center-menus"> +<title>The &infocenter; Menus</title> + +<para> +This next section gives you a brief description of what each menu item +does. +</para> + +<sect2 id="info-center-menu-file"> +<title><guimenu>File</guimenu> Menu</title> + +<para> +The <guimenu>File</guimenu> menu has a single entry. +</para> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem> +<para> +<action>Closes the info center.</action> +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="info-center-menu-help"> +<title><guimenu>Help</guimenu> Menu</title> + +&help.menu.documentation; + +</sect2> + +</sect1> + +<sect1 id="info-center-exiting"> +<title>Exiting The &kde; Information Center</title> + +<para> +You can exit the info center one of three ways: +</para> + +<itemizedlist> +<listitem> +<para> +Select <menuchoice><guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem></menuchoice> from the menu bar. +</para> +</listitem> + +<listitem> +<para>Type <keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +on the keyboard. +</para> +</listitem> + +<listitem> +<para> +Click on the <guiicon>Close</guiicon> button on the frame surrounding +the info center. +</para> +</listitem> +</itemizedlist> + +</sect1> + +</chapter> + +<!--*****************************************************************--> + +<chapter id="module"> +<title>The &infocenter; Modules</title> + +<sect1 id="module-intro"> +<title>Navigating Modules</title> + +<para> +This is a list of the <emphasis>standard</emphasis> configuration +modules (sorted by category) provided by the <application +role="package">&kde; base</application> package. Please note that there +may be many more modules on your system if you have installed additional +software. +</para> + +<itemizedlist> +<listitem> +<para><ulink url="help:/kinfocenter/devices/index.html">Devices</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/dma/index.html">DMA-Channels</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/interrupts/index.html">Interrupts</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/ioports/index.html">IO-Ports</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/memory/index.html">Memory</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/nics/index.html">Network Interfaces</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/opengl/index.html">OpenGL</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/partitions/index.html">Partitions</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/pci/index.html">PCI</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/pcmcia/index.html">PCMCIA</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/processor/index.html">Processor</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/protocols/index.html">Protocols</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/samba/index.html">Samba Status Information</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/scsi/index.html">SCSI</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/sound/index.html">Sound</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/usb/index.html">USB Devices</ulink></para> +</listitem> +<listitem> +<para><ulink url="help:/kinfocenter/xserver/index.html">X-Server</ulink></para> +</listitem> +</itemizedlist> + +</sect1> + +<!--****************************************--> + +</chapter> + +<chapter id="credits"> +<title>Credits and License</title> + +<para>&infocenter;</para> +<para>Program copyright 1997-2001 The &infocenter; Developers</para> +<para>Contributors:</para> + +<itemizedlist> +<listitem><para>Matthias Hoelzer-Kluepfel +<email>[email protected]</email></para></listitem> +<listitem><para>Matthias Elter <email>[email protected]</email></para></listitem> +</itemizedlist> + +<para>Documentation <trademark class="copyright">copyright 2000 Michael +McBride</trademark> <email>[email protected]</email></para> + +<para>Contributors:</para> + +<itemizedlist> +<listitem><para>Paul Campbell <email>[email protected]</email></para></listitem> +<listitem><para>Helge Deller <email>[email protected]</email></para></listitem> +<listitem><para>Mark Donohoe </para></listitem> +<listitem><para>Pat Dowler</para></listitem> +<listitem><para>Duncan Haldane <email>[email protected]</email></para></listitem> +<listitem><para>Steffen Hansen <email>[email protected]</email>.</para></listitem> +<listitem><para>Matthias Hoelzer-Kluepfel <email>[email protected]</email></para></listitem> +<listitem><para>Martin Jones <email>[email protected]</email></para></listitem> +<listitem><para>Jost Schenck <email>[email protected]</email></para></listitem> +<listitem><para>Jonathan Singer <email>[email protected]</email></para></listitem> +<listitem><para>Thomas Tanghus <email>[email protected]</email></para></listitem> +<listitem><para>Krishna Tateneni <email>[email protected]></email></para></listitem> +<listitem><para>Ellis Whitehead <email>[email protected]</email></para></listitem> + +</itemizedlist> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; +</chapter> + +</book> +<!-- +Local Variables: +mode: sgml +End: +--> diff --git a/doc/kinfocenter/interrupts/Makefile.am b/doc/kinfocenter/interrupts/Makefile.am new file mode 100644 index 000000000..46be8b9ce --- /dev/null +++ b/doc/kinfocenter/interrupts/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/interrupts diff --git a/doc/kinfocenter/interrupts/index.docbook b/doc/kinfocenter/interrupts/index.docbook new file mode 100644 index 000000000..b29611202 --- /dev/null +++ b/doc/kinfocenter/interrupts/index.docbook @@ -0,0 +1,70 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Interrupt Request (<abbrev>IRQ</abbrev>) Lines</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>IRQ</keyword> +<keyword>interrupts</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title>Interrupt Request (<abbrev>IRQ</abbrev>) Lines in Use</title> + +<para>This page displays information about the Interrupt Request +Lines in use, and the devices that use them.</para> + +<para>An <acronym>IRQ</acronym> is a hardware line used in a +<acronym>PC</acronym> by (<acronym>ISA</acronym> bus) devices like +keyboards, modems, sound cards, &etc;, to send interrupt signals to the +processor to tell it that the device is ready to send or accept data. +Unfortunately, there are only sixteen <acronym>IRQ</acronym>'s (0-15) +available in the i386 (<acronym>PC</acronym>) architecture for sharing among +the various <acronym>ISA</acronym> devices.</para> + +<para>Many hardware problems are the result of <acronym>IRQ</acronym> +conflicts, when two devices try to use the same <acronym>IRQ</acronym>, or +software is misconfigured to use a different <acronym>IRQ</acronym> from the +one a device is actually configured for.</para> + +<note><para>The exact information displayed is system-dependent. On some +systems, <acronym>IRQ</acronym> information cannot be displayed + yet.</para></note> + +<para>On &Linux;, this information is read from +<filename class="directory">/proc/interrupts</filename>, which is only +available if the <filename class="directory">/proc</filename> +pseudo-filesystem is compiled into the kernel.</para> + +<para>The first column, is the <acronym>IRQ</acronym> number. The second +column, is the number of interrupts that have been received since the last +reboot. The third column shows the type of interrupt. The fourth, +identifies the device assigned to that interrupt.</para> + +<para>The user cannot modify any settings on this page.</para> + +</sect1> + +</article> + diff --git a/doc/kinfocenter/ioports/Makefile.am b/doc/kinfocenter/ioports/Makefile.am new file mode 100644 index 000000000..56e830b08 --- /dev/null +++ b/doc/kinfocenter/ioports/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/ioports diff --git a/doc/kinfocenter/ioports/index.docbook b/doc/kinfocenter/ioports/index.docbook new file mode 100644 index 000000000..fa662feba --- /dev/null +++ b/doc/kinfocenter/ioports/index.docbook @@ -0,0 +1,64 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>I/O Port</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>ioports</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title>Input/Output Port Information</title> + +<para>This page displays information about the I/O ports.</para> + +<para>I/O Ports are memory addresses used by the processor for direct +communication with a device that has sent an +interrupt signal to the processor.</para> + +<para>The exchange of commands or data between the processor and the device +takes place through the I/O port address of the device, which is a + hexadecimal +number. No two devices can share the same I/O port. Many devices use + multiple +I/O port addresses, which are expressed as a range of hexadecimal +numbers. </para> + +<note><para>The exact information displayed is system-dependent. On some +systems, I/O port information can not yet be displayed.</para></note> + +<para>On &Linux;, this information is read from <filename +class="devicefile">/proc/ioports</filename> which is only available if +the <filename class="devicefile">/proc</filename> pseudo-filesystem is +compiled into the kernel. A list of all currently-registered I/O port +regions that are in use is shown.</para> + +<para>The first column is the I/O port (or the range of I/O ports), the +second column identifies the device that uses these I/O ports.</para> + +<para>The user cannot modify any settings on this page.</para> + +</sect1> +</article> diff --git a/doc/kinfocenter/memory/Makefile.am b/doc/kinfocenter/memory/Makefile.am new file mode 100644 index 000000000..e9a9e23ef --- /dev/null +++ b/doc/kinfocenter/memory/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/memory diff --git a/doc/kinfocenter/memory/index.docbook b/doc/kinfocenter/memory/index.docbook new file mode 100644 index 000000000..19d10fc57 --- /dev/null +++ b/doc/kinfocenter/memory/index.docbook @@ -0,0 +1,108 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Memory Information</title> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<date>2002-02-13</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>memory</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title>Memory Information</title> + +<para>This module displays the current memory usage. It is updated +constantly, and can be very useful for pinpointing bottlenecks when certain +applications are executed.</para> + +<sect2 id="memory-intro"> +<title>Memory Types</title> + +<para>The first thing you must understand, is there are two types of +<quote>memory</quote>, available to the operating system and the programs +that run within it.</para> + +<para>The first type, is called physical memory. This is the memory located +within the memory chips, within your computer. This is the +<acronym>RAM</acronym> (for Random Access Memory) you bought when you +purchased your computer.</para> + +<para>The second type of memory, is called virtual or swap memory. This +block of memory, is actually space on the hard drive. The operating +system reserves a space on the hard drive for <quote>swap space</quote>. +The operating system can use this virtual memory (or swap space), if it +runs out of physical memory. The reason this is called +<quote>swap</quote> memory, is the operating system takes some data that +it doesn't think you will want for a while, and saves that to disk in +this reserved space. The operating system then loads the new data you +need right now. It has <quote>swapped</quote> the not needed data, for +the data you need right now. Virtual or swap memory is not as fast as +physical memory, so operating systems try to keep data (especially often +used data), in the physical memory.</para> + +<para>The total memory, is the combined total of physical memory and +virtual memory.</para> + +</sect2> + +<sect2 id="memory-use"> +<title>Memory Information Module</title> + +<para>This window is divided into a top and bottom section</para> + +<para>The top section shows you the total physical memory, total free + physical memory, shared memory, and buffered memory.</para> + +<para>All four values are represented as the total number of bytes, and + as the number of megabytes (1 megabyte = slightly more than 1,000,000 + bytes)</para> + +<para>The bottom section shows you three graphs: </para> + +<itemizedlist> +<listitem><para><guilabel>Total Memory</guilabel> (this is the combination of physical and virtual memory).</para></listitem> +<listitem><para><guilabel>Physical Memory</guilabel></para></listitem> +<listitem><para>Virtual memory, or <guilabel>Swap Space</guilabel>.</para></listitem> +</itemizedlist> + +<para>The green areas are free, and the red areas are used.</para> + +<tip><para>The exact values of each type of memory are not critical, and + they change regularly. When you evaluate this page, look at + trends.</para> + +<para>Does your computer have plenty of free space (green areas)? If + not, you can increase the swap size or increase the physical + memory.</para> + +<para>Also, if your computer seems sluggish: is your physical memory + full, and does the hard drive always seem to be running? This suggests + that you do not have enough physical memory, and your computer is + relying on the slower virtual memory for commonly used data. Increasing + your physical memory will improve the responsiveness of your + computer.</para></tip> + +</sect2> + +</sect1> + +</article> diff --git a/doc/kinfocenter/nics/Makefile.am b/doc/kinfocenter/nics/Makefile.am new file mode 100644 index 000000000..73ab1b332 --- /dev/null +++ b/doc/kinfocenter/nics/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/nics diff --git a/doc/kinfocenter/nics/index.docbook b/doc/kinfocenter/nics/index.docbook new file mode 100644 index 000000000..f82552c28 --- /dev/null +++ b/doc/kinfocenter/nics/index.docbook @@ -0,0 +1,45 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Network Interfaces</title> +<articleinfo> + +<authorgroup> +<author>&Lauri.Watts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-11</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>Network</keyword> +<keyword>Interfaces</keyword> +</keywordset> +</articleinfo> + +<sect1> + +<title>Network Interfaces</title> + +<para> +This page displays information about the network interfaces +installed in your computer. +</para> + +<note><para>The exact information displayed is system-dependent. On +some systems, this information can not yet be displayed.</para></note> + +<para>The user cannot modify any settings on this page.</para> + + +</sect1> + +</article> diff --git a/doc/kinfocenter/opengl/Makefile.am b/doc/kinfocenter/opengl/Makefile.am new file mode 100644 index 000000000..cc8923bc3 --- /dev/null +++ b/doc/kinfocenter/opengl/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG= en +KDE_DOCS = kinfocenter/opengl diff --git a/doc/kinfocenter/opengl/index.docbook b/doc/kinfocenter/opengl/index.docbook new file mode 100644 index 000000000..62af34008 --- /dev/null +++ b/doc/kinfocenter/opengl/index.docbook @@ -0,0 +1,47 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title><acronym>OpenGL</acronym></title> +<articleinfo> + +<authorgroup> +<author><personname><firstname>Ilya</firstname><surname>Korniyko</surname></personname><email>[email protected]</email></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<date></date> +<releaseinfo></releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>OpenGL</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1 id="opengl"> + +<title>OpenGL</title> + +<para>This page displays information about installed <acronym>OpenGL</acronym> implementation. +OpenGL (for "Open Graphics Library") is a cross-platform, +hardware independent interface for 3D graphics. </para> + +<para><acronym>GLX</acronym> is the binding for OpenGL to X Window system.</para> + +<para> <acronym>DRI</acronym> (Direct Rendering Infrastucture) provides hardware acceleration for OpenGL. +You must have a videocard with 3D accelerator and properly installed driver for this.</para> +<para> </para> + +<para>Read more at the official OpenGL site <ulink url="http://www.opengl.org">http://www.opengl.org</ulink> </para> + +</sect1> + +</article> diff --git a/doc/kinfocenter/partitions/Makefile.am b/doc/kinfocenter/partitions/Makefile.am new file mode 100644 index 000000000..7eab338b4 --- /dev/null +++ b/doc/kinfocenter/partitions/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/partitions diff --git a/doc/kinfocenter/partitions/index.docbook b/doc/kinfocenter/partitions/index.docbook new file mode 100644 index 000000000..f3655a8cf --- /dev/null +++ b/doc/kinfocenter/partitions/index.docbook @@ -0,0 +1,56 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Partition Information</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>drive partition</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title>Partition Information</title> + +<para>This page displays information about partitions on your hard +drives.</para> + +<note><para>The exact information displayed is system-dependent. On +some systems, partition information cannot be displayed +yet.</para></note> + +<para>On &Linux;, this information is read from <filename +class="devicefile">/proc/partitions</filename>, which is only available +if the <filename class="directory">/proc</filename> pseudo-filesystem is +compiled into the (2.1.x or later) kernel.</para> + +<para>The first two columns are the major and minor numbers +respectively. The third column is the number of blocks (usually 1 +block = 1024 bytes). The fourth column is a label for the +device.</para> + +<para>The user cannot modify any settings on this page.</para> + +</sect1> + +</article> + diff --git a/doc/kinfocenter/pci/Makefile.am b/doc/kinfocenter/pci/Makefile.am new file mode 100644 index 000000000..b6702265a --- /dev/null +++ b/doc/kinfocenter/pci/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/pci diff --git a/doc/kinfocenter/pci/index.docbook b/doc/kinfocenter/pci/index.docbook new file mode 100644 index 000000000..1d4d8b3f9 --- /dev/null +++ b/doc/kinfocenter/pci/index.docbook @@ -0,0 +1,57 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title><acronym>PCI</acronym>-bus and Installed <acronym>PCI</acronym> Cards</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>PCI</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1 id="pci"> + +<title><acronym>PCI</acronym>-bus and Installed <acronym>PCI</acronym> +Cards</title> + +<para>This page displays information about the +<acronym>PCI</acronym>-bus and installed <acronym>PCI</acronym> cards, +and other devices that use the Peripheral Component Interconnect +(<acronym>PCI</acronym>) bus.</para> + +<note><para>The exact information displayed is system-dependent. On some +systems, <acronym>PCI</acronym>-information can not yet be +displayed.</para> </note> + +<para>On &Linux;, this information is read from <filename +class="devicefile">/proc/pci</filename> which is only available if the +<filename class="directory">/proc</filename> pseudo-filesystem is +compiled into the kernel. A listing of all <acronym>PCI</acronym> +devices found during kernel initialization, and their configuration, is +shown.</para> + +<para>Each entry begins with a bus, device and function number.</para> +<para>The user cannot modify any settings on this page.</para> + +</sect1> + +</article> diff --git a/doc/kinfocenter/pcmcia/Makefile.am b/doc/kinfocenter/pcmcia/Makefile.am new file mode 100644 index 000000000..23040b3c9 --- /dev/null +++ b/doc/kinfocenter/pcmcia/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/pcmcia diff --git a/doc/kinfocenter/pcmcia/index.docbook b/doc/kinfocenter/pcmcia/index.docbook new file mode 100644 index 000000000..901fdf2e5 --- /dev/null +++ b/doc/kinfocenter/pcmcia/index.docbook @@ -0,0 +1,38 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title><acronym>PCMCIA</acronym></title> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>Laptop</keyword> +<keyword>PCMCIA</keyword> +</keywordset> +</articleinfo> + +<sect1 id="pcmcia"> +<title><acronym>PCMCIA</acronym></title> + +<para>This module displays information about <acronym>PCMCIA</acronym> +Cards</para> + +<para>The exact information is system dependent. On most systems no +information is displayed at all.</para> + +</sect1> +</article> diff --git a/doc/kinfocenter/processor/Makefile.am b/doc/kinfocenter/processor/Makefile.am new file mode 100644 index 000000000..7cdf67a93 --- /dev/null +++ b/doc/kinfocenter/processor/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/processor diff --git a/doc/kinfocenter/processor/index.docbook b/doc/kinfocenter/processor/index.docbook new file mode 100644 index 000000000..3794aca67 --- /dev/null +++ b/doc/kinfocenter/processor/index.docbook @@ -0,0 +1,56 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Processor Information</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>CPU</keyword> +<keyword>processor</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1 id="processor"> +<title>Processor Information</title> + +<para>This page displays information about the system +Central Processing Unit (<acronym>CPU</acronym>).</para> + +<note><para>The exact information displayed is system-dependent. On +some systems, processor information cannot be displayed +yet.</para></note> + +<para>On &Linux;, this information is read from <filename +class="devicefile">/proc/cpuinfo</filename>, which is only available if +the <filename class="directory">/proc</filename> pseudo-filesystem is +compiled into the kernel.</para> + +<para>The exact contents of the window will depend on the +<acronym>CPU</acronym>(s) in your machine, but the window is organized +into two columns. The first column is the parameter, and the second +column is the value of that parameter.</para> + +<para>The user cannot modify any settings on this page.</para> + +</sect1> + +</article> diff --git a/doc/kinfocenter/protocols/Makefile.am b/doc/kinfocenter/protocols/Makefile.am new file mode 100644 index 000000000..afc73fa8a --- /dev/null +++ b/doc/kinfocenter/protocols/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/protocols diff --git a/doc/kinfocenter/protocols/index.docbook b/doc/kinfocenter/protocols/index.docbook new file mode 100644 index 000000000..a5a37658b --- /dev/null +++ b/doc/kinfocenter/protocols/index.docbook @@ -0,0 +1,39 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Protocols</title> + +<articleinfo> +<authorgroup> +<author>&Lauri.Watts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Protocols</keyword> +<keyword>IOSlaves</keyword> +</keywordset> +</articleinfo> + +<sect1 id="protocols"> +<title>Protocols</title> + +<para>On the left of the panel you will see a list of the IOSlaves that +are installed on your system. IOSlaves are how &kde; applications +<quote>talk</quote> to other computers, other applications, or act on +files.</para> + +<para>Clicking on an IOSlave name will display some help information +about that IOSlave, such as how to use it, and what it does.</para> + +<para>The protocols module is purely informational, you cannot change +any settings here.</para> + +</sect1> +</article>
\ No newline at end of file diff --git a/doc/kinfocenter/samba/Makefile.am b/doc/kinfocenter/samba/Makefile.am new file mode 100644 index 000000000..91de8fa54 --- /dev/null +++ b/doc/kinfocenter/samba/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/samba + diff --git a/doc/kinfocenter/samba/index.docbook b/doc/kinfocenter/samba/index.docbook new file mode 100644 index 000000000..37b14c48c --- /dev/null +++ b/doc/kinfocenter/samba/index.docbook @@ -0,0 +1,207 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Samba Status Information</title> +<articleinfo> +<authorgroup> +<author>&Alexander.Neundorf;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>Samba</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1 id="sambastatus"> + + +<title>Samba Status Information</title> + +<para>The Samba and <acronym>NFS</acronym> Status Monitor is a front end +to the programs <command>smbstatus</command> and +<command>showmount</command>. Smbstatus reports on current Samba +connections, and is part of the suite of Samba tools, which implements +the <acronym>SMB</acronym> (Session Message Block) protocol, also called +the NetBIOS or LanManager protocol.</para> + +<para>This protocol can be used to provide printer sharing or drive +sharing services on a network including machines running the various +flavors of &Microsoft; &Windows;.</para> + +<para><command>showmount</command> is part of the <acronym>NFS</acronym> +software package. <acronym>NFS</acronym> stands for Network File System +and is the traditional &UNIX; way to share folders over the +network. In this case the output of <command>showmount</command> +<option>-a localhost</option> is parsed. On some systems showmount is in +<filename class="directory">/usr/sbin</filename>, check if you have +showmount in your <envar>PATH</envar>.</para> + +<sect2 id="smb-exports"> +<title>Exports</title> + +<para>On this page you can see a big list which shows the currently +active connections to Samba shares and <acronym>NFS</acronym> exports of +your machine. The first column shows you whether the resource is a Samba +(<acronym>SMB</acronym>) share or a <acronym>NFS</acronym> export. The +second column contains the name of the share, the third the name of the +remote host, which accesses this share. The remaining columns have only +a meaning for Samba-shares.</para> + +<para>The fourth column contains the User <abbrev>ID</abbrev> of the +user, who accesses this share. Note that this does not have to be equal +to the &UNIX; user <abbrev>ID</abbrev> of this user. The same applies +for the next column, which displays the group <abbrev>ID</abbrev> of the +user.</para> + +<para>Each connection to one of your shares is handled by a single +process (<command>smbd</command>), the next column shows the process +<abbrev>ID</abbrev> (<acronym>pid</acronym>) of this +<command>smbd</command>. If you kill this process the connected user +will be disconnected. If the remote user works from &Windows;, as soon +as this process is killed a new one will be created, so he will almost +not notice it.</para> + +<para>The last column shows how many files this user has currently open. +Here you see only, how many files he has <emphasis>open</emphasis> just +now, you don't see how many he copied or formerly opened &etc;</para> + +</sect2> + +<sect2 id="smb-imports"> +<title>Imports</title> + +<para> Here you see which Samba- and <acronym>NFS</acronym>-shares from +other hosts are mounted on your local system. The first column shows +wether it is a Samba- or <acronym>NFS</acronym>-share, the second column +displays the name of the share, and the third shows where it is +mounted.</para> + +<para>The mounted <acronym>NFS</acronym>-shares you should see on +&Linux; (this has been tested), and it should also work on &Solaris; +(this has not been tested).</para> + +</sect2> + +<sect2 id="smb-log"> +<title>Log</title> + +<para>This page presents the contents of your local samba log file in a +nice way. If you open this page, the list will be empty. You have to +press the <guibutton>Update</guibutton> button, then the samba log file +will be read and the results displayed. Check whether the samba log file +on your system is really at the location as specified in the input +line. If it is somewhere else or if it has another name, correct +it. After changing the file name you have to press +<guibutton>Update</guibutton> again.</para> + +<para>Samba logs its actions according to the log level (see +<filename>smb.conf</filename>). If loglevel = 1, samba logs only when +somebody connects to your machine and when this connection is closed +again. If log level = 2, it logs also if somebody opens a file and if he +closes the file again. If the log level is higher than 2, yet more +stuff is logged.</para> + +<para>If you are interested in who accesses your machine, and which +files are accessed, you should set the log level to 2 and regularly +create a new samba log file (⪚ set up a <command>cron</command> task +which once a week moves your current samba log file into another +folder or something like that). Otherwise your samba log file may +become very big.</para> + +<para>With the four checkboxes below the big list you can decide, which +events are displayed in the list. You have to press +<guibutton>Update</guibutton> to see the results. If the log level of +your samba is too low, you won't see everything.</para> + +<para>By clicking on the header of one column you can sort the list by +this column.</para> + +</sect2> + + +<sect2 id="smb-statistics"> +<title>Statistics</title> + +<para>On this page you can filter the contents of the third page for +certain contents.</para> + +<para>Let's say the <guilabel>Event</guilabel> field (not the one in the +list) is set to <userinput>Connection</userinput>, +<guilabel>Service/File</guilabel> is set to <userinput>*</userinput>, +<guilabel>Host/User</guilabel> is set to <userinput>*</userinput>, +<guilabel>Show expanded service info</guilabel> is disabled and +<guilabel>Show expanded host info</guilabel> is disabled.</para> + +<para>If you press <guibutton>Update</guibutton> now, you will see how +often a connection was opened to share <literal>*</literal> (&ie; to any +share) from host <literal>*</literal> (&ie; from any host). Now enable +<guilabel>Show expanded host info</guilabel> and press +<guibutton>Update</guibutton> again. Now you will see for every host +which matches the wildcard <literal>*</literal>, how many connections +were opened by him.</para> + +<para>Now press <guibutton>clear</guibutton>.</para> + +<para>Now set the <guilabel>Event</guilabel> field to File Access and +enable <guilabel>Show expanded service info</guilabel> and press +<guibutton>Update</guibutton> again.</para> + +<para>Now you will see how often every single file was accessed. If you +enable <guilabel>Show expanded host info</guilabel> too, you will see +how often every single user opened each file.</para> + +<para>In the input lines <guilabel>Service/File</guilabel> and +<guilabel>Host/User</guilabel> you can use the wildcards +<literal>*</literal> and <literal>?</literal> in the same way you use +them at the command line. Regular expressions are not +recognized.</para> + +<para>By clicking on the header of a column you can sort the list by +this column. This way you can check out which file was opened most +often, or which user opened the most files or whatever.</para> + +</sect2> + + +<sect2 id="smb-stat-author"> +<title>Section Author</title> + +<para>Module copyright 2000: Michael Glauche and &Alexander.Neundorf; &Alexander.Neundorf.mail;</para> + +<para>Originally written by: Michael Glauche</para> + +<para>Currently maintained by: &Alexander.Neundorf; &Alexander.Neundorf.mail;</para> + +<itemizedlist> +<title>Contributors</title> +<listitem><para>Conversion to kcontrol applet:</para> +<para>&Matthias.Hoelzer-Kluepfel; &Matthias.Hoelzer-Kluepfel.mail;</para></listitem> +<listitem><para>Use of <classname>KProcess</classname> instead of popen, and more error checking:</para> +<para>&David.Faure; &David.Faure.mail;</para></listitem> +<listitem><para>Conversion to kcmodule, added tab pages 2,3,4, bug +fixed:</para> +<para>&Alexander.Neundorf; &Alexander.Neundorf.mail;</para></listitem> +</itemizedlist> + +<para>Documentation copyright 2000 &Alexander.Neundorf; &Alexander.Neundorf.mail;</para> + +<para>Documentation translated to docbook by &Mike.McBride; &Mike.McBride.mail;</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +</sect2> +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kinfocenter/scsi/Makefile.am b/doc/kinfocenter/scsi/Makefile.am new file mode 100644 index 000000000..09cdb4e25 --- /dev/null +++ b/doc/kinfocenter/scsi/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = kinfocenter/scsi diff --git a/doc/kinfocenter/scsi/index.docbook b/doc/kinfocenter/scsi/index.docbook new file mode 100644 index 000000000..87ec0934f --- /dev/null +++ b/doc/kinfocenter/scsi/index.docbook @@ -0,0 +1,56 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title><acronym>SCSI</acronym> Interface Information</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>SCSI</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1 id="scsi"> + +<title><acronym>SCSI</acronym> Interface Information</title> + +<para>This page displays information about Small Computer Systems +Interface (<acronym>SCSI</acronym>) Interfaces and the attached +<acronym>SCSI</acronym> devices.</para> + +<note><para>The exact information displayed is system-dependent. On +some systems <acronym>SCSI</acronym> information cannot be displayed +yet.</para></note> + +<para>On &Linux;, this information is read from <filename +class="devicefile">/proc/scsi/scsi</filename>, which is only available +if the <filename class="directory">/proc</filename> pseudo-filesystem is +compiled into the kernel. A listing of all <acronym>SCSI</acronym> +devices known to the kernel is shown.</para> + +<para>The devices are sorted numerically by their host, channel, and +<acronym>ID</acronym> numbers.</para> + +<para>The user cannot modify any settings on this page.</para> + +</sect1> + +</article> diff --git a/doc/kinfocenter/sound/Makefile.am b/doc/kinfocenter/sound/Makefile.am new file mode 100644 index 000000000..611f571ca --- /dev/null +++ b/doc/kinfocenter/sound/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/sound diff --git a/doc/kinfocenter/sound/index.docbook b/doc/kinfocenter/sound/index.docbook new file mode 100644 index 000000000..de1fd601d --- /dev/null +++ b/doc/kinfocenter/sound/index.docbook @@ -0,0 +1,51 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title>Soundcard Information</title> +<articleinfo> + +<authorgroup> +<author>&Matthias.Hoelzer-Kluepfel;</author> +<author>&Helge.Deller;</author> +<author>&Duncan.Haldane;</author> +<author>&Mike.McBride;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>soundcard</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1 id="soundinfo"> + +<title>Soundcard Information</title> + +<para>This page displays information about any soundcards installed in the +system.</para> + +<note><para>The exact information displayed is system-dependent. On some +systems, soundcard information cannot be displayed yet.</para></note> + +<para>On &Linux;, this information is read either from <filename +class="devicefile">/dev/sndstat</filename>, if present, or from +<filename class="devicefile">/proc/sound</filename>, which is only +available if the <filename class="directory">/proc</filename> +pseudo-filesystem is compiled into the (2.1.x or later) kernel.</para> + +<para>The user cannot modify any settings on this page.</para> + +</sect1> + +</article> diff --git a/doc/kinfocenter/usb/Makefile.am b/doc/kinfocenter/usb/Makefile.am new file mode 100644 index 000000000..80cc84914 --- /dev/null +++ b/doc/kinfocenter/usb/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/usb diff --git a/doc/kinfocenter/usb/index.docbook b/doc/kinfocenter/usb/index.docbook new file mode 100644 index 000000000..8936fa796 --- /dev/null +++ b/doc/kinfocenter/usb/index.docbook @@ -0,0 +1,43 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;"> +<title><acronym>USB</acronym></title> +<articleinfo> + +<authorgroup> +<author> +<firstname></firstname> +<surname></surname> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KControl</keyword> +<keyword>USB</keyword> +<keyword>System Information</keyword> +</keywordset> +</articleinfo> + +<sect1 id="usb"> + +<title><acronym>USB</acronym></title> + +<para>This module allows you to see the devices attached to your +<acronym>USB</acronym> bus(es).</para> + +<para>This module is for information only, you cannot edit any +information you see here.</para> +</sect1> + +</article>
\ No newline at end of file diff --git a/doc/kinfocenter/xserver/Makefile.am b/doc/kinfocenter/xserver/Makefile.am new file mode 100644 index 000000000..f72dcdbbf --- /dev/null +++ b/doc/kinfocenter/xserver/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG= en +KDE_DOCS = kinfocenter/xserver diff --git a/doc/kinfocenter/xserver/index.docbook b/doc/kinfocenter/xserver/index.docbook new file mode 100644 index 000000000..a56e47fb3 --- /dev/null +++ b/doc/kinfocenter/xserver/index.docbook @@ -0,0 +1,56 @@ +<?xml version="1.0" ?> +<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<article lang="&language;" id="xserver"> +<title>X Server Information</title> +<articleinfo> + +<authorgroup> +<author>&Mike.McBride;</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<date>2002-02-12</date> +<releaseinfo>3.00.00</releaseinfo> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KControl</keyword> +<keyword>X server</keyword> +<keyword>system information</keyword> +</keywordset> +</articleinfo> + +<sect1> +<title>X Server Information</title> + +<para>This screen is useful for getting specific information about your +X server and the current session of X.</para> + +<para>When you open this module, you are presented with some +information. The left hand side of the window is organized into a +tree. Some of the elements have a plus sign in front of the label. +Clicking this sign opens a <quote>submenu</quote> related to the +label. Clicking on a minus sign in front of a label hides the +submenu.</para> + +<para>The right hand side of the window contains the individual +values for each of the parameters on the left.</para> + +<para>The information presented will vary depending on your +setup.</para> + +<note><para>Some setups may not be able to determine some or all of the +parameters.</para></note> + +<para>You can not change any values from this menu. It is for +information only.</para> + +</sect1> +</article> diff --git a/doc/kioslave/Makefile.am b/doc/kioslave/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kioslave/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kioslave/bzip.docbook b/doc/kioslave/bzip.docbook new file mode 100644 index 000000000..9a3dc90cb --- /dev/null +++ b/doc/kioslave/bzip.docbook @@ -0,0 +1,29 @@ +<article lang="&language;" id="bzip"> +<title>bzip</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para><command>bzip</command> is a compression program. It is rarely +used today, having been replaced with bzip2, which offers much better +compression.</para> + +<para>The bzip kioslave is not directly usable, and is intended for use +as a filter. For example, the tar kioslave can filter a file through +the bzip kioslave, in order to display the contents of a <literal +role="extension">tar.bz</literal> file directly in a &konqueror; +window.</para> + +<para>If you click on a file compressed with a <literal +role="extension">bz</literal> extension in &konqueror;, this kioslave is +used to uncompress it and display it as a normal (uncompressed) +file.</para> + +<para>If you are a developer, and would like to use the bzip filter, +you can find documentation on using kioslaves at <ulink +url="http://developer.kde.org">http://developer.kde.org</ulink></para> + +</article> diff --git a/doc/kioslave/bzip2.docbook b/doc/kioslave/bzip2.docbook new file mode 100644 index 000000000..9551632a5 --- /dev/null +++ b/doc/kioslave/bzip2.docbook @@ -0,0 +1,29 @@ +<article lang="&language;" id="bzip2"> +<title>bzip2</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para>Bzip2 is a compression program</para> + +<para>The bzip2 kioslave is not directly usable, and is intended for use +as a filter. For example, the tar kioslave can filter a file through +the bzip2 kioslave, in order to display the contents of a <literal +role="extension">tar.bz2</literal> file directly in a &konqueror; +window.</para> + +<para>If you click on a file compressed with a <literal +role="extension">.bz2</literal> in &konqueror;, this kioslave is used to +uncompress it and display it as a normal (uncompressed) file.</para> + +<para>If you are a developer, and would like to use the bzip2 filter, +you can find documentation on using kioslaves at <ulink +url="http://developer.kde.org">http://developer.kde.org</ulink></para> + +<para> See the manual: <ulink url="man:/bzip2">bzip2</ulink>. +</para> + +</article> diff --git a/doc/kioslave/cgi.docbook b/doc/kioslave/cgi.docbook new file mode 100644 index 000000000..5df94da13 --- /dev/null +++ b/doc/kioslave/cgi.docbook @@ -0,0 +1,24 @@ +<article lang="&language;" id="cgi"> +<title>cgi</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts;&Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para>The <acronym>CGI</acronym> slave provides a way to execute +<acronym>CGI</acronym> programs without the need to have a running web +server. This can for example be used for local testing of +<acronym>CGI</acronym> programs or for using search engines that only +provide a <acronym>CGI</acronym> frontend like the one from +<application>Doxygen</application>.</para> + +<para>The slave implements the <command>cgi:</command> protocol. It +uses the filename from the given &URL; and searches a configurable +list of folders. If it finds an executable with the given name it +executes it, passes the arguments of the &URL; and sets the +environment variables needed by <acronym>CGI</acronym> +programs.</para> + +</article> diff --git a/doc/kioslave/data.docbook b/doc/kioslave/data.docbook new file mode 100644 index 000000000..ca0e4e9a5 --- /dev/null +++ b/doc/kioslave/data.docbook @@ -0,0 +1,47 @@ +<article lang="&language;" id="data"> +<title>Data URLs</title> + +<articleinfo> +<authorgroup> +<author><personname><firstname>Leo</firstname><surname>Savernik</surname></personname> +<address><email>[email protected]</email></address> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-02-06</date> +<!--releaseinfo>2.20.00</releaseinfo--> + +</articleinfo> + +<para>Data URLs allow small document data to be included in the URL itself. +This is useful for very small HTML testcases or other occasions that do not +justify a document of their own.</para> + +<para><userinput>data:,foobar</userinput> +(note the comma after the colon) will deliver a text document that contains +nothing but <literal>foobar</literal> +</para> + +<para>The last example delivered a text document. For HTML documents one +has to specify the MIME type <literal>text/html</literal>: +<userinput>data:text/html,<title>Testcase</title><p>This +is a testcase</p></userinput>. This will produce exactly the same +output as if the content had been loaded from a document of its own. +</para> + +<para>Specifying alternate character sets is also possible. Note that 8-Bit +characters have to be escaped by a percentage sign and their two-digit +hexadecimal codes: +<userinput>data:;charset=iso-8859-1,Gr%FC%DFe aus Schl%E4gl</userinput> +results in +<literal>Grüße aus Schlägl</literal> +whereas omitting the charset attribute might lead to something like +<literal>Gr??e aus Schl?gl</literal> +</para> + +<para><ulink url="http://www.ietf.org/rfc/rfc2397.txt">IETF +RFC2397</ulink> provides more information.</para> + +</article> + diff --git a/doc/kioslave/file.docbook b/doc/kioslave/file.docbook new file mode 100644 index 000000000..a9031a259 --- /dev/null +++ b/doc/kioslave/file.docbook @@ -0,0 +1,20 @@ +<article lang="&language;" id="file"> +<title>file</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para> +The <emphasis>file</emphasis> protocol is used by all &kde; applications to +display locally available files. +</para> +<para> +Entering +<userinput><command>file:/directoryname</command></userinput> in &konqueror; + lists the files of this folder. +</para> + +</article> diff --git a/doc/kioslave/finger.docbook b/doc/kioslave/finger.docbook new file mode 100644 index 000000000..27b278c48 --- /dev/null +++ b/doc/kioslave/finger.docbook @@ -0,0 +1,33 @@ +<article lang="&language;" id="finger"> +<title>finger</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts;&Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para>Finger is a program to display information about users.</para> + +<para>If finger is enabled on the remote machine, you may be given +information on the user's real name, if they are currently logged in, if +they have mail and the text of their <filename>.plan</filename> file in +their home folder.</para> + +<para>Finger is normally associated with a user@hostname address, which +may or may not be the same as a users email address.</para> + +<para>Most Internet Service Providers no longer allow finger access, so, +you may find that you get no useful answer for most people.</para> + +<para>Other people use their local <filename>.plan</filename> file to +hold such information as <acronym>PGP</acronym> keys, the fact they are +on vacation, and all sorts of information.</para> + +<para>Use the finger kioslave like this: +<userinput>finger://<replaceable>username</replaceable>@<replaceable>hostname</replaceable></userinput></para> + +<para> See the manual: <ulink url="man:/finger">finger</ulink>. +</para> + +</article> diff --git a/doc/kioslave/fish.docbook b/doc/kioslave/fish.docbook new file mode 100644 index 000000000..5063abd04 --- /dev/null +++ b/doc/kioslave/fish.docbook @@ -0,0 +1,66 @@ +<article lang="&language;" id="fish"> +<title>fish</title> +<articleinfo> +<authorgroup> +<author>&Joerg.Walter; &Joerg.Walter.mail;</author> +<author>&Brad.Hards; &Brad.Hards.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-02-29</date> +<releaseinfo>1.1.2</releaseinfo> + +</articleinfo> + +<para>Allows you to access another computer's files using the SEcure Shell (<acronym>SSH</acronym>) protocol. The remote computer needs to be running the <acronym>SSH</acronym> daemon, but the remainder of the protocol uses standard commandline tools as discussed below.</para> + +<para>You can use the fish kioslave like this: +<userinput>fish://<replaceable>hostname</replaceable></userinput> or <userinput>fish://<replaceable>username</replaceable>@<replaceable>hostname</replaceable></userinput>.</para> + +<note><para>You need to use double forward slashes.</para></note> + +<para>You can omit the <replaceable>username</replaceable> (and the trailing +@ symbol) if you have the same username on both computers.</para> + +<para>You can add a password in the format: +<userinput>fish://<replaceable>username</replaceable>:<replaceable>password</replaceable>@<replaceable>hostname</replaceable></userinput> +but it is not necessary as you will be prompted for one if it is not +supplied.</para> + +<para>If you are running the <acronym>SSH</acronym> daemon on a non-standard +port, you can specify that port using the normal &URL; syntax as shown +below: +<userinput>fish://<replaceable>hostname</replaceable>:<replaceable>portnumber</replaceable></userinput>.</para> + +<para>Fish should work with any roughly <acronym>POSIX</acronym> compatible +&UNIX; based remote computer. It uses the shell commands +<command>cat</command>, <command>chgrp</command>, +<command>chmod</command>, <command>chown</command>, +<command>cp</command>, <command>dd</command>, +<command>env</command>, <command>expr</command>, +<command>grep</command>, <command>ls</command>, +<command>mkdir</command>, <command>mv</command>, +<command>rm</command>, <command>rmdir</command>, +<command>sed</command>, +and <command>wc</command>. Fish starts +<command>/bin/sh</command> as its shell and expects it to be a +Bourne shell (or compatible, like <command>bash</command>). +If the <command>sed</command> and +<command>file</command> commands are available, as well as a +<filename>/etc/apache/magic</filename> file with &MIME; type +signatures, these will be used to guess &MIME; types. +</para> + +<para>If <application>Perl</application> is available on the remote +machine, it will be used instead. Then only <command>env</command> and +<command>/bin/sh</command> are needed. Using +<application>Perl</application> has the additional benefit of being +faster.</para> + +<para>Fish may even work on &Windows; machines, if tools like +<application>Cygwin</application> are installed. All the above +utilities must be in the system <envar>PATH</envar>, and the initial +shell must be able to process the command <command>echo +FISH:;/bin/sh</command> correctly.</para> + +</article> diff --git a/doc/kioslave/floppy.docbook b/doc/kioslave/floppy.docbook new file mode 100644 index 000000000..ff32c217c --- /dev/null +++ b/doc/kioslave/floppy.docbook @@ -0,0 +1,51 @@ +<article lang="&language;" id="floppy"> +<title>Floppy</title> +<articleinfo> +<authorgroup> +<author>&Alexander.Neundorf; &Alexander.Neundorf.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para> +The floppy ioslave gives you easy access to the floppy disk drives +installed on your system. +</para> + +<para> +The drive letter becomes the first subdirectory +in the floppy &URL;. Let's say there is a file <filename>logo.png</filename> on your floppy +disk in drive A, then the &URL; will be <userinput><command>floppy:</command><replaceable>/a/logo.png</replaceable></userinput> +</para> + +<para> +If you want to access drive B, <userinput><command>floppy:/b</command></userinput> will do it. +<command>floppy:/</command> is a shortcut for <command>floppy:/a</command>. +</para> + +<note><para>Note that <command>floppy:/logo.png</command> means you have a disk drive +named <filename>logo.png</filename>.</para></note> + +<para> +To use it you need to have the mtools package +installed, and the floppy ioslave supports everything the various mtools +command line utilities support. You don't have to mount your floppy disks, +simply enter <userinput>floppy:/</userinput> in any &kde; 3.x app and you will be able to +read from and write to your floppy drive.</para> + +<para> +It also works with USB sticks, ZIP and JAZ drives. +You can use <command>floppy:/u</command> for the USB stick and <command>floppy:/z</command> for the zip drive, for example. +To make this work, you might need to adjust your <filename>/etc/mtools</filename> file. See the manpage +for documentation. +</para> + +<para>The ioslave gives read and write access to the floppy drive, but not +simultaneously. While you can read and write to the floppy during the same +session, reading and writing have to happen one after the other, not at the same +time.</para> + +<para>Author: Alexander Neundorf <email>[email protected]</email></para> + +</article> + diff --git a/doc/kioslave/ftp.docbook b/doc/kioslave/ftp.docbook new file mode 100644 index 000000000..3d4114850 --- /dev/null +++ b/doc/kioslave/ftp.docbook @@ -0,0 +1,43 @@ +<article id="ftp"> +<title>&FTP;</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para> +&FTP; is the Internet service used to transfer a data file from the disk of +one computer to the disk of another, regardless of the operating system type. +</para> + +<para> Similar to other Internet applications, &FTP; uses the +client-server approach — a user invokes an &FTP; program on the +computer, instructs it to contact a remote computer, and then requests +the transfer of one or more files. The local &FTP; program becomes a +client that uses <acronym>TCP</acronym> to contact an &FTP; server +program on the remote computer. Each time the user requests a file +transfer, the client and the server programs cooperate to send a copy +of the data across the Internet. </para> + +<para> &FTP; servers which allow <quote>anonymous &FTP;</quote> permit +any user, not only users with accounts on the host, to browse the +<quote>ftp</quote> archives and download files. Some &FTP; servers are +configured to allow users to upload files. </para> + +<para> +&FTP; is commonly used to retrieve information and obtain software stored in +files at &FTP; archive sites throughout the world. +</para> + + +<para> +Source: Paraphrased from <ulink +url="http://tlc.nlm.nih.gov/resources/tutorials/internetdistlrn/ftpdef.htm"> +http://tlc.nlm.nih.gov/resources/tutorials/internetdistlrn/ftpdef.htm</ulink> +</para> + +<para> See the manual: <ulink url="man:/ftp">ftp</ulink>.</para> + +</article> diff --git a/doc/kioslave/gopher.docbook b/doc/kioslave/gopher.docbook new file mode 100644 index 000000000..29e418faf --- /dev/null +++ b/doc/kioslave/gopher.docbook @@ -0,0 +1,39 @@ +<article lang="&language;" id="gopher"> +<title>gopher</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para> +<command>gopher</command> began as a distributed campus information service +at the University of Minnesota. Gopher allows the user to access information +on Gopher servers running on Internet hosts.</para> + +<para> +Gopher is an Internet information browsing service that uses a menu-driven +interface. Users select information from menus, which may return another +menu or display a text file. An item may reside on a Gopher server you +originally queried, or it may be on another Gopher server (or another host). +Gopher can <quote>tunnel</quote> from one Gopher to another without the +user knowing that the server and/or host machine have changed. Gopher keeps +the exact location of computers hidden from the user, providing the +<quote>illusion</quote> of a single, large set of interconnected menus. +</para> + +<para> +Gopher permits the user to record an item's location in a +<quote>bookmark</quote> thereby allowing users to follow a +<quote>bookmark</quote> directly to a particular item without +searching the menu system. Gopher menus are not standardized, inasmuch as +each Gopher server is individually determined. +</para> + +<para> +Source: +<ulink +url="http://tlc.nlm.nih.gov/resources/tutorials/internetdistlrn/gophrdef.htm"> http://tlc.nlm.nih.gov/resources/tutorials/internetdistlrn/gophrdef.htm</ulink> +</para> +</article> diff --git a/doc/kioslave/gzip.docbook b/doc/kioslave/gzip.docbook new file mode 100644 index 000000000..906f0d654 --- /dev/null +++ b/doc/kioslave/gzip.docbook @@ -0,0 +1,30 @@ +<article lang="&language;" id="gzip"> +<title>gzip</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para><command>gzip</command> is a compression program</para> + +<para>The gzip kioslave is not directly usable, and is intended for use +as a filter. For example, the tar kioslave can filter a file through +the gzip kioslave, in order to display the contents of a <literal +role="extension">tar.gz</literal> file directly in a &konqueror; +window.</para> + +<para>If you click on a file compressed with a <literal +role="extension">gz</literal> extension in &konqueror;, this kioslave is +used to uncompress it and display it as a normal (uncompressed) +file.</para> + +<para>If you are a developer, and would like to use the gzip filter, you +can find documentation on using kioslaves at <ulink +url="http://developer.kde.org">http://developer.kde.org</ulink></para> + +<para> See the manual: <ulink url="man:/gzip">gzip</ulink>. +</para> + +</article> diff --git a/doc/kioslave/help.docbook b/doc/kioslave/help.docbook new file mode 100644 index 000000000..0b38cb93f --- /dev/null +++ b/doc/kioslave/help.docbook @@ -0,0 +1,17 @@ +<article lang="&language;" id="help"> +<title>help</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer;&Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para> +The help system of &kde; +</para> +<para> + See <ulink url="help:/">The &khelpcenter;</ulink>. +</para> + +</article> diff --git a/doc/kioslave/http.docbook b/doc/kioslave/http.docbook new file mode 100644 index 000000000..0d6a8cef6 --- /dev/null +++ b/doc/kioslave/http.docbook @@ -0,0 +1,25 @@ +<article lang="&language;" id="http"> +<title>http</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para><acronym>http</acronym> is the +<emphasis>H</emphasis>yper<emphasis>T</emphasis>ext +<emphasis>T</emphasis>ransfer <emphasis>P</emphasis>rotocol.</para> + +<para>The http kioslave is used by all &kde; applications to handle +connections to http servers, that is, web servers. The most common +usage is to view web pages in the &konqueror; web browser.</para> + +<para>You can use the http kioslave in &konqueror; by giving it a +<acronym>URL</acronym>. +<userinput>http://<replaceable>www.kde.org</replaceable></userinput>.</para> + +<para> See the manual: <ulink url="man:/http">http</ulink>. +</para> + +</article> diff --git a/doc/kioslave/https.docbook b/doc/kioslave/https.docbook new file mode 100644 index 000000000..38772f5dc --- /dev/null +++ b/doc/kioslave/https.docbook @@ -0,0 +1,21 @@ +<article lang="&language;" id="https"> +<title>https</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +HTTPS is +<ulink url="help:/kioslave/http.html">HTTP</ulink> + encapsulated in an SSL/TLS stream. +</para> +<para> +SSL is the Secure Sockets Layer protocol, a security protocol that provides communications privacy over the Internet. The protocol allows client/server applications to communicate in a way that is designed to prevent eavesdropping, tampering, or message forgery. +</para> +<para> +TLS stands for Transport Layer Security +</para> + +</article> diff --git a/doc/kioslave/imap.docbook b/doc/kioslave/imap.docbook new file mode 100644 index 000000000..e34c1e4e9 --- /dev/null +++ b/doc/kioslave/imap.docbook @@ -0,0 +1,31 @@ +<article lang="&language;" id="imap"> +<title>imap</title> +<articleinfo> +<authorgroup> +<author>&Michael.Haeckel; &Michael.Haeckel.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2001-08-07</date> + + +</articleinfo> + +<para>The IMAP4rev1 protocol (Internet Message Access Protocol) allows +access to messages in mail folders on a server. Unlike POP3, which is designed +to download the mails and delete them from the server, the purpose of IMAP is +to store all mails on the server to be able to access these mails from +everywhere. Messages can be stored on the server, retrieved from there or +moved between folders.</para> + +<para>This plugin is currently mainly used by KMail, but you can also use it +in any other KDE application that uses kioslave plugins.</para> + +<para>For example in &konqueror;, simply type +<userinput>imap://[email protected]/</userinput> to get your IMAP +folders listed. You can then deal with the folders and mails like with folders +and files on a local file system. +IMAP URLs are defined in <ulink url="http://www.ietf.org/rfc/rfc2192.txt?number=2192">RFC 2192</ulink>. +</para> + +</article> diff --git a/doc/kioslave/imaps.docbook b/doc/kioslave/imaps.docbook new file mode 100644 index 000000000..d5f8e7b6f --- /dev/null +++ b/doc/kioslave/imaps.docbook @@ -0,0 +1,17 @@ +<article lang="&language;" id="imaps"> +<title>imaps</title> +<articleinfo> +<authorgroup> +<author>&Michael.Haeckel; &Michael.Haeckel.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2001-08-07</date> + + +</articleinfo> + +<para>IMAPS is the <ulink url="help:/kioslave/imap.html">IMAP</ulink> protocol +encrypted via SSL.</para> + +</article> diff --git a/doc/kioslave/index.docbook b/doc/kioslave/index.docbook new file mode 100644 index 000000000..6f70d6e23 --- /dev/null +++ b/doc/kioslave/index.docbook @@ -0,0 +1,93 @@ +<?xml version="1.0" ?> +<!DOCTYPE part PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ +<!ENTITY kio-bzip SYSTEM "bzip.docbook"> +<!ENTITY kio-bzip2 SYSTEM "bzip2.docbook"> +<!ENTITY kio-cgi SYSTEM "cgi.docbook"> +<!ENTITY kio-data SYSTEM "data.docbook"> +<!ENTITY kio-file SYSTEM "file.docbook"> +<!ENTITY kio-finger SYSTEM "finger.docbook"> +<!ENTITY kio-fish SYSTEM "fish.docbook"> +<!ENTITY kio-floppy SYSTEM "floppy.docbook"> +<!ENTITY kio-ftp SYSTEM "ftp.docbook"> +<!ENTITY kio-gopher SYSTEM "gopher.docbook"> +<!ENTITY kio-gzip SYSTEM "gzip.docbook"> +<!ENTITY kio-help SYSTEM "help.docbook"> +<!ENTITY kio-http SYSTEM "http.docbook"> +<!ENTITY kio-https SYSTEM "https.docbook"> +<!ENTITY kio-imap SYSTEM "imap.docbook"> +<!ENTITY kio-imaps SYSTEM "imaps.docbook"> +<!ENTITY kio-info SYSTEM "info.docbook"> +<!ENTITY kio-lan SYSTEM "lan.docbook"> +<!ENTITY kio-ldap SYSTEM "ldap.docbook"> +<!ENTITY kio-mailto SYSTEM "mailto.docbook"> +<!ENTITY kio-mac SYSTEM "mac.docbook"> +<!ENTITY kio-man SYSTEM "man.docbook"> +<!ENTITY kio-mrml SYSTEM "mrml.docbook"> <!-- post release, put this in the right module --> +<!ENTITY kio-news SYSTEM "news.docbook"> +<!ENTITY kio-nfs SYSTEM "nfs.docbook"> +<!ENTITY kio-nntp SYSTEM "nntp.docbook"> +<!ENTITY kio-pop3 SYSTEM "pop3.docbook"> +<!ENTITY kio-pop3s SYSTEM "pop3s.docbook"> +<!ENTITY kio-print SYSTEM "print.docbook"> +<!ENTITY kio-rlan SYSTEM "rlan.docbook"> +<!ENTITY kio-rlogin SYSTEM "rlogin.docbook"> +<!ENTITY kio-sftp SYSTEM "sftp.docbook"> +<!ENTITY kio-smb SYSTEM "smb.docbook"> +<!ENTITY kio-smtp SYSTEM "smtp.docbook"> +<!ENTITY kio-tar SYSTEM "tar.docbook"> +<!ENTITY kio-telnet SYSTEM "telnet.docbook"> +<!ENTITY kio-thumbnail SYSTEM "thumbnail.docbook"> +<!ENTITY kio-webdav SYSTEM "webdav.docbook"> +<!ENTITY kio-webdavs SYSTEM "webdavs.docbook"> +<!ENTITY kdeprint "<application>KDEPrint</application>"> +<!ENTITY Ferdinand.Gassauer '<personname><firstname>Ferdinand</firstname><surname>Gassauer</surname></personname>'> +<!ENTITY Ferdinand.Gassauer.mail '<email>[email protected]</email>'> +<!ENTITY % addindex "IGNORE"> +<!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<part lang="&language;"> +<title>IO-Slaves</title> +&kio-bzip; +&kio-bzip2; +&kio-cgi; +&kio-data; +&kio-file; +&kio-finger; +&kio-fish; +&kio-floppy; +&kio-ftp; +&kio-gopher; +&kio-gzip; +&kio-help; +&kio-http; +&kio-https; +&kio-imap; +&kio-imaps; +&kio-info; +&kio-lan; +&kio-ldap; +&kio-mailto; +&kio-mac; +&kio-man; +&kio-mrml; +&kio-news; +&kio-nfs; +&kio-nntp; +&kio-pop3; +&kio-pop3s; +&kio-print; +&kio-rlan; +&kio-rlogin; +&kio-sftp; +&kio-smb; +&kio-smtp; +&kio-tar; +&kio-telnet; +&kio-thumbnail; +&kio-webdav; +&kio-webdavs; + +</part> + diff --git a/doc/kioslave/info.docbook b/doc/kioslave/info.docbook new file mode 100644 index 000000000..1ea645c33 --- /dev/null +++ b/doc/kioslave/info.docbook @@ -0,0 +1,36 @@ +<article lang="&language;" id="info"> +<title>Info</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<author> + <firstname>Nicolas</firstname> + <surname>Goutte</surname> + <email>[email protected]</email> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para>Info is a type of documentation. The documents are in a file +format called texinfo, and can be read on the command line with the +<command>info</command> program.</para> + +<para>The Info ioslave allows you to read the info pages installed on +your system, from within &konqueror;. You can use it very easily:</para> + +<screen><userinput><command>info:</command><replaceable>gcc</replaceable></userinput></screen> + +<para>This would show you the top level node of the Info documentation +for the &gcc; compiler.</para> + +<para>Info is a &GNU; replacement for +<command>man</command>, but is not widely used outside of +&GNU; software.</para> + +<para>You can quite easily browse the info documentation you have +installed from within the &khelpcenter; application, or you can use the +info ioslave directly from within both &konqueror; and the +mini-cli.</para> + +</article> diff --git a/doc/kioslave/lan.docbook b/doc/kioslave/lan.docbook new file mode 100644 index 000000000..c494b5767 --- /dev/null +++ b/doc/kioslave/lan.docbook @@ -0,0 +1,23 @@ +<article lang="&language;" id="lan"> +<title>lan</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para> +This protocol is intended to provide a kind of <quote>network +neighborhood</quote> but only relying on the TCP/IP protocol stack and with +the ability to use other protocols than just <acronym>SMB</acronym>.</para> + +<para>The lan kioslave can use &FTP;, &HTTP;, <acronym>SMB</acronym>, +<acronym>NFS</acronym>, and <acronym>FISH</acronym></para> + +<para>It must first be configured in &kcontrol;, +<menuchoice><guimenu>Network</guimenu><guimenuitem>LAN-Browsing</guimenuitem> +</menuchoice> and for more information see <ulink url="help:/lisa">the +Lan Browsing manual</ulink>.</para> + +</article> diff --git a/doc/kioslave/ldap.docbook b/doc/kioslave/ldap.docbook new file mode 100644 index 000000000..ff23339c3 --- /dev/null +++ b/doc/kioslave/ldap.docbook @@ -0,0 +1,23 @@ +<article lang="&language;" id="ldap"> +<title>ldap</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para><acronym>ldap</acronym> is the lightweight directory access +protocol. It provides access to an X.500 directory, or to a stand-alone +<acronym>LDAP</acronym> server.</para> + +<para>You can use the ldap kioslave as follows:</para> + +<para><userinput>ldap://host:port/ou=People,o=where,c=de??sub</userinput> +for a subtree-query</para> + +<para>or +<userinput>ldap://host:port/cn=MM,ou=People,o=where,c=de??base</userinput> +for a complete branch.</para> + +</article> diff --git a/doc/kioslave/mac.docbook b/doc/kioslave/mac.docbook new file mode 100644 index 000000000..a1398c39a --- /dev/null +++ b/doc/kioslave/mac.docbook @@ -0,0 +1,53 @@ +<article lang="&language;" id="mac"> +<title>mac</title> +<articleinfo> +<authorgroup> +<author><personname><firstname>Johnathan</firstname><surname>Riddell</surname></personname><email>[email protected]</email> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para>The mac ioslave lets you read an HFS+ partition from &konqueror; +or any other &kde; file dialog. It uses <ulink +url="http://www.google.com/search?hl=en&q=hfsplus+utils"> hfsplus +tools</ulink>, so you will need these installed for it to work.</para> + +<para>Enter <userinput>mac:/</userinput> into &konqueror; and you +should see the contents of your &MacOS; partition. If you have not +used kio-mac before, you will probably get an error message saying you +have not specified the right partition. Enter something like +<userinput>mac:/<option>?dev=/dev/hda2</option></userinput> to specify +the partition (if you don't know which partition &MacOS; is on, you +can probably guess by changing hda2 to hda3 and so on or use the print +command from <command>mac-fdisk</command>). This partition will be +used the next time, so you do not have to specify it each time.</para> + +<para><application>Hfsplus tools</application> let you see the file and copy +data from the HFS+ partition, but not to copy data to it or change the +filenames.</para> + +<para>HFS+ actually keeps two files for every one you see (called +forks), a resource fork and a data fork. The default copy mode when +you are copying files across to your native drive is raw data, which +means it only copies the data fork. Text files are copied in text mode +(same as raw format but changes the line endings to be &UNIX; friendly +and gets rid of some extra characters - strongly advised for text +files), unless you specify otherwise. You can also copy the files +across in Mac Binary II format or specify text or raw format with +another query: +<userinput>mac:/<option>myfile?mode=b</option></userinput> or +<userinput>mac:/<option>myfile?mode=t</option></userinput>. See the +<command>hpcopy</command> man page for more.</para> + +<para>Note that you need permissions to read your HFS+ partition. How +you get this depends on your distribution. <!-- , do a <command>ls -l +/dev/hdaX</command> on it to see. Under Debian you have to be in the +'disk' group (just add your username to the end of the entry in +/etc/group).--></para> + +<para>For some reason some folders in &MacOS; end in a funny tall +<quote>f</quote> character. This seems to confuse hfstools.</para> + +</article> + diff --git a/doc/kioslave/mailto.docbook b/doc/kioslave/mailto.docbook new file mode 100644 index 000000000..3603aea8d --- /dev/null +++ b/doc/kioslave/mailto.docbook @@ -0,0 +1,17 @@ +<article lang="&language;" id="mailto"> +<title>mailto</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para>The mailto kioslave is used when you click on a mailto link in an +<acronym>HTML</acronym> page. &konqueror; will open the preferred mail +client you have configured, with a composer window. Any information +supplied in the <acronym>URL</acronym> will be filled in for you.</para> + +<para> +See the manual: <ulink url="man:/mailto">mailto</ulink>. +</para> +</article> diff --git a/doc/kioslave/man.docbook b/doc/kioslave/man.docbook new file mode 100644 index 000000000..6d2d00c15 --- /dev/null +++ b/doc/kioslave/man.docbook @@ -0,0 +1,86 @@ +<article lang="&language;" id="man"> +<title>Man</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<author> + <firstname>Nicolas</firstname> + <surname>Goutte</surname> + <email>[email protected]</email> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + +<para> +Using the man ioslave you are able to read the man pages installed +on your system. It is easy to use: +</para> + +<variablelist> +<varlistentry> +<term><userinput><command>man:</command></userinput></term> +<listitem> +<para>See the sections of the manual, click to find the rest. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>man:</command><replaceable>fopen</replaceable></userinput></term> +<listitem> +<para>See the man page of <command>fopen</command>. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>man:</command><replaceable>fopen(3)</replaceable></userinput></term> +<listitem> +<para>See the man page of <command>fopen</command> in section 3. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>man:</command><replaceable>(3)</replaceable></userinput></term> +<listitem> +<para>See the index of section 3. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>man:</command>intro<replaceable>(3)</replaceable></userinput></term> +<listitem> +<para>See the introduction of section 3. +</para> +</listitem> +</varlistentry> +</variablelist> + +<note><para>If there are more than one man page of the name that you +have entered, you will get a list where you can choose the man page +that you want to see.</para></note> + +<para> +There is also a shortcut: <userinput><command>#fopen</command></userinput>, +which has the same effect as above. +</para> + +<para> +If you do not find all your man pages, adjust the configuration file +<filename>/etc/manpath.config</filename> +(or a file of a similar name depending on your distribution) +or adjust the environment variables +<envar>MANPATH</envar> and <envar>MANSECT</envar>. +</para> + +<para> +As with any other &kde; ioslave, it is possible to enter a &URL;, like +<userinput><command>man:socket</command></userinput> in <emphasis>any</emphasis> +&kde; application. Try it in &kwrite; and you will see the man page in +&HTML; format. +</para> + +<para> +Contact mailing list: <email>[email protected]</email> +</para> + +</article> diff --git a/doc/kioslave/mrml.docbook b/doc/kioslave/mrml.docbook new file mode 100644 index 000000000..32af0922c --- /dev/null +++ b/doc/kioslave/mrml.docbook @@ -0,0 +1,26 @@ +<article lang="&language;" id="mrml"> +<title>mrml</title> +<articleinfo> +<authorgroup> +<author>&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail; +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-01-08</date> + + +</articleinfo> + +<para><acronym>MRML</acronym> stands for Multimedia Retrieval Markup Language. <acronym>MRML</acronym> is an XML-based +protocol to provide standardized access to Multimedia retrieval software. +See <ulink url="http://www.mrml.net">http://www.mrml.net</ulink> for more information. +</para> + +<para>kio_mrml is used for the Image Finding feature in &kde;</para> + +<para>⪚ type <userinput>mrml:/</userinput> or <userinput>mrml:/some.other.server</userinput> in &konqueror; to start searching for +images. +</para> + +</article> diff --git a/doc/kioslave/news.docbook b/doc/kioslave/news.docbook new file mode 100644 index 000000000..c56e3a8e0 --- /dev/null +++ b/doc/kioslave/news.docbook @@ -0,0 +1,20 @@ +<article lang="&language;" id="news"> +<title>news</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> + + +<para>The news kioslave is used when you click on a news link on a web +page. It will open &knode;, and if the group referred to in the news +link is available from your server, it will subscribe you to the group, in +the first available account you have configured in &knode;</para> + +<para>You can unsubscribe from within &knode; if you decide you don't +want to read the group, by <mousebutton>right</mousebutton> clicking and +selecting <guimenuitem>Unsubscribe from Group</guimenuitem>.</para> + +</article> diff --git a/doc/kioslave/nfs.docbook b/doc/kioslave/nfs.docbook new file mode 100644 index 000000000..bbe9bb625 --- /dev/null +++ b/doc/kioslave/nfs.docbook @@ -0,0 +1,39 @@ +<article lang="&language;" id="nfs"> +<title>nfs</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +Sun's <acronym>NFS</acronym> protocol provides transparent remote access to +shared file systems across networks. The <acronym>NFS</acronym> protocol is +designed to be machine, operating system, network architecture, and +transport protocol independent. This independence is achieved through the +use of Remote Procedure Call (<acronym>RPC</acronym>) primitives built on +top of an eXternal Data Representation (<acronym>XDR</acronym>). +</para> + +<para> +The supporting MOUNT protocol performs the operating system-specific +functions that allow clients to attach remote folder trees to a point +within the local file system. The mount process also allows the server to +grant remote access privileges to a restricted set of clients via export +control.</para> + +<para> +The Lock Manager provides support for file locking when used in the +<acronym>NFS</acronym> environment. The Network Lock Manager +(<acronym>NLM</acronym>) protocol isolates the inherently stateful aspects +of file locking into a separate protocol.</para> + +<para> +Source: +<ulink url="http://www.networksorcery.com/enp/protocol/nfs.htm"> +http://www.networksorcery.com/enp/protocol/nfs.htm</ulink> +</para> + +<para> See the manual: <ulink url="man:/nfs">nfs</ulink>. +</para> +</article> diff --git a/doc/kioslave/nntp.docbook b/doc/kioslave/nntp.docbook new file mode 100644 index 000000000..8020b8903 --- /dev/null +++ b/doc/kioslave/nntp.docbook @@ -0,0 +1,41 @@ +<article lang="&language;" id="nntp"> +<title>nntp</title> +<articleinfo> +<authorgroup> +<author>&Lauri.Watts; &Lauri.Watts.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para>The nntp kioslave accesses <acronym>NNTP</acronym> servers +directly.</para> + +<para>This kioslave can not be used with servers that do not implement +the <command>GROUP</command> command, including some versions of the +popular <application>INN</application> news server which is often used +by <acronym>ISP</acronym>s. It does work with +<application>leafnode</application>, which many people use to keep an +offline cache of news articles on their own hard drive or within their +<acronym>LAN</acronym>.</para> + +<para>You can use the nntp kioslave by typing +<userinput>nntp://yourserver/groupname</userinput> into the &konqueror; +<acronym>URL</acronym> bar.</para> + +<para>If you enter a group name, as above, and the group is available, +you will see the messages stored for that group as icons in +&konqueror;.</para> + +<para>Clicking on a message will display it as plain text, including all +headers. This could be useful for debugging a news client to news +server connection, for example, to ensure that your new +<application>leafnode</application> server is working correctly.</para> + +<para>If you don't enter a group name, and only the server name, you +will see a list of available groups. </para> + +<para>Please be aware that this could take an enormous amount of time, and +will cause a lot of network traffic. Some commercial usenet servers +have 60,000 or more groups available, and doing such a thing may +cause your desktop to freeze.</para> + +</article> diff --git a/doc/kioslave/pop3.docbook b/doc/kioslave/pop3.docbook new file mode 100644 index 000000000..1c956a1cd --- /dev/null +++ b/doc/kioslave/pop3.docbook @@ -0,0 +1,13 @@ +<article lang="&language;" id="pop3"> +<title>pop3</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +The Post Office Protocol (POP3) allows a user's workstation to access mail from a mailbox server. +</para> + +</article> diff --git a/doc/kioslave/pop3s.docbook b/doc/kioslave/pop3s.docbook new file mode 100644 index 000000000..856709e80 --- /dev/null +++ b/doc/kioslave/pop3s.docbook @@ -0,0 +1,14 @@ +<article lang="&language;" id="pop3s"> +<title>pop3s</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +POP3S is the POP3 protocol encrypted via SSL. + +</para> + +</article> diff --git a/doc/kioslave/print.docbook b/doc/kioslave/print.docbook new file mode 100644 index 000000000..034eddab1 --- /dev/null +++ b/doc/kioslave/print.docbook @@ -0,0 +1,170 @@ +<article lang="&language;" id="print"> +<title>print</title> +<articleinfo> +<authorgroup> +<author>&Kurt.Pfeifle; &Kurt.Pfeifle.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<date>2002-06-23</date> +<releaseinfo>1.00.00</releaseinfo> + +</articleinfo> + +<para>The <acronym>print</acronym> KIOSlave gives quick access to browse +different &kdeprint; sections via <quote>virtual folders</quote>. +These folders provide some information about and quick access to your print +subsystem.</para> + +<para><command>print:/</command> represents one more of those useful +KIOSlaves implemented by &kde;. To access it, just type <userinput>print:/ + </userinput> into the address field of &konqueror;. <userinput>print:/ + </userinput> doesn't purely provide <quote>read-only</quote> access to + your print subsystem, but it also allows you to change settings + of your printers, of your print system and lets you create new printers + and classes.</para> + +<para>You are asked for the Administrator or root password, if you are +not allowed a view or an operation as a normal user.</para> + +<para>You can bookmark frequently used shortcuts like + <command>print:/manager</command></para> + +<para>Valid syntax is either +<userinput>print:/[path-to-virtual-folder]</userinput> or +<userinput>print:[path-to-virtual-folder]</userinput></para> + +<para>Note, that some of the views and actions offered do heavily + depend on the print subsystem that is installed on your box and presently +activated for &kde;. Pages showing printer information display only +those parts that are valid for the &kde; selected print subsystem. +(So if you normally run <acronym>CUPS</acronym>, but switched temporarily to + + + <quote>Generic UNIX LPD Printing</quote>, which is possible, you will see +less printer info, because LPD is not capable of using the same amount of +print settings as are possible in CUPS).</para> + +<para>Valid syntax to access different virtual folders +and a short explanation of what they represent:</para> + +<variablelist> +<title>Some examples</title> + +<varlistentry> +<term><userinput>print:/ </userinput> (&ie; the root of +print-kioslave)</term> +<listitem> +<para> virtual root for browsing your print subsystem. + It displays subfolders <quote>Classes</quote>, + <quote>Jobs</quote>, + <quote>Manager</quote>, <quote>Printers</quote>, + and <quote>Specials</quote></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>print:/classes</userinput> or +<userinput>print:classes </userinput> +</term> <listitem> +<para> view your printer classes + (supported by and useful for CUPS only) +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><userinput>print:/classes/class_name </userinput> or + <userinput>print:classes/class_name </userinput> </term> <listitem> +<para>view all members of the named + printer class (supported by and useful only + for CUPS) </para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><userinput>print:/jobs </userinput> +or <userinput>print:jobs </userinput></term> +<listitem> +<para> lists the current and pending jobs. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>print:/printers </userinput> +or <userinput>print:printers </userinput></term> +<listitem> +<para> lists all your printers. Clicking + on a printer name shows more info about that printer. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>print:/printers/printer_name </userinput> +or <userinput>print:printers/printer_name </userinput> </term> +<listitem> +<para>displays useful info about the named + printer </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>print:/manager </userinput> or +<userinput>print:manager </userinput> +</term> <listitem> +<para>opens a page very similar to the &kdeprint; + Manager module inside the &kde; Control Center. + Switch to a different printing system here or do every + other administrative task. </para> +<para>This is the most important of access points to your printing + system. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><userinput>print:/specials </userinput> or +<userinput>print:specials </userinput> +</term><listitem> +<para>lists all presently available <quote>special printers</quote>: + Likely you'll see:</para> +<itemizedlist> +<listitem> + <para>The two that let you save a printfile to disk, in + &PostScript; or <acronym>PDF</acronym> format.</para> +</listitem> +<listitem> + <para>One that sends it as a <acronym>PDF</acronym> attachment via +&kmail;.</para> +</listitem> +<listitem> + <para>And last, send it via fax, if you have one of the + supported fax backends active, +<application>Hylafax</application> or +<application>efax</application>.</para> +</listitem> +</itemizedlist> +</listitem> +</varlistentry> + +</variablelist> + +<tip><para>You can also put <command>print:/manager</command> + or similar as the command in + the <quote>Quick Command</quote> utility (started via +<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>)</para></tip> + +<para>You can learn more about printing and &kdeprint;'s powerful abilities +by reading the <ulink url="help:/kdeprint/index.html">&kdeprint; Handbook +locally</ulink> or at the <ulink url="http://printing.kde.org/">&kdeprint; +Website</ulink> where there are documents online (<acronym>HTML</acronym> and +<acronym>PDF</acronym>),containing +<ulink +url="http://printing.kde.org/documentation/tutorials/">Tutorials</ulink>, + as well as <ulink url="http://printing.kde.org/faq/">FAQs</ulink> and + Tips and Tricks related to printing in general.</para> + +</article> diff --git a/doc/kioslave/rlan.docbook b/doc/kioslave/rlan.docbook new file mode 100644 index 000000000..98c962444 --- /dev/null +++ b/doc/kioslave/rlan.docbook @@ -0,0 +1,11 @@ +<article lang="&language;" id="rlan"> +<title>rlan</title> +<articleinfo> +<authorgroup> +<corpauthor>The &kde; team</corpauthor> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para>Not yet documented</para> + +</article> diff --git a/doc/kioslave/rlogin.docbook b/doc/kioslave/rlogin.docbook new file mode 100644 index 000000000..a24b20f85 --- /dev/null +++ b/doc/kioslave/rlogin.docbook @@ -0,0 +1,31 @@ +<article lang="&language;" id="rlogin"> +<title>rlogin</title> +<articleinfo> +<authorgroup> +<author><personname><firstname>Christian</firstname><surname>Bunting</surname></personname></author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para>Using &konqueror; you can start up an <command>rlogin</command> +session with a server hosting the rlogin service.</para> + +<para>To use this kioslave feature, in the &konqueror; +<acronym>URL</acronym> bar, type +<userinput>rlogin:/host_to_connect_to</userinput></para> + +<para>This will initialize &konsole; with an <command>rlogin</command> +session, prompting you for your password.</para> + +<para>The <command>rlogin</command> kioslave uses the username of the +account you are currently using in &kde;.</para> + +<para>After you have successfully entered your password, you can begin +your remote session.</para> + +<para> See the manual: <ulink url="man:/rlogin">rlogin</ulink>. +</para> + + +<!-- By Christian Bunting (need to ask if he wants crediting and email) --> + +</article> diff --git a/doc/kioslave/sftp.docbook b/doc/kioslave/sftp.docbook new file mode 100644 index 000000000..ff2770a47 --- /dev/null +++ b/doc/kioslave/sftp.docbook @@ -0,0 +1,19 @@ +<article lang="&language;" id="sftp"> +<title>sftp</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para><acronym>SFTP</acronym> is a Secure file transfer protocol. +<command>sftp</command> is an interactive file transfer program, +similar to ftp, but it performs all operations over an encrypted +<command>ssh</command> transport. It may use many of the features of +<command>ssh</command>, including public key authentication and +compression.</para> + +<para> See the manual: <ulink url="man:/sftp">sftp</ulink>. +</para> + +</article> diff --git a/doc/kioslave/smb.docbook b/doc/kioslave/smb.docbook new file mode 100644 index 000000000..716db415f --- /dev/null +++ b/doc/kioslave/smb.docbook @@ -0,0 +1,56 @@ +<article lang="&language;" id="smb"> +<title>SMB</title> +<articleinfo> +<authorgroup> +<author>&Alexander.Neundorf; &Alexander.Neundorf.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +The smb ioslave enables you to browse the shares of a &Windows; (or Samba) +network. +</para> + +<para> +To see the workgroups, enter +<userinput><command>smb:/</command></userinput>. +</para> +<para> +<userinput><command>smb://</command><replaceable>a_workgroup</replaceable></userinput> +will list the hosts in this workgroup. +</para> +<para> +To see the shares of a host, enter +<userinput><command>smb://</command><replaceable>the_host</replaceable></userinput> +or +<userinput><command>smb:/</command><replaceable>a_workgroup</replaceable>/<replaceable>the_host</replaceable></userinput>. +</para> +<para> +To access a share directly enter +<userinput><command>smb://</command><replaceable>the_host/the_share</replaceable></userinput> +or +<userinput><command>smb:/</command><replaceable>a_workgroup</replaceable>/<replaceable>the_host</replaceable>/<replaceable>the_share</replaceable></userinput> +</para> + +<para> +The smb ioslave requires that you have libsmbclient to use this ioslave. +</para> + +<para> +You can set your default user name and password in the &kcontrol; in +<menuchoice><guisubmenu>Network</guisubmenu><guimenuitem>Windows +Shares</guimenuitem></menuchoice>. This is especially useful if you are a +member of a &Windows; <acronym>NT</acronym> domain. There you can also set your +workgroup name, but in most cases this is not required. The kioslave will ask for your username and password if a default is not set. +</para> + +<para> +This ioslave is tested and developed using mainly Samba 2.0.7, but other +versions of Samba should work too. +</para> + +<para> +Author: Alexander Neundorf <email>[email protected]</email> +</para> +</article> + diff --git a/doc/kioslave/smtp.docbook b/doc/kioslave/smtp.docbook new file mode 100644 index 000000000..2aa2c7dbf --- /dev/null +++ b/doc/kioslave/smtp.docbook @@ -0,0 +1,16 @@ +<article lang="&language;" id="smtp"> +<title>smtp</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +A protocol to send mail from the client workstation to the mail server. +</para> + +<para> See : <ulink url="http://cr.yp.to/smtp.html">Simple Mail Transfer Protocol </ulink>. +</para> + +</article> diff --git a/doc/kioslave/tar.docbook b/doc/kioslave/tar.docbook new file mode 100644 index 000000000..8a5405198 --- /dev/null +++ b/doc/kioslave/tar.docbook @@ -0,0 +1,18 @@ +<article lang="&language;" id="tar"> +<title>tar</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +An archiving program designed to store and extract files from an archive +file known as a tarfile. A tarfile may be made on a tape drive, however, it +is also common to write a tarfile to a normal file. +</para> + +<para> See the manual: <ulink url="man:/tar">tar</ulink>. +</para> + +</article> diff --git a/doc/kioslave/telnet.docbook b/doc/kioslave/telnet.docbook new file mode 100644 index 000000000..9d2131e84 --- /dev/null +++ b/doc/kioslave/telnet.docbook @@ -0,0 +1,17 @@ +<article lang="&language;" id="telnet"> +<title>telnet</title> +<articleinfo> +<authorgroup> +<author>&Ferdinand.Gassauer; &Ferdinand.Gassauer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para> +The network terminal protocol (TELNET) allows a user to log in on any other computer on the network supporting TELNET. + +</para> + +<para> See the manual: <ulink url="man:/telnet">telnet</ulink>. +</para> + +</article> diff --git a/doc/kioslave/thumbnail.docbook b/doc/kioslave/thumbnail.docbook new file mode 100644 index 000000000..7b2e0752f --- /dev/null +++ b/doc/kioslave/thumbnail.docbook @@ -0,0 +1,28 @@ +<article lang="&language;" id="thumbnail"> +<title>thumbnail</title> +<articleinfo> +<authorgroup> +<author>&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> +</articleinfo> +<para>The thumbnail kioslave is used by &kde; for network transparent +and persistent generation of thumbnails.</para> + +<para>The thumbnail kioslave uses plugins to generate the actual +thumbnails. You can enable viewing of these thumbnails from the +<menuchoice><guimenu>View</guimenu> +<guisubmenu>Preview</guisubmenu></menuchoice> submenu, available in +&konqueror; in file manager mode.</para> + +<para>The thumbnail kioslave is not directly useful to a user, but if +you are a developer, you can use it within your own applications to +create file previews.</para> + +<para>See the documentation in the sources for more information. You +will find these at +<filename>$<envar>KDEDIR</envar>/include/kio/thumbcreator.h</filename> or +in the source folder <filename +class="directory">kdebase/kioslave/thumbnail</filename></para> + +</article> diff --git a/doc/kioslave/webdav.docbook b/doc/kioslave/webdav.docbook new file mode 100644 index 000000000..d549384f2 --- /dev/null +++ b/doc/kioslave/webdav.docbook @@ -0,0 +1,65 @@ +<article lang="&language;" id="webdav"> +<title>webdav</title> +<articleinfo> +<authorgroup> +<author>&Hamish.Rodda; &Hamish.Rodda.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-01-21</date> +</articleinfo> + +<para><acronym>WebDAV</acronym> is a <emphasis>D</emphasis>istributed +<emphasis>A</emphasis>uthoring and <emphasis>V</emphasis>ersioning +protocol for the World Wide Web. It allows for easy management of +documents and scripts on a <ulink +url="help:/kioslave/webdav.html">http</ulink> server, and has +additional features designed to simplify version management amongst +multiple authors.</para> + +<para>Usage of this protocol is simple. Type the location you want to +view, similar to a <acronym>http</acronym> URL except for the +webdav:// protocol name at the start. An example is +<userinput>webdav://<replaceable>www.hostname.com/path/</replaceable></userinput>. +If you specify a folder name, a list of files and folders will be +displayed, and you can manipulate these folders and files just as you +would with any other filesystem.</para> + +<variablelist> +<title>WebDAV Features</title> +<varlistentry> +<term>Locking</term> +<listitem> +<para>File locking allows users to lock a file, informing others that they +are +currently working on this file. This way, editing can be done without fear +that +the changes may be overwritten by another person who is also editing the +same +document.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Source file access</term> +<listitem> +<para><acronym>WebDAV</acronym> allows access to the script which is called +to +produce a specific page, so changes can be made to the script itself.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Per-document property support</term> +<listitem> +<para>Arbitrary properties may be set to assist identification of a +document, +such as the author.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>To take advantage of these additional capabilities, you will need an +application which supports them. No application currently supports them +through +this kioslave.</para> + +</article> diff --git a/doc/kioslave/webdavs.docbook b/doc/kioslave/webdavs.docbook new file mode 100644 index 000000000..edbd635e6 --- /dev/null +++ b/doc/kioslave/webdavs.docbook @@ -0,0 +1,17 @@ +<article lang="&language;" id="webdavs"> +<title>webdavs</title> +<articleinfo> +<authorgroup> +<author>&Hamish.Rodda; &Hamish.Rodda.mail;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-01-21</date> + + +</articleinfo> + +<para>WebDAVS is the <ulink url="help:/kioslave/webdav.html">WebDAV</ulink> protocol +encrypted via SSL.</para> + +</article> diff --git a/doc/klipper/Makefile.am b/doc/klipper/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/klipper/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/klipper/index.docbook b/doc/klipper/index.docbook new file mode 100644 index 000000000..71327f14c --- /dev/null +++ b/doc/klipper/index.docbook @@ -0,0 +1,511 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&klipper;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &klipper; Handbook </title> + +<authorgroup> +<author>&Philip.Rodrigues; &Philip.Rodrigues.mail;</author> + +<othercredit role="developer"> +&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail; +<!-- <contrib>Developer</contrib> --> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000-2003</year> +<holder>&Philip.Rodrigues;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-01-31</date> +<releaseinfo>2.92.00</releaseinfo> + +<abstract> +<para>&klipper; is the &kde; clipboard cut & paste utility.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Klipper</keyword> +<keyword>kdebase</keyword> +<keyword>clipboard</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> +<para>&klipper; is the &kde; clipboard utility. It stores clipboard +history, and allows you to link clipboard contents to application +actions. Please report any problems or feature requests to Esben Mose +Hansen (see <ulink +url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink> +for contact details).</para> + +</chapter> + +<chapter id="using-klipper"> +<title>Using &klipper;</title> + +<sect1 id="basic-usage"> +<title>Basic Usage</title> +<screenshot> +<screeninfo>The &klipper; icon.</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The &klipper; icon</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>To display the clipboard history, click on the &klipper; icon in + the &kde; panel, or press <keycombo + action="simul">&Ctrl;&Alt;<keycap>V</keycap> </keycombo>. Previous + clipboard entries are shown at the top of the pop-up menu which + appears. Selecting one of these copies it to the clipboard, from + where it can be pasted into any &kde; or X application as + usual.</para> + +<para>You can search through the clipboard history by opening it +(click on &klipper;) and typing your query. The results are updated as +you type. In case you're wondering how to use the accelerator keys in +the &klipper; menu, just press &Alt; and the accelerator you want. For +example, to clear the clipboard history when the &klipper; menu is +open, press <keycombo action="simul">&Alt;<keycap>L</keycap> +</keycombo>.</para> + +<para>To remove &klipper;, click on its icon in the System Tray, and from the +menu that appears, select <guimenuitem>Quit</guimenuitem>.</para> + +</sect1> + +<sect1 id="actions"> +<title>Actions</title> + +<para>&klipper; can perform actions on the contents of the clipboard, +based on whether they match a particular regular expression. For +example, any clipboard contents starting with <quote>http://</quote> can +be passed to &Netscape; or &konqueror; as &URL;s to open.</para> + +<para>To use this feature, just copy a &URL; or filename to the +clipboard. If there is a matching regular expression in &klipper;'s +list, a menu will appear showing you the options you have (⪚ Open +&URL; in &konqueror;, open &URL; in &Netscape;). Use the mouse or +keyboard to select the option you want, and &klipper; will run the +program you have selected, opening the address pointed to by the +clipboard contents.</para> + +<para>If you do not want to perform any actions on the clipboard +contents, select <guimenuitem>Do Nothing</guimenuitem> on the pop-up menu +to return to what you were doing before. If you leave the menu, it will +disappear, leaving you to continue your work. You can change the time +that the menu remains for in the <guilabel>Configure Klipper...</guilabel> +dialog, with the option <guilabel>Timeout for action pop-ups</guilabel> +under the <guilabel>General</guilabel> tab.</para> + +<para>Actions can be disabled completely by clicking on &klipper; and +selecting <guimenuitem>Actions Enabled</guimenuitem>, or by pressing +<keycombo action="simul">&Ctrl;&Alt;<keycap>X</keycap></keycombo>.</para> + +<para>Clipboard contents which match a regular expression can also be +edited before performing an action on them. Select <guimenuitem>Edit contents...</guimenuitem> on the &klipper; pop-up menu, and you can +change the clipboard contents in the dialog which appears, before +clicking the <guibutton>OK</guibutton> button to run the appropriate +action.</para> + +<para>Pressing <keycombo +action="simul">&Ctrl;&Alt;<keycap>R</keycap></keycombo> shows the pop-up +menu to repeat the last action which &klipper; performed.</para> + +</sect1> + +<sect1 id="clipboard-modes"> +<title>Clipboard/Selection Behavior</title> + +<sect2 id="clipboard-modes-general"> +<title>General</title> +<para> +&klipper; can be used to set the behavior of the clipboard and selection in +&kde;. +</para> + +<note><para>The &X-Window; uses two separate clipboard buffers: the +<quote>selection</quote> and the <quote>clipboard</quote>. Text is +placed in the selection buffer by simply selecting it, and can be +pasted with the middle mouse button. To place text in +the clipboard buffer, select it and press +<keycombo>&Ctrl;<keycap>X</keycap> </keycombo> or +<keycombo>&Ctrl;<keycap>C</keycap> </keycombo>. Text from the +clipboard buffer is pasted using <keycombo>&Ctrl;<keycap>V</keycap> +</keycombo> or by selecting +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem> +</menuchoice>.</para> +</note> + +<!-- &klipper; can be used to set the clipboard mode for the whole of &kde;. The +first mode will be familiar to &Microsoft; &Windows; and &Mac; users: Text is +inserted into the clipboard using an application's cut/copy (or generally +<keycombo>&Ctrl;<keycap>X</keycap></keycombo> and +<keycombo>&Ctrl;<keycap>C</keycap></keycombo> respectively) +function, and the application's paste (or generally +<keycombo>&Ctrl;<keycap>V</keycap></keycombo>) function pastes the +contents of this clipboard. +</para> +<para> +The second mode will be more familiar to longtime &UNIX; users: Selected text +is copied to this clipboard, and clicking the <mousebutton>middle</mousebutton> +mouse button pastes the +contents of this clipboard. +--> +</sect2> + +<sect2 id="changing-clipboard-modes"> +<title>Changing Clipboard/Selection Behavior</title> +<para> +In order to change clipboard/selection behavior, select +<guimenuitem>Configure Klipper...</guimenuitem> from the &klipper; pop-up menu, +and in the dialog box that appears, select the +<guilabel>General</guilabel> tab. Selecting <guilabel>Separate clipboard and +selection</guilabel> makes the clipboard and selection function as completely +separate buffers as described above. With this option set, the option +<guilabel>Ignore selection</guilabel> will prevent &klipper; from +including the contents of the selection in its clipboard history and from +performing actions on the contents of the selection. Selecting +<guilabel>Synchronize contents of the clipboard and the selection</guilabel> +causes the clipboard and selection buffers to always be the same, meaning that +text in the selection can be pasted with either the +<mousebutton>middle</mousebutton> mouse button or the key combination <keycombo>&Ctrl;<keycap>V</keycap> +</keycombo>, and similarly for text in the clipboard buffer. +</para> + + <!-- The +<guilabel>Synchronize contents of the clipboard and the +selection</guilabel> check box determines the clipboard mode. If the box is +selected, the clipboard functions in the &UNIX; mode; if not, the +&Windows;/&Mac; mode is used. --> + +</sect2> + + +</sect1> + +</chapter> + +<chapter id="preferences"> +<title>Configuring Klipper</title> + +<sect1 id="viewing-options"> + +<title>Viewing the Configuration Dialog</title> + +<para>To view or change &klipper;'s settings, open the &klipper; +pop-up menu, and select <guimenuitem>Configure Klipper...</guimenuitem>. The &klipper; +configuration dialog will appear. Its contents are described +below.</para> + +</sect1> + +<sect1 id="general-tab"> +<title>General Options</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Popup menu at mouse-cursor position</guilabel></term> +<listitem><para>Make the &klipper; pop-up menus appear at the position of +the mouse cursor, instead of their default position (in the &kde; Panel). +Useful if you use the mouse more than the keyboard.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Save clipboard contents on +exit</guilabel></term> <listitem><para>If this option is on, the clipboard +history will be saved when &klipper; exits, allowing you to use it next time +&klipper; starts.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remove whitespace when executing actions</guilabel></term> +<listitem><para>If selected, any whitespace (spaces, tabs, &etc;) at the +beginning and end of the clipboard contents will be removed before passing the +clipboard contents to an application. This is useful, for example, if the +clipboard contains a &URL; with spaces which, if opened by a web browser, would +cause an error.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Replay actions on an item selected from +history</guilabel></term> +<listitem><para>If this is switched on, selecting an item from the history +causes &klipper; to display the actions pop-up on that item, if +appropriate.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Prevent empty clipboard</guilabel></term> +<listitem><para>If selected, the clipboard will never be empty: &klipper; will +insert the most recent item from the clipboard history into the clipboard +instead of allowing it to be empty.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Ignore selection</guilabel></term> +<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Synchronize contents of the clipboard and the +selection</guilabel></term> +<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Separate clipboard and selection</guilabel></term> +<listitem><para>Sets the clipboard mode. See <xref linkend="clipboard-modes"/>. +</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Timeout for Action pop-ups</guilabel></term> +<listitem><para>Set the time that a pop-up menu will remain for if you do +nothing with it.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Clipboard history +size</guilabel></term> +<listitem><para>Sets the number of items that are stored +in the clipboard history.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="actions-tab"> +<title>Actions Options</title> + +<variablelist> +<varlistentry> +<term>Editing Expressions/Actions</term> +<listitem><para>On the <guilabel>Actions</guilabel> tab, double-click +the regular expression or action that you want to edit. An in-place text editing +box will appear in which the text can be edited as you wish. Make sure you +press <keysym>Enter</keysym> when you are done.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Adding Expressions/Actions</term> +<listitem><para>Click the <guibutton>Add Action</guibutton> button +to add a regular expression for &klipper; to match. &klipper; uses +&Qt;'s <classname>QRegExp</classname>, which understands most regular +expressions as you would use in <application>grep</application> or +<application>egrep</application> for instance.</para> +<para>You can add a description of the regular expression type (⪚ +<quote>HTTP URL</quote>) by <mousebutton>left</mousebutton> clicking in the +<guilabel>Description</guilabel> column.</para> + +<note><para>You can find detailed information about the use of +<classname>QRegExp</classname> regular expressions at <ulink +url="http://doc.trolltech.com/qregexp.html#details">http://doc.trolltech.com/qregexp.html#details</ulink>. +Note that &klipper; does not support the wildcard mode mentioned on this +page.</para></note> + +<para>Edit the regular expression as described above. To add a command +to execute, <mousebutton>right</mousebutton> click, select +<guimenuitem>Add Command</guimenuitem> and edit the command which +appears in the tree under the regular expression.</para> + +<para>Note that <token>%s</token> in the command line is replaced with +the clipboard contents, ⪚ if your command definition is +<userinput><command>kedit</command> <token>%s</token></userinput> and +your clipboard contents are <filename>/home/phil/textfile</filename>, +the command <userinput><command>kedit</command> +<filename>/home/phil/textfile</filename></userinput> will be run. To +include <token>%s</token> in the command line, escape it with a +backslash, as so: <userinput>\%s</userinput>.</para></listitem> +</varlistentry> + +<varlistentry><term><guibutton>Advanced...</guibutton></term> +<listitem><para>Brings up the <guilabel>Disable Actions for windows of type +WM_CLASS</guilabel> dialog.</para> +<para>Some programs, such as &konqueror;, +use the clipboard internally. If you get unwanted &klipper; pop-ups all the time +when using a certain application, do the following:</para> + +<orderedlist> +<listitem><para>Open the application.</para></listitem> +<listitem><para>From a terminal, run <userinput><command>xprop</command> +| <command>grep</command> <parameter>WM_CLASS</parameter></userinput> +and then click on the window of the application you are +running.</para></listitem> +<listitem><para>The first string after the equals sign is the one to +enter.</para></listitem> +</orderedlist> + +<para>Once the WM_CLASS is added, no more actions will be generated for +windows of that application.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="shortcuts-tab"> +<title>Shortcuts Options</title> + +<para>The shortcuts tab allows you to change the keyboard shortcuts +which are used to access &klipper; functions. You can change the +shortcut to one of three things:</para> + +<variablelist> +<varlistentry> +<term><guilabel>None</guilabel></term> +<listitem><para>The selected action cannot be accessed directly from the +keyboard</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Default</guilabel></term> +<listitem><para>The selected action uses &klipper;'s default key. These are the +shortcuts referred to in this manual.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Custom</guilabel></term> +<listitem><para>The selected action is assigned to the keys you choose.</para> +<para>To choose a custom key for the action you have selected, click on the +representation of a key in the lower right of the screen to activate it, and +type the desired key combination on your keyboard, as in any &kde; application. +</para> </listitem> +</varlistentry> +</variablelist> + +</sect1> +</chapter> + +<chapter id="credits"> +<title>Credits and License</title> + +<para> +&klipper; +</para> +<para> +Program copyright 1998 Andrew Stanley-Jones <email>[email protected]</email> +</para> +<para> +Program copyright 1998-2000 &Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;</para> +<para> +Currently maintained by Esben Mose Hansen. See <ulink +url="http://mosehansen.dk/about">http://mosehansen.dk/about</ulink> +for contact details. +</para> + +<para> +Documentation copyright 2000-2003, 2005 &Philip.Rodrigues; +&Philip.Rodrigues.mail;</para> + +&underFDL; +&underGPL; + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-klipper"> +<title>How to obtain &klipper;</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> +<para>&klipper; should compile and install along with the kdebase +package, and appear on your &kde; panel (&kicker;) when you run &kde; +3. If it does not appear, you can start it by selecting +<menuchoice><guimenu>Panel +Menu</guimenu><guisubmenu>Add</guisubmenu><guisubmenu>Applet</guisubmenu><guimenuitem>Klipper</guimenuitem> +</menuchoice> +in any context menu in &kicker;, the &kde; Panel.</para> + +<screenshot> +<screeninfo>&klipper; icon</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="screenshot.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> + +<!-- +<para>To remove &klipper; from your panel, select <guimenuitem>Remove +Klipper</guimenuitem> from the context menu (accessed by left-clicking the +small handle to the left of the &klipper; icon).</para> +--> +<!-- +<para>To disable this, simply remove the file +<filename>$<envar>KDEDIR</envar>/share/autostart/klipper.desktop</filename> +or create a file <filename>$<envar>HOME</envar>/share/autostart/klipper.desktop</filename> +with the following contents: + +<programlisting> +[Desktop Entry] +Hidden=true +</programlisting> + +The latter will keep the system installation intact and only prevent +&klipper; being started for you, without affecting other users. +</para> +--> +</sect1> +</appendix> + +&documentation.index; + +</book> +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-indent-step: 0 +End: +--> + + + + + + + + + + diff --git a/doc/klipper/screenshot.png b/doc/klipper/screenshot.png Binary files differnew file mode 100644 index 000000000..2b1fbbafe --- /dev/null +++ b/doc/klipper/screenshot.png diff --git a/doc/kmenuedit/Makefile.am b/doc/kmenuedit/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kmenuedit/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kmenuedit/done.png b/doc/kmenuedit/done.png Binary files differnew file mode 100644 index 000000000..c614475a7 --- /dev/null +++ b/doc/kmenuedit/done.png diff --git a/doc/kmenuedit/index.docbook b/doc/kmenuedit/index.docbook new file mode 100644 index 000000000..73cb76ced --- /dev/null +++ b/doc/kmenuedit/index.docbook @@ -0,0 +1,521 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY package "kdebase"> + <!ENTITY firefox "<application>Firefox</application>"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> + +<title>The &kmenuedit; Handbook</title> + +<authorgroup> +<author>&Milos.Prudek; &Milos.Prudek.mail;</author> + +<othercredit role="reviewer"> +&Lauri.Watts; &Lauri.Watts.mail; +<!-- <contrib>Reviewer</contrib> --> +</othercredit> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2000</year> +<holder>&Milos.Prudek;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2006-11-23</date> +<releaseinfo>0.7 (&kde; 3.5.5)</releaseinfo> + +<abstract><para>&kmenuedit; allows editing of the &kde; &kmenu;. +</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KDE Menu Editor</keyword> +<keyword>kmenuedit</keyword> +<keyword>application</keyword> +<keyword>program</keyword> +<keyword>menu</keyword> +<keyword>kicker</keyword> + +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kmenuedit; allows editing of &kde; &kmenu;.</para> + +<para>&kmenuedit; can be started either by &RMB; clicking the +&kmenu; button on the panel and choosing +<guimenuitem>Menu Editor</guimenuitem>, or by choosing +<guimenuitem>Menu Editor</guimenuitem> from the +<guisubmenu>Settings</guisubmenu> submenu of the &kmenu;.</para> + +<para>&kmenuedit; allows you to:</para> + +<itemizedlist> +<listitem><para>View and edit the current &kmenu;</para></listitem> +<listitem><para><guimenuitem>Cut</guimenuitem>, <guimenuitem>Copy</guimenuitem> +and <guimenuitem>Paste</guimenuitem> menu items</para></listitem> +<listitem><para>Create and delete submenus</para></listitem> +</itemizedlist> + +</chapter> + +<chapter id="quickstart"> +<chapterinfo> +<authorgroup> +<author>&Virgil.J.Nisly; &Virgil.J.Nisly.mail;</author> +</authorgroup> +</chapterinfo> +<title>A Quick Start Guide to Adding an Entry to the &kmenu;</title> + + <para>In this example, we will add &firefox; to the <guisubmenu>Internet</guisubmenu> submenu. <note><para>Most applications can be added with &kappfinder;, &firefox; can usually be added that way, but was used for lack of a better example.</para></note></para> + <para>To start off, we need to open &kmenuedit;, so &RMB; on the &kmenu;, click <guimenuitem>Menu Editor</guimenuitem> to start &kmenuedit;. After &kmenuedit; has started, select <guisubmenu>Internet</guisubmenu> as shown in picture below. +<screenshot> +<screeninfo>Select <guisubmenu>Internet</guisubmenu></screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="selectinternet.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>Select <guisubmenu>Internet</guisubmenu></phrase> +</textobject> +</mediaobject> +</screenshot></para> + <para> + Once you have selected <guisubmenu>Internet</guisubmenu>, click on <menuchoice><guimenu>File</guimenu><guimenuitem>New Item...</guimenuitem></menuchoice>, opening the <guilabel>New Item</guilabel> dialog, as shown below. Type the name of the program you want to add, in this case, type <userinput>firefox</userinput>. +<screenshot> +<screeninfo><guilabel>New Item</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="itemname.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>New Item</guilabel> dialog.</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> +<para> +Press return, and you should see something like the picture below in the main window. +<screenshot> +<screeninfo>New Item</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="new.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The new item created.</phrase> +</textobject> +</mediaobject> +</screenshot></para> + +<para> + Now lets fill in the <guilabel>Description:</guilabel>, in this case type <userinput>Web Browser</userinput>. <note><para>The description and name will be displayed on the &kmenu; as <quote>Web Browser (Firefox)</quote>.</para></note> We will need to fill in the executable name in the <guilabel>Command:</guilabel> field, in this instance we will type <userinput><command>firefox</command></userinput>.</para> +<note><para>Following the command, you can have several place holders which will be replaced with actual values when the program is run: +<simplelist> +<member>%f - a single file name</member> +<member>%F - a list of files; use for applications that can open several local files at once</member> +<member>%u - a single &URL;</member> +<member>%U - a list of &URL;s</member> +<member>%d - the folder of a file to open</member> +<member>%D - a list of folders</member> +<member>%i - the icon</member> +<member>%m - the mini icon</member> +<member>%c - the caption</member> +</simplelist></para> +<informalexample><para>For example: if you want to firefox to start your web browsing at www.kde.org - instead of <command>firefox</command> you would type <command>firefox %u www.kde.org</command>.</para></informalexample></note> +<para>We would like to have a more creative icon, so we will click the generic icon sitting beside <guilabel>Name:</guilabel>. It will bring the <guilabel>Select Icon</guilabel> dialog which will let us choose the new icon, as shown below. +<screenshot> +<screeninfo><guilabel>Select Icon</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="selecticon.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The <guilabel>Select Icon</guilabel> dialog.</phrase> +</textobject> +</mediaobject> +</screenshot></para> + + <para>We choose the firefox icon from the list, and press return. Your finished screen should probably look something like the screenshot below. +<screenshot> +<screeninfo>Done screenshot</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="done.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>This is what the completed menu item should looks like.</phrase> +</textobject> +</mediaobject> +</screenshot></para> + +<para>Click <menuchoice><guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice>, wait for the <guilabel>Updating System Configuration</guilabel> dialog to get finished, you should find &firefox; in the &kmenu; <guisubmenu>Internet</guisubmenu> submenu!</para> + + + +</chapter> + +<chapter id="using-kmenuedit"> +<title>Using &kmenuedit;</title> + +<para>The left application panel shows the &kmenu; structure. When +you browse items in the left panel, the right panel shows detailed +information for the highlighted menu item.</para> + +<sect1 id="details-general"> +<title>General program information</title> + +<variablelist> +<varlistentry> +<term><guilabel>Name:</guilabel></term> +<listitem><para>This is the name of your program as it appears in the +&kmenu; menu. It can be different from the real executable +name. For instance the name of <command>mc</command> executable is +"<application>Midnight Commander</application>".</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Description:</guilabel></term> +<listitem><para>The description will be displayed together with the name in the &kmenu;. This is +entirely optional.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Comment:</guilabel></term> +<listitem><para>Describe the program in greater detail in this field. This is +entirely optional.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Command:</guilabel></term> +<listitem><para>This is the name of the executable program. Make sure that you +have permission to run the program.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Enable launch feedback</guilabel></term> +<listitem><para>If this box is checked, this will display feedback when an application is started +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Place in system tray</guilabel></term> +<listitem><para>When checked, the application's icon will show up in the panel system tray. +You will then be able to hide or show the application by clicking on the system +tray icon. Clicking on it using the &RMB; will allow also you to undock, or quit the +application. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guiicon>Icon List</guiicon></term> +<listitem><para>Click +this icon to display a choice of icons. Choose an icon for your +program.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Work path:</guilabel></term> +<listitem><para>Specify the work path of the program. This will be the current +path when the program launches. It does not need to be the same as the +executable location.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Run in terminal</guilabel></term> +<listitem><para>You must check this if your program requires terminal emulator +in order to run. This mainly applies to <link +linkend="gloss-console-application">console +applications</link>.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Terminal options:</guilabel></term> +<listitem><para>Put all terminal options in this field.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Run as a different user</guilabel></term> +<listitem><para>If you want to run this program as a different user (not you), +check this checkbox, and provide the username in the +<guilabel>Username:</guilabel> field.</para></listitem> +</varlistentry> +</variablelist> + +<para>You can assign a special keyboard shortcut to launch your program.</para> + +<para>Click the <guibutton>None</guibutton> button to the right of the <guilabel>Current +shortcut key:</guilabel> checkbox.</para> + +<para>A dialog box will pop up, allowing you to assign a <guilabel>Primary shortcut:</guilabel> +by pressing the key combination on your keyboard that you want to be assigned to your program. +It might be useful to assign a second +keybinding to the same item by checking the +<guilabel>Alternate shortcut:</guilabel> button, for +example, if you often switch keyboard maps, and some shortcuts are not +as convenient to type at all times.</para> + +<para>Click the <guiicon>x</guiicon> to clear the shortcut, if you +made a mistake. Check the <guilabel>Multi-key mode</guilabel> box if you +want to assign a shortcut that uses more than one key.</para> + +<para>The dialog will close when you have selected a keybinding. +</para> + +</sect1> + +</chapter> + +<chapter id="menu-reference"> +<title>Menu Reference</title> + +<variablelist> +<varlistentry id="file-new-item"> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo></shortcut> +<guimenu>File</guimenu> <guimenuitem>New Item...</guimenuitem> +</menuchoice></term> <listitem><para><action>Adds new menu +item.</action></para></listitem> +</varlistentry> + +<varlistentry id="file-new-submenu"> +<term><menuchoice> +<guimenu>File</guimenu> +<guimenuitem>New Submenu...</guimenuitem> +</menuchoice></term> +<listitem><para><action>Adds new submenu.</action></para></listitem> +</varlistentry> + +<varlistentry id="file-new-separator"> +<term><menuchoice><guimenu>File</guimenu><guimenuitem>New +Separator</guimenuitem></menuchoice></term> +<listitem> +<para><action>Adds a new separator to the menu.</action></para> +</listitem> +</varlistentry> + +<varlistentry id="file-save"> +<term><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>S</keycap></keycombo></shortcut> +<guimenu>File</guimenu><guimenuitem>Save</guimenuitem> +</menuchoice></term> +<listitem> +<para><action>Saves the menu</action></para> +</listitem> +</varlistentry> + +<varlistentry id="file-quit"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Quits</action> &kmenuedit;.</para></listitem> +</varlistentry> + +<varlistentry id="edit-cut"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> +</shortcut> +<guimenu> +Edit</guimenu> <guimenuitem>Cut</guimenuitem> +</menuchoice></term> +<listitem><para><action>Cuts the current menu item to the clipboard.</action> If +you want to move menu item, you should first cut it to the clipboard, move to +the destination place using the left panel, and use the +<guimenuitem>Paste</guimenuitem> function to paste the menu item from the +clipboard.</para></listitem> +</varlistentry> + +<varlistentry id="edit-copy"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> +</shortcut> +<guimenu> +Edit</guimenu> <guimenuitem>Copy</guimenuitem> +</menuchoice></term> +<listitem><para><action>Copies the current menu item to the +clipboard</action>. You can later use the <guimenuitem>Paste</guimenuitem> +function to paste the copied menu itemfrom the clipboard to its destination. You +can paste the same item many times.</para></listitem> +</varlistentry> + +<varlistentry id="edit-paste"> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem> </menuchoice></term> +<listitem><para><action>Paste menu item from the clipboard</action> to currently +selected place in the <guimenu>Main</guimenu> menu. You must first use +<guimenuitem>Cut</guimenuitem> or <guimenuitem>Copy</guimenuitem> before you can +<guimenuitem>Paste</guimenuitem>.</para></listitem> +</varlistentry> + +<varlistentry id="edit-delete"> +<term><menuchoice> +<shortcut><keycap>Delete</keycap></shortcut> +<guimenu>Edit</guimenu> <guimenuitem>Delete</guimenuitem> +</menuchoice></term> +<listitem><para><action>Deletes currently selected menu +item.</action></para></listitem> +</varlistentry> + +<varlistentry id="settings-hide-toolbar"> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show/Hide Toolbar</guimenuitem> +</menuchoice></term> +<listitem><para><action>Show or hide the toolbar</action></para></listitem> +</varlistentry> + +<varlistentry id="settings-configure-shortcuts"> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure +Shortcuts...</guimenuitem></menuchoice></term> +<listitem> +<para><action>Customize the keyboard shortcuts</action></para> +</listitem> +</varlistentry> + +<varlistentry id="settings-configure-toolbars"> +<term><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure +Toolbars...</guimenuitem></menuchoice></term> +<listitem> +<para><action>Customize the toolbar icons.</action></para> +</listitem> +</varlistentry> + +</variablelist> + +&help.menu.documentation; + +</chapter> + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&kmenuedit; +</para> +<para>Program copyright © 2002, &Raffaele.Sandrini;</para> + +<para>Contributors:</para> +<itemizedlist> +<listitem><para>&Matthias.Elter; &Matthias.Elter.mail; - Original +Author</para> +</listitem> +<listitem><para>&Matthias.Ettrich; &Matthias.Ettrich.mail;</para> +</listitem> +<listitem><para>&Daniel.M.Duley; &Daniel.M.Duley.mail;</para> +</listitem> +<listitem><para>&Preston.Brown; &Preston.Brown.mail;</para> +</listitem> +</itemizedlist> + +<para>Documentation copyright © 2000 &Milos.Prudek;</para> + +<para>Updated for &kde; 3.0 by &Lauri.Watts; &Lauri.Watts.mail; +2002</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> + +<glossary id="glossary"> +<title>Glossary</title> + +<glossentry id="gloss-terminal-emulator"> +<glossterm>Terminal emulator</glossterm> +<glossdef> +<para>Terminal emulator is simply a windowed shell; this is known as +<quote>command line window</quote> in some other environments. If you +want to use the shell, you should know at least a few of the +system-level commands for your operating system.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-applet"> +<glossterm>Applet</glossterm> +<glossdef><para>A small application that occupies very little memory +and screen space, and at the same time gives you some useful +information or provides a control shortcut. For instance the +<application>Clock</application> applet shows current time and date +(and even a month diary if you click it), and <application>System +Monitor</application> applet shows how busy your machine currently is +in real-time.</para> </glossdef> +</glossentry> + +<glossentry id="gloss-legacy-application"> +<glossterm>Legacy Application</glossterm> +<glossdef> + +<para>An X-window application which was not written with &kde; in +mind. Such applications run fine in &kde;. However, they are not +warned automatically when you shut down your &kde; session. You +therefore must not forget to save documents open in these applications +before you log out from &kde;. </para> <para>Additionally, many of +these applications do not support copying and pasting from +&kde; compliant applications. &Netscape; 4.x browser is a prominent +example of such application <footnote><para>Some <ulink +url="http://www.gnome.org">GNOME</ulink> applications may provide +limited interoperability with the &kde;.</para></footnote>.</para> +</glossdef> +</glossentry> + +<glossentry id="gloss-console-application"> +<glossterm>Console Application</glossterm> +<glossdef> + +<para>Application originally written for non-graphic, text oriented +environment. Such applications run fine in &kde;. They must run within +console emulator, like &konsole;. They are not warned automatically +when you shut down your &kde; session. You therefore must not forget +to save documents open in these applications before you log out from +the &kde;.</para> + +<para>Console applications support copying and pasting from +&kde;-compliant applications.Simply mark the text in the console +application with your mouse, switch to the &kde;-compliant application +and press <keycombo action="simul">&Ctrl; +<keycap>V</keycap></keycombo> to paste the text. If you want to copy +from &kde; application to a console application, first mark the text +with your mouse, press <keycombo action="simul">&Ctrl; +<keycap>C</keycap></keycombo>, switch to the console application and +press the middle button on your mouse<footnote><para>If your mouse +does not have a middle button, you must press +<mousebutton>left</mousebutton> and <mousebutton>right</mousebutton> +button at the same time. This is called <quote>middle button +emulation</quote> and it must be supported by your operating system to +work.</para></footnote>.</para> + +</glossdef> +</glossentry> + +</glossary> + +&documentation.index; + +</book> +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> + diff --git a/doc/kmenuedit/itemname.png b/doc/kmenuedit/itemname.png Binary files differnew file mode 100644 index 000000000..fb3d8a286 --- /dev/null +++ b/doc/kmenuedit/itemname.png diff --git a/doc/kmenuedit/kmenueditmain.png b/doc/kmenuedit/kmenueditmain.png Binary files differnew file mode 100644 index 000000000..46509372f --- /dev/null +++ b/doc/kmenuedit/kmenueditmain.png diff --git a/doc/kmenuedit/new.png b/doc/kmenuedit/new.png Binary files differnew file mode 100644 index 000000000..a26a1dd41 --- /dev/null +++ b/doc/kmenuedit/new.png diff --git a/doc/kmenuedit/selecticon.png b/doc/kmenuedit/selecticon.png Binary files differnew file mode 100644 index 000000000..c60363f37 --- /dev/null +++ b/doc/kmenuedit/selecticon.png diff --git a/doc/kmenuedit/selectinternet.png b/doc/kmenuedit/selectinternet.png Binary files differnew file mode 100644 index 000000000..92d63b092 --- /dev/null +++ b/doc/kmenuedit/selectinternet.png diff --git a/doc/knetattach/Makefile.am b/doc/knetattach/Makefile.am new file mode 100644 index 000000000..171f575ce --- /dev/null +++ b/doc/knetattach/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/knetattach/index.docbook b/doc/knetattach/index.docbook new file mode 100644 index 000000000..c5e7a4db0 --- /dev/null +++ b/doc/knetattach/index.docbook @@ -0,0 +1,349 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!-- Define an entity for your application if it is not part of KDE + CVS --> + <!ENTITY kappname "&knetattach;"> + <!ENTITY package "kdebase"><!-- I think this came from kdebase... --> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> + + <!-- Do not define any other entities; instead, use the entities + from entities/general.entities and $LANG/user.entities. --> +]> + +<book lang="&language;"> + +<!-- This header contains all of the meta-information for the document such +as Authors, publish date, the abstract, and Keywords --> + +<bookinfo> +<title>The &knetattach; Handbook</title> + +<authorgroup> +<author> +&Orville.Bennett; &Orville.Bennett.mail; +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +<copyright> +<year>2005</year> +<holder>&Orville.Bennett;</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-02-09</date> +<releaseinfo>1.01.00</releaseinfo> + +<abstract> +<para> +&knetattach; is an application which makes it easier to integrate your +network resources with your &kde; Desktop. +</para> +</abstract> + +<!-- This is a set of Keywords for indexing by search engines. +Please at least include KDE, the KDE package it is in, the name + of your application, and a few relevant keywords. --> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdebase</keyword> +<keyword>knetattach</keyword> +<keyword>Network Folders</keyword> +<keyword>Network Folder Wizard</keyword> +<keyword>KDE Network Folder Wizard</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +The &knetattach; program, affectionately and hereafter known as the +Network Folder Wizard, allows easy addition and integration of various +network folders with your &kde; desktop. Please report any problems or +feature requests for it to the &kde; bugs website. +</para> +</chapter> + +<chapter id="using-knetattach"> +<title>Using &knetattach;</title> + +<para> +As you will see in the screenshot below, the Network Folder Wizard currently allows +you to add four types of network folders: WebDav, FTP, +<trademark class="registered">Microsoft</trademark> +<trademark class="registered">Windows</trademark> (Samba) network drives and SSH. + +<screenshot> +<screeninfo>Here's a screenshot of &knetattach;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Screenshot</phrase> +</textobject> +<caption> +<para>Network Folder Wizard main window</para> +</caption> +</mediaobject> +</screenshot> +</para> + + +<sect1 id="knetattach-features"> +<title>Adding network folders</title> + +<para> +Network folders show up in a special location of &konqueror; called a +<emphasis>virtual folder</emphasis>. +This virtual folder is accessed by typing <userinput>remote:/</userinput> in +&konqueror; <interface>Location bar</interface>. You will then be able to see +any folders which have been previously added and you also will be able to use +the wizard to add new ones. +<screenshot> +<screeninfo>Here's a screenshot of &knetattach;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot1.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Screenshot</phrase> +</textobject> +<caption> +<para>The virtual folder with the Network Folder wizard</para> +</caption> +</mediaobject> +</screenshot> +</para> + +<para> +Speaking of wizards, the Network Folder Wizard aims at being very easy to use. +After opening the wizard you must choose the type of network folder you would +like to access. When you move on to the next screen you will just need to +fill in the requested information. The final step is entering your username and +login password for the network share you've chosen to access. +</para> +<para> +Below is a list of the information needed by the wizard to create the network folders. If an option is not +available for a particular folder it does not have to be entered. e.g. The Samba +folders do not require a <guilabel>Port</guilabel> entry. +</para> + +<para> +<variablelist> +<varlistentry> +<term><guilabel>Name:</guilabel></term> +<listitem> +<para> +This is where you give a name to the network connection. It is limited only by +your imagination (or alphabet). +</para> +</listitem> +</varlistentry> +<varlistentry> +<term>Server:</term> +<listitem> +<para> +This is the address of the server you are attempting to add. It can be an +IP address or domain name. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Port:</guilabel></term> +<listitem> +<para> +Here you enter the port number you wish to connect to. The defaults are usually +sufficient. +<note> +<para> +Not available for <trademark class="registered">Microsoft</trademark> +<trademark class="registered">Windows</trademark> (Samba) folders. +</para> +</note> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Folder:</guilabel></term> +<listitem> +<para> +The path to the folder you wish to connect to should go here. +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Create an icon for this remote folder</guilabel></term> +<listitem> +<para> +If this box is checked an icon will be created allowing access through the +remote:/ virtual folder. If it is not checked, a connection will be possible +but it will not be accessible from remote:/. +<note> +<para> +The <guilabel>Recent connection:</guilabel> option allows you to re-connect to the +last network mount point you connected to using the wizard whether an icon is created or not. +</para> +</note> +</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Use encryption</guilabel></term> +<listitem> +<para> +If checked the ability to make a secure connection will be enabled. +<note> +<para>Available only for WebDav folders.</para> +</note> +</para> +</listitem> +</varlistentry> +</variablelist> +</para> + +</sect1> +</chapter> + +<chapter id="knetattach-walkthrough"> +<title>&knetattach; Walkthrough</title> + + +<para> +This will be a quick walkthrough of the Network Folder Wizard. Don't +blink or you might miss it. +</para> + +<para> +Below you see the main window of the Network Folder Wizard. It is here +that we choose what type of folder we want to add or connect to. For +the purposes of this walkthrough we will be using FTP. It contains most +of the options you will encounter while using the wizard. +</para> + +<para> +<screenshot> +<screeninfo>Here's a screenshot of the &knetattach; main window</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Screenshot</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +<para> +OK, so we (as in me) have chosen to add an FTP folder. Below you see +an example of the type of information you will need to add for your particular +FTP server. After filling it in we press <guibutton>Save & +Connect</guibutton> +and wait for the magic. Oh yes, if your server requires validation of some kind +you will be prompted at this point before being allowed to connect. +</para> + +<para> +<screenshot> +<screeninfo>Screenshot showing addition of FTP Folder +using &knetattach;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot2.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Screenshot</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +<para> +So now we are all connected now and able to navigate our newly added share. Joy! +</para> + +<para> +<screenshot> +<screeninfo>Screenshot of the connected FTP folder</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot3.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Screenshot</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +<para> +To get back to our network folders all that is necessary is typing <action>remote:/</action> +in the <guilabel>Location:</guilabel> bar of &konqueror;. +</para> + +<para> +<screenshot> +<screeninfo>Screenshot of the remote:/ virtual folder with the +added connection</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="screenshot4.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Screenshot</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +<para> +You can even add new folders from the same location by using the +<guilabel>Add a Network Folder</guilabel> link. Well that brings us to +the end of our walkthrough (told you it would be quick). I wish you the +best of luck in your own network folder adventures ;-) +</para> +</chapter> + +<chapter id="credits"> + +<title>Credits and License</title> + +<para> +&knetattach; +</para> +<para> +Program copyright 2004 &George.Staikos; &George.Staikos.mail; +</para> + +<para> +Documentation Copyright © 2005 &Orville.Bennett; &Orville.Bennett.mail; +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; <!-- FDL: do not remove --> +&underGPL; + +</chapter> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +kate: space-indent on; indent-width 2; tab-width 2; indent-mode none; +--> diff --git a/doc/knetattach/screenshot.png b/doc/knetattach/screenshot.png Binary files differnew file mode 100644 index 000000000..a22996512 --- /dev/null +++ b/doc/knetattach/screenshot.png diff --git a/doc/knetattach/screenshot1.png b/doc/knetattach/screenshot1.png Binary files differnew file mode 100644 index 000000000..1a9ef1001 --- /dev/null +++ b/doc/knetattach/screenshot1.png diff --git a/doc/knetattach/screenshot2.png b/doc/knetattach/screenshot2.png Binary files differnew file mode 100644 index 000000000..581fa167c --- /dev/null +++ b/doc/knetattach/screenshot2.png diff --git a/doc/knetattach/screenshot3.png b/doc/knetattach/screenshot3.png Binary files differnew file mode 100644 index 000000000..668d093e0 --- /dev/null +++ b/doc/knetattach/screenshot3.png diff --git a/doc/knetattach/screenshot4.png b/doc/knetattach/screenshot4.png Binary files differnew file mode 100644 index 000000000..13e375a05 --- /dev/null +++ b/doc/knetattach/screenshot4.png diff --git a/doc/kompmgr/Makefile.am b/doc/kompmgr/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kompmgr/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kompmgr/index.docbook b/doc/kompmgr/index.docbook new file mode 100644 index 000000000..2d70bc9d6 --- /dev/null +++ b/doc/kompmgr/index.docbook @@ -0,0 +1,433 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "kompmgr"> + <!ENTITY package "kwin"> + <!ENTITY % English "INCLUDE"> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> +<bookinfo> +<title>&kappname; Information</title> + +<authorgroup> +<author> +<personname><firstname>Thomas</firstname><surname>Luebking</surname></personname> +<email>[email protected]</email> +</author> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2005</year> +<holder>Thomas Luebking</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-01-15</date> +<releaseinfo>2.0.1</releaseinfo> + +<abstract> +<para>&kappname; is a composite rendering engine to be used by &kwin;.</para> +<para>This document is rather a general explanation of what it does, +how it works and what the restrictions are than a documentation how to use +it (as it works in the background automatically).</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kwin</keyword> +<keyword>render engine</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kappname; is based upon <application>xcompmgr</application>, Keith +Packards reference composing implementation for the use of the new X +features.</para> + +<para>A composite manager catches the output of the X windows and renders +them into a single picture that will be displayed on the screen. The advantage +of doing so is that you can do basically anything with the windows contents, +including blending them together (translucency) or attaching shadows. You +could also tint them, add a nasty advertise on any window, squeeze them, +fract them, add scanlines, or anything else you can imagine, limited by +your hardware.</para> + +</chapter> + +<chapter id="xorg"> +<title>Xorg</title> + +<para>You necessarily need <emphasis>X.org 6.8 or later</emphasis> to have +&kappname; work. X.org 6.7 or older or XFree86 won't work.</para> + +<sect1 id="xsetup"> +<title>Setup</title> +<para>You need to explicitly enable the Composite extension. Add a +new Section to your X.org configuration file:</para> + +<programlisting> +Section "Extensions" + Option "Composite" "Enable" +EndSection +</programlisting> + +<para>If supported by your <acronym>GPU</acronym> (the complex chip that +powers a modern graphics card), activate the Render acceleration. This is +best supported by <trademark>NVIDIA</trademark>, and less completely by ATI +cards.</para> + +<programlisting> +Section "Device" +.... +.... + Option "RenderAccel" "true" +.... +.... +EndSection</programlisting> + +<para>&kappname; should be available now. For more information, please see +the <link linkend="problems">FAQ</link>.</para> + +</sect1> + +</chapter> + +<chapter id="settings"> +<title>Settings</title> + +<para>This chapter describes which parameters you can tweak, how they will +result visually and their performance impact.</para> + +<sect1 id="translucency"> +<title>Translucency</title> + +<para>A translucent object is one that allows light to pass through it. In +terms of windows on your desktop, that means that the contents of windows +can be seen through the one on the top.</para> + +<para>Translucency allows you to emphasize special windows, have a 3 +dimensional view on your desktop, keep track of covered windows, and just +looks cute. The price is, that blending things together costs some system +capacity.</para> + +<para>You can independently configure translucency for the following +items:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Active windows</guilabel></term> +<listitem><para>It is suggested you deactivate translucency for the active +window. The main reason is for perfomance, and secondly because to scan the +content of a translucent window means your brain has to strip the irritating +throughshining information, which is tiring.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Inactive windows</guilabel></term> +<listitem><para>If you set inactive windows translucent, active windows will +appear emphasized and are easier to focus. However, if you choose a lower +value, you may have trouble to find an inactive window. If you choose very +low values (< 20%) you may not be able to distinguish +windows in their stack order - so you may accidently click the +<guibutton>OK</guibutton> button of a dialog when you just wanted to +activate a window. Optimal values are between 60% and +80%.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Moving windows</guilabel></term> +<listitem><para>Though it's a nice effect to have heavily translucent +(opacity < 20%) moving windows, there is a heavy price to pay in +performance, especially if you do not deactivate shadows (see below). Just +try out and if you feel your system is too slow, keep moving windows +opaque. This value also applies to windows in resize state.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Dock windows</guilabel></term> +<listitem><para>As docks like kicker are seldom if ever moved and usually of +limited size, this is purely visual and won't detrimentally affect your +system's performance.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Treat "keep above" windows as active ones</guilabel></term> +<listitem><para>If you set a window to keep above others, you usually want +to keep focus on it, so it can make sense to give it the same +emphasis.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Disable ARGB windows</guilabel></term> +<listitem><para>XRender supports windows with an alpha mask, &ie; +translucent sections. Currently there are no or only very few applications +that would make use of this feature, as it doesn't make any sense without +using a composite manager. This may change in the future.</para> +<para>On the other side, most gtk 1.x applications (⪚ +<application>xmms</application>) set such an alpha mask, resulting in +almost unusable windows (as long as the sublying windows are not black), so +you can disable the support for ARGB windows here to make use of gtk +applications. There will hopefully be a patch for gtk in the near future to +fix this.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="shadows"> +<title>Shadows</title> +<para>Why should anyone want his windows to throw shadows? Well, maybe just +because it looks cute, or because it allows a better window separation, +or... because it looks cute!</para> +<variablelist> +<varlistentry> +<term><guilabel>Use shadows</guilabel></term> +<listitem><para>As shadows cost some additional cpu/gpu power, they can be +deactivated, while keeping a general alpha channel capability.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Active window size</guilabel></term> +<term><guilabel>Inactive window size</guilabel></term> +<term><guilabel>Dock window size</guilabel></term> +<listitem><para>You may select different shadow sizes for different window +states/types. The values are not absolute, but will apply to your screen +resolution.</para> +<para>In principle, you can set every value you want (if you edit the config +file with a text editor, far beyond the offered <quote>32</quote>), but +bigger shadows cost more cpu/gpu power.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Vertical offset</guilabel></term> +<term><guilabel>Horizontal offset</guilabel></term> +<listitem><para>By default, the window would throw a <quote>all around +equal</quote> shadow, implying a frontal light source. Users familiar with +&MacOS; may like a vertical offset, &Windows; users may prefer a +slighter offset to the southeast. Experiment with the values until you are +happy.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Shadow color</guilabel></term> +<listitem><para>Usually shadows as the absence of light appear in shades of +grey (so the maximum shadow color is black, or no light at all). But hey, +this is a virtual world, and if you'd like to have even pink shadows, why +not?</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Remove shadows on move</guilabel></term> +<listitem><para>Check this if you need more performance (especially when +using translucent moving windows).</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Remove shadows on resize</guilabel></term> +<listitem><para>It's a good idea to check this item whether using +translucent resizing (moving) windows, or not. The windows shadow pixmap has +to be permanently recreated on resizes what has a deep impact on the system +performance.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="effects"> +<title>Effects</title> +<variablelist> +<varlistentry> +<term><guilabel>Fade-in windows</guilabel></term> +<term><guilabel>Fade between opacity changes</guilabel></term> +<listitem><para>Instead of just popping up a new window, you might want to +slowly fade it in. While this looks impressive, there is an equally +impressive price to pay in performance speed, and it is difficult to interact +meaningfully with windows that are in the process of fading. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Fade-in speed</guilabel></term> +<term><guilabel>Fade-out speed</guilabel></term> +<listitem><para>For the usability reasons mentioned under <guilabel>Fade-in +windows</guilabel>, it is most practical to use a fast fade in speed and +(for more eye candy) a slow fade out speed. This will provide you nice +effects and a smooth feeling system as well as low latency before +information appears.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +</chapter> + +<chapter id="problems"> +<title>Problems</title> + +<para>The whole Composite extension is quite new. It may cause several +problems and even crash X, so <emphasis>it is strongly suggested to not even +enable the Composite extension in Xorg.conf on mission critical production +systems</emphasis>. If you however can risk a slightly more unstable system, +it's certainly nice to have some eye candy around.</para> + +<para> +In this case you may notice some glitches. +Here are some common problems - and workarounds: +</para> + +<qandaset> +<qandaentry> +<question> +<para>I have X.org 6.8.x, but &kappname; fails to start</para> +</question> +<answer> +<para>You need to explicitly enable the Composite extension, add a new Section to /etc/X11/XorgConfig:</para> +<programlisting>Section "Extensions" + Option "Composite" "Enable" +EndSection</programlisting> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>Ok, &kappname; works, but it's horribly slow</para> +</question> +<answer> +<para>If supported by your <acronym>GPU</acronym> (mainly +<trademark>NVIDIA</trademark>, and somewhat by ATI cards), first make sure +you activated the Render acceleration</para> +<programlisting> +Section "Device" +.... +.... +Option "RenderAccel" "true" +.... +.... +EndSection +</programlisting> + +<para>If it's still slow, you can try to adjust your memory usage. Either +decrease you screen depth (⪚ from 24 to 16) or lower your resolution +(⪚ from 1280x1024 to 1024x768).</para> + +<para>Please notice that the currently limiting factor for the Composite +extension seems to be the CPU cache size.</para> + +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>After enabling the Composite extension, I cannot run any +<acronym>GLX</acronym> applications anymore. I've got an +<trademark>NVIDIA</trademark> card.</para> +</question> +<answer> +<para>To prevent some problems, <trademark>NVIDIA</trademark> deactivated the +GLX support when Coposite is active. Reactivating is possible, but may cause +problems on some kernel/driver/GPU combinations.</para> +<programlisting> +Section "Device" +.... +.... +Option "AllowGLXWithComposite" "true" +.... +.... +EndSection +</programlisting> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>I wanted to play a game using <acronym>SDL</acronym> (but not +<acronym>GL</acronym>), say <application>scummvm</application>, but when the +compmgr is active, all I can see is a shadow!</para> +</question> +<answer> +<para>This is a problem with the PictType reported by SDL.</para> + +<para>Workaround:</para> +<screen> +Instead of calling <command>scummvm</command> directly, call +<command>SDL_VIDEO_X11_VISUALID=0x24 scummvm</command> This will tell SDL to +use a supported format and you can play as ever. </screen> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para> Application XXX refuses to start after enabling the Composite +extension.</para> +<para>Application YYY breaks X after enabling the Composite +extension.</para> +<para>Application ZZZ looks weird after activating the composite +manager.</para> +</question> +<answer> +<para>The Composite extension is still experimental.</para> +<para>Workaround:</para> +<para>Instead of calling <command>appName</command> directly, call <command>XLIB_SKIP_ARGB_VISUALS=1 appName</command></para> +<para>Applications that are known to cause problems:</para> +<itemizedlist> +<listitem><para>All gtk1 applications (⪚ <application>gmplayer</application>, +<application>xmms</application>, <application>gaim</application>) - failing +startup or look unusable weird or crash X</para></listitem> +<listitem><para>&kuickshow; - displays only a black frame</para></listitem> +<listitem><para>&Qt; <application>Designer</application> - crashes +X</para></listitem> +<listitem><para>&kopete; - crashes X</para></listitem> +<listitem><para>&kolf; - crashes X</para></listitem> +</itemizedlist> +</answer> +</qandaentry> + +<qandaentry> +<question> +<para>I try to watch a video, but only see artefacts in the Video +Window.</para> +</question> +<answer> +<para>You're using <quote>xv</quote> as video backend. This is the overlay +mode, where the video content is written directly into the video card +memory, bypassing X. Therefore the window seems to be static (colored +background) and is not updated by the damage extension.</para> +<para> There will hopefully be a fix for this in the future. Currently I had +the best results using <application>Xine</application> but displaying +translucent videos isn't fast anyway.</para> +</answer> +</qandaentry> + +</qandaset> +</chapter> + +<chapter id="credits-and-licenses"> +<title>Credits and Licenses</title> + +<sect1 id="authors"> +<title>Authors</title> +<para>Thomas Luebking <email>[email protected]</email> - Editor</para> + +&underFDL; +&underGPL; +</sect1> + + +</chapter> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/konqueror/Makefile.am b/doc/konqueror/Makefile.am new file mode 100644 index 000000000..da8216ae4 --- /dev/null +++ b/doc/konqueror/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO +KDE_MANS = AUTO diff --git a/doc/konqueror/basics.docbook b/doc/konqueror/basics.docbook new file mode 100644 index 000000000..8940df621 --- /dev/null +++ b/doc/konqueror/basics.docbook @@ -0,0 +1,386 @@ +<chapter id="basics"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-20</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + +<title>&konqueror; Basics</title> + +<important><para>Like all &kde; applications, &konqueror; is highly + configurable. This document describes how &konqueror; behaves with the normal, + default settings.</para> +<para> A three button mouse can be useful when you are running +&konqueror; or any other &kde; application. If your mouse only has two buttons +then you should be able to set your system up so that you can simulate a &MMB; +by pressing both buttons at the same time.</para> +<para>You can read more about mouse usage in <xref +linkend="lmb-mmb"/></para> +<para>If you are used to having to double-click to perform an action, +then take care, because in common with the rest of &kde;, &konqueror; defaults +to single-clicking.</para></important> + +<sect1 id="konq-start"> +<title>Starting &konqueror;</title> + +<para>Being a combined File Manager and Browser, +&konqueror; will automatically +switch between the two modes as needed when it is running, but it is convenient +to be able to choose which mode is to be used when you start it up.</para> + +<itemizedlist> +<listitem><para>If you have a <guiicon>house</guiicon> shaped icon on the panel +or desktop, then <mousebutton>left</mousebutton> click on it to open +&konqueror; as a file manager.</para></listitem> + +<listitem><para>Or <mousebutton>left</mousebutton> click on <guiicon>world +</guiicon> shaped icon on the panel or desktop to open &konqueror; in browser +mode.</para></listitem> + +<listitem><para>From the <guimenu>K</guimenu> menu, select +<menuchoice><guisubmenu>Internet</guisubmenu><guimenuitem>Konqueror Web +Browser</guimenuitem></menuchoice> to start it as a browser, or +<guimenuitem>Home</guimenuitem> to launch &konqueror; in file manager mode. +</para></listitem> + +<listitem><para><keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo> +will open a <guilabel>Run Command</guilabel> dialog box, type +<userinput><command>konqueror</command></userinput> (lower case) and press +<keycap>Enter</keycap> or the <guibutton>Run</guibutton> button to start in +file +manager mode, or just enter a &URL; such as + <userinput>http://www.konqueror.org</userinput> to start &konqueror; as a +browser.</para></listitem> + +</itemizedlist> + +<para>&konqueror; is also started automatically when you +<mousebutton>left</mousebutton> click on a desktop icon that represents a +folder, such as a hard disk drive or the <guiicon>Trash</guiicon> icon. +</para> + + +</sect1> + +<sect1 id="parts"> +<title>The Parts of &konqueror;</title> + +<para>A brief look at the main parts of &konqueror;'s window:</para> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="parts.png"/></imageobject> +<textobject> +<phrase>Here's a screenshot of &konqueror;</phrase> +</textobject> +</mediaobject> + +<para>The <interface>Titlebar</interface> is the strip across the top of +&konqueror;'s window, and operates in the same way as for other &kde; +applications. <mousebutton>Right</mousebutton> click on the central portion to +bring up the neat Titlebar menu.</para> + +<para>The <interface>Menubar</interface> is the strip containing the names of +the drop-down menus. <mousebutton>Left</mousebutton> click on a name to +alternately show and hide that menu, or use <keycombo +action="simul">&Alt;<keycap>the underlined +letter</keycap></keycombo> in the name as a hot key, for example <keycombo +action="simul">&Alt;<keycap>E</keycap></keycombo> to show the +<guimenu>Edit</guimenu> menu. The various menus are described in the <link +linkend="menubar">Menubar</link> section of this document.</para> + +<para>The <interface>Toolbar</interface> contains icons for commonly used +operations. <mousebutton>Left</mousebutton> clicking on an icon will activate +it. If you have enabled tooltips in the Control Center <menuchoice><guimenu> +Appearance & +Themes</guimenu><guisubmenu>Style</guisubmenu></menuchoice> +dialog a brief description of what that icon does will appear when you hover +the pointer over it.</para> + +<para>Some icons, for example the Up and Back icons in the previous screenshot, +have a small black triangle at their bottom right corner. If you hold the &LMB; +pressed while the cursor is over this type of icon a small dropdown menu will +appear.</para> <para><mousebutton>Right</mousebutton> clicking on the +<interface>Toolbar </interface> will bring up the <link +linkend="rmb-menus"><guilabel>Toolbar Menu</guilabel></link> which you can use +to change the <interface>Toolbar</interface>'s appearance and position.</para> + +<para>The <interface>Location Toolbar</interface> shows the path to the +directory, &URL; or file being viewed. You can type a path or &URL; here and +press &Enter; or <mousebutton>left</mousebutton> click on the +<guiicon>Go</guiicon> icon at the right hand end of the <interface>Location +Toolbar</interface> to go to it. The black icon at the left hand end of the +<interface>Location Toolbar</interface> clears the text entry box.</para> + +<para>The <interface>Bookmark Toolbar</interface> is the area under the +<interface>Location Toolbar</interface> in the previous screenshot. You can add +frequently used bookmarks here; see the <link +linkend="orgbmark">Organizing +Your +Bookmarks</link> section of this document.</para> + +<para>The <interface>Window</interface> is the main area of &konqueror; and +can show you the contents of a directory, web page, document or image. Using +the <link linkend="menu-window"><guimenu>Window</guimenu></link> menu you can +split &konqueror;'s main window into one or more separate views, useful for +drag and drop operations, or set it to contain two or more tabbed views. +</para> + +<para>The <interface>Status Bar</interface> runs across the bottom of the +&konqueror;'s window +and often shows general information about whatever the mouse pointer is +hovering +over. If you have split the main window into a number of views you will get an +Status Bar for each view, and it will include a small green light at the left +hand end to show which is the <quote>active</quote> +view. <mousebutton>Right</mousebutton> clicking on the Status Bar brings up the +Status Bar <link linkend="rmb-menus"><mousebutton>Right</mousebutton> Mouse +Button Menu</link>.</para> + +<note><para>Don't worry if your &konqueror; doesn't look exactly like this +screenshot; it is highly configurable. In particular:</para> + +<itemizedlist> +<listitem><para>You can use the <link +linkend="menu-settings"><guimenu>Settings</guimenu></link> menu to choose +whether to show or hide the Menubar, Main Toolbar, Location Toolbar and +Bookmark Toolbar, or even to add an Extra Toolbar.</para></listitem> +<listitem><para>You can also <quote>flatten</quote> the toolbars by +<mousebutton>left</mousebutton> clicking on the vertical lines at the left hand end +of the bars, or move them around by holding the &LMB; down while you +drag these bars around. </para></listitem> +<listitem><para>This screenshot does not show the optional <link linkend="sidebar"> +Navigation Panel</link>.</para></listitem> +</itemizedlist> + +<para>For more details of how to change &konqueror;'s appearance, see the <link +linkend="config">Configuring &konqueror;</link> section</para></note> + +</sect1> + +<sect1 id="bubble"> +<title>Tooltips and What's This?</title> + +<para>You can find out a lot about how &konqueror; works without needing to +read +this entire document if you take advantage of <guilabel>Tooltips</guilabel> and + the +<guimenuitem>What's This?</guimenuitem> feature.</para> + +<para>If <guilabel>Tooltips</guilabel> have been enabled in &kde; (K menu + <menuchoice><guimenu>Control Center</guimenu><guisubmenu>Appearance & + Themes</guisubmenu><guisubmenu>Style</guisubmenu></menuchoice>, + <guilabel>Style</guilabel> dialog) then when you hover the mouse pointer + over a Toolbar or Navigation Panel +button it should bring up a terse description of what that button does.</para> + +<para><guimenuitem>What's This?</guimenuitem> is invoked by the Menubar +<menuchoice><guimenu>Help</guimenu><guimenuitem>What's This?</guimenuitem></menuchoice> item, by +<keycombo action="simul">&Shift;<keycap>F1</keycap></keycombo>, or by +just &LMB; clicking on the question mark near the top right hand corner of +&konqueror;'s window. It changes the cursor to show a question mark alongside +the arrow.</para> + +<para>When this question mark is visible, a &LMB; click won't actually do +anything until you have clicked on a control (or the text alongside it) that +supports <guimenuitem>What's This?</guimenuitem>, in which case it will +display +a reasonably comprehensive description of what the control is supposed to do. +Most of the dialog boxes that &konqueror; brings up support the +<guimenuitem>What's This?</guimenuitem> feature.</para> + +</sect1> + +<sect1 id="lmb-mmb"> +<title><mousebutton>Left</mousebutton> and <mousebutton>Middle</mousebutton> +Mouse Button Actions</title> + +<para>If you click the &LMB; on an item in &konqueror;'s window, it will + be +<quote>activated</quote>. Thus</para> + +<itemizedlist> + +<listitem><para><mousebutton>Left</mousebutton> click on an icon in the Toolbar +to do whatever that icon is supposed to do. </para></listitem> +<listitem><para><mousebutton>Left</mousebutton> click on an item in the Menubar +to make that menu drop down.</para></listitem> +<listitem><para><mousebutton>Left</mousebutton> click on a menu item to do that +thing.</para></listitem> +<listitem><para><mousebutton>Left</mousebutton> click on an icon in the +Bookmark + Toolbar +to open that &URL;.</para></listitem> +<listitem><para><mousebutton>Left</mousebutton> click on a link in a web page +to make &konqueror; follow that link.</para></listitem> +<listitem><para><mousebutton>Left</mousebutton> click on a folder icon or +name and &konqueror; will descend into (show the contents of) that folder. +</para></listitem> +<listitem><para><mousebutton>Left</mousebutton> click on a file name or icon +and &konqueror; will do whatever it thinks appropriate, based on the file type. +In general this means opening <acronym>HTML</acronym> pages, or previewing +text, image or +<application>KOffice</application> files, showing them within &konqueror;'s +window (<quote>Preview</quote> means that you can see the file but not change +it).</para> + +<para>&konqueror; decides what the file type is by matching the filename +extension against a list of known types. If that fails it tries to guess +the type from the file contents. You can change the list of known file types +and associated actions with the <guilabel>File Associations</guilabel> page of +the <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Konqueror... +</guimenuitem></menuchoice> dialog.</para></listitem> + +</itemizedlist> + +<para>Clicking the &MMB; on a file or folder name or icon does essentially the +same as <mousebutton>left</mousebutton> clicking except that it usually does it +in a new &konqueror; window, unless the <guilabel>Open links in new tab instead +of in new window</guilabel> box has been checked in the +<guimenuitem>Behavior</guimenuitem> page of the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure + +Konqueror...</guimenuitem></menuchoice> dialog. &konqueror; can open +links on pages and <menuchoice><guimenu>Bookmarks</guimenu></menuchoice>, +as well as the +<guibutton>Home</guibutton>, <guibutton>Up</guibutton>, +<guibutton>Back</guibutton> and <guibutton>Forward</guibutton> +entries in a new tab or window.</para> + +<para>Holding the &Shift; key down while pressing the &MMB; will open the link +in the background.</para> +<important><para>If you click the &MMB; when the mouse cursor is over a blank +part of the main view (not over a link or file name or icon) &konqueror; will +copy the contents of the clipboard into the Location Toolbar and try to use +that as a &URL;.</para></important> +</sect1> + +<sect1 id="rmb-menus"> +<title><mousebutton>Right</mousebutton> Mouse Button Menus</title> + +<para>Clicking the &RMB; on almost any part of &konqueror;'s window +will bring up an appropriate context menu.</para> + +<note><para>If you have enabled the <guilabel>Right click goes back in +history</guilabel> option in &konqueror;'s <link linkend="othersettings"> +configuration</link> settings a +simple <mousebutton>right</mousebutton> click is equivalent to clicking on the +<guibutton>Back</guibutton> button. In this case you can access the context +menu by moving the mouse with the <mousebutton>right</mousebutton> button held +down.</para></note> + +<variablelist> + +<varlistentry> +<term>On the Titlebar</term> +<listitem><para><mousebutton>Right</mousebutton> clicking on any free area of +the Titlebar brings up the Titlebar Menu, allowing you to control the position +of &konqueror;'s window as well as the decoration applied to all &kde; program +windows. </para></listitem> +</varlistentry> + +<varlistentry> +<term>On the Main Toolbar</term> +<listitem><para><mousebutton>Right</mousebutton> click on any free area of the +Toolbar to bring up the Toolbar Menu. You can use it to control whether the +Toolbar is at the top, bottom, left or right of &konqueror;'s window. +You can also use the Toolbar Menu to set the size of the buttons on the +Toolbar, +and whether they are shown as icons, text or both.</para></listitem> +</varlistentry> + +<varlistentry> +<term>On the Location Toolbar</term> +<listitem><para><mousebutton>Right</mousebutton> click in the + &URL; +entry box area to perform Cut, Copy, Paste or Clear operations in this area, or +to change the automatic <link linkend="path-complete">Text Completion</link> +features.</para></listitem> +</varlistentry> + +<varlistentry> +<term>On the Bookmark Toolbar</term> +<listitem><para> If you have the Bookmark Toolbar showing, then +<mousebutton>right</mousebutton> click on any free part of it to bring up the +Bookmark Toolbar Menu which lets you change its position and whether items are +shown as text, icons, or both. </para></listitem> +</varlistentry> + +<varlistentry> +<term>Within a View</term> +<listitem><para>If you <mousebutton>right</mousebutton> click on any free area +of a view then you will get a menu that contains, among other options, the + <guiicon>Up</guiicon>, +<guiicon>Back</guiicon>, <guiicon>Forward</guiicon> and +<guiicon>Reload</guiicon> navigation commands. + </para></listitem> +</varlistentry> + +<varlistentry> +<term>On a File or Folder</term> +<listitem><para>This is a most useful feature. <mousebutton>Right</mousebutton> +clicking on the name or icon of any file or folder not only +<quote>selects</quote> that item but also brings up a menu allowing you to +<guiicon>Cut</guiicon>, Move, <guiicon>Copy</guiicon> or Remove the item in +various +ways, add it to your <guimenu>Bookmarks</guimenu>, open it with the program of +your choice or preview it, rename it, or edit the file type or +properties.</para></listitem> </varlistentry> + +<varlistentry> +<term>On the Status Bar</term> +<listitem><para><mousebutton>Right</mousebutton> click on the Status Bar at the +bottom of a window or view to add or remove a view within &konqueror;'s +window.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="man-info"> +<title>Viewing Help, Man and Info Pages</title> + +<para>You can view &kde; Help and &UNIX; Man and Info pages directly in +&konqueror;, without having to start up <application>KHelpCenter</application>. +</para> + +<para>To view a &kde; Help page, enter +<userinput>help:/<replaceable>application name</replaceable></userinput> (for +example <userinput>help:/kmail</userinput> to view the &kmail; documentation.) +into &konqueror;'s Location Toolbar window. +</para> + +<para> +If you want to read &UNIX; Man pages &konqueror; makes it easy. For +example type <userinput>man:/touch</userinput> or +<userinput>#touch</userinput> into the Location Toolbar to see the page for +the <command>touch</command> command.</para> + +<para>To browse through &UNIX; Info pages, entering +<userinput>info:/dir</userinput> takes you to Info's top level directory, then +it's just a matter of clicking on the right links to find the page you +want. Alternatively, use <userinput>info:/<replaceable>command +name</replaceable></userinput> to go straight to the Info page you want.</para> + +<note><para>Unfortunately, &kde; Help pages are stored in such a way that they +cannot be viewed in other browsers. If you really need to do this your only +recourse is to go online and visit <ulink url="http://docs.kde.org"> +http://docs.kde.org</ulink>.</para></note> +</sect1> + +</chapter> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/bookmarks.docbook b/doc/konqueror/bookmarks.docbook new file mode 100644 index 000000000..99eac7ab7 --- /dev/null +++ b/doc/konqueror/bookmarks.docbook @@ -0,0 +1,129 @@ +<chapter id="bookmarks"> +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-05</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + +<title>Using Bookmarks</title> + +<para>Although you can use &konqueror;'s bookmarks to record the locations of +your own files and folders, they are most useful when you are surfing the +Web, letting you build up a list of useful sites.</para> + +<para>To open the <guimenu>Bookmarks</guimenu> menu you may either +<mousebutton>left</mousebutton> click on the +<guimenu>Bookmarks</guimenu> menu or use the <keycombo +action="simul">&Alt;<keycap>B</keycap></keycombo> shortcut. Once +the list is visible, you can navigate through it with the arrow keys or with +your mouse, then press &Enter; or +<mousebutton>left</mousebutton> click to visit the selected location.</para> + +<para>To add a new item to the list use <menuchoice><guimenu>Bookmarks +</guimenu><guimenuitem>Add Bookmark</guimenuitem></menuchoice> or +<keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo> or +<mousebutton>right</mousebutton> click on a clear space in the web page or +folder view and select <guimenuitem>Bookmark this Location</guimenuitem> from +the pop up menu.</para> + +<para>The <guimenu>Bookmarks</guimenu> list can contain subfolders containing +other bookmarks, you can create these with <menuchoice><guimenu>Bookmarks +</guimenu><guimenuitem>New Bookmark Folder...</guimenuitem></menuchoice> . +To add a bookmark into a subfolder rather than into the main Bookmark list, +select the folder from within the <guimenu>Bookmarks</guimenu> list and use +the <guimenuitem>Add Bookmark</guimenuitem> item in that folder.</para> + +<para>You can also access your bookmarks from the <link linkend="sidebar"> +<guilabel>Navigation Panel</guilabel></link>.</para> + +<sect1 id="orgbmark"> +<title>The Bookmark Editor</title> + +<para>The <menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Edit +Bookmarks</guimenuitem> </menuchoice> option opens the <guilabel>Bookmark +Editor</guilabel>.</para> +<para>This shows a tree view of your bookmarks and bookmark subfolders. +As is usual for tree views in &kde;, subfolders are shown with a small square +at the left of the folder name; if the square contains a <keycap>+</keycap> +sign <mousebutton>left</mousebutton> clicking on it will expand the view to +show the contents of that subfolder and the <keycap>+</keycap> sign will +change to <keycap>-</keycap>, <mousebutton>left</mousebutton> clicking on the +<keycap>-</keycap> sign will collapse the subfolder view.</para> + +<para>To select an item in the list you can <mousebutton>left</mousebutton> +click on it, or you can navigate through the list by using the <keysym> +Up arrow</keysym> and <keysym>Down arrow</keysym> keys to move around, +<keysym>Right arrow</keysym> to expand a subfolder and <keysym> +Left arrow</keysym> to collapse it.</para> + +<para>You can move an item to a different place in the list by using the +normal Drag and Drop or <guimenuitem>Cut</guimenuitem> and <guimenuitem> +Paste</guimenuitem> methods. The order in which the items appear in +the <guilabel>Bookmark Editor</guilabel> is the order they will appear in the +<guimenu>Bookmarks</guimenu> drop down list. The <menuchoice><guimenu>Insert +</guimenu><guimenuitem>Insert Separator</guimenuitem></menuchoice> option can +be used to insert separating lines into the list wherever you wish.</para> + +<para>A new subfolder can be created at the selected point in the list by +using the <guimenuitem>Create New Folder...</guimenuitem> option in the +<guimenu>Insert</guimenu> menu or from the drop down menu you get when you +<mousebutton>right</mousebutton> click on an item in the main part of the +window, or with <keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</para> + +<para>To change the name of a bookmark or folder select it then press +<keycap>F2</keycap> or choose the <guimenuitem>Rename</guimenuitem> item from +the <guimenu>Edit</guimenu> menu or the pop up menu that appears when you +<mousebutton>right</mousebutton> click on the item. Similarly, you can edit +the &URL; by pressing <keycap>F3</keycap> or choosing the <guimenuitem> +Change URL</guimenuitem> menu item.</para> + +<para>The <guilabel>Bookmark Editor</guilabel> lets you import bookmarks from +a range of other browsers into &konqueror;'s bookmark list, putting them into + a new folder or replacing all current bookmarks. To do this select +<guisubmenu>Import</guisubmenu> from the <guimenu>File</guimenu> menu. The +<menuchoice><guimenu>File</guimenu><guisubmenu>Export</guisubmenu> +</menuchoice> option can be used to export &konqueror;'s bookmarks to a +&Netscape; or Mozilla browser.</para> + +<para>If you often use the &Netscape; browser as well as &konqueror;, then +rather than importing your &Netscape; bookmarks into &konqueror; it is +better to select the <guimenuitem>Show Netscape Bookmarks in Konqueror +Windows</guimenuitem> item in the <guimenu>Settings</guimenu> menu. If you +do this any updates to &Netscape;'s bookmarks are automatically seen by +&konqueror;.</para> + +<para>To select which bookmark subfolder is used to hold the Bookmark +Toolbar items select the subfolder then choose <guimenuitem>Set as Toolbar +Folder</guimenuitem> from the <guimenu>Edit</guimenu> menu.</para> + +<para>If you are tidying up your bookmarks and have forgotten what a +particular web page is, you can easily open it from within the <guilabel> +Bookmark Editor</guilabel> by <mousebutton>right</mousebutton> clicking +on the item and selecting <guimenuitem>Open in Konqueror</guimenuitem> from +the pop up menu. If you just want to check that the &URL; is still valid +select <guimenuitem>Check Status</guimenuitem> instead.</para> + +<important><para>Don't forget to save your changes with <menuchoice> +<guimenu>File</guimenu><guimenuitem>Save</guimenuitem></menuchoice> or +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> before you leave +the <guilabel>Bookmark Editor</guilabel>. +</para></important> +</sect1> + + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/browser.docbook b/doc/konqueror/browser.docbook new file mode 100644 index 000000000..9707e29ad --- /dev/null +++ b/doc/konqueror/browser.docbook @@ -0,0 +1,482 @@ +<chapter id="browser"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-05</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + + +<title>&konqueror; the Web Browser</title> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="konqorg.png"/></imageobject> +<textobject> +<phrase>Browsing www.konqueror.org</phrase> +</textobject> +</mediaobject> + +<sect1 id="conn-inet"> +<title>Connecting to the Internet</title> + +<para>Once you are connected to the Internet you can use &konqueror; to browse +the Web just as easily as you can use it to handle your local files. Just type +a &URL; into the <guilabel>Location</guilabel> Toolbar window, press +&Enter;, and you are away!</para> + +<itemizedlist> +<listitem><para>If you use a dial-up modem connection, then you will be using +&kppp; or a similar dialer program to make the connection.</para></listitem> + +<listitem><para>If your machine is connected to a local area network +(<acronym>LAN</acronym>) that gives you a proxy connection to the Internet +then you will have to set &konqueror; up for the proxy connection. This can be +done with the <guilabel>Proxy</guilabel> page of the <menuchoice><guimenu> +Settings</guimenu><guimenuitem>Configure Konqueror...</guimenuitem> +</menuchoice> dialog.</para></listitem> + +<listitem><para>If you are lucky enough to have a high speed cable connection, +then the service provider will probably give you an external cable modem which +needs an ethernet connection to your machine. Unfortunately the details of how +to establish the connection depend on the service provider and to some extent +on which Linux/&UNIX; distribution you are using. Some <acronym>ISP</acronym>s +connect their customers to the Internet through a proxy server, in which case +you will have to set up &konqueror; to use it. You may find it useful to +search the archives of your distribution's user group mailing list for +help.</para> +</listitem> +</itemizedlist> + +<note><para>An error message such as <errorname>Unknown Host</errorname> +usually means that &konqueror; cannot find a connection to the Internet or that +you have entered an incorrect &URL;.</para></note> + +</sect1> + +<sect1 id="surf"> +<title>Surfing and Searching</title> + +<para>Once you have a connection to the Internet, you can surf with +&konqueror; just as you can with any other browser.</para> + +<para>Type a &URL; into the Location Toolbar window, press +&Enter; or <mousebutton>left</mousebutton> click on the +<guibutton>Go</guibutton> button at the right hand end of the Location +Toolbar, and &konqueror; will download and display that page. +If you have visited the page before, &konqueror;'s +<link linkend="path-complete">Automatic Text Completion</link> feature can help +you type the &URL; a second time, or you could look through the +<guilabel>History</guilabel> page in the +<link linkend="sidebar">Navigation Panel</link>. If you want to use one of +the web's search engines, &konqueror;'s <link linkend="enhanced-browsing"> +Web Shortcuts</link> feature can make this easier.</para> + +<para><mousebutton>Left</mousebutton> click on a link in the page to + go there.</para> + +<para>To open a link in a new instance of &konqueror;, leaving the +old page still visible, &MMB; click on the link or <mousebutton> right +</mousebutton> click on it and select the +<guimenuitem>Open in New Window</guimenuitem> option. Alternatively, you might want to <guimenuitem>Open in New Tab</guimenuitem>. <link linkend="tabbrowse">Tabbed Browsing</link> will let +you hold a number of pages in one &konqueror; window and quickly switch +between them with a single mouse click.</para> + +<para>You could also select the multiple view mode with <keycombo +action="simul">&Ctrl;&Shift;<keycap>L</keycap> +</keycombo> +or the Menubar <menuchoice><guimenu>Window</guimenu> <guimenuitem>Split View +Left/Right</guimenuitem></menuchoice> option which will let you see different +pages at the same time. This can be useful if you are looking through a +complicated set of <acronym>HTML</acronym> pages, but make sure the little link +box at the bottom right hand corner is empty when you are doing +this.</para> +<para>To go back to the previous page use the <keycombo +action="simul">&Alt;<keysym>Left Arrow</keysym></keycombo> +shortcut, the <guibutton>Back</guibutton> button on the Toolbar, or the Menubar +<menuchoice><guimenu>Go</guimenu> <guimenuitem>Back</guimenuitem></menuchoice> +option.</para> +<para>Similarly, once you have gone back you can go forward by using +<keycombo action="simul">&Alt;<keysym>Right +Arrow</keysym></keycombo>, the <guibutton>Forward</guibutton> button, or the +Menubar +<menuchoice><guimenu>Go</guimenu> +<guimenuitem>Forward</guimenuitem></menuchoice> option.</para> + +<para>If you want to stop the download for any reason then use the +<keycap>Esc</keycap> key, the Toolbar <guibutton>Stop</guibutton> button or the +Menubar <menuchoice><guimenu>View</guimenu> +<guimenuitem>Stop</guimenuitem></menuchoice> item.</para> + +<para>When you are viewing a web page you should see two new icons in the +Toolbar, looking like magnifying glasses with small <keycap>+</keycap> and +<keycap>-</keycap> symbols. Use these to adjust the size of the text in the +page if you find it difficult to read. How well this works will +depend on how the web page has been constructed.</para> +</sect1> + +<sect1 id="tabbrowse"> +<title>Tabbed Browsing</title> +<para>By using this feature you can make &konqueror; load multiple web pages in +the same window, and switch between them using tabbed pages. This way, you can +preload a page <quote>in the background</quote> while you carry on reading another.</para> + +<para>To use tabbed browsing, <mousebutton>right</mousebutton> click on a +link and choose <guimenuitem>Open in New Tab</guimenuitem> from the drop down +menu. The page will be downloaded and displayed as normal, but with tabs +across the top of the view, one tab for each page. <mousebutton>Left +</mousebutton> click on a tab to view that page, or you can use the shortcuts +<keycombo action="simul">&Ctrl;<keycap>[</keycap></keycombo> and +<keycombo action="simul">&Ctrl;<keycap>]</keycap></keycombo> to cycle through +the tab pages. Alternatively, you can scroll through the tabs using +the mouse <mousebutton>wheel</mousebutton> while the mouse pointer is +over the tab bar (presuming that your mouse has one). Also, +double-clicking over the empty tab bar space will open a new +tab.</para> + +<para>The <guimenuitem>Open in Background Tab</guimenuitem> option in the +&RMB; menu also downloads the page and shows a new tab for it, but the new +page will not be displayed until you <mousebutton>left</mousebutton> click +on the tab.</para> + +<para>If you check the <guilabel>Open links in new tab instead of in new window +</guilabel> box in the <guimenuitem>Web Behavior</guimenuitem> page of the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Konqueror... +</guimenuitem></menuchoice> dialog, &MMB; clicking on a link will open it +in a new tab page and if you hold the &Shift; key down while clicking the +&MMB; the link will be opened in a background tab page.</para> + +<para><mousebutton>Right</mousebutton> clicking on a tab will bring up a +menu with the following options:</para> +<variablelist> + +<varlistentry> +<term><guimenuitem>New Tab</guimenuitem></term> +<listitem><para>This opens a new, blank, tabbed page view. +You can then download a web page into it by typing the &URL; into the +Location Bar or by making a selection from the Bookmark Toolbar or the +<link linkend="sidebar">Navigation Panel</link> history page.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guimenuitem>Duplicate Tab</guimenuitem></term> +<listitem><para>To create a duplicate tabbed page.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guimenuitem>Detach Tab</guimenuitem></term> +<listitem><para>This option removes the selected tabbed +page from the current &konqueror; window and opens it in a new instance of +&konqueror;.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guimenuitem>Close Tab</guimenuitem></term> +<listitem><para>To close the selected tab page.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guimenuitem>Reload</guimenuitem></term> +<listitem><para>Reloads the content of the current tab.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guimenuitem>Reload all Tabs</guimenuitem></term> +<listitem><para>Reloads the content of every tab.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guimenuitem>Switch to Tab</guimenuitem></term> +<listitem><para>Displays a submenu showing all other tabs. Choosing a tab from +this list makes it the active tab.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guimenuitem>Close Other Tabs</guimenuitem></term> +<listitem><para>To close all but the selected tab page.</para> +</listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="enhanced-browsing"> +<title>Web Shortcuts</title> + +<para>If enabled, &konqueror;'s Web Shortcuts +feature lets you submit a query directly to a search engine or similar web site +without having to visit the site first.</para> <para>For example, entering +<userinput>gg:konqueror</userinput> into the Location Bar and pressing &Enter; +will ask <trademark>Google</trademark> to search for items related to +&konqueror;.</para> <para>To see what Web Shortcuts are available, and perhaps +add your own, use <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Konqueror...</guimenuitem></menuchoice> to open the <guilabel>Settings +</guilabel> dialog box and click on the <guiicon>Web Shortcuts</guiicon> +icon.</para> + +<para>Once there, to make a new Web Shortcut select +<guibutton>New...</guibutton> and you will now have a new dialog +requesting the options and specifications of your new Web +Shortcut. The first field is for the human readable name of the search +provider; that is, simply the name of the Search provider. For +example, <trademark>Google</trademark>.</para> + +<para>In the next field you should enter the &URI; that is used to do a +search on the search engine. The whole text to be searched for can be +specified as <userinput>\{@}</userinput> or +<userinput>\{0}</userinput>. The recommended version is +<userinput>\{@}</userinput> since it removes all query variables +(<replaceable>name</replaceable>=<replaceable>value</replaceable>) +from the resulting string whereas <userinput>\{0}</userinput> will be +substituted with the unmodified query string. </para> + +<para>You can use <userinput>\{1}</userinput> +... <userinput>\{n}</userinput> to specify certain words from the +query and +<userinput>\{<varname><replaceable>name</replaceable></varname>}</userinput> +to specify a value given by +<userinput><varname><replaceable>name</replaceable></varname>=<replaceable>value</replaceable></userinput> +in the user query. In addition it is possible to specify multiple +references (names, numbers and strings) at once, like +<userinput>(\{<varname><replaceable>name1</replaceable></varname>,<varname><replaceable>name2</replaceable></varname>,...,"<replaceable>string</replaceable>"})</userinput>. The first +matching value (from the left) will be used as substitution value for +the resulting &URI;. A quoted string can be used as the default value if +nothing matches from the left of the reference list.</para> + +<para>To make a basic Web Shortcut here however, all that is required +is the &URI; that is used to do a search on the search +engine. Following our previous example with +<trademark>Google</trademark>, we would enter +<userinput>http://www.google.com/search?q=\{@}&ie=UTF-8&oe=UTF-8</userinput>. You +can often easily find where to place the <userinput>\{@}</userinput> +by doing a search on the search engine in question, and then analysing +the &URL; address. For example, doing a <trademark>Google</trademark> +search for &konqueror; produces the &URL;: <ulink +url="http://www.google.com/search?q=konqueror&ie=UTF-8&oe=UTF-8">http://www.google.com/search?q=konqueror&ie=UTF-8&oe=UTF-8</ulink>. Now +you need to merely replace &konqueror; with +<userinput>\{@}</userinput> in this example to find the appropriate +&URI; to be entered.</para> + +<para>In the third field you need to enter the &URI; shortcut. For +example, the <userinput>gg</userinput> in +<userinput>gg:konqueror</userinput>. In the next option — the +drop-down menu — you have the option to select the character set that +will be used to encode the search query. Once you have entered all the +options correctly to your satisfaction, press &Enter; and your new Web +Shortcut should now be available in &konqueror;.</para> + +</sect1> + +<sect1 id="accesskeys"> + +<title>Access Keys</title> + +<para>&konqueror; has full support for the +<sgmltag class="attribute">accesskey</sgmltag> &HTML; attribute in +forms and links. Access keys allow you to use +the keyboard keys for functions which would perhaps normally be done +with the mouse, such as following links. The benefit of this is, quite +simply, that users can interact with a page with devices other than a +pointing device.</para> + +<para>To activate the access keys in &konqueror;, press and release +&Ctrl;. Once this is pressed, if a particular link on the website has +the <sgmltag class="attribute">accesskey</sgmltag> attribute in the given link, then the +character(s) should appear over the link, identifying what needs to be +pressed. Then, you can enter the character(s) associated with the link +as an alternative to following the link with the mouse. To disable the +access keys once activated you can press &Ctrl; again.</para> + +<note><para>The proper use of this feature requires that the web +designer of the page has specifically assigned, using the +<sgmltag class="attribute">accesskey</sgmltag> attribute, an access key for the +link. Many web designers might not include the +<sgmltag class="attribute">accesskey</sgmltag> in their links and forms, and +consequently this feature will be unusable on the given +webpage.</para></note> + +</sect1> + +<sect1 id="useragent"> +<title>Browser Identification</title> +<para>When &konqueror; connects to a web site it sends some brief browser +identification information, known as the <quote>User Agent</quote> string. +Many web sites use this information to customize the pages that they send +back, based on the strengths and weaknesses of different browsers.</para> +<para>Unfortunately, some badly designed sites refuse to work properly +unless you are using a browser that the site recognizes as a +<quote>valid</quote> one, even though if given a chance, &konqueror; will +work satisfactorily with the vast majority of web pages.</para> +<para>To overcome this problem you can change the browser identification +information that &konqueror; sends for specific sites or domains by +selecting <menuchoice><guimenu>Settings</guimenu><guimenuitem> +Configure Konqueror...</guimenuitem></menuchoice> to bring up the <guilabel> +Settings</guilabel> dialog box and clicking the <guiicon>Browser Identification</guiicon> +icon.</para> +<note><para>Problems with getting a web page to work properly may also be due +to its use of &Java; or JavaScript. If you suspect that this may be the case +check that they have been enabled in the <guiicon>Java & JavaScript +</guiicon> section of the <guilabel>Settings</guilabel> dialog box.</para></note> + +</sect1> + +<sect1 id="save-print-web"> +<title>Saving and Printing Web Items</title> + +<para>When you are viewing a web page you can save it (or at least the basic +&HTML; or similar source text) to your local disk with +<menuchoice><guimenu>Location</guimenu><guimenuitem>Save +As...</guimenuitem></menuchoice>. If the page +you are viewing uses frames, then you will also be given the +<menuchoice><guimenu>Location</guimenu><guimenuitem>Save Frame +As...</guimenuitem></menuchoice> option. <mousebutton>Left</mousebutton> click + in the frame you want to save first.</para> + +<para>If the page uses a background image, you can get and save that with the +<menuchoice><guimenu>Location</guimenu><guimenuitem>Save Background +Image As...</guimenuitem></menuchoice> option.</para> + +<para>But if what you really want is that glorious picture of the latest +Ferrari, then <mousebutton>right</mousebutton> clicking on the image will +give you a drop-down menu with a +<guimenuitem>Save Image As...</guimenuitem> option. Be sure to respect the +owner's copyright, and ask for permission before using any pictures saved this +way for anything other than your own viewing pleasure.</para> + +<para>If you <mousebutton>right</mousebutton> click on a link (which may be a +picture) and select <guimenuitem>Save Link As...</guimenuitem> from the pop +up menu the basic &HTML; or similar source text will be +downloaded and saved on your local disk.</para> + +<para><mousebutton>Right</mousebutton> clicking on a link (which may be a +picture) and choosing <guimenuitem>Copy Link Location</guimenuitem> will copy +the &URL; of the link to the clipboard so you can then paste it into, say, an +e-mail to a friend telling her about this wonderful new site.</para> + +<para><mousebutton>Right</mousebutton> clicking on a picture and choosing +<guimenuitem>Copy Image Location</guimenuitem> copies the &URL; of the picture +to the clipboard.</para> + +<para>To save a complete web page, including images, select <guimenuitem> +Archive Web Page...</guimenuitem> from the <guimenu>Tools</guimenu> menu. +Note that this feature is provided by a <link linkend="konq-plugin">plugin +</link> and may not have been installed on your system. The web page will be +saved as a single file with a <literal role="extension">.war</literal> +extension and can be opened by <mousebutton>left</mousebutton> clicking +on the filename in &konqueror; running in File Manager mode.</para> + +<para>Printing a copy of the page you are viewing is easily done with the +Menubar <menuchoice><guimenu>Location</guimenu> +<guimenuitem>Print...</guimenuitem></menuchoice> or <guimenuitem>Print +Frame</guimenuitem> option or with the Toolbar <guiicon>Print</guiicon> +button.</para> + +</sect1> + +<sect1 id="ftp"> +<title>&FTP;</title> + +<para>&FTP;, or File Transfer Protocol, is one of the the earliest, and still +perhaps the best, way of transferring files between computers over the +Internet.</para> + +<para>With &FTP; you can see files and folders on the distant computer just +as if they were on your own system, download them onto your computer using +&konqueror;'s normal <guimenuitem>Copy</guimenuitem> and +<guimenuitem>Paste</guimenuitem> or Drag n' Drop methods and, if allowed, +upload files from your machine to the other computer's filesystem. To try it, +type the &URL;</para> + +<screen> +<userinput>ftp://ftp.kde.org/pub/kde</userinput> +</screen> + +<para>into the Location Toolbar and press &Enter;. As long as +you are connected to the Internet, and as long as the &kde;'s &FTP; site is +not too busy, you should end up seeing the <filename +class="directory">/pub/kde</filename> folder at &kde-ftp;</para> + +<note><para>Although, strictly speaking, &FTP; &URL;s should +be entered starting with <userinput>ftp://</userinput> and <acronym>WWW +</acronym> &URL;s starting with <userinput>http://</userinput> +&konqueror; is usually smart enough to figure out what is meant, and insert +these characters for you if you leave them out.</para></note> + +<para>When you access an &FTP; site it will usually need some form of username +and password from you. To simplify things, most &FTP; sites that offer files +for free downloading will accept the word <systemitem class="username"> +anonymous</systemitem> as a username and your email +address as a password, and to make your life even easier &konqueror; will +automatically supply these without troubling you. </para> + +<note><para>If you try to access an &FTP; site that does not need a proper +username or password but which is too busy to accept any more connections, +&konqueror; often interprets the <quote>busy</quote> message as a request for +a name and password and will therefore pop up a dialog box asking you to +supply them.</para></note> + +<para>Sites that are more concerned with security will need a proper username +and password, in which case &konqueror; will ask you for them or you can +include the username in the &URL; you type into the Location Toolbar, as +for example</para> + +<screen> +<userinput>ftp://<replaceable>username</replaceable>@ftp.cia.org</userinput> +</screen> + +<para>&konqueror; will then prompt you for the password.</para> + +<para>&konqueror; can also support automatic logins as specified in a +<filename>.netrc</filename> file. Details of how to enable this feature are +given at <ulink url="http://www.konqueror.org/faq.html#netrc"> +http://www.konqueror.org/faq.html#netrc</ulink></para> + +</sect1> + + +<sect1 id="portnumbers"> +<title>&URL;s with Port Numbers</title> +<para>If you specify a port number in your &URL;, as in for example +<userinput>http://intranet.corp.com:1080</userinput>, you might get the error +message <quote>Access to restricted port in POST denied</quote>. This is done +for security reasons. If you nevertheless need to access a server on this port, +just add a key line +<screen><userinput> +OverridenPorts=CommaSeparatedListOfAllowedPorts +</userinput></screen> +to <filename>$KDEDIR/share/config/kio_httprc +</filename> or +<filename>~/.kde/share/config/kio_httprc</filename>.</para> +<para>For example +<screen><userinput>OverridenPorts=23,15 +</userinput></screen> +(it should not include any embedded spaces).</para> +<para>&konqueror; will reject the following ports (the list is hardcoded in +<filename>kdelibs/kio/kio/job.cpp</filename>):</para> +<para> + 1, 7, 9, 11, 13, 15, 17, 19, + 20, 21, 22, 23, 25, 37, 42, 43, + 53, 77, 79, 87, 95, 101, 102, 103, 104, + 109, 110, 111, 113, 115, 117, 119, 123, + 135, 139, 143, 179, 389, 512, 513, 514, + 515, 526, 530, 531, 532, 540, 556, 587, + 601, 989, 990, 992, 993, 995, 1080, + 2049, 4045, 6000, 6667 +</para> +</sect1> + + +</chapter> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/cmndline.png b/doc/konqueror/cmndline.png Binary files differnew file mode 100644 index 000000000..380fead0f --- /dev/null +++ b/doc/konqueror/cmndline.png diff --git a/doc/konqueror/commands.docbook b/doc/konqueror/commands.docbook new file mode 100644 index 000000000..2b3142ecc --- /dev/null +++ b/doc/konqueror/commands.docbook @@ -0,0 +1,1210 @@ +<chapter id="commands"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-06</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + +<title>Command Reference</title> + +<note><para>The shortcut key combinations shown in this chapter are the +default ones. They can of course be <link linkend="configshort">changed</link>. +</para></note> + +<sect1 id="specshort"> +<title>Special Shortcuts</title> +<para>There are some useful shortcuts that are not shown in any of the menus:</para> +<variablelist> + +<varlistentry> +<term><keycap>F6</keycap></term> +<listitem> +<para>Sets the focus to the text entry box in the Location Toolbar.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycombo action="simul">&Ctrl;<keycap>]</keycap></keycombo></term> +<listitem> +<para>Activate the next tab page.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycombo action="simul">&Ctrl;<keycap>[</keycap></keycombo></term> +<listitem> +<para>Activate the previous tab page.</para> +</listitem> +</varlistentry> + +</variablelist> + + +</sect1> + +<sect1 id="menubar"> +<title>The Menubar</title> <para>Note that some menu entries only appear when +they are applicable to the file you currently have open in &konqueror;. For +example, the +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Find...</guimenuitem> +</menuchoice> +item will not appear when you are viewing the contents of a directory.</para> +<sect2 id="menu-location"> +<title>The <guimenu>Location</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>Location</guimenu> +<guimenuitem>New Window</guimenuitem> +</menuchoice></term> +<listitem><para>Open another &konqueror; +window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>Location</guimenu> <guimenuitem>New Tab</guimenuitem> +</menuchoice></term> +<listitem><para>Open another &konqueror; tab, containing a +blank page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>Location</guimenu> +<guimenuitem>Duplicate Window</guimenuitem> +</menuchoice></term> +<listitem><para>Open another &konqueror; window, duplicating the +current +one.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>Location</guimenu> +<guimenuitem>Open Location...</guimenuitem> +</menuchoice></term> +<listitem><para>Open a folder or file by entering its path + (for example <filename class="directory">/home/pam</filename> or +<filename>/home/pam/fred.txt</filename>) in a simple dialog +box.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Location</guimenu> +<guimenuitem>Send Link</guimenuitem> +</menuchoice></term> +<listitem><para>Send an email containing a link to the current +location.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Location</guimenu> +<guimenuitem>Send File</guimenuitem> +</menuchoice></term> +<listitem><para>Send an email containing the selected file as an +attachment.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice> +<guimenu>Location</guimenu> +<guimenuitem>Save Background Image As...</guimenuitem> +</menuchoice></term> +<listitem> +<para>Only applies if you are viewing a web page with a background image. Opens +the <guilabel>Save As dialog</guilabel> box to let you save the background +image file to your own computer.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>Location</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice></term> +<listitem><para>Only applies if you are viewing a document or web page, uses +the +<guilabel>Save As...</guilabel> dialog box to let you save a copy to your own +computer.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Location</guimenu> +<guimenuitem>Save Frame As...</guimenuitem> +</menuchoice></term> +<listitem><para>Similar to <guimenuitem>Save As...</guimenuitem> but for +use with a web site that uses frames.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> +</shortcut> +<guimenu>Location</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice></term> +<listitem><para>Print.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Location</guimenu> +<guimenuitem>Print Frame</guimenuitem> +</menuchoice></term> +<listitem><para>Print selected frame of a Web +page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Location</guimenu> +<guimenuitem>Open With Netscape/Mozilla</guimenuitem> +</menuchoice></term> +<listitem><para>Open the web page you are +viewing in &konqueror; with &Netscape;/<application>Mozilla</application> as well.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>Location</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para>Close down this instance of +&konqueror;.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-edit"> +<title>The <guimenu>Edit</guimenu> Menu</title> + +<note><para>Most items in the Menubar <guimenu>Edit</guimenu> menu can also be +found by &RMB; clicking on a free area of a view.</para></note> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Z</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Undo</guimenuitem> +</menuchoice></term> +<listitem><para>Sometimes lets you reverse a mistaken +action.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Cut</guimenuitem> +</menuchoice></term> +<listitem><para>Puts selected item(s) into the clipboard. If +you then do a a <guimenuitem>Paste</guimenuitem> the item(s) will be moved +from the original location to the new one.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>C</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem> +</menuchoice></term> +<listitem><para>Copy selected item(s) to the +clipboard.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>V</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem> +</menuchoice></term> +<listitem><para>Paste item(s) from clipboard to the currently viewed +folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>F2</keycap> +</shortcut><guimenu>Edit</guimenu> +<guimenuitem>Rename</guimenuitem> +</menuchoice></term> +<listitem><para>Lets you rename a file or folder without + having to +open the <guimenuitem>Properties...</guimenuitem> dialog box. +</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>Delete</keycap></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Move to Trash</guimenuitem> +</menuchoice></term> +<listitem><para>Move selected item(s) to the Trash +folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Shift;<keycap>Delete</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Delete</guimenuitem> +</menuchoice></term> +<listitem><para>Delete the selected item(s).</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>F7</keycap></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Copy Files</guimenuitem> +</menuchoice></term> +<listitem><para>Copy the selected item(s) to another +folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Move Files</guimenuitem> +</menuchoice></term> +<listitem><para>Move the selected item(s) to another +folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Create New</guimenuitem> +</menuchoice></term> +<listitem><para>Create a link to an application, +<acronym>URL</acronym>, Floppy or &CD-ROM; device, or create a new Folder or +text or &HTML; file. See the <link linkend="making">Create +New...</link>section for more details.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Edit File Type...</guimenuitem> +</menuchoice></term> +<listitem><para>Open the <guilabel>Edit File Type</guilabel> +dialog box</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Properties..</guimenuitem> +</menuchoice></term> +<listitem><para>Open the <guilabel>Edit Properties</guilabel> +dialog box</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guisubmenu>Selection</guisubmenu> +</menuchoice></term> +<listitem><para>Contains a number of options for changing the items selected in +the &konqueror; window: +<!-- DANGER: Nested variablelist! Be careful... --> +<variablelist> +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guisubmenu>Selection</guisubmenu> +<guimenuitem>Select...</guimenuitem> +</menuchoice></term> +<listitem><para>Together with the <guimenuitem>Unselect...</guimenuitem>, +<guimenuitem>Unselect All</guimenuitem> and <guimenuitem>Invert</guimenuitem> +Selection commands, this provides an easy and powerful way of selecting +multiple +files.</para> +<para>It brings up a simple dialog box where you can enter a file +name using the wild card characters * and ?, for example entering +<literal role="extension">*.html</literal> will select all files ending with +<literal role="extension">.html</literal> while <filename>?a*</filename> will +select all files which have the letter a as the second character in their +filename.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>-</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guisubmenu>Selection</guisubmenu> +<guimenuitem>Unselect...</guimenuitem> +</menuchoice></term> +<listitem><para>Unselect files or folders via a dialog similar to the one used +by <guimenuitem>Select...</guimenuitem>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guisubmenu>Selection</guisubmenu> +<guimenuitem>Unselect All</guimenuitem> +</menuchoice></term> +<listitem><para>Unselect all selected files or +folders.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>*</keycap></keycombo> +</shortcut><guimenu>Edit</guimenu> +<guisubmenu>Selection</guisubmenu> +<guimenuitem>Invert Selection</guimenuitem> +</menuchoice></term> +<listitem><para>Invert current selection.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>A</keycap></keycombo> +</shortcut><guimenu>Edit</guimenu> +<guisubmenu>Selection</guisubmenu> +<guimenuitem>Select All</guimenuitem> +</menuchoice></term> +<listitem><para>Selects all text in an &HTML; +page or in a text page being previewed, you can then +<guimenuitem>Copy</guimenuitem> it and <guimenuitem>Paste</guimenuitem> it into +a text editor.</para></listitem> </varlistentry> +</variablelist> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>F</keycap></keycombo> +</shortcut><guimenu>Edit</guimenu> +<guimenuitem>Find...</guimenuitem> +</menuchoice></term> +<listitem><para>Find a text string in a text +page you are previewing or in an &HTML; +page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>F3</keycap></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find Next</guimenuitem> +</menuchoice></term> +<listitem><para>Find the next occurrence of the text string +in the text or &HTML; page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Edit</guimenu> +<guimenuitem>Go to Line...</guimenuitem> +</menuchoice></term> +<listitem><para>Go to a particular line number in a text +page you are previewing.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-view"> + +<title>The <guimenu>View</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>View Mode...</guisubmenu> +</menuchoice></term> +<listitem><para>Selects <guimenuitem>Icon</guimenuitem>, +<guimenuitem>MultiColumn</guimenuitem>, <guimenuitem>Tree</guimenuitem>, +<guimenuitem>Detailed List</guimenuitem> +or <guimenuitem>Text</guimenuitem> view mode.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Use index.html</guimenuitem> +</menuchoice></term> +<listitem><para>If a selected folder contains a file +<filename>index.html</filename>, it will be opened as a web +page rather than showing the folder as a list of +files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Lock to current location</guimenuitem> +</menuchoice></term> +<listitem><para>Lock to current location. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Unlock all views</guimenuitem> +</menuchoice></term> +<listitem><para>Unlock all views. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Link View</guimenuitem> +</menuchoice></term> +<listitem><para>Link current view to others in a multiple view +window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>F5</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Reload</guimenuitem> +</menuchoice></term> +<listitem><para>Reload.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycap>Esc</keycap></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Stop</guimenuitem> +</menuchoice></term> +<listitem><para>Stop load (particularly useful when web +browsing).</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Icon Size</guimenuitem> +</menuchoice></term> +<listitem><para>Select size of icons used when +viewing a folder in Icon Mode.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Sort</guisubmenu> +</menuchoice></term> +<listitem><para>Choose order in which items are presented in the +window when in Icon or MultiColumn View mode.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Case Insensitive Sort</guimenuitem> +</menuchoice></term> +<listitem><para>Choose whether the sort order in Tree, Detailed List +or Text View modes is case sensitive.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>U</keycap> +</keycombo> +</shortcut> +<guimenu>View</guimenu> +<guimenuitem>View Document Source</guimenuitem> +</menuchoice></term> +<listitem><para>View document source text.</para> +<para>Only available if you are viewing a document or &HTML; +page.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>View Frame Source</guimenuitem> +</menuchoice></term> +<listitem><para>View frame source text</para> +<para>Only applies if you are viewing a web site that uses frames. Similar to +<guimenuitem>View Document Source</guimenuitem>. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo action="simul">&Ctrl;<keycap>I</keycap> +</keycombo> +</shortcut> +<guimenu>View</guimenu> +<guimenuitem>View Document Information</guimenuitem> +</menuchoice></term> +<listitem><para>View document information, such as title, &URL;, and &HTTP; +headers used in retrieving the document.</para> +<para>Only available if you are viewing an &HTML; +page.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Security...</guimenuitem> +</menuchoice></term> +<listitem><para>Tells you whether the current browser connection is +secured with <acronym>SSL</acronym> and lets you bring up the +<guilabel>Cryptography Configuration...</guilabel> dialog +box. <mousebutton>Left</mousebutton> clicking on the Menubar padlock icon does +the same thing.</para></listitem> </varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Set Encoding</guimenuitem> +</menuchoice></term> +<listitem><para>Set encoding</para> +<para>Allows you to choose the character encoding used to display +&HTML; pages. <guimenuitem>Auto</guimenuitem> is usually the + best +choice.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Preview</guisubmenu> +</menuchoice></term> +<listitem><para>Lets you choose to show thumbnails of images, text +files +or &HTML; pages instead of the normal icons in Icon or +MultiColumn View modes.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Show Hidden Files</guimenuitem> +</menuchoice></term> +<listitem><para>Show hidden (dot) files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Show details...</guimenuitem> +</menuchoice></term> +<listitem><para>Lets you choose which file and folder details are +shown in Tree, Detailed List and Text views.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Background Color...</guimenuitem> +</menuchoice></term> +<listitem><para>Select background color for the File Manager mode. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Background Image...</guimenuitem> +</menuchoice></term> +<listitem><para>Select background image for the File Manager mode. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-go"> +<title>The <guimenu>Go</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keysym>Up Arrow</keysym></keycombo> +</shortcut><guimenu>Go</guimenu> +<guimenuitem>Up</guimenuitem> +</menuchoice></term> +<listitem><para>Go up a level in the folder +hierarchy.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keysym>Left Arrow</keysym></keycombo> +</shortcut><guimenu>Go</guimenu> +<guimenuitem>Back</guimenuitem> +</menuchoice></term> +<listitem><para>Go back to the previous +view.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keysym>Right Arrow</keysym></keycombo> +</shortcut><guimenu>Go</guimenu> +<guimenuitem>Forward</guimenuitem> +</menuchoice></term> +<listitem><para>You can only go forward if you've just gone +back.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Home</keycap></keycombo> +</shortcut><guimenu>Go</guimenu> +<guimenuitem>Home URL</guimenuitem> +</menuchoice></term> +<listitem><para>Go to your home folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Go</guimenu> +<guimenuitem>Applications</guimenuitem> +</menuchoice></term> +<listitem><para>Open the folder holding your +applications.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Go</guimenu> +<guimenuitem>Trash</guimenuitem> +</menuchoice></term> +<listitem><para>Open your <filename + class="directory">Trash</filename> +folder in a separate window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Go</guimenu> +<guimenuitem>Templates</guimenuitem> +</menuchoice></term> +<listitem><para>Open the <filename +class="directory">Templates</filename> folder in a separate +window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Go</guimenu> +<guimenuitem>Autostart</guimenuitem> +</menuchoice></term> +<listitem><para>Open your <filename +class="directory">Autostart</filename> folder in a separate +window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Go</guimenu> +<guisubmenu>Most Often Visited</guisubmenu> +</menuchoice></term> +<listitem> +<para>Displays a submenu showing the &URL;s you visit most often. Selecting one +of these will make &konqueror; open that &URL;.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-bookmarks"> +<title>The <guimenu>Bookmarks</guimenu> Menu</title> + +<note><para>See the section <link linkend="bookmarks">Using Bookmarks</link> +in this manual for a fuller description of these menu items. +</para></note> +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo> +</shortcut> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Add Bookmark</guimenuitem> +</menuchoice></term> +<listitem><para>Add current selection to your +bookmarks.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Bookmark Tabs as Folder...</guimenuitem> +</menuchoice></term> +<listitem> +<para>Create a bookmark folder containing links to all of the &URL;s currently +open in &konqueror; tabs. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Edit Bookmarks...</guimenuitem> +</menuchoice></term> +<listitem><para>Open the <link linkend="bookmarks">Bookmark Editor</link>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Bookmarks</guimenu> +<guimenuitem>New Bookmark Folder...</guimenuitem> +</menuchoice></term> +<listitem><para>Create a new folder in your Bookmarks +folder.</para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="menu-tools"> +<title>The <guimenu>Tools</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo></shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Run Command...</guimenuitem> +</menuchoice></term> +<listitem><para>Run a program by entering its name in a +simple dialog box.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>T</keycap></keycombo></shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Open Terminal</guimenuitem> +</menuchoice></term> +<listitem><para>Open a &konsole; terminal + window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Find File...</guimenuitem> +</menuchoice></term> +<listitem><para>Open the &kfind; application.</para></listitem> +</varlistentry> +</variablelist> + +<para>If you have &konqueror; plugins installed there will be additional +entries in the <guimenu>Tools</guimenu> menu. See the <link +linkend="konq-plugin">&konqueror; Plugins</link> chapter for further +details.</para> +</sect2> + +<sect2 id="menu-settings"> +<title>The <guimenu>Settings</guimenu> Menu</title> + +<note><para>See also the section <link linkend="save-settings">Saving Settings +and Profiles</link>.</para></note> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo></shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Show Menubar</guimenuitem> +</menuchoice></term> +<listitem><para>Show/Hide the menubar.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Toolbars</guimenuitem> +</menuchoice></term> +<listitem><para>Opens a sub menu where you can choose to show or hide +the various Toolbars.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift; +<keycap>F</keycap></keycombo> +</shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Full Screen Mode</guimenuitem> +</menuchoice></term> +<listitem> +<para>Changes &konqueror; to full screen mode, in which the &konqueror; window +takes up the whole screen, and does not have the usual window decorations. To +exit full screen mode, click on the <guiicon>Exit Full Screen Mode</guiicon> +icon on the toolbar, or press <keycombo action="simul">&Ctrl;&Shift; +<keycap>F</keycap></keycombo>.</para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>View Properties Saved in Folder</guimenuitem> +</menuchoice></term> +<listitem><para>Save View properties to current + folder. If this is selected, a <filename>.directory</filename> file will be +written in the current directory storing the settings you last used to view the +directory. These settings are then loaded when you open the directory in &konqueror;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Remove Folder Properties</guimenuitem> +</menuchoice></term> +<listitem><para>Remove settings stored in folder by <guimenuitem>View +Properties Saved in Folder</guimenuitem>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Load View Profile</guisubmenu> +</menuchoice></term> +<listitem><para>Load the settings associated with a particular view profile.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Save View Profile "<replaceable>ProfileName</replaceable>"...</guimenuitem> +</menuchoice></term> +<listitem><para>Save the current settings to the current view profile.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure View Profiles...</guimenuitem> +</menuchoice></term> +<listitem><para>Lets you change an existing view profile or create a +new one.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> <guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem> +</menuchoice></term> <listitem><para>Lets you +see and change &konqueror;'s shortcut key bindings, i.e. the +associations between actions such as <guimenuitem>Copy</guimenuitem> and keys +or combinations of keys such a <keycombo +action="simul">&Ctrl;<keycap>V</keycap></keycombo>. If you do +this take care not to duplicate an existing shortcut.</para> +</listitem></varlistentry> + +<varlistentry> +<term><menuchoice> <guimenu>Settings</guimenu> +<guimenuitem>Configure Toolbars...</guimenuitem> +</menuchoice></term> <listitem><para> +Lets you configure the Main, Extra and Location Toolbars. See the +section <link linkend="configure-bars">Changing Bars</link>. +</para></listitem> </varlistentry> + +<varlistentry> +<term><menuchoice> <guimenu>Settings</guimenu> +<guimenuitem>Configure &konqueror;...</guimenuitem> </menuchoice></term> +<listitem><para>Lets you configure the File manager, File Associations, +Browser, Internet Keywords, Cookies, Proxies, Cryptography, User Agent, or +Toolbars by bringing up the appropriate dialog box.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> <guimenu>Settings</guimenu> +<guimenuitem>Configure Spell Checking...</guimenuitem> </menuchoice></term> +<listitem> +<para>Displays the spell checking configuration dialog box, in which you can +change settings associated with spell checking in &konqueror;.</para> +</listitem> +</varlistentry> + + +</variablelist> + +</sect2> + +<sect2 id="menu-window"> +<title>The <guimenu>Window</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>L</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Split View Left/Right</guimenuitem> +</menuchoice></term> +<listitem><para>Split View Left/Right.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo +action="simul">&Ctrl;&Shift;<keycap>T</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Split View Top/Bottom</guimenuitem> +</menuchoice></term> +<listitem><para>Split View Top/Bottom.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo +action="simul">&Ctrl;&Shift;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Remove Active View</guimenuitem> +</menuchoice></term> +<listitem><para>Remove Active View.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>N</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>New Tab</guimenuitem> +</menuchoice></term> +<listitem><para>Open a new, empty, tab page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Duplicate Current Tab</guimenuitem> +</menuchoice></term> +<listitem><para>Open a duplicate tab page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>B</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Detach Current Tab</guimenuitem> +</menuchoice></term> +<listitem><para>Show the current tab page in a new instance of +&konqueror;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Close Current Tab</guimenuitem> +</menuchoice></term> +<listitem><para>Close the current tab page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>Left</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Move Tab Left</guimenuitem> +</menuchoice></term> +<listitem><para>Move the current tab one place left in the list of tabs.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>Left</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Move Tab Right</guimenuitem> +</menuchoice></term> +<listitem><para>Move the current tab one place right in the list of tabs.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Window</guimenu> +<guimenuitem>Show Terminal Emulator</guimenuitem> +</menuchoice></term> +<listitem><para>Open a small text terminal view at the bottom of the + main +window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul"><keycap>F9</keycap></keycombo></shortcut> +<guimenu>Window</guimenu> +<guimenuitem>Show Navigation Panel</guimenuitem> +</menuchoice></term> +<listitem><para>Toggles the display of the &konqueror; navigation panel. See +<xref linkend="sidebar"/>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> + +<sect2 id="menu-help"> +<title>The <guimenu>Help</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>&konqueror; Handbook</guimenuitem> +</menuchoice></term> +<listitem><para>View this document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo + action="simul">&Shift;<keycap>F1</keycap></keycombo></shortcut> +<guimenu>Help</guimenu> +<guimenuitem>What's This?</guimenuitem> +</menuchoice></term> +<listitem><para>Draws a question mark (?) beside the mouse +pointer, clicking on a window item such as the +<guiicon>Stop</guiicon> button will then display a brief explanation. See +<link linkend="bubble">Tooltips and What's This?</link> .</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>&konqueror; Introduction</guimenuitem> +</menuchoice></term> +<listitem><para>Revisit the introductory pages that you got when +&konqueror; was first started.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>Report Bug...</guimenuitem> +</menuchoice></term> +<listitem><para>Report bug.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>About &konqueror;...</guimenuitem> +</menuchoice></term> +<listitem><para>Display some brief information about +&konqueror;'s version number, authors and license agreement.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Help</guimenu> +<guimenuitem>About KDE...</guimenuitem> +</menuchoice></term> +<listitem><para>Show some information about the version of &kde; that +you are running.</para></listitem> +</varlistentry> + +</variablelist> + +</sect2> +</sect1> + + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/config.docbook b/doc/konqueror/config.docbook new file mode 100644 index 000000000..18ebfaa4f --- /dev/null +++ b/doc/konqueror/config.docbook @@ -0,0 +1,137 @@ +<chapter id="config"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-06</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + + +<title>Configuring &konqueror;</title> + +<para>In common with the rest of &kde;, &konqueror; is highly configurable, so +you can really get the look and feel that best fits your needs and +wishes.</para> + +<sect1 id="configure-bars"> +<title>Toolbars</title> + +<para>When &kde; is newly installed, &konqueror;'s window contains a Menubar, +Main and Location Toolbars and possibly a Bookmark Toolbar.</para> + +<para>Maybe you don't need all these toolbars. To hide one of them, go into +the <menuchoice><guimenu>Settings</guimenu><guisubmenu>Toolbars</guisubmenu> +</menuchoice> menu and uncheck its box. To show a hidden toolbar, just check +the box.</para> + +<para>The Menubar itself can be toggled on and off with the shortcut key +combination <keycombo action="simul">&Ctrl;<keycap>M</keycap></keycombo>. +</para> + +<!-- FIXME --> +<para>On the left hand end of each bar you can see some vertical +lines. By &LMB; clicking on them, you <quote>flatten</quote> the bar, meaning +that it is hidden but can be quickly restored by clicking on the now +horizontal lines. You can also drag a bar into a new position with these +lines.</para> + +<para>If you <mousebutton>right</mousebutton> click on a Toolbar, you +will get a menu to configure this bar. You can choose the orientation, text +position and icon size</para> + +<para>The icons shown in the various bars can be changed by using the +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +Toolbars...</guimenuitem></menuchoice> option, which brings up the +<guilabel>Configure Toolbars</guilabel> dialog box. The Main and Extra Toolbars +are divided into sections, such as Main Toolbar <&konqueror;>, Main +Toolbar <khtmlpart> and Extra Toolbar <khtmlsettingsplugin>. The +number and type of these sections will depend on whether &konqueror; is in Web +Browser or File Manager mode and whether you have &konqueror; plugins +installed.</para> + +</sect1> + +<sect1 id="configshort"> +<title>Shortcuts</title> +<para>To change the shortcut key arrangements used by &konqueror; select +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Shortcuts... +</guimenuitem></menuchoice>. This will launch a dialog box as shown below. +</para> +<mediaobject> +<imageobject> +<imagedata fileref="shortcut1.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Shortcut config screenshot 1</phrase> +</textobject> +</mediaobject> +<para>Search through the combo box to find the action you want to add or +change the shortcut keys for and select it by <mousebutton>left</mousebutton> +clicking on the name. You will then be able to change the shortcut by +selecting the <guilabel>None</guilabel>, <guilabel>Default</guilabel> or +<guilabel>Custom</guilabel> radio button or by clicking on the large button in +the <guilabel>Shortcut for Selected Action</guilabel> area.</para> + +<para>If you select <guilabel>Define Shortcut</guilabel>, and then +select <guilabel>Advanced</guilabel>, the dialog box below will be shown: +</para> +<mediaobject> +<imageobject> +<imagedata fileref="shortcut2.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Shortcut config screenshot 2</phrase> +</textobject> +</mediaobject> +<para>Choose whether you want to change the <guilabel>Primary</guilabel> or +<guilabel>Alternate</guilabel> shortcut then press the key combination you +want to act as the shortcut, for example <keycombo action="simul"> +&Ctrl;&Shift;<keycap>S</keycap></keycombo>. +If the <guilabel>Auto-Close</guilabel> box is checked the dialog will vanish +as soon as you enter the key combination, otherwise it will remain until you +press <guibutton>OK</guibutton> or <guibutton>Cancel</guibutton>. Clicking on +the little black icon with a white cross in it clears the shortcut.</para> + +<sect2 id="userdefmenus"> +<title>User Defined Menus</title> +<para>You can add your own pop up menu to &konqueror; so that pressing one key +combination will make the menu appear then pressing a second key, or using the +<keysym>Up arrow</keysym> and <keysym>Down arrow</keysym> keys and pressing +<keycap>Enter</keycap>, will select an item from it.</para> +<para>To do this add a <guilabel>Custom</guilabel> shortcut for each of the +actions you want to appear in the menu and in the <guilabel>Define Shortcut +</guilabel> dialog check the <guilabel>Multi-Key</guilabel> box, press the +key combination that you want to bring up your new menu then, separately, +press the key that will choose that item from the menu.</para> +</sect2> +</sect1> + +<sect1 id="othersettings"> +<title>Other Settings</title> +<para>Selecting <menuchoice><guimenu>Settings</guimenu><guimenuitem> +Configure Konqueror...</guimenuitem></menuchoice> brings up a dialog box +which you can use to control most aspects of &konqueror;'s behavior. +It contains several sections which are selected by <mousebutton>left +</mousebutton> clicking on one of the icons at the left of the dialog +box.</para> +<para>Pressing the <guibutton>Help</guibutton> button will give you +detailed instructions about how to use each of these sections, or you can +use the <link linkend="bubble">What's This?</link> feature.</para> +</sect1> + + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/credits.docbook b/doc/konqueror/credits.docbook new file mode 100644 index 000000000..ed63a9b5f --- /dev/null +++ b/doc/konqueror/credits.docbook @@ -0,0 +1,182 @@ +<chapter id="credits"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-06</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + + +<title>Credits and License</title> + +<para>&konqueror;. Program copyright 1999-2003, the &konqueror; + developers:</para> + +<variablelist> + +<varlistentry> +<term>&David.Faure; &David.Faure.mail;</term> +<listitem><para>developer (parts, I/O lib) and maintainer</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Simon.Hausmann; &Simon.Hausmann.mail;</term> +<listitem><para>developer (framework, parts)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Michael.Reiher; &Michael.Reiher.mail;</term> +<listitem><para>developer (framework)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Mattias.Welk; &Mattias.Welk.mail;</term> +<listitem><para>developer</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Alexander.Neundorf; &Alexander.Neundorf.mail;</term> +<listitem><para>developer (list views)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Michael.Brade; &Michael.Brade.mail;</term> +<listitem><para>developer (list views, I/O lib)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Lars.Knoll; &Lars.Knoll.mail;</term> +<listitem><para>developer (<acronym>HTML</acronym> rendering +engine)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Antti.Koivisto; &Antti.Koivisto.mail;</term> +<listitem><para>developer (<acronym>HTML</acronym> rendering +engine)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Dirk.Mueller; &Dirk.Mueller.mail;</term> +<listitem><para>developer (<acronym>HTML</acronym> rendering +engine)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Peter.Kelly; &Peter.Kelly.mail;</term> +<listitem><para>developer (<acronym>HTML</acronym> rendering engine, +JavaScript)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Waldo.Bastian; &Waldo.Bastian.mail;</term> +<listitem><para>developer (<acronym>HTML</acronym> rendering engine, I/O +lib)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Matt.Koss; &Matt.Koss.mail;</term> +<listitem><para>developer (I/O lib)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Alex.Zepeda; &Alex.Zepeda.mail;</term> +<listitem><para>developer (I/O lib)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Stephan.Kulow; &Stephan.Kulow.mail;</term> +<listitem><para>developer (I/O lib)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Richard.J.Moore; &Richard.J.Moore.mail;</term> +<listitem><para>developer (&Java; applet support)</para></listitem> +</varlistentry> + +<varlistentry> +<term>Dima Rogozin <email>[email protected]</email></term> +<listitem><para>developer (&Java; applet support)</para></listitem> +</varlistentry> + +<varlistentry> +<term>Wynn Wilkes <email>[email protected]</email></term> +<listitem><para>developer (&Java;2 manager support and other major improvements +to applet support)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Harri.Porten; &Harri.Porten.mail;</term> +<listitem><para>developer (JavaScript)</para></listitem> +</varlistentry> + +<varlistentry> +<term>Stefan Schimanski <email>[email protected]</email></term> +<listitem><para>developer (&Netscape; plugin support)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Carsten.Pfeiffer; &Carsten.Pfeiffer.mail;</term> +<listitem><para>developer (framework)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&George.Staikos; &George.Staikos.mail;</term> +<listitem><para>developer (SSL support)</para></listitem> +</varlistentry> + +<varlistentry> +<term>Dawit Alemayehu <email>[email protected]</email></term> +<listitem><para>developer (I/O lib, Authentication support)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Torsten.Rahn; &Torsten.Rahn.mail;</term> +<listitem><para>Graphics / icons</para></listitem> +</varlistentry> + +<varlistentry> +<term>Torben Weis <email>[email protected]</email></term> +<listitem><para>kfm author</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Joseph.Wenninger; &Joseph.Wenninger.mail;</term> +<listitem><para>developer (navigation panel framework)</para></listitem> +</varlistentry> + +<varlistentry> +<term>&Stephan.Binner; &Stephan.Binner.mail;</term> +<listitem><para>developer (misc stuff)</para></listitem> +</varlistentry> + +</variablelist> + +<para>Documentation copyright 2000-2003</para> + +<itemizedlist> +<listitem><para>&Erwan.Loisant; &Erwan.Loisant.mail;</para></listitem> +<listitem><para>&Pamela.Roberts; &Pamela.Roberts.mail;</para></listitem> +</itemizedlist> + +<para>Documentation updated for &kde; 3.2 by &Philip.Rodrigues; &Philip.Rodrigues.mail;.</para> +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/dirtree.png b/doc/konqueror/dirtree.png Binary files differnew file mode 100644 index 000000000..fc20b2cc6 --- /dev/null +++ b/doc/konqueror/dirtree.png diff --git a/doc/konqueror/dragdrop.png b/doc/konqueror/dragdrop.png Binary files differnew file mode 100644 index 000000000..8994a5c89 --- /dev/null +++ b/doc/konqueror/dragdrop.png diff --git a/doc/konqueror/faq.docbook b/doc/konqueror/faq.docbook new file mode 100644 index 000000000..5429c71e7 --- /dev/null +++ b/doc/konqueror/faq.docbook @@ -0,0 +1,169 @@ +<chapter id="faq"> +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-06</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + +<title>Questions and Answers</title> + +<qandaset> + +<!-- Link is dead, unfortunately. I suppose this is a more general thing anyway +<qandaentry> +<question><para>How can I browse web sites using non latin + scripts?</para></question> +<answer><para>Detailed instructions can be found at <ulink +url="http://www.konqueror.org/i18n.html">http://www.konqueror.org/i18n.html</ulink></para></answer> +</qandaentry> +--> + +<qandaentry> +<question><para>Can I run &konqueror; from another window +manager?</para></question> + +<answer><para>Just install &Qt;, kdelibs and kdebase, and from your favorite +window manager, launch &konqueror;. It should work just fine, but if it +doesn't (&kde; developers don't test that case often), report it to <ulink +url="http://bugs.kde.org">http://bugs.kde.org</ulink> and try running +<application>kdeinit</application> before running &konqueror;; it usually +helps.</para></answer> +</qandaentry> + +<qandaentry> +<question><para>Where does &konqueror; keep all its configuration +data?</para></question> +<answer><para>Generally in the <filename>~/.kde</filename> folder (this may +be <filename>~/.kde3</filename> on your system, depending on how &kde; 3 +was installed). Don't alter these files unless you really know what you are +doing.</para> + +<itemizedlist> + +<listitem><para>The <filename +class="directory">~/.kde/share/apps/konqueror/profiles</filename> folder +holds individual files containing settings for each of your <link +linkend="save-settings">profiles. </link></para></listitem> + +<listitem><para>Your bookmarks are held in <filename +class="directory">~/.kde/share/apps/konqueror/bookmarks.xml</filename></para></listitem> +<listitem><para>Cookies are held in <filename +class="directory">~/.kde/share/apps/kcookiejar/cookies</filename></para></listitem> +<listitem><para>Your history, as used for the auto-completion feature, is in +<filename>~/.kde/share/config/konq_history</filename></para></listitem> + +<listitem><para>In the folder <filename +class="directory">~/.kde/share/config/</filename> the files +<filename>konqiconviewrc</filename>, <filename>konqlistviewrc</filename> and +<filename>konquerorrc</filename> hold a whole lot of general configuration +settings.</para></listitem> + +<listitem><para>The folder +<filename class="directory">~/.kde/share/cache/http/</filename> +contains the browser cache.</para></listitem> + +<listitem><para>The Navigation Panel uses the files and subfolders in +<filename +class="directory">~/.kde/share/apps/konqsidebartng</filename></para></listitem> +</itemizedlist> + +<para>Any folder specific view settings are put into <literal +role="extension">.directory</literal> files in the individual +folders.</para></answer> +</qandaentry> + +<qandaentry> +<question><para>How do I clear out the history file?</para></question> +<answer><para>There are two <quote>histories</quote>:</para> +<itemizedlist> +<listitem><para>One is used for text completion in the Location Toolbar text entry +box. To clear this <mousebutton>right</mousebutton> click on the text entry +box and select <guimenuitem>Clear History +</guimenuitem>.</para> +</listitem> +<listitem><para>The other is the log of visited locations. Select the History +page in the Navigation Panel, +<mousebutton>right</mousebutton> click on an entry and choose +<guimenuitem>Remove Entry</guimenuitem> to remove just that entry or +<guimenuitem>Clear History</guimenuitem> to delete all +entries.</para></listitem> + +</itemizedlist> + +</answer> +</qandaentry> + +<qandaentry> +<question><para>How do I enable, disable or clear the browser +cache?</para></question> <answer> +<para>If you select <guimenuitem>Cache</guimenuitem> in the dialog launched by +selecting +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Konqueror... +</guimenuitem></menuchoice>, you will be presented with a dialog box that lets +you disable the cache, clear it or set its size, and change the caching +policy.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>How can I change the timeout values used by &konqueror; +when web browsing?</para></question> <answer> +<para>In the Control Center <menuchoice><guimenu>Internet & Network</guimenu> +<guimenuitem>Preferences</guimenuitem></menuchoice> page.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>How do I set my <quote>home</quote> page - the page loaded +on startup?</para></question> +<answer><para>Start &konqueror; with the <guiicon>Web Browser</guiicon> icon +on the panel. Open the page you want to be loaded in any new <quote>Web +Browser</quote> window and select <guimenuitem>Save View Profile "Web +Browsing"</guimenuitem> from the <guimenu>Settings</guimenu> menu.</para> + +<para>All new &konqueror; windows that are started with the <guiicon>Web +Browser</guiicon> icon on the panel, or from the <guimenu>location</guimenu> +menu, and new empty tabs, will now start at this page.</para> + +<note><para>This does not change the behavior of the +<guiicon>Home</guiicon> button on the &konqueror; toolbar, which will +continue to take you to the &URI; defined in the &konqueror; configuration +module. You can reach that module from within &konqueror;, via +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Konqueror</guimenuitem><guilabel>Behavior</guilabel></menuchoice>. By +default this is set to <userinput>~</userinput>, which is your Home folder. +You may set this to any &URI;, either local or remote, and pressing the +<guiicon>Home</guiicon> icon on the toolbar will display it.</para></note> + +<para>To have &konqueror; start up with no page loaded, use +<userinput>about:blank</userinput>.</para> +</answer> +</qandaentry> + +<qandaentry> +<question><para>I can't find the answer to my question here.</para></question> +<answer> +<para>Take a look at <ulink url="http://www.konqueror.org/faq.html"> +http://www.konqueror.org/faq.html</ulink> or +<ulink url="http://www.konqueror.org/konq-java.html"> +http://www.konqueror.org/konq-java.html</ulink>.</para> +</answer> +</qandaentry> + +</qandaset> + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/filemanager.docbook b/doc/konqueror/filemanager.docbook new file mode 100644 index 000000000..c6fb880ba --- /dev/null +++ b/doc/konqueror/filemanager.docbook @@ -0,0 +1,898 @@ +<chapter id="filemanager"> +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2005-04-01</date> +<releaseinfo>3.4</releaseinfo> +</chapterinfo> + +<title>&konqueror; the File Manager</title> + +<sect1 id="dirfolders"> +<title>Folders and Paths</title> +<para>In &UNIX; and &Linux; all folders are arranged in a simple +inverted tree structure descending and branching down from from a single top +level folder. This means that you can get from any folder to +any other by going <quote>up</quote> until you reach a common point then +<quote>down</quote> through the appropriate subfolders until you reach +your +target. </para> + +<para>The position of any file or folder in the tree can be described by its +<quote>path</quote>, which is a simple list of the folders you would have +to descend through to get to the target folder or file. For example +<filename class="directory">/home/pam</filename> is the subfolder <filename +class="directory">pam</filename> of the subfolder <filename +class="directory">home</filename> of the top level folder, and <filename> +/home/pam/words.txt</filename> is the file <filename>words.txt</filename> in +that subfolder. The leading <quote>/</quote> in these paths represents the +top level folder.</para> + +<para>Every folder accessible by your system — including those on +other hard disk partitions, your floppy and &CD-ROM; — will appear +in the tree descending +from /, their exact paths will depend on how your system was set up (see +also +the section on <link linkend="floppy-cd">Floppy and &CD-ROM; Drives</link>). +</para> +<para>Every user on a &UNIX; / &Linux; system has their own <quote>home</quote> +folder to hold their personal files and settings; for example +<filename class="directory">/home/john</filename> and +<filename class="directory">/home/mary</filename>. The +symbol <keycap>~</keycap> is often used to represent the user's home +folder, so that <filename>~/letter.txt</filename> refers to the file +<filename>letter.txt</filename> in my home folder.</para> +<para>Note that the term <quote>directory</quote> is often used instead of +<quote>folder</quote>.</para> +</sect1> + +<sect1 id="viewmode"> +<title>View Modes</title> +<para>In File Manager mode, &konqueror; shows you what files and +subfolders are held in a folder, and can provide you with some +information about them.</para> +<para>The <quote>path</quote> of the folder you are looking at is shown in +the Titlebar, and also in the Location Toolbar, prefixed with <quote>file: +</quote> to indicate that the folder is part of your computer's normal file +system. For example <filename>file:/home/pam</filename>.</para> + +<para>The way that &konqueror; displays the files and folders depends mainly +on your choice of View Mode. This can be selected from the <menuchoice> +<guimenu>View</guimenu><guisubmenu>View Mode</guisubmenu></menuchoice> +sub menu, which gives you the following options: +</para> + +<variablelist> + +<varlistentry> +<term><guimenuitem>Icon View</guimenuitem></term> +<listitem><para>Displays the name and a suitable icon for each file or folder. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>MultiColumn View</guimenuitem></term> +<listitem><para>Similar to <guimenuitem>Icon View</guimenuitem> except that the +display is neatly formatted into regular columns.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Detailed List View</guimenuitem></term> +<listitem><para>Displays each file or folder on a separate line, as a small +icon followed by the file or folder name followed by information about the +item. The amount of information shown is controlled by the <menuchoice> +<guimenu>View</guimenu><guisubmenu>Show Details</guisubmenu></menuchoice> +sub menu settings. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Text View</guimenuitem></term> +<listitem><para>Similar to <guimenuitem>Detailed List View</guimenuitem> +except that icons are not shown and the first character in each line will be +<quote>/</quote> if the item is a folder. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Tree View</guimenuitem></term> +<listitem><para>This option is useful for <link linkend="navigation"> +navigating</link> through the folder tree below the current folder. +The display is similar to <guimenuitem>Detailed List View</guimenuitem> +except that the start of each line will show a small <keycap>+</keycap> sign +in a box if the item is a folder. +<mousebutton>Left</mousebutton> clicking on the box will expand the display to +show the contents of that folder.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Info List View</guimenuitem></term> +<listitem><para>Similar to <guimenuitem>Detailed List View</guimenuitem> +except that, where applicable, it shows the number of lines, words and +characters and file format for each file. +</para></listitem> +</varlistentry> +</variablelist> + +<para>The default file icons shown in <guimenuitem>Icon View</guimenuitem> and +<guimenuitem>MultiColumn View</guimenuitem> modes can be replaced by small +preview images of the file contents, see the section <link linkend="previews"> +File Previews</link> of this handbook for more details.</para> + +<sect2 id="filetipinfo"> +<title>File Tip Info</title> +<para>Checking the <guilabel>Show file tips</guilabel> box in the <guilabel> +Behavior</guilabel> page of the &konqueror; Configuration dialog causes a +small pop up information +window to appear when the mouse pointer is hovered over a file or folder name +or icon in <guimenuitem>Icon View</guimenuitem> or <guimenuitem> +MultiColumn View</guimenuitem> mode. +</para> +<para>If the <guilabel>Show previews in file tips</guilabel> checkbox is +checked the pop up window will also show a small image of the file contents. +</para> +</sect2> + +<sect2 id="previews"> +<title>File Previews</title> +<para>Selecting <menuchoice><guimenu>View</guimenu><guisubmenu>Preview +</guisubmenu></menuchoice> from the Menubar will bring up a sub menu +that lets you enable file previews for certain types of file.</para> +<para>Generally this means that the file's icon will be replaced by a small +image showing the file contents.</para> +<para>If file preview is enabled for <guimenuitem>Sound Files</guimenuitem> +the file will be played whenever the mouse cursor is hovering over the file +name or icon.</para> +<para>Note that file previews are only available in <guimenuitem>Icon View +</guimenuitem> and <guimenuitem>MultiColumn View</guimenuitem> modes.</para> +<para>Because &konqueror; has to read much more data than just the file name +details to generate a preview, file previews may not be appropriate +when viewing files on a floppy or from a remote system. The <guilabel>Previews +</guilabel> page of the File Manager Configuration +dialog allows you to disable file previews for protocols such as +<link linkend="ftp">ftp</link> where reading the extra data would take too +long.</para> +</sect2> + +</sect1> + +<sect1 id="navigation"> +<title>Navigation</title> +<para>To get to a file with &konqueror; you first need to navigate +through the folder tree to find the folder containing that +file.</para> + +<para>To move between folders you can simply step up and down the +tree:</para> + +<itemizedlist> +<listitem><para>To descend into a subfolder <mousebutton>left +</mousebutton> click on its name or +icon -- or if you have already <quote>selected</quote> it (see below) -- then just press +<keycap>Enter</keycap>.</para></listitem> +<listitem><para>To go up the folder tree you can click on the <guiicon>Up +</guiicon> button in the Toolbar, use<keycombo action="simul">&Alt;<keysym>Up Arrow</keysym></keycombo>, or use the Menubar +<menuchoice><guimenu>Go</guimenu><guimenuitem>Up</guimenuitem></menuchoice> +option.</para></listitem> +</itemizedlist> + +<para>To <quote>select</quote> a file or folder in the displayed folder +without opening it in any way use the <keysym>up</keysym> and <keysym>down +</keysym> arrow keys to move through the items. +The selected item will be highlighted and some information about it +will be displayed in the Status Bar.</para> + +<para>Setting the <link linkend="viewmode">View Mode</link> to <guimenuitem> +Tree View</guimenuitem> can help you locate folders in the tree below the +current folder; in this mode each folder is shown with a small box at +the left. If the box contains a <keycap>+</keycap> sign, <mousebutton>left +</mousebutton> clicking on the box (not on the folder name or icon) will +display a sub tree showing files and subfolders contained in that folder. +The small box will then change to show a <keycap>-</keycap> sign. +<mousebutton>Left</mousebutton> click on that to collapse the sub tree. Once +you have found the folder you are looking for, <mousebutton>left +</mousebutton> click on the folder name or icon to open it.</para> + +<para>The <link linkend="sidebar">Navigation Panel</link> can also help you +find your way around the file system.</para> + +<para>You can go directly to any folder by typing its path into the +Location Toolbar window or into the dialog box invoked by the Menubar +<menuchoice><guimenu>Location</guimenu><guimenuitem>Open Location</guimenuitem> +</menuchoice> item or by <keycombo action="simul">&Ctrl;<keycap> +O</keycap></keycombo>. &konqueror;'s <link linkend="path-complete"> +Text Completion</link> feature may be useful when you do this. Don't forget +that in &Linux; / &UNIX; file and folder names are case sensitive.</para> + +<para>When you have moved to a new folder you can go back to your +previous choice by using the Toolbar <guiicon>Back</guiicon> button, the +Menubar +<menuchoice><guimenu>Go</guimenu> <guimenuitem>Back</guimenuitem></menuchoice> +item, or <keycombo action="simul">&Alt;<keysym>Left +Arrow</keysym></keycombo>. Once you have gone back you can go forward. Use the Toolbar +<guiicon>Forward</guiicon> button, the Menubar +<menuchoice><guimenu>Go</guimenu> +<guimenuitem>Forward</guimenuitem></menuchoice> item or <keycombo +action="simul">&Alt;<keysym>Right +Arrow</keysym></keycombo>.</para> + +<para>Alternatively, you can also choose to enter the parent folder by clicking on the Toolbar <guiicon>Up</guiicon>, the <menuchoice><guimenu>Go</guimenu> <guimenuitem>Up</guimenuitem></menuchoice> item, or with <keycombo +action="simul">&Alt;<keysym>Up +Arrow</keysym></keycombo>.</para> + +<tip><para>Holding the &LMB; pressed while the mouse pointer is +over the Toolbar <guiicon>Up</guiicon>, <guiicon>Back</guiicon> or +<guiicon>Forward</guiicon> buttons brings up a menu of recently visited +locations.</para></tip> + +<sect2 id="file-find"> +<title>Finding Files and Folders</title> + +<para>If you don't know or can't remember where a file or folder is within +your system, then use the Toolbar <guiicon>Find File</guiicon> button or the +Menubar <menuchoice><guimenu>Tools</guimenu><guimenuitem>Find +File...</guimenuitem></menuchoice> option. This will embed the file finder +application &kfind; into &konqueror;'s window. See the &kfind; Handbook +for help in using &kfind;. +</para> + +<note><para>If the name of a file or folder begins with a period (dot), then +it is a <quote>hidden</quote> file or folder, and will not normally be shown +by &konqueror;. To see hidden files or folders use the Menubar <menuchoice> +<guimenu>View</guimenu><guimenuitem>Show Hidden Files</guimenuitem> +</menuchoice> option.</para> +<para>Another reason &konqueror; may not show the file or folder you are +looking for is that you may have the <link linkend="konq-plugin"><guisubmenu> +View Filter</guisubmenu></link> plugin set to display only certain types of +file.</para></note> + +</sect2> + +<sect2 id="floppy-cd"> +<title>Floppy and &CD-ROM; Drives</title> + +<para>Any floppy disk, &CD; drive or other hard disk partition that you have +on your system will usually appear in the <filename class="directory">/ +</filename>, <filename class="directory">/media</filename>, <filename class="directory">/mnt</filename> or +<filename class="directory">/auto</filename> folder, having a path something +like <filename class="directory">/mnt/floppy</filename> or +<filename class="directory">/cdrom</filename>. The details will depend on +how your system was set up.</para> + +<para>&UNIX; / &Linux; requires that you <command>mount</command> a floppy disk +or &CD-ROM; when you have inserted it into the drive, and <command>mount +</command> other hard disk partitions when you want to access them. You also +need to unmount a floppy disk or &CD-ROM; before removing it to register that +it is no longer available. </para> + +<para>How you do this will depend on how your system:</para> + +<itemizedlist> +<listitem><para>You may have an <application>Automount</application> facility, +in which case you don't have to bother about explicitly mounting and +unmounting, +although you may find that the &CD-ROM; occasionally starts up by itself for no +apparent reason.</para></listitem> + +<listitem><para>You may have <guiicon>Floppy</guiicon>, &CD-ROM; and hard disk +icons on your desktop, in which case &LMB; click on the icon to mount it. +Doing this should also bring up a &konqueror; window showing the contents of +the floppy, &CD-ROM; or partition. To unmount, <mousebutton>right</mousebutton> +click on the icon and choose the <guimenuitem>Unmount</guimenuitem> item. +Visit the section <link linkend="making">Create New...</link> in this Handbook +to see how to create such an icon.</para></listitem> + +<listitem><para>Or you can do it the traditional way by typing into a text +console window:</para> + +<para><userinput><command>mount /mnt/floppy</command></userinput></para> + +<!-- This markup doesn't work properly, it puts 'mount' and '/mnt/floppy' +on separate lines +<screen> +<userinput><command>mount</command> + <option><replaceable>/mnt/floppy</replaceable></option></userinput> +</screen> --> + +<para>to mount, for example, the floppy drive, and</para> + +<!-- Same as above +<screen> +<userinput><command>umount</command> + <option><replaceable>/mnt/floppy</replaceable></option></userinput></screen> +--> + +<para><userinput><command>umount /mnt/floppy</command></userinput></para> + +<para>to unmount it (<command>umount</command> not <command>unmount</command>). +</para> + +<note><para>Rather than having to open a text console to type the +<command>mount +</command> or <command>umount</command> commands, you may prefer to use +&konqueror;'s <menuchoice><guimenu> Tools</guimenu><guimenuitem>Execute Shell +Command</guimenuitem></menuchoice> +(<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo>) + feature. +</para></note> + +</listitem> + +</itemizedlist> +</sect2> + +</sect1> + +<sect1 id="deleting"> +<title>Deleting Files and Folders</title> + +<para>&konqueror; gives you two ways to dispose of an unwanted file or +folder:</para> + +<itemizedlist> +<listitem><para>You can move it to the <filename>Trash</filename> folder, which +is the safest method as you can get it back if you realize that you have made a +mistake.</para></listitem> + +<listitem><para>You can just plain Delete it, which +removes the entry from the folder and adds the disk area occupied by the +file(s) to the system's list of free disk areas, in the same way as the +<command>rm</command> command.</para></listitem> +</itemizedlist> + +<para>The simplest way to remove a file or folder is to position +the mouse pointer over its name or icon and press the &RMB;, which +will bring up a menu containing the options <guimenuitem>Move to +Trash</guimenuitem> and <guimenuitem>Delete</guimenuitem>.</para> + +<para>Or, if you have <quote>selected</quote> the item, the Menubar +<guimenu>Edit</guimenu> menu will give you the choice of +<quote><guimenuitem>Move to Trash</guimenuitem></quote> and +<quote><guimenuitem>Delete</guimenuitem></quote> options.</para> + +<para><keycap>Del</keycap> will move the selected item or items to Trash.</para> + +<para><keycombo action="simul">&Shift;<keycap>Del</keycap></keycombo> +will really, truly and irrevocably delete the selected item or +items.</para> + +<note><para>You won't be able to remove a file or folder if you don't have +the necessary permissions; see the section on <link linkend="super-user">Super +User Mode</link> for further details.</para></note> + +</sect1> + +<sect1 id="moving"> +<title>Moving and Copying</title> + +<para>To copy a file or subfolder between folders you can:</para> + +<itemizedlist> +<listitem><para>Position the mouse pointer over its name or icon and hold down +the &RMB;, which will bring up a menu containing the +<guimenuitem>Copy</guimenuitem> option. Choose that.</para> + +<para>Or if the item is <quote>selected</quote> you can use the +<guiicon>Copy</guiicon> button on the Toolbar or the Menubar +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem></menuchoice> +item, or the <keycombo +action="simul">&Ctrl;<keycap>C</keycap></keycombo> +shortcut key combination. You can also select <link linkend="multiple">multiple</link> files or folders to copy/move as well.</para></listitem> + +<listitem><para>Navigate to the folder you want to copy the item into then +Paste the item into the new folder by using the Toolbar +<guiicon>Paste</guiicon> button or the Menubar +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Paste</guimenuitem></menuchoice> option or the <keycombo +action="simul">&Ctrl;<keycap>V</keycap></keycombo> shortcut, or by +moving the mouse pointer to a clear area of the window and holding the &RMB; +down to bring up a menu containing the <guimenuitem>Paste</guimenuitem> option. +</para></listitem> +</itemizedlist> + +<para>Moving a file or subfolder between folders can be done in the +same +way as copying, except that you choose the <guimenuitem>Cut</guimenuitem> +option +or <keycombo action="simul">&Ctrl;<keycap>X</keycap></keycombo> +instead of <guimenuitem>Copy</guimenuitem>. The item that you have +<guimenuitem>Cut</guimenuitem> will be removed from the original folder when +you do the <guimenuitem>Paste</guimenuitem> into the new folder.</para> + +<para>You can also copy or move selected item(s) to another folder by using +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Copy Files</guimenuitem></menuchoice> (<keycap>F7</keycap>) or +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Move Files</guimenuitem> +</menuchoice> (<keycap>F8</keycap>), or by selecting +<guimenuitem>Copy To</guimenuitem> or <guimenuitem>Move To</guimenuitem> from +the drop down menu you get when you <mousebutton>right</mousebutton> click on +an file or folder name in the File Manager window.</para> + +<note><para>You may not be able to copy or move a file or folder if +you don't have the necessary permissions. See the section on <link +linkend="super-user">Super User Mode</link> for further +details.</para></note> + +<sect2 id="dnd"> +<title>Using Drag 'n Drop</title> + +<para>&konqueror; also supports Drag and Drop copying and moving of files and +folders.</para> + +<para>You can do this by having two instances of &konqueror;, one showing the +folder you want to copy from, the other showing the target folder. +Position the mouse pointer over the item you wish to copy or move, then, +holding the &LMB; pressed, <quote>drag</quote> it to a clear space in the +target + +folder. Release the button and you will be +presented with a menu choice of <guimenuitem>Copy</guimenuitem> or +<guimenuitem>Move</guimenuitem>. Take care to <quote>drop</quote> the item into + an empty area of the target +folder view - dropping it on top of another file name or icon can cause +problems.</para> + +<para>You can also set up &konqueror; to show more than one folder within +its window and drag & drop between them.</para> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="dragdrop.png"/></imageobject> +<textobject> +<phrase>Split Views for Drag & Drop</phrase> +</textobject> +</mediaobject> + +<para>This screenshot illustrates the use of the Menubar +<menuchoice><guimenu>Window</guimenu> <guimenuitem>Split View +Left/Right</guimenuitem></menuchoice> option, also available with the shortcut +<keycombo +action="simul">&Ctrl;&Shift;<keycap>L</keycap> +</keycombo>, +to split the main &konqueror; window into two views, each showing the contents +of a different folder.</para> + +<para>To be able to show different folders in each view they should not be +linked; the little boxes at the bottom right of each view should be empty. +</para> + +<para>The <quote>active</quote> view, that is the one whose path is shown in +the Location Toolbar and which responds to navigation and Menubar commands, is +shown by the little green light in the bottom left corner. To make a view +active, <mousebutton>left</mousebutton> click on an empty area of the view or +on its Status Bar.</para> + +<para>To remove an active view from &konqueror;'s window use the <keycombo +action="simul">&Ctrl;&Shift;<keycap>R</keycap> +</keycombo> shortcut, or the Menubar <menuchoice><guimenu>Window</guimenu> +<guimenuitem>Remove +Active View</guimenuitem></menuchoice> option, or &RMB; click on the Status Bar +and choose the <guimenuitem>Remove Active View</guimenuitem> option from the +resulting menu.</para> + +<para>If you use &konqueror; tabs, you can drag and drop between tabs +by dragging the file to the tab label, without letting go yet. The +destination tab will pop to the front, allowing you to continue +dragging and then drop the file.</para> + +</sect2> + +<sect2 id="dups"> +<title>Duplicate File Names</title> +<para>If you try to paste a file into a folder that already +contains a file with the same name, &konqueror; will pop up a dialog box warning +you that the file already exists. You can then choose to: +</para> +<itemizedlist> +<listitem><para> +<guilabel>Overwrite</guilabel> the old file with the newly copied one. +The <guibutton>Overwrite All</guibutton> button can be used if you have copied +multiple items.</para></listitem> +<listitem><para>Cancel the paste operation by pressing the <guibutton>Skip +</guibutton> or <guibutton>Skip All</guibutton> button.</para></listitem> +<listitem><para>Give the file that is being copied a different name. You can +do this by typing a new name into the text entry box or get &konqueror; to +<guibutton>Propose</guibutton> one. When you have done this press the +<guibutton>Rename</guibutton> button.</para></listitem> +</itemizedlist> +</sect2> +</sect1> + +<sect1 id="multiple"> +<title>Selecting Multiple Files</title> + +<para>You sometimes want to delete, copy or move a number of files that are +similar in some way. For example you may wish to move all of the .png graphics +files from one folder to another. &konqueror; makes this easy by letting you +select multiple files based on similarities in their file names.</para> + +<para>Use the Menubar +<menuchoice><guimenu>Edit</guimenu><guisubmenu>Selection</guisubmenu> +<guimenuitem>Select...</guimenuitem></menuchoice> item or the shortcut +<keycombo action="simul">&Ctrl;<keycap>+</keycap></keycombo>. This +brings up a little dialog box in which you enter a filename containing +the wildcard characters <keycap>*</keycap>, which matches any number +of characters, and <keycap>?</keycap> which matches a single +character. Press <guibutton>OK</guibutton> and &konqueror; will +highlight all files with matching names. For example;</para> + +<itemizedlist> +<listitem><para> <userinput><filename>flag*.png</filename></userinput> will +select all filenames starting with the letters <quote>flag</quote> and ending +with <quote><literal role="extension">.png</literal></quote>.</para></listitem> +<listitem><para><userinput><filename>memo?.txt</filename></userinput> will +select <filename>memo1.txt</filename> and <filename>memo9.txt</filename> but +not <filename>memo99.txt</filename>.</para></listitem> +</itemizedlist> + +<para>When you have selected a range of files, you can narrow down the +selection +by uing the Menubar <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Unselect...</guimenuitem></menuchoice> option or <keycombo +action="simul">&Ctrl;<keycap>-</keycap></keycombo> to specify +which of the selected files should be removed from the selection.</para> + +<para>Use <keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +or the Menubar <menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Unselect All</guimenuitem></menuchoice> option or just +&LMB; click on a clear area of the view to cancel the +selection.</para> + +<para>You can even invert the selection: that is, deselect all selected +files and select those that were previously unselected. Use the +Menubar <menuchoice><guimenu>Edit</guimenu><guimenuitem>Invert +Selection</guimenuitem></menuchoice> option or <keycombo +action="simul">&Ctrl;<keycap>*</keycap></keycombo> to do this.</para> + +<para>You can also select multiple files and folders by holding the <keycap>&Ctrl;</keycap> button while you click on each individual file or folder. This enables you to then move or copy multiple files and folders to a different location at one time by using the same method above.</para> + +<para>A number of useful shortcut keys can be used in list, tree and text +view modes:</para> +<variablelist> + +<varlistentry> +<term><keycap>Space</keycap></term> +<listitem> +<para>Toggle the current selection. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycap>Insert</keycap></term> +<listitem> +<para>Toggle the current selection and move down to the next item. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycombo action="simul">&Ctrl;<keysym>Up Arrow</keysym></keycombo>, +<keycombo action="simul">&Ctrl;<keysym>Down Arrow</keysym></keycombo>, +<keycombo action="simul">&Ctrl;<keycap>Home</keycap></keycombo>, +<keycombo action="simul">&Ctrl;<keycap>End</keycap></keycombo>, +<keycombo action="simul">&Ctrl;<keycap>Page Up</keycap></keycombo>, +<keycombo action="simul">&Ctrl;<keycap>Page Down</keycap></keycombo> +</term> +<listitem> +<para>Move the selection, toggling the selection of everything on the way. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><keycombo action="simul">&Shift;<keysym>Up Arrow</keysym></keycombo>, +<keycombo action="simul">&Shift;<keysym>Down Arrow</keysym></keycombo>, +<keycombo action="simul">&Shift;<keycap>Home</keycap></keycombo>, +<keycombo action="simul">&Shift;<keycap>End</keycap></keycombo>, +<keycombo action="simul">&Shift;<keycap>Page Up</keycap></keycombo>, +<keycombo action="simul">&Shift;<keycap>Page Down</keycap></keycombo> +</term> +<listitem> +<para>Deselect everything, then move the selection, selecting everything on +the way. +</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Once you have selected the right files then the normal delete, copy or +move commands will act on all of the selected files at once. </para> + +<note><para>Depending on your keyboard type and locale, you may find +that the <keycombo +action="simul">&Ctrl;<keycap>+</keycap></keycombo>, <keycombo +action="simul">&Ctrl;<keycap>-</keycap></keycombo> and <keycombo +action="simul">&Ctrl;<keycap>*</keycap></keycombo> shortcuts +only work with the Numeric keypad <keycap>+</keycap>, <keycap>-</keycap> and +<keycap>*</keycap> keys.</para></note> + +</sect1> + +<sect1 id="making"> +<title>Create New</title> + +<para>When &konqueror; is in File Manager mode, picking +<guisubmenu>Create New</guisubmenu> from the <guimenu>Edit</guimenu> +menu or from the context menu you get by &RMB; clicking on a free +area in a folder view gives you a submenu letting you create any +of the following in the current folder:</para> + +<variablelist> + +<varlistentry> +<term><menuchoice><guisubmenu>File</guisubmenu><guimenuitem>Link To Application...</guimenuitem> + </menuchoice></term> +<listitem><para>This option is most useful if you want to create an icon that +will open a particular application. It opens a dialog box with three tabbed +pages. The first, <guilabel>General</guilabel>, is where you choose an icon and +the text that will appear with it. The second page, +<guilabel>Permissions</guilabel>, lets you select who can use or modify the +icon. In the <guilabel>Application</guilabel> page you must enter the <guilabel>Command</guilabel> that +will run the application, for example, <userinput>kedit</userinput> to start up +the &kedit; text editor. <userinput>kedit /home/pam/todo.txt</userinput> would +open the file <filename>/home/pam/todo.txt</filename> in &kedit;. Advanced +options such as the file types which the application can open are also +available from this page.</para> + +<para>To make the application icon appear on your desktop, create the link in +your <filename class="directory">~/Desktop</filename> folder (this may be +called something slightly different depending on how &kde; was installed on +your system) or get to the +<guisubmenu>Create New...</guisubmenu> sub menu by +<mousebutton>right</mousebutton> clicking on a free area of the desktop +instead of within &konqueror;'s window.</para> + +<para>If you have a lot of specialized application links and don't want to +clutter up the desktop, then why not create them in your Applications +folder. You can get there in &konqueror; by choosing +<menuchoice><guimenu>Go</guimenu> +<guimenuitem>Applications</guimenuitem></menuchoice>. Then create a single icon +on your desktop to open your Applications folder, which is usually in +<filename class="directory">~/.kde/share/applnk</filename>.</para> + +<para>To put an application link icon into the panel, first create it in the +Applications folder then drag the icon onto a clear area of the +panel.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guisubmenu>File</guisubmenu><guimenuitem>Link To Location (URL)...</guimenuitem></menuchoice></term> +<listitem><para>This lets you create an icon to open &konqueror; at a +particular +folder or web page. As with <guimenuitem>Link To +Application...</guimenuitem> +you can make the application icon appear on your desktop by creating the link +in +your <filename>~/Desktop</filename> folder or going to the +<guisubmenu>Create +New...</guisubmenu> sub menu by right clicking on a free area of the +desktop. When you first create it the text shown with the icon will be the full +path or &URL;. You can change it by right clicking on the icon, selecting +<guimenuitem>Properties...</guimenuitem> and entering the preferred text in +the +<guilabel>General</guilabel> tab page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guisubmenu>Device</guisubmenu><guimenuitem>Floppy Device...</guimenuitem></menuchoice></term> +<listitem><para>Use this option to create an icon that will mount a floppy disk +and open an instance of &konqueror; showing the disk's contents. To unmount the +disk when you have finished with it <mousebutton>right</mousebutton> click on +the icon and select <guimenuitem>Unmount</guimenuitem>. In practice it doesn't +have to be a floppy disk but can be any hard disk or partition on your system +that is not normally mounted. However, in most cases you will want to create the icon +on +your desktop.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Hard Disk...</guimenuitem></term> +<listitem><para>This option is similar to <guimenuitem>Floppy +Device...</guimenuitem> but for a hard disk drive or + partition.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>CD/DVD-ROM Device...</guimenuitem></term> +<listitem><para>This option is similar to <guimenuitem>Floppy +Device...</guimenuitem> but for a <acronym>CD</acronym> or <acronym>DVD</acronym> +drive.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Folder...</guimenuitem></term> +<listitem><para>An easy way of creating a new (sub)folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Text File...</guimenuitem></term> +<listitem><para>Use this to create an ordinary, empty, text file. A +dialog box will be opened for you to enter the name of your new +file.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>HTML File...</guimenuitem></term> +<listitem><para>Creates a skeleton <acronym>HTML</acronym> source file. When +you +type the new file's name into the dialog box it is probably best to give +it a <literal role="extension">.html </literal> extension to avoid +confusion.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Presentation Document...</guimenuitem></term> +<listitem><para>Creates a skeleton &koffice; +&kpresenter; document. Give its name a <literal role="extension">.kpr</literal> +extension.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Text Document...</guimenuitem></term> +<listitem><para>Creates a skeleton <application>KOffice</application> &kword; +document using the standard &kword; style template. Give its name a <literal +role="extension">.kwd</literal> extension.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Spread Sheet Document...</guimenuitem></term> +<listitem><para>Use this to create a new <application>KOffice</application> +&kspread; spreadsheet file, and name it with a <literal +role="extension">.ksp</literal> extension.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Illustration Document...</guimenuitem></term> +<listitem><para>Creates a new <application>KOffice</application> &kontour; +document. Name it with the extension <literal +role="extension">.kil</literal>.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="newname"> +<title>Changing Names and Permissions</title> + +<para>The two easiest ways to change the name of a file or folder is to either +<mousebutton>right</mousebutton> click on it and select +<guimenuitem>Rename</guimenuitem>, or select the file or folder and then press the <keycap>F2</keycap> button.</para> + +<para>To change the name or permissions of a file or folder +<mousebutton>right</mousebutton> click on its name or icon and select the +<guimenuitem>Properties...</guimenuitem> item, or if you have +<quote>selected</quote> the file or folder, then you can use the Menubar +<menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Properties</guimenuitem></menuchoice> option.</para> + +<para>This will bring up the Properties dialog box with two tabbed +pages:</para> + +<itemizedlist> +<listitem><para><guilabel>General</guilabel>, which gives you some +information about the item and lets you change its name and, for a folder, +the associated icon.</para></listitem> +<listitem><para><guilabel>Permissions</guilabel>, which shows you the item's +ownership and access permissions and lets you change the permissions. +</para></listitem> +</itemizedlist> + +<sect2 id="copyrename"> +<title>Copy and Rename</title> +<para>If you want to make a copy of an existing file with a different name -- +perhaps as a backup -- in the same folder as the original file, do a normal +<guimenuitem>Copy</guimenuitem> then when you <guimenuitem>Paste</guimenuitem> +it a dialog box will pop up complaining that the file already exists. +Just type the new name into the dialog's text box and press the +<guibutton>Rename</guibutton> button (or if you are feeling lazy pressing the +<guibutton>Propose</guibutton> button will generate a new name for you).</para> +</sect2> + +<sect2 id="super-user"> +<title>Super User Mode</title> + +<para>If you are running as a normal user and try to access files outside of +your own home folder you will often be prevented from doing so and get an +error message such as <errorname>Access Denied</errorname>. </para> + +<para>To access these files you need to be logged in as the system +administrator, often known as the Super User or <systemitem class="username">root</systemitem>. </para> + +<para>Rather than logging out then in again, you can launch &konqueror; from +the +<guimenu>K</guimenu> Menu in Super User mode by selecting +<menuchoice><guisubmenu>System</guisubmenu><guimenuitem>File Manager - Super + User Mode +</guimenuitem></menuchoice>. You will be asked for the <systemitem class="username">root</systemitem> +login password but as long as you can provide that &konqueror; will be started +up with full access privileges to all files on your system.</para> + +<warning><para>Take care. As Super User (<systemitem class="username">root</systemitem>), you have complete control of +your system, and a wrong command can easily do irrevocable damage.</para> +<para>Also, connecting to the internet as <systemitem class="username">root</systemitem> is an extremely bad idea, as it +seriously increases your vulnerability to malicious hacking.</para></warning> + +</sect2> +</sect1> + +<sect1 id="file-associations"> +<title>Configuring File Associations</title> + +<!-- TODO: The content should probably be here too, but this'll do for --> +<!-- now. --> +<para>&kde; provides many applications which can open many different +types of file. Most of the time, the defaults will work with no +problems, but &konqueror; provides a powerful system to allow you to +change the applications used to open each file type. For more details, +choose the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Konqueror...</guimenuitem></menuchoice> menu item, select +<guilabel>File Associations</guilabel> in the configuration dialog, +and click on <guibutton>Help</guibutton>.</para> + +</sect1> + + +<sect1 id="commandline"> +<title>At the Command Line</title> + +<para>Although &konqueror; is a very powerful and flexible +<acronym>GUI</acronym> file manager, there are occasions when the experienced +&Linux; / &UNIX; user wants to get down to the basics and work at the text +command line level.</para> + +<para>You can, of course, open an instance of &konsole;, perhaps with +&konqueror;'s Menubar <menuchoice><guimenu>Tools</guimenu><guimenuitem>Open +Terminal</guimenuitem></menuchoice> option or with <keycombo +action="simul">&Ctrl;<keycap>T</keycap></keycombo>.</para> +<para>If you only want to launch a program or view a &URL;, the <menuchoice> +<guimenu>Tools</guimenu><guimenuitem>Run Command</guimenuitem></menuchoice> +(<keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>) option may be +easier.</para> + +<para><menuchoice><guimenu>Tools</guimenu><guimenuitem>Execute Shell Command... +</guimenuitem></menuchoice> (<keycombo action="simul">&Ctrl; +<keycap>E</keycap></keycombo>) opens a small command line dialog window where +you can enter a shell command such as <userinput>ps -ax | grep kdeinit +</userinput>. Note that it does not support full featured terminal control +characters, so applications such as <userinput>top</userinput> and <userinput> +less</userinput> will not work properly, but it is available immediately +without the delay involved in starting &konsole;. +</para> + +<para>For more complex operations, &konqueror; has another nice feature: the +Menubar <menuchoice><guimenu>Window</guimenu><guimenuitem>Show Terminal +Emulator</guimenuitem></menuchoice> option, which opens up a terminal window as +a new view within &konqueror;. As long as the link icon is visible at the +bottom right corner of each view, the terminal will follow any folder changes +you make in the normal file manager view.</para> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="cmndline.png"/></imageobject> +<textobject> +<phrase>Including the terminal emulator</phrase> +</textobject> +</mediaobject> + +</sect1> + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/index.docbook b/doc/konqueror/index.docbook new file mode 100644 index 000000000..ef4c485d3 --- /dev/null +++ b/doc/konqueror/index.docbook @@ -0,0 +1,110 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd" [ + <!ENTITY kappname "&konqueror;"> + <!ENTITY package "kdebase"> + <!ENTITY konqueror-introduction SYSTEM "introduction.docbook"> + <!ENTITY konqueror-basics SYSTEM "basics.docbook"> + <!ENTITY konqueror-filemanager SYSTEM "filemanager.docbook"> + <!ENTITY konqueror-browser SYSTEM "browser.docbook"> + <!ENTITY konqueror-path-complete SYSTEM "path-complete.docbook"> + <!ENTITY konqueror-bookmarks SYSTEM "bookmarks.docbook"> + <!ENTITY konqueror-sidebar SYSTEM "sidebar.docbook"> + <!ENTITY konqueror-save-settings SYSTEM "save-settings.docbook"> + <!ENTITY konqueror-plugins SYSTEM "plugins.docbook"> + <!ENTITY konqueror-config SYSTEM "config.docbook"> + <!ENTITY konqueror-commands SYSTEM "commands.docbook"> + <!ENTITY konqueror-faq SYSTEM "faq.docbook"> + <!ENTITY konqueror-credits SYSTEM "credits.docbook"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + <!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &konqueror; Handbook</title> + +<authorgroup> +<author>&Pamela.Roberts; &Pamela.Roberts.mail;</author> + +<othercredit role="developer"> +<othername>The KDE Team</othername> +<contrib>Developers</contrib> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2000</year> <year>2002</year> +<holder>Erwan Loisant</holder> +<holder>Pamela Roberts</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2002-09-22</date> +<releaseinfo>3.1</releaseinfo> + +<abstract><para>&konqueror; is &kde;'s advanced File Manager, Web Browser and + Universal Viewing Application.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Konqueror</keyword> +<keyword>Kdebase</keyword> +<keyword>File Manager</keyword> +<keyword>Browser</keyword> +<keyword>Viewer</keyword> +</keywordset> + +</bookinfo> + + +&konqueror-introduction; +&konqueror-basics; +&konqueror-filemanager; +&konqueror-browser; +&konqueror-path-complete; +&konqueror-bookmarks; +&konqueror-sidebar; +&konqueror-save-settings; +&konqueror-plugins; +&konqueror-config; +&konqueror-commands; +&konqueror-faq; +&konqueror-credits; + + +<appendix id="installation"> +<title>Installation</title> + +<para>&konqueror; is part of the kdebase package which an essential part of +&kde;.</para> + +<para>For instructions on acquiring &kde; please see <ulink +url="http://www.kde.org">http://www.kde.org</ulink>.</para> + +<para>For further information about &konqueror; you might like to visit +<ulink url="http://www.konqueror.org">http://www.konqueror.org</ulink>.</para> + + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +</appendix> + + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> diff --git a/doc/konqueror/introduction.docbook b/doc/konqueror/introduction.docbook new file mode 100644 index 000000000..14fc2a6c8 --- /dev/null +++ b/doc/konqueror/introduction.docbook @@ -0,0 +1,64 @@ +<chapter id="introduction"> +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-10-20</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + +<title>Overview</title> + +<para><emphasis>&konqueror;</emphasis> is an advanced +<link linkend="filemanager">file manager</link> for the +K Desktop Environment, providing file management functions ranging from simple +cut/copy and paste operations to advanced local and remote network file +browsing. Folder contents can be displayed in a variety of text and icon +<link linkend="viewmode">view modes</link>, which can include thumbnail +preview images of file contents. File and folder properties can easily be +examined and changed and applications launched with a simple click of the +&LMB;.</para> + +<para><emphasis>&konqueror;</emphasis> is an <acronym>HTML</acronym> 4.01 +compliant <link linkend="browser">web browser</link> with built in support for +JavaScript (ECMA-262), <acronym>CSS</acronym> (Cascading Style Sheets) and +bidirectional scripts (such as Arabic and Hebrew). It provides support for the secure +running of &Java; applets, &Netscape; plugins for viewing &Flash;, &RealAudio; and &RealVideo; and <acronym>SSL</acronym> for secure +communications. Advanced features include automatic &URL; and form completion, +the ability to import bookmarks from other browsers and tabbed browsing. +</para> + +<para><emphasis>&konqueror;</emphasis> is also an excellent full featured +<link linkend="ftp">FTP</link> client.</para> + +<para><emphasis>&konqueror;</emphasis> is a universal viewing application, +capable of displaying images and documents without having to launch another +application. It does this by embedding components (&kde; Parts) provided by +other applications; from &kview; for image viewing, &kdvi; for +<acronym>DVI</acronym> viewing, &kghostview; for &PostScript; documents and +from the various &koffice; applications for their document types. +</para> + +<para><emphasis>&konqueror;</emphasis> is a fully customizable application +which anyone can <link linkend="config">configure</link> to suit their own +needs, from changing the overall style and the sizes of text and icons to +selecting which items appear in the Menubar, changing the number and +positions of the toolbars and even defining new shortcut key combinations. +Different configuration <link linkend="save-settings">profiles</link> can be +saved for easy recall as needed. +</para> + +</chapter> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/konqorg.png b/doc/konqueror/konqorg.png Binary files differnew file mode 100644 index 000000000..0812aa045 --- /dev/null +++ b/doc/konqueror/konqorg.png diff --git a/doc/konqueror/man-kbookmarkmerger.1.docbook b/doc/konqueror/man-kbookmarkmerger.1.docbook new file mode 100644 index 000000000..dab890556 --- /dev/null +++ b/doc/konqueror/man-kbookmarkmerger.1.docbook @@ -0,0 +1,112 @@ +<?xml version="1.0" ?> +<!-- vim:set ts=4 noet syntax=xml: --> +<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ +<!ENTITY % English "INCLUDE"> +<!ENTITY kbookmarkmerger "<command>kbookmarkmerger</command>"> +]> + +<refentry lang="&language;"> +<refentryinfo> + <title>KDE User's Manual</title> + <author> + &Frerich.Raabe; + &Frerich.Raabe.mail; + </author> + <date>February 1st, 2005</date> + <productname>K Desktop Environment</productname> +</refentryinfo> + +<refmeta> + <refentrytitle>&kbookmarkmerger;</refentrytitle> + <manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> + <refname>&kbookmarkmerger;</refname> + <refpurpose>A program for merging a given set of bookmarks into the + user's list of bookmarks.</refpurpose> +</refnamediv> + +<refsynopsisdiv> +<cmdsynopsis> + &kbookmarkmerger; + <arg choice="opt" rep="repeat">Qt Options</arg> + <arg choice="opt" rep="repeat">KDE Options</arg> + <arg choice="req">directory</arg> +</cmdsynopsis> +</refsynopsisdiv> + +<refsect1> +<title>Description</title> +<para>&kbookmarkmerger; is a program for merging a given set of bookmarks into +the user's set of bookmarks; if the user doesn't have any bookmarks created +yet, a new bookmark list is created and the given bookmarks are inserted into +it. While doing this, &kbookmarkmerger; keeps track of which files were +merged in a previous run already, so no bookmark will get installed to the +user's bookmarks more than once. In case &kde; is running while +&kbookmarkmerger; is executed, the &kde; bookmark subsystem will be informed +of any changes to the user's bookmarks, so that all applications accessing +that information (&ie; &konqueror;) will pick the changes up instantly.</para> + +<para>The traditionally used approach to achieve something like this was to +use carefully crafted skeleton home directories when creating a new user +account, to provide the user with a standard set of bookmarks. The problem +with this approach is that after the user account has been created, no new +bookmarks can be propagated.</para> + +<para>This mechanism is useful for system administrators who want to propagate +a bookmark pointing to a certain document (for instance, important notes about +the system) to all users. Distributors might find it useful as well, for +instance by augmenting the software packages they supply with bookmark files +which &kbookmarkmerger; merges into the user's bookmark list when the +package is installed. That way, documentation shipped with a software package +is easily and visibly accessible right after the package has been +installed.</para> + +<para>The only parameter required by &kbookmarkmerger; is the name of a +directory which shall be scanned for bookmark files. All files in the given +directory will be considered for being merged into the user's setup. The +files in the given directory should be valid <acronym>XBEL</acronym> +files.</para> +</refsect1> + +<refsect1> +<title>See Also</title> +<para><ulink url="help:/konqueror/index.html">&konqueror; manual</ulink></para> +</refsect1> + +<refsect1> +<title>Examples</title> +<screen>joe@hal9000:~> <command>kbookmarkmerger <filename>/usr/local/extra-bookmarks</filename></command></screen> +<para>Merges all bookmark files stored in +<filename>/usr/local/extra-bookmarks</filename> into joe's list of +bookmarks.</para> +</refsect1> + +<refsect1> +<title>Standards</title> +<variablelist> +<varlistentry><term/><listitem><para> + <ulink url="http://pyxml.sourceforge.net/topics/xbel/"><acronym>XBEL</acronym> specification</ulink> +</para></listitem></varlistentry> +</variablelist> +</refsect1> + +<refsect1> +<title>Restrictions</title> +<para>When determining whether a given bookmark file has been merged into the +user's bookmarks already or not, &kbookmarkmerger; merely looks at the +filename of the bookmark file - the contents are not checked at all. This means +that changing a bookmark file which was already merged into a user's bookmarks +will not trigger merging it once again.</para> + +<para>Also note that in case a user modifies a bookmark which was merged into +his setup, the original bookmark file will be left unmodified.</para> +</refsect1> + +<refsect1> +<title>Author</title> +<para>&Frerich.Raabe; &Frerich.Raabe.mail;</para> +</refsect1> +</refentry> + diff --git a/doc/konqueror/parts.png b/doc/konqueror/parts.png Binary files differnew file mode 100644 index 000000000..1439d0b89 --- /dev/null +++ b/doc/konqueror/parts.png diff --git a/doc/konqueror/path-complete.docbook b/doc/konqueror/path-complete.docbook new file mode 100644 index 000000000..a05f0845c --- /dev/null +++ b/doc/konqueror/path-complete.docbook @@ -0,0 +1,82 @@ +<chapter id="path-complete"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-05</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + + +<title>Automatic Text Completion</title> + +<para>You can get &konqueror; to help you enter a path or &URL; into the +Location Toolbar by enabling one of the <guimenuitem>Text Completion</guimenuitem> +features. To do this <mousebutton>right</mousebutton> + click on a clear part of the Location Toolbar text entry box and select +<guisubmenu>Text Completion</guisubmenu> from the pop up menu. This will let you +choose between the following options:</para> + +<variablelist> + +<varlistentry> +<term><guimenuitem>None</guimenuitem></term> +<listitem><para>What you get is what you type.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Manual</guimenuitem></term> +<listitem><para>When you have typed part of a path or &URL;, pressing +<keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo> will complete the entry if it is +possible to do so unambiguously.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Automatic</guimenuitem></term> +<listitem><para>As you type into the Location Toolbar window &konqueror; will +automatically extend what you type to complete one possible path or &URL;, +highlighting the characters it has added. Continue typing if that's not what +you wanted or press &Enter; to accept it.</para></listitem> + </varlistentry> + +<varlistentry> +<term><guimenuitem>Dropdown List</guimenuitem></term> +<listitem><para>A drop-down window will appear as you type, showing the +possible matches to what you have typed so far. When the path or &URL; that +you want appears in the window double click on it with the &LMB;. +You can also use the +<keysym>Down Arrow</keysym> and <keysym>Up Arrow</keysym> +keys to select it then press &Enter;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Short Automatic</guimenuitem></term> +<listitem><para>This is like Automatic mode except that it only extends +what you have typed as far as the next <keycap>/</keycap> symbol in the path +or &URL;. Press <keycombo action="simul">&Ctrl;<keycap>E</keycap></keycombo> to accept the +suggestion, &Enter; when the complete path or &URL; is +shown.</para></listitem> +</varlistentry> + +</variablelist> +<para>You should try out these different modes and pick the one that suits you + best.</para> +<para>The history of recently visited &URL;s that &konqueror; uses for the +Text Completion function can be viewed and edited in the <guilabel>History +</guilabel> page of the <link linkend="sidebar">Navigation Panel</link>.</para> + + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/plugins.docbook b/doc/konqueror/plugins.docbook new file mode 100644 index 000000000..83ca89075 --- /dev/null +++ b/doc/konqueror/plugins.docbook @@ -0,0 +1,162 @@ +<chapter id="plugins"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-09-22</date> +<releaseinfo>3.1</releaseinfo> +</chapterinfo> + + +<title>Plugins</title> + +<sect1 id="netscape-plugin"> +<title>&Netscape; Plugins</title> + +<para>Currently, &konqueror; supports &Netscape; 4.x plugins.</para> + +<para>Selecting <menuchoice><guimenu>Settings</guimenu><guisubmenu> +Configure Konqueror...</guisubmenu><guimenuitem>Plugins</guimenuitem> +</menuchoice> will give you a dialog box with two tabbed pages; +<guilabel>Scan</guilabel> and <guilabel>Plugins</guilabel>.</para> + +<para>The <guilabel>Scan</guilabel> page controls how &kde; scans for new +&Netscape; plugins, either manually by pressing the <guibutton>Scan for New +Plugins</guibutton> button or automatically each time &kde; starts up.</para> + +<para>The scan is done by looking through the folders listed in the +<guilabel>Scan Folders</guilabel> list for <literal +role="extension">.so</literal> files containing plugin code. It examines every +such file to find out which <acronym>MIME</acronym> types the plugin +supports. It then creates <acronym>MIME</acronym> type definitions for &kde; in +the user's <filename class="directory"> ~/.kde/share/mimelnk</filename> +folder to make other applications aware of them.</para> + +<para>The <guilabel>Plugins</guilabel> page shows you the &Netscape; plugins +that &kde; has found, and for each plugin it lists the <acronym>MIME</acronym> +types and the filename suffixes it uses to recognize them.</para> + +<para>The dialog box also contains a checkbox <guilabel> +Enable plugins globally</guilabel> which you can use to enable or disable +plugins that can be contained in <acronym>HTML</acronym> pages (these can +be considered a security risk).</para> + +</sect1> + +<sect1 id="konq-plugin"> +<title>&konqueror; Plugins</title> + +<para>The package kdeaddons contains several useful plugins that interact with +&konqueror; in various ways. These are explained briefly below, more detailed +information may be obtained by looking through the <guimenuitem>Konqueror +Plugins</guimenuitem> section in the &kde; Help Center.</para> + +<variablelist> + +<varlistentry> +<term>Web Page Translation</term> +<listitem><para>This uses AltaVista's BabelFish site to translate the current +<acronym>HTML</acronym> page to whatever language you want (within reason). It +can be launched with <menuchoice><guimenu>Tools</guimenu><guisubmenu>Translate +Web Page</guisubmenu></menuchoice>.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Folder View Filter</term> +<listitem><para>This is controlled by +<menuchoice><guimenu>Tools</guimenu><guisubmenu>View +Filter</guisubmenu></menuchoice> and allows you to choose which types of item +are displayed in a folder.</para></listitem> +</varlistentry> + +<varlistentry> +<term>DOM Tree Viewer</term> +<listitem><para>Selecting <menuchoice><guimenu>Tools</guimenu><guisubmenu>Show +DOM Tree</guisubmenu></menuchoice> opens a new window which displays the +document object model (DOM) of the current <acronym>HTML</acronym> +page.</para></listitem> +</varlistentry> + +<varlistentry> +<term>HTML Validator</term> +<listitem><para>This is started with +<menuchoice><guimenu>Tools</guimenu><guisubmenu>Validate Web +Page</guisubmenu><guimenuitem>Validate HTML</guimenuitem></menuchoice>. It +uses the W3C HTML validator to validate the current page, very useful when +creating web pages.</para></listitem> +</varlistentry> + +<varlistentry> +<term>CSS Validator</term> +<listitem><para>Started with +<menuchoice><guimenu>Tools</guimenu><guisubmenu>Validate Web +Page</guisubmenu><guimenuitem>Validate CSS</guimenuitem></menuchoice>, it uses +the W3C CSS validator to validate the current page's Cascading Style +Sheets.</para></listitem> +</varlistentry> + +<varlistentry> +<term>HTML Settings</term> +<listitem><para>Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>HTML +Settings</guisubmenu></menuchoice> to enable or disable a number of HTML +settings without going through the <guimenu>Settings</guimenu> dialog. +</para></listitem> +</varlistentry> + +<varlistentry> +<term>Image Gallery</term> +<listitem><para>In File Manager mode, you can select +<menuchoice><guimenu>Tools</guimenu><guisubmenu>Create Image +Gallery</guisubmenu></menuchoice> to create an HTML page with +thumbnails of all the images in the current folder. By default the HTML page +is called <filename>images.html</filename> and the thumbnails are put into a +new <filename>thumbs</filename> folder. +</para></listitem> +</varlistentry> + +<varlistentry> +<term>User Agent Changer</term> +<listitem><para>Select <menuchoice><guimenu>Tools</guimenu><guisubmenu>Change +Browser Identification</guisubmenu></menuchoice> to get a menu that allows +you to change the User Agent string without going through the <guimenu>Settings +</guimenu> dialog procedure. +</para></listitem> +</varlistentry> + +<varlistentry> +<term>Archive Web Page</term> +<listitem><para>Invoked with <menuchoice><guimenu>Tools</guimenu><guisubmenu> +Archive Web Page</guisubmenu></menuchoice>, this tool creates an archive +(<literal role="extension">.war</literal> ) file containing the web page being +viewed including the images. <mousebutton>Left</mousebutton> click on the +archive file name to view the saved page. +</para></listitem> +</varlistentry> + +<varlistentry> +<term>Navigation Panel Media Player</term> +<listitem><para>This is a simple media player, embedded as a tab page in the +Navigation Panel. You can drag songs or videos onto this page to play them. +</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + + + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/save-settings.docbook b/doc/konqueror/save-settings.docbook new file mode 100644 index 000000000..9fb248815 --- /dev/null +++ b/doc/konqueror/save-settings.docbook @@ -0,0 +1,92 @@ +<chapter id="save-settings"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2003-11-06</date> +<releaseinfo>3.2</releaseinfo> +</chapterinfo> + +<title>Saving Settings & Profiles</title> +<sect1 id="save-settings-general"> +<title>General Settings</title> +<para>When you close down &konqueror; your current <guimenu>View</guimenu> +menu settings (such as the <guimenuitem>View Mode</guimenuitem>, +<guimenuitem>Use index.html</guimenuitem> and <guimenuitem>Show Hidden Files +</guimenuitem> items) are not automatically saved as the default +options; however, you can have &konqueror; remember these settings by +selecting <menuchoice><guimenu>Settings</guimenu><guimenuitem>Save View +Profile "Web Browsing"...</guimenuitem></menuchoice> and the current +setting will become the default option to be used the next time +&konqueror; is started.</para> + +<para>But you can also specify different <guimenu>View</guimenu> menu settings +for an individual folder. To do this check the <guimenuitem>View Properties +Saved in Folder</guimenuitem> box in the <guimenu>Settings</guimenu> menu, +change the <guimenu>View</guimenu> settings to whatever you want then uncheck +the +<guimenuitem>View Properties saved in Folder</guimenuitem> box. Doing this +creates a <filename>.directory</filename> file in that folder to hold the +folder <guimenu>View</guimenu> settings. Use the <menuchoice><guimenu> +Settings</guimenu><guimenuitem>Remove Folder Properties</guimenuitem> +</menuchoice> option to remove the folder specific +settings (or just delete the <filename>.directory</filename> file).</para> +<note><para>One nice use of this feature is if you have a folder full of +pictures. You can set that particular folder to display thumbnails of the +pictures (by choosing <guimenuitem>Icon View</guimenuitem> and <menuchoice> +<guisubmenu>Preview</guisubmenu><guimenuitem>Show Previews</guimenuitem> +</menuchoice> from the <guimenu>View</guimenu> menu) when you open it, while +not displaying images as thumbnails in other folders.</para></note> +</sect1> + +<sect1 id="save-settings-view-profiles"> +<title>View Profiles</title> +<para>&konqueror; can save a whole set of options as a <quote>View +Profile</quote>. Some view profiles are part of the standard &konqueror; +installation, such as <property>Web Browsing</property> and <property>File +Management</property>, but you can add your own, too.</para> + +<para>To modify a view profile (say, the <property>Web Browsing</property> +profile), load the profile with +<menuchoice><guimenu>Settings</guimenu><guisubmenu>Load View +Profile</guisubmenu><guimenuitem>Web Browsing</guimenuitem> </menuchoice>, and +change the &konqueror; settings to whatever you want. Now select +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Save View Profile "Web +Browsing"...</guimenuitem></menuchoice>. In the dialog which appears, you can +change the name of the profile, which will create a new profile with that name, +or you can leave the name as it is to modify the current profile. If you select +<guilabel>Save URLs in profile</guilabel>, the current &URL; will be loaded +when you load that view profile. This functions in a similar way to the +<quote>Home Page</quote> in many web browsers. If you want &konqueror; to start +up with an empty window enter <userinput>about:blank</userinput> into the +location bar before saving the profile.</para> + +<note><para>You can create a desktop icon to start &konqueror; with your new +profile. First create a desktop icon by dragging the &konqueror; icon from the +<guimenu>K</guimenu> menu onto the desktop and selecting <guimenuitem>Copy +Here</guimenuitem>. Then <mousebutton>right</mousebutton> click on the new +icon, select +<guimenuitem>Properties...</guimenuitem> and change <guilabel>Program +Name</guilabel> in the <guilabel>Execute</guilabel> tab page to +<userinput><command>kfmclient</command> <option>openProfile +<replaceable>MyNewProfile</replaceable></option></userinput>, +<replaceable>MyNewProfile</replaceable> being what you called the new +profile. Then in the <guilabel>General</guilabel> tab page change the name to +something like <filename>MyNewProfile</filename> and pick a more +suitable icon.</para></note> + +</sect1> +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konqueror/shortcut1.png b/doc/konqueror/shortcut1.png Binary files differnew file mode 100644 index 000000000..4d7a77c30 --- /dev/null +++ b/doc/konqueror/shortcut1.png diff --git a/doc/konqueror/shortcut2.png b/doc/konqueror/shortcut2.png Binary files differnew file mode 100644 index 000000000..7c461b417 --- /dev/null +++ b/doc/konqueror/shortcut2.png diff --git a/doc/konqueror/sidebar.docbook b/doc/konqueror/sidebar.docbook new file mode 100644 index 000000000..9ba4cb923 --- /dev/null +++ b/doc/konqueror/sidebar.docbook @@ -0,0 +1,201 @@ +<chapter id="sidebar"> + +<chapterinfo> +<authorgroup> +<author>&Pamela.Roberts;</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2002-09-22</date> +<releaseinfo>3.1</releaseinfo> +</chapterinfo> + +<title>The Navigation Panel</title> + +<para>The Navigation Panel appears as a separate view at the left of +&konqueror;'s window. It can be invoked with <menuchoice><guimenu>Window +</guimenu><guimenuitem>Show Navigation Panel</guimenuitem></menuchoice> or +toggled on and off with the <keycap>F9</keycap> key.</para> + +<mediaobject> +<imageobject><imagedata format="PNG" fileref="dirtree.png"/></imageobject> +<textobject> +<phrase>With the Navigation Panel</phrase> +</textobject> +</mediaobject> + +<para>It contains a number of tabbed pages; <mousebutton>left</mousebutton> +click on a tab's icon to view that page. <mousebutton>Left</mousebutton> +clicking on the icon for the visible page will collapse the Navigation Panel +so that only the tab icons are visible.</para> +<variablelist> + +<varlistentry> +<term><guilabel>Bookmarks</guilabel></term> +<listitem><para>This page shows a tree view of your Bookmarks. <mousebutton> +Left</mousebutton> click on an item to open it in the main view.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>History</guilabel></term> +<listitem><para>This page shows a tree view of your browsing History. +<mousebutton>Left</mousebutton> clicking on an item will open it in the main +view, or you can open it in a new &konqueror; window by <mousebutton>right +</mousebutton> clicking and selecting <guimenuitem>New Window</guimenuitem> +from the pop up menu.</para> +<para>You can remove an item from the history by <mousebutton>right +</mousebutton> clicking on it and selecting <guimenuitem>Remove Entry +</guimenuitem>. Selecting <guimenuitem>Clear History...</guimenuitem> will +clear out the entire history.</para> +<para>The pop up menu you get when you <mousebutton>right</mousebutton> click +on any entry in the History page also gives you the option of choosing +whether the entire history is sorted by name or by date.</para> +<para>Selecting <guimenuitem>Preferences...</guimenuitem> from this pop up +menu brings up the <guilabel>History Sidebar</guilabel> control module. This +can be used to set the maximum size of your history and set a time after which +items are automatically removed. You can also set different fonts for new and +old &URL;s. +The <guilabel>Detailed tooltips</guilabel> checkbox controls how much +information is displayed when you hover the mouse pointer over an item in the +history page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Home Folder</guilabel></term> +<listitem><para>This page shows a tree view of the subfolders your home +folder. Note that <quote>hidden</quote> folders (those with names +beginning with a dot) are not shown. +<mousebutton>Left</mousebutton> click on an item to open it in the +main view, or <mousebutton>right</mousebutton> click to display a pop up +menu allowing you to open the subfolder in a new window or as a new tab +page of the main view. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Network</guilabel></term> +<listitem><para>This page is intended to show a tree view of your important +network connections, although local folders can also be included. Again, +you can <mousebutton>left</mousebutton> click on an item to open it in the +main view or <mousebutton>right</mousebutton> click to bring up a menu with +a wider range of possibilities.</para> +<para>The folders shown in the <guilabel>Network</guilabel> page are held in +the folder <filename class="directory"> +~/.kde/share/apps/konqsidebartng/virtual_folders/remote/</filename>, and you can make +new ones just as you would make any other subfolder. The items within +these folders are held as <literal role="extension">.desktop</literal> files +and can be created with &konqueror;'s <menuchoice><guisubmenu>Create New</guisubmenu> +<guimenuitem>Link to Location (URL)...</guimenuitem></menuchoice> option.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Root Folder</guilabel></term> +<listitem><para>The Root Folder tree has the path <filename +class="directory">/</filename>, and is the base folder of your system's +local files. If you expand the <quote>Root</quote> folder you will find +another folder called <filename class="directory">root</filename>. This +belongs to the system administrator or Super User and is her home folder. +You will also find a folder called +<filename class="directory">home</filename>, in which you should be able to +find your own <quote>Home</quote> folder again.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Services</guilabel></term> +<listitem><para>This page provides quick access to the following services: +</para> +<para>The <guilabel>Audio CD Browser</guilabel>.</para> +<para><guilabel>Devices</guilabel>. This shows your hard disc +partitions, floppy and &CD-ROM;. <mousebutton>Left</mousebutton> click on +a device or partition name to mount it and display its contents in the main +view. A mounted device or partition can be unmounted by <mousebutton>right +</mousebutton> clicking on the device name and selecting <guimenuitem>Unmount +</guimenuitem> from the pop up menu. +</para> +<para>The <guilabel>LAN Browser</guilabel> allows you to browse other +machines connected to your Local Area Network.</para> +<para>The <guilabel>Print System Browser</guilabel> tree gives you quick +access to &kde;'s print manager <application>Kprinter</application>.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>The Navigation Panel configuration can be changed by <mousebutton>right +</mousebutton> clicking on the empty area below the bottom tab icon or by +<mousebutton>left</mousebutton> clicking on the <guilabel>Configuration +Button</guilabel> icon (the top icon in the previous screenshot, it may not +be present in your setup). Doing this brings up a menu with the following +options:</para> +<variablelist> + +<varlistentry> +<term><guisubmenu>Add New</guisubmenu></term> +<listitem><para>This option lets you add a new tab page to the Navigation +Panel. The new page can contain the <guimenuitem>Sidebar Media Player +</guimenuitem> (a <link linkend="konq-plugin">&konqueror; Plugin</link> +feature) or a new +<guimenuitem>Folder</guimenuitem> tree view.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Multiple Views</guimenuitem></term> +<listitem><para>Selecting this option splits the Navigation Panel so that +two tab pages can be seen at once.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Show Tabs Left</guimenuitem></term> +<listitem><para>This option lets you choose whether the tab icons are shown at +the left or right of the Navigation Panel.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Show Configuration Button</guimenuitem></term> +<listitem><para>Use this option to show or hide the <guilabel>Configuration +Button</guilabel> icon.</para> +</listitem> +</varlistentry> + +</variablelist> + +<para><mousebutton>Right</mousebutton> clicking on a tab icon brings up a +menu with the following options:</para> + +<variablelist> +<varlistentry> +<term><guimenuitem>Set URL</guimenuitem></term> +<listitem><para>Only available for folder pages, this option lets you +change the &URL; (path) of the folder viewed in that page.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Set Icon</guimenuitem></term> +<listitem><para>To change the tab icon.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guimenuitem>Remove</guimenuitem></term> +<listitem><para>To remove the tab page from the Navigation Panel.</para> +</listitem> +</varlistentry> + +</variablelist> + + +</chapter> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +sgml-parent-document:("index.docbook" "book" "chapter") +End: +--> diff --git a/doc/konsole/Makefile.am b/doc/konsole/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/konsole/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/konsole/index.docbook b/doc/konsole/index.docbook new file mode 100644 index 000000000..826964fa4 --- /dev/null +++ b/doc/konsole/index.docbook @@ -0,0 +1,1465 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" + "dtd/kdex.dtd" [ +<!ENTITY kappname "&konsole;"> +<!ENTITY package "kdebase"> +<!ENTITY % English "INCLUDE"> +<!ENTITY % addindex "IGNORE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &konsole; Handbook</title> +<authorgroup> +<author>&Jonathan.Singer; &Jonathan.Singer.mail;</author> +<author>&Kurt.Hindenburg; &Kurt.Hindenburg.mail;</author> + +<othercredit role="developer"> +&Kurt.Hindenburg; &Kurt.Hindenburg.mail; +</othercredit> + +<othercredit role="developer"> +&Waldo.Bastian; &Waldo.Bastian.mail; +<!-- <contrib>Maintainer</contrib> --> +</othercredit> + +<othercredit role="reviewer"> +&Mike.McBride; &Mike.McBride.mail; +<!-- <contrib>Reviewer</contrib> --> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year><year>2001</year><year>2002</year> +<holder>&Jonathan.Singer;</holder> +</copyright> +<copyright> +<year>2005</year> +<holder>&Kurt.Hindenburg;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2006-08-16</date> +<releaseinfo>1.6.2</releaseinfo> + +<abstract><para>This document is the user handbook for the &konsole; + application.</para> +<para>&konsole; is an X terminal emulator for &kde;.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>konsole</keyword> +<keyword>kdebase</keyword> +<keyword>command</keyword> +<keyword>line</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction to &konsole;</title> + +<sect1 id="terminal"> +<title>What is a terminal?</title> +<para>&UNIX; operating systems were +originally designed as text-only systems, controlled by keyboard +commands -- what is known as a command-line interface +(<acronym>CLI</acronym>). The &X-Window; and &kde; and other projects +have since added the graphical interface you are now using. However, +the underlying <acronym>CLI</acronym> system is still there, and is +frequently the easiest, fastest and most powerful way to perform many +tasks.</para> +<para>&konsole; is what is known as an X terminal +emulator, often referred to as a terminal or a shell. It gives you the +equivalent of an old-fashioned text screen on your desktop, but one +which can easily share the screen with your graphical +applications. &Windows; users may be familiar with the +<application>MS-DOS Prompt</application> utility, which has the analogous +function of offering a <trademark>DOS</trademark> command-line under +&Windows;. (Although the &UNIX; <acronym>CLI</acronym>s offer far more +power and ease of use than does <acronym>DOS</acronym>!)</para> + +<para>Explaining the use of the &UNIX; <acronym>CLI</acronym> is +beyond the scope of this document, as it would require a lengthy +book. Fortunately, many such books are available in every language in +any good bookstore or library. There are also tutorials available on +the Internet. Enjoy &kde;, but don't be shy about learning to use the +command-line! You will find that even learning just the basics will +make your computer use much more efficient and enjoyable.</para> +</sect1> + +<sect1 id="features"> +<title>What makes &konsole; special?</title> +<para>&konsole;'s +advanced features include simple configuration and the ability to use +multiple terminal shells in a single window, making for a less +cluttered desktop.</para> + +<para>Using &konsole;, a user can open:</para> +<itemizedlist> +<listitem><para>&Linux; console sessions</para></listitem> +<listitem><para>Shell sessions</para></listitem> +<listitem><para><application>Screen</application> sessions</para></listitem> +<listitem><para><application>Midnight Commander</application> file manager +sessions</para></listitem> +<listitem><para><systemitem class="username">Root</systemitem> console + sessions</para></listitem> +<listitem><para><systemitem class="username">Root</systemitem> + <application>Midnight Commander</application> sessions</para></listitem> +<listitem><para>User created sessions</para></listitem> +</itemizedlist> + +<para>These sessions can be renamed to help you keep track of all your shells, +or signaled (<errorcode>STOP</errorcode>, <errorcode>CONT</errorcode>, +<errorcode>HUP</errorcode>, <errorcode>INT</errorcode>, +<errorcode>TERM</errorcode>, <errorcode>KILL</errorcode>).</para> + +<para>For more control over &konsole;, a user can:</para> +<itemizedlist> +<listitem><para>hide/show the menubar and/or +frame</para></listitem> +<listitem><para>select the size of a &konsole; window, fonts, color +schemes, and key mapping</para></listitem> +<listitem><para>change location of the scrollbar or hide the +scrollbar</para></listitem> +<listitem><para>change location of the tabbar or hide the +tabbar</para></listitem> +</itemizedlist> + +<para>All chosen settings can be made the default for forthcoming sessions by +saving them.</para> + +<para>For those with a deep interest in the taxonomy of free X +terminals, there are two others of this kind: +<application>xterm</application>, the original, written even before X +itself (a month or two), and <application>xvt</application>, a +lightweight <application>xterm</application> clone, on which most +other currently available derivatives (notably +<application>eterm</application>) are based.</para> + +<para>After a decade, &konsole; is the first rewrite from the ground +up. While <application>xterm</application> has definitely been hacked +to death (its <filename>README</filename> begins with the words +<quote>Abandon All Hope, Ye Who Enter Here</quote>), &konsole; offers +a fresh start using contemporary technologies and understanding of +X.</para> + +</sect1> +</chapter> + +<chapter id="use-of-konsole"> +<title>Use of &konsole;</title> + +<sect1 id="startup"> +<title>Startup</title> + +<para>When &konsole; is started, an application (typically a &UNIX; +shell) runs in the window. Simply type at the prompt.</para> + +<screenshot> +<screeninfo>&konsole; Screen</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="konsole.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>&konsole; Screen</phrase> +</textobject> +<caption><para>&konsole; with 4 +terminal sessions open.</para></caption> +</mediaobject> +</screenshot> +<para>A <quote>Tip of the Day</quote> window may also appear on +startup, offering hints on the use of &konsole;. If you do not wish to +receive tips, uncheck the <guilabel>Show tips on startup</guilabel> +box.</para> +</sect1> + +<sect1 id="history-option"> +<title>History</title> + +<para>As lines scroll off the top of the screen, they can be reviewed +by moving the scroll bar upwards, scrolling with a mouse wheel or through +the use of the <keycombo +action="simul">&Shift;<keycap>Page Up</keycap></keycombo> (to move +back a page), <keycombo action="simul">&Shift;<keycap>Page +Down</keycap></keycombo> (to move forward a page), <keycombo +action="simul">&Shift;<keycap>Up Arrow</keycap></keycombo> (to move up a +line) and <keycombo +action="simul">&Shift;<keycap>Down Arrow</keycap></keycombo> (to move down a +line) keys (provided the <link +linkend="settings-menu">History</link> option is on).</para> + +<para>In addition, &konsole; mimics the FreeBSD console when +<keycap>scroll lock</keycap> is pressed. When scroll lock is on, +ordinary in- and output from the shell is suspended, and you can +scroll through the history with <keycap>Page Up</keycap>, <keycap>Page +Down</keycap>, and <keycap>Up Arrow</keycap> and <keycap>Down +Arrow</keycap>.</para> + +<para>&konsole;'s history can be configured via +<menuchoice><guimenu>Settings</guimenu><guimenuitem>History...</guimenuitem> +</menuchoice> +</para> + +<para>&konsole; provides a number of history related actions located in the +<link linkend="edit-menu">Edit</link> menu. +</para> + +<itemizedlist> +<listitem> +<para><guimenuitem>Find in History...</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Find Next</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Find Previous</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Save History As...</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Clear History</guimenuitem></para> +</listitem> +<listitem> +<para><guimenuitem>Clear All Histories</guimenuitem></para> +</listitem> +</itemizedlist> + +<note><para>In &konsole;, references to history are to +the text that is displayed in &konsole;'s window. +The shell that is running in &konsole; (e.g. bash) also +has a <quote>history</quote> which is unrelated to &konsole;'s +history.</para></note> + +</sect1> + +<sect1 id="sessions"> +<title>Sessions</title> +<para>If you often have to log into remote machines, or always run a similar set of +terminal applications, you can use &konsole;'s <quote>Session</quote> feature +along with &kde;'s session management to automate a lot of this for you. +Let's take the following example: +You often have open an <application>ssh</application> session to the machine +<replaceable>administration</replaceable> ready for generic administration +tasks. +You may have noticed the <guibutton>New Session</guibutton> button on &konsole;'s tab +bar contains a menu if you click and hold on it, and you can choose new session +types here. We are going to add new entries to this menu. + +<orderedlist> +<listitem><para>Click on the menu entry <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &konsole;...</guimenuitem> +</menuchoice></para></listitem> +<listitem><para>Choose the <guilabel>Session</guilabel> tab.</para> +</listitem> + +<listitem><para>Fill in the first entry with a name. This is the +name that will show in the menu, and will be the default label instead +of <guilabel>Shell</guilabel> when you start a session of this type. +</para></listitem> + +<listitem><para>Enter a command just as you normally would if you opened a new +shell and were going to issue that command. For our first example above, you +might type <userinput><command>ssh</command> <replaceable>administration</replaceable></userinput>.</para></listitem> + +<listitem><para>On the lower part of the panel, configure this +session's appearance. You can have a different font, colour scheme, +and $<envar>TERM</envar> type for each session.</para></listitem> + +<listitem><para>Press the <guibutton>Save +Session...</guibutton> button. A dialog will ask you to confirm the filename. +</para></listitem> + +<listitem><para>Press <guibutton>OK</guibutton>.</para></listitem> + +</orderedlist> +</para> +<para>You should now be able to press and hold the <guibutton>New Session</guibutton> button +on the tab bar, and select your new session type from the list. A new shell +session will open within the &konsole; window, with the result of your executed +command. In our example, you will be at an <application>ssh</application> +passphrase prompt, and when you provide your passphrase, you will be logged +into the remote machine. +<footnote id="use-ssh-agent"><para>You can avoid this step also, by using +ssh-agent, but that is a topic for another goodie.</para></footnote> +Perhaps you want to remotely tail your <acronym>http</acronym> error logs on a +webserver, you could use a commandline something like +<userinput><command>ssh</command> <option>-f</option> +<replaceable>webserver</replaceable> <command>tail</command> +<option>-f</option> +<filename><replaceable>/var/log/httpd-error.log</replaceable></filename></userinput>.</para> + +<para>You can use this to execute local commands as well. Try creating a +session where the command is <userinput><command>tail</command> <option>-f</option> <filename><replaceable>/var/log/messages</replaceable></filename></userinput>. <!--or 'screen +<someone who uses screen please supply some sensible command switches here, say --> +<!--to attach to an irc session>'. --> In this case, exiting the +running application will close the shell session as well.</para> + +<para>One really nice use of this feature is if you find you always have the +same set of open sessions, &kde; can open them all for you automatically +when you start a new &kde; session. Simply have them open as you like +when you exit &kde;, and they will be saved with your &kde; session, and +restored just like any other application when you restart &kde;.</para> + +<note><para>You can assign +<link linkend="settings-menu">shortcuts</link> +to any session.</para></note> + +</sect1> + +<sect1 id="mousebuttons"> + +<title>Mouse Buttons</title> + +<para>This section details the use of the mouse buttons for the common +right handed mouse button order. +For the left handed mouse button order, swap left and right in the text below. +</para> + +<variablelist> + +<varlistentry> +<term><mousebutton>Left</mousebutton></term> + +<listitem><para> All &LMB; clicks will be sent to a mouse-aware +application running in &konsole;. +If an application will react on mouse clicks, &konsole; +indicates this by showing an arrow cursor. If not, an I-beam (bar) +cursor is shown.</para> + +<para>Holding the &LMB; down and +dragging the mouse over the screen with a mouse-unaware application +running will mark a region of the text. While dragging, the marked +text is displayed reversed for visual feedback. Select <guimenuitem>Copy</guimenuitem> +from the <guimenu>Edit</guimenu> menu to copy the marked text to the clipboard for further use +within &konsole; or another application. The selected text can also be +dragged and dropped into compatible applications. Click on the selected +text and drag it to the desired location. Depending on your &kde; settings, +you may need to hold the &Ctrl; key while dragging.</para> + +<para>Normally, new-line characters are inserted at the end of each +line selected. This is best for cut and paste of source code, or the output +of a particular command. For ordinary text, the line breaks are often +not important. One might prefer, however, for the text to be a stream +of characters that will be automatically re-formatted when pasted into +another application. To select in text-stream mode, hold down the +&Ctrl; key while selecting normally.</para> + +<para>Pressing the &Ctrl; and &Alt; keys along with the &LMB; +will select a column of text. +</para> + +<para>Double-click with the &LMB; to select a word; +triple-click to select an entire line.</para> + +<para>If the upper or lower edge of the text area is touched while +marking, &konsole; scrolls up or down, eventually exposing text within +the history buffer. The scrolling stops when the mouse stops +moving.</para> + +<para>After the mouse is released, &konsole; attempts to keep the text +in the clipboard visible by holding the marked area reversed. The +marked area reverts back to normal as soon as the contents of the +clipboard change, the text within the marked area is altered or the +&LMB; is clicked.</para> + +<para>To mark text on a mouse-aware application (Midnight Commander, for example) +the &Shift; key has to be pressed when clicking.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><mousebutton>Middle</mousebutton></term> + +<listitem><para>Pressing the &MMB; +pastes text currently in the clipboard. Holding down the &Ctrl; key as you +press the &MMB; pastes the text and sends +it to &konsole;.</para> + +<note><para>If you have a mouse with only two buttons, pressing both +the &LMB; and &RMB; +together emulates the +&MMB; +of a three button mouse.</para></note> + +<para>If you have a <mousebutton>wheel</mousebutton> as the middle button, +rolling it in a mouse-unaware program will move &konsole;'s scrollbar.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><mousebutton>Right</mousebutton></term> +<listitem> +<para>The items that appear in the menu when the &RMB; +is pressed depend on whether the menubar is visible.</para> + +<para>Menubar is visible: +<guimenuitem>Set Selection End</guimenuitem>, +<guimenuitem>Copy</guimenuitem>, +<guimenuitem>Paste</guimenuitem>, +<guimenuitem>Send Signal</guimenuitem>, +<guimenuitem>Detach Session</guimenuitem>, +<guimenuitem>Rename Session...</guimenuitem>, +<guimenuitem>Bookmarks</guimenuitem> +and <guimenuitem>Close Session</guimenuitem> +menu items.</para> + +<para>Menubar is hidden: +<guimenuitem>Show Menubar</guimenuitem>, +<guimenuitem>Set Selection End</guimenuitem>, +<guimenuitem>Copy</guimenuitem>, +<guimenuitem>Paste</guimenuitem>, +<guimenuitem>Send Signal</guimenuitem>, +<guimenuitem>New Session</guimenuitem>, +<guimenuitem>Detach Session</guimenuitem>, +<guimenuitem>Rename Session...</guimenuitem>, +<guimenuitem>Bookmarks</guimenuitem>, +<guimenuitem>Settings</guimenuitem> +and <guimenuitem>Close Session</guimenuitem> +menu items.</para> + +<para>In a mouse-aware application, press the &Shift; key along with the +&RMB; to get the pop-up menu. +</para> + +<para>Pressing the &Ctrl; key and &RMB; brings up the +<guimenu>Session</guimenu> menu. +</para> + +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="menubar"> +<title>Menu Bar</title> + +<para>The menubar is at the top of the &konsole; window. +The menubar can be activated and deactivated by the +<keycombo>&Alt;</keycombo> key.</para> +<para><menuchoice><guimenu>Settings</guimenu><guimenuitem>Hide +Menubar</guimenuitem></menuchoice> allows the menubar to be hidden. When +the menubar is hidden, <guimenuitem>Show Menubar</guimenuitem> can be +reached by <mousebutton>right</mousebutton> clicking in the +window or by <keycombo action="simul">&Alt;&Ctrl;<keycap>M</keycap> +</keycombo>, which is the default shortcut for activating the menubar. +The menubar can also be toggled by assigning it a shortcut.</para> + + +<sect2 id="session-menu"> +<title><guimenu>Session</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu><guimenuitem>New +Shell</guimenuitem></menuchoice></term> +<listitem><para><action>Open a new session</action> with a terminal +shell. <keycombo action="simul">&Alt;&Ctrl;<keycap>N</keycap> +</keycombo> can also be used, as described in more detail below. +</para></listitem></varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu><guimenuitem>New +Window</guimenuitem></menuchoice></term> +<listitem><para><action>Open a new &konsole; window</action>. +</para></listitem></varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu><guimenuitem>New Linux +Console</guimenuitem></menuchoice></term> +<listitem><para><action>Open a new session emulating a text-only &Linux; +system</action>.</para> +<note><para>See the file <filename>README.linux.console</filename> in +the &konsole; source package for detailed information on how the &Linux; +console differs from a typical &UNIX; console. If this doesn't mean anything +to you, you almost certainly don't need to worry about it.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu><guimenuitem>New Midnight +Commander</guimenuitem></menuchoice></term> +<listitem><para><action>Open a new session</action> with the + <application>Midnight +Commander</application> file browser.</para> +<note><para>This menu entry will only be visible if Midnight Commander +(<command>mc</command>) is installed on your system. +</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice><guimenu>Session</guimenu> +<guimenuitem>New Root Midnight Commander</guimenuitem></menuchoice> +</term> +<listitem> +<para><action>Open a new session</action> with the <application>Midnight +Commander</application> file browser, as the <systemitem +class="username">root</systemitem> user.</para> + +<para>After being prompted for the <systemitem +class="username">root</systemitem> password, the <prompt>#</prompt> +prompt appears under the browser window, indicating that the user is +working with <systemitem class="username">root</systemitem> +privileges. Again, working as <systemitem +class="username">root</systemitem> is frequently necessary but care +should be taken to avoid accidental damage.</para> + +<note><para>This menu entry will only be visible if Midnight Commander +(<command>mc</command>) is installed on your system. +</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<menuchoice><guimenu>Session</guimenu> +<guimenuitem>New Root Shell</guimenuitem></menuchoice> +</term> +<listitem> +<para><action>Open a new session with a terminal shell</action>, as the +<systemitem class="username">root</systemitem> user.</para> + +<para>After being prompted for the <systemitem +class="username">root</systemitem> password, the <prompt>#</prompt> +prompt appears, indicating that the user is working with <systemitem +class="username">root</systemitem> privileges. This is frequently +necessary for installing new software and other system maintenance, but +care should be taken to avoid accidental damage.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu><guimenuitem>New +Screen Session</guimenuitem></menuchoice></term> +<listitem><para><action>Open a new session</action> with the + <application>Screen</application> virtual terminal manager. +See <userinput><command>man</command> <option>screen</option> +</userinput>for more information. +<note><para>This menu entry will only be visible if Screen +(<command>screen</command>) is installed on your system.</para></note> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu> +<guimenuitem>New Shell at Bookmark</guimenuitem></menuchoice></term> +<listitem><para><action>Start</action> a new terminal shell, in a folder +chosen from the bookmark list.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu> +<guimenuitem>Print Screen...</guimenuitem></menuchoice></term> +<listitem><para><action>Print</action> the current screen. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu> +<guimenuitem>Close Session</guimenuitem></menuchoice></term> +<listitem><para><action>Close</action> the current session. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Session</guimenu> +<guimenuitem>Quit</guimenuitem></menuchoice></term> +<listitem><para><action>Quit</action> &konsole;, closing all sessions and any +applications launched from them.</para></listitem> +</varlistentry> + +</variablelist> + +<para>You can also open a new session with a key shortcut. By default, +<keycombo action="simul">&Alt;&Ctrl;<keycap>N</keycap></keycombo> +is used. You can also define your own key shortcuts through the +<menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice> menu command.</para> + +<para>The list of available sessions will reflect what programs are +installed along with any user defined sessions. +The session list will be alphabetized for quick viewing.</para> + +<para>Finally, note that the session types can be modified, and new +types created, by using the configuration dialog, reached from the +<menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Configure Konsole...</guimenuitem></menuchoice> +menu entry.</para> + +</sect2> +<sect2 id="edit-menu"> +<title><guimenu>Edit</guimenu> Menu</title> +<variablelist> + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu> +<guimenuitem>Copy</guimenuitem></menuchoice></term> +<listitem><para><action>Copy the selected text to the clipboard</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo + action="simul">&Shift;<keycap>Insert</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Paste +</guimenuitem></menuchoice></term> +<listitem><para><action>Paste text from the clipboard at the cursor +location</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu> +<guisubmenu>Send Signal</guisubmenu></menuchoice></term> +<listitem><para><action>Send Signal - Send the specified signal to the shell +process, or other process, that was launched when the new session was +started</action>.</para><para>Currently available signals are:</para> + +<informaltable> +<tgroup cols="2"> +<tbody> +<row> +<entry><errorcode>STOP</errorcode></entry> +<entry>to stop process</entry> +</row> +<row> +<entry><errorcode>CONT</errorcode></entry> +<entry>continue if stopped</entry> +</row> +<row> +<entry><errorcode>HUP</errorcode></entry> +<entry>hangup detected on controlling terminal, or death of controlling +process</entry> +</row> +<row> +<entry><errorcode>INT</errorcode></entry> +<entry>interrupt from keyboard</entry> +</row> +<row> +<entry><errorcode>TERM</errorcode></entry> +<entry>termination signal</entry> +</row> +<row> +<entry><errorcode>KILL</errorcode></entry> +<entry>kill signal</entry> +</row> +<row> +<entry><errorcode>USR1</errorcode></entry> +<entry>user signal 1</entry> +</row> +<row> +<entry><errorcode>USR2</errorcode></entry> +<entry>user signal 2</entry> +</row> +</tbody> +</tgroup> +</informaltable> + +<para>Refer to your system manual pages for further details by giving the +command <userinput><command>man</command> <option>7 +signal</option></userinput>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo + action="simul">&Alt;&Ctrl;<keycap>U</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>ZModem Upload...</guimenuitem></menuchoice></term> +<listitem><para><action>Send a file via ZModem</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Clear Terminal</guimenuitem></menuchoice></term> +<listitem><para><action>Clear all text from the session window</action>.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Reset & Clear Terminal</guimenuitem></menuchoice></term> +<listitem><para><action>Reset and clear the session window</action>.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Find +in History...</guimenuitem></menuchoice></term> +<listitem><para><action>Find a word or string of text</action> in the current +history. Options allow case sensitive or backwards searches, and the use of regular +expressions in searches. Press the <guibutton>Edit</guibutton> button to use the &kde; +graphical editor to create a regular expression.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Find +Next</guimenuitem></menuchoice></term> +<listitem><para><action>Move to the next instance of the +text for which you are searching</action>.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Find +Previous</guimenuitem></menuchoice></term> +<listitem><para><action>Move to the previous instance of the +text for which you are searching</action>.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Save +History As...</guimenuitem></menuchoice></term> +<listitem><para><action>Save the current history</action> as a text + file.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Clear + History +</guimenuitem></menuchoice></term> +<listitem><para><action>Clear the history for the current + session</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Edit</guimenu><guimenuitem>Clear All + Histories +</guimenuitem></menuchoice></term> +<listitem><para><action>Clear the history +for all sessions</action>.</para></listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="view-menu"> +<title><guimenu>View</guimenu> Menu</title> +<variablelist> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Detach +Session</guimenuitem></menuchoice></term> +<listitem><para><action>Open the current session in a +separate window</action>. The name of the session is +displayed on the titlebar of the new window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo + action="simul">&Alt;&Ctrl;<keycap>S</keycap></keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Rename +Session...</guimenuitem></menuchoice></term> +<listitem><para><action>Open a dialog box allowing you to change +the name of the current session</action>. The name is displayed +on the session tab. <keycombo action="simul">&Alt;&Ctrl;<keycap>S</keycap> +</keycombo> can also be used.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Monitor for +Activity</guimenuitem></menuchoice></term> +<listitem><para><action>Flag the current session so it will show +an alert if activity occurs</action>. An icon of a lit light bulb will +appear in the session's tab. Use this to alert you if something +happens while you are working in another session. The time before an alert can be +modified in the &konsole; preferences.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Monitor for +Silence</guimenuitem></menuchoice></term> +<listitem><para><action>Flag the current session so it will show an alert +if no activity occurs for 10 seconds</action>. An icon of a dark light bulb will +appear in the session's tab. Use this to alert you if a task stops +while you are working in another session. The time before an alert can be +modified in the &konsole; preferences.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu><guimenuitem>Send +Input to All Sessions</guimenuitem></menuchoice></term> +<listitem><para><action>Flag the current session so any commands entered +into it will be sent to all sessions</action>. The session will have a small +icon in its tab to remind you to be careful of what you enter! +<userinput><command>rm</command> <parameter>-rf *</parameter></userinput>, +for instance, is probably not a good idea.</para></listitem> +</varlistentry> + + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo + action="simul">&Ctrl;&Shift;<keycap>Left</keycap></keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Move +Session Left</guimenuitem></menuchoice></term> +<listitem><para><action>Move the tab of the current session one tab to the +left</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo + action="simul">&Ctrl;&Shift;<keycap>Right</keycap></keycombo></shortcut> +<guimenu>View</guimenu><guimenuitem>Move +Session Right</guimenuitem></menuchoice></term> +<listitem><para><action>Move the tab of the current session one tab to the +right</action>.</para> +<para><keycombo +action="simul">&Shift; <keycap>Left</keycap></keycombo> and <keycombo +action="simul">&Shift; <keycap>Right</keycap></keycombo> can be also +be used to move between sessions.</para></listitem></varlistentry> + + +<varlistentry> +<term><menuchoice><guimenu>View</guimenu> +<guimenuitem>Session icons...</guimenuitem></menuchoice></term> +<listitem><para>At the bottom of the menu is a list of the available +sessions. Selecting one makes that session active.</para><para>You can also use + the <keycombo +action="simul">&Shift;<keycap>Left</keycap></keycombo>/<keycombo +action="simul">&Shift;<keycap>Right</keycap></keycombo> keys to +cycle through the available sessions.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="bookmarks-menu"> +<title><guimenu>Bookmarks</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Add Bookmark</guimenuitem></menuchoice></term> +<listitem><para><action>Add the current location</action> to the bookmark list.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>Edit Bookmarks</guimenuitem></menuchoice></term> +<listitem><para><action>Edit</action> the bookmark list.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Bookmarks</guimenu><guimenuitem>New Bookmark Folder...</guimenuitem></menuchoice></term> +<listitem><para><action>Add a new folder</action> to the bookmark list.</para></listitem> +</varlistentry> + +</variablelist> + +<para>The bookmark list is displayed at the bottom of the menu. Select a bookmark to change to +that location.</para> + +<note><para>You can use the bookmark editor to manually add URLs +like ssh://user@host or telnet://host to open remote connections.</para></note> + + +</sect2> + + + +<sect2 id="settings-menu"> +<title><guimenu>Settings</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Hide +Menubar</guimenuitem></menuchoice></term> +<listitem><para><action>Hide the menubar</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Tab Bar</guimenuitem></menuchoice></term> +<listitem><para><action>Control visibility/location of tabbar</action>: +<guimenuitem>Hide</guimenuitem>, <guimenuitem>Top</guimenuitem>, or +<guimenuitem>Bottom</guimenuitem>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guisubmenu>Scrollbar</guisubmenu></menuchoice></term> +<listitem><para><action>Control visibility/location of scrollbar</action>: +<guimenuitem>Hide</guimenuitem>, <guimenuitem>Left</guimenuitem>, or +<guimenuitem>Right</guimenuitem>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut><keycombo + action="simul">&Ctrl;&Shift;<keycap>F</keycap></keycombo></shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Full Screen Mode</guimenuitem></menuchoice></term> +<listitem><para><action>Toggle window between full-screen and normal +size</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Bell</guimenuitem></menuchoice></term> +<listitem><para><action>Set the bell</action>: +<guimenuitem>System Bell</guimenuitem>, +<guimenuitem>System Notification</guimenuitem>, +<guimenuitem>Visible Bell</guimenuitem>, or +<guimenuitem>None</guimenuitem>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guisubmenu>Font</guisubmenu></menuchoice></term> +<listitem><para><action>Set font size</action>: +<guimenuitem>Enlarge Font</guimenuitem> or +<guimenuitem>Shrink Font</guimenuitem>. +</para> +<para>Use the <guimenuitem>Select...</guimenuitem> option to pick any +combination of font, size and style.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Encoding</guimenuitem></menuchoice></term> +<listitem><para><action>Select character encoding</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Keyboard</guimenuitem></menuchoice></term> +<listitem><para><action>Choose desired keymapping</action>.</para> +<para>The list of these keymappings is taken from +<filename>$KDEDIR/share/apps/konsole/*.keytab</filename>. The file +<filename>$KDEDIR/share/apps/konsole/README.KeyTab</filename> +describes the <literal role="extension">*.keytab</literal> format in more detail. +Add to or modify these files to match your needs. The default keytab is taken from +<filename>$KDEDIR/share/apps/konsole/README.default.Keytab</filename>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guimenuitem>Schema</guimenuitem></menuchoice></term> +<listitem><para><action>Set colors of text and background</action>.</para> +<para>The list is taken from +<filename>$KDEDIR/share/apps/konsole/*.schema</filename>. The file +<filename>$KDEDIR/share/apps/konsole/README.Schema</filename> +describes the <literal role="extension">*.schema</literal> format in more detail. +Add to or modify these files to match your needs. You can also create custom +schemas through the preferences dialog at <menuchoice><guisubmenu>Settings</guisubmenu> +<guimenuitem>Configure &konsole;...</guimenuitem></menuchoice>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guisubmenu>Size</guisubmenu></menuchoice></term> +<listitem><para><action>Set size of text area (given in columns x +rows)</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu> +<guimenuitem>History...</guimenuitem></menuchoice></term> +<listitem><para><anchor id="configure-history"/><action>Open a dialog +where you can configure the history</action>. The +<guilabel>Enable</guilabel> check box toggles saving of lines that have +scrolled off the top of the window. You can enter the <guilabel>Number +of lines</guilabel> to remember in the text field, or use the spinner +buttons to increase or decrease the number in steps of 100 lines. The +<guibutton>Defaults</guibutton> button will reset the history to 1000 +lines. Selecting <guibutton>Set Unlimited</guibutton> will cause all history to be saved. +Press <guibutton>OK</guibutton> to save your changes, or +<guibutton>Cancel</guibutton> to close the dialog without saving your +settings.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Save +as Default</guimenuitem></menuchoice></term> +<listitem><para><action>Save the current settings as the new +default</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Save Sessions Profile...</guimenuitem></menuchoice></term> +<listitem><para><action>Save the current set of sessions</action> under a name you choose. +The profile can then be used by starting &konsole; from the command-line with the +<parameter>--profile</parameter> and the name of the profile.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Notifications...</guimenuitem></menuchoice></term> +<listitem><para><action>Customize notifications for &konsole;</action>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Shortcuts...</guimenuitem></menuchoice></term> +<listitem><para><action>Customize keyboard shortcuts for &konsole; commands</action>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +&konsole;...</guimenuitem></menuchoice></term> +<listitem><para><action>Open the &kcontrolcenter; module, allowing +many additional changes to &konsole;'s interface and behavior, including the creation +of custom schemas and modification of the available sessions</action>.</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="help-menu"> +<title><guimenu>Help</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><menuchoice><guimenu>Help</guimenu><guimenuitem>Konsole +Handbook</guimenuitem></menuchoice></term> +<listitem><para><action>Open the table of contents of this +document</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Help</guimenu> +<guimenuitem>Tip of the Day</guimenuitem></menuchoice></term> +<listitem><para><action>Display a helpful tip about the use of &konsole;. +</action>Check the <guilabel>Show on start</guilabel> box to display a tip +each time &konsole; is started.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><guimenu>Help</guimenu><guimenuitem>Report +Bug...</guimenuitem></menuchoice></term> +<listitem><para><action>Submit a bug report or a feature request</action> for +&konsole;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Help</guimenu><guimenuitem>About +Konsole</guimenuitem></menuchoice></term> +<listitem><para><action>Information about</action> &konsole;'s +author</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenu>Help</guimenu><guimenuitem>About +KDE</guimenuitem></menuchoice></term> +<listitem><para><action>Information about the &kde; +project</action></para></listitem> +</varlistentry> +</variablelist> + +</sect2> + +</sect1> + +<sect1 id="tabbar"> +<title>Tab Bar</title> + +<para>The tabbar allows multiple terminal sessions to be attached to a single &konsole; window.</para> + +<screenshot> +<screeninfo>Tabbar Image</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="tabbar.png" format="PNG"/> +</imageobject> +<textobject> +<phrase>Tabbar Image</phrase> +</textobject> +<caption><para>&konsole; with 4 terminal sessions open with the tabbar on the bottom.</para></caption> +</mediaobject> +</screenshot> + +<para>The <menuchoice><guimenu>Settings</guimenu><guimenuitem>Tab +Bar</guimenuitem></menuchoice> menu item allows the tabbar to be moved to +the <guimenuitem>Top</guimenuitem> or <guimenuitem>Bottom</guimenuitem>. +The tabbar can also be hidden by selecting <guimenuitem>Hide</guimenuitem>.</para> + +<para>On the left side of the tabbar is a button which allows for a multitude of actions. +<itemizedlist> +<listitem><para>Click on the button to start a new +standard session.</para></listitem> +<listitem><para>Clicking and holding on the button will popup +a list of sessions to select.</para></listitem> +<listitem><para>Right-clicking on the button (or any empty +space on the tabbar) will popup up a menu to set certain options: +<itemizedlist> + <listitem><para><guimenu>Tab Bar</guimenu>: + <guimenuitem>Hide</guimenuitem>, + <guimenuitem>Top</guimenuitem>, + <guimenuitem>Bottom</guimenuitem>.</para></listitem> +</itemizedlist> +<itemizedlist> + <listitem><para><guimenu>Tab Options</guimenu>: + <guimenuitem>Text & Icons</guimenuitem>, + <guimenuitem>Text Only</guimenuitem>, + <guimenuitem>Icons Only</guimenuitem>.</para></listitem> +</itemizedlist> +<itemizedlist> + <listitem><para><guimenuitem>Dynamic Hide</guimenuitem> + will hide the tabbar when there is only one session opened.</para> + </listitem> +</itemizedlist> +<itemizedlist> + <listitem><para><guimenuitem>Auto Resize Tabs</guimenuitem> + will automatically resize the tabs to the width of the tabbar.</para> + </listitem> +</itemizedlist> +</para></listitem> +</itemizedlist> +</para> + +<para>On the right side of the tabbar is a button that closes +the current session. This button will be disabled when there +is only one session running.</para> + +<para>Right-clicking on any tab will popup another menu: +<itemizedlist> +<listitem><para><guimenu>Detach Session</guimenu></para></listitem> +<listitem><para><guimenu>Rename Session...</guimenu></para></listitem> +<listitem><para><guimenu>Monitor for Activity</guimenu></para></listitem> +<listitem><para><guimenu>Monitor for Silence</guimenu></para></listitem> +<listitem><para><guimenu>Send Input to All Sessions</guimenu></para></listitem> +<listitem><para><guimenu>Select Tab Color...</guimenu></para></listitem> +<listitem><para><guimenu>Switch to Tab...</guimenu></para></listitem> +<listitem><para><guimenu>Close Session</guimenu></para></listitem> +</itemizedlist></para> + +</sect1> + +<sect1 id="command-line-options"> +<title>Command-line Options</title> + +<para>When &konsole; is started from the command-line, various options +can be specified to modify its behavior.</para> + +<variablelist> +<varlistentry> +<term><option>--help</option></term> +<listitem><para><action>List the various options</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>-e</option> <parameter>command</parameter></term> +<listitem><para><action>Execute</action> +<parameter>command</parameter> instead of the normal shell.</para> +<note><para>Any arguments after <parameter>command</parameter> will be passed to +<parameter>command</parameter>, not &konsole;.</para></note> +</listitem> +</varlistentry> + +<varlistentry> +<term><option>--keytab</option> <parameter>file</parameter></term> +<listitem><para><action>Start &konsole; using a specified .keytab +file</action> to customize key bindings.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--keytabs</option></term> +<listitem><para><action>List all of the available keytabs</action>. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--ls</option></term> +<listitem><para><action>Start with a login shell environment</action>. +What that does varies depending on your system, but generally it +means that files such as <filename>~/.profile</filename> or +<filename>~/.bash_profile</filename> will be read. (If that doesn't mean +anything to you, don't worry about it, but keep in the back of your mind +for when you realize you need it.)</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--name</option> <parameter>name</parameter></term> +<listitem><para><action>Set the name that appears in the +titlebar</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--noclose</option></term> +<listitem><para><action>Prevent &konsole; from closing</action> when an +<userinput><command>exit</command></userinput> +command is issued in the only session window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--noframe</option></term> +<listitem><para><action>Start &konsole; without a + frame</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--nohist</option></term> +<listitem><para><action>Disable the saving of lines</action> + that scroll off the top of the window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--nomenubar</option></term> +<listitem><para><action>Start &konsole; with +the menubar hidden</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--noresize</option></term> +<listitem><para><action>Disable the resizing</action> + of the terminal window.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--noscrollbar</option></term> +<listitem><para><action>Start &konsole; with +the scrollbar hidden</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--notabbar</option></term> +<listitem><para><action>Start &konsole; +with the tabbar hidden</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--noxft</option></term> +<listitem><para><action>Start &konsole; without Xft antialiasing</action>. +Antialiasing of a small font may be difficult to read.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--profile</option> <parameter>file</parameter></term> +<listitem><para><action>Start &konsole; using a saved set of sessions</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--profiles</option></term> +<listitem><para><action>List all of the available profiles. +</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--schema</option> <parameter>name</parameter> | <parameter>file</parameter></term> +<listitem><para><action>Start &konsole; using schema 'name' or specified in 'file'</action> to customize appearance.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--schemata</option></term> +<listitem><para><action>List all of the available schemata. +</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--script</option></term> +<listitem><para><action>Enable extended &DCOP; &Qt; functions. +</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><option>-T</option> <parameter>title</parameter></term> +<listitem><para><action>Set the window title</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--tn</option> <parameter>terminal</parameter></term> +<listitem><para><action>Sets the environment variable TERM to the specified +value</action>. Read <userinput><command>man</command> <option>xterm</option> +</userinput> for more information on TERM.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--type</option> <parameter>type</parameter></term> +<listitem><para><action>Start a session of the given type</action> + rather than the default.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--types</option></term> +<listitem><para><action>List all of the available session types. +</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--vt_sz</option> <parameter>CCxLL</parameter></term> +<listitem><para><action>Start a terminal window of CC Columns and LL +lines</action>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--workdir</option> <parameter>dir</parameter></term> +<listitem><para><action>Open with</action> +<parameter>dir</parameter> as the working folder.</para></listitem> +</varlistentry> + +</variablelist> + +<informalexample> +<para>Examples:</para> +<screen><prompt>%</prompt> <userinput><command>konsole</command> <option>--vt_sz</option> <parameter>90x25</parameter> <option>--nohist</option></userinput></screen> + +<para>Starts a &konsole; window with 90 columns and 25 rows, with no +history</para> + +<screen><prompt>%</prompt> <userinput><command>konsole</command> <option>--noclose</option> <option>-e</option> <parameter>echo_args</parameter> <parameter>Hello, thanks for using &konsole;!</parameter></userinput></screen> + +<para>Starts a &konsole; window with the text printed 'Hello, thanks for using &konsole;!' +</para> +<para>The <parameter>echo_args</parameter> is a simple Bash script: +<programlisting>#!/bin/bash +echo $*</programlisting> +</para> +</informalexample> + +<para>&konsole; also accepts generic &Qt; and &kde; options:</para> + +<variablelist> +<varlistentry> +<term><option>--help-qt</option></term> +<listitem><para><action>List &Qt;-specific options</action></para></listitem> +</varlistentry> +</variablelist> + +<caution><para>The following &Qt; options have no effect on &konsole;: +<informalexample> +<variablelist> + +<varlistentry> +<term><option>--fn</option>, <option>--font</option> +<parameter>fontname</parameter></term> +<listitem><para><action>Defines the application font</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--bg</option>, <option>--background</option> +<parameter>color</parameter></term> +<listitem><para><action>Sets the default background color</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--fg</option>, <option>--foreground</option> +<parameter>color</parameter></term> +<listitem><para><action>Sets the default foreground color</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><option>--btn</option>, <option>--button</option> +<parameter>color</parameter></term> +<listitem><para><action>Sets the default button color</action></para></listitem> +</varlistentry> + +</variablelist> + +</informalexample> +</para></caution> + +<variablelist> +<varlistentry> +<term><option>--help-kde</option></term> +<listitem><para><action>List &kde;-specific options</action></para></listitem> +</varlistentry> +<varlistentry> +<term><option>--help-all</option></term> +<listitem><para><action>List all options</action></para></listitem> +</varlistentry> +<varlistentry> +<term><option>--author</option></term> +<listitem><para><action>Show the authors' names</action></para></listitem> +</varlistentry> +<varlistentry> +<term><option>-v,--version</option></term> +<listitem><para><action>Show the version number</action></para></listitem> +</varlistentry> +<varlistentry> +<term><option>--license</option></term> +<listitem><para><action>Show license information</action></para></listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="dcop"> +<title>&DCOP;</title> + +<para>For an introduction to +&DCOP; and using <command>dcop</command> please look at +<ulink url="help:/khelpcenter/userguide/kde-diy.html#dcop">the User Guide entry on &DCOP;</ulink>. +</para> + +</sect1> + +</chapter> + +<chapter id="credits"> +<title>Credits and Copyright</title> + +<para>As of &kde; 3.4, &konsole; is maintained by &Kurt.Hindenburg; &Kurt.Hindenburg.mail;</para> + +<para>Previously, &konsole; was maintained by &Waldo.Bastian; &Waldo.Bastian.mail;</para> + +<para>The application &konsole; Copyright © 1997-2005 +&Lars.Doelle; &Lars.Doelle.mail;</para> + +<para>This document was written by &Jonathan.Singer; +&Jonathan.Singer.mail;</para> + +<para>This document was updated for &kde; 3.4 by +&Kurt.Hindenburg; &Kurt.Hindenburg.mail;</para> + +<para>Originally converted to DocBook <acronym>SGML</acronym> by +&Mike.McBride; and &Lauri.Watts;</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; +</chapter> + +<appendix id="porting"> +<title>&konsole; on non-&Linux; platforms</title> + +<para>Information on building &konsole; on platforms other than &Linux; +is available in the <filename>README.ports</filename> file in the +&konsole; source package. It provides a list of experts for certain +platforms (Tru64, &Solaris;, OpenBSD) and requests volunteers from other +&UNIX; platforms.</para> + +<para>For more infomation please visit these websites:</para> +<itemizedlist> +<listitem><para><ulink url="http://freebsd.kde.org/">&kde; on +FreeBSD</ulink></para></listitem> +<listitem><para><ulink url="http://solaris.kde.org/">&kde; on &Solaris;</ulink></para></listitem> +</itemizedlist> + +</appendix> + +&documentation.index; + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +sgml-general-insert-case: lower +End: +--> + + diff --git a/doc/konsole/konsole.png b/doc/konsole/konsole.png Binary files differnew file mode 100644 index 000000000..8ec9a1b4e --- /dev/null +++ b/doc/konsole/konsole.png diff --git a/doc/konsole/tabbar.png b/doc/konsole/tabbar.png Binary files differnew file mode 100644 index 000000000..fb0fb0dbe --- /dev/null +++ b/doc/konsole/tabbar.png diff --git a/doc/kpager/Makefile.am b/doc/kpager/Makefile.am new file mode 100644 index 000000000..e786da562 --- /dev/null +++ b/doc/kpager/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = AUTO diff --git a/doc/kpager/index.docbook b/doc/kpager/index.docbook new file mode 100644 index 000000000..e2779abf5 --- /dev/null +++ b/doc/kpager/index.docbook @@ -0,0 +1,381 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kpager;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kpager; Handbook</title> + +<authorgroup> +<author>&Dirk.Doerflinger; &Dirk.Doerflinger.mail;</author> + +<othercredit role="developer"> +&Antonio.Larrosa.Jimenez; &Antonio.Larrosa.Jimenez.mail; +<!-- <contrib>Developer</contrib> --> +</othercredit> + +<othercredit role="developer"> +&Matthias.Elter; +&Matthias.Elter.mail; +<!-- <contrib>Developer</contrib> --> +</othercredit> + +<othercredit role="developer"> +&Matthias.Ettrich; &Matthias.Ettrich.mail; +<!-- <contrib>Developer</contrib> --> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year> +<holder>&Dirk.Doerflinger;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2001-01-28</date> +<releaseinfo>0.02.00</releaseinfo> + +<abstract> +<para> +&kpager; gives you a thumbnail view of all virtual desktops. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>pager</keyword> +<keyword>kpager</keyword> +<keyword>desktop</keyword> +<keyword>overview</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kpager; gives you a thumbnail sketch of all your desktops. It is a handy +tool to let you see, resize or close windows on any desktop and move windows +around within or between desktops. </para> + +</chapter> + + +<chapter id="using-kpager"> +<title>Using &kpager;</title> + +<screenshot> +<screeninfo>Here's a screenshot of &kpager;</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="screenshot.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> + +<sect1 id="kpager-features"> +<title>More &kpager; features</title> + +<para>&kpager; can show all virtual desktops and the applications within them. +It +can be used to chose an application or even to move applications within virtual +desktops or to others.</para> + +</sect1> +</chapter> + +<chapter id="commands"> +<title>Command Reference</title> + +<sect1 id="kpager-mainwindow"> +<title>The main &kpager; window</title> + +<sect2> +<title>Using the mouse</title> + +<para>In &kpager; you can activate applications by clicking them with the +<mousebutton>left</mousebutton> button.</para> + +<para>The <mousebutton>middle</mousebutton> button of the mouse can be used for +dragging applications within &kpager;. Applications can either be moved within a +virtual desktop or to another one.</para> + +<para>Clicking the <mousebutton>right</mousebutton> mouse button anywhere in +&kpager; will open a context menu.</para> + +</sect2> + +<sect2> +<title>The Context Menu</title> + +<para>The context menu depends on where the <mousebutton>right</mousebutton> +mouse button is clicked: If it is clicked on the empty background of &kpager;, +it +only has two items: <guimenuitem>Configure KPager</guimenuitem> and +<guimenuitem>Quit</guimenuitem>. Otherwise, if clicked on a window, there are +also the name and the icon of the application, and +<guimenuitem>Minimize</guimenuitem>, <guimenuitem>Maximize</guimenuitem>, +<guimenuitem>To Desktop</guimenuitem> and <guimenuitem>Close</guimenuitem> are +displayed. See below for a detailed description of the menu items.</para> + +<variablelist> +<varlistentry> +<term><menuchoice> +<guimenuitem>Maximize</guimenuitem> +</menuchoice></term> +<listitem><para><action>Maximizes the application window to the whole +desktop. This item only appears if right clicked on an application +window.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Minimize</guimenuitem> +</menuchoice></term> +<listitem><para><action>Iconifies the application. This item only appears if +right clicked on an application window.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>To Desktop</guimenuitem> +</menuchoice></term> +<listitem><para><action>Sends the application window to the chosen virtual +desktop. This item only appears if right clicked on an application +window.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Close</guimenuitem> +</menuchoice></term> +<listitem><para><action>Closes the clicked application. This item only appears +if right clicked on an application window.</action></para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Configure Pager</guimenuitem> +</menuchoice></term> +<listitem><para><action>Opens</action> the <link +linkend="kpager-settings">settings +dialog</link>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para><action>Quits</action> &kpager;.</para></listitem> +</varlistentry> +</variablelist> + + +</sect2> +</sect1> + +<sect1 id="kpager-settings"> +<title>The Settings Dialog</title> + +<screenshot> +<screeninfo>Here's a screenshot of the settings dialog</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="settings.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Screenshot</phrase> + </textobject> + </mediaobject> +</screenshot> + +<para>In the settings dialog you will find five check boxes and two groups of +radio buttons.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Enable Window Dragging</guilabel></term> +<listitem><para>If this box is checked, you can drag windows inside of &kpager; +with the &MMB;. +Windows can be dragged over the desktop or even to another +desktop.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Name</guilabel></term> +<listitem><para>If this box is checked, the names of the desktops are shown in +the main view of &kpager;.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Number</guilabel></term> +<listitem><para>If this box is checked, the numbers of the desktops are shown in +the main view of &kpager;. If it is checked together with the <guilabel>Show +Name</guilabel> box, the name is displayed with ordinals, <abbrev>e.g.</abbrev> +<guilabel>1. Desktop</guilabel>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Background</guilabel></term> +<listitem><para>If this box is checked, the wallpaper of each desktop - if set - +will be shown as backgrounds in &kpager;, too.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show Windows</guilabel></term> +<listitem><para>If this box is checked, the applications on the desktops are +shown in &kpager; as small views. Otherwise, &kpager; will remain empty, just +for +choosing the virtual desktops.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Type of Window</guilabel></term> +<listitem><para>This group of radio buttons sets the kind of view for the +application window views. <guilabel>Plain</guilabel> will show just empty +rectangles with the proportions of the application window, +<guilabel>Icon</guilabel> will show them with their standard icon and +<guilabel>Pixmap</guilabel> with a small view of the contents of the application +window. Note that using the pixmap mode is only recommended for very fast +machines.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Layout</guilabel></term> +<listitem><para>In this group the layout of the &kpager; main view can be +set. <guilabel>Classical</guilabel> will show &kpager; in a 2xn grid like pager +applications in some other window managers, <guilabel>Horizontal</guilabel> will +show the virtual desktops in a horizontal view and <guilabel>Vertical</guilabel> +in a vertical row, which may perfectly fit on the side of the +desktop.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +<qandaset id="faq-questions"> +<qandaentry> +<question> +<para>Why could I need &kpager;?</para> +</question> +<answer><para>&kpager; can be used as an alternative to the pager applet in the +panel. It has the advantage of being resizeable and within this able to show +icon or pixmap views of the running applications, move the windows across +desktops and run outside of the panel.</para></answer> +</qandaentry> +<qandaentry> +<question> +<para>How can I change the behavior of &kpager;?</para> +</question> +<answer><para>Clicking the <mousebutton>right</mousebutton> mouse button +anywhere within &kpager; lets you chose <guilabel>Configure</guilabel> from the +context menu for displaying the <link linkend="kpager-settings">settings +dialog</link></para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>Windows are transparent by default, how do I turn this off?</para> +</question> +<answer> +<para>Currently, you cannot turn that option off within the config dialog, but +you can do it manually like this:</para> + +<para>Open the file <filename>$KDEHOME/share/config/kpagerrc</filename> with any +text editor like &kedit; or <application>vi</application>. If you have no +rights to write that file, you may need to do it as root or contact your system +administrator. In this file you will have to add a new key with the name +<userinput>windowTransparentMode</userinput> with a number as value. Values +are:</para> + +<simplelist> +<member>0 - No transparent windows at all.</member> +<member>1 - Only maximized windows are transparent.</member> +<member>2 - all windows are transparent (default).</member> +</simplelist> + +</answer> +</qandaentry> +</qandaset> +</chapter> + +<chapter id="credits"> + + +<title>Credits and License</title> + +<para> +&kpager; +</para> + +<para> +Program copyright 2000 Antonio Larrosa <email>[email protected]</email> +</para> + +<para> +Documentation copyright 2000 by Dirk Doerflinger +<email>[email protected]</email> +</para> + +&underFDL; +&underGPL; + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="getting-kpager"> +<title>How to obtain &kpager;</title> + +&install.intro.documentation; + +</sect1> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>As &kpager; is part of the &package; package, you will just need an +installation of the main &kde; packages.</para> + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</sect1> + +</appendix> + +&documentation.index; + +</book> + +<!-- +Local Variables: +mode: sgml +sgml-minimize-attributes: nil +sgml-general-insert-case: lower +End: +--> + diff --git a/doc/kpager/screenshot.png b/doc/kpager/screenshot.png Binary files differnew file mode 100644 index 000000000..ef895c128 --- /dev/null +++ b/doc/kpager/screenshot.png diff --git a/doc/kpager/settings.png b/doc/kpager/settings.png Binary files differnew file mode 100644 index 000000000..6aab9773f --- /dev/null +++ b/doc/kpager/settings.png diff --git a/doc/ksplashml/Makefile.am b/doc/ksplashml/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/ksplashml/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/ksplashml/index.docbook b/doc/ksplashml/index.docbook new file mode 100644 index 000000000..b64c2816c --- /dev/null +++ b/doc/ksplashml/index.docbook @@ -0,0 +1,1354 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&ksplash;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &ksplash; Handbook</title> + +<authorgroup> +<author> +&Teemu.Rytilahti; &Teemu.Rytilahti.mail; +</author> + +<othercredit role="developer"> +&Brian.C.Ledbetter; &Brian.C.Ledbetter.mail; +</othercredit> + +<othercredit role="developer"> +&Ravikiran.Rajagopal; &Ravikiran.Rajagopal.mail; +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2003</year> +<holder>Teemu Rytilahti</holder> +</copyright> +<copyright> +<year>2003-04</year> +<holder>Ravikiran Rajagopal</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2003-01-10</date> +<releaseinfo>1.01.00</releaseinfo> + +<abstract> +<para> +&ksplash; is a nice splash screen that shows the progress of an +application that is loading.</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kdebase</keyword> +<keyword>ksplash</keyword> +<keyword>ksplashml</keyword> +<keyword>splashscreen</keyword> +<keyword>eye candy</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&ksplash; is a nice splash screen that shows the progress of an +application that is loading. Please report any problems or feature +requests to the &kde; mailing lists. The principal features of +&ksplash;: +</para> +<simplelist> +<member>Themeable</member> +<member>Uses plugins for complete customizability</member> +<member>Can be used by any application that uses DCOP</member> +</simplelist> + +<para> +This handbook will show you how to create themes for use with plugins +that are already available. If none of the plugins available satisfy +your tastes, you can learn how to customize the appearance of +&ksplash; completely by writing a plugin in C++. +</para> +</chapter> + +<chapter id="using-themes"> +<title>Using themes</title> + +<para>To use themes from <ulink +url="http://www.kde-look.org">KDE-Look</ulink>, extract them to +<filename>~/.kde/share/apps/ksplash/Themes/</filename> for a single user, or +to +<filename>$<envar>KDEDIR</envar>/share/apps/ksplash/Themes/</filename> +to make them available to all users of your system.</para> + +<para>You can also use the <guilabel>Splash Screen</guilabel> module under +<guilabel>Appearance</guilabel> in the &kde; control center to do this +automatically.</para> + +<sect1 id="using-kcontrol-module"> +<title>Using the &kcontrol; Module</title> + +<para>This module allows you to install, test and remove &ksplash; +themes.</para> + +<para>Down the side of the module is a list of currently available +&ksplash; themes. As you select one, a preview will display in the main +part of the window. When you have selected the one you wish to use, press +<guibutton>OK</guibutton> or <guibutton>Apply</guibutton>. Press +<guibutton>Cancel</guibutton> to exit the module without making changes, and +<guibutton>Defaults</guibutton> to restore the system default splash +screen.</para> + +<para>To install new modules, press <guibutton>Add...</guibutton>, and +find the theme on your computer. You do not have to unpack theme files, you +can safely select the compressed theme file. Installing a theme does not +make it the theme in use until you select it in the list and press either +<guibutton>OK</guibutton> or <guibutton>Apply</guibutton>.</para> + +<para>Although you can see a preview of the splash screen, you may like to +see how it looks in real use, for instance to see what the animation looks +like. You can test themes by selecting them in the list and clicking the +<guibutton>Test</guibutton> button.</para> + +<para>You can also remove themes you no longer wish to use, by selecting +them and pressing the <guibutton>Remove</guibutton> button. Note that your +user account may not have the right to remove themes installed system-wide. +It is also recommended you do not uninstall the <guilabel>Default</guilabel> +splash screen.</para> + +</sect1> + +</chapter> + +<chapter id="themes"> +<title>How to make themes for &ksplash;</title> +<sect1 id="themes-general"> +<title>General</title> +<para>Making your own themes for &ksplash; is easy. After you have +finished your themes you can post them on the <ulink +url="http://www.kde-look.org">KDE-Look</ulink> so that others can use +it.</para> + +<sect2 id="theme-syntax"> +<title>Identifying your theme</title> + +<para>Let us create a theme called <literal>MyCoolTheme</literal>. For +the theme to be recognized by &ksplash;, it should be stored in a +folder called <filename class="directory">MyCoolTheme</filename> +under <filename +class="directory">~/.kde/apps/ksplash/Themes/</filename>. It should +have a file called <filename>Theme.rc</filename>, containing the +settings of the theme. You can specify large numbers of special things +to theme, change the plugin engine to use, and so on. You do not have +to use all the settings available; usually, the settings have an +acceptable default value. The basic syntax for entries in the +<filename>Theme.rc</filename> file is <literal>[option] = +[value]</literal> You can find the definitions of the various options +in the following sections.</para> + +<example> +<title>Simple <filename>Theme.rc</filename> file</title> +<programlisting> +[KSplash Theme: MyCoolTheme] +Name = MyCoolTheme +Description = A nice theme using XpLike engine +Version = 1.0 +Author = Real Name <[email protected]> +## Use the XpLike engine for this theme. +Engine = XpLike +Show Icon = false +Welcome Text = Loading KDE +</programlisting> +</example> + +<para>After specifying the name, the description and the author of the +theme, you should first choose a theme engine (also known as a +plugin). Then, you can customize various features of the theme engine +by assigning key-value pairs as in the example file above.</para> + +<important> +<para>Ensure that the name of the directory that contains the theme files +(<filename class="directory">~/.kde/apps/ksplash/Themes/MyCoolTheme</filename> +in this example) and the identifier (<literal>[KSplash Theme: +MyCoolTheme]</literal> in this example) of the theme in the +<filename>Theme.rc</filename> file are identical. Otherwise, &ksplash; will not +recognize the theme.</para> +</important> + +</sect2> + +<sect2 id="theme-files"> +<title>Background files</title> + +<para>When &ksplash; starts, it tries to find a background image for +your current screen resolution, if the theme engine uses one. The +background image file should be named in the following format: +<filename>Background-<replaceable>WWWxHHH</replaceable>.png</filename>.</para> + +<para>For example, you might use a file called +<filename>Background-1024x768</filename>. If the background image for +your screen resolution cannot be found, it tries to resize the +original <filename>Background.png</filename> or the file specified in +<filename>Theme.rc</filename> to suit the current resolution. Resizing +on-the-fly will certainly take some time, so you should provide +background images for at least the following sizes: 1280x1024, 1024x768 +and 800x600.</para> +</sect2> +</sect1> + +<sect1 id="theme-engines"> +<title>Options for Theme Engines</title> + +<sect2 id="default-themes"> +<title>Default Theme</title> +<table> +<title>Default Theme Options</title> +<tgroup cols="3"> +<tbody> +<row> +<entry>Name</entry> +<entry>Argument</entry> +<entry>Explanation</entry> +</row> +<!-- Statusbar --> +<row> +<entry>Always Show Progress</entry> +<entry>[true/false]</entry> +<entry>Indicates whether loading progress should be shown. Default is +true.</entry> +</row> +<row> +<entry>Label Foreground</entry> +<entry>[color]</entry> +<entry>Determines what color to use for the statusbar text. Default is #FFFFFF (white).</entry> +</row> +<!-- Misc. things --> +<row> +<entry>Icons Flashing</entry> +<entry>[true/false]</entry> +<entry>Indicates whether icons should <quote>flash</quote>. Default is true.</entry> +</row> +</tbody> +</tgroup> +</table> +</sect2> + +<sect2 id="standard-themes"> +<title>Standard Theme</title> +<table> +<title>Standard Theme Options</title> +<tgroup cols="3"> +<tbody> +<row> +<entry>Name</entry> +<entry>Argument</entry> +<entry>Explanation</entry> +</row> +<!-- Statusbar --> +<row> +<entry>Statusbar Position</entry> +<entry>[top/bottom]</entry> +<entry>Toggles the position of the statusbar on the screen. Default is +bottom.</entry> +</row> +<row> +<entry>Statusbar Visible</entry> +<entry>[true/false]</entry> +<entry>Indicates whether the statusbar should be shown. Default is true.</entry> +</row> +<row> +<entry>Progress Visible</entry> +<entry>[true/false]</entry> +<entry>Indicates whether loading progress should be shown. Default is +true.</entry> +</row> +<!-- Fonts --> +<row> +<entry>Statusbar Font</entry> +<entry>[fontname]</entry> +<entry>The font used in statusbar. Default is Helvetica.</entry> +</row> +<row> +<entry>Statusbar Font Size</entry> +<entry>[size]</entry> +<entry>The font size for the statusbar. Default is 16.</entry> +</row> +<row> +<entry>Statusbar Font Bold</entry> +<entry>[true/false]</entry> +<entry>Indicates whether the statusbar font should be bold. Default is +true.</entry> +</row> +<row> +<entry>Statusbar Font Italic</entry> +<entry>[true/false]</entry> +<entry>Indicates whether the statusbar font should be italic. Default is +false.</entry> +</row> +<!-- Misc. things --> +<row> +<entry>Statusbar Foreground</entry> +<entry>[color]</entry> +<entry>The foreground color of statusbar. Default is white.</entry> +</row> +<row> +<entry>Statusbar Background</entry> +<entry>[color]</entry> +<entry>The background color of statusbar. Default is black.</entry> +</row> +<row> +<entry>Statusbar Icon</entry> +<entry>[true/false]</entry> +<entry>Indicates whether the statusbar should have an icon.</entry> +</row> +<row> +<entry>Icons Visible</entry> +<entry>[true/false]</entry> +<entry>Indicates whether icons should be visible. Default is true.</entry> +</row> +<row> +<entry>Icons Jumping</entry> +<entry>[true/false]</entry> +<entry>Indicates whether icons should be jumping. Default is true.</entry> +</row> +<row> +<entry>Icon Position</entry> +<entry>[0-3,10-13]</entry> +<entry>Position where the icons are shown. Default is bottom-left.</entry> +</row> +<row> +<entry>Splash Screen</entry> +<entry>[name]</entry> +<entry>Changes the splash screen image that is shown.</entry> +</row> +</tbody> +</tgroup> +</table> +</sect2> + +<sect2 id="redmond-themes"> +<title>Redmond theme</title> +<table> +<title>Redmond theme options</title> +<tgroup cols="3"> +<tbody> +<row> +<entry>Name</entry> +<entry>Argument</entry> +<entry>Explanation</entry> +</row> +<!-- Main elements --> +<row> +<entry>Background Image</entry> +<entry>[filename]</entry> +<entry>User defined background image to use.</entry> +</row> +<row> +<entry>User Icon</entry> +<entry>[Iconname]</entry> +<entry>Name of standard icon to show for user. Default is +<constant>go</constant>.</entry> +</row> +<row> +<entry>Welcome Text</entry> +<entry>[text]</entry> +<entry>Text shown in splash screen. Default is "Welcome".</entry> +</row> +<row> +<entry>Username Text</entry> +<entry>[text]</entry> +<entry>Text shown instead of user's real name.</entry> +</row> +<!-- Positioning elements --> +<row> +<entry>Welcome Text Position</entry> +<entry>[x,y]</entry> +<entry>Position on the screen where the Welcome Text is shown.</entry> +</row> +<row> +<entry>Username Text Position</entry> +<entry>[x,y]</entry> +<entry>Position on the screen where the username is shown.</entry> +</row> +<row> +<entry>Action Text Position</entry> +<entry>[x,y]</entry> +<entry>Position on the screen where the current action is shown.</entry> +</row> +<row> +<entry>Icon Position</entry> +<entry>[x,y]</entry> +<entry>Position on the screen where the user icon is shown.</entry> +</row> +<!-- Show to show.. --> +<row> +<entry>Show Welcome Text</entry> +<entry>[true/false]</entry> +<entry>Toggles showing of welcome text. Default is true.</entry> +</row> +<row> +<entry>Show Welcome Shadow</entry> +<entry>[true/false]</entry> +<entry>Toggles showing of welcome text's shadow. Default is true.</entry> +</row> +<row> +<entry>Show Username</entry> +<entry>[true/false]</entry> +<entry>Toggles showing of username. Default is true.</entry> +</row> +<row> +<entry>Show Action</entry> +<entry>[true/false]</entry> +<entry>Toggles showing of action currently being performed. Default is +true.</entry> +</row> +<row> +<entry>Show Icon</entry> +<entry>[true/false]</entry> +<entry>Indicates whether icon should be shown. Default is true</entry> +</row> +<row> +<entry>Use KDM User Icon</entry> +<entry>[true/false]</entry> +<entry>Show user's login icon. Default is true.</entry> +</row> +</tbody> +</tgroup> +</table> +</sect2> + +<sect2 id="macx-themes"> +<title>MacX Theme</title> +<table> +<title>MacX Theme Options</title> +<tgroup cols="3"> +<tbody> +<row> +<entry>Name</entry> +<entry>Argument</entry> +<entry>Explanation</entry> +</row> +<row> +<entry>Icon Size Minimum</entry> +<entry>[size]</entry> +<entry>Assign the minimum size for icons. Default is 16.</entry> +</row> +<row> +<entry>Icon Size Maximum</entry> +<entry>[size]</entry> +<entry>Assign the maximum size for icons. Default is 64.</entry> +</row> +<row> +<entry>Optimized Icon Rendering</entry> +<entry>[true/false]</entry> +<entry>Optimize icon rendering. Default is true.</entry> +</row> +<row> +<entry>Progress Bar Visible</entry> +<entry>[true/false]</entry> +<entry>Default is true.</entry> +</row> +<row> +<entry>Progress Bar Position</entry> +<entry>[top/bottom]</entry> +<entry>Toggles whether statusbar should be in bottom or top. Default is +bottom.</entry> +</row> +<row> +<entry>Icons Jumping</entry> +<entry>[true/false]</entry> +<entry>Indicates whether icons should be jumping. Default is false.</entry> +</row> +</tbody> +</tgroup> +</table> +</sect2> + +<sect2 id="mac-classic-themes"> +<title>MacClassic Theme</title> +<table> +<title>MacClassic Theme Options</title> +<tgroup cols="3"> +<tbody> +<row> +<entry>Name</entry> +<entry>Argument</entry> +<entry>Explanation</entry> +</row> +<row> +<entry>Icon Position</entry> +<entry>[0-3,10-13]</entry> +<entry>Position of the icons on the screen. Default is bottom left.</entry> +</row> +<row> +<entry>Icons Jumping</entry> +<entry>[true/false]</entry> +<entry>Indicates whether icons should be jumping. Default is false.</entry> +</row> +<row> +<entry>Icons Visible</entry> +<entry>[true/false]</entry> +<entry>Indicates whether icons should be visible. Default is true.</entry> +</row> +<row> +<entry>Splash Screen</entry> +<entry>[name]</entry> +<entry>Changes the splash screen image that is shown.</entry> +</row> +</tbody> +</tgroup> +</table> +</sect2> + +<sect2 id="themes-2k"> +<title>2k theme</title> +<table> +<title>2k theme options</title> +<tgroup cols="3"> +<tbody> +<row> +<entry>Name</entry> +<entry>Argument</entry> +<entry>Explanation</entry> +</row> +<row> +<entry>Title Background Color</entry> +<entry>[color]</entry> +<entry>The background color of title. Default is dark blue.</entry> +</row> +<row> +<entry>Title Foreground Color</entry> +<entry>[color]</entry> +<entry>The foreground color of title. Default is white.</entry> +</row> +<row> +<entry>Status Text Color</entry> +<entry>[color]</entry> +<entry>The color of status texts. Default is the same as Title Background +Color.</entry> +</row> +<row> +<entry>Rotator Color 1</entry> +<entry>[color]</entry> +<entry>Defines the color of rotator 1. Default is dark blue.</entry> +</row> +<row> +<entry>Rotator Color 2</entry> +<entry>[color]</entry> +<entry>Defines the color of rotator 2. Default is cyan.</entry> +</row> +<row> +<entry>Rotator Speed</entry> +<entry>[value]</entry> +<entry>Defines the speed of the rotator. Default is 30.</entry> +</row> +<row> +<entry>Window Title</entry> +<entry>[text]</entry> +<entry>Specifies the title text of the window.</entry> +</row> +<row> +<entry>Logo File</entry> +<entry>[filename]</entry> +<entry>Defines the logo used.</entry> +</row> +</tbody> +</tgroup> +</table> +</sect2> +</sect1> +</chapter> + +<chapter id="from-other-applications"> +<title>Using &ksplash; From Within Your Own Application</title> + +<para> In this chapter, we describe a simple method for using +&ksplash; as the splash screen for your &kde; application. If you do +not develop applications for &kde;, you can skip this chapter.</para> + +<sect1 id="basic-other-reqs"> +<title>Basic Requirements</title> + +<para> Your &kde; application must be &DCOP;-aware. &DCOP; is the &kde; +technology used to communicate between applications. If you use the +standard <ulink url="http://developer.kde.org">&kde; application +framework</ulink>, this is taken care of automatically. For +information about &DCOP; and related &kde; technologies, please visit +the <ulink url="http://developer.kde.org">&kde; developers' +corner</ulink>.</para> +</sect1> + +<sect1 id="other-using"> +<title>Starting &ksplash;</title> + +<para>Before your application starts its computation intensive work, +or before it starts loading plugins, &etc;, invoke &ksplash; as +follows:</para> + +<programlisting> +DCOPClient *c = kapp->dcopClient(); +QString error; +QCString KSplashName; +int pid = 0; +QStringList args; +args << "--theme=MyCoolTheme" << "--managed"; +if (kapp->startServiceByDesktopName("ksplash", args, &error, +&KSplashName, &pid)) +{ + KMessageBox::sorry(0, error, "Unable to invoke KSplash"); + // Some error processing here. +} +</programlisting> + +<para>We will assume that there is only one instance of &ksplash; +running. Other cases are slightly more complex. Please see the &DCOP; +documentation for further details.</para> +</sect1> + +<sect1 id="show-messages"> +<title>Showing messages</title> + +<para>Before you show any messages, you need to set up the number of +steps you will show. For example, the &kde; startup procedure uses 7 +steps.</para> + +<programlisting> + QByteArray data; + QDataStream arg(data,IO_WriteOnly); + arg << someNumber; + if (!(c->send(KSplashName, "KSplashIface", "setStartupItemCount(int)", +data)) + // Some error processing here. +</programlisting> + +<para>Whenever you want to display a message with or without an icon, use</para> + +<programlisting> + arg << QString("iconName") << QString("programName") << +QString("Some description"); + if (!(c->send(KSplashName, "KSplashIface", +"programStarted(QString,QString,QString)", data)) + { + // Some error processing here. + } +</programlisting> + +<para> Each time you call <constant>programStarted</constant>, the +steps completed is incremented. When your program has finished its +startup, do the following to make the splash screen go away:</para> + +<programlisting> + if (!(c->send(KSplashName, "KSplashIface", "startupComplete()", data)) + { + // Some error processing here. + } +</programlisting> + +<para>That's it! You don't need anything more to take advantage of all +that &ksplash; has to offer you.</para> + +</sect1> +</chapter> + +<!-- FIXME: Better to leave this out until it's written, or the translators --> +<!-- will have to still translate it ... --> + +<chapter id="wrplugins"> +<title>Writing new &ksplash; plugins</title> + +<para>Writing new &ksplash; plugins is not difficult. In this chapter, we will +write +a simple plugin that will emulate the splash screen of a well known operating +system. This +tutorial assumes that you know the basics of C++, and a little bit of KDE/Qt +programming.</para> + +<sect1 id="basic-requirements"> +<title>Basic Requirements</title> +<para> +We will create a plugin called <literal>2k</literal>. The plugin name is used in +various +places, and is important that you consistently use it so that the plugin is +recognized by +&ksplash;. &ksplash; plugins are actually dynamically loadable libraries with +the following +naming convention: +</para> +<simplelist> +<member>The library should be named as +<filename>ksplash+lowercasethemename</filename>. For our +theme, it will be <filename>ksplash2k</filename>.</member> +<member>It should have a corresponding desktop file which is named as +<filename>ksplash+lowercasethemename.desktop</filename>. For our theme, it will +be +<filename>ksplash2k.desktop</filename>. </member> +<member>Finally, the object that is returned by the library should be a class +which is named +<literal>Theme+themename</literal>. For our example, it will be +<literal>Theme2k</literal>.</member> +</simplelist> +<para>Do not worry about it if you don't understand all of the above. We will +consider each +of those points in detail later. The other very important detail is that the +plugin class +should be derived from <literal>ThemeEngine</literal>. +</para> +</sect1> +<sect1 id="skeleton"> +<title>Building the skeleton framework</title> +<para>We will use the &kde; application framework which will take care of +building the plugin +and will provide us with platform independence without any work on our part. To +do that, +make sure you have the <filename>kdesdk</filename> package installed. Run the +command +<literal>kapptemplate</literal> to produce an application named "2k". It will +create a +toplevel folder which contains generic files such as AUTHORS, &etc;. We are most +interested +in the subfolder called <filename class="directory">2k</filename>. Go into that +subfolder +and delete all the files there. Now we have the skeleton we require. +</para> +<para> +The next step is to create a <filename>.desktop</filename> file which, when +installed, will +tell &ksplash; that our plugin is available. Consistent with the naming +conventions laid out +in <link linkend="basic-requirements">the preceding section</link>, +create a file called +<filename>ksplash2k.desktop</filename> in that folder. It should contain the +following lines: +</para> +<programlisting> +<literal> +[Desktop Entry] +Encoding=UTF-8 +Type=Service +Comment=KSplash Plugin +Name=KSplash2k +ServiceTypes=KSplash/Plugin +X-KDE-Library=ksplash2k +X-KSplash-Default=true +X-KSplash-PluginName=2k +X-KSplash-ObjectName=Theme2k +</literal> +</programlisting> +<para> +The <literal>Encoding</literal>, <literal>Type</literal>, +<literal>Comment</literal> and +<literal>ServiceTypes</literal> are the same for all plugins. The plugin name +and the library +name follow the conventions noted earlier. The entry +<literal>X-KSplash-Default</literal> takes +a boolean value which determines whether it is shown in the control panel +configuration +module by default. Except for some very rare cases, it should be +<constant>true</constant>. +</para> +</sect1> +<sect1 id="headerfile"> +<title>Declaration of plugin class</title> +<para>Now that we have the preliminary work done, let us get into the actual fun +part - creating +a class that will provide the behavior we want. While we are free to make this +class do +almost anything we want it to do, there are a few restrictions.</para> +<orderedlist> +<listitem><para>Plugin classes must inherit the <constant>ThemeEngine</constant> +class.</para></listitem> +<listitem><para>Plugin classes must be named according to the rule: +<classname>Theme+PluginName</classname>.</para></listitem> +<listitem><para>Plugin classes should provide a <literal>static</literal> +function called <function>names</function> +that returns a list of names by which it can be invoked.</para></listitem> +<listitem><para>If the plugin can be configured in the control center module, it +should provide a +<literal>ThemeEngineConfig</literal>-based class for the +configuration.</para></listitem> +<listitem><para>Plugin classes must override at least one of the virtual +functions <function>slotSetText</function>, +<function>slotSetPixmap</function>, <function>slotUpdateProgress</function> and +<function>slotUpdateSteps</function> to make it usable.</para></listitem> +<listitem><para>The constructor should take the form +<literal>ThemeEngine( QWidget *parent, const char *name, const QStringList +&args )</literal> +so that it can be used with +<classname>KGenericFactory</classname>.</para></listitem> +</orderedlist> +<para>The last requirement may seem complicated, but, as we will see later, by +adding a single +line to your source files, you can usually ignore it.</para> +</sect1> +<sect1 id="headercode"> +<title>Code for the header file</title> +<para>Given the constaints, we will now see what the header file +<filename>theme2k.h</filename> looks +like this:</para> +<example> +<title>Listing for <filename>theme2k.h</filename></title> +<programlisting> +#ifndef __THEME2K_H__ +#define __THEME2K_H__ + +#include <qlabel.h> +#include <qwidget.h> + +#include <kdialogbase.h> +#include <kpixmap.h> +#include <ksplash/themeengine.h> + +class RotWidget; + +class Cfg2k: public ThemeEngineConfig +{ + Q_OBJECT +public: + Cfg2k( KConfig * ); +}; + +class ObjKsTheme; +class Theme2k: public ThemeEngine +{ + Q_OBJECT +public: + Theme2k( QWidget *, const char *, const QStringList& ); + + inline const QString name() + { + return( QString("KSplash2k") ); + } + inline const KDialogBase *config( KConfig *kc ) + { + return new Cfg2k( kc ); + } + static QStringList names() + { + QStringList Names; + Names << "KSplash2k"; + Names << "ks2k"; + Names << "2k"; + Names << "2000"; + return( Names ); + }; + +public slots: + inline void slotSetText( const QString& s ) + { + if( mText && mText->text() != s ) mText->setText( s ); + }; + +private: + void initUi(); + void readSettings(); + + QLabel *mText; + RotWidget *mRotator; + QColor mTBgColor, mTFgColor, mRotColor1, mRotColor2, mStatusColor; + int mRotSpeed; + QString mWndTitle, mLogoFile; +}; + +#endif +</programlisting> +</example> +<para>Let us analyze the listing above. The <classname>Theme2k</classname> class +satisfies +the naming conventions, and is inherited from +<classname>ThemeEngine</classname>. It provides +a <methodname>Theme2k::names()</methodname>, and has a constructor that takes +the required +parameters: <function>Theme2k( QWidget *, const char *, const QStringList& +);</function> +and also provides a simple <methodname>Theme2k::slotSetText()</methodname> +method. For the moment, +do not worry about the <classname>RotWidget</classname> class. It is a small +widget that provides +some eye candy for the user. Our plugin is very simple and does not display any +icons or show +a progressbar. If you would like to display icons, override the +<function>slotSetPixmap</function> +function. Similar functions exist for setting the progressbar range +(<function>slotUpdateSteps</function>) +and incrementing(<function>slotUpdateProgress</function>) the current step. +</para> +</sect1> +<sect1 id="Implementation"> +<title>Implementation of the plugin</title> +<para>We will examine only the relevant parts of the implementation. For a +listing of the whole +implementation, please see the appendix. The first thing we will do is to get +the library +requirement out of the way:</para> +<example> +<title>Library requirement</title> +<programlisting> +K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> ); +</programlisting> +</example> +<para> The macro <constant>K_EXPORT_COMPONENT_FACTORY</constant> is declared in +<filename>kgenericfactory.h</filename>. Onwards to the constructor! +Since this is a very simple plugin, the constructor is pretty +straightforward.</para> +<example> +<title>Plugin constructor</title> +<programlisting> +Theme2k::Theme2k( QWidget *parent, const char *name, const QStringList &args + ) + :ThemeEngine( parent, name, args ) +{ + readSettings(); + initUi(); +} +</programlisting> +</example> +<para>The method <function>readSettings()</function> illustrates the +proper way to obtain your theme settings. (You do want people to use your +plugins +in their themes, don't you?)</para> +<example> +<title>Obtaining theme settings</title> +<programlisting> +void Theme2k::readSettings() +{ + if( !mTheme ) + return; + + KConfig *cfg = mTheme->themeConfig(); + if( !cfg ) + return; + + cfg->setGroup( QString("KSplash Theme: %1").arg(mTheme->theme()) ); + + QColor DefaultTBgColor( Qt::darkBlue ); + QColor DefaultTFgColor( Qt::white ); + + mTBgColor = cfg->readColorEntry( "Title Background Color", +&DefaultTBgColor ); + mTFgColor = cfg->readColorEntry( "Title Foreground Color", +&DefaultTFgColor ); + mStatusColor = cfg->readColorEntry("Status Text Color", &mTBgColor ); + + QColor DefaultRot1( Qt::darkBlue ); + QColor DefaultRot2( Qt::cyan ); + mRotColor1 = cfg->readColorEntry( "Rotator Color 1", &DefaultRot1 ); + mRotColor2 = cfg->readColorEntry( "Rotator Color 2", &DefaultRot2 ); + + mRotSpeed = cfg->readNumEntry( "Rotator Speed", 30 ); + mWndTitle = cfg->readEntry( "Window Title", i18n("Please wait...") ); + mLogoFile = cfg->readEntry( "Logo File", QString::null ); +} +</programlisting> +</example> +<para>Since we like our users, we provide sensible defaults for parameters that +are not +present in the theme file. Note that we should always set our group to "KSplash +Theme: themename" +to remain compatible with future theme specifications. The +<function>initUI()</function> method is +not very interesting, as it merely builds up the widgets. Please see the +appendix for details. +</para> +</sect1> +<sect1 id="compilingfile"> +<title>Compiling the plugin</title> +<para>Since we decided to use the &kde; framework for compiling the plugin, we +need to create a +<filename>Makefile.am</filename>. It should look like this:</para> +<example> +<title>Listing of <filename>Makefile.am</filename></title> +<programlisting> +INCLUDES = $(all_includes) + +kde_module_LTLIBRARIES = ksplash2k.la + +ksplash2k_la_SOURCES = theme2k.cpp rotwidget.cpp +ksplash2k_la_LDFLAGS = $(all_libraries) $(KDE_RPATH) +ksplash2k_la_LIBADD = $(LIB_KDEUI) -lksplashthemes + +METASOURCES = AUTO + +noinst_HEADERS = theme2k.h rotwidget.h + +servicesdir = $(kde_servicesdir) +services_DATA = ksplash2k.desktop + +themedir = $(kde_datadir)/ksplash/Themes/2k +theme_DATA = Theme.rc Preview.png +</programlisting> +</example> +<para>For more information on writing <filename>Makefile.am</filename> files for +&kde;, please see +the &kde; developers' <ulink +url="http://developer.kde.org/documentation/other/makefile_am_howto.html"> +website</ulink>. +The only thing of note is that we provide a default theme based on this plugin, +and provide +a preview image for it. As a matter of courtesy to your users, you should +provide an example +<filename>Theme.rc</filename> file illustrating the use of the various +options.</para> +</sect1> +</chapter> + +<chapter id="faq"> +<title>Questions and Answers</title> + +&reporting.bugs; +&updating.documentation; + +<qandaset id="faqlist"> +<qandaentry> +<question> +<para>I can't find any themes that work in &ksplash;. Why is that?</para> +</question> +<answer> +<para>You probably don't have the correct plugins for the theme. The +plugins are in the <literal>kde-artwork</literal> package. Download +and install it, and try then again.</para> +</answer> +</qandaentry> +<qandaentry> +<question> +<para>What is file <filename>Theme.rc</filename> and how do I make one?</para> +</question> +<answer> +<para> +<filename>Theme.rc</filename> is the file where you can specify a +theme's settings. For more information, take a look at <link +linkend="themes">How to make themes for &ksplash;</link>. +</para> +</answer> +</qandaentry> +</qandaset> +</chapter> + +<chapter id="credits"> +<title>Credits and License</title> + +<para>&ksplash;</para> + +<para>Program Copyright © 2003 &Ravikiran.Rajagopal; +&Ravikiran.Rajagopal.mail;</para> + +<itemizedlist> +<title>Contributors</title> +<listitem><para>&Brian.C.Ledbetter; &Brian.C.Ledbetter.mail;</para> +</listitem> +</itemizedlist> + +<para>Documentation Copyright © 2003 &Teemu.Rytilahti; +&Teemu.Rytilahti.mail;</para> + +&underFDL; <!-- FDL: do not remove --> +&underGPL; <!-- GPL License --> + +</chapter> + +<appendix id="installation"> +<title>Installation</title> + +<sect1 id="requirements"> +<title>Requirements</title> + +<para>In order to successfully use &ksplash;, you need &kde; version 3.2 or +higher. Some themes may require specific plugins. If a theme does not +work, please contact the theme author to find out where to obtain the +appropriate plugin.</para> + +</sect1> + +<sect1 id="compilation"> +<title>Compilation and Installation</title> + +&install.compile.documentation; + +</sect1> +</appendix> +<appendix id="srccode"> +<title>Source code</title> +<sect1 id="theme2kcpp"> +<title>Listing of <filename>theme2k.cpp</filename></title> +<programlisting> +#include <qlabel.h> +#include <qwidget.h> + +#include <kapplication.h> +#include <kconfig.h> +#include <kdebug.h> +#include <kdialogbase.h> +#include <kgenericfactory.h> +#include <kglobalsettings.h> +#include <klocale.h> +#include <ksplash/objkstheme.h> +#include <kstandarddirs.h> + +#include "rotwidget.h" +#include "theme2k.h" +#include "theme2k.moc" + +K_EXPORT_COMPONENT_FACTORY( ksplash2k, KGenericFactory<Theme2k> ); + +Cfg2k::Cfg2k( KConfig * ) +{} + +Theme2k::Theme2k( QWidget *parent, const char *name, const QStringList &args + ) + :ThemeEngine( parent, name, args ) +{ + readSettings(); + initUi(); +} + +void Theme2k::initUi() +{ + QVBox *vbox = new QVBox( this ); + vbox->setFrameShape( QFrame::WinPanel ); + vbox->setFrameShadow( QFrame::Raised ); + + QHBox *labelBox = new QHBox( vbox ); + labelBox->setPalette( mTBgColor ); + labelBox->setMargin( 1 ); + QLabel *lbl = new QLabel( mWndTitle, labelBox ); + lbl->setFont( QFont( "Arial", 12, QFont::Bold ) ); + lbl->setPaletteForegroundColor( mTFgColor ); + + QLabel *logo = new QLabel( vbox ); + logo->setPalette( Qt::white ); + + QString px( locate( "appdata", mTheme->themeDir() + +(mLogoFile.isNull()?QString("/Logo.png"):mLogoFile) ) ); + if (px.isNull()) + px = locate("appdata","Themes/Default/splash_top.png"); + if( !px.isNull() ) + { + QPixmap pix( px ); + logo->setPixmap( pix ); + } + else + { + logo->setText( "<B>KDE</B>2000" ); + logo->setAlignment( AlignCenter|AlignVCenter ); + } + + mRotator = new RotWidget( vbox, mRotColor1, mRotColor2, mRotSpeed ); + + QHBox *hbox = new QHBox( vbox ); + labelBox->setSpacing( 4 ); + labelBox->setMargin( 4 ); + + mText = new QLabel( hbox ); + mText->setPaletteForegroundColor( mStatusColor ); + mText->setPaletteBackgroundColor( mTFgColor ); + mText->setText( mWndTitle ); + mText->setFixedHeight( 48 ); + + setFixedSize( vbox->sizeHint() ); + QRect rect(KGlobalSettings::splashScreenDesktopGeometry()); + move( rect.x() + (rect.width() - size().width())/2, + rect.y() + (rect.height() - size().height())/2 ); +} + +void Theme2k::readSettings() +{ + if( !mTheme ) + return; + + KConfig *cfg = mTheme->themeConfig(); + if( !cfg ) + return; + + cfg->setGroup( QString("KSplash Theme: %1").arg(mTheme->theme()) ); + + QColor DefaultTBgColor( Qt::darkBlue ); + QColor DefaultTFgColor( Qt::white ); + + mTBgColor = cfg->readColorEntry( "Title Background Color", +&DefaultTBgColor ); + mTFgColor = cfg->readColorEntry( "Title Foreground Color", +&DefaultTFgColor ); + mStatusColor = cfg->readColorEntry("Status Text Color", &mTBgColor ); + + QColor DefaultRot1( Qt::darkBlue ); + QColor DefaultRot2( Qt::cyan ); + mRotColor1 = cfg->readColorEntry( "Rotator Color 1", &DefaultRot1 ); + mRotColor2 = cfg->readColorEntry( "Rotator Color 2", &DefaultRot2 ); + + mRotSpeed = cfg->readNumEntry( "Rotator Speed", 30 ); + mWndTitle = cfg->readEntry( "Window Title", i18n("Please wait...") ); + mLogoFile = cfg->readEntry( "Logo File", QString::null ); +} +</programlisting> +</sect1> +<sect1 id="rotwidgeth"> +<title>Listing of <filename>rotwidget.h</filename></title> +<programlisting> +#ifndef __ROTWIDGET_H__ +#define __ROTWIDGET_H__ + +#include <qlabel.h> +#include <qtimer.h> +#include <qwidget.h> + +#include <kdialogbase.h> +#include <kpixmap.h> + +/** + * @short Display a rotating-gradient widget. + */ +class RotWidget: public QWidget +{ + Q_OBJECT +public: + RotWidget( QWidget *, const QColor&, const QColor&, int ); + ~RotWidget(); + +private slots: + void stepEvent(); + +protected: + void preparePixmap( int ); + void paintEvent( QPaintEvent * ); + void resizeEvent( QResizeEvent * ); + + QColor m_color1, m_color2; + int m_step, m_speed; + QTimer *m_stepTimer; + + QList<KPixmap> m_stepPixmap; +}; + +#endif +</programlisting> +</sect1> +<sect1 id="rotwidgetcpp"> +<title>Listing of <filename>rotwidget.cpp</filename></title> +<programlisting> +#include <kdebug.h> +#include <kdialogbase.h> +#include <kpixmapeffect.h> + +#include <qlabel.h> +#include <qpainter.h> +#include <qwidget.h> + +#include "rotwidget.h" +#include "rotwidget.moc" + +RotWidget::RotWidget( QWidget *parent, const QColor& c1, const QColor& +c2, int sp ) + :QWidget(parent), m_color1(c1), m_color2(c2), m_step(0), m_speed(sp) +{ + if( (m_speed <= 0) || (m_speed > 20) ) + m_speed = 1; + setFixedHeight( 6 ); + + for( int i = 0; i <= width(); i++ ) + preparePixmap( i ); + + m_stepTimer = new QTimer( this ); + connect(m_stepTimer, SIGNAL(timeout()), this, SLOT(stepEvent())); + m_stepTimer->start( 50 ); +} + +RotWidget::~RotWidget() +{ +} + +void RotWidget::stepEvent() +{ + // This is inefficient as we create too many pixmaps, optimize later. + m_step += m_speed; + if( m_step > width() ) + m_step = 0; + repaint( true ); +} + +// Todo: Optimize drawing. +void RotWidget::paintEvent( QPaintEvent *pe ) +{ + QPainter p; + p.begin( this ); + + QRect r = pe->rect(); + + if( m_stepPixmap.at( m_step ) ) + bitBlt( this, r.x(), r.y(), m_stepPixmap.at( m_step ), r.x(), r.y(), +r.width(), r.height() ); + else + p.fillRect( rect(), Qt::black ); + p.end(); +} + +void RotWidget::resizeEvent( QResizeEvent *re ) +{ + m_stepPixmap.clear(); + for( int i = 0; i <= re->size().width(); i++ ) + preparePixmap( i ); +} + +void RotWidget::preparePixmap( int step ) +{ + if( step < 0 ) + return; + + // Explicitly draw our first pixmap. The rest we will bitBlt() from here. + if( step == 0 ) + { + KPixmap tmp; tmp.resize( size().width() / 2, size().height() ); + KPixmap tmp2(tmp); + KPixmapEffect::gradient( tmp, m_color1, m_color2, +KPixmapEffect::HorizontalGradient ); + KPixmapEffect::gradient( tmp2, m_color2, m_color1, +KPixmapEffect::HorizontalGradient ); + KPixmap *px = new KPixmap( size() ); + QPainter p; + p.begin( px ); + p.drawPixmap( 0, 0, tmp ); + p.drawPixmap( size().width()/2, 0, tmp2 ); + p.end(); + m_stepPixmap.append( px ); + } + else if( m_stepPixmap.at( step-1 ) ) + { + QPixmap *prev = m_stepPixmap.at( step-1 ); + QPixmap next; next.resize( size() ); + // convert + // prev = "[------------]" + // to + // next = "------------][" + bitBlt( &next, 0, 0, prev, 1, 0, prev->width()-1, prev->height() +); + bitBlt( &next, width()-1, 0, prev, 0, 0, 1, prev->height() ); + KPixmap *n = new KPixmap( next ); + m_stepPixmap.append( n ); + } +} +</programlisting> +</sect1> +</appendix> + +&documentation.index; +</book> + +<!-- +Local Variables: +mode: xml +sgml-minimize-attributes:nil +sgml-general-insert-case:lower +sgml-indent-step:0 +sgml-indent-data:nil +End: + +vim:tabstop=2:shiftwidth=2:expandtab +--> diff --git a/doc/ksysguard/Makefile.am b/doc/ksysguard/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/ksysguard/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/ksysguard/index.docbook b/doc/ksysguard/index.docbook new file mode 100644 index 000000000..cfeb64098 --- /dev/null +++ b/doc/ksysguard/index.docbook @@ -0,0 +1,496 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&ksysguard;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &ksysguard; Handbook</title> + +<authorgroup> +<author> +&Chris.Schlaeger;&Chris.Schlaeger.mail; +</author> + +<othercredit role="developer"> +&Chris.Schlaeger;&Chris.Schlaeger.mail; +<!-- <contrib>Developer</contrib> --> +</othercredit> + +<othercredit role="developer"> +&Tobias.Koenig;&Tobias.Koenig.mail; +<!-- <contrib>Developer</contrib> --> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year> +<holder>&Chris.Schlaeger;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2000-12-14</date> +<releaseinfo>1.00.00</releaseinfo> + +<abstract><para>&ksysguard; is a network enabled task manager and system monitor +application, with the additional functionality of +<application>top</application>.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KSysGuard</keyword> +<keyword>process monitor</keyword> +<keyword>top</keyword> +<keyword>ps</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&ksysguard; is the &kde; Task Manager and Performance Monitor. It features + +a +client/server architecture that allows monitoring of local as well as remote +hosts. The graphical front end uses so-called sensors to retrieve the +information it displays. A sensor can return simple values or more complex +information like tables. For each type of information, one or more displays are +provided. Displays are organized in work sheets that can be saved and loaded +independently from each other. So, &ksysguard; is not only a simple task manager +but also a very powerful tool to control large server farms.</para> + +</chapter> + + +<chapter id="usingtheksysguard"> +<title>Using &ksysguard;</title> + +<sect1 id="getting-started"> +<title>Getting started</title> + +<para>&ksysguard; can be started from the start menu, using the entry +<guimenuitem>KDE System +Guard</guimenuitem> in the <guimenu>Systems</guimenu> menu. Alternatively, you +can start it by typing <command>ksysguard</command> in a terminal.</para> + +<para>The &ksysguard; main window consists of a menu bar, an optional tool bar +and +status bar, the sensor browser and the work space. When first started you see +your local machine listed as <guilabel>localhost</guilabel> in the sensor +browser and 2 pages in the work space area. This is the default setup.</para> + +<para>This default setup is sufficient enough for an inexperienced user to do +some system management. An experienced user or even a system administrator of a +large computer lab has different needs. To address a wide range of users, +&ksysguard; +is highly flexible.</para> +</sect1> + +<sect1 id="the-sensor-browser"> +<title>The Sensor Browser</title> + +<para>The sensor browser displays the registered hosts and their sensors in a +tree form. Click on the tree handles to open or close a branch. Each sensor +monitors a certain system value.</para> + +<sect2 id="connectingtootherhosts"> +<title>Connecting to other hosts</title> + +<para>To connect to a new host use <guimenuitem>Connect Hosts</guimenuitem> +from the <guimenu>File</guimenu> menu. A dialog box will appear and allows you +to +enter the name of the host you want to connect to. Below the name you can choose +the connection method. The default is <application>ssh</application>, the secure +shell. Alternatively the <application>rsh</application>, the remote shell, or +the daemon mode can be used. Click <guibutton>OK</guibutton> to +establish the connection. Shortly afterwards the new host will appear in the +sensor browser and you can browse the list of sensors.</para> + +<para>To establish a connection, a program called +<application>ksysguardd</application>, that can be started in the following +two modes, must be installed on the new host.</para> + +<variablelist> +<varlistentry> +<term>daemon mode</term> +<listitem> +<para>You can start <application>ksysguardd</application> at boot time in +<guilabel>Daemon</guilabel> mode by adding <parameter>-d</parameter> as the +argument. In this case, you have to select daemon mode at the connection +dialog of <application>ksysguard</application>. +A disadvantage of this connection type is that you won't be able to kill or +renice a process with the <guilabel>Process Controller</guilabel> and +the data exchange over network won't be encrypted.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>shell mode</term> +<listitem> +<para>In this mode <application>ksysguardd</application> is started at +connecting time by <application>ksysguard</application>. To make that possible, +its location needs to be included in your <envar>PATH</envar>. +Unfortunately the ssh does not source your <filename>.profile</filename> file, +so your regular <envar>PATH</envar> setting will not be available. +Instead it uses a default <envar>PATH</envar> like +<parameter>/bin:/usr/bin</parameter>. +Since it is very likely that &kde; is not installed in these folders you need +to create or update a file in your home folder. The file is called +<filename>environment</filename> and needs to be in a hidden folder called +<filename>.ssh</filename>. See the manual page for +<application>ssh</application> for more details. The file needs to contain a +line similar to:</para> + +<screen> +<userinput>PATH=/bin:/usr/bin:/opt/kde/bin</userinput> +</screen> + +<para>assuming that <application>ksysguardd</application> can be found under +<filename>/opt/kde/bin/ksysguardd</filename>.</para> + +<tip><para>When using <application>ssh</application> you should make sure that +you have your <filename>identity.pub</filename> installed on the remote machine +and the host key of the remote machine is already registered on your machine. +The easiest way to check this is to type <command>ssh <option>remotehost +ksysguardd</option></command> in a shell. If you are greeted by +<application>ksysguardd</application> you can type <userinput>quit</userinput> +and everything is in order.</para></tip> +</listitem> +</varlistentry> +</variablelist> + +<note><para>For experts: <application>ksysguardd</application> is a +very small program that is only linked against the libc. So it can +also be used on machines that do not have a full blown &kde; +installed, such as servers. If you choose the custom command option in +the host connector you need to specify the complete command to start +<application>ksysguardd</application>.</para></note> + +</sect2> + +<sect2 id="disconnecting-hosts"> +<title>Disconnecting hosts</title> + +<para>To disconnect from a host, select the host in the sensor browser and +choose <guimenuitem>Disconnect Host</guimenuitem> from the +<guimenu>File</guimenu> menu. If you still have sensors in use, the display +frames will be grayed and the displays won't update any longer.</para> +</sect2> +</sect1> + +<sect1 id="the-workspace"> +<title>The Work Space</title> + +<para>The work space is organized as work sheets. Select +<guimenuitem>New</guimenuitem> from the <guimenu>File</guimenu> menu to create a +new work sheet. A dialog will appear where you can set the name, the +dimension and the update interval of the work sheet. To remove a work sheet +again, select +<guimenuitem>Close</guimenuitem> from the <guimenu>File</guimenu> menu. Any +modifications will be saved to the work sheet file. If a work sheet has +never been saved, you will be asked for a file name. Work sheets consist of +cells +organized as a grid.</para> + +<para>Each cell can be filled with a display for one or more sensors. You can +fill a cell by dragging a sensor from the sensor browser and dropping it over +the cell. If there is more than one type of display available for that type +of sensor, a popup menu will appear. You can then select which display you +prefer +to use. Certain types of displays can display more than one sensor. Add more +sensors to a display by dragging them over from the sensor browser and dropping +them over the already existing display.</para> + +<para>Work sheets can be configured by clicking <guimenuitem>Configure Worksheet +</guimenuitem> at the <guimenu>Edit</guimenu> menu. In the appearing dialog +you can set the dimension and the update interval. This update interval is +used by all displays of the worksheet, which has the <guilabel>use update +interval of worksheet</guilabel> set in its timer configuration dialog.</para> + +<para>The entry <guimenuitem>Configure Style</guimenuitem> of the +<guimenu>Settings</guimenu> menu gives you the possibility to configure the +global style attributes and apply them to the current active worksheet.</para> + +<para>Displays can be configured by clicking with the right mouse button on +them. A popup menu appear where you can select whether you want to change the +properties of that display, remove it from the work sheet, change its update +interval type and value or pause and restart its updating.</para> + +<sect2 id="signal-plotter"> +<title>Signal Plotter</title> + +<para>The signal plotter prints samples of one or more sensors over time. If, +several sensors are displayed, the values are piled in different colors. If +the display is large enough a grid will be displayed to show the range of the +plotted samples. By default, the automatic range mode is active so the minimum +and maximum values will be set automatically. Sometimes you want fixed +minimum and maximum values. In that case, you can deactivate automatic range +mode and set the values in the properties dialog.</para> +</sect2> + +<sect2 id="multimeter"> +<title>Multimeter</title> + +<para>The multimeter displays the sensor values as a digital meter. In the +properties dialog you can specify a lower and upper limit. If the range +is exceeded, the display is colored in the alarm color.</para> +</sect2> + +<sect2 id="process-controller"> +<title>Process Controller</title> + +<para>The Process Controller gives you a list of processes on your +system. The list can be sorted by each column. Just press the left +mouse button at the head of the column. </para> + +<para>The list shows the following information about each process. Please note +that not all properties are available on every operating system.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Name</guilabel></term> +<listitem><para>The name of the executable that started the process.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>PID</guilabel></term> +<listitem><para>The Process <abbrev>ID</abbrev>. A unique number for each +process.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>PPID</guilabel></term> +<listitem><para>The Process <abbrev>ID</abbrev> of the process parent.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>UID</guilabel></term> +<listitem><para>The <abbrev>ID</abbrev> of the user that started the +process.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>GID</guilabel></term> +<listitem><para>The <abbrev>ID</abbrev> of the group the process +belongs to.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Status</guilabel></term> +<listitem><para>The process status.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>User%</guilabel></term> +<listitem> +<para>The processor load of the process in user space (in percent).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>System%</guilabel></term> +<listitem> +<para>The processor load of the process in system space (in percent).</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Nice</guilabel></term> +<listitem><para>The scheduling priority.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>VmSize</guilabel></term> +<listitem><para>The total amount of virtual memory used by the process +(in kBytes).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>VmRss</guilabel></term> +<listitem><para>The total amount of physical memory used by the process +(in kBytes).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Login</guilabel></term> +<listitem><para>The login name of the user that started the process.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Command</guilabel></term> +<listitem><para>The complete start command of the process.</para></listitem> +</varlistentry> +</variablelist> + +<para>Underneath the table you find four buttons which will be described now +from left to right.</para> + +<sect3 id="the-tree-view"> +<title>The <guibutton>Tree</guibutton> View</title> + +<para>The tree view has been designed to show the relationships between the +running processes. A process that is started by another process is called the +child of that process. A tree is an elegant way to show this parent-child +relationship. The <emphasis>init</emphasis> process is the ancestor of all +processes.</para> + +<para>If you are not interested in the children of a particular process you can +click on the little box to the left of the parent and the subtree will +collapse. Another click on that box will unfold the subtree again.</para> + +</sect3> + +<sect3 id="the-process-filter"> +<title>The Process Filter </title> + +<para>The Process Filter can be used to reduce the number of processes displayed +in the table. You can filter out processes you are not interested in. Currently +you can display all processes, system processes only, user processes only or +your processes only.</para> + +</sect3> + +<sect3 id="therefreshbutton"> +<title>The <guibutton>Refresh</guibutton> Button </title> + +<para>This button can be used to force an immediate update of the process +list.</para> + +</sect3> + +<sect3 id="thekillbutton"> +<title>The <guibutton>Kill</guibutton> Button </title> + +<para>If you have selected one or more processes you can press the kill button +to kill them. A so called <errorcode>SIGKIL</errorcode> is sent to the processes + +which causes them to +terminate immediately. If these applications still have unsaved data this data +will be lost. So use this button with care.</para> + +</sect3> +</sect2> + +<sect2 id="bargraph"> +<title>BarGraph</title> + +<para>The bargraph displays the sensor values as dancing bars. In the +properties dialog you can specify minimum and maximum values of range and +a lower and upper limit. If the range is exceeded, the display is +colored in the alarm color.</para> +</sect2> + +<sect2 id="sensorlogger"> +<title>Sensor Logger</title> + +<para>The sensor logger does not display any values, but logs them in +a file with additional date and time information. For each sensor +you can specify a lower and upper limit in the properties dialog. +If the range is exceeded, the entry of the sensor table is colored in +the alarm color and a <application>knotify</application> event is sent.</para> +</sect2> + +<sect2 id="logfile"> +<title>Log File</title> + +<para>The log file monitor displays the content of a file ⪚ +<filename>/var/log/messages</filename>. +In the properties dialog, you can compose a list of regular expressions that +will be compared with the content of the file. If one of the expressions match, +a <application>knotify</application> +event will be sent. +</para> +</sect2> + +<sect2 id="listview"> +<title>List View</title> + +<para>The listview displays the data of some sensors in the form of a +table.</para> +</sect2> + +</sect1> +</chapter> + +<chapter id="multiple-platforms"> +<title>Configuring <application>ksysguardd</application></title> + +<para>The graphical front-end is available on any platform that &kde; runs +on. The back-end is at the moment available on the following flavors of +&UNIX;:</para> + +<variablelist> +<varlistentry> +<term>&Linux; 2.x</term> +<listitem><para> For <application>ksysguardd</application> to work it +is necessary to compile the &Linux; Kernel +with the <filename>/proc</filename> Filesystem enabled. This is the default +setting and most &Linux; Distributions have it already.</para> </listitem> +</varlistentry> +<varlistentry> +<term>FreeBSD</term> +<listitem><para>The <application>ksysguardd</application> program +needs to be owned by the <systemitem +class="groupname">kmem</systemitem> group and needs to have the setgid +bit set.</para></listitem> +</varlistentry> +<varlistentry> +<term>&Solaris;</term> +<listitem><para>To be written</para></listitem> +</varlistentry> +</variablelist> + +<para>Support for other platforms is in progress. Your help is greatly +appreciated.</para> +</chapter> + +<chapter id="credits-and-licenses"> +<title>Credits and Licenses</title> + +<para>&ksysguard; is currently developed and maintained by Chris Schläger +<email>[email protected]</email>. &ksysguard; is a rewrite of +<application>KTop</application>, the KDE 1.x task manager. Several other people +have worked on <application>KTop</application>:</para> + +<itemizedlist> +<listitem><para> A. Sanda <email>[email protected]</email></para></listitem> +<listitem><para> Ralf Mueller <email>[email protected]</email></para></listitem> +<listitem><para> Bernd Johannes Wuebben +<email>[email protected]</email></para></listitem> +<listitem><para> Nicolas Leclercq +<email>[email protected]</email></para></listitem> +</itemizedlist> + +<para>The porting to other platforms than &Linux; was done by:</para> + +<itemizedlist> +<listitem><para> FreeBSD: Hans Petter Bieker +<email>[email protected]</email></para></listitem> +</itemizedlist> + +&underFDL; +&underGPL; + +</chapter> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/kwrite/Makefile.am b/doc/kwrite/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kwrite/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kwrite/index.docbook b/doc/kwrite/index.docbook new file mode 100644 index 000000000..b1762a201 --- /dev/null +++ b/doc/kwrite/index.docbook @@ -0,0 +1,2952 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kwrite;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kwrite; Handbook</title> +<authorgroup> +<author>&Thad.McGinnis; &Thad.McGinnis.mail;</author> +<author>&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</author> +<author>&Anders.Lund; &Anders.Lund.mail;</author> +<othercredit role="developer"> +&Christoph.Cullmann; &Christoph.Cullmann.mail; +<!-- <contrib>Core Developer and Maintainer</contrib> --> +</othercredit> + +<othercredit role="reviewer"> +&Lauri.Watts; &Lauri.Watts.mail; +<!-- <contrib>Reviewer</contrib> --> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2000</year><year>2001</year> +<holder>&Thad.McGinnis;</holder> +</copyright> +<copyright> +<year>2005</year> +<holder>&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</holder> +<holder>&Anders.Lund; &Anders.Lund.mail;</holder> +</copyright> +<legalnotice>&FDLNotice;</legalnotice> + +<date>2005-12-27</date> +<releaseinfo>4.5.0</releaseinfo> + +<abstract> +<para>&kwrite; is a text editor for &kde;</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>KWrite</keyword> +<keyword>text</keyword> +<keyword>editor</keyword> +</keywordset> + +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +&kwrite; is more than a text editor for the &kde; Desktop. It is meant +to be a programmer's editor, and could be considered as at least a +partial alternative to more powerful editors. It may be best used in +conjunction with &konqueror; for source file browsing for different +languages. &kwrite; also works very well as a simple text editor. One +of &kwrite;'s main features is the colorized syntax, customized for many +different programming languages such as: C/C++, &Java;, Python, Perl, +Bash, Modula 2, &HTML;, and Ada. +</para> + +</chapter> + +<chapter id="on-screen-fundamentals"> +<title>Some Fundamentals</title> + +<para> +&kwrite; is very simple to use. Anyone that has used a text editor +should have no problems. +</para> + +<sect1 id="drag-and-drop"> +<title>Drag and Drop</title> + +<para> +&kwrite; uses the &kde; Drag and Drop protocol. Files may be dragged and +dropped onto &kwrite; from the Desktop, &konqueror; or some remote &FTP; +site opened in one of &konqueror;'s windows. +</para> +</sect1> + +<sect1 id="command-line-options"> +<title>Command Line Options</title> + +<para> +Though &kwrite; may most often be started from the &kde; program menu, or +a desktop icon, it can also be opened at the command line prompt of a +terminal window. There are a few useful options that are available when +doing this. +</para> + +<sect2 id="specify-a-file"> +<title>Specify a File</title> + +<para>By specifying the path and name of a particular file the user can +have &kwrite; open (or create) that file immediately upon startup. This +option might look something like the following:</para> + +<informalexample><screen> +<prompt>%</prompt> <userinput><command>kwrite</command> +<option><replaceable>/home/myhome/docs/myfile.txt</replaceable></option> +</userinput> +</screen> +</informalexample> +</sect2> +<sect2 id="editing-files-on-the-internet"> +<title>Specify a file on the internet</title> + +<para>The above-mentioned method could even be used to open files on the +internet (if the user has an active connection at the time.) An example of +this might look like the following:</para> + +<informalexample><screen> +<prompt>%</prompt> <userinput><command>kwrite</command> +<option><replaceable>ftp://ftp.kde.org/pub/kde/Welcome.msg</replaceable> +</option></userinput> +</screen> +</informalexample> + +</sect2> + +<sect2 id="other-command-line-options"> +<title>Other Command Line Options</title> + +<para>The following command line help options are available</para> + +<variablelist> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--help</option></userinput></term> +<listitem><para>This lists the most basic options available at the command +line.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--help-qt</option></userinput></term> +<listitem><para>This lists the options available for changing the way +&kwrite; interacts with &Qt;.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--help-kde</option></userinput></term> +<listitem><para>This lists the options available for changing the way +&kwrite; interacts with &kde;.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--help-all</option></userinput></term> +<listitem><para>This lists all of the command line options.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--author</option></userinput></term> +<listitem><para>Lists &kwrite;'s authors in the terminal +window</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--version</option></userinput></term> +<listitem><para>Lists version information for &Qt;, &kde;, and &kwrite;. Also +available through <userinput><command>kwrite</command> +<option>-v</option></userinput> </para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--stdin</option></userinput></term> +<listitem><para>Causes &kwrite; to read the document content from STDIN. This +is similar to the common option <option>-</option> used in many command line +programs, and allows you to pipe command output into &kwrite;.</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--encoding</option> <parameter>encoding</parameter> +<parameter>&URL;</parameter></userinput></term> +<listitem><para>Causes &kwrite; to use the specified encoding for the document. +</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--line</option> <parameter>line</parameter> +<parameter>&URL;</parameter></userinput></term> +<listitem><para>Navigate to the specified line after opening the document. +</para></listitem> +</varlistentry> +<varlistentry> +<term><userinput><command>kwrite</command> +<option>--column</option> <parameter>column</parameter> +<parameter>&URL;</parameter></userinput></term> +<listitem><para>Navigate to the specified column after opening the document. +</para></listitem> +</varlistentry> + +</variablelist> +</sect2> +</sect1> + +<sect1 id="keybindings"> +<title>Shortcuts</title> + +<para>Many of the shortcuts are configurable by way of the <link + linkend="settings">Settings</link> menu. By default &kwrite; honors the +following shortcuts:</para> +<informaltable> +<tgroup cols="2"> +<tbody> + +<row><entry><para><keycombo +action="simul"><keycap>Insert</keycap></keycombo></para></entry> +<entry><para> Toggle between Insert and Overwrite mode. When in insert mode the +editor will add any typed characters to the text while pushing along any data to +the right of the text cursor. Overwrite mode causes the entry of each character +to eliminate the character immediately to the right of the text +cursor.</para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Left +Arrow</keycap></keycombo></para></entry> +<entry><para>Move the cursor one character to the left </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Right +Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor one character to the right </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Up +Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor up one line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Down +Arrow</keycap></keycombo></para></entry> +<entry><para> Move the cursor down one line </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Page +Up</keycap></keycombo></para></entry> +<entry><para> Move the cursor up one page </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Alt;<keycap>Page +Up</keycap></keycombo></para></entry> +<entry><para>Previous Bookmark </para></entry> +</row> +<row> +<entry><para><keycombo action="simul"><keycap>Page +Down</keycap></keycombo></para></entry> +<entry><para>Move the cursor down one page </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Alt;<keycap>Page +Down</keycap></keycombo></para></entry> +<entry><para>Next Bookmark </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>Backspace</keycap></keycombo></para></entry> +<entry><para> Delete the character to the left of the cursor </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>Home</keycap></keycombo></para></entry> +<entry><para> Move the cursor to the beginning of the line </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>End</keycap></keycombo></para></entry> +<entry><para> Move the cursor to the end of the line </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>Delete</keycap></keycombo></para></entry> +<entry><para>Delete the character to the right of the cursor (or any selected +text)</para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Left +Arrow</keycap></keycombo></para></entry> +<entry><para> Mark text one character to the left </para></entry> +</row> +<row> +<entry><para><keycombo action="simul">&Shift;<keycap>Right +Arrow</keycap></keycombo></para></entry> +<entry><para> Mark text one character to the right </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F1</keycap></keycombo></para></entry> +<entry><para> Help</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Shift;<keycap>F1</keycap></keycombo></para></entry> +<entry><para>What's this?</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F3</keycap></keycombo></para></entry> +<entry><para><link linkend="find-again"> Find again</link></para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Shift;<keycap>F3</keycap></keycombo></para></entry> +<entry><para><link linkend="find-previous"> Find Previous</link></para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>A</keycap></keycombo></para></entry> +<entry><para>Select All</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo></para></entry> +<entry><para>Deselect</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>B</keycap></keycombo></para></entry> +<entry><para>Block Selection Mode</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>B</keycap></keycombo></para></entry> +<entry><para>Set a Bookmark</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>C</keycap></keycombo></para></entry> +<entry><para> Copy the marked text to the clipboard. </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>D</keycap></keycombo></para></entry> +<entry><para> Comment</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo></para></entry> +<entry><para> Uncomment</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>F</keycap></keycombo></para></entry> +<entry><para><link linkend="find"> Find</link></para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>G</keycap></keycombo></para></entry> +<entry><para> Go to line...</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>I</keycap></keycombo></para></entry> +<entry><para> Indent selection</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>I</keycap></keycombo></para></entry> +<entry><para> Unindent selection</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>J</keycap></keycombo></para></entry> +<entry><para>Join Lines</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo></para></entry> +<entry><para> <link linkend="new">New</link> document</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>O</keycap></keycombo></para></entry> +<entry><para><link linkend="open">Open a document</link> </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>P</keycap></keycombo></para></entry> +<entry><para><link linkend="print">Print</link> </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>Q</keycap></keycombo></para></entry> +<entry><para>Quit - close active copy of editor </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>R</keycap></keycombo></para></entry> +<entry><para><link linkend="replace"> Replace</link></para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>S</keycap></keycombo></para></entry> +<entry><para>Invokes the <link +linkend="save"><guilabel>Save</guilabel></link> command.</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>U</keycap></keycombo></para></entry> +<entry><para>Uppercase</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>U</keycap></keycombo></para></entry> +<entry><para>Lowercase</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Alt;&Ctrl;<keycap>U</keycap></keycombo></para></entry> +<entry><para>Capitalize</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>V</keycap></keycombo></para></entry> +<entry><para> Paste the clipboard text into line edit. </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>W</keycap></keycombo></para></entry> +<entry><para><link linkend="close">Close</link> </para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>X</keycap></keycombo></para></entry> +<entry><para>Delete the marked text and copy it to the clipboard. +</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>Z</keycap></keycombo></para></entry> +<entry><para><link linkend="undo">Undo</link></para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></para></entry> +<entry><para><link linkend="redo">Redo</link></para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>-</keycap></keycombo></para></entry> +<entry><para>Collapse One Local Level</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>-</keycap></keycombo></para></entry> +<entry><para>Collapse Toplevel</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;<keycap>+</keycap></keycombo></para></entry> +<entry><para>Expand One Local Level</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul">&Ctrl;&Shift;<keycap>+</keycap></keycombo></para></entry> +<entry><para>Expand Toplevel</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F5</keycap></keycombo></para></entry> +<entry><para><link linkend="reload"> Reload</link></para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F6</keycap></keycombo></para></entry> +<entry><para>Show/Hide Icon Border</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F7</keycap></keycombo></para></entry> +<entry><para> Switch to Command Line</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F9</keycap></keycombo></para></entry> +<entry><para> Show/Hide Folding Markers</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F10</keycap></keycombo></para></entry> +<entry><para> Dynamic Word Wrap</para></entry> +</row> +<row> +<entry><para><keycombo +action="simul"><keycap>F11</keycap></keycombo></para></entry> +<entry><para> Show/Hide Line Numbers</para></entry> +</row> +</tbody> +</tgroup> +</informaltable> +</sect1> +</chapter> + +<chapter id="the-menu-entries"> +<title>The Menu Entries</title> + +<sect1 id="file"> +<title>The <guimenu>File</guimenu> Menu</title> + +<variablelist> + +<varlistentry> +<term id="new"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>N</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>New</guimenuitem></menuchoice></term> +<listitem> +<para> +This starts a new Document in the editor. If there is a current +document with unsaved changes the user is given a chance to save it. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="open"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Open...</guimenuitem> +</menuchoice> +</term> + +<listitem> +<!-- +This is description of a standard dialog and so should go in the UG, +with a pointer to it. In fact, I'll probably nick this very stuff for +the UG +- Phil +<para> +This command opens a file. It does this by means of a dialog box which +allows the user to navigate the file system. The dialog operates like a +small file manager. Clicking on folders displayed in the central +window directs the dialog to enter that folder - displaying its +contents. There is an entry/dropdown box which can be used to type in +directly the location and name of the file or by clicking the arrow at +the side choose from a drop down box of recently used locations. Below +this is a filter which similarly may have data entered directly or +chosen from a drop down box of recent filter types. The filter facility +lets only files that meet its specifications be displayed in the central +window. If the filter contained text such as <literal +role="extension">*.txt</literal> then only files with the <literal +role="extension">txt</literal> extension would be visible in the +selection window. Below the filter is a status bar giving information +about the number of files and subfolders within the current +folder. +</para> + +<para> +The toolbar, which is located at the top of the dialog, has left and +right arrow buttons that let the user move back and forth through +previously selected folders as well as an up arrow button for moving +up the folder tree. The button with the little house takes the user +to his or her home folder and the one with the two arrows curved in +on each other updates the view of the current folder. The flag button +lets the user set a new bookmark at the current folder or go to one +that was previously set. +</para> + +<para> +The last button on the toolbar allows you to create a new folder, and +even change some basic settings for the dialog box, and finally there is +dropdown box with a list of some commonly frequented folders. +</para> +--> +<para>Displays a standard &kde; <guilabel>Open File</guilabel> +dialog. Use the file view to select the file you want to open, and +click on <guibutton>Open</guibutton> to open it. You can find more +information about the &kde; <guilabel>Open File</guilabel> dialog in +the &kde; User Guide.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term id="open-recent"> +<menuchoice> +<guimenu>File</guimenu> +<guisubmenu>Open Recent</guisubmenu> +</menuchoice> +</term> +<listitem> +<para> +This is a shortcut to open recently saved documents. Clicking on this +item opens a list to the side of the menu with several of the most +recently saved files. Clicking on a specific file will open it in +&kwrite; - if the file still resides at the same +location. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="save"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>S</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Save</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This saves the current document. If there has already been a save of +the document then this will overwrite the previously saved file without +asking for the user's consent. If it is the first save of a new +document the save as dialog (described below) will be invoked. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="save-as"> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Save As...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This allows a document to be saved with a new file name. This is done by +means of the file dialog box described above in the <link +linkend="open">Open</link> section of this help file. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="reload"> +<menuchoice> +<shortcut> +<keycombo action="simul"><keycap>F5</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Reload</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Reloads the active file from disk. This command is useful if another program or +process has changed the file while you have it open in &kwrite;. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="print"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>P</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Print...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Opens a simple print dialog allowing the user to specify what, where, +and how to print. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="export-as-html"> +<menuchoice> +<guimenu>File</guimenu> +<guimenuitem>Export as HTML...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Export your file in HTML format so your document can be viewed as a web page. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="close"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>W</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Close</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Close the active file with this command. If you have made unsaved changes, you +will be prompted to save the file before &kwrite; closes it. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="quit"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>Q</keycap></keycombo> +</shortcut> +<guimenu>File</guimenu> +<guimenuitem>Quit</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This will close the editor window, if you have more than one instance of +&kwrite; running, through the <guimenuitem>New View</guimenuitem> or +<guimenuitem>New Window</guimenuitem> menu items, those instances will +not be closed. +</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="edit"> +<title>The <guimenu>Edit</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term id="undo"><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Undo</guimenuitem></menuchoice></term> +<listitem> +<para>This is used to eliminate or reverse the most recent user action +or operation. +<!-- +Just what constitutes such an action may be better +understood by referring to the <link linkend="group-undos">Group +Undos</link> portion of this help file. +--> +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="redo"/><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;&Shift;<keycap>Z</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Redo</guimenuitem></menuchoice></term> +<listitem> +<para>This will reverse the most recent change (if any) made using Undo</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="cut"/><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>X</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Cut</guimenuitem></menuchoice></term> +<listitem> +<para>This command deletes the current selection and places it on the +clipboard. +The clipboard is a feature of &kde; that works invisibly to provide a way to +transfer data between applications.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="copy"/><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>C</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Copy</guimenuitem></menuchoice></term> +<listitem> +<para>This copies the currently selected text to the clipboard so that it may +be pasted elsewhere. The clipboard is a feature of &kde; that works invisibly +to provide a way to transfer data between applications.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="copy-as-html"/><menuchoice> +<guimenu>Edit</guimenu><guimenuitem>Copy as +HTML</guimenuitem></menuchoice></term> +<listitem> +<para>This copies the currently selected text to the clipboard as HTML.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="paste"/><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>V</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem></menuchoice></term> +<listitem> +<para>This will insert the contents of the clipboard at the cursor position. +The clipboard is feature of &kde; that works invisibly to provide a way to +transfer data between applications.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="select-all"/><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>A</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Select All</guimenuitem></menuchoice></term> +<listitem> +<para>This will select the entire document. This could be very useful for +copying the entire file to another application.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="deselect"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>A</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu><guimenuitem>Deselect</guimenuitem></menuchoice></term> +<listitem> +<para>Deselects the selected text in the editor if any.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="block-selection-mode"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>B</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu><guimenuitem>Bloc +Selection Mode</guimenuitem></menuchoice></term> +<listitem> +<para>Toggles Selection Mode. When the Selection Mode is “BLOCK”, you can make +vertical selections, ie select column 5 to 10 in lines 9 to 15. +The status bar shows the current state of the Selection Mode, either “NORM” or +“BLK”.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="overwrite-mode"/><menuchoice> +<shortcut> +<keycombo action="simul"><keycap>Insert</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu><guimenuitem>Overwrite +Mode</guimenuitem></menuchoice></term> +<listitem> +<para>Toggles the Insert/Overwrite modes. When the mode is "INS", you +insert characters where the cursor is. When the mode is "OVR", writing +characters will replace the current characters if your cursor is positioned +before any character. The status bar shows the current state of the Overwrite +Mode, either “INS” or “OVR”.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="find"/><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>F</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Find</guimenuitem></menuchoice></term> +<listitem> +<para>This opens the find dialog which is used to specify the <guilabel>Text to +Find</guilabel> in the document. There is small text box for entering the search +pattern which also doubles as a dropdown box. Clicking on the dropdown arrow at +the side of the box makes available other recent search patterns. Other +parameters are included to make the search more efficient. Selecting +<guilabel>Case Sensitive</guilabel> will limit finds to entries that match the +case (upper or lower) of each of the characters in the search pattern. +<guilabel>Find Backwards</guilabel> directs the search to proceed in an upwardly +direction. The <guilabel>Selected Text</guilabel> option keeps the search +within currently selected text. Checking <guilabel>Whole Words Only</guilabel> +prevents the search from stopping on words that contain the searched for +pattern. The <guilabel>Search from Cursor</guilabel> option begins the search +from the current position of the cursor within the document rather than from +the beginning.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="find-again"/><menuchoice> +<shortcut><keycombo action="simul"><keycap>F3</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Find Next</guimenuitem></menuchoice></term> + <listitem> +<para>This repeats the last find operation, if any, without calling the find +dialog box. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="find-previous"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Shift;<keycap>F3</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Find Previous</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This repeats the last find operation, if any, without calling the find +dialog box, and searching backwards instead of forwards through the +document. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="replace"/><menuchoice> +<shortcut><keycombo +action="simul">&Ctrl;<keycap>R</keycap></keycombo></shortcut> +<guimenu>Edit</guimenu><guimenuitem>Replace...</guimenuitem></menuchoice></term> +<listitem> +<para>This command opens the replace dialog box. The replace dialog is +almost identical to the above-mentioned find dialog. In addition to the features +in the find dialog it contains a <guilabel>Replace With:</guilabel> text +entry/dropdown box. Using this dialog the user can specify both the text to be +found and text with which to replace it. The additional <guilabel>Prompt +On Replace</guilabel> option allows the user to have &kwrite; ask for +confirmation before each replacement. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="go-to-line"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>G</keycap></keycombo> +</shortcut> +<guimenu>Edit</guimenu> +<guimenuitem>Go to line</guimenuitem></menuchoice></term> +<listitem> +<para> +This opens the goto line dialog box which is used to have the cursor +jump to a particular line (specified by number) in the document. The +line number may be entered directly into the text box or graphically by +clicking on the up or down arrow spin controls at the side of the text +box. The little up arrow will increase the line number and the down +arrow decrease it. There is also a slide control to the right of the +text box which allows the user to move the goto point in the document in +an analog manner. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> +<sect1 id="view-menu"> +<title>The <guimenu>View</guimenu> menu</title> + +<para>The <guimenu>View</guimenu> menu allows you to manage settings +specific to the active editor, and to manage frames.</para> + +<variablelist> + +<varlistentry> +<term> +<anchor id="view-new-window"/> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>New Window</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Opens a new window with the same text.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-command-line"/> +<menuchoice> +<shortcut><keycombo +action="simul"><keycap>F7</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Switch to Command Line</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Displays the Katepart command line at the bottom of the window. +In the command line, type "help" to get help and "help list" to get a list of +commands.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-schema"/> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Schema</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>Select a font schema.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-dynamic-word-wrap"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F10</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Dynamic Word Wrap</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>The text lines will be wrapped at the view +border on the screen.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-dynamic-word-wrap-indicators"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F10</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Dynamic Word Wrap Indicators</guimenuitem> +</menuchoice> +</term> +<listitem> + <para>Choose when and how the dynamic word wrap indicators should be +displayed. This is only available if the <guilabel>Dynamic Word +Wrap</guilabel> option is checked.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-show-static-word-wrap"/> +<menuchoice> +<guimenu>View</guimenu> +<guimenuitem>Show Static Word Wrap Marker</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If this option is checked, a vertical line will be drawn at the +word wrap column as defined in the <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Editor...</guimenuitem></menuchoice> in the +Editing tab. Please note that the word wrap marker is only drawn if you +use a fixed pitch font.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-show-icon-border"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F6</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Show Icon Border</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This is a toggle item. Setting it on checked will make the +side of the active editor, and vice versa.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-show-line-numbers"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F11</keycap></keycombo></shortcut> +<guimenu>View</guimenu> +<guimenuitem>Show Line Numbers</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>This is a toggle Item. Setting it on checked will make a pane displaying +the line numbers of the document visible in the left border of the active +editor, and vice versa.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-scrollbar-marks"/> +<menuchoice> +<guimenu>View</guimenu> +<guisubmenu>Show Scrollbar Marks</guisubmenu> +</menuchoice> +</term> +<listitem> +<para>If this option is checked, the view will show marks on the vertical +scrollbar.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-hide-folding-markers"/> +<menuchoice> +<shortcut><keycombo action="simul"><keycap>F9</keycap></keycombo></shortcut> +<guimenuitem>Hide Folding Markers</guimenuitem> +</menuchoice> +</term> +<listitem> +<para>If this option is checked, the marks for code folding will be +hidden.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<anchor id="view-code-folding"/> +<menuchoice> +<guimenuitem>Code Folding</guimenuitem> +</menuchoice> +</term> +<listitem> +<variablelist> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>Ctrl</keycap> +<keycap>Shift</keycap><keycap>-</keycap></keycombo></shortcut> +<guimenuitem>Collapse Toplevel</guimenuitem></menuchoice> +</term> +<listitem><para>Collapse all toplevel regions in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>Ctrl</keycap> +<keycap>Shift</keycap><keycap>+</keycap></keycombo></shortcut> +<guimenuitem>Expand Toplevel</guimenuitem></menuchoice> +</term> +<listitem><para>Expand all toplevel regions in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>Ctrl</keycap> +<keycap>-</keycap></keycombo></shortcut> +<guimenuitem>Collapse One Local Level</guimenuitem></menuchoice> +</term> +<listitem><para>Collapse the region closest to the cursor.</para></listitem> +</varlistentry> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>Ctrl</keycap> +<keycap>+</keycap></keycombo></shortcut> +<guimenuitem>Expand One Local Level</guimenuitem></menuchoice> +</term> +<listitem><para>Expand the region closest to the cursor.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="go"> +<title>The <guimenu>Bookmarks</guimenu> Menu</title> +<variablelist> + +<varlistentry> +<term id="set-bookmark"> +<menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>B</keycap></keycombo> +</shortcut> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Set Bookmark</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Sets or removes a bookmark in the current line of the active document. (If it's +there, it is removed, otherwise one is set). +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term id="clear-bookmarks"> +<menuchoice> +<guimenu>Bookmarks</guimenu> +<guimenuitem>Clear All Bookmarks</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This command will remove all the markers from the document as well as +the list of markers which is appended at the bottom of this menu item. +</para> +</listitem> +</varlistentry> + +<varlistentry id="bookmarks-previous"> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>Alt</keycap> +<keycap>Page Up</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu><guimenuitem>Previous</guimenuitem></menuchoice> +</term> +<listitem><para>This will move the cursor to beginning of the first above line +with a bookmark. The menuitem text will include the line number and the first +piece of text on the line. This item is only available when there is a bookmark +in a line above the cursor.</para></listitem> +</varlistentry> + +<varlistentry id="bookmarks-next"> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>Alt</keycap> +<keycap>Page Down</keycap></keycombo></shortcut> +<guimenu>Bookmarks</guimenu><guimenuitem>Next</guimenuitem></menuchoice></term> +<listitem><para>This will move the cursor to beginning of the next line with a +bookmark. The menuitem text will include the line number and the first piece of +text on the line. This item is only available when there is a bookmark in a line +below the cursor.</para></listitem> +</varlistentry> + +</variablelist> + +<para> +At the bottom of this menu, a list of markers appears if any markers are +available for this window. +</para> + +</sect1> + +<sect1 id="tools"> +<title>The <guimenu>Tools</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><anchor id="tools-read-only"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Read Only Mode</guimenuitem></menuchoice></term> + <listitem> +<para>Set the current document to Read Only mode. This prevents any text +addition and any changes in the document formatting.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-filetype"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Filletype</guimenuitem></menuchoice></term> + <listitem> +<para>Choose the filetype scheme you prefer for the active document. This +overwrites the global filetype mode set in <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure +Editor...</guimenuitem></menuchoice> in the Filetypes tab for your current +document only.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-highlighting"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Highlighting</guimenuitem></menuchoice></term> + <listitem> +<para>Choose the Highlighting scheme you prefer for the active document. This +overwrites the global highlighting mode set in <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure +Editor...</guimenuitem></menuchoice> for your current document only.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-indentation"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Indentation</guimenuitem></menuchoice></term> + <listitem> +<para>Choose the style of indentation you want for your active document. +This overwrites the global indentation mode set in <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure +Editor...</guimenuitem></menuchoice> for your current document only.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-encoding"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Encoding</guimenuitem></menuchoice></term> + <listitem> +<para>You can overwrite the default encoding set in <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure +Editor...</guimenuitem></menuchoice> in the <guilabel>Open/Save</guilabel> tab +to set a different encoding for your current document. The encoding you +set here will be only valid for your current document.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-end-of-line"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>End of Line</guimenuitem></menuchoice></term> + <listitem> +<para>Choose your prefered end of line mode for your active +document. This overwrites the global end of line mode set in <menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure +Editor...</guimenuitem></menuchoice> for your current document only.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="Spelling..."/><menuchoice> +<guimenu>Tools</guimenu><guimenuitem>Spelling...</guimenuitem></menuchoice> +</term> + +<listitem><para><action>This initiates the spellchecking program - a program +designed to help the user catch and correct any spelling errors.</action> +Clicking on this entry will start the checker and bring up the speller dialog +box through which the user can control the process. There are four settings +lined up vertically in the center of the dialog with their corresponding labels +just to the left. Starting at the top they are:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Unknown word:</guilabel></term> +<listitem><para>Here, the spellchecker indicates the word currently under +consideration. This happens when the checker encounters a word not in its +dictionary - a file containing a list of correctly spelled words against which +it compares each word in the editor.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Replace with:</guilabel></term> +<listitem><para> If the checker has any similar words in its dictionary the +first one will be listed here. The user can accept the suggestion, type in his +or her own correction, or choose a different suggestion from the next +box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Suggested Words:</guilabel></term> +<listitem><para> The checker may list here a number of possible replacements for +the word under consideration. Clicking on any one of the suggestions will cause +that word to be entered in the <guilabel>Replacement:</guilabel> box, +above.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Language:</guilabel></term> +<listitem><para> If you have installed multiple dictionaries, here you can +select which dictionary/language should be used.</para></listitem> +</varlistentry> +</variablelist> + +<para>On the right side of the dialog box are 5 buttons that allow the user to +control the spellcheck process. They are:</para> + +<variablelist> +<varlistentry> +<term><guibutton>Add to Dictionary</guibutton></term> +<listitem><para>Pressing this button adds the word in the <guilabel>Misspelled +Word:</guilabel> box to the checker's dictionary. This means that in the future +the checker will always consider this word to be correctly +spelled.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Replace</guibutton></term> +<listitem><para> This button has the checker replace the word under +consideration in the document with the word in the +<guilabel>Replacement:</guilabel> box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Replace All</guibutton></term> +<listitem><para> This button causes the checker to replace not only the current +<guilabel>Unknown word:</guilabel> but to automatically make the same +substitution for any other occurrences of this <guilabel>Misspelled +Word:</guilabel> in the document.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Ignore</guibutton></term> +<listitem><para>Activating this button will have the checker move on without +making any changes.</para></listitem> +</varlistentry> +<varlistentry> +<term><guibutton>Ignore All</guibutton></term> +<listitem><para> This button tells the checker to do nothing with the current +<guilabel>Unknown word:</guilabel> and to pass over any other instances of +the same word.</para> <note><para>This only applies to the current spellcheck +run. If the checker is run again later it will stop on this same +word.</para></note></listitem> +</varlistentry> +</variablelist> + +<!--<para>Located horizontally along the bottom of the spellcheck dialog is a +progress bar. As the checking process proceeds the bar will fill from left to +right providing a graphical representation of how far along in the document the +process has reached. In addition, the progress is displayed numerically in +the center of the progress bar.</para>//--> + +<!--<note><para>A numerical display of the spellcheck +process is simultaneously displayed in the status bar of the editor. The <link +linkend="show-statusbar">status bar</link> is the horizontal strip at the bottom +of the editor just outside of the text entry area.</para></note>//--> + +<para>Three more buttons are located horizontally along the bottom of the +spellcheck dialog. They are:</para> + +<variablelist> +<varlistentry> +<term><guibutton>Help</guibutton></term> +<listitem><para> This invokes the &kde; help system starting at the &kwrite; help +pages (this document).</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Finished</guibutton></term> +<listitem><para> This button ends the spellcheck process, and returns to the +document.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Cancel</guibutton></term> +<listitem><para> This button cancels the spellcheck process, all modifications +are reverted, and you will return to your document.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<varlistentry> +<term><anchor id="tools-spelling-from-cursor"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Spelling (from cursor)...</guimenuitem></menuchoice></term> + <listitem> +<para>This initiates the spellchecking program but it starts where your cursor +is instead of at the beginning of the document.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-spellcheck-selection"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Spellcheck Selection...</guimenuitem></menuchoice></term> + <listitem> +<para>Spellchecks the current selection.</para> + </listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="indent"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>I</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu><guimenuitem>Indent</guimenuitem></menuchoice></term> +<listitem> +<para>This increases the paragraph's indentation by one step. The size of the +step depends on the <link linkend="pref-indent"> indentation +settings</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="unindent"/><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>I</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu><guimenuitem>Unindent</guimenuitem></menuchoice></term> + +<listitem> +<para>This reduces the paragraph's indentation by one step. The size of the step + +depends on the <link linkend="pref-indent"> indentation settings</link>.</para> + +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="cleanindent"/><menuchoice> +<guimenu>Tools</guimenu><guimenuitem>Clean +Indentation</guimenuitem></menuchoice></term> <listitem> +<para>This cleans the indentation for the current selection or for the +line the cursor is currently in. Cleaning the indentation ensures that +all your selected text follows the indentation mode you choose.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="tools-align"/><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Align</guimenuitem> +</menuchoice></term> +<listitem> +<para>Causes a realign of the current line or selected lines using the +indentation mode and indentation settings in the doucment.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Comment</guimenuitem> +</menuchoice></term> +<listitem><para>This adds one space to the beginning of the line +where the text cursor is located or to the beginning of any +selected lines.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>D</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Uncomment</guimenuitem> +</menuchoice></term> +<listitem><para>This removes one space (if any exist) from the beginning of the +line where the text cursor is located or from the beginning of any +selected lines.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Uppercase</guimenuitem> +</menuchoice></term> +<listitem><para>Put the selected text or the letter after the cursor in +uppercase.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;&Shift;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Lowercase</guimenuitem> +</menuchoice></term> +<listitem><para>Put the selected text or the letter after the cursor in +lowercase.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Alt;&Ctrl;<keycap>U</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Capitalize</guimenuitem> +</menuchoice></term> +<listitem><para>Capitalize the selected text or the current +word.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<shortcut> +<keycombo action="simul">&Ctrl;<keycap>J</keycap></keycombo> +</shortcut> +<guimenu>Tools</guimenu> +<guimenuitem>Join Lines</guimenuitem> +</menuchoice></term> +<listitem><para>Joins the selected lines, or the current line and the line below +with one white space character as a separator. Leading/trailing white space on +joined lines is removed in the affected ends.</para></listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Word Wrap Document</guimenuitem> +</menuchoice></term> +<listitem><para>Apply static word wrapping on all the document. That means that +a new line of text will automatically start when the current +line exceeds the length specified by the Wrap words at: option +in the Editing tab in <menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure +Editor...</guimenuitem></menuchoice></para></listitem> +</varlistentry> + +</variablelist> + + +</sect1> + +<sect1 id="settings"> +<title>The <guimenu>Settings</guimenu> Menu</title> + +<variablelist> +<varlistentry> +<term><anchor id="show-toolbar"/><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Show Toolbar</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +When checked, this displays a movable toolbar containing buttons used to +initiate frequently used commands. When unchecked the toolbar is hidden. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="show-statusbar"/><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Show +Statusbar</guimenuitem></menuchoice></term> +<listitem> +<para>When checked, this displays a small bar at the bottom of the editor +containing information about the status of the current document. When unchecked +the statusbar is hidden.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="show-path"/><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Show +Path</guimenuitem></menuchoice></term> +<listitem> +<para>When selected, this displays in the titlebar the path (its location in the +file system) of the current document. When unchecked the path is hidden.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="preferences"/><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Configure Editor...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This menu item opens a dialog whereby several different <link +linkend="pref-dialog">settings</link> may be adjusted. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="choose-editor"/><menuchoice> +<guimenu>Settings</guimenu> +<guimenuitem>Choose Editor...</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Choose the default text editing component that you wish to use in &kwrite;. You +can choose <guilabel>System Default</guilabel>, <guilabel>Embedded +Advanced Text Editor</guilabel> or <guilabel>&Qt; Designer Based +Text Editor</guilabel> (note that the &Qt; Designer Based Text Editor is +only available if you have KDevelop installed on your system). If you choose +<guilabel>System Default</guilabel>, &kwrite; will honor your changes in +&kcontrolcenter;. All other choices will override that setting. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="configure-keybindings"/><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure +Shortcuts...</guimenuitem></menuchoice></term> +<listitem> +<para>This command opens a dialog box whereby the <link +linkend="keybindings">shortcuts</link> may be changed. A display window at the +top of the dialog box shows the list of commands (actions) that can have +keyboard shortcuts. Below the display are three radio buttons. The user may +choose between No Key, Default Key, and Custom Key. (Note that a set of radio +buttons only allows the selection of one of the offered items - in the way that +buttons on a car radio only offer the selection of one preset station. Also, +the Default Key selection is only available for those commands that actually +have a 'default' shortcut.) Selecting the Custom Key option activates the three +check boxes and key button at the bottom of the dialog. The user may then select +a key combination for the command in question by means of the check boxes and +key button. For example, with the About &kde; command selected in the display +window, the user could select &Ctrl; and <keycap>Alt</keycap>, click on the key +button, and then press the <keycap>K</keycap> key on the keyboard. This would +mean that anytime he or she held down the &Ctrl; and <keycap>Alt</keycap> +buttons and pressed <keycap>K</keycap> (while using +&kwrite;) the About &kde; display box would be called. </para> +</listitem> +</varlistentry> + +<varlistentry> +<term><anchor id="configure-toolbars"/><menuchoice> +<guimenu>Settings</guimenu><guimenuitem>Configure +Toolbars...</guimenuitem></menuchoice></term> +<listitem><para>This will open the dialog whereby the toolbar configuration may +be changed. The user can choose which shortcut buttons should appear on the +toolbar. A display window on the left lists the commands available to placed +on the toolbar. A display on the right lists those commands already on the +toolbar. A set of four arrow buttons between the two displays manipulates the +selections. The right pointing arrow places any command selected in the left +pane onto the right pane, <abbrev>i.e.</abbrev>, it is added to the toolbar. +The left arrow does just the opposite, removing any action selected in the right + +window from the toolbar. The up and down pointing arrows change the position of + +an action selected in the right window which changes the position of its button + +in the toolbar.</para> </listitem> +</varlistentry> + + + +<!-- +<varlistentry> +<term> +<menuchoice><guimenu>>Settings</guimenu><guimenuitem>Configure +Highlighting</guimenuitem></menuchoice></term> +<listitem><para>Opens a dialog box allowing configuration of the syntax +highlighting. The dialog is described in <xref +linkend="pref-highlighting"/>.</para></listitem> +</varlistentry> --> + +<!--<varlistentry> +<term> +<menuchoice> +<shortcut> +<keycombo action="simul"><keycap>F6</keycap></keycombo> +</shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Show Icon Border</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +Toggle the display of a border on the left of the editing window, where +bookmarks are displayed next to the line they apply to. +</para> +</listitem> +</varlistentry>//--> + +<!--<varlistentry> +<term id="vertical-selection"> +<menuchoice> +<shortcut> +<keycombo action="simul"><keycap>F4</keycap></keycombo> +</shortcut> +<guimenu>Settings</guimenu> +<guimenuitem>Vertical Selection</guimenuitem> +</menuchoice> +</term> +<listitem> +<para> +This is used to turn on or off the vertical selection feature. Vertical +selection allows text to be selected by column as well as by row. In other +words with this feature the user is able to select text contained in only +particular contiguous columns and rows. In affect the user can select a +rectangular area of text anywhere in the document. +</para> +</listitem> +</varlistentry> //--> + +<!--<varlistentry> +<term id="set-highlight"> +<menuchoice> +<guimenu>Settings</guimenu> +<guisubmenu>Highlight Mode</guisubmenu> +</menuchoice> +</term> +<listitem> +<para> +This allows the user to choose the style of color highlighting which the +editor uses to display the text. The styles are selected by programming +language. The font/color information is not stored with the document. +</para> +</listitem> +</varlistentry> //--> + +<!--<varlistentry> +<term><anchor id="end-of-line"/> +<menuchoice> +<guimenu>Settings</guimenu><guisubmenu>End of +Line</guisubmenu></menuchoice></term> +<listitem> +<para>This opens a sub-menu from which the user can select the type of +<quote>end of +line</quote> code for &kwrite; to use, <abbrev>i.e.</abbrev>, the accepted +standard +used by &UNIX;, &Mac; or MSDOS/&Windows; systems.</para> +</listitem> +</varlistentry> //--> + +</variablelist> +</sect1> + +<sect1 id="help"> +<title>The <guimenu>Help</guimenu> Menu</title> + +&help.menu.documentation; + +</sect1> +</chapter> + +<chapter id="pref-dialog"> +<title>Configure &kwrite;</title> + +<para> +Selecting <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Editor...</guimenuitem></menuchoice> from the menu brings up the +<guilabel>Configure Editor</guilabel> dialog box. This dialog can be +used to alter a number of different settings. The settings available +for change vary according to which category the user chooses from a +vertical list on the left side of the dialog. By means of three buttons +along the bottom of the box the user can control the process. +</para> + +<para> +She or he may invoke the <guilabel>Help</guilabel> system, accept the +current settings and close the dialog by means of the +<guibutton>OK</guibutton> button, or <guibutton>Cancel</guibutton> the +process. The categories <guilabel>Colors</guilabel>, +<guilabel>Fonts</guilabel> <guilabel>Indent</guilabel>, +<guilabel>Select</guilabel>, <guilabel>Edit</guilabel>, +<guilabel>Spelling</guilabel> and <guilabel>Highlighting</guilabel> are +detailed below. +</para> + +<sect1 id="appearance"> +<title>Appearance</title> + +<variablelist> +<varlistentry> +<term><guilabel>Word Wrap</guilabel></term> +<listitem> +<variablelist> +<varlistentry id="appearance-settings"> +<term><guilabel>Dynamic word wrap</guilabel></term> +<listitem><para>If this option is checked, the text lines +will be wrapped at the view border on the screen.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Dynamic word wrap indicators</guilabel></term> +<listitem><para>Choose when the Dynamic word wrap indicators +should be displayed. +</para></listitem></varlistentry> +<varlistentry> +<term><guilabel>Vertically align dynamically wrapped lines +to indentation depth: +</guilabel></term> +<listitem><para>Enables the start of dynamically wrapped +lines to be aligned vertically to the indentation level of the first +line. This can help to make code and markup more +readable.</para><para>Additionally, this allows you to +set a maximum width of the screen, as a percentage, +after which dynamically wrapped lines will no longer be vertically aligned. +For example, at 50%, lines whose indentation levels are deeper than 50% of the +width of the screen will not have vertical alignment applied to subsequent +wrapped lines.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Code Folding</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Show folding markers (if available) +</guilabel></term> +<listitem><para>If this option is checked, the current view will display marks +for code folding, if code folding is available.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Borders</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Show icon border +</guilabel></term> +<listitem><para>If this is checked, you will see an icon border on the left +hand side. The icon border shows bookmark signs for instance.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show line numbers +</guilabel></term> +<listitem><para>If this is checked, you will see line numbers on the left +hand side.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show scrollbar marks +</guilabel></term> +<listitem><para>If this option is checked the current view +will show marks on the vertical scrollbar. These marks will +for instance show bookmarks.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Sort Bookmarks Menu +</guilabel></term> +<listitem><para> +<variablelist> +<varlistentry> +<term><guilabel>By position +</guilabel></term> +<listitem><para>The bookmarks will be ordered by the line +numbers they are placed at.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>By creation +</guilabel></term> +<listitem><para>Each new bookmark will be added to the bottom, +independently from where it is placed in the document.</para></listitem> +</varlistentry> +</variablelist> +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Show identation lines +</guilabel></term> +<listitem><para>If this is checked, the editor wil display +vertical lines to help identifying indent lines.</para></listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="prefcolors"> +<title>Fonts & Colors</title> + +<para>This section of the dialog lets you configure all fonts and colors in +any color scheme you have, as well creating new schemes or deleting existing +ones. Each scheme has settings for colors, fonts and normal and highlight text +styles. +</para> + +<para>&kwrite; will preselect the currently active scheme for you, if you want to +work on a different scheme start by selecting that from the +<guilabel>Schema</guilabel> combobox.</para> + +<sect2 id="prefcolors-colors"> +<title>Colors</title> + +<variablelist> +<varlistentry id="prefcolors-colors-text-background"> +<term><guilabel>Text Area Background</guilabel></term> +<listitem> + +<variablelist> + +<varlistentry id="pref-colors-normal-text"> +<term><guilabel>Normal text</guilabel></term> +<listitem><para>This is the default background for the editor area, it will be +the dominant color on the editor area.</para></listitem> +</varlistentry> + +<varlistentry id="pref-colors-selected-text"> +<term><guilabel>Selected Text</guilabel></term> +<listitem><para>This is the background for selected text. The default is +the global selection color, as set in your &kde; color preferences. +</para></listitem> +</varlistentry> + +<varlistentry id="pref-colors-current-line"> +<term><guilabel>Current Line</guilabel></term> +<listitem><para>Set the color for the current line. Setting this a bit different +from the Normal text background helps to keep focus on the current line. +</para></listitem> +</varlistentry> + +<varlistentry id="pref-colors-marks"> +<term><guilabel>Bookmark</guilabel></term> +<listitem><para>This combo lets you set overlay colors for various mark types. +The color is mixed into the background color of a marked line, so that a line +with more marks or a marked line that is current has a background that is a mix +of more colors. The mark colors are also used if you enable display of scrollbar +marks.</para></listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +<varlistentry id="prefcolors-colors-other-elements"> +<term><guilabel>Other Elements</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Left Border Background</guilabel></term> +<listitem><para>This color is used for the marks, line numbers and folding +marker borders in the left side of the editor view when they are displayed. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Line Numbers</guilabel></term> +<listitem><para>This color is used to draw the line numbers on the left side of +the view when displayed.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Bracket Highlight</guilabel></term> +<listitem><para>This color is used to draw the background of matching brackets. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Word Wrap Markers</guilabel></term> +<listitem><para>This color is used to draw a pattern to the left of dynamically +wrapped lines when those are aligned vertically, as well as for the static word +wrap marker.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Tab Markers</guilabel></term> +<listitem><para>This color is used to draw white space indicators when enabled. +</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="prefcolors-fonts"> +<title>Fonts</title> +<para> +Here you can choose the font for the schema. You can choose from +any font available on your system, and set a default size. A sample text +displays at the bottom of the dialog, so you can see the effect of your choices. +</para> +</sect2> + +<sect2 id="prefcolors-normal-text-styles"> +<title>Normal Text Styles</title> +<para>The normal text styles are inherited by the highlight text styles, +allowing the editor to present text in a very consistent way, for example comment +text is using the same style in allmost all of the text formats that kate can +highlight.</para> +<para>The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. +</para> +<para>Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu.</para> +</sect2> + +<sect2 id="prefcolors-highlighting-text-styles"> +<title>Highlighting Text Styles</title> +<para>Here you can edit the text styles used by a specific highlight definition. +The editor preselects the highlight used by your current document. To work on a +different highlight, select one in the <guilabel>Highlight</guilabel> combobox +above the style list. +</para> +<para>The name in the list of styles is using the style configured for +the item, providing you with an immediate preview when configuring a style. +</para> +<para>Each style lets you select common attributes as well as foreground +and background colors. To unset a background color, rightclick to use the +context menu. In addition you can see if a style is equal to the default style +used for the item, and set it to that if not.</para> +<para>You will notice that many highlights contain other highlights represented +by groups in the style list. For example most highlights import the Alert +highlight, and many source code formats imports the Doxygen highlight. Editing +colors in those groups only affects the styles when used in the edited highlight +format. +</para> +</sect2> + +</sect1> + +<sect1 id="pref-cursor-selection"> +<title>Cursor & Selection</title> + +<variablelist> + +<varlistentry> +<term><guilabel>Text Cursor Movement</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Smart home</guilabel></term> +<listitem> +<para>When selected, pressing the home key will cause the cursor to +skip white space and go to the start of a line's text.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Wrap cursor</guilabel></term> +<listitem> +<para>When on, moving the insertion cursor using the <emphasis +role="bold">Left</emphasis> and <emphasis role="bold">Right</emphasis> keys will +go on to previous/next line at beginning/end of the line, similar to most +editors.</para><para>When off, the insertion cursor cannot be moved left of the +line start, but it can be moved off the line end, which can be very handy for +programmers. When this option is chosen, moving the cursor with the arrow keys +off the end of a line (to the right) causes it to jump down to the beginning of +the next line. Likewise when the cursor is moved past the beginning of a line +(to the left) it jumps up to the end of the preceding line. When this option is +not selected, moving the cursor right past the end of a line merely causes it to +continue horizontally in the same line and trying to move it left past the +beginning does nothing.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Page Up/Page Down moves cursor</guilabel></term> +<listitem> +<para>This option changes the behavior of the cursor when the user presses +the <keycap>Page Up</keycap> or <keycap>Page Down</keycap> key. If unselected +the text cursor will maintain its relative position within the visible text in +&kwrite; as new text becomes visible as a result of the operation. So if the +cursor is in the middle of the visible text when the operation occurs it will +remain there (except when one reaches the beginning or end.) With this option +selected, the first key press will cause the cursor to move to either the top or +bottom of the visible text as a new page of text is displayed.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Autocenter cursor (lines):</guilabel></term> +<listitem> +<para>Sets the number of lines to maintain visible above and below the cursor +when possible.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Selection Mode</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Normal</guilabel></term> +<listitem> +<para>Selections will be overwritten by typed text and will be lost on +cursor movement.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Persistent</guilabel></term> +<listitem> +<para>Selections will stay even after cursor movement and typing.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect1> + +<sect1 id="pref-edit"> +<title>Editing</title> +<variablelist> + +<varlistentry> +<term><guilabel>Tabulators</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Insert spaces instead of tabulators</guilabel></term> +<listitem> +<para>When this is enabled the editor will insert a calculated number of spaces +according to the position in the text and the <option>tab-width</option> setting +when you press the <keycap>TAB</keycap> key.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show tabulators</guilabel></term> +<listitem> +<para>When this is enabled &kwrite; will display a small dot as a visual +representation of tabulator characters.</para> +<note><para>This also causes dots to be drawn to indicate trailing white space. +This will be fixed in a future version of &kwrite;</para></note> +</listitem> +</varlistentry> +<varlistentry> +<term id="pref-tab-width">Tab Width</term> <listitem><para>If the +<link linkend="pref-word-wrap"><guilabel>Replace Tabs By +Spaces</guilabel></link> +option is selected this entry determines the number of +spaces with which the editor will automatically replace +tabs.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term id="pref-word-wrap"><guilabel>Static Word Wrap</guilabel></term> +<listitem><para> +Word wrap is a feature that causes the editor to automatically start a new line +of text and move (wrap) the cursor to the beginning of that new line. &kwrite; +will automatically start a new line of text when the current line reaches the +length specified by the <link linkend="pref-wrap-words-at">Wrap Words +At:</link> option.</para> +<variablelist> +<varlistentry> +<term><guilabel>Enable static word wrap</guilabel></term> +<listitem> +<para>Turns static word wrap on or off.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show static word wrap markers +(if applicable)</guilabel></term> +<listitem> +<para>If this option is checked, a vertical line will be drawn at the word wrap +column as defined in the <menuchoice> <guimenu>Settings</guimenu> +<guimenuitem>Configure Editor...</guimenuitem></menuchoice> in the Editing tab. +Please note that the word wrap marker is only drawn if you use a fixed pitch +font.</para> +</listitem> +</varlistentry> +<varlistentry> +<term id="pref-wrap-words-at"><guilabel>Wrap words at:</guilabel></term> +<listitem> +<para>If the <link linkend="pref-word-wrap">Word Wrap</link> option is selected +this entry determines the length (in characters) at which the editor will +automatically start a new line.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Remove Trailing Spaces</guilabel></term> +<listitem><para>&kwrite; will automatically eliminate extra spaces +at the ends of lines of text.</para></listitem> </varlistentry> + +<varlistentry> +<term><guilabel>Auto Brackets</guilabel></term> <listitem><para>When +the user types a left bracket ([, (, or {) &kwrite; automatically enters the +right bracket (}, ), or ]) to the right of the cursor.</para></listitem> +</varlistentry> + +<varlistentry> <term>Maximum <link linkend="undo">undo</link> steps:</term> +<listitem><para>Here the user may specify the number of steps &kwrite; will +retain in memory for purposes of undoing entries and actions. This means that +the higher the number of steps set the more memory &kwrite; will use for this. +Setting this entry to 10 would mean that the user would be be able reverse the +last ten operations, <abbrev>i.e.</abbrev> click the <guibutton>undo</guibutton> +button 10 times and obtain results.</para></listitem> </varlistentry> + +<varlistentry> <term>Smart search text from:</term> +<listitem><para>This determines where &kwrite; will get the search +text from (this will be automatically entered into the Find Text +dialog): +<itemizedlist> +<listitem><para><emphasis role="bold">Nowhere:</emphasis> Don't guess the search +text.</para></listitem> +<listitem><para><emphasis role="bold">Selection Only:</emphasis> Use + the current text selection, if available. </para></listitem> +<listitem><para><emphasis role="bold">Selection, then Current Word:</emphasis> +Use the current selection if available, otherwise use the current word. +</para></listitem> +<listitem><para><emphasis role="bold">Current Word +Only:</emphasis> Use the word that the cursor is currently resting on, if +available. </para></listitem> +<listitem><para><emphasis role="bold">Current Word, then Selection:</emphasis> +Use the current word if available, otherwise use the current selection. +</para></listitem> +</itemizedlist> +Note that, in all the above modes, if a +search string has not been or cannot be determined, then the Find Text Dialog +will fall back to the last search text. +</para></listitem> +</varlistentry> +<!--<varlistentry> +<term id="pref-replace-tabs-by-spaces"><guilabel>Replace Tabs By +Spaces</guilabel></term> <listitem><para>&kwrite; will replace any tabs with +the number of spaces indicated in the <link linkend="pref-tab-width">Tab +Width:</link> entry.</para></listitem> </varlistentry> + +<varlistentry> <term><guilabel>Show Tabs</guilabel></term> +<listitem><para>The editor will display a symbol to indicate +the presence +of a tab in the text.</para></listitem> +</varlistentry> --> +</variablelist> +</sect1> + +<sect1 id="pref-indent"> +<title>Indentation</title> +<variablelist> +<varlistentry> +<term><guilabel>Automatic indentation</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Indentation mode:</guilabel></term> +<listitem> +<para>Select the automatic indentation mode you want to use as default. It is +strongly recommended to use <userinput>None</userinput> or +<userinput>Normal</userinput>here, and use filetype configurations to set other +indentation modes for text formats like C/C++ code or &XML;.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Insert leading Doxygen "*" when typing</guilabel></term> +<listitem> +<para>Automatically insert a leading "*" while typing within a doxygen +style comment. This setting is only enabled when applicable.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Indentation with Spaces</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Use spaces instead of tabs to indent</guilabel></term> +<listitem> +<para>This replaces tabs with the number of spaces set in <guilabel>Number of +spaces:</guilabel> below.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Emacs style mixed mode</guilabel></term> +<listitem> +<para>Use a mix of tabs and space characters for indentation.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Number of spaces:</guilabel></term> +<listitem> +<para>Set the number of spaces you want to use for indentation when you +check <guilabel>Use spaces instead of tabs to indent</guilabel> +above.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep Indent Profile</guilabel></term> +<listitem><para>When this is enabled, the editor will not unindent lines in a +selection further when the line with the least indentation becomes unindented. +If you sometimes unindent blocks of indented code, this may be helpful. +</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keep Extra Spaces</guilabel></term> +<listitem><para>Indentations of more than the selected number of spaces +will not be shortened.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Keys to use</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Tab key indents</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>tab</keycap></keycombo> key to be used to indent.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Backspace key indent</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>backspace</keycap></keycombo> key to be used to +indent.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Tab Key Mode if Nothing Selected</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Insert indent characters</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key insert indent +characters.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Insert tab character</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key insert a tab.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Indent current line</guilabel></term> +<listitem> +<para>This allows the <keycombo +action="simul"><keycap>Tab</keycap></keycombo> key indent the current +line.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<!--<varlistentry> +<term><guilabel>Auto Indent</guilabel></term> <listitem><para>This causes +new lines to begin with the same indentation level as the previous +line.</para></listitem> +</varlistentry> --> +</variablelist> +</sect1> + +<sect1 id="pref-open-save"> +<title>Open & Save</title> + +<variablelist> + +<varlistentry> +<term><guilabel>File Format</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Encoding:</guilabel></term> +<listitem> +<para>This sets the default character encoding for your files.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>End of line:</guilabel></term> +<listitem> +<para>Choose your prefered end of line mode for your active +document. You have the choice between &UNIX;, DOS/&Windows; or Macintosh.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Automatic end of line detection</guilabel></term> +<listitem> +<para>Check this if you want the editor to autodetect the end of line +type. The first found end of line type will be used for the whole file.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Memory Usage</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Maximum loaded blocks per file:</guilabel></term> +<listitem> +<para>The editor will load given number of blocks (of around 2048 lines) of +text into memory; if the filesize is bigger than this the other blocks +are swapped to disk and loaded transparently as-needed.</para> +<para>This can cause little delays while navigating in the document; a +larger block count increases the editing speed at the cost of memory. +</para><para>For normal usage, just choose the highest possible block count: +limit it only if you have problems with the memory usage.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Automatic Cleanups on Load/Save</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Remove trailing spaces</guilabel></term> +<listitem> +<para>The editor will automatically eliminate extra spaces at the ends of lines +of text while loading/saving the file.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Folder Config File</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>Search depth for config file:</guilabel></term> +<listitem> +<para>The editor will search the given number of folder levels upwards +for &kwrite; config file and load the settings line from it.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Backup on Save</guilabel></term> +<listitem><para>Backing up on save will cause &kwrite; to copy the disk file to +<prefix><filename><suffix>' before saving changes. +The suffix defaults to <emphasis role="bold">~</emphasis> and prefix is empty by +default. </para> +<variablelist> +<varlistentry> +<term><guilabel>Local files</guilabel></term> +<listitem> +<para>Check this if you want backups of local files when +saving.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Remote files</guilabel></term> +<listitem> +<para>Check this if you want backups of remote files when saving.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Prefix</guilabel></term> +<listitem> +<para>Enter the prefix to prepend to the backup file names.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Suffix</guilabel></term> +<listitem> +<para>Enter the suffix to add to the backup file names.</para> +</listitem> +</varlistentry> + +</variablelist> +</listitem> +</varlistentry> + +</variablelist> +</sect1> + +<sect1 id="pref-highlighting"> +<title>Highlighting</title> +<para>This group of options is used to customize the highlighting styles for +each programming language type. Any changes you made in other areas of this +dialog apply only to this type.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Highlight:</guilabel></term> +<listitem><para>This is used to choose the language type to +configure.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Informations</guilabel></term> +<listitem> +<para> +View the properties of the chosen language highlighting rules: +author name and license. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Properties</guilabel></term> +<listitem> +<variablelist> +<varlistentry> +<term><guilabel>File extensions:</guilabel></term> +<listitem><para>This is the list of file extensions used to determine which +files to highlight using the current syntax highlight mode.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>MIME types:</guilabel></term> +<listitem><para>Clicking the wizard button will display a dialog with a list of +all available mime types to choose from.</para><para>The <emphasis +role="bold">File Extensions</emphasis> entry will automatically be edited as +well.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Priority:</guilabel></term> +<listitem><para>Set the priority of the highlight rule.</para></listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Download...</guibutton></term> +<listitem> +<para> +Click this button to download new or updated syntax highlight descriptions +from the &kate; website. +</para> +</listitem> +</varlistentry> + +</variablelist> +<!-- obsolete annma 24 December 2005 +<para>The <guilabel>Configure +Highlighting</guilabel> dialog consists of +two pages, <guilabel>Defaults</guilabel> and <guilabel>Highlighting +Modes</guilabel>. The user can select which page to view by +clicking on the appropriate tab at the top of the dialog</para> + +<para>Items available on the <guilabel>Defaults</guilabel> page are as +follows:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Default Item Styles</guilabel></term> +<listitem> +<para> +The user can configure the default appearance for +particular items. This would allow a programmer to more easily identify +different items (types of entries) in his or her code. +</para> + +<variablelist> +<varlistentry> +<term><guilabel>Item</guilabel></term> +<listitem><para>This drop down box offers a variety of items that the user +might want to highlight. They include <guilabel>Normal</guilabel> for +text does not fit in any of the other categories, <guilabel>Comment</guilabel>, +<guilabel>String</guilabel>, <guilabel>Keyword</guilabel> and many more. Not +all of these entries will need to be configured for every language and so may be +selected as needed. The options in the rest of this section apply +to the entry selected in this box.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Normal</guilabel></term> +<listitem><para>This allows the user to choose the +item's normal (unselected) color. This is done by means +of a color selection dialog box, a further explanation of which +may be found in the <link linkend="prefcolors">Colors</link> section of <link +linkend="pref-dialog">Configure &kwrite;</link>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Bold</guilabel></term> +<listitem><para>This option determines whether or +not the item should be displayed in bold text.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Italic</guilabel></term> +<listitem><para>This option determines whether or +not the item should be displayed in italic text.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Selected</guilabel></term> +<listitem><para>This allows the user to choose the +item's color when selected. This is done by means of a +color selection dialog box, a further explanation of which +may be found in the <link linkend="prefcolors">Colors</link> section of <link +linkend="pref-dialog">Configure &kwrite;</link>.</para> +</listitem> +</varlistentry> +</variablelist> +</listitem> +</varlistentry> +</variablelist> + +<para>Items on the <guilabel>Highlight Modes</guilabel> tab allow the +user to define more specific highlighting depending on the language +style.</para> + +<para>One need not set every available option, items not configured +specifically will use the default configuration specified on the +previous <guilabel>Defaults</guilabel> tab.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Config Select</guilabel></term> +<listitem><para>This group of options is used to customize the +highlighting styles for each programming language type. Any changes you +made in other areas of this dialog apply only to this +type.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Highlight</guilabel></term> +<listitem><para>This is used to choose the language +type to configure</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Item</guilabel></term> +<listitem><para>This is to choose the syntax item to +configure. Remember this only configures +<emphasis>this</emphasis> item for +<emphasis>this</emphasis> +language.</para></listitem> +</varlistentry> +</variablelist> + +<para>As an example, if the user wished to configure the +appearance of <quote>comments</quote> while writing C++, she or he +could choose C++ in the <guilabel>Highlight</guilabel> drop down box, and then +choose Comment in the <guilabel>Item</guilabel> drop down box. To have +<quote>comments</quote> look the same across all languages, the user would need +to configure this in the <guilabel>Defaults</guilabel> page of this dialog box +while leaving <quote>comments</quote> unconfigured within the more +specific <guilabel>Highlight Modes</guilabel> page.</para> +</listitem> </varlistentry> + +<varlistentry> +<term><guilabel>Item Style</guilabel></term> +<listitem><para>Here the user can configure the general +appearance of the above +selected item. Checking the +<guilabel>Default</guilabel> check box causes the +default style as configured on the previous tab to be set, or +the appearance can be configured directly. The available +options are the same as on the +<guilabel>Defaults</guilabel> tab: +<guilabel>Normal</guilabel>, +<guilabel>Selected</guilabel>, <guilabel>Bold</guilabel> +and <guilabel>Italic</guilabel>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Highlight Auto Select</guilabel></term> +<listitem><para>&kwrite; can apply syntax highlighting +automatically, depending on the file extension or mime-type of the opened file. +The defaults are fairly comprehensive, but users that regularly edit files with +non-standard extensions can add them here. Wildcards are allowed in the +<guilabel>File Extensions</guilabel> text box. For example, the +default entry for the C++ language is +<userinput>*.cpp;*.cc;*.C;*.h</userinput>. Opening a file called +<filename>foo.h</filename> would automatically apply the +C++ style to it. +</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Item Font</guilabel></term> +<listitem><para>Here the user can choose the font for the +selected item.</para> +<para>The default style can be applied by checking the +<guilabel>Default</guilabel> check box or the user can +choose a specific font +<guilabel>Family</guilabel>, <guilabel>Size</guilabel> +and <guilabel>Charset</guilabel>. The available options are +the same as those on the <guilabel>Defaults</guilabel> tab.</para></listitem> +</varlistentry> +</variablelist>--> +</sect1> + +<sect1 id="pref-filetypes"> +<title>Filetypes</title> +<para>This page allows you to override the default configuration for documents +of specified mimetypes. When the editor loads a document, it will try if it +matches the file masks or mimetypes for one of the defined filetypes, and if so +apply the variables defined. If more filetypes match, the one with the highest +priority will be used. +</para> +<variablelist> +<varlistentry> +<term><guilabel>Filetype:</guilabel></term> +<listitem><para>The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are +also listed.</para> +<variablelist> +<varlistentry> +<term><guilabel>New</guilabel></term> +<listitem><para>This is used to create a new filetype. After +you click on this button, the fields below get empty and you +can fill the properties you want for the new filetype.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Delete</guilabel></term> +<listitem><para>To remove an existing filetype, select it from the drop down +box and press the Delete button.</para></listitem> +</varlistentry> +</variablelist> +</listitem> </varlistentry> + +<varlistentry> +<term><guilabel>Properties of current filetype</guilabel></term> +<listitem><para>The filetype with the highest priority is the one displayed in +the first drop down box. If more filetypes were found, they are also +listed.</para> +<variablelist> +<varlistentry> +<term><guilabel>Name:</guilabel></term> +<listitem><para>The name of the filetype will be the text of the corresponding +menu item. This name is displayed in the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem> +</menuchoice ></para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Section:</guilabel></term> +<listitem><para>The section name is used to organize the file types in +menus. This is also used in the +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Filetypes</guimenuitem> +</menuchoice> menu.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Variables:</guilabel></term> +<listitem><para>This string allows you to configure &kwrite;'s settings for the +files selected by this mimetype using &kwrite; variables. You can set almost any +configuration option, such as highlight, indent-mode, encoding, +etc.</para><para>For a full list of known variables, see the +manual.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>File extensions:</guilabel></term> +<listitem><para>The wildcards mask allows you to select files by filename. A +typical mask uses an asterisk and the file extension, for example +<filename>*.txt; *.text</filename>. The string is a semicolon-separated list of +masks.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>MIME types:</guilabel></term> +<listitem><para>Displays a wizard that helps you easily select +mimetypes.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Priority:</guilabel></term> +<listitem><para>Sets a priority for this file type. If more than one file type +selects the same file, the one with the highest priority will be +used.</para></listitem> +</varlistentry> +</variablelist> +</listitem> </varlistentry> + +</variablelist> +</sect1> + +<sect1 id="pref-shortcuts"> +<title>Shortcuts</title> +<para>You can change here the shortcut keys configuration. Select an +action and click on <guilabel>Custom</guilabel> if you want a different shortcut +for this action.</para> +<para>The search line alllows you to look for a specific action and see +its associated shortcut.</para> +</sect1> + +<sect1 id="pref-plugins"> +<title>Plugins</title> +<para>This tab lists all available plugins and you can check those you +want to use. Once a plugin is checked, the +<guibutton>Configure</guibutton> button is enabled and you can click it +in order to configure the highlighted plugin.</para> +</sect1> +</chapter> + +<chapter id="credits"> +<title>Credits and Licenses</title> + +<para>&kwrite; Copyright 2001 by the &kate; team.</para> + +<para> +Based on the original &kwrite;, which was Copyright 2000 by Jochen Wilhelmy +<email>[email protected]</email> +</para> + +<para>Contributions:</para> + +<itemizedlist> +<listitem> +<para>&Christoph.Cullmann; &Christoph.Cullmann.mail;</para> +</listitem> + +<listitem> +<para>Michael Bartl <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Phlip <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>&Anders.Lund; &Anders.Lund.mail;</para> +</listitem> + +<listitem> +<para>Matt Newell <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>&Joseph.Wenninger; &Joseph.Wenninger.mail;</para> +</listitem> + +<listitem> +<para>Jochen Wilhely <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>&Michael.Koch; &Michael.Koch.mail;</para> +</listitem> + +<listitem> +<para>&Christian.Gebauer; &Christian.Gebauer.mail;</para> +</listitem> + +<listitem> +<para>&Simon.Hausmann; &Simon.Hausmann.mail;</para> +</listitem> + +<listitem> +<para>Glen Parker <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>Scott Manson <email>[email protected]</email></para> +</listitem> + +<listitem> +<para>&John.Firebaugh; &John.Firebaugh.mail;</para> +</listitem> +</itemizedlist> + +<para> +Original documentation by &Thad.McGinnis; &Thad.McGinnis.mail; +</para> + +<para> +Updated by &Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; and +&Anders.Lund; &Anders.Lund.mail; +</para> + +<para> +This version of the &kwrite; Handbook is based on the original by +&Cristian.Tibirna; &Cristian.Tibirna.mail; +</para> + +<para> +Converted to docbook/proofreading by &Lauri.Watts; &Lauri.Watts.mail; +</para> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +&underGPL; +</chapter> + +&documentation.index; +</book> +<!-- +Local Variables: +mode: sgml +sgml-namecase-general: t +sgml-namecase-entity: nil +sgml-general-insert-case: lower +sgml-minimize-attributes: nil +sgml-omittag: nil +End: +--> + diff --git a/doc/kxkb/Makefile.am b/doc/kxkb/Makefile.am new file mode 100644 index 000000000..085981d9b --- /dev/null +++ b/doc/kxkb/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = AUTO + diff --git a/doc/kxkb/index.docbook b/doc/kxkb/index.docbook new file mode 100644 index 000000000..6f3673aba --- /dev/null +++ b/doc/kxkb/index.docbook @@ -0,0 +1,358 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kxkb;"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &kxkb; Handbook</title> + +<authorgroup> +<author> +&Andriy.Rysin; &Andriy.Rysin.mail; +</author> +<author> +&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail; +</author> +<othercredit role="developer"> +&Andriy.Rysin; &Andriy.Rysin.mail; +<!-- <contrib>Developer</contrib> --> +</othercredit> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</authorgroup> + +<copyright> +<year>2003</year> +<holder>&Andriy.Rysin;</holder> +</copyright> +<copyright> +<year>2006</year> +<holder>&Anne-Marie.Mahfouf;</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2006-02-16</date> +<releaseinfo>3.5.2</releaseinfo> + +<abstract><para>&kxkb; is a keyboard layout switching +utility based on X11 xkb extension.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>kxkb</keyword> +<keyword>keyboard</keyword> +<keyword>layout</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para>&kxkb; is the &kde; keyboard layout switching utility. +It is based on X11 xkb extension and allows to use different keyboard +layouts for inputing text. &kxkb; features keyboard layout indicator. +</para> + +</chapter> + +<chapter id="usingthekxkb"> +<title>Using &kxkb;</title> + +<sect1 id="getting-started"> +<title>Getting Started</title> + +<para>&kxkb; starts automatically and stays in system tray as a flag +with 2 or 3 letter abbreviation of layout name on top of it if more +than one layout is defined or <guilabel>Show indicator for single +layout</guilabel> option is turned on.</para> + +<para>When &kxkb; is running you can change layouts clicking on its +tray icon with the mouse or pressing its keyboard shortcut. Keyboard +shortcut or mouse click will switch to next layout or alternatively you +can &RMB; click the &kxkb; icon and select layout from the +list.</para> + +<para>&RMB; clicking on the &kxkb; icon you can start its +configuration by selecting <guimenuitem>Configure...</guimenuitem> or +by opening <application>Control Center</application> and selecting +Localization/Keyboard Layout. Alternatively, you can start it by +typing <command>kcmshell keyboard_layout</command> in a +terminal.</para> + +</sect1> +</chapter> + +<chapter id="configuringkxkb"> +<title>Configuring &kxkb;</title> + +<sect1 id="general-config"> +<title>General Information</title> +<para> +&kxkb; Configuration consists of three tabs: Layout, Switching + Options and Xkb Options. Layout and Xkb Options are mutually independent. +The Layout tab defines layouts you want to use and their options, the Switching +Options tab defines how you want to switch keyboards and the Xkb Otions tab +defines parameters for Xkb extension on which &kxkb; is based. +Xkb options are property of X and are not handled in any way by &kxkb; - +it just sets it up. +</para> +<note><para> +&kxkb; configuration does not change anything in XFree86 configuration +files and Layout settings from XFree86 configuration are overridden +by &kxkb; if <option>Enable keyboard layout</option> option is turned on. +</para></note> +<note><para> +To make your XFree86 configuration work you have to turn off both +<option>Enable keyboard layout</option> in layout configuration tab +<emphasis>and</emphasis> <option>Enable xkb options</option> in +Xkb options configuration tab (for the latter the same effect can be +reached if <option>Reset Old Options</option> is turned off and +none of xkb options are set). +</para></note> +<para> +&kxkb; does most of its actions through <command>setxkbmap</command> command. +You can see the commandline to be executed for each active layout +when you select it and, on the xkb options tab, its available xkb option set. +</para> +</sect1> + +<sect1 id="layout-config"> +<title>Layout Configuration</title> + +<screenshot> +<screeninfo>The Layout tab</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="layout.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Layout tab</phrase> + </textobject> + </mediaobject> +</screenshot> + +<para> +In layout configuration dialog the list of available layouts on your left. +You have to choose each layout you want to use and add them (one by one) +to the list of active layouts on the right. You can also change the order +in which active layouts will be switched when toggled by keyboard shortcut +or mouse button. The first layout in the list becomes default layout. +</para> +<para> +Some layouts have several variants. Layout variants usually represent +different key maps for the same language. For example, Ukrainian +layout might have four variants: basic, winkeys (as in Windows), typewriter +(as in typewriters) and phonetic (each Ukrainian letter is placed on a +transliterated latin one). If your layout is multi-variant one +you can the variant in combobox below the active layouts list. +</para> +<para> +Keyboard model setting is independent of your keyboard layout and refers +to the "hardware" model, i.e. the way your keyboard is manufactured. +Modern keyboards that come with your computer usually have two extra keys +and are referred to as "104-key" models, which is probably what you want +if you don't know what kind of keyboard you have. +</para> +<para> +You can also choose switching policy for keyboard layout. By default it's +<option>Global meaning</option> all applications will share the same current layout. +<option>Application</option> means each application will have it's own layout and +switching layout while you are working with one application will not impact layout for any +others. <option>Window</option> will make every window have its own layout even if they belong +to the same program. +</para> +<para> +If you set only one active layout, at startup kxkb configures the keyboard and exits thus +its indicator will not appear. If you still want kxkb indicator select +<option>Show indicator for single layout</option> option. +</para> +<note> +<para> +If you leave active layout list empty keyboard layouts will be disabled +</para> +</note> +</sect1> + +<sect1 id="switching-config"> +<title>Switching Options</title> + +<screenshot> +<screeninfo>The Switching Options tab</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="switching.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Switching Options tab</phrase> + </textobject> + </mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guilabel>Show indicator for single layout</guilabel></term> +<listitem><para>Shows icon in system tray even when thee is +only one layout.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Show country flag</guilabel></term> +<listitem><para>Shows country flag on background of layout name in tray +icon.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Switching Policy</guilabel></term> +<listitem><para>If you select <guilabel>Application</guilabel> or +<guilabel>Window</guilabel> switching policy, +changing the keyboard layout will only affect the current application or +window. <guilabel>Global</guilabel> will make the switching +policy work globally for all applications and windows.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Sticky Switching</guilabel></term> +<listitem><para>If you have more than two layouts and check <guilabel>Enable +sticky switching</guilabel>, switching with the keyboard shortcut or clicking on +the kxkb indicator will only cycle through the last few layouts. You can specify +the number of layouts to rotate below in the <guilabel>Number of layouts to +rotate</guilabel> box. You can still access all layouts by right-clicking on the +&kxkb; indicator.</para></listitem> +</varlistentry> +</variablelist> +</sect1> + +<sect1 id="xkboptions-config"> +<title>XKB Options Configuration</title> + +<screenshot> +<screeninfo>The Xkb tab</screeninfo> + <mediaobject> + <imageobject> + <imagedata fileref="xkb.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>The Xkb tab</phrase> + </textobject> + </mediaobject> +</screenshot> + +<para> +Xkb options allow you to select behavior of your keyboard. These options are not +handled by &kxkb; but may help tune your keyboard to your needs. You can set Xkb +extension options instead of, or in addition to, specifying them in the X11 +configuration file. +</para> +</sect1> + +</chapter> + +<chapter id="kxkbtroubleshooting"> +<title>Troubleshooting</title> + +<sect1 id="troubles"> +<title>Common Problems</title> + +<para>If you switch to some layout and you can not see some characters +from your layout as you type, please check your local settings. ⪚ +<filename>~/.i18n</filename> or +<filename>/etc/sysconfig/i18n</filename>, locale you have before +starting kde applications must have an encoding which contains +characters from your layout. For example, to enter ukrainian symbols +you must have encoding KOI8-U, CP1251 or UTF-8. The last one is a good +choice to try for most of the languages if you have such a problem. +</para> + +<para>If kxkb does not switch with keyboard shortcut when you switch +it to some layout but switching with mouse is ok may mean +that your layout does not contain the key +assigned in shortcut.</para> + +<para>In XFree86 prior to version 4.3.0 non-latin layouts mutually included +latin group and this group was the default thus pressing +<keycombo action="simul">&Ctrl;&Alt;<keycap>k</keycap></keycombo> +always yielded the right combination. From version 4.3.0 by default +all layouts contain only one group thus non-latin layouts may not work +here.</para> + +<para>Possible solutions are:</para> + +<orderedlist> +<listitem> +<para>add your layout to $nonlatin or $oldlayouts lists in +<filename>/etc/X11/xkb/rules/xfree86</filename> or the location of the +xkb rules on your computer.</para> +</listitem> +<listitem> +<para>Change the shortcut to something language neutral, ⪚ +<keycombo action="simul">&Ctrl;<keycap>Menu</keycap></keycombo></para> +</listitem> +<listitem> +<para>Turn on the option to include the <quote>us</quote> group in +your layout (effectively the same as solution 1).</para> +</listitem> +</orderedlist> + +</sect1> +</chapter> + +<chapter id="xkb-files"> +<title>Files and Layout Descriptions</title> +<sect1 id="xkb-files-and-layouts"> +<title><application>xkb</application> Files and Layouts</title> + +<para>All available keyboard layouts are described in +<filename>/etc/X11/xkb/rules/xfree86.lst</filename> (and +<filename>/etc/X11/xkb/rules/xfree86.xml</filename> since XFree86 +4.3.0), the layouts themselves can be found in +<filename>/etc/X11/xkb/symbols/pc</filename> (or +<filename>/etc/X11/xkb/symbols</filename> for XFree86 4.2.x and +older). Note that the location of these files may differ depending on +your operating system and distribution.</para> + +<para>&kxkb; now uses the xkb extension instead of xmodmap, so to +define your own layout you have to get one from <filename +class="directory">/etc/X11/xkb/symbols</filename> which is closest to +what you want to get (or <filename +class="directory">/etc/X11/xkb/symbold/pc</filename> for XFree86 +4.3.0), rename it to something you like and edit it. Then just add the +name to <filename>/etc/X11/xkb/rules/xfree86.lst</filename> (and for +XFree86 4.3.0 or later it is a good idea to add the name also to +<filename>/etc/X11/xkb/ruls/xfree86.xml</filename> - some packages +already use it, not &kxkb; though yet) kxkb will pick it up on +restart. Note: you have to be root to edit those files.</para> + +</sect1> + +</chapter> + +<chapter id="credits-and-licenses"> +<title>Credits and Licenses</title> + +<para>&kxkb; is currently developed and maintained by Andriy Rysin +<email>[email protected]</email>. Several other people +have worked on <application>kxkb</application>:</para> + +<itemizedlist> +<listitem><para>Shaheed Haque <email>[email protected]</email></para></listitem> +<listitem><para>Ilya Konstantinov <email>[email protected]</email></para></listitem> +</itemizedlist> + +&underFDL; +&underGPL; + +</chapter> + +</book> +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/kxkb/layout.png b/doc/kxkb/layout.png Binary files differnew file mode 100644 index 000000000..dfb30cbf6 --- /dev/null +++ b/doc/kxkb/layout.png diff --git a/doc/kxkb/switching.png b/doc/kxkb/switching.png Binary files differnew file mode 100644 index 000000000..504eaa7b2 --- /dev/null +++ b/doc/kxkb/switching.png diff --git a/doc/kxkb/xkb.png b/doc/kxkb/xkb.png Binary files differnew file mode 100644 index 000000000..df2db58f7 --- /dev/null +++ b/doc/kxkb/xkb.png diff --git a/doc/quickstart/Makefile.am b/doc/quickstart/Makefile.am new file mode 100644 index 000000000..7e42282c4 --- /dev/null +++ b/doc/quickstart/Makefile.am @@ -0,0 +1,3 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/quickstart diff --git a/doc/quickstart/index.docbook b/doc/quickstart/index.docbook new file mode 100644 index 000000000..7828c7121 --- /dev/null +++ b/doc/quickstart/index.docbook @@ -0,0 +1,1340 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "&kde; Quick Start Guide"> + <!ENTITY package "kdebase"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> +]> + +<book lang="&language;"> +<bookinfo> + +<title>An Introduction to &kde;</title> + +<authorgroup> + +<author> +<surname>The &kde; Team</surname> +</author> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2004-08-28</date> +<releaseinfo>3.00.00</releaseinfo> + +<copyright> +<year>1999</year><year>2000</year><year>2001</year><year>2002</year> +<holder>The &kde; Team</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<abstract> +<para>An introduction to the K Desktop Environment</para> +<para>Quick Start Guide to &kde;</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>quick start</keyword> +<keyword>introduction</keyword> +</keywordset> +</bookinfo> + +<chapter id="introduction"> +<title>Introduction</title> + +<para> +This document is a brief introduction to the K Desktop Environment. It +will familiarize you with some of the basic features of &kde;. +</para> + +<para> +This guide is far from covering all aspects of the K Desktop or even most +of them. It will only describe some of the most basic ways to accomplish a few +of the most common tasks. +</para> + +<para> +We assume that you are already familiar with at least one graphical +user interface, for example <trademark>CDE</trademark>, +<trademark>Geos</trademark>, <trademark>GEM</trademark>, &NeXTSTEP;, +&Mac;, <trademark>OS/2</trademark> or &Microsoft; &Windows;. So we +will not explain the usage of the mouse or the keyboard but +concentrate on hopefully more interesting things. +</para> + +</chapter> + +<chapter id="an-overview-of-kde"> +<title>An Overview of &kde;</title> + +<para> +This section is for users who prefer to learn by exploring and want +only a brief orientation to get started. Later sections provide a more +thorough introduction to the environment, with helpful hints and +shortcuts. If you are impatient to get started, skim this section, go +play for a bit, then come back and peruse the other sections of this +guide as needed. +</para> + +<note> +<para> +&kde; provides a highly configurable desktop environment. This +overview assumes that you are using the default environment. +</para> +</note> + +<sect1 id="the-kde-desktop"> +<title>The &kde; Desktop</title> + +<para>A typical &kde; desktop consists of several parts:</para> + +<itemizedlist> +<listitem> +<para>A <interface>panel</interface> at the bottom of the screen, used +to start applications and switch between desktops. Among other things, it +contains the &kmenu;, a large &kicon; +which displays a menu of applications to start when clicked. +</para> +</listitem> + +<listitem> +<para> +A <interface>taskbar</interface>, by default embedded in the panel, used +to switch between and manage currently running applications. Click on an +application on the taskbar to switch to the application. +</para> +</listitem> + +<listitem> +<para> +The <interface>desktop</interface> itself, on which frequently used +files and folders may be placed. &kde; provides multiple desktops, +each of which has its own windows. Click on the numbered buttons on +the panel to switch between desktops. +</para> +</listitem> +</itemizedlist> + +</sect1> + +<sect1 id="ready-set-go"> +<title>Ready, Set, Go!</title> + +<para>Here are a few quick tips to get you up and running.</para> + +<itemizedlist> +<listitem> +<para> +To start an application, click on the &kicon; button on +the panel (called the <link linkend="starter">&kmenu;</link>) +and choose an item from the menu. +</para> +</listitem> +<listitem> +<para> +Click the icon that looks like a picture of a house on +the panel to access the files in your home folder using +&konqueror;, &kde;'s File Manager utility. +</para> +</listitem> +<listitem> +<para>Choose <menuchoice><guimenu>K menu</guimenu> +<guisubmenu>System</guisubmenu> +<guimenuitem>Konsole</guimenuitem></menuchoice> to get a &UNIX; +command prompt, or press <keycombo action="simul">&Alt; +<keycap>F2</keycap></keycombo> to get a mini command prompt window to +execute a single command. +</para> +</listitem> + +<listitem> +<para> +Choose the <menuchoice><guimenuitem>Control Center</guimenuitem> +</menuchoice>item on the &kmenu; +to configure &kde;. +</para> +</listitem> + +<listitem> +<para> +Press <keycombo action="simul">&Alt;<keycap>Tab</keycap></keycombo> to +switch between applications and <keycombo +action="simul">&Ctrl;<keycap>Tab</keycap></keycombo> to switch between +desktops using the keyboard. +</para> +</listitem> + +<listitem> +<para> +Use the &RMB; mouse button to access context menus for the panel, +desktop, and most &kde; applications. +</para> +</listitem> +</itemizedlist> + +</sect1> +</chapter> + +<chapter id="launching-applications"> +<title>Launching Applications</title> + +<sect1 id="starter"> +<title>Using the &kmenu; and the Panel</title> + +<para> +At the bottom of the screen you will find the desktop panel, which is called +&kicker;. You use the panel to launch applications. Have a look at the +button on the left with a large &kicon;. +</para> + +<para> +This button is called the &kmenu;. It has +a small arrow on the top to indicate that it will pop up a menu if you +click on it. Just do it! The popup offers you easy access to all &kde; +applications installed on your computer system. +</para> + +<sect2> +<title>Customizing &kicker;</title> + +<!-- FIXME: To add a button, use the little arrows on kicker, not the K menu +I am not sure I agree - some distributions fade or hide the applet handles by default, but +I haven't found one yet that hides the kmenu. (JLH) --> + +<para>If you use one application or tool very often, then you may want to have even faster +access to it. In this case you can add a single application or an entire sub-menu of the +&kmenu; as a special quick-launch button on the panel. If you want to reach an application +directly via a launch button, click with the &RMB; either on a clear space on the panel or on the +&kmenu; icon. Select <menuchoice><guimenu>Panel Menu</guimenu> <guisubmenu>Add Application to Panel... +</guisubmenu></menuchoice> and then navigate to the application or menu you would like to add to +the panel.</para> + + +<para> +You can add an entire menu this way, or one of the &kicon; +button sub-menus. For example, if you have &koffice; installed and +want quick access to all the &koffice; applications, without having to +navigate through the &kmenu;, then instead of choosing an +application, click on the <guimenuitem>Add this menu</guimenuitem> menu +entry. Now you will have instant access to all the &koffice; +applications, without having to put an icon for each on the panel. +</para> + +<note> +<para> +You can move all items of the panel around with the +<guimenuitem>Move</guimenuitem> command of the context menu. Just click +with the <mousebutton>third</mousebutton> mouse button (the +<mousebutton>third</mousebutton> mouse button is normally the +<mousebutton>right</mousebutton> button, but if you have configured your +mouse differently, for example for left-handers, it might also be the +<mousebutton>left</mousebutton> one). A menu will pop up where you can +choose <guimenuitem>Move</guimenuitem>. Now move the mouse and see how +the icon follows while still staying on the panel. When you are done, +simply hit the <mousebutton>first</mousebutton> mouse button (by default +the <mousebutton>left</mousebutton> one). As you may have noticed, +there is also a menu entry <guimenuitem>Remove</guimenuitem> in case you +are tired of a certain launch button on your desktop. +</para> +</note> + +</sect2> + +<sect2> +<title>Using Context menus</title> + +<para> +This leads us to another interesting topic: in many places, you can +click the <mousebutton>right</mousebutton> mouse button to display a +<interface>context menu</interface> with choices that are applicable to +the item you clicked. It is therefore always a good idea to try out the +<mousebutton>third</mousebutton> mouse button on something, if you do +not know what to do with it. Even the background of the desktops has +such a menu! +</para> + +</sect2> + +<sect2> +<title>Other Panel features</title> + +<para> +There are other interesting things possible with the panel. One +may be important if you have a low resolution on your monitor: it is +the <quote>hide-and-show</quote> function, activated by clicking on the +small arrowed button, which is at one or both ends of the panel. +</para> + +<para> +Perhaps you just do not like the panel extending the full width of the +screen. That's easily changed! &RMB; on an empty space in the panel, +and choose <menuchoice><guimenuitem>Configure Panel...</guimenuitem></menuchoice>. In the &kcontrolcenter; +dialog that pops up, you can choose <guilabel>Length</guilabel> on +the <guilabel>Appearance</guilabel> tab, and use the slider there to set +the panel to less than 100% width. +</para> + +<para> +If you're following along, and have that dialog open anyway, then feel +free to play with all the options, and use the +<guibutton>Apply</guibutton> to see the effect they have. You can +easily reset everything to the default configuration, by simply pressing +the <guibutton>Use Defaults</guibutton> button. +</para> + +<para> +By the way, if you are not sure what a certain button does in &kde;, +just move the mouse pointer over it and wait for a short while: &kde; +has a built-in mini context help, called <quote>tool tips</quote>, which +explains the functionality of such controls in a few words. +</para> + + +</sect2> +</sect1> + +<sect1 id="want-command-line-back"> +<title>But I want my command line back!</title> + +<para> +Just calm down, there is nothing to fear. &kde; does not want to take your +beloved (and sometimes very effective) command line away from you. You can move +your files with the desktop, but you can also use the &UNIX; commands you are +accustomed to. In fact,&kde; puts command line power at your fingertips, +in perhaps some surprising places. +</para> + +<para> +&kde; provides a very sophisticated command line window called +&konsole;. Choose <menuchoice><guimenu>K menu</guimenu> +<guisubmenu>System</guisubmenu> +<guimenuitem>Konsole</guimenuitem></menuchoice> to start it. This may +be something you want on your panel: luckily it's already there in the +default configuration! +</para> + +<para> +Sometimes, you only want to enter one command on the command line. In +these cases, you do not need a full-blown terminal. Just hit +<keycombo>&Alt;<keycap>F2</keycap></keycombo> and you get a +small command line where you can enter one command. The command line +window will disappear afterwards, but it remembers your command. +</para> + +<para> +When you pop up this window (which we call +<application>minicli</application> by the way) and hit the <keycap>Up +arrow</keycap>, you can browse through all the commands you have +previously entered. Also, you can enter &URL;s in +<application>minicli</application> to open a &konqueror; window with +the specified &URL;. +</para> + +<para> +&konqueror; and the editor &kate; can both display terminal windows, +which behave just like &konsole;. In &konqueror;, you can turn this +on with the menu choice +<menuchoice><guimenu>Window</guimenu><guimenuitem>Show Terminal +Emulator</guimenuitem></menuchoice>. The embedded terminal will display +at the bottom of your &konqueror; window, and the really clever thing +is that it will follow your clicks in the file manager view, changing +folder as you do. In &kate; you can display a terminal with the +menu choice <menuchoice><guimenu>Settings</guimenu><guimenuitem>Show +Console</guimenuitem></menuchoice>. +</para> + +<tip> +<para> +To display a &UNIX; man page, enter +<userinput><command>man:</command><replaceable>command</replaceable></userinput> +in <application>minicli</application>, where <replaceable>command</replaceable> +is the name of a &UNIX; command. +</para> +</tip> + +<tip> +<para> +To search for a word or words on the Google search engine, you can try entering +<userinput><command>gg:</command><replaceable>word or +words</replaceable></userinput>. There are a whole lot more of these +shortcut commands, and you can even add your own! Take a look in +&kcontrolcenter;, in the tab <menuchoice><guilabel>Web Browsing</guilabel> + <guilabel>Enhanced Browsing</guilabel></menuchoice>. +</para> +</tip> + +<para> +Finally, there's a way to have your command line always available, no +matter what you're doing - add one to your &kicker; panel! +</para> + +<para>Simply &RMB; click on an empty space in the panel and choose +<menuchoice><guilabel>Add Applet to Panel...</guilabel></menuchoice>. In the dialog that appears, +scroll down until you see the <guilabel>Run Command</guilabel> list item. Select +it with the &LMB; and click <guilabel>Add to Panel</guilabel>. This will embed a mini-cli +directly into your panel, complete with command history.</para> + +<para> +So, in conclusion, the command line is never far from view when you're +using &kde;. +</para> + +</sect1> +</chapter> + +<chapter id="working-with-windows"> +<title>Working with Windows</title> + +<para> +If you have not already done so, start an application using the <link +linkend="starter">&kmenu;</link>; say, +<guimenuitem>Find Files</guimenuitem>. +</para> + +<sect1 id="window-what-now"> +<title>A window! What now?</title> + +<para> +Well, usually people work <emphasis>inside</emphasis> windows, but +sometimes you may want to manipulate windows. Here's a quick overview +of some of the most common window related functions: +</para> + +<variablelist> +<varlistentry> +<term>Move a window</term> +<listitem> +<para> +Drag the window's title bar, or hold the &Alt; key down +and drag anywhere in the window. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Resize a window:</term> +<listitem> +<para> +Drag the window's border, or hold the &Alt; key down and drag with the +&RMB; anywhere in the window. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Maximize a window</term> +<listitem> +<para> +Click the maximize button in the titlebar (in the default decoration it +is the square, next to the X) to make the window fill the screen, or if +the window is already maximized, to shrink it back to its original +size. Clicking with the &MMB; maximizes the window vertically, and with +the &RMB;, horizontally. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Iconify a window</term> +<listitem> +<para> +Click the <guilabel>Minimize</guilabel> button in the titlebar (next to <guilabel>Maximize</guilabel>) +to hide the window. Restore it by clicking on the window's icon in the +taskbar. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Switch between windows</term> +<listitem> +<para> +Aside from the usual mouse click to switch to another window, +you can use <keycombo action="simul">&Alt; +<keycap>Tab</keycap></keycombo> to switch windows. See below for more +techniques. +</para> +</listitem> +</varlistentry> +</variablelist> + +<sect2> +<title>Titlebar buttons</title> + +<para> +&kde; windows have some pretty standard buttons on their titlebars which +give you fast access to some common operations. The default button +layout looks like this: +</para> + +<itemizedlist> +<title>On the left side:</title> +<listitem> +<para> +A <guilabel>Menu</guilabel> button. This usually shows a mini icon for the application. Click +on it to get a window operations menu. Shortcut: <keycombo +action="simul">&Alt;<keycap>F3</keycap></keycombo> opens the window +menu. +</para> +</listitem> + +</itemizedlist> + +<itemizedlist> +<title>On the right side:</title> +<listitem> +<para> +A <guilabel>Minimise</guilabel> button. +</para> +</listitem> + +<listitem> +<para> +A <guilabel>Maximize</guilabel> button. +</para> +</listitem> + +<listitem> +<para> +A <guilabel>Close</guilabel> button. This closes the window. Shortcut: <keycombo +action="simul">&Alt;<keycap>F4</keycap></keycombo>. +</para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2> +<title>Switching between windows</title> + +<para> +Now that we know how to deal with windows, we encourage you to open +some other windows using the panel, since we will now discuss how to +switch between different windows. Since this is such a common +activity, &kde; offers several ways to do it; pick your favorite! +</para> + +<para> +Many window systems require you to click the mouse in another window +to begin using it. This is &kde;'s default behavior, termed +<quote>Click To Focus</quote> focus policy. But you can also configure +your desktop in a way that moving the mouse pointer on to a window will +activate it. This is called <quote>Focus Follows Mouse</quote>. If you +select this policy using the <link linkend="configure">&kde; Control +Center</link>, the window under the mouse pointer is always the active +one. It does not necessarily come to the front automatically, but you +can still click on to the titlebar or the border of a window or, a +&kde; special, you can use the &Alt; key and click the &MMB; +anywhere on the window to raise it. +</para> + +<para> +Here are some other methods to switch windows: +</para> + +<itemizedlist> +<listitem> +<para> +Pick a window from the <emphasis>window list</emphasis> menu. To open +the menu, click the &MMB; on +an empty area of the desktop, or click the icon with several windows +on the panel, or finally click the up arrow at the left hand end of +the taskbar in the panel. +</para> +</listitem> + +<listitem> +<para> +Hold down the &Alt; key and press <keycap>Tab</keycap> to cycle through +the windows. +</para> +</listitem> + +<listitem> +<para> +Use the taskbar (see below). +</para> +</listitem> +</itemizedlist> + +</sect2> +</sect1> + +<sect1 id="using-taskbar"> +<title>Using the Taskbar</title> + +<para> +The <interface>taskbar</interface> displays a list of small icons, one +for each window on the desktop. In the default &kde; setup the taskbar +is located inside the panel, but it can also be located at the top or +the bottom of the screen. </para> + +<para> +The taskbar is very powerful. In the default configuration, if you +have more than one window from the same application open, they will be +<quote>grouped</quote>, so that you see one icon per application in +the taskbar.</para> + +<para>A simple &LMB; +click on the taskbar button will pop up a list of the open windows for +that application and you can choose the window you want to +use. Choosing one of these entries with the +<mousebutton>left</mousebutton> will bring you to the selected +window immediately. Click on a taskbar entry with the +<mousebutton>right</mousebutton> and you will see a menu allowing you +to operate on all the windows grouped under that icon, or each window +individually.</para> + +<para> +You can choose to see all the windows on all the desktops in your +taskbar, no matter which desktop you are currently viewing, or to only +see the icons for the desktop you are looking at. You can also choose +to ungroup the icons, so that each open window will have its own icon +in the taskbar. These and many more options are available simply by +right clicking on the taskbar handle (the small textured bar at the +left hand side) and choosing <guimenuitem>Configure Taskbar...</guimenuitem>. +</para> + +<para> +The icons on the taskbar resize themselves to make room for +applications, so you can fit many more applications than you might +think. Making the panel wider will let the taskbar icons take on a row +and column layout, but they will still resize to fit more icons. +</para> + +</sect1> + +<sect1 id="using-v-desktops"> +<title>Using Virtual Desktops</title> + +<para> +Now, what was that <quote>sticky</quote> thing? +</para> + +<para> +It may happen that you have more windows open than space on your +desktop. In this case you have three possibilities: +</para> + +<orderedlist> +<listitem> +<para> +Leave all windows open (cluttered desktop) +</para> +</listitem> + +<listitem> +<para> +Iconify those windows which you do not need at present and use +the taskbar or <keycombo action="simul">&Alt; +<keycap>Tab</keycap></keycombo> to switch between them +(still a bit confusing and much work!) +</para> +</listitem> + +<listitem> +<para> +Recommended: Do what a real operating system does if there is not enough +physical memory: Use virtual memory, in this case virtual desktops. +</para> +</listitem> +</orderedlist> + +<para> +The third option is the way to go! &kde; can handle several different desktops, +each with its own windows. The default configuration provides four +desktops. You can switch between the virtual desktops easily with a +click on one of the desktop buttons on the panel. Also <keycombo +action="simul">&Ctrl;<keycap>F1...F4</keycap></keycombo> will send you +to the corresponding desktop immediately, or <keycombo +action="simul">&Ctrl; <keycap>Tab</keycap></keycombo> will cycle through +the desktops. +</para> + +<para> +Virtual desktops are very nice. But sometimes you want a window to be +present on <emphasis>every</emphasis> desktop. This could be, for example, +a small chat window, an alarm clock or whatever. In this case you can +use the above mentioned <quote>sticky</quote> button which will pin the +window on the background so that it will appear on every virtual +desktop. +</para> + +<para> +The sticky button can also be used to move a window from one virtual +desktop to another one: push the sticky pin on the window, switch to a +different desktop, and release the pin by pushing it again. You can +achieve the same result by using the context popup menu of the +window's entry in the taskbar (menu item <guimenuitem>To Current +Desktop</guimenuitem>) or the <guimenuitem>To Desktop</guimenuitem> +option on the window operations menu. +</para> + +</sect1> +</chapter> + +<chapter id="managing-your-files"> +<title>Managing your files</title> + +<!-- NB Deliberate use of 'directory' rather than 'folder', since we're talking --> +<!-- about folders on disk --> +<para> +A common metaphor of graphical desktops is the use of folders to +represent folders on your hard disk. Folders contain files and +other folders. A &kde; application called &konqueror;, the K File +Manager, uses this metaphor to help you manage your files. +</para> + +<sect1 id="using-konqueror"> +<title>Using &konqueror;</title> + +<para> +The first time you start &kde;, a window with lots of icons in it +appears. This is a &konqueror; window displaying the files in your +home folder (the area where your personal files are stored). The +pathname of the folder is displayed under the window's tool bar. If +you do not see such a window now, click the icon on the panel that +looks like a folder with a picture of a house. +</para> + +<para> +To open a file or folder, simply click it once with the &LMB;. +You can also choose +<menuchoice><guimenu>Window</guimenu><guimenuitem>Show +Navigation Panel</guimenuitem></menuchoice> from the menu to display the folder +hierarchy for more direct navigation. Or you can edit the path +displayed under the toolbar to get to a specific folder quickly. +</para> + +<sect2> +<title>Opening Files</title> + +<para> +&kde; comes with a set of applications to view and edit files of many +common types, and when you click a file containing, say, a document +or image, &konqueror; will start the appropriate application to +display the file. If it does not know what application to start to open +a file you clicked, &konqueror; will prompt you for the name of the +application to run, and when you have chosen, &konqueror; will offer +to remember your choice for the next time you open a file of that type. +</para> + +<note> +<para> +&konqueror; uses MIME types to associate +files with applications. +</para> +</note> + +</sect2> + +<sect2> +<title>Dragging and Dropping Icons</title> + +<para> +To copy or move a file, simply drag its icon to the desktop, to +another &konqueror; window, or to a folder icon. When you release the +button, &konqueror; displays a menu to allow you to choose to copy, +move, or create a link to the file. +</para> + +<note> +<para> +Note that if you choose to create a link, &kde; creates a &UNIX; +symbolic link (not a hard link), so if you move or delete the original +file, the link will be broken. +</para> +</note> + +<para> +Most &kde; applications also support drag and drop operations: you can +drag an icon on to a window of a running application, or on to an icon of +an application that is not started, to have the application open the +file. Try it! +</para> + +</sect2> + +<sect2> +<title>Setting File Properties</title> + +<para> +To change file properties, such as its name and permissions, &RMB; +click the icon and choose <guimenuitem>Properties</guimenuitem> from +the menu. +</para> + +</sect2> +</sect1> + +<sect1 id="archives-and-networks"> +<title>Working with Archives and Networks</title> + +<para> +In the recent past, you needed special software to access files on the +Internet. Not any more! +</para> + +<para> +&kde; supports a technology called <quote>Network Transparent +Access</quote> (<acronym>NTA</acronym>) which allows you to work with +files on the other side of the world as easily as those on your local +hard disk.</para> + +<para> +For example, to access files on an &FTP; server, just choose +<menuchoice><guimenu>Location</guimenu><guimenuitem>Open +Location</guimenuitem></menuchoice> from a &konqueror; menu, and enter +the <acronym>URL</acronym> of an &FTP; server. You can drag and drop +files to and from the folders on the server just as if they were on +your local disk. You'll even be able to open files on the &FTP; server +without having to manually copy them to your local disk (&kde; does it for you +when necessary). +</para> + +<note> +<para> +Note that &konqueror; uses anonymous &FTP; access, which may restrict +your access to files on the &FTP; server. If you have an account on +the server, you can supply your user <abbrev>ID</abbrev> as part of +the <acronym>URL</acronym>, like this: +<userinput><command>ftp://</command><parameter>userid</parameter>@<parameter>server</parameter>/<parameter>folder</parameter></userinput> +</para> + +<para> +&konqueror; will prompt you for your password, and if the login +succeeds, you will have full access to your files on the server. +</para> +</note> + +<para> +If you are used to the +<trademark><application>WinZip</application></trademark> utility on +&Microsoft; &Windows;, then you will be happy to hear that &kde; can +look into tar archives, too. It treats such archives just like a +normal folder, and you can browse into the archive, open files, &etc; In +general, accessing files on the Internet and in archives should look +and feel just like accessing files on your local disk, except for +delays imposed by the network and extracting the archive. +</para> +</sect1> + +<sect1 id="using-templates"> +<title>Using Templates to access Applications and Devices</title> + +<para> +In &kde; it's easy to put icons on the panel or the desktop to access +your applications. It's just as easy to add icons to access other +items of interest. &kde; has templates for shortcuts to: +</para> + +<itemizedlist> +<listitem> +<para> +Applications +</para> +</listitem> +<listitem> +<para> +Printers +</para> +</listitem> +<listitem> +<para> +Mountable Devices (⪚ floppy drives) +</para> +</listitem> +<listitem> +<para> +Internet resources (⪚ <acronym>WWW</acronym> documents, &FTP; +folders) +</para> +</listitem> +<listitem> +<para> +Documents for some of &kde;'s &koffice; applications. +</para> +</listitem> +</itemizedlist> + +<para> +You can add any of these items to the desktop by &RMB; clicking where +you want the icon, and choosing <guisubmenu>Create New</guisubmenu> +and selecting the item you want to link to. +</para> + +<para> +Nearly every item in the &kmenu;, on the desktop, and on +the panel refers to a <literal role="extension">.desktop</literal> +file on disk. The <literal role="extension">.desktop</literal> file +specifies what icon to display, as well as specific information about +what the icon represents (an application, device, or +<acronym>URL</acronym>). You can drag any <literal +role="extension">.desktop</literal> file to the panel to create a +quick-launch button. +</para> + +<!-- +<sect2> +<title>Setting up printers</title> + +<para> +You can create icons for your printers so that you can print a file by +dragging it to a printer icon. Here's how: +</para> + +<procedure> +<step><para>Open the Templates folder located on the desktop. </para></step> +<step><para>Drag the Program icon in the folder to the desktop. Choose +<guimenuitem>Copy</guimenuitem> from the menu that appears when you drop the +icon.</para></step> +<step><para><mousebutton>Right</mousebutton> click the new icon, and choose +<guimenuitem>Properties</guimenuitem> from the context menu.</para></step> +<step><para>On the <guilabel>General</guilabel> tab, change the name to +<filename>Printer.kdelnk</filename>.</para></step> +<step><para>On the <guilabel>Execute</guilabel> tab, enter the following in the +first <guilabel>Execute</guilabel> field:</para> +<screen><command>lpr <option>%f</option></command></screen> +<note><para>This example assumes that you print using the <command>lpr</command> +command. If you use a different command, enter the one you +use.</para></note></step> +<step><para>Still in the <guilabel>Execute</guilabel> tab, click the icon that +looks like a <guiicon>cog</guiicon>, and select the <guiicon>Printer</guiicon> icon from the list that appears.</para></step> +</procedure> + +<para>Now you should be able to drag a file to the Printer icon and have it +printed on your default printer.</para> +</sect2> + +--> + +<sect2> +<title>Mounting devices</title> + +<para> +&UNIX; provides access to storage devices other than the primary +<hardware>hard disk</hardware> through a process called +<emphasis>mounting</emphasis>. &kde; uses <literal +role="extension">.desktop</literal> files to allow you to easily +mount, unmount, and access files on secondary storage devices such as +<hardware>floppy</hardware> drives and &cdrom; drives. +</para> + +<para> +As an example, here are the steps needed to create an icon to access +files on a floppy disk: +</para> + +<note> +<para> +Many systems require you to be logged in as <systemitem +class="username">root</systemitem> to mount and unmount devices. +</para> +</note> + +<procedure> +<step> +<para><mousebutton>Right</mousebutton> click on the desktop and choose +<menuchoice><guisubmenu>Create +New</guisubmenu><guisubmenu>Device</guisubmenu> +<guimenuitem>Floppy Device...</guimenuitem></menuchoice>. +</para> +</step> +<step> +<para> +On the <guilabel>General</guilabel> tab of the resulting dialog, change +the name to whatever you like, in the text box at the top. +</para> +</step> + +<step> +<para> +On the <guilabel>Device</guilabel> tab, enter <filename +class="devicefile">/dev/fd0</filename> (or the path to the floppy device +as it is named on your system) as the <guilabel>Device</guilabel>. +</para> +</step> +<step> +<para> +You can add a <guilabel>Mount Point</guilabel> here too. This should be +an existing folder, but empty. Common mount points are <filename +class="directory">/mnt/floppy</filename> or <filename +class="directory">/floppy</filename>, but you can just as easily have floppy +disks mounted on <filename class="directory">~/mydisk</filename> if you +want. +</para> +</step> +<step> +<para> +Click the <guilabel>Unmounted Icon</guilabel> and select the picture +of a floppy disk without the green light. +</para> +</step> +<step> +<para> +Once you're happy with your choices, choose <guibutton>OK</guibutton> +and you are finished! +</para> +</step> +</procedure> + +<para> +Now, place a properly formatted floppy in the drive and click the +<guiicon>Floppy</guiicon> icon to have &kde; mount the floppy drive and display +the files on the disk. Before removing the disk from the drive, &RMB; +click the <guiicon>Floppy</guiicon> icon and choose +<guimenuitem>Unmount</guimenuitem> from the menu. +</para> + +</sect2> +</sect1> +</chapter> + +<chapter id="configure"> +<title>Configuring your desktop</title> + +<para> +If you do not like something about the way the desktop looks or +operates, you can probably change it. &kde; is very configurable and you +can change almost every aspect of the appearance and the behavior of +your desktop. Unlike many other &UNIX; desktop environments, you do not +have to edit cryptic configuration files either (but you can if you +really want to!) You use the &kcontrolcenter;, a special program for +configuring your desktop. +</para> + +<sect1 id="using-kde-control"> +<title>Using the <application>&kde; Control Center</application></title> + +<para> +Launch the &kcontrolcenter; from the <link linkend="starter">&kmenu;</link>. +A window with two panes appears, displaying a list of +modules in the left pane. +</para> + +<para> +Open a module by clicking its name; a list of submodules will +appear. Then, click one of the submodule category names to edit its +configuration in the right pane. +</para> + +<para> +Changing the configuration is fairly straightforward. A help button is +available on each configuration panel to explain settings that are not +obvious. Each panel has buttons labeled <guibutton>Help</guibutton>, +<guibutton>Use Defaults</guibutton>, <guibutton>Apply</guibutton>, and +<guibutton>Reset</guibutton>, which work as follows: +</para> + +<variablelist> +<varlistentry> +<term><guibutton>Help</guibutton></term> +<listitem> +<para> +Displays a short help text in the left hand pane, including a link to a +longer manual for the module in question. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Use Defaults</guibutton></term> +<listitem> +<para> +Sets all the options in the current module back to the default at the +time &kde; was installed. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Apply</guibutton></term> +<listitem> +<para> +Applies the current settings in the currently open module. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Reset</guibutton></term> +<listitem> +<para> +Resets the options to the state they were in when you opened the module. +If you have already used the <guibutton>Apply</guibutton> button, then +this button will reset the options to the state they were in when you +pressed <guibutton>Apply</guibutton>. +</para> +</listitem> +</varlistentry> +</variablelist> + +<note> +<para> +If you make changes on one configuration panel and move to a different module +without clicking <guibutton>OK</guibutton> or <guibutton>Apply</guibutton> +first, &kcontrolcenter; will prompt you to ask whether your changes should be applied +first. +</para> +</note> + +</sect1> + +</chapter> + +<chapter id="logging-out"> +<title>Logging out</title> + +<para> +We sincerely hope that using &kde; gives you so much fun and +pleasure that you never want to log out. But if you do, simply choose +<menuchoice><guimenu>K menu</guimenu> +<guimenuitem>Logout</guimenuitem></menuchoice>. +</para> + +<para> +There is also a logout button directly on the panel, which looks like a +small power button. Or you can press <keycombo action="simul">&Ctrl; +&Alt; <keycap>Delete</keycap></keycombo> to log out. +</para> + +<sect1 id="session-management"> +<title>Session Management</title> + +<para> +When you log out, &kde; can remember which applications you had open, as +well as where all the windows were located, so that it can open them +for you the next time you log in. This feature is termed +<emphasis>Session Management</emphasis>. &kde;-aware applications will +restore themselves to the state they were in when you logged out. For +example, &kate; remembers which files you were editing. </para> + +<para> +Non-&kde; applications do not memorize their state on logout, and +&kde; will warn you to make sure that you have saved any important +data in them when you start to log out. +</para> + +<para> +To illustrate session management, choose <menuchoice> +<guimenu>K menu</guimenu><guisubmenu>Editors</guisubmenu> +<guimenuitem>Kate</guimenuitem> </menuchoice> to start &kate;. Open +a text document to edit. Now log out and back in. You will observe +that &kate; will be restored to the exact same position on the screen, +including the right virtual desktop, and the document we left open in +&kate; before we logged out is opened again automatically. &kate; +will even remember whether you had unsaved changes to your document +before you logged out and will save them to the file you were working +on if you choose <guimenuitem>Save</guimenuitem> from the +<guimenu>File</guimenu> menu. +</para> + +</sect1> +</chapter> + +<chapter id="kde-an-exciting-journey"> +<title>&kde;, an exciting Journey</title> + +<para> +We hope you enjoyed this brief tour of the K Desktop environment and +that this unique desktop environment will help you get your work done +faster and more comfortably than ever. +</para> + +<para> +Please remember that the &kde; project is not a commercial venture, +but rather a project run by volunteers from all over the world. We +would like to invite you to join the &kde; project and become part of +this unique network of people. If you are a programmer you might +consider helping us write &kde; applications. If you are an artist or +have experience with graphic design, consider creating icons sets, +color schemes, sound schemes and logos for &kde;. If you enjoy +writing we would love for you to join our documentation project. +</para> + +<para> +As you can see there are many ways in which you can help. You are +cordially invited to join this world-wide network of people dedicated +to making &kde; the best desktop environment for any computer. Please +visit <ulink url="http://www.kde.org">www.kde.org</ulink> for more +information. +</para> + +<para> +<emphasis>Welcome aboard on this exciting journey, </emphasis> +</para> +<para> +<literal>Your &kde; Team</literal> +</para> +</chapter> + +<!-- +2004-08-27 +Removed because it probably should not be here, and it will only end up +getting out-of-date if it is (Phil) +<chapter id="advanced-topics"> +<title>Advanced Topics</title> + +<sect1 id="mime"> +<title>&MIME; Types</title> + +<para> +&kde; comes with a number of &MIME; types predefined, but you can add +your own &MIME; types by choosing +<menuchoice><guimenu>Settings</guimenu> +<guisubmenu>Configure Konqueror...</guisubmenu> +</menuchoice> and then <guilabel>File +Associations</guilabel> in a &konqueror; window. +</para> + +<para> +&kde;'s handling of &MIME; types is very powerful, and very +configurable. On the one hand, you can set a default action to be +performed when you click on a file in &konqueror;. Just as usefully, +you can add many more actions, which are then available with a &RMB; +click menu on the file in question. +</para> + + +<procedure> +<title>To link a certain file type with a particular application:</title> +<step> +<para> +Make sure the application you want to start this file type has an +entry in the &kmenu;. +</para> +</step> + +<step> +<para>In &konqueror; find or make a file with the extension you wish to +link. +</para> +</step> + +<step> +<para> +<mousebutton>Right</mousebutton> click on the file, and choose +<guimenuitem>Edit File Type</guimenuitem> from the context menu, or +choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Edit File +Type</guimenuitem></menuchoice> in &konqueror;'s menu bar. +</para> +</step> + +<step> <para> Add file masks for the application by clicking the +<guibutton>Add</guibutton> button, and entering the file pattern you +want. Remember that &UNIX; is case sensitive, so you may need to add +variations - <userinput>*.mp3</userinput> may need +<userinput>*.MP3</userinput> added as well, for example. Add as many +extensions as you like in this way. </para> </step> + +<step> +<para> +Add a description if you like. This is optional. +</para> +</step> + +<step> +<para>In the section labeled <guilabel>Application Preference +Order</guilabel>, press the <guibutton>Add</guibutton> button. A +miniature copy of the &kmenu; will +open, where you can choose the application you want files of this type +to be opened with. +</para> +</step> + +<step> +<para> +Sometimes, you may want to use a different application to open this +file type. For example, you might like to use &kate; to open text +files you wish to edit, and &kedit; for text files that you just want +to take a quick peek into. You can add more applications in the same +way as you did in the last step, and you can change the preferred +order using the <guibutton>Move Up</guibutton> and <guibutton>Move +Down</guibutton> buttons. +</para> +</step> + +<step> +<para> +If you're satisfied with your choices, you can click the +<guibutton>Apply</guibutton> button to save your changes without +closing the dialog box. This gives you the opportunity to test in the +<application>Konqueror</application> window that your file association +is correct. You can choose <guibutton>OK</guibutton> to save your +changes and close the dialog box, or <guibutton>Cancel</guibutton> if +you have changed your mind and just want to close the dialog box. +</para> +</step> +</procedure> + +<para> +Be sure to try your new association by opening a folder containing +a file of the type you just selected. Click on the file, and the +program needed to edit it should start. +</para> + +<note> +<para> +&MIME; types are a way of describing the contents of files. You may +be used to using file extensions for that purpose, and you may know +that on &UNIX; systems the file extension often bears little or no +relation to the contents of the file. On the other hand, it may be +vital - for example, some implementations of <command>gunzip</command> +will not operate on files that are not named <literal +role="extension">.gz</literal>. +</para> + +<para> +&MIME; types naturally make use of filename patterns, but not +necessarily the extensions - you can set up any filename pattern you +like. For example, if you always want to open any files relating to a +particular client with &kate;, and you make a habit of naming the files +with the client's name at the beginning so that they naturally group in +the &konqueror; window, then you can set up a filename pattern that +matches <literal>^<replaceable>clientname</replaceable>*</literal>. +Then any files that have <replaceable>clientname</replaceable> at the +beginning (the <token>^</token> character means <quote>starts with...</quote>) and +without any regard to the rest of the filename. +</para> +</note> + +</sect1> + +</chapter> +--> +<chapter id="credits"> +<title>Credits</title> +<sect1 id="authors"> +<title>Authors</title> + +<itemizedlist> +<listitem><para>Matthias Ettrich +<email>[email protected]</email></para></listitem> +<listitem><para>Kalle Dahlheimer <email>[email protected]</email></para></listitem> +<listitem><para>Torben Weiss <email>[email protected]</email></para></listitem> +<listitem><para>Bernd Wuebben <email>[email protected]</email></para></listitem> +<listitem><para>Stephen Schaub <email>[email protected]</email> - +Editor</para></listitem> +<listitem><para>Robert Williams <email>[email protected]</email> - +Editor</para></listitem> +<listitem><para>Lauri Watts <email>[email protected]</email></para></listitem> +</itemizedlist> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; + +</sect1> +</chapter> +</book> + +<!-- +Local Variables: +mode: sgml +sgml-omittag: nil +sgml-shorttag: t +End: +--> + diff --git a/doc/userguide/Makefile.am b/doc/userguide/Makefile.am new file mode 100644 index 000000000..488634323 --- /dev/null +++ b/doc/userguide/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/userguide + diff --git a/doc/userguide/a-window.png b/doc/userguide/a-window.png Binary files differnew file mode 100644 index 000000000..3a0072f99 --- /dev/null +++ b/doc/userguide/a-window.png diff --git a/doc/userguide/accessibility.docbook b/doc/userguide/accessibility.docbook new file mode 100644 index 000000000..e3195635a --- /dev/null +++ b/doc/userguide/accessibility.docbook @@ -0,0 +1,168 @@ + +<chapter id="accessibility"> + +<chapterinfo> +<authorgroup> +<author> +<firstname>Gary</firstname> +<surname>Cramblitt </surname> +</author> +</authorgroup> +</chapterinfo> + +<title>Accessibility</title> + +<indexterm><primary>Accessibility</primary></indexterm> + +<para><acronym>KDEAP</acronym> (the &kde; Accessibility Project) aims to ensure that &kde;, as a desktop environment, is accessible to all users, including those of us with physical disabilities. In addition to the accessibility aids in the <link linkend="kcontrol-regional-and-accessibility">Control Center</link>, &kde; has several other accessibility tools, which are available in the &kde;-Accessibility package. This package may not be installed on your computer; if it is not, you can download it from here:</para> + +<para><itemizedlist> +<listitem><para><ulink url="ftp://ftp.kde.org/pub/kde/stable/apps/KDE3.x/accessibility/kdeaccessibility-1.0.0.tar.gz">kdeaccessibility-1.0.0.tar.gz</ulink>, or +<ulink url="ftp://ftp.kde.org/pub/kde/stable/apps/KDE3.x/accessibility/kdeaccessibility-1.0.0.tar.bz2">kdeaccessibility-1.0.0.tar.bz2</ulink></para></listitem> +<listitem><para><ulink url="ftp://ftp.kde.org/pub/kde/stable/apps/KDE3.x/accessibility/kdeaccessibility-1.0.0.md5">MD5</ulink></para></listitem> +<listitem><para><ulink url="ftp://ftp.kde.org/pub/kde/stable/apps/KDE3.x/accessibility/kdeaccessibility-1.0.0.lsm">lsm file</ulink></para></listitem> +</itemizedlist></para> + +<para>For more information on the project, visit the <ulink url="http://accessibility.kde.org/">&kde; Accessibility Home Page</ulink>.</para> + +<sect1 id="kmousetool"> +<title><application>KMouseTool</application></title> + +<indexterm><primary>Mouse</primary><secondary>clicking +automatically</secondary></indexterm> + +<para> + <application>KMouseTool</application> is a &kde; program, which clicks the mouse for you, so you + do not have to. <application>KMouseTool</application> works with any mouse or pointing device. +</para> +<para> +<inlinemediaobject> + <imageobject> + <imagedata fileref="kmousetool.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>KMouseTool</phrase> + </textobject> +</inlinemediaobject> +</para> + +<itemizedlist><title>Related Information</title> + <listitem><para><application>MouseTool</application> Website: <ulink url="http://mousetool.com/">http://mousetool.com</ulink></para></listitem> + <listitem><para><ulink url="help:/kmousetool"><application>KMouseTool</application> Handbook</ulink></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="kmagnifier"> +<title>KMagnifier</title> + +<indexterm><primary>Magnifier</primary></indexterm> + +<para>KMagnifier (or <command>kmag</command>, to use its &UNIX; name) is a small utility for Linux to magnify + a part of the screen. It magnifies the area of the screen around the + mouse pointer or, optionally, a user-defined area. Additionally, it can save + a magnified screenshot to disk. +</para> + +<para> +<inlinemediaobject> + <imageobject> + <imagedata fileref="kmag.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>KMag</phrase> + </textobject> +</inlinemediaobject> +</para> + +<itemizedlist><title>Related Information</title> + <listitem><para>Website: <ulink url="http://kmag.sourceforge.net/">http://kmag.sourceforge.net</ulink></para></listitem> + <listitem><para><ulink url="help:/kmag"><application>KMag</application> Handbook</ulink></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="kmouth"> +<title><application>KMouth</application></title> + +<indexterm><primary>Speech</primary></indexterm> + +<para><application>KMouth</application> is a KDE program which enables people who cannot speak to let their + computer speak, ⪚ mutal people or people who have lost their voice. + It has a text-input field and speaks the sentences that you enter. It also has + support for user-defined phrasebooks. +</para> + +<para> +<inlinemediaobject> + <imageobject> + <imagedata fileref="kmouth.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>First screenshot of <application>KMouth</application></phrase> + </textobject> +</inlinemediaobject> +</para> +<para> +<inlinemediaobject> + <imageobject> + <imagedata fileref="kmouth2.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Second screenshot of <application>KMouth</application></phrase> + </textobject> +</inlinemediaobject> +</para> +<para> +<inlinemediaobject> + <imageobject> + <imagedata fileref="kmouth3.png" format="PNG" /> + </imageobject> + <textobject> + <phrase>Third screenshot of <application>KMouth</application></phrase> + </textobject> +</inlinemediaobject> +</para> + +<itemizedlist><title>Related Information</title> + <listitem><para>Website: <ulink url="http://www.schmi-dt.de/kmouth/index.en.html">http://www.schmi-dt.de/kmouth/index.en.html</ulink></para></listitem> + <listitem><para><ulink url="help:/kmouth"><application>KMouth</application> Handbook</ulink></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="ktts"> +<title><application>KTTS</application> - Text-to-Speech</title> + +<para><application>KTTS</application> is a &kde; application for the conversion of text into audible speech. Currently, since &kde; 3.4, you can use <application>KTTS</application> to speak any text from the &klipper;, the &kde; clipboard, any text from a plain text file (using &kate; or otherwise), speak any portion of text from a &HTML; page in &konqueror;, and much more.</para> + +<para>To get <application>KTTS</application> up-and-running you will need to start by running <command>kttsmgr</command>, the &kde; Text-to-Speech manager.</para> + +<!-- Insert Screeny here --> + +<itemizedlist><title>Related Information</title> + <listitem><para>Website: <ulink url="http://accessibility.kde.org/developer/kttsd/">http://accessibility.kde.org/developer/kttsd/</ulink></para></listitem> + <listitem><para><ulink url="help:/kttsd"><application>KTTSD</application> Handbook</ulink></para></listitem> + +</itemizedlist> + +</sect1> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/amarok-icon.png b/doc/userguide/amarok-icon.png Binary files differnew file mode 100644 index 000000000..575d9a274 --- /dev/null +++ b/doc/userguide/amarok-icon.png diff --git a/doc/userguide/amarok.png b/doc/userguide/amarok.png Binary files differnew file mode 100644 index 000000000..ddcb285bc --- /dev/null +++ b/doc/userguide/amarok.png diff --git a/doc/userguide/base-kde-applications.docbook b/doc/userguide/base-kde-applications.docbook new file mode 100644 index 000000000..863271b37 --- /dev/null +++ b/doc/userguide/base-kde-applications.docbook @@ -0,0 +1,441 @@ +<chapter id="basic-applications"> + +<chapterinfo> +<authorgroup> +<author> +&Francis.Giannaros; +&Francis.Giannaros.mail; +</author> +</authorgroup> +</chapterinfo> + +<title>The Base &kde; Applications</title> + +<para>What follows is a brief description of a few of the base &kde; applications. For more information on any of the applications you should check the links recommended with each respective entry. </para> + +<!-- What are they?? (Phil) --> +<!-- Included a few here; may be a good idea to add to this in future --> + +<sect1 id="base-applications-fundamental"> + +<title>Fundamentals</title> + +<variablelist> +<varlistentry> +<term>&konqueror;</term> + <listitem><para>&kde;'s file manager, web browser, <acronym>FTP</acronym> client and much more. &konqueror; is the canvas for all the latest &kde; technology, from KIO slaves (which provide mechanisms for file access) to component embedding, allowing it to be a universal viewing application, capable of displaying various image files as well as documents.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://konqueror.org">http://konqueror.org</ulink></para></listitem> + <listitem><para>View the handbook by typing <userinput>help:/konqueror</userinput> in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;.</para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kate;</term> + <listitem><para>&kde;'s advanced multi-view text editor. &kate; is excellent for things such as viewing the &HTML; source of a webpage to handling advanced coding in <acronym>C++</acronym>, <acronym>PHP</acronym> and <acronym>XML</acronym> with its powerful syntax highlighting engine and code folding capabilities. &kate; is a very speedy application, being capable of opening huge text files in a matter of seconds, as well as allowing you to view a hefty amount of multiple views in order to see more instances of the same document and/or more documents at any particular time.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kate.kde.org">http://kate.kde.org</ulink></para></listitem> + <listitem><para><ulink + url="help:/kate">&kate; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +<!-- Insert Screeny --> + +</varlistentry> + +<varlistentry> +<term>&konsole;</term> + <listitem><para>The X terminal emulator for &kde;. &konsole;, like many &kde; applications, is extremely customizable; while you can create your own user sessions, you can also of course open &Linux; console sessions, shell sessions, as well as standard <systemitem class="username">root</systemitem> and sudo sessions.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://konsole.kde.org">http://konsole.kde.org</ulink></para></listitem> + <listitem><para><ulink + url="help:/konsole">&konsole; Handbook</ulink></para></listitem> + <listitem><para>User Guide <xref linkend="konsole-intro" /></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + + +<varlistentry> +<term>&kicker;</term> + <listitem><para>The &kde; Panel, used for handling your currently running applications, a pager allowing you to switch between desktops, quick launch buttons to act as application launchers and much more.</para> + + <itemizedlist> + <listitem><para>See <xref linkend="panel-and-desktop"/> for altering some of its settings.</para></listitem> + <listitem><para><ulink + url="help:/kicker">&kicker; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term><application>kdcop</application></term> +<!-- Mainly mentioned to raise awareness, for DCOP --> + <listitem><para>A <acronym>GUI</acronym> front-end to the powerful &DCOP; (Desktop COmmunications Protocol). &DCOP; provides a comprehensive protocol for interprocess communication between &kde; applications. While this is increasingly useful to &kde; programmers, it is also beneficial to the ordinary user who would want to create a script, or, say, a <application>SuperKaramba</application> theme.</para> + + <itemizedlist> + <listitem><para>In the User Guide <xref linkend="scripting-the-desktop"/> and <xref linkend="kdialog"/></para></listitem> + <listitem><para>Other Documentation: <ulink + url="http://developer.kde.org/documentation/library/kdeqt/dcop.html">http://developer.kde.org/documentation/library/kdeqt/dcop.html</ulink></para></listitem> + + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term>&kcontrol;</term> + <listitem><para>The control center for the K Desktop Environment. You can alter a myriad of different things, ranging from themes, fonts and screensavers, to Internet, security and system administration.</para> + + <itemizedlist> + <listitem><para>See <xref linkend="control-center"/>.</para></listitem> + <listitem><para><ulink + url="help:/kcontrol">&kcontrol; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&khelpcenter;</term> + <listitem><para>The &kde; help system is used to provide access to the base &UNIX; help pages (man or info) as well as the native &kde; documentation provided by the &kde; documentation team or the application authors. You should be able to access all of the &kde; application handbooks from here.</para> + + <itemizedlist> + <listitem><para><ulink + url="help:/khelpcenter">&khelpcenter; Handbook</ulink></para></listitem> + <listitem><para>For information on the &kde; Documentation team, how to possibly join and help &kde;, see: <ulink url="http://kde.org/documentation">http://kde.org/documentation</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + + </variablelist> + +<itemizedlist> +<title>Related Information</title> + <listitem><para><ulink url="http://kde-apps.org">http://kde-apps.org</ulink> -- The largest directory of third-party &kde; applications.</para></listitem> + <listitem><para>As you may have noticed, a wealth of information is accessible from the respective handbooks themselves, which can be accessed either by using the help KIO slave in &konqueror; (that is, type <userinput>help:/<replaceable>application</replaceable></userinput> in the Location toolbar), or by selecting it in the &khelpcenter;.</para></listitem> + <listitem><para>You can also likely find out quite a bit of information from the &kde; website, itself, at <ulink url="http://kde.org">http://kde.org</ulink>.</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="base-applications-kdepim"> +<sect1info> +<authorgroup> +<author> +&Francis.Giannaros; +&Francis.Giannaros.mail; +</author> +</authorgroup> +</sect1info> + +<title>Personal Information Management</title> + +<para>&kde; <acronym>PIM</acronym> (Personal Information Manager) is a sub-project of &kde;, and it aims to provide an application suite to manage personal information. It has several components, but these can all be brought under one application -- &kontact;, which is the personal information manager. Below is an overview of a few of its popular components; that is, a few of the applications that integrate into it.</para> + +<variablelist> +<varlistentry> +<term>&kontact;</term> + <listitem><para>This serves as the medium by which the rest of the applications in &kde; <acronym>PIM</acronym> can integrate with one another. All of the applications in &kde; <acronym>PIM</acronym> can be displayed inside here, and you can easily choose which ones to display. It also contains a Summary page by which you can get a brief overview of events and information in the other components.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kontact.kde.org">http://kontact.kde.org</ulink></para></listitem> + <listitem><para>View the handbook by typing <userinput>help:/kontact</userinput> in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;.</para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kmail;</term> + <listitem><para>The mail component. &kmail; comes with full <acronym>IMAP</acronym>, <acronym>POP3</acronym> and <acronym>SMTP</acronym> support. Signing and encrypting of emails is permitted, and there are many comprehensive anti-spam functions available. A spell check can easily be used, &HTML; emails can be viewed appropriately, and there is an advanced search feature.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kmail.kde.org">http://kmail.kde.org</ulink></para></listitem> + <listitem><para><ulink url="help:/kmail">&kmail; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&korganizer;</term> + <listitem><para>A fully customizable organizer which constitutes as the calender component. &korganizer; provides management of events and tasks, alarm notification, web export, network transparent handling of data, group scheduling, import and export of calendar files, and much more.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://korganizer.kde.org">http://korganizer.kde.org</ulink></para></listitem> + <listitem><para><ulink url="help:/korganizer">&korganizer; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kaddressbook;</term> + <listitem><para>The contacts component. &kaddressbook; enables you to manage your contacts efficiently and comfortably; contacts can be easily exported and imported from a plethora of different address book standards, and it can be efficiently integrated with &kopete;, &kde;'s multi-protocol instant messenger. Other features include support for all international character sets and advanced search functions.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://pim.kde.org/components/kaddressbook.php">http://pim.kde.org/components/kaddressbook.php</ulink></para></listitem> + <listitem><para><ulink url="help:/kaddressbook">&kaddressbook; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&knotes;</term> + <listitem><para>A handy component which can serve to handle all your digital sticky notes. You can have them displayed on your desktop, they can be <quote>dragged n' dropped</quote> into emails, printed, or even be displayed after &kontact; is closed down.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://pim.kde.org/components/knotes.php">http://pim.kde.org/components/knotes.php</ulink></para></listitem> + <listitem><para><ulink url="help:/knotes">&knotes; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&knode;</term> + <listitem><para>The newsreader component. It is <acronym>GNSKA</acronym> (The Good Net-Keeping Seal of Approval) compliant, has support for <acronym>MIME</acronym> and multiple servers.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://knode.sourceforge.net/">http://knode.sourceforge.net/</ulink></para></listitem> + <listitem><para><ulink url="help:/knode">&knode; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&akregator;</term> + <listitem><para>A lightweight and fast program to display news items provided by feeds, supporting all commonly used versions of <acronym>RSS</acronym> and <acronym>Atom</acronym> feeds. Useful features include searching in article titles, management of feeds in folders and setting archiving preferences.</para> + <itemizedlist> + <listitem><para>Website: <ulink url="http://akregator.sourceforge.net">http://akregator.sourceforge.net</ulink></para></listitem> + <listitem><para><ulink url="help:/akregator">&akregator; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +</variablelist> + +<itemizedlist> +<title>Related Information</title> + <listitem><para>See <ulink url="http://kontact.kde.org">http://kontact.kde.org</ulink> and <ulink url="http://kdepim.kde.org">http://kdepim.kde.org</ulink> for more information.</para></listitem> + <listitem><para><ulink url="help:kontact">&kontact; Handbook</ulink></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="network-applications"> + +<title>Network</title> + +<para>There are several network-related applications in &kde;. Below is a description of a few of these.</para> + +<variablelist> +<varlistentry> +<term>&kopete;</term> + <listitem><para>A fully-featured and advanced <acronym>IM</acronym> (Instant Messaging) client, which has a number of protocols including <trademark class="registered">MSN</trademark>, <trademark class="registered">Yahoo</trademark>, and <trademark class="registered">AIM</trademark>. &kopete; can fetch display pictures, set aliases for particular persons, as well as run multiple <acronym>IM</acronym> sessions at any particular time. &kopete; is quite extensible, and has a comprehensive plugin system which comes with a searchable History of previous chats, statistics on a user's status, as well as a note system allowing you to create notes for each contact.</para> + <itemizedlist> + <listitem><para>Website: <ulink url="http://kopete.kde.org">http://kopete.kde.org</ulink></para></listitem> + <listitem><para><ulink url="help:/kopete">&kopete; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term>&kdict;</term> + <listitem><para>A &GUI; front-end to the <acronym>DICT</acronym> protocol. It enables you to search through dictionary databases for a word or phrase, then displays suitable definitions.</para> + <itemizedlist> + <listitem><para><ulink url="help:/kdict">&kdict; Handbook</ulink></para></listitem> + <listitem><para>The <acronym>DICT</acronym> Development Group: <ulink url="http://www.dict.org/bin/Dict">http://www.dict.org/bin/Dict</ulink>.</para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term>&kget;</term> + <listitem><para>A manager for your downloads which integrates with &konqueror;. &kget; allows you to group your downloads, pause and resume them, as well as several other things. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kget.sourceforge.net/">http://kget.sourceforge.net</ulink></para></listitem> + <listitem><para><ulink url="help:/kget">&kget; Handbook</ulink></para></listitem> + + </itemizedlist> + </listitem> +</varlistentry> +</variablelist> + +<itemizedlist> +<title>Related Information</title> + <listitem><para>Several more &kde; network applications can be found in the &kde; Extragear; see <xref linkend="extragear-network"/>, under <xref linkend="extragear-components"/>.</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="office-applications"> + +<title>Office</title> + +<para>This includes all applications in the &koffice; suite. See <xref linkend="kde-office-components" /> for a summary of the components.</para> + +</sect1> + +<sect1 id="graphics-applications"> + +<title>Graphics</title> + +<para>&kde; has several graphics-related applications, ranging from <acronym>PDF</acronym> viewers to applications enabling you to take screenshots. Below is a delineation, as well as some related links, for a few of them.</para> + +<variablelist> + +<varlistentry> +<term><application>KColorEdit</application></term> + <listitem><para>A small and handy application for editing color palettes, as well as color choosing and naming. Colors can be chosen by giving the <acronym>RGB</acronym> hex code, by choosing the color from a myriad of different colors in the program, or even by grabbing the precise color of any particular thing on your screen.</para> + + <itemizedlist> + <listitem><para><ulink url="help:/kcoloredit"><application>KColorEdit</application> Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term><application>KPDF</application></term> + <listitem><para>An advanced <acronym>PDF</acronym> viewer, based on <application>xpdf</application>, for &kde;. <application>KPDF</application> contains a number of ways to search through the document (standard find dialog, thumbnail filter, etc.) and has other features such as hands-free reading.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kpdf.kde.org">http://kpdf.kde.org</ulink></para></listitem> + <listitem><para><ulink url="help:/kpdf"><application>KPDF</application> Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term><application>KView</application></term> + <listitem><para>An image viewer program which supports a number of different image filetypes including <acronym>JPEG</acronym>, <acronym>GIF</acronym>, <acronym>PNG</acronym>, <acronym>TIFF</acronym> and many others. <application>Kview</application> has full integration with &kde; and it can be embedded into &konqueror; for viewing image files on your diskdrive as well as your <acronym>FTP</acronym> site or webserver, using its &URL; open support. Other features include a few image manipulations such as zoom, rotate, grayscale and flip. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.ph.unimelb.edu.au/~ssk/kde/kview/">http://www.ph.unimelb.edu.au/~ssk/kde/kview/</ulink></para></listitem> + <listitem><para><ulink url="help:/kview"><application>KView</application> Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term>&ksnapshot;</term> + <listitem><para>An application for taking screenshots. It is capable of capturing images of the whole desktop, a single window, or a selected region. The images can then be saved in a variety of formats, including <acronym>JPG</acronym> and <acronym>PNG</acronym>.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.ipso-facto.demon.co.uk/ksnapshot/">http://www.ipso-facto.demon.co.uk/ksnapshot/</ulink></para></listitem> + <listitem><para><ulink url="help:/ksnapshot">&ksnapshot; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term>&kolourpaint;</term> + <listitem><para>A simple and easy-to-use paint program, with features such as basic painting (drawing diagrams and finger painting), image manipulation and icon editing. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kolourpaint.sourceforge.net">http://kolourpaint.sourceforge.net</ulink></para></listitem> + <listitem><para><ulink url="help:/kolourpaint">&kolourpaint; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + + +<varlistentry> +<term>&kooka;</term> + <listitem><para>An intuitive raster image scan program. &kooka; helps you to handle the most important scan parameters, find the correct image file format to save and manage your scanned images.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kooka.kde.org">http://kooka.kde.org</ulink></para></listitem> + <listitem><para><ulink url="help:/kooka">&kooka; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +</variablelist> + +<itemizedlist> +<title>Related Information</title> + <listitem><para>Several more advanced &kde; graphics applications can be found in the &kde; Extragear; under the <xref linkend="extragear-components"/>, see <xref linkend="extragear-graphics"/> for a list of a few of them.</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="multimedia-applications"> +<title>Multimedia</title> + +<para>A brief overview of a few of the multimedia-related applications below.</para> + +<variablelist> +<varlistentry> +<term>&juk;</term> + <listitem><para>An easy-to-use music player for &kde;. &juk; is playlist and meta-data focused, allowing you to quickly search through the dynamic playlist provided. Some of the features include &CD; cover-art fetching from <trademark class="registered">Google</trademark> images, <application>MusicBrainz</application> integration for file identification over the Internet, and multiple audio backends, including &arts;, <application>GStreamer</application> and <application>aKode</application>. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://developer.kde.org/~wheeler/juk.html">http://developer.kde.org/~wheeler/juk.html</ulink></para></listitem> + <listitem><para><ulink url="help:/juk">&juk; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term>&kmix;</term> + <listitem><para>An application that allows you to change the volume of your sound card, and it supports several sound drivers. Each mixer device is represented by a volume slider, and you have basic options such as to mute that particular mixer device.</para> + + <itemizedlist> + <listitem><para><ulink url="help:/kmix">&kmix; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +<varlistentry> +<term>&noatun;</term> + <listitem><para>A media player capable of playing <acronym>WAV</acronym>, <application>Ogg Vorbis</application>, as well as DivX encoded <acronym>AVI</acronym>s and other media formats. &noatun; features audio effects, a six-band graphic equalizer, a full plugin architecture, network transparency, and various look and feels. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://noatun.kde.org">http://noatun.kde.org</ulink></para></listitem> + <listitem><para><ulink url="help:/noatun">&noatun; Handbook</ulink></para></listitem> + </itemizedlist> + </listitem> +</varlistentry> + +</variablelist> + +<itemizedlist> +<title>Related Information</title> + <listitem><para>Several more advanced &kde; multimedia applications can be found in the &kde; Extragear; under the <xref linkend="extragear-components"/>, see <xref linkend="extragear-multimedia"/> for a list of a few of them.</para></listitem> +</itemizedlist> + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/browser-fine-tuning.docbook b/doc/userguide/browser-fine-tuning.docbook new file mode 100644 index 000000000..0a503b6bb --- /dev/null +++ b/doc/userguide/browser-fine-tuning.docbook @@ -0,0 +1,71 @@ +<sect1 id="customizing-konqueror"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Fine Tuning your Browsing Experience</title> + +<example> +<title>Using your own style for webpages</title> + +<para>Webpages come in every possible set of colors and fonts, and +sometimes this doesn't give the best result. For example, if you have +visual difficulties, it may be impossible to read certain combinations +of background and text colors. &konqueror; provides a way to choose +your own colors and apply them to all webpages. Here's how:</para> + +<orderedlist> +<listitem><para>Open &konqueror; and go to +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Konqueror...</guimenuitem></menuchoice>.</para> +</listitem> +<listitem><para>In the configuration dialog that appears, select the +<guilabel>Stylesheets</guilabel> page on the left hand side.</para> +</listitem> +<listitem><para>On this page, choose <guilabel>Use accessibility +stylesheet defined in "Customize" tab</guilabel>, then go to the +<guilabel>Customize</guilabel> tab, and choose the settings you prefer.</para> +</listitem> +<listitem><para>Close all &konqueror; windows (you may need to restart +&kde; to be sure) and when you re-open them, your settings should be applied.</para> +</listitem> +</orderedlist> + +</example> + + +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/burning-cds.docbook b/doc/userguide/burning-cds.docbook new file mode 100644 index 000000000..901709ff4 --- /dev/null +++ b/doc/userguide/burning-cds.docbook @@ -0,0 +1,38 @@ +<sect1 id="burning"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Burning CDs and DVDs</title> + +<para>Brief overview of k3b</para> + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/control-center.docbook b/doc/userguide/control-center.docbook new file mode 100644 index 000000000..240046c73 --- /dev/null +++ b/doc/userguide/control-center.docbook @@ -0,0 +1,922 @@ +<chapter id="control-center"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<chapterinfo> +<authorgroup>Here you can set up different profiles for your Wireless card, +to be able to quickly switch settings if you connect to multiple +networks. You can select a profile to be loaded on KDE startup. +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</chapterinfo> +--> + +<title>The &kcontrolcenter;</title> + +<indexterm><primary>&kcontrolcenter;</primary></indexterm> +<indexterm><primary>&kcontrol;</primary></indexterm> +<indexterm><primary>Configuration</primary></indexterm> +<indexterm><primary>Customization</primary></indexterm> + +<mediaobject> +<imageobject> +<imagedata fileref="kcontrol.png" format="PNG" /> +</imageobject> +<textobject><phrase>The &kcontrolcenter;</phrase></textobject> +<caption><para>The &kcontrolcenter;</para></caption> +</mediaobject> + +<para>The &kcontrolcenter; is the place to go to change any settings that +affect the whole of your &kde; environment. You can open it using the +<guimenuitem>Control Center</guimenuitem> item in the &kmenu;, or with its +command-line name, <filename>kcontrol</filename>.</para> + +<para>The settings are divided into several major categories, which each +contain several pages of settings. To display a settings page, expand the +major category by clicking on the <guilabel>+</guilabel> button next to it, +and then click on the name of the page you want. The settings page then +appears on the right, and you can change settings to your heart's +content. No changes take effect until you click on the +<guibutton>Apply</guibutton> button. If you decide, after making some +changes, that you want to leave the settings as they were, just click on +<guibutton>Reset</guibutton>.</para> + +<para>If you need more help with a page, visit that page, then click on the +<guilabel>Help</guilabel> tab. You might also want to look at the +&kcontrolcenter; Handbook, which you can open with the +<menuchoice><guimenu>Help</guimenu><guimenuitem>&kcontrolcenter; +Handbook</guimenuitem></menuchoice>.</para> + + +<sect1 id="kcontrol-appearance-and-themes"> +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> + +<title>Appearance & Themes</title> + +<para>Here you will find settings that change the way your &kde; desktop and +applications look.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Background</guilabel></term> +<listitem> +<para>This section controls the color or image that is set as your desktop +background. These settings can be applied to all virtual workspaces, or to +only a specific one. There are a range of background wallpapers that come +with &kde; or you can supply your own.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Colors</guilabel></term> +<listitem> +<para>This is where you can modify the colors for your kde applications. +There are a variety of color schemes installed with &kde; by default, and +you can find others at kde-look.org. You can also create your own. Here you +can also modify the contrast and choose whether you want your &kde; colors +to be applied to non-kde applications, for a more consistant overall +appearance.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Fonts</guilabel></term> +<listitem> +<para>Here you can control the various font settings for &kde; applications. +You can also modify here anti-aliasing settings, including what range of +fonts to exclude from anti-aliasing settings.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Icons</guilabel></term> +<listitem> +<para>This section is where you can manage your icon themes and other +settings related to icons. New icon themes can be downloaded from +kde-look.org, and installed here. Conversely, you can remove icon themes by +highlighting them in the list and clicking remove. You can also set icon +sizes for various uses in &kde; and effects to apply to icons.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Launch Feedback</guilabel></term> +<listitem> +<para>This is where you can modify what kind of cursor and/or taskbar +feedback you'd like for launching applications. You can also set the +duration of this feedback here. For example, the default setting is for a +bouncing cursor with a duration of 30 seconds, or when the application has +loaded.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Screen Saver</guilabel></term> +<listitem> +<para>Here you can configure options about your screensaver. You can +configure the timeout before it starts, and whether it requires a password +to unlock the screen.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Splash Screen</guilabel></term> +<listitem> +<para>This is where you can install, remove and test the splash screens that +display on &kde; startup. More splash screens can be downloaded from +<ulink +url="http://www.kde-look.org"> + +http://www.kde-look.org</ulink>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Style</guilabel></term> +<listitem> +<para>This section allows you to modify your widget style. A variety of +styles come with &kde;, and more can be downloaded from <ulink url="http://www.kde-look.org">http://www.kde-look.org</ulink>. This is also +where you would enable or disable interface options such as transparent +menus, showing icons on buttons and tooltips. Some styles have more +configuration options than others.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Theme Manager</guilabel></term> +<listitem> +<para>This is where you can create and manage themes that are made up of +personalized settings. They are a combination of desktop background, colors, &kde; widget styles, icons, fonts and what Screensaver you'd like to display . This allows you to save your favorite +<quote>looks</quote> and apply them with the click of a mouse button.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Window Decorations</guilabel></term> +<listitem> +<para>Here you can configure your window decorations. You can modify the +style as well as place the buttons in custom positions. Some window +decorations will have more configuration options than others.</para> +</listitem> +</varlistentry> +</variablelist> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> <listitem><para>If &kcontrolcenter; +doesn't have the setting you want, you may need to edit a configuration file +manually. See <xref linkend="hand-editing-config-files" /> for more +information about how to do this.</para> +</listitem> + +<listitem><para>If you enjoy modifying the appearance of your &kde; desktop, +you can find plenty of themes and styles at <ulink url="http://kde-look.org">kde-look.org</ulink>.</para> +</listitem> + +</itemizedlist> + + +</sect1> + +<sect1 id="kcontrol-desktop"> +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> +<title>Desktop</title> + +<para>This is where you will find settings to configure the appearance and +behavior of your &kde; desktop.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Behavior</guilabel></term> +<listitem> +<para>Here you can configure the behavior of your desktop. This is where +you would go to configure options such as showing or hiding desktop icons, +showing tooltips and icon layout. You can also specify if you would like to +see previews of particular filetypes on the desktop, and which devices you'd +like to see icons for.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Multiple Desktops</guilabel></term> +<listitem> +<para>This is where you would configure the number of virtual desktops or +workspaces you would like to have, and what you would like them to be +called. By default &kde; has 4 virtual desktops, and you can configure up to +20. You can also enable switching between virtual desktops using the scroll +button on your mouse.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Panels</guilabel></term> +<listitem> +<para>Here you can modify options to do with &kicker; and other &kde; +panels. Among the options are size, position, length and hiding. You can +also modify the appearance of the panel with transparency, background images +and icon zooming. This is also where you would configure various menu +options including what applications you'd like to show in your +&kmenu;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Taskbar</guilabel></term> +<listitem> +<para>The Taskbar module allows you to configure options related to your +taskbar. You can configure whether to show windows from all desktops, +grouping of similar tasks and what actions you would like to assign to your +mouse buttons.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Window Behavior</guilabel></term> +<listitem> +<para>This is where you would configure options related to the behavior of +&kde;'s window manager, &kwin;. &kwin; is extremely configurable and has +advanced features such as focus stealing prevention and different focus +policies such as focus follows mouse. You can also configure what actions +you would like to bind to certain keys and mouse events.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Window-Specific Settings</guilabel></term> +<listitem> +<para>This is an advanced configuration dialog where you can set options for +the behavior of specific windows. There are many options here for the fine +tuning of your window layout, including what position on the screen you +would like certain windows to open to, and whether they should be shown on +the taskbar or pager. You can select windows by application, or even by +their specific role within an application.</para> +</listitem> +</varlistentry> +</variablelist> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + +</sect1> + +<sect1 id="kcontrol-internet-and-network"> +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> +<title>Internet & Network</title> + +<para>This section is where you would configure settings to do with internet +and networking under &kde;.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Connection Preferences</guilabel></term> +<listitem> +<para>Here you can set advanced networking options such as timeout values +for server connects. Usually you would leave these options at the defaults +unless you really knew what you were doing.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Desktop Sharing</guilabel></term> +<listitem> +<para>Desktop Sharing allows you to invite someone to share your session +with you, or can enable you to log in remotely to your machine from another +location. You would then use a VNC client like &kde;'s Remote Desktop +Connection application to control your desktop over the network. This is +extremely useful if you want someone to help you perform a task. </para> + +<para>Here you can create and manage invitations as well as set your +security policy for uninvited connections. You can also configure whether to +show a background image and which port for the service to 'listen' +on.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>File Sharing</guilabel></term> +<listitem> +<para>File sharing allows you to configure Samba (&Microsoft; &Windows;) and +<acronym>NFS</acronym> (&UNIX;) file sharing. To make changes in this module +you need to have the root or administrator password. This is where you would +set up whether users are allowed to share files without knowing the root +password, and which users are allowed to do so. You can also configure which +folders you're like to be shared, using which type of sharing and who is +allowed to view these shares.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Local Network Browsing</guilabel></term> +<listitem> +<para>Here you can configure options related to browsing network shares in +&konqueror;. &konqueror; is able to browse a variety of network shares and +manipulate remote files as though they were on your local machine. You can +configure it to remember your preferred username and password for connecting +to &Windows; shares (Samba). You can also set what types of network shares +you would like to be able to browse, including &FTP;, <acronym>NFS</acronym> +and <acronym>SMB</acronym>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Local Network Chat</guilabel></term> +<listitem> +<para>This module allows you to configure options relating to the &UNIX; +<command>talk</command> daemon. It is a very simple network chat program +that runs in a terminal, designed for chatting over a local area +network. Some of it's features are being able to set up an 'answering +machine' that will email to you messages left for you, and being able to +forward messages to another location.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Proxy</guilabel></term> +<listitem> +<para>This is where you would configure &kde; to connect to a proxy server +rather than directly to the internet. Once again you would generally leave +these options at their defaults unless you really knew what you were +doing. If you do use a proxy server your network administrator will be able +to tell you what details to fill in here.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Samba</guilabel></term> +<listitem> +<para>The Samba Configuration module requires the +<systemitem class="username">root</systemitem> or administrator password. It is +an advanced configuration tool that allows you to control Samba's security, +shares, users and printers in an intuitive graphical interface. This is a +very powerful tool with support for configuring everything from simple file +and printer sharing, to using your Samba server as a &Windows; NT Domain +Controller.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Service Discovery</guilabel></term> +<listitem> +<para>You can set up services browsing with ZeroConf. You can for example browse +your local network using multicast DNS.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Web Browser</guilabel></term> +<listitem> +<para>This module is where you would configure options relating to +&konqueror; as a web browser. The usual options you would expect from a +web browser, such as cookie configuration, cache and history can be found +here as well as sections to modify keyboard shortcuts, plugins and +fonts.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Wireless Network</guilabel></term> +<listitem> +<para>Here you can set up different profiles for your Wireless card, to be +able to quickly switch settings if you connect to multiple networks. You can +select a profile to be loaded on &kde; startup.</para> +</listitem> +</varlistentry> +</variablelist> + + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + +</sect1> + +<sect1 id="kcontrol-kde-components"> + + +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> + +<title>&kde; Components</title> + +<para>This section is where you can modify advanced &kde; options such as +file associations and default applications.</para> + +<variablelist> + +<varlistentry><term><guilabel>Component Chooser</guilabel></term> + +<listitem><para>The component chooser allows you to select the default +applications you would like to use for various services. Here you can define +what Email Client, Embedded Text Editor, Instant Messenger, Terminal +Emulator and Web Browser to use. If you prefer to use +<application>Xterm</application>, <application>Vim</application> or +<application>Mozilla</application>, this is the place to specify those +preferences.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>File Associations</guilabel></term> + +<listitem><para>This is where you configure everything to do with file +associations. Here you can select a filetype, and choose what applications +you would like to be able to open it with. You can also select which icon +you would like to represent each filetype, and whether to show it in an +embedded or a separate viewer.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>File Manager</guilabel></term> + +<listitem><para>Here you can configure the behavior of &konqueror; in file +manager mode. Among the options are fonts and font sizes, previews over +various network protocols and context menus. &konqueror; is an extremely +powerful and configurable file management tool with a plethora of +options. For more information, consult the &konqueror; handbook.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>KDE Performance</guilabel></term> + +<listitem><para>Here are settings related to the memory usage of +&konqueror;. <guilabel>Minimize Memory Usage</guilabel> allows you to +control whether separate instances of &konqueror; will open or whether all +new &konqueror; windows connect to the same instance. This has the effect of +reducing memory usage. You can also select whether to pre-load &konqueror; +after &kde; startup, to reduce start times.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>KDE Resources Configuration</guilabel></term> + +<listitem><para><remark>To be written</remark></para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>Service Manager</guilabel></term> + +<listitem><para>The Service Manager module displays a static list of +services that are started on demand, and a second list of services that can +be manipulated by the user. The services in the first list cannot be +modified or changed. The services in the second list you can enable or +disable a service loading at start up, and manually start and stop +services.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>Session Manager</guilabel></term> + +<listitem><para>Here you can configure how you would like &kde; to handle +sessions. You can configure &kde; to remember your previous session and +restore the applications you were using the next time you log in. You can +also specify individual applications to exclude from being restored, or +disable restoring sessions on login entirely.</para> +</listitem> +</varlistentry> + +<varlistentry><term><guilabel>Spell Checker</guilabel></term> + +<listitem><para>This module allows you to configure the &kde; Spell +checker. It allows you to modify what spell checker to use, what types of +error to check for and also what default dictionary to use. &kde; supports +the use of both <application>ASpell</application> and +<application>ISpell.</application></para> +</listitem> +</varlistentry> + + +<varlistentry><term><guilabel>Vim Component Configuration</guilabel></term> + +<listitem><para>This module allows you to configure the use of +<application>Vim</application> as an embeddable component. You need to have +a recent version of <application>Gvim</application> or +<application>Kvim</application> installed for this. You can configure the +appearance of the editor as well as which <command>vim</command> binary to +use.</para> +</listitem> +</varlistentry> + +</variablelist> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + +</sect1> + +<sect1 id="kcontrol-peripherals"> +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> +<title>Peripherals</title> + +<para>This section is where you would change settings related to peripheral +devices such as keyboards and joysticks.</para> + +<variablelist> +<varlistentry><term><guilabel>Display</guilabel></term> + +<listitem><para>Here you can modify settings to do with the size, +orientation and refresh rate of your display, and whether you would like +these settings to be applied on &kde; startup. On the <guilabel>Power +Control</guilabel> tab, you can configure your power management options for +this screen such as blanking. </para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Joystick</guilabel></term> + +<listitem><para>This section allows you to configure your joystick and test +that it is working properly. You can also calibrate your joystick here, and +manually specify the joystick device if it is not autodetected correctly. +</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Keyboard</guilabel></term> + +<listitem><para>This module allows you to configure basic keyboard settings. +These include keyboard repeat delay and rate, and what state you would +prefer numlock to be on KDE startup.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Mouse</guilabel></term> + +<listitem><para>Here is where you can configure settings to do with your +mouse device. You can switch the button order, reverse the scroll direction +or modify the behaviour of clickable icons. You may also preview, install +and select cursor themes. The <guilabel>Advanced</guilabel> tab allows you +to fine tune your mouse settings further.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Printers</guilabel></term> + +<listitem><para> This dialog allows you to configure printers using a +variety of print systems. You can add local and remote printers, check +current jobs and look at printer properties.</para> +</listitem> +</varlistentry> + +</variablelist> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + +</sect1> + +<sect1 id="kcontrol-power-control"> +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> + +<title>Power Control</title> + +<para>This section has a single module, <guilabel>Laptop Battery</guilabel>. +Here you can configure the appearance and behaviour of the <application>Klaptopdaemon</application> +battery monitor. You can select battery icons to represent different power states, and set up +notification of certain events. In the case that your battery runs down to a critical level, you can +configure the daemon to suspend or shutdown your laptop, to save you from losing data. +</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + +</sect1> + +<sect1 id="kcontrol-regional-and-accessibility"> +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> + +<title>Regional & Accessibility</title> +<para>This section is where you can configure options to do with region +and locale, and also acessibility related options for disabled +persons.</para> + +<variablelist> + +<varlistentry><term><guilabel>Accessibility</guilabel></term> + +<listitem><para>Here is where you can configure options for users who have +difficulty hearing system sounds or using a keyboard. You can configure the +system bell to use a visual signal, such as flashing the screen or inverting +screen colors. You can also configure keyboard accessibility options such +as sticky keys and slow keys.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Country/Region & Language</guilabel></term> + +<listitem><para>This module allows you to configure options that are +specific to your location such as language, currency and date format. To +make available more languages, install the kde-i18n packages for your +distribution.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Input Actions</guilabel></term> + +<listitem><para>Here is where you would configure input actions, such as +mouse gestures and keyboard shotcuts for launching applications and running +commands.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Keyboard Layout</guilabel></term> + +<listitem><para>This module is where you would configure +<application>Kxkb</application>, a keyboard layout switching utility that +uses the &X-Window; xkb extension. It allows you to switch between different +layouts using a tray indicator or a keyboard shortcut. You can +enable/disable keyboard layouts through this dialog, and add more. Some of +the more powerful features are the ability to configure switching of layouts +globally, per application or per window.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Keyboard Shortcuts</guilabel></term> + +<listitem><para>Here you can configure global &kde; keyboard +shortcuts. There are several predefined shortcut schemes you can use if you +are more used to another windowing environment, like &Windows; or +&MacOS;. If you prefer, you can customise your own scheme and modifier keys. +</para></listitem> +</varlistentry> +</variablelist> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + +</sect1> + +<sect1 id="kcontrol-security-and-privacy"> +<sect1info> +<authorgroup> +<author> +&Anne-Marie.Mahfouf; +&Anne-Marie.Mahfouf.mail; +</author> +<author> +<firstname>Javier</firstname> +<surname>Martín Diez</surname> +</author> +<othercredit role="reviewer"> +<personname><firstname>Rocco</firstname> <surname>Stanzione</surname> +</personname> +</othercredit> +</authorgroup> +</sect1info> +<title>Security & Privacy</title> + +<para>This section is where you can configure options related to +security and privacy such as the use of cryptography, enabling the KDE +wallet, setting your identity and managing caches.</para> + +<variablelist> +<varlistentry><term><guilabel>Crypto</guilabel></term> +<listitem><para>This module allows you to configure SSl for use with most +KDE applications, as well as manage your personal certificates +and the known certificate authorities.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>KDE Wallet</guilabel></term> +<listitem><para> +Here you can change your KDE Wallet Manager settings.</para> + +<para>KDE Wallet aims to provide secure storage for passwords and web form data. +You can group different passwords in different wallets, and each one will only +be opened with a master password (which you should never forget!). The +default wallet is named "kdewallet", and you can either create a new wallet +for your local passwords or accept the default wallet for all data in +the "Automatic Wallet Selection" section.</para> + +<para>KDE programs like Konqueror, Kmail and Kopete are fully compatible with +the KDE Wallet Manager. All of them will ask at least once for permission to +access to actual wallet. You can give different access levels, such as "always +allow", "allow once", etc. If you want to change that access level, you can do +it from the "Access Control" tab by deleting the program entry and selecting a +new preference the next time that application requests access to the +wallet.</para> + + <variablelist> + + <varlistentry><term><guilabel>Wallet Preferences</guilabel></term> + + <listitem><para>To enable the KDE wallet subsystem, check the <guilabel> +Enable the KDE wallet subsystem</guilabel> box. +Unchecking this box will disable the KDE Wallet on your system.</para> + +<para>By default, KDE Wallet Manager is kept opened until the +user session is closed, but you can change that in the <guilabel>Close +Wallet</guilabel> section to close it when unused for a time, when a screen +saver starts or when the last application stops using it.</para> + +<para>As you can have several wallets, <guilabel>Automatic Wallet +Selection</guilabel> allows you start KDE with a given wallet.</para> + +<para>KDE Wallet will appear in your system tray by default, but you can hide +it. Uncheck <guilabel>Show manager in the system tray</guilabel> to keep it +always hidden, or check <guilabel>Hide system tray icon when last wallet +closes</guilabel> to hide it only when all wallets are closed. These items are +in the <guilabel>Wallet Manager</guilabel> section.</para></listitem> +</varlistentry> + + +<varlistentry><term><guilabel>Access Control</guilabel></term> + +<listitem><para>You can set here what policy you want for your +KDE applications, regarding to the wallet use.</para></listitem> +</varlistentry> +</variablelist> + +</listitem> +</varlistentry> + + +<varlistentry><term><guilabel>Password & User Account</guilabel></term> +<listitem><para>You can change here your personal information +which will be used in mail programs and word processors. You +can change your login password by clicking the <guibutton>Change +Password...</guibutton> button.</para></listitem> +</varlistentry> + +<varlistentry><term><guilabel>Privacy</guilabel></term> +<listitem><para>This module allows you to erase traces which +KDE leaves on your system such as command histories or +browser caches.</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<!-- <sect1 id="kcontrol-sound-and-multimedia"> +<title>Sound & Multimedia</title> +<para>to be written</para> + +<itemizedlist> +<title>Related Information</title> +<listitem><para></para> +</listitem> +</itemizedlist> + +</sect1> --> + +<sect1 id="kcontrol-system-administration"> +<sect1info> +<authorgroup> +<author> +&J.Hall; +&J.Hall.mail; +</author> +</authorgroup> +</sect1info> + +<title>System Administration</title> +<para>This module allows you to configure aspects of your system such as +the bootloader, the kernel and helps you perform essential system tasks. Most of these +sections will require the root or Administrator password to effect changes.</para> + +<variablelist> +<varlistentry> +<term><guilabel>Boot Manager (LILO)</guilabel></term> +<listitem><para>If you use the popular bootloader +<acronym>LILO</acronym> this section will allow you to configure it. +You can configure the location to install the bootloader to, set the timeout +on the <acronym>LILO</acronym> boot screen as well as add or modify +kernel images for the boot list.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Date & Time</guilabel></term> +<listitem><para>This configuration module allows you to configure the system date and time +settings. You can set the date, time, and also the current time zone. These settings will be applied system-wide.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Font Installer</guilabel></term> +<listitem><para>Here is where you would configure both personal and system-wide fonts. +This dialog allows you to install new fonts, delete old ones and preview the fonts you +have installed. By default, it displays personal fonts. To modify system-wide fonts click the <guibutton>Administrator Mode</guibutton> button.</para> </listitem> +</varlistentry> +<varlistentry> +<term><guilabel>IBM Thinkpad Laptop</guilabel></term> +<listitem><para>This configuration module allows you to configure the special keys on an IBM thinkpad + laptop. You will need the <quote>nvram</quote> module to use these features.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Linux Kernel</guilabel></term> +<listitem><para>If you run &kde; on &Linux; there is a &kcontrol; module to create or modify +configuration files for a &Linux; kernel. This configurator is compatible with kernels previous to 2.5.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Login Manager</guilabel></term> +<listitem><para>This module allows you to configure the &kde; login manager, &kdm;. &kdm; is +a powerful login manager with a large range of options. It supports user switching, remote graphical logins and has a fully customizable appearance. For more information, see the &kdm; handbook. </para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Paths</guilabel></term> +<listitem><para>This dialog allows you to configure the default locations where certain +important files are kept. The <guilabel>Desktop</guilabel> directory contains all the files on your desktop. The <guilabel>Autostart</guilabel> directory contains files or links to files that you want run when &kde; starts, and the <guilabel>Documents</guilabel> directory is the default location &kde; applications will open or save documents to.</para></listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Sony Vaio Laptop</guilabel></term> +<listitem><para>This configuration module allows you to configure features specific to +Sony Vaio laptops. If you have a Sony Vaio, you will have to install the <quote>sonypi</quote> +driver to use this section.</para></listitem> +</varlistentry> +</variablelist> +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> +</sect1> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> + diff --git a/doc/userguide/creating-graphics.docbook b/doc/userguide/creating-graphics.docbook new file mode 100644 index 000000000..30407b0c4 --- /dev/null +++ b/doc/userguide/creating-graphics.docbook @@ -0,0 +1,48 @@ +<sect1 id="graphics"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Creating Graphics</title> + +<para>How to create graphics with &kde; apps.. (ok, maybe not)</para> + +<!-- Add links to "further reading" here - in this case, for the whole --> +<!-- chapter. --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/credits-and-license.docbook b/doc/userguide/credits-and-license.docbook new file mode 100644 index 000000000..19c9b2641 --- /dev/null +++ b/doc/userguide/credits-and-license.docbook @@ -0,0 +1,315 @@ +<sect1 id="credits"> +<title>Credits</title> +<para> +&kde; is written by and copyright The &kde; Team. +</para> + +<para>This document is copyright 2006 The &kde; Documentation +Team. Individual credits are as follows: +<variablelist> + +<varlistentry> +<term>Tom Albers <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="integrated-messaging" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Waldo Bastian <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote the notes which became <xref linkend="kde-for-administrators"/>.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Gardner Bell <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="networking-with-windows"/>.</para> +</listitem> +<listitem><para>Wrote <xref linkend="konsole-intro" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Gary Cramblitt <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="accessibility" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>David Faure <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="adding-extra-keys" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Nicolas Goutte <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="hand-editing-config-files" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>&Francis.Giannaros; &Francis.Giannaros.mail;</term> +<listitem> + +<itemizedlist> + <listitem><para>Proofreading and update on various parts.</para></listitem> + <listitem><para>Wrote <xref linkend="root" />.</para></listitem> + <listitem><para>Wrote <xref linkend="ktts" />.</para></listitem> + <listitem><para>Wrote <xref linkend="basic-applications" />.</para></listitem> + <listitem><para>Wrote <xref linkend="extragear-applications" />.</para></listitem> + <listitem><para>Re-wrote <xref linkend="kde-edutainment" />.</para></listitem> + <listitem><para>Wrote <xref linkend="migrator-applications" />.</para></listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Adriaan de Groot <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="configuring-toolbars"/>.</para> +</listitem> +<listitem><para>Wrote <xref linkend="kdebugdialog" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>J Hall <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="kcontrol-appearance-and-themes" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="kcontrol-desktop" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="kcontrol-internet-and-network" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="kcontrol-kde-components" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="kcontrol-peripherals" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="kcontrol-power-control" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="kcontrol-regional-and-accessibility" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="troubleshooting-network-x" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>&Anne-Marie.Mahfouf; &Anne-Marie.Mahfouf.mail;</term> +<listitem> + +<itemizedlist> + <listitem><para>Proofreading and update on various parts.</para></listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>&Richard.J.Moore; &Richard.J.Moore.mail;</term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote the <application>kstart</application> and +<application>ksystraycmd</application> sections.</para> + +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Peter Nuttall <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="messaging" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Steven Robson <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Took the screenshots for <xref +linkend="playing-music"/>, <xref linkend="audio-cd"/>, <xref +linkend="file-manager"/> and <xref linkend="accessibility"/>.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry><term>&Philip.Rodrigues; &Philip.Rodrigues.mail;</term> +<listitem> + +<itemizedlist> +<listitem><para>Reviewing and proofreading.</para> +</listitem> +<listitem><para>Wrote <xref linkend="logging-in" +/>.</para> +</listitem> +<listitem><para>Wrote <xref linkend="using-the-clipboard" />.</para> +</listitem> +<listitem><para>Wrote <xref +linkend="configuring-programs" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="menus" />.</para> +</listitem> +<listitem><para>Marked up parts of <xref +linkend="kde-for-administrators"/>.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Deepak Sarda <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="audio-cd"/>.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Robert Stoffers <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="programs-launching" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Juan Carlos Torres <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="customizing-desktop" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry> +<term>Simon Vermeersch <email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="fonts"/>.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry><term>&Lauri.Watts; &Lauri.Watts.mail;</term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote the outline.</para> +</listitem> +<listitem><para>Wrote <xref linkend="getting-help"/>.</para> +</listitem> +<listitem><para>Marked up parts of <xref +linkend="kde-for-administrators"/>.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +<varlistentry><term>Christian Weickhmann +<email>[email protected]</email></term> +<listitem> + +<itemizedlist> +<listitem><para>Wrote <xref linkend="file-manager" />.</para> +</listitem> +<listitem><para>Wrote <xref linkend="switching-sessions" />.</para> +</listitem> +</itemizedlist> + +</listitem> +</varlistentry> + +</variablelist> +</para> + +</sect1> +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/customizing-desktop.docbook b/doc/userguide/customizing-desktop.docbook new file mode 100644 index 000000000..eb427d599 --- /dev/null +++ b/doc/userguide/customizing-desktop.docbook @@ -0,0 +1,365 @@ +<chapter id="customizing-desktop"> +<chapterinfo> +<authorgroup> +<author> +<firstname>Juan Carlos</firstname> +<surname>Torres</surname> +</author> +</authorgroup> +</chapterinfo> + +<title>Customizing the Appearance of your &kde; Desktop</title> + +<para>Changing the appearance of your &kde; desktop can be done quite easily and +flexibly by either individually controlling different parts of the visual +appearance or by using a predefined theme. This guide explains the various +customizable parts of &kde; and how to control their appearance.</para> + +<sect1 id="background"> +<title>Background</title> +<para>The desktop background, more commonly known as the wallpaper, allows you +to display certain images on your desktop. The settings for the background are +found in the &kcontrolcenter;, or by <mousebutton>right</mousebutton>-clicking +on the desktop and selecting <guilabel>Configure Desktop...</guilabel>.</para> + +<para>In &kde;, you have the option to use no picture, a single picture, or a +slideshow of images. If <guilabel>No picture</guilabel> is chosen to be the +desktop background, the <guilabel>Colors</guilabel> options are used instead. +You can also choose whether to use a single +background on all virtual desktops or to apply a different background for each +desktop. This is done by selecting <guilabel>All desktops</guilabel> or the +specific desktop name from the drop-down menu.</para> + +<para>Other background images can be downloaded using the +<guibutton>Get New Wallpapers</guibutton> button on the right or you can visit +the <ulink url="http://www.kde-look.org/index.php?xcontentmode=1x2x3x4x5x6x7"> +Wallpapers section</ulink> of the kde-look.org website.</para> +</sect1> + +<sect1 id="colors"> +<title>Colors</title> +<para>The <guilabel>Colors</guilabel> settings of the &kcontrolcenter; allow you to control the +colors that are used for various window elements, such as window titlebars, +window backgrounds, text, and buttons. You can change the color of each window +element by selecting the element from the drop down list and choosing a color +for it. You can then save your changes by clicking on +<guibutton>Save Scheme...</guibutton>. This will save your settings in a Color +Scheme file. Color schemes are text files, with a <literal +role="extension">.kcsrc</literal> extension, that contain +entries for each window widget and its color, in RGB format. It is also very +easy to add color schemes that you have downloaded by clicking on +<guibutton>Import Scheme...</guibutton> and pointing to the <literal +role="extension">.kcsrc</literal> file. With color schemes, you can save the +changes you have done in one convenient file or easily change to a predefined +color setting, without having to change each window element separately.</para> + +<para>Additional color schemes can be downloaded from <ulink +url="http://www.kde-look.org/index.php?xcontentmode=28">the Color Schemes +section</ulink> of kde-look.org.</para> +</sect1> + +<sect1 id="icons"> +<title>Icons</title> +<para>An icon theme contains the images used to represent actions, files, +devices, and applications. Managing icon themes is easily done through the Icons +module in the &kcontrolcenter;. Simply select the icon theme you want to use and +click on <guibutton>Apply</guibutton> to switch to the new theme. To install new +icon themes, all you need to do is to click on <guibutton>Install New +Theme...</guibutton> and browse to the location of the icon theme archive. There +is no need to extract the contents of the archive into a directory. In fact, the +Icons module only accepts archived icon themes. To remove an icon theme, simply +select the theme from the list and click on <guibutton>Remove Theme</guibutton>. +Note that you cannot remove the icon theme that you are currently using. You +need to switch to some other theme before the current one will become removable. +You also cannot remove icon themes that were installed by the administrator +(<systemitem class="username">root</systemitem>) or by your distribution's +package manager.</para> +<para>Other icon themes can be found in <ulink +url="http://www.kde-look.org/index.php?xcontentmode=27">the Icon Themes +subsection</ulink> of kde-look.org.</para> +</sect1> + +<sect1 id="splash-screen"> +<title>Splash Screen</title> + +<mediaobject> +<imageobject> +<imagedata fileref="splash-screen.png" format="PNG" /> +</imageobject> +<textobject><phrase>The default &kde; splash screen</phrase></textobject> +<caption><para>The default &kde; splash screen</para></caption> +</mediaobject> + +<para>The splash screen is the animated image or screen that is displayed while +&kde; loads after you log in. Each user can have a different splash screen. +Changing the splash screen for the current user can be done in the Splash +Screen module of the &kcontrolcenter;. Select the splash screen you want to +use and click on <guibutton>Apply</guibutton>. You can also test what a splash +screen will look like by selecting the splash screen and clicking on +<guibutton>Test</guibutton>. Installing a new splash theme is very easy. Just +click on <guibutton>Add...</guibutton> and browse to the splash screen archive you +want to add. There is no need to extract the contents of the archive. Removing +splash screens is also easily done by selecting the splash screen and clicking +on <guibutton>Remove</guibutton>. Note that you cannot remove splash screens +installed by the administrator (<systemitem class="username">root</systemitem>) +or by your distribution's package manager.</para> + +<para>Splash screen themes can be found on kde-look.org, in <ulink +url="http://www.kde-look.org/index.php?xcontentmode=35">the Splash Screens +section</ulink>. Take note that some splash screens require a specific &ksplash; +engine to be installed.</para> +</sect1> + +<sect1 id="win-deco"> +<title>Window Decorations</title> +<para>You can change the appearance of window borders, titlebars and buttons in +&kde; using window decorations. Some window decorations even have the capability +to apply effects such as translucency. Window decorations must be able to do all +these without sacrificing speed and performance. This is the reason why window +decorations come in source code that must be compiled, or as binary packages +that must be installed. Basically, Window decorations are plugins or small +programs that instruct &kwin;, &kde;'s Window Manager, +how to display window frames.</para> + +<para>In order to add a new window decoration, you need to compile it from +source code. If a binary package for your distribution or system is provided, +you simply need to install it using your distribution's package manager. Please +refer to your distribution's manual for instructions on how to do this. Once the +window decoration has been installed, it can be accessed in the Window +Decorations settings in the &kcontrolcenter;. In the +<guilabel>Window Decoration</guilabel> tab, +a list of installed window decorations can be seen in the drop down box. Simply +select the decoration you want to use and click on <guibutton>Apply</guibutton>. +Different window decorations have different capabilities and settings. Play +around with the different options available. The <guilabel>Buttons</guilabel> tab allows you to +control the buttons on the window titlebar. Enable the <guilabel>Use custom +titlebar button positions</guilabel> check box in order to rearrange, remove, or +add buttons. To add buttons to the titlebar, drag an item from the list to the +titlebar preview above it. To remove a button, drag the button from the titlebar +preview to the item list. Simply drag buttons in the titlebar preview to +rearrange them.</para> + +<para>While all window decorations need to be compiled from source code, some +window decorations can load pixmap-based theme files that do not need to be +compiled. &kde; ships with a pixmap-based window decoration called the IceWM +window decoration. Another pixmap-based window decoration is <ulink +url="http://www.kde-look.org/content/show.php?content=31447">deKorator</ulink>, +which can be found on kde-look.org. Please refer to your distribution's +documentation on how to install these. The advantage of using pixmap-based +window decorations is it is relatively easy to make themes for them, by using +images and editing a configuration file. The tradeoff is a slight loss of performance, +while this may be unnoticeable on very fast systems.</para> + +<para>To add an IceWM theme, select IceWM as the window decoration and click on +the <guilabel>Open &kde;'s IceWM theme folder</guilabel> link in the window +decoration description area. This will open a &konqueror; window +to <filename>$<envar>KDEHOME</envar>/share/apps/kwin/icewm-themes</filename>. +Extract your IceWM theme to this folder. The theme will then be added to +the list of IceWM themes. Select the theme you want to use and click on +<guibutton>Apply</guibutton>.</para> + +<para>To add a deKorator theme after you've installed deKorator, select +deKorator from the window decorations list and go to the <guilabel>Themes</guilabel> +tab. Click on <guibutton>Install New Theme</guibutton> and locate +your deKorator theme archive. Make sure that the version of the deKorator theme +matches the deKorator version installed on your system. Once the theme has been +added, select the theme you want to use and click on <guibutton>Set Theme +Paths</guibutton>. Click on <guibutton>Apply</guibutton> for the changes to +take effect.</para> + +<para>Some more window decorations are available at kde-look.org under <ulink +url="http://www.kde-look.org/index.php?xcontentmode=17">the +Native &kde; 3.x</ulink> and <ulink +url="http://www.kde-look.org/index.php?xcontentmode=20">the +Native &kde; 3.2+</ulink> subsections. Themes for the <ulink +url="http://www.kde-look.org/index.php?xcontentmode=18">IceWM</ulink> and +<ulink +url="http://www.kde-look.org/index.php?xcontentmode=21">deKorator</ulink> window +decorations have their own subsections under the Window Decorations +category.</para> +</sect1> + +<sect1 id="style"> +<title>Style</title> +<para>Widgets are the basic elements of a graphical user interface, such as +buttons, scrollbars, tabs, and menus. A widget style is a plugin or a small +program that instructs &kde; how widgets are displayed. Since widgets are the +very basic parts of an interface, they are frequently accessed and must be able +to respond very quickly. This is why widget styles must come as source code to +be compiled or as binary packages to be installed, just like window decorations. +Please refer to your distribution's documentation on how to compile from source +or install binary packages.</para> + +<para>Once a widget style has been installed, it will be added to the list of +available styles in the <guilabel>Style</guilabel> module in the &kcontrolcenter;. +The <guilabel>Style</guilabel> tab allows +you to select a widget style from the list and to configure it if the style has +a <guibutton>Configure...</guibutton> feature. Different styles have different options. A preview of the +selected style is available at the lower portion of the tab. The +<guilabel>Effects</guilabel> tab +controls different visual effects for some widgets like comboboxes and tooltips. +The <guilabel>Toolbar</guilabel> tab gives some options on the general appearance of toolbars.</para> + +<para>Additional widget styles can be found in <ulink +url="http://www.kde-look.org/index.php?xcontentmode= +8x9x10x11x12x13x14x15x16">the different &kde; subsections of the +Themes/Styles</ulink> of kde-look.org. Take note that styles come in source +code or binary package forms. They are not &kde; theme files.</para> +</sect1> + +<sect1 id="kde-theme"> +<title>&kde; Theme</title> +<para>&kde; allows you to save the different changes you made to your desktop's +appearance in one file, using the Theme Manager in &kcontrolcenter;. Once you +have set up your desktop the way you want, click on <guibutton>Create New +Theme...</guibutton>. Enter the details you want to give your theme, such as theme +name, author, version, &etc;, then click <guibutton>OK</guibutton> when done. +This will add your theme to the list of available themes and save your settings +in a &kde; theme. A &kde; theme (<literal role="extension">.kth</literal> file) +instructs &kde; on what window decoration, style, or color scheme to use for +that particular theme. To add a &kde; theme from an outside source, click on +<guibutton>Install New Theme...</guibutton> and locate the &kde; theme file. +Removing a theme is easily done by clicking on <guibutton>Remove +Theme</guibutton>. If you made changes to your theme, you have to either create +a new theme name for it, or remove the previous version first to be able to use +the same theme name.</para> + +<para>The following are the settings that are saved and indicated in a &kde; +Theme:</para> + +<itemizedlist> +<listitem><para> +Background</para> +</listitem> +<listitem> +<para> +Screen Saver</para> +</listitem> +<listitem> +<para> +Icon Theme</para> +</listitem> +<listitem> +<para> +System Notifications</para> +</listitem> +<listitem> +<para> +Color Scheme</para> +</listitem> +<listitem> +<para> +Cursor Theme</para> +</listitem> +<listitem> +<para> +Window Decoration</para> +</listitem> +<listitem> +<para> +&konqueror; background (File Management)</para> +</listitem> +<listitem> +<para> +Panel background</para> +</listitem> +<listitem> +<para> +Style</para> +</listitem> +<listitem> +<para> +Fonts</para> +</listitem> +</itemizedlist> + +<para>One very important thing to consider when using or installing a &kde; +Theme is that it only indicates what settings to use for the above. A &kde; +Theme includes only system notifications, desktop background, panel background, +&konqueror; background, and the color scheme in its package. The other +components must be installed separately if they do not already come with +&kde;.</para> + +<para>&kde; Themes can be downloaded from the <ulink +url="http://www.kde-look.org/index.php?xcontentmode=8">Theme-Manager +subsection</ulink> of +kde-look.org, under the Themes/Styles section.</para> +</sect1> + +<sect1 id="desktop-glossary"> +<title>Glossary</title> + +<glosslist> +<glossentry id="gloss-background"> +<glossterm>Background</glossterm> +<glossdef><para>Background/wallpaper image or color for the +desktop</para></glossdef> +</glossentry> + +<glossentry id="gloss-color-scheme"> +<glossterm>Color Scheme</glossterm> +<glossdef><para>(<literal role="extension">.kcsrc</literal>) +Configuration file that indicates what colors to use +for certain widgets</para></glossdef> +</glossentry> + +<glossentry id="gloss-icons"> +<glossterm>Icons</glossterm> +<glossdef><para>Images representing applications, files, +devices, &etc;</para></glossdef> +</glossentry> + +<glossentry id="gloss-splash-screen"> +<glossterm>Splash Screen</glossterm> +<glossdef><para>Animated image or screen that displays while &kde; +loads after logging in</para></glossdef> +</glossentry> + +<glossentry id="gloss-win-deco"> +<glossterm>Window Decoration</glossterm> +<glossdef><para>Plugins or small programs that instruct the window +manager how to display window frames</para></glossdef> +</glossentry> + +<glossentry id="gloss-style"> +<glossterm>Style</glossterm> +<glossdef><para>Plugin or a small program that instructs &kde; +how widgets are displayed</para></glossdef> +</glossentry> + +<glossentry id="gloss-kde-theme"> +<glossterm>&kde; Theme</glossterm> +<glossdef><para>(<literal role="extension">.kth</literal>) +A file that contains instructions on what settings to use for +different GUI components</para></glossdef> +</glossentry> + +<glossentry id="gloss-widgets"> +<glossterm>Widgets</glossterm> +<glossdef><para>Basic elements that build up a graphical user +interface: buttons, scrollbars, menus, tabs, &etc;</para></glossdef> +</glossentry> + +</glosslist> +</sect1> + + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/desktop.png b/doc/userguide/desktop.png Binary files differnew file mode 100644 index 000000000..c5e683f61 --- /dev/null +++ b/doc/userguide/desktop.png diff --git a/doc/userguide/email.docbook b/doc/userguide/email.docbook new file mode 100644 index 000000000..04e95c9b2 --- /dev/null +++ b/doc/userguide/email.docbook @@ -0,0 +1,254 @@ +<chapter id="email"> + +<chapterinfo> +<authorgroup> +<author> +&Daniel.Naber; +</author> +<author> +&David.Rugge; +</author> +</authorgroup> +</chapterinfo> + +<!-- Stolen and modified by Phil from the KMail manual --> +<!-- TODO: Screenies! --> +<title>Getting Started with Email</title> + +<indexterm><primary>Email</primary><secondary>getting +started</secondary></indexterm> + +<indexterm><primary>&kmail;</primary></indexterm> + +<para>&kde; features a powerful and easy-to-use email client called +&kmail;, which allows you to send, receive, and organize your email +quickly and efficiently. Let us look at how to set it up. If you have +any problems with this procedure, refer to the full &kmail; manual.</para> + +<sect1 id="email-information-needed"> +<title>Information you will need before you start</title> + +<para>Many email settings can vary greatly depending on the setup of +your system, your ISP's configuration, or your local network +setup. You will need to find out some information before you can start +setting up your email: +<variablelist> + +<varlistentry> +<term>Your email address</term> +<listitem><para>This should be provided by your ISP or system administrator.</para></listitem> +</varlistentry> + +<varlistentry> +<term>Your username and password for your email account</term> +<listitem><para>The username is often the same as the part before the +<quote>@</quote> symbol in your email address, but not always: check +with your <acronym>ISP</acronym>.</para></listitem> +</varlistentry> + +<varlistentry> + + +<term> +<indexterm><primary>Email</primary><secondary>SMTP +server</secondary></indexterm> +Your outgoing email (<acronym>SMTP</acronym>) server name and +details</term> +<listitem><para>Again, your ISP should have provided +you with this information. If not, you can try the form <systemitem +class="systemname">smtp.<replaceable>your-isp-name</replaceable>.com</systemitem>.</para></listitem> +</varlistentry> + +<varlistentry> + +<term> +<indexterm><primary>Email</primary><secondary>IMAP +server</secondary></indexterm> + +<indexterm><primary>Email</primary><secondary>POP3 +server</secondary></indexterm> + +Your incoming email (<acronym>IMAP</acronym> or +<acronym>POP</acronym>) server name and details</term> +<listitem><para>If you do not have this information to hand, you can +try <systemitem +class="systemname">imap.<replaceable>your-isp-name</replaceable>.com</systemitem> +for <acronym>IMAP</acronym> or <systemitem +class="systemname">pop.<replaceable>your-isp-name</replaceable>.com</systemitem> +if you use <acronym>POP3</acronym>.</para></listitem> +</varlistentry> +</variablelist> +</para> + +<para>Once you have that information, you are ready to start setting +up &kmail;. Open &kmail; from the <guimenu>K</guimenu> menu (you can +find it in the <guisubmenu>Internet</guisubmenu> submenu, or use one +of the methods described in <xref linkend="programs-launching"/>.) Once +&kmail; has opened, select the menu entry +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KMail...</guimenuitem> +</menuchoice>. The next sections describe how to use the dialog that +appears to set up &kmail;.</para> +</sect1> + + +<sect1 id="email-setting-your-identity"> +<title>Setting your Identity</title> + +<para> +The settings in the <guilabel>Identities</guilabel> page are fairly +straightforward. Select the <guilabel>default</guilabel> identity and +click <guibutton>Modify...</guibutton>. Fill in the <guilabel>Your +name</guilabel> field with your full name (⪚ <userinput>John +Doe</userinput>) and, optionally, the +<guilabel>Organization</guilabel> field with the appropriate +information. +</para> +<para> +Next, fill in the <guilabel>Email address</guilabel> field with +your email address (⪚ <userinput>[email protected]</userinput>). +</para> + +<para>That is all for this dialog unless you want to use the more +advanced features (cryptography, a signature, &etc;). You can find +more information about these features in the full &kmail; +manual. Click on the <guibutton>OK</guibutton> button to close this +dialog, and move on to the next configuration page...</para> + +</sect1> + +<sect1 id="email-setting-up-your-account"> +<title>Setting up your Account</title> + +<para>Click on the <guilabel>Network</guilabel> icon to move to the +network configuration page. It contains the settings that +tell &kmail; how to send and receive your email messages. You will see +two tabs on the right-hand side: <guilabel>Sending</guilabel> and +<guilabel>Receiving</guilabel>. You need to set up both, so let us look +at them each in turn:</para> + +<sect2 id="sending-mail"> +<title>Sending Messages</title> + +<indexterm><primary>Email</primary><secondary>sending</secondary></indexterm> + +<para>The <guilabel>Sending</guilabel> tab provides a list of +ways to send messages. The first item in the list is the default +way to send messages. Using the <guibutton>Add...</guibutton> +button you can choose between two different ways of sending messages: +<guilabel>SMTP</guilabel> and +<guilabel>Sendmail</guilabel>. &Sendmail; here +means a local software installation — this has a +reputation of being difficult to set up, so if you do not already have a +working &Sendmail; configuration, choose +<guilabel>SMTP</guilabel> and fill in the <guilabel>Name</guilabel> +field with a descriptive name +(⪚ <userinput>My Mail Account</userinput>) +and the <guilabel>Host</guilabel> +field with the name and domain of your mail server +(⪚ <userinput>smtp.provider.com</userinput>). You will probably +not need to change the <guilabel>Port</guilabel> setting (the default is +<userinput>25</userinput>).</para> + +<para>A description of the other options can be found +in the full &kmail; manual. Click on <guibutton>OK</guibutton> to +close this dialog, and then click on the +<guilabel>Receiving</guilabel> tab.</para> + +</sect2> + +<sect2 id="receiving-mail"> +<title>Receiving Messages</title> + +<para>To set up an account so you can receive mail, press the +<guibutton>Add...</guibutton> button in the +<guilabel>Receiving</guilabel> tab. You will then be prompted for the +type of your email account; most users should select +<guilabel>POP3</guilabel> or <guilabel>IMAP</guilabel>. If you wish to +use a different system, consult the &kmail; manual.</para> + +<para>You will then be presented with +the <guilabel>Add account</guilabel> window. First, fill in the +<guilabel>Name</guilabel> field to name your account. You can choose any name +you like. <guilabel>Login</guilabel>, <guilabel>Password</guilabel>, and +<guilabel>Host</guilabel> should be filled in with the information you +gathered earlier. You should not usually need to change the <guilabel>Port</guilabel> setting.</para> + +<para>You are now ready to send and receive mail. For +<acronym>IMAP</acronym>, just open your folders in the +folder tree in &kmail;'s main window. &kmail; then connects to your +server and displays the messages it finds. For POP3 use +<menuchoice><guimenu>File</guimenu><guimenuitem>Check +Mail</guimenuitem></menuchoice>.</para> + +</sect2> + +</sect1> + +<sect1 id="email-testing-your-setup"> +<title>Testing your Setup</title> + +<indexterm><primary>Email</primary><secondary>testing</secondary></indexterm> + +<para>First, you should send yourself a message to test your +configuration. To send a message, either hit <keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo>, select the +<guiicon>New Message</guiicon> icon or select +the <menuchoice><guimenu>Message</guimenu><guimenuitem>New +Message...</guimenuitem></menuchoice> menu item. The +composer window will appear. Fill in the +<guilabel>To:</guilabel> field with your email address and type +something in the <guilabel>Subject</guilabel> field. Send the message by +selecting <menuchoice><guimenu>Message</guimenu> <guimenuitem>Send</guimenuitem> +</menuchoice>.</para> + +<para>To check your email, select +<menuchoice><guimenu>File</guimenu><guimenuitem>Check +Mail</guimenuitem></menuchoice>. In the lower-right corner of the main +window, a progress bar will indicate how many messages are being +downloaded. If you receive the message you just sent, then +congratulations! If, however, you receive any error messages while +testing your setup, make sure that your network connection is working +and recheck your settings at +<menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure +&kmail;...</guimenuitem></menuchoice>.</para> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> + +<listitem><para>The &kmail; Handbook has full descriptions of advanced +email settings and so on. You can read it in the &khelpcenter; or by +entering <userinput>help:/kmail</userinput> in &konqueror;'s +<guilabel>Location</guilabel> bar.</para> +</listitem> + +<listitem><para>The &kmail; website at <ulink +url="http://kmail.kde.org">http://kmail.kde.org</ulink> contains +latest news, tips and tricks, and plenty more.</para> +</listitem> + +</itemizedlist> + + + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/extragear-applications.docbook b/doc/userguide/extragear-applications.docbook new file mode 100644 index 000000000..fd55985aa --- /dev/null +++ b/doc/userguide/extragear-applications.docbook @@ -0,0 +1,199 @@ +<chapter id="extragear-applications"> + +<chapterinfo> +<authorgroup> +<author> +&Francis.Giannaros; +&Francis.Giannaros.mail; +</author> +</authorgroup> +</chapterinfo> + +<title>&kde; Extragear Applications</title> + +<para>These are applications that are directly associated with &kde;, the project, but do not appear and are not shipped with the main &kde; distribution. This can be down to a number of reasons, but a common case is either down to a duplication of functionality, or because they're simply too specialised. Perhaps the most popular occurence however is that the developers themselves may not want it to appear in the main &kde; distribution; choosing, rather, to handle their own release schedules. Nevertheless, the applications in Extragear are distinguished by &kde;, and many are increasingly popular. </para> + +<sect1 id="extragear-components"> +<title>Available in the &kde; Extragear</title> + +<!-- Begin Multimedia --> +<sect2 id="extragear-multimedia"> +<title>Multimedia</title> + +<variablelist> +<varlistentry> +<term>&amarok;</term> + <listitem><para>An advanced and comprehensive music player with the capability to play <acronym>MP3</acronym>, <acronym>WAV</acronym>, and <acronym>OGG</acronym> audio filetypes and others. There is not room here to mention all of &amarok;'s features, but by default, &amarok; can automatically fetch cover art, embed song lyrics, and display aesthetically pleasing visualizations. &amarok; remains, as much of &kde; does, highly customizable; it contains a powerful scripting interface, and the context browser can be stylised easily using &CSS;. &amarok; also supports several backends, including <application>GStreamer</application>, <application>xine</application>, <acronym>NMM</acronym>, <acronym>MAS</acronym>, <application>aKode</application> and &arts;.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://amarok.kde.org">http://amarok.kde.org</ulink></para></listitem> + <listitem><para>View the handbook by typing <userinput>help:/amarok</userinput> in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;; if you do not already have &amarok; installed (and hence do not have the handbook), then you can view it online <ulink url="http://amarok.kde.org/component/option,com_staticxt/staticfile,index.html/Itemid,49/">here</ulink>.</para></listitem> + </itemizedlist> + + </listitem> + +<!-- Insert Screeny --> + +</varlistentry> + +<varlistentry> +<term><application>K3b</application></term> + <listitem><para>The definitive &CD;/<acronym>DVD</acronym> burning application for &kde;. With <application>K3b</application> you can create data, video, and audio (it comes with plugins for <acronym>WAV</acronym>, <acronym>MP3</acronym>, <acronym>FLAC</acronym>, and <application>Ogg Vorbis</application>) &CD;s. Projects can be saved and loaded, &CD;-ripping is supported, and you can appropriately make &CD;/<acronym>DVD</acronym> copies. </para> + + <itemizedlist> + <listitem><para>Extragear Summary: <ulink url="http://extragear.kde.org/apps/k3b/">http://extragear.kde.org/apps/k3b/</ulink></para></listitem> + <listitem><para>Website: <ulink url="http://k3b.org">http://k3b.org</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-multimedia/k3b/index.html"><application>K3b</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> +</variablelist> +<!-- End Multimedia --> +</sect2> + +<!-- Begin Graphics --> +<sect2 id="extragear-graphics"> +<title>Graphics</title> +<variablelist> +<varlistentry> +<term>&digikam;</term> + <listitem><para>A photo management application which can conveniently organize and import digital photos. Features include complete tagging functionality, a plugin system, and a fully-featured comment system. &digikam; also makes use of <acronym>KIPI</acronym> (&kde; Image Plugin Interface), therefore contributing to the initiative to create a common plugin infrastructure, which allows development of image plugins that can be shared among graphical applications in &kde; (others include <application>Gwenview</application>, <application>ShowImg</application> and <application>KimDaBa</application>).</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://digikam.org">http://digikam.org</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-graphics/digikam/index.html">&digikam; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term><application>Gwenview</application></term> + <listitem><para>Another advanced image viewer which can load and save all image formats supported by &kde;, as well as being able to display the <application>GIMP</application> (*.<acronym>xcf</acronym>) image filetype. <application>Gwenview</application> can perform a few graphical manipulations (rotate, mirroring) and has full support for KIO slaves (allowing you to use it via &FTP;). Other features also include file management operations, such as copy, paste, move and delete.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://gwenview.sourceforge.net/">http://gwenview.sourceforge.net/</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-graphics/gwenview/index.html"><application>Gwenview</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + + +<varlistentry> +<term><application>ShowImg</application></term> + <listitem><para>A feature-rich image viewer, written for &kde;, which can display numerous formats, including <acronym>JPEG</acronym>, <acronym>PNG</acronym>, [animated] <acronym>GIF</acronym> and <acronym>MNG</acronym>. It consists of a tree-view frame, a directory/preview frame, and a view frame. The (larger) view frame can be exchanged with the (smaller) directory/preview frame. It can preview and display images from multiple directories and search for identical images. <application>ShowImg</application> also features a full-screen mode, zooming, sorting, drag and drop with &konqueror;, and support for images in compressed archives.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.jalix.org/projects/showimg/">http://www.jalix.org/projects/showimg/</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-graphics/showimg/index.html"><application>ShowImg</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term><application>KimDaBa</application></term> + <listitem><para><application>KimDaBa</application> (&kde; Image Database) attempts to provide an efficient solution for the organization of hundreds (or even thousands) of images. Having been highly optimized for annotating images, <application>KimDaBa</application> can help you locate an image in a matter of seconds.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://ktown.kde.org/kimdaba/">http://ktown.kde.org/kimdaba/</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-graphics/kimdaba/index.html"><application>KimDaBa</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> +</variablelist> +</sect2> +<!-- End Graphics --> + +<!-- Begin Network --> + +<sect2 id="extragear-network"> +<title>Network</title> +<variablelist> +<varlistentry> +<term>&konversation;</term> + <listitem><para>A fully-featured <acronym>IRC</acronym> client which supports per channel encoding, downloading and resuming file transfers, nick completion and highlighting, as well as tight integration with &kontact; and the rest of &kde;.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://konversation.kde.org">http://konversation.kde.org</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-network/konversation/index.html">&konversation; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term><application>KMldonkey</application></term> + <listitem><para>A &kde; frontend for <application>MLDonkey</application>, a powerful <acronym>P2P</acronym> file-sharing tool. Highly configurable, real-time graphical bandwidth and network statistics, and much more.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kmldonkey.org/">http://kmldonkey.org/</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-network/kmldonkey/index.html"><application>KMldonkey</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term><application>KNemo</application></term> + <listitem><para>Displays for every network interface an icon in the systray. Tooltips and an info dialog provide further information about the interface. Passive popups inform about interface changes and a traffic plotter is also integrated.</para> + + <itemizedlist> + <listitem><para><ulink url="http://kde-apps.org">&kde;-apps</ulink> entry: <ulink url="http://kmldonkey.org/">http://www.kde-apps.org/content/show.php?content=12956</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> +</variablelist> +</sect2> +<!-- End Network --> + +<!-- Beging Utilities --> + +<sect2 id="extragear-utilities"> +<title>Utilities</title> +<variablelist> +<varlistentry> +<term><application>Filelight</application></term> + <listitem><para>A simple, yet ideal, application for graphically displaying where your diskpace is being used. <application>Filelight</application> displays this information by representing your filesystem as a set of concentric segmented-rings.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.methylblue.com/filelight/">http://www.methylblue.com/filelight/</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-utils/filelight/index.html"><application>Filelight</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +<!-- Insert Screeny here --> +</varlistentry> + +<varlistentry> +<term><application>Krecipes</application></term> + <listitem><para>A &kde; recipe tool that can manage a recipe database with an easy-to-use interface. Full support for creating and removing ingredients as well as units; helps with diets, can calculate the amount of calories, vitamins, carbohydrates etc. Other advantages are its flexilibity and potential to extend further.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://krecipes.sourceforge.net">http://http://krecipes.sourceforge.net</ulink></para></listitem> + <listitem><para><ulink url="http://docs.kde.org/development/en/extragear-utils/krecipes/index.html"><application>Krecipes</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> +</variablelist> +</sect2> +<!-- End Utilities --> + +</sect1> + +<sect1 id="extragear-related-information"> +<title>Related Information</title> +<itemizedlist> +<title>Related Information and Links</title> + <listitem><para>It should be stressed that the above is but a preview of what is available in the &kde; extragear. To view all of the applications and utilities available there visit <ulink url="http://extragear.kde.org">http://extragear.kde.org</ulink>, where a briefer summary of each application is provided.</para></listitem> + <listitem><para>The handbooks for the majority of applications in extragear can be viewed from <ulink url="http://docs.kde.org">http://docs.kde.org</ulink>.</para></listitem> + <listitem><para>Once again, you can find a plethora of other [third-party] &kde; applications at the popular <ulink url="http://kde-apps.org">http://kde-apps.org</ulink>.</para></listitem> +</itemizedlist> +</sect1> + +</chapter>
\ No newline at end of file diff --git a/doc/userguide/file-sharing.docbook b/doc/userguide/file-sharing.docbook new file mode 100644 index 000000000..395e7b9e2 --- /dev/null +++ b/doc/userguide/file-sharing.docbook @@ -0,0 +1,109 @@ +<sect1 id="file-sharing"> + +<sect1info> +<authorgroup> +<author> +&Lauri.Watts; +</author> +</authorgroup> +</sect1info> + + +<title>File Sharing</title> +<sect2 id="file-sharing-kpf"> +<title>How to share files with &kpf;</title> + +<indexterm><primary>File sharing</primary></indexterm> +<indexterm><primary>Shared Folders</primary></indexterm> + +<para>&kpf; provides simple file sharing using &HTTP; (the Hyper Text +Transfer Protocol,) which is the same protocol used by web sites to provide +data to your web browser. &kpf; is strictly a public fileserver, which means +that there are no access restrictions to shared files: whatever you select +for sharing is available to anyone.</para> + +<para>&kpf; is designed to be used for sharing files with friends, not to +act like a fully-fledged web server such as +<application>Apache</application>. &kpf; was primarily conceived as an easy +way to share files with others while chatting on <acronym>IRC</acronym> +(Internet Relay Chat, or <quote>chat rooms</quote>.)</para> + +<para>&kpf; runs as an applet inside &kicker;. This means that it takes up +little space on your screen and its status is always visible. To start the +&kpf; applet, <mousebutton>right</mousebutton> click on &kicker; and choose +<guimenu>Add Applet to Panel...</guimenu> to open the <guilabel>Add +Applet</guilabel> dialog. Select <guilabel>Public File Server</guilabel> and +click the <guibutton>Add to Panel</guibutton> button.</para> + +<para>&kpf; employs the concept of shared folders. You may choose one or +more folders to make public, and all files in that folder (and any +subfolders) will be shared.</para> + +<note><para>Please be extremely careful about which folders you share. Remember +that all files in the folder and its subfolders, including +<quote>hidden</quote> files (<quote>dotfiles</quote> to the techies) will be +made available to the world, so be careful not to share sensitive +information, such as passwords, cryptographic keys, your addressbook, +documents private to your organization, &etc;.</para></note> + +<para>Once &kpf; is running, you will see a square applet with a thin sunken +bevel and an icon depicting an <guiicon>hot air balloon</guiicon>. The +balloon is visible when no folders are being shared.</para> + +<para>To share a folder, <mousebutton>right</mousebutton> click on the +balloon icon and a pop-up menu will appear, containing only one item, +<guimenuitem>New Server...</guimenuitem>. Selecting this entry will cause a +<quote>wizard</quote> to appear, which will ask you a few simple +questions. Completing the questions will set up a folder for sharing.</para> + +<para>There is an alternative to using the applet directly when you want to +share a folder. &kpf; is integrated with &konqueror;.</para> + +<para>With &konqueror; open and displaying a folder, +<mousebutton>right</mousebutton> click on the background and bring up the +<quote>Properties</quote> dialog. On install, &kpf; added a +<guilabel>Sharing</guilabel> tab to this dialog. You will be offered the +option of starting &kpf; if it is not running. Choosing +<guibutton>Ok</guibutton> will send a signal to the &kpf; applet, asking it +to add a new share.</para> + +<para>For more detailed information, such as how to share different +directories to different people, see the <ulink +url="help:/kpf">&kpf;</ulink> handbook.</para> + +</sect2> + +<!-- <sect2 id="file-sharing-other-strategies"> +<title>Other strategies</title> + +Samba, local cgi? nfs devices +--> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> + + +</sect2>--> +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/font-installation.docbook b/doc/userguide/font-installation.docbook new file mode 100644 index 000000000..bca1a2308 --- /dev/null +++ b/doc/userguide/font-installation.docbook @@ -0,0 +1,79 @@ +<sect1 id="fonts"> + +<sect1info> +<authorgroup> +<author> +<personname> +<firstname>Simon</firstname> +<surname>Vermeersch</surname> +</personname> +<email>[email protected]</email> +</author> +</authorgroup> +</sect1info> + +<title>Fonts - Installing and Configuring</title> + +<indexterm><primary>Fonts</primary></indexterm> + +<para>Fonts are really easy to configure in &kde;. Open up the Control +Center (with <menuchoice><guimenu>K-Menu</guimenu><guimenuitem>Control +Center</guimenuitem></menuchoice>) and choose +<guilabel>Font Installer</guilabel> in <guilabel>System +Administration</guilabel>in the tree view.</para> + +<para>There are two kinds of fonts: Personal and Global fonts. +Personal fonts are only accessible to your user, whereas global fonts are +accessible to everyone. When you open the <application>Font +Installer</application>, you're in Personal mode (you can see this in +the <guilabel>Location</guilabel> bar). When you click on the <guibutton>Administrator Mode</guibutton> +button, and put the <systemitem class="username">root</systemitem> password, +you can access global mode, where you can change the fonts for every user on +this computer.</para> + +<para>For the rest, there is no difference between those two kind of fonts.</para> + +<indexterm><primary>Fonts</primary><secondary>previewing</secondary></indexterm> + +<para>There is a list of fonts in the center. Click on a font to see a preview. +In the toolbar on the top you have buttons to access the top directory, +refresh and change the view.</para> + +<para>If you want to, you can organise your fonts in multiple directories, so that +you can easily find them later.</para> + +<indexterm><primary>Fonts</primary><secondary>installing</secondary></indexterm> + +<para>To install a font, click on the <guibutton>Add +Fonts...</guibutton> button. A file open dialog will appear where you can +choose your font.</para> + +<para>Alternatively, you can drag fonts from &konqueror; to the +list. To remove a font, <mousebutton>right</mousebutton> click on it and +choose <guibutton>Delete</guibutton>.</para> + + + +<para>Configuration (anti-aliasing)</para> + +<para>kfontinst and kfontview should probably get a mention too, since +they don't seem to have any existing docs.</para> +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/getting-help.docbook b/doc/userguide/getting-help.docbook new file mode 100644 index 000000000..c3a872c7c --- /dev/null +++ b/doc/userguide/getting-help.docbook @@ -0,0 +1,213 @@ +<sect1 id="getting-help"> + +<sect1info> +<authorgroup> +<author>&Lauri.Watts; +</author> +</authorgroup> +</sect1info> + + +<title>Getting Help</title> + +<sect2 id="user-manuals"> +<title>User Manuals</title> + +<indexterm><primary>User Manual</primary></indexterm> +<para>Most applications come with a comprehensive user manual<indexterm><primary>User Manual</primary><secondary>Handbook</secondary></indexterm>, which you can +reach various ways:</para> + +<itemizedlist> +<listitem> +<para>By pressing <keycap>F1</keycap> inside the application.</para> +</listitem> +<listitem> +<para>From the menu bar: +<menuchoice><guimenu>Help</guimenu><guimenuitem><replaceable>Application name +</replaceable></guimenuitem></menuchoice></para> +</listitem> +<listitem> +<para>By browsing to it in &khelpcenter;<indexterm><primary>&khelpcenter;</primary></indexterm></para> +</listitem> +<listitem> +<para>By using the help KIOslave in &konqueror;. So, in the Location Toolbar, simply type <userinput>help:/<replaceable>Application name</replaceable></userinput> +</para> +</listitem> +<listitem> +<para>Online at <ulink +url="http://docs.kde.org">http://docs.kde.org</ulink></para> +</listitem> +</itemizedlist> + +</sect2> + +<sect2 id="context-help"> +<title>Context and <quote>What's This</quote> Help</title> + +<para>Many applications also provide context help in two forms: +Tooltips, and <quote>What's This</quote> help.</para> + +<sect3 id="tooltips"> +<title>Tooltips</title> + +<indexterm><primary>Tooltips</primary></indexterm> +<para>Tooltips are small informational windows or balloons that display when +you hover the mouse over an item on your screen without clicking.</para> + +<para>&kde; uses tooltips in many places to provide brief help or +information about an item on your screen. For instance, most toolbar buttons +inside applications will display their name in a tooltip if you rest or hover +your mouse over them.</para> + +<para>Tooltips have another function, which is not specifically tied to +help. In the &konqueror; file manager and on your Desktop, tooltips can +provide information about files. This is commonly referred to as <quote>meta information</quote>.</para> + +<para>You can find out more about meta-information tooltips in the section +about <link linkend="file-manager">the &konqueror; file manager</link>.</para> + +</sect3> + +<sect3 id="whats-this-help"> +<title><quote>What's This?</quote></title> + +<indexterm><primary>What's This?</primary></indexterm> + +<para><quote>What's This?</quote> help is usually more detailed than tooltips. +You can access <quote>What's This?</quote> help in two ways:</para> + +<itemizedlist> +<listitem> +<para>By pressing the <guibutton>?</guibutton> button in the titlebar of the +window.</para> +</listitem> +<listitem> +<para>By pressing the key combination +<keycombo>&Shift;<keycap>F1</keycap></keycombo></para> +</listitem> +</itemizedlist> + +<para>The cursor will change to a pointer with a question mark next to it. +Click on the item you want to know about, and a small window will +pop up displaying information.</para> + +</sect3> +</sect2> + +<sect2 id="mailing-lists-newsgroups-and-irc"> +<title>Mailing Lists, Newsgroups and <acronym>IRC</acronym></title> + +<sect3 id="mailing-lists"> +<title>Mailing Lists</title> + +<indexterm><primary>Mailing Lists</primary></indexterm> +<para>&kde; provides many mailing lists which can provide you with help +and guidance in using and configuring your Desktop.</para> + +<para>Some of the lists you might find useful are:</para> + +<variablelist> +<varlistentry> +<term>The &kde; User List +<indexterm><primary>&kde; User Mailing List</primary></indexterm></term> +<listitem> +<para>This mailing list focuses specifically on <acronym>OS</acronym>-independent questions +and discussions regarding using &kde;. Operating-system-specific questions and +discussion are off-topic here. For +example, the question <quote>How do I change the margin size for KWord +documents</quote> is appropriate for this list; whereas <quote>How do I set +up my printer using &kde; under UnixOS X.Y</quote> is not. Questions asked and +discussions here should apply to all &kde; users using the applicable &kde; +software, not just those using the same operating system.</para> +<para>You can subscribe to this list at <ulink +url="https://mail.kde.org/mailman/listinfo/kde">https://mail.kde.org/mailman/listinfo/kde</ulink>.</para> +<para>You can find archives at <ulink +url="http://lists.kde.org/?l=kde">http://lists.kde.org/?l=kde</ulink>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>The &kde;-&Linux; List +<indexterm><primary>kde-linux Mailing List</primary></indexterm></term> +<listitem> +<para>This mailing list focusses specifically on questions and discussions +regarding using &kde; on &Linux;. Questions and discussions can involve any +issue confronting desktop users who run &kde; on a &Linux; system. Hence, +questions such as <quote>How do I setup a networked printer for printing from +&kde; on LinuxDistro X.Y</quote> are appropriate here. If you prefer a list +limited to <acronym>OS</acronym>-independent questions and discussions +concerning &kde;, please use the general &kde; mailing list.</para> +<para>You can subscribe to this list at <ulink +url="https://mail.kde.org/mailman/listinfo/kde-linux">https://mail.kde.org/mailman/listinfo/kde-linux</ulink>.</para> +<para>You can find archives at <ulink +url="http://lists.kde.org/?l=kde-linux">http://lists.kde.org/?l=kde-linux</ulink>.</para> +</listitem> +</varlistentry> +</variablelist> +</sect3> + +<sect3> +<title>IRC</title> + +<para>There is a #kde channel on Freenode (irc.freenode.net) for support and other general talk about &kde;. As usual, you can access this channel by using any of &kde;'s popular IRC clients which include <application>konversation</application>, &ksirc;, as well as &kopete;. For more information, check the <xref linkend="irc"/> section.</para> + +</sect3> +</sect2> + + +<sect2 id="more-resources"> +<title>More Resources</title> + +<para>There are many other resources which you may found useful; some of these are listed below:</para> + +<variablelist> +<varlistentry> +<term>dot.kde.org +<indexterm><primary>&kde; News Resource</primary></indexterm></term> +<listitem> +<para>This website has a searchable &kde; news resource where you can find out about a superfluity of innovations in the world of &kde;.</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<varlistentry> +<term>kde-look.org +<indexterm><primary>icandy for &kde;</primary></indexterm></term> +<listitem> +<para>The paramount resource for &kde; icandy, including themes, window decorations, wallpapers, mouse themes and icons for your &kde; desktop. Note also that the site contains a howto section on how to install the most common of these.</para> +</listitem> +</varlistentry> +</variablelist> + +<variablelist> +<varlistentry> +<term>wiki.kde.org +<indexterm><primary>&kde; wiki</primary></indexterm></term> +<listitem> +<para>The official &kde; Wiki. From here you can have access to a plethora of information ranging from frequently asked questions and HOWTOs to tips and tricks. The wiki should never, however, be used as a substitute for the respective application's handbook or the official &kde; documentation.</para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/glossary.docbook b/doc/userguide/glossary.docbook new file mode 100644 index 000000000..1e4b85d74 --- /dev/null +++ b/doc/userguide/glossary.docbook @@ -0,0 +1,38 @@ +<chapter id="glossary"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<chapterinfo> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</chapterinfo> +--> + +<title>Glossary of Terms</title> + +<para>KDE/GUI/UNIX terms that are worth explaining.</para> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/groupware-kontact.docbook b/doc/userguide/groupware-kontact.docbook new file mode 100644 index 000000000..beaf1f338 --- /dev/null +++ b/doc/userguide/groupware-kontact.docbook @@ -0,0 +1,614 @@ +<chapter id="groupware-with-kontact"> + +<chapterinfo> +<authorgroup> +<author> +<personname> +<firstname>Marco</firstname> +<surname>Menardi</surname> +</personname> +<email>[email protected]</email> +</author> +</authorgroup> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> + +</chapterinfo> +<title>Sharing data with &kontact; via <acronym>IMAP</acronym></title> + +<sect1 id="kontact-imap-intro"> +<title>Introduction</title> + +<para>For my small office, I was looking for a long time for a +<acronym>PIM</acronym> solution that let me share data, so my secretary and +I can share contacts, appointments and so on. Being a &kde; user, I've heard +about the Kroupware project and wait its completion. But when I saw how +complicated is the architecture and setup of the +<application>Kolab</application> server 1.0 (the server side of the +project), I gave up, waiting for an easier to deploy +<application>Kolab</application> 2.0. In any case, the +<application>Kolab</application> stuff was clearly too much for my +needs. Fortunately in the &kde; wiki I've found some piece of +<acronym>IRC</acronym> conversation where they were talking about sharing +data without the <application>Kolab</application> infrastructure... mmm so +interesting!</para> + +<para>For small offices and needs, you can have &kontact; use shared data +without the need of installing the <application>Kolab</application> server +or another groupware backend. It can work with just an +<acronym>IMAP</acronym> server, that can be easily set up.</para> + +<para>My scenario is a server with Debian unstable and &kde; 3.4. I access +&kontact; and other fabulous GNU/Linux apps from windows using Cygwin/X, +while waiting Wine project to be able to run the last Windows programs I +need (and that are not available under GNU/Linux). I want to share contacts, +events, todo, notes with my secretary.</para> + +</sect1> + +<sect1 id="kontact-imap-whatis"> +<title>What is <acronym>IMAP</acronym></title> + +<para>This definition is from the <ulink +url="http://computeruser.com">ComputerUser.com High-Tech Dictionary:</ulink> +<blockquote><para>Internet Message Access Protocol. A protocol that allows a +user to perform certain electronic mail functions on a remote server rather +than on a local computer. Through IMAP the user can create, delete, or +rename mailboxes; get new messages; delete messages; and perform search +functions on mail. A separate protocol is required for sending mail. Also +called Internet Mail Access Protocol.</para></blockquote> </para> + +<para>So it can be considered a data storage. To use it you you need an +<acronym>IMAP</acronym> server, such as <application>Cyrus</application>, +<application>Courier</application> or <application>UW</application>.</para> + +</sect1> + +<sect1 id="kontact-kolab-or-imap"> +<title><application>Kolab</application> or <acronym>IMAP</acronym>?</title> + +<para><application>Kolab</application> brings the ability to share data +between different clients. It makes possible for your secretary to use +<application>Outlook</application> and you use &kontact;, for +instance.</para> + +<para>You will have a configuration interface which does user management, mail +account setup, a central <acronym>LDAP</acronym> config data and addressbook +server, spam and virus filtering, vacation scripts, free busy list handling, +resource handling (rooms, cars), groups, distribution lists, automatic +invitation handling, &etc;</para> + +<para>But that can cause initial setup troubles. For a newbie like me it +means: a long long frustrating nightmare, and too much complexity to manage +once working. So no, thanks, I'll go to simple +<acronym>IMAP</acronym>.</para> + +</sect1> + +<sect1 id="kontact-imap-cyrus"> +<title>How to set up <acronym>IMAP</acronym> server <application>Cyrus</application></title> + +<para>My choice is <application>Cyrus</application>, that is part of the +<application>Kolab</application> set of software, so if l will go for +<application>Kolab</application> in the future, at least I'm acquainted with +it.</para> <para>Let's start the installation and the setup!</para> + +<para>Become <systemitem class="username">root</systemitem>.</para> + +<screen># <userinput><command>apt-get</command> <command>install</command> cyrus21-imapd cyrus21-common cyrus21-admin cyrus21-client sasl-bin sasl2-bin</userinput> +<computeroutput>Installing cyrus21-imapd...</computeroutput><lineannotation>The installer asks something I've not understood about an search address... I just pressed <keycap>Enter</keycap></lineannotation>.</screen> + +<para>The installer also created the user <systemitem +class="username">cyrus</systemitem> that is in the (automatically created) +group <systemitem class="groupname">sasl</systemitem>, that is the +<quote>owner</quote> of all cyrus files. At the end with <command>ps +<option>-A</option></command> you can find the new processes: +<command>cyrmaster</command> and <command>notifyd</command>.</para> + +<para>The real problem in setting up <application>Cyrus</application> is the +authentication, just because it's not trivial and I'm a newbie, with limited +knowledge about what I'm doing.</para> + +<para><application>Cyrus</application> can use different +<acronym>SASL</acronym> (Simple Authentication and Security Layer) +mechanisms, the default being sasldb (it stores usernames and passwords in +the SASL secrets file <filename>sasldb</filename>), but also getpwent, +kerberos4, kerberos5, PAM, rimap, shadow and LDAP are supported.</para> + +<para> Since I don't want to define users/passwords different than the ones +that access my &Linux; box I choose then <quote>shadow</quote> mechanism so +<application>Cyrus</application> will use &Linux; passwords for +authenticate.</para> + +<para>To do so we have to tell sasl to use <command>saslauthd</command> as +password authentication method, and then setup <command>saslauthd</command> +to use <quote>shadow</quote> (or <quote>getpwent</quote>) as the +authentication mechanism.</para> + +<para>OK, let's start!</para> + +<para>As <systemitem class="username">root</systemitem>, change the Linux +password of <systemitem class="username">cyrus</systemitem> user:</para> + +<screen># <userinput><command>passwd <option>cyrus</option></command></userinput></screen> + +<para>Enter the password you like (and you will remember) we will use for +this example <quote>cyrus</quote> as the <application>cyrus</application> +administrator password.</para> + +<screen># <command>vi</command> <filename>/etc/imapd.conf</filename></screen> + +<programlisting>sasl_pwcheck_method: <userinput>saslauthd</userinput> <lineannotation>instead of the default <literal>auxprop</literal></lineannotation></programlisting> + +<para>remove the <literal>#</literal> remark from the line:</para> + +<programlisting>#admins: cyrus</programlisting> + +<para>this way you can administer <application>cyrus</application> logging +in as <systemitem class="username">cyrus</systemitem> user (what a fantasy I +have!)</para> + +<screen># <userinput><command>vi</command> <filename>/etc/default/saslauthd</filename></userinput></screen> + +<para>Uncomment the line:</para> + +<programlisting># START=yes</programlisting> + +<para>(otherwise the <application>saslauthd</application> will not start at +boot time, even if referenced in some <filename +class="directory">/etc/rcx.d</filename>!)</para> + +<para>and instead of <literal>MECHANISMS="pam"</literal> put +<userinput>MECHANISMS="shadow"</userinput> this way at the boot a +<command>saslauthd</command> <option>-a +<parameter>shadow</parameter></option> will be executed.</para> + +<para>Once exited from your editor, restart <application>sasl</application> +and <application>cyrus</application>.</para> + +<para>To test <acronym>IMAP</acronym>:</para> + +<screen> <userinput><command>su</command> <option>cyrus</option></userinput> +$ <userinput><command>imtest</command> <option>-m login -p imap localhost</option></userinput></screen> + +<para>You are prompted for the <systemitem +class="username">cyrus</systemitem> (user) password, so enter it.</para> + +<para>If the user <systemitem class="username">cyrus</systemitem> is +correctly authenticated, the following lines will appear:</para> + +<screen><computeroutput>S: L01 OK User logged in +Authenticated.</computeroutput></screen> +<para>To exit type <userinput>. logout</userinput> (&ie; dot space <quote>logout</quote>)</para> + +<para>Now add a user named <systemitem +class="username">groupware</systemitem> and set a password for it, using +your usual system tools. It should be in an unprivileged group such as +<systemitem class="groupname">nobody</systemitem> and does not require a +login shell or a home directory.</para> + +<para>Now I have to create the user and an <acronym>IMAP</acronym> in +<application>cyrus</application> also:</para> + +<screen># <userinput><command>cyradm</command> <option>--user cyrus localhost</option></userinput> +after entering the password for the admin user <systemitem class="username">cyrus</systemitem>, you get the prompt <prompt>localhost></prompt> +<prompt>localhost></prompt> <userinput><command>cm</command> <option>user.groupware</option></userinput> +<prompt>localhost></prompt> <userinput><command>lm</command></userinput> <lineannotation>lists the mailbox only just created</lineannotation> +<computeroutput>user.groupware (\HasNoChildren))</computeroutput> +<prompt>localhost></prompt> <userinput><command>quit</command></userinput></screen> + +<para>You can type <userinput><command>help</command></userinput> for a list +of available commands.</para> + +<para>You can check what has happened with:</para> + +<screen># <userinput><command>ls</command> <option>-l</option> <filename class="directory">/var/spool/cyrus/mail/g/user/groupware</filename></userinput> +<computeroutput>total 12 +-rw------- 1 cyrus mail 4 Oct 29 20:55 cyrus.cache +-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header +-rw------- 1 cyrus mail 76 Oct 29 20:55 cyrus.index</computeroutput></screen> + +<para>Now you should be able to connect with an <acronym>IMAP</acronym> client +as the <systemitem class="username">groupware</systemitem> user and see the +<literal>INBOX</literal>.</para> +<note><para>In the <acronym>IMAP</acronym> protocol, selecting the mailbox +<literal>INBOX</literal> is a magic word, a sort of <quote>alias</quote> for +the above directory structure. The client sees <literal>INBOX</literal>, and +the <acronym>IMAP</acronym> server maps it in the <filename +class="directory">/var/spool/cyrus/mail/...</filename> folder and file +structure.</para></note> + +</sect1> + +<sect1 id="kontact-imap-clients"> +<title>How to setup &kontact; clients</title> + +<para>I connect to my GNU/Linux office server PC (a sort of "black box" +without monitor and keyboard) from 2 &Windows; 2000 PC with +<application>Cygwin/X</application>, using them as a X-Window server (in the +near future I hope to replace both with 2 mini-itx thin clients using the +LTSP). With this setup every user runs &kontact; on the same machine where +<application>Cyrus</application> is installed and running +(localhost).</para> + +<para>To have &kontact; work with <acronym>IMAP</acronym>, there are these +steps to complete:</para> + +<procedure> + +<step><para>Create an <acronym>IMAP</acronym> account on the +<application>Cyrus</application> for fake <systemitem +class="username">groupware</systemitem> user (already previously +done!)</para></step> + +<step><para>Create/configure an <acronym>IMAP</acronym> account in &kmail; +for login as that user</para></step> <step><para>Use kresources to make +&kontact; components work with data taken from <acronym>IMAP</acronym> +source</para></step> + +<step><para>Enable groupware functionality and make related subfolders of +that <acronym>IMAP</acronym> <literal>INBOX</literal> (if not +already)</para></step> + +<step><para>Enjoy &kontact; and shared data through +<application>Cyrus</application> IMAP</para></step> + +</procedure> + +<para>So login to &kde; with the first <quote>real user</quote> account you +want to provide groupware functionality to.</para> + +<para>Let's create the IMAP account in &kmail;.</para> + +<para>Run &kontact; and select <guilabel>Mail</guilabel> (the &kmail; +component). From the menu choose +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure KMail +</guimenuitem><guilabel>Accounts</guilabel><guilabel>Receiving</guilabel></menuchoice> tab, press the <guibutton>Add...</guibutton> button. You will then be +prompted for the type of your email account, and select +<guilabel>disconnected IMAP</guilabel> (not just +<guilabel>IMAP</guilabel>). Then in the <guilabel>General</guilabel> tab +enter the following data:</para> + +<variablelist> +<varlistentry> +<term><guilabel>Account Name:</guilabel> <userinput>office_gwdata</userinput></term> +<listitem> +<para>A name that will be used for the <quote>local</quote> folder that +points to this <acronym>IMAP</acronym> account.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Login:</guilabel> <userinput>groupware</userinput></term> +<listitem> +<para>The <application>Cyrus</application> user we have chosen as +<quote>owner</quote> of all of the office data</para> +</listitem> +</varlistentry> +<varlistentry><term><guilabel>Password:</guilabel></term> +<listitem> +<para>The password of the <systemitem +class="username">groupware</systemitem> user.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Host:</guilabel> <userinput>localhost</userinput></term> +<listitem> +<para>Remember for our example, the &kontact; client runs on the same +computer as the <acronym>IMAP</acronym> server</para> +</listitem> +</varlistentry> +<varlistentry> +<term><guilabel>Port:</guilabel> <userinput>143</userinput></term> +<listitem> +<para>The default</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Check <guilabel>store IMAP password</guilabel> +so you will not be asked for it next time you run &kontact;. Check the +<guilabel>Enable interval mail checking</guilabel> and set a value in +minutes.</para> + +<para>Note that we have checked the <guilabel>disconnected IMAP</guilabel> +type account. This has the effect that a copy of the groupware data is +stored <quote>locally</quote> to the client (under the home folder), and it +is synchronized every time the client connects. This seems very inefficient, +since your data is duplicated many times (&ie; if you have 10 users that use +&kontact;, you have 10+1 times the data), but it is the only way to make +things run fast, because at every connection &kontact; has to fetch all data +and have &korganizer; and &kaddressbook; interpret it. If you use +<quote>disconnected IMAP</quote> data is cached locally, and only the +<quote>delta</quote> (&ie; the data that has changed) is sent.</para> + +<para>On the other end, if your users run &korganizer; on the same PC that +runs the <acronym>IMAP</acronym> server, it seems reasonable to use +<acronym>IMAP</acronym> (that is called <quote>online IMAP</quote>) to save +space, since transfer speed should not be an issue. But unfortunately this +does not work because &kontact; does not update automatically the +<guilabel>Calendar</guilabel> folder in <quote>online IMAP</quote>, so you +are not updated when someone adds events (you must manually switch to +&kmail; application and click on the <guilabel>Calendar</guilabel> +folder). In addition, at start up when it does read +<guilabel>Calendar</guilabel> folders, you may see a tremendous flicker and +slow data updates.</para> + +<para>Now we have to tell &kontact; to use <acronym>IMAP</acronym> as the +data source for it's various components. From the &kmenu;, choose +<guimenuitem>Run command</guimenuitem>, run <userinput><command>kcmshell +kresources</command></userinput>. In the combo box select +<guilabel>Contacts</guilabel>, then press the <guibutton>Add...</guibutton> +button, and choose <guilabel>Addressbook on IMAP Server via KMail</guilabel>. Then select that new line and +press <guibutton>Use as Standard</guibutton> button. Do the same for +<guilabel>Calendar</guilabel> and <guilabel>Notes</guilabel>.</para> + +<para>Now we have to enable the &kmail; (and as a consequence, the whole +&kontact;) groupware functionality:</para> + +<procedure> +<step> +<para>Choose from the menu +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +KMail</guimenuitem><guilabel>Misc</guilabel><guilabel>Groupware</guilabel></menuchoice></para> +</step> +<step> +<para>Check <guilabel>Enable IMAP resource functionality</guilabel></para> +</step> +<step> +<para>Choose <guilabel>English</guilabel> as <guilabel>Language of the +groupware folders</guilabel> (this is in case you already have the folders +in the <acronym>IMAP</acronym> server created by a different program in a +different language).</para> +</step> +<step> +<para>Now move to <guilabel>Resource folder are in account</guilabel> and +select the the <guilabel>Inbox</guilabel> subfolder of the +<guilabel>office_gwdata</guilabel> folder.</para> +<para>Leave <guilabel>Hide groupware folders</guilabel> unchecked for now, +so we can see that happens. You can return here and check it once everything +is clear.</para> +</step> +<step> +<para>When you press OK you are prompted with: +<computeroutput>&kmail; will now create the required folders for the IMAP +resource as subfolders of Inbox</computeroutput> </para> +<para>If you do not want this, press <guibutton>No</guibutton>, and the +<acronym>IMAP</acronym> resource will be disabled. Press +<guibutton>Yes</guibutton> (this happens only the first time with the first +<quote>real user</quote>). You will immediately see that in the &kmail; +folder tree, under +<menuchoice><guilabel>office_gwdata</guilabel><guilabel>Inbox</guilabel></menuchoice> +these subfolders are created:</para> +<simplelist> +<member>Calendar</member> +<member>Contacts</member> +<member>Notes</member> +<member>Tasks</member> +<member>Journal</member> +</simplelist> +<para>if you now do a:</para> +<screen># <command>ls</command> <option>-l /var/spool/cyrus/mail/g/user/groupware/</option> +<computeroutput>drwx------ 2 cyrus mail 144 Oct 31 16:36 Calendar +drwx------ 2 cyrus mail 144 Oct 31 16:36 Contacts +drwx------ 2 cyrus mail 144 Oct 31 16:36 Journal +drwx------ 2 cyrus mail 144 Oct 31 16:36 Notes +drwx------ 2 cyrus mail 144 Oct 31 16:36 Tasks +-rw------- 1 cyrus mail 4 Oct 31 15:28 cyrus.cache +-rw------- 1 cyrus mail 155 Oct 29 20:55 cyrus.header +-rw------- 1 cyrus mail 76 Oct 31 15:28 cyrus.index</computeroutput></screen> + +<para>As you see, the <guilabel>office_gwdata Inbox</guilabel> is stored not +local to the &kontact; current user home, but in the <acronym>IMAP</acronym> +<systemitem class="username">groupware</systemitem> user's folders.</para> +</step> +</procedure> + +<para>Now &kontact; is ready to work and store data there. In the calendar +application, if &kmail; <acronym>IMAP</acronym> account was of type +<quote>disconnected</quote>, the <guilabel>resource</guilabel> window should +display the item <guilabel>Imap resource</guilabel> with 3 subitems, that +are paths to local home files. Instead, the <guilabel>Contacts</guilabel> +application does not show subitems below the <guilabel>Imap +resource</guilabel>.</para> + +<para>You can now login to &kde; with a different username and set up +his/her &kontact; client in a very similar manner:</para> + +<procedure> +<step> +<para>Open &kontact; and in the <guilabel>Mail</guilabel> component add an +<acronym>IMAP</acronym> account specifying as <guilabel>host</guilabel> the +computer where <application>Cyrus</application> server runs (in my case: +<literal>192.168.1.3</literal>).</para> + +<para>Remember to check the <guilabel>Enable interval mail +checking</guilabel> and set a value in minutes. When you confirm, you are +not prompted for the subfolder creation (since they are found in the +<acronym>IMAP</acronym> server), and you see them in the folder tree.</para> +</step> +<step> +<para>Activate the groupware functionality to be able to save data in the +<acronym>IMAP</acronym> server.</para> +</step> +</procedure> +<para>Beware that in <quote>disconnected <acronym>IMAP</acronym></quote>, +data are transmitted from a client to <acronym>IMAP</acronym> server only +when the clients connects to check for new mail. So if you have your +&kontact; clients with an <guilabel>interval mail checking</guilabel> of, +for instance, 5 minutes, in the worst case you have a 10 minutes delay +between the event being written and it's appearance to the other +users.</para> +</sect1> +<sect1 id="kontact-imap-readonly"> +<title>How to have Read Only Access</title> + +<note><para>Beware that I've been confirmed that Notes +<acronym>IMAP</acronym> implementation in &kontact; prior to version 1.01 is +broken, so this setup will not work for them, so you want to use them, you +need to use the previous setup.</para></note> + +<para>In the previous setup, we have the same <quote>fake</quote> user, named +<systemitem class="username">groupware</systemitem>, that is used by all the +<quote>real</quote> &kontact; users (&ie; <systemitem +class="username">tony</systemitem>, <systemitem +class="username">rohn</systemitem>, <systemitem +class="username">amanda</systemitem>, &etc;) through the +<acronym>IMAP</acronym> account with it's login and password. But this way +every real user has the same read/write permissions of the others, since +everyone connects as the user <systemitem +class="username">groupware</systemitem> to the <acronym>IMAP</acronym> +server.</para> + +<para>To limit access to some users (typically, providing read-only access), +we can use the <acronym>ACL</acronym> (Access Control Lists).</para> + +<para>Select in &kmail; a subfolder of <guilabel>office_gwdata</guilabel> +inbox, for instance <guilabel>Calendar</guilabel>, and right click the +mouse. Select <guilabel>Properties</guilabel><guilabel>Access +Control</guilabel> tab. Here you can enter the users you want give access to +this folder and what they can do.</para> + +<para>Just to experiment trying to exchange events, we give +<quote>All</quote> permission to the user <systemitem +class="username">mary</systemitem></para> + +<para>At <application>cyrus</application> level (in the +<acronym>PC</acronym> that runs <acronym>IMAP</acronym> server cyrus, with +<application>cyrus</application> tools), we first need to add the user +<systemitem class="username">mary</systemitem>, so it's an +<acronym>IMAP</acronym> recognized user, and create an +<acronym>IMAP</acronym> folder for her.</para> + +<para>Then we login to GNU/Linux as <systemitem +class="username">mary</systemitem> and enter &kontact;. As previously shown, +we will setup an <acronym>IMAP</acronym> account in &kmail; with the same +data but the one of the user (instead of the fake user <systemitem +class="username">groupware</systemitem> and it's password, we will use +<systemitem class="username">mary</systemitem> and her password).</para> + +<para>In &kmail; folder tree, this time you will see this structure: +<menuchoice><guimenu>office_gwdata</guimenu><guisubmenu>user</guisubmenu> +<guisubmenu>groupware</guisubmenu><guimenuitem>Calendar and +Tasks</guimenuitem></menuchoice>. Check the mail +(<menuchoice><guimenu>File</guimenu><guimenuitem>Check +Mail</guimenuitem></menuchoice>) and you will also have an +<quote>inbox</quote> folder under <quote>office_gwdata</quote>.</para> + +<para>Now enable &kmail; groupware functionality, and in <guilabel>Resource +folders are subfolders of</guilabel> put the +<guimenuitem>inbox</guimenuitem> that is subfolder of +<quote>office_gwdata</quote>.</para> + +<para>Now enable &kmail; groupware functionality, and in <guilabel>Resource +folders are subfolders of</guilabel> put the +<guimenuitem>inbox</guimenuitem> that is subfolder of +<guisubmenu>office_gwdata</guisubmenu>.</para> + +<para>Now you have two branches of folder under +<quote>office_gwdata</quote>:</para> + +<orderedlist> +<listitem> +<para><quote>inbox</quote> with Calendar, Contacts, Notes, Tasks and +Journal, that are saved on <systemitem class="username">mary</systemitem> +<acronym>IMAP</acronym> folders on the <acronym>IMAP</acronym> server</para> +</listitem> +<listitem> +<para><quote>user</quote>, with the subfolder <quote>groupware</quote> and +the subfolders to which <systemitem class="username">mary</systemitem> has +access to (in this example, Calendar and Tasks)</para> +</listitem> +</orderedlist> +<para>&RMB; click on the <quote>user</quote> <quote>Calendar</quote> and +check if it's of type Calendar (if not, set it to be), and also if +<quote>user</quote><quote>Tasks</quote> is of type Tasks.</para> +<para>Now in Calendar you have two available <acronym>IMAP</acronym> +resources to write against, so if you create a new event, you are prompted +which one use (or if you left the local resources available, you have +3!).</para> +<para>You have go to the lower left small window in Calendar, the one that +shows available resources, and uncheck the ones that don't point to +<guilabel>.groupware.directory</guilabel> path (see the tail part of each +resource path).</para> + +</sect1> + +<sect1 id="kontact-imap-credits"> +<title>Credits</title> + +<para>I'm a newbie, and for this howto I've only provided my time and my +will. For the knowledge I have really to thank some guys in freenode +channels for their competence, patience and helpfulness.</para> + +<itemizedlist> +<title>Special thanks to:</title> +<listitem> +<para>For the <application>Cyrus</application> <acronym>IMAP</acronym> part +in #cyrus channel:</para> +<itemizedlist> +<listitem> +<para>[protagonist] Andy Morgan <email>[email protected]</email></para> +</listitem> +<listitem> +<para>[plixed] Okke Timm <email>[email protected]</email></para> +</listitem> +</itemizedlist> +</listitem> +<listitem> +<para>For the &kontact; part in #kontact channel:</para> +<itemizedlist> +<listitem> +<para>[till] Till Adam <email>[email protected]</email></para> +</listitem> +<listitem> +<para>[dfaure] David Faure <email>[email protected]</email></para> +</listitem> +<listitem> +<para>[mdouhan] Matt Douhan <email>[email protected]</email></para> +</listitem> +</itemizedlist> +</listitem> +</itemizedlist> + +<para>Thank a lot guys!</para> + +<para>Ah, and there is also me, [markit] Marco Menardi +<email>[email protected]</email></para> + +</sect1> + +<sect1 id="kontact-imap-further-reading"> +<title>Further Reading</title> + +<itemizedlist> +<title>Reference</title> +<listitem><para>KDE: <ulink url="http://www.kde.org">http://www.kde.org</ulink></para></listitem> +<listitem><para>&kontact; website: <ulink url="http://www.kontact.org">http://www.kontact.org</ulink></para></listitem> +<listitem><para>Kroupware project: <ulink url="http://www.kroupware.org">http://www.kroupware.org</ulink></para></listitem> +<listitem><para>&kde; Community Wiki: <ulink url="http://wiki.kde.org">http://wiki.kde.org</ulink></para></listitem> +<listitem><para>Wine project: <ulink url="http://www.winehq.org">http://www.winehq.org</ulink></para></listitem> +<listitem><para>Cygwin/X project <ulink url="http://x.cygwin.com">http://x.cygwin.com</ulink></para></listitem> +<listitem><para>LTSP project: <ulink url="http://www.ltsp.org">http://www.ltsp.org</ulink></para></listitem> +</itemizedlist> + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/index.docbook b/doc/userguide/index.docbook new file mode 100644 index 000000000..b039979ce --- /dev/null +++ b/doc/userguide/index.docbook @@ -0,0 +1,611 @@ +<?xml version="1.0" ?> + <!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [ + <!ENTITY kappname "<replaceable>KApp</replaceable>"> + <!ENTITY % addindex "INCLUDE"> + <!ENTITY % imageobjectco.module "INCLUDE"> + <!ENTITY getting-help SYSTEM "getting-help.docbook"> + <!ENTITY programs-controlling SYSTEM "programs-controlling.docbook"> + <!ENTITY troubleshooting-no-open SYSTEM "troubleshooting-no-open.docbook"> + <!ENTITY troubleshooting-network-x SYSTEM "troubleshooting-network-x.docbook"> + <!ENTITY windows-how-to SYSTEM "windows-how-to.docbook"> + <!ENTITY the-filemanager SYSTEM "the-filemanager.docbook"> + <!ENTITY panel-and-desktop SYSTEM "panel-and-desktop.docbook"> + <!ENTITY programs-and-documents SYSTEM "programs-and-documents.docbook"> + <!ENTITY control-center SYSTEM "control-center.docbook"> + <!ENTITY customizing-desktop SYSTEM "customizing-desktop.docbook"> + <!ENTITY base-kde-applications SYSTEM "base-kde-applications.docbook"> + <!ENTITY removable-disks SYSTEM "removable-disks.docbook"> + <!ENTITY burning-cds SYSTEM "burning-cds.docbook"> + <!ENTITY playing-music SYSTEM "playing-music.docbook"> + <!ENTITY playing-audiocds SYSTEM "playing-audiocds.docbook"> + <!ENTITY playing-movies SYSTEM "playing-movies.docbook"> + <!ENTITY your-kde-account SYSTEM "your-kde-account.docbook"> + <!ENTITY kde-as-root SYSTEM "kde-as-root.docbook"> + <!ENTITY switching-sessions SYSTEM "switching-sessions.docbook"> + <!ENTITY file-sharing SYSTEM "file-sharing.docbook"> + <!ENTITY networking-with-windows SYSTEM "networking-with-windows.docbook"> + <!ENTITY shared-sessions SYSTEM "shared-sessions.docbook"> + <!ENTITY printer-setup SYSTEM "printer-setup.docbook"> + <!ENTITY printing-from-apps SYSTEM "printing-from-apps.docbook"> + <!ENTITY pdf-files SYSTEM "pdf-files.docbook"> + <!ENTITY font-installation SYSTEM "font-installation.docbook"> + <!ENTITY creating-graphics SYSTEM "creating-graphics.docbook"> + <!ENTITY screen-captures SYSTEM "screen-captures.docbook"> + <!ENTITY konsole-intro SYSTEM "konsole-intro.docbook"> + <!ENTITY kde-edutainment SYSTEM "kde-edutainment.docbook"> + <!ENTITY accessibility SYSTEM "accessibility.docbook"> + <!ENTITY under-the-hood SYSTEM "under-the-hood.docbook"> + <!ENTITY net-connection-setup SYSTEM "net-connection-setup.docbook"> + <!ENTITY email SYSTEM "email.docbook"> + <!ENTITY internet-shortcuts SYSTEM "internet-shortcuts.docbook"> + <!ENTITY browser-fine-tuning SYSTEM "browser-fine-tuning.docbook"> + <!ENTITY usenet SYSTEM "usenet.docbook"> + <!ENTITY messaging-intro SYSTEM "messaging-intro.docbook"> + <!ENTITY kde-office SYSTEM "kde-office.docbook"> + <!ENTITY kde-for-admins SYSTEM "kde-for-admins.docbook"> + <!ENTITY migrator-dictionary SYSTEM "migrator-dictionary.docbook"> + <!ENTITY glossary SYSTEM "glossary.docbook"> + <!ENTITY standard-menu-entries SYSTEM "standard-menu-entries.docbook"> + <!ENTITY where-next SYSTEM "where-next.docbook"> + <!ENTITY credits-and-license SYSTEM "credits-and-license.docbook"> + <!ENTITY groupware-with-kontact SYSTEM "groupware-kontact.docbook"> + <!ENTITY extragear-applications SYSTEM "extragear-applications.docbook"> + <!ENTITY migrator-applications SYSTEM "migrator-applications.docbook"> + <!ENTITY % English "INCLUDE"> +]> + +<book lang="&language;"> +<bookinfo> +<title>The &kde; User Guide</title> + +<authorgroup> +<corpauthor> +The &kde; Documentation Team +</corpauthor> + +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<copyright> +<year>2004</year><year>2005</year> +<holder>The &kde; Documentation Team</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<date>2004-06-16</date> +<releaseinfo>0.0.1</releaseinfo> + +<abstract> +<para>A general user guide to &kde; +</para> + +<para>Please report any problems with this document to +<email>[email protected]</email>. +</para> +</abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>desktop</keyword> +<keyword>handbook</keyword> +<keyword>tutorial</keyword> +</keywordset> + +</bookinfo> + +<part id="introduction"> +<title>Introduction</title> + +<chapter id="welcome"> +<title>Welcome to the &kde; User Guide</title> + +<para>This User Guide aims to provide an overview of the entire &kde; experience. We +assume here that you have a standard, working installation of a complete &kde; +desktop environment, and the accompanying packages. This book should be +your first point of reference for any simple &kde; configuration question, or +to find out how to perform a common task.</para> + +<sect1 id="what-the-ug-is"> +<title>What this book aims to be</title> + +<para>The first place to look and a one stop shop for all questions you have +regarding your &kde; experience.</para> + +<para>A Quick Start Guide to commonly performed tasks - In most cases, you do not +need to know the details of how to configure every option in an application, +in order to get down to work. You will find step-by-step guides which +will work in most common situations, along with links to sources of +further information in case you have any problems.</para> + +<para>There are also some tips and tricks showing you the most useful and +impressive features of &kde;, and ways to save you time and effort.</para> + +</sect1> + +<sect1 id="what-the-ug-is-not"> +<title>What this book is not</title> + +<para>The User Guide is not intended to be a replacement for the application +manuals. You should turn to the handbook for help with specific program +configuration and troubleshooting issues not covered in this book. If the +answer is outside the scope of this book, we will tell you here precisely +where to look for further help.</para> + +<para>You may also have a variety of third party packages, and some of these +applications are mentioned briefly here, but we normally cover only the +applications provided as part of a &kde; release. This is not a judgment on +the value of third party applications, and in fact many of them are +excellent.</para> + +<para>The User Guide is not specific to a distribution, and covers a default &kde; +installation. Your local installation may be customized by your +distribution provider, or by yourself, and so our advice here is +generic. You may have to adjust paths in order to locate the files that are +discussed.</para> +</sect1> + +<sect1 id="typographic-conventions"> +<title>Conventions used in this book</title> + +<para>We'll use the following formatting conventions to make it clear what +we're referring to: +<informaltable> +<tgroup cols="3"> + +<thead> +<row> +<entry>Type of Text</entry> +<entry>Style</entry> +<entry>Example</entry> +</row> +</thead> +<tbody> + +<row> +<entry>Text appearing in the &GUI; (on buttons, &etc;)</entry> +<entry>Light gray background</entry> +<entry><guilabel>Settings</guilabel></entry> +</row> + +<row> +<entry>Names of keys</entry> +<entry>Bold font</entry> +<entry>&Ctrl;</entry> +</row> + +<row> +<entry>Menu entries</entry> +<entry><quote>Menu Name</quote>-><quote>Menu Item</quote></entry> +<entry><menuchoice><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem> +</menuchoice></entry> +</row> + +<row> +<entry>Key combinations (pressed simultaneously)</entry> +<entry><quote>Modifier Key</quote>+<quote>Action Key</quote></entry> +<entry><keycombo action="simul">&Ctrl;<keycap>Q</keycap> +</keycombo></entry> +</row> + +<row> +<entry>Text you should enter</entry> +<entry>Bold, fixed width font</entry> +<entry><userinput>ls -al kde/</userinput></entry> +</row> + +<row> +<entry>Text you should replace as appropriate</entry> +<entry>Italic green font</entry> +<entry><replaceable>user</replaceable></entry> +</row> + +</tbody> +</tgroup> +</informaltable> +</para> + +</sect1> + +<sect1 id="system-locations"> +<title>System Locations</title> + +<para>You may need to know the following system locations: + +<variablelist> + +<varlistentry> +<term>&kde; prefix</term> +<listitem><para>&kde; installs into its own folder tree, which you can find by +running the command <userinput><command>kde-config</command> <option>--prefix</option></userinput>. This folder is referred to +by the environment variables $<envar>KDEDIRS</envar> and possibly +$<envar>KDEDIR</envar>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>&kde; user-specific settings</term> +<listitem><para>The environment variable $<envar>KDEHOME</envar> +points to the folder where &kde; should find user-specific settings. If it is not +set, the default value of <filename +class="directory">~/.kde</filename> is used.</para> +</listitem> +</varlistentry> + +</variablelist> + +</para> +</sect1> + +<sect1 id="overview"> +<title>Overview, or <quote>Where to look in the User Guide</quote></title> + +<para>Here's an overview of what's in the User Guide:</para> + +<para><xref linkend="desktop"/> contains an introduction to the basic +use of &kde;, such as <xref linkend="windows-how-to-work"/>, and the tools +that you'll be using in all &kde; applications, like <xref +linkend="programs-save-open" />. If you're new to &kde; or even +computers in general, you will probably find this section +helpful.</para> + +<para><xref linkend="components"/> explains some important components +of a &kde; installation and how they fit together: &kde;'s multimedia +and networking capabilities are extensive, and not covered thoroughly +here, but there's a taster of both of them in this part of the User +Guide. At the end of this part, you'll find a guide to tweaking &kde; +just that little bit more, in <xref +linkend="tinkering-under-the-hood"/>.</para> + +<para><xref linkend="kde-online"/> highlights &kde;'s suite of +Internet applications. &kde; includes a powerful web browser, +&konqueror;, a full-featured email client, &kmail;, a news reader, +&knode;, and many more applications to make your Internet experience +easier and more productive. This part of the User Guide contains +information about setting up these applications.</para> + +<para><xref linkend="kde-for-administrators"/> is a reference guide to +some &kde; features which will be useful to administrators setting up +multi-user systems. This part also has information that may be useful +to &kde; users with single-user systems: where configuration files are +stored, what environment variables affect &kde;, and so on. The KIOSK +framework is the &kde; system which allows administrators to limit +what users can do in &kde;. It is potentially useful in many +situations, but especially for running single-function kiosks with, +for example, just a web browser, hence the name.</para> + +</sect1> +</chapter> +</part> + +<part id="desktop"> +<title>The Desktop</title> + +<chapter id="basics"> +<title>The Basics</title> +<para>The <quote>desktop</quote><indexterm><primary>Desktop</primary> +</indexterm> is just the name for the layout of +the screen when you start &kde;. It looks something like this (on your +own system, it might look slightly different, but the main features +should be the +same):</para> + +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="desktop.png" format="PNG"/> +</imageobject> +<textobject><phrase>A default desktop layout</phrase> +</textobject> +</mediaobject> +</screenshot> + +<para>Let us look at the most important parts: +<itemizedlist> +<listitem><para>Most of the screen is +taken up by the background<indexterm><primary>Background</primary></indexterm>. At the moment, there is a picture making up +the background. This picture is usually referred to as the +<quote>wallpaper,</quote><indexterm><primary>Wallpaper</primary></indexterm> and you can change it to make &kde; suit your +taste.</para> +</listitem> + +<listitem><para>In the top left-hand corner are two icons: +<guiicon>Trash</guiicon> and <guiicon>Home</guiicon>. Clicking on +these will open your <filename>Trash</filename> folder and Home +folder, respectively. You can add more icons to the desktop so that +you can open your favorite programs, or access removable media, with +just one click.</para> +</listitem> + +<listitem><para>At the bottom is the &kde; Panel<indexterm><primary>Panel</primary></indexterm>, also known as +<quote>&kicker;</quote>. The Panel contains several useful ways of +interacting with &kde;. It houses the &kmenu;, from where you can open +any &kde; application installed on your computer, it shows all the +programs that are currently running, as well as the time, and more. +Take a look at <xref linkend="panel-and-desktop"/> for more +information about the &kde; Panel.</para> +</listitem> +</itemizedlist></para> + +<!-- Put this somewhere else +At the far left is the &kmenu; +button. Clicking on this button will open the main &kde; menu, which +has links to all the installed &kde; applications, and some useful +commands, like <guilabel>Find Files</guilabel> and <guilabel>Log +Out</guilabel>. You can start an application by finding it in the +&kmenu; and clicking on its name. Like the other things on the +desktop, the &kmenu; can be changed to fit your needs.</para> +</listitem> +--> + +<!-- Put this in the Panel section +<listitem><para>Next to the &kmenu; button are icons which will +start some commonly-used &kde; applications. icons are similar +to the ones on the desktop background, but you can only put links to +programs here (and not links to removable media, like CDs).</para> +</listitem> + +--> + +<sect1 id="logging-in"> +<sect1info> +<authorgroup> +<author> +&Philip.Rodrigues; +</author> +</authorgroup> +</sect1info> + +<title>Logging In and Logging Out</title> +<para>Basic KDM & startkde stuff.</para> +<!-- Not sure what exactly to say about startkde and where to say it --> +<!-- (Phil) --> +<para>There are two ways to log into &kde;: graphically and via the +command line. We'll look at them both briefly:</para> + +<sect2 id="logging-in-graphically"> +<title>Logging in Graphically</title> +<indexterm><primary>login</primary></indexterm> +<indexterm><primary>&kdm;</primary></indexterm> + +<para>If you see a screen a little bit like the one below when you +start up your computer, then you are all set for logging in +graphically. Just enter your username in the +<guilabel>Login</guilabel> text box and your password in the +<guilabel>Password</guilabel> text box. Your password will not be shown +as you type it; it will probably be shown as asterisks. When you have +entered that information, click on the <guibutton>Login</guibutton> +button, and &kde; will start up. The &kde; splash screen will appear, +and keep you informed about the progress of &kde; startup, and when +it is done, &kde; will be ready to use.</para> +</sect2> + +<sect2 id="logging-in-via-cmdline"> +<title>Logging in via the Command Line</title> +<indexterm><primary><command>startkde</command></primary></indexterm> +<indexterm><primary><command>startx</command></primary></indexterm> + +<para>If you prefer using the command line, you can log in to &kde; +with the <command>startx</command> command. Add the line +<userinput>exec startkde</userinput> to the +<filename>.xinitrc</filename> file in your home folder (create it +if it does not exist), save the file, and then run +<command>startx</command>. &kde; should start in the same way as if +you had logged in graphically.</para> +</sect2> + +<sect2 id="logging-out"> +<title>Logging Out</title> +<indexterm><primary>logout</primary></indexterm> + +<para>Once you have finished using &kde; for the moment, you will +want to log out until next time. The easiest way to do this is to +click on the &kmenu; at the bottom left of your screen, and then +select the <guimenuitem>Log Out...</guimenuitem> item. A dialog with the +text <guilabel>End session for +<replaceable>username</replaceable></guilabel> will appear. To confirm +that you want to log out, click on the <guibutton>End Current Session</guibutton> +button. If you change your mind, and decide to carry on using &kde; +for now, hit <guibutton>Cancel</guibutton>.</para> + +<itemizedlist> +<title>Related Information</title> +<listitem><para>The &kdm; Handbook has information about using and setting up +the &kde; graphical login manager. You can read it in &khelpcenter; or +by entering <userinput>help:/kdm</userinput> in &konqueror;'s +<guilabel>Location</guilabel> bar.</para> +</listitem> +</itemizedlist> + +</sect2> +</sect1> + +&getting-help; +&windows-how-to; + +&the-filemanager; + + +</chapter> + +&panel-and-desktop; + +&programs-and-documents; + +</part> + +<part id="components"> +<title>&kde; Components</title> + +&control-center; + +&base-kde-applications; + +&extragear-applications; + +<chapter id="multimedia"> +<title>Multimedia With &kde;</title> + +&removable-disks; + +&playing-music; + +&playing-audiocds; + +&playing-movies; + +</chapter> + +<chapter id="multiuser-kde"> +<title>&kde; the Multiuser Desktop</title> + +&your-kde-account; + +&kde-as-root; + +&switching-sessions; +</chapter> + +<chapter id="networking"> +<title>Networking with &kde;</title> + +&file-sharing; + +&networking-with-windows; + +&shared-sessions; +</chapter> + +<chapter id="graphics-printing-and-fonts"> +<title>Graphics, Printing, and Fonts</title> + +&printer-setup; + +&printing-from-apps; + +&pdf-files; + +&font-installation; + +&creating-graphics; + +</chapter> +&customizing-desktop; + +&konsole-intro; + +&kde-edutainment; + +&accessibility; + +&under-the-hood; +</part> + +<part id="kde-online"> +<title>&kde; and the Internet</title> + +&net-connection-setup; + +&email; + +<chapter id="browser"> +<title>&konqueror;</title> + +<para>Intro to the browser</para> + +&internet-shortcuts; + +&browser-fine-tuning; +</chapter> + +&usenet; + +&messaging-intro; + +</part> + +&kde-office; + +&kde-for-admins; + +<part id="more"> +<title>More Tools</title> + +&migrator-applications; + +&migrator-dictionary; + +&standard-menu-entries; + +&glossary; + +<chapter id="troubleshooting"> +<title>Troubleshooting Problems</title> + +<para>Problems that aren't</para> + +<para>Frozen apps (how to kill them)</para> + +<para>Things won't open</para> + +<para>That scary crash dialog</para> + +<para>Reporting Bugs</para> + +<para>More Resources</para> + +&troubleshooting-network-x; + +&troubleshooting-no-open; + +</chapter> + +<chapter id="contributing"> +<title>Contributing to &kde;</title> + +<para>Some basic information to get encourage people to contribute to +&kde;, information about what's available, and how to get +started.</para> + +</chapter> + +</part> + + +<appendix id="appendix-credits"> +<title>Credits and Licenses</title> + +&credits-and-license; + +<sect1 id="license"> +<title>License</title> + +<!-- TRANS:CREDIT_FOR_TRANSLATORS --> + +&underFDL; +</sect1> + +</appendix> + +&documentation.index; + + +</book> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:nil +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/internet-shortcuts.docbook b/doc/userguide/internet-shortcuts.docbook new file mode 100644 index 000000000..f6705c292 --- /dev/null +++ b/doc/userguide/internet-shortcuts.docbook @@ -0,0 +1,80 @@ +<sect1 id="internet-keywords"> +<sect1info> +<authorgroup> +<author> +<personname> +<firstname>Simon</firstname> +<surname>Vermeersch</surname> +</personname> +<email>[email protected]</email> +</author> +</authorgroup> +</sect1info> + +<title>Internet Shortcuts</title> + +<indexterm><primary>Web shortcuts</primary></indexterm> +<indexterm><primary>Internet Shortcuts</primary></indexterm> +<indexterm><primary>gg:</primary></indexterm> + +<para>Internet shortcuts are a really useful feature of &konqueror;: +once you get used to them, you'll wonder how you ever lived without them.</para> + +<para>To see what internet shortcuts are, open up &konqueror; and type +<userinput>gg:kde</userinput> in the <guilabel>Location</guilabel> +bar.</para> + +<para>You will go to Google, searching for &kde;.</para> + +<para>They are many such shortcuts like <userinput>ggl:</userinput> (Google +I'm feeling lucky), <userinput>bug:</userinput> (bugs.kde.org) and so +on.</para> + +<para>To get a full list, click on <guimenu>Settings</guimenu> in the +&konqueror; menu, and select <guilabel>Web Shortcuts</guilabel>. Here you will find a full list of all the shortcuts. You can create +new ones, change existing ones, or delete unused shortcuts. You can also +disable web shortcuts if you don't like them. If you set the <guilabel>Default +search engine</guilabel>, you don't have to type the shortcut anymore. For +instance if you set it to Google, you can just type +<userinput>kde</userinput> in the <guilabel>Location</guilabel> bar, +and it will search Google for <quote>&kde;</quote>.</para> + +<para>In <guilabel>Keyword delimiter</guilabel> you can choose if you want +to separate a shortcut with a colon (<userinput>gg: kde</userinput>) or a +space (<userinput>gg kde</userinput>).</para> + +<para>A nice tip with Internet shortcuts is that you can use them from the +<guilabel>Run Command</guilabel> dialog. Just open it (through the &kmenu; +or with <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>) and +type your shortcut, ⪚ <userinput>gg: kde</userinput>, and press +&Enter;. It will automatically open &konqueror; with a Google +search for &kde;.</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/juk-icon.png b/doc/userguide/juk-icon.png Binary files differnew file mode 100644 index 000000000..2b58a33d3 --- /dev/null +++ b/doc/userguide/juk-icon.png diff --git a/doc/userguide/juk.png b/doc/userguide/juk.png Binary files differnew file mode 100644 index 000000000..9ec3ae91e --- /dev/null +++ b/doc/userguide/juk.png diff --git a/doc/userguide/kaboodle-icon.png b/doc/userguide/kaboodle-icon.png Binary files differnew file mode 100644 index 000000000..87ac58b8c --- /dev/null +++ b/doc/userguide/kaboodle-icon.png diff --git a/doc/userguide/kaboodle.png b/doc/userguide/kaboodle.png Binary files differnew file mode 100644 index 000000000..dbbcfd923 --- /dev/null +++ b/doc/userguide/kaboodle.png diff --git a/doc/userguide/kcalc-systray.png b/doc/userguide/kcalc-systray.png Binary files differnew file mode 100644 index 000000000..5e0ac5cc5 --- /dev/null +++ b/doc/userguide/kcalc-systray.png diff --git a/doc/userguide/kcontrol.png b/doc/userguide/kcontrol.png Binary files differnew file mode 100644 index 000000000..3de78f3f8 --- /dev/null +++ b/doc/userguide/kcontrol.png diff --git a/doc/userguide/kde-as-root.docbook b/doc/userguide/kde-as-root.docbook new file mode 100644 index 000000000..7e6bb6fe9 --- /dev/null +++ b/doc/userguide/kde-as-root.docbook @@ -0,0 +1,52 @@ +<sect1 id="root"> + +<sect1info> +<authorgroup> +<author> +&Francis.Giannaros; &Francis.Giannaros.mail; +</author> +</authorgroup> +</sect1info> + + +<title>Using &kde; as Root</title> + +<para>For &UNIX; operating systems there are often different users, which in turn might have different privileges. The conventional method is to have an ordinary user account, whose files are generally stored in <filename>/home/username</filename>, and then to also have a <systemitem class="username">root</systemitem> account. The <systemitem class="username">root</systemitem>, or Super User, account has system-wide privileges, being able to modify any file on the system. </para> + +<para>Although this means that it is easy to perform administrative tasks without hassle, it also means that there are no security restrictions imposed upon it. Thus, a small typographical error or other mistake can result in irrevocable damage.</para> + +<para>Some of the operating systems that run &kde; come with a graphical <systemitem class="username">root</systemitem> login enabled. Despite this, you should never log in to &kde; as <systemitem class="username">root</systemitem>, and you should never need to. Your system is far more open to attack, particularly if you are browsing the Internet as <systemitem class="username">root</systemitem>, and you dramatically increase your chances of damaging your system.</para> + +<para>Some &Linux; distributions have tried to stress this point so much that they have disabled the <systemitem class="username">root</systemitem> account altogether, and instead use the <command>sudo</command> model. Nevertheless, the basic security model in <command>sudo</command> is the same as <command>su</command>, and thus they share the same security strengths and weaknesses, essentially.</para> + +<para>If you should ever need to run a program with Super User privileges, then it is always recommend that you use &kdesu;. From &konsole; or from hitting <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>, enter <userinput>kdesu <replaceable>application</replaceable></userinput>, and the application will be run with the appropriate Super User privileges. </para> + +<para>Even if you have set up your system to use <command>sudo</command>, or you are on a distribution that uses <command>sudo</command>, such as &kubuntu;, you should still use &kdesu;. The program will be appropriately modified by the developers to use the correct settings. You should not, however, ever use <command>sudo <replaceable>application</replaceable></command> to run an application with <systemitem class="username">root</systemitem> permissions; it can derange permissions of certain configuration files for a program. Running a graphical applications as <systemitem class="username">root</systemitem> in general is not a good idea, but using &kdesu; will always be your safest bet with it.</para> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> +<listitem><para><ulink url="help:kdesu">&kdesu; Handbook</ulink></para> +</listitem> +</itemizedlist> + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/kde-edutainment.docbook b/doc/userguide/kde-edutainment.docbook new file mode 100644 index 000000000..11c6faae7 --- /dev/null +++ b/doc/userguide/kde-edutainment.docbook @@ -0,0 +1,342 @@ +<chapter id="kde-edutainment"> +<!-- Uncomment this and add your name in order to be credited for +writing this section +<chapterinfo> +<authorgroup> +<author> +Your name here +</author> +</authorgroup> +</chapterinfo> +--> + +<title>&kde; Edutainment</title> + +<para>The &kde; Edutainment Project offers children, families, and teachers some +educational programs. You can find applications to help you improve +your language skills and train your vocabulary, like &kvoctrain; and +&kwordquiz;; or Scientific programs, like the +very advanced &kstars; (a planetarium) and &kig; (interactive +geometry), which will bring you to the edge of knowledge. Have fun learning +touch-typing with &ktouch;. Teachers will find an easy way to make +their lessons with &keduca;. You can find a complete list of &kde; +educational software on <ulink url="http://edu.kde.org">the KDE-Edu +website</ulink>. What follows is an overview of a few of them. +</para> +<para>View the handbook of each application by typing <userinput>help:/<appname></userinput> in &konqueror;'s Location Toolbar, or by selecting it in &khelpcenter;. </para> + +<sect1 id="languages"> +<title>Improve your language skills</title> + +<variablelist> +<varlistentry> +<term>&khangman;</term> + <listitem><para>An easy-to-use application which implements the classical hangman game. You can choose for the words to be from a particular topic and even choose from a selection of difficulty levels. The program comes in twenty-four languages, and is therefore quite ideal for learning the spelling of basic nouns in other languages.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/khangman">http://edu.kde.org/khangman</ulink></para></listitem> + <listitem><para><ulink + url="help:/khangman">&khangman; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&klettres;</term> + <listitem><para>An application specially designed to help the user learn the alphabet of a new language and then to learn to read simple syllables. Ideal for children, or any person attempting to learn and familiarize themselves with a foreign language's alphabet. A number of alphabets are currently supported.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/klettres">http://edu.kde.org/klettres</ulink></para></listitem> + <listitem><para><ulink + url="help:/klettres">&klettres; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kanagram;</term> + <listitem><para>A simple mind-training game, in which you have to figure out the word that has been given in the program. The letters from the word are disordered, and from the given words you have to solve which word the letters might make, if rearranged. Similar to the popular Countdown game as seen on Television.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kanagram">http://edu.kde.org/kanagram</ulink></para></listitem> + <listitem><para><ulink + url="help:/kanagram">&kanagram; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kverbos;</term> + <listitem><para>A simple way to learn and study Spanish verb forms. The program suggests a verb and a tense and the user enters the different forms. The program corrects the user input and gives feedback. The user can edit the list of the verbs that can be studied and the program can build regular verb forms, and the forms of the most important verb groups, by itself. Irregular verb forms can be entered by the user.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kverbos">http://edu.kde.org/kverbos</ulink></para></listitem> + <listitem><para><ulink + url="help:/kverbos">&kverbos; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kvoctrain;</term> + <listitem><para>Another advanced vocabulary training application, using the flash card approach. <ulink url="http://edu.kde.org/contrib/kvtml.php">Vocabulary files</ulink> and be downloaded and loaded into the application.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kvoctrain">http://edu.kde.org/kvoctrain</ulink></para></listitem> + <listitem><para><ulink + url="help:/kvoctrain">&kvoctrain; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + + +<varlistentry> +<term>&kiten;</term> + <listitem><para>A Japanese reference and learning tool. Words from both English and Japanese can be looked up, and filtered, using the <application>Edict</application> and <application>Kanjidic</application> dictionary protocols. Other features in &kiten; include a few comprehensive search functions, a history of searches, and a learning section which contains various different learning modes.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kiten">http://edu.kde.org/kiten</ulink></para></listitem> + <listitem><para><ulink + url="help:/kiten">&kiten; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&klatin;</term> + <listitem><para>A program to help revise Latin. There are vocabulary, grammar, and verb testing sections. In addition there is a set of revision notes that can be used for self-guided revision.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/klatin">http://edu.kde.org/klatin</ulink></para></listitem> + <listitem><para><ulink + url="help:/klatin">&klatin; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="mathematics"> +<title>Mathematics</title> + +<para>Several applications to help you with Mathematics and Geometry.</para> + +<variablelist> +<varlistentry> +<term>&kbruch;</term> + <listitem><para>An application with several exercise types in order to enhance your calculating with fractions. Different tasks include exercises to find the sum of two fractions, the conversion of fractions into the respective decimal, the comparison (with less than, more than) of fractions, and more. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kbruch">http://edu.kde.org/kbruch</ulink></para></listitem> + <listitem><para><ulink + url="help:/kbruch">&kbruch; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kig;</term> + <listitem><para>A great application with interactive geometry. Ideal for teachers attempting to draw a graph on the computer, or students who wish to find out more and investigate with graphs and curves. Currently many things are supported, and you can very easily construct several things from parabolas and hyperbolas, to ellipses. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kig">http://edu.kde.org/kig</ulink></para></listitem> + <listitem><para><ulink + url="help:/kig">&kig; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kpercentage;</term> + <listitem><para>Essentially an application to help you improve your skills in calculating percentages. Different exercises are included, and there are varying difficulty levels to target persons with varying abilities.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kpercentage">http://edu.kde.org/kpercentage</ulink></para></listitem> + <listitem><para><ulink + url="help:/kpercentage">&kpercentage; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +</varlistentry> + +<varlistentry> +<term>&kmplot;</term> + <listitem><para>A mathematical function plotter. It has built in a powerful parser. You can plot different functions simultaneously and combine their function terms to build new functions. &kmplot; supports functions with parameters and functions in polar coordinates. Several grid modes are possible and plots may be printed with high precision in correct scale.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kmplot">http://edu.kde.org/kmplot</ulink></para></listitem> + <listitem><para><ulink + url="help:/kmplot">&kmplot; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +</variablelist> + + +</sect1> +<sect1 id="science"> +<title>Science</title> + +<variablelist> +<varlistentry> +<term>&kstars;</term> + <listitem><para>A desktop Planetarium for &kde;. It provides an accurate graphical simulation of the night sky, from any location on Earth, at any date and time. The display includes 130,000 stars, 13,000 deep-sky objects,all 8 planets, the Sun and Moon, and thousands of comets and asteroids.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kstars">http://edu.kde.org/kstars</ulink></para></listitem> + <listitem><para><ulink + url="help:/kstars">&kstars; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> + <term>&kalzium;</term> + <listitem><para>A fully-featured periodic table, with the full list of all elements, and extended information about each individual element is accessible. As well as being able to view a basic overview, other features include being able to view its chemical data, atomic model, energies, as well as a picture of the element.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kalzium">http://edu.kde.org/kalzium</ulink></para></listitem> + <listitem><para><ulink url="help:/kalzium">&kalzium; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +<!-- Screeny! --> +</varlistentry> +</variablelist> +</sect1> +<sect1 id="teaching_tools"> +<title>Teaching Tools</title> +<variablelist> +<varlistentry> + <term>&keduca;</term> + <listitem><para>A flash card application, which allows you to make interactive form-based tests. It also currently comes with support to add servers from which you can fetch tests from. Several languages supported.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/keduca">http://edu.kde.org/keduca</ulink></para></listitem> + <listitem><para><ulink url="help:/keduca">&keduca; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +<!-- Screeny! --> +</varlistentry> +</variablelist> +</sect1> +<sect1 id="miscellaneous"> +<title>Miscellaneous</title> +<variablelist> +<varlistentry> + <term>&ktouch;</term> + <listitem><para>An application for learning touch-typing. &ktouch; displays the keyboard on the screen, and the color of the keys changes when they need to be depressed. Text appears on the screen, and the user is asked to type it out. A few default lectures are contained in the program by default, with various different difficulty levels.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/ktouch">http://edu.kde.org/ktouch</ulink></para></listitem> + <listitem><para><ulink url="help:/ktouch">&ktouch; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +<!-- Screeny! --> +</varlistentry> + +<varlistentry> + <term>&kwordquiz;</term> + <listitem><para>A flash card application, which allows you to make interactive form-based tests. It also currently comes with support to add servers from which you can fetch tests from. Several languages supported.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kwordquiz">http://edu.kde.org/kwordquiz</ulink></para></listitem> + <listitem><para><ulink url="help:/kwordquiz">&kwordquiz; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +</varlistentry> + +<varlistentry> + <term>&kturtle;</term> + <listitem><para>An educational programming environment using the Logo programming language, with several languages currently supported.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/kturtle">http://edu.kde.org/kturtle</ulink></para></listitem> + <listitem><para><ulink url="help:/kturtle">&kturtle; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +</varlistentry> + +<varlistentry> + <term><application>&kgeography;</application></term> + <listitem><para>&kgeography; is a geography learning tool for &kde;. You can browse the maps by clicking in a map division to see its name and you can also answer several types of questions where the program shows you a map division or a capital for example and you have to guess its name.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://kgeography.berlios.de/">http://kgeography.berlios.de/</ulink> and <ulink url="http://edu.kde.org/kgeography">http://edu.kde.org/kgeography</ulink></para></listitem> + <listitem><para><ulink url="help:/kgeography"><application>&kgeography;</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +</varlistentry> + +<varlistentry> + <term><application>&blinken;</application></term> + <listitem><para>&blinken; is a Simon Says game for &kde;. The player should remember the sequence of lights in the correct order and is then presented with an identical sequence with one extra step.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://edu.kde.org/blinken">http://edu.kde.org/blinken</ulink></para></listitem> + <listitem><para><ulink url="help:/blinken"><application>&blinken;</application> Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> + +</varlistentry> + +</variablelist> +</sect1> + +<sect1 id="edu-related"> +<title>Related Information</title> +<itemizedlist> +<listitem><para>The &kde;-Edu website at <ulink +url="http://edu.kde.org">http://edu.kde.org</ulink> has news and +information about all the &kde; Edutainment applications.</para> +</listitem> +</itemizedlist> +</sect1> + + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/kde-for-admins.docbook b/doc/userguide/kde-for-admins.docbook new file mode 100644 index 000000000..f7d5d2ee0 --- /dev/null +++ b/doc/userguide/kde-for-admins.docbook @@ -0,0 +1,2747 @@ +<part id="kde-for-administrators"> +<partinfo> +<authorgroup> +<author> +<personname> +<firstname>Waldo</firstname> +<surname>Bastian</surname> +</personname> +<email>[email protected]</email> +</author> +<othercredit role="reviewer"> +&Philip.Rodrigues; +&Philip.Rodrigues.mail; +</othercredit> +</authorgroup> +</partinfo> + +<title>&kde; for Administrators</title> + +<chapter id="kde-internals"> +<title>&kde; Internals</title> + +<sect1 id="kde-for-admins-overview"> +<title>Overview</title> +<para>to be written</para> +</sect1> + +<sect1 id="directory-layout"> +<title>Directory Layout</title> + +<para>&kde; defines a filesystem hierarchy which is used by the &kde; +environment itself as well as all &kde; applications. In general &kde; +stores all its files in a directory tree with a fixed structure. +</para> + +<para>By default &kde; uses two directory trees:</para> + +<itemizedlist> +<listitem><para>One at the system level (for example <filename +class="directory">/opt/kde3</filename>).</para></listitem> +<listitem><para>One at the user level in the user's home directory +(usually <filename class="directory"> +~/.kde</filename>)</para></listitem> +</itemizedlist> + +<para>As a system administrator you can create additional trees. Such +additional trees can be used for <link +linkend="user-profiles">profiles</link></para> + +<informalexample><para>&SuSE; &Linux; for example uses:</para> + +<itemizedlist> +<listitem><para><filename +class="directory">$<envar>HOME</envar>/.kde</filename></para></listitem> +<listitem><para><filename +class="directory">/opt/kde3</filename>. (This is +&SuSE;-specific; other distributions may use +<filename class="directory">/usr</filename> or <filename +class="directory">/usr/kde3</filename>)</para></listitem> +<listitem><para><filename +class="directory">/etc/opt/kde3</filename>. (This was added by +&SuSE;).</para></listitem> +</itemizedlist> + +<para>If you have the KIOSK Admin tool v0.7 or later installed you can +check which directory trees are used with the following command: +<userinput><command>kiosktool-kdedirs</command> +<option>--check</option></userinput></para> +</informalexample> + +<para>&kde; and &kde; applications look up files by scanning all the +&kde; directory trees. The directory trees are checked in order of +precedence. When a file is present in multiple directory trees, the +file from the last tree takes precedence. Normally, the tree +located in the user's home directory has the highest precedence. This +is also the directory tree to which changes are written.</para> + +<informalexample> +<para>For information about the <literal>text/plain</literal> &MIME; type +the following files are searched:</para> + +<itemizedlist> +<listitem><para><filename +class="directory">$<envar>HOME</envar>/.kde/share/mimelnk/text/plain.desktop</filename></para></listitem> +<listitem><para><filename +class="directory">/opt/kde3/share/mimelnk/text/plain.desktop</filename></para></listitem> +<listitem><para><filename +class="directory">/etc/opt/kde3/share/mimelnk/text/plain.desktop</filename></para></listitem> +</itemizedlist> + +<para>If a user makes a change, the change is written to <filename +class="directory">$<envar>HOME</envar>/.kde/share/mimelnk/text/plain.desktop</filename></para> +</informalexample> + +<para>For configuration files the story is slightly different. If +there are multiple configuration files found in the directory trees +with the same name, their content is combined. The precedence order of +the directory trees plays a role here. When two files define the same +configuration key, the file with the highest precedence determines +which value is used for the key.</para> + +<informalexample><para> +For example, if the following two files exist, with these contents:</para> +<variablelist> +<varlistentry><term><filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename></term> +<listitem><programlisting> +Color=red +Shape=circle +</programlisting> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>/etc/opt/kde3/share/config/foobar</filename></term> +<listitem><programlisting> +Color=blue +Position=10,10 +</programlisting> +</listitem> +</varlistentry> +</variablelist> + +<para>The files will be merged to result in:</para> + +<programlisting> +Color=red +Shape=circle +Position=10,10 +</programlisting> + +</informalexample> +</sect1> + +<sect1 id="specifying-directories"> +<title>Specifying Directories</title> + +<para> + +<segmentedlist> +<segtitle>Environment Variable</segtitle> +<segtitle>Example Setting(s)</segtitle> +<segtitle>Comment</segtitle> + +<seglistitem> +<seg><envar>KDEHOME</envar></seg> +<seg><filename class="directory">~/.kde</filename></seg> +<seg></seg> +</seglistitem> + +<seglistitem> +<seg><envar>KDEROOTHOME</envar></seg> +<seg><filename class="directory">/root/.kde</filename></seg> +<seg>Different variable to prevent +root writing to $KDEHOME of the user after running +<command>su</command>.</seg> +</seglistitem> + +<seglistitem> +<seg><envar>KDEDIR</envar></seg> +<seg><filename class="directory">/opt/kde3</filename>, <filename +class="directory">/usr</filename>, <filename +class="directory">/usr/kde3</filename></seg> +<seg>Vendor dependent. Used by &kde; 2. If not set, falls back to +compiled-in default.</seg> +</seglistitem> + +<seglistitem> +<seg><envar>KDEDIRS</envar></seg> +<seg><filename class="directory">/opt/kde3</filename>, <filename +class="directory">/usr</filename>, <filename +class="directory">/usr/kde3</filename></seg> +<seg>New in &kde;3. Can list multiple locations separated by a +colon. If not set, falls back to $<envar>KDEDIR</envar></seg> +</seglistitem> + +</segmentedlist> +</para> +<para>Don't <emphasis>need</emphasis> to be set, defaults work just fine.</para> +<para>Running &kde;2 next to &kde;3? Point $<envar>KDEDIR</envar> to +&kde; 2 and $<envar>KDEDIRS</envar> to &kde; 3.</para> + +<informalexample> +<para>A staff member at a university could have the following +settings:</para> +<programlisting> +KDEHOME='~/.kde3' +KDEROOTHOME='/root/.kde3' +KDEDIRS='/opt/kde_staff:/opt/kde3' +</programlisting> + +</informalexample> + +</sect1> + +<sect1 id="user-profiles"> +<title>User Profiles</title> + +<para>In the previous example <filename +class="directory">/opt/kde_staff</filename> contained additional settings +and applications for staff members. <quote>User Profiles</quote> allow you +to add this directory only for certain users and not for others. Add the +following to <filename>/etc/kderc</filename>:</para> + +<programlisting> +[Directories-staff] +prefixes=/opt/kde_staff +</programlisting> + +<para>This creates a profile named <quote>staff</quote> that adds the +<filename class="directory">/opt/kde_staff</filename> directory +tree. (Note that &SuSE; &Linux; uses +<filename>/etc/kde3rc</filename> instead of +<filename>/etc/kderc</filename>. Now that we have a named profile it +can be assigned to users.</para> + +<para>To map profiles to users a mapping file needs to be specified in +<filename>/etc/kderc</filename>:</para> + +<programlisting> +[Directories] +userProfileMapFile=/etc/kde-user-profile +</programlisting> + +<para>It is now possible to assign a profile based on either the user name +or based on the &UNIX; group the user is part of.</para> + +<para>To assign the staff profile to all users that are a member of the +&UNIX; group staff_members add the following to +<filename>/etc/kde-user-profile</filename>:</para> + +<programlisting> +[General] +groups=staff_members +[Groups] +staff_members=staff +</programlisting> + +<para>It is also possible to assign a profile to a single user:</para> + +<programlisting> +[Users] +bastian=staff +</programlisting> + +</sect1> + +<sect1 id="directory-layout-revisited"> +<title>Directory Layout Revisited</title> + +<para>Each directory tree used by &kde; has a fixed directory structure. +Directories that are not relevant for a certain tree, or simply not used can +be left out though. For example, directories used for temporary files are +usually only found under <filename +class="directory">$<envar>KDEHOME</envar></filename> but not in any other +directory tree.</para> + +</sect1> + +<sect1 id="architecture-specific-directories"> +<title>Architecture-specific Directories</title> + +<para>Architecture (OS and CPU type) specific directories:</para> + +<variablelist> +<varlistentry> +<term><filename class="directory">bin</filename></term> +<listitem><para>Used for &kde; executables.</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">lib</filename></term> +<listitem><para>Used for &kde; libraries.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">lib/kde3</filename></term> +<listitem><para>This directory contains components, plugins, and other +runtime loadable objects for use by &kde; 3.<replaceable>x</replaceable> +applications.</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="shared-directories"> +<title>Shared Directories</title> + +<para>Shared: Not architecture specific, can be shared between different +archs.</para> + +<variablelist> +<varlistentry> +<term><filename class="directory">share/applnk</filename></term> +<listitem><para><literal role="extension">.desktop</literal> files for +&kde;-menu (old)</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/applications</filename></term> +<listitem><para><literal role="extension">.desktop</literal> files for +&kde;-menu (since &kde; 3.2)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/apps</filename></term> +<listitem><para>Contains application-specific data files. Each +application has a sub-directory here for storing additional data +files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/config</filename></term> +<listitem><para>Configuration files. Configuration files are normally +named after the application they belong to plus the letters +<quote>rc</quote>. A special case is <filename>kdeglobals</filename>. +This file is read by all &kde; applications.</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename +class="directory">share/config/session</filename></term> +<listitem><para>This directory is used by session management and is +normally only available under <filename +class="directory">$<envar>KDEHOME</envar></filename>. At the end of a +session &kde; applications store their state here. The file names +consist of the name of the application followed by a number. The +session manager <command>ksmserver</command> stores references to +these numbers when saving a session in +<filename>ksmserverrc</filename>.</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/doc/HTML</filename></term> +<listitem><para>This directory contains documentation for &kde; +applications. Documentation is categorized by language and the +application it belongs to. Normally at least two files can be found in +a directory: <filename>index.docbook</filename>, which contains the +documentation in the unformatted DocBook format, and +<filename>index.cache.bz2</filename>, which contains the same +documentation formatted as <command>bzip2</command>-compressed +&HTML;. The &HTML; version is used by &khelpcenter;. If the &HTML; +version is missing, &khelpcenter; will regenerate it from the DocBook +version but this is a time-consuming process.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/icons</filename></term> +<listitem><para>Under this directory icons are stored. Icons are +categorized by theme, dimension and usage category.</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/mimelnk</filename></term> +<listitem><para>In this directory,<literal +role="extension">.desktop</literal> files that describe &MIME; types +are stored. &kde; uses &MIME; types to identify the type of a +file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/services</filename></term> +<listitem><para>This directory contains <literal +role="extension">.desktop</literal> files that describe services. Services +are like applications but are usually launched by other applications instead +of the user. Services do not appear in the &kde; menu.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/servicetypes</filename></term> +<listitem><para>This directory contains <literal +role="extension">.desktop</literal> files that describe +servicetypes. A servicetype usually represents a certain programming +interface. Applications and Services include in their <literal +role="extension">>.desktop</literal> files the servicetypes that they +provide.</para> </listitem></varlistentry> + +<varlistentry> +<term><filename class="directory">share/sounds</filename></term> +<listitem><para>This directory contains sound files.</para></listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/templates</filename></term> +<listitem><para>This directory contains templates for creating files +of various types. A template consists of a <literal +role="extension">.desktop</literal> file that describes the file and +that includes a reference to a file in the <filename +class="directory">.source</filename> sub-directory. The templates in +this directory appear in the <guimenu>Create New</guimenu> menu +available on the desktop and in the file browser. When a user selects +a template from the menu its source file is copied.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename class="directory">share/wallpapers</filename></term> +<listitem><para>This directory contains images that can be used as +background picture</para></listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="host-specific-directories"> +<title>Host-specific Directories</title> + +<para>There are three host-specific directories that are usually +symlinked to other locations. If the directories do not already exist, +the following symlinks and directories will be created using the +<command>lnusertemp</command> utility:</para> + +<variablelist> + +<varlistentry> +<term><filename>$<envar>KDEHOME</envar>/socket-$<envar>HOSTNAME</envar></filename></term> +<listitem><para>Usually <filename +class="directory">/tmp/ksocket-$<envar>USER</envar>/</filename>, this +is used for various &UNIX; sockets.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>$<envar>KDEHOME</envar>/tmp-$<envar>HOSTNAME</envar></filename></term> +<listitem><para>Usually <filename +class="directory">/tmp/kde-$<envar>USER</envar>/</filename>, this is used for temporary files.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>$<envar>KDEHOME</envar>/cache-$<envar>HOSTNAME</envar></filename></term> +<listitem><para>Usually <filename +class="directory">/var/tmp/kdecache-$<envar>USER</envar>/</filename>, +this is used for cached files.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>Since both <filename class="directory">/tmp</filename> and +<filename class="directory">/var/tmp</filename> are world writable, +there is a possibility that one of the above directories already +exists but is owned by another user. In that case the +<command>lnusertemp</command> utility will create a new directory with +an alternative name and link to that instead.</para> + +</sect1> + +<sect1 id="configuration-files"> +<title>Configuration Files</title> <para>&kde; uses a simple +text-based file format for all its configuration files. It consists of +key-value pairs that are placed in groups. All &kde; configuration +files use <acronym>UTF</acronym>-8 encoding for text outside the +<acronym>ASCII</acronym> range.</para> + +<para>The start of a group is indicated by a group name that is placed +in square brackets. All the key-value entries that follow belong to +the group. The group ends when either another group starts or when the +end of the file is reached. Entries at the top of the +file that are not preceded by a group name belong to the default +group.</para> + +<informalexample><para>The following example shows a configuration +file that consists of two groups. The first group contains the keys +<varname>LargeCursor</varname> and <varname>SingleClick</varname>, the +second group contains the keys <varname>Show hidden files</varname> +and <varname>Sort by</varname>:</para> + +<programlisting> +[KDE] +LargeCursor=false +SingleClick=true +</programlisting> + +<programlisting> +[KFileDialog Settings] +Show hidden files=false +Sort by=Name +</programlisting> +</informalexample> + +<para>Entries in a group consist of a key and value separated by an equals +sign. The key can contain spaces and may be followed by options placed in +square brackets. The part after the equals sign is the value of the +entry. Any white space surrounding the equals sign is ignored, as is any +trailing white space. Put more concisely, the format is:</para> + +<programlisting> +<replaceable>entry</replaceable>=<replaceable>value</replaceable> +</programlisting> + +<para>If a value is supposed to include a space at the begin or end +then this can be achieved by using a backslash followed by an +<quote>s</quote>.</para> + +<para>There are several other backslash codes; here is a complete +list: +<itemizedlist> +<listitem><para><token>\s</token> can be used as space</para> +</listitem> +<listitem><para><token>\t</token> can be used to include a tab</para> +</listitem> +<listitem><para><token>\r</token> for a carriage return character</para> +</listitem> +<listitem><para><token>\n</token> for a linefeed character (new line)</para> +</listitem> +<listitem><para><token>\\</token> to include the backslash itself</para> +</listitem> +</itemizedlist></para> + +<informalexample><para>In the following example the value of the +<varname>Caption</varname> entry starts with two spaces while the +<varname>Description</varname> entry contains three lines of +text. Linefeeds in backslash notation are used to separate the +different lines.</para> + +<programlisting> +[Preview Image] +Caption=\s My Caption +Description=This is\na very long\ndescription. +</programlisting> +</informalexample> + +<para>Empty lines in configuration files are ignored, as are lines that +start with a hash mark (<quote>#</quote>). The hash mark can be used to add +comments to configuration files. It should be noted that when a &kde; +application updates a configuration file the comments are +<emphasis>not</emphasis> preserved.</para> + +<para>There can be multiple configuration files with the same name in the +<filename class="directory">share/config</filename> sub-directory of the +various &kde; directory trees. In this case the information of all these +configuration files is combined on a key-by-key basis. If the same key +within a certain group is defined in more than one place, the key value read +from the directory tree with the highest precedence will be used. +Configuration files under <filename +class="directory">$<envar>KDEHOME</envar></filename> always have the highest +precedence. If a key in a certain group is defined multiple times in a +single file, the value of the last entry is used.</para> + +<informalexample> +<para>If <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename> +contains: +<programlisting> +[MyGroup] +Color=red +Shape=circle +</programlisting> +and <filename>/etc/opt/kde3/share/config/foobar</filename> contains +<programlisting> +[MyGroup] +Color=blue +Position=10,10 +</programlisting> +the result will be: +<programlisting> +[MyGroup] +Color=red +Shape=circle +Position=10,10 +</programlisting> +</para> +</informalexample> + +<informalexample> +<para>If + <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename> + contains +<programlisting> +[MyGroup] +Color=red +Shape=circle +[MyGroup] +Color=green +</programlisting> +and <filename>/opt/kde_staff/share/config/foobar</filename> contains +<programlisting> +[MyGroup] +Color=purple +Position=20,20 +</programlisting> +and <filename>/etc/opt/kde3/share/config/foobar</filename> contains +<programlisting> +[MyGroup] +Color=blue +Position=10,10 +</programlisting> +the result will be: +<programlisting> +[MyGroup] +Color=green +Shape=circle +Position=20,20 +</programlisting> +</para> +</informalexample> + +<para>To prevent users being able to override default settings, +settings can be marked immutable. Settings can be made immutable +individually, per group or per file. An individual entry can be locked +down by adding <userinput>[$i]</userinput> behind the key, ⪚: +<programlisting> +Color[$i]=blue +</programlisting> +</para> +<para>A group of entries can be locked down by placing +<userinput>[$i]</userinput> behind the group name, ⪚: +<programlisting> +[MyGroup][$i] +</programlisting> +</para> +<para>To lock down the entire file, start the file with +<userinput>[$i]</userinput> on a single line, &ie;: +<programlisting> +[$i] +</programlisting> +</para> + +<informalexample> +<para>If + <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename> + contains: +<programlisting> +[MyGroup] +Color=red +Shape=circle +</programlisting> +and <filename>/etc/opt/kde3/share/config/foobar</filename> contains: +<programlisting> +[MyGroup][$i] +Color=blue +Position=10,10 +</programlisting> +the result will be: +<programlisting> +[MyGroup] +Color=blue +Position=10,10 +</programlisting> +</para> +</informalexample> + +<informalexample><para>If + <filename>$<envar>HOME</envar>/.kde/share/config/foobar</filename> + contains: +<programlisting> +[MyGroup] +Color=red +Shape=circle +</programlisting> +and <filename>/opt/kde_staff/share/config/foobar</filename> contains +<programlisting> +[MyGroup] +Color=purple +Shape=rectangle +</programlisting> +and <filename>/etc/opt/kde3/share/config/foobar</filename> contains +<programlisting> +[MyGroup][$i] +Color=blue +Position=10,10 +</programlisting> +the result will be +<programlisting> +[MyGroup] +Color=purple +Shape=rectangle +Position=10,10 +</programlisting> +</para> +</informalexample> + + +<para>So-called <quote>Shell Expansion</quote> can be used to provide more +dynamic default values. With shell expansion the value of a configuration +key can be constructed from the value of an environment variable or from the +output of a shell command. To enable shell expansion for a configuration +entry, the key must be followed by <token>[$e]</token>. Normally the +expanded form is written into the user's configuration file after first use. +To prevent that, it is recommend to lock the configuration entry down by +using <token>[$ie]</token>. The user can't change it then of course.</para> + +<informalexample> +<para>In the following example the value for the <varname>Host</varname> +entry is determined by the output of the <command>hostname</command> +program. This setting is also locked down to ensure that the value is always +determined dynamically.</para> + +<para>The value for the <varname>Email</varname> entry is determined by +filling in the values of the $<envar>USER</envar> and $<envar>HOST</envar> +environment variables. When <systemitem class="username">joe</systemitem> is +logged in on <systemitem class="systemname">joes_host</systemitem> this will +result in a value equal to <literal>joe@joes_host</literal>. The setting is +not locked down.</para> + +<programlisting> +[Mail Settings] +Host[$ie]=$(hostname) +Email[$e]=${USER}@${HOST} +</programlisting> +</informalexample> + +<para>Most configuration entries can be indexed with a language code. In +this case, the language that the user has selected for use on the desktop is +used to look up the key value. If the default language (American English) +has been selected or if there is no index that corresponds to the selected +language, the key entry without index is used.</para> + +<informalexample> +<para>In the following example the value of the <varname>Caption</varname> +entry depends on the language. If the user has selected French as language +(language code <literal>fr</literal>) the value of the entry will be +<quote>Ma Légende</quote>. In all other cases the value <quote>My +Caption</quote> will be used.</para> + +<programlisting> +[Preview Image] +Caption=My Caption +Caption[fr]=Ma Légende +</programlisting> +</informalexample> + +<informalexample> +<para>In this example the value of the <varname>Caption</varname> entry +depends on the language. If the user has selected French as language +(language code <literal>fr</literal>) the value of the entry will be +<quote>Ma Légende.</quote> In all other cases the value <quote>My +Caption</quote> will be used.</para> + +<programlisting> +[Preview Image] +Caption=My Caption +Caption[fr]=Ma Légende +</programlisting> +</informalexample> + +<para>In general the entries that can appear in a configuration file are not +documented. With &kde; 3.2 a start has been made to change this. In +<filename +class="directory">$<envar>KDEDIR</envar>/share/config.kcfg</filename>, files +can be found that provide a formal description of the possible entries in a +configuration file. These are used by the new &kde; Configuration Editor +when available.</para> + +<informalexample> +<para>Here is an example &XML; configuration file: +<programlisting> +<markup> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE kcfg SYSTEM "http://www.kde.org/standards/kcfg/1.0/kcfg.dtd"> +<kcfg> + <kcfgfile name="korganizerrc"/> + <group name="General"> + <entry type="Bool" key="Auto Save"> + <label>Enable automatic saving of calendar</label> + <default>true</default> + </entry> + <entry type="Int" key="Auto Save Interval"> + <default>10</default> + </entry> + </group> +</kcfg> +</markup> +</programlisting> +</para> +<para>It has the same effect as: +<programlisting> +[General] +Auto Save=false +Auto Save Interval=25 +</programlisting> +</para> +</informalexample> + +</sect1> + +<sect1 id="kde-startup-sequence"> +<title>&kde; Startup Sequence</title> + +<sect2 id="kdm"> +<title>&kdm;</title> + +<para>Always runs as <systemitem class="username">root</systemitem>! Uses +<filename>$<envar>KDEDIR</envar>/share/config/kdmrc</filename> and +<filename>/etc/X11/xdm/Xservers</filename>. The latter contains entries +like:</para> + +<programlisting> +:0 local /usr/X11R6/bin/X :0 vt07 +</programlisting> + +<para>Relevant startup files are also: </para> +<simplelist> +<member> +[X-*-Core] section in <filename>kdmrc</filename> +</member> +<member> +Setup - <filename>/etc/X11/xdm/Xsetup</filename> +</member> +<member> +User enters username & password +</member> +<member> +Startup - <filename>/etc/X11/xdm/Xstartup</filename> - prepare as root +</member> +<member> +Session - <filename>/etc/X11/xdm/Xsession</filename> - starts session as user +</member> +<member> += For a KDE session: <command>kde</command> or <command>startkde</command> +</member> +<member> += If present <filename>~/.xsession</filename> or <filename>~/.xinitrc</filename> +</member> +<member> +Reset - <filename>/etc/X11/xdm/Xreset</filename> - after session finished +</member> +</simplelist> + +</sect2> + +<sect2 id="startkde"> +<title>The &kde; Startup Script: <command>startkde</command></title> + +<para>The &kde; startup sequence starts with the +<filename>startkde</filename> script. In most cases this script gets called +from the display manager (&kdm;) once the user has been authenticated. Their +are two very important lines in the <filename>startkde</filename> +script:</para> + +<programlisting> +LD_BIND_NOW=true kdeinit +kcminit +knotify and kwrapper +ksmserver $KDEWM +</programlisting> + +<para>The first line starts the <command>kdeinit</command> master process. +The <command>kdeinit</command> master process is used to start all other +&kde; processes. It show up in the output of <command>ps +<option>aux</option></command> as <computeroutput>kdeinit: +Running...</computeroutput>. The arguments after <command>kdeinit</command> +are the names of additional processes to be started. The <token>+</token> +indicates that <command>kdeinit</command> needs to wait till the process has +finished. <command>kdeinit</command> also starts +<command>dcopserver</command>, <command>klauncher</command> and +<command>kded</command>.</para> + +<para>The second of the two lines asks <command>kdeinit</command> to start +the <command>ksmserver</command> session manager process. The session +manager determines the lifetime of the session. When this process exits, the +user is logged out.</para> + +</sect2> +</sect1> + +<sect1 id="background-processes"> +<title>Background Processes</title> + +<para>All &kde; background services are user-specific: unlike system daemons +they are not shared between users. As well as being unique per user they are +also unique per X-server display. The processes are:</para> + +<variablelist> +<varlistentry> +<term><command>dcopserver</command></term> +<listitem><para>Desktop communication</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>kded</command></term> +<listitem><para>Generic service daemon.</para> +<para>Triggers <link linkend="ksycoca">Sycoca</link> database updates when +needed</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>kcminit</command></term> +<listitem><para>Initialization service</para> +<para>See <xref linkend="kcminit"/> for more information.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>klauncher</command></term> +<listitem><para>Program launch (this is <emphasis>not</emphasis> the +<keycombo action="simul">&Alt;<keycap>F2</keycap> +</keycombo>dialog!)</para> +<para>See <xref linkend="klauncher"/> for more information.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>knotify</command></term> +<listitem><para>User notifications.</para> +<para>See <xref linkend="knotify"/> for more information.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>ksmserver</command></term> +<listitem><para>Session management</para> +<para>See <xref linkend="ksmserver"/> for more information.</para> +</listitem> +</varlistentry> + +</variablelist> + +<sect2 id="kdeinit"> +<title><command>kdeinit</command></title> +<para><command>kdeinit</command> is used to start all other &kde; +programs. <command>kdeinit</command> can start normal binary program files +as well as <command>kdeinit</command> loadable modules +(<acronym>KLM</acronym>s). <acronym>KLM</acronym>s work just like binary +program files but can be started more efficiently. <acronym>KLM</acronym>s +live in <filename +class="directory">$<envar>KDEDIR</envar>/lib/kde3</filename></para> + +<para>The drawback is that programs started this way appear as +<computeroutput><command>kdeinit</command></computeroutput> in the output of +<command>top</command> and <command>ps</command>. Use <command>top +<option>-c</option></command> or <command>ps <option>aux</option></command> +to see the actual program name:</para> + +<screen> +<prompt>%</prompt><userinput><command>ps <option>aux</option></command></userinput> +<computeroutput> +waba 23184 0.2 2.1 23428 11124 ? S 21:41 0:00 kdeinit: Running... +waba 23187 0.1 2.1 23200 11124 ? S 21:41 0:00 kdeinit: dcopserver --nosid +waba 23189 0.2 2.4 25136 12496 ? S 21:41 0:00 kdeinit: klauncher +waba 23192 0.7 2.8 25596 14772 ? S 21:41 0:00 kdeinit: kded +waba 23203 0.8 3.4 31516 17892 ? S 21:41 0:00 kdeinit: +knotify +</computeroutput> +</screen> + +<para><computeroutput>kdeinit: Running...</computeroutput> indicates the +master <command>kdeinit</command> process. The other processes listed are +programs started as <acronym>KLM</acronym>s.</para> + +<para>When <command>kdeinit</command> starts for the first time it will +launch <command>dcopserver</command>, <command>klauncher</command>, and +<command>kded</command>, as well as any additional programs specified on its +command line in the <command>startkde</command> script, normally +<command>kcminit</command> and <command>knotify</command>.</para> + +</sect2> + +<sect2 id="dcopserver"> +<title><command>dcopserver</command></title> + +<para><command>dcopserver</command> is a daemon which provides inter-process +communication (&DCOP;) facilities to all &kde; applications. The &DCOP; +facilities are accessible from the command shell via the +<command>dcop</command> command line tool. &DCOP; is essential for all &kde; +applications.</para> + +<para>Some related files:</para> + +<variablelist> +<varlistentry> +<term><filename>$<envar>HOME</envar>/.DCOPserver_$<envar>HOSTNAME</envar>_$<envar>DISPLAY</envar></filename></term> +<listitem><para>⪚ <filename>.DCOPserver_linux__0</filename>. Controlled by $<envar>DCOPAUTHORITY</envar></para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>/tmp/.ICE-unix/dcop<replaceable>pid</replaceable>-<replaceable>number</replaceable></filename></term> +<listitem><para>⪚ <filename>dcop7634-1069677856</filename>. This is +the file that the <filename>DCOPserver</filename> file above points to.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><filename>$<envar>HOME</envar>/.ICEauthority</filename></term> +<listitem><para>Authorization information controlled by +$<envar>ICEAUTHORITY</envar></para> +</listitem> +</varlistentry> +</variablelist> + +</sect2> + +<sect2 id="kcminit"> +<title>kcminit</title> + +<para><command>kcminit</command> executes initialization services during +startup. Initialization services are specified in the .desktop files of +applications or services via the <varname>X-KDE-Init</varname> line:</para> + +<programlisting> +[Desktop Entry] +Encoding=UTF-8 +Exec=kcmshell energy +Icon=energy_star +Type=Application +X-KDE-Library=energy +X-KDE-Init=energy +</programlisting> + +<para>Initialization services are typically used for initializing +hardware based on user-specified settings.</para> + +<para><userinput><command>kcminit +<option>--list</option></command></userinput> can be used to show all +initialization services and <userinput><command>kcminit +<replaceable>service</replaceable></command></userinput> can be used to +execute a single service explicitly. This can be useful when investigating +startup problems.</para> + +</sect2> + +<sect2 id="klauncher"> +<title><command>klauncher</command></title> + +<para><command>klauncher</command> is a daemon which is responsible for +service activation within &kde;. It operates in close connection with the +<command>kdeinit</command> master process to start new processes. &kde; +applications communicate with <command>klauncher</command> over &DCOP; in +order to start new applications or services.</para> + +<para>Best known from the error message: <computeroutput><errortext> +KLauncher could not be reached via DCOP </errortext></computeroutput> which +either indicates a serious problem with the <command>dcopserver</command> or +that <command>klauncher</command> crashed.</para> + +<para><command>klauncher</command> can be restarted by restarting +<command>kdeinit</command> from a console window. Make sure that +$<envar>HOME</envar>, $<envar>DISPLAY</envar> and the various +$<envar>KDEDIR(S)</envar> are set correctly when doing so!</para> + +</sect2> + +<sect2 id="knotify"> +<title><command>knotify</command></title> + +<para>The primary task of <command>knotify</command> is to relay sound +notifications to the sound server, it also provides alternative notification +methods.</para> + +</sect2> + + +</sect1> + +<sect1 id="ksmserver"> +<title>KSMServer</title> + +<para><command>ksmserver</command> is &kde;'s session manager. On startup +the session manager launches auto-start applications and restores +applications from the previous session. The applications to auto-start are +indicated by <literal role="extension">.desktop</literal> files in the +<filename +class="directory">$<envar>KDEDIR</envar>/share/autostart</filename> +directory. Whether or not to auto-start an application can be made +conditional upon some configuration entry determined by the +<varname>X-KDE-autostart-condition</varname> entry in the <literal +role="extension">.desktop</literal> file.</para> + +<informalexample> +<para>The <filename>ktip.desktop</filename> file for example +contains:</para> + +<programlisting> +X-KDE-autostart-condition=ktiprc:TipOfDay:RunOnStart:true +</programlisting> + +<para>This means that the <filename>ktiprc</filename> configuration +file is checked for a <varname>RunOnStart</varname> entry in the +<varname>[TipOfDay]</varname> section. If no such entry is found, +<literal>true</literal> is assumed, which means that +<application>ktip</application> is one of the applications that is +auto-started by default.</para> +</informalexample> + +<para>Some of the applications auto-started by <command>ksmserver</command> +are:</para> + +<variablelist> + +<varlistentry> +<term><command>kdesktop</command></term> +<listitem><para>The &kde; desktop</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>&kicker;</command></term> +<listitem><para>The &kde; panel</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>ktip</command></term> +<listitem><para>A tip of the day program</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>kwrited</command></term> +<listitem><para>A utility to receive system messages sent to the user</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>&klipper;</term> +<listitem><para>A clipboard utility that docks in the panel</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><command>kalarm</command></term> +<listitem><para>A utility that warns about upcoming events and appointments</para> +</listitem> + +</varlistentry> +</variablelist> + +<para><command>kdesktop</command> in its turn automatically starts +applications stored in <filename +class="directory">$<envar>KDEHOME</envar>/Autostart</filename>. <command>kdesktop</command> +will automatically open any files stored in this directory including +documents, binary files or applications in the form of <literal +role="extension">.desktop</literal> files.</para> + +<para>The &kde; session manager also restores one of the previous +sessions. A session contains a collection of applications as well as +application-specific information that reflects the state of the applications +at the time the session was saved. Sessions are stored in the +<filename>ksmserverrc</filename> configuration file which contains +references to application-specific state information. The +application-specific state information is saved in <filename +class="directory">$<envar>KDEHOME</envar>/share/config/session</filename>. +The state information of &kwin; contains the location of the application +windows of all the other applications in the session. +</para> + +</sect1> + +<sect1 id="environment-variables"> +<title>Environment variables</title> + +<para>Some important environment variables used by &kde;:</para> + +<variablelist> + +<varlistentry> +<term>$<envar>KDEDIR</envar></term> +<listitem><para>Has to be set if +<envar>KDEDIRS</envar> is not set and has to point to the root of the +&kde; installation tree. Allows &kde; to find its data like icons, +menus and libraries.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDEDIRS</envar></term> +<listitem><para>Overrides <envar>KDEDIR</envar> and allows you to specify +multiple directories where &kde; searches for its data. Useful if you want +or have to install some programs to a different prefix than the rest of +&kde;.</para> +</listitem> +</varlistentry> + +<varlistentry><term><envar>$KDEHOME</envar></term><listitem><para>If +not set, &kde; uses <filename class="directory">~/.kde</filename> as +the directory where personal data is stored.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDEROOTHOME</envar></term><listitem><para>If +not set, &kde; uses <filename class="directory">~root/.kde</filename> +as the directory for <systemitem class="username">root</systemitem>'s +personal data. Was introduced to prevent &kde; from accidently +overwriting user data with root permissions when the user runs a &kde; +program after switching with <command>su</command> to <systemitem +class="username">root</systemitem>.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDEWM</envar></term><listitem><para>If the +<envar>KDEWM</envar> environment variable has been set, then it will +be used as &kde;'s window manager within the +<command>startkde</command> script instead of &kwin;.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_LANG</envar></term><listitem><para>Overrides +the &kde; language configuration, ⪚ <userinput>KDE_LANG=fr kprogram +&</userinput> starts a program with French translation if the +necessary files are installed.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_MULTIHEAD</envar></term><listitem><para>Set +this variable to <literal>true</literal> to indicate that &kde; is running +on a multi-head system.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_FORK_SLAVES</envar></term> +<listitem><para>(Since &kde; 3.2.3) Set this variable to spawn +<acronym>KIO</acronym>-slaves directly from the application process +itself. By default <acronym>KIO</acronym>-slaves are spawned using +<command>klauncher</command>/<command>kdeinit</command>. This option is +useful if the <acronym>KIO</acronym>-slave should run in the same +environment as the application. This can be the case with +<application>Clearcase</application>.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_HOME_READONLY</envar></term> +<listitem><para>Set this variable to indicate that your home directory is +mounted as read-only.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_NO_IPV6</envar></term><listitem><para> +(Since &kde; 3.2.3) - Set this variable to disable <acronym>IPv6</acronym> +support and <acronym>IPv6</acronym> <acronym>DNS</acronym> +lookups.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_IS_PRELINKED</envar></term><listitem><para> +(Since &kde; 3.2) - Set this variable to indicate that you have prelinked +your &kde; binaries and libraries. This will turn off +<command>kdeinit</command>.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_UTF8_FILENAMES</envar></term><listitem><para>If +this environment variable is set, &kde; assumes all filenames are in +<acronym>UTF-8</acronym> encoding regardless of the current C +locale.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDE_FULL_SESSION</envar></term><listitem><para> +(Since &kde; 3.2) Automatically set to true by &kde; startup, it is used +by ⪚ &konqueror; to know if it should consider remaining in memory +for future re-use when being closed. If not set, &konqueror; will exit +after being closed (⪚ &kdesu; does that, it's also useful for +debugging).</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDESYCOCA</envar></term><listitem><para>Allows +you to specify the path and the name of the generated &kde; system +configuration cache file.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDETMP</envar></term><listitem><para>Allows +to specify another path than <filename +class="directory">/tmp</filename> where &kde; stores its temporary +files.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>KDEVARTMP</envar></term><listitem><para>Allows +to specify another path than <filename +class="directory">/var/tmp</filename> where &kde; stores its variable +files.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>XDG_DATA_HOME</envar></term><listitem><para> +(Since &kde; 3.2) Defines the base directory relative to which user-specific +data files should be stored. Default is <filename +class="directory">$<envar>HOME</envar>/.local/share</filename></para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>XDG_DATA_DIRS</envar></term><listitem><para> +(Since &kde; 3.2) Defines the preference-ordered set of base directories to +search for data files in addition to the <filename +class="directory">$<envar>XDG_DATA_HOME</envar></filename> base +directory. Default is +<literal>/usr/local/share/:/usr/share/</literal></para> + +<para>&kde; adds locations from $<envar>KDEDIRS</envar> and profiles +as well. Used for <literal role="extension">.desktop</literal> and +<literal role="extension">.directory</literal> menu files. <literal +role="extension">.desktop</literal> files under <filename +class="directory">$<envar>XDG_DATA_DIRS</envar>/applications</filename>. +<literal +role="extension">.directory</literal> files under +$XDG_DATA_DIRS/desktop-directories +</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>XDG_CONFIG_HOME</envar></term><listitem><para> +(&kde; 3.2) - Defines the base directory relative to which user +specific configuration files should be stored. Default is +<filename class="directory">$<envar>HOME</envar>/.config</filename>.</para> +</listitem> +</varlistentry> + +<varlistentry><term>$<envar>XDG_CONFIG_DIRS</envar></term><listitem><para> +(&kde; 3.2) - Defines the preference-ordered set of base directories +to search for configuration files in addition to the $<envar>XDG_CONFIG_HOME</envar> +base directory. The default is <filename class="directory">/etc/xdg</filename> &kde; adds locations from +$<envar>KDEDIRS</envar> and profiles as well. Used by <literal role="extension">.menu</literal> descriptions in +<filename class="directory">$<envar>XDG_CONFIG_DIRS</envar>/menus</filename>. +</para> +</listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="the-kdeinit-mystery"> +<title>The kdeinit Mystery</title> + +<!-- FIXME: Add more words. Fix markup --> + +<para><command>kdeinit</command> is used to start all other &kde; +programs. <command>kdeinit</command> can start normal binary program f iles +as well as <command>kdeinit</command> loadable modules +(<acronym>KLM</acronym>s). <acronym>KLM</acronym>s work just like binary +program files but can be started more efficiently. <acronym>KLM</acronym>s +live in <filename +class="directory">$<envar>KDEDIR</envar>/lib/kde3</filename></para> + +<para>The drawback is that programs started this way appear as +<computeroutput><command>kdeinit</command></computeroutput> in the +output of <command>top</command> and <command>ps</command>. Use +<command>top <option>-c</option></command> or <command>ps +<option>aux</option></command> to see the actual program name:</para> + +<screen> +<prompt>%</prompt> <userinput><command>ps aux | grep bastian</command></userinput> +<computeroutput> +bastian 26061 0.0 2.2 24284 11492 ? S 21:27 0:00 kdeinit: Running... +bastian 26064 0.0 2.2 24036 11524 ? S 21:27 0:00 kdeinit: dcopserver +bastian 26066 0.1 2.5 26056 12988 ? S 21:27 0:00 kdeinit: klauncher +bastian 26069 0.4 3.2 27356 16744 ? S 21:27 0:00 kdeinit: kded +bastian 26161 0.2 2.7 25344 14096 ? S 21:27 0:00 kdeinit: ksmserver +bastian 26179 1.1 3.4 29716 17812 ? S 21:27 0:00 kdeinit: kicker +bastian 26192 0.4 3.0 26776 15452 ? S 21:27 0:00 kdeinit: klipper +bastian 26195 1.0 3.5 29200 18368 ? S 21:27 0:00 kdeinit: kdesktop +</computeroutput> +</screen> +<para>As you might have noticed, this has another side effect, making it +difficult to kill a process that is causing trouble:</para> + +<screen><prompt>%</prompt> <userinput><command>killall kdesktop</command></userinput> +<computeroutput>kdesktop: no process killed</computeroutput></screen> + +<para>You might be tempted to try <userinput><command>killall +kdeinit</command></userinput>, but killing all kdeinit processes will have +the effect of shutting down all of &kde;. In effect, total +destruction!</para> + +<para>There are two simple solutions to this:</para> + +<screen><prompt>%</prompt> <userinput><command>kdekillall kdesktop</command></userinput> +or good old +<prompt>%</prompt> <userinput><command>kill 26195</command></userinput></screen> +<para><command>kdekillall</command> is part of the &kde; <acronym>SDK</acronym> +package.</para> + +</sect1> + +</chapter> + +<chapter id="customizing-kde"> +<title>Customizing &kde;</title> + + +<sect1 id="desktop-icons"> +<title>Desktop Icons</title> + +<para>&kde; uses several types of icons:</para> +<itemizedlist> +<listitem><para>Documents</para> +</listitem> +<listitem><para>Links to Websites (using <literal role="extension">.desktop</literal> file)</para> +</listitem> +<listitem><para>Links to Applications (using <literal role="extension">.desktop</literal> file)</para> +</listitem> +<listitem><para>Devices - Disks, Partitions & Peripherals: +<itemizedlist> +<listitem><para>Explicit using <literal role="extension">.desktop</literal> file</para> +</listitem> +<listitem><para>Automatic via devices:// io-slave</para> +</listitem> +</itemizedlist> +</para> +</listitem> +<listitem><para>Vendor-specific (⪚ &SuSE;'s My Computer)</para> +</listitem> +</itemizedlist> + +<sect2 id="desktop-icons-websites"> +<title>Websites</title> +<para> +Links to Websites using <literal role="extension">.desktop</literal> +file: <menuchoice><guimenu>Create +New</guimenu><guisubmenu>File</guisubmenu><guimenuitem>Link to +Location (URL)</guimenuitem></menuchoice>. Change Icon using +<guilabel>Properties</guilabel> dialogs. The resulting <literal +role="extension">.desktop</literal> file: +<programlisting> +[Desktop Entry] +Encoding=UTF-8 +Icon=/opt/kde3/share/apps/kdesktop/pics/ksslogo.png +Type=Link +URL=http://www.kde.org/ +</programlisting> +</para> +</sect2> + +<sect2 id="desktop-icons-applications"> +<title>Applications</title> + +<para>Links to Applications using <literal +role="extension">.desktop</literal> file: <menuchoice><guimenu>Create +New</guimenu><guisubmenu>File</guisubmenu><guimenuitem>Link to +Application</guimenuitem></menuchoice>. You must provide details +yourself. Drag from &kde; Menu: Either copy or link (creates symlink), +much easier</para> + +<!-- Perhaps legacy and translated should be the other way around, but --> +<!-- this is how it appears in Waldo's presentation. Need to check --> +<!-- this --> + +<programlisting> +[Desktop Entry]<co id="boilerplate"/> +Encoding=UTF-8 +GenericName=IRC Client<co id="generic-desc"/> +GenericName[af]=Irc Kliët +GenericName[de]=IRC Programm +... +GenericName[zu]=Umthengi we IRC<co id="legacy"/> +SwallowExec=<co id="translated"/> +Name=KSirc +Name[af]=Ksirc +Name[de]=KSirc +... +</programlisting> + +<calloutlist> +<callout arearefs="boilerplate"><para>Boiler plate</para> +</callout> +<callout arearefs="generic-desc"><para>Translated generic description, not used on desktop</para> +</callout> +<callout arearefs="legacy"><para>Legacy, can be removed</para> +</callout> +<callout arearefs="translated"><para>Translated name as it appears on desktop</para> +</callout> +</calloutlist> + +<para>Desktop Icons</para> +<programlisting> +... +Name[zu]=Ksirc +MimeType=<co id="co-mimetype"/> +Exec=ksirc %i %m<co id="co-exec"/> +Icon=ksirc<co id="co-icon"/> +TerminalOptions=<co id="co-terminaloptions"/> +Path=<co id="co-path"/> +Type=Application<co id="co-type"/> +Terminal=0<co id="co-terminal"/> +X-KDE-StartupNotify=true<co id="co-x-kde-startupnotify"/> +X-DCOP-ServiceType=Multi<co id="co-x-dcop-servicetype"/> +Categories=Qt;KDE;Network<co id="co-categories"/> +</programlisting> + +<calloutlist> +<callout arearefs="co-mimetype"><para>Supported &MIME; types, not used on +desktop</para> +</callout> +<callout arearefs="co-exec"><para>The command line to execute</para> +</callout> +<callout arearefs="co-icon"><para>The icon, from icon theme or full path</para> +</callout> +<callout arearefs="co-terminaloptions"><para>Only used if terminal is +needed</para> +</callout> +<callout arearefs="co-path"><para>Working directory for command</para> +</callout> +<callout arearefs="co-type"><para>More boiler plate</para> +</callout> +<callout arearefs="co-terminal"><para>Use true if terminal is needed, +text application</para> +</callout> +<callout arearefs="co-x-kde-startupnotify"><para>Show bouncy cursor, +disable if it doesn't work.</para> +</callout> +<callout arearefs="co-x-dcop-servicetype"><para>Has app started ok? +Remove if it doesn't work</para> +</callout> +<callout arearefs="co-categories"><para>Categories for &kde; Menu, not +used on desktop</para> +</callout> +</calloutlist> + + + +</sect2> + +<sect2 id="desktop-icons-exec"> +<title>The <varname>Exec</varname> option in <literal +role="extension">.desktop</literal> files</title> + +<para>Following the command, you can have several place holders which will +be replaced with the actual values when the actual program is run: +<variablelist> +<varlistentry> +<term>%f</term> <listitem><para>A single file name; used when dropping +file on icon, or with file associations.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%F</term> +<listitem><para>A list of files; use for applications that can +open several local files at once.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%u</term> +<listitem><para>A single &URL;: if the app can +handle ⪚ &FTP; or &HTTP; &URL;s itself, otherwise &kde;.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%U</term> +<listitem><para>A list of +&URL;s; will download the file first and pass a local file to the app +(!!)</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%d</term> +<listitem><para>The folder of the file to open; useful if app needs to +have file in current working directory.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%D</term> +<listitem><para>A list of folders, not very practical.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%i</term> +<listitem><para>The icon; <option>--icon</option> option; &kde; app +will use icon from <varname>Icon</varname>= line in taskbar.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%m</term> +<listitem><para>The mini-icon; legacy.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>%c</term> +<listitem><para>The caption; <option>--caption</option> option; &kde; +app will use name from <varname>Name</varname>= line in +taskbar.</para> +</listitem> +</varlistentry> + +</variablelist> +</para> + +<informalexample> +<para>Examples: +<segmentedlist> +<segtitle><varname>Exec</varname> line</segtitle> +<segtitle>Command executed</segtitle> +<seglistitem><seg>ksirc %i</seg><seg><command>ksirc --icon ksirc</command></seg> +</seglistitem> +<seglistitem><seg>cd %d; kedit $(basename %f)</seg><seg><command>cd /tmp; kedit file.txt</command></seg> +</seglistitem> +</segmentedlist> +</para> +</informalexample> + +<!--Dont' know what this refers to: --> +<!--See What's This (Shift-F1) in Properties Dialog--> + +</sect2> + +<sect2 id="desktop-icons-devices"> +<title>Devices</title> +<para> +Links to Devices using <literal role="extension">.desktop</literal> file: +o Create New -> Device + +</para> +</sect2> + +<sect2 id="where-to-define"> +<title>Where to Define</title> + +<para>Many places to define Desktop Icons: +<itemizedlist> + +<listitem><para><filename class="directory">~/Desktop</filename>: +copied from <filename +class="directory">/etc/skel/Desktop</filename></para></listitem> + +<listitem><para><filename +class="directory">$<envar>KDEDIR</envar>/apps/kdesktop/Desktop</filename> +(merged)</para></listitem> + +<listitem><para><filename +class="directory">$<envar>KDEDIR</envar>/apps/kdesktop/DesktopLinks</filename> +(copied)</para></listitem> + +<listitem><para>Device Icons (dynamically +merged)</para></listitem> + +<listitem><para>Distribution Specific SUSE Linux copies certain icons +in startkde.theme from <filename +class="directory">/opt/kde3/share/config/SuSE/default/</filename></para></listitem> + +</itemizedlist> +</para> +</sect2> +</sect1> + +<sect1 id="kde-menu"> +<title>&kde; Menu</title> + +<sect2 id="how-it-works"> +<title>How it Works</title> + +<para>In &kde; 3.2 a common menu format is introduced at +<ulink +url="http://freedesktop.org/Standards/menu-spec/">http://freedesktop.org/Standards/menu-spec/</ulink></para> +<para>Before &kde; 3.2: +<itemizedlist> + +<listitem><para>Directory structure under <filename +class="directory">share/applnk</filename></para></listitem> + +<listitem><para>Directory structure represents menu +structure</para></listitem> + +<listitem><para>Each <literal role="extension">.desktop</literal> file +represents a single application</para></listitem> + +</itemizedlist> +</para> + +<para>It was difficult to rearrange the structure in &kde; 3.2 so the +new menu format: +<itemizedlist> +<listitem><para>Defines structure in a single .menu file</para></listitem> +<listitem><para>Is based on categories</para></listitem> +<listitem><para>is shared between <acronym>GNOME</acronym> and &kde;</para></listitem> +<listitem><para>Supports applnk style menus as well</para></listitem> +</itemizedlist> +</para> + +<informalexample> +<para>Example from <filename>applications.menu</filename>: +<programlisting> +<markup> + <Menu> + <Name>Office</Name> + <Directory>suse-office.directory</Directory> + <Include> + <Filename>Acrobat Reader.desktop</Filename> + <Filename>kde-kpresenter.desktop</Filename> + <Filename>kde-kword.desktop</Filename> + </Include> + <Menu> +</markup> +</programlisting> +</para> +<para>Menu entry with 3 applications: +<itemizedlist> + +<listitem><para><filename>/usr/share/applications/Acrobat +Reader.desktop</filename></para></listitem> + +<listitem><para><filename>/opt/kde3/share/applications/kde/kpresenter.desktop</filename></para></listitem> + +<listitem><para><filename>/opt/kde3/share/applications/kde/kword.desktop</filename></para></listitem> + +</itemizedlist> +</para> +</informalexample> +</sect2> + +<sect2 id="stored-where"> +<title>Stored Where?</title> + +<para><literal role="extension">.menu</literal> files describing the +menu structure. The files are stored in <filename +class="directory">$<envar>KDEDIR</envar>/etc/xdg/menus</filename> and +<filename class="directory">/etc/xdg/menus</filename>. These store the +system-wide menu structure and are controlled by +$<envar>XDG_CONFIG_DIRS</envar>. <filename +class="directory">$<envar>HOME</envar>/.config/menus</filename> stores +user-specific changes to the menu structure and is controlled by +$<envar>XDG_CONFIG_HOME</envar>. For more information, see <ulink +url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink>.</para> + +<para><literal role="extension">.desktop</literal> files describe the +applications and are stored in: <filename +class="directory">$<envar>KDEDIR</envar>/share/applications</filename>, +<filename class="directory">/usr/share/applications</filename>, +<filename +class="directory">/usr/local/share/applications</filename>. These are +the system-wide application <literal +role="extension">.desktop</literal> files which are controlled by +$<envar>XDG_DATA_DIRS</envar>.</para> + +<para><filename +class="directory">$<envar>HOME</envar>/.local/applications</filename> +contains user-specific <literal role="extension">.desktop</literal> +files and user-specific changes. It is controlled by +$<envar>XDG_DATA_HOME</envar>. For more information, see <ulink +url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink></para> + + +<para><literal role="extension">.directory</literal> files describing +the sub-menus are stored in: <filename +class="directory">$<envar>KDEDIR</envar>/share/desktop-directories</filename>, +<filename class="directory">/usr/share/desktop-directories</filename>, <filename +class="directory">/usr/local/share/desktop-directories</filename>. +These are the system-wide menu <literal +role="extension">.directory</literal> files, controlled by +$<envar>XDG_DATA_DIRS</envar>. The user-specific changes are stored in <filename class="directory">$<envar>HOME</envar>/.local/desktop-directories</filename>. +These are controlled by $<envar>XDG_DATA_HOME</envar>. For more +information, see <ulink url="http://www.freedesktop.org/Standards/basedir-spec">http://www.freedesktop.org/Standards/basedir-spec</ulink></para> + +<informalexample> +<para>Example from <filename>applications.menu</filename>: +<programlisting> +<markup> + <Menu> + <Name>Art</Name> + <Directory>suse-edutainment-art.directory</Directory> + <Include> + <Category>X-SuSE-Art</Category> + </Include> + </Menu> +</markup> +</programlisting> +</para> + +<para><literal>Art</literal> is the internal name for this +menu. <filename>suse-edutainment-art.directory</filename> defines the +name and icon for this menu, and the menu includes all applications +that have <literal>X-SuSE-Art</literal> listed as a category, ⪚: +<programlisting> +Categories=Qt;KDE;Education;X-SuSE-Art +</programlisting></para> + +<para><filename>suse-edutainment-art.directory</filename> defines the +name and icon for this menu: +<programlisting> +[Desktop Entry] +Name=Art and Culture +Icon=kcmsystem +</programlisting> +</para> +</informalexample> +</sect2> + +<sect2 id="common-pitfalls"> +<title>Common Pitfalls</title> + +<para>Applications <emphasis>not</emphasis> in the menu do +<emphasis>not</emphasis> exist with regard to other applications or +file associations: If you remove an application from the menu, &kde; assumes you don't want to use it.</para> + +<para>When applications are unwanted in the menu, either place them in +<filename>.hidden</filename> menu or a dedicated menu with +<programlisting> +NoDisplay=true +</programlisting> in the <literal +role="extension">.directory</literal> file</para> +</sect2> + +<sect2 id="essential-menus"> +<title>Essential Menus</title> + +<para><filename +class="directory">$<envar>KDEDIR</envar>/etc/xdg/menus/applications-merged/</filename> +contains <filename>kde-essential.menu</filename> which includes some +essential menus that are normally not shown in the &kde; menu itself: +<itemizedlist> +<listitem><para>Control Center has a hidden Settings menu whose +contents are defined by <filename>kde-settings.menu</filename> and +whose icon and name are defined by <filename>kde-settings.directory</filename></para> +</listitem> +<listitem><para>Info Center has a hidden Information menu whose +contents are defined by <filename>kde-information.menu</filename> and +whose icon and name are defined by <filename>kde-information.directory</filename>.</para> +</listitem> + +<listitem><para>Screensavers contains a hidden System/Screensavers menu, +whose contents are defined by +<filename>kde-screensavers.menu</filename> and whose icon and name +are defined by +<filename>kde-system-screensavers.directory</filename>. +<filename>$<envar>KDEDIR</envar>/share/desktop-directories/kde-system-screensavers.directory</filename> +contains: +<programlisting> +NoDisplay=true +</programlisting> +</para> +</listitem> +</itemizedlist></para> +</sect2> + +<sect2 id="old-style-menus"> +<title>Old-Style Menus</title> + +<para>&kde; continues to support old-style menus that are defined by +the directory structures in <filename +class="directory">$<envar>KDEDIR</envar>/share/applnk</filename> +(system wide) and <filename +class="directory">$<envar>HOME</envar>/.kde/share/applnk</filename> +(user specific). This is observed unless the <literal role="extension">.desktop</literal> file has a <varname>Categories</varname>= line. In that case the categories determine the location in the menu.</para> +</sect2> + +<sect2 id="ksycoca"> +<title><application>KSycoca</application></title> +<para><application>KSycoca</application> caches menu structure and +information about all available applications. You can rebuild the +database with +<userinput><command>kbuildsycoca</command></userinput>. The database +which is built lives in <filename +class="directory">/var/tmp/kdecache-${<envar>USER</envar>}/ksycoca</filename>. +It is automatically updated by <application>KDED</application>, +checked during &kde; login, and <application>KDED</application> +watches for changes while logged in.</para> + +<para>To disable watching for changes (since it may hurt over NFS) add +the following to <filename>kdedrc</filename>: +<programlisting> +[General] +CheckSycoca=false +</programlisting> +</para> + +<para>To force regeneration, run <userinput><command>touch $<envar>KDEDIR</envar>/share/services/update_ksycoca</command></userinput>.</para> + +</sect2> + +<sect2 id="kmenuedit"> +<title>&kmenuedit;</title> + +<para>&kmenuedit; is aimed at a single user setup. Changes to menu +structure are saved to +<filename>~/.config/menus/applications-kmenuedit.menu</filename>, +changes to applications are saved in <filename +class="directory">~/.local/share/applications/</filename> and changes +to sub-menus (icon, name) are saved in <filename +class="directory">~/.local/share/desktop-directories/</filename>. The +KIOSK Admin Tool uses &kmenuedit; and copies the above changes to +profile- or system-wide locations. +</para> + +</sect2> + +</sect1> + +<!-- This section might be redundant. If it isn't, it needs some screenies --> +<sect1 id="kde-panel"> +<title>&kde; Panel</title> + +<para>The &kde; panel is also known as &kicker;. It is modular and +consists of the following components: +<itemizedlist> +<listitem><para>Applets</para></listitem> +<listitem><para>Application buttons</para></listitem> +<listitem><para>Special Buttons</para></listitem> +</itemizedlist> +</para> + +<para>By default, the panel contains the following applets: +<itemizedlist> +<listitem><para>Pager - shows the virtual desktops</para></listitem> +<listitem><para>Taskbar</para></listitem> +<listitem><para>System Tray</para></listitem> +<listitem><para>Clock</para></listitem> +</itemizedlist> +and the following special buttons: +<itemizedlist> +<listitem><para>&kde; menu</para></listitem> +<listitem><para>Desktop Button</para></listitem> +</itemizedlist> +</para> + +<para>Various application buttons are also added, space permitting: +<itemizedlist> +<listitem><para>Home Button</para></listitem> +<listitem><para>Browser Button</para></listitem> +<listitem><para>KMail Button</para></listitem> +</itemizedlist> +</para> +</sect1> + +<sect1 id="file-associations"> +<title>File Associations</title> + +<para>File associations associate a file type with an application or +applications. The type of a file is established by determining its +&MIME; type. &MIME; types known by &kde; are stored in <filename +class="directory">$<envar>KDEDIR</envar>/share/mimelnk</filename> and +each application's <literal role="extension">.desktop</literal> file +contains a list of &MIME; types supported by that application.</para> + +<informalexample> +<para><filename>kview.desktop</filename>: +<programlisting> +MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg; +image/x-bmp;image/png;image/x-ico;image/x-portable-bitmap; +image/x-portable-pixmap;image/x-portable-greymap; +image/tiff;image/jp2 +</programlisting> +</para> + +<para><filename>kuickshow.desktop</filename>: +<programlisting> +MimeType=image/gif;image/x-xpm;image/x-xbm;image/jpeg; +image/png;image/tiff;image/x-bmp;image/x-psd;image/x-eim; +image/x-portable-bitmap;image/x-portable-pixmap; +image/x-portable-greymap +</programlisting> +</para> + +<para>Both can open image/gif Which one is used to open a <literal role="extension">.gif</literal> file?</para> + +<para>The application with highest +preference!. <filename>kview.desktop</filename> contains +<programlisting> +InitialPreference=3 +</programlisting> +whereas <filename>kuickshow.desktop</filename> contains +<programlisting> +InitialPreference=6 +</programlisting> +Therefore, &kuickshow; will be used to open <literal +role="extension">.gif</literal> files. +</para> + +<para>How can we make &kview; default?</para> + +<para>A user can change file association in the +&kcontrolcenter;. These changes are stored in +<filename>$<envar>HOME</envar>/.kde/share/config/profilerc</filename>. +To use the same settings for multiple users, store these settings in +user profile directory or the global &kde; config directory to use as +default for multiple users.</para> + +</informalexample> + +</sect1> + +</chapter> + +<chapter id="locking-down-kde"> +<title>Locking Down &kde;</title> + +<sect1 id="how-it-works-the-basics"> +<title>How It Works - The Basics</title> + +<para>&kde;'s lock down features are centered around the following +options:</para> + +<itemizedlist> +<listitem><para><link linkend="immutable-configuration-options">Make +configuration options immutable</link></para></listitem> +<listitem><para><link linkend="action-restrictions">Restriction of specific +actions</link></para></listitem> +<listitem><para><link linkend="url-restrictions">Restrict access to certain +&URL;s</link></para></listitem> +<listitem><para><link linkend="configuration-modules">Restrict access to +certain configuration modules</link></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="immutable-configuration-options"> +<title>Immutable Configuration Options</title> +<subtitle>Locking Down &kde;</subtitle> + +<para>Immutable options allow system administrator to provide default +settings that can not be changed by the user.</para> + +<para>Pre-existing configuration options of the user will be ignored once a +configuration option is made immutable.</para> + +<para>Options can be controlled either on a per entry basis, per group of +entries or on a file by file basis.</para> + +<para>If a file or group is immutable, all configuration options for that +file or group are immutable, even those options for which the system +administrator has no default provided.</para> + +<note><para>The support in applications for immutable options may vary from +application to application. Although the user will not be able to make +permanent changes to immutable configuration options, the user may still be +presented with an user interface option to make such change.</para></note> + +</sect1> + +<sect1 id="action-restrictions"> +<title>Action Restrictions</title> + +<para>&kde; applications are built around the action-concept. Actions can be +activated in various ways, typically via the menu-bar, one of the toolbars +or a keyboard shortcut. <action>Save Document</action> is an example of an +action. If you know the internal action name it is possible to restrict an +action. When an action is restricted it will no longer appear in the +menu-bar or toolbar. The internal name for the <action>Save +Document</action> action is <option>action/file_save</option>. The lock +down framework also provides a set of more abstract restrictions which can +be used to disable functionality not covered by a single action. An example +is the <option>shell_access</option> restriction which disables all +functionality that would offer the user access to a &UNIX; shell.</para> + +<example> +<title>Restrict User Access to Shells</title> + +<para>In order to prevent the user access to a command shell we can restrict +the <option>shell_access</option> action by adding the following to +<filename>kdeglobals</filename>: +</para> + +<screen>[KDE Action Restrictions] +shell_access=false</screen> + +<para>Since this affects the &kde; menu and the available applications, we +must force an update of the sycoca database:</para> + +<screen><userinput><command>touch</command> <filename>$<envar>KDEDIR</envar>/share/services/update_ksycoca</filename></userinput></screen> + +<para>Now re-login to &kde; and check the following points:</para> + +<itemizedlist> +<listitem><para>The &kmenu;</para></listitem> +<listitem><para>In &konqueror;, +<menuchoice><guimenu>Tools</guimenu><guimenuitem>Open +Terminal</guimenuitem></menuchoice></para></listitem> +<listitem><para>The <keycombo +action="simul">&Alt;<keycap>F2</keycap></keycombo> run +command</para></listitem> +</itemizedlist> +</example> +<para>Full documentation about available actions can be found on <ulink +url="http://www.kde.org/areas/sysadmin/">http://www.kde.org/areas/sysadmin/</ulink>.</para> + +<para>A few of the more interesting actions are listed below:</para> + +<variablelist> +<varlistentry> +<term><option>action/options_configure</option></term> +<listitem><para>The <guimenuitem>Configure</guimenuitem> option form the +<guimenu>Settings</guimenu> menu</para></listitem> +</varlistentry> +<varlistentry> +<term><option>action/help_report_bug</option></term> +<listitem><para>The <guimenuitem>Report Bug</guimenuitem> option from the +<guimenu>Help</guimenu> menu.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>action/kdesktop_rmb</option></term> +<listitem><para>&RMB; mouse button menu on the desktop.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>action/kicker_rmb</option></term> +<listitem><para>&RMB; mouse button menu on the panel.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>user/root</option></term> +<listitem><para>Hide all actions or applications that require <systemitem +class="username">root</systemitem> access.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>shell_access</option></term> +<listitem><para>Hides all actions or applications that provide shell +access.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>print/system</option></term> +<listitem><para>Disables the option to select the printing system +(backend).</para></listitem> +</varlistentry> +<varlistentry> +<term><option>lock_screen</option></term> +<listitem><para>Whether the user will be able to lock the +screen</para></listitem> +</varlistentry> +<varlistentry> +<term><option>start_new_session</option></term> +<listitem><para>Whether the user may start a second X session (see also +&kdm;)</para></listitem> +</varlistentry> +<varlistentry> +<term><option>opengl_screensavers</option></term> +<listitem><para>Whether OpenGL screensavers are allowed to be +used.</para></listitem> +</varlistentry> +<varlistentry> +<term><option>manipulatescreen_screensavers</option></term> +<listitem><para>Permit screensavers that do not hide the entire +screen</para></listitem> +</varlistentry> +</variablelist> + +</sect1> + +<sect1 id="url-restrictions"> +<title>&URL; Restrictions</title> + +<para>There are three types of restrictions that can be applied to +&URL;s:</para> + +<variablelist> +<varlistentry> +<term>list</term> +<listitem><para>To control whether a directory listing is +allowed.</para></listitem> +</varlistentry> +<varlistentry> +<term>open</term> +<listitem><para>To control whether certain &URL;s can be +opened</para></listitem> +</varlistentry> +<varlistentry> +<term>Redirect</term> +<listitem><para>To control whether one &URL; can open another &URL;, either +automatically or via a hyperlink.</para></listitem> +</varlistentry> +</variablelist> + +<para>Rules are checked in the order in which they are defined. The last +rule that is applicable to a &URL; defines whether the &URL; may be +accessed.</para> + +<para>The following rules disable opening http and https &URL;s outside +<systemitem class="domainname">.ourcompany.com</systemitem>:</para> + +<screenco><areaspec> +<area id="url_commas" coords="3"/> +<area id="url_rule1" coords="3"/> +<area id="url_rule2" coords="4"/> +</areaspec> +<screen>[KDE URL Restrictions] +rule_count=2 +rule_1=open,,,,http,,,false +rule_2=open,,,,http,*.ourcompany.com,,true</screen></screenco> + +<calloutlist> +<callout arearefs="url_commas"> +<para>The first four commas skip over the selection criteria with respect to +the originating &URL;. This part is only needed with redirect type +rules.</para> +</callout> +<callout arearefs="url_rule1"><para><option>rule_1</option> forbids the +opening of any http or https &URL;</para></callout> +<callout arearefs="url_rule2"><para><option>rule_2</option> allows the +opening of any http and https &URL; in the <systemitem +class="domainname">.ourcompany.com</systemitem> domain. Note the wildcard +<token>*</token> is only allowed at the start of a domain.</para></callout> +</calloutlist> + +<para>The following rules makes that the user can no longer browse +directories on the local file system that are outside his +$<envar>HOME</envar> directory:</para> + +<screenco><areaspec> +<area id="home_rule1" coords="3"/> +<area id="home_rule2" coords="4"/> +</areaspec> +<screen>[KDE URL Restrictions] +rule_count=2 +rule_1=list,,,,file,,,false +rule_2=list,,,,file,,$HOME,true</screen></screenco> + +<calloutlist> +<callout arearefs="home_rule1"><para><option>rule_1</option> forbids the +listing of any local directory</para></callout> +<callout arearefs="home_rule2"><para><option>rule_2</option> allows listing +directories under the users own $<envar>HOME</envar> +directory.</para></callout> +</calloutlist> + +<para>$<envar>HOME</envar> and $<envar>TMP</envar> are special values to +indicate the users home directory and the &kde; temporary directory of the +user, ⪚ <filename class="directory">/tmp/kde-bastian</filename></para> + +<para>The following rules makes that the user can no longer open local files +that are outside his $<envar>HOME</envar> directory:</para> + +<screenco><areaspec> +<area id="local_rule1" coords="3"/> +<area id="local_rule2" coords="4"/> +<area id="local_rule3" coords="5"/> +</areaspec> +<screen>[KDE URL Restrictions] +rule_count=3 +rule_1=open,,,,file,,,false +rule_2=open,,,,file,,$HOME,true +rule_3=open,,,,file,,$TMP,true</screen></screenco> + +<calloutlist> +<callout arearefs="local_rule1"><para><option>rule_1</option> forbids the +opening of any local file</para></callout> +<callout arearefs="local_rule2"><para><option>rule_2</option> allows opening +files under the users own $<envar>HOME</envar> directory.</para></callout> +<callout arearefs="local_rule3"><para><option>rule_3</option> allows opening +files in the &kde; temporary directory of the user. This is needed by +certain &kde; applications that first download a file or document to the +temporary directory and then open it in an application.</para></callout> +</calloutlist> + + +<para>The redirection option controls whether documents from a certain +location can refer, either automatically or manually via a hyperlink, to a +certain other location. A set of default rules is present as a general +security measure. For example documents located on the Internet may not +refer to locally stored documents.</para> + +<para>For example, if we want to give the intranet-server <systemitem +class="systemname">www.mycompany.com</systemitem> the possibility to refer +to local files we could add the following rule:</para> + +<screen>[KDE URL Restrictions] +rule_count=1 +rule_1=redirect,http,www.mycompany.com,,file,,,true</screen> + +<para>Instead of listing a protocol by name, it is also possible to specify +a whole group of protocols. For that the following groups have been +defined:</para> + +<variablelist> +<varlistentry> +<term>:local</term> +<listitem><para>Protocols that access locally stored information, examples +are file:/, man:/, fonts:/, floppy:/</para></listitem> +</varlistentry> +<varlistentry> +<term>:internet</term> +<listitem><para>Common internet protocols such as http and +ftp</para></listitem> +</varlistentry> +</variablelist> + +<para>Information about protocols is stored in <literal +role="extension">*.protocol</literal> files stored in +<filename +class="directory">$<envar>KDEDIR</envar>/share/services</filename>.</para> + +<para>The <option>Class</option>= entry defines the group a protocol is part +of: +<userinput><command>grep</command> <option>Class=</option> +<filename>$<envar>KDEDIR</envar>/share/services/*.protocol</filename></userinput></para> + +<para>General rules:</para> + +<itemizedlist> +<listitem><para>The :local protocols may refer to any other +protocol</para></listitem> +<listitem><para>It's always allowed to refer to an :internet +protocol</para></listitem> +<listitem><para>Not all protocols are part of a group, fish:/ for +example.</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="configuration-modules"> +<title>Configuration Modules</title> + +<para>&kde; has configuration modules to configure various aspects of the +&kde; environment. Configuration modules appear in the Control Center, in the +Configuration dialog of an application or in both.</para> + +<informalexample> +<para>The proxy configuration module appears in the Control Center but also +as part of the <guilabel>Configure Konqueror</guilabel> dialog in +&konqueror;</para> + +<para>Individual configuration modules can be started with +<command>kcmshell</command> <replaceable>module</replaceable></para> + +<para>To start the Proxy module use:</para> +<itemizedlist> +<listitem><para><command>kcmshell</command> +<filename>kde-proxy.desktop</filename></para></listitem> +<listitem><para><command>kcmshell</command> proxy</para></listitem> +</itemizedlist> + +<para><note><para>Not all applications use configuration modules, often the +configuration dialog is an integral part of the application +itself.</para></note></para> +</informalexample> + +<para>All configuration modules are strictly speaking part of the &kde; +menu.</para> + +<itemizedlist> +<listitem> +<para>The modules that are visible in the Control Center normally +have a <literal role="extension">.desktop</literal> file in <filename +class="directory">$<envar>KDEDIR</envar>/share/applications/kde</filename> +and are sorted under the hidden <guimenu>Settings-Modules</guimenu> menu by +the <filename>kde-settings.menu</filename>, included from +<filename>kde-essential.menu</filename></para> +<screen><userinput><command>kbuildsycoca</command> <option>--menutest</option> 2> /dev/null | <command>grep</command> Settings-Modules</userinput></screen> +</listitem> +<listitem> +<para>Application specific modules normally have a <literal role="extension">.desktop</literal> file under +<filename>$<envar>KDEDIR</envar>/share/applnk/.hidden</filename> which +corresponds to the hidden .hidden menu, included as a result of +<markup><KDELegacyDirs/></markup></para> +<screen><userinput><command>kbuildsycoca</command> <option>--menutest</option> 2> /dev/null | <command>grep</command> .hidden</userinput></screen> +</listitem> +<listitem><para>In &kde; 3.3 it is possible to edit the Control Center with +<application>kcontroledit</application>. +<application>kcontroledit</application> works just like +<application>kmenuedit</application>, changes for current user only. Use +<application>kiosktool</application> to make changes for +everyone.</para></listitem> +</itemizedlist> + +<para>Individual configuration modules can be disables by adding the +following to <filename>kdeglobals</filename>:</para> + +<screen>[KDE Control Module Restrictions] +<replaceable>module-id</replaceable>=false</screen> +<para>For example, to disable the proxy module use</para> +<screen>[KDE Control Module Restrictions] +kde-proxy.desktop=false</screen> +<para>Check the Control Center and the <guilabel>Configure +Konqueror</guilabel> dialog if the proxy configuration is still +there.</para> + +</sect1> +<!-- +<sect1 id="making-it-work"> +<title>Making it Work</title> + +Making It Work +KDE 3.2: Set $KDEDIRS from startkde script +Distribute profiles to all clients + +</para> +</sect1> +--> +</chapter> + +<chapter id="the-lazy-admin"> +<title>The Lazy Admin</title> + +<!-- This section appears to need quite a lot of additional words to --> +<!-- make sense. Perhaps it would be better to comment it out if it --> +<!-- can't be updated before the next release (Phil) --> +<!-- FIXME: Commented it out until it's got some more content fleshing it --> +<!-- out (Lauri) + +<sect1 id="lazy-admin-overview"> +<title>Overview</title> + +<para> +The Lazy Admin +Overview +Deployment + How to get &kde; available on many clients +Remote Desktop Sharing +Take a look at someone else desktop +DCOP + The DCOP command line tool makes it possible to control &kde; applications from the command line +KDialog + A versatile tool to use standard &kde; dialogs in your own scripts + + + +Deployment +Thin Clients +Installing Software += AutoYaST += KickStart +Maintaining Settings += /etc/kderc, other settings += Use rsync to copy files around += Shared filesystem such as NFS +o store profiles themselves on NFS + + + +http://www.suse.de/~nashif/autoinstall/index.html + +</para> +</sect1> +--> +<sect1 id="remote-desktop-sharing"> +<title>Remote Desktop Sharing</title> + +<para>Remote desktop sharing allows remote users to view and optionally +control the desktop of the current user. The remote user needs to be sent +an invitation, and it is possible to create a password protected standing +invitation. This is ideal for tech support teams or administrators to gain +access to users desktops in order to troubleshoot or remedy a problem or +guide a user through a procedure.</para> + +<para>Remote desktop sharing involves two applications: &krfb; (&kde; remote +frame buffer, a VNC server) and &krdc; (&kde; remote desktop connection; a +VNC client.)</para> + +<para>&krfb; can be used by any user to create and manage invitations. +Invitations create a one time password that allows the recipient to connect +to your desktop. By default it is valid for only one successful connection, +and expires after one hour if not used.</para> + +<para>Incoming connections are handled by the kinetd kded module. You can +use the command <userinput><command>dcop</command> kded kinetd +services</userinput> to see if it is running. &krfb; waits for connections +on port 5900 by default. When an incoming connection is made, a dialog will +appear to ask for confirmation by the current user.</para> + +<!-- TODO: Write a bit more here, with a walk through maybe? --> + +</sect1> + +<sect1 id="kde-diy"> +<title>&kde; DIY - Building Your Own Tools</title> + +<sect2 id="dcop"> +<title>DCOP</title> + +<para> +Desktop COmmunication Protocol, <acronym>DCOP</acronym>, is a lightweight mechanism for inter-process communication. +<acronym>DCOP</acronym> allows the user to interact with programs that are currently running. +&kde; supplies two programs to utilitize <acronym>DCOP</acronym>: +<application>dcop</application>, a command-line program, and +<application>kdcop</application>, a <acronym>GUI</acronym> program. +</para> +<para> +A few notes about using <command>dcop</command>: +</para> + +<para> +<itemizedlist> +<listitem> +<para> +<command>dcop</command> [options] [application [object [function [arg1] [arg2] ... ] ] ] +</para> +</listitem> +<listitem> +<para> +Applications that can open more than one window at a time will be listed as +<application>-<acronym>PID</acronym> +</para> +</listitem> +<listitem> +<para> +All the arguments are case-sensitve. setFullScreen and setfullscreen are two different functions. +</para> +</listitem> +<listitem> +<para> +The regular expression token * can be used in the application and object arguments. +<screen><prompt>% </prompt><userinput><command>dcop</command><option> kon*</option></userinput> +konqueror-16006 +konsole-8954 +</screen> +</para> +</listitem> + +</itemizedlist> + +</para> + +<para>Some example commands and their output are below: +</para> + +<informalexample> +<screen><prompt>% </prompt><userinput><command>dcop</command><option> konsole*</option></userinput> +konsole-8954 +</screen> +<para>One &konsole; is running with a <acronym>PID</acronym> of 8954.</para> + +<screen><prompt>% </prompt><userinput><command>dcop</command><option> konsole-8954</option></userinput> +KBookmarkManager-.../share/apps/kfile/bookmarks.xml +KBookmarkManager-.../share/apps/konqueror/bookmarks.xml +KBookmarkNotifier +KDebug +MainApplication-Interface +konsole (default) +konsole-mainwindow#1 +ksycoca +session-1 +session-2 +session-3 +session-4 +</screen> +<para>Here you see that there are four sessions running.</para> + +<screen><prompt>% </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> konsole</option></userinput> +QCStringList interfaces() +QCStringList functions() +int sessionCount() +QString currentSession() +QString newSession() +QString newSession(QString type) +QString sessionId(int position) +void activateSession(QString sessionId) +void nextSession() +void prevSession() +void moveSessionLeft() +void moveSessionRight() +bool fullScreen() +void setFullScreen(bool on) +ASYNC reparseConfiguration() +</screen> +<para>Here are the options for the main &konsole; program. +</para> + +<screen><prompt>% </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> session-1</option></userinput> +QCStringList interfaces() +QCStringList functions() +bool closeSession() +bool sendSignal(int signal) +void clearHistory() +void renameSession(QString name) +QString sessionName() +int sessionPID() +QString schema() +void setSchema(QString schema) +QString encoding() +void setEncoding(QString encoding) +QString keytab() +void setKeytab(QString keyboard) +QSize size() +void setSize(QSize size) +</screen> +<para>Here are the options for the first session, session-1.</para> + +<screen><prompt>% </prompt><userinput><command>dcop</command><option> konsole-8954</option><option> konsole</option><option> setFullScreen</option><parameter> true</parameter></userinput> +</screen> +<para>This sets &konsole; to full screen.</para> + +</informalexample> + +<para> +When there is more than one application/object, which one should you use? + Got a reference? +</para> +<screen><prompt>% </prompt><userinput><command>echo</command><option> $KONSOLE_DCOP</option></userinput> +DCOPRef(konsole-7547,konsole) + +<prompt>% </prompt><userinput><command>dcop</command><option> $KONSOLE_DCOP</option><option> newSession</option></userinput> +session-6 + +<prompt>% </prompt><userinput><command>dcopstart</command><option> konsole</option></userinput> +konsole-9058 + + +#!/bin/sh +konsole=$(dcopstart konsole-script) +session=$(dcop $konsole konsole currentSession) +dcop $konsole $session renameSession Local + +session=$(dcop $konsole konsole newSession) +dcop $konsole $session renameSession Remote + +session=$(dcop $konsole konsole newSession) +dcop $konsole $session renameSession Code +dcop $konsole $session sendSession 'cd /my/work/directory' + +</screen> + +</sect2> + +<sect2 id="kdialog"> +<title>KDialog</title> +<subtitle>&kde; DIY - Building Your Own Tools</subtitle> + +<para>You can use &kde; dialogs from your own scripts, to combine the power +of &UNIX; shell scripting with the ease of use of &kde;.</para> + +<screen><userinput><command>kdialog</command> <option>--msgbox 'You have new mail!'</option></userinput></screen> + +<screen><userinput><command>kdialog</command> <option>--title 'New Mail'</option> <option>--msgbox 'You have new mail!'</option></userinput></screen> + +<para>The <application>KDialog</application> part can be replaced via +<option>--caption</option> option</para> + +<screen><userinput><command>kdialog</command> <option>--title 'New Mail'</option> <option>--msgbox 'You have new mail!'</option> <option>--dontagain myfile:mykey</option></userinput></screen> + +<para>Saves whether to show again in +<filename>$<envar>KDEHOME</envar>/share/config/myfile</filename> (by writing +into this file the following lines:</para> + +<screen>[Notification Messages] +mykey=false</screen> + +<para>Instead of <option>--msgbox</option> you can also use +<option>--sorry</option> and <option>--error</option>, as appropriate. For +instance, you might use <command>kdialog</command> <option>--sorry 'The +network can not be reached'</option> or <command>kdialog</command> +<option>--error 'Mail box can not be opened'</option>.</para> + +<para>It is also possible to create message boxes that accept a yes or no +answer.</para> + +<screen><command>kdialog</command> <option>--yesno 'Do you want to connect +to the Internet?'</option> <command>echo</command> <returnvalue>$?</returnvalue></screen> + +<informaltable> +<tgroup cols="2"> +<thead> +<row> +<entry>Return Value</entry> +<entry>Meaning</entry> +</row> +</thead> +<tbody> +<row><entry>0</entry><entry>Yes, OK, Continue</entry></row> +<row><entry>1</entry><entry>No</entry></row> +<row><entry>2</entry><entry>Cancel</entry></row> +</tbody> +</tgroup> +</informaltable> + +<para>Make sure to store the result in a variable if you do not use it +directly, the next command will fill $? with a new value You can use +<option>--dontagain</option> here as well, it will remember the users choice +and returns it the next times without showing the dialog any more.</para> + +<para>Further variations are:</para> + +<variablelist> +<varlistentry> +<term><option>--warningyesno</option></term> +<listitem> +<para>like <option>--yesno</option> but with a different +icon</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>--warningcontinuecancel</option></term> +<listitem><para>With <guibutton>Continue</guibutton> and +<guibutton>Cancel</guibutton> buttons.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>--warningyesnocancel</option></term> +<listitem><para>With <guibutton>Yes</guibutton>, <guibutton>No</guibutton> +and <guibutton>Cancel</guibutton> button. For example:</para> +<screen><command>kdialog</command> <option>--warningyesnocancel 'Do you want +to save the changes?'</option></screen> +</listitem> +</varlistentry> +</variablelist> + +<screen><command>kdialog</command> <option>--inputbox "Enter your name:" "YourName"</option></screen> + +<para>The result is printed to stdout, to put it in a variable you can use +<userinput>name=$(kdialog --inputbox "Enter your name:" +"YourName")</userinput>. The last argument is optional, it is used to +pre-fill the dialog.</para> + +<screen><userinput><varname>password</varname>=$(<command>kdialog</command> <option>--password "Enter your password:"</option>)</userinput></screen> + +<para>The <option>--dontagain</option> option does not work with +<option>--inputbox</option> or <option>--password</option></para> + +<para>There are two dialogs that let the user make a choice from a +list:</para> + +<variablelist> +<varlistentry> +<term><option>--menu</option></term> +<listitem> +<para>Lets the user select a single item from a list.</para> +</listitem> +</varlistentry> +<varlistentry> +<term><option>--checklist</option></term> +<listitem> +<para>Lets the user select one or more items from a list.</para> +</listitem> +</varlistentry> +</variablelist> + +<screen><userinput><varname>city</varname>=$(<command>kdialog</command> <option>--menu "Select a city" a London b Madrid c Paris d Berlin</option>)</userinput></screen> + +<para><varname>$city</varname> will <returnvalue>a</returnvalue>, <returnvalue>b</returnvalue>, <returnvalue>c</returnvalue> or <returnvalue>d</returnvalue>.</para> + +<screen><userinput><varname>city</varname>=$(<command>kdialog</command> <option>--checklist "Select cities" a London off b Madrid on c Paris on d Berlin off</option>)</userinput></screen> + +<para>Madrid and Paris will be pre-selected. The result with Madrid and +Paris selected will be <returnvalue>"b"</returnvalue> +<returnvalue>"c"</returnvalue>.</para> + +<para>If you add the <option>--separate-output</option> option, it will put +<returnvalue>b</returnvalue> and <returnvalue>c</returnvalue> each on a line +of its own, making the result easier to process.</para> + +<screen>file=$(kdialog --getopenfilename $HOME) +file=$(kdialog --getopenfilename $HOME "*.png *.jpg|Image Files") +file=$(kdialog --getsavefilename $HOME/SaveMe.png) +file=$(kdialog --getexistingdirectory $HOME)</screen> + +</sect2> + +</sect1> + +</chapter> + +&groupware-with-kontact; + +</part> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "part") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/kde-office.docbook b/doc/userguide/kde-office.docbook new file mode 100644 index 000000000..176180294 --- /dev/null +++ b/doc/userguide/kde-office.docbook @@ -0,0 +1,321 @@ +<part id="kde-office"> +<partinfo> +<authorgroup> +<author> +<personname> +<firstname>Raphael</firstname> +<surname>Langerhorst</surname> +</personname> +<email>[email protected]</email> +</author> +<!-- +<othercredit role="reviewer"> +</othercredit> +--> +</authorgroup> +</partinfo> + +<!-- keep a copy of the desired structure here: +* KDE Office + * Introduction to KOffice + * Overview + * Features + * OASIS OpenDocument file format + * Document embedding + * KParts and KOffice + * Example document + * KOffice components overview + * ... [a short intro to all components] + * Further information + * Application manuals + * Internet resources + * Plugin development +--> + +<title>Office</title> + +<chapter id="kde-office-introduction"> +<title>Introduction to KOffice</title> + +<sect1 id="kde-office-overview"> +<title>Overview</title> +<para> +The &kde; project has also created a fully featured office suite +called &koffice; which adheres to standards and fits very well into +the &kde; desktop. This section was written with version 1.4 of +&koffice; in mind. +</para> +<para> +&koffice; is a highly integrated office suite that builds directly on the +KDE technology. This has many advantages in terms of integration, features, +performance, familiar look and feel and so on. All technologies like &DCOP;, +KIO, KParts are directly available. +</para> +<para> +In particular the KParts technology is extended for the &koffice; +components to allow very flexible embedding of documents inside documents. +</para> +<para> +Because much technology is already present inside &kde; itself, &koffice; is +a very lightweight office suite, which results in fast application startup +and low memory consumption. This makes &koffice; a very suitable office suite +for older hardware as well, which can save lots of costs in some cases. +</para> +<para> +&koffice; is also a very feature complete office suite. It is not limited to +word processing, spreadsheets or presentations, but has also components for +image manipulation, flow charts, business report generation, database +management and project management. Because of the flexible component +integration smaller utilities like the diagram and chart engine as well +as the formula editor are available as stand alone tools. +</para> +<para> +As you can see &koffice; brings a lot of features that can enrich your +office experience. Its straight forward and &kde; like approach in look +and feel as well as familiar usability makes &koffice; quite useful for +daily office work. +</para> +<!-- include this para at the end in further information +<para> +You can always take a look at the &koffice; +<ulink url="http://www.koffice.org">website</ulink> to check on the latest +state of the application. +</para> +--> +</sect1> + +<sect1 id="kde-office-features"> +<title>Features</title> +<para> +This list gives a general outline of the &koffice; features. +The &koffice; office suite is too large to list every detail. +</para> +<itemizedlist> +<title>&koffice; features:</title> +<listitem><para>Fully builds on &kde; which makes these technologies available at low costs.</para></listitem> +<listitem><para>Fully integrates into &kde; which is vital for business environments.</para></listitem> +<listitem><para>&kde; technologies include document location abstraction, DCOP scripting, parts and plugins,...</para></listitem> +<listitem><para>Full Component embedding.</para></listitem> +<listitem><para>Low memory footprint, fast startup, lightweight.</para></listitem> +<listitem><para>Feature complete: many components are offered.</para></listitem> +<listitem><para>Intuitive, good looking and easy to learn user interface.</para></listitem> +<listitem><para>Adheres to standards: OASIS OpenDocument file format.</para></listitem> +</itemizedlist> +</sect1> + +<sect1 id="kde-office-fileformat"> +<title>OASIS OpenDocument file format</title> +<para> +It is important for an office suite to use standards where possible, +especially for the file format. The OASIS OpenDocument file format +specification is an open standard for office applications. This +format is spreading more and more, it is also the same file format +OpenOffice.org uses, which means that file exchange with any +user of this office suite is easily possible. +</para> +<para> +Adhering to official standards is always a good thing. For business +environments it is even vital to exactly know about their documents. +</para> +<para> +&koffice; has more components to offer than what is covered by the +OASIS specification. Still, all components covered by the specifications +actually use the OASIS OpenDocument file format. +</para> +</sect1> +</chapter> + +<!-- comment out for final commit before freeze +<chapter id="kde-office-embedding"> +<title>Component Embedding</title> +<sect1 id="kde-office-kparts"> +<title>KParts and &koffice;</title> +<para>To be written</para> +</sect1> + +<sect1 id="kde-office-example"> +<title>Example</title> +<para>To be written</para> +</sect1> +</chapter> +--> + +<chapter id="kde-office-components"> +<title>&koffice; Components Overview</title> + +<para>Keep in mind that all these components can integrate very well into each other. So basically a spreadsheet can contain anything from charts to presentations, reports and even text documents. Likewise almost any component can contain almost any other.</para> + +<variablelist> + +<varlistentry> +<term>&kword;</term> + <listitem><para>The textprocessing component, but it includes many aspects of a desktop publishing application. This creates a rather unique mixture of features that makes interesting layouts easily possible.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kword/">http://www.koffice.org/kword/</ulink></para></listitem> + <listitem><para><ulink url="help:/kword">&kword; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kspread;</term> + <listitem><para>The spreadsheet component. &kspread; is a scriptable spreadsheet program which provides both table-oriented sheets and support for complex mathematical formulas and statistics. Features include Hyperlinks, cell data validity checking with configurable warnings/actions, scripting and specific cell customization. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kspread/">http://www.koffice.org/kspread/</ulink></para></listitem> + <listitem><para><ulink url="help:/kspread">&kspread; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kpresenter;</term> + <listitem><para>The presentation component. It can be used to create on-screen presentations or to design and print transparencies. Features include embedding images and clip-art, easy working with objects, and the ability to make &HTML; or &XML; slideshows.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kpresenter/">http://www.koffice.org/kpresenter/</ulink></para></listitem> + <listitem><para><ulink url="help:/kpresenter">&kpresenter; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kivio;</term> + <listitem><para>The flowcharting and diagramming component. Additional stencil sets can be used for custom needs, there is a plugin framework for additional functionality, and even <acronym>UML</acronym> diagrams are possible.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kivio/">http://www.koffice.org/kivio/</ulink></para></listitem> + <listitem><para><ulink url="help:/kivio">&kivio; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&karbon14;</term> + <listitem><para>A vector-drawing application.</para></listitem> +</varlistentry> + +<varlistentry> +<term>&krita;</term> + <listitem><para>The painting and image manipulation component. &krita; contains both ease-of-use, fun features like guided painting, as well as high-end features like support for 16-bit images, <acronym>CMYK</acronym> and even OpenEXR <acronym>HDR</acronym> images. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/krita/">http://www.koffice.org/krita/</ulink></para></listitem> + <listitem><para><ulink url="help:/krita">&krita; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kugar;</term> + <listitem><para>The appropriate component for creating business reports, which is accomplished with an advanced designer that it has. Features include report printing in postscript, full control of fonts, colors, text alignment and wrapping, as well as open report definition files (with the layout stored as &XML;).</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kugar/">http://www.koffice.org/kugar/</ulink></para></listitem> + <listitem><para><ulink url="help:/kugar">&kugar; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term><application>KPlato</application></term> + <listitem><para>The component for project management, allowing for the planning and scheduling of various projects.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kplato/">http://www.koffice.org/kplato/</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kexi;</term> + <listitem><para>The data management component. It can be used for creating database schemas, inserting data, performing queries, and processing data. Forms can be created to provide a custom interface to your data. All database objects -- tables, queries and forms -- are stored in the database, making it easy to share data and database design.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kexi/">http://www.koffice.org/kexi/</ulink> and <ulink url="http://kexi-project.org">http://kexi-project.org</ulink>.</para></listitem> + <listitem><para><ulink url="help:/kexi">&kexi; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kchart;</term> + <listitem><para>The chart drawing component; it is used to embed charts into one of the other &koffice; components. It's easy to use, highly customizable allowing all of the parameters to be changed, and has a flexible layout. </para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kchart/">http://www.koffice.org/kchart/</ulink></para></listitem> + <listitem><para><ulink url="help:/kchart">&kchart; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +<varlistentry> +<term>&kformula;</term> + <listitem><para> A formula editor which provides the basic input facilities and support functionality that appears in other &koffice; applications. Some of its features include intelligent cursor management, multi-level undo support and advanced syntax highlighting.</para> + + <itemizedlist> + <listitem><para>Website: <ulink url="http://www.koffice.org/kformula/">http://www.koffice.org/kformula/</ulink></para></listitem> + <listitem><para><ulink url="help:/kformula">&kformula; Handbook</ulink></para></listitem> + </itemizedlist> + + </listitem> +</varlistentry> + +</variablelist> + +<itemizedlist> +<title>Related Information</title> + <listitem><para>Main website: <ulink url="http://www.koffice.org">http://www.koffice.org</ulink>.</para></listitem> + <listitem><para><ulink url="help:/koffice">&koffice; Handbook</ulink></para></listitem> +</itemizedlist> + +</chapter> + +<chapter id="kde-office-furtherinfo"> + +<title>Further Information</title> +<sect1 id="kde-office-manuals"> +<title>Application Manuals</title> +<para>Each Koffice component comes with its own manual. +These manuals offer all the latest information about the +various components &koffice; has to offer and should be +read to learn more about &koffice;. The application manuals can be accessed by using the documentation KIO Slave in &konqueror; (that is, typing <userinput>help:/<replaceable>application</replaceable></userinput> into the Location toolbar) or by selecting the respective handbook from the &khelpcenter;. The website is +also a good place to find out more; it is at <ulink url="http://www.koffice.org">http://www.koffice.org</ulink>.</para> +</sect1> + +<sect1 id="kde-office-internet"> +<title>Internet Resources</title> +<para>The primary site on the internet is +<ulink url="http://www.koffice.org">http://www.koffice.org</ulink></para> +<para>You will also find information about the user and developer +mailing lists as well as additional developer resources.</para> +<para>The Kexi project has even an additional website, which can be +found at <ulink url="http://www.kexi-project.org">http://www.kexi-project.org +</ulink></para> +</sect1> + +<sect1 id="kde-office-plugininfo"> +<title>Plugin development</title> +<para>&koffice; can easily be extended with plugins. Plugin development is +not very difficult and can be used to optimize your everyday workflow. Such +capabilities are probably very interesting in business environments to +make &koffice; meet individual requirements. You can either take a look +at existing plugins or read a general introduction at +<ulink url="http://developer.kde.org/documentation/tutorials/developing-a-plugin-structure/index.html"> +the developer's site</ulink>. The general KDE developers website is available +at <ulink url="http://developer.kde.org/">http://developer.kde.org</ulink>. +</para> +</sect1> + +</chapter> +</part> diff --git a/doc/userguide/kmag.png b/doc/userguide/kmag.png Binary files differnew file mode 100644 index 000000000..cba958528 --- /dev/null +++ b/doc/userguide/kmag.png diff --git a/doc/userguide/kmousetool.png b/doc/userguide/kmousetool.png Binary files differnew file mode 100644 index 000000000..371f041ae --- /dev/null +++ b/doc/userguide/kmousetool.png diff --git a/doc/userguide/kmouth.png b/doc/userguide/kmouth.png Binary files differnew file mode 100644 index 000000000..c5507eaba --- /dev/null +++ b/doc/userguide/kmouth.png diff --git a/doc/userguide/kmouth2.png b/doc/userguide/kmouth2.png Binary files differnew file mode 100644 index 000000000..6cf0e613e --- /dev/null +++ b/doc/userguide/kmouth2.png diff --git a/doc/userguide/kmouth3.png b/doc/userguide/kmouth3.png Binary files differnew file mode 100644 index 000000000..8bed5a532 --- /dev/null +++ b/doc/userguide/kmouth3.png diff --git a/doc/userguide/knode-identity.png b/doc/userguide/knode-identity.png Binary files differnew file mode 100644 index 000000000..c9f63347f --- /dev/null +++ b/doc/userguide/knode-identity.png diff --git a/doc/userguide/knode-mail-account.png b/doc/userguide/knode-mail-account.png Binary files differnew file mode 100644 index 000000000..f2271662f --- /dev/null +++ b/doc/userguide/knode-mail-account.png diff --git a/doc/userguide/knode-news-account.png b/doc/userguide/knode-news-account.png Binary files differnew file mode 100644 index 000000000..e046870f1 --- /dev/null +++ b/doc/userguide/knode-news-account.png diff --git a/doc/userguide/knode-start.png b/doc/userguide/knode-start.png Binary files differnew file mode 100644 index 000000000..1057f946b --- /dev/null +++ b/doc/userguide/knode-start.png diff --git a/doc/userguide/konq-sidebar.png b/doc/userguide/konq-sidebar.png Binary files differnew file mode 100644 index 000000000..0e9328e3a --- /dev/null +++ b/doc/userguide/konq-sidebar.png diff --git a/doc/userguide/konq-simple.png b/doc/userguide/konq-simple.png Binary files differnew file mode 100644 index 000000000..a35133865 --- /dev/null +++ b/doc/userguide/konq-simple.png diff --git a/doc/userguide/konsole-intro.docbook b/doc/userguide/konsole-intro.docbook new file mode 100644 index 000000000..d42b4f59a --- /dev/null +++ b/doc/userguide/konsole-intro.docbook @@ -0,0 +1,126 @@ +<chapter id="konsole-intro"> + +<chapterinfo> +<authorgroup> +<author> +<firstname>Gardner</firstname> +<surname>Bell</surname> +</author> +</authorgroup> +</chapterinfo> + + +<title>&konsole; Introduction</title> + +<para>Extremely brief intro to managing in a shell</para> + +<para>Emergency procedures: killing wild apps, etc</para> + +<para>SSH, sessions, envars, other fun things</para> + +<para>Some tips and tricks</para> + + +<!-- Some Content borrowed from the konsole handbook --> + +<para>&konsole; is a terminal emulator for the X Window System. It is +essentially based on the <ulink url="http://vt100.net">DEC's VT100</ulink> +and many of its succesors. &konsole; – also referred to as a +shell – is an +essential tool on &Linux; and &UNIX; based machines for fast and productive +work.</para> + +<para>Emergency Procedures:</para> + +<para>On &Linux; and &UNIX;-based systems every process runs independently in its own memory +space so it can't accidentally overwrite any other processes memory, unless +of course it has <systemitem class="username">root</systemitem> privileges. +If a process in &kde; crashes due to a bug one should not need to worry +about it accessing any other active process.</para> + +<para>To keep track of all system processes use the <command>top</command> +command or <command>ps</command> in &konsole;. Using these utilities will +make it much easier to find and kill off rogue programs.</para> + +<para>An example of using signals in &konsole;, &konqueror; has crashed +leaving behind a running process of +<application>nspluginviewer</application> which is taking up 12% of your +memory and 10% of your cpu cycles. In <command>top</command> use the <keycap>k</keycap> +command switch to kill the task. You will be prompted for the PID and then +the signal to send to kill it. For more on info on what signals you can +send to a running process see the full manual on signals (type +<command>man signal</command> in a &konsole; or go to +<userinput>#signal</userinput> in &konqueror;).</para> + +<para>SSH, sessions, envars, other fun things.</para> + +<para>If you are using &konsole; for remote administration consider using +&konsole;'s <quote>Session</quote> feature. To use this click on the menu +entry +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &konsole;</guimenuitem></menuchoice>. +From here choose the <guimenuitem>Sessions</guimenuitem> tab and fill in the +name for your new session. This will now become your default session when +you start &konsole;.</para> + +<para>When &konsole; is invoked <application>bash</application> specific +commands and &kde; specific variables are read and executed from +<filename>~/.bashrc</filename> or <filename>~/.bash_profile</filename>. +The preferred configuration file for user environments is +<filename>~/.bash_profile</filename>, the commands +<command>printenv</command> or <command>env</command> can be used to +display all currently set variables. To set a variable in the shell use +<command>VARNAME=<replaceable>value</replaceable></command>. For a full +list of variables that can be set in &kde; see the <ulink +url="http://wiki.kde.org/tiki-index.php?page=Environment+Variables">wiki +</ulink>.</para> + +<para>Some tips and tricks</para> + +<para>To rename &konsole;'s session use <keycombo +action="simul">&Ctrl;&Alt;<keycap>S</keycap></keycombo> and enter the new +name.</para> + +<para>If you find the need to run any &kde; program with <systemitem +class="username">root</systemitem> privileges, you can use the &kdesu; command with the <option>-c</option> switch +from the command line like this: <userinput><command>kdesu</command> +<option>-c -n <replaceable>PROGRAM</replaceable></option></userinput>, using +the <option>-n</option> switch will prevent &kde; from remembering your +passwords.</para> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> + + +<listitem><para>The &konsole; +Handbook has much more information about the features available in +&konsole;. You can read it in &khelpcenter; or by entering +<userinput>help:/konsole</userinput> in &konqueror;'s +<guilabel>Location</guilabel> bar.</para> +</listitem> + +</itemizedlist> + + + + + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/kopete.png b/doc/userguide/kopete.png Binary files differnew file mode 100644 index 000000000..446a26655 --- /dev/null +++ b/doc/userguide/kopete.png diff --git a/doc/userguide/kppp-dialer-tab.png b/doc/userguide/kppp-dialer-tab.png Binary files differnew file mode 100644 index 000000000..bb344979f --- /dev/null +++ b/doc/userguide/kppp-dialer-tab.png diff --git a/doc/userguide/kppp-wizard.png b/doc/userguide/kppp-wizard.png Binary files differnew file mode 100644 index 000000000..cbb731fcb --- /dev/null +++ b/doc/userguide/kppp-wizard.png diff --git a/doc/userguide/messaging-intro.docbook b/doc/userguide/messaging-intro.docbook new file mode 100644 index 000000000..8d042a451 --- /dev/null +++ b/doc/userguide/messaging-intro.docbook @@ -0,0 +1,188 @@ +<chapter id="messaging"> + +<chapterinfo> +<authorgroup> +<author> +<firstname>Peter</firstname> +<surname>Nuttall</surname> +</author> + +<author> +<firstname>Tom</firstname> +<surname>Albers</surname> +</author> + +</authorgroup> + +</chapterinfo> + + +<title>Introduction to messaging</title> + + +<para>The default way to send instant messages in &kde; is to use the <acronym>IM</acronym> +client, &kopete;. This is a multi-protocol <acronym>IM</acronym> client, meaning that it +handles several different protocols including <acronym>MSN</acronym>, +Jabber, <acronym>AOL</acronym> and <acronym>IRC</acronym>. It also has +useful features including support for &kaddressbook;, meta-contacts, +encryption support and lots more.</para> + +<screenshot> +<screeninfo>&kopete;, the &kde; IM client.</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kopete.png" format="PNG"/> </imageobject> +<textobject> +<phrase>&kopete;, the &kde; IM client.</phrase> +</textobject> +<caption> +<para>&kopete;, the &kde; IM client.</para> +</caption> +</mediaobject> +</screenshot> + +<sect1 id="messaging-getting-started"> +<title>How to get started</title> + +<para>Start up &kopete; from the menu (it can normally be found in the +Internet folder) When it starts up you should see a window with &kopete; +at the top, menus and a tool bar below, and then your contacts below. +You should add some accounts by clicking on the +<guimenu>Settings</guimenu> menu and selecting the <guimenuitem>Configure +Kopete</guimenuitem> option. By selecting the <guilabel>Accounts</guilabel> +option you should see a list of your accounts (initially empty) and +options to add new accounts and to edit or remove existing accounts. +By clicking on the <guibutton>add new account</guibutton> button, you can +add a new account using the wizard. When you have added an account, you can +connect to this account by clicking on the relevant icon at the bottom of +your main &kopete; window. This should make your contacts appear in the +contacts window.</para> + +</sect1> + +<sect1 id="meta-contacts"> +<title>Meta-contacts</title> + +<para>Meta contacts are one of the features of &kopete; that make sense +once you figure out what they are. Until you do, they annoy you. They are +basically a way of taking a contact on one network (such as +<acronym>MSN</acronym>) and linking it to another contact on a different +network. This is useful for when people have accounts on different networks +as you can chat to them without needing to know which account they are +signed on to. This also lets you assign names to your meta-contacts that +don't change when people change their names on their account, this is useful +if you have contacts who insist upon setting their +<acronym>MSN</acronym> nick to something like +<quote>=EF=81=8A</quote>.</para> + +<para>You can do other useful things with meta-contacts like link them to +entries in your address book. See <xref +linkend="integrated-messaging"/></para> + +</sect1> + +<sect1 id="irc"> +<title><acronym>IRC</acronym></title> + +<para>Internet Relay Chat (<acronym>IRC</acronym>) has been around far longer than most <acronym>IM</acronym> +systems, and is still widely used. It is mainly designed for group (many-to-many) communication in discussion forums called channels, but also allows one-to-one communication.</para> + +<para>The #kde channel is under Freenode, the <acronym>IRC</acronym> server, which provides an interactive environment for coordination and support of peer-directed projects, including -- and placing particular stress upon -- those relating to free software and open source projects, such as &kde;.</para> + + +<para>While &kopete; has a <acronym>IRC</acronym> plugin, and handles both channels and nicks well, +long time <acronym>IRC</acronym> users might prefer a client designed just +for that role, which is what <application>Konversation</application> is. It supports features such +as granting and taking op status, banning, easy nick changing, special +channel support for passwords and invites, and other things that the power +<acronym>IRC</acronym> users expect. It also is far better at handling +large channels such as #debian. If you have used another +power-<acronym>IRC</acronym> client before, you should have no trouble using +<application>Konversation</application>.</para> + + +</sect1> + +<sect1 id="integrated-messaging"> +<title>Linking email and messaging</title> + +<para>Did it happen to you? You received an email and the first thing +you would like to do is to give a reaction on it, but not by +email. So you switch to your instant messaging client and/or IRC +client and look if that person is online via MSN, Jabber or IRC. Well +&kde; 3.3 has made that a lot easier. A step-by-step manual:</para> + +<para>The requirements are &kmail;, &kaddressbook; and &kopete; +(<application>Konversation</application> should do as well). Make sure &kmail; is configured and +fully functional for email, and Kopete is well configured for IRC, +Jabber and/or MSN and/or any other protocol. </para> + +<para>If an email comes in from a contact you know, the first thing +you have to do is to add it to your address book. This can be achieved +by right clicking the address and choosing the entry <guibutton>Add to Address +Book</guibutton>.</para> + +<para>If you know the nickname which the user uses on, for example, IRC, +go to &kopete;. Go to +<menuchoice><guimenu>File</guimenu><guimenuitem>Add +contact</guimenuitem> </menuchoice>. In the wizard, select the +checkbox at the bottom called <guilabel>Use the KDE address book for +this contact</guilabel> and choose <guibutton>Next</guibutton>. Select +the right Address Book entry for that contact and press +<guibutton>Next</guibutton>. Now you can set the display name and the +group it belongs to for &kopete;. In the next screen select which +protocol should be used if you have set up more then one protocol. You +can select more than one protocol. After that, depending on the +protocol, there will be some other questions, which you can answer as +you like.</para> + +<para>Although we did specify to choose from the address book, +&kopete; has not automatically linked your contact to the address +book. So select the contact and choose +<menuchoice><guimenu>Edit</guimenu><guimenuitem>Properties</guimenuitem> +</menuchoice>. On the <guilabel>General</guilabel> tab check the box +labeled <guilabel>Has address book entry</guilabel>. Press +<guilabel>...</guilabel> and select the contact. Close these two +windows.</para> + +<para>Now go to your addressbook, if you select the contact you will +see that it shows an extra field <guilabel>Presence</guilabel>, followed by the current +status. This status will automatically update as soon as the contact +goes away, offline, online, and so on. Now go to &kmail;, select another email and return to the original email (in other words: reload +the current email). You can now see behind the email address the +current state of your contact. </para> + +<para>If you want to chat with this person, just right click the +address in &kmail; and choose <guilabel>Chat With...</guilabel>. Your +Instant Messenger will start a conversation with the contact.</para> + +<!-- Add links to "further reading" here --> +<!--<itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/migrator-applications.docbook b/doc/userguide/migrator-applications.docbook new file mode 100644 index 000000000..fee1caacd --- /dev/null +++ b/doc/userguide/migrator-applications.docbook @@ -0,0 +1,272 @@ +<chapter id="migrator-applications"> +<chapterinfo> +<authorgroup> +<author> +&Francis.Giannaros; &Francis.Giannaros.mail; +</author> +</authorgroup> +</chapterinfo> + +<title>Application Guide for Migrates</title> + +<!-- Section needs a +lot+ of work. I couldn't do any of the Mac equivalents, as I haven't used it before. More entries could be put in, too. --> + +<para>&kde; has many applications, often prefixed with (or containing) the letter k. The names are generally self-explanatory, but it can still be difficult sometimes to find the appropriate packages. Migrates from operating systems such as <trademark class="registered">Microsoft Windows</trademark> or <trademark class="registered">Apple Macintosh</trademark> might have some difficulty in locating an application for a particular job. Below is a table with an expansion on the &kmenu; and the respective Win/Mac equivalent.</para> + +<table><title>Sample Table</title> +<tgroup cols='6' align='left' colsep='1' rowsep='1'> +<colspec colname='c1'/> +<colspec colname='c2'/> +<colspec colname='c3'/> +<colspec colname='c5'/> +<colspec colnum='6' colname='c6' /> +<thead> +<row> + <entry namest="c1" nameend="c2" align="center"><para>&kmenu; Location</para></entry> + <entry><para>&kde; Application</para></entry> + <entry><para><trademark class="registered">Windows</trademark> Equivalent</para></entry> + <entry><para><trademark class="registered">Macintosh</trademark> Equivalent</para></entry> + <entry><para>Notes</para></entry> +</row> +</thead> +<!--<tfoot> +<row> + <entry><para>f1</para></entry> + <entry><para>f2</para></entry> + <entry><para>f3</para></entry> + <entry><para>f4</para></entry> + <entry><para>f5</para></entry> +</row> +</tfoot>--> +<tbody> +<row> + <entry align="center" namest="c1" nameend="c2"><para>File Manager</para></entry> + <entry align="center"><para>&konqueror; (Home Folder)</para></entry> + <entry align="center"><para>Windows Explorer</para></entry> + <entry align="center"><para>Integrated file manager, content +viewer/player and web browser</para></entry> +</row> +<row> + <entry namest="c1" nameend="c2"><para>System and User Settings</para></entry> + <entry><para>&kcontrol;</para></entry> + <entry><para>Control Center</para></entry> +</row> +<row> + <entry morerows='1' valign='middle'><para>Office</para></entry> + <entry><para>Office Suite: + <orderedlist> + <listitem><para>Word Processing</para></listitem> + <listitem><para>Spreadsheets</para></listitem> + <listitem><para>Slide Presentations</para></listitem> + <listitem><para>Flowchart & Diagram Editing</para></listitem> + <listitem><para>Scalable Graphics</para></listitem> + <listitem><para>Image Manipulation</para></listitem> + <listitem><para>Report Generator</para></listitem> + <listitem><para>Chart</para></listitem> + <listitem><para>Database Creation</para></listitem> + <listitem><para>Formula Editor</para></listitem> + </orderedlist> + + </para></entry> + + <entry><para> + <orderedlist> + <listitem><para>&kword;</para></listitem> + <listitem><para>&kspread;</para></listitem> + <listitem><para>&kpresenter;</para></listitem> + <listitem><para>&kivio;</para></listitem> + <listitem><para>&karbon14;</para></listitem> + <listitem><para>&krita;</para></listitem> + <listitem><para>&kugar;</para></listitem> + <listitem><para>&kchart;</para></listitem> + <listitem><para>&kexi;</para></listitem> + <listitem><para>&kformula;</para></listitem> + </orderedlist> + + </para></entry> + + <entry><para> + <orderedlist> + <listitem><para><application><acronym>MS</acronym> Word</application></para></listitem> + <listitem><para><application><acronym>MS</acronym> Excel</application></para></listitem> + <listitem><para><application><acronym>MS</acronym> Powerpoint</application></para></listitem> + <listitem><para><application>Adobe Illustrator</application></para></listitem> + <listitem><para><application>Adobe Photoshop</application></para></listitem> + <listitem><para><application>Report Generator</application></para></listitem> + <listitem><para><application>Chart</application></para></listitem> + <listitem><para><application><acronym>MS</acronym> Access</application></para></listitem> + </orderedlist> + + + +</para></entry> + +<!--Fill in Mac equivalents + <entry><para>Office Suite: +<orderedlist> + <listitem><para>Word Processing</para></listitem> + <listitem><para>Spreadsheets</para></listitem> + <listitem><para>Slide Presentations</para></listitem> + <listitem><para>Flowchart & Diagram Editing</para></listitem> + <listitem><para>Scalable Graphics</para></listitem> + <listitem><para>Image Manipulation</para></listitem> + <listitem><para>Report Generator</para></listitem> + <listitem><para>Chart</para></listitem> + <listitem><para>Database Creation</para></listitem> + <listitem><para>Formula Editor</para></listitem> +</orderedlist> + +</para></entry>--> + +</row> + +<row> + <entry><para>Personal Information Management: + <orderedlist> + <listitem><para>Mail</para></listitem> + <listitem><para>Address Book</para></listitem> + <listitem><para>Personal Organizer</para></listitem> + <listitem><para>News Reader</para></listitem> + <listitem><para>Pop-up Notes</para></listitem> + <listitem><para><acronym>RSS</acronym> Reader</para></listitem> + </orderedlist> + + </para></entry> + <entry><para> + <orderedlist> + <listitem><para>&kmail;</para></listitem> + <listitem><para>&kaddressbook;</para></listitem> + <listitem><para>&korganizer;</para></listitem> + <listitem><para>&knode;</para></listitem> + <listitem><para>&knotes;</para></listitem> + <listitem><para>&akregator;</para></listitem> + </orderedlist> + + </para></entry> + + <entry><para><application><acronym>MS</acronym> Outlook</application></para></entry> + + <entry><para>The Personal Information Manager is &kontact;; all other &kde; <acronym>PIM</acronym> applications integrate into it.</para></entry> + +</row> + +<row> + <entry morerows='2' valign='middle'><para>Internet</para></entry> + <entry><para>Web Browser</para></entry> + <entry><para>&konqueror;</para></entry> + <entry><para><acronym>MS</acronym> Internet Explorer</para></entry> + <entry><para><application>Safari</application></para></entry> + <entry><para>Integrated file manager, web browser, <acronym>FTP</acronym> manager, and univerval viewing application.</para></entry> + + +</row> + +<row> + <entry><para>Instant Messaging</para></entry> + <entry><para>&kopete; + <itemizedlist> + <listitem><para><acronym>AIM</acronym></para></listitem> + <listitem><para><acronym>MSN</acronym></para></listitem> + <listitem><para><acronym>ICQ</acronym></para></listitem> + <listitem><para>Jabber</para></listitem> + <listitem><para>Novell GroupWise</para></listitem> + <listitem><para>Yahoo</para></listitem> + <listitem><para><acronym>IRC</acronym></para></listitem> + <listitem><para><acronym>SMS</acronym></para></listitem> + </itemizedlist> + +</para></entry> + <entry><para><acronym>MSN</acronym> Messenger</para></entry> + <entry><para>Comprehensive multi-network compatible instant messaging software</para></entry> +</row> + +<row> + <entry><para>Chat (<acronym>IRC</acronym>)</para></entry> + <entry><para>&ksirc;</para></entry> + <entry><para><application>mIRC</application></para></entry> +</row> + +<row> + <entry morerows='4' align="center"><para>Multimedia</para></entry> + <entry><para>Music/Audio</para></entry> + <entry><para>&juk;</para></entry> + <entry><para><trademark class="registered">Windows</trademark> Media Player</para></entry> +</row> + +<row> + <entry><para>&CD;/<acronym>DVD</acronym> Burner</para></entry> + <entry><para><application>K3b</application></para></entry> + <entry><para>Nero</para></entry> +</row> + +<row> + <entry><para>Video Player</para></entry> + <entry><para>&noatun;</para></entry> + <entry><para><trademark class="registered">Windows</trademark> Media Player</para></entry> +</row> + +<row> + <entry><para>Audio &CD; Ripper</para></entry> + <entry><para><application>KAudioCreator</application></para></entry> +</row> + +<row> + <entry><para>Sound Controls</para></entry> + <entry><para>&kmix;</para></entry> +</row> + +<row> + <entry morerows='3' align="center"><para>System</para></entry> + <entry><para>System Info Center</para></entry> + <entry><para>&kinfocenter;</para></entry> +</row> + +<row> + <entry><para>Terminal</para></entry> + <entry><para>&konsole;</para></entry> + <entry><para><application>CMD</application></para></entry> +</row> + +<row> + <entry><para>User Manager</para></entry> + <entry><para>&kuser;</para></entry> + <entry><para>User Manager</para></entry> +</row> + +<row> + <entry><para>Package Manager</para></entry> + <entry><para>&kpackage;</para></entry> + <entry><para><application>Add/Remove Programs</application></para></entry> +</row> + +<row> + <entry morerows='2' align="center"><para>Utilities</para></entry> + <entry><para>Archiver</para></entry> + <entry><para>&ark;</para></entry> + <entry><para><application>WinZip</application></para></entry> +</row> + +<row> + <entry><para>Password Manager</para></entry> + <entry><para><application>KWallet</application></para></entry> +</row> + +<row> + <entry><para>Text Editor</para></entry> + <entry><para>&kate;</para></entry> + <entry><para>Notepad</para></entry> +</row> + + +</tbody> +</tgroup> + +</table> + +<itemizedlist> +<title>Related Information</title> +<listitem><para>Many more &kde; applications are available from the &kde; extragear (see <xref linkend="extragear-applications" /> for more information) or from <ulink url="http://kde-apps.org">http://kde-apps.org</ulink>.</para></listitem> +<listitem><para>Reference: <ulink url="http://kudos.berlios.de/kf/kf1.html#pkgtablestock">http://kudos.berlios.de/kf/kf1.html#pkgtablestock</ulink></para></listitem> +</itemizedlist> + +</chapter>
\ No newline at end of file diff --git a/doc/userguide/migrator-dictionary.docbook b/doc/userguide/migrator-dictionary.docbook new file mode 100644 index 000000000..4bd2efa5d --- /dev/null +++ b/doc/userguide/migrator-dictionary.docbook @@ -0,0 +1,38 @@ +<chapter id="migration-dictionary"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<chapterinfo> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</chapterinfo> +--> + +<title>Dictionary for Migrators</title> + +<para>Tables of terminology differences</para> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/net-connection-setup.docbook b/doc/userguide/net-connection-setup.docbook new file mode 100644 index 000000000..cd44fda34 --- /dev/null +++ b/doc/userguide/net-connection-setup.docbook @@ -0,0 +1,238 @@ +<chapter id="setup"> + +<chapterinfo> +<authorgroup> +<author> +&Lauri.Watts; +</author> +</authorgroup> +</chapterinfo> + + +<title>Setting up an Internet Connection</title> +<!-- Contents shamelessly stolen from the KPPP manual, written by --> +<!-- Lauri --> + +<para>&kde; offers a complete Internet experience, with all the +programs you'll need to make the most of the Web, email, Usenet and +many other Internet technologies. But before you can enjoy &kde;'s +advanced features, you'll need to get online. Here's how:</para> + +<para>If you're using <quote>dialup</quote> (that is, connecting to +the Internet with a modem connected to a telephone line), you'll want +to set up the &kde; dialing program, &kppp;. If that sounds +complicated, don't worry: &kppp; has an advanced configuration wizard, +which will usually take the pain out of setting up your dialup +connection. Take a look at the next two sections for more +details.</para> + +<para>If you're using a broadband connection, or connecting via a +local network, things are easier (from the point of view of +&kde;). Once you've set up the connection with the tools provided by +your &Linux; or &UNIX; distribution, &kde; will use the connection +automatically.</para> + +<sect1 id="getting-online"> +<title>Getting online the easy way</title> + +<sect2 id="things-to-prepare"> +<title>A few things you should have ready before you start</title> + +<para>If you have a fairly modern &Linux; distribution, you might find the rest +of this document superfluous. &kppp; comes with a clever little wizard that in +many cases can have you up and running with an internet connection in just a few +minutes.</para> + +<para>Whether using the wizard or not, you should know the following information +before you begin:</para> + +<itemizedlist> +<listitem><para>Your <acronym>ISP</acronym> modem pool phone +number.</para></listitem> +<listitem><para>Your username and password for your +<acronym>ISP</acronym>.</para></listitem> +<listitem><para>Your <acronym>ISP</acronym>'s <acronym>DNS</acronym> servers +(one is sufficient, but two is better).</para></listitem> +</itemizedlist> + +<para>Other optional information you should find out to fully access your +<acronym>ISP</acronym>'s services are:</para> + +<itemizedlist> +<listitem><para>The incoming mail server address (often <systemitem +class="systemname">pop.yourisp.com</systemitem> or <systemitem +class="systemname">mail.yourisp.com</systemitem>).</para><para>Also find out if +your <acronym>ISP</acronym> uses the POP3 protocol or IMAP.</para></listitem> +<listitem><para>The outgoing (<acronym>SMTP</acronym>) mail server address (it +could be the same as the incoming mail server, or it is often called something +like <systemitem +class="systemname">smtp.yourisp.com</systemitem>).</para></listitem> +<listitem><para>The Usenet News (<acronym>NNTP</acronym>) server address (possibly +<systemitem class="systemname">news.yourisp.com</systemitem> or <systemitem +class="systemname">nntp.yourisp.com</systemitem>).</para></listitem> +<listitem><para>Any proxy servers your <acronym>ISP</acronym> has set +up.</para></listitem> +</itemizedlist> + +<para>All this information is probably available on any paperwork you received +from your <acronym>ISP</acronym> when you signed up with them, or you can find +it out from your <acronym>ISP</acronym>'s support telephone line.</para> + +<para>Armed with the above, and a fairly recent default installation +of &Linux;, you may well find that setting up an internet connection +is as simple as running the &kppp; wizard.</para> + + +</sect2> + +</sect1> + +<sect1 id="wizard"> +<title>The &kppp; wizard</title> + +<sect2 id="starting-the-wizard"> +<title>Starting the Wizard.</title> + +<para>You can start the wizard from &kppp;'s initial screen. Start &kppp; from +your <guimenu>K</guimenu> menu, where you will find its entry in the +<guisubmenu>Internet</guisubmenu> as <guimenuitem>&kppp; (Internet Dial-Up +Tool</guimenuitem>.</para> + +<para>The following dialog will appear:</para> + +<screenshot> +<screeninfo>The &kppp; dialer startup dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kppp-dialer-tab.png" format="PNG"/> +</imageobject> +<textobject><phrase>The &kppp; dialer startup dialog</phrase> +</textobject> +<caption><para>The &kppp; dialer startup dialog</para></caption> +</mediaobject> +</screenshot> + +<para>It will probably not have any entries to begin with, and that's +what we're about to do now.</para> + +<para>Click the <guibutton>Configure...</guibutton> button to begin setting up a new +Internet connection.</para> +<!-- the following is outdated and has to be rewritten 27.06.2006 lueck--> +<para>The wizard will offer you three choices, <guibutton>Wizard</guibutton>, +<guibutton>Dialog Setup</guibutton> and <guibutton>Cancel</guibutton></para> + +<screenshot> +<screeninfo>The wizard asks you what you want to do...</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="kppp-wizard.png" format="PNG"/> +</imageobject> +<textobject><phrase>The wizard asks you what you want to +do...</phrase></textobject> +<caption><para>The wizard asks you what you want to do</para></caption> +</mediaobject> +</screenshot> + +<variablelist> +<varlistentry> +<term><guibutton>Cancel</guibutton></term> +<listitem><para>Choose this if you really don't want to be setting up a new +account right now. The message box will go away, and you will be left with the +dialer window as before.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Wizard</guibutton></term> +<listitem><para>If you have a fairly standard modem, and use one of the larger +ISP's for your country, the wizard will probably be able to set you up +immediately with a working Internet Connection. Try this first, before you try +to set up the connection manually.</para></listitem> +</varlistentry> + +<varlistentry> +<term><guibutton>Dialog Setup</guibutton></term> +<listitem><para>If you don't succeed with the Wizard, or you just want to do +things yourself, choose this. The wizard currently is only useful for a small +subset of countries and Internet Providers.</para> +</listitem> +</varlistentry> +</variablelist> + +<para>For the purposes of this chapter, we'll assume you are choosing +<guibutton>Wizard</guibutton>, and the dialog based setup will be +described in a later chapter.</para> + +</sect2> + +<sect2 id="finishing-the-wizard"> +<title>The Rest of the Wizard</title> + +<para>The first window you see contains just introductory text, explaining the +things you read about in the first section of this chapter. Click +<guibutton>Next</guibutton> to move on.</para> + +<para>The second window asks you to choose the country you live in. Not all +countries are represented here, and if the country you live in is not listed, +you will have to click <guibutton>Cancel</guibutton>, in which case the Dialog-based setup will start for you to continue +with.</para> + +<para>On the next window, you will be given a choice of Internet +Providers that &kppp; knows about, based on your choice of location in +the previous window. Again, if your <acronym>ISP</acronym> is not +listed here, you will have to click <guibutton>Cancel</guibutton> and +do your setup in the Dialog-based setup</para> + +<para>You will now be asked to enter your username and password for your +internet connection. Please note, that for some <acronym>ISP</acronym>s this +differs from your mail account user name and password, so make sure you use the +right one. Choose <guibutton>Next</guibutton> to continue.</para> + +<para>On the next window, you have a chance to enter any special dial prefixes +you might have - for example, if you must dial <quote>0</quote> for an outside +line, or if you have a prefix you can dial to turn off call waiting. Choose +<guibutton>Next</guibutton> to continue.</para> + +<para>And that's all! If you want to revisit any of your choices, you can use +the <guibutton>Back</guibutton> and <guibutton>Next</guibutton> buttons to move +back and forth through the dialogs. When you're done with your settings, click the +<guibutton>Finish</guibutton> button, and you're all done.</para> + +<para>If you need more details, you can read the full &kppp; +manual in the &kde; Help Center, or by typing +<userinput>help:/kppp</userinput> in the <guilabel>Location</guilabel> +bar in &konqueror;.</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + + +</sect2> + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> + + diff --git a/doc/userguide/networking-with-windows.docbook b/doc/userguide/networking-with-windows.docbook new file mode 100644 index 000000000..ba8ef0596 --- /dev/null +++ b/doc/userguide/networking-with-windows.docbook @@ -0,0 +1,128 @@ +<sect1 id="networking-with-windows"> +<sect1info> +<authorgroup> +<author> +<firstname>Gardner</firstname> +<surname>Bell</surname> +</author> +</authorgroup> +</sect1info> + + +<title>Networking With Windows</title> + +<para> This section is borrowed and modified from Alexander Neundorf's +README file on LISa.</para> + +<para>&kde; features two powerful servers called the Lan Information +Server (<application>LISa</application>) and Restricted Lan +Information Server (<application>resLISa</application>) which are used +to identify CIFS and other servers on your local network providing a +function similar to <quote>Network Neighbourhood</quote> in +&Microsoft; &Windows;.</para> + +<sect2 id="How-It-Works"> +<title>How It Works</title> + +<para>&lisa; only depends on the TCP/IP stack so samba configuration is not +required to make it work but the <ulink +url="http://www.samba.org">samba</ulink> package is a dependency. To find +hosts on your local network you set a range of IP-Addresses in your +configuration file that &lisa; will check. When you start the &lisa; daemon +it will send a <ulink url="http://www.ietf.org/rfc/rfc792.txt">ICMP</ulink>, +echo request message to all the IP addresses given in the configuration file +and await a response.</para> + +<note><para>The &lisa; daemon requires root privileges to open the socket, +but once the socket has been established root privileges are immediately +dropped.</para></note> + +<para>You can also execute &lisa; using <command>nmblookup +<option>"*"</option></command>.<note><para>If you do not have the +<command>nmblookup</command> program it can be found at <ulink +url="http://www.samba.org">http://www.samba.org</ulink> or through packages +provided by your distribution</para></note>. The samba command +<command>nmblookup <option>"*"</option></command> will send a broadcast +message to the attached network and any host that is running the +smb-services will send a reply stating that it is accepting +connections.</para> +</sect2> + +<sect2 id="resLISa"> +<title><application>resLISa</application></title> + +<para>If your company network has very strict guidelines governing what +ports can and cannot be opened you will have to use &reslisa; to communicate +with other hosts on your network. Because &reslisa; cannot ping entire +networks or address ranges you will have to add each host by name to your +confiuration file. Currently you are able to add up to 64 hosts, and these +addresses are pingable.</para> + +<note><para>&reslisa; will only provide the information over a &UNIX; domain +socket, &ie; not over the network. The name of the socket is +<filename>/tmp/resLISa-<replaceable>YourLoginName</replaceable></filename>, +so &reslisa; can be safely run on the same machine by more than one +user.</para></note> +</sect2> + +<sect2 id="configuration"> +<title>Configuration</title> + +<para>At startup &lisa; first parses the configuration file in the users +home directory under <filename>$<envar>HOME</envar>/.lisarc</filename>. If +this file does not exist &lisa; will then look for a system wide +confiuration located at <filename>/etc/lisarc</filename>. Now for a sample +example configuration file:</para> + +<programlisting> +PingAddresses = 192.168.100.0/255.255.255.0;192.168.100.10-192.168.199.19;192.168.200.1; +PingNames = my_host1;my_host2 #Hosts by name (required for <application>resLISa</application>) +AllowedAddresses = 192.168.0.0/255.255.0.0 +BroadcastNetwork = 192.168.100.0/255.255.255.0 +SearchUsingNmblookup = 1 #also try nmblookup +FirstWait = 30 #30 one-hundredth's of a second +SecondWait = -1 #Only try once +#SecondWait = 60 #Try twice and wait 0.6 seconds +UpdatePeriod = 300 #Update every 300 sec's +DeliverUnnamedHosts = 0 #Don't publish unnamed hosts +MaxPingsAtOnce = 256 #Send up to 256 ICMP echo requests at once +</programlisting> + +<para>&lisa; can also be configured graphically in the +<menuchoice><guimenuitem>&kcontrolcenter;</guimenuitem><guisubmenu>Internet +& Network</guisubmenu><guimenuitem>Local Network Browsing</guimenuitem> +</menuchoice> item in the &kmenu;. However, to use this option &lisa; must +be started with the <option>-K</option> command line switch.</para> + +<!--TODO add a section explaining graphical configuration? --> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> +<listitem><para>For a full list of command line switches and further +examples see the entire &lisa; manual by entering +<userinput>help:/lisa</userinput> in &konqueror;.</para> +</listitem> +</itemizedlist> + + +</sect2> +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/noatun-icon.png b/doc/userguide/noatun-icon.png Binary files differnew file mode 100644 index 000000000..c440d0924 --- /dev/null +++ b/doc/userguide/noatun-icon.png diff --git a/doc/userguide/noatun.png b/doc/userguide/noatun.png Binary files differnew file mode 100644 index 000000000..2f807e715 --- /dev/null +++ b/doc/userguide/noatun.png diff --git a/doc/userguide/oggfolder.png b/doc/userguide/oggfolder.png Binary files differnew file mode 100644 index 000000000..ac1527c32 --- /dev/null +++ b/doc/userguide/oggfolder.png diff --git a/doc/userguide/open-file-dialog.png b/doc/userguide/open-file-dialog.png Binary files differnew file mode 100644 index 000000000..38378aa0c --- /dev/null +++ b/doc/userguide/open-file-dialog.png diff --git a/doc/userguide/panel-and-desktop.docbook b/doc/userguide/panel-and-desktop.docbook new file mode 100644 index 000000000..1e92d3a82 --- /dev/null +++ b/doc/userguide/panel-and-desktop.docbook @@ -0,0 +1,325 @@ +<chapter id="panel-and-desktop"> + +<chapterinfo> +<authorgroup> +<author> +&Philip.Rodrigues; +</author> +</authorgroup> +</chapterinfo> + + +<title>The Panel and the Desktop</title> + +<sect1 id="kicker-panel"> +<title>&kicker;, the &kde; Panel</title> + +<indexterm +significance="preferred"><primary>Panel</primary></indexterm> +<indexterm +significance="preferred"><primary>&kicker;</primary></indexterm> + +<para>&kicker; is the application launcher panel of the K Desktop +Environment. By default, it appears along the bottom of the screen, +and takes up the whole of the width of the screen, but this is +configurable. &kicker; is something of a one-stop shop for (almost!) +everything that you might want quick access to. Besides the &kicon; +Menu, where you can start applications, &kicker; is also capable of +running docked applets like the pager, the taskbar or the clock, and +extensions, such as child panels. With all these options, you will +probably want to configure &kicker; so that it works best for you. The +next section describes some common ways to customize the panel.</para> +<!-- TODO: steal screenies from kicker manual --> +</sect1> + +<!-- FIXME: Titles and id's in this section should be more consistent --> +<sect1 id="kicker-configuring"> +<title>Configuring &kicker;</title> + + +<sect2 id="customize-panel-icons"> +<title>Customizing the icons on the panel</title> + +<para>When you first start &kde;, kicker displays some icons next to +the <guimenu>K</guimenu> menu. These can be used to start the +applications that they represent. To see which application is launched + by each icon, hold the mouse cursor over the icon until a tooltip (a +small popup label) appears telling you the name of the application.</para> + +<para>These default icons might not represent the applications you use +most often, so you can remove the ones you do not want and add icons +for other applications that you use. To remove an icon, &RMB;-click on +the icon, and select <guilabel>Remove <replaceable>application +name</replaceable> Button</guilabel> in the popup menu that +appears. To add a new icon, &RMB;-click on an empty space on the +panel, and follow the menu entry <guisubmenu>Add Application to Panel +</guisubmenu>. This leads you to a copy of the +<guimenu>K</guimenu> menu, where you can find all of the &kde; +applications. For example, to add an icon for the &juk; music player, +follow through the menus to <menuchoice><guisubmenu>Add Application +to Panel</guisubmenu><guisubmenu>Multimedia</guisubmenu><guimenuitem>&juk; (Music +Player)</guimenuitem></menuchoice>. The icon will appear on the +panel in the space that you <mousebutton>right</mousebutton>-clicked on.</para> + +</sect2> + + +<sect2 id="adding-extras-and-applets"> +<title>Adding extras and applets</title> + +<indexterm><primary>Applets</primary></indexterm> + +<para>&kicker; can add many types of items as well as application +launch icons. You can find these items using the same menu as before, +but this time selecting +<guisubmenu>Add Applet to Panel...</guisubmenu> +or +<guisubmenu>Add New Panel</guisubmenu>. +The items in the <guilabel>Add Applet</guilabel> window are small +programs that can reside on the panel. An example of an applet is the +<guilabel>Desktop Preview & Pager</guilabel><indexterm><primary>Pager</primary></indexterm>, which shows a small image of each of your virtual +desktops. (For more information about virtual desktops, see <xref +linkend="using-multiple-desktops" />). You can switch to a different +virtual desktop by clicking on its image in the desktop pager. +<!-- TODO: screenie --></para> +<para>You can find information about the other applets available for +&kicker; in the &kicker; manual. Just enter +<userinput>help:/kicker</userinput> in the +<guilabel>Location</guilabel> bar in &konqueror;. </para> +</sect2> + +<sect2 id="the-system-tray"> +<sect2info> +<authorgroup> +<author> +<personname> +<firstname>Simon</firstname> +<surname>Vermeersch</surname> +</personname> +<email>[email protected]</email> +</author> +</authorgroup> +</sect2info> + +<title>The System Tray</title> + +<!-- Simon Vermeersch --> +<para>The system tray is where programs that are run, but not directly needed are +kept. Some programs (like music players) are shown there, because you +probably want to keep them open, but so that it does not take too much space on +your screen, it will put an icon in the system tray.</para> + +<para>When you <mousebutton>right</mousebutton> click on such an icon, a +popup menu will appear where you can see some options of the program (like +play, pause, stop, ... in a music player).</para> +<para>When you <mousebutton>left</mousebutton> click on it, the main window +of the program will appear. If you hover your mouse above the icon, a tool +tip will appear with some information (in the music player case information +like the current song). Programs that normally support system tray icons are +music players, IRC clients, organizers, ...</para> + +<para>In most of these programs you can configure if you want an icon to be +shown or not. For other tricks and tips with the system tray see the section on <xref linkend="system-tray" />.</para> + +</sect2> + +<sect2 id="removing-panel-items"> +<title>Removing Panel Items</title> + +<!-- TODO: Need a screenie to show the handles, since they're not very --> +<!-- easy to describe (and also very small - possible --> +<!-- accessibility/usability issue? --> +<para>You can remove applets and other special items from the panel +using the arrow on its handle on the applet's left. Right click on the +arrow, and choose <guimenuitem>Remove <replaceable>applet +name</replaceable></guimenuitem>.</para> +</sect2> + +</sect1> + +<sect1 id="kicker-taskbar"> +<title>The Taskbar</title> +<!-- TODO: Screenie (again), write more about why taskbar is useful --> +<para>The taskbar is an item on the panel which displays an entry for +each window that you have opened. You can use the taskbar to switch +between windows by clicking on the entry of the window you want to +activate. The taskbar has entries for windows on each virtual desktop, +including windows which have been minimized.</para> + +</sect1> + +<sect1 id="using-the-clipboard"> +<sect1info> +<authorgroup> +<author>&Philip.Rodrigues; +</author> +</authorgroup> +</sect1info> + +<title>Using the Clipboard</title> + +<indexterm><primary>Clipboard</primary></indexterm> + +<para>Very often, it's useful to move some text, or an object in a +program, from one place to another. It's also very common to need to +duplicate some text, for example, if you're typing the same thing +several times. The system used for doing this is known as the +<firstterm>clipboard</firstterm>. There are two slightly different ways to use this system, +known technically as the <quote>selection</quote> and the +<quote><glossterm>clipboard</glossterm></quote>. We'll look at them separately: +</para> + +<!-- TODO: Describe how to select text --> + +<sect2 id="the-selection"> +<title>The Selection</title> +<indexterm><primary>Selection</primary></indexterm> + +<para>This method uses the mouse to copy text from one place to +another. The method is: +<orderedlist> + +<listitem><para>Select the text you want to copy.</para> +</listitem> + +<listitem><para>Click the &MMB; at the place you want the text to be +copied to. This can be in the same program as you copied the text +from, or in another program entirely.</para> +</listitem> +</orderedlist> +If you have three buttons on your mouse, this is easy, but if not, all +is not lost! If you have only two buttons, try clicking them both at +the same time instead of the &MMB;. +<!-- Should we mention Emulate3Buttons in XF86Config here? --> +</para> +</sect2> + +<sect2 id="the-clipboard-proper"> +<title>The Clipboard</title> +<indexterm><primary>Cut</primary></indexterm> +<indexterm><primary>Paste</primary></indexterm> +<para>With this method, you can copy text, or <quote>cut</quote> it +(that is, remove it from one place and move it to another). You can +use either the mouse and the menu entries, or the keyboard with this +method. I'll list both ways, with the menu entry to use, followed by +the keyboard shortcut which will do the same thing, like this:</para> +<para> +<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>X</keycap> +</keycombo> +</shortcut><guimenu>Edit</guimenu><guimenuitem>Cut</guimenuitem> +</menuchoice> </para> +<para> +<orderedlist> +<title>Moving (<quote>Cutting</quote>) Text</title> +<listitem><para>Select the text you want to cut.</para> +</listitem> +<listitem><para>From the menu, select +<menuchoice><shortcut><keycombo + action="simul">&Ctrl;<keycap>X</keycap> +</keycombo> +</shortcut><guimenu>Edit</guimenu><guimenuitem>Cut</guimenuitem> +</menuchoice>, and the text will be removed from its current location.</para> +</listitem> +<listitem><para>Position the text cursor at the point you want to +insert the text. This can be in the same application you got the text +from, or another application entirely. Select +<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>V</keycap> +</keycombo> +</shortcut><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem> +</menuchoice>, and the text will appear at the point where you placed +the cursor.</para> +</listitem> +</orderedlist> +</para> + +<para> +Copying text from one place to another is very similar: +<orderedlist> +<title>Copying Text</title> +<listitem><para>Select the text you want to copy.</para> +</listitem> +<listitem><para>From the menu, select +<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap> +</keycombo> +</shortcut><guimenu>Edit</guimenu><guimenuitem>Copy</guimenuitem> +</menuchoice>, and the text will be copied in the clipboard.</para> +</listitem> +<listitem><para>Position the text cursor at the point you want to +insert the text. This can be in the same application you got the text +from, or another application entirely. Select +<menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>V</keycap> +</keycombo> +</shortcut><guimenu>Edit</guimenu><guimenuitem>Paste</guimenuitem> +</menuchoice></para> +</listitem> +</orderedlist> +</para> + + +</sect2> +<sect2 id="klipper"> +<title>More Advanced Clipboard Use</title> +<indexterm><primary>&klipper;</primary></indexterm> +<indexterm><primary>Clipboard</primary><secondary>History</secondary></indexterm> +<!-- Should we describe this advanced use, or just point to it? --> +<para>The instructions above describe the default <glossterm>clipboard</glossterm> +behavior. The &klipper; application, which you can add as an applet in +the panel (see <xref linkend="kicker-configuring"/> for instructions +on how to do this), provides some useful clipboard-related features, +like a clipboard history, and the ability to change the behavior of +the clipboard and selection. Take a look at the &klipper; Handbook for +more information.</para> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> + +<listitem><para>You can find more information about &kicker;, the +&kde; Panel, in &khelpcenter; or by entering +<userinput>help:/kicker</userinput> in &konqueror;'s +<guilabel>Location</guilabel> bar.</para> +</listitem> + +<listitem><para>The &klipper; +Handbook has information about the advanced clipboard management +features in &kde;. You can read it in &khelpcenter; or by entering +<userinput>help:/klipper</userinput> in &konqueror;'s +<guilabel>Location</guilabel> bar.</para> +</listitem> + +</itemizedlist> + + +</sect2> + +</sect1> + +<sect1 id="kicker-related-information"> +<title>Related Information</title> +<itemizedlist> +<title>Related Information</title> +<listitem><para>Though some information has been presented here, there is a lot more information on &kicker; tips, options, tricks and hacks, in the &kicker; handbook. You can access it via the &khelpcenter; or by simply entering <userinput>help:/kicker</userinput> in the &konqueror; Location toolbar.</para> +</listitem> +</itemizedlist> + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/pdf-files.docbook b/doc/userguide/pdf-files.docbook new file mode 100644 index 000000000..0dd83c2e3 --- /dev/null +++ b/doc/userguide/pdf-files.docbook @@ -0,0 +1,40 @@ +<sect1 id="pdfs"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>PDF Files</title> + +<para>How to print to a pdf file</para> + +<para>Viewing pdf files</para> + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/playing-audiocds.docbook b/doc/userguide/playing-audiocds.docbook new file mode 100644 index 000000000..3f96a6056 --- /dev/null +++ b/doc/userguide/playing-audiocds.docbook @@ -0,0 +1,142 @@ +<sect1 id="audio-cd"> +<sect1info> +<author> +<personname> +<firstname>Deepak</firstname> +<surname>Sarda</surname> +</personname> +<email>[email protected]</email> +</author> +</sect1info> + +<title>Audio CD Ripping in &kde;</title> + +<para>The conventional way of ripping Audio CDs to MP3 or Ogg files is to +use a standalone program such as <trademark class="registered"><application>iTunes</application></trademark>, Winamp or &kde;'s own +<application>KAudioCreator</application>. But if we stick to conventions, +where's the fun?! So in this article, I am going to show you how to feel +elite by ripping your CDs in the, umm.. elite way. ;-) </para> + +<sect2 id="audio-cd-ingredients"> +<title>Ingredients</title> + +<para>What do we need to be cool? Vanilla &kde;, without any extra +ingredients, will be able to rip your CDs. But to encode them, you'll need +to install the relevant codecs. At the moment, Ogg Vorbis, MP3 and FLAC formats +are supported. To enable encoding to these formats, you'll have to install +libogg, lame and flac respectively. How exactly you install these depends on +your distribution: take a look at their documentation to find out how.</para> + +<para>Once you have your favourite codec(s) installed, open &kcontrolcenter; and navigate your way to <menuchoice><guimenu>Sound & +Multimedia</guimenu><guimenuitem>Audio CDs</guimenuitem></menuchoice> +and configure the settings on the various tabs to your liking. You can leave +everything in the default state if you so wish, but it's helpful to take a +look so you at least know what's on offer. Again, take a look at +<menuchoice><guimenu>Sound & Multimedia</guimenu><guimenuitem>CDDB +Retrieval</guimenuitem></menuchoice> and change anything that's not to your +liking. <acronym>CDDB</acronym>, in case you didn't know, stands for CD DataBase (or Compact +Disc DataBase in it's more free flowing form). This functionality enables +&kde; to retrieve the Artist/Album/Track information about your CDs from the +Internet. This metadata is also used to write tags to the MP3 or Ogg files +that you'll be encoding your CDs to anytime now. </para> + + +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="ripsettings.png"/> +</imageobject> +</mediaobject> + +</sect2> + +<sect2 id="audio-cd-recipe"> +<title>Recipe</title> + +<para>Without further delay, let's get down to the business of being cool. +First, pop in the CD you want to rip (obviously!). Next, fire up a +&konqueror; window and open the <guilabel>Services</guilabel> tab on the Navigation panel. The +Navigation panel sits on the left side of the window, as shown in the +screenshot below. If it's not visible, you can produce it out of thin air by +pressing the magic <keycap>F9</keycap> key.</para> + + +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="services.png"/> +</imageobject> +</mediaobject> + + +<para>Now click on Audio CD Browser and in a few seconds, you'll see a lot +of folders which you can start browsing. If it's taking some time to show +anything, it's because it's trying to fetch information about the CD from +the CDDB database you configured earlier. </para> + +<para>In the screenshot below, you can see the contents of the Ogg Vorbis +folder. It shows all the songs in the Ogg format; it even shows their file +size! But, you and I both know that audio CDs don't contain Ogg tracks. So +what exactly is happening here?</para> + + +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="oggfolder.png"/> +</imageobject> +</mediaobject> + + +<para>All the folders you see under Audio CD Browser are virtual folders. +They show contents of the CD through different filters, so to speak. When +you open the Ogg Vorbis folder, you are actually seeing the contents of the +CD <emphasis>as if</emphasis> it were stored in the Ogg format. You can go through the other +folders and you'll find MP3, flac and wav representations of the CD's +contents. You can even see the approximate file sizes when encoded in the +various formats. </para> + + +<para>So how do we rip and encode the CD? I think you can guess the answer +by now. Just decide which format you wish to rip to, open that folder, and +copy and paste those files in your target folder. That's it! &kde; will start +ripping and encoding the files on the fly! If you copy any of the files in +the <guilabel>Full CD</guilabel> folder, you'll be ripping the entire CD as +one continuous stream. </para> + + +<mediaobject> +<imageobject> +<imagedata format="PNG" fileref="rip.png"/> +</imageobject> +</mediaobject> + + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> +<listitem><para>The <application>amaroK</application> website at +<ulink url="http://amarok.sf.net">http://amarok.sf.net</ulink> has the +latest news and information about <application>amaroK</application>.</para> +</listitem> +</itemizedlist> + +<!-- TODO: Add a link to the full audiocd documentation as soon as --> +<!-- it's fixed :-) --> +</sect2> +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/playing-movies.docbook b/doc/userguide/playing-movies.docbook new file mode 100644 index 000000000..89e986cbb --- /dev/null +++ b/doc/userguide/playing-movies.docbook @@ -0,0 +1,48 @@ +<sect1 id="playing-movies"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Playing Movies</title> + +<para>Intro to xine plugin to aRts</para> + +<para>Alternatives (kaffeine, kmplayer)</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/playing-music.docbook b/doc/userguide/playing-music.docbook new file mode 100644 index 000000000..22c129f1e --- /dev/null +++ b/doc/userguide/playing-music.docbook @@ -0,0 +1,150 @@ +<sect1 id="playing-music"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<sect1info> +<authorgroup> +<author>&Lauri.Watts;</author> +</authorgroup> +</sect1info> + +<title>Playing Music</title> +<indexterm><primary>Music</primary></indexterm> +<indexterm><primary>Sound</primary></indexterm> +<indexterm><primary>Audio</primary></indexterm> +<indexterm><primary>&arts;</primary></indexterm> + +<para>Intro to &arts;</para> + +<para>Performance tuning, sharing devices</para> + +<sect2 id="music-media-players"> +<title>Music Players</title> + +<para>There are several &kde; music players with somewhat overlapping +feature sets, however, each is quite different in style. </para> + +<variablelist> +<varlistentry> +<term> +<inlinemediaobject> +<imageobject><imagedata fileref="noatun-icon.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +&noatun; +<indexterm><primary>&noatun;</primary></indexterm> +</term> +<listitem> +<para>Noatun is the default &kde; music player. It features a highly +configurable interface, including several styles of playlist manager, and +many plugins to provide different &GUI;s, visualizations, and other +features.</para> +<para>&noatun; is part of the kdemultimedia package.</para> + +<para><mediaobject> +<imageobject><imagedata fileref="noatun.png" format="PNG"/> +</imageobject> +</mediaobject></para> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<inlinemediaobject> +<imageobject><imagedata fileref="juk-icon.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +&juk; +<indexterm><primary>&juk;</primary></indexterm></term> +<listitem> +<para>&juk; is a media manager, playlist manager, and metadata tagger. It is a +highly efficient way to manage all your music files, make and maintain +playlists, and maintain the metadata tags in your music.</para> +<para>It is equally useful as your primary music player, or managing +playlists and files for use in another application.</para> +<para>&juk; is part of the kdemultimedia package.</para> + +<para><mediaobject> +<imageobject><imagedata fileref="juk.png" format="PNG"/> +</imageobject> +</mediaobject></para> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<inlinemediaobject> +<imageobject><imagedata fileref="kaboodle-icon.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +&kaboodle; +<indexterm><primary>&kaboodle;</primary></indexterm></term> +<listitem> +<para>&kaboodle; is a one shot player. That means, it will run, play a file, +and stop. &kaboodle; is useful for instance if you want to quickly listen +to a single file without interupting your current playlist from another +media player.</para> +<para>&kaboodle; is part of the kdemultimedia package.</para> + +<para><mediaobject> +<imageobject><imagedata fileref="kaboodle.png" format="PNG"/> +</imageobject> +</mediaobject></para> + +</listitem> +</varlistentry> + +<varlistentry> +<term> +<inlinemediaobject> +<imageobject><imagedata fileref="amarok-icon.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +<application>amaroK</application></term> +<listitem> +<para><application>amaroK</application> is a popular third party application. You should be able to +find packages from your normal distribution source.</para> + +<para><mediaobject> +<imageobject><imagedata fileref="amarok.png" format="PNG"/> +</imageobject> +</mediaobject></para> + +</listitem> +</varlistentry> +</variablelist> + +<para>Most of the &kde; based movie players such as +<application>Kaffeine</application> and <application>kmplayer</application> +also make useful music players.</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + +</sect2> +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/printer-setup.docbook b/doc/userguide/printer-setup.docbook new file mode 100644 index 000000000..658be16ac --- /dev/null +++ b/doc/userguide/printer-setup.docbook @@ -0,0 +1,47 @@ +<sect1 id="printing"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Setting Up a Printer</title> + +<para>Assume everything is pre-configured, how to set up a printer, refer to +big manual if there is trouble</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/printing-from-apps.docbook b/doc/userguide/printing-from-apps.docbook new file mode 100644 index 000000000..975149cdb --- /dev/null +++ b/doc/userguide/printing-from-apps.docbook @@ -0,0 +1,40 @@ +<sect1 id="printing-from-apps"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Printing From Applications</title> + +<para>Printing from &kde; apps</para> + +<para>Printing from non-kde apps</para> + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/programs-and-documents.docbook b/doc/userguide/programs-and-documents.docbook new file mode 100644 index 000000000..c5eef682d --- /dev/null +++ b/doc/userguide/programs-and-documents.docbook @@ -0,0 +1,565 @@ +<chapter id="programs-and-documents"> + +<title>Programs and Documents</title> + +<sect1 id="programs-launching"> + +<sect1info> +<author> +<firstname>Robert</firstname> +<surname>Stoffers</surname> +</author> +</sect1info> + +<title>Launching Programs</title> + +<para>&kde; offers a varying number of ways to launch programs. You may:</para> + <itemizedlist> + <listitem> + <para>Simply select the relevant item in the &kmenu;.</para> + </listitem> + <listitem> + <para>Run the program from &konsole;, or by clicking the &kmenu; and choosing <guimenuitem>Run Command...</guimenuitem> (while you still might prefer the quick keyboard shortcut, which is simply <keycombo action="simul">&Alt;<keycap>F2</keycap></keycombo>).</para> + </listitem> + <listitem> + <para>Create a shortcut on the desktop or use &kicker;'s quick launcher.</para> + </listitem> +</itemizedlist> + +<para>The &kmenu; functions much like the Start menu of &Windows;, however +it breaks programs up by what they do. Programs on the &kmenu; are broken +into category menus, such as <guisubmenu>Multimedia</guisubmenu> and +<guisubmenu>Office</guisubmenu>. Under these category menus there are +subcategory menus, such as <guisubmenu>Sound</guisubmenu>, +<guisubmenu>Video</guisubmenu> and <guisubmenu>Graphics</guisubmenu>. Under +the subcategory menus lie program launchers, which, when clicked on, launch +the associated application.</para> + +<para>Depending on the program, there may not be a launcher in the &kmenu;. +To search your hard drive for more applications, click the &kmenu;, choose +<guimenuitem>Run Command</guimenuitem> and type +<userinput><command>kappfinder</command></userinput>. In +&kappfinder;, click <guibutton>Scan</guibutton>, and the hard drive will be +searched for programs. Click the checkbox next to each program to be added +to the &kmenu;, and click <guibutton>Apply</guibutton> and +<guibutton>Close</guibutton>. The &kmenu; now will have new program +launchers under the relevant category menus.</para> + +<para>Launchers to programs may also be placed on the desktop. To create a +new launcher, <mousebutton>right</mousebutton> click on the desktop, and +choose <menuchoice><guimenu>Create +New</guimenu><guimenuitem>Link to +Application</guimenuitem></menuchoice>. On the &kdesktop; properties dialog +box, type in the name of the program on the <guilabel>General</guilabel> +tab. You may also wish to choose a custom icon by clicking on the gear icon. +Click the <guilabel>Application</guilabel> tab and type a short sentence +about the program in the <guilabel>Description</guilabel> textbox. In the +<guilabel>Command</guilabel> textbox, type the name of the program (case +sensitive), and any command line options you wish to use. Choose +<guibutton>OK</guibutton>, and your new program launcher will be created on +your desktop. Simply click on the new launcher on the desktop and the + associated program will run.</para> + +<para>To launch a program using &konsole;, click the &kmenu; and choose +<menuchoice><guisubmenu>System</guisubmenu><guisubmenu>Terminals +</guisubmenu><guimenuitem>Konsole</guimenuitem></menuchoice>. Once &konsole; +appears on the screen, simply type the name of the program you wish to +launch (remembering that <application>bash</application>, the command language interpreter that &konsole; uses by default, is case-sensitive) and press +<keycap>Enter</keycap>. If you are unsure about the name of a program, type +the first few letters then press the 	 key on your keyboard. By pressing +	, <application>bash</application> (through &konsole;) will try to guess the name of the program you wish to +launch. If it finds more then one matching program, a list of + matching programs will be printed on the screen. Type the name of the + program from the list and press <keycap>Enter</keycap> to launch.</para> + +<para>Whichever way you choose, launching a program is a simple affair with +&kde;. From the &kmenu;, to &konsole;, all your programs are just a few +clicks or key-presses away.</para> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> +<listitem><para>Check the &kicker; handbook for more information on enabling or disabling the &kmenu;, adding applications to the quick launch, or on organizing the categorization of the applications in the &kmenu;. You can view the &kicker; handbook either via the &khelpcenter; or by using &konqueror;'s KIOslave by typing <userinput>help:/kicker</userinput> in the Location toolbar.</para> +</listitem> +</itemizedlist> + + + +</sect1> + +&programs-controlling; + +<sect1 id="programs-save-open"> + +<sect1info> +<author> +<personname> +<firstname>Christian</firstname> +<surname>Weickhmann</surname> +</personname> +<email>[email protected]</email> +</author> +</sect1info> + + +<title>Opening and Saving Files</title> +<!-- TODO: Convert this whole thing to an image with callouts. It --> +<!-- should be much nicer that way. --> + + +<para>&kde; provides a unified way to open or save files via the file +dialog. In almost every &kde; program you will find a +<menuchoice><guimenu>File</guimenu><guimenuitem>Open</guimenuitem> +</menuchoice> and <menuchoice><guimenu>File</guimenu> +<guimenuitem>Save</guimenuitem></menuchoice> (and/or <guimenuitem>Save +As...</guimenuitem>) entry.</para> + +<sect2 id="file-dialog"> +<title>The File Dialog</title> + +<!-- +<screenshot> +<screeninfo>The &kde; <quote>Open File</quote> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="open-file-dialog.png" format="PNG"/> </imageobject> +<textobject> +<phrase>The &kde; <quote>Open File</quote> dialog</phrase> +</textobject> +<caption> +<para>The &kde; <quote>Open File</quote> dialog</para> +</caption> +</mediaobject> +</screenshot> +--> +<screenshot> +<mediaobjectco> +<imageobjectco> +<areaspec units="calspair"> +<area id="navigation-area-co" coords="1 1"/> +<area id="icon-view-co" coords="1 1"/> +<area id="bottom-area-co" coords="1 1"/> +<area id="quick-access-co" coords="1 1"/> +<area id="preview-area-co" coords="1 1"/> +</areaspec> +<imageobject> +<imagedata fileref="open-file-dialog.png" format="PNG"/> +</imageobject> +</imageobjectco> +</mediaobjectco> +</screenshot> + +<!-- ====================================================================== + +<calloutlist> + +<callout arearefs="pt-first-channel-1"><para>This is called the <interface>Input Line</interface>. To send a message to everyone in the channel, type the message here and press &Enter;. + Your message, as well as everyone else's messages appear in the channel scroll above. + Each message is preceded by the time and user's &nickname;.</para></callout> + + +</calloutlist> + + + ====================================================================== --> +<para>This dialog consists of between three and five areas. The +top area is where you find the navigation and configuration functions. The +main area (in the middle) is where all your files are being displayed as +icons. This is called an icon view. The bottom area is where you can edit +filename or filter expressions and say <guibutton>Save</guibutton> or +<guibutton>Open</guibutton>.</para> + +<para>In addition to that you can add two even more sophisticated areas: +the <link linkend="quick-access">Quick Access Navigation Panel</link> and +the <link linkend="preview-area">Preview Panel</link>.</para> + +<calloutlist> + +<callout arearefs="navigation-area-co"> + +<para>Next to the three navigation buttons (one directory +<guiicon>up</guiicon>, <guiicon>back</guiicon> and +<guiicon>forward</guiicon>) and the <guiicon>new folder</guiicon> button +there is the <guiicon>bookmarks</guiicon> menu. Here you can mark any folder +you visit often to find it quickly. The <guiicon>wrench</guiicon> icon holds +the different functions to sort your files by name, date or size and to +enable the two extra panels mentioned above. Next to it you can type the +directory and choose (on the very right side) the encoding.</para> +</callout> + + +<callout arearefs="icon-view-co"> + +<para>You'll find the icon view in the middle of the dialog. You will find +most of the navigation functions in the context menu by clicking on the +items or the background with the <mousebutton>right</mousebutton> mouse +button.</para> + +</callout> + +<callout arearefs="bottom-area-co"> + + +<para>The bottom of the dialog consists of the address field holding the +file name you chose or typed in and the maybe most powerful tool: The +filter. Here you can make the icon view display only items that match the +criteria you define. Try filtering files whose names contain +<quote>air</quote> by typing <userinput>*air*</userinput> into the filter +field.</para> + +</callout> + +<callout arearefs="quick-access-co"> + +<anchor id="quick-access"/> + +<para>The Quick Access Panel (activate it by typing the +<keycap>F9</keycap> key on your keyboard or through the wrench icon on top +of the dialog) provides configurable shortcuts to frequently used +locations on your hard drive or even on the Internet. There are several +preconfigured locations such as your home directory. Try right clicking on +any item to configure it or to empty space to add a new entry. You will be +shown a context menu. Here you can choose the icon size and to add, modify +or rename any entry. Choose <guimenuitem>Add Entry</guimenuitem> and you +will see a window containing anything you need: Type your description, enter +the location (or choose it via the dialog opening by clicking on the +folder symbol), choose a symbol from a vast variety in the symbol dialog +opening when you click on the predefined icon (usually a simple folder +symbol).</para> + +</callout> + +<callout arearefs="preview-area-co"> + +<anchor id="preview-area"/> +<para>The Preview area (activate it by typing the <keycap>F11</keycap> +key on your keyboard or via the wrench icon on top of the dialog) +makes it easy to preview almost any file on your filesystem. Images +will be displayed as thumbnails. Usually also sound files (such as +MP3, Ogg or Wave-Files), text files (among them raw text, PDF and +&HTML;) and even video files (MPG, AVI and so on) will be +previewed.</para> + +<note><para>Note that large files might take a long time to be previewed +(⪚ scaled down if they are large images). You can disable automatic +previews by unselecting <guilabel>Automatic Preview</guilabel> below the +preview. You can still preview individual files: just click <guibutton>Preview</guibutton>. You can also disable previews for files above a certain +size. Go to &kcontrolcenter;, choose <menuchoice><guilabel>KDE +components</guilabel><guilabel>File manager</guilabel></menuchoice>, go to +the <guilabel>Preview and Metafiles</guilabel> tab and change the +<guilabel>Maximum Filesize</guilabel> value.</para></note> + +</callout> +</calloutlist> + +<!-- Add links to "further reading" here --> +<!--<itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + + </sect2> + + +</sect1> + +<sect1 id="configuring-programs"> +<sect1info> +<authorgroup> +<author> +&Philip.Rodrigues; +</author> +</authorgroup> +</sect1info> + +<title>Configuring Programs</title> + +<sect2 id="configure-kapp"> +<title>Application Configuration</title> +<!-- FIXME: Make a more friendly title --> +<indexterm><primary>Configuration</primary></indexterm> +<indexterm><primary>Customization</primary></indexterm> + +<para>&kde; applications are intended to be as useful and usable as +possible <quote>out of the box</quote>, but they also offer a wide +range of options which you can change to make &kde; work for you. As +well as the settings which affect the whole of &kde; (see <xref +linkend="control-center"/>), each application has a set of +configuration options, which you can access using the menu option +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +<replaceable>Application</replaceable></guimenuitem> +</menuchoice>. This is the same for all &kde; applications, which +makes it easy to find the configuration dialog for an +application.</para> + +<!-- TODO: Screenie of a typical config dialog --> + +<para>On the left of the configuration dialog is a list of +sections. Clicking on one of these sections displays the configuration +page for that section on the right-hand side of the dialog. You can +change these options to fit your preferences.</para> + +<para>When you have made the changes you want, you can click on +<guibutton>OK</guibutton> to save your changes and close the +configuration dialog. If you want to see the effect of your changes, +but not close the configuration dialog, click on the +<guibutton>Apply</guibutton> button. This is useful if you aren't sure +about the change you've made, and might want to change back, because +the dialog is still open, ready for you to do so.</para> + +<para>If you decide that you don't want to keep the changes you've +made, just click <guibutton>Cancel</guibutton> to close the dialog +without saving your changes.</para> + +</sect2> + +<sect2 id="configure-shortcuts"> +<title>Configuring Keyboard Shortcuts</title> + +<indexterm><primary>Shortcuts</primary></indexterm> +<indexterm><primary>Keybindings</primary></indexterm> + +<para>Most &kde; applications offer keyboard shortcuts for the main +actions in the application. If you find that you don't like the +default keyboard shortcuts, or that they conflict with the shortcuts +of another application (maybe one that's not part of &kde;), you can +change them with the +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Shortcuts...</guimenuitem> +</menuchoice> menu entry. This brings up the +<guilabel>Configure Shortcuts</guilabel> dialog for the +application. As an example of how to use this dialog, let's add a +shortcut for the <guimenuitem>Send Link Address...</guimenuitem> action to +&konqueror;, so that we can email the locations of interesting pages +to friends just by hitting a key (or two): </para> +<procedure> +<step><para>Open the <guilabel>Configure Shortcuts</guilabel> +dialog in &konqueror;, as described above.</para> +</step> +<step><para>Click on the <guilabel>Send Link Address...</guilabel> item +in the main listbox (it's near the bottom, in the +<guilabel>Konqueror</guilabel> section).</para> +</step> +<step><para>In the <guilabel>Shortcut for Selected +Action</guilabel> panel, select <guilabel>Custom</guilabel>, since we +are going to give this action a keyboard shortcut that we have chosen.</para> +</step> +<step><para>A small shortcut entry dialog pops up. Just hit +<keycombo action="simul">&Ctrl;<keycap>E</keycap> +</keycombo> (or whatever you want to change the shortcut to), and the +dialog disappears. The <quote>key</quote> icon in the +<guilabel>Configure Shortcuts</guilabel> dialog now shows the new +shortcut.</para> +</step> +<step><para>If you made a mistake, or change your mind about what +to use as the shortcut, just click on the key icon showing the current +shortcut. The shortcut entry dialog reappears, and you can press the +key combination for the shortcut you want.</para> +</step> +</procedure> + +<!-- TODO: Screenie --> + +</sect2> + +<sect2 id="configure-notifications"> +<title>Configuring Notifications</title> + +<indexterm><primary>Notifications</primary></indexterm> +<indexterm><primary>Sounds</primary></indexterm> + +<para>Something about +<menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure Notifications...</guimenuitem> +</menuchoice>.</para> +</sect2> + + +<sect2 id="configuring-toolbars"> +<sect2info> +<author> +<firstname>Adriaan</firstname> +<surname>de Groot</surname> +</author> +</sect2info> +<title>Configuring Toolbars</title> + +<para>Nearly every &kde; application has one or more toolbars at the top of +the application window, underneath the menu. The toolbar contains icons +(toolbar buttons) that represent commonly used actions and configuration +settings. The &kmail; window, for instance, has a toolbar that contains +buttons for <guiicon>New Message</guiicon>, <guiicon>Check Mail</guiicon> +and several others. Each of these actions is something you do often, so +that's why they have toolbar buttons as well as menu entries (<guiicon>New +Message</guiicon> is under +<menuchoice><guimenu>Message</guimenu><guimenuitem>New +Message</guimenuitem></menuchoice>, <guiicon>Check Mail</guiicon> is +<menuchoice><guimenu>File</guimenu><guimenuitem>Check +Mail</guimenuitem></menuchoice>).</para> + +<para>Not everybody agrees on what actions are commonly used, though, (I +never use the <guiicon>New Message</guiicon> toolbar button or the menu +item, I use the keyboard shortcut <keycombo +action="simul">&Ctrl;<keycap>N</keycap></keycombo>). To ensure that your +screen isn't cluttered with things you don't need, each toolbar can be +customized. Additionally, you can usually customize which toolbars are +displayed and how, as well.</para> + +<sect3 id="customizing-toolbar-displays"> +<title>Customizing Toolbar Displays</title> + +<para>The easiest thing to customize with the toolbars of any given +application is whether they are displayed at all. Most applications have a +<menuchoice><guimenu>Settings</guimenu><guisubmenu>Toolbars</guisubmenu> +</menuchoice> menu where you can select which toolbars are displayed and +which are not. &konqueror; has four toolbars, <interface>Main</interface>, +<interface>Extra</interface>, <interface>Location</interface> and +<interface>Bookmark</interface>. It can be convenient to turn off the +<interface>Bookmark</interface> toolbar to save +screen space. To do so, click on the <guimenu>Settings</guimenu> menu, +choose <guisubmenu>Toolbars</guisubmenu>, and then uncheck the +<guimenuitem>Bookmark Toolbar</guimenuitem> entry (do this just by clicking +on the menu item).</para> + +<para>If there is no <guimenu>Settings</guimenu> menu, you can also +<mousebutton>right</mousebutton> click on the toolbar itself, and choose the +<guisubmenu>Toolbars</guisubmenu> sub-menu from the resulting context +menu.</para> + +<para>The same <guimenu>Toolbar</guimenu> context menu, accessed by +<mousebutton>right</mousebutton> clicking on the toolbar, allows you to +customize other properties of the toolbar:</para> + +<itemizedlist> +<listitem> +<para>Its orientation, so that instead of appearing at the top of the +window under the menu bar you can place it on the left, right or bottom of +the window.</para> +</listitem> +<listitem> +<para>Its orientation, so that the toolbar <quote>floats</quote> as a +separate window which you can move independently.</para> +</listitem> +<listitem> +<para>Its orientation, so that the toolbar is squashed into a little flat +grip that you can re-open by double-clicking on it (this is subtly +different from making the toolbar vanish completely, since it it easier to +cause it to re-appear).</para> +</listitem> +<listitem> +<para>The appearance of text alongside, underneath, or instead of the icons +on the toolbar.</para> +</listitem> +<listitem> +<para>The size of the icons (if they are not supplanted by +text).</para> +</listitem> +</itemizedlist> +</sect3> + +<sect3 id="customizing-icons-on-toolbar"> +<title>Customizing the Icons on the Toolbar</title> + +<para>The toolbar is intended for actions that you perform often, so what do +you do if there is some useless icon there, like <guiicon>Cut</guiicon>? Or +what if you really want a <guiicon>cut</guiicon> button on the toolbar, but +the application doesn't give you one? This is where the customize toolbars +dialog comes in — it give you complete control over the actions that +are available on each toolbar.</para> + +<para>Choose <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure +Toolbars</guimenuitem></menuchoice> from the application's menu, or +<guimenuitem>Configure Toolbars</guimenuitem> from the context menu of the +toolbar itself. This displays the configure toolbars dialog, which consists +of a combobox <!-- drop-down box? --> with which you can select +<emphasis>which</emphasis> toolbar to customize, and two lists of items +— one of the available actions, and one of the actions that are +already in use on the toolbar.</para> + +<para>Often there are many many more actions available ( <guiicon>activate +tab #12</guiicon>, for instance) than you would ever want on the toolbar, or +even that you know exist in the application. The customize toolbar dialog +can be a learning experience. You can drag actions from one list box to the +other, rearrange the items on the toolbar <!-- in the list box on the right +..... not sure if I should be LTR-centric -->, or change the icon for a +selected action. This allows you to drag the actions you don't want off of +the toolbar and into the list of available actions; similarly, the actions +you do want can be dragged into the toolbar. Clicking +<guibutton>OK</guibutton> in the dialog immediately updates the toolbar with +your new preferred actions.</para> + +<para>There are a few special items that can end up in the listbox for the +current toolbar:</para> + +<itemizedlist> +<listitem> +<para>separators, which exist in two flavors: +<itemizedlist> +<listitem><para><guilabel>line separator</guilabel> appears as a line +between two action icons</para> +</listitem> +<listitem><para><guilabel>separator</guilabel> appears as a larger +space between two action icons</para> +</listitem> +</itemizedlist> +</para> +</listitem> +<listitem> +<para><guilabel><Merge></guilabel>, which is a special item that +allows plugins and other loadable components of the application to insert +their actions into the toolbar as well. It is generally not a good idea to +remove this, since you cannot get it back.</para> +</listitem> +<listitem> +<para><guilabel>ActionList:</guilabel>, these appear in various flavors +(there is a viewmode_toolbar one in &konqueror;) and again these +represent lists of actions that might be inserted by +plugins.</para> +</listitem> +</itemizedlist> + +<para>Whenever you click on an action in the list of current actions, a +description of it is shown in the dialog. This description will warn you if +it is a bad idea to remove the action.</para> + +<para>If you do not like to drag things around, there are four buttons in +the middle of the dialog which allow you to move the selected action from +one list to the other, and to move a selected current action up or down in +the list. There must be a way to restore the default toolbars in an +application, in order to recover from accidentally deleting an important +action like <guilabel><Merge></guilabel>, but I don't know what it +is.</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + +</sect3> +</sect2> + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/programs-controlling.docbook b/doc/userguide/programs-controlling.docbook new file mode 100644 index 000000000..a1f072e6f --- /dev/null +++ b/doc/userguide/programs-controlling.docbook @@ -0,0 +1,39 @@ +<sect1 id="programs-controlling"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Controlling Programs</title> + +<para>Standard Toolbar layout</para> + +<para>Keybindings</para> + +</sect1> +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/removable-disks.docbook b/doc/userguide/removable-disks.docbook new file mode 100644 index 000000000..7b07941e4 --- /dev/null +++ b/doc/userguide/removable-disks.docbook @@ -0,0 +1,140 @@ +<sect1 id="removable-disks"> + +<sect1info> +<authorgroup> +<author> +<firstname>Edward</firstname> +<surname>Haven</surname> +<email>[email protected]</email> +</author> +</authorgroup> +</sect1info> + +<title>Removable Disks</title> + +<para>For &kde; to use any device, removable or not, the device must +first be mounted. When a device is mounted, &kde; gets all the needed +information about the device: how to read it, how to write information to +it, and much more.</para> + +<para>The use of a device is controlled by the operating +system and it is important your operating system has tools for managing +these devices. &kde; can also auto mount devices, working with +<acronym>HAL</acronym> (Hardware Abstraction Layer). Your distribution +should have set up <acronym>HAL</acronym> automatically; if not, +consult the documentation provided by your distribution.</para> +<para>There are several ways to find the list of media devices: use +whichever one suits you best:</para> + +<itemizedlist> +<listitem> +<para>Enter <userinput>media:/</userinput> or +<userinput>system:/media</userinput> into the &konqueror; location bar.</para> +</listitem> + +<listitem> +<para>Navigate to it by clicking on the <guilabel>Services</guilabel> +tab in &konqueror;'s Navigation Panel, then selecting <guilabel>Storage +Media</guilabel>.</para> +</listitem> + +<listitem> +<para>Select <menuchoice><guimenu>Go</guimenu><guimenuitem>Storage Media</guimenuitem> +</menuchoice> from the &konqueror; menus.</para> +</listitem> + +<listitem> +<para>Click the <guilabel>System</guilabel> desktop icon, then from +the window that appears, click on <guilabel>Storage +Media</guilabel>.</para> +</listitem> + +</itemizedlist> + + +<para>The <guilabel>Storage Media</guilabel> location (also known as +the media:/ protocol) will show all devices which are recognized by +&kde;, including the hard drive and &CD; and <acronym>DVD</acronym> +drives, as well as <acronym>USB</acronym> and Firewire devices, +provided that your distribution is set up correctly to tell &kde; +about them.</para> + + + <para>You can also setup &kde; to display a device icon +on the desktop. To start or configure this feature in the &kcontrolcenter; go +to +<menuchoice><guilabel>Desktop</guilabel><guilabel>Behavior</guilabel></menuchoice> +and select the <guilabel>Device Icons</guilabel> Tab. The device icon action +can be used to show both mounted and unmounted devices, or to only create an +icon when media is detected and automounted (only if automount is properly +configured), by not checking the unmounted boxes.</para> + +<sect2 id="automounting"> +<title>Automount</title> + +<para>With &kde; 3.5 and newer, devices can be automounted, meaning one only +has to insert the removable disk. &kde; will then open an automount prompt +asking the user <quote>What do you want to do?</quote> with the media. To +configure the list of options prompted for devices open the &kcontrolcenter; and +navigate to <menuchoice><guilabel>Peripherals</guilabel><guilabel>Storage +Media</guilabel></menuchoice>. Here you can add and remove programs from the +list of devices.</para> + +<para>The automount feature will only work if +<application>dbus</application>, <application>hal</application> and +<application>udev</application> are installed and the kernel is properly +configured. To find out if they are running on your system check the +<guilabel>Process Table</guilabel> in &ksysguard; for: +<command>hald</command>, <command>dbus-deamon</command>, and +<command>udevd</command>. &kde; does not provide any of these +components. You must check with you distribution.</para> + +<itemizedlist> +<title>Related Information</title> +<listitem><para><ulink url="http://wiki.kde.org/tiki-index.php?page=DBUS">HOWTO: setting up D-BUS and HAL with KDE's media ioslave +edit</ulink> (A community maintained HOWTO on the &kde; wiki)</para></listitem> +<listitem><para><ulink url="http://www.freedesktop.org/wiki/Software/dbus">The DBus page</ulink></para></listitem> +<listitem><para><ulink url="http://www.freedesktop.org/wiki/Software/hal"></ulink>HAL - Hardware Abstraction Layer</para></listitem> +</itemizedlist> + +</sect2> + +<sect2 id="mounting-removable-disks"> +<title>Mounting</title> + +<para>If your system does not automount, &kde; is configured to mount and +unmount devices which the current user has permission to mount. If a device +is mounted as the root partition (&ie; <literal>/</literal>), and you log in +to &kde; as a user, &kde; can not mount or unmount it without being given a +higher permission. To check a devices mount permission see the +<filename>/etc/fstab</filename> file.</para> + +<para>To mount and unmount devices manually in &kde; one only has to &RMB; +click the device icon in media:/ or on the desktop and select +<guimenuitem>Mount</guimenuitem> or <guimenuitem>Unmount</guimenuitem>, for +removable devices one can also unmount with <guimenuitem>Safely Remove</guimenuitem>. &kde; still requires the device to be setup in +/etc/fstab.</para> +</sect2> + + + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/rip.png b/doc/userguide/rip.png Binary files differnew file mode 100644 index 000000000..0a044efb9 --- /dev/null +++ b/doc/userguide/rip.png diff --git a/doc/userguide/ripsettings.png b/doc/userguide/ripsettings.png Binary files differnew file mode 100644 index 000000000..21f53fbfd --- /dev/null +++ b/doc/userguide/ripsettings.png diff --git a/doc/userguide/screen-captures.docbook b/doc/userguide/screen-captures.docbook new file mode 100644 index 000000000..35d1a726a --- /dev/null +++ b/doc/userguide/screen-captures.docbook @@ -0,0 +1,38 @@ +<sect1 id="screen-captures"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Screen Captures</title> + +<para>Grabbing screen caps</para> + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/services.png b/doc/userguide/services.png Binary files differnew file mode 100644 index 000000000..d281c88b7 --- /dev/null +++ b/doc/userguide/services.png diff --git a/doc/userguide/shared-sessions.docbook b/doc/userguide/shared-sessions.docbook new file mode 100644 index 000000000..688a4b93f --- /dev/null +++ b/doc/userguide/shared-sessions.docbook @@ -0,0 +1,46 @@ +<sect1 id="shared-sessions"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>Shared Sessions</title> + +<para>Sharing your desktop with krfb and pals</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/splash-screen.png b/doc/userguide/splash-screen.png Binary files differnew file mode 100644 index 000000000..ccc6a29ea --- /dev/null +++ b/doc/userguide/splash-screen.png diff --git a/doc/userguide/standard-menu-entries.docbook b/doc/userguide/standard-menu-entries.docbook new file mode 100644 index 000000000..cfa37b453 --- /dev/null +++ b/doc/userguide/standard-menu-entries.docbook @@ -0,0 +1,319 @@ +<chapter id="menus"> +<chapterinfo> +<authorgroup> +<author> +&Philip.Rodrigues; +</author> +</authorgroup> +</chapterinfo> + + +<title>The Standard Menu Entries</title> + +<!-- FIXME: The text is immensely repetitive. Fix that. --> + +<para>One of the main ways that you'll control programs in &kde; is +via the program's menus. They provide access to nearly everything +you'll need to do with that program. So that you can more easily +remember where things are in the menus, and to help you learn new +programs more easily, the menus have a standard layout. This means +that once you know how to open a file in one program, you know how to +open a file in any &kde; program. Let's take a look at the standard +menus:</para> <!-- TODO: Note that programs have other menu entries as well--> + +<!-- Probably a good place for a screenie, but we'd need one showing +*only* the standard entries --> + +<variablelist> +<title>The <guimenu>File</guimenu> Menu</title> +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>N</keycap> +</keycombo> +</shortcut><guimenuitem>New</guimenuitem> +</menuchoice></term> +<listitem><para>This entry will start a new, blank document that's +appropriate to the program you're using. For example, in &kate; (the +&kde; Advanced Text Editor) this entry creates a new text file.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>O</keycap> +</keycombo> +</shortcut><guimenuitem>Open...</guimenuitem> +</menuchoice></term> +<listitem><para>The <guimenuitem>Open...</guimenuitem> menu entry +displays the &kde; <quote>Open File</quote> dialog box, where you can +choose a file to open in the program you're using. The <quote>Open +File</quote> dialog is also standardized, so it's the same for all +&kde; programs. You can find out more about using this dialog +somewhere else in this guide <!-- FIXME: real link -->.</para> +<para>You probably noticed that this menu entry had an ellipsis (...) +after the name of the entry. This means that clicking on the entry +will open a dialog box of some kind. If you make any changes in the +dialog box that appears, they won't take effect until you click on the +<guibutton>OK</guibutton> button in the dialog. You can always ignore +any changes you made, and close the dialog, by clicking on the +<guibutton>Cancel</guibutton> button.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>S</keycap> +</keycombo> +</shortcut><guimenuitem>Save</guimenuitem> +</menuchoice></term> +<listitem><para>This menu entry will save any changes you've made to +the file that you are currently working on. If this is the first time +that you've saved the file, the &kde; <quote>Save File</quote> dialog +will appear, and ask you for a name and location for the file. <!-- TODO: Point to another section for more info --></para> +</listitem> +</varlistentry> + + + +<varlistentry> +<term><menuchoice><guimenuitem>Save As...</guimenuitem> +</menuchoice></term> +<listitem><para>The <guimenuitem>Save As...</guimenuitem> menu entry +will save the file you're working on with a different name. The +<quote>Save File</quote> dialog appears, and you can choose a name and +location as usual. Note that after you save the file with +<guimenuitem>Save As..</guimenuitem>, you will be working on the +<emphasis>new</emphasis> file. If you save changes, they will be saved +under the new filename. To make this a bit clearer, let's take an +example: + +<orderedlist> +<listitem><para>You are working on a file called +<filename>hello.txt</filename> that contains the text <quote>Hello +World!</quote> </para> +</listitem> + +<listitem><para>You use the <guimenuitem>Save As...</guimenuitem> menu +entry to save the file with the new name +<filename>newhello.txt</filename>. </para> +</listitem> + +<listitem><para>You add the text <quote>Nice to see you!</quote> to +the file, and use the <guimenuitem>Save</guimenuitem> menu entry to +save these changes.</para> +</listitem> +</orderedlist> + + + +Now, the file <filename>newhello.txt</filename> contains the text +<quote>Hello World! Nice to see you!</quote>, while the file +<filename>hello.txt</filename> contains only the text <quote>Hello +World!</quote>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>P</keycap> +</keycombo> +</shortcut><guimenuitem>Print...</guimenuitem> +</menuchoice></term> +<listitem><para>This menu entry displays the &kde; +<quote>Print</quote> dialog, read to print the current +document. Youcan find more information about the options available in +this dialog in <xref linkend="printing-from-apps"/>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>W</keycap> +</keycombo> +</shortcut><guimenuitem>Close</guimenuitem> +</menuchoice></term> +<listitem><para>This menu entry closes the current document. If you +have made any changes since you last saved the document, you will be +asked whether you want to save those changes. You can choose to +<guibutton>Save</guibutton> or <guibutton>Discard</guibutton> those +changes. If you didn't really want to close the file, just click +<guibutton>Cancel</guibutton>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Q</keycap> +</keycombo> +</shortcut><guimenuitem>Quit</guimenuitem> +</menuchoice></term> +<listitem><para>Use this entry to close the program you're using. If +you have unsaved changes in any files, you will be asked whether you +want to +save them.</para> +</listitem> +</varlistentry> + + + +</variablelist> + +<variablelist> +<title>The <guimenu>Edit</guimenu> Menu</title> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>Z</keycap> +</keycombo> +</shortcut><guimenuitem>Undo</guimenuitem> +</menuchoice></term> +<listitem><para>Use this entry to remove the effect of the last +action you performed in the application. For example, if you deleted a +line of text, the <guimenuitem>Undo</guimenuitem> menu entry will +replace that line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;&Shift;<keycap>Z</keycap> +</keycombo> +</shortcut><guimenuitem>Redo</guimenuitem> +</menuchoice></term> +<listitem><para>Use this menu entry to perform the last action that +you removed with the <guimenuitem>Undo</guimenuitem> menu entry. For +example, if, as in the example above, you had replaced a deleted line +of text with <guimenuitem>Undo</guimenuitem>, the +<guimenuitem>Redo</guimenuitem> entry would redo the action of +deleting the line.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>X</keycap> +</keycombo> +</shortcut><guimenuitem>Cut</guimenuitem> +</menuchoice></term> +<listitem><para>This menu entry cuts the contents of the current +selection to the clipboard. See <xref linkend="using-the-clipboard"/> +for more information. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>C</keycap> +</keycombo> +</shortcut><guimenuitem>Copy</guimenuitem> +</menuchoice></term> +<listitem><para>This menu entry copies the contents of the current +selection to the clipboard. See <xref linkend="using-the-clipboard"/> +for more information. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>V</keycap> +</keycombo> +</shortcut><guimenuitem>Paste</guimenuitem> +</menuchoice></term> +<listitem><para>This menu entry inserts the contents of the clipboard +in the current document. The clipboard contents are inserted where the +cursor is currently positioned.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>A</keycap> +</keycombo> +</shortcut><guimenuitem>Select All</guimenuitem> +</menuchoice></term> +<listitem><para>Use this item to select the whole of the current +document.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul">&Ctrl;<keycap>F</keycap> +</keycombo> +</shortcut><guimenuitem>Find...</guimenuitem> +</menuchoice></term> +<listitem><para>This menu entry displays the <guilabel>Find +Text</guilabel> dialog, which you can use to search for a particular +word or phrase in the current document. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><shortcut><keycombo action="simul"><keycap>F3</keycap> +</keycombo> +</shortcut><guimenuitem>Find Next</guimenuitem> +</menuchoice></term> +<listitem><para>Use this item to find the next occurrence of the most +recent text you searched for using <guimenuitem>Find...</guimenuitem>. +</para> +</listitem> +</varlistentry> + +</variablelist> + +<variablelist> +<title>The <guimenu>Settings</guimenu> Menu</title> + +<varlistentry> +<term><menuchoice><guimenuitem>Configure Shortcuts...</guimenuitem></menuchoice></term> +<listitem><para>In the dialog displayed by this menu entry, you can +change the keyboard shortcuts used by the application. See <xref +linkend="configure-shortcuts"/>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Configure +Toolbars...</guimenuitem></menuchoice></term> + +<listitem><para>In the dialog displayed by this menu entry, you can +change which buttons appear on the application's toolbars. See <xref +linkend="configuring-toolbars"/>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Configure Notifications...</guimenuitem></menuchoice></term> +<listitem><para>In the dialog displayed by this menu entry, you can +change the notifications (sounds, error messages, &etc;) used by the +application. See <xref +linkend="configure-notifications"/>. +</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><menuchoice><guimenuitem>Configure <replaceable>Application</replaceable></guimenuitem></menuchoice></term> +<listitem><para>In the dialog displayed by this menu entry, you can +change settings relating to how the application works in general. +</para> +</listitem> +</varlistentry> + +</variablelist> + + +&help.menu.documentation; + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/switching-sessions.docbook b/doc/userguide/switching-sessions.docbook new file mode 100644 index 000000000..d869d0808 --- /dev/null +++ b/doc/userguide/switching-sessions.docbook @@ -0,0 +1,92 @@ +<sect1 id="switching-sessions"> + +<sect1info> +<author> +<personname> +<firstname>Christian</firstname> +<surname>Weickhmann</surname> +</personname> +<email>[email protected]</email> +</author> +</sect1info> + + +<title>Switching Sessions</title> + +<para>From version 3.3 onwards, &kde; provides a session management +system which allows you to switch between different user account on +one computer. You can stay logged in and ⪚ let your sister, +brother, wife, neigbour or whoever read her or his emails just for a +moment. Before you had to log off (therefore ⪚ close programs or +save documents) and let her or him log in.</para> + +<para>Now it's almost as easy as switching to another virtual desktop.</para> + +<variablelist> +<title>Switching Sessions: How it works</title> + +<varlistentry> +<term>The <guimenuitem>Switch User</guimenuitem> Menu</term> +<listitem> +<para>The &kmenu; now bears a new entry. Rather at the bottom of the menu +you will find a <guisubmenu>Switch User</guisubmenu> submenu. It contains +the command to lock the current and start a new session which means that +your desktop will start the screensaver and after a few seconds can log in +with KDM as always. The <guimenuitem>Start New Session</guimenuitem> entry +skips the activation of your screensaver.</para> + +<para>Once you have running more than one session you can either choose to +press <keycombo action="simul">&Ctrl;&Alt;<keycap>F7</keycap></keycombo> + or <keycap>F8</keycap> and so on (what is usually configured by default) or +— even more comfortable — choose from the list of active +sessions at the bottom of the <guisubmenu>Switch User</guisubmenu> +submenu.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Switch User with the screensaver</term> +<listitem><para>If you have activated your screensaver and another user +wants to log in she or he can simply press the <guibutton>Switch +User...</guibutton> button and log into another session.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term>Switch Session in &kdm;</term> +<listitem><para>If you are in &kdm; and want to switch to another active +session you can press the <guibutton>Menu</guibutton> button and choose +<guisubmenu>Switch User</guisubmenu> which is mainly the same as described +above.</para> +</listitem> +</varlistentry> +</variablelist> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/the-filemanager.docbook b/doc/userguide/the-filemanager.docbook new file mode 100644 index 000000000..a56628cf8 --- /dev/null +++ b/doc/userguide/the-filemanager.docbook @@ -0,0 +1,291 @@ +<sect1 id="file-manager"> + +<sect1info> +<authorgroup> +<author> +<firstname>Christian</firstname> +<surname>Weickhmann</surname> +</author> +</authorgroup> +</sect1info> + +<title>The File Manager</title> +<indexterm><primary>&konqueror;</primary><secondary>File +Management</secondary></indexterm> +<indexterm><primary>File Management</primary></indexterm> + +<mediaobject> +<imageobject> +<imagedata fileref="konq-simple.png" format="PNG" /> +</imageobject> +<caption><para>&konqueror; with simple settings</para></caption> +</mediaobject> + +<sect2 id="filemanager-intro"> +<title>Introduction</title> + +<para>&kde; includes a versatile and powerful file manager called +&konqueror; which allows you to do everything you want with the files +stored on your computer, your network, and even the Internet. There +are too many features of &konqueror; to describe here, so we will just +take an overview. If you want more details about what &konqueror; can +do, take a look at the &konqueror; Handbook<indexterm><primary>&konqueror;</primary><secondary>Handbook</secondary></indexterm> by selecting +<menuchoice><guimenu>Help</guimenu><guimenuitem>Konqueror +Handbook</guimenuitem></menuchoice> in the &konqueror; menus; or, alternatively, you can use the help KIOslave in &konqueror; by entering <userinput>help:/konqueror</userinput> in the Location Toolbar.</para> +</sect2> + +<sect2 id="folder-structure"> +<title>Folders</title> + +<para>When you first open &konqueror; in file management mode, you can +see two panes: on the right is the folder view; on the left is the +sidebar. The folder view contains icons for +each item inside the current folder. These items can be +folders or files. Many file types can be <quote>previewed</quote> +without opening a new application to edit them in.<indexterm><primary>Previews</primary></indexterm> To preview a file, +hold the mouse cursor over the name of the file for about a second: a +popup window will appear, showing the contents of the file and other some +useful information, like file's size and which user owns the file.</para> + +<para>You can open any item by clicking (just once – &kde; +does not use double-clicking in its default settings) on the icon for the +file. Folders will be opened in the same window; files will either be +opened in the appropriate program, or the file manager will ask you +what program to use. For instance, if do not have a word-processor set up to +open &Microsoft; Word documents, the file manager will +ask you what to do.</para> + +<para>You can go back to the last-opened folder by clicking on the +<guiicon>Back</guiicon><!--screenie --> button or go up one folder by clicking +the <guiicon>Up</guiicon><!--screenie --> button.</para> +</sect2> + +<sect2 id="the-navigation-panel"> +<title>The Navigation Panel (aka <quote>The Sidebar</quote>)</title> + +<indexterm><primary>Navigation Panel</primary></indexterm> +<indexterm><primary>Sidebar</primary></indexterm> + +<mediaobject> +<imageobject> +<imagedata fileref="konq-sidebar.png" format="PNG" /> +</imageobject> +<caption><para>The &konqueror; sidebar</para></caption> +</mediaobject> + +<para>Navigating through the folders by using +the folder view can become impractical. The sidebar provides +shortcuts and special functions that make it easier to +find what you are searching for.</para> + +<para>On the left edge of the sidebar you will find a number of buttons, each + with a different icon:</para> + +<!-- TODO: Add screenies of what each of these buttons looks like --> +<variablelist> + +<varlistentry> +<term><guilabel>Bookmarks</guilabel></term> + +<listitem> +<para>As &konqueror; (the file manager) also serves as a very powerful +web browser, it also has a bookmark functionality. Here you will find the +same structure as in your <guimenu>Bookmarks</guimenu> menu.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Devices</guilabel></term> + +<listitem> +<para>Next the sidebar provides a list of all known devices +on your computer. These devices can be either physical drives — +such as your hard disk, &CD-ROM; drive, or floppy disk drive — +or virtual <quote>drives</quote> — such as remote shares or hard disk partitions.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>History</guilabel></term> + +<listitem> +<para>&konqueror; will remember the web pages you have visited and list them +either by date or alphabetically in a tree structure. You can select the +behavior by right clicking on the <guilabel>History</guilabel> item and +selecting <guimenu>Sort by</guimenu>. Left click on an item (⪚ +<guilabel>www.kde.org</guilabel>) and &konqueror; will show you the documents you have visited. Left +clicking on a document (⪚ <guilabel>index.html</guilabel>) will open +the web site in the folder view.</para> +<para>Right clicking on a history item, like <menuchoice><guimenu>www.kde.org</guimenu><guimenuitem>index.html</guimenuitem> +</menuchoice>, opens a slightly different popup menu: you will also find the +item <guimenuitem>New Window</guimenuitem>, which makes &konqueror; open the +site in a new window.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Home Directory</guilabel></term> + +<listitem> +<para>The <guilabel>Home Directory</guilabel> item is in the sidebar's navigation +panel. You will find your home directory as the first entry. Below you will +find all folders of your home directory. Left clicking on any +folder in this view opens the folder in the folder view. Alternatively, you can also +work with the folders' context menus, create subfolders, and so on.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Sidebar Media Player</guilabel></term> + +<listitem> +<!-- TODO: think of a better solution for marking up the file --> +<!-- formats. It should probably involve entities --> +<para>Try dragging a music file (like <acronym>MP3</acronym>, Ogg, or +<literal role="extension">.wav</literal> files) +on the sidebar. The file will immediately be played.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Newsticker</guilabel></term> +<!-- I don't have this button. Ought to check what it depends on --> +<listitem> +<para>Newsticker will display a customisable list of news sources. Right-click +either on the <guilabel>Configure button</guilabel> or on one of the +newssource buttons (e.g. KDE News, which is usually predefined) to add a new +newsticker source.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Network</guilabel></term> + +<listitem> +<para>Here you can browse the services provided by other computers on +the network. The &lisa;-Daemon has to be started in order to work +correctly. The network browser allows you to see a variety of services +provided by a computer. You can easily browse <acronym>SMB</acronym> +shares, &HTTP; sites, or transfer files via the secure FISH +layer.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Root Directory</guilabel></term> + +<listitem> +<para>Everything on a &UNIX;-based system is organized in a file +system tree. This tree must have a root and here it is. The +<guilabel>Root Directory</guilabel> function is like the +<guilabel>Home Directory</guilabel> function. The only difference is +that every folder is being displayed, not only your home +directory.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Services</guilabel></term> + +<listitem> +<para>This is somehow the "rest". Try browsing through the different +items. If an Audio &CD; is in your &CD; or <acronym>DVD</acronym> +drive you will be able to find everything on it and even more in the +<guilabel>Audio CD Browser</guilabel> item (you can even compress +audio files and save them on your hard drive with this +function).</para> +</listitem> +</varlistentry> + +</variablelist> +</sect2> + +<sect2 id="filemanager-icons"> +<title>Icons</title> + +<para> +To select only one icon hold down the &Ctrl; key and click on the icon +you want to select. If you want to select more than one icon, hold +down &Ctrl; while you click on each of the items you want to select. +Once one or more icons are selected you can do what you want with +them. If you want to move or copy items, select them and then drag them +(with the left mouse button down) to the desired location. When +you release the mouse button a menu will come up offering you to +<guimenuitem>Move</guimenuitem><indexterm><primary>Moving +Files</primary></indexterm>, +<guimenuitem>Copy</guimenuitem><indexterm><primary>Copying +Files</primary></indexterm>, or <guimenuitem>Link</guimenuitem> the +selected items. You can also <guimenuitem>Cancel</guimenuitem> your +action. +</para> + +<para>Many other actions can be applied to the selected items by +right-clicking on one of the selected items, and choosing the action +from the menu which appears. (The exact contents of this menu depend on the +type of files selected, so it is called a <quote>context menu</quote>).</para> +</sect2> + +<sect2 id="links"> +<title>Links and Shortcuts</title> + +<para> +As already mentioned above you can link files or folders anywhere. It means +that the linked folder will appear and behave just like the original in +another location without consuming additional space on your harddrive. +So if you, for example, have a number of documents, and only a few are used +regularly, you can easily group them in a folder and create links in it. +</para> + +</sect2> + +<sect2 id="trash"> +<title>The Trash</title> + +<indexterm><primary>Trash</primary></indexterm> +<indexterm><primary><quote>Recycle Bin</quote></primary></indexterm> + +<para>Before a file is deleted in the &kde; file manager it will be +moved to the <filename>Trash</filename> folder to give you the +possibility of getting it back if you deleted it by accident. The +trash bin will show all deleted items. You can select the one to be +recovered and move it to its original place as described in <xref +linkend="filemanager-icons" />. If you right click on the trash bin and select +<guimenuitem>Empty trash bin</guimenuitem> the files in it will be +deleted permanently.</para> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> + +<listitem><para>As mentioned in the introduction, the &konqueror; +Handbook has much more information about the features available in +&konqueror;. You can read it in &khelpcenter; or by entering +<userinput>help:/konqueror</userinput> in &konqueror;'s +<guilabel>Location</guilabel> bar.</para> +</listitem> + +</itemizedlist> + + +</sect2> +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> + + diff --git a/doc/userguide/titlebar-menu.png b/doc/userguide/titlebar-menu.png Binary files differnew file mode 100644 index 000000000..d9d672982 --- /dev/null +++ b/doc/userguide/titlebar-menu.png diff --git a/doc/userguide/troubleshooting-network-x.docbook b/doc/userguide/troubleshooting-network-x.docbook new file mode 100644 index 000000000..45c55196c --- /dev/null +++ b/doc/userguide/troubleshooting-network-x.docbook @@ -0,0 +1,41 @@ +<sect1 id="troubleshooting-network-x"> +<sect1info> +<authorgroup> +<author>&J.Hall;</author> +</authorgroup> +</sect1info> +<title>Networking and X</title> +<para> +Misconfigured networking can often be the cause of &kde; applications launching slowly, or in the worst case not launching at all. Your &X-Server; has a very powerful client/server interface and is very network aware. +</para> +<para> + X uses the hostname to create both a unique key for authorization, and to figure out where (via $<envar>DISPLAY</envar>) to send + the actual windows it's drawing on screen. If your computer doesn't know it's own name, it will spend inordinate amounts of time + trying to look itself up, a fate you can avoid by simply teaching your computer what it's own name is. +</para> +<para> +Check your <filename>/etc/hosts</filename> file and ensure there is an entry for localhost that looks +something like this at the top of the file (after any comments). +</para> +<screen> +127.0.0.1 localhost +</screen> +<para> +You also should add your computers fully qualified domain name, short name, and it's usual ip address if it has a static ip. If your ip address is assigned dynamically using <acronym>DHCP</acronym> you can simply use the address for the loopback device. +</para> +<screen> +127.0.0.1 hal.btl hal (for dhcp) +192.168.0.1 hal.btl hal (static) +</screen> +<para> +Make sure that your firewall is not so restrictive that it stops packets to the loopback device. For example in iptables if the default rule on the <parameter>INPUT</parameter> chain for this device is set to anything other than <parameter>>ACCEPT</parameter> this will cause performance problems in X. To check this, you can type in: +</para> +<screen> +<prompt>%</prompt><userinput><command>iptables-save</command> <literal>|</literal> <command>grep</command> <option>lo</option></userinput> +<computeroutput><option>-A</option> <parameter>INPUT</parameter> <option>-i</option> <parameter>lo</parameter> <option>-j</option> <parameter>ACCEPT</parameter> +</computeroutput> +</screen> +<para> +The rule <computeroutput><option>-A</option> <parameter>INPUT</parameter> <option>-i</option> <parameter>lo</parameter> <option>-j</option> <parameter>ACCEPT</parameter></computeroutput> should always work, unless there are other misconfigured rules (Such as a <parameter>DROP</parameter> on the <parameter>OUTPUT</parameter> chain) +</para> +</sect1> diff --git a/doc/userguide/troubleshooting-no-open.docbook b/doc/userguide/troubleshooting-no-open.docbook new file mode 100644 index 000000000..682f4b675 --- /dev/null +++ b/doc/userguide/troubleshooting-no-open.docbook @@ -0,0 +1,49 @@ +<sect1 id="troubleshooting-not-opening"> +<sect1info> +<authorgroup> +<author>&Lauri.Watts;</author> +</authorgroup> +</sect1info> +<title>When An Application Will Not Open</title> + +<para>Sometimes when you start an application, it does not open the expected +window. Here are some questions to answer and steps to help you figure out +what is wrong.</para> + +<variablelist> +<varlistentry> +<term>Did the application ever start, when launched in the same +manner?</term> +<listitem><para>If it did, for instance you have clicked an icon on your +desktop that previously worked, then it is unlikely to be a problem with the +launcher itself.</para> +<para>If, however, you normally start your application from an icon on +&kicker; and this time started it with a desktop icon, then it could simply +be that the launcher itself is wrong.</para> +</listitem> +</varlistentry> +<varlistentry> +<term>But I can see the launch notification spinning cursor and taskbar entry. +</term> +<listitem><para>Foo</para></listitem> +</varlistentry> +</variablelist> +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/under-the-hood.docbook b/doc/userguide/under-the-hood.docbook new file mode 100644 index 000000000..094a01d63 --- /dev/null +++ b/doc/userguide/under-the-hood.docbook @@ -0,0 +1,521 @@ +<chapter id="tinkering-under-the-hood"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<chapterinfo> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</chapterinfo> +--> + +<title>Tinkering Under the Hood of &kde;</title> + +<sect1 id="hand-editing-config-files"> + +<sect1info> +<author> +<personname> +<firstname>Nicolas</firstname> +<surname>Goutte</surname> +</personname> +<email>[email protected]</email> +</author> +</sect1info> + +<title>Hand-Editing Configuration Files</title> + +<sect2 id="hand-editing-intro"> +<title>Introduction</title> +<para>In &kde;, the configuration files are easy to edit with a simple +editor like &kate; as the configuration files are text files.</para> + +<para>An example of a text file:</para> + +<programlisting>[General] +AutoSave=1 +LastFile=/var/tmp/test.txt</programlisting> + +<para>The user-specific configuration files are stored in <filename +class="directory">.kde/share/config</filename> (replace +<filename>.kde</filename> with your $<envar>KDEHOME</envar> setting) and +the global ones are in the <filename +class="directory">share/config</filename> sub-directory of &kde;'s +installation path. (You can find this path by running the command +<command>kde-config --prefix</command>.) Their filenames typically +end in rc (without an initial period), for example <filename>kopeterc</filename>.</para> + +<warning><para> +Editing configuration files by hand can risk the stability of your +&kde; installation. Applications usually do not check what they read from the +configuration files. This means that they can be disturbed by what they +get as configuration and might even +crash.</para></warning> + +</sect2> + +<sect2 id="hand-editing-backups"> +<title>Backups</title> + +<para>So the first rule is to make a backup of your file before modifying +it. The backup is better stored outside any +<filename class="directory">.kde</filename> subdirectory +(or the corresponding $<envar>KDEHOME</envar> directory). Backups are anyway +a good idea in case of a major failure of &kde; that would +destroy important configuration files (for example your &kmail; settings, +which are in in the file <filename>kmailrc</filename>). +(Such a major failure should not happen but it still can happen.)</para> +</sect2> + +<sect2 id="hand-editing"> +<title>Editing</title> + +<para>So why would you want to touch the configuration files at all? Well, first you need it +when you want to enforce the KIOSK mode. Perhaps a developer has asked you +to add an entry to help him to solve a problem with the application. Perhaps you want to recover from +a problem without having to remove all the <filename +class="directory">.kde</filename> directory. Perhaps you want to learn more +about the depths of &kde;.</para> + +<para>Anyway, whatever your reason, you want to modify by hand a +configuration file.</para> + +<para>When planning to edit such a file, make sure that the application +using it is not running. If it is one of the basic configuration files, +consider editing the file while &kde; is not running at all.</para> + +<para>Ready? So make a backup of the file (Did I tell you this already?), +start you favorite editor (let us assume it is &kate;), load the file +(Be careful to load as UTF-8, &kate; displays it as +<quote>utf8</quote>).</para> + +<para>Now you have a file like:</para> + +<programlisting>[Group] +Key1=Value1 +Key2=Value2 +Key3=Value3</programlisting> + +<para>You can now modify it (with care!) and then save it (Be sure that it +is as <acronym>UTF-8</acronym> again).</para> + +<para>Now you can test the application and if the application does not run +correctly anymore, close the application and restore the backup of the +configuration file.</para> + +<itemizedlist> +<title>Related Information</title> + + +<listitem><para><xref linkend="kde-for-administrators"/> has more +information about &kde;'s directory structure, to help you find the +file you need to edit.</para> +</listitem> + +</itemizedlist> + +</sect2> + +</sect1> + +<sect1 id="scripting-the-desktop"> +<title>Scripting the Desktop</title> + +<para>&kde; provides a powerful interprocess communication system in +&DCOP;, the Desktop COmmunication Protocol. Using &DCOP;, you can +control a wide range of functions in &kde; from the command line or +from a script written in your favorite scripting language. You can +also get information out of &kde; applications: for example, several +&kde; media players provide methods to query the player for +information about the currently-playing track.</para> + +<para>Broadly speaking, each &kde; application provides one or more +&DCOP; <firstterm>interfaces</firstterm>, which in turn provide +methods (or, if you prefer, functions) that another application can +call. So, the first step in using &DCOP; is to find the appropriate +method for the task. The easiest way to do this is using the +<application>kdcop</application> frontend to the available &DCOP; +methods.</para> + +<para>Run <application>kdcop</application> from a &konsole; or the +mini-<acronym>CLI</acronym> (the window which pops up on <keycombo +action="simul">&Alt;<keycap>F2</keycap> </keycombo>). The +<application>kdcop</application> window shows the applications +currently running which provide &DCOP; interfaces, using a tree +view. +<!-- TODO: Describe the search lineedit thingy --> +In general, finding the correct method requires a little bit of +searching through the tree view, but a useful hint is that the +interface marked <quote>(default)</quote> usually contains the most +frequently-used functions.</para> + + + +<para>To test that the function does what we expect, double-click on +the <guilabel>setColor</guilabel> entry. To set the color +<varname>c</varname>, click on the color selector button, and choose a +color. Set whether the color should be color A with the +checkbox. Click <guilabel>OK</guilabel> and the background color is +set.</para> + +<para>To access the &DCOP; method from your favorite scripting +language, you can either use &DCOP; bindings, if available in the +kdebindings module, or call the <command>dcop</command> command-line +application. For simple usage, calling the +<command>dcop</command> command-line application is sufficient. To +call a &DCOP; method on the command line, we need to specify the +application and interface owning the method, the method itself, and +the arguments, in a form suitable for the shell.</para> + +<para>We specify the application, interface and method in that order, +followed by the arguments in the same order that they are shown in +<application>kdcop</application>. <command>dcop</command> +has plenty of other options: take a look at the output of +<userinput><command>dcop</command> +<option>--help</option></userinput>.</para> + +<para>That's enough theory: time for an example:</para> + +<example> +<title>A Background Color Changing Script with &DCOP;</title> + +<para>With the <command>dcop</command> command-line application and a +little bit of Perl, we're going to make a simple script which slowly +cycles the desktop background through the spectrum.</para> + +<para>Firstly, we look for the appropriate method with +<application>kdcop</application>. For this example, we'll short +circuit the searching, and go straight to it: the method we want is +<menuchoice><guimenu>kdesktop</guimenu><guisubmenu>KBackgroundIface</guisubmenu><guimenuitem>setColor</guimenuitem> +</menuchoice>. The arguments and return type of the function are shown +in the style of the C++ language. For +<methodname>setColor</methodname>, the arguments are a color, +<varname>c</varname>, which specifies the new background color, and a +boolean (true or false) value, <varname>isColorA</varname>, which +specifies whether the color is the first or second (this is useful for +setting gradients and so on).</para> + +<para>To use our <methodname>setColor</methodname> method on the +command line, we use the following: + +<screen> +<prompt>%</prompt> <userinput><command>dcop</command> kdesktop KBackgroundIface setColor '#ffffff' false</userinput> +</screen> +</para> + +<para>To specify the color, we used the +hexadecimal RGB value, as used in &HTML;. Note that it is enclosed in +single quotes to protect the <token>#</token> from the shell.</para> + +<para>To find the hexadecimal RGB value of a color, open any +color chooser dialog in a &kde; application (for example, in +&kcontrolcenter;, <menuchoice><guimenu>Appearance & Themes</guimenu><guimenuitem>Colors</guimenuitem> +</menuchoice>), select the color you want, and use the value given in +the <guilabel>HTML</guilabel> text box.</para> + + +<para>So, that's all we need from &DCOP;; now it's just a case of +writing a script around it. Here's a (very!) rough implementation: + +<programlisting> +<![CDATA[ +$min=49; # Minimum value of R, G, or B colour +$max=174; # Maximum value of R, G, or B colour +$step=5; # Amount to step colour by on each step +$sleeptime=15; # Interval in seconds between each step + +@start = ($max, $min, $min); +@colour = @start; + +while (1) { + foreach (0..5) { + my $which = $_ % 3; # Which colour (R, G or B) to change + my $updown = $_ % 2; # Whether to increase or decrease the colour value + do { + if ($updown == 0) { $colour[$which]+=$step; } + if ($updown == 1) { $colour[$which]-=$step; } + my $dcopcall=sprintf "dcop kdesktop KBackgroundIface setColor '#%x%x%x' true\n", @colour; + system($dcopcall); + sleep $sleeptime; + } while (($colour[$which] >= $min) and ($colour[$which] <= $max)); + } +} +]]> +</programlisting> +</para> + +<para>Just run the script with no arguments, and it will cycle the +background colour through a slightly muted spectrum until it is +killed. <foreignphrase>Voilà</foreignphrase>!</para> + +</example> + +<para>Of course, Perl isn't the only language you can use to write +scripts with &DCOP;—if you prefer shell scripting, that's +available too:</para> + +<example> +<title>Setting a background from the Internet</title> + +<para>The following script gets the main image from the <quote>User +Friendly</quote> comic strip and sets it as the desktop wallpaper, +using commonly available tools and a little bit of &DCOP;:</para> + +<programlisting> +<![CDATA[ +#!/bin/sh +COMICURL=`wget -qO - http://www.userfriendly.org/static/index.html | \ + grep Latest | sed -e "s,.*SRC=\",," -e "s,\">.*,,"` +TMPFILE=`mktemp /tmp/$0.XXXXXX` || exit 1 +wget -q -O $TMPFILE $COMICURL +dcop kdesktop KBackgroundIface setWallpaper $TMPFILE 1 +]]> +</programlisting> + +<para>The first line after the #!/bin/sh uses <command>wget</command> and some regular +expression magic to extract the image location from the main page's +&HTML; source. The second and third lines download the image, and +finally, <command>dcop</command> sets the downloaded image as +wallpaper.</para> + +</example> + + +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist> --> + + +</sect1> + + +<sect1 id="adding-extra-keys"> +<title>Adding Extra Keybindings to &kde;</title> + +<para>Many modern keyboards contain extra keys that are not by default +assigned to any action.</para> + +<para><quote>Multimedia</quote> keys often generate a signal, and can simply +be chosen as a keybinding within an application just like choosing any other +key. Some keys however, are not detected and pressing them in a +<guilabel>Configure Shortcuts</guilabel> has no effect.</para> + +<para>Some IBM laptops, for instance, have extra keys about the left and right +arrows, which look like <guiicon>page left</guiicon> and <guiicon>page +right</guiicon>.</para> + +<procedure> +<step><para>Use <command>xev</command> to find the code of the keys. In +this case, they are 233 and 234 <!-- TODO: Very briefly how to use xev here --> +</para></step> +<step><para>Choose key symbols. There are quite a range of these that are not +used by default, so many are free. You can find the list in +<filename>/usr/X11R6/include/X11/keysymdef.h</filename> (or its equivalent +on your system).</para></step> +<step><para>Create a file in your home directory called +<filename>.Xmodmap</filename>, and add to it the following:</para> +<screen>keycode 233 = Next_Virtual_Screen +keycode 234 = Prev_Virtual_Screen</screen> +</step> +<step><para>Run the command <userinput><command>xmodmap</command> +<filename>~/.Xmodmap</filename></userinput></para></step> +</procedure> + +<para>At this point, you should be able to run <command>xev</command> again +and see that the keys now generate the keysym that you assigned. You can now +simply assign them to any action as normal.</para> + +<itemizedlist> +<title>Related Information</title> +<listitem><para>The <command>xev</command> manpage. You can see this by typing +<userinput>man:/xev</userinput> into a &konqueror; window or by typing +<userinput><command>man</command> xev</userinput> into a terminal.</para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="keys-for-scripts"> +<title>Adding Keybindings for New Actions</title> + +<para>Most actions in either the desktop or in applications are readily +available to assign a keybinding to. If the action you want a +shortcut for is something you wrote yourself, or is otherwise not available, +you can still assign a shortcut.</para> + +<para>To bring together the two previous sections, perhaps you want to +assign an otherwise unused key on your keyboard to a script or dcop +command. Our example here will be to assign the two keys we added +in <xref linkend="adding-extra-keys"/> to go to the previous or +next virtual desktop, two functions for which you will need DCOP (as discussed in +<xref linkend="scripting-the-desktop"/>).</para> + +<para>This can be achieved easily using the following method:</para> + +<procedure> +<step> +<para>Open &kcontrol;, and in the <guilabel>Regional & Accessibility</guilabel> +section, select <guilabel>Input Action</guilabel></para> +</step> +<step> +<para>Choose <guibutton>New Action</guibutton></para> +</step> +<step> +<para>Name the new action, ⪚ <userinput>Next Virtual +Screen</userinput></para> +</step> +<step> +<para>Select <guilabel>Keyboard shortcut -> Command/URL (simple)</guilabel> +for the <guilabel>Action type:</guilabel></para> +</step> +<step> +<para>In the <guilabel>Keyboard Shortcut</guilabel> tab, click the button +you wish to use to trigger the command. For this example, you would press +the one with the <guiicon>Next Page</guiicon> picture on it. +<keysym>Next_Virtual_Screen</keysym> will appear in the key image.</para> +</step> +<step> +<para>In the <guilabel>Command/URL Settings</guilabel> tab, enter the +command to run in the field: <userinput><command>dcop kwin default +nextDesktop</command></userinput></para> +</step> +</procedure> + +<para>Repeat the above with the <keysym>Prev_Virtual_Screen</keysym> key and +<userinput><command>dcop kwin default +previousDesktop</command></userinput>.</para> + +<para>Now pressing the <keysym>Prev_Virtual_Screen</keysym> or +<keysym>Next_Virtual_Screen</keysym> will switch you to the previous or next +virtual desktop, respectively.</para> + +<para>Obviously you can assign any free key to any action.</para> + +<itemizedlist> +<title>Related Information</title> +<listitem><para>See the <application>KHotKeys</application> documentation by +looking it up in &khelpcenter;, or typing +<userinput>help:/khotkeys</userinput> in a &konqueror; +window.</para></listitem> +<listitem><para><xref linkend="adding-extra-keys"/></para></listitem> +<listitem><para><xref linkend="scripting-the-desktop"/></para></listitem> +</itemizedlist> + +</sect1> + +<sect1 id="kdebugdialog"> +<sect1info> +<authorgroup> +<author> +<personname> +<firstname>Adriaan</firstname> +<surname>de Groot</surname> +</personname> +<email>[email protected]</email> +</author> +</authorgroup> +</sect1info> + +<title>&kdebugdialog; - Controlling &kde;'s Debugging Output</title> + +<sect2 id="kdebugdialog-basic-usage"> +<title>Basic Usage</title> + +<para>&kdebugdialog; is not in the &kmenu; by default. You will need to run +it from the shell or from the mini-CLI <!-- link to CLI, for sure --> with +the command <userinput><command>kdebugdialog</command></userinput>. +&kdebugdialog; pops up a window with a long list of debugging areas. Each +area has a checkbox that you can check or uncheck <!-- perhaps +select/deselect --> in order to enable or disable debugging output for +that part of &kde;.</para> + +<para>The list of debugging areas is sorted numerically, not alphabetically, +so kio (127) comes before artskde (400). The numbers go up to 200000 or so, +but there are really only 400 areas. You don't have to scroll through the +entire list to find the area you need, though. There is a line edit <!-- +text-entry ? --> box at the top of the dialog where you can enter a part of +the name of the area you want. The list of entries that is displayed is +filtered to include only those debug areas that contain the text you have +entered. ⪚ entering <userinput>k</userinput> does not filter very much at +all, but entering <userinput>kont</userinput> <!-- that's "butt" in dutch, +haha --> will show you just the &kontact; debugging areas. As an even +quicker way of enabling or disabling debugging output, there are also +<guibutton>select all</guibutton> and <guibutton>deselect all</guibutton> +buttons which will cause &kde; to produce a mountain of debugging output, or +very little.</para> +</sect2> + +<sect2 id="kdebugdialog-fullmode"> +<title>KDebugDialog in full mode</title> + +<!-- this text partly taken from the kdebugdialog handbook --> + +<para>In full mode, which is what you get when you start kdebugdialog as +<userinput><command>kdebugdialog</command> +<option>--fullmode</option></userinput>, the same list of debugging areas +as in plain mode is available, but you can select only one at a time from a +drop-down <!-- combo? --> box. You may then independently set the output +for various types of messages: Information, Warning, Error and Fatal Error. +For each of these types, you can choose where the messages are sent. The +choices are:</para> + +<para>File, in which case you can enter a filename. This file is written into your +$<envar>HOME</envar> directory.</para> + +<para>Message Box. Each debugging message is displayed in an information dialog, +which you must <guibutton>OK</guibutton> to continue with the +application.</para> + +<para>Shell, the default entry. Messages are printed to stderr, and will appear + either in the shell window where the application was started, or +in <filename>.xsession-errors</filename>.</para> + +<para>Syslog. This sends each debugging message to the system's syslog facility, +which can perform its own processing of the message.</para> + +<para>None. This suppresses the output of this type of message.</para> + +<para>For messages generated by fatal errors, it is generally a bad idea to choose +None or Syslog, since in both cases you most likely will not see the message +and the application that encounters the fatal error will vanish without +leaving a clue as to why it vanishes. Whether or not the application will +vanish on fatal errors can be controlled by the checkbox <guilabel>abort on +fatal errors</guilabel>, which is checked by default — but you might +expect an application to crash (in a messy fashion) if a fatal error is +encountered anyway.</para> + +<!-- Add links to "further reading" here --> +<!-- <itemizedlist> +<title>Related Information</title> +<listitem><para>to be written</para> +</listitem> +</itemizedlist>--> + + + +</sect2> +</sect1> +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/usenet.docbook b/doc/userguide/usenet.docbook new file mode 100644 index 000000000..2aba10a2b --- /dev/null +++ b/doc/userguide/usenet.docbook @@ -0,0 +1,251 @@ +<chapter id="usenet"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<chapterinfo> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</chapterinfo> +--> + +<title>Usenet News</title> + +<para>Usenet newsgroups are forums in which you can post messages to discuss +various topics: almost any subject you like (and many you don't!) can +be found there. Although usenet has become less popular than it once +was, because of the increasing use of web forums, &etc;, it is still a +useful tool. &kde; provides a powerful usenet news reader called &knode;.</para> + +<para>You can find &knode; in the <guimenu>K</guimenu> Menu under the +<guisubmenu>Internet</guisubmenu> entry: the menu entry +<guimenuitem>&knode; (News Reader)</guimenuitem> launches the program.</para> + + +<para>The main window of &knode; should now be displayed on your +desktop as shown; on the first start, the settings dialog will be +invoked.</para> + +<screenshot> +<screeninfo>Setting up &knode;</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-start.png" format="PNG"/> </imageobject> +<textobject> +<phrase>&knode; after first start</phrase> +</textobject> +<caption> +<para>&knode; after first start</para> +</caption> +</mediaobject> +</screenshot> + +<sect1 id="knode-setting-your-identity"> +<title>Personal settings</title> + +<para>The first page of the settings dialog is for personal settings: </para> +<screenshot> +<screeninfo>Dialog for entering personal information</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-identity.png" format="PNG"/> </imageobject> +<textobject> +<phrase>Entering personal information</phrase> +</textobject> +<caption> +<para>Entering personal information</para></caption> +</mediaobject> +</screenshot> + +<variablelist> + +<varlistentry> +<term> +<guilabel>Name</guilabel></term> +<listitem> +<para>In the field <guilabel>Name</guilabel>, enter your name. This +name will later appear in the newsgroups as sender, and can be seen by +anyone.</para> + +<para>Filling out the field <guilabel>Name</guilabel> is +mandatory.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term> +<guilabel>Email address</guilabel></term> +<listitem> +<para>The email address you enter here will be used as sender in news +articles, &ie; as actual address of the author, in conjunction with +the real name (set in the field <guilabel>Name</guilabel>).</para> + +<para>Filling out the <guilabel>Email Address</guilabel> field is +mandatory.</para> + +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="knode-setting-the-news-account"> +<title>Configuring the news account</title> + + +<para>Now we must tell &knode; about where we get the news from or +where to send the articles to later on. In the list on the +right, there is an <guilabel>Accounts</guilabel> entry; click on it and choose the +<guilabel>Newsgroup servers</guilabel> tab, because we first want to configure +the news account: the list of accounts is still empty.</para> + +<para>To create a new account click on <guibutton>Add...</guibutton>. The +following dialog appears:</para> + +<screenshot> +<screeninfo>The <guilabel>New Account</guilabel> dialog</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-news-account.png" format="PNG"/> </imageobject> +<textobject> +<phrase>The <guilabel>New Account</guilabel> dialog</phrase> +</textobject> +<caption> +<para>The <guilabel>New Account</guilabel> dialog</para> +</caption> +</mediaobject> +</screenshot> + +<variablelist> + +<varlistentry> +<term><guilabel>Name</guilabel></term> +<listitem> +<para>The <guilabel>Name</guilabel> field can be filled in as you +like; the text you enter will later be visible in the folder view. You +could, for example, enter the name of your Internet Provider; for our example we +enter the name <userinput>My News Account</userinput>.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Server</guilabel></term> +<listitem> + +<para>The next field is labelled <guilabel>Server</guilabel>. Unlike +the field <guilabel>Name</guilabel>, what you enter here is important. +The name of the news server is fixed and you should be able to get it +from your Internet service provider; if you do not know the name of +the news server, you should get it now: without this information you +cannot read any news. If your Internet service provider doesn't own a +news server you can use a public one (universities often provide +public news servers.)</para> + +<para>For our example configuration we enter the name +<userinput><systemitem +class="systemname">news.server.com</systemitem></userinput>; you will, +of course, enter the real name of your news server.</para> +</listitem> +</varlistentry> + +<varlistentry> +<term><guilabel>Port</guilabel></term> +<listitem> +<para>You probably will not need to change this from the default in most +cases.</para> +</listitem> +</varlistentry> + +</variablelist> + +</sect1> + +<sect1 id="knode-setting-the-mail-account"> +<title>Setting up the mail account</title> + +<para>Sometimes you need to answer to the author of an article +directly, without posting to the newsgroup; for example, when you want +to make a very personal comment or want to correct an error. If you +want to do this, select the <guilabel>Mail Server (SMTP)</guilabel> tab. The +following dialog box appears:</para> + +<screenshot> +<screeninfo>Dialog Box for setting up the mail account</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="knode-mail-account.png" format="PNG"/> </imageobject> +<textobject> +<phrase>Setting up the mail account</phrase> +</textobject> +<caption> +<para>Setting up the mail account</para> +</caption> +</mediaobject> +</screenshot> + +<variablelist> + +<varlistentry> +<term><guilabel>Server</guilabel></term> +<listitem> +<para>The name (address) of your mail server as provided by your +Internet service provider or system administrator; all you have to do +here is enter the mail server's name in the +<guilabel>Server</guilabel> field.</para> + +<para>In our example we enter <userinput><systemitem +class="systemname">mail.server.com</systemitem></userinput></para> +</listitem> +</varlistentry> + + +<varlistentry> +<term><guilabel>Port</guilabel></term> +<listitem> + +<para>Again, you probably will not need to change the +<guilabel>Port</guilabel> setting.</para> +</listitem> +</varlistentry> +</variablelist> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> +<listitem><para>The comp.windows.x.kde newsgroup is the main user +support group for &kde; on usenet. You can find other resources for +getting help with &kde; in <xref linkend="getting-help"/>.</para> +</listitem> +<listitem><para><ulink url="http://gmane.org">Gmane</ulink> provides a +usenet frontend to many mailing lists, including most of the &kde; +lists, so you can read them with &knode;.</para> +</listitem> +</itemizedlist> + + +</sect1> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "chapter") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/where-next.docbook b/doc/userguide/where-next.docbook new file mode 100644 index 000000000..2da8d3e84 --- /dev/null +++ b/doc/userguide/where-next.docbook @@ -0,0 +1,40 @@ +<chapter id="where-next"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<chapterinfo> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</chapterinfo> +--> + +<title>Where To Next?</title> + +<para>Web Sites</para> + +<para>Books</para> + +</chapter> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/windows-how-to.docbook b/doc/userguide/windows-how-to.docbook new file mode 100644 index 000000000..914e228da --- /dev/null +++ b/doc/userguide/windows-how-to.docbook @@ -0,0 +1,559 @@ +<sect1 id="windows-how-to-work"> +<sect1info> +<authorgroup> +<author> +&Philip.Rodrigues; +</author> +</authorgroup> +</sect1info> + + +<title>Windows, How To Work Them</title> + +<sect2 id="basic-window-management"> +<title>Basic Window Management</title> +<indexterm><primary>Window Management</primary></indexterm> + +<para>Each application running in &kde; has its own window, and some +applications may use more than one window. You can manipulate these +windows in many ways to make your desktop work for you. Here is a +normal window: +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="a-window.png" format="PNG"/> +</imageobject> +<textobject><phrase>A normal window</phrase> +</textobject> +</mediaobject> +</screenshot> +</para> + +<sect3 id="switching-between-windows"> +<title>Switching Between Windows</title> +<indexterm><primary>Focus (windows)</primary></indexterm> + +<para>If you want to use a window, it must be active. A window +automatically becomes active when you open it, so that the application +you opened is immediately ready to use. Only one window can be active +at a time. The active window is the one into which you can type, and can +be distinguished from the others because it has a different colored +titlebar. (With the &kde; default theme, the active window has a +<replaceable>light blue</replaceable> titlebar, and the inactive +windows have <replaceable>gray</replaceable> titlebars.)</para> + +<para> +<indexterm><primary>Raising Windows</primary></indexterm> +When you want to work in a different window, you need to make +it active. There are two ways to do this: +<itemizedlist> + +<listitem> +<para>&LMB;-click on the window that you want to make active. The +window will become active and will be raised above other windows if it +overlaps them.</para> +</listitem> + +<listitem> +<para><indexterm><primary><keycombo +action="simul">&Alt;	</keycombo></primary></indexterm> +Hold down &Alt; and press 	 (do not release the &Alt; +key). A popup dialog appears with a list of available windows, one of +which is highlighted. You can select a different window by pressing +	 again to move through the list, all the time holding down +&Alt;. When you release the &Alt; key, the window which was highlighted +is made active.</para> +</listitem> +</itemizedlist> +</para> + +</sect3> + +<sect3 id="moving-windows"> +<title>Moving Windows</title> +<indexterm><primary>Moving Windows</primary></indexterm> + +<para>The first way to organize the windows on your desktop is to move +them around. You can move windows so that they overlap other windows, +or so that you can see the whole window. There are three ways to move +a window: +<itemizedlist> +<listitem> +<para>Click the &LMB; on the window titlebar and hold it down. Move +the mouse cursor and the window moves with it. Release the mouse +button, and the window remains where you left it.</para> +</listitem> + +<!-- FIXME: OK, so the screenie sucks, but it shows the idea --> +<!-- In fact, maybe it's not even necessary: just mention the previous --> +<!-- screenshot (having callouts on it would be nice) --> + +<listitem> +<para>Open the window menu using the leftmost button on the window +titlebar (as displayed below), and select <guimenuitem>Move</guimenuitem>. The mouse cursor +moves to the center of the current window and by moving the mouse +around, you can move the window. Once you have moved the window to the +position you want, click the &LMB; to release it.</para> +<indexterm><primary>Window Menu</primary></indexterm> + +<screenshot> +<screeninfo>The Window Menu</screeninfo> +<mediaobject> +<imageobject> +<imagedata fileref="titlebar-menu.png" format="PNG" /> +</imageobject> +<textobject> +<phrase>The Window Menu</phrase> +</textobject> +</mediaobject> +</screenshot> +</listitem> + +<listitem> +<para>Hold down &Alt; and the &LMB; when the mouse cursor is +above the window you want to move. The mouse cursor changes to a +compass, and by moving the mouse, you can move the window. Just +release the mouse button to release the window. This method is +particularly useful if the window titlebar has been moved off the +screen, so you cannot use the other methods.</para> +</listitem> +</itemizedlist> +</para> + +</sect3> + +<sect3 id="resizing-windows"> +<title>Resizing Windows</title> + +<indexterm><primary>Resizing Windows</primary></indexterm> + +<para>You can make windows bigger or smaller, wider, or taller in +one of two ways. Just use whichever you are most comfortable with: +<itemizedlist> +<listitem> +<para>Move the mouse cursor over the border of the window (it is light +blue in the screenshot above). The pointer will turn into a +double-headed arrow. Click and drag, and the edge of the window +follows the mouse cursor, making the window bigger or smaller. If you +click on the borders on the top or bottom of the window, you can +adjust the height on its own. If you click on the borders on the left +or right of the window, you can adjust the width. To change both at +the same time, move the mouse cursor over the corner of the +window. When the pointer becomes a diagonal double-headed arrow, click +and drag.</para> +</listitem> +<listitem> +<para>Use the leftmost button on the window titlebar to display the +window menu. Choose the <guimenuitem>Resize</guimenuitem> entry, and +the mouse pointer will become a double-headed arrow. Move the mouse +cursor around to resize, and click the &LMB; when you are done +to release the window.</para> +</listitem> +<listitem> +<para>If you cannot see the window border or the button for the window +menu, you can use &Alt; and the &RMB;: Hold down &Alt; and drag with +the &RMB;. The window will resize. You just release the &RMB; when +you are done. </para> +</listitem> +</itemizedlist> +</para> + +<para>If you just want to make a window as big as possible, so it +takes up the whole screen, use the +<guibutton>Maximize<indexterm><primary>Maximizing +Windows</primary></indexterm></guibutton> button, which is the second +button from the right on the window titlebar. Clicking with the &LMB; +on this button will make the window as big as possible in both +directions; while clicking with the &MMB;<indexterm><primary>Maximizing +Windows</primary><secondary>Vertically</secondary></indexterm> or the +&RMB;<indexterm><primary>Maximizing Windows</primary><secondary>Horizontally</secondary></indexterm> +will increase the window's size in only the vertical or horizontal +direction, respectively.</para> + + +</sect3> + +<sect3 id="hiding-windows"> +<title>Hiding Windows</title> +<indexterm><primary>Hiding Windows</primary></indexterm> + +<!-- TODO: Screenshot of the minimize button --> +<para> +<indexterm><primary>Minimize</primary></indexterm> +When you need to keep a program open, but you do not want it to +take up space on your desktop, you can minimize it or shade it. To +minimize a window, click the <guibutton>Minimize</guibutton> button, +which is third from the right on the window titlebar. The window will +not be displayed, but the program is still running, and an entry for +it appears in the taskbar on the panel. To display the window again, +click on its entry in the taskbar. You can also use <keycombo +action="simul">&Alt;	</keycombo><indexterm><primary><keycombo +action="simul">&Alt;	</keycombo></primary></indexterm>: see <xref +linkend="switching-between-windows" />.</para> + +<para> +<indexterm><primary>Shade</primary></indexterm> +Shading windows is very similar to minimizing them, but this +time, only the titlebar of the window is shown. To shade a window, +double-click on the titlebar. To restore the window, just double-click +on the titlebar again.</para> +</sect3> + +<sect3 id="cascade-windows"> +<title>Cascading Windows</title> + +<para>Sometimes you might have a whole lot of windows open and all over the place. By selecting to cascade windows &kde; will automatically line them up as a succession from the top-left of your screen. To use this option use your &MMB; on the desktop, and then select <guimenuitem>Cascade Windows</guimenuitem>.</para> + +</sect3> + +<sect3 id="unclutter-windows"> +<title>Uncluttering Windows</title> + +<para>By selecting to unclutter your opened windows &kde; will attempt to use the maximum available space of the desktop in order to display as much of each window as possible. For example, should you have four windows open and you request that they be uncluttered, they will each be placed in a corner of the desktop, regardless of where they were originally. To use this option once again use your &MMB; on the desktop and then select <guimenuitem>Unclutter Windows</guimenuitem>.</para> + +</sect3> + +<sect3 id="closing-windows"> +<title>Closing Windows</title> + +<indexterm><primary>Closing Windows</primary></indexterm> + +<para>When you finish using an application, you will want to stop +the application and close its window. Once again, you have the choice +of a few options: +<itemizedlist> +<listitem> +<para>Click on the rightmost button on the window titlebar.<!-- TODO: --> +<!-- Screenie --> If you are editing a document with that application, +you will be asked whether you want to <guibutton>Save</guibutton> your +changes, <guibutton>Discard</guibutton> them, or +<guibutton>Cancel</guibutton> your command to close the application.</para> +</listitem> +<listitem> +<para>Use the <menuchoice><guimenu>File</guimenu><guimenuitem>Quit</guimenuitem> +</menuchoice> option on the menubar. You will be presented with the +same choice of <guibutton>Save</guibutton>, +<guibutton>Discard</guibutton>, or +<guibutton>Cancel</guibutton>.</para> +</listitem> + +<listitem> +<para> <mousebutton>Right</mousebutton>-click on the respective window in &kicker;, the &kde; panel, and then select <guimenuitem>Close</guimenuitem>. You will be prompted with an option to save any documents that were being edited.</para> +</listitem> + +<listitem> +<para>Press <keycombo action="simul">&Alt;<keycap>F4</keycap></keycombo><indexterm><primary><keycombo action="simul">&Alt;<keycap>F4</keycap> +</keycombo></primary></indexterm> +. Once again, the confirmation dialog will be shown if you +were editing any documents.</para> +</listitem> +</itemizedlist> +</para> + +</sect3> + +<!-- Let's try organising this a different way +<para>The bar along the top is called the titlebar, and contains most +of the things you'll need to manipulate the window. Let's take a +closer look: +<screenshot> +<mediaobject> +<imageobject> +<imagedata fileref="titlebar.png" format="png"/> +</imageobject> +<textobject><phrase>A window titlebar</phrase> +</textobject> +</mediaobject> +</screenshot> +<note><para>This screenshot shows the titlebar which appears in the +default &kde; configuration. The exact appearance on your system may +be slightly different, but the functions are similar.</para> +</note> +--> + +<!-- TODO:Note &MMB; mouse button/&RMB mouse button on maximize for +vertical/horizontal maximization. Or is this advanced? --> + +</sect2> + +<sect2 id="advanced-window-management"> +<title>Advanced Window Management</title> + +<para>kstart</para> +<sect3 id="kstart"> +<sect3info> +<author> +&Richard.J.Moore; +&Richard.J.Moore.mail; +</author> +</sect3info> +<title>&kstart;</title> + +<para>The simplest way to access the advanced window management +facilities in &kde; is to use a little known +utility called &kstart;, which is included in &kde; since version 2.1 &kstart; lets you control the way an application interacts with +the window manager. The command is usually +used to define special behavior for commonly-used applications, but +it can also be useful for integrating non-&kde; applications into your +desktop.</para> + +<para>Using &kstart; is easy: you simply put +<userinput><command>kstart</command></userinput> and some options +before a command. To begin, let's look at how we might use +&kstart; to customize the behaviour of a +&kcalc; window. The command we'll use is as follows: + +<screen><prompt>%</prompt> <userinput><command>kstart</command> <option>--ontop</option> <option>--alldesktops</option> <option>kcalc</option></userinput></screen> +</para> + +<para>With luck, the effect this command has +should be fairly obvious - the kcalc window will stay on top of all +the others and be visible on every virtual desktop. A feature that is +less obvious is that this command will work with any NET compliant +environment, not just &kde;.</para> + +<para>We can pass arguments to programs we invoke with &kstart; as normal, for +example: + +<screen><prompt>%</prompt> <userinput><command>kstart</command> +<option>--skiptaskbar</option> <option>--desktop</option> +1 xmessage'Hello World'</userinput></screen> + +</para> + +<para>This command displays <computeroutput>Hello +World</computeroutput> with <application>xmessage</application> and +ensures that the window will be shown on the first virtual desktop and +will be omitted from the taskbar. The fact that this program is +written using the Xt toolkit rather than being a native &kde; +application does not cause any problem for +&kstart;, hopefully this illustrates how +&kstart; can be used to integrate foreign +applications into your &kde; desktop.</para> +</sect3> + +<sect3 id="special-window-settings"> +<title>Other Special Window Settings</title> +<para>While you can use &kstart; to assign particular window settings, &kde; also allows you to alter these -- as well as other similar settings -- from the program window itself. Simply select the leftmost button in the window titlebar (or just hit <keycombo action="simul">&Alt;<keycap>F3</keycap></keycombo> once the window is focued), and then go to <menuchoice><guisubmenu>Advanced</guisubmenu><guimenuitem>Special Window Settings...</guimenuitem></menuchoice>. As you can see, from here you change various things from its geometry upon startup, to whether it should have a border or not.</para> +</sect3> + +<sect3 id="system-tray"> +<sect3info> +<author> +&Richard.J.Moore; +&Richard.J.Moore.mail; +</author> +</sect3info> + +<title>The System Tray</title> + +<para>Now that we know how to customize the decoration of a window +let's take a look at another aspect of the desktop: the system +tray. The system tray is an area in which an application can display a +small window. It is used to display status information or provide +quick access to commands. A window that has an item in the system tray +usually disappears from the task manager when minimised with the tray +icon providing a replacement. Normally tray icons are specifically +developed as part of an application, but as with window decorations, +&kde; provides a tool for changing this: +<application>ksystraycmd</application>.</para> + +<para>To begin with, we'll take the standard application &kcalc; and turn +it into a system tray application. This is acheived with one simple +command: +<screen><prompt>%</prompt> <userinput><command>ksystraycmd</command> <option>--title</option> 'kcalc' kcalc</userinput></screen> + +</para> + +<para>The icon shown in the tray is the one specified in the window +hints and will be updated if the icon changes. The window title is +shown as a tooltip if you hold the mouse over the icon. +<application>ksystraycmd</application> follows standard &kde; +behaviour so the target window can be shown and hidden by clicking the +tray icon, and a standard context menu is available. </para> + +<screenshot> <mediaobject> <imageobject><imagedata +fileref="kcalc-systray.png"></imagedata></imageobject> +</mediaobject></screenshot> +</sect3> + +<sect3 id="more-complex-uses-of-ksystraycmd"> +<sect3info> +<author> +&Richard.J.Moore; +&Richard.J.Moore.mail; +</author> +</sect3info> + +<title>More Complex Uses of +<application>ksystraycmd</application></title> + +<para>To illustrate the other features of +<application>ksystraycmd</application>, we'll use a more complicated example: a &konsole; window tracking the +<filename>.xsession-errors</filename> file (this is the log file that records what's +happening on your desktop). To begin with, we'll simply look at how +we can view this: +<screen><prompt>%</prompt> <userinput><command>konsole</command> <option>--icon</option> +log <option>--caption</option> 'X Log' \ +<option>--nomenubar</option> <option>--notabbar</option> +<option>--noframe</option> \ +<option>-e</option> tail -f ~/.xsession-errors</userinput></screen> +</para> + + <para>The <option>--caption</option> and <option>--icon</option> +arguments are provided as standard by &kde; applications. You can get +a full list of these global options by running an application with the +<option>--help-kde</option> and <option>--help-qt</option> +parameters. Here we give our &konsole; window the title 'X Log' and +the icon <quote>log</quote>. You can use these options with any &kde; application and +as mentioned above, <application>ksystraycmd</application> takes account of these when creating +the tray icon. The <option>-e</option> argument is specific to &konsole; and tells it +to run the <command>less</command> command. Despite its complexity, we can easily move +this window into the tray with <application>ksystraycmd</application>: + +<screen><prompt>%</prompt> <userinput><command>ksystraycmd</command> +<option>--hidden</option> <option>--title</option> 'X Log' \ +konsole --icon log --caption 'XLog' \ +--nomenubar --notabbar --noframe \ +-e tail -f .xsession-errors</userinput></screen> +</para> + + <para>In addition to being the +most complex command we've used, this example demonstrates the +<option>--hidden</option> option which starts the command with only the system tray +icon visible. This example achieves our aim of providing quick access +to the log file, but we can do things a little more efficiently if we +only run the konsole process when it is visible. The command we use +is +<screen><prompt>%</prompt> <userinput><command>ksystraycmd</command> <option>--startonshow</option> \ + --<option>icon</option> log <option>--tooltip</option> 'X Log' \ +konsole --icon log --caption 'X Log' \ +--nomenubar --notabbar --noframe \ +-e tail -f ~/.xsession-errors</userinput></screen> +</para> + +<para>The addition of the <option>--startonshow</option> parameter tells +<application>ksystraycmd</application> to start with only the tray +icon visible (like the <option>--hidden</option> parameter), and to wait until the user +activates the tray icon before running the target command. We've also +used the <option>--quitonhide</option> parameter which tells <application>ksystraycmd</application> to terminate +the target app whenever its window is hidden. Using both these +parameters ensures that our &konsole; tray icon doesn't waste resources +when we aren't using it. Creating and destroying the target window as +we do here prevents the standard icon and title handling of +<application>ksystraycmd</application> from working, so we now need to +specify the initial icon and tooltip explicitly +too.</para> +</sect3> + +<sect3 id="improving-reliability"> +<sect3info> +<author> +&Richard.J.Moore; +&Richard.J.Moore.mail; +</author> +</sect3info> + +<title>Improving Reliability</title> + +<para>In all of our previous examples we've relied on +&kstart; and +<application>ksystraycmd</application> to figure out which window we +want to affect, and unless we say otherwise, they assume that the first +window to appear is the one we want. This policy is usually OK because +we are starting the application at the same time, but it can fail +badly when lots of windows are appearing (such as when you log on). To +make our commands more robust we can use the +<option>--window</option> parameter. This specifies the title +of the target window. The following example uses the <option>--window</option> parameter +to ensure that a particular konsole window is affected: + +<screen><prompt>%</prompt> <userinput><command>kstart</command> <option>--iconify</option> <option>--window</option> 'kstart_me' konsole +--caption 'kstart_me' -e tail -f +~/.xsession-errors</userinput></screen> + +</para> + +<para>Here we've used the tried and tested technique of specifying a +title for both &kstart; and the target application. This is generally +the best way to use &kstart; and <application>ksystraycmd</application>. The <option>--window</option> argument is +supported by both &kstart; and <option>ksystraycmd</option> and can be regular expression +(⪚ <quote>window[0-9]</quote>) as well as a particular title. (Regular +expressions are a powerful pattern matching tool you'll find used +throughout &kde;.) </para> + +</sect3> + +</sect2> + +<sect2 id="using-multiple-desktops"> +<title>Using Multiple Desktops</title> + +<indexterm><primary>Virtual Desktops</primary></indexterm> +<indexterm><primary>Multiple Desktops</primary></indexterm> + +<para>Sometimes, one screen's worth is just not enough space. If you +use many applications at the same time, and find yourself drowning in +different windows, virtual desktops offer the solution. By default, +&kde; has four virtual desktops, each one of which is like a separate +screen: you can open windows, move windows around, and set backgrounds and +icons on each of the desktops. If you are familiar with the concept of +virtual terminals, you will have no trouble with &kde;'s virtual +desktops.</para> + +<sect3 id="switching-virtual-desktops"> +<title>Switching Virtual Desktops</title> +<para>To move to a different virtual desktop, you can use <keycombo action="simul">&Ctrl;	 +</keycombo> in the same way as you would use <keycombo action="simul">&Alt;	 +</keycombo> to switch between windows (see <xref linkend="switching-between-windows"/>): Hold down &Ctrl; and then press +	. A small popup window appears, showing the virtual desktops, +with one highlighted. If you release &Ctrl;, &kde; will switch to the +highlighted virtual desktop. To select a different desktop, press +	 repeatedly, while holding down &Ctrl;. The selection moves +through the available desktops. When the desktop you want to switch to +is highlighted, release &Ctrl;.</para> + +<!-- TODO: Write about the desktop pager thing --> + +</sect3> + +<sect3 id="windows-and-virtual-desktops"> +<title>Windows and Virtual Desktops</title> +<para>You can move windows around your virtual desktops with the +<guisubmenu>To Desktop</guisubmenu> item in the window menu: just +select the desktop to which you want to move the window. You can make the +window appear on all desktops with the <guimenuitem>All +Desktops</guimenuitem><indexterm><primary>Sticky +Windows</primary></indexterm> item.</para> + +<!-- Add links to "further reading" here +<itemizedlist> +<title>Related Information</title> +<listitem><para></para> +</listitem> +</itemizedlist> + +--> +</sect3> + + +</sect2> + +</sect1> +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/userguide/your-kde-account.docbook b/doc/userguide/your-kde-account.docbook new file mode 100644 index 000000000..aa37dddac --- /dev/null +++ b/doc/userguide/your-kde-account.docbook @@ -0,0 +1,79 @@ +<sect1 id="account-intro"> +<!-- Uncomment the <*info> below and add your name to be --> +<!-- credited for writing this section. --> + +<!-- +<sect1info> +<authorgroup> +<author> +<firstname>Your First Name here</firstname> +<surname>Your Surname here </surname> +</author> +</authorgroup> +</sect1info> +--> + +<title>About Your &kde; Account</title> + +<para>&kde; stores information about your personal settings in a few +different places: + +<itemizedlist> +<listitem><para>The hidden directory <filename>.kde</filename> (note the +period at the beginning), located in your home directory, contains a +large number of files that store &kde; settings. Some subdirectories +you may find useful are:<filename>.kde/share/config</filename>, which +contains configuration files for individual applications; +<filename>.kde/Autostart</filename>, which contains links to +applications which should start each time you start &kde;; and +<filename>.kde/share/apps/kabc</filename>, where your address book is +stored.</para> +</listitem> +<!-- FIXME: Apparently KDEDIR and KDEDIRS are deprecated. I need to --> +<!-- get the truth on this --> +<listitem><para>The environment variables <envar>KDEDIR</envar> and +<envar>KDEDIRS</envar> tell &kde; where its files are stored. You will +usually only need to set <envar>KDEDIR</envar> to the directory in which +&kde; is installed, but sometimes you might have other &kde; +programs installed elsewhere: in this case, you can use the +<envar>KDEDIRS</envar> environment variable. Set +<envar>KDEDIRS</envar> to a list of all the directories containing +&kde; programs, separated by commas. For example, if you have &kde; +programs in both <filename>/usr/local/kde</filename> and +<filename>/home/phil/kde</filename>, you can use <userinput>export +KDEDIR=/usr/local/kde,/home/phil/kde</userinput> if you use +<application>bash</application> or <userinput>setenv +KDEDIR=/usr/local/kde,/home/phil/kde</userinput> if you use sh. +</para> +</listitem> +</itemizedlist> +</para> + +<!-- Add links to "further reading" here --> +<itemizedlist> +<title>Related Information</title> +<listitem><para><xref linkend="kde-for-administrators" /> contains +more information about the directories that &kde; uses.</para> +</listitem> +</itemizedlist> + + +</sect1> + +<!-- Keep this comment at the end of the file +Local variables: +mode: xml +sgml-omittag:nil +sgml-shorttag:nil +sgml-namecase-general:nil +sgml-general-insert-case:lower +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:0 +sgml-indent-data:true +sgml-parent-document:("index.docbook" "book" "sect1") +sgml-exposed-tags:nil +sgml-local-catalogs:nil +sgml-local-ecat-files:nil +End: +--> diff --git a/doc/visualdict/Makefile.am b/doc/visualdict/Makefile.am new file mode 100644 index 000000000..81064650f --- /dev/null +++ b/doc/visualdict/Makefile.am @@ -0,0 +1,4 @@ + +KDE_LANG = en +KDE_DOCS = khelpcenter/visualdict + diff --git a/doc/visualdict/index.docbook b/doc/visualdict/index.docbook new file mode 100644 index 000000000..c950ca395 --- /dev/null +++ b/doc/visualdict/index.docbook @@ -0,0 +1,349 @@ +<?xml version="1.0" ?> +<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" +"dtd/kdex.dtd" [ + <!ENTITY kappname "Visual Guide to &kde;"> + <!ENTITY % addindex "IGNORE"> + <!ENTITY % English "INCLUDE" > <!-- change language only here --> + + +]> + +<book lang="&language;"> + +<bookinfo> +<title>The &kde; Visual Guide</title> +<authorgroup> +<corpauthor> +The &kde; Team +</corpauthor> +<!-- TRANS:ROLES_OF_TRANSLATORS --> +</authorgroup> + +<date>2006-12-06</date> +<releaseinfo>3.00.00</releaseinfo> + +<copyright> +<year>2000</year><year>2006</year> +<holder>The &kde; Team</holder> +</copyright> + +<legalnotice>&FDLNotice;</legalnotice> + +<abstract><para>A visual guide to &kde;'s interface. This is a very early +version +of the document. Eventually, this will be a graphical tour of +&kde;.</para></abstract> + +<keywordset> +<keyword>KDE</keyword> +<keyword>Visual</keyword> +<keyword>Dictionary</keyword> +<keyword>Guide</keyword> +</keywordset> + +</bookinfo> + +<chapter id="visual-dictionary"> + +<!-- Translators please note: If you have already translated the visual --> +<!-- dictionary on the i18n website, please make sure the translations here --> +<!-- match that file exactly. --> + +<title>&kde; Visual Dictionary of terms</title> + +<para>This project was started to help unify the vocabulary used in &kde; +documentation.</para> + +<para>We provide this for you here as an aid to learning your way around the +&kde; +Graphical User Interface. These names have been standardized within &kde; +documentation, so that you will always find interface items referred to in the +same way.</para> + +<tip><para>The term <quote>Widget</quote> refers to the basic building +block of a computer program's interface.</para> +<para>Each widget operates in a +similar manner each time it is used, but the effect that the widget has depends on +its place within the program.</para></tip> + +<!-- TODO: +Widgets to add: combo buttons (eg, the 'back' button in konq), popup +menus/context menus, passive popups, navigation panel buttons? + +Perhaps list deprecated names, for search/replace purposes? +--> +<sect1 id="widget-table"> +<title>Listing of Common &kde; Widgets</title> +<para>Currently, this guide consists of a table of the names of the graphical +elements often found in &kde; documentation, and an example of each one. </para> +<para>Our hope, eventually, is to make this a much more complete document, +which will take you on a visual tour of &kde;.</para> + +<informaltable> +<tgroup cols="2"> +<tbody> + +<row> +<entry>Button</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict12.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Check Boxes</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict13.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Color Selector</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict9.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Combo Box</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict2.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Context Menu</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict21.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Dialog Box</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict6.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Drop Down Box</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict1.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Icon List</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict16.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>List Box</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict7.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict8.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Menubar</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict4.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Progress Bar</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict17.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Radio Buttons</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict10.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Scroll Bar</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict18.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Slider</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict15.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Spin Box</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict11.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Status Bar</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict20.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Tab</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict22.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Tabbed Window</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict23.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Text Box</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict14.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Toolbar</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict3.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +<row> +<entry>Tree View</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict19.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + + +<row> +<entry>Window Titlebar</entry> +<entry> +<inlinemediaobject> +<imageobject> +<imagedata fileref="pict5.png" format="PNG"/> +</imageobject> +</inlinemediaobject> +</entry> +</row> + +</tbody> +</tgroup> +</informaltable> +</sect1> +</chapter> +<chapter id="credits"> +<title>Credits and Licenses</title> +<para>&kappname;</para> + +<para>Documentation by the &kde; Documentation Team.</para> + +&underFDL; +</chapter> + +</book> + diff --git a/doc/visualdict/pict1.png b/doc/visualdict/pict1.png Binary files differnew file mode 100644 index 000000000..de9cf8695 --- /dev/null +++ b/doc/visualdict/pict1.png diff --git a/doc/visualdict/pict10.png b/doc/visualdict/pict10.png Binary files differnew file mode 100644 index 000000000..4d526ca74 --- /dev/null +++ b/doc/visualdict/pict10.png diff --git a/doc/visualdict/pict11.png b/doc/visualdict/pict11.png Binary files differnew file mode 100644 index 000000000..5968a7a2d --- /dev/null +++ b/doc/visualdict/pict11.png diff --git a/doc/visualdict/pict12.png b/doc/visualdict/pict12.png Binary files differnew file mode 100644 index 000000000..49643c607 --- /dev/null +++ b/doc/visualdict/pict12.png diff --git a/doc/visualdict/pict13.png b/doc/visualdict/pict13.png Binary files differnew file mode 100644 index 000000000..26a615502 --- /dev/null +++ b/doc/visualdict/pict13.png diff --git a/doc/visualdict/pict14.png b/doc/visualdict/pict14.png Binary files differnew file mode 100644 index 000000000..1f32bfe83 --- /dev/null +++ b/doc/visualdict/pict14.png diff --git a/doc/visualdict/pict15.png b/doc/visualdict/pict15.png Binary files differnew file mode 100644 index 000000000..6fc7a5ca2 --- /dev/null +++ b/doc/visualdict/pict15.png diff --git a/doc/visualdict/pict16.png b/doc/visualdict/pict16.png Binary files differnew file mode 100644 index 000000000..c5692e751 --- /dev/null +++ b/doc/visualdict/pict16.png diff --git a/doc/visualdict/pict17.png b/doc/visualdict/pict17.png Binary files differnew file mode 100644 index 000000000..a49a9a271 --- /dev/null +++ b/doc/visualdict/pict17.png diff --git a/doc/visualdict/pict18.png b/doc/visualdict/pict18.png Binary files differnew file mode 100644 index 000000000..0853ddb52 --- /dev/null +++ b/doc/visualdict/pict18.png diff --git a/doc/visualdict/pict19.png b/doc/visualdict/pict19.png Binary files differnew file mode 100644 index 000000000..e366a3da1 --- /dev/null +++ b/doc/visualdict/pict19.png diff --git a/doc/visualdict/pict2.png b/doc/visualdict/pict2.png Binary files differnew file mode 100644 index 000000000..87724f8ea --- /dev/null +++ b/doc/visualdict/pict2.png diff --git a/doc/visualdict/pict20.png b/doc/visualdict/pict20.png Binary files differnew file mode 100644 index 000000000..82c4a738e --- /dev/null +++ b/doc/visualdict/pict20.png diff --git a/doc/visualdict/pict21.png b/doc/visualdict/pict21.png Binary files differnew file mode 100644 index 000000000..573c7a2a0 --- /dev/null +++ b/doc/visualdict/pict21.png diff --git a/doc/visualdict/pict22.png b/doc/visualdict/pict22.png Binary files differnew file mode 100644 index 000000000..052be0b83 --- /dev/null +++ b/doc/visualdict/pict22.png diff --git a/doc/visualdict/pict23.png b/doc/visualdict/pict23.png Binary files differnew file mode 100644 index 000000000..1e09a5787 --- /dev/null +++ b/doc/visualdict/pict23.png diff --git a/doc/visualdict/pict3.png b/doc/visualdict/pict3.png Binary files differnew file mode 100644 index 000000000..124986e53 --- /dev/null +++ b/doc/visualdict/pict3.png diff --git a/doc/visualdict/pict4.png b/doc/visualdict/pict4.png Binary files differnew file mode 100644 index 000000000..498ca7212 --- /dev/null +++ b/doc/visualdict/pict4.png diff --git a/doc/visualdict/pict5.png b/doc/visualdict/pict5.png Binary files differnew file mode 100644 index 000000000..f383ca563 --- /dev/null +++ b/doc/visualdict/pict5.png diff --git a/doc/visualdict/pict6.png b/doc/visualdict/pict6.png Binary files differnew file mode 100644 index 000000000..542b2f278 --- /dev/null +++ b/doc/visualdict/pict6.png diff --git a/doc/visualdict/pict7.png b/doc/visualdict/pict7.png Binary files differnew file mode 100644 index 000000000..4ed9d6074 --- /dev/null +++ b/doc/visualdict/pict7.png diff --git a/doc/visualdict/pict8.png b/doc/visualdict/pict8.png Binary files differnew file mode 100644 index 000000000..6f896ea4b --- /dev/null +++ b/doc/visualdict/pict8.png diff --git a/doc/visualdict/pict9.png b/doc/visualdict/pict9.png Binary files differnew file mode 100644 index 000000000..9a4aac405 --- /dev/null +++ b/doc/visualdict/pict9.png |
