1 files changed, 108 insertions, 0 deletions
diff --git a/README.html b/README.html
new file mode 100644
index 0000000..561f69a
--- /dev/null
+++ b/README.html
@@ -0,0 +1,108 @@
+
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <link href="http://fonts.googleapis.com/css?family=Droid+Serif"
+              rel="stylesheet"
+              type="text/css"/>
+        <link href="markdown.css" rel="stylesheet"></link>
+    </head>
+    <body>
+<h1>HTML activities - Draft 1</h1>
+
+<h2>Premise</h2>
+
+<p>XXX Improve the Sugar OS developer experience</p>
+
+<p>XXX Cross platform sugar activities -> future</p>
+
+<p>XXX What is Sugar.</p>
+
+<h2>Modules</h2>
+
+<p>The framework is composed of various libraries, initially</p>
+
+<ul>
+<li>activity</li>
+<li>graphics</li>
+<li>datastore</li>
+<li>collaboration</li>
+</ul>
+
+<h3>Interface description</h3>
+
+<p>Each module provides one or more interface descriptions which are language
+independent. A subset of object-oriented languages should be chosen, so that
+it's possible to implement these from all the languages we are interested
+to support. The description uses the Java syntax because unlike, for example,
+python and JavaScript it's explicit about types.</p>
+
+<p>For example, the datastore interface could look like</p>
+
+<pre><code>class Datastore {
+    DatastoreObject load();
+    void save(DatastoreObject object);
+}
+</code></pre>
+
+<p>XXX The interface is totally made up!</p>
+
+<h3>Implementation</h3>
+
+<p>The implementation should be written as much as possible using web languages.
+But of course we will have the necessity to interact with native system
+components. The multi language nature of the interfaces will be useful here
+because it will allow to provide system specific implementation of certain
+interfaces and generically bridge to them from JavaScript. All the modules
+should provide a web fallback, which will allow to run the activity everywhere
+even if with degraded functionality.</p>
+
+<h3>Code style</h3>
+
+<p>View source is a core part of the sugar experience, so any kind of code
+obfuscation should be avoided. This includes languages that compiles to
+JavaScript, like CoffeeScript.</p>
+
+<h3>Namespacing and package management</h3>
+
+<p>We are using <a href="http://volojs.org">volo</a> for namespacing and package management,
+both in the libraries and in the documentation.</p>
+
+<h2>Activities</h2>
+
+<p>Activities are <a href="https://developer.mozilla.org/en-US/docs/Apps">open web apps</a>,
+their only specificity is that can make use of our libraries framework. On some
+platforms (Sugar OS for example) it might be necessary to generate boilerplate
+code, configuration or to package the app in a certain way to have it integrate
+with the system flawlessly. We will provide scripts to fully automate those
+tasks.</p>
+
+<h2>Implementation notes</h2>
+
+<h3>Sugar OS</h3>
+
+<ul>
+<li>We should probably use firefox, as provided by upstream, to run activities.
+Chrome would probably be an equally good alternative. At some point we could
+just support both.</li>
+<li>We should be able to customize it to look like a native activity without
+patching the code. We need to avoid showing any chrome UI (toolbar, menubar,
+etc) and to provide the X properties Sugar expects from an activity.</li>
+<li>We can generate activity.info from the webapp manifest  when building a .xo.</li>
+<li>The svg icon might be provided in a native/sugar-os directory of the web
+activity or something.</li>
+<li>Communication between JavaScript and native code will be handled by a firefox
+extension and it will most likely go through DBus. pythonext might be an
+alternative but I'm not convinced we should get into pyxpcom again. We can use
+dom events to communicate between content and extension.</li>
+<li>Icons should be shipped as part of the graphics library, we can write a
+script to sync them with the sugar-artwork repository.</li>
+<li>The datastore interface should probably make use of HTML files support. I
+hope using local paths will work in a web activity.</li>
+<li>To get full permission I suspect a web app needs to be installed. We will
+have to figure out if/how we can avoid that.</li>
+</ul>
+
+    </body>
+</html>
+