Documentation translation: first patch

[John Mandereau]

Hello,

Here's (finally) my first patch against stable/2.10 git head for the
documentation build infrastructure.

It includes:

- French translation of the tutorial, which is up-to-date according to
checking against the revision history of English tutorial.itely.

- Documentation/po: directory for po files, used to translate all node
names and section titles.
'make po-update' in that directory updates lilypond-doc.pot and all
existing po files

- Documentation/GNUmakefile: new target new-lang.
        [<source dir>/Documentation]$ make ISOLANG=ab new-lang
creates po/ab.po, and a skeleton of the user manual in ab/user. I've
successfully tested it, and have used it for the French translation.

- buildscripts/texi-langutils.py, html-gettext.py: scripts used to
gettext node names and section titles in Texinfo docs.

- make/doc-lang/*.make: makefiles used for translated documentation.
Maybe they should be stepmake templates instead, but it it'd be more
difficult for me.
I've tested:
  * afer 'make web' at root:
        [<source dir>/Documentation/fr/user]$ make out=www local-WWW
        [<source dir>/Documentation/fr/user]$ make out=www web-clean
  * at root, after 'make web-clean', 'make web' with 'fr' included in
Documentation/GNUmakefile SUBDIRS runs successfully.
However, in <source dir>/out-www/web-root/, there are some undesirable
files: Documentation/po/out-www and Documentation/fr/user/out-www
shouldn't be copied there.
Besides that and the missing png snippets in HTML output, evryting works
fine, including the gettext trickery.


Here's a possible devel to-do list:
     1. make png snippets in translated documentation work;
     2. make new-lang from Documentation and po-update from
        Documentation/po callable from top of the source tree
     3. rewrite GNUmakefile.in:local-WWW-post;
     4. write documentation for translators (like TRANSLATION in
        lilypond.org sources)
     5. change/create makefiles to translate topdocs and index.html.in;
     6. take check-translation.py from lilypond.org sources;
     7. change makefiles to generate pdf user manual.

1. might be hairy, I haven't been able to see yet why png snippets are
missing, so it'd be very nice from you to take a look into it.


Regarding 3, I'm thinking of a DOC-TARGETS makefile variable, which
value would be a subset of {online-i11l, ondisk-i11l, localized} and
would default to ondisk-i11l. (i11l = international) Each of these 3
values would be a specific documentation tree target; these targets
would only differ by the HTML files.

In 'ondisk-i11l', HTML pages have 'Other languages: ...' footers, and
translated pages links point to existing translated pages, otherwise to
English pages. This target could be rolled into a tarball for on-disk
reading of the docs, be used by develepors to check output of 'make
web', or be used by translators to check translation against English
docs.

In 'online-i11l', HTML pages have 'Other languages: ...\nAbout automatic
language selection' footers, and '.html' and '.png' extensions are
stripped from all links. Of course, this target would be for
lilypond.org online docs.

In 'localized', a documentation tree is created for each language. In
each tree, there is only one language for each HTML page (the
translation if existing, otherwise English). No specific footer is
added, and HTML links don't need too be changed according to the way
they are generated with my patch.

This target would be used by the packager to get one docs tarball per
language.

If you agree with this plan, and if you don't find my Python coding too
ugly, I'm going to rewrite add-html-footer.py.


As 2.10 is released now, I think I can now wake up all French
translators to work on the user manual again.

Finally, congratulations about the gitted check-translation.py! It's
much easier to maintain lilypond.org translation than with cvs.

Cheers,
-- 
John Mandereau <address@hidden>

fr-doc.patch.gz
Description: GNU Zip compressed data