incubator-netbeans-html4j git commit: Adding a readme file

[jt...@apache.org]

Repository: incubator-netbeans-html4j
Updated Branches:
  refs/heads/master 9032affbe -> 926c9a0b6


Adding a readme file


Project: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/commit/926c9a0b
Tree: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/tree/926c9a0b
Diff: http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/diff/926c9a0b

Branch: refs/heads/master
Commit: 926c9a0b6dd62e918dfb17b10a779b7b55bf8cc8
Parents: 9032aff
Author: Jaroslav Tulach <ja...@oracle.com>
Authored: Fri Oct 6 15:10:41 2017 +0200
Committer: Jaroslav Tulach <ja...@oracle.com>
Committed: Fri Oct 6 15:10:41 2017 +0200

----------------------------------------------------------------------
 README.md | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 84 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/incubator-netbeans-html4j/blob/926c9a0b/README.md
----------------------------------------------------------------------
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..9b29791
--- /dev/null
+++ b/README.md
@@ -0,0 +1,84 @@
+== HTML/Java API ==
+
+In need of cross platform, client side interaction between Java and JavaScript?
+The HTML/Java library provides [basic building blocks](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/js/package-summary.html)
+as well as advanced [high level concepts](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/json/Model.html)
+to make communication between JavaScript and Java as smooth as possible.
+
+Read more in the [latest javadoc](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/) documentation.
+
+== Portability ==
+
+Every browser widget Java API offers ways for communication between Java and
+JavaScript running in such widget. However, each of them is unique - e.g. one
+writes different code when communicating with [JavaFX WebView](https://docs.oracle.com/javase/8/javafx/api/javafx/scene/web/WebView.html),
+different one when communicating with [Android WebView](https://developer.android.com/reference/android/webkit/WebView.html),
+yet another one when talking to [iOS WebView](https://developer.apple.com/documentation/uikit/uiwebview).
+
+The goal of HTML/Java API is to **unify this communication**. By providing simple
+and highly portable [building blocks](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/js/package-summary.html)
+one can create sophisticated APIs that can be embedded into
+[Swing or JavaFX applications](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/boot/fx/FXBrowsers.html),
+executed [headlessly on a server](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/net/java/html/boot/script/Scripts.html).
+
+Various ports of this rendering pipeline were built including support for
+pure [webkit desktop rendring](https://github.com/dukescript/dukescript-presenters/),
+[Android WebView](https://dukescript.com/javadoc/presenters/com/dukescript/presenters/Android.html)
+and [iOS WebView](https://dukescript.com/javadoc/presenters/com/dukescript/presenters/iOS.html)
+developed by [DukeScript project](https://dukescript.com/).
+
+This technology has also been adopted by some Java bytecode to JavaScript
+transpilers - for example [Bck2Brwsr VM](https://github.com/jtulach/bck2brwsr/) -
+as such you can also run the same Java application in a pluginless browser.
+
+Porting of HTML/Java rendering pipeline is as easy as implementing
+[Fn.Presenter](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/org/netbeans/html/boot/spi/Fn.Presenter.html)
+interface and passing the [technology compatibility kit](https://builds.apache.org/job/incubator-netbeans-html4j-linux/javadoc/org/netbeans/html/json/tck/package-summary.html).
+
+== Contributing ==
+
+You can contribute to development of this library by forking
+its [GitHub repository](https://github.com/apache/incubator-netbeans-html4j).
+Change, modify, test:
+
+```bash
+$ mvn clean install
+```
+
+and create a pull request, which may then be merged into the
+official [Apache repository](https://git-wip-us.apache.org/repos/asf?p=incubator-netbeans-html4j.git).
+
+=== Full History ===
+
+The origins of the code in this repository are older than
+its Apache existance. As such significant part of the history
+(before the code has been donated to Apache) is kept in an
+independent repository. To fully understand the code you may
+want to merge the modern and ancient versions together:
+
+```bash
+$ git clone https://github.com/apache/incubator-netbeans-html4j.git html+java+both
+$ cd html+java+both
+$ git log boot/src/main/java/net/java/html/boot/BrowserBuilder.java
+```
+
+This gives you just few log entries including the initial checkin and change of the
+file headers to Apache. But then the magic comes:
+
+```bash
+$ git remote add emilian https://github.com/emilianbold/netbeans-html4j.git
+$ git fetch emilian
+$ git replace 408363d d029b8e
+```
+
+When you search the log, or use the blame tool, the full history is
+available:
+
+```bash
+$ git log boot/src/main/java/net/java/html/boot/BrowserBuilder.java
+$ git blame boot/src/main/java/net/java/html/boot/BrowserBuilder.java
+```
+
+Many thanks to Emilian Bold who converted the ancient history to
+[his Git repository](https://github.com/emilianbold/netbeans-html4j)
+and made the magic possible!