From 3d529f4ea2b0de42aa2144dbe904e564b7b0b813 Mon Sep 17 00:00:00 2001 From: Luca Falavigna Date: Mon, 20 Aug 2012 23:30:34 +0200 Subject: Imported Upstream version 2.2.0 --- doc/SConscript | 2 +- doc/design/scons.mod | 2 +- doc/developer/architecture.xml | 2 +- doc/developer/branches.xml | 2 +- doc/developer/copyright.xml | 2 +- doc/developer/cycle.xml | 2 +- doc/developer/main.xml | 2 +- doc/developer/packaging.xml | 2 +- doc/developer/preface.xml | 2 +- doc/developer/sourcetree.xml | 2 +- doc/developer/testing.xml | 2 +- doc/man/scons-time.1 | 6 +- doc/man/scons.1 | 6 +- doc/man/sconsign.1 | 6 +- doc/python10/scons.mod | 2 +- doc/scons.mod | 2 +- doc/user/MANIFEST | 1 + doc/user/README | 2 +- doc/user/actions.in | 2 +- doc/user/actions.xml | 2 +- doc/user/add-method.in | 4 +- doc/user/add-method.xml | 4 +- doc/user/alias.in | 2 +- doc/user/alias.xml | 2 +- doc/user/ant.in | 2 +- doc/user/ant.xml | 2 +- doc/user/build-install.in | 20 +-- doc/user/build-install.xml | 20 +-- doc/user/builders-built-in.in | 2 +- doc/user/builders-built-in.xml | 2 +- doc/user/builders-commands.in | 2 +- doc/user/builders-commands.xml | 2 +- doc/user/builders-writing.in | 8 +- doc/user/builders-writing.xml | 8 +- doc/user/builders.in | 2 +- doc/user/builders.xml | 2 +- doc/user/caching.in | 2 +- doc/user/caching.xml | 2 +- doc/user/command-line.in | 32 +++- doc/user/command-line.xml | 32 +++- doc/user/copyright.in | 2 +- doc/user/copyright.xml | 2 +- doc/user/depends.in | 10 +- doc/user/depends.xml | 10 +- doc/user/environments.in | 8 +- doc/user/environments.xml | 8 +- doc/user/errors.in | 2 +- doc/user/errors.xml | 2 +- doc/user/example.in | 2 +- doc/user/example.xml | 2 +- doc/user/factories.in | 2 +- doc/user/factories.xml | 2 +- doc/user/file-removal.in | 2 +- doc/user/file-removal.xml | 2 +- doc/user/functions.in | 2 +- doc/user/functions.xml | 2 +- doc/user/gettext.in | 351 +++++++++++++++++++++++++++++++++++++++++ doc/user/gettext.xml | 334 +++++++++++++++++++++++++++++++++++++++ doc/user/hierarchy.in | 4 +- doc/user/hierarchy.xml | 4 +- doc/user/install.in | 2 +- doc/user/install.xml | 2 +- doc/user/java.in | 2 +- doc/user/java.xml | 2 +- doc/user/less-simple.in | 2 +- doc/user/less-simple.xml | 2 +- doc/user/libraries.in | 2 +- doc/user/libraries.xml | 2 +- doc/user/main.in | 8 +- doc/user/main.xml | 8 +- doc/user/make.in | 2 +- doc/user/make.xml | 2 +- doc/user/mergeflags.in | 2 +- doc/user/mergeflags.xml | 2 +- doc/user/misc.in | 2 +- doc/user/misc.xml | 2 +- doc/user/nodes.in | 2 +- doc/user/nodes.xml | 2 +- doc/user/output.in | 2 +- doc/user/output.xml | 2 +- doc/user/parseconfig.in | 2 +- doc/user/parseconfig.xml | 2 +- doc/user/parseflags.in | 2 +- doc/user/parseflags.xml | 2 +- doc/user/preface.in | 2 +- doc/user/preface.xml | 2 +- doc/user/python.in | 2 +- doc/user/python.xml | 2 +- doc/user/repositories.in | 2 +- doc/user/repositories.xml | 2 +- doc/user/run.in | 2 +- doc/user/run.xml | 2 +- doc/user/scanners.in | 2 +- doc/user/scanners.xml | 2 +- doc/user/sconf.in | 2 +- doc/user/sconf.xml | 2 +- doc/user/separate.in | 2 +- doc/user/separate.xml | 2 +- doc/user/sideeffect.in | 2 +- doc/user/sideeffect.xml | 2 +- doc/user/simple.in | 6 +- doc/user/simple.xml | 6 +- doc/user/sourcecode.in | 2 +- doc/user/sourcecode.xml | 2 +- doc/user/tasks.in | 2 +- doc/user/tasks.xml | 2 +- doc/user/tools.in | 2 +- doc/user/tools.xml | 2 +- doc/user/troubleshoot.in | 2 +- doc/user/troubleshoot.xml | 2 +- doc/user/variables.in | 2 +- doc/user/variables.xml | 2 +- doc/user/variants.in | 2 +- doc/user/variants.xml | 2 +- 114 files changed, 909 insertions(+), 175 deletions(-) create mode 100644 doc/user/gettext.in create mode 100644 doc/user/gettext.xml (limited to 'doc') diff --git a/doc/SConscript b/doc/SConscript index 54b620e..1206e6f 100644 --- a/doc/SConscript +++ b/doc/SConscript @@ -3,7 +3,7 @@ # # -# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 The SCons Foundation # # Permission is hereby granted, free of charge, to any person obtaining # a copy of this software and associated documentation files (the diff --git a/doc/design/scons.mod b/doc/design/scons.mod index 33538fb..d059d71 100644 --- a/doc/design/scons.mod +++ b/doc/design/scons.mod @@ -1,6 +1,6 @@ + + + The &t-link-gettext; toolset supports internationalization and localization + of SCons-based projects. Builders provided by &t-link-gettext; automatize + generation and updates of translation files. You can manage translations and + translation templates similarly to how it's done with autotools. + + +
+ Prerequisites + + To follow examples provided in this chapter set up your operating system to + support two or more languages. In following examples we use locales + en_US, de_DE, and + pl_PL. + + + + Ensure, that you have GNU gettext + utilities installed on your system. + + + + To edit translation files you may wish to install poedit editor. + +
+ +
+ Simple project + + Let's start with a very simple project, the "Hello world" program + for example + + + /* hello.c */ + #include <stdio.h> + int main(int argc, char* argv[]) + { + printf("Hello world\n"); + return 0; + } + + + + Prepare a SConstruct to compile the program + as usual. + + + # SConstruct + env = Environment() + hello = Program(["hello.c"]) + + + + + + Now we'll convert the project to a multi-lingual one. If you don't + already have GNU gettext + utilities installed, install them from your preffered + package repository, or download from + http://ftp.gnu.org/gnu/gettext/. For the purpose of this example, + you should have following three locales installed on your system: + en_US, de_DE and + pl_PL. On debian, for example, you may enable certain + locales through dpkg-reconfigure locales. + + + + First prepare the hello.c program for + internationalization. Change the previous code so it reads as follows: + + + /* hello.c */ + #include <stdio.h> + #include <libintl.h> + #include <locale.h> + int main(int argc, char* argv[]) + { + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + return 0; + } + + + Detailed recipes for such conversion can + be found at + http://www.gnu.org/software/gettext/manual/gettext.html#Sources. + The gettext("...") has two purposes. + First, it marks messages for the xgettext(1) program, which + we will use to extract from the sources the messages for localization. + Second, it calls the gettext library internals to + translate the message at runtime. + + + + Now we shall instruct SCons how to generate and maintain translation files. + For that, use the &b-link-Translate; builder and &b-link-MOFiles; builder. + The first one takes source files, extracts internationalized + messages from them, creates so-called POT file + (translation template), and then creates PO translation + files, one for each requested language. Later, during the development + lifecycle, the builder keeps all these files up-to date. The + &b-link-MOFiles; builder compiles the PO files to binary + form. Then install the MO files under directory + called locale. + + + The completed + SConstruct is as follows: + + + # SConstruct + env = Environment( tools = ['default', 'gettext'] ) + hello = env.Program(["hello.c"]) + env['XGETTEXTFLAGS'] = [ + '--package-name=%s' % 'hello', + '--package-version=%s' % '1.0', + ] + po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1) + mo = env.MOFiles(po) + InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"]) + InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"]) + InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"]) + + + + + Generate the translation files with scons po-update. + You should see the output from SCons simillar to this: + + user@host:$ scons po-update + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + Entering '/home/ptomulik/projects/tmp' + xgettext --package-name=hello --package-version=1.0 -o - hello.c + Leaving '/home/ptomulik/projects/tmp' + Writting 'messages.pot' (new file) + msginit --no-translator -l pl -i messages.pot -o pl.po + Created pl.po. + msginit --no-translator -l en -i messages.pot -o en.po + Created en.po. + msginit --no-translator -l de -i messages.pot -o de.po + Created de.po. + scons: done building targets. + + + + + If everything is right, you should see following new files. + + user@host:$ ls *.po* + de.po en.po messages.pot pl.po + + + + + Open en.po in poedit and provide + the English translation to message "Hello world\n". Do the + same for de.po (deutsch) and + pl.po (polish). Let the translations be, for example: + + + en: "Welcome to beautiful world!\n" + + + de: "Hallo Welt!\n" + + + pl: "Witaj swiecie!\n" + + + + + Now compile the project by executing scons. The + output should be similar to this: + + user@host:$ scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + msgfmt -c -o de.mo de.po + msgfmt -c -o en.mo en.po + gcc -o hello.o -c hello.c + gcc -o hello hello.o + Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" + Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" + msgfmt -c -o pl.mo pl.po + Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" + scons: done building targets. + + SCons automatically compiled the PO files to binary format + MO, and the InstallAs lines installed + these files under locale folder. + + + Your program should be now ready. You may try it as follows (linux): + + user@host:$ LANG=en_US.UTF-8 ./hello + Welcome to beautiful world + + + user@host:$ LANG=de_DE.UTF-8 ./hello + Hallo Welt + + + user@host:$ LANG=pl_PL.UTF-8 ./hello + Witaj swiecie + + + + To demonstrate the further life of translation files, let's change Polish + translation (poedit pl.po) to "Witaj drogi + swiecie\n". Run scons to see how scons + reacts to this + + user@host:$scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + msgfmt -c -o pl.mo pl.po + Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" + scons: done building targets. + + + + Now, open hello.c and add another one + printf line with new message. + + + /* hello.c */ + #include <stdio.h> + #include <libintl.h> + #include <locale.h> + int main(int argc, char* argv[]) + { + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + return 0; + } + + + + + Compile project with scons. This time, the + msgmerge(1) program is used by SCons to update + PO file. The output from compilation is like: + + user@host:$scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + Entering '/home/ptomulik/projects/tmp' + xgettext --package-name=hello --package-version=1.0 -o - hello.c + Leaving '/home/ptomulik/projects/tmp' + Writting 'messages.pot' (messages in file were outdated) + msgmerge --update de.po messages.pot + ... done. + msgfmt -c -o de.mo de.po + msgmerge --update en.po messages.pot + ... done. + msgfmt -c -o en.mo en.po + gcc -o hello.o -c hello.c + gcc -o hello hello.o + Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" + Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" + msgmerge --update pl.po messages.pot + ... done. + msgfmt -c -o pl.mo pl.po + Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" + scons: done building targets. + + + + The next example demonstrates what happens if we change the source code + in such way that the internationalized messages do not change. The answer + is that none of translation files (POT, + PO) are touched (i.e. no content changes, no + creation/modification time changed and so on). Let's append another + line to the program (after the last printf), so its code becomes: + + + /* hello.c */ + #include <stdio.h> + #include <libintl.h> + #include <locale.h> + int main(int argc, char* argv[]) + { + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + printf("----------------\n"); + return a; + } + + + Compile the project. You'll see on your screen + + user@host:$scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + Entering '/home/ptomulik/projects/tmp' + xgettext --package-name=hello --package-version=1.0 -o - hello.c + Leaving '/home/ptomulik/projects/tmp' + Not writting 'messages.pot' (messages in file found to be up-to-date) + gcc -o hello.o -c hello.c + gcc -o hello hello.o + scons: done building targets. + + As you see, the internationalized messages ditn't change, so the + POT and the rest of translation files have not + even been touched. + +
diff --git a/doc/user/gettext.xml b/doc/user/gettext.xml new file mode 100644 index 0000000..ebaf3c0 --- /dev/null +++ b/doc/user/gettext.xml @@ -0,0 +1,334 @@ + + + + The &t-link-gettext; toolset supports internationalization and localization + of SCons-based projects. Builders provided by &t-link-gettext; automatize + generation and updates of translation files. You can manage translations and + translation templates similarly to how it's done with autotools. + + +
+ Prerequisites + + To follow examples provided in this chapter set up your operating system to + support two or more languages. In following examples we use locales + en_US, de_DE, and + pl_PL. + + + + Ensure, that you have GNU gettext + utilities installed on your system. + + + + To edit translation files you may wish to install poedit editor. + +
+ +
+ Simple project + + Let's start with a very simple project, the "Hello world" program + for example + + /* hello.c */ + #include <stdio.h> + int main(int argc, char* argv[]) + { + printf("Hello world\n"); + return 0; + } + + + Prepare a SConstruct to compile the program + as usual. + + # SConstruct + env = Environment() + hello = Program(["hello.c"]) + + + + + Now we'll convert the project to a multi-lingual one. If you don't + already have GNU gettext + utilities installed, install them from your preffered + package repository, or download from + http://ftp.gnu.org/gnu/gettext/. For the purpose of this example, + you should have following three locales installed on your system: + en_US, de_DE and + pl_PL. On debian, for example, you may enable certain + locales through dpkg-reconfigure locales. + + + + First prepare the hello.c program for + internationalization. Change the previous code so it reads as follows: + + /* hello.c */ + #include <stdio.h> + #include <libintl.h> + #include <locale.h> + int main(int argc, char* argv[]) + { + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + return 0; + } + + Detailed recipes for such conversion can + be found at + http://www.gnu.org/software/gettext/manual/gettext.html#Sources. + The gettext("...") has two purposes. + First, it marks messages for the xgettext(1) program, which + we will use to extract from the sources the messages for localization. + Second, it calls the gettext library internals to + translate the message at runtime. + + + + Now we shall instruct SCons how to generate and maintain translation files. + For that, use the &b-link-Translate; builder and &b-link-MOFiles; builder. + The first one takes source files, extracts internationalized + messages from them, creates so-called POT file + (translation template), and then creates PO translation + files, one for each requested language. Later, during the development + lifecycle, the builder keeps all these files up-to date. The + &b-link-MOFiles; builder compiles the PO files to binary + form. Then install the MO files under directory + called locale. + + + The completed + SConstruct is as follows: + + # SConstruct + env = Environment( tools = ['default', 'gettext'] ) + hello = env.Program(["hello.c"]) + env['XGETTEXTFLAGS'] = [ + '--package-name=%s' % 'hello', + '--package-version=%s' % '1.0', + ] + po = env.Translate(["pl","en", "de"], ["hello.c"], POAUTOINIT = 1) + mo = env.MOFiles(po) + InstallAs(["locale/en/LC_MESSAGES/hello.mo"], ["en.mo"]) + InstallAs(["locale/pl/LC_MESSAGES/hello.mo"], ["pl.mo"]) + InstallAs(["locale/de/LC_MESSAGES/hello.mo"], ["de.mo"]) + + + + Generate the translation files with scons po-update. + You should see the output from SCons simillar to this: + + user@host:$ scons po-update + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + Entering '/home/ptomulik/projects/tmp' + xgettext --package-name=hello --package-version=1.0 -o - hello.c + Leaving '/home/ptomulik/projects/tmp' + Writting 'messages.pot' (new file) + msginit --no-translator -l pl -i messages.pot -o pl.po + Created pl.po. + msginit --no-translator -l en -i messages.pot -o en.po + Created en.po. + msginit --no-translator -l de -i messages.pot -o de.po + Created de.po. + scons: done building targets. + + + + + If everything is right, you should see following new files. + + user@host:$ ls *.po* + de.po en.po messages.pot pl.po + + + + + Open en.po in poedit and provide + the English translation to message "Hello world\n". Do the + same for de.po (deutsch) and + pl.po (polish). Let the translations be, for example: + + + en: "Welcome to beautiful world!\n" + + + de: "Hallo Welt!\n" + + + pl: "Witaj swiecie!\n" + + + + + Now compile the project by executing scons. The + output should be similar to this: + + user@host:$ scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + msgfmt -c -o de.mo de.po + msgfmt -c -o en.mo en.po + gcc -o hello.o -c hello.c + gcc -o hello hello.o + Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" + Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" + msgfmt -c -o pl.mo pl.po + Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" + scons: done building targets. + + SCons automatically compiled the PO files to binary format + MO, and the InstallAs lines installed + these files under locale folder. + + + Your program should be now ready. You may try it as follows (linux): + + user@host:$ LANG=en_US.UTF-8 ./hello + Welcome to beautiful world + + + user@host:$ LANG=de_DE.UTF-8 ./hello + Hallo Welt + + + user@host:$ LANG=pl_PL.UTF-8 ./hello + Witaj swiecie + + + + To demonstrate the further life of translation files, let's change Polish + translation (poedit pl.po) to "Witaj drogi + swiecie\n". Run scons to see how scons + reacts to this + + user@host:$scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + msgfmt -c -o pl.mo pl.po + Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" + scons: done building targets. + + + + Now, open hello.c and add another one + printf line with new message. + + /* hello.c */ + #include <stdio.h> + #include <libintl.h> + #include <locale.h> + int main(int argc, char* argv[]) + { + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + return 0; + } + + + + Compile project with scons. This time, the + msgmerge(1) program is used by SCons to update + PO file. The output from compilation is like: + + user@host:$scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + Entering '/home/ptomulik/projects/tmp' + xgettext --package-name=hello --package-version=1.0 -o - hello.c + Leaving '/home/ptomulik/projects/tmp' + Writting 'messages.pot' (messages in file were outdated) + msgmerge --update de.po messages.pot + ... done. + msgfmt -c -o de.mo de.po + msgmerge --update en.po messages.pot + ... done. + msgfmt -c -o en.mo en.po + gcc -o hello.o -c hello.c + gcc -o hello hello.o + Install file: "de.mo" as "locale/de/LC_MESSAGES/hello.mo" + Install file: "en.mo" as "locale/en/LC_MESSAGES/hello.mo" + msgmerge --update pl.po messages.pot + ... done. + msgfmt -c -o pl.mo pl.po + Install file: "pl.mo" as "locale/pl/LC_MESSAGES/hello.mo" + scons: done building targets. + + + + The next example demonstrates what happens if we change the source code + in such way that the internationalized messages do not change. The answer + is that none of translation files (POT, + PO) are touched (i.e. no content changes, no + creation/modification time changed and so on). Let's append another + line to the program (after the last printf), so its code becomes: + + /* hello.c */ + #include <stdio.h> + #include <libintl.h> + #include <locale.h> + int main(int argc, char* argv[]) + { + bindtextdomain("hello", "locale"); + setlocale(LC_ALL, ""); + textdomain("hello"); + printf(gettext("Hello world\n")); + printf(gettext("and good bye\n")); + printf("----------------\n"); + return a; + } + + Compile the project. You'll see on your screen + + user@host:$scons + scons: Reading SConscript files ... + scons: done reading SConscript files. + scons: Building targets ... + Entering '/home/ptomulik/projects/tmp' + xgettext --package-name=hello --package-version=1.0 -o - hello.c + Leaving '/home/ptomulik/projects/tmp' + Not writting 'messages.pot' (messages in file found to be up-to-date) + gcc -o hello.o -c hello.c + gcc -o hello hello.o + scons: done building targets. + + As you see, the internationalized messages ditn't change, so the + POT and the rest of translation files have not + even been touched. + +
diff --git a/doc/user/hierarchy.in b/doc/user/hierarchy.in index 950bc8a..855c54a 100644 --- a/doc/user/hierarchy.in +++ b/doc/user/hierarchy.in @@ -1,6 +1,6 @@