diff options
Diffstat (limited to 'src/engine/SCons/Tool/xgettext.xml')
| -rw-r--r-- | src/engine/SCons/Tool/xgettext.xml | 288 |
1 files changed, 288 insertions, 0 deletions
diff --git a/src/engine/SCons/Tool/xgettext.xml b/src/engine/SCons/Tool/xgettext.xml new file mode 100644 index 0000000..ec37ad1 --- /dev/null +++ b/src/engine/SCons/Tool/xgettext.xml @@ -0,0 +1,288 @@ +<!-- +Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011, 2012 The SCons Foundation + +This file is processed by the bin/SConsDoc.py module. +See its __doc__ string for a discussion of the format. +--> +<tool name="xgettext"> +<summary> +This scons tool is a part of scons &t-link-gettext; toolset. It provides +scons interface to <command>xgettext(1)</command> +program, which extracts internationalized messages from source code. The tool +provides &b-POTUpdate; builder to make <literal>PO</literal> +<emphasis>Template</emphasis> files. +</summary> +<sets> +POTSUFFIX +POTUPDATE_ALIAS +XGETTEXTCOM +XGETTEXTCOMSTR +XGETTEXTFLAGS +XGETTEXTFROM +XGETTEXTFROMPREFIX +XGETTEXTFROMSUFFIX +XGETTEXTPATH +XGETTEXTPATHPREFIX +XGETTEXTPATHSUFFIX +_XGETTEXTDOMAIN +_XGETTEXTFROMFLAGS +_XGETTEXTPATHFLAGS +</sets> +<uses> +POTDOMAIN +</uses> +</tool> + +<builder name="POTUpdate"> +<summary> +The builder belongs to &t-link-xgettext; tool. The builder updates target +<literal>POT</literal> file if exists or creates one if it doesn't. The node is +not built by default (i.e. it is <literal>Ignore</literal>d from +<literal>'.'</literal>), but only on demand (i.e. when given +<literal>POT</literal> file is required or when special alias is invoked). This +builder adds its targe node (<filename>messages.pot</filename>, say) to a +special alias (<literal>pot-update</literal> by default, see +&cv-link-POTUPDATE_ALIAS;) so you can update/create them easily with +<command>scons pot-update</command>. The file is not written until there is no +real change in internationalized messages (or in comments that enter +<literal>POT</literal> file). + +<note> <para>You may see <command>xgettext(1)</command> being invoked by the +&t-link-xgettext; tool even if there is no real change in internationalized +messages (so the <literal>POT</literal> file is not being updated). This +happens every time a source file has changed. In such case we invoke +<command>xgettext(1)</command> and compare its output with the content of +<literal>POT</literal> file to decide whether the file should be updated or +not.</para></note> + +<emphasis>Example 1.</emphasis> +Let's create <filename>po/</filename> directory and place following +<filename>SConstruct</filename> script there: +<example> + # SConstruct in 'po/' subdir + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp']) + env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp']) +</example> +Then invoke scons few times: +<example> + user@host:$ scons # Does not create foo.pot nor bar.pot + user@host:$ scons foo.pot # Updates or creates foo.pot + user@host:$ scons pot-update # Updates or creates foo.pot and bar.pot + user@host:$ scons -c # Does not clean foo.pot nor bar.pot. +</example> +the results shall be as the comments above say. + +<emphasis>Example 2.</emphasis> +The &b-POTUpdate; builder may be used with no target specified, in which +case default target <filename>messages.pot</filename> will be used. The +default target may also be overriden by setting &cv-link-POTDOMAIN; construction +variable or providing it as an override to &b-POTUpdate; builder: +<example> + # SConstruct script + env = Environment( tools = ['default', 'xgettext'] ) + env['POTDOMAIN'] = "foo" + env.POTUpdate(source = ["a.cpp", "b.cpp"]) # Creates foo.pot ... + env.POTUpdate(POTDOMAIN = "bar", source = ["c.cpp", "d.cpp"]) # and bar.pot +</example> + +<emphasis>Example 3.</emphasis> +The sources may be specified within separate file, for example +<filename>POTFILES.in</filename>: +<example> + # POTFILES.in in 'po/' subdirectory + ../a.cpp + ../b.cpp + # end of file +</example> +The name of the file (<filename>POTFILES.in</filename>) containing the list of +sources is provided via &cv-link-XGETTEXTFROM;: +<example> + # SConstruct file in 'po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in') +</example> + +<emphasis>Example 4.</emphasis> +You may use &cv-link-XGETTEXTPATH; to define source search path. Assume, for +example, that you have files <filename>a.cpp</filename>, +<filename>b.cpp</filename>, <filename>po/SConstruct</filename>, +<filename>po/POTFILES.in</filename>. Then your <literal>POT</literal>-related +files could look as below: +<example> + # POTFILES.in in 'po/' subdirectory + a.cpp + b.cpp + # end of file +</example> + +<example> + # SConstruct file in 'po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../') +</example> + +<emphasis>Example 5.</emphasis> +Multiple search directories may be defined within a list, i.e. +<literal>XGETTEXTPATH = ['dir1', 'dir2', ...]</literal>. The order in the list +determines the search order of source files. The path to the first file found +is used. + +Let's create <filename>0/1/po/SConstruct</filename> script: +<example> + # SConstruct file in '0/1/po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../']) +</example> +and <filename>0/1/po/POTFILES.in</filename>: +<example> + # POTFILES.in in '0/1/po/' subdirectory + a.cpp + # end of file +</example> +Write two <filename>*.cpp</filename> files, the first one is +<filename>0/a.cpp</filename>: +<example> + /* 0/a.cpp */ + gettext("Hello from ../../a.cpp") +</example> +and the second is <filename>0/1/a.cpp</filename>: +<example> + /* 0/1/a.cpp */ + gettext("Hello from ../a.cpp") +</example> +then run scons. You'll obtain <literal>0/1/po/messages.pot</literal> with the +message <literal>"Hello from ../a.cpp"</literal>. When you reverse order in +<varname>$XGETTEXTFOM</varname>, i.e. when you write SConscript as +<example> + # SConstruct file in '0/1/po/' subdirectory + env = Environment( tools = ['default', 'xgettext'] ) + env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../']) +</example> then the <filename>messages.pot</filename> will contain +<literal>msgid "Hello from ../../a.cpp"</literal> line and not +<literal>msgid "Hello from ../a.cpp"</literal>. + +</summary> + +</builder> + +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="POTSUFFIX"> +<summary> +Suffix used for PO Template files (default: <literal>'.pot'</literal>). +See &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="POTUPDATE_ALIAS"> +<summary> +Name of the common phony target for all PO Templates created with +&b-link-POUpdate; (default: <literal>'pot-update'</literal>). +See &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXT"> +<summary> +Path to <command>xgettext(1)</command> program (found via +<function>Detect()</function>). +See &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTCOM"> +<summary> +Complete xgettext command line. +See &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTCOMSTR"> +<summary> +A string that is shown when <command>xgettext(1)</command> command is invoked +(default: <literal>''</literal>, which means "print &cv-link-XGETTEXTCOM;"). +See &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTFLAGS"> +<summary> +Additional flags to <command>xgettext(1)</command>. +See &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTFROM"> +<summary> +Name of file containing list of <command>xgettext(1)</command>'s source +files. Autotools' users know this as <filename>POTFILES.in</filename> so they +will in most cases set <literal>XGETTEXTFROM="POTFILES.in"</literal> here. +The &cv-XGETTEXTFROM; files have same syntax and semantics as the well known +GNU <filename>POTFILES.in</filename>. +See &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTPATH"> +<summary> +List of directories, there <command>xgettext(1)</command> will look for +source files (default: <literal>[]</literal>). +<note><para> +This variable works only together with &cv-link-XGETTEXTFROM; +</para></note> +See also &t-link-xgettext; tool and &b-link-POTUpdate; builder. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTPATHPREFIX"> +<summary> +This flag is used to add single search path to +<command>xgettext(1)</command>'s commandline (default: +<literal>'-D'</literal>). +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTPATHSUFFIX"> +<summary> +(default: <literal>''</literal>) +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTFROMPREFIX"> +<summary> +This flag is used to add single &cv-link-XGETTEXTFROM; file to +<command>xgettext(1)</command>'s commandline (default: +<literal>'-f'</literal>). +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="XGETTEXTFROMSUFFIX"> +<summary> +(default: <literal>''</literal>) +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="_XGETTEXTDOMAIN"> +<summary> +Internal "macro". Generates <command>xgettext</command> domain name +form source and target (default: <literal>'${TARGET.filebase}'</literal>). +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="_XGETTEXTFROMFLAGS"> +<summary> +Internal "macro". Genrates list of <literal>-D<dir></literal> flags +from the &cv-link-XGETTEXTPATH; list. +</summary> +</cvar> +<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% --> +<cvar name="_XGETTEXTPATHFLAGS"> +<summary> +Internal "macro". Generates list of <literal>-f<file></literal> flags +from &cv-link-XGETTEXTFROM;. +</summary> +</cvar> + +<!-- + +--> |