Fix crash if key bindings specified in profile cannot be found. Improve

[personal-kdebase.git] / apps / doc / konqueror / browser.docbook

<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><guisubmenu>Other Tabs</guisubmenu></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><menuchoice><guisubmenu>Other Tabs</guisubmenu><guimenuitem>Reload all Tabs</guimenuitem></menuchoice></term>
<listitem><para>Reloads the content of every tab.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><menuchoice><guisubmenu>Other Tabs</guisubmenu><guimenuitem>Close Other Tabs</guimenuitem></menuchoice></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 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:
-->