Update documentation.

- Update readme to fill out some of the `TODO` sections

- Add an API user's guide that gives the basics of linking against Slang and using it to compile and reflect shaders

- Add a bit of usage info for the command-line `slangc` program

- Add an overview of the Slang language as it stands today

- Add an initial FAQ, mostly to help answer the "why should I use this?" question

1 files changed, 104 insertions, 0 deletions

diff --git a/docs/language-guide.md b/docs/language-guide.md
new file mode 100644
index 000000000..a388e70f3
--- /dev/null
+++ b/docs/language-guide.md
@@ -0,0 +1,104 @@
+Slang Language Guide
+====================
+
+This document will try to describe the main characteristis of the Slang language that might make it different from other shading languages you have used.
+
+The Basics
+----------
+
+Slang is similar to HLSL, and it is expected that many HLSL programs can be used as Slang code with no modifications.
+Big-picture stuff that is supported:
+
+* A C-style preprocessor
+* Ordinary function, `struct`, `typedef`, etc. declarations
+* The standard vector/matrix types like `float3` and `float4x4`
+* The less-used explicit `vector<T,N>` and `matrix<T,R,C>` types
+* `cbuffer` declarations for uniform parameters
+* Global-scope declarations of texture/sampler parameters, including with `register` annotations
+* Entry points with varying `in`/`out` parameters using semantics (including `SV_*` system-value semantics)
+* The built-in templated resource types like `Texture2D<T>` with their object-oriented syntax for sampling operations
+* Attributes like `[unroll]` are parsed, and passed along for HLSL/DXBC output, but dropped for other targets
+* `struct` types that contain textures/samplers as well as ordinary uniform data, both as function parameters and in constant buffers
+
+New Features
+------------
+
+Right now the Slang language only has one major feature that is different from existing HLSL (that will change over time).
+
+### Import Declarations
+
+In order to support better software modularity, and also to deal with the issue of how to integrate shader libraries written in Slang into other langauges, Slang introduces an `__import` declaration construct.
+
+The basic idea is that if you write a file `foo.slang` like this:
+
+```
+// foo.slang
+
+float4 someFunc(float4 x) { return x; }
+```
+
+you can then import this code into another file in Slang, HLSL, or GLSL:
+
+```
+// bar.glsl
+
+__import foo;
+
+vec4 someOtherFunc(vec4 y) { return someFunc(y); }
+```
+
+The simplest way to think of it is that the `__import foo` declaration instructs the compiler to look for `foo.slang` (in the same search paths it uses for `#include` files), and give an error if it isn't found.
+If `foo.slang` is found, then the compiler will go ahead and parse and type-check that file, and make any declarations there visible to the original file (`bar.glsl` in this example).
+
+When it comes time to generate output code, Slang will output any declarations from `__import`ed files that were actually used (it skips those that are never referenced), and it will cross-compile them as needed for the chosen target.
+
+A few other details worth knowing about `__import` declarations:
+
+* The name you use on the `__import` line gets translated into a file name with some very simple rules. An underscore (`_`) in the name turns into a dash (`-`) in the file name, and dot separators (`.`) turn into directory seprators (`/`). After these substitutions, `.slang` is added to the end of the name.
+
+* If there are multiple `__import` declarations naming the same file, it will only be imported once. This is also true for nested imports.
+
+* Currently importing does not imply any kind of namespacing; all global declarations still occupy a single namespace, and collisions between different imported files (or between a file and the code it imports) are possible. This is a bug.
+
+* If file `A.slang` imports `B.slang`, and then some other file does `__import A;`, then only the names from `A.slang` are brought into scope, not those from `B.slang`. This behavior can be controlled by having `A.slang` use `__exported __import B;` to also re-export the declarations it imports from `B`.
+
+* An import is *not* like a `#include`, and so the file that does the `__import` can't see preprocessor macros defined in the imported file (and vice versa). Think inf `__import foo;` as closer to `using namspace foo;` in C++ (perhaps without the same baggage).
+
+On that last point, if you really do want something that is like `__import` but interacts with the preprocessor more like `#include` then you can try using `#import`:
+
+```
+#import "foo.slang"
+...
+```
+
+The `#import` directive is recognized during preprocessing, so macro definitions from the importing file will affect the imported code, and vice versa.
+The rules about multiple imports still apply, though, so only the first `#import` encountered will determine the text that is parsed (be careful).
+Please think of `#import` as a stopgap for when you want the cross-compilation benefits of `__import`, but need to deal with code that depends on macros in the here and now.
+
+Future Extensions
+-----------------
+
+Longer term we would like to make Slang a much more advanced language, and indeed the implementation already has some of the underpinnings for more powerful things.
+
+The most important feature we plan to add is support for "constrained generics" as they appear in C#, Rust, and Swift.
+For those of you with a C++ background you could think of this as "templates + concepts", but without many of the rought edges.
+
+Using constrained generics as an underlying mechanism, we then plan to introduce a feature similar in capability to Cg's "interfaces" feature, to allow shaders to express more flexible patterns of composition and dispatch.
+
+
+Not Supported
+-------------
+
+Some things are not supported, but probably will be given enough time/resources:
+
+* Local variables of texture/sampler type (or that contain these)
+* Matrix swizzles
+* Object-oriented extensions for putting methods inside `struct` types
+* Explicit `packoffset` annotations on members of `cbuffer`s
+
+Some things from HLSL are *not* planned to be supported, unless there is significant outcry from users:
+
+* Pre-D3D10/11 syntax and operations
+* The "effect" system, and the related `<>` annotation syntax
+* Explicit `register` bindings on textures/samplers nested in `cbuffer`s
+* Any further work towards making HLSL a subset of C++ (simply because implementing a full C++ compiler is way out of scope for the Slang project)