Add content

guides/introduction.md

@@ -57,27 +57,78 @@ Books:
 - [Refactoring by Fowler and Beck](https://martinfowler.com/books/refactoring.html)
 - [Clean Code by Martin](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882)
 
-## Elixir Tooling
+## Other Languages
+
+Refactoring libraries written for other languages:
+
+- Python: [python-rope](https://github.com/python-rope/rope)
+- Javascript: [grasp](https://graspjs.com)
+- Rust: [Structural Search and Replace](https://rust-analyzer.github.io/manual.html#structural-search-and-replace)
+- Rust: [ReRast](https://github.com/google/rerast)
+
+Posts, discussions and tools:
+
+- Python: [AST Patching (Hacker News)](https://news.ycombinator.com/item?id=27419237)
+- Javascript: [AST Explorer](https://astexplorer.net/)
+
+## Elixir AST Tooling
+
+**This section is a work in progress!!**
+
+Any elixir code can be represented as a tree of expressions, called an Abstract
+Syntax Tree (AST).  Elixir tools are able to convert code to AST and
+vice-versa.  
+
+There are three categories of tools that parse Elixir source code.  Each
+category generates a different type of AST.
+
+| Tool       | Input       | Output                 | AST Type         |
+|------------|-------------|------------------------|------------------|
+| Compiler   | Source Code | Machine Code           | Basic AST        |
+| Formatter  | Source Code | Formatted Source Code  | Document Algebra |
+| Refactorer | Source Code | Refactored Source Code | Annotated AST    |
+
+Each tool uses different methods to convert between source code and AST.
 
-Rfx builds on a foundation of prior work by the Elixir community:
+**Basic AST**
 
-- [Elixir Macros and Metaprogramming][macros] - Any elixir code you write can
-  be represented as a tree of expressions, called an Abstract Syntax Tree
-  (AST).  Elixir is able to convert code to AST and vice-versa.  Elixir Macros
-  and Metaprogramming give superpowers to extend the language.
+    # Code to Basic AST
+    # TBD 
+    # Basic AST to Code
+    # NA
+
+**Document Algebra**
+
+    # Code to Basic AST
+    # TBD 
+    # Basic AST to Code
+    # TBD
+
+**Annotated AST**
+
+    # Code to Document Algebra
+    # TBD
+    # Document Algebra to Code
+    # TBD
+
+Rfx builds on a history of prior work by the Elixir community:
+
+- [Elixir Macros and Metaprogramming][macros] - Elixir Macros and
+  Metaprogramming work with the Basic AST, and give superpowers to extend the
+  language.
 - [AST Ninja][astn] - AST Ninja is a handy online tool to easily convert Elixir
-  code to AST.
+  code to a Basic AST.
 - [Refactoring Problems][as_talk] - In his [2019 talk][as_talk]
   ([slides][as_slides]), [Arjan Scherpenisse][asgh] gives an excellent AST
   tutorial, and identifies roadblocks to implement Refactoring.  Key problem:
-  the standard Elixir AST does not capture comments.
+  the Basic AST does not capture comments.
 - [Sourceror][sourceror] - As of Elixir 1.13 (and backported to Elixir 1.10),
   [Dorgan][dorgangh] made critical contributions to enable Refactoring.  The
-  first is new functions for the Elixir standard library:
+  first is new generator functions for the Elixir standard library:
   [Code.string_to_quoted_with_comments/2][stqwc] and
-  [Code.quoted_to_algebra/2][qta].  These allow generation of an AST which
-  preserves comments.  The second is a new library [Sourceror][sourceror] which
-  provides tooling to manipulate the AST-with-comments.  
+  [Code.quoted_to_algebra/2][qta].  These allow generation of an Annotated AST
+  which preserves comments.  The second is a new library [Sourceror][sourceror]
+  which provides tooling to manipulate the Annotated AST.
 
 [macros]: https://www.google.com/search?q=elixir+macros+metaprogramming&oq=elixir+macros+metaprogramming&aqs=chrome.0.69i59j69i64j69i60.6516j0j1&sourceid=chrome&ie=UTF-8
 [astn]: http://ast.ninja
@@ -89,17 +140,5 @@ Rfx builds on a foundation of prior work by the Elixir community:
 [stqwc]: https://hexdocs.pm/elixir/master/Code.html#quoted_to_algebra/2
 [qta]: https://hexdocs.pm/elixir/master/Code.html#string_to_quoted_with_comments/2
 
-## Other Languages
-
-Refactoring libraries written for other languages:
-
-- Python: [python-rope](https://github.com/python-rope/rope)
-- Javascript: [grasp](https://graspjs.com)
-- Rust: [Structural Search and Replace](https://rust-analyzer.github.io/manual.html#structural-search-and-replace)
-- Rust: [ReRast](https://github.com/google/rerast)
 
-Posts, discussions and tools:
-
-- Python: [AST Patching (Hacker News)](https://news.ycombinator.com/item?id=27419237)
-- Javascript: [AST Explorer](https://astexplorer.net/)