Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdebase@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 565 insertions, 0 deletions

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 &Tab; key on your keyboard. By pressing
+&Tab;, <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
+(&eg; 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 &mdash; 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
+&mdash; 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>&lt;Merge&gt;</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>&lt;Merge&gt;</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:
+-->