Add important admonition about using System.Decimal POCO property types (#2495)

Bump AsciiDoctNet to support additional asciidoc syntax
Closes #2463

Author: russcam

docs/aggregations/writing-aggregations.asciidoc

@@ -144,7 +144,6 @@ return s => s
     );
 ----
 <1> a list of aggregation functions to apply
-
 <2> Using LINQ's `Aggregate()` function to accumulate/apply all of the aggregation functions
 
 Combining multipe `AggregationDescriptor`'s is also possible using the bitwise `&` operator
@@ -212,6 +211,5 @@ var maxPerChild = childAggregation.Max("max_per_child");
 maxPerChild.Should().NotBeNull(); <2>
 ----
 <1> Do something with the average per child. Here we just assert it's not null
-
 <2> Do something with the max per child. Here we just assert it's not null
 

docs/client-concepts/high-level/mapping/auto-map.asciidoc

@@ -249,6 +249,29 @@ var expected = new
 Expect(expected).WhenSerializing((ICreateIndexRequest)descriptor);
 ----
 
+[IMPORTANT]
+====
+Some .NET types do not have direct equivalent Elasticsearch types. For example, `System.Decimal` is a type
+commonly used to express currencies and other financial calculations that require large numbers of significant
+integral and fractional digits and no round-off errors. There is no equivalent type in Elasticsearch, and the
+nearest type is {ref_current}/number.html[``double``], a double-precision 64-bit IEEE 754 floating point.
+
+When a POCO has a `System.Decimal` property, it is automapped to the Elasticsearch `double` type. With the caveat
+of a potential loss of precision, this is generally acceptable for a lot of use cases, but it can however cause
+problems in _some_ edge cases.
+
+As the https://download.microsoft.com/download/3/8/8/388e7205-bc10-4226-b2a8-75351c669b09/csharp%20language%20specification.doc[C# Specification states],
+
+[quote, C# Specification section 6.2.1]
+For a conversion from `decimal` to `float` or `double`, the `decimal` value is rounded to the nearest `double` or `float` value.
+While this conversion may lose precision, it never causes an exception to be thrown.
+
+This conversion causes an exception to be thrown at deserialization time for `Decimal.MinValue` and `Decimal.MaxValue` because, at
+serialization time, the nearest `double` value that is converted to is outside of the bounds of `Decimal.MinValue` or `Decimal.MaxValue`,
+respectively. In these cases, it is advisable to use `double` as the POCO property type.
+
+====
+
 [[auto-mapping-with-overrides]]
 [float]
 == Auto mapping with overrides

docs/high-level.asciidoc

@@ -14,6 +14,7 @@ please modify the original csharp file found at the link and submit the PR with
 [partintro]
 --
 The high level client, `ElasticClient`, provides a strongly typed query DSL that maps one-to-one with the Elasticsearch query DSL.
+
 It can be installed from the Package Manager Console inside Visual Studio using
 
 [source,shell]
@@ -22,8 +23,10 @@ Install-Package NEST
 ----
 
 Or by searching for https://www.nuget.org/packages/NEST[NEST] in the Package Manager GUI. 
+
 NEST internally uses and still exposes the low level client, `ElasticLowLevelClient`, from <<elasticsearch-net,Elasticsearch.Net>> via
 the `.LowLevel` property on `ElasticClient`.
+
 There are a number of conventions that NEST uses for inference of
 
 * <<index-name-inference, Index Names>>

docs/low-level.asciidoc

@@ -15,6 +15,7 @@ please modify the original csharp file found at the link and submit the PR with
 --
 The low level client, `ElasticLowLevelClient`, is a low level, dependency free client that has no 
 opinions about how you build and represent your requests and responses. 
+
 It can be installed from the Package Manager Console inside Visual Studio using
 
 [source,shell]

paket.lock

@@ -1,6 +1,6 @@
 NUGET
   remote: https://www.nuget.org/api/v2
-    AsciiDocNet (1.0.0-alpha3)
+    AsciiDocNet (1.0.0-alpha5)
     Bogus (7.1.6)
       NETStandard.Library (>= 1.6) - framework: >= netstandard13
       Newtonsoft.Json (>= 9.0.1) - framework: >= net40, >= netstandard13

src/CodeGeneration/DocGenerator/AsciiDoc/GeneratedAsciidocVisitor.cs

@@ -265,7 +265,7 @@ public override void Visit(SectionTitle sectionTitle)
 				var builder = new StringBuilder();
 				using (var writer = new AsciiDocVisitor(new StringWriter(builder)))
 				{
-					writer.Visit(sectionTitle.Elements);
+					writer.Visit((InlineContainer)sectionTitle);
 				}
 
 				var title = builder.ToString().PascalToHyphen();
@@ -301,7 +301,7 @@ private bool LastSectionTitleMatches(Func<string, bool> predicate)
 				var builder = new StringBuilder();
 				using (var visitor = new AsciiDocVisitor(new StringWriter(builder)))
 				{
-					visitor.Visit(lastSectionTitle.Elements);
+					visitor.Visit((InlineContainer)lastSectionTitle);
 				}
 
 				return predicate(builder.ToString());

src/CodeGeneration/DocGenerator/Documentation/Files/CSharpDocumentationFile.cs

@@ -199,7 +199,6 @@ private void CleanDocumentAndWriteToFile(string body, FileInfo destination)
 			{
 				document.Accept(new AsciiDocVisitor(file));
 			}
-
 		}
 	}
 }

src/CodeGeneration/DocGenerator/Documentation/Files/DocumentationFile.cs

@@ -1,9 +1,6 @@
 using System;
-using System.Collections.Generic;
 using System.IO;
-using System.Reflection.Emit;
 using System.Text.RegularExpressions;
-using DocGenerator;
 
 namespace DocGenerator.Documentation.Files
 {

src/CodeGeneration/DocGenerator/Documentation/Files/ImageDocumentationFile.cs

@@ -11,7 +11,7 @@ public override void SaveToDocumentationFolder()
 		{
 			var docFileName = this.CreateDocumentationLocation();
 
-			// copy for asciidoc to work (path is relative to file)
+			// copy for asciidoc to work when viewing a single asciidoc in the browser (path is relative to file)
 			this.FileLocation.CopyTo(docFileName.FullName, true);
 
 			// copy to the root as well, for the doc generation process (path is relative to root)

src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs

@@ -235,14 +235,36 @@ public void UsingAutoMap()
 			};
 
 			Expect(expected).WhenSerializing((ICreateIndexRequest)descriptor);
-		}
-
+		}
+		/**[IMPORTANT]
+		 * ====
+		 * Some .NET types do not have direct equivalent Elasticsearch types. For example, `System.Decimal` is a type
+		 * commonly used to express currencies and other financial calculations that require large numbers of significant
+		 * integral and fractional digits and no round-off errors. There is no equivalent type in Elasticsearch, and the
+		 * nearest type is {ref_current}/number.html[``double``], a double-precision 64-bit IEEE 754 floating point.
+		 *
+		 * When a POCO has a `System.Decimal` property, it is automapped to the Elasticsearch `double` type. With the caveat
+		 * of a potential loss of precision, this is generally acceptable for a lot of use cases, but it can however cause
+		 * problems in _some_ edge cases.
+		 *
+		 * As the https://download.microsoft.com/download/3/8/8/388e7205-bc10-4226-b2a8-75351c669b09/csharp%20language%20specification.doc[C# Specification states],
+		 *
+		 * [quote, C# Specification section 6.2.1]
+		 * For a conversion from `decimal` to `float` or `double`, the `decimal` value is rounded to the nearest `double` or `float` value.
+		 * While this conversion may lose precision, it never causes an exception to be thrown.
+		 *
+		 * This conversion causes an exception to be thrown at deserialization time for `Decimal.MinValue` and `Decimal.MaxValue` because, at
+		 * serialization time, the nearest `double` value that is converted to is outside of the bounds of `Decimal.MinValue` or `Decimal.MaxValue`,
+		 * respectively. In these cases, it is advisable to use `double` as the POCO property type.
+		 * ====
+		 */
+
 		/**[float]
 		* == Auto mapping with overrides
 		* In most cases, you'll want to map more than just the vanilla datatypes and also provide
 		* various options for your properties (analyzer to use, whether to enable doc_values, etc...).
 		* In that case, it's possible to use `.AutoMap()` in conjunction with explicitly mapped properties.
-		*/
+		*/
 		[U]
 		public void OverridingAutoMappedProperties()
 		{
@@ -882,7 +904,7 @@ public void PutMappingAlsoAdheresToMaxRecursion()
 		//endhide
 
 		/**[float]
-                 * == Applying conventions through the Visitor pattern
+         * == Applying conventions through the Visitor pattern
 		 * It is also possible to apply a transformation on all or specific properties.
 		 *
 		 * `.AutoMap()` internally implements the https://en.wikipedia.org/wiki/Visitor_pattern[visitor pattern]. The default visitor, `NoopPropertyVisitor`,