Doc: Add a topic for element mapping

src/App/core-app.dox

@@ -3,6 +3,10 @@
  * @ingroup CORE
  * @brief The part of FreeCAD that works without GUI (console or server mode)
  *
+ * @htmlonly
+ * <div class="textblock">
+ * @endhtmlonly
+ *
  * @details It contains the App namespace and defines core concepts such as
  * @ref ApplicationGroup "Application", @ref DocumentGroup "Document", @ref
  * DocumentObjectGroup "DocumentObject", @ref PropertyFramework "Property
@@ -14,6 +18,10 @@
  * in @ref App::Document "Document" and @ref App::DocumentObject
  * "DocumentObject".  In addition, %App has a representation of the running
  * @ref App::Application "Application".
+ *
+ * @htmlonly
+ * </div>
+ * @endhtmlonly
  */
 
 /**
@@ -827,6 +835,45 @@
  * object are tracked and applied on the copy.
  */
 
+/**
+ * @defgroup ElementMapping Element Mapping for Topological naming.
+ * @ingroup APP
+ * @brief Element mapping system for topological naming
+ *
+ * Since the names of vertices, edges, and faces that we obtain from
+ * OpenCascade are not stable under modifications of the shape, FreeCAD
+ * implements a system called "topological naming" to provide stable names for
+ * these elements.
+ *
+ * A shape in FreeCAD is represented by Part::TopoShape, a subclass of
+ * Data::ComplexGeoData that contains much of the logic for element mapping.
+ * This logic mainly resides in package Data.
+ *
+ * A @ref Data::ComplexGeoData "ComplexGeoData" object contains a @ref
+ * Data::ComplexGeoData::Tag "Tag" that uniquely identifies the shape in the
+ * document.  A @ref Data::ComplexGeoData "ComplexGeoData" object also contains
+ * a @ref Data::ElementMap "ElementMap" that maintains a mapping from an @ref
+ * Data::IndexedName "IndexedName" to a @ref Data::MappedName "MappedName".
+ *
+ * An indexed name, is a name that we obtain from the shapes from OpenCascade.
+ * A mapped name is a name that is formed by means of topological relations.  A
+ * mapped name consists of an immutable base name (called the "data") while the
+ * second part is appended on operations on the shape.  This is called the
+ * "postfix" of the mapped name.  For a selection of used postfix tags, see
+ * the @ref ElementNameConstants "Element name constants" section in Data.
+ *
+ * An example of a mapped name is
+ * `Pocket.;g2;SKT;:H7cf,E;:G;XTR;:H7cf:7,F;:M;CUT;:H-7d0:7,F.Face8` which
+ * roughly means that the selected face `Face8` was modified `M` with a `CUT`
+ * operation.  The `T` or `H` tags provide the tag of the shape in decimal and
+ * hexadecimal respectively.
+ *
+ * Because multiple operations can result in long mapped names, FreeCAD makes
+ * use of a string hasher that creates short hashes out of the long mapped
+ * names.  An example of the hashed name for the above mapped name is:
+ * `Pocket.;#20:2;:M;CUT;:H-e61:7,F.Face8`.
+ */
+
 /**
  * @namespace App
  * @ingroup APP
@@ -841,3 +888,10 @@
  * For a more high-level discussion see the topic @ref APP "App".
  */
 
+/**
+ * @namespace Data
+ * @ingroup ElementMapping
+ * @brief The namespace for element names
+ *
+ */
+