Rephrase documentation parts

Signed-off-by: Ivan Kanakarakis <ivan.kanak@gmail.com>

Author: c00kiemon5ter

docs/howto/config.rst

@@ -235,10 +235,12 @@ encryption_keypairs
 Indicates which certificates will be used for encryption capabilities::
 
     # Encryption
-    'encryption_keypairs': [{
-        'key_file': BASE_DIR + '/certificates/private.key',
-        'cert_file': BASE_DIR + '/certificates/public.cert',
-    }],
+    'encryption_keypairs': [
+        {
+            'key_file': BASE_DIR + '/certificates/private.key',
+            'cert_file': BASE_DIR + '/certificates/public.cert',
+        },
+    ],
 
 metadata
 ^^^^^^^^
@@ -273,7 +275,7 @@ For example::
             {
                 "url": "https://mdq.thaturl.org/",
                 "disable_ssl_certificate_validation": True,
-                "check_validity": False
+                "check_validity": False,
             },
         ],
     },
@@ -286,9 +288,11 @@ metadata signing certificates should be used.  These public keys must be
 acquired by some secure out-of-band method before being placed on the local
 file system.
 
-When using MDQ or remote, the paramenter *disable_ssl_certificate_validation*
-prevents that the validity of ssl certificate involved in the https connection
-will be verified. *check_validity* to False accept as valid the metadata that has expired.
+When the parameter *check_validity* is set to False metadata that have expired
+will be accepted as valid.
+
+When the paramenter *disable_ssl_certificate_validation* is set to True the
+validity of ssl certificate will be skipped.
 
 When using MDQ, the `freshness_period` option can be set to define a period for
 which the metadata fetched from the the MDQ server are considered fresh. After
@@ -406,8 +410,8 @@ difference you are prepared to accept.
 allow_unknown_attributes
 """"""""""""""""""""""""
 
-Indicates that attributes not configured in attribute-mapping, with
-unsupported attribute name format, will not be discarded.
+Indicates that attributes that are not recognized (they are not configured in
+attribute-mapping), will not be discarded.
 Default to False.
 
 xmlsec_binary
@@ -465,7 +469,9 @@ True or False. Default is False.
 
 want_authn_requests_only_with_valid_cert
 """"""""""""""""""""""""""""""""""""""""
-This option make mandatory the presence of the SP cert in a (signed) AuthnRequest.
+
+When verifying a signed AuthnRequest ignore the signature and verify the
+certificate.
 
 policy
 """"""
@@ -914,14 +920,14 @@ Example::
 only_use_keys_in_metadata
 """""""""""""""""""""""""
 
-If True prevents that the certificate contained in a
-SAML message, if present, will be used for signature verification.
+If set to False, the certificate contained in a SAML message will be used for
+signature verification.
 Default True.
 
 validate_certificate
 """"""""""""""""""""
 
-Indicates that the certificate used in signatures must be valid.
+Indicates that the certificate used in sign SAML messages must be valid.
 Default to False.
 
 logout_requests_signed
@@ -1088,21 +1094,29 @@ Other considerations
 
 Entity Categories
 -----------------
-Entity categories and their attributes are defined in src/saml2/entity_category/<registrar of entcat>.py
+
+Entity categories and their attributes are defined in
+src/saml2/entity_category/<registrar-of-entity-category>.py.
 We can configure Entity Categories in pysaml2 in two ways:
 
-1. As EntityAttributes, *entity_category_support* or *entity_category*.
-2. As Policy, it acts like a filter.
+1. Using the configuration options *entity_category_support* or
+   *entity_category*, to generate the appropriate EntityAttribute metadata
+   elements.
+2. Using the configuration option *entity_categories* as part of the policy
+   configuration, to make the entity category work as a filter on the
+   attributes that will be released.
 
-Entity Category and Entity Category support can be configured as follow::
+If the entity categories are configured as metadata, as follow::
 
     'debug' : True,
     'xmlsec_binary': get_xmlsec_binary([/usr/bin/xmlsec1']),
     'entityid': '%s/metadata' % BASE_URL,
 
     # or entity_category: [ ... ]
-    'entity_category_support': [edugain.COCO, # "http://www.geant.net/uri/dataprotection-code-of-conduct/v1"
-                                refeds.RESEARCH_AND_SCHOLARSHIP],
+    'entity_category_support': [
+        edugain.COCO, # "http://www.geant.net/uri/dataprotection-code-of-conduct/v1"
+        refeds.RESEARCH_AND_SCHOLARSHIP,
+    ],
 
     'attribute_map_dir': 'data/attribute-maps',
     'description': 'SAML2 IDP',
@@ -1114,21 +1128,21 @@ Entity Category and Entity Category support can be configured as follow::
 In the metadata we'll then have::
 
     <md:Extensions>
-    <mdattr:EntityAttributes>
+      <mdattr:EntityAttributes>
         <saml:Attribute Name="http://macedir.org/entity-category-support" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:uri">
-        <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://www.geant.net/uri/dataprotection-code-of-conduct/v1</saml:AttributeValue>
-        <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://refeds.org/category/research-and-scholarship</saml:AttributeValue>
+          <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://www.geant.net/uri/dataprotection-code-of-conduct/v1</saml:AttributeValue>
+          <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xsi:type="xs:string">http://refeds.org/category/research-and-scholarship</saml:AttributeValue>
         </saml:Attribute>
-    </mdattr:EntityAttributes>
+      </mdattr:EntityAttributes>
 
-If Entity Category would be configured instead in the policy section, as follow, it
-will acts like a filter on the released attributes.
+If the entity categories are configurated in the policy section, they will act
+as filters on the released attributes.
 
 Example::
 
     "policy": {
-    "default": {
+      "default": {
         "lifetime": {"minutes": 15},
-
-        # if the sp are not conform to entity_categories the attributes will not be released
+        # if the SP is not conform to entity_categories
+        # the attributes will not be released
         "entity_categories": ["refeds",],