syncope git commit: More grammatical work on the reference guide

[co...@apache.org]

Repository: syncope
Updated Branches:
  refs/heads/master 9aea42ba0 -> dae8e14a7


More grammatical work on the reference guide


Project: http://git-wip-us.apache.org/repos/asf/syncope/repo
Commit: http://git-wip-us.apache.org/repos/asf/syncope/commit/dae8e14a
Tree: http://git-wip-us.apache.org/repos/asf/syncope/tree/dae8e14a
Diff: http://git-wip-us.apache.org/repos/asf/syncope/diff/dae8e14a

Branch: refs/heads/master
Commit: dae8e14a747b1501072a6cce991f954e01dc6098
Parents: 9aea42b
Author: Colm O hEigeartaigh <co...@apache.org>
Authored: Thu Aug 11 11:05:03 2016 +0100
Committer: Colm O hEigeartaigh <co...@apache.org>
Committed: Thu Aug 11 11:05:03 2016 +0100

----------------------------------------------------------------------
 .../concepts/externalresources.adoc             | 40 ++++++++++----------
 .../concepts/typemanagement.adoc                | 31 +++++++--------
 2 files changed, 36 insertions(+), 35 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/syncope/blob/dae8e14a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
index 0fc4f9a..ef2cdd4 100644
--- a/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/externalresources.adoc
@@ -23,7 +23,7 @@ Connector Bundles:: The components able to connect to identity stores; not speci
 as they are part of the http://connid.tirasa.net[ConnId^] project.
 Connector Instances:: Instances of connector bundles, obtained by assigning values to the defined configuration 
 properties. For instance, there is only a single `DatabaseTable` (the bundle) that can be instantiated
-several times, for example if there is need to connect to different databases.
+several times, for example if there is a need to connect to different databases.
 External Resources:: Meant to encapsulate all information about how Apache Syncope will use connector instances for 
 provisioning. For each entity supported by the related connector bundle (user, group, printer, services, ...),
 <<mapping,mapping>> information can be specified.
@@ -46,7 +46,7 @@ be JDBC URL, table name, etc.
 * capabilities - define what operations are allowed on this connector: during <<provisioning,provisioning>>, if a
 certain operation is invoked but the corresponding capability is not set on the related connector instance, no actual
 action is performed on the underlying connector; the capabilities are:
-** `AUTHENTICATE` - consent <<pass-through-authentication, pass-through authentication>>
+** `AUTHENTICATE` - consent to <<pass-through-authentication, pass-through authentication>>
 ** `CREATE` - create objects on the underlying connector
 ** `UPDATE` - update objects on the underlying connector
 ** `DELETE` - delete objects on the underlying connector
@@ -61,16 +61,16 @@ action is performed on the underlying connector; the capabilities are:
 Capabilities and individual configuration properties can be set for _override_: in this case, all the external resources
 using the given connector instance will have the chance to override some configuration values, or the capabilities set.
 
-This can be useful when the same connector instance is shared among different resources, with small difference in the
+This can be useful when the same connector instance is shared among different resources, with little difference in the
 required configuration or capabilities.
 ====
 
 ==== External Resource details
 
-Given a selected connector instance, the following information is required for defining an external resource:
+Given a selected connector instance, the following information is required to define an external resource:
 
 * priority - integer value, in use by the default <<propagation,propagation task executor>>
-* generate random password flag - under some circumstances, password might be mandatory but no actual value could be
+* generate random password flag - under some circumstances, a password might be mandatory but no actual value could be
 available: with this flag set, a random value will be generated, compliant with the defined
 <<policies-password,password policy>> (if set)
 * propagation actions - which <<propagationactions,actions>> shall be executed during propagation
@@ -89,19 +89,19 @@ resource
 
 ==== Mapping
 
-One of the most crucial information to provide, when configuring an external resource, is the mapping between internal
-and external data. Such information, in fact, plays a key role for <<provisioning,provisioning>>.
+The mapping between internal and external data is of crucial importance when
+configuring an external resource. Such information, in fact, plays a key role for <<provisioning,provisioning>>.
 
 [.text-center]
 image::mapping.png[title="Sample mapping",alt="Sample mapping"]
 
 For each of the <<anytype,any types>> supported by the underlying connector, a different mapping is provided.
 
-Mapping is essentially a collection of _mapping items_ describing the correspondance between an user / group / any
-object attribute and its counterpart on the identity store represented by the current external resource; each item
+A mapping is essentially a collection of _mapping items_ describing the correspondance between an user / group / any
+object attribute and its counterpart on the identity store represented by the current external resource. Each item
 specifies:
 
-* internal attribute - the <<schema, schema>> acting as source or destination of provisioning operations; must be
+* internal attribute - the <<schema, schema>> acting as the source or destination of provisioning operations; it must be
 specified by an expression matching one of the following models:
 ** `schema` - resolves to the attribute for the given `schema`, owned by the mapped entity (user, group, any object)
 ** `groups[groupName].schema` - resolves to the attribute for the given `schema`, owned by the group with name
@@ -109,7 +109,7 @@ specified by an expression matching one of the following models:
 ** `anyObjects[anyObjectName].schema` - resolves to the attribute for the given `schema`, owned by the any object with
 name `anyObjectName`, if a relationship with the mapped entity exists
 ** `memberships[groupName].schema` - resolves to the attribute for the given `schema`, owned by the membership for group
-`groupName` of the mapped entity (user, any object), if such membership exists
+`groupName` of the mapped entity (user, any object), if such a membership exists
 * external attribute - the name of the attribute on the identity store
 * transformers - http://commons.apache.org/proper/commons-jexl/[JEXL^] expression or Java class implementing
 ifeval::["{snapshotOrRelease}" == "release"]
@@ -120,18 +120,18 @@ https://github.com/apache/syncope/blob/master/core/provisioning-api/src/main/jav
 endif::[]
 ; the purpose is to transform values before they are sent to or received from the underlying connector
 * mandatory condition - http://commons.apache.org/proper/commons-jexl/[JEXL^] expression indicating whether values for 
-this mapping item must be necessarily available or not; compared to simple boolean value, such condition allows to
-express complex statements like as 'be mandatory only if this other attribute value is above 14', and so on
+this mapping item must be necessarily available or not; compared to a simple boolean value, such condition allows
+complex statements to be expressed such as 'be mandatory only if this other attribute value is above 14', and so on
 * remote key flag - should this item be considered as the key value on the identity store?
-* password flag (users only) - should this item be treated as password value?
+* password flag (users only) - should this item be treated as the password value?
 * purpose - should this item be considered for <<propagation,propagation>> / <<provisioning-push,push>>,
 <<provisioning-pull,pull>>, both or none? 
 
-Besides items, some more data needs to be specified for a complete mapping:
+Besides the items documented above, some more data needs to be specified for a complete mapping:
 
 * ConnId `objectClass` - which
 http://connid.tirasa.net/apidocs/1.4/org/identityconnectors/framework/common/objects/ObjectClass.html[object class^]
-shall be used during communication with identity store; predefined are `\\__ACCOUNT__` for users and 
+shall be used during communication with the identity store; predefined are `\\__ACCOUNT__` for users and 
 `\\__GROUP__` for groups
 * Object link - only required by some connector bundles as
 https://connid.atlassian.net/wiki/display/BASE/LDAP[LDAP^] and
@@ -140,7 +140,7 @@ for generating the DN (distinguished name) values
 
 .Mapping items
 ====
-The following mapping item binds mandatory the internal `name` schema with external attribute `cn` for both 
+The following mapping item binds the mandatory internal `name` schema with the external attribute `cn` for both 
 propagation / push and pull.
 
 [source,json]
@@ -156,9 +156,9 @@ propagation / push and pull.
 }
 ----
 
-The following mapping item binds optional the internal `aLong` schema for the membership of the `additional` group
-with external attribute `age` for propagation / push only; moreover, specifies JEXL expression which appends `.0`
-to the selected `aLong` value before sending out to the underlying connector.
+The following mapping item binds the optional internal `aLong` schema for the membership of the `additional` group
+with the external attribute `age` for propagation / push only; in addition, it specifies a JEXL expression which appends `.0`
+to the selected `aLong` value before sending it out to the underlying connector.
 
 [source,json]
 ----

http://git-wip-us.apache.org/repos/asf/syncope/blob/dae8e14a/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc
----------------------------------------------------------------------
diff --git a/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc b/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc
index 63713c1..044f196 100644
--- a/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc
+++ b/src/main/asciidoc/reference-guide/concepts/typemanagement.adoc
@@ -82,31 +82,32 @@ evaluating the related JEXL expression
 
 ===== Virtual
 
-Virtual attributes are somehow linked from identity stores rather than kept internally.
+Virtual attributes are somehow linked from identity stores rather than stored internally.
 
-The typical use case is when attribute values can change on identity store without notice, and there is need of 
-having always access to the most recent available values.
+The typical use case is when attribute values can change in the identity store without notice, and it is required to
+always have access to the most recent values that are available.
 
-It can also be said that virtual schemas are for attributes whose ownership is not of Syncope but of identity stores;
+It can also be said that virtual schemas are for attributes whose ownership is not that of Syncope but of an identity store;
 the external resources for such identity stores are said to be the _linking resources_.
 
 [TIP]
 As best practice, only attributes for which Apache Syncope retains ownership should be modeled as plain attributes;
-others should be virtual, instead.
+attributes for which Apache Syncope does not retain ownership should be modeled
+as virtual instead.
 
-When defining a virtual schema, the following information is to be provided:
+When defining a virtual schema, the following information must be provided:
 
 * External resource - linking resource
-* External attribute - attribute to be linked on external resource
-* Any Type - reference <<anytype,Any Type>> on external resource
-* Read-only flag - whether the external attribute value(s) for this schema can only be read, or written too
+* External attribute - attribute to be linked on the external resource
+* Any Type - reference <<anytype,Any Type>> on the external resource
+* Read-only flag - whether the external attribute value(s) for this schema can only be read, or whether they can be written to as well
 
 .Virtual Attribute Cache
 ****
 For performance optimization, virtual attributes are managed by an internal cache to control the actual access to 
 the linked identity stores.
 
-The actual cache implements the 
+The internal cache implements the 
 ifeval::["{snapshotOrRelease}" == "release"]
 https://github.com/apache/syncope/blob/syncope-{docVersion}/core/provisioning-api/src/main/java/org/apache/syncope/core/provisioning/api/cache/VirAttrCache.java[VirAttrCache^]
 endif::[]
@@ -136,7 +137,7 @@ endif::[]
 ifeval::["{snapshotOrRelease}" == "snapshot"]
 https://github.com/apache/syncope/blob/master/core/provisioning-java/src/main/java/org/apache/syncope/core/provisioning/java/cache/DisabledVirAttrCache.java[DisabledVirAttrCache^]
 endif::[]
-| Pass-through cache which actually does not provide any caching: use when actual access to identity store is required.
+| Pass-through cache which actually does not provide any caching: use when direct access to the identity store is required.
 
 |===
 ****
@@ -153,7 +154,7 @@ given user / group / any object instance) and for <<type-extensions,type extensi
 Any types represent the type of identities that Apache Syncope is able to manage; besides the predefined `USER` and 
 `GROUP`, more types can be created to model workstations, printers, folders, sensors, services, ...
 
-For all any types defined, a set of <<anytypeclass, classes>> can be selected so that instances af a given any type will
+For all any defined types, a set of <<anytypeclass, classes>> can be selected so that instances af a given any type will
 be enabled to populate attributes for schemas in those classes.
 
 .Any types and attributes allowed for users, groups and any objects
@@ -251,7 +252,7 @@ increase readability):
 
 ==== RelationshipType
 
-Relationships allow to create a link between an user and an any object, or between two any objects; relationship types
+Relationships allow the creation of a link between a user and an any object, or between two any objects; relationship types
 define the available link types.
 
 .Relationship between any objects (printers)
@@ -294,14 +295,14 @@ The following any object of type `PRINTER` contains a relationship of type `neig
 
 ==== Type Extensions
 
-When an user (or an any object) is part of a group, a _membership_ is defined.
+When a user (or an any object) is part of a group, a _membership_ is defined.
 
 It is sometimes useful to define attributes which are bound to a particular membership: if, for example, the
 `University A` and `University B` groups are available, a student might have different e-mail addresses for each
 university. How can this be modeled?
 
 Type extensions define a set of <<anytypeclass,classes>> associated to a group, that can be automatically
-assigned to a given user (or any object) when becoming member of such group.
+assigned to a given user (or any object) when becoming a member of such group.
 
 .Membership with type extension
 ====