Skip to content

Commit 60057b2

Browse files
bobzhangbobzhang
committed
more docs
1 parent 68107ea commit 60057b2

File tree

2 files changed

+99
-73
lines changed

2 files changed

+99
-73
lines changed

‎docs/Manual.html

Lines changed: 68 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -669,7 +669,7 @@ <h2 id="_why_bucklescript"><a class="anchor" href="#_why_bucklescript"></a>Why B
669669
<div class="sect2">
670670
<h3 id="_benefits_of_javascript_platform"><a class="anchor" href="#_benefits_of_javascript_platform"></a>Benefits of JavaScript platform</h3>
671671
<div class="paragraph">
672-
<p>JavaScript is not just <strong>the</strong> browser language, it&#8217;s also the <strong>only</strong>
672+
<p>JavaScript is not just <em>the</em> browser language, it&#8217;s also the <em>only</em>
673673
existing cross platform language. It is truly everywhere: users don&#8217;t
674674
need to install binaries or use package managers to access software,
675675
just a link will work.</p>
@@ -683,32 +683,34 @@ <h3 id="_benefits_of_javascript_platform"><a class="anchor" href="#_benefits_of_
683683
<div class="sect2">
684684
<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>
685685
<div class="paragraph">
686-
<p>BuckleScript is mainly designed to solve the problems of <strong>large scale JavaScript programming</strong>:</p>
686+
<p>BuckleScript is mainly designed to solve the problems of <em>large scale</em> JavaScript programming:</p>
687687
</div>
688-
<div class="olist arabic">
689-
<ol class="arabic">
690-
<li>
691-
<p>Lack of type-safety:
692-
<a href="https://ocaml.org/">OCaml</a> offers an industrial-strength
693-
state-of-the-art type system and provides type inference (i.e. No
694-
verbose type annotation required), which proves
688+
<div class="dlist">
689+
<dl>
690+
<dt class="hdlist1">Type-safety</dt>
691+
<dd>
692+
<p>OCaml offers an industrial-strength
693+
state-of-the-art type system and provides very strong type inference (i.e. No
694+
verbose type annotation required compared with typescript), which proves
695695
<a href="http://programmers.stackexchange.com/questions/215482/what-are-the-safety-benefits-of-a-type-system">invaluable</a>
696-
in managing large projects.</p>
697-
</li>
698-
<li>
699-
<p>Dead code: A large amount of web-development relies on inclusion of
700-
code dependencies by copying or referencing CDNs (the very thing
701-
that makes JavaScript highly accessible), but this also introduces
702-
a lot of <a href="https://en.wikipedia.org/wiki/Dead_code">dead code</a>. This
703-
impacts performance adversely when the JavaScript VM has to
704-
interpret code that will never be invoked. BuckleScript provides
705-
powerful dead-code elimination at all levels:</p>
696+
in managing large projects. OCaml&#8217;s type system is not just for tooling,
697+
it is a <em>sound</em> type system which means it is guaranteed that there will
698+
be no runtime type errors after type checking.</p>
699+
</dd>
700+
<dt class="hdlist1">High quality dead code elimination</dt>
701+
<dd>
702+
<p>A large amount of web-development relies on inclusion of
703+
code dependencies by copying or referencing CDNs (the very thing
704+
that makes JavaScript highly accessible), but this also introduces
705+
a lot of <a href="https://en.wikipedia.org/wiki/Dead_code">dead code</a>. This
706+
impacts performance adversely when the JavaScript VM has to
707+
interpret code that will never be invoked. BuckleScript provides
708+
powerful dead-code elimination at all levels:</p>
706709
<div class="ulist">
707710
<ul>
708711
<li>
709712
<p>Function and module level elimination is facilitated by the
710-
sophistication of the type-system of OCaml and
711-
purity analysis.</p>
713+
sophistication of the type-system of OCaml and <em>purity analysis</em>.</p>
712714
</li>
713715
<li>
714716
<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
717719
</li>
718720
</ul>
719721
</div>
720-
</li>
721-
<li>
722-
<p>Lack of offline optimizations: JavaScript is a dynamic language, it
722+
</dd>
723+
<dt class="hdlist1">Offline optimizations</dt>
724+
<dd>
725+
<p>JavaScript is a dynamic language, it
723726
takes a performance-hit for the VM to optimize code at runtime.
724727
While some JS engines circumvent the problem to some extent by
725728
<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
728731
BuckleScript, using features of the OCaml type-system and compiler
729732
implementation is able to provide many optimizations during offline
730733
compilation, allowing the runtime code to be extremely fast.</p>
731-
</li>
732-
<li>
733-
<p>Run your programs on all platforms, but run your system <strong>faster</strong>
734+
</dd>
735+
<dt class="hdlist1">JS platform and Native platform</dt>
736+
<dd>
737+
<p>Run your programs on all platforms, but run your system <em>faster</em>
734738
under specific platforms. Javascript is everywhere but it does not
735739
mean we have to run all apps in JS, under several platforms, for
736740
example, server side or iOS/Android native apps, when programs are
737-
written in OCaml, it can also be compiled to native code for <strong>best
738-
performance</strong>.</p>
739-
</li>
740-
</ol>
741+
written in OCaml, it can also be compiled to native code for <em>better
742+
and reliable performance</em>.</p>
743+
</dd>
744+
</dl>
741745
</div>
742746
<div class="paragraph">
743747
<p>While a strong type-system helps in countering these problems, at the
744748
same time we hope to avoid some of the problems faced in using other
745749
offline <a href="https://github.com/jashkenas/coffeescript/wiki/list-of-languages-that-compile-to-js">transpilation systems</a>:</p>
746750
</div>
747-
<div class="ulist">
748-
<ul>
749-
<li>
750-
<p>Slow compilation: OCaml byte-code compilation is known to be fast
751+
<div class="dlist">
752+
<dl>
753+
<dt class="hdlist1">Slow compilation</dt>
754+
<dd>
755+
<p>OCaml byte-code compilation is known to be fast
751756
(one or two orders of magnitude faster than other similar languages:
752757
<a href="http://www.scala-lang.org/">Scala</a> or
753758
<a href="https://www.haskell.org/">Haskell</a>),
754759
BuckleScript shares the same property and compiles even faster
755760
since it saves the link time. See the speeds at work in the
756761
<a href="http://bloomberg.github.io/bucklescript/js-demo/">playground</a>, the native backend is one
757762
order faster than the JS backend.</p>
758-
</li>
759-
<li>
760-
<p>Un-readable JS Code and hard to integrate with existing JS
761-
libraries: When compiling to JavaScript, many systems
762-
generate code, that while syntactically and semantically correct is
763-
not human-readable and very difficult to debug and profile.
764-
Our BuckleScript implementation and the multi-pass compilation strategy of OCaml,
765-
allows us to avoid <a href="https://en.wikipedia.org/wiki/Name_mangling">name-mangling</a>,
766-
and produce JavaScript code that is human-readable and easier to debug and
767-
maintain. More importantly, this makes integration with existing JS
768-
libraries much easier.</p>
769-
</li>
770-
<li>
771-
<p>Loss of code-structure: Many systems generate JavaScript code that is essentially a
772-
<a href="https://en.wikipedia.org/wiki/Big_ball_of_mud">big ball of mud</a>. We try
773-
to keep the original structure of the code by mapping one OCaml module
774-
to one JS module.</p>
775-
</li>
776-
</ul>
763+
</dd>
764+
<dt class="hdlist1">Un-readable JS Code and hard to integrate with existing JS libraries</dt>
765+
<dd>
766+
<p>When compiling to JavaScript, many systems
767+
generate code, that while syntactically and semantically correct is
768+
not human-readable and very difficult to debug and profile.
769+
Our BuckleScript implementation and the multi-pass compilation strategy of OCaml,
770+
allows us to avoid <a href="https://en.wikipedia.org/wiki/Name_mangling">name-mangling</a>,
771+
and produce JavaScript code that is human-readable and easier to debug and
772+
maintain. More importantly, this makes integration with existing JS
773+
libraries <em>much easier</em>.</p>
774+
</dd>
775+
<dt class="hdlist1">Large JS output even for a simple program</dt>
776+
<dd>
777+
<p>In BuckleScript, a <code>Hello world</code> program generates <em>20 bytes</em> JS code
778+
instead of <em>50K bytes</em>. This is due to that BuckleScript has an excellent
779+
integration with JS libs that unlike most JS compilers,
780+
all BuckleScript&#8217;s runtime is written in OCaml itself so that these
781+
runtime libraries are only needed when user actually call it.</p>
782+
</dd>
783+
<dt class="hdlist1">Loss of code-structure</dt>
784+
<dd>
785+
<p>Many systems generate JavaScript code that is essentially a
786+
<a href="https://en.wikipedia.org/wiki/Big_ball_of_mud">big ball of mud</a>. We try
787+
to keep the original structure of the code by mapping one OCaml module
788+
to one JS module.</p>
789+
</dd>
790+
</dl>
777791
</div>
778792
</div>
779793
</div>

‎site/docsource/Why_BuckleScript.adoc

Lines changed: 31 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
### Benefits of JavaScript platform
44

5-
JavaScript is not just *the* browser language, it's also the *only*
5+
JavaScript is not just _the_ browser language, it's also the _only_
66
existing cross platform language. It is truly everywhere: users don't
77
need to install binaries or use package managers to access software,
88
just a link will work.
@@ -13,16 +13,18 @@ increasingly capable of supporting large applications.
1313

1414
### Problems of JavaScript && how BuckleScript solves it
1515

16-
BuckleScript is mainly designed to solve the problems of *large scale JavaScript programming*:
16+
BuckleScript is mainly designed to solve the problems of _large scale_ JavaScript programming:
1717

18-
. Lack of type-safety:
19-
{OCaml}[OCaml] offers an industrial-strength
20-
state-of-the-art type system and provides type inference (i.e. No
21-
verbose type annotation required), which proves
18+
Type-safety:: OCaml offers an industrial-strength
19+
state-of-the-art type system and provides very strong type inference (i.e. No
20+
verbose type annotation required compared with typescript), which proves
2221
http://programmers.stackexchange.com/questions/215482/what-are-the-safety-benefits-of-a-type-system[invaluable]
23-
in managing large projects.
22+
in managing large projects. OCaml's type system is not just for tooling,
23+
it is a _sound_ type system which means it is guaranteed that there will
24+
be no runtime type errors after type checking.
2425

25-
. Dead code: A large amount of web-development relies on inclusion of
26+
High quality dead code elimination::
27+
A large amount of web-development relies on inclusion of
2628
code dependencies by copying or referencing CDNs (the very thing
2729
that makes JavaScript highly accessible), but this also introduces
2830
a lot of https://en.wikipedia.org/wiki/Dead_code[dead code]. This
@@ -31,13 +33,12 @@ BuckleScript is mainly designed to solve the problems of *large scale JavaScript
3133
powerful dead-code elimination at all levels:
3234

3335
- Function and module level elimination is facilitated by the
34-
sophistication of the type-system of OCaml and
35-
purity analysis.
36+
sophistication of the type-system of OCaml and _purity analysis_.
3637
- At the global level BuckleScript generates code ready for
3738
dead-code elimination done by bundling tools such as the
3839
{closure}[Google closure-compiler].
3940

40-
. Lack of offline optimizations: JavaScript is a dynamic language, it
41+
Offline optimizations:: JavaScript is a dynamic language, it
4142
takes a performance-hit for the VM to optimize code at runtime.
4243
While some JS engines circumvent the problem to some extent by
4344
http://v8project.blogspot.com/2015/07/code-caching.html[caching],
@@ -47,18 +48,19 @@ BuckleScript is mainly designed to solve the problems of *large scale JavaScript
4748
implementation is able to provide many optimizations during offline
4849
compilation, allowing the runtime code to be extremely fast.
4950

50-
. Run your programs on all platforms, but run your system *faster*
51+
JS platform and Native platform::
52+
Run your programs on all platforms, but run your system _faster_
5153
under specific platforms. Javascript is everywhere but it does not
5254
mean we have to run all apps in JS, under several platforms, for
5355
example, server side or iOS/Android native apps, when programs are
54-
written in OCaml, it can also be compiled to native code for *best
55-
performance*.
56+
written in OCaml, it can also be compiled to native code for _better
57+
and reliable performance_.
5658

5759
While a strong type-system helps in countering these problems, at the
5860
same time we hope to avoid some of the problems faced in using other
5961
offline {transpile-list}[transpilation systems]:
6062

61-
* Slow compilation: OCaml byte-code compilation is known to be fast
63+
Slow compilation:: OCaml byte-code compilation is known to be fast
6264
(one or two orders of magnitude faster than other similar languages:
6365
http://www.scala-lang.org/[Scala] or
6466
https://www.haskell.org/[Haskell]),
@@ -67,17 +69,27 @@ http://www.scala-lang.org/[Scala] or
6769
{BuckleScript-playground}[playground], the native backend is one
6870
order faster than the JS backend.
6971

70-
* Un-readable JS Code and hard to integrate with existing JS
71-
libraries: When compiling to JavaScript, many systems
72+
Un-readable JS Code and hard to integrate with existing JS libraries::
73+
When compiling to JavaScript, many systems
7274
generate code, that while syntactically and semantically correct is
7375
not human-readable and very difficult to debug and profile.
7476
Our BuckleScript implementation and the multi-pass compilation strategy of OCaml,
7577
allows us to avoid {name-mangling}[name-mangling],
7678
and produce JavaScript code that is human-readable and easier to debug and
7779
maintain. More importantly, this makes integration with existing JS
78-
libraries much easier.
80+
libraries _much easier_.
7981

80-
* Loss of code-structure: Many systems generate JavaScript code that is essentially a
82+
Large JS output even for a simple program::
83+
In BuckleScript, a `Hello world` program generates _20 bytes_ JS code
84+
instead of _50K bytes_. This is due to that BuckleScript has an excellent
85+
integration with JS libs that unlike most JS compilers,
86+
all BuckleScript's runtime is written in OCaml itself so that these
87+
runtime libraries are only needed when user actually call it.
88+
89+
90+
91+
Loss of code-structure::
92+
Many systems generate JavaScript code that is essentially a
8193
https://en.wikipedia.org/wiki/Big_ball_of_mud[big ball of mud]. We try
8294
to keep the original structure of the code by mapping one OCaml module
8395
to one JS module.

0 commit comments

Comments
 (0)