README.md big update for VS for Mac

1 files changed, 127 insertions, 5 deletions

diff --git a/README.md b/README.md
index a51db21..6884212 100644
--- a/README.md
+++ b/README.md
@@ -1,12 +1,92 @@
 # Microsoft Visual Studio Editor API
 
-This repository contains Microsoft Visual Studio Editor public API representing text model, text logic and text view subsystems of the editor.
-For more information about Visual Studio Editor architecture see [Inside the Editor](https://msdn.microsoft.com/en-us/library/dd885240.aspx).
-This API is typically used to build Visual Studio extensions.
+This repository contains the open source layers of the Microsoft Visual
+Studio editor. This includes all public API definitions and some low level
+implementations of the editor including the text model, text logic, and
+editor primitives & operations subsystems. These layers are intended for
+extension authors to better integrate with the editor.
 
-# Installation
+With a few caveats, the layers in this repository power both Visual
+Studio on Windows and the Visual Studio for Mac editors. While both editors
+are built on this codebase, many aspects of the editor are not open source,
+including the WPF and Cocoa UI layers.
 
-Visual Studio Editor API is shipping as the following Nuget packages and also gets installed with Visual Studio Extension Development workload.
+## Visual Studio for Mac
+
+Visual Studio for Mac 8.1 [introduced a brand new native macOS text editor](https://docs.microsoft.com/en-us/visualstudio/releasenotes/vs2019-mac-relnotes#---new-c-editor)
+built on the "real" Visual Studio editor core. Central to our ongoing effort
+to bring parity and performance benefits to developers by leveraging and
+sharing more code with Visual Studio on Windows, the UI layers were ported
+directly from WPF to modern Cocoa.
+
+Most notably, the Cocoa editor uses Apple's
+[Core Text](https://developer.apple.com/documentation/coretext),
+[Core Graphics](https://developer.apple.com/documentation/coregraphics), and
+[Core Animation](https://developer.apple.com/documentation/quartzcore)
+technologies to perform retained-mode layout and high fidelity rendering of
+text. Among other enhancements for and integrations with macOS, it
+now supports all of the macOS input methods via the
+[`NSTextInputClient`](https://developer.apple.com/documentation/appkit/nstextinputclient)
+protocol.
+
+Currently, the new native editor based on Visual Studio and the legacy editor
+co-exist while we transition all language services away from the legacy
+editor. Visual Studio for Mac supports C# and XAML (in 8.2 previews) so far,
+but will continue to enable support for other languages over the coming
+releases. Please refer to the
+[Visual Studio for Mac roadmap](https://docs.microsoft.com/en-us/visualstudio/productinfo/mac-roadmap)
+for details on what's next.
+
+This diagram should help visualize the layering of Visual Studio for Mac
+compared to Visual Studio while the legacy editor still exists for some
+languages.
+
+![Visual Studio for Mac Editor Architecture](https://docs.microsoft.com/en-us/visualstudio/mac/media/vs-editor-architecture.png)
+
+## Caveats
+
+In order to facilitate porting the WPF editor from Windows to macOS, some
+breaking changes have been made to some of the lower-level interfaces. The
+ongoing plan is to reconcile these differences such that there is no API
+difference whatsoever between the WPF and Cocoa editors.
+
+For now, however, there are two separate sets of NuGet packages for targeting
+Visual Studio and Visual Studio for Mac, available in the respective sections
+below.
+
+While _most_ non-UI related interfaces are identical across WPF and Cocoa
+implementations of the editor, many are new yet familiar: when targeting
+Cocoa, `ICocoa*` interfaces can generally be found in place of analogous
+`IWpf*` interfaces.
+
+## Resources
+
+The following resources should help extension authors become familiar with
+the editor APIs and capabilities, and are relevant to both Visual Studio
+and Visual Studio for Mac.
+
+* [Managed Extensibility Framework](https://docs.microsoft.com/dotnet/framework/mef/index)
+* [MEF in the Editor](https://docs.microsoft.com/visualstudio/extensibility/managed-extensibility-framework-in-the-editor)
+* [Inside the Editor](https://docs.microsoft.com/visualstudio/extensibility/inside-the-editor)
+* [Language Service and Editor Extension Points](https://docs.microsoft.com/visualstudio/extensibility/language-service-and-editor-extension-points)
+* [A video introduction to the editor architecture](https://www.youtube.com/watch?v=PkYVztKjO9A)
+
+## Editor SDK Installation
+
+### Visual Studio for Mac
+
+NuGet packages are forthcoming, but all assemblies are available to extensions
+for Visual Studio for Mac when using Add-in Maker. The assemblies can also be
+produced directly from this repository (see
+[Building the Editor API](#build-the-editor-api) below).
+
+Refer to the [Extending Visual Studio for Mac](https://docs.microsoft.com/en-us/visualstudio/mac/extending-visual-studio-mac) documentation for details.
+
+
+### Visual Studio (Windows)
+
+On Windows, the Visual Studio Editor API is available via NuGet and is also
+installed with the Visual Studio Extension Development workload. Note that
 
 | Nuget package | Current version |
 | ------------- | ------------- |
@@ -14,3 +94,45 @@ Visual Studio Editor API is shipping as the following Nuget packages and also ge
 | [Microsoft.VisualStudio.Text.Data](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Data) | [![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Text.Data.svg)](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Data) |
 | [Microsoft.VisualStudio.Text.Logic](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Logic) | [![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Text.Logic.svg)](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.Logic) |
 | [Microsoft.VisualStudio.Text.UI](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.UI) | [![NuGet package](https://img.shields.io/nuget/v/Microsoft.VisualStudio.Text.UI.svg)](https://www.nuget.org/packages/Microsoft.VisualStudio.Text.UI) |
+
+## Building The Editor API
+
+While this repository is largely intended for reference, it can produce a
+viable build of the lower levels of the editor. Either open `VSEditorCore.sln`
+in Visual Studio or Visual Studio for Mac and build from the IDE, or build
+on the command line.
+
+Visual Studio 2019 or Visual Studio for Mac 8.0 or newer is required.
+
+### Build
+
+Assemblies will be available in the `bin/` directory at the root of the
+repository.
+
+```bash
+$ msbuild /restore
+```
+
+### Package
+
+NuGet packages may also be produced locally and will be available in
+the `_artifacts/nuget/` directory at the root of the repository.
+
+```bash
+$ msbuild /t:Pack
+```
+
+## Contributing
+
+This project has adopted the
+[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
+For more information see the
+[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
+or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any
+additional questions or comments.
+
+### Pull Requests
+
+We are generally not accepting pull requests for this repository for the
+core editor code at this time. Please feel free to submit pull requests for
+other content in this repository, including new samples.
\ No newline at end of file