svn commit: r1789103 - /sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext

[kw...@apache.org]

Author: kwin
Date: Tue Mar 28 12:05:56 2017
New Revision: 1789103

URL: http://svn.apache.org/viewvc?rev=1789103&view=rev
Log:
clarify run mode options

Modified:
    sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext

Modified: sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext
URL: http://svn.apache.org/viewvc/sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext?rev=1789103&r1=1789102&r2=1789103&view=diff
==============================================================================
--- sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext (original)
+++ sling/site/trunk/content/documentation/bundles/sling-settings-org-apache-sling-settings.mdtext Tue Mar 28 12:05:56 2017
@@ -14,11 +14,11 @@ The Sling Settings Bundle exposes the `S
 The new Sling Settings Bundle replaces the former [Run Modes (org.apache.sling.runmode)]({{ refs.run-modes-org-apache-sling-runmode.path }}) Bundle and the `SlingSettingsService` previously provided by the Sling Engine bundle, as it also implements the run modes logic.
 
 ## Selecting the active run modes
-The run modes are selected based on the `sling.run.modes` property (the "selection property"), specified in the Sling settings file or as a command-line parameter (which takes precedence), out of the valid run modes defined by the properties described below.
+The run modes are selected based on the `sling.run.modes` property (the "selection property"), specified in the Sling settings file or as a command-line parameter (which takes precedence), out of the valid run modes defined by the properties described below. The value is a String which contains a list of comma-separated run modes. If a run mode is given here which is not contained in any group of valid run modes (given in `sling.run.mode.install.options` or `sling.run.mode.options`) it is always active, on the other hand run modes which are contained in any of the predefined groups may be modified/removed (see below for the details).
 
 Using `-Dsling.run.modes=foo,bar` on the JVM command-line, for example, activates the *foo* and *bar* run modes if that combination is valid.
 
-The Absolute Truth about run modes definition and selection is found in the [RunModeImplTest](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/settings/src/test/java/org/apache/sling/settings/impl/RunModeImplTest.java) which should be self-explaining.
+The absolute truth about run modes definition and selection is found in the [RunModeImplTest](https://svn.apache.org/repos/asf/sling/trunk/bundles/extensions/settings/src/test/java/org/apache/sling/settings/impl/RunModeImplTest.java) which should be self-explaining.
 
 ## Defining valid run modes
 Since [SLING-2662](https://issues.apache.org/jira/browse/SLING-2662) the valid run modes are defined by the `sling.run.mode.options` and `sling.run.mode.install.options` configuration properties, usually defined in the `sling.properties` file or in the provisioning model of a Sling Launchpad instance.
@@ -31,30 +31,35 @@ The value of the both these properties i
 
     red,green,blue|one|moon,mars
 
-where comma-separated groups of run modes are separated by a pipe character (which is not an OR operation, it's just as separator).
+where *comma-separated run modes form a group*. The individual groups are separated by a pipe character (`|`, which is not an OR operation, it's just as separator). A group defines a number of run modes which are **mutually exclusive**. It means once a group is defined, exactly one run mode will be active from that group.
 
-Once a group is defined, exactly one run mode will be active from that group. 
+The example from above consists out of 3 different groups
 
-If none of the listed run modes are selected, the first one from each group is activated by default. 
+1. `red,green,blue`
+2. `one`
+3. `moon,mars`
 
-If one is selected, this is active.
+The rules for determining the active run modes from the selected run mode (`sling.run.modes`) and the run mode options (`sling.run.mode.install.options` and `sling.run.mode.options`) are as follows : 
 
-If several are selected, the first one from the list of valid modes is used.
+1. If none of the run modes in the options are selected, the first one from each group in the options is activated by default. 
+1. If one is selected from a group in the options, this is active.
+1. If several are selected from one group in the options, the first one from the list of valid run modes is used.
+1. If the selected run mode is not mentioned in any of the option groups it is active
 
 Examples
 
     sling.run.mode.options=a,b|c,d,e
 
-User Defines -> Result:
+User defined run modes (e.g. via property `sling.run.modes`) | Effectively active run modes
+--- | ---
+(none) | `a,c`
+`a` | `a,c`
+`b` | `b,c`
+`a,b` | `a,c`
+`a,d` | `a,d`
+`a,e,f` | `a,e`
 
-    -> a,c
-    a -> a,c
-    b -> b,c
-    a,b -> a,c
-    a,d -> a,d
-    a,e,f -> a,e
-
-Remember to look at the `RunModeImplTest` mentioned above for details, and feel freee to enhance it with useful examples.
+Remember to look at the `RunModeImplTest` mentioned above for details, and feel free to enhance it with useful examples.
 
 ### Getting the Run Modes of the Sling instance