diff options
author | Daniel Narvaez <dwnarvaez@gmail.com> | 2013-02-01 11:42:41 (GMT) |
---|---|---|
committer | Daniel Narvaez <dwnarvaez@gmail.com> | 2013-02-01 11:42:41 (GMT) |
commit | f0c20584e7299c11e6eebad3d8388c4618863e94 (patch) | |
tree | bc226231b1464a40c0fe30d70f631bd12efbc2e4 | |
parent | 36828cf89af8fa3b49c44286c156e61558a36a43 (diff) |
Generate an html doc
Formatting fixes, no real content changes.
-rw-r--r-- | Makefile | 2 | ||||
-rw-r--r-- | README.html | 108 | ||||
-rw-r--r-- | README.md | 50 | ||||
-rw-r--r-- | TODO | 17 | ||||
-rwxr-xr-x | markdown | 33 | ||||
-rw-r--r-- | markdown.css | 25 |
6 files changed, 203 insertions, 32 deletions
diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..3c2ad2f --- /dev/null +++ b/Makefile @@ -0,0 +1,2 @@ +all: + ./markdown README.md > README.html 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> + @@ -1,10 +1,14 @@ -### Premise +# HTML activities - Draft 1 + +## Premise XXX Improve the Sugar OS developer experience + XXX Cross platform sugar activities -> future + XXX What is Sugar. -# Modules +## Modules The framework is composed of various libraries, initially @@ -13,7 +17,7 @@ The framework is composed of various libraries, initially * datastore * collaboration -## Interface description +### Interface description Each module provides one or more interface descriptions which are language independent. A subset of object-oriented languages should be chosen, so that @@ -23,14 +27,14 @@ python and JavaScript it's explicit about types. For example, the datastore interface could look like -class Datastore { - DatastoreObject load() - void save(DatastoreObject object); -} + class Datastore { + DatastoreObject load(); + void save(DatastoreObject object); + } XXX The interface is totally made up! -## Implementation +### Implementation 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 @@ -40,18 +44,18 @@ 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. -## Code style +### Code style 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. -## Namespacing and package management +### Namespacing and package management We are using [volo](http://volojs.org) for namespacing and package management, both in the libraries and in the documentation. -# Activities +## Activities Activities are [open web apps](https://developer.mozilla.org/en-US/docs/Apps), their only specificity is that can make use of our libraries framework. On some @@ -60,7 +64,9 @@ 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. -# Random Sugar OS implementation notes +## Implementation notes + +### Sugar OS * 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 @@ -81,23 +87,3 @@ script to sync them with the sugar-artwork repository. hope using local paths will work in a web activity. * 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. - -# TODO - -Version 0.1 - -* Write an helloworld open web activity. Or maybe just steal a cool one? Might -make for a more shiny demo without any effort :) -* Write a firefox activity using firefox as packaged in the distro. Will -probably require an extension to disable the chrome UI cleanly. -* Write the web activity -> sugar activity script, probably as a volo command. -volo build sugar-os, or something. -* Play with volo to see if there are any road blockers. -* Write the activity library, with a close method. It should be enough to call -window.close() on Sugar OS at least. -* Document how to use volo to pull in the library. -* Write the datastore library. This will involve writing an extension which -will use DBus to communicate with the datastore and making sure we can -communicate between content and extension. -* Write the graphics library with initial toolbar implementation. It will -require writing the script to sync the svg icons from sugar-artwork. @@ -0,0 +1,17 @@ +Version 0.1 + +* Write an helloworld open web activity. Or maybe just steal a cool one? Might +make for a more shiny demo without any effort :) +* Write a firefox activity using firefox as packaged in the distro. Will +probably require an extension to disable the chrome UI cleanly. +* Write the web activity -> sugar activity script, probably as a volo command. +volo build sugar-os, or something. +* Play with volo to see if there are any road blockers. +* Write the activity library, with a close method. It should be enough to call +window.close() on Sugar OS at least. +* Document how to use volo to pull in the library. +* Write the datastore library. This will involve writing an extension which +will use DBus to communicate with the datastore and making sure we can +communicate between content and extension. +* Write the graphics library with initial toolbar implementation. It will +require writing the script to sync the svg icons from sugar-artwork. diff --git a/markdown b/markdown new file mode 100755 index 0000000..c79afd3 --- /dev/null +++ b/markdown @@ -0,0 +1,33 @@ +#!/usr/bin/python3 + +import os +import argparse + +import markdown2 + + +parser = argparse.ArgumentParser(description="Format markdown text") +parser.add_argument("input_file_path", nargs=1, help="Input file path") +args = parser.parse_args() + +output = """ +<!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> +""" + +with open(args.input_file_path[0]) as f: + output += markdown2.markdown(f.read()) + +output += """ + </body> +</html> +""" + +print(output) diff --git a/markdown.css b/markdown.css new file mode 100644 index 0000000..5ae7cbc --- /dev/null +++ b/markdown.css @@ -0,0 +1,25 @@ +body { + font-family: "Droid Sans", Helvetica, Arial, sans-serif; + font-size: 18; + margin-left: 160px; + margin-right: 160px; +} + +h1 { + font-family: "Droid Serif", Georgia, Times, serif; + font-size: 34px; + border-bottom: 2px solid #DDDDDD; + margin-bottom: 30px; +} + +h2 { + font-family: "Droid Serif", Georgia, Times, serif; + font-size: 28px; + margin-bottom: 30px; +} + +h3 { + font-family: "Droid Serif", Georgia, Times, serif; + font-size: 20px; + margin-bottom: 30px; +} |