Item14237: Added feature sets to the essentials topic

Minor docs fixes

core/data/System/FeatureSets.txt

@@ -0,0 +1,33 @@
+%META:TOPICINFO{author="ProjectContributor" date="1508803797" format="1.1" version="1"}%
+%META:TOPICPARENT{name="FoswikiV3Essentials"}%
+---+ Feature Sets
+
+This is a completely new concept for allowing fine granular compatibility
+checks.  If we consider a feature as some functionality provided by Foswiki (or
+any other code) and focused on a particular subject (like support of PSGI, or OO
+with help of Moo framework) then feature set is composed of many features and
+ideally it would represent Foswiki (or any other code) functionality. Though
+usually software version represents more/less same concept but there is a
+difference; especially when it comes to automated compatibility checks.
+
+Let's see how it works with an example. Suppose the core has switched from using
+Moo for the OO framework to Moose in Foswiki v4. Most extensions depending on
+Moo would stop working because of incompatibilities between the two frameworks.
+So, we must not use any extension not declaring v4 compatibility. Ok, what if
+changes from v3 to v4 are less significant but numerous? Say, an outdated
+feature is gone but otherwise v4 would maintain good backward compatibility. All
+v3 compatible extensions are still ok under v4 except for a few depending on the
+outdated feature. With version-based compatibility check we would still require
+the extensions to be disabled until they're fixed. But wait, can changing a
+single with API version be called a fix? And what if a otherwise perfectly ok
+extension is abandoned by its author?
+
+With feature sets in place it would then be possible do declare the removed
+features as unsupported by v4 and to disable only those few extensions which are
+requiring them. The rest would continue working as if no major version switch
+took place. Basically, specifying required features would demand a little more
+from a developer on the initial stages of extension development but it would
+save its users from many headaches in the future.
+
+See more details in %PERLDOC{"Fosweiki::FeatureSet"}% module documentation.
+

core/data/System/FoswikiV3Essentials.txt

@@ -1,4 +1,4 @@
-%META:TOPICINFO{author="ProjectContributor" date="1508637123" format="1.1" version="1"}%
+%META:TOPICINFO{author="ProjectContributor" date="1508803797" format="1.1" version="1"}%
 %META:TOPICPARENT{name="DeveloperDocumentationCategory"}%
 ---+ Foswiki v3 Essentials
 %TOC%
@@ -48,6 +48,7 @@ There are some under the hood changes in behaviour of some components like
    $ [[EngineRevisedV3]] : Engine new role in Foswiki V3.
    $ [[ChainedExecutionFlow]] : Callbacks and extensions chaining of calls.
    $ [[CallbacksFramework]] : Callbacks framework
+   $ [[FeatureSets]] : Compatibility checks with feature sets
 
 ---++ New Standards And Major Changes
 

core/lib/Foswiki/FeatureSet.pm

@@ -50,7 +50,7 @@ was declared deprecated; and finally the version when support for the feature is
 cancelled. A keyword paired with version triplet represents a complete feature
 information required to technically describe a feature.
 
-*NOTE* An obsoleted feature description must never be removed from the source
+%X% *NOTE:* An obsoleted feature description must never be removed from the source
 code. First in order to provide necesarry information to some third-party code
 which may rely on this entry to exists. Second to avoid re-use of the same
 keyword for different or differently implemented feature. For example, would
@@ -122,11 +122,12 @@ a duplicate feature keyword will result in raising =Foswiki::Exception::Fatal=
 exception.
 
 #AppContext
----++ Application context
+---++ Application Context
 
-Active features (including the deprecated ones) are registered in the application
-context and could be checked by any code where the context is accessible. This
-is specifically useful as not all code has access to the core API.
+Active features (including the deprecated ones) are registered in the
+%PERLDOC{"Foswiki::App" attr="context" text="application context"}% and could be
+checked by any code where the context is accessible. This is specifically useful
+as not all code has access to the core API.
 
 Before registered in the context a feature names gets transofrmed to avoid
 possible name conflicts with other context entries and between featues from
@@ -258,7 +259,7 @@ sub features_provided (@) {
 
 =begin TML
 
----+++ StatucMethod getFSNamespaces => @nsList
+---+++ StaticMethod getFSNamespaces => @nsList
 
 Returns unordered list of registered namespaces.
 
@@ -270,7 +271,7 @@ sub getFSNamespaces {
 
 =begin TML
 
----++ StatucMethod nsExists( $ns ) => $bool
+---+++ StaticMethod nsExists( $ns ) => $bool
 
 Returns true if namespace defined by =$ns= exists.