Merge pull request #683 from bloomberg/tweak

more docs and fix a wrong error check for bs.pipe.send

Author: bobzhang

.gitattributes

@@ -3,4 +3,5 @@ jscomp/bin/compiler.ml binary
 jscomp/bin/reason.ml binary
 jscomp/bin/bs_ppx.ml binary
 docs/js-demo/exports.js binary
-docs/reason-demo/exports.js binary
+docs/reason-demo/exports.js binary
+docs/Manual.html binary

.travis.yml

@@ -2,9 +2,12 @@ language: node_js
 env:
   - BS_TRAVIS_CI=1
 node_js:
-  - 6
   - 4
 
+#
+# - 6
+# This delays notification
+
 # Not a very reliable service..  
 # script: npm run coveralls
 

README.md

@@ -18,25 +18,10 @@ If you need help or have a question, comment, or suggestion, please feel free to
 issue](https://github.com/bloomberg/bucklescript/issues).
 
 ## Installing BuckleScript
-
-#### Prerequisites
-
-* Standard C toolchain
-* `npm` (should be installed with Node)
-
-#### Installing the Release Package
-
 ```
 npm install bs-platform
 ```
-
-#### Installing from Source
-
-```
-git clone https://github.com/bloomberg/bucklescript
-cd bucklescript
-npm install
-```
+For more advanced settings, please visit [Installation](./site/docsource/Installation.adoc)
 
 The BuckleScript installation includes the following:
 
@@ -47,13 +32,10 @@ The BuckleScript installation includes the following:
 Installing BuckleScript from the npm package places binaries in `./node_modules/.bin`. Installing
 from the git repository places them in `./bin`.
 
-## Manually Building BuckleScript
 
-See [Developing BuckleScript](./site/docsource/Developing-bucklescript.md) for detailed instructions on manually building BuckleScript.
+## Documentation
 
-## Detailed Documentation
-
-See http://bloomberg.github.io/bucklescript for detailed documentation on BuckleScript. If you'd
+See http://bloomberg.github.io/bucklescript/Manual.html for detailed documentation on BuckleScript. If you'd
 like to contribute content [see here](https://github.com/bloomberg/bucklescript/blob/master/site/docsource)
 for the documentation source.
 
@@ -193,10 +175,6 @@ function test() {
 test();
 ```
 
-## Release Status
-
-BuckleScript has not reached a stable release. However, it is already quite usable and we
-encourage you to try it out and let us know what you think.
 
 ## Licensing
 

docs/Manual.html

@@ -502,7 +502,7 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
 <ul class="sectlevel2">
 <li><a href="#_install_from_npm_registries">Install from NPM registries</a></li>
 <li><a href="#_install_from_source_with_npm_package_manager">Install from source with npm package manager</a></li>
-<li><a href="#_install_with_minimal_dependencies">Install with minimal dependencies</a></li>
+<li><a href="#_install_with_em_minimal_em_dependencies">Install with <em>minimal</em> dependencies</a></li>
 <li><a href="#_introduction_to_ocaml_ecosystem_opam">Introduction to OCaml ecosystem: OPAM</a></li>
 </ul>
 </li>
@@ -571,7 +571,7 @@ <h1><a href="https://github.com/bloomberg/bucklescript">BuckleScript</a> User Ma
 <li><a href="#_debugger_support">Debugger support</a></li>
 <li><a href="#_regex_support">Regex support</a></li>
 <li><a href="#_examples_2">Examples</a>
-<ul class="sectlevel4">
+<ul class="sectlevel3">
 <li><a href="#_a_simple_example_binding_to_mocha_unit_test_library">A simple example: binding to mocha unit test library</a></li>
 </ul>
 </li>
@@ -669,7 +669,7 @@ <h2 id="_why_bucklescript"><a class="anchor" href="#_why_bucklescript"></a>Why B
 <div class="sect2">
 <h3 id="_benefits_of_javascript_platform"><a class="anchor" href="#_benefits_of_javascript_platform"></a>Benefits of JavaScript platform</h3>
 <div class="paragraph">
-<p>JavaScript is not just <strong>the</strong> browser language, it&#8217;s also the <strong>only</strong>
+<p>JavaScript is not just <em>the</em> browser language, it&#8217;s also the <em>only</em>
 existing cross platform language. It is truly everywhere: users don&#8217;t
 need to install binaries or use package managers to access software,
 just a link will work.</p>
@@ -683,32 +683,34 @@ <h3 id="_benefits_of_javascript_platform"><a class="anchor" href="#_benefits_of_
 <div class="sect2">
 <h3 id="_problems_of_javascript_how_bucklescript_solves_it"><a class="anchor" href="#_problems_of_javascript_how_bucklescript_solves_it"></a>Problems of JavaScript &amp;&amp; how BuckleScript solves it</h3>
 <div class="paragraph">
-<p>BuckleScript is mainly designed to solve the problems of <strong>large scale JavaScript programming</strong>:</p>
+<p>BuckleScript is mainly designed to solve the problems of <em>large scale</em> JavaScript programming:</p>
 </div>
-<div class="olist arabic">
-<ol class="arabic">
-<li>
-<p>Lack of type-safety:
-<a href="https://ocaml.org/">OCaml</a> offers an industrial-strength
-state-of-the-art type system and provides type inference (i.e. No
-verbose type annotation required), which proves
+<div class="dlist">
+<dl>
+<dt class="hdlist1">Type-safety</dt>
+<dd>
+<p>OCaml offers an industrial-strength
+state-of-the-art type system and provides very strong type inference (i.e. No
+verbose type annotation required compared with typescript), which proves
 <a href="http://programmers.stackexchange.com/questions/215482/what-are-the-safety-benefits-of-a-type-system">invaluable</a>
-in managing large projects.</p>
-</li>
-<li>
-<p>Dead code: A large amount of web-development relies on inclusion of
-code dependencies by copying or referencing CDNs (the very thing
-that makes JavaScript highly accessible), but this also introduces
-a lot of <a href="https://en.wikipedia.org/wiki/Dead_code">dead code</a>. This
-impacts performance adversely when the JavaScript VM has to
-interpret code that will never be invoked. BuckleScript provides
-powerful dead-code elimination at all levels:</p>
+in managing large projects. OCaml&#8217;s type system is not just for tooling,
+it is a <em>sound</em> type system which means it is guaranteed that there will
+be no runtime type errors after type checking.</p>
+</dd>
+<dt class="hdlist1">High quality dead code elimination</dt>
+<dd>
+<p>A large amount of web-development relies on inclusion of
+  code dependencies by copying or referencing CDNs (the very thing
+  that makes JavaScript highly accessible), but this also introduces
+  a lot of <a href="https://en.wikipedia.org/wiki/Dead_code">dead code</a>. This
+  impacts performance adversely when the JavaScript VM has to
+  interpret code that will never be invoked. BuckleScript provides
+  powerful dead-code elimination at all levels:</p>
 <div class="ulist">
 <ul>
 <li>
 <p>Function and module level elimination is facilitated by the
-sophistication of the type-system of OCaml and
-purity analysis.</p>
+sophistication of the type-system of OCaml and <em>purity analysis</em>.</p>
 </li>
 <li>
 <p>At the global level BuckleScript generates code ready for
@@ -717,9 +719,10 @@ <h3 id="_problems_of_javascript_how_bucklescript_solves_it"><a class="anchor" hr
 </li>
 </ul>
 </div>
-</li>
-<li>
-<p>Lack of offline optimizations: JavaScript is a dynamic language, it
+</dd>
+<dt class="hdlist1">Offline optimizations</dt>
+<dd>
+<p>JavaScript is a dynamic language, it
 takes a performance-hit for the VM to optimize code at runtime.
 While some JS engines circumvent the problem to some extent by
 <a href="http://v8project.blogspot.com/2015/07/code-caching.html">caching</a>,
@@ -728,52 +731,63 @@ <h3 id="_problems_of_javascript_how_bucklescript_solves_it"><a class="anchor" hr
 BuckleScript, using features of the OCaml type-system and compiler
 implementation is able to provide many optimizations during offline
 compilation, allowing the runtime code to be extremely fast.</p>
-</li>
-<li>
-<p>Run your programs on all platforms, but run your system <strong>faster</strong>
+</dd>
+<dt class="hdlist1">JS platform and Native platform</dt>
+<dd>
+<p>Run your programs on all platforms, but run your system <em>faster</em>
 under specific platforms. Javascript is everywhere but it does not
 mean we have to run all apps in JS, under several platforms, for
 example, server side or iOS/Android native apps, when programs are
-written in OCaml, it can also be compiled to native code for <strong>best
-performance</strong>.</p>
-</li>
-</ol>
+written in OCaml, it can also be compiled to native code for <em>better
+and reliable performance</em>.</p>
+</dd>
+</dl>
 </div>
 <div class="paragraph">
 <p>While a strong type-system helps in countering these problems, at the
 same time we hope to avoid some of the problems faced in using other
 offline <a href="https://github.com/jashkenas/coffeescript/wiki/list-of-languages-that-compile-to-js">transpilation systems</a>:</p>
 </div>
-<div class="ulist">
-<ul>
-<li>
-<p>Slow compilation: OCaml byte-code compilation is known to be fast
+<div class="dlist">
+<dl>
+<dt class="hdlist1">Slow compilation</dt>
+<dd>
+<p>OCaml byte-code compilation is known to be fast
   (one or two orders of magnitude faster than other similar languages:
 <a href="http://www.scala-lang.org/">Scala</a> or
   <a href="https://www.haskell.org/">Haskell</a>),
   BuckleScript shares the same property and compiles even faster
   since it saves the link time. See the speeds at work in the
   <a href="http://bloomberg.github.io/bucklescript/js-demo/">playground</a>, the native backend is one
   order faster than the JS backend.</p>
-</li>
-<li>
-<p>Un-readable JS Code and hard to integrate with existing JS
-libraries: When compiling to JavaScript, many systems
-generate code, that while syntactically and semantically correct is
-not human-readable and very difficult to debug and profile.
-Our BuckleScript implementation and the multi-pass compilation  strategy of OCaml,
-allows us to avoid <a href="https://en.wikipedia.org/wiki/Name_mangling">name-mangling</a>,
-and produce JavaScript code that is human-readable and easier to debug and
-maintain. More importantly, this makes integration with existing JS
-libraries much easier.</p>
-</li>
-<li>
-<p>Loss of code-structure: Many systems generate JavaScript code that is essentially a
-<a href="https://en.wikipedia.org/wiki/Big_ball_of_mud">big ball of mud</a>. We try
-to keep the original structure of the code by mapping one OCaml module
-to one JS module.</p>
-</li>
-</ul>
+</dd>
+<dt class="hdlist1">Un-readable JS Code and hard to integrate with existing JS  libraries</dt>
+<dd>
+<p>When compiling to JavaScript, many systems
+  generate code, that while syntactically and semantically correct is
+  not human-readable and very difficult to debug and profile.
+  Our BuckleScript implementation and the multi-pass compilation  strategy of OCaml,
+  allows us to avoid <a href="https://en.wikipedia.org/wiki/Name_mangling">name-mangling</a>,
+  and produce JavaScript code that is human-readable and easier to debug and
+  maintain. More importantly, this makes integration with existing JS
+  libraries <em>much easier</em>.</p>
+</dd>
+<dt class="hdlist1">Large JS output even for a simple program</dt>
+<dd>
+<p>In BuckleScript, a <code>Hello world</code> program generates <em>20 bytes</em> JS code
+instead of <em>50K bytes</em>. This is due to that BuckleScript has an excellent
+integration with JS libs that unlike most JS compilers,
+all BuckleScript&#8217;s runtime is written in OCaml itself so that these
+runtime libraries are only needed when user actually call it.</p>
+</dd>
+<dt class="hdlist1">Loss of code-structure</dt>
+<dd>
+<p>Many systems generate JavaScript code that is essentially a
+ <a href="https://en.wikipedia.org/wiki/Big_ball_of_mud">big ball of mud</a>. We try
+ to keep the original structure of the code by mapping one OCaml module
+ to one JS module.</p>
+</dd>
+</dl>
 </div>
 </div>
 </div>
@@ -783,6 +797,17 @@ <h2 id="_installation"><a class="anchor" href="#_installation"></a>Installation<
 <div class="sectionbody">
 <div class="sect2">
 <h3 id="_install_from_npm_registries"><a class="anchor" href="#_install_from_npm_registries"></a>Install from NPM registries</h3>
+<div class="ulist">
+<div class="title">Prerequisites</div>
+<ul>
+<li>
+<p>Standard C toolchain</p>
+</li>
+<li>
+<p><code>npm</code> (should be installed with Node)</p>
+</li>
+</ul>
+</div>
 <div class="paragraph">
 <p>The standard <code>npm</code> package management tool can be used to install
 BuckleScript. If you don&#8217;t already have <code>npm</code> installed, follow the
@@ -827,7 +852,7 @@ <h3 id="_install_from_source_with_npm_package_manager"><a class="anchor" href="#
 </div>
 </div>
 <div class="sect2">
-<h3 id="_install_with_minimal_dependencies"><a class="anchor" href="#_install_with_minimal_dependencies"></a>Install with minimal dependencies</h3>
+<h3 id="_install_with_em_minimal_em_dependencies"><a class="anchor" href="#_install_with_em_minimal_em_dependencies"></a>Install with <em>minimal</em> dependencies</h3>
 <div class="olist arabic">
 <div class="title">Prerequisites:</div>
 <ol class="arabic">
@@ -844,7 +869,7 @@ <h3 id="_install_with_minimal_dependencies"><a class="anchor" href="#_install_wi
 <div class="title">Build OCaml compiler</div>
 <div class="content">
 <pre class="pygments highlight"><code data-lang="sh">git clone --recursive https://github.com/bloomberg/bucklescript
-<span class="tok-nb">cd </span>ocaml
+<span class="tok-nb">cd </span>bucklescript/ocaml
 ./configure -prefix <span class="tok-sb">`</span><span class="tok-nb">pwd</span><span class="tok-sb">`</span> <span class="tok-c"># put your preferred directory</span>
 make world.opt
 make install</code></pre>
@@ -2621,7 +2646,7 @@ <h3 id="_regex_support"><a class="anchor" href="#_regex_support"></a>Regex suppo
 </div>
 </div>
 <div class="paragraph">
-<p>The compiler will infer <code>f</code> has type <code>Js_re.t</code> and generate code as
+<p>The compiler will infer <code>f</code> has type <code>Js.Re.t</code> and generate code as
 below</p>
 </div>
 <div class="listingblock">
@@ -2636,7 +2661,7 @@ <h3 id="_regex_support"><a class="anchor" href="#_regex_support"></a>Regex suppo
 <div class="title">Note</div>
 </td>
 <td class="content">
-<code>Js_re.t</code> is an abstract type, we are working on providing
+<code>Js.Re.t</code> is an abstract type, we are working on providing
 bindings for it.
 </td>
 </tr>
@@ -2650,8 +2675,8 @@ <h3 id="_examples_2"><a class="anchor" href="#_examples_2"></a>Examples</h3>
 more examples, please visit
 <a href="https://github.com/bloomberg/bucklescript-addons" class="bare">https://github.com/bloomberg/bucklescript-addons</a></p>
 </div>
-<div class="sect4">
-<h5 id="_a_simple_example_binding_to_mocha_unit_test_library"><a class="anchor" href="#_a_simple_example_binding_to_mocha_unit_test_library"></a>A simple example: binding to mocha unit test library</h5>
+<div class="sect3">
+<h4 id="_a_simple_example_binding_to_mocha_unit_test_library"><a class="anchor" href="#_a_simple_example_binding_to_mocha_unit_test_library"></a>A simple example: binding to mocha unit test library</h4>
 <div class="paragraph">
 <p>This is an example showing how too provide bindings to the
 <a href="https://mochajs.org/">mochajs</a> unit test framework.</p>

docs/js-demo/examples/default.ml

@@ -1,3 +1,3 @@
 
-Js.log "Hello BuckleScript!"
+print_endline "Hello BuckleScript!"
 

docs/js-demo/index.html

@@ -92,7 +92,7 @@ <h3>JavaScript</h2>
 
     <div class = "right-border" style="width: 50%;float:left">
         <textarea id="ocamlcode#1">
-Js.log "Hello BuckleScript!"
+print_endline "Hello BuckleScript!"
         </textarea>
     </div>
     <div style="width: 50%; float:right">

jscomp/Makefile

@@ -119,8 +119,8 @@ travis-world-test:./bin/bspack
 # since in npm mode, they are generated from a single file
 install:
 	cp  ./bin/bsc ./bin/bsppx  ./bin/bspack ../bin/
-	cp ./runtime/*.cmt* ./runtime/*.cmj* ./stdlib/*.cm*   ./others/*.cm* ../lib/ocaml/
-	cp ./runtime/js.ml  ./runtime/js.cmi ./runtime/js_array.mli ./runtime/js_array.ml ./runtime/js_array.cmi  ./runtime/js_string.ml ./runtime/js_string.mli ./runtime/js_string.cmi ./runtime/js_re.ml ./runtime/js_re.mli ./runtime/js_re.cmi ./runtime/js_unsafe.cmi ../lib/ocaml/	
+	cp ./runtime/*.cmt* ./runtime/*.cmj* ./stdlib/*.cm* ./others/*.ml ./others/*.mli  ./others/*.cm* ../lib/ocaml/
+	cp ./runtime/js.ml  ./runtime/js.cmi ./runtime/js_unsafe.cmi ../lib/ocaml/	
 
 
 

jscomp/js.sh

@@ -8,7 +8,7 @@ FILE=bin/reason.byte
 ocamlbuild -lflags -no-check-prims -use-ocamlfind -I bin -no-hygiene   -pkgs compiler-libs.common -no-links $FILE
 
 # jsoo_mkcmis stdlib
-js_of_ocaml -I +compiler-libs   --toplevel +weak.js +toplevel.js  ./polyfill.js _build/$FILE -I ./runtime/ --file js.cmi:/cmis/js.cmi --file js_unsafe.cmi:/cmis/js_unsafe.cmi --file js_re.cmi:/cmis/js_re.cmi   -o _build/exports.js 
+js_of_ocaml -I +compiler-libs   --toplevel +weak.js +toplevel.js  ./polyfill.js _build/$FILE -I ./others/ -I ./runtime/ --file js.cmi:/cmis/js.cmi --file js_unsafe.cmi:/cmis/js_unsafe.cmi --file js_re.cmi:/cmis/js_re.cmi   -o _build/exports.js 
 
 DOCS_DIR=../docs/js-demo
 

jscomp/others/.depend

@@ -6,8 +6,15 @@ bs_node_process.cmj :
 bs_node_process.cmx :
 bs_dict.cmj :
 bs_dict.cmx :
-bs_node_module.cmj : bs_node.cmi bs_dict.cmj
-bs_node_module.cmx : bs_node.cmi bs_dict.cmx
+bs_node_module.cmj : bs_node.cmj bs_dict.cmj
+bs_node_module.cmx : bs_node.cmx bs_dict.cmx
+js_array.cmj :
+js_array.cmx :
+js_string.cmj : js_re.cmi
+js_string.cmx : js_re.cmx
+js_re.cmj : js_re.cmi
+js_re.cmx : js_re.cmi
+js_re.cmi :
 bs_node_path.cmo :
 bs_node_path.cmj :
 bs_node_fs.cmo :
@@ -16,5 +23,11 @@ bs_node_process.cmo :
 bs_node_process.cmj :
 bs_dict.cmo :
 bs_dict.cmj :
-bs_node_module.cmo : bs_node.cmi bs_dict.cmo
-bs_node_module.cmj : bs_node.cmi bs_dict.cmj
+bs_node_module.cmo : bs_node.cmo bs_dict.cmo
+bs_node_module.cmj : bs_node.cmj bs_dict.cmj
+js_array.cmo :
+js_array.cmj :
+js_string.cmo : js_re.cmi
+js_string.cmj : js_re.cmj
+js_re.cmo : js_re.cmi
+js_re.cmj : js_re.cmi