Better descriptions

Author: jaredpar

Directory.Build.props

@@ -12,10 +12,10 @@
     <Authors>jaredpar</Authors>
     <Title>Basic.Reference.Assemblies: Reference assemblies for use in Roslyn</Title>
     <PackageDescription>
-    This package provides reference assemblies for use in Roslyn Compilation objects. This greatly
-    simplifies the work involved in doing in memory compilations with the Microsoft.CodeAnalysis 
-    API. Developers can now create correct Compilations with reference sets from all of the major
-    target frameworks: netcoreapp31, net50 and netstandard.
+This package provides reference assemblies for use in Roslyn Compilation objects. This greatly
+simplifies the work involved in doing in memory compilations with the Microsoft.CodeAnalysis 
+API. Developers can now create correct Compilations with reference sets from all of the major
+target frameworks: netcoreapp31, net50 and netstandard.
     </PackageDescription>
   </PropertyGroup>
 

README.md

@@ -5,31 +5,15 @@ Basic compilations. Provide it code, a few options and a set of references and
 it will provide an API to inspect the syntax, semantic model, diagnostics and 
 even generate DLLs / EXEs. 
 
-These technologies are very straight forward to use when running on .NET 
-Framework because implementation assemblies can substitute for reference 
-assemblies. That means if a user wants to add a reference to `System.Core.dll'
-to the compiler all they need to do is use the runtime assembly:
+Getting references for .NET Core or .NET Standard to use with a `Compilation`
+is challenging because these are only shipped as physical files. In order to use
+them in a library the developer must do the heavy lifting of packaging them up
+as resources in their library and unpacking them at runtime.
 
-```c#
-Assembly systemCoreAssembly = typeof(System.Linq.Enumerable).Assembly;
-string systemCorePath = systemCoreAssembly.Location;
-MetadataReference systemCoreRef = AssemblyMetadata.CreateFromFile(string path).GetReference();
-```
-
-This does not work on .NET Core though because there is a strong split between 
-reference and implementation assemblies. The above code will give you access to 
-the implementation assembly on .NET Core and is not a supported input for 
-compilation. Instead you need to get the actual reference assembly.
-
-Unfortunately .NET Core and .NET Standard only ship reference assemblies as 
-physical files. These are not easily consumable at runtime in a .NET library 
-or application. Hence any .NET app which wants to use the reference assemblies 
-must do the heavy lifting of packaging them up as resources and unpacking them
-at runtime. 
-
-The `DotNet.Reference.Assemblies` libraries takes care of this heavy lifting 
-and provides the reference assemblies for `netstandard2.0`, `netcoreapp3.1` and
-`net5.0`. These can be easily integrated into the existing Roslyn APIs.
+The [Basic.Reference.Assemblies](https://www.nuget.org/packages/Basic.Reference.Assemblies/) 
+library takes care of this heavy lifting and provides the reference assemblies 
+for `netstandard2.0`, `netcoreapp3.1` and `net5.0`. These can be easily 
+integrated into the existing Roslyn APIs.
 
 ```c#
 var code = @"
@@ -48,14 +32,57 @@ var compilation = CSharpCompilation
     .Create(
         "HelloWorld.dll",
         new[] { CSharpSyntaxTree.ParseText(code) },
-        references: Net50.All);
+        references: ReferenceAssemblies.Net50);
 
 using var fileStream = new FileStream(@"p:\temp\helloworld.exe", FileMode.Create, FileAccess.ReadWrite);
 var emitResults = compilation.Emit(fileStream);
 ```
 
-These make it much simpler to approach compilation inside your libraries
-or application.
+This package also adds extensions methods for easily retargeting `Compilation` 
+instances to different Target Frameworks.
+
+```c#
+CSharpCompilation compilation = ...;
+compilation = compilation.WithReferenceAssemblies(ReferenceAssemblyKind.NetCoreApp31);
+```
+
+This repository actually provides a series of packages. The expectation is that
+most developers will use [Basic.Reference.Assemblies](https://www.nuget.org/packages/Basic.Reference.Assemblies/).
+This package has reference assemblies for all of the supported target frameworks
+and provides APIs to make it easy to switch between them in `Compilation` 
+instances. 
+
+# FAQ
+
+## What if I only need a single target framework?
+Developers who only need a single target framework and are extremely size 
+conscious can grab the target framework specific package:
+
+- [Basic.Reference.Assemblies.Net50](https://www.nuget.org/packages/Basic.Reference.Assemblies.Net50/)
+- [Basic.Reference.Assemblies.NetCoreApp31](https://www.nuget.org/packages/Basic.Reference.Assemblies.NetCoreApp31/)
+- [Basic.Reference.Assemblies.NetStandard20](https://www.nuget.org/packages/Basic.Reference.Assemblies.NetStandard20/)
+
+## What is wrong with using typeof(Enumerable).Assembly?
+Developers working on .NET Framework will often end up with the following pattern
+for creating `Compilation` instances:
+
+```c#
+Assembly systemCoreAssembly = typeof(System.Linq.Enumerable).Assembly;
+string systemCorePath = systemCoreAssembly.Location;
+MetadataReference systemCoreRef = AssemblyMetadata.CreateFromFile(string path).GetReference();
+```
+
+This pattern will often work on .NET Framework but will fail with running on 
+.NET Core. The reason for this is due to the differences in reference and 
+implementation assemblies. Reference assemblies are designed for use at build 
+time while implementation assemblies are used at runtime. A particular type for 
+a given target framework doesn't necessarily live in the same reference and 
+implementation assembly. Also the set of implementation assemblies can be larger
+than the reference assemblies for the same target framework.
 
-**Note** .NET Framework also has a split between reference and implementation 
-assemblies but it is not as strong as on .NET Core.
+The reason the above tends to work on .NET Framework is the split between 
+reference and implementation assemblies is not as pronounced. In most cases 
+there is a 1:1 relationship. On .NET Core though the split is much more 
+pronounced and it often requires probing for implementation assemblies to get a 
+set which will work for building. This is a fragile process though, developers
+are much better off using the reference assemblies as intended by the .NET team.