Merge pull request #641 from PowerShell/docs

Update readme and known issues

KNOWNISSUES.md

@@ -22,16 +22,10 @@ the stub is also used with a `#if ETW` guard.
 
 ## xUnit
 
-The xUnit tests cannot currently be run; we are working to integrate the
-prototype .NET Core runner to re-enable them.
+The xUnit tests can only be run on Linux.
 
 ## Console Output
 
-The console output on Windows and under certain `TERM` environments on Linux
-(`xterm` is known to work fine), the console scrolls badly. We believe this is
-due to incomplete System.Console APIs, which have been fixed upstream and will
-be updated when new packages drop.
-
 Performance issues have been seen in some scenarios, such as nested SSH
 sessions. We believe this is likely an issue with `Console.ReadKey()` and are
 investigating.

README.md

@@ -61,7 +61,7 @@ non-Windows platforms). Install `dotnet` by following their [documentation][].
 
 The version of .NET CLI is very important, you want a recent 1.0.0 beta
 (**not** 1.0.1). The following instructions will install precisely
-1.0.0.001517, though any 1.0.0 version *should* work.
+1.0.0.001638, though any 1.0.0 version *should* work.
 
 > Previous installations of DNX, `dnvm`, or older installations of .NET CLI
 > can cause odd failures when running. Please check your version.
@@ -107,10 +107,11 @@ Invoke-WebRequest -Uri https://raw.githubusercontent.com/dotnet/cli/rel/1.0.0/sc
 ./install.ps1 -version 1.0.0.001638 -channel beta
 ```
 
-Note:
->If you meet "Unable to cast COM object of type 'System.__ComObject' to interface type 'Microsoft.Cci.ISymUnmanagedWriter5'", please install [Visual C++ Redistributable for Visual Studio 2015].
+If you meet `Unable to cast COM object of type 'System.__ComObject' to
+interface type 'Microsoft.Cci.ISymUnmanagedWriter5'`, please install
+[Visual C++ Redistributable for Visual Studio 2015][redist].
 
-[Visual C++ Redistributable for Visual Studio 2015]:https://www.microsoft.com/en-hk/download/details.aspx?id=48145
+[redist]: https://www.microsoft.com/en-hk/download/details.aspx?id=48145
 
 ### OS X
 
@@ -148,6 +149,13 @@ dotnet restore
 ./build.ps1
 ```
 
+### PowerShellGitHubDev
+
+Alternatively, the `PowerShellGitHubDev.psm1` module contains a `Start-PSBuild`
+function to build Core PowerShell on both Linux and Windows. This module can be
+imported into the built-in PowerShell on Windows, and a self-hosting copy of
+PowerShell can be installed using our packages under the releases tab.
+
 ## Running
 
 If you encounter any problems, see the [known issues](KNOWNISSUES.md),
@@ -162,6 +170,7 @@ The local managed host has built-in documentation via `--help`.
 
 ### Windows
 
+- set the module path `$env:PsModulePath = "$pwd\bin\Modules"`
 - launch `./bin/powershell.exe`
 - run tests with `./bin/powershell.exe -c "Invoke-Pester test/powershell"`