Merge branch 'develop' into test_merge

.jsdoc.json

@@ -0,0 +1,9 @@
+{
+  "source": {
+    "exclude": ["src/common/api.js", "src/semantic_tree/semantic_api.js"],
+    "excludePattern": "externs.js"
+  },
+  "tags": {
+    "dictionaries": ["closure", "jsdoc"]
+  }
+}

Makefile

@@ -39,6 +39,12 @@ TEST_DEPS = $(TEST_DIR)/deps.js
 TEST = $(BIN_DIR)/test_sre
 TEST_SRC = $(TEST_DIR)/*.js
 
+JSDOC = $(NODE_MODULES)/.bin/jsdoc
+JSDOC_FLAGS = -c $(PREFIX)/.jsdoc.json
+DOCS = $(PREFIX)/docs
+DOCS_SRC = $(DOCS)/src
+DOCS_TESTS = $(DOCS)/tests
+
 ##################################################################
 # Error flags.
 # Compiling as rigidly as possible.
@@ -250,3 +256,10 @@ clean_enrich:
 
 emacs: publish
 	@cp $(TARGET) ../emacs-math-speak/
+
+docs: $(JSDOC)
+	@$(JSDOC) $(JSDOC_FLAGS) $(SRC) -r -d $(DOCS_SRC)
+	@$(JSDOC) $(JSDOC_FLAGS) $(TEST_DIR) -r -d $(DOCS_TESTS)
+
+clean_docs:
+	rm -rf $(DOCS)

NOTICE

@@ -7,3 +7,6 @@ ChromeVox (http://www.chromevox.com/) at Google Inc. (http://google.com/).
 
 The browser version depends on the wicked good XPath library wgxpath
 (https://github.com/google/wicked-good-xpath) to run in IE and Edge.
+
+The node version also depends on wicked good XPath
+(https://www.npmjs.com/package/wicked-good-xpath).

README.md

@@ -6,8 +6,7 @@ Speech Rule Engine
 NodeJS version of the ChromeVox speech rule engine.
 Forked from ChromeVox release 1.31.0
 
-Speech rule engine (SRE) is 
-The speech rule engine can translate XML expressions into speech strings according to rules that
+Speech rule engine (SRE) can translate XML expressions into speech strings according to rules that
 can be specified in a syntax using Xpath expressions.  It was originally designed for translation
 of MathML and MathJax DOM elements for the ChromeVox screen reader. 
 Besides the rules originally designed for the use in ChromeVox, it also has an implemententation of the 
@@ -24,7 +23,7 @@ it in your project.
 if you want to use the speech rule engine in batch mode or interactivley to add
 your own code. Or simply run it with ```npx```, for example to get all SRE options anywhere without local installation run:
 
-    ```npx -p speech-rule-engine sre -h```
+    ```npx speech-rule-engine -h```
 
 3. **Browser Library:** This gives you the option of loading SRE in a browser and
    use its full functionality on your webesites.
@@ -57,7 +56,7 @@ Current API functions are divided into three categories.
 
 **Note that in asynchronous operation mode for these methods to work correctly,
 it is necessary to ensure that the Engine is ready for processing. See the
-isReady flag below.**
+engineReady flag below.**
 
 #### Methods that take an input filename and optionally an output filename: 
 
@@ -84,6 +83,7 @@ Most common options are:
 | ---- | ---- |
 | *domain* | Domain or subject area of speech rules (e.g., mathspeak, emacspeak).|
 | *style* | Style of speech rules (e.g., brief).|
+| *locale* | Language locale in 639-1. Currently available: en, es |
 | *markup*| Set the markup: ```none```, ```ssml```, ```sable```, ```voicexml```, ```acss``` |
 | *walker* | A walker to use for interactive exploration: ```None```, ```Syntax```, ```Semantic```, ```Table``` |
 | *semantics* | Boolean flag to switch **OFF** semantic interpretation. Non-semantic rule sets are deprecated. |
@@ -123,23 +123,23 @@ exposed via the command line interface.
 | ---- | ---- |
 | `pprintXML(string)` | Returns pretty printed version of a serialised XML string. |
 | `version` | Returns SRE's version number. |
-| `isReady()` | Returns flag indicating that the engine is ready for procssing (i.e., all necessary rule files have been loaded, the engine is done updating, etc.). **This is important in asynchronous settings.** |
+| `engineReady()` | Returns flag indicating that the engine is ready for procssing (i.e., all necessary rule files have been loaded, the engine is done updating, etc.). **This is important in asynchronous settings.** |
 
 Standalone Tool
 ---------------
 
-Node dependencies you have to install:
+Install dependencies either by running:
+
+     npm install
+     
+Or install them manually. SRE depends on the following libraries:
 
      google-closure-compiler
      google-closure-library
-     xmldom
-     xpath
+     xmldom-sre
+     wicked-good-xpath
      commander
      xml-mapping
-
-Using npm run
-
-     npm install google-closure-compiler google-closure-library xmldom xpath commander xml-mapping
 
 
 ### Build #############
@@ -157,7 +157,7 @@ This will make both the command line executable and the interactive load script.
 
 As an example run
 
-    bin/sre -i samples/sample1.xml -o sample1.txt
+    bin/sre -i resources/samples/sample1.xml -o sample1.txt
 
 ### Run interactively ############
 
@@ -238,7 +238,7 @@ important API functions are also available in ``SRE``.
 ### Configuration ####
 
 In addition to programmatically configuring SRE using the ``setupEngine``
-method, you can also include a configuration element in a website, that can take
+method, you can also include a configuration element in a website, that can take the same options as ``setupEngine``.
 
 For example the configuration element
 ``` html
@@ -278,19 +278,19 @@ Other make targets useful during development are:
 
     make test
 
-Runs all the tests using the Node's assert module. Output is pretty printed to stdout.
+Runs all the tests using Node's assert module. Output is pretty printed to stdout.
 
     make lint
 
-Runs the closure linter tool. To use this option, you need to install the appropriate node package with
+Runs the closure linter tool. To use this option, you need to install the node package
 
     npm install closure-linter-wrapper
 
 To automatically fix some of linting errors run:
 
     make fixjsstyle
 
-Note, that all JavaScript code in this repository is fully linted and compiles error free with respect to the strictest possible closure compiler settings.
+Note, that all JavaScript code in this repository is fully linted and compiles error free with respect to the strictest possible closure compiler settings, however, not using the ``newCheckTypes`` option.
 
 When creating a pull request, please make sure that your code compiles and is fully linted.
 
@@ -308,3 +308,11 @@ This first builds the package by executing
     make publish
 
 This make command is also useful for local testing of the package.
+
+### Documentation
+
+To generate documentation from the [JSDOC](http://usejsdoc.org/), simply run 
+
+    make docs
+
+This will generate documentation for the source coude and test code in the directories ``docs/src`` and ``docs/tests``, respectively.

index.html

@@ -5,8 +5,8 @@
     <meta http-equiv="X-UA-Compatible" content="chrome=1">
     <title>Speech-rule-engine by zorkow</title>
 
-    <link rel="stylesheet" href="stylesheets/styles.css">
-    <link rel="stylesheet" href="stylesheets/github-light.css">
+    <link rel="stylesheet" href="resources/stylesheets/styles.css">
+    <link rel="stylesheet" href="resources/stylesheets/github-light.css">
     <meta name="viewport" content="width=device-width">
     <!--[if lt IE 9]>
     <script src="//html5shiv.googlecode.com/svn/trunk/html5.js"></script>
@@ -41,8 +41,8 @@ <h3>
         <p>Support for complex equation systems is currently being added in the scope of a
         a <a href="http://diagramcenter.org/">Diagram Center</a> Project.</p>
 
-        <p>Pages for user testing with equation systems can be found <a href="www">here</a></p>
-        <p>Unit tests in English for localisation can be found <a href="www/localisation">here</a></p>
+        <p>Pages for user testing with equation systems can be found <a href="resources/www">here</a></p>
+        <p>Unit tests in English for localisation can be found <a href="resources/www/localisation">here</a></p>
 
       </section>
       <footer>

package.json

@@ -32,14 +32,15 @@
   "homepage": "https://github.com/zorkow/speech-rule-engine",
   "dependencies": {
     "commander": "*",
-    "xmldom": ">=0.1.25",
+    "wicked-good-xpath": "*",
     "xml-mapping": "*",
-    "xpath": "*"
+    "xmldom-sre": "*"
   },
   "devDependencies": {
     "closure-linter-wrapper": ">=1.1.0",
     "google-closure-compiler": ">=20160911.0.0",
-    "google-closure-library": ">=20160822.0.0"
+    "google-closure-library": ">=20160822.0.0",
+    "jsdoc": ">=3.5.5"
   },
   "files": [
     "index.js",

resources/examples/README.md

@@ -0,0 +1,12 @@
+# Visualisation Examples
+
+Contains examples for visualisation of the semantic tree. XML files contain the
+original, JSON files the semantic tree in JSON format. To visualise use the
+[semantic tree visualiser](https://github.com/zorkow/semantic-tree-visualiser).
+Go to the
+[web front end](http://zorkow.github.io/semantic-tree-visualiser/visualise.html)
+and enter for example
+```
+http://rawgit.com/zorkow/speech-rule-engine/gh-pages/resouces/examples/quadratic.json
+```
+and browse the semantic tree for the quadratic equation.