Sugar Labs - User contributions [en]

Karma/Future Direction

2010-06-22T11:05:55Z

Petergijsels: /* Git Repositories */

We have now converted around 80 lessons to Karma, so this might be a good time to look back and evaluate what we have done so far. The focus on this page will be on things that can be improved and possible future directions we could explore.

==Issues in the Current Incarnation of Karma==
# If you look at the current Karma activities you'll see a lot of duplication:
#* a number of lessons are variations on a theme. E.g. the 2_English_Vocabulary* lessons are all very similar. The only thing that varies are the pictures, positions and words.
#* the html of a lot of lessons is very similar except for the title and maybe one or two JavaScript libraries. Html lacks the abstraction mechanisms to remove this duplication.
# You get very few errors if there is something wrong in your html (e.g. missing DOCTYPE declaration or wrong path to a JavaScript or CSS file). This is very painful if you are not familiar with web development.
# CSS is a big pain for layouts if you want to be able to resize them (CSS is ok if you only use absolute positioning).

==Generating Lessons==
Most of these issues can be alleviated if we generate html, css and (part of) the JavaScript from a higher level description.

I would propose a stratified design with two layers.

===Base layer===
At the lowest level you would have a description language embedded in Python. This approach of embedding a language in Python is also used by SCons (www.scons.org), a replacement for Make. I have very good experience with it except for the speed in large projects (which is not a concern for us).

To give you an idea of what such a description could look like:
lesson_title('My lesson')
java_script('jQuery')
java_script('jQuery.UI')
java_script('karma')
#...
# Some code to configure header and footer
#...
css('JQuery.UI')
#...
for img in files_in('assets/images'): karma_preload(img)
#...
div(id='div1', left=10, top=20, width=30, height=40)
#...

The base layer provides a number of primitives like: lesson_title, java_script, css,... You can combine and abstract them using the mechanisms built into Python.

Notice that in the above description there is no mention of the specific version nor location of the javascript files. We can e.g. easily switch between minimized/non-minimized versions at generation time.

Since it is embedded in Python, we can use the full power of Python (e.g. the for loop over all images in the assets/image directory).

You can develop your complete lesson on this layer if you want to.

Notice that you still have to write the logic of your lesson in JavaScript (what is now in lesson.js) and can still style your lesson with CSS (lesson.css).

For many lessons a couple of divs in the body of the html suffice; the rest can be done in JavaScript. If you need more complex html you can use the markup library to generate html from Python or include the contents of an html file in the generated html.

===Higher layer===
On top of the base layer you can create a template lesson. E.g. a generic multiple choice quiz. Everything that is generic you put here (generic CSS and JavaScript code) and a small amount of Python code to read in a configuration file (xml, json) containing the questions and their answers.

For the layout, one of the requests I got from the team here is a way to visually lay out the divs, because CSS is so difficult to work with (I agree). One way to do this is to make a small layout editor that runs in the browser and that generates the div part of the base layer description above.

Similarly you can make a GUI where you can just check some checkboxes for which JavaScript and CSS files you want for your lessons and which assets you want Karma to preload.

===Output from the Generator===
The generator would generate:
* a (big part of) the html. Everything in the <head> part can be generated. The header and footer can be generated (other deployments than OLEN can easily plug in another header/footer). The divs in the body can be generated.
* a javascript file that contains a call to the Karma constructor to tell Karma about the assets that need to be preloaded
* a css file that contains the positions of the divs.
* optionally it can copy some js files (e.g. when it is a template lesson)
* it can do some of the things our current deployment script does. I am not familiar with it, but I imagine it does things like adjust paths, minimize js files, share resources between lessons, etc. The advantage would be that it doesn't have to grovel through the html files to adjust paths, but starts from the python description.

===CSS Positioning===
I would simplify our life and go for a fixed resolution (1200x900) and absolute positioning in CSS. The positioning of the elements would be done in the CSS editor, so at generation time we can always scale all coordinates with a fixed scale factor (flash does a similar thing).

==Comparison with the eXe framework==
Mike Dawson is using it in Afghanistan and he seems quite happy with it. There are some similarities and differences to the approach above (called KarmaNT below):
* we both have a higher (than html) level description of a lesson.
* we both have support for template lessons.
* we both generate (part of) the html, css, js.
* eXe is very focussed on the GUI part and is lacking the clear lowest layer that KarmaNT has. In my experience that is a big drawback (e.g. in VisualWorks you have a GUI to define GUIs, but the base layer is not really well designed and documented which leads to big problems when you want to reuse or generate parts of GUIs from code instead of using the provided GUI). A stratified design is much more robust.
* the GUI is a bit off-putting, with non-standard controls and lots of superfluous controls (probably due to XUL). You probably get used to it, but my first impression was not very positive. I'm not sure though that our GUI will be much better.
* eXe is quite big and I'm not sure it would be easy to tailor it to our specific needs. I envision something much smaller for KarmaNT.
* eXe is more mature and plugs into a number of other tools (IMS, SCORM,...)

==Git Repositories==
* http://github.com/pg42/karma-generator : a simple generator for a lesson, with an example of a template lesson
* http://github.com/pg42/karma-editor : a sketch of a gui to edit karma lessons

Karma/Future Direction

2010-06-22T11:02:30Z

Petergijsels:

We have now converted around 80 lessons to Karma, so this might be a good time to look back and evaluate what we have done so far. The focus on this page will be on things that can be improved and possible future directions we could explore.

==Issues in the Current Incarnation of Karma==
# If you look at the current Karma activities you'll see a lot of duplication:
#* a number of lessons are variations on a theme. E.g. the 2_English_Vocabulary* lessons are all very similar. The only thing that varies are the pictures, positions and words.
#* the html of a lot of lessons is very similar except for the title and maybe one or two JavaScript libraries. Html lacks the abstraction mechanisms to remove this duplication.
# You get very few errors if there is something wrong in your html (e.g. missing DOCTYPE declaration or wrong path to a JavaScript or CSS file). This is very painful if you are not familiar with web development.
# CSS is a big pain for layouts if you want to be able to resize them (CSS is ok if you only use absolute positioning).

==Generating Lessons==
Most of these issues can be alleviated if we generate html, css and (part of) the JavaScript from a higher level description.

I would propose a stratified design with two layers.

===Base layer===
At the lowest level you would have a description language embedded in Python. This approach of embedding a language in Python is also used by SCons (www.scons.org), a replacement for Make. I have very good experience with it except for the speed in large projects (which is not a concern for us).

To give you an idea of what such a description could look like:
lesson_title('My lesson')
java_script('jQuery')
java_script('jQuery.UI')
java_script('karma')
#...
# Some code to configure header and footer
#...
css('JQuery.UI')
#...
for img in files_in('assets/images'): karma_preload(img)
#...
div(id='div1', left=10, top=20, width=30, height=40)
#...

The base layer provides a number of primitives like: lesson_title, java_script, css,... You can combine and abstract them using the mechanisms built into Python.

Notice that in the above description there is no mention of the specific version nor location of the javascript files. We can e.g. easily switch between minimized/non-minimized versions at generation time.

Since it is embedded in Python, we can use the full power of Python (e.g. the for loop over all images in the assets/image directory).

You can develop your complete lesson on this layer if you want to.

Notice that you still have to write the logic of your lesson in JavaScript (what is now in lesson.js) and can still style your lesson with CSS (lesson.css).

For many lessons a couple of divs in the body of the html suffice; the rest can be done in JavaScript. If you need more complex html you can use the markup library to generate html from Python or include the contents of an html file in the generated html.

===Higher layer===
On top of the base layer you can create a template lesson. E.g. a generic multiple choice quiz. Everything that is generic you put here (generic CSS and JavaScript code) and a small amount of Python code to read in a configuration file (xml, json) containing the questions and their answers.

For the layout, one of the requests I got from the team here is a way to visually lay out the divs, because CSS is so difficult to work with (I agree). One way to do this is to make a small layout editor that runs in the browser and that generates the div part of the base layer description above.

Similarly you can make a GUI where you can just check some checkboxes for which JavaScript and CSS files you want for your lessons and which assets you want Karma to preload.

===Output from the Generator===
The generator would generate:
* a (big part of) the html. Everything in the <head> part can be generated. The header and footer can be generated (other deployments than OLEN can easily plug in another header/footer). The divs in the body can be generated.
* a javascript file that contains a call to the Karma constructor to tell Karma about the assets that need to be preloaded
* a css file that contains the positions of the divs.
* optionally it can copy some js files (e.g. when it is a template lesson)
* it can do some of the things our current deployment script does. I am not familiar with it, but I imagine it does things like adjust paths, minimize js files, share resources between lessons, etc. The advantage would be that it doesn't have to grovel through the html files to adjust paths, but starts from the python description.

===CSS Positioning===
I would simplify our life and go for a fixed resolution (1200x900) and absolute positioning in CSS. The positioning of the elements would be done in the CSS editor, so at generation time we can always scale all coordinates with a fixed scale factor (flash does a similar thing).

==Comparison with the eXe framework==
Mike Dawson is using it in Afghanistan and he seems quite happy with it. There are some similarities and differences to the approach above (called KarmaNT below):
* we both have a higher (than html) level description of a lesson.
* we both have support for template lessons.
* we both generate (part of) the html, css, js.
* eXe is very focussed on the GUI part and is lacking the clear lowest layer that KarmaNT has. In my experience that is a big drawback (e.g. in VisualWorks you have a GUI to define GUIs, but the base layer is not really well designed and documented which leads to big problems when you want to reuse or generate parts of GUIs from code instead of using the provided GUI). A stratified design is much more robust.
* the GUI is a bit off-putting, with non-standard controls and lots of superfluous controls (probably due to XUL). You probably get used to it, but my first impression was not very positive. I'm not sure though that our GUI will be much better.
* eXe is quite big and I'm not sure it would be easy to tailor it to our specific needs. I envision something much smaller for KarmaNT.
* eXe is more mature and plugs into a number of other tools (IMS, SCORM,...)

==Git Repositories==
http://github.com/pg42/karma-generator
http://github.com/pg42/karma-editor

Karma/Future Direction

2010-06-16T03:49:46Z

Petergijsels: /* Base layer */

Karma/Future Direction

2010-06-15T08:20:04Z

Petergijsels: Created page with 'We have now converted around 80 lessons to Karma, so this might be a good time to look back and evaluate what we have done so far. The focus on this page will be on things that c...'

We have now converted around 80 lessons to Karma, so this might be a good time to look back and evaluate what we have done so far. The focus on this page will be on things that can be improved and possible future directions we could explore.

==Issues in the Current Incarnation of Karma==
# If you look at the current Karma activities you'll see a lot of duplication:
#* a number of lessons are variations on a theme. E.g. the 2_English_Vocabulary* lessons are all very similar. The only thing that varies are the pictures, positions and words.
#* the html of a lot of lessons is very similar except for the title and maybe one or two JavaScript libraries. Html lacks the abstraction mechanisms to remove this duplication.
# You get very few errors if there is something wrong in your html (e.g. missing DOCTYPE declaration or wrong path to a JavaScript or CSS file). This is very painful if you are not familiar with web development.
# CSS is a big pain for layouts if you want to be able to resize them (CSS is ok if you only use absolute positioning).

==Generating Lessons==
Most of these issues can be alleviated if we generate html, css and (part of) the JavaScript from a higher level description.

I would propose a stratified design with two layers.

===Base layer===
At the lowest level you would have a description language embedded in Python. This approach of embedding a language in Python is also used by SCons (www.scons.org), a replacement for Make. I have very good experience with it except for the speed in large projects (which is not a concern for us).

To give you an idea of what such a description could look like:
lesson_title('My lesson')
java_script('jQuery')
java_script('jQuery.UI')
java_script('karma')
#...
# Some code to configure header and footer
#...
css('JQuery.UI')
#...
for img in files_in('assets/images'): karma_preload(img)
#...
div(id='div1', left=10, top=20, width=30, height=40)
#...

The base layer provides a number of primitives like: lesson_title, java_script, css,... You can combine and abstract them using the mechanisms built into Python.

Notice that in the above description there is no mention of the specific version nor location of the javascript files. We can e.g. easily switch between minimized/non-minimized versions at generation time.

Since it is embedded in Python, we can use the full power of Python (e.g. the for loop over all images in the assets/image directory).

You can develop your complete lesson on this layer if you want to.

Notice that you still have to write the logic of your lesson in JavaScript (what is now in lesson.js) and can still style your lesson with CSS (lesson.css).

===Higher layer===
On top of the base layer you can create a template lesson. E.g. a generic multiple choice quiz. Everything that is generic you put here (generic CSS and JavaScript code) and a small amount of Python code to read in a configuration file (xml, json) containing the questions and their answers.

For the layout, one of the requests I got from the team here is a way to visually lay out the divs, because CSS is so difficult to work with (I agree). One way to do this is to make a small layout editor that runs in the browser and that generates the div part of the base layer description above.

Similarly you can make a GUI where you can just check some checkboxes for which JavaScript and CSS files you want for your lessons and which assets you want Karma to preload.

===Output from the Generator===
The generator would generate:
* a (big part of) the html. Everything in the <head> part can be generated. The header and footer can be generated (other deployments than OLEN can easily plug in another header/footer). The divs in the body can be generated.
* a javascript file that contains a call to the Karma constructor to tell Karma about the assets that need to be preloaded
* a css file that contains the positions of the divs.
* optionally it can copy some js files (e.g. when it is a template lesson)
* it can do some of the things our current deployment script does. I am not familiar with it, but I imagine it does things like adjust paths, minimize js files, share resources between lessons, etc. The advantage would be that it doesn't have to grovel through the html files to adjust paths, but starts from the python description.

===CSS Positioning===
I would simplify our life and go for a fixed resolution (1200x900) and absolute positioning in CSS. The positioning of the elements would be done in the CSS editor, so at generation time we can always scale all coordinates with a fixed scale factor (flash does a similar thing).

==Comparison with the eXe framework==
Mike Dawson is using it in Afghanistan and he seems quite happy with it. There are some similarities and differences to the approach above (called KarmaNT below):
* we both have a higher (than html) level description of a lesson.
* we both have support for template lessons.
* we both generate (part of) the html, css, js.
* eXe is very focussed on the GUI part and is lacking the clear lowest layer that KarmaNT has. In my experience that is a big drawback (e.g. in VisualWorks you have a GUI to define GUIs, but the base layer is not really well designed and documented which leads to big problems when you want to reuse or generate parts of GUIs from code instead of using the provided GUI). A stratified design is much more robust.
* the GUI is a bit off-putting, with non-standard controls and lots of superfluous controls (probably due to XUL). You probably get used to it, but my first impression was not very positive. I'm not sure though that our GUI will be much better.
* eXe is quite big and I'm not sure it would be easy to tailor it to our specific needs. I envision something much smaller for KarmaNT.
* eXe is more mature and plugs into a number of other tools (IMS, SCORM,...)

Karma

2010-06-15T07:18:32Z

Petergijsels: /* Project Roadmap */

<noinclude>{{GoogleTrans-en}}{{TOCleft}}
[[Category:GSoC]]
[[Category:Project]]</noinclude>
[[Image:Karma.png|right]]

== The Karma Project ==

Karma is a framework for creating educational software using JavaScript, html5, and SVG. The Karma team is primarily focused on developing Sugar activities but you can also Karma to create lessons that run in any web browser that supports html5. The best ways to get involved are to join the [http://groups.google.com/group/karmajs mailing list] and [http://git.olenepal.org/karma/karma get the code]

=== Rationale ===

Anyone with a modern standards-compliant web browser and a text editor should be able to create learning activities that can be used by anyone with a computer. Sugar should not be a walled garden that only allows learning activities expressly designed for it and it alone but rather gives extra power and depth to learning activities. Karma uses a specialized vocabulary that features a number of specialized terms. Please refer to the [[Karma/Dictionary|Karma Dictionary]] early and often.

=== Status ===

Karma is a sub-project of Sugar Labs that is under active development. The latest examples can be seen at [http://karma.sugarlabs.org http://karma.sugarlabs.org]. You can also check out the [http://karmaproject.wordpress.com Karma Project blog] for updates.

To try out the karma examples you need to have an html5-capable browser. The Browse activity within Sugar does not currently support html5. To try out karma within Sugar you need to install [http://dev.laptop.org/~bobbyp/surf/Surf-106.xo Surf] and its webkit dependencies or run Firefox 3.5 from the command-line (yum install pywebkitgtk WebKit-gtk gnome-python2-gconf).

The current focus of development is to convert Nepal's set of lessons coded in Squeak smalltalk. You can find the list of lessons to be converted [http://spreadsheets.google.com/pub?key=tweUJyn1BkEciHqVtSvCYDA&output=html here]. This is a good place for new contributors to get started

=== What Karma Is ===

* Karma is a simple framework to create simple interactive learning activities primarily for Sugar but also to be viewable through any web browser that supports html5
* Karma is used to create simple activities that run off-line w/out access to the Internet
* Karma is for web developers who want to contribute to Sugar using their current skills
* Karma is built on top of open web standards such as html5, javascript, and CSS.
* Karma is built to run on top of web browsers that support html5, particularly the canvas element.
* Karma is built around the concept of individual "lessons" and multiple lessons can be aggregated into a sugar activity
* Karma is the evolution of OLE Nepal's work on the EPaath suite of lessons in Nepal
* Karma is designed with pervasive and easy internationalizaton in mind and integration with moodle, particularly for monitoring student progress
* Karma is pedagogically agnostic. Pedagogical choices are left to the lesson author.

=== What Karma Isn't ===

* Karma is not compatible with Internet Explorer because Internet Explorer does not support html5 apis such as canvas, svg, localStorage, etc.
* Karma is not meant to replace pyGTK as the dominant toolset for creating Sugar activities
* Karma is not a tool for creating activities with complex 3D graphics. Karma is a tool for creating activities with simple 2D graphics
* Karma is not meant as a basis for a WYSIWG programming environment like TurtleArt, EToys, or Logo
* Karma is not built to support browsers that do not support html5, such as Internet Explorer and Firefox < version 3.5
* Karma is not intended to teach programming to children though it could be used as such

=== Design Philosophy ===

A Karma lesson is composed of a valid html5 document, javascript code, and css stylesheets and optional assets such as images, audio, video and lesson plans. Karma should be very easy for inexperienced developers to understand and work with. Even non-programmers should be able to make visible changes by tweaking the code and liberal use of cut-and-paste. Complexities such as integration with pootle, local storage, and certain types of animation should be abstracted so that novice developers don't have to understand them in order to effectively use Karma. Karma strictly adheres to the Model-View-Controller Pattern and similarly to unobtrusive JavaScript. In essence. you should be able to substantially change the look and feel of a Karma lesson by modifying the CSS or you could translate the activity, without having to understand the JavaScript code.

=== Design Goals ===
* Unobtrusive JavaScript
* No globals
* No extension of native objects

=== Technical Architecture ===

* Run-time - Karma will work with basic functionality on any W3C standards-compliant browser that supports HTML5 tags canvas, audio, and svg. This notably excludes Microsoft's Internet Explorer. Karma will be particularly tailored to work with Sugar's Journal and collaboration through Telepathy. Longer-term we hope to extend Karma to take advantage of Sugar's collaboration features.
* Primary Programming language - [https://developer.mozilla.org/en/New_in_JavaScript_1.6 Javascript 1.6]
* [[Karma/i18n|i18n]] -- Pervasive internationalization is a critical part of Karma
** Supported types of i18n -- ToDo
*** Output of Native Digits
*** Image switching per locale
*** Regular text, though it is unclear how to support plural forms, grammar shifts, and gender
*** Audio switching per locale
** Integration with pootle
* [[Karma/Utilities|Utilities]] -- we primarily use [http://www.narwhaljs.org narwhal] for command-line scripting and [http://code.google.com/p/jsdoc-toolkit/ jsdoc] for documentation
* Journal, Telepathy Integration -- method to be determined, perhaps using html5's offline storage feature, some resources [https://developer.mozilla.org/en/Offline_resources_in_Firefox here] and [http://www.weboshelp.net/webos-tutorials/156-palm-webos-html5-database-storage-tutorial here]
* Moodle Integration -- method to be determined
* [[Karma/Bundle_layout|Repo and Bundle layout]]
* UI Widgets
** [[Scoreboard]]
** Dialog -- use standard jQuery UI one?

=== Conventions ===

* [[Karma:Anatomy_of_Lesson|Anatomy of a Karma Lesson]]
* The [[Karma/Dictionary|Karma Dictionary]]
* [[Karma/Specifications|Karma Specifications]] (early draft)
* [[Karma/Anti-conventions|Anti-Conventions]] -- coding no-nos
* [[Karma/Layout_Converted_Squeak_Lessons|Layout for converted Squeak Lessons]]
* Source Code stored in http://git.olenepal.org/karma/karma
* Each lesson must be in a folder named according to the schema "karma_Grade_Maths_title_WeekNo" where the week number is optional
The following are valid names
karma_3_Maths_LargestNumber_15
karma_2_English_MatchingPuzzle
karma_6_Maths_AddingUpTo10_4
* Version Control and repository management see the [[Karma#Version_Control|Version Control]] section of this page
* Unit testing is required for the karma.js library but not for individual lessons http://karma.sugarlabs.org/tests/
* Project Documentation kept in the Sugar Labs wiki
* Coding conventions: Based on [http://www.dojotoolkit.org/developer/StyleGuide Dojo Style Guide]
** Use sadCamelCase for function names and variables
** Exception to above -- object constructors should start with a capital letter
** boolean variables should be prefixed with "is", "has", "can", or "should"
** counters should be prefixed with "num" or "count"
** Whenever possible, use [http://www.jslint.com/ jslint]
* File naming conventions: lowercase letters, underscore instead of spaces (need to write more about it)
* Coding Pattern - We generally try to follow this coding pattern as it makes it easier to browse your code
Put code in following order
1) variable declarations
2) method declarations
3) method calls

== Version Control ==
Currently all lessons are stored in the examples/ folder of [http://git.olenepal.org/karma/karma main karma repository]

<strike>
Here is how you can use the karma_lesson template to create a new repository from scratch

$ git clone git://git.sugarlabs.org/karma_lesson/mainline.git
$ mkdir ../karma_3_English_3 # create a new lesson directory following our naming convention
$ cp -r * ../karma_3_English_3
$ cd ../karma_3_English_3
$ rm -r .git # make sure you get rid of the old git directory
$ git init
$ git add .
$ git commit -a -m "first commit"

Now go to the http://git.sugarlabs.org/projects/new, make sure you are logged in
Create a new project, use the same name as you did for your lesson's main folder
then,
$ git remote add origin git://... # the pubic push url

Then on to coding your lesson ;)

From then on
$ git push origin master # will sync your local tree w/ the server

'''Tagging''' -- a karma lesson can be in only one of two states, stable or unstable. Any commit tagged 'stable' is the stable version of your code. Every other version of your code is unstable. We will not use numeric versioning such as 0.1, 1.0, 1.2, etc. for the foreseeable future.
</strike>

== Meetings ==
[[Karma:Meeting 21 December 2009]]

== GSoC Project ==

Karma started as a GSoC project with Felipe Lopez Toledo "SubZero" as the student participant and [[USER:BryanWB| Bryan Berry]] as mentor.

=== GSoC Meetings ===

Notes from GSoC meetings - kept for archival purposes
* [[Karma:Meeting 12 May 2009]]
* [[Karma:Meeting 02 Jun 2009]]
* [[Karma:Meeting 09 Jun 2009]]
* [[Karma:Meeting 23 Jun 2009]]
* [[Karma:Meeting 30 Jun 2009]]
* [[Karma:Meeting 21 Jul 2009]]
* [[Karma:Meeting 4 Aug 2009]]
* [[Karma:Meeting 11 Aug 2009]]
* [[Karma:Meeting 18 Aug 2009]]
* [[Karma:Meeting 24 Aug 2009]]
* [[Karma:Meeting 08 Sep 2009]]
* [[Karma:Meeting 14 Sep 2009]]
* [[Karma:Meeting 21 Sep 2009]]

== Project Roadmap ==

==== 0.1 "Osito" ====

Was completed September 11, 2009

* 1 Working example in "adding_up_to_10"
* cleaned up documentation with jsdocs api documentation and cleaned up README.txt
* integrate chakra and "adding_up_to_10" and knavbar
* adding_up_to_10 works on the XO
** Surf
** Browse

==== 0.2 "Gatito" ====

Completed mid-December 2009

* unit testing added to karma.js using QUnit
* API documented w/ jsdoc-toolkit
* support for SVG and canvas animation
* 3 working examples
** Adding_Up_to_10 using both SVG and canvas
** Quadrilaterals
** "Conozco A Uruguay" done with karma -- 50% done

==== 0.3 "niño" ====

Due 31 March 2010

* Full i18n support
* All Squeak lessons converted to Karma
* Integrate all of the existing E-Paath lesson into chakra
* narwhal build script to build one giant karma bundle w/ all the E-Paath lessons inside it and chakra
* At least 6 lessons ready that have been translated into 3 languages each
* Version 0.1 draft of karma specification done

==== Future Direction of Karma ====

No schedule yet.

[[Karma/Future Direction|This page]] has more information.

=== Library ===

here lies a lot of links to resources specific to karma

UI
* Iphone Human Interface Guide http://developer.apple.com/iphone/library/documentation/userexperience/conceptual/mobilehig/MobileHIG.pdf
* Palm Pre interface guide http://developer.palm.com/images/palm/pdf/palm_webos_hi_guidelines.pdf
* 30 Usability Issues To Be Aware Of http://www.smashingmagazine.com/2007/10/09/30-usability-issues-to-be-aware-of/
* 10 Usability Nightmares You Should Be Aware Of http://www.smashingmagazine.com/2007/09/27/10-usability-nightmares-you-should-be-aware-of/
* "The Design of Everyday Things" book by Don Norman
* "Don't Make me think" by Steve Krug, guide to usability for web apps

HTML5
* http://www.smashingmagazine.com/2009/07/16/html5-and-the-future-of-the-web/
* http://www.w3.org/TR/html5-diff/ Differences between html4 and html5
* [http://diveintohtml5.org/ Dive Into HTML5]

General Web Design
* "Web Design in a Nutshell" from O'Reilly
* Apple "Web Page Development: Best Practices" http://developer.apple.com/internet/webcontent/bestwebdev.html

Canvas
* demos: http://html5demos.com/
* basics: http://dev.opera.com/articles/view/html-5-canvas-the-basics/
* painting web app: http://dev.opera.com/articles/view/html5-canvas-painting/
* mozilla canvas tutorial: https://developer.mozilla.org/en/Canvas_tutorial
* using canvas on webkit: http://developer.apple.com/documentation/AppleApplications/Conceptual/SafariJSProgTopics/Tasks/Canvas.html
* http://www.whatwg.org/specs/web-apps/current-work/multipage/the-canvas-element.html

SVG
* The [http://www.w3.org/Graphics/SVG/IG/resources/svgprimer.html SVG Primer] a very detailed and in-depth resource
* [http://raphaeljs.com/reference.html Raphaeljs documentation]
* https://developer.mozilla.org/en/svg

Javascript
* [http://eloquentjavascript.net Eloquent Javascript] best beginning javascript resource
* "Javascript: The Good Parts" book by Doug Crockford
* "jQuery in Action" book
* "Pro Javascript Techniques" by john resig
* All the tutorials at www.ejohn.org, esp.
** http://ejohn.org/blog/how-javascript-timers-work/

Coding Tools and Conventions
* Firebug --- http://www.getfirebug.com
* Web-Inspector --- webkit's answer to firebug
* Browsers --- We primarily work with Chromium and Firefox > 3.5
* For emacs users -- nxhtml mode and magit.el for working w/ git
* [http://www.jslint.com/ jslint]
* [http://www.inkscape.org inkscape]
* [http://narwhaljs.org narwhal]

== Subpages ==

{{Special:PrefixIndex/{{PAGENAMEE}}/}}

Karma/i18n

2010-03-07T16:16:14Z

Petergijsels: /* General Strategy */

Rough plan for implementing i18n for Karma

=== Requirements ===
* Integrate with pootle
* Handle strings inside code and html markup
Examples
$("#someDiv").text(gettext("Hello World"));
<nowiki>
<div>Hello <strong>W</strong>orld</div>
</nowiki>

* All strings stored in one file per locale, messages.json
* All message identifiers must be unique within an a lesson
* Accommodating numeric, currency, and date formatting is not an immediate requirement

=== General Strategy ===
====JavaScript Strings====
We try to follow a subset of the [http://www.gnu.org/software/gettext/manual/gettext.html#gettext gettext api] quite closely. After including jquery.i18n.js you can use the following gettext functions in your javascript scripts:
* $.i18n.gettext('text to be translated') or $. _('text to be translated'): to translate a simple string
* $.i18n.ngettext('a car', 'multiple cars', n): to choose a pluralized form depending on n
* $.i18n.pgettext('context', 'text to be translated'): this is useful if you are writing plugins. E.g. in ui.kFooter.js the context is '$.ui.kFooter'.

Remarks:
* you can add the statement var _ = $._; at the beginning of your $(document).ready function and then use _('message') without needing to add the $. However the name of the function you are calling should be _, gettext, ngettext or pgettext. Otherwise the strings can not be automatically be extracted with xgettext.
* the arguments to the different calls should be string literals. Otherwise xgettext will not be able to extract the messages to be translated.

The lesson examples/6_Maths_matchingAnglesAndShapes/ contains an example.

====HTML Strings====
We will try to use the [http://en.wikipedia.org/wiki/Internationalization_Tag_Set Internationalization Tag Set] for handling strings inline with html. The [http://okapi.sourceforge.net/ Okapi] tool may be able to parse out strings marked with ITS.

There is first attempt at internationalizing html without using ITS. It will be in git under karma/i18n.
* You annotate the tags of elements that need translation with a class attribute: class="translate".
* i18n/html2po.py is the equivalent of xgettext for html.
* i18n/translate-html.py translates an html page.

Have a look at karma/i18n/example for an example.

The following is no longer true (translate-html.py generates a static translated html page), but can be implemented if needed:
* For the immediate future we will dynamically change out strings per locale on page load