Merge lp:~michihenning/unity-scopes-api/config-params into lp:unity-scopes-api

[Michi Henning]

Documented missing config settings.

Documented missing config settings.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:275
http://jenkins.qa.ubuntu.com/job/unity-scopes-api-ci/490/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-amd64-ci/15
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/15
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/15/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-i386-ci/15

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-ci/490/rebuild

review: Approve (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:276
http://jenkins.qa.ubuntu.com/job/unity-scopes-api-ci/491/
Executed test runs:
    FAILURE: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-amd64-ci/16/console
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/16
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/16/artifact/work/output/*zip*/output.zip
    FAILURE: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-i386-ci/16/console

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-ci/491/rebuild

review: Needs Fixing (continuous-integration)

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:276
http://jenkins.qa.ubuntu.com/job/unity-scopes-api-ci/494/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-amd64-ci/19
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/19
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-armhf-ci/19/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-vivid-i386-ci/19

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-ci/494/rebuild

review: Approve (continuous-integration)

[Paweł Stołowski (stolowski)]

+1

review: Approve

=== modified file 'doc/tutorial.dox'
--- doc/tutorial.dox	2014-12-10 10:15:55 +0000
+++ doc/tutorial.dox	2015-01-06 06:09:16 +0000
@@ -1128,6 +1128,9 @@
     ResultsTtlType = None, Small, Medium, or Large
     ChildScopes =
     Keywords =
+    IdleTimeout = idle timeout in seconds
+    LocationDataNeeded = true or false
+    ScopeRunner = path_to_scope_runner args... %R %S
 
     [Appearance]
     ForegroundColor = default text color (defaults to theme-provided foreground color)
@@ -1142,7 +1145,10 @@
     PageHeader.DividerColor = color of the header divider
     PageHeader.NavigationBackground = background scheme of the navigation bar
 
-The `ScopeConfig` group is mandatory and must contain settings for at least `DisplayName`, `Description`, and `Author`.
+The `ScopeConfig` group is mandatory. The information in this group makes the scope known to the registry.
+In addition, this information controls how the scope appears in the "Scopes" scope.
+
+The `ScopeConfig` group must contain settings for at least `DisplayName`, `Description`, and `Author`.
 `DisplayName` and `Description` can (and should) be localized. For example:
 
 `Description[de_DE] = Fußballergebnisse`
@@ -1154,11 +1160,27 @@
 your scope is installed.
 If not set, the default value is 0. You can set the value to any integer >= 1.
 
-In addition to allowing the registry to make the scope available, this information controls how the scope appears
-in the "Scopes" scope.
-
-The group `Appearance` and all keys within are optional and can be used to customize the look of the scope.
-Some of the `Appearance` keys (like `PageHeader.Background`) require background scheme uris. Valid uris for these keys include:
+The `IdleTimeout` key controls how long a scope can remain idle before it is told to stop by the registry (or
+killed if it does not stop within 4 seconds). The default idle timeout is 40 seconds, meaning that a
+scope will be told to stop if no query was sent to it for that amount of time.
+
+`LocationDataNeeded` should be set to `true` if the scope requires location data. In that case, the
+\link unity::scopes::SearchMetadata SearchMetadata\endlink provides access to
+\link unity::scopes::Location Location\endlink information
+(assuming the user has granted location permission to the scope). If not set, the default value is `false`.
+
+The `Scoperunner` key defines a command line to be executed when the scope is started by the registry.
+Typically, scopes do not need to change this setting. It is provided mainly to allow scopes implemented
+in languages other than C++ to be started, as well as for debugging.
+For example, the following setting causes a scope to be run under `gdb`:
+
+`ScopeRunner = /usr/bin/gdb --ex run --args /usr/lib/x86_64-linux-gnu/unity-scopes/scoperunner %R %S`
+
+The `%R` expands to the path to the `Runtime.ini` config file, and `%S` expands to the scope's `.ini` file.
+
+The `Appearance` group and all keys within it are optional and can be used to customize the look of the scope.
+Some of the `Appearance` keys (such as `PageHeader.Background`) require background scheme uris.
+Valid uris for these keys include:
 
 <ul>
 <li>color:///\#aarrggbb</li>