Merge pull request plone#1225 from plone/polish-indexing

Spruce up Backend - Indexing chapter

Author: stevepiercy

docs/backend/indexing.md

@@ -3,7 +3,7 @@ html_meta:
   "description": "Using Plone's catalog to index content and make it searchable."
   "property=og:description": "Using Plone's catalog to index content and make it searchable."
   "property=og:title": "Indexing"
-  "keywords": "indexing, indexes, indexer, catalog, searching, FieldIndex, SearchableText, textindexer"
+  "keywords": "Plone, indexing, indexes, indexer, catalog, searching, FieldIndex, KeywordIndex, DateIndex, DateRangeIndex, BooleanIndex, ZCTextIndex, SearchableText, textindexer"
 ---
 
 (backend-indexing-label)=
@@ -12,44 +12,51 @@ html_meta:
 
 To make Plone content searchable, one can use different indexes to index content.
 
-The most important index types are:
+The most important index types are the following.
 
 - `FieldIndex`
 - `KeywordIndex`
 - `DateIndex`
-- `DateRangeindex`
+- `DateRangeIndex`
 - `BooleanIndex`
 - `ZCTextIndex`
 
-The most important indexes are:
+The most important indexes are described in the following sections.
 
-## `SearchableText`
 
-The `SearchableText` is a `ZCTextIndex` for indexing full text and is used by default for `Dublin core` fields like Title, Description and Text.
+(backend-indexing-searchabletext-label)=
+
+## `SearchableText`
 
-### TextIndexer
+The `SearchableText` is a `ZCTextIndex` for indexing full text.
+It is used by default for Dublin Core fields such as `Title`, `Description`, and `Text`.
 
-To add other fields to the `SearchableText`, one can use the `plone.app.dexterity.textindexer`.
 
-For enabling the indexer just add the behavior to the list of behaviors of your content types.
+(backend-indexing-textindexer-label)=
 
-In your *profiles/default/types/YOURTYPE.xml* add the behavior::
+## `TextIndexer`
 
-    <?xml version="1.0"?>
-    <object name="example.conference.presenter" meta_type="Dexterity FTI"
-       xmlns:i18n="http://xml.zope.org/namespaces/i18n"
-       i18n:domain="example.conference">
+To add other fields to the `SearchableText`, one can use the `plone.app.dexterity.textindexer`.
 
-     <!-- enabled behaviors -->
-     <property name="behaviors" purge="false">
-         <element value="plone.textindexer" />
-     </property>
+For enabling the indexer, add the behavior to the list of behaviors of your content types.
 
-    </object>
+In your `profiles/default/types/YOURTYPE.xml` add the behavior.
 
+```xml
+<?xml version="1.0"?>
+<object name="example.conference.presenter" meta_type="Dexterity FTI"
+   xmlns:i18n="http://xml.zope.org/namespaces/i18n"
+   i18n:domain="example.conference">
+
+ <!-- enabled behaviors -->
+ <property name="behaviors" purge="false">
+     <element value="plone.textindexer" />
+ </property>
+</object>
+```
 
 Now you need to mark the fields you want to have in your SearchableText. 
-This  can be done with the searchable directive:
+This can be done with the `searchable` directive.
 
 ```python
 from plone.app.dexterity import textindexer
@@ -63,7 +70,7 @@ class IMyBehavior(Schema):
 
 ```
 
-If you want to mark fields of an existing 3rd party behavior, it can be done using this utility function:
+If you want to mark fields of an existing third party behavior, it can be done using the following utility function.
 
 ```python
 from plone.app.dexterity.behaviors.metadata import ICategorization
@@ -73,7 +80,7 @@ utils.searchable(ICategorization, 'categorization')
 ```
 
 The `title` and `description` on `plone.app.dexterity`'s `IBasic` behavior are marked as searchable by default.
-For marking them as no longer searchable, there is a utility function:
+For marking them as no longer searchable, there is a utility function.
 
 ```python
 from plone.app.dexterity.behaviors.metadata import IBasic
@@ -82,11 +89,9 @@ from plone.app.dexterity.textindexer import utils
 utils.no_longer_searchable(IBasic, 'title')
 ```
 
-Alternatively, if you specified your model as a plone.supermodel XML model,
-you can mark the field searchable by using `indexer:searchable="true"`:
+Alternatively, if you specified your model as a `plone.supermodel` XML model, you can mark the field searchable by using `indexer:searchable="true"`.
 
 ```xml
-
 <model xmlns="http://namespaces.plone.org/supermodel/schema"
         xmlns:indexer="http://namespaces.plone.org/supermodel/indexer">
     <schema based-on="plone.supermodel.model.Schema">
@@ -100,21 +105,27 @@ you can mark the field searchable by using `indexer:searchable="true"`:
 </model>
 ```
 
+The `SearchableText` indexer now includes your custom field on your behavior.
+The field of your content type is indexed if the `plone.textindexer` behavior is enabled on your content type.
 
-Your SearchableText indexer includes now your custom field on your behavior. 
-It is enabled on your content type, if the `plone.textindexer` behavior is enabled there too.
 
+(backend-indexing-registering-custom-field-converter-label)=
 
-#### Registering a custom field converter
+## Registering a custom field converter
 
+By default a field is converted to a searchable text by rendering the widget in display mode and transforming the result to `text/plain`. 
+However if you need to convert your custom field in a different way, you have to provide a more specific converter multi-adapter.
 
-By default, a field is converted to a searchable text by rendering the widget in display mode and transforming the result to `text/plain`. 
-However, if you need to convert your custom field in a different way, you only have to provide a more specific converter multi-adapter.
 
-Convert multi-adapter specification:
+(backend-indexing-convert-multi-adapter-specification-label)=
 
-:Interface: `plone.app.dexterity.textindexer.IDexterityTextIndexFieldConverter`
-:Discriminators: context, field, widget
+### Convert multi-adapter specification
+
+Interface
+: `plone.app.dexterity.textindexer.IDexterityTextIndexFieldConverter`
+
+Discriminators
+: context, field, widget
 
 Example:
 
@@ -147,15 +158,15 @@ ZCML:
 </configure>
 ```
 
-There is already an adapter for converting files properly. 
+There is already an adapter for converting files properly.
 
 
+(backend-indexing-extending-indexed-data-label)=
 
-#### Extending indexed data
+## Extending indexed data
 
-
-Sometimes you need to extend the SearchableText with additional data which is not stored in a field. 
-It is possible to register a named adapter which provides additional data:
+Sometimes you need to extend the `SearchableText` with additional data which is not stored in a field.
+It is possible to register a named adapter which provides additional data.
 
 ```python
 from plone.app.dexterity import textindexer
@@ -187,26 +198,30 @@ ZCML:
 </configure>
 ```
 
-This is a **named** adapter! This makes it possible to register multiple
-extenders for the same object on different behavior interfaces. The name of
-the adapter does not matter, but it's recommended to use the name of the
-behavior (this may reduce conflicts).
+This is a **named** adapter!
+The named registration allows registering multiple extenders on different behavior interfaces applying to the same object.
+The name of the adapter does not matter, but it's recommended to use the name of the behavior to reduce potential conflicts.
 
-If your behavior has a defined factory (which is not attribute storage), then
-you need to define a marker interface and register the adapter on this marker
-interface (dexterity objects do not provide behavior interfaces of behaviors,
-which are not using attribute storage).
+If your behavior has a defined factory (which is not attribute storage), then you need to define a marker interface and register the adapter on this marker interface. 
+Dexterity objects do not provide behavior interfaces of behaviors, which are not using attribute storage.
 
 
+(backend-indexing-portal-type-fieldindex-label)=
 
 ## `portal_type` (`FieldIndex`)
 
-Indexes the `portal_type` field and contains values like `Folder`.
+Indexes the `portal_type` field and contains values such as `Folder`.
+
+
+(backend-indexing-path-pathindex-label)=
+
+## `path` (`PathIndex`)
+
+Indexes the object path, such as `/news/news-item-1`.
 
-## `path` (`PathIndex)`
 
-Indexes the object path, like `/news/news-item-1`.
+(backend-indexing-subject-keywordindex-label)=
 
 ## `Subject` (`KeywordIndex`)
 
-Indexes the `Subject` field which contains a list of object categories.
+Indexes the `Subject` field which contains a list of object categories.