Presentation held in the seminar on "Development Processes in Open Source Projects." Features the documentation tool Sphinx and its internationalization component sphinx-i18n, along with general insights to Open Source communities and technical details about gettext, Docutils, ReStructuredText, and Google's Summer of Code. Also fixed lotsa bugs in sphinx-i18n. :-)

1. 1 sphinx-i18n The True Story robertlehmann.de Development Processes in Open Source Projects

2. ocumentclass{manual}sepackage[T1]{fontenc}sepackage{textcomp}itle{PythonTutorial}nput{boilerplate}akeindexegin{document}aketitlefhtmlhapter*{FrontMatterabel{front}}input{copyright}egin{abstract}oindent For a description of standard objects and modules, see the itetitle[../lib/lib.html]{Python Library Reference} document. The itetitle[../ref/ref.html]{Python Reference Manual} gives a more formal definition of the language. To write extensions in C or pp, read itetitle[../ext/ext.html]{Extending and Embedding the Python Interpreter} and itetitle[../api/api.html]{Python/C API Reference}. There are also several books covering Python in depth. nd{abstract} ableofcontents hapter{Whetting Your Appetite abel{intro}} Python enables programs to be written compactly and readably. Programs written in Python are typically much shorter than equivalent C, pp{}, or Java programs, for several reasons:egin{itemize}tem the high-level data types allow you to express complex operations in a single statement;tem statement grouping is done by indentation;tem no variable or argument declarations are necessary.nd{itemize} On Windows machines, the Python installation is usually placed in ile{C: Python24}, though you can change this when you're running the installer: egin{verbatim} set path=%path%; C:ython24nd{verbatim}egin{seealso}eetitle[../lib/typesseq.html]{Sequence Types}%{Strings, and the Unicode strings described in the next section, are examples of mph{sequence types}, and support the common operations supported by such types.}nd{seealso}ubsection{Unicode Strings abel{unicodeStrings}}ectionauthor{Marc-Andre Lemburg}{mal@ lemburg.com}egin{methoddesc}[list]{pop}{ptional{i}}If no index is specified, ode{a.pop()} removes and returns the last item in the list. You will see this notation frequently in the itetitle[../lib/lib.html]{Python Library Reference}.)nd{methoddesc} Everbodyhates it with a passion. 2

3. GSoC ReST Docutils gettext Sphinx Issue #653 to the rescue! 3

4. implemented June 2007 as py-rest-docfor Docutils live August 2007 on docs.python.org released March 2008 as Sphinx BSD license requires attribution 1.0 in July 2010 1.0.7 in January 2011 latest stable release 3290 commits[as of 2011/05/15] 4

5. Docutils tutorial.rst "reST" is **ONE** word, *not two!* tutorial "reST" isONE word, not two! 5 Check out http://docutils.sf.net/docs/user/rst/quickstart.html for details!

6. math rendering markup domains search indices feedback syntax highlighting tutorial.rst "reST" is **ONE** word, *not two!* tutorial.pdf tutorial.html tutorial.tex tutorial.1.gz tutorial.epub i18n ... autodoc themes Hierarchical structure: easy definition of a document tree, with automatic links to siblings, parents and children doctests 6

7. Georg “birkenfeld” Brandl 2004: Pocoo project the makers of Werkzeug, Pygments, Jinja, … 2008: PSF Community Award 2011: Frank Willison Award 205k churns [as of 2011/06/27] 2500 commits that‘s changed LOCs without bfb5b73af019, e88201ce226b, and 2d7e85e0c7b4, which imported the Python docs 7

8. Daniel Neuhäuser Jacob Mason Japanese community Armin Ronacher …and about 70 others! http://sphinx-users.jp/event/20100724_release_party.html http://flickr.com/photos/bastispicks/3911044033 8

9. Who’s using it All logos and trademarks are © Copyright their respective owners. 9

10. bitbucket.org/birkenfeld/sphinx Github for Mercurial 10

11. groups.google.com/groups/sphinx-dev sphinx-dev mailing list 11

12. gsoc.robertlehmann.de © 2010 Google Open Source Programs Office 12

13. 13 gsoc.robertlehmann.de umbrellaorganisation © 2010 Google Open Source Programs Office

14. 14 © 2010 Google Open Source Programs Office, http://socghop.appspot.com/document/show/gsoc_program/google/gsoc2010/timeline

15. pootle.python.org 15 Sphinx Native Language Support: Toolchain for Creating, Tracking and Viewing Internationalized Versions of Sphinx Documents

16. cool story, bro. ? but what is this internationalization you are talking about enter gettext! 16

17. gettext 0106 #include <libintl.h> 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956dfaerror("out of memory"); 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956dfaerror(_("out of memory")); dfa.c - deterministic extended regexp routines for GNU gettext(3) usually aliased as _ ftp://mirrors.kernel.org/gnu/grep/grep-2.5.1.tar.bz2 17

18. gettext dfa.c 2954 char *lcopy = malloc(len); 2955 if (!lcopy) 2956dfaerror(_("out of memory")); xgettext grep.pot #: src/dfa.c:2956 msgid "out of memory" msgstr "" 18

19. gettext grep.po #: src/dfa.c:2956 msgid "out of memory" msgstr msginit "Speicheristalle." "" http://translationproject.org/PO-files/de/grep-2.5.de.po 19

20. gettext grep.po #: src/dfa.c:2956 msgid "out of memory" msgstr "Speicheristalle." msgfmt grep.mo 20

21. gettext /usr/share/locale/de/LC_MESSAGES/grep.mo grep.mo LANG=de grep.c 1346#if defined(ENABLE_NLS) 1347bindtextdomain("grep", "/usr/share/locale") 1348textdomain("grep"); 1349#endif bindtextdomain(3) – set directory containing message catalogs textdomain(3) – set domain for gettext() calls 21

22. *gasp* Cool. What else? internationalization is hard,let’s go shopping 22

23. gettext interpolation 873 if (not_text) 874printf (_("Binary file %s matches"), 875 filename); grep.c – main driver file for grep #: src/grep.c:874 #, c-format msgid "Binary file: %s matches" msgstr "" "ÜbereinstimmungeninBinärdatei %s" http://translationproject.org/PO-files/de/grep-2.5.de.po 23

24. gettext plural forms 219 x = ngettext("There is %s file", 220"There are %s files", n) test_gettext.py, CPython Plural-Forms:nplurals=2; plural=n!=1 msgid "There is %s file" msgid_plural "There are %s files" msgstr[0] "Hay %s fichero" msgstr[1] "Hay %s ficheros" 24

25. gettext comments 751/* --option */ 752printf(_("unrecognized option")); lib/getopt.c #. --option #: lib/getopt.c:752 msgid "unrecognized option" msgstr "" 25

26. awesome! but… how does it work in Sphinx? enter sphinx-i18n 26

27. replaces xgettext replaces libintl.h http://sphinx.pocoo.org/latest/intl.html 27

28. d.hatena.ne.jp/rudi/20110202/1296632643 Shirou Wakayama actuallytriedtoi18n the Sphinx 28

29. 29 messages are scrambled (sorry, my Japanese is horrible)

30. Ian Lewis @ PyConMini.JP slideshare.net/Ianmlewis/Sphinx-11-I18N 30

31. ? you are doing it wrong http://www.flickr.com/photos/iirraa/141120311/ 31

32. 32

33. Pull request @mtlpython We’ve just fixed a problem in the gettext builder. Pull request @shibu I'd like to create patch for Internationalization feature for 1.1. Pull request @r_rudi Hello, I write the gettext builder patch. Please check and merge if fair enough. Pull request @kou I hereby encourage you to pull some changes in my fork of sphinx. You can find my changes on the i18n-generate-valid-pot branch. messages snipped 33

34. let‘s call it a day all work has already been done! not quite:the dreaded merge 34

35. 35 releasethe kraken octomerge of sorts literally 8 different sources! http://www.flickr.com/photos/kfisto/1926477413

36. 36 merged by Georg

37. 37 cower, mere mortals here comes the merge resolver Georg Brandl http://www.flickr.com/photos/pasukaru76/4293395231/

38. thanks. questions? I’m that stargaming guy. #pocoo on Freenode sphinx.pocoo.org 38