how to herd cat statues and make awesome things

HOW TOHERD CATSTATUES& MAKEAWESOMETHINGSMELISSA DRAPERKIWIPYCON 2012

flickr.com/photos/schristia/4366659009/

A story of 3 users.

Jack found a useful sounding tool...

...but can't figure it out.

Jack looks for documentation

A lack of documentation is

bad.

Jill found a useful sounding tool too.

It has documentation!

So she will use it.

Good documentation tells people how to use

your product.

Jaques found a useful tool too

¿Qué?

Excellent documentation is

available for everyone.

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

thought

Open Source Eportfolio

Students and Educators

Comprehensiveuser manual.

In English.

Requirements:

Low learning curvefor translators.

One set of rST source

(per software version)

Images need to be translated too!

Support multiple non-latin scripts

(and unicode symbols)

OOB Sphinx does not really do this!

(it kind of does Japanese)

p.s. Really, nothing does all this

How to make Sphinx do magic?

Makefile-driven

Get the translations:

Automagically import translations

Launchpad↓

msgfmt↓

Sphinx (via gettext)

Swap to XeLaTeX:

Good old fashioned patching

ಠ_ಠ

General patches

Locale patches

Unsupported locales

Localised images:

Localised imagesgit submodule

Copy images overbefore each build.

Standardise DPI

$(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).

patch; \make -C $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) all-pdf-ja; \patch -R --directory=$(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA) -p1 < $(BUILDDIR)/latex/$(TRANSLATION)/$(MAHARA)/$(TRANSLATION).

patch \;)$(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

gitorious.org/mahara/manual

Disclaimer: Not perfected yet.