1. HOW TO
HERD CAT
STATUES
& MAKE
AWESOME
THINGS
MELISSA DRAPER
KIWIPYCON 2012
flickr.com/photos/schristia/4366659009/

2. A story of 3 users.

3. Jack found a useful
sounding tool...

4. ...but can't figure it
out.

5. Jack looks for
documentation

7. A lack of
documentation is
bad.

8. Jill found a useful
sounding tool too.

9. It has documentation!

10. So she will use it.

11. Good
documentation tells
people how to use
your product.

12. Jaques found a
useful tool too

13. ¿Qué?

15. Excellent
documentation is
available for
everyone.

19. Mahara
(mah-hah-rah; verb)
To think, thinking,
thought

20. Open Source
Eportfolio

21. Students and
Educators

22. Comprehensive
user manual.

23. In English.

24. Requirements:

25. Low learning curve
for translators.

26. One set of rST
source
(per software version)

27. Images need to be
translated too!

28. Support multiple
non-latin scripts
(and unicode symbols)

29. OOB Sphinx does
not really do this!
(it kind of does Japanese)

30. p.s. Really, nothing
does all this

31. How to make Sphinx
do magic?

32. Makefile-driven

33. Get the translations:

34. Automagically
import translations

35. Launchpad
↓
msgfmt
↓
Sphinx (via gettext)

36. Swap to XeLaTeX:

37. Good old fashioned
patching
ಠ_ಠ

38. General patches

39. Locale patches

40. Unsupported locales

41. Localised images:

42. Localised images
git submodule

43. Copy images over
before each build.

44. Standardise DPI

45. $(foreach TRANSLATION,$(UNSUPPORTED),
mkdir -p source/locales/$(TRANSLATION)/$(MAHARA)/LC_MESSAGES;
cp -n /usr/share/locale-langpack/en_AU/LC_MESSAGES/sphinx.mo source/locales/$(TRANSLATION)/$(MAHARA)/LC_MESSAGES/sphinx.mo
;)
$(foreach TRANSLATION,$(TRANSLATIONS),
git checkout source/images ;
cp -ra localeimages/$(TRANSLATION)/* source/images ;
/bin/bash convert_images_dpi.sh;
$(SPHINXBUILD) -a -D language=$(TRANSLATION) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA);
cp patches/makesty.patch $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA);
cp patches/tex.patch $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA);
patch --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/makesty.patch;
patch --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/tex.patch
;)
$(foreach TRANSLATION,$(CLEAN),
make -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf-ja
;)
$(foreach TRANSLATION,$(PATCHED),
cp patches/$(TRANSLATION).patch $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA);
patch --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/$(TRANSLATION).
ch;
make -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf-ja;
patch -R --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/$(TRANSLATION
ch
;)
$(foreach TRANSLATION,$(TRANSLATIONS),
patch -R --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/tex.patch;
patch -R --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/makesty.patch;
cp $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/Mahara.pdf $(BUILDDIR)/html/$(TRANSLATION)/$(MAHARA)/Mahara.pdf;
rm -r $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/
;)
git checkout source/images

46. gitorious.
org/mahara/manual

47. Disclaimer: Not
perfected yet.