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

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=\{@}&amp;ie=UTF-8&amp;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&amp;ie=UTF-8&amp;oe=UTF-8">http://www.google.com/search?q=konqueror&amp;ie=UTF-8&amp;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 &mdash; the
+drop-down menu &mdash; 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 &amp; 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:
+-->