Make a branch to make krunner Good Enough For Aaron™.

[kdebase/uwolfer.git] / runtime / doc / kcontrol / khtml / index.docbook

<?xml version="1.0" ?>
<!DOCTYPE article PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN"
"dtd/kdex.dtd" [
<!ENTITY nsplugins-kcontrol SYSTEM "nsplugin.docbook">
<!ENTITY % addindex "IGNORE">
<!ENTITY % English "INCLUDE" > <!-- change language only here -->
]>

<article lang="&language;">
<articleinfo>

<authorgroup>
<author>&Krishna.Tateneni; &Krishna.Tateneni.mail;</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<date>2003-10-12</date>
<releaseinfo>3.2</releaseinfo>

<keywordset>
<keyword>KDE</keyword>
<keyword>KControl</keyword>
<keyword>konqueror</keyword>
<keyword>browsing</keyword>
</keywordset>

</articleinfo>
<sect1 id="konq-browsing">
<title>Browsing With &konqueror;</title>

<para>The &konqueror; Browser module of &kcontrol; allows you to select
various options for the appearance and behavior of &konqueror;, the
integrated web browser of &kde;.</para>

<sect2 id="kbrowse-html">

<title>Behavior</title>

<para>The first option you can enable on this page is <guilabel>Enable
completion of forms</guilabel>.  If you check this box, &konqueror; will
try to remember what you answer to form questions, and will try to fill
in forms for you with the answers you previously used.</para>

<para>You can configure the number of form items &konqueror; remembers
with the slider below labelled <guilabel>Maximum
completions</guilabel></para>

<note><para>Of course, anything &konqueror; fills in a form with, you
can still edit before submitting the form!</para></note>

<para>The next option is <guilabel>Change cursor over
links</guilabel>. If this option is selected, the shape of the cursor
will change (usually to a hand) whenever it moves over a
hyperlink. This makes it easy to identify links, especially when they
are in the form of images.</para>

<para>&konqueror; defaults to a single window per page, but has the
capability to open multiple <firstterm>tabs</firstterm> inside a
single window. &konqueror; also, by default, has a &MMB; shortcut to
open any link in a new window.  If you enable <guilabel>Open links in
new tab instead of in new window</guilabel> you can &MMB; click on a
link to have it open in a new tab.</para>

<para>If you are using tabbed browsing, you can choose if a newly
opened tab becomes the active (<quote>front</quote>) tab, or goes to
the back.  On a slow internet connection, or while browsing a page
that has a list of headlines or other links in a list, you may like to
have the new tabs load in the background while you continue reading.
In this case, leave this setting disabled.  If you prefer to go
straight to the new page, leaving the old one in the background to
return to later, enable it.</para>

<para>If you close a window in &konqueror; that has multiple tabs
open, &konqueror; will ask you if you're sure that you meant to close
it.  You can toggle on and off this behavior with the
<guilabel>Confirm when closing windows with multiple tabs</guilabel>
checkbox.</para>

<para>As a convenience feature, if you enable <guilabel>Right click
goes back in history</guilabel>, then clicking an empty area (&ie; not
a link) in the &konqueror; window will act as if you pressed the
<guiicon>Back</guiicon> button on the toolbar.</para>

<para>The checkbox labeled <guilabel>Automatically load
images</guilabel>, allows you to control whether images on web pages are
loaded by default. Unless you have a very slow connection, you will
probably want to leave this option selected, as there are many web pages
that are difficult to use without images. If you don't select the option
to automatically load images, you can still view the text on the page,
and then load the images if you need them.</para>

<para>Enabling <guilabel>Allow automatic delayed
reloading/redirecting</guilabel> allows websites to send you to
another page without your interaction.  In many cases, this is a
convenience.  For example, the website has moved to a new
<acronym>URL</acronym>.  Many webmasters in this situation will put up
a page on the old site, telling you that it has moved and you may like
to change your bookmark, and then automatically move you along to the
new website.  However, such features can be confusing, or annoying,
when misused, and so you may wish to disable it.</para>

<para>The next setting is <guilabel>Underline links:</guilabel>. You can
choose to underline links <guilabel>Always</guilabel>.  If this option
is selected, any text on web pages that acts as a link will be shown in
an underlined font. While many web pages do use color to distinguish
text that acts as a link, underlining makes it very easy to spot
links.</para>

<para>If you don't like underlined links, you can choose
<guilabel>Never</guilabel>, so that no links are underlined.  Or you
can choose a middle ground, <guilabel>Hover</guilabel>, so that links
are underlined when the mouse cursor is resting over them, and not
underlined the rest of the time.</para>

<para>Many web pages use animated gif images, and these can be very
annoying, and in some cases, quite a drain on your system resources.
The <guilabel>Animations</guilabel> option lets you choose when
animations are enabled.  The default is enabled, but you can set this
to disabled, or to run the animation only once, even if the file
itself contains instructions that the animation should run more times,
or continuously.</para>

</sect2>

<sect2 id="kbrowse-appearance">

<title>Fonts</title>

<para>Under this tab, you can select various options related to the use
of fonts. Although the shapes and sizes of fonts are often part of the
design of a web page, you can select some default settings for
&konqueror; to use.</para>

<para>The first thing you can set here is the font size.  There are two
settings which work together to allow you a comfortable browsing
experience.</para>

<para>Firstly, you can set a <guilabel>Minimum Font Size</guilabel>.
This means, even if the font size is set specifically in the page you
are viewing, &konqueror; will ignore that instruction and never show
smaller fonts than you set here.</para>

<para>Next you can set a <guilabel>Medium Font Size</guilabel>.  This is
not only the default size of text, used when the page doesn't specify
sizes, but it is also used as the base size that relative font sizes are
calculated against.  That is, the <acronym>HTML</acronym> instruction
<quote>smaller</quote>, it means smaller than the size you set for this
option.</para>

<para>For either option, you can select the exact font size in points by
using the up/down spin control (or just typing) next to the option
label.</para>

<para>These options are independent of each other.  Pages that do not
set a font size, or ask for the default, will display with the size
you set from <guilabel>Medium Font Size</guilabel>, while any pages
that ask for a size smaller than your <guilabel>Minimum Font
Size</guilabel> setting will instead show that size.  The one does not
affect the other.</para>

<para>The remaining options are for the fonts to be associated with
different types of markup used in <acronym>HTML</acronym> pages. Note
that many web pages may override these settings. If you click anywhere
on a control which shows a font name, a list of font names appears, and
you can select a different font if you like. (If there are a lot of
fonts, a vertical scrollbar appears in the list to allow you to scroll
through all of the fonts.)</para>
<!--
<para>You can set a font for each <quote>type</quote> of markup, for
each <guilabel>Charset</guilabel>, by changing the character set in the
first drop down box, and then selecting a font for each category below.
This would take quite some time, so you may just want to set up the
fonts for your default character set.  Most English speaking users will
use iso8859-1</para>
-->
<para>Below this, you can set a <guilabel>Font size adjustment for this
encoding</guilabel>.  Sometimes the fonts you want to use for a
particular encoding or language are much larger or smaller than average,
so you can use this setting to bring them into line.</para>

<para>You can set a default encoding that &konqueror; should assume
pages are when rendering them.  The default setting is <guilabel>Use
language encoding</guilabel>, but you can change it to any encoding
available in the list.</para>

</sect2>

<sect2 id="kbrowse-java">
<title>&Java; and JavaScript</title>

<para>&Java; allows applications to be downloaded and run by a web
browser, provided you have the necessary software installed on your
machine. Many web sites make use of &Java; (for example, online
banking services or interactive gaming sites). You should be aware
that running programs from unknown sources could pose a threat to the
security of your computer, even if the potential extent of the damage
is not great.</para>

<para>The checkboxes under <guilabel>Global Settings</guilabel> allows
you to turn &Java; support on for all web sites by default. You can
also select to turn &Java; on or off for specific hosts. To add a
policy for a specific host, click the <guilabel>Add...</guilabel>
button to bring up a dialog in which you can type the host name and
then choose to accept or reject &Java; code from that particular host,
which will add the domain to the list on the left of the page.</para>

<para>You can select a host in the list, and click the
<guilabel>Change...</guilabel> button to choose a different policy for
that host. Clicking the <guilabel>Delete</guilabel> button removes the
policy for the selected host; after deletion, the global settings will
then apply to that host. You can import policies from a file by clicking
the <guilabel>Import...</guilabel> button. To save the current list to a
compressed archive file, click the <guilabel>Export...</guilabel>
button.</para>

<para>Finally, the group of controls labeled <guilabel>Java Runtime
Settings</guilabel> allows you to set some options for the way in
which &Java; should run. These options are useful for diagnosing
problems, or if you are a &Java; developer, and should not normally
need adjusting.</para>

<para>If you select the <guilabel>Show Java
Console</guilabel> option, &konqueror; will open a console window from
which &Java; applications can read and write text. While most &Java;
applications will not require such a console, it could be helpful in
diagnosing problems with &Java; applications.</para>

<para><guilabel>Use KIO</guilabel> will cause the
<acronym>JVM</acronym>to use &kde;'s own <acronym>KIO</acronym>
transports for network connections.</para>

<para><guilabel>Use security
manager</guilabel> is normally enabled by default.  This setting will
cause the <acronym>JVM</acronym> to run with a Security Manager in place. This will keep
applets from being able to read and write to your file system, creating
arbitrary sockets, and other actions which could be used to compromise
your system. Disable this option at your own risk. You can modify your <filename>$<envar>HOME</envar>/.java.policy</filename> file with the
&Java; policytool utility to give code downloaded from certain sites
more permissions.</para>

<para>The <guilabel>Shutdown Applet Server when inactive</guilabel>
checkbox allows you to save resources by closing the &Java; Applet
Server when it is not in use, rather than leaving it running in the
background.  Leaving this disabled may make &Java; applets start up
faster, but it will use system resources when you are not using a
&Java; applet.  If you enable this, you can set a timeout.</para>

<para>You can either opt to have &konqueror; automatically detect the
&Java; installation on your system, or specify the path to the
installation yourself by selecting <guilabel>Use user-specified
Java</guilabel>. You may want to choose the latter method, for
instance, if you have multiple &Java; installations on your system,
and want to specify which one to use. If the &Java; Virtual Machine
you are using requires any special startup options, you can type them
in the text box labeled <guilabel>Additional Java
Arguments</guilabel>.</para>

</sect2>

<sect2 id="kbrowse-javascript">
<title>JavaScript</title>

<para>Despite the name, JavaScript is not related at all to
&Java;.</para>

<para>The first part of this page works the same as the &Java; page
settings.</para>

<para>The checkboxes under <guilabel>Global Settings</guilabel> allow
you to turn JavaScript support on for all web sites by default. You
can also select to turn JavaScript on or off for specific hosts. To
add a policy for a specific host, click the
<guilabel>Add...</guilabel> button to bring up a dialog in which you
can type the host name and then choose to accept or reject JavaScript
code from that particular host, which will add the domain to the list
on the left of the page.</para>

<para>You can select a host in the list, and click the
<guilabel>Change...</guilabel> button to choose a different policy for
that host. Clicking the <guilabel>Delete</guilabel> button removes the
policy for the selected host; after deletion, the global settings will
then apply to that host. You can import policies from a file by
clicking the <guilabel>Import...</guilabel> button. To save the
current list to a compressed archive file, click the
<guilabel>Export...</guilabel> button.</para>

<para>The final set of options on this page determine what happens
when a page uses JavaScript for specific actions.</para>

<para>You can individually enable or disable the ability of JavaScript
to manipulate your windows by moving, resizing or changing focus.  You
can also disable JavaScript from changing the status bar text, so that
for instance, you can always see where links will take you when
clicked.The choices for these options are <guilabel>Allow</guilabel> and
<guilabel>Ignore</guilabel>.</para>

<para>For opening a new window, there is even more control.  You can
set &konqueror; to <guilabel>Allow</guilabel> all such requests,
<guilabel>Ask</guilabel> each time a request is made, or
<guilabel>Deny</guilabel> all popup requests.</para>

<para>The <guilabel>Smart</guilabel> setting will only allow
JavaScript popup windows when you have explicitly chosen a link that
creates one.</para>

</sect2>

<sect2 id="khtml-adblock">
<title>AdBlocK</title>

<para>&konqueror; AdBlocK can be configured to replace or remove
images or frames from web pages that match a series of filters.</para>

<para>The setting <guilabel>Enable filters</guilabel> enables or
disables the use of list of URL filters.</para>
<para>If <guilabel>Hide filtered images</guilabel> is enabled then
blocked images are completely removed from the page and the space they
occupied is reclaimed. If the option is disabled then a placeholder
image is used in place of filtered images.</para>

<para><guilabel>URL expressions to filter</guilabel> is a list of
URLs that will be compared against image and frame names to decide
on fitlering actions. The wildcards can be given as filename style
regular expressions.</para>

<para>Each filter can either be expressed as a file style wildcard
string (e.g. http://www.site.com/ads/*) or as a full regular expression
by enclosing the filter with forward slashes (e.g. //(ads|dclk)\./).</para>

<para>Import and export will save or read the current filter list to a
plain text file. Lines prefixed with an exclamation mark (!) are treated
as comments and can be used to clarify or label a set of filters.</para>
</sect2>

<sect2 id="kbrowse-plugins">
<title>Plugins</title>

<para>The first setting here is <guilabel>Enable Plugins
globally</guilabel>.  If you disable this checkbox, then &konqueror;
will not use any plugins.  If you enable it, then any installed and
configured plugins that it can find will be used by &konqueror;</para>

<para>You can also restrict &konqueror; to <guilabel>Only allow HTTP
and HTTPS URLs for plugins</guilabel> by checking the box.</para>

</sect2>

&nsplugins-kcontrol;

</sect1>

</article>