Add subfolders to Documentation folder

As raised in dotnet/coreclr#1075 by @akoeplinger, the Documentation folder's file
list forces the user to scroll way down to see the README.md. This
PR fixes that by storing the documents in separate sub-folders one
per hierarchy of related documents. Also changed
Documentation\README.md and root README.md to take into account
the new paths.


Commit migrated from 8d3936bff7

docs/coreclr/README.md

@@ -12,71 +12,71 @@ Learn about .NET Core
 Get .NET Core
 =============
 
-- [Get .NET Core DNX SDK on Windows](get-dotnetcore-dnx-windows.md)
-- [Get .NET Core DNX SDK on OS X](get-dotnetcore-dnx-osx.md)
-- [Get .NET Core DNX SDK on Linux](get-dotnetcore-dnx-linux.md)
-- [Get .NET Core (Raw) on Windows](get-dotnetcore-windows.md)
+- [Get .NET Core DNX SDK on Windows](installing/get-dotnetcore-dnx-windows.md)
+- [Get .NET Core DNX SDK on OS X](installing/get-dotnetcore-dnx-osx.md)
+- [Get .NET Core DNX SDK on Linux](installing/get-dotnetcore-dnx-linux.md)
+- [Get .NET Core (Raw) on Windows](installing/get-dotnetcore-windows.md)
 
 Project Docs
 ============
 
-- [Developer Guide](developer-guide.md)
-- [Project priorities](project-priorities.md)
-- [Contributing to .NET Core](contributing.md)
-- [Contributing Workflow](contributing-workflow.md)
-- [Performance Guidelines](performance-guidelines.md)
-- [Garbage Collector Guidelines](garbage-collector-guidelines.md)
+- [Developer Guide](project-docs/developer-guide.md)
+- [Project priorities](project-docs/project-priorities.md)
+- [Contributing to .NET Core](project-docs/contributing.md)
+- [Contributing Workflow](project-docs/contributing-workflow.md)
+- [Performance Guidelines](project-docs/performance-guidelines.md)
+- [Garbage Collector Guidelines](project-docs/garbage-collector-guidelines.md)
 
 Coding Guidelines
 =================
 
-- [CLR Coding Guide](clr-code-guide.md)
-- [CLR JIT Coding Conventions](clr-jit-coding-conventions.md)
-- [Cross Platform Performance and Eventing Design](cross-platform-performance-and-eventing.md)
+- [CLR Coding Guide](coding-guidelines/clr-code-guide.md)
+- [CLR JIT Coding Conventions](coding-guidelines/clr-jit-coding-conventions.md)
+- [Cross Platform Performance and Eventing Design](coding-guidelines/cross-platform-performance-and-eventing.md)
 
 Build CoreCLR from Source
 =========================
 
-- [Building CoreCLR on FreeBSD](freebsd-instructions.md)
-- [Building CoreCLR on Linux](linux-instructions.md)
-- [Building CoreCLR on OS X](osx-instructions.md)
-- [Building CoreCLR on Windows](windows-instructions.md)
-- [Debugging CoreCLR on Windows](windows-debugging-instructions.md)
-- [Testing Changes on Windows](windows-test-instructions.md)
-- [Testing with CoreFX](testing-with-corefx.md)
-- [Creating a Custom DNX](custom-dnx-instructions.md)
+- [Building CoreCLR on FreeBSD](building/freebsd-instructions.md)
+- [Building CoreCLR on Linux](building/linux-instructions.md)
+- [Building CoreCLR on OS X](building/osx-instructions.md)
+- [Building CoreCLR on Windows](building/windows-instructions.md)
+- [Debugging CoreCLR on Windows](building/windows-debugging-instructions.md)
+- [Testing Changes on Windows](building/windows-test-instructions.md)
+- [Testing with CoreFX](building/testing-with-corefx.md)
+- [Creating a Custom DNX](building/custom-dnx-instructions.md)
 
 Book of the Runtime
 ===================
 
-- [Book of the Runtime FAQ](botr-faq.md)
-- [Introduction to the Common Language Runtime](intro-to-clr.md)
-- [Garbage Collection Design](garbage-collection.md)
-- [Threading](threading.md)
-- [RyuJIT Overview](ryujit-overview.md)
-- [Type System](type-system.md)
-- [Type Loader](type-loader.md)
-- [Method Descriptor](method-descriptor.md)
-- [Virtual Stub Dispatch](virtual-stub-dispatch.md)
-- [Stack Walking](stackwalking.md)
-- [Mscorlib and Calling Into the Runtime](mscorlib.md)
-- [Data Access Component (DAC) Notes](dac-notes.md)
-- [Profiling](profiling.md)
-- [Implementing Profilability](profilability.md)
-- [What Every Dev needs to Know About Exceptions in the Runtime](exceptions.md)
+- [Book of the Runtime FAQ](botr/botr-faq.md)
+- [Introduction to the Common Language Runtime](botr/intro-to-clr.md)
+- [Garbage Collection Design](botr/garbage-collection.md)
+- [Threading](botr/threading.md)
+- [RyuJIT Overview](botr/ryujit-overview.md)
+- [Type System](botr/type-system.md)
+- [Type Loader](botr/type-loader.md)
+- [Method Descriptor](botr/method-descriptor.md)
+- [Virtual Stub Dispatch](botr/virtual-stub-dispatch.md)
+- [Stack Walking](botr/stackwalking.md)
+- [Mscorlib and Calling Into the Runtime](botr/mscorlib.md)
+- [Data Access Component (DAC) Notes](botr/dac-notes.md)
+- [Profiling](botr/profiling.md)
+- [Implementing Profilability](botr/profilability.md)
+- [What Every Dev needs to Know About Exceptions in the Runtime](botr/exceptions.md)
 
 Decoder Rings
 =============
 
-- [.NET Core Glossary](glossary.md)
-- [.NET Filename Encyclopedia](dotnet-filenames.md)
+- [.NET Core Glossary](decoders/glossary.md)
+- [.NET Filename Encyclopedia](decoders/dotnet-filenames.md)
 
 Other Information
 =================
 
 - [CoreFX Repo documentation](https://github.com/dotnet/corefx/tree/master/Documentation)
 - [Porting to .NET Core](https://github.com/dotnet/corefx/blob/master/Documentation/support-dotnet-core-instructions.md)
-- [.NET Standards (Ecma)](dotnet-standards.md)
-- [CLR Configuration Knobs](clr-configuration-knobs.md)
+- [.NET Standards (Ecma)](miscellaneous/dotnet-standards.md)
+- [CLR Configuration Knobs](miscellaneous/clr-configuration-knobs.md)
 - [MSDN Entry for the CLR](http://msdn.microsoft.com/library/8bs2ecf4.aspx)
 - [Wikipedia Entry for the CLR](http://en.wikipedia.org/wiki/Common_Language_Runtime)

docs/coreclr/botr/dac-notes.md

@@ -58,7 +58,7 @@ DAC marshaling works through a collection of typedefs, macros and templated type
 
 An example may be helpful in understanding how marshaling works. The common debugging scenario is represented in the following block diagram:
 
-![DAC Overview](images/dac-overview.png)
+![DAC Overview](../images/dac-overview.png)
 
 The debugger in this figure could be Visual Studio, MDbg, WinDbg, etc. The debugger interfaces with the CLR debugger interface (DBI) APIs to get the information it needs. Information that must come from the target goes through the DAC. The debugger implements the data target, which is responsible for implementing a ReadVirtual function to read memory in the target. The dotted line in the diagram represents the process boundary.
 

docs/coreclr/botr/method-descriptor.md

@@ -50,11 +50,11 @@ P/Invoke methods. These are methods marked with DllImport attribute.
 
 **EEImpl**
 
-Delegate methods whose implementation is provided by the runtime (Invoke, BeginInvoke, EndInvoke). See [ECMA 335 Partition II - Delegates](dotnet-standards.md).
+Delegate methods whose implementation is provided by the runtime (Invoke, BeginInvoke, EndInvoke). See [ECMA 335 Partition II - Delegates](../miscellaneous/dotnet-standards.md).
 
 **Array**
 
-Array methods whose implementation is provided by the runtime (Get, Set, Address). See [ECMA Partition II – Arrays](dotnet-standards.md).
+Array methods whose implementation is provided by the runtime (Get, Set, Address). See [ECMA Partition II – Arrays](../miscellaneous/dotnet-standards.md).
 
 **ComInterop**
 
@@ -96,7 +96,7 @@ MethodDesc Chunks
 
 The MethodDescs are allocated in chunks to save space. Multiple MethodDesc tend to have identical MethodTable and upper bits of metadata token. MethodDescChunk is formed by hoisting the common information in front of an array of multiple MethodDescs. The MethodDesc contains just the index of itself in the array.
 
-![Figure 1](images/methoddesc-fig1.png)
+![Figure 1](../images/methoddesc-fig1.png)
 
 Figure 1 MethodDescChunk and MethodTable
 
@@ -185,13 +185,13 @@ The **stable entry point** is either the native code or the precode. The **nativ
 
 Temporary entry points are never saved into NGen images. All entry points in NGen images are stable entry points that are never changed. It is an important optimization that reduced private working set.
 
-![Figure 2](images/methoddesc-fig2.png)
+![Figure 2](../images/methoddesc-fig2.png)
 
 Figure 2 Entry Point State Diagram
 
 A method can have both native code and precode if there is a need to do work before the actual method body is executed. This situation typically happens for NGen image fixups. Native code is an optional MethodDesc slot in this case. This is necessary to lookup the native code of the method in a cheap uniform way.
 
-![Figure 3](images/methoddesc-fig3.png)
+![Figure 3](../images/methoddesc-fig3.png)
 
 Figure 3 The most complex case of Precode, Stub and Native Code
 

docs/coreclr/botr/mscorlib.md

@@ -174,7 +174,7 @@ FCalls require a lot of glue, too much to describe here. Look at [fcall.h][fcall
 
 ### GC Holes, FCall, and QCall
 
-A much more complete discussion on GC holes can be found in the [CLR Code Guide](clr-code-guide.md). Look for ["Is your code GC-safe?"](clr-code-guide.md#is-your-code-gc-safe). This tailored discussion motivates some of the reasons why FCall and QCall have some of their strange conventions.
+A much more complete discussion on GC holes can be found in the [CLR Code Guide](../coding-guidelines/clr-code-guide.md). Look for ["Is your code GC-safe?"](../coding-guidelines/clr-code-guide.md#is-your-code-gc-safe). This tailored discussion motivates some of the reasons why FCall and QCall have some of their strange conventions.
 
 Object references passed as parameters to FCall methods are not GC-protected, meaning that if a GC occurs, those references will point to the old location in memory of an object, not the new location. For this reason, FCalls usually follow the discipline of accepting something like "StringObject*" as their parameter type, then explicitly converting that to a STRINGREF before doing operations that may trigger a GC. You must GC protect object references before triggering a GC, if you expect to be able to use that object reference later.
 

docs/coreclr/botr/ryujit-overview.md

@@ -38,7 +38,7 @@ The RyuJIT IR can be described at a high level as follows:
   * It includes the type of the node, as well as value number, assertions, and register assignments when available.
 * `LclVarDsc` represents a local variable, argument or JIT-created temp. It has a `gtLclNum` which is the identifier usually associated with the variable in the JIT and its dumps. The `LclVarDsc` contains the type, use count, weighted use count, frame or register assignment etc. These are often referred to simply as “lclVars”. They can be tracked (`lvTracked`), in which case they participate in dataflow analysis, and have a different index (`lvVarIndex`) to allow for the use of dense bit vectors.
 
-![RyuJIT IR Overview](images/ryujit-ir-overview.png)
+![RyuJIT IR Overview](../images/ryujit-ir-overview.png)
 
 The IR has two modes:
 
@@ -536,7 +536,7 @@ Below are some of the most useful `COMPLUS` variables. Where {method-list} is sp
 * `COMPLUS_JitTimeLogFile`={file name} – this specifies a log file to which timing information is written.
 * `COMPLUS_JitTimeLogCsv`={file name} – this specifies a log file to which summary timing information can be written, in CSV form.
 
-See also: [CLR Configuration Knobs](https://github.com/dotnet/coreclr/blob/master/Documentation/clr-configuration-knobs.md)
+See also: [CLR Configuration Knobs](../miscellaneous/clr-configuration-knobs.md)
 
 # Reading a JitDump
 

docs/coreclr/botr/stackwalking.md

@@ -26,7 +26,7 @@ Because we control the format of the frames we're interested in (we'll delve int
 
 The following diagram illustrates a stack containing all the frames types (note that this document uses a convention where stacks grow towards the top of the page):
 
-![image](images/stack.png)
+![image](../images/stack.png)
 
 # Making Frames Crawlable
 

docs/coreclr/botr/threading.md

@@ -168,12 +168,12 @@ Thus entering cooperative mode in native code is discouraged. In cases where  co
 
 Similarly, GCX\_PREEMP potentially _releases_ a lock that had been held by the thread. Great care must be taken to ensure that all GC references are properly protected before entering preemptive mode.
 
-The [Rules of the Code](clr-code-guide.md) document describes the disciplines needed to ensure safety around GC mode switches.
+The [Rules of the Code](../coding-guidelines/clr-code-guide.md) document describes the disciplines needed to ensure safety around GC mode switches.
 
 Crst
 ----
 
-Just as Monitor is the preferred locking mechanism for managed code, Crst is the preferred mechanism for VM code. Like Monitor, Crst is a hybrid lock that is aware of hosts and GC modes. Crst also implements deadlock avoidance via "lock leveling," described in the [Crst Leveling chapter of the BotR](clr-code-guide.md#entering-and-leaving-crsts).
+Just as Monitor is the preferred locking mechanism for managed code, Crst is the preferred mechanism for VM code. Like Monitor, Crst is a hybrid lock that is aware of hosts and GC modes. Crst also implements deadlock avoidance via "lock leveling," described in the [Crst Leveling chapter of the BotR](../coding-guidelines/clr-code-guide.md#entering-and-leaving-crsts).
 
 It is generally illegal to acquire a Crst while in cooperative mode, though exceptions are made where absolutely necessary.
 

docs/coreclr/botr/type-loader.md

@@ -26,7 +26,7 @@ cast is safe and can be done).
 This performance requirement rules out any dictionary look up
 approaches and leaves us with the following high-level architecture.
 
-![Figure 1](images/typeloader-fig1.png)
+![Figure 1](../images/typeloader-fig1.png)
 
 Figure 1 The abstract high-level object design
 
@@ -98,7 +98,7 @@ If **MyClass** fails to load, for example because it's supposed to be defined in
 
 The most universal type designation in the CLR is the **TypeHandle**. It's an abstract entity which encapsulates a pointer to either a **MethodTable** (representing "ordinary" types like **System.Object** or **List<string>** ) or a **TypeDesc** (representing byrefs, pointers, function pointers, arrays, and generic variables). It constitutes the identity of a type in that two handles are equal if and only if they represent the same type. To save space, the fact that a **TypeHandle** contains a **TypeDesc** is indicated by setting the second lowest bit of the pointer to 1 (i.e. (ptr | 2)) instead of using additional flags<sup>2</sup>. **TypeDesc** is "abstract" and has the following inheritance hierarchy.
 
-![Figure 2](images/typeloader-fig2.png)
+![Figure 2](../images/typeloader-fig2.png)
 
 Figure 2 The TypeDesc hierarchy
 
@@ -176,7 +176,7 @@ Runtime][generics-design] for more detailed explanation of load levels.
 
 In the generics-free world, everything is nice and everyone is happy because every ordinary (not represented by a **TypeDesc**) type has one **MethodTable** pointing to its associated **EEClass** which in turn points back to the **MethodTable**. All instances of the type contain a pointer to the **MethodTable** as their first field at offset 0, i.e. at the address seen as the reference value. To conserve space, **MethodDescs** representing methods declared by the type are organized in a linked list of chunks pointed to by the **EEClass**<sup>4</sup>.
 
-![Figure 3](images/typeloader-fig3.png)
+![Figure 3](../images/typeloader-fig3.png)
 
 Figure 3 Non-generic type with non-generic methods
 
@@ -287,7 +287,7 @@ that there is a considerable amount of information that they can
 share. This sharing has a positive impact on the memory footprint and
 consequently also performance.
 
-![Figure 4](images/typeloader-fig4.png)
+![Figure 4](../images/typeloader-fig4.png)
 
 Figure 4 Generic type with non-generic methods - shared EEClass
 

docs/coreclr/botr/type-system.md

@@ -43,7 +43,7 @@ Dependencies
 
 The type system is generally a service provided to many parts of the CLR, and most core components have some form of dependency on the behavior of the type system. This diagram describes the general dataflow that effects the type system. It is not exhaustive, but calls out the major information flows.
 
-![dependencies](images/type-system-dependencies.png)
+![dependencies](../images/type-system-dependencies.png)
 
 ### Component Dependencies
 
@@ -227,7 +227,7 @@ Major entry points are BuildMethodTable, LoadTypeHandleThrowing, CanCastTo\*, Ge
 Related Reading
 ===============
 
-- [ECMA CLI Specification](dotnet-standards.md)
+- [ECMA CLI Specification](../miscellaneous/dotnet-standards.md)
 - [Type Loader](type-loader.md) Book of the Runtime Chapter
 - [Virtual Stub Dispatch](virtual-stub-dispatch.md) Book of the Runtime Chapter
 - [MethodDesc](method-descriptor.md) Book of the Runtime Chapter

docs/coreclr/botr/virtual-stub-dispatch.md

@@ -89,7 +89,7 @@ The slot map is a table of zero or more <_type_, [<_slot_, _scope_, (_index | sl
 
 The following is a small class structure (modeled in C#), and what the resulting implementation table and slot map would be for each class.
 
-![Figure 1](images/virtualstubdispatch-fig1.png)
+![Figure 1](../images/virtualstubdispatch-fig1.png)
 
 Thus, looking at this map, we see that the first column of the sub-maps of the slot maps correspond to the slot number in the classic virtual table view (remember that System.Object contributes four virtual methods of its own, which are omitted for clarity). Searches for method implementations are always bottom-up. Thus, if I had an object of type _B_ and I wished to invoke _I.Foo_, I would look for a mapping of _I.Foo_ starting at _B_'s slot map. Not finding it there, I would look in _A_'s slot map and find it there. It states that virtual slot 0 of _I_ (corresponding to _I.Foo_) is implemented by virtual slot 0. Then I return to _B_'s slot map and search for an implementation for slot 0, and find that it is implemented by slot 1 in its own implementation table.
 
@@ -130,7 +130,7 @@ Interface dispatch calls go through stubs. These stubs are all generated on dema
 
 There are currently three types of stubs. The below diagram shows the general control flow between these stubs, and will be explained below.
 
-![Figure 2](images/virtualstubdispatch-fig2.png)
+![Figure 2](../images/virtualstubdispatch-fig2.png)
 
 ### Generic Resolver
 
@@ -160,11 +160,11 @@ One resolve stub is created per token, but they all use a global cache. A stub-p
 
 The former interface virtual table dispatch mechanism results in a code sequence similar to this:
 
-![Figure 3](images/virtualstubdispatch-fig3.png)
+![Figure 3](../images/virtualstubdispatch-fig3.png)
 
 And the typical stub dispatch sequence is:
 
-![Figure 1](images/virtualstubdispatch-fig4.png)
+![Figure 1](../images/virtualstubdispatch-fig4.png)
 
 where expectedMT, failure and target are constants encoded in the stub.
 

docs/coreclr/decoders/glossary.md

@@ -16,6 +16,6 @@ As much as possible, we should link to the most authoritative and recent source
 * SOS: [Son of Strike](http://blogs.msdn.com/b/jasonz/archive/2003/10/21/53581.aspx). The debugging extension for DbgEng based debuggers. Uses the DAC as an abstraction layer for its operation.
 * SVR: The CLR used to be built as two variants, with one called "mscorsvr.dll", to mean the "server" version. In particular, it contained the server GC implementation, which was intended for multi-threaded apps capable of taking advantage of multiple processors. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available.
 * URT: Universal Runtime. Ancient name for what ended up being .NET, is used in the WinError facility name FACILITY_URT.
-* VSD: [Virtual Stub Dispatch](virtual-stub-dispatch.md). Technique of using stubs for virtual method invocations instead of the traditional virtual method table.
+* VSD: [Virtual Stub Dispatch](../botr/virtual-stub-dispatch.md). Technique of using stubs for virtual method invocations instead of the traditional virtual method table.
 * VM: Virtual machine.
 * WKS: The CLR used to be built as two variants, with one called "mscorwks.dll", to mean the "workstation" version. In particular, it contained the client GC implementation, which was intended for single-threaded apps, independent of how many processors were on the machine. In the .NET Framework 2 release, the two variants were merged into "mscorwks.dll". The WKS version was the default, however the SVR version remained available.

docs/coreclr/installing/get-dotnetcore-dnx-linux.md

@@ -7,7 +7,7 @@ These instructions are for .NET Core console apps. If you want to try out ASP.NE
 
 .NET Core NuGet packages and the .NET Core DNX SDKs are available on the [ASP.NET 'vnext' myget feed](https://www.myget.org/F/aspnetvnext), which you can more easily view on [gallery](https://www.myget.org/gallery/aspnetvnext) for the feed.
 
-You can also [build from source](linux-instructions.md). 
+You can also [build from source](../building/linux-instructions.md). 
 
 Environment
 ===========

docs/coreclr/installing/get-dotnetcore-dnx-osx.md

@@ -7,7 +7,7 @@ These instructions are for .NET Core console apps. If you want to try out ASP.NE
 
 .NET Core NuGet packages and the .NET Core DNX SDKs are available on the [ASP.NET 'vnext' myget feed](https://www.myget.org/F/aspnetvnext), which you can more easily view on [gallery](https://www.myget.org/gallery/aspnetvnext) for the feed.
 
-You can also [build from source](osx-instructions.md). 
+You can also [build from source](../building/osx-instructions.md). 
 
 Installing DNVM
 ===============

docs/coreclr/installing/get-dotnetcore-dnx-windows.md

@@ -7,7 +7,7 @@ These instructions are for .NET Core console apps. If you want to try out ASP.NE
 
 .NET Core NuGet packages and the .NET Core DNX SDKs are available on the [ASP.NET 'vnext' myget feed](https://www.myget.org/F/aspnetvnext), which you can more easily view on [gallery](https://www.myget.org/gallery/aspnetvnext) for the feed.
 
-You can also acquire .NET Core directly via [NuGet restore](get-coreclr-windows.md) or [build from source](windows-instructions.md). 
+You can also acquire .NET Core directly via [NuGet restore](get-dotnetcore-windows.md) or [build from source](../building/windows-instructions.md). 
 
 Installing DNVM
 ===============

docs/coreclr/installing/get-dotnetcore-windows.md

@@ -7,7 +7,7 @@ These instructions are for .NET Core console apps. If you want to try out ASP.NE
 
 .NET Core NuGet packages are available on the [.NET Core myget feed](https://www.myget.org/F/dotnet-core), which you can more easily view on [gallery](https://www.myget.org/gallery/dotnet-core) for the feed.
 
-The preferred approach to acquire .NET Core is via the [.NET Core DNX SDK](get-dotnetcore-dnx-windows.md). It's the easiest approach. Alternatively, you can [build from source](windows-instructions.md). This "raw" approach falls between the two in difficulty.
+The preferred approach to acquire .NET Core is via the [.NET Core DNX SDK](get-dotnetcore-dnx-windows.md). It's the easiest approach. Alternatively, you can [build from source](../building/windows-instructions.md). This "raw" approach falls between the two in difficulty.
 
 NuGet Restore Packages
 ======================

docs/coreclr/project-docs/developer-guide.md

@@ -15,7 +15,7 @@ The CoreCLR repo can be built from a regular, non-admin command prompt. The buil
 | ARM32 | ◯ | ◯| ◯ |
 |       | [Instructions](windows-instructions.md) | [Instructions](linux-instructions.md) | [Instructions](osx-instructions.md) |  
 
-The CoreCLR build and test suite is a work in progress, as are the [building and testing instructions](README.md). The .NET Core team and the community are improving Linux and OS X support on a daily basis are and adding more tests for all platforms. See [CoreCLR Issues](https://github.com/dotnet/coreclr/issues) to find out about specific work items or report issues.
+The CoreCLR build and test suite is a work in progress, as are the [building and testing instructions](../README.md). The .NET Core team and the community are improving Linux and OS X support on a daily basis are and adding more tests for all platforms. See [CoreCLR Issues](https://github.com/dotnet/coreclr/issues) to find out about specific work items or report issues.
 
 Understanding the TFS-Git Mirror
 ================================