Docs: Reorganised the mapping home page

docs/reference/mapping.asciidoc

@@ -36,10 +36,84 @@ treated. Examples of meta-fields include the document's
 
 Each mapping type contains a list of fields or `properties` pertinent to that
 type.  A `user` type might contain `title`, `name`, and `age` fields, while a
-`blogpost` type might contain `title`, `body`, `user_id` and `created`
+`blogpost` type might contain `title`, `body`, `user_id` and `created` fields.
-fields.
+Fields with the same name in different mapping types in the same index
+<<field-conflicts,must have the same mapping>>.
 
-The mapping for the above example could look like this:
+
+[float]
+== Field datatypes
+
+Each field has a data `type` which can be:
+
+* a simple type like <<string,`string`>>, <<date,`date`>>, <<number,`long`>>,
+  <<number,`double`>>, <<boolean,`boolean`>> or <<ip,`ip`>>.
+* a type which supports the hierarchical nature of JSON such as
+  <<object,`object`>> or <<nested,`nested`>>.
+* or a specialised type like <<geo-point,`geo_point`>>,
+  <<geo-shape,`geo_shape`>>, or <<search-suggesters-completion,`completion`>>.
+
+[float]
+== Dynamic mapping
+
+Fields and mapping types do not need to be defined before being used. Thanks
+to _dynamic mapping_, new mapping types and new field names will be added
+automatically, just by indexing a document. New fields can be added both to
+the top-level mapping type, and to inner <<object,`object`>>  and
+<<nested,`nested`>> fields.
+
+The
+<<dynamic-mapping,dynamic mapping>> rules can be configured to
+customise the mapping that is used for new types and new fields.
+
+[float]
+== Explicit mappings
+
+You know more about your data than Elasticsearch can guess, so while dynamic
+mapping can be useful to get started, at some point you will want to specify
+your own explicit mappings.
+
+You can create mapping types and field mappings when you
+<<indices-create-index,create an index>>, and you can add mapping types and
+fields to an existing index with the <<indices-put-mapping,PUT mapping API>>.
+
+[float]
+== Updating existing mappings
+
+Other than where documented, *existing type and field mappings cannot be
+updated*. Changing the mapping would mean invalidating already indexed
+documents.  Instead, you should create a new index with the correct mappings
+and reindex your data into that index.
+
+[[field-conflicts]]
+[float]
+== Fields are shared across mapping types
+
+Mapping types are used to group fields, but the fields in each mapping type
+are not independent of each other. Fields with:
+
+* the _same name_
+* in the _same index_
+* in _different mapping types_
+* map to the _same field_ internally,
+* and *must have the same mapping*.
+
+If a `title` field exists in both the `user` and `blogpost` mapping types, the
+`title` fields must have exactly the same mapping in each type.  The only
+exceptions to this rule are the <<copy-to>>, <<dynamic>>, <<enabled>>,
+<<ignore-above>>, <<include-in-all>>, and <<properties>> parameters, which may
+have different settings per field.
+
+Usually, fields with the same name also contain the same type of data, so
+having the same mapping is not a problem.  When conflicts do arise, these can
+be solved by choosing more descriptive names, such as `user_title` and
+`blog_title`.
+
+[float]
+== Example mapping
+
+A mapping for the example described above could be specified when creating the
+index, as follows:
 
 [source,js]
 ---------------------------------------
@@ -78,75 +152,6 @@ PUT my_index <1>
 <4> Specify fields or _properties_ in each mapping type.
 <5> Specify the data `type` and mapping for each field.
 
-[float]
-== Field datatypes
-
-Each field has a data `type` which can be:
-
-* a simple type like <<string,`string`>>, <<date,`date`>>, <<number,`long`>>,
-  <<number,`double`>>, <<boolean,`boolean`>> or <<ip,`ip`>>.
-* a type which supports the hierarchical nature of JSON such as
-  <<object,`object`>> or <<nested,`nested`>>.
-* or a specialised type like <<geo-point,`geo_point`>>,
-  <<geo-shape,`geo_shape`>>, or <<search-suggesters-completion,`completion`>>.
-
-[IMPORTANT]
-.Fields are shared across mapping types
-=========================================
-
-Mapping types are used to group fields, but the fields in each mapping type
-are not independent of each other. Fields with:
-
-* the _same name_
-* in the _same index_
-* in _different mapping types_
-* map to the _same field_ internally,
-* and *must have the same mapping*.
-
-The `title` field exists in both the `user` and `blogpost` mapping types and
-so must have exactly the same mapping in each type.  The only exceptions to
-this rule are the <<copy-to>>, <<dynamic>>, <<enabled>>, <<ignore-above>>,
-<<include-in-all>>, and <<properties>> parameters, which may have different
-settings per field.
-
-Usually, fields with the same name also contain the same type of data, so
-having the same mapping is not a problem.  When conflicts do arise, these can
-be solved by choosing more descriptive names, such as `user_title` and
-`blog_title`.
-
-=========================================
-
-[float]
-== Dynamic mapping
-
-Fields and mapping types do not need to be defined before being used. Thanks
-to _dynamic mapping_, new mapping types and new field names will be added
-automatically, just by indexing a document. New fields can be added both to
-the top-level mapping type, and to inner <<object,`object`>>  and
-<<nested,`nested`>> fields.
-
-The
-<<dynamic-mapping,dynamic mapping>> rules can be configured to
-customise the mapping that is used for new types and new fields.
-
-[float]
-== Explicit mappings
-
-You know more about your data than Elasticsearch can guess, so while dynamic
-mapping can be useful to get started, at some point you will want to specify
-your own explicit mappings.
-
-You can create mapping types and field mappings when you
-<<indices-create-index,create an index>>, and you can add mapping types and
-fields to an existing index with the <<indices-put-mapping,PUT mapping API>>.
-
-[float]
-== Updating existing mappings
-
-Other than where documented, *existing type and field mappings cannot be
-updated*. Changing the mapping would mean invalidating already indexed
-documents.  Instead, you should create a new index with the correct mappings
-and reindex your data into that index.
 
 --
 

docs/reference/mapping/types.asciidoc

@@ -40,6 +40,33 @@ Attachment datatype::
     which supports indexing ``attachments'' like Microsoft Office formats, Open
     Document formats, ePub, HTML, etc. into an `attachment` datatype.
 
+[[field-conflicts]]
+[IMPORTANT]
+.Fields are shared across mapping types
+=========================================
+
+Mapping types are used to group fields, but the fields in each mapping type
+are not independent of each other. Fields with:
+
+* the _same name_
+* in the _same index_
+* in _different mapping types_
+* map to the _same field_ internally,
+* and *must have the same mapping*.
+
+If a `title` field exists in both the `user` and `blogpost` mapping types, the
+`title` fields must have exactly the same mapping in each type.  The only
+exceptions to this rule are the <<copy-to>>, <<dynamic>>, <<enabled>>,
+<<ignore-above>>, <<include-in-all>>, and <<properties>> parameters, which may
+have different settings per field.
+
+Usually, fields with the same name also contain the same type of data, so
+having the same mapping is not a problem.  When conflicts do arise, these can
+be solved by choosing more descriptive names, such as `user_title` and
+`blog_title`.
+
+=========================================
+
 include::types/array.asciidoc[]
 
 include::types/binary.asciidoc[]