Rewrite kiosk documentation

A lot of kiosk stuff is actually in other frameworks, from the point of
view of applications, but KConfig provides the core functionality.  Make
the docs here describe KConfig's role, rather than KIO's or KXMLGui's.

REVIEW: 117486

1 files changed, 93 insertions, 0 deletions

diff --git a/docs/options.md b/docs/options.md
new file mode 100644
index 00000000..c7a6c061
--- /dev/null
+++ b/docs/options.md
@@ -0,0 +1,93 @@
+KConfig Entry Options            {#options}
+=====================
+
+KConfig provides various options that can alter how it interprets configuration
+entries on a per-entry, per-group or per-file basis.  Note that these are not
+supported by other configuration frameworks, and so should not be used in files
+that are intended to be used by applications that do not use KConfig (such as
+application desktop files).
+
+
+Immutable Entries
+-----------------
+
+KConfig's cadcading configuration mechanism usually causes values from earlier,
+"global" configuration files to be overridden by later, "local" ones.
+Typically, the system administrator might set global defaults, and a user might
+override them in their local configuration files.
+
+However, KConfig provides a way to lock down configuration values, so that the
+global settings override the local ones.  This allows system administrators to
+restrict the values a user can set for an entry, group of entries or an entire
+configuration file.
+
+This is important for Kiosk authorization (see the KAuthorized namespace),
+which allows parts of the user interface to be locked down.
+
+Configuration entries can be marked as immutable with the `$i` option.  This can
+be done on a per-entry basis:
+
+    [MyGroup]
+    someKey[$i]=42
+
+on a per-group basis (which will prevent any attempts to modify entries in the
+group at all in later files):
+
+    [MyGroup][$i]
+    someKey=42
+
+or for an entire file by putting `[$i]` at the start of the file:
+
+    [$i]
+    [MyGroup]
+    someKey=42
+    [MyOtherGroup]
+    someOtherKey=11
+
+Once this is done, the immutable entries or groups cannot be overridden by later
+files of the same name (and, if the file is immutable, later files will be
+ignored entirely).
+
+Note that a similar effect to file immutability can be acheived by using file
+system permissions to prevent the user from writing to their local versions of
+the configuration file, although (since this is normally a setup error), the
+user will be warned that the configuration file is not writable.  This warning
+can be supressed by adding the following setting to either the relevant
+configuration file or the `kdeglobals` file:
+
+    [General]
+    warn_unwritable_config=true
+
+However, using file system permissions like this can potentially be circumvented
+by the user if they have write access to the containing directory or can modify
+environment variables (and `XDG_CONFIG_HOME` in particular).
+
+
+
+Shell Expansion
+---------------
+
+If an entry is marked with `$e`, environment variables and shell commands will
+be expanded.
+
+    Name[$e]=$USER
+    Host[$e]=$(hostname)
+
+When the "Name" entry is read `$USER` will be replaced with the value of the
+`$USER` environment variable, and `$(hostname)` will be replaced with the output
+of the `hostname` command.
+
+Note that the application will replace `$USER` and `$(hostname)` with their
+respective expanded values after saving. To prevent this combine the `$e` option
+with `$i` (immmutable) option.  For example:
+
+    Name[$ei]=$USER
+
+This will make that the "Name" entry will always return the value of the `$USER`
+environment variable. The user will not be able to change this entry.
+
+The following syntax for environment variables is also supported:
+
+    Name[$ei]=${USER}
+
+