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, 611 insertions, 0 deletions

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 &amp; 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:
+-->