Format README using markdown.

diff --git a/README.md b/README.md
new file mode 100644 (file)
index 0000000..fb6d12c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,187 @@
+glslang
+=======
+
+An OpenGL and OpenGL ES shader front end and validator.
+
+There are two components:
+
+1. A front-end library for programmatic parsing of GLSL/ESSL into an AST.
+
+2. A standalone wrapper, `glslangValidator`, that can be used as a shader
+   validation tool.
+
+How to add a feature protected by a version/extension/stage/profile:  See the
+comment in `glslang/MachineIndependent/Versions.cpp`.
+
+Things left to do:  See `Todo.txt`
+
+Execution of Standalone Wrapper
+-------------------------------
+
+There are binaries in the `Install/Windows` and `Install/Linux` directories.
+
+To use the standalone binary form, execute `glslangValidator`, and it will print
+a usage statement.  Basic operation is to give it a file containing a shader,
+and it will print out warnings/errors and optionally an AST.
+
+The applied stage-specific rules are based on the file extension:
+* `.vert` for a vertex shader
+* `.tesc` for a tessellation control shader
+* `.tese` for a tessellation evaluation shader
+* `.geom` for a geometry shader
+* `.frag` for a fragment shader
+* `.comp` for a compute shader
+
+There is also a non-shader extension
+* `.conf` for a configuration file of limits, see usage statement for example
+
+Source: Build and run on Linux
+-------------------------------
+
+A simple bash script `BuildLinux.sh` is provided at the root directory
+to do the build and run a test cases.  You will need a recent version of
+bison installed.
+
+Once the executable is generated, it needs to be dynamically linked with the
+shared object created in `lib` directory. To achieve that, `cd` to
+`StandAlone` directory to update the `LD_LIBRARY_PATH` as follows
+
+```bash
+export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./../glslang/MachineIndependent/lib
+```
+
+You can also update `LD_LIBRARY_PATH` in the `.cshrc` or `.bashrc` file,
+depending on the shell you are using. You will need to give the complete path
+of `lib` directory in `.cshrc` or `.bashrc` files.
+
+Source: Build and run on Windows
+--------------------------------
+
+Current development is with Visual Studio verion 11 (2012).  The solution
+file is in the project's root directory `Standalone.sln`.
+
+Building the StandAlone project (the default) will create `glslangValidate.exe`
+and copy it into the `Test` directory and `Install` directory.  This allows
+local test scripts to use either the debug or release version, whichever was
+built last.
+
+Windows execution and testing is generally done from within a cygwin
+shell.
+
+Note: Despite appearances, the use of a DLL is currently disabled; it
+simply makes a standalone executable from a statically linked library.
+
+Programmatic Interfaces
+-----------------------
+
+Another piece of software can programmatically translate shaders to an AST
+using one of two different interfaces:
+* A new C++ class-oriented interface, or
+* The original C functional interface
+
+The `main()` in `StandAlone/StandAlone.cpp` shows examples using both styles.
+
+### C++ Class Interface (new, preferred)
+
+This interface is in roughly the last 1/3 of `ShaderLang.h`.  It is in the
+glslang namespace and contains the following.
+
+```cxx
+const char* GetEsslVersionString();
+const char* GetGlslVersionString();
+bool InitializeProcess();
+void FinalizeProcess();
+
+class TShader
+    bool parse(...);
+    void setStrings(...);
+    const char* getInfoLog();
+
+class TProgram
+    void addShader(...);
+    bool link(...);
+    const char* getInfoLog();
+    Reflection queries
+```
+
+See `ShaderLang.h` and the usage of it in `StandAlone/StandAlone.cpp` for more
+details.
+
+### C Functional Interface (orginal)
+
+This interface is in roughly the first 2/3 of `ShaderLang.h`, and referred to
+as the `Sh*()` interface, as all the entry points start `Sh`.
+
+The `Sh*()` interface takes a "compiler" call-back object, which it calls after
+building call back that is passed the AST and can then execute a backend on it.
+
+The following is a simplified resulting run-time call stack:
+
+```c
+ShCompile(shader, compiler) -> compiler(AST) -> <back end>
+```
+
+In practice, `ShCompile()` takes shader strings, default version, and
+warning/error and other options for controling compilation.
+
+Testing
+-------
+
+`Test` is an active test directory that contains test input and a
+subdirectory `baseResults` that contains the expected results of the
+tests.  Both the tests and `baseResults` are under source-code control.
+Executing the script `./runtests` will generate current results in
+the `localResults` directory and `diff` them against the `baseResults`.
+When you want to update the tracked test results, they need to be
+copied from `localResults` to `baseResults`.
+
+There are some tests borrowed from LunarGLASS.  If LunarGLASS is
+missing, those tests just won't run.
+
+Basic Internal Operation
+------------------------
+
+* Initial lexical analysis is done by the preprocessor in
+  `MachineIndependent/Preprocessor`, and then refined by a GLSL scanner
+  in `MachineIndependent/Scan.cpp`.  There is currently no use of flex.
+
+* Code is parsed using bison on `MachineIndependent/glslang.y` with the
+  aid of a symbol table and an AST.  The symbol table is not passed on to
+  the back-end; the intermediate representation stands on its own.
+  The tree is built by the grammar productions, many of which are
+  offloaded into `ParseHelper.cpp`, and by `Intermediate.cpp`.
+
+* The intermediate representation is very high-level, and represented
+  as an in-memory tree.   This serves to lose no information from the
+  original program, and to have efficient transfer of the result from
+  parsing to the back-end.  In the AST, constants are propogated and
+  folded, and a very small amount of dead code is eliminated.
+
+  To aid linking and reflection, the last top-level branch in the AST
+  lists all global symbols.
+
+* The primary algorithm of the back-end compiler is to traverse the
+  tree (high-level intermediate representation), and create an internal
+  object code representation.  There is an example of how to do this
+  in `MachineIndependent/intermOut.cpp`.
+
+* Reduction of the tree to a linear byte-code style low-level intermediate
+  representation is likely a good way to generate fully optimized code.
+
+* There is currently some dead old-style linker-type code still lying around.
+
+* Memory pool: parsing uses types derived from C++ `std` types, using a
+  custom allocator that puts them in a memory pool.  This makes allocation
+  of individual container/contents just few cycles and deallocation free.
+  This pool is popped after the AST is made and processed.
+
+  The use is simple: if you are going to call `new`, there are three cases:
+
+  - the object comes from the pool (its base class has the macro
+    `POOL_ALLOCATOR_NEW_DELETE` in it) and you do not have to call `delete`
+
+  - it is a `TString`, in which case call `NewPoolTString()`, which gets
+    it from the pool, and there is no corresponding `delete`
+
+  - the object does not come from the pool, and you have to do normal
+    C++ memory management of what you `new`

diff --git a/README.txt b/README.txt
deleted file mode 100644 (file)
index 3a2fe29..0000000
--- a/README.txt
+++ /dev/null
@@ -1,178 +0,0 @@
-An OpenGL and OpenGL ES shader front end and validator.
-
-There are two components:
-
-1) A front-end library for programmatic parsing of GLSL/ESSL into an AST.
-
-2) A standalone wrapper, glslangValidator, that can be used as a shader 
-   validation tool. 
-
-How to add a feature protected by a version/extension/stage/profile:  See the
-comment in glslang/MachineIndependent/Versions.cpp.
-
-Things left to do:  See Todo.txt
-
-Execution of Standalone Wrapper
--------------------------------
-
-There are binaries in the Install/Windows and Install/Linux directories.
-
-To use the standalone binary form, execute glslangValidator, and it will print
-a usage statement.  Basic operation is to give it a file containing a shader,
-and it will print out warnings/errors and optionally an AST.
-
-The applied stage-specific rules are based on the file extension:
-    .vert for a vertex shader
-    .tesc for a tessellation control shader
-    .tese for a tessellation evaluation shader
-    .geom for a geometry shader
-    .frag for a fragment shader
-    .comp for a compute shader
-
-There is also a non-shader extension
-    .conf for a configuration file of limits, see usage statement for example
-
-Source: Build and run on Linux
--------------------------------
-
-A simple bash script "BuildLinux.sh" is provided at the root directory
-to do the build and run a test cases.  You will need a recent version of
-bison installed.
-
-Once the executable is generated, it needs to be dynamically linked with the 
-shared object created in lib directory. To achieve that, "cd" to 
-StandAlone directory to update the LD_LIBRARY_PATH as follows
-
-export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:./../glslang/MachineIndependent/lib
-
-You can also update LD_LIBRARY_PATH in the .cshrc or .bashrc file, depending on 
-the shell you are using. You will need to give the complete path of "lib" directory
-in .cshrc or .bashrc files.
-
-Source: Build and run on Windows
---------------------------------
-
-Current development is with Visual Studio verion 11 (2012).  The solution
-file is in the project's root directory Standalone.sln.  
-
-Building the StandAlone project (the default) will create glslangValidate.exe and
-copy it into the Test directory and Install directory.  This allows local
-test scripts to use either the debug or release version, whichever was
-built last.
-
-Windows execution and testing is generally done from within a cygwin
-shell.
-
-Note: Despite appearances, the use of a DLL is currently disabled; it
-simply makes a standalone executable from a statically linked library.
-
-Programmatic Interfaces
------------------------
-
-Another piece of software can programmatically translate shaders to an AST 
-using one of two different interfaces: 
-    - A new C++ class-oriented interface, or
-    - The original C functional interface
-
-The main() in StandAlone/StandAlone.cpp shows examples using both styles.
-
-C++ Class Interface (new, preferred):
-
-    This interface is in roughly the last 1/3 of ShaderLang.h.  It is in the 
-    glslang namespace and contains the following.
-
-        const char* GetEsslVersionString();
-        const char* GetGlslVersionString();
-        bool InitializeProcess();
-        void FinalizeProcess();
-
-        class TShader
-            bool parse(...);
-            void setStrings(...);
-            const char* getInfoLog();
-
-        class TProgram
-            void addShader(...);
-            bool link(...);
-            const char* getInfoLog();
-            Reflection queries
-
-    See ShaderLang.h and the usage of it in StandAlone/StandAlone.cpp for more
-    details.
-            
-C Functional Interface (orginal):
-
-    This interface is in roughly the first 2/3 of ShaderLang.h, and referred to
-    as the Sh*() interface, as all the entry points start "Sh".
-
-    The Sh*() interface takes a "compiler" call-back object, which it calls after 
-    building call back that is passed the AST and can then execute a backend on it.
-
-    The following is a simplified resulting run-time call stack:
-
-        ShCompile(shader, compiler) -> compiler(AST) -> <back end>
-
-    In practice, ShCompile() takes shader strings, default version, and
-    warning/error and other options for controling compilation.
-
-Testing
--------
-
-"Test" is an active test directory that contains test input and a
-subdirectory baseResults that contains the expected results of the
-tests.  Both the tests and baseResults are under source-code control.
-Executing the script ./runtests will generate current results in 
-the localResults directory and diff them against the baseResults.
-When you want to update the tracked test results, they need to be
-copied from localResults to baseResults
-
-There are some tests borrowed from LunarGLASS.  If LunarGLASS is
-missing, those tests just won't run.
-
-Basic Internal Operation
-------------------------
-
- -  Initial lexical analysis is done by the preprocessor in
-    MachineIndependent/Preprocessor, and then refined by a GLSL scanner
-    in MachineIndependent/Scan.cpp.  There is currently no use of flex.
-
- -  Code is parsed using bison on MachineIndependent/glslang.y with the 
-    aid of a symbol table and an AST.  The symbol table is not passed on to
-    the back-end; the intermediate representation stands on its own.
-    The tree is built by the grammar productions, many of which are 
-    offloaded into ParseHelper.cpp, and by Intermediate.cpp.
-
- -  The intermediate representation is very high-level, and represented
-    as an in-memory tree.   This serves to lose no information from the
-    original program, and to have efficient transfer of the result from
-    parsing to the back-end.  In the AST, constants are propogated and 
-    folded, and a very small amount of dead code is eliminated.
-
-    To aid linking and reflection, the last top-level branch in the AST 
-    lists all global symbols.
-
- -  The primary algorithm of the back-end compiler is to traverse the 
-    tree (high-level intermediate representation), and create an internal
-    object code representation.  There is an example of how to do this
-    in MachineIndependent/intermOut.cpp.
-
- -  Reduction of the tree to a linear byte-code style low-level intermediate
-    representation is likely a good way to generate fully optimized code.
-
- -  There is currently some dead old-style linker-type code still lying around.
-
- - Memory pool: parsing uses types derived from C++ std types, using a 
-   custom allocator that puts them in a memory pool.  This makes allocation
-   of individual container/contents just few cycles and deallocation free.
-   This pool is popped after the AST is made and processed.
-
-   The use is simple: if you are going to call "new", there are three cases:
-
-    - the object comes from the pool (its base class has the macro
-      POOL_ALLOCATOR_NEW_DELETE in it) and you do not have to call delete
-
-    - it is a TString, in which case call NewPoolTString(), which gets 
-      it from the pool, and there is no corresponding delete
-
-    - the object does not come from the pool, and you have to do normal
-      C++ memory management of what you 'new'