HSEARCH-4461 Fix typos and grammar in documentation

documentation/src/main/asciidoc/reference/architecture.asciidoc

@@ -276,7 +276,7 @@ allowing retries for as long as necessary.
 ** the possibility of out-of-sync indexes caused by <<limitations-parallel-embedded-update,concurrent updates>>
 that affects other architectures is eliminated here,
 because <<coordination-outbox-polling-indexing-full-loading,each entity instance is reloaded from the database within a new transaction>>
-before being reindexed.
+before being re-indexed.
 * Easy to extend: you can easily access most Elasticsearch features,
 even those that are not exposed by Hibernate Search, by providing your own JSON.
 See for example <<search-dsl-predicate-extensions-elasticsearch-from-json,JSON-defined predicates>>,

documentation/src/main/asciidoc/reference/backend-elasticsearch.asciidoc

@@ -112,7 +112,7 @@ Alternatively, it is possible to define both the protocol and hosts as one or mo
 hibernate.search.backend.uris = http://localhost:9200
 ----
 
-This property may be set to a String representing an URI such as `http://localhost` or `https://es.mycompany.com:4400`,
+This property may be set to a String representing a URI such as `http://localhost` or `https://es.mycompany.com:4400`,
 or a String containing multiple such URI strings separated by commas,
 or a `Collection<String>` containing such URI strings.
 
@@ -193,7 +193,7 @@ you will find it requires a proprietary authentication method:
 https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/es-request-signing.html[request signing].
 
 While request signing is not supported by default,
-you can enable it with an additional dependency and a little bit of configuration.
+you can enable it with an additional dependency and a bit of configuration.
 
 You will need to add this dependency:
 
@@ -320,7 +320,7 @@ include::{sourcedir}/org/hibernate/search/documentation/backend/elasticsearch/cl
 <1> The class has to implement the `ElasticsearchHttpClientConfigurer` interface.
 <2> The `configure` method provides the access to the `ElasticsearchHttpClientConfigurationContext`.
 <3> From the context it is possible to get the `HttpAsyncClientBuilder`.
-<4> Finally you can use the builder to configure the client with your custom settings.
+<4> Finally, you can use the builder to configure the client with your custom settings.
 ====
 
 .Define a custom http client configurer in the properties
@@ -550,7 +550,7 @@ specifying the data type and capabilities of each "property" (called an "index f
 
 For the most part, the Elasticsearch mapping is inferred from
 <<mapper-orm-mapping,the mapping configured through Hibernate Search's mapping APIs>>,
-which are generic and independent from Elasticsearch.
+which are generic and independent of Elasticsearch.
 
 Aspects that are specific to the Elasticsearch backend are explained in this section.
 
@@ -813,7 +813,7 @@ e.g. if link:{hibernateDocUrl}#multitenacy[a multi-tenancy strategy is selected
 
 However, it is possible to enable multi-tenancy manually.
 
-The multi-tenancy strategy is set a the backend level:
+The multi-tenancy strategy is set at the backend level:
 
 [source]
 ----
@@ -838,8 +838,8 @@ The Elasticsearch ID of each document is set to the concatenation of the tenant
 
 When indexing, two fields are populated transparently for each document:
 
-* `_tenant_id`: the "discriminator" field holding the tenant ID.
-* `_tenant_doc_id`: a field holding the the original (tenant-scoped) document ID.
+* `+_tenant_id+`: the "discriminator" field holding the tenant ID.
+* `+_tenant_doc_id+`: a field holding the original (tenant-scoped) document ID.
 
 When searching, a filter targeting the tenant ID field is added transparently to the search query
 to only return search hits for the current tenant.
@@ -851,14 +851,23 @@ The ID field is used to retrieve the original document IDs.
 [[backend-elasticsearch-mapping-custom-basics]]
 ==== Basics
 
-Hibernate Search can <<mapper-orm-schema-management,create and validate indexes>>, but by default created indexes will only include the bare minimum required to index and search: the mapping, and the analysis settings.
-Should you need to customize some link:{elasticsearchDocUrl}/mapping-params.html[mapping parameters], it is possible to provide a custom mapping to Hibernate Search: it will include the custom mapping when creating an index.
+Hibernate Search can <<mapper-orm-schema-management,create and validate indexes>>,
+but by default created indexes will only include the bare minimum required to index and search:
+the mapping, and the analysis settings.
+Should you need to customize some link:{elasticsearchDocUrl}/mapping-params.html[mapping parameters],
+it is possible to provide a custom mapping to Hibernate Search:
+it will include the custom mapping when creating an index.
 
 [CAUTION]
 ====
-The consistency of the custom Elasticsearch mapping with the Hibernate Search mapping will not get checked in any way. You are responsible for making sure that any override in your mapping can work, e.g. that you're not changing the type of an index field from `text` to `integer`, or disabling `doc_values` on a field used for sorting.
+The consistency of the custom Elasticsearch mapping with the Hibernate Search mapping will not get checked in any way.
+You are responsible for making sure that any override in your mapping can work,
+e.g. that you're not changing the type of an index field from `text` to `integer`,
+or disabling `doc_values` on a field used for sorting.
 
-An invalid custom mapping may not trigger any exception on bootstrap, but later while indexing or querying. In the worst case, it could not trigger any exception, but simply lead to incorrect search results. Exercise extreme caution.
+An invalid custom mapping may not trigger any exception on bootstrap, but later while indexing or querying.
+In the worst case, it could not trigger any exception, but simply lead to incorrect search results.
+Exercise extreme caution.
 ====
 
 [source]
@@ -882,7 +891,8 @@ include::{resourcesdir}/custom/index-mapping.json[]
 Properties that are only defined in the custom mappings file but not mapped by Hibernate Search
 will not be visible to Hibernate Search.
 
-This means Hibernate Search will throw exceptions if you try to reference these properties in the <<search-dsl,Search DSL>>, or when <<mapper-orm-bridge-index-field-dsl-dynamic,writing to a document from a bridge>>
+This means Hibernate Search will throw exceptions if you try to reference these properties in the <<search-dsl,Search DSL>>,
+or when <<mapper-orm-bridge-index-field-dsl-dynamic,writing to a document from a bridge>>
 ====
 
 The file does not need to contain the full mapping: Hibernate Search will automatically inject
@@ -915,7 +925,7 @@ has a `String name` property annotated with `@FullTextField`.
 ==== [[_disable_source]] Disabling `_source`
 
 Using this feature it is possible to link:{elasticsearchDocUrl}/mapping-source-field.html[disable the `_source` field].
-For instance you could pass a `custom/index-mapping.json` file like the following:
+For instance, you could pass a `custom/index-mapping.json` file like the following:
 
 .Possible content of `custom/index-mapping.json` file to disable the `_source` field
 ====

documentation/src/main/asciidoc/reference/backend-lucene.asciidoc

@@ -203,7 +203,7 @@ See `org.apache.lucene.store.NativeFSLockFactory`.
 Locks using a Java object held in the JVM's heap.
 Since the lock is only accessible by the same JVM,
 this strategy will only work properly when it is known
-that only a single application will ever try to accesses the indexes.
+that only a single application will ever try to access the indexes.
 +
 This is the default strategy for the `local-heap` directory type.
 +
@@ -325,15 +325,15 @@ This creates a dependency to the Lucene index format.
 The Lucene developers of course attempt to keep a stable index format,
 but sometimes a change in the format can not be avoided.
 In those cases you either have to re-index all your data or use an index upgrade tool.
-Sometimes, Lucene is also able to read the old format so you don't need to take specific actions
-(besides making backup of your index).
+Sometimes, Lucene is also able to read the old format, so you don't need to take specific actions
+(beside making backup of your index).
 
 While an index format incompatibility is a rare event,
 it can happen more often that Lucene's Analyzer implementations might slightly change its behavior.
 This can lead to some documents not matching anymore, even though they used to.
 
 To avoid this analyzer incompatibility,
-Hibernate Search allows to configure to which version of Lucene
+Hibernate Search allows configuring to which version of Lucene
 the analyzers and other Lucene classes should conform their behavior.
 
 This configuration property is set at the backend level:
@@ -379,7 +379,7 @@ in order to remember which predicates/projections/sorts can be applied to each f
 
 For the most part, the schema is inferred from
 <<mapper-orm-mapping,the mapping configured through Hibernate Search's mapping APIs>>,
-which are generic and independent from Elasticsearch.
+which are generic and independent of Lucene.
 
 Aspects that are specific to the Lucene backend are explained in this section.
 
@@ -391,16 +391,16 @@ Aspects that are specific to the Lucene backend are explained in this section.
 
 [NOTE]
 ====
-Some types are not supported directly by the Elasticsearch backend,
+Some types are not supported directly by the Lucene backend,
 but will work anyway because they are "bridged" by the mapper.
 For example a `java.util.Date` in your entity model is "bridged" to `java.time.Instant`,
-which is supported by the Elasticsearch backend.
+which is supported by the Lucene backend.
 See <<mapper-orm-directfieldmapping-supported-types>> for more information.
 ====
 
 [NOTE]
 ====
-Field types that are not in this list can still be used with a little bit more work:
+Field types that are not in this list can still be used with a bit more work:
 
 * If a property in the entity model has an unsupported type,
 but can be converted to a supported type, you will need a bridge.
@@ -531,7 +531,7 @@ e.g. if link:{hibernateDocUrl}#multitenacy[a multi-tenancy strategy is selected
 
 However, it is possible to enable multi-tenancy manually.
 
-The multi-tenancy strategy is set a the backend level:
+The multi-tenancy strategy is set at the backend level:
 
 [source]
 ----
@@ -791,7 +791,7 @@ it is expected that there will be a lot of "indexing" operations to create/updat
 We generally want to preserve the relative order of these requests
 when they are about the same documents.
 
-For this reasons, Hibernate Search pushes these operations to internal queues and applies them in batches.
+For this reason, Hibernate Search pushes these operations to internal queues and applies them in batches.
 Each index maintains 10 queues holding at most 1000 elements each.
 Queues operate independently (in parallel), but each queue applies one operation after the other,
 so at any given time there can be at most 10 batches of indexing requests being applied for each index.
@@ -1204,7 +1204,7 @@ otherwise it won't exist.
 ====
 
 Alternatively, you can also retrieve the (composite) analyzers for a whole index.
-These analyzers behaves differently for each field,
+These analyzers behave differently for each field,
 delegating to the analyzer configured in the mapping for each field.
 
 .Retrieving the Lucene analyzers for a whole index

documentation/src/main/asciidoc/reference/concepts.asciidoc

@@ -191,7 +191,7 @@ when the backend decides to refresh the index reader.
 This behavior can be customized by setting a different <<mapper-orm-indexing-automatic-synchronization,synchronization strategy>>.
 * The <<mapper-orm-indexing-massindexer,mass indexer>>
 will not require any commit or refresh until the very end of mass indexing,
-so as to maximize indexing throughput.
+to maximize indexing throughput.
 * Whenever there are no particular commit or refresh requirements,
 backend defaults will apply:
 ** See <<backend-elasticsearch-io,here for Elasticsearch>>.
@@ -210,7 +210,7 @@ After a refresh, *all* changes to the index are taken into account:
 those committed to the index, but also those that are still buffered in the index writer.
 
 For this reason, commits and refreshes can be treated as completely orthogonal concepts:
-certain setups will occasionally lead to committed changes not being be visible in search queries,
+certain setups will occasionally lead to committed changes not being visible in search queries,
 while others will allow even uncommitted changes to be visible in search queries.
 ====
 

documentation/src/main/asciidoc/reference/configuration.asciidoc

@@ -118,7 +118,7 @@ Here are the definitions of all property types.
 or a reference by type as a `java.lang.Class`
 (see <<configuration-bean-reference>>)
 |See <<configuration-bean-reference-parsing>>
-|Multi-valued bean reference of type T
+|Multivalued bean reference of type T
 |A `java.util.Collection` containing bean references (see above)
 |Comma-separated string containing bean references (see above)
 |===============
@@ -173,7 +173,7 @@ property to `ignore`.
 [[configuration-bean]]
 == Beans
 
-Hibernate Search allows to plug in references to custom beans in various places:
+Hibernate Search allows plugging in references to custom beans in various places:
 configuration properties, mapping annotations, arguments to APIs, ...
 
 This section describes <<configuration-bean-frameworks,the supported frameworks>>,
@@ -210,7 +210,7 @@ the type is implicitly set to whatever interface Hibernate Search expects for th
 ====
 For experienced users, Hibernate Search also provides the `org.hibernate.search.engine.environment.bean.BeanReference` type,
 which is accepted in configuration properties and APIs.
-This interface allows to plug in custom instantiation and cleanup code.
+This interface allows plugging in custom instantiation and cleanup code.
 See the javadoc of this interface for details.
 ====
 
@@ -265,7 +265,7 @@ the reference is resolved using the DI framework (see <<configuration-bean-frame
 Example: the name `myLayoutStrategy`,
 when used as the value of the property `hibernate.search.backend.layout.strategy`
 to configure the <<backend-elasticsearch-indexlayout,Elasticsearch index layout strategy>>,
-resolves to any bean known from CDI/Spring of type `IndexLayoutStrategy` and annotated with `@Named("myShardinStrategy")`.
+resolves to any bean known from CDI/Spring of type `IndexLayoutStrategy` and annotated with `@Named("myLayoutStrategy")`.
 ** Otherwise, if a name is given, and that name is a fully-qualified class name,
 and a managed bean of that type exists, that bean is used.
 +

documentation/src/main/asciidoc/reference/coordination.asciidoc

@@ -117,7 +117,7 @@ this behavior means that <<limitations-backend-indexing-error,index changes may
 If this is a problem for you, you should consider switching to <<coordination-outbox-polling,another coordination strategy>>.
 +
 [[mapper-orm-indexing-automatic-concepts-notransaction-flush]]
-NOTE: When entity changes happen outside of any transaction (not recommended),
+NOTE: When entity changes happen outside any transaction (not recommended),
 indexes are updated immediately upon session `flush()`.
 Without that flush, indexes will not be updated automatically.
 [[coordination-none-indexing-visibility]]
@@ -194,7 +194,7 @@ Indexing happens in a background thread::
 When a Hibernate ORM session is flushed,
 Hibernate Search will persist entity change events within the same Hibernate ORM session and the same transaction.
 +
-A <<coordination-outbox-polling-event-processor,event processor>> polls the database for new entity change events,
+An <<coordination-outbox-polling-event-processor,event processor>> polls the database for new entity change events,
 and asynchronously performs reindexing of the appropriate entities when it finds new events
 (i.e. after the transaction is committed).
 +
@@ -214,7 +214,7 @@ The background processor responsible for reindexing entities
 does not have access to the state of the link:{hibernateDocUrl}#best-practices-caching[first level cache]
 when the entity change occurred, because it occurred in a different session.
 +
-This means each time an entity changes and has to be reindexed,
+This means each time an entity changes and has to be re-indexed,
 the background process will load that entity in full.
 Depending on your mapping, it may also need to load lazy associations to other entities.
 +
@@ -238,7 +238,7 @@ and that the indexes will be updated accordingly,
 but only when (if) the transaction succeeds.
 +
 [[coordination-outbox-polling-indexing-guarantee-notransaction]]
-NOTE: When entity changes happen outside of any transaction (not recommended),
+NOTE: When entity changes happen outside any transaction (not recommended),
 events indexes are sent immediately after the session `flush()`.
 Without that flush, indexes will not be updated automatically.
 [[coordination-outbox-polling-indexing-visibility]]
@@ -332,7 +332,7 @@ For more details about dynamic and static sharding, see the following sections.
 Among agents of the `outbox-polling` coordination strategy executing in the background,
 the most important one is the event processor:
 it polls the outbox table for events
-and then reindexes the corresponding entities when new events are found.
+and then re-indexes the corresponding entities when new events are found.
 
 The event processor can be configured using the following configuration properties: