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

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