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

3 files changed, 445 insertions, 0 deletions

diff --git a/doc/kcontrol/khtml/Makefile.am b/doc/kcontrol/khtml/Makefile.am
new file mode 100644
index 000000000..c54c99e96
--- /dev/null
+++ b/doc/kcontrol/khtml/Makefile.am
@@ -0,0 +1,2 @@
+KDE_LANG = en
+KDE_DOCS = kcontrol/khtml
diff --git a/doc/kcontrol/khtml/index.docbook b/doc/kcontrol/khtml/index.docbook
new file mode 100644
index 000000000..9f204f075
--- /dev/null
+++ b/doc/kcontrol/khtml/index.docbook
@@ -0,0 +1,352 @@
+<?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>
diff --git a/doc/kcontrol/khtml/nsplugin.docbook b/doc/kcontrol/khtml/nsplugin.docbook
new file mode 100644
index 000000000..1f8547461
--- /dev/null
+++ b/doc/kcontrol/khtml/nsplugin.docbook
@@ -0,0 +1,91 @@
+<sect2 id="nsplugins">
+<title>&Netscape; Plugins</title>
+
+<sect3 id="nsplugins-intro">
+<title>Introduction</title>
+
+<para>As &Netscape;'s <application>Navigator</application> has been a
+web browsing standard for many years, so-called &Netscape; plugins have
+appeared that allow rich web content.  Using those plugins, web sites
+can contain <acronym>PDF</acronym> files, flash animations, video, &etc;
+With &konqueror;, you can still use these plugins to take advantage of
+rich web content.</para>
+
+<note><para>&Netscape; plugins should not be confused with &konqueror;
+plugins. The latter ones specifically extend &konqueror;'s
+functionality; they are normally not used to display rich web
+content.</para></note>
+
+</sect3>
+
+<sect3 id="nsplugins-scan">
+<title>Scan</title>
+
+<para>&konqueror; has to know where your &Netscape; plugins are
+installed.  This can be in several places, &ie; you might have
+system-wide plugins in <filename
+class="directory">/opt/netscape/plugins</filename> and your personal
+plugins in <filename
+class="directory">$<envar>HOME</envar>/.netscape/plugins</filename>.
+However, &konqueror; will not automatically use the installed plugins:
+it first has to scan a list of folders.  You can initiate the scan
+by clicking <guibutton>Scan for new plugins</guibutton>.  Alternatively,
+you can enable <guilabel>Scan for new plugins at &kde; startup</guilabel>
+so &konqueror; will scan the appropriate folders every time &kde; 
+starts up, to see whether new plugins have been installed.</para>
+
+<note><para>Enabling <guilabel>Scan for new plugins at &kde;
+startup</guilabel> can considerably slow down the startup procedure,
+and is known to give difficulty on certain installations.  Turn this
+option off if you experience problems.</para></note>
+
+<para>To find plugins, &konqueror; will look in the folders
+specified in the <guilabel>Scan Folders</guilabel> frame.  When you
+use this control module for the first time, this list will already be
+filled with reasonable paths that should work on most operating systems.
+If you need to provide a new path, click the <guibutton>New</guibutton>
+button; then you can either enter the new path in the text edit box to
+the left, or choose a folder using the file dialog by clicking the
+<guibutton>New...</guibutton> button.  As scanning the folders can take
+a little time, you might want to remove folders from the list where
+you know that no plugins are installed: do this by selecting a folder
+and clicking <guibutton>Remove</guibutton>.  Using the
+<guibutton>Up</guibutton> and <guibutton>Down</guibutton> buttons you
+can change the order in which folders will be scanned by moving the
+selected folder up or down.</para>
+
+<para>As usual, click <guibutton>Apply</guibutton> to save your changes
+permanently.</para>
+
+</sect3>
+
+<sect3 id="nsplugins-plugins">
+<title>Plugins</title>
+
+<para>In this tab, you can see a list of the &Netscape; plugins found by
+&konqueror;, displayed as a tree.  Double click on a plugin to fold it
+out and you'll see that the different mime types this plugin can handle
+will be displayed as branches.  Fold out a mime type to see its
+info.</para>
+
+<para>This tab is mostly for informational purposes.  The only
+configurable option is <guilabel>Use artsdsp to pipe plugin sound
+through aRts</guilabel>, which is enabled by default. Disable this if
+you wish plugins to use their own method for sounds, and you have
+configured &arts; in such a way that third-party applications can do
+so (for example, by having it exit when idle, or by having it use a
+custom sound device on modern soundcards which allow this.)</para>
+
+</sect3>
+
+<sect3 id="nsplugins-author">
+<title>Section Author</title>
+
+<para>This section written by: Jost Schenck
+<email>[email protected]</email></para>
+
+<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+</sect3>
+
+</sect2>