Merge pull request #1524 from ericvergnaud/improve-javascript-doc

Update npm related docs

doc/ace-javascript-target.md

@@ -174,13 +174,20 @@ At this point, you should have an editor which displays an error icon next to th
 
 What remains to be done is have our validate function actually validate the input. Finally ANTLR comes in the picture!
 
-To start with, let's load ANTLR and your parser, listener etc.. Easy, since you could write:
+To start with, let's load ANTLR and your parser, listener etc.. 
+
+The preferred approach for loading parser code is to bundle your parser, [as described here](javascript-target.md).
+You can then load it as part of the importScripts instruction at the start of your worker code.
+
+Another approach is to load it using 'require'. Easy, since you could write:
 
 ```js
 var antlr4 = require('antlr4/index');
 ```
 
-This may work, but it's actually unreliable. The reason is that the require function used by ANTLR, which exactly mimics the NodeJS require function, uses a different syntax than the require function that comes with ACE. So we need to bring in a require function that conforms to the NodeJS syntax. I personally use one that comes from Torben Haase's Honey project, which you can find here. But hey, now we're going to have 2 'require' functions not compatible with each other! Indeed, this is why you need to take special care, as follows:
+This may work, but it's actually unreliable. The reason is that the 'require' function that comes with ACE uses a different syntax than the 'require' function used by ANTLR, which follows the NodeJS 'require' convention. 
+So we need to bring in a NodeJS compatible 'require' function that conforms to the NodeJS syntax. I personally use one that comes from Torben Haase's Honey project, which you can find in li/require.js. 
+But hey, now we're going to have 2 'require' functions not compatible with each other! Indeed, this is why you need to take special care, as follows:
 
 ```js
 // load nodejs compatible require
@@ -191,7 +198,8 @@ importScripts("../lib/require.js");
 var antlr4_require = require;
 require = ace_require;
 ```
-Now it's safe to load antlr, and the parsers generated for your language. Assuming that your language files (generated or hand-built) are in a folder with an index.js file that calls require for each file, your parser loading code can be as simple as follows:
+Now it's safe to load antlr and the parsers generated for your language. 
+Assuming that your language files (generated or hand-built) are in a folder with an index.js file that calls require for each file, your parser loading code can be as simple as follows:
 ```js
 // load antlr4 and myLanguage
 var antlr4, mylanguage;
@@ -204,6 +212,7 @@ try {
 }
 ```
 Please note the try-finally construct. ANTLR uses 'require' synchronously so it's perfectly safe to ignore the ACE 'require' while running ANTLR code. ACE itself does not guarantee synchronous execution, so you are much safer always switching 'require' back to 'ace_require'.
+
 Now detecting deep syntax errors in your code is a task for your ANTLR listener or visitor or whatever piece of code you've delegated this to. We're not going to describe this here, since it would require some knowledge of your language. However, detecting grammar syntax errors is something ANTLR does beautifully (isn't that why you went for ANTLR in the first place?). So what we will illustrate here is how to report grammar syntax errors. I have no doubt that from there, you will be able to extend the validator to suit your specific needs.
 Whenever ANTLR encounters an unexpected token, it fires an error. By default, the error is routed to an error listener which simply writes to the console.
 What we need to do is replace this listener by our own listener, se we can route errors to the ACE editor. First, let's create such a listener:
@@ -243,5 +252,4 @@ var validate = function(input) {
 };
 ```
 You know what? That's it! You now have an ACE editor that does syntax validation using ANTLR! I hope you find this useful, and simple enough to get started.
-What I did not address here is packaging, not something I'm an expert at. The good news is that it makes development simple, since I don't have to run any compilation process. I just edit my code, reload my editor page, and check how it goes.
-Now wait, hey! How do you debug this? Well, as usual, using Chrome, since neither Firefox or Safari are able to debug worker code. What a shame...
+WNow wait, hey! How do you debug this? Well, as usual, using Chrome, since no other browser is able to debug worker code. What a shame...

doc/javascript-target.md

@@ -15,7 +15,7 @@ The tests were conducted using Selenium. No issue was found, so you should find
 
 ## Is NodeJS supported?
 
-The runtime has also been extensively tested against Node.js 0.10.33. No issue was found.
+The runtime has also been extensively tested against Node.js 0.12.7. No issue was found.
 
 ## How to create a JavaScript lexer or parser?
 
@@ -31,7 +31,9 @@ For a full list of antlr4 tool options, please visit the [tool documentation pag
 
 Once you've generated the lexer and/or parser code, you need to download the runtime.
 
-The JavaScript runtime is available from the ANTLR web site [download section](http://www.antlr.org/download/index.html). The runtime is provided in the form of source code, so no additional installation is required.
+The JavaScript runtime is [available from npm](https://www.npmjs.com/package/antlr4).
+
+If you can't use npm, the JavaScript runtime is also available from the ANTLR web site [download section](http://www.antlr.org/download/index.html). The runtime is provided in the form of source code, so no additional installation is required.
 
 We will not document here how to refer to the runtime from your project, since this would differ a lot depending on your project type and IDE. 
 
@@ -47,11 +49,28 @@ However, it would be a bit of a problem when it comes to get it into a browser.
 <script src='lib/myscript.js'>
 ```
 
-In order to avoid having to do this, and also to have the exact same code for browsers and Node.js, we rely on a script which provides the equivalent of the Node.js 'require' function.
+To avoid having doing this, the preferred approach is to bundle antlr4 with your parser code, using webpack.
 
-This script is provided by Torben Haase, and is NOT part of ANTLR JavaScript runtime, although the runtime heavily relies on it. Please note that syntax for 'require' in NodeJS is different from the one implemented by RequireJS and similar frameworks.  
+You can get [information on webpack here](https://webpack.github.io).
 
-So in short, assuming you have at the root of your web site, both the 'antlr4' directory and a 'lib' directory with 'require.js' inside it, all you need to put in your HTML header is the following:
+The steps to create your parsing code are the following:
+ - generate your lexer, parser, listener and visitor using the antlr tool
+ - write your parse tree handling code by providig your custom listener or visitor, and associated code, using 'require' to load antlr.
+ - create an index.js file with the entry point to your parsing code (or several if required).
+ - test your parsing logic thoroughly using node.js
+ 
+You are now ready to bundle your parsing code as follows:
+ - following webpack specs, create a webpack.config file
+ - in the webpack.config file, exclude node.js only modules using: node: { module: "empty", net: "empty", fs: "empty" }
+ - from the cmd line, nag-vigate to the directory containing webpack.config and type: webpack
+ 
+This will produce a single js file containing all your parsing code. Easy to include in your web pages!
+
+If you can't use webpack, you can use the lib/require.js script which implements the Node.js 'require' function in brwsers.
+
+This script is provided by Torben Haase, and is NOT part of ANTLR JavaScript runtime.   
+
+Assuming you have, at the root of your web site, both the 'antlr4' directory and a 'lib' directory with 'require.js' inside it, all you need to put in your HTML header is the following:
 
 ```xml
 <script src='lib/require.js'>
@@ -62,16 +81,6 @@ So in short, assuming you have at the root of your web site, both the 'antlr4' d
 
 This will load the runtime asynchronously.
 
-## How do I get the runtime in Node.js?
-
-Right now, there is no npm package available, so you need to register a link instead. This can be done by running the following command from the antlr4 directory:
-
-```bash
-$ npm link antlr4
-```
-
-This will install antlr4 using the package.json descriptor that comes with the script.
- 
 ## How do I run the generated lexer and/or parser?
 
 Let's suppose that your grammar is named, as above, "MyGrammar". Let's suppose this parser comprises a rule named "StartRule". The tool will have generated for you the following files:

runtime/JavaScript/src/antlr4/package.json

@@ -1,6 +1,6 @@
 {
   "name": "antlr4",
-  "version": "4.6",
+  "version": "4.6.0",
   "description": "JavaScript runtime for ANTLR4",
   "main": "src/antlr4/index.js",
   "repository": "antlr/antlr4.git",

runtime/JavaScript/src/npm.txt

@@ -0,0 +1,12 @@
+publishing to npm
+=================
+The JavaScript runtime is published on npm.
+There is nothing to build since JavaScript is based on source code only.
+The JavaScript itself is tested using npm, so assumption is npm is already installed.
+The current npm version used is 3.10.9.
+The publishing itself relies on the information in src/antlr4/package.json.
+To publish, from Terminal, you need to navigate to the src/ directory.
+Once there, login: npm login
+Then npm publish antlr4
+That's it!
+