Documentation fixes (#690)

* Replacing obsolete and no more existent documented methods.

* Modernize/fix code examples and guidelines.

* Removing obsolete default configuration: no need for proxy factory by default.

* Removed references to abandoned or not ported tools.

* Upgrade/fix external links.

* Second level cache: transaction requirement.

* Recommandation on transacting.

* Update and sort dialects in configuration listing.

* More alternatives to xml mapping.

* Fix typo and other minor adjustments.

* Fixing pdf overflows.

* Fixing SHFB build by using msbuild.exe instead of dotnet.

Author: fredericDelaporte

Tools/actual_msbuild.cmd

@@ -0,0 +1,11 @@
+@echo off
+
+for /f "usebackq tokens=*" %%i in (`%~dp0\vswhere.2.1.4\tools\vswhere -latest -products * -requires Microsoft.Component.MSBuild -property installationPath`) do (
+  set InstallDir=%%i
+)
+
+if exist "%InstallDir%\MSBuild\15.0\Bin\MSBuild.exe" (
+  "%InstallDir%\MSBuild\15.0\Bin\MSBuild.exe" %*
+) else ( 
+  exit /b -1
+)

Tools/packages.config

@@ -8,4 +8,5 @@
   <package id="NUnit.Extension.TeamCityEventListener" version="1.0.2" targetFramework="net461" />
   <package id="NUnit.Extension.VSProjectLoader" version="3.6.0" targetFramework="net461" />
   <package id="CSharpAsyncGenerator.CommandLine" version="0.4.4" targetFramework="net461" />
+  <package id="vswhere" version="2.1.4" targetFramework="net461" />
 </packages>

build-common/common.xml

@@ -36,6 +36,7 @@
 	<!-- This is used only for build folder -->
 	<!-- TODO: Either remove or refactor to use NHibernate.props -->
 	<property name="project.version" value="5.0.0-Alpha1" overwrite="false" />
+	<property name="project.version.numeric" value="5.0.0" overwrite="false" />
 
 	<!-- debug|release -->
 	<property name="build.defines" value="" />

doc/documentation.build

@@ -65,10 +65,10 @@
 		<echo if="${api.uptodate}">API documentation is up to date, skipping generation step.</echo>
 
 		<if test="${not api.uptodate}">
-			<exec program="${path::combine(tools.dir, 'msbuild.cmd')}">
+			<exec program="${path::combine(tools.dir, 'actual_msbuild.cmd')}">
 				<arg line="NHibernate.shfbproj" />
 			</exec>
 		</if>
 	</target>
 
-</project>
+</project>

doc/reference/master.xml

@@ -31,8 +31,6 @@
 <!ENTITY nhc-preface            SYSTEM "modules/nhibernatecontrib_preface.xml">
 <!ENTITY nhcaches-chapter       SYSTEM "modules/nhibernate_caches.xml">
 <!ENTITY nhma-chapter           SYSTEM "modules/nhibernate_mapping_attributes.xml">
-<!ENTITY nhbm2net-chapter       SYSTEM "modules/nhibernate_tool_hbm2net.xml">
-<!ENTITY nullables-chapter      SYSTEM "modules/nullables.xml">
 ]>
 
 

doc/reference/modules/architecture.xml

@@ -64,7 +64,7 @@
         </mediaobject>
 
         <para>
-            Heres some definitions of the objects in the diagrams:
+            Here are some definitions of the objects in the diagrams:
 
             <variablelist spacing="compact">
                 <varlistentry>
@@ -122,7 +122,8 @@
                             (Optional) A single-threaded, short-lived object used by the application to
                             specify atomic units of work. Abstracts application from underlying ADO.NET
                             transaction. An <literal>ISession</literal> might span several
-                            <literal>ITransaction</literal>s in some cases.
+                            <literal>ITransaction</literal>s in some cases. Transaction scopes may be used
+                            instead.
                         </para>
                     </listitem>
                 </varlistentry>
@@ -227,7 +228,7 @@
             Starting with version 1.2, NHibernate added the <literal>ISessionFactory.GetCurrentSession()</literal>
             method. The processing behind <literal>ISessionFactory.GetCurrentSession()</literal> is pluggable.
             An extension interface (<literal>NHibernate.Context.ICurrentSessionContext</literal>) and a new
-            configuration parameter (<literal>hibernate.current_session_context_class</literal>) have been added
+            configuration parameter (<literal>current_session_context_class</literal>) have been added
             to allow pluggability of the scope and context of defining current sessions.
         </para>
         <para>
@@ -245,7 +246,7 @@
                     by current asynchronous flow. You are responsible to bind and unbind an
                     <literal>ISession</literal> instance with static methods of class
                     <literal>CurrentSessionContext</literal>. Binding operations from inner flows will not be
-                    propagated to outer or siblings flows.
+                    propagated to outer or siblings flows. Added in NHibernate 5.0.
                 </para>
             </listitem>
             <listitem>
@@ -293,7 +294,7 @@
         </itemizedlist>
 
         <para>
-            The <literal>hibernate.current_session_context_class</literal> configuration parameter
+            The <literal>current_session_context_class</literal> configuration parameter
             defines which <literal>NHibernate.Context.ICurrentSessionContext</literal> implementation
             should be used. Typically, the value of this parameter would just name the implementation
             class to use (including the assembly name); for the out-of-the-box implementations, however,

doc/reference/modules/basic_mapping.xml

@@ -15,7 +15,9 @@
             Note that, even though many NHibernate users choose to define XML mappings by hand,
             a number of tools exist to generate the mapping document, including
             NHibernate.Mapping.Attributes library and various template-based code
-            generators (CodeSmith, MyGeneration).
+            generators (CodeSmith, MyGeneration). You may also use
+            <literal>NHibernate.Mapping.ByCode</literal> available since NHibernate 3.2, or
+            <ulink url="https://github.com/jagregory/fluent-nhibernate">Fluent NHibernate</ulink>.
         </para>
 
         <para>
@@ -614,8 +616,9 @@
                         <listitem>
                             <para>
                                 uses the algorithm to generate a new <literal>System.Guid</literal>
-                                described by Jimmy Nilsson in the article 
-                                http://www.informit.com/articles/article.asp?p=25862.
+                                described by Jimmy Nilsson in
+                                <ulink url="https://www.informit.com/articles/article.aspx?p=25862">this
+                                article</ulink>.
                             </para>
                         </listitem>
                         </varlistentry>
@@ -2929,9 +2932,10 @@
                 are possible.
             </para>
 
-            <programlisting><![CDATA[<property name="TwoStrings" type="NHibernate.DomainModel.DoubleStringType, NHibernate.DomainModel">
-    <column name="first_string"/>
-    <column name="second_string"/>
+            <programlisting><![CDATA[<property name="TwoStrings"
+    type="NHibernate.DomainModel.DoubleStringType, NHibernate.DomainModel">
+  <column name="first_string"/>
+  <column name="second_string"/>
 </property>]]></programlisting>
 
             <para>

doc/reference/modules/batch.xml

@@ -208,7 +208,8 @@ using (ITransaction tx = session.BeginTransaction())
         <programlisting><![CDATA[using (ISession session = sessionFactory.OpenSession())
 using (ITransaction tx = session.BeginTransaction())
 {
-    string hqlVersionedUpdate = "update versioned Customer set name = :newName where name = :oldName";
+    string hqlVersionedUpdate =
+        "update versioned Customer set name = :newName where name = :oldName";
     int updatedEntities = s.CreateQuery(hqlUpdate)
         .SetString("newName", newName)
         .SetString("oldName", oldName)
@@ -313,7 +314,9 @@ using (ITransaction tx = session.BeginTransaction())
         <programlisting><![CDATA[using (ISession session = sessionFactory.OpenSession())
 using (ITransaction tx = session.BeginTransaction())
 {
-    var hqlInsert = "insert into DelinquentAccount (id, name) select c.id, c.name from Customer c where ...";
+    var hqlInsert =
+        "insert into DelinquentAccount (id, name) " +
+        "select c.id, c.name from Customer c where ...";
     int createdEntities = s.CreateQuery(hqlInsert)
         .ExecuteUpdate();
     tx.Commit();