Update libraries.md

rfcs/libraries.md

@@ -16,24 +16,26 @@ We need a way to group together related code and provide easy ways to require th
 
 Our require syntax should:
 
-- Work the same way in the Roblox engine and Luau language
-- Be resolvable at compile-time
+- Allow a library written in Luau to be imported into the Roblox engine and 'just work'.
+- Support compile-time file resolution _where possible_ for type checking.
 
 #### Absolute
 
 Modules can be required by their absolute path from the root of the filesystem.
 
 Requiring a file called `MyModule.luau` in `C:/MyLibrary`:
-```lua=
+```lua
 local MyModule = require("C:/MyLibrary/MyModule")
 ```
 
+Generally, absolute paths should not be used in regular code and should only appear in the alias map. Their purpose is to allow libraries to be stored in a global location (such as if a package is installed globally) without breaking if the libraries location is changed on disk.
+
 #### Relative
 
 Modules can be required relative to the requiring files location in the filesystem.
 
 If we are trying to access a file called `MyModule.luau` in `C:/MyLibrary`:
-```lua=
+```lua
 -- From C:/MyLibrary/SubDirectory/SubModule.luau
 local MyModule = require("../MyModule")
  
@@ -47,23 +49,23 @@ All relative paths will start with either `./`  or `../`  which denote the direc
 
 Aliases can be used to bind an absolute or relative path to a convenient name that can be required directly. They are always prefixed with `$` to make it obvious they are not the same as a regular path.
 
-While the format is yet to be decided it will be a map that exists as part of a library and is defined in a format such as JSON.
+Each library has its own map which will be stored in the `.luaurc` file. Since libraries can be embedded inside of one another, any aliases which are not overriden will be inherited from the parent library.
 
-```json=
-{
+```json
+"Aliases": {
     "Roact": "C:/LuauModules/Roact-v1.4.2"
 }
 ```
 
 Based on that map you would be able to require Roact directly:
 
-```lua=
+```lua
 local Roact = require("$Roact")
 ```
 
 Or even a sub-module:
 
-```lua=
+```lua
 local createElement = require("$Roact/createElement")
 ```
 
@@ -76,14 +78,10 @@ Aliases are simple bindings and aren't concerned with versioning. The intention
 All libraries have a special alias for referring to their root. This alias cannot be overriden and is simply defined as `$`.
 
 Requiring any file in the library can be done relative to the root:
-```lua=
+```lua
 local ModuleAtLibraryRoot = require("$/ModuleAtLibraryRoot")
 ```
 
-##### Inheritance
-
-Libraries can be embedded in other libraries. In this case aliases are inherited from the parent.
-
 ##### Limitations
 
 - Aliases cannot reference other aliases
@@ -100,7 +98,13 @@ If the string resolves to a directory rather than a file then we will attempt to
 
 #### DataModel as VFS
 
-In the Roblox engine, the DataModel will act as a VFS with the DataModel itself at the root. This will allow packages from Luau to be imported and exported freely without needing to consider the platform they are being used on.
+In the Roblox engine, the DataModel will act as a virtual file system. At the root of this VFS is the DataModel itself. This will allow packages from Luau to be imported and exported freely without needing to consider the platform they are being used on.
+
+All paths used in the Roblox engine must refer to a location in the DataModel, they cannot be used to access files on disk.
+
+#### Platforms
+
+For compatability across platforms, we will automatically map `/` onto `\` on Windows.
 
 #### Backwards Compatibility
 
@@ -108,7 +112,9 @@ Possibly not. TBD
 
 ### Defining a Library
 
-TBD
+Any directory containing a `.luaurc` file is considered a library.
+
+Since we don't support `.luaurc` files in the DataModel we will introduce a new `Library` instance which contains the alias map and other properties.
 
 ## Drawbacks