first doc commit

doc/faq/index.md

@@ -2,7 +2,7 @@
 
 This is the main landing page for the ANTLR 4 FAQ. The links below will take you to the appropriate file containing all answers for that subcategory.
 
-*To add to or improve this FAQ, [fork](https://help.github.com/articles/fork-a-repo/) the [antlr/antlr4 repo](https://github.com/antlr/antlr4) then update this `doc/faq/index.md` or file(s) in that directory.  Submit a [pull request](https://help.github.com/articles/creating-a-pull-request/) to get your changes incorporated into the main repository. Do not mix code and FAQ updates in the sample pull request since code updates require signing the contributors.txt certificate of origin.*
+*To add to or improve this FAQ, [fork](https://help.github.com/articles/fork-a-repo/) the [antlr/antlr4 repo](https://github.com/antlr/antlr4) then update this `doc/faq/index.md` or file(s) in that directory.  Submit a [pull request](https://help.github.com/articles/creating-a-pull-request/) to get your changes incorporated into the main repository. Do not mix code and FAQ updates in the sample pull request.* **You must sign the contributors.txt certificate of origin with your pull request if you've not done so before.**
 
 ## Getting Started
 

doc/getting-started.md

@@ -0,0 +1,131 @@
+# Getting Started with ANTLR v4
+
+Hi and welcome to the version 4 release of ANTLR! It's named after the fearless hero of the [Crazy Nasty-Ass Honey Badger](http://www.youtube.com/watch?v=4r7wHMg5Yjg) since ANTLR v4 takes whatever you give it--it just doesn't give a crap! See [Why do we need ANTLR v4?](faq/general.md) and the [preface of the ANTLR v4 book](http://media.pragprog.com/titles/tpantlr2/preface.pdf).
+
+## Installation
+
+ANTLR is really two things: a tool that translates your grammar to a parser/lexer in Java (or other target language) and the runtime needed by the generated parsers/lexers. Even if you are using the ANTLR Intellij plug-in or ANTLRWorks to run the ANTLR tool, the generated code will still need the runtime library. 
+
+The first thing you should do is probably download and install a development tool plug-in. Even if you only use such tools for editing, they are great. Then, follow the instructions below to get the runtime environment available to your system to run generated parsers/lexers.  In what follows, I talk about antlr-4.5-complete.jar, which has the tool and the runtime and any other support libraries (e.g., ANTLR v4 is written in v3).
+
+If you are going to integrate ANTLR into your existing build system using mvn, ant, or want to get ANTLR into your IDE such as eclipse or intellij, see Integrating ANTLR into Development Systems.
+
+### UNIX
+
+0. Install Java (version 1.6 or higher)
+1. Download
+```
+$ cd /usr/local/lib
+$ curl -O http://www.antlr.org/download/antlr-4.5-complete.jar
+```
+Or just download in browser from website:
+    [http://www.antlr.org/download.html](http://www.antlr.org/download.html)
+and put it somewhere rational like `/usr/local/lib`.
+2. Add `antlr-4.5-complete.jar` to your `CLASSPATH`:
+```
+$ export CLASSPATH=".:/usr/local/lib/antlr-4.5-complete.jar:$CLASSPATH"
+```
+It's also a good idea to put this in your `.bash_profile` or whatever your startup script is.
+3. Create aliases for the ANTLR Tool, and `TestRig`.
+```
+$ alias antlr4='java -Xmx500M -cp "/usr/local/lib/antlr-4.5-complete.jar:$CLASSPATH" org.antlr.v4.Tool'
+$ alias grun='java org.antlr.v4.runtime.misc.TestRig'
+```
+
+### WINDOWS
+
+(*Thanks to Graham Wideman*)
+
+0. Install Java (version 1.6 or higher)
+1. Download antlr-4.5-complete.jar (or whatever version) from [http://www.antlr.org/download/](http://www.antlr.org/download/)
+Save to your directory for 3rd party Java libraries, say `C:\Javalib`
+2. Add `antlr-4.5-complete.jar` to CLASSPATH, either:
+  * Permanently: Using System Properties dialog > Environment variables > Create or append to `CLASSPATH` variable
+  * Temporarily, at command line:
+```
+SET CLASSPATH=.;C:\Javalib\antlr-4.5-complete.jar;%CLASSPATH%
+```
+3. Create short convenient commands for the ANTLR Tool, and TestRig, using batch files or doskey commands:
+  * Batch files (in directory in system PATH) antlr4.bat and grun.bat
+```
+java org.antlr.v4.Tool %*
+```
+```
+java org.antlr.v4.runtime.misc.TestRig %*
+```
+  * Or, use doskey commands:
+```
+doskey antlr4=java org.antlr.v4.Tool $*
+doskey grun =java org.antlr.v4.runtime.misc.TestRig $*
+```
+
+### Testing the installation
+
+Either launch org.antlr.v4.Tool directly:
+
+```
+$ java org.antlr.v4.Tool
+ANTLR Parser Generator Version 4.5
+-o ___ specify output directory where all output is generated
+-lib ___ specify location of .tokens files
+...
+```
+
+or use -jar option on java:
+
+```
+$ java -jar /usr/local/lib/antlr-4.5-complete.jar
+ANTLR Parser Generator Version 4.5
+-o ___ specify output directory where all output is generated
+-lib ___ specify location of .tokens files
+...
+```
+
+## A First Example
+
+In a temporary directory, put the following grammar inside file Hello.g4:
+Hello.g4
+
+```
+// Define a grammar called Hello
+grammar Hello;
+r  : 'hello' ID ;         // match keyword hello followed by an identifier
+ID : [a-z]+ ;             // match lower-case identifiers
+WS : [ \t\r\n]+ -> skip ; // skip spaces, tabs, newlines
+```
+
+Then run ANTLR the tool on it:
+
+```
+$ cd /tmp
+$ antlr4 Hello.g4
+$ javac Hello*.java
+```
+
+Now test it:
+
+```
+$ grun Hello r -tree
+hello parrt
+^D
+(r hello parrt)
+(That ^D means EOF on unix; it's ^Z in Windows.) The -tree option prints the parse tree in LISP notation.
+It's nicer to look at parse trees visually.
+$ grun Hello r -gui
+hello parrt
+^D
+```
+
+That pops up a dialog box showing that rule `r` matched keyword `hello` followed by identifier `parrt`.
+
+![](images/hello-parrt.png)
+
+## Book source code
+
+The book has lots and lots of examples that should be useful to. You can download them here for free:
+
+[http://pragprog.com/titles/tpantlr2/source_code](http://pragprog.com/titles/tpantlr2/source_code)
+
+Also, there is a large collection of grammars for v4 at github:
+
+[https://github.com/antlr/grammars-v4](https://github.com/antlr/grammars-v4)

doc/index.md

@@ -1,10 +1,17 @@
 # ANTLR 4 Documentation
 
-Please check Frequently asked questions (FAQ) before asking questions. The main wiki page is also useful.
+Please check [Frequently asked questions (FAQ)](faq/index.md) before asking questions on stackoverflow or antlr-discussion list.
 
-*Copyright © 2012, The Pragmatic Bookshelf.  Pragmatic Bookshelf grants a nonexclusive, irrevocable, royalty-free, worldwide license to reproduce, distribute, prepare derivative works, and otherwise use this contribution as part of the ANTLR project and associated documentation.*
+Notes:
+<ul>
+<li>*To add to or improve this FAQ, [fork](https://help.github.com/articles/fork-a-repo/) the [antlr/antlr4 repo](https://github.com/antlr/antlr4) then update this `doc/index.md` or file(s) in that directory.  Submit a [pull request](https://help.github.com/articles/creating-a-pull-request/) to get your changes incorporated into the main repository. Do not mix code and FAQ updates in the sample pull request.* **You must sign the contributors.txt certificate of origin with your pull request if you've not done so before.**</li>
 
-This text was copied with permission from the [The Definitive ANTLR 4 Reference](http://pragprog.com/book/tpantlr2/the-definitive-antlr-4-reference), though it is being morphed over time as the tool changes.  Links in the documentation refer to various sections of the book but have been redirected to the general book page on the publisher's site. There are two excerpts on the publisher's website that might be useful to you without having to purchase the book: [Let's get Meta](http://media.pragprog.com/titles/tpantlr2/picture.pdf) and [Building a Translator with a Listener](http://media.pragprog.com/titles/tpantlr2/listener.pdf). You should also consider reading the following books (the vid describes the reference book):
+<li>*Copyright © 2012, The Pragmatic Bookshelf.  Pragmatic Bookshelf grants a nonexclusive, irrevocable, royalty-free, worldwide license to reproduce, distribute, prepare derivative works, and otherwise use this contribution as part of the ANTLR project and associated documentation.*</li>
+
+<li>This text was copied with permission from the [The Definitive ANTLR 4 Reference](http://pragprog.com/book/tpantlr2/the-definitive-antlr-4-reference), though it is being morphed over time as the tool changes.</li>
+</ul>
+
+Links in the documentation refer to various sections of the book but have been redirected to the general book page on the publisher's site. There are two excerpts on the publisher's website that might be useful to you without having to purchase the book: [Let's get Meta](http://media.pragprog.com/titles/tpantlr2/picture.pdf) and [Building a Translator with a Listener](http://media.pragprog.com/titles/tpantlr2/listener.pdf). You should also consider reading the following books (the vid describes the reference book):
 
 <a href=""><img src=images/tpantlr2.png width=120></a>
 <a href=""><img src=images/tpdsl.png width=120></a>
@@ -16,36 +23,36 @@ This documentation is a reference and summarizes grammar syntax and the key sema
 
 ## Sections
 
-Getting Started with ANTLR v4
+* [Getting Started with ANTLR v4](getting-started.md)
 
-Grammar Lexicon
+* Grammar Lexicon
 
-Grammar Structure
+* Grammar Structure
 
-Parser Rules
+* Parser Rules
 
-Left-recursive rules
+* Left-recursive rules
 
-Actions and Attributes
+* Actions and Attributes
 
-Lexer Rules
+* Lexer Rules
 
-Wildcard Operator and Nongreedy Subrules
+* Wildcard Operator and Nongreedy Subrules
 
-Parse Tree Listeners
+* Parse Tree Listeners
 
-Parse Tree Matching and XPath
+* Parse Tree Matching and XPath
 
-Semantic Predicates
+* Semantic Predicates
 
-Options
+* Options
 
-ANTLR Tool Command Line Options
+* ANTLR Tool Command Line Options
 
-Runtime Libraries and Code Generation Targets
+* Runtime Libraries and Code Generation Targets
 
-Parser and lexer interpreters
+* Parser and lexer interpreters
 
-Integrating ANTLR into Development Systems
+* Integrating ANTLR into Development Systems
 
-You can also build ANTLR itself.
+* Build ANTLR itself.