Update .Net notes

mkdocs/docs/howto-dotnet.md

@@ -1,18 +1,28 @@
 # Getting Started with .Net
-For many people the easiest way to work with MPXJ is via
-[NuGet](http://www.nuget.org/packages?q=mpxj). The .Net assemblies and their
-dependencies can also be found in the zip file distribution from
+MPXJ uses a tool called [IKVM](https://github.com/ikvmnet/ikvm)
+to convert the original Java version of MPXJ into .Net assemblies. The MPXJ .Net
+assemblies provided via NuGet and shipped as part of the MPXJ distribution
+use a "legacy" version of IKVM to do this. The "modern" version of IKVM
+allows .Net assemblies to be generated in a different, and ultimately more
+future-proof way. However there are, at present, some minor disadvantages to
+using the approach based on the "modern" version of IKVM. These disadvantages
+are being addressed, and ultimately assemblies produced by the "modern" version
+of IKVM will become the default way to include MPXJ in your project.
+
+
+## MPXJ assemblies (legacy IKVM)
+For many people the easiest way to work with MPXJ is to use the assemblies
+generated by the "legacy" version of IKVM. This are available via
+[NuGet](http://www.nuget.org/packages?q=mpxj) and also as part of the zip file distribution from
 [GitHub](https://www.github.com/joniles/mpxj/releases) or
 [SourceForge](http://sourceforge.net/project/showfiles.php?group_id=70649).
 
-You'll find a general introduction to MPXJ's functionality [here](howto-start.md).
 
-## MPXJ assemblies
 MPXJ ships with a set of .Net Framework and .Net Core assemblies, which are
 managed for you by NuGet or can be found in the `src.net\lib\net45` and
 `src.net\lib\netcoreapp3.1` folders of the distribution respectively.
 
-There are actually three different .Net DLLs shipped with MPXJ - you only need
+There are actually three different .Net DLLs available for MPXJ - you only need
 one of these:
 
 * **mpxj.dll** - this is the default .Net version, the API is
@@ -57,13 +67,59 @@ Using the "for C#" DLL your code will look like this:
 Task task = projectFile.AddTask();
 ```
 
-## MPXJ dependencies
 Once you have selected the version of the MPXJ DLL most suitable for your
 project, you will need to add its dependencies. If you are using NuGet to
 manage your dependencies, this is done for you automatically. If you are
 managing the dependencies manually, the files you need will all be in the
 relevant sub folder with the `src.net\lib` folder of the MPXJ distribution.
 
+## MPXJ assemblies (modern IKVM)
+The modern version of IKVM provides an extension to modern SDK-style .Net
+projects which allows you to refer to a Java library using Maven (probably the
+most common dependency management solution for Java projects). This means that
+your .Net project will be working directly with the original Java version of
+the library, which will automatically be translated into .Net assemblies for
+you as you build your project.
+
+> Note that this build process can be time-consuming when your project is first
+> built using this approach, but the results of this translation will be
+> reused, so subsequent builds will be more rapid. You may also see various
+> transient warning messages as this first build completes. These can be ignored
+> and will disappear once your project has finished building.
+
+To include MPXJ in your project using the modern version of IKVM, edit
+your project file and include the following lines:
+
+```xml
+<ItemGroup>
+ <PackageReference Include="IKVM.Maven.Sdk" Version="1.6.8" />
+</ItemGroup>
+
+<ItemGroup>
+ <MavenReference Include="net.sf.mpxj:mpxj" Version="12.8.0"/>
+</ItemGroup>
+```
+
+The first `<ItemGroup>` you are adding enables IKVM's Maven integration
+functionality. The second `<ItemGroup>` simply refers to the version of MPXJ
+you'd like to use from Maven.
+
+The advantages of using MPXJ this way are:
+
+* Improved performance when compared to the version of MPXJ generated by legacy IKVM.
+* Supports modern .Net platforms and architectures, not all of which will be supported by legacy IKVM.
+* Works more efficiently with the Visual Studio debugger.
+* Benefits from ongoing bug fixes and enhancements in IKVM.
+
+The disadvantages of using MPXJ this way are:
+
+* There is no translation of getters and setters into .Net properties.
+* All method names remain as "Java-style" initial lower case.
+
+As mentioned earlier, work is underway to provide address these disadvantages
+by providing a "wrapper" assembly which hides the "Java-ness" of the original
+MPXJ library.
+
 ## .Net samples
 MPXJ ships with some sample files which can be found in the `src.net\samples`
 folder of the distribution. These files illustrate how the MPXJ API can be 
@@ -74,7 +130,9 @@ and the other written in Visual Basic (VB) to illustrate the basics of using
 MPXJ in either language. Even if you are developing software in a .Net
 language you may still find it useful to refer to the Java examples, and
 indeed the original Java source of MPXJ, to give you an insight into how the
-API can be used.
+API can be used. There is also a standalone repository containing sample .Net
+code for MPXJ covering use of the library in more depth. This repository 
+can be found [here](https://github.com/joniles/mpxj-dotnet-samples).
 
 ## .Net and Java types
 The .Net version of MPXJ has been generated directly from the Java version using