JLM Hacker documentation

Here are some quick notes about how to hack on JLM. The documentation is a bit sparse, but that's a wiki. Feel free to improve it ;)

Git workflow

The main thing for now is that the git worflow we are aiming at should follow the classical GitHub one. See for example https://github.com/diaspora/diaspora/wiki/Git-Workflow

Modifying lessons

The lessons integrated into the tool are quite complicated to edit and maintain. This is because they are translated between french and english, and also because they are used for all supported programming language. About the translation between human language, you should only edit the english HTML, never edit the french HTML. If you do so, your work will get lost the next time that the french HTML is regenerated with po4a. Check the next section to see how to change the french texts.

About sharing the text between Java and Python, we have something working, but it's not very satisfying. It may well change in the future (see https://github.com/oster/JLM/issues/37 for example). For now, we use the HTML class attribute of elements to separate the progLangs. But Java CSS support is to weak to use it directly, so we have to actually kill the parts destinated to other languages (that's done in JlmHtmlEditorKit). It's hackish, not really robust and kinda cumbersome to use. In particular, you cannot use the tag because the EditorKit don't seem to seem them (don't ask why). As a result, we had to duplicate whole paragraphs just to change one word.

Again, I guess that this way of doing things will change at some point, but you now know how to edit the files for now.

Getting the translations to work

To translate the exercises and lessons, we use [[http://po4a.alioth.debian.org/][PO4A]] project (PO for anything), which was designed to ease the maintainance of documentation translations.

installing po4a

The first thing to do is thus to get that software and install it. It's realy trivial on debian and ubuntu boxes :

sudo apt-get install po4a

It should be quite simple on other linux flavors, too. Installing the beast on Windows or OSX is more adventurous, and there is no ready to use path for this. We managed to get it working on Gérald OSX, but it involved editing some of the installation files manually. Sorry about it. If you manage to get a nice way to do it, please document it in this wiki. As we know quite well the po4a guys, we could also get changes integrated if needed.

Translation workflow

Here is the big picture from the po4a documentation:

  Input document --\                          /---> Output document (translated)
                    \                        /       
                     +-->--   po4a  --------+
                    /                        \
  Input PO --------/                          \---> Output PO (extracted)

That is to say that all html files written manually should be in english. If you want to fix a translation, do not fix the html file directly or your changes will get lost since they are generated files. Instead, modify the lib/l10n/.po file to fix the problem, and rerun po4a. These po files are at the same time input and outpout in the process: the new english parts are added to the file, and old translations get "fuzzied" while the translation parts are used to generate the translated html files.

It may sound a bit strange at the first glance, but it's quite simple at the end. Check the po4a documentation, it's quite complete.

Adding a new file to translate

Simply add a line in the po4a.conf file at the root of the JLM project. The syntax should be quite self-explanatory, but the po4a documentation is there for you if you don't feel so.