From f4d0a235b9a6a5de838fd6a1ea44a4cdbeed7bde Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 20 Sep 2024 08:39:54 -0600 Subject: [PATCH] Clean up manpage entries for gettext and pdf builders [skip appveyor] Minor wording cleanup, formatting for examples, etc. in the gettext-family (inc. msginit, msgformat, msgmerge) and the pdf and dvips builders. No code changes, no test changes. Signed-off-by: Mats Wichmann --- CHANGES.txt | 1 + RELEASE.txt | 2 + SCons/Tool/dvips.xml | 8 +- SCons/Tool/gettext.xml | 145 ++++++++++++++++---------------- SCons/Tool/msgfmt.xml | 57 +++++++------ SCons/Tool/msginit.xml | 107 ++++++++++++------------ SCons/Tool/msgmerge.xml | 113 ++++++++++++------------- SCons/Tool/pdf.xml | 8 +- SCons/Tool/xgettext.xml | 213 ++++++++++++++++++++++++------------------------ 9 files changed, 334 insertions(+), 320 deletions(-) diff --git a/CHANGES.txt b/CHANGES.txt index 8d58fd433..218c0c66e 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -47,6 +47,7 @@ RELEASE VERSION/DATE TO BE FILLED IN LATER Note: on Windows, SCons currently only has builtin support for clang, not for clang-cl, the version of the frontend that uses cl.exe-compatible command line switches. + - Some manpage cleanup for the gettext and pdf/ps builders. RELEASE 4.8.1 - Tue, 03 Sep 2024 17:22:20 -0700 diff --git a/RELEASE.txt b/RELEASE.txt index 785ef953e..cbf061d17 100644 --- a/RELEASE.txt +++ b/RELEASE.txt @@ -77,6 +77,8 @@ DOCUMENTATION typo fixes, even if they're mentioned in src/CHANGES.txt to give the contributor credit) +- Some manpage cleanup for the gettext and pdf/ps builders. + DEVELOPMENT ----------- diff --git a/SCons/Tool/dvips.xml b/SCons/Tool/dvips.xml index 4df22ef19..d8a69e896 100644 --- a/SCons/Tool/dvips.xml +++ b/SCons/Tool/dvips.xml @@ -54,15 +54,17 @@ or The suffix specified by the &cv-link-PSSUFFIX; construction variable (.ps by default) is added automatically to the target -if it is not already present. Example: +if it is not already present. +&b-PostScript; is a single-source builder. +Example: - + # builds from aaa.tex env.PostScript(target = 'aaa.ps', source = 'aaa.tex') # builds bbb.ps from bbb.dvi env.PostScript(target = 'bbb', source = 'bbb.dvi') - + diff --git a/SCons/Tool/gettext.xml b/SCons/Tool/gettext.xml index 160612993..a2b7c9873 100644 --- a/SCons/Tool/gettext.xml +++ b/SCons/Tool/gettext.xml @@ -27,27 +27,27 @@ This file is processed by the bin/SConsDoc.py module. -This is actually a toolset, which supports internationalization and -localization of software being constructed with SCons. The toolset loads -following tools: +A toolset supporting internationalization and +localization of software being constructed with &SCons;. +The toolset loads the following tools: - &t-link-xgettext; - to extract internationalized messages from source code to - POT file(s), + &t-link-xgettext; - extract internationalized messages from source code to + POT file(s). - &t-link-msginit; - may be optionally used to initialize PO - files, + &t-link-msginit; - initialize PO + files during initial tranlation of a project. - &t-link-msgmerge; - to update PO files, that already contain + &t-link-msgmerge; - update PO files that already contain translated messages, - &t-link-msgfmt; - to compile textual PO file to binary - installable MO file. + &t-link-msgfmt; - compile textual PO files to binary + installable MO files. @@ -65,12 +65,12 @@ may be however interested in top-level -To use &t-gettext; tools add 'gettext' tool to your -environment: +To use the &t-gettext; tools, add the 'gettext' tool to your +&consenv;: - - env = Environment( tools = ['default', 'gettext'] ) - + +env = Environment(tools=['default', 'gettext']) + @@ -82,10 +82,11 @@ environment: -This pseudo-builder belongs to &t-link-gettext; toolset. The builder extracts -internationalized messages from source files, updates POT -template (if necessary) and then updates PO translations (if -necessary). If &cv-link-POAUTOINIT; is set, missing PO files +This pseudo-Builder is part of the &t-link-gettext; toolset. +The builder extracts internationalized messages from source files, +updates the POT template (if necessary) +and then updates PO translations (if necessary). +If &cv-link-POAUTOINIT; is set, missing PO files will be automatically created (i.e. without translator person intervention). The variables &cv-link-LINGUAS_FILE; and &cv-link-POTDOMAIN; are taken into acount too. All other construction variables used by &b-link-POTUpdate;, and @@ -95,41 +96,42 @@ acount too. All other construction variables used by &b-link-POTUpdate;, and Example 1. The simplest way is to specify input files and output languages inline in -a SCons script when invoking &b-Translate; +a SCons script when invoking &b-Translate;: - + # SConscript in 'po/' directory -env = Environment( tools = ["default", "gettext"] ) -env['POAUTOINIT'] = 1 -env.Translate(['en','pl'], ['../a.cpp','../b.cpp']) - +env = Environment(tools=["default", "gettext"]) +env['POAUTOINIT'] = True +env.Translate(['en', 'pl'], ['../a.cpp', '../b.cpp']) + Example 2. -If you wish, you may also stick to conventional style known from +If you wish, you may also stick to the conventional style known from autotools, i.e. using POTFILES.in and LINGUAS files +to specify the targets and sources: - + # LINGUAS en pl -#end - +# end + - + # POTFILES.in a.cpp b.cpp # end - + - + # SConscript -env = Environment( tools = ["default", "gettext"] ) -env['POAUTOINIT'] = 1 +env = Environment(tools=["default", "gettext"]) +env['POAUTOINIT'] = True env['XGETTEXTPATH'] = ['../'] -env.Translate(LINGUAS_FILE = 1, XGETTEXTFROM = 'POTFILES.in') - +env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in') + The last approach is perhaps the recommended one. It allows easily split @@ -152,7 +154,7 @@ project in their usual way. Example 3. Let's prepare a development tree as below - + project/ + SConstruct + build/ @@ -162,52 +164,55 @@ Let's prepare a development tree as below + SConscript.i18n + POTFILES.in + LINGUAS - + -with build being variant directory. Write the top-level +with build being the variant directory. +Write the top-level SConstruct script as follows - - # SConstruct - env = Environment( tools = ["default", "gettext"] ) - VariantDir('build', 'src', duplicate = 0) - env['POAUTOINIT'] = 1 - SConscript('src/po/SConscript.i18n', exports = 'env') - SConscript('build/po/SConscript', exports = 'env') - + +# SConstruct +env = Environment(tools=["default", "gettext"]) +VariantDir('build', 'src', duplicate=False) +env['POAUTOINIT'] = True +SConscript('src/po/SConscript.i18n', exports='env') +SConscript('build/po/SConscript', exports='env') + the src/po/SConscript.i18n as - - # src/po/SConscript.i18n - Import('env') - env.Translate(LINGUAS_FILE=1, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) - + +# src/po/SConscript.i18n +Import('env') +env.Translate(LINGUAS_FILE=True, XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../']) + and the src/po/SConscript - - # src/po/SConscript - Import('env') - env.MOFiles(LINGUAS_FILE = 1) - + +# src/po/SConscript +Import('env') +env.MOFiles(LINGUAS_FILE=True) + -Such setup produces POT and PO files -under source tree in src/po/ and binary -MO files under variant tree in +Such a setup produces POT and PO files +under the source tree in src/po/ and binary +MO files under the variant tree in build/po/. This way the POT and PO files are separated from other output files, which must not be committed back to source repositories (e.g. MO files). - -In above example, the PO files are not updated, -nor created automatically when you issue scons '.' command. -The files must be updated (created) by hand via scons -po-update and then MO files can be compiled by -running scons '.'. - +In the above example, +the PO files are not updated, +nor created automatically when you issue the command +scons .. +The files must be updated (created) by hand via +scons po-update +and then MO files can be compiled by +running scons .. + @@ -245,10 +250,10 @@ them). The &cv-LINGUAS_FILE; defines file(s) containing list of additional linguas to be processed by &b-link-POInit;, &b-link-POUpdate; or &b-link-MOFiles; builders. It also affects &b-link-Translate; builder. If the variable contains -a string, it defines name of the list file. The &cv-LINGUAS_FILE; may be a +a string, it defines the name of the list file. The &cv-LINGUAS_FILE; may be a list of file names as well. If &cv-LINGUAS_FILE; is set to -True (or non-zero numeric value), the list will be read from -default file named +a non-string truthy value, the list will be read from +the file named LINGUAS. diff --git a/SCons/Tool/msgfmt.xml b/SCons/Tool/msgfmt.xml index e56c12c41..f92830ff3 100644 --- a/SCons/Tool/msgfmt.xml +++ b/SCons/Tool/msgfmt.xml @@ -27,10 +27,13 @@ This file is processed by the bin/SConsDoc.py module. -This scons tool is a part of scons &t-link-gettext; toolset. It provides scons -interface to msgfmt(1) command, which generates binary -message catalog (MO) from a textual translation description -(PO). +This tool is a part of the &t-link-gettext; toolset. +It provides &SCons; +an interface to the msgfmt(1) command +by setting up the &b-link-MOFiles; builder, +which generates binary message catalog (MO) files +from a textual translation description +(PO files). @@ -49,8 +52,12 @@ message catalog (MO) from a textual translation description -This builder belongs to &t-link-msgfmt; tool. The builder compiles +This builder is set up by the &t-link-msgfmt; tool. +The builder compiles PO files to MO files. +&b-MOFiles; is a single-source builder. +The source parameter +can also be omitted if &cv-link-LINGUAS_FILE; is set. @@ -58,19 +65,17 @@ This builder belongs to &t-link-msgfmt; tool. The builder compiles Create pl.mo and en.mo by compiling pl.po and en.po: - - # ... - env.MOFiles(['pl', 'en']) - + +env.MOFiles(['pl', 'en']) + Example 2. Compile files for languages defined in LINGUAS file: - - # ... - env.MOFiles(LINGUAS_FILE = 1) - + +env.MOFiles(LINGUAS_FILE=True) + Example 3. @@ -78,24 +83,22 @@ Create pl.mo and en.mo by compiling pl.po and en.po plus files for languages defined in LINGUAS file: - - # ... - env.MOFiles(['pl', 'en'], LINGUAS_FILE = 1) - + +env.MOFiles(['pl', 'en'], LINGUAS_FILE=True) + Example 4. Compile files for languages defined in LINGUAS file (another version): - - # ... - env['LINGUAS_FILE'] = 1 - env.MOFiles() - + +env['LINGUAS_FILE'] = True +env.MOFiles() + - + @@ -104,7 +107,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder. - + @@ -114,7 +117,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder. - + @@ -123,7 +126,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder. - + @@ -133,7 +136,7 @@ See &t-link-msgfmt; tool and &b-link-MOFiles; builder. - + diff --git a/SCons/Tool/msginit.xml b/SCons/Tool/msginit.xml index 667ed54b6..225074d30 100644 --- a/SCons/Tool/msginit.xml +++ b/SCons/Tool/msginit.xml @@ -27,10 +27,12 @@ This file is processed by the bin/SConsDoc.py module. -This scons tool is a part of scons &t-link-gettext; toolset. It provides -scons interface to msginit(1) program, which creates new +This tool is a part of scons &t-link-gettext; toolset. It provides +&SCons; an interface to the msginit(1) program, +by setting up the &b-link-POInit; builder, +which creates a new PO file, initializing the meta information with values from -user's environment (or options). +the &consenv; (or options). @@ -54,26 +56,31 @@ user's environment (or options). -This builder belongs to &t-link-msginit; tool. The builder initializes missing -PO file(s) if &cv-link-POAUTOINIT; is set. If -&cv-link-POAUTOINIT; is not set (default), &b-POInit; prints instruction for -user (that is supposed to be a translator), telling how the -PO file should be initialized. In normal projects +This builder is set up by the &t-link-msginit; tool. +The builder initializes missing +PO file(s) if &cv-link-POAUTOINIT; is set. +If &cv-link-POAUTOINIT; is not set (the default), +&b-POInit; prints instruction for the user (such as a translator), +telling how the PO file should be initialized. +In normal projects you should not use &b-POInit; and use &b-link-POUpdate; instead. &b-link-POUpdate; chooses intelligently between msgmerge(1) and msginit(1). &b-POInit; always uses msginit(1) and should be regarded as builder for special purposes or for temporary use (e.g. for quick, one time initialization of a bunch of PO files) or for tests. +&b-POInit; is a single-source builder. +The source parameter +can also be omitted if &cv-link-LINGUAS_FILE; is set. Target nodes defined through &b-POInit; are not built by default (they're Ignored from '.' node) but are added to -special Alias ('po-create' by default). +special &f-link-Alias; ('po-create' by default). The alias name may be changed through the &cv-link-POCREATE_ALIAS; -construction variable. All PO files defined through -&b-POInit; may be easily initialized by scons po-create. +&consvar;. All PO files defined through +&b-POInit; may be easily initialized by scons po-create. @@ -81,31 +88,27 @@ construction variable. All PO files defined through Initialize en.po and pl.po from messages.pot: - - # ... - env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po] - + +env.POInit(['en', 'pl']) # messages.pot --> [en.po, pl.po] + Example 2. Initialize en.po and pl.po from foo.pot: - - # ... - env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po] - + +env.POInit(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.po] + Example 3. Initialize en.po and pl.po from -foo.pot but using &cv-link-POTDOMAIN; construction -variable: +foo.pot but using the &cv-link-POTDOMAIN; &consvar;: - - # ... - env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po] - + +env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --> [en.po, pl.po] + Example 4. @@ -113,10 +116,9 @@ Initialize PO files for languages defined in LINGUAS file. The files will be initialized from template messages.pot: - - # ... - env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file - + +env.POInit(LINGUAS_FILE=True) # needs 'LINGUAS' file + Example 5. @@ -125,34 +127,30 @@ Initialize en.po and pl.pl LINGUAS file. The files will be initialized from template messages.pot: - - # ... - env.POInit(['en', 'pl'], LINGUAS_FILE = 1) - + +env.POInit(['en', 'pl'], LINGUAS_FILE=True) + Example 6. You may preconfigure your environment first, and then initialize PO files: - - # ... - env['POAUTOINIT'] = 1 - env['LINGUAS_FILE'] = 1 - env['POTDOMAIN'] = 'foo' - env.POInit() - + +env['POAUTOINIT'] = True +env['LINGUAS_FILE'] = True +env['POTDOMAIN'] = 'foo' +env.POInit() + which has same efect as: - - # ... - env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo') - + +env.POInit(POAUTOINIT=True, LINGUAS_FILE=True, POTDOMAIN='foo') + - @@ -162,7 +160,7 @@ See &t-link-msginit; tool and &b-link-POInit; builder. - + @@ -171,17 +169,17 @@ See &t-link-msginit; tool and &b-link-POInit; builder. - + Path to msginit(1) program (found via -Detect()). +&f-link-Detect;). See &t-link-msginit; tool and &b-link-POInit; builder. - + @@ -190,17 +188,18 @@ See &t-link-msginit; tool and &b-link-POInit; builder. - + -String to display when msginit(1) is invoked -(default: '', which means ``print &cv-link-MSGINITCOM;''). +String to display when msginit(1) is invoked. +The default is an empty string, +which will print the command line (&cv-link-MSGINITCOM;). See &t-link-msginit; tool and &b-link-POInit; builder. - + @@ -210,7 +209,7 @@ See &t-link-msginit; tool and &b-link-POInit; builder. - + diff --git a/SCons/Tool/msgmerge.xml b/SCons/Tool/msgmerge.xml index 1f0437cf0..f318d4705 100644 --- a/SCons/Tool/msgmerge.xml +++ b/SCons/Tool/msgmerge.xml @@ -27,8 +27,10 @@ This file is processed by the bin/SConsDoc.py module. -This scons tool is a part of scons &t-link-gettext; toolset. It provides -scons interface to msgmerge(1) command, which merges two +This tool is a part of scons &t-link-gettext; toolset. It provides +&SCons; an interface to the msgmerge(1) command, +by setting up the &b-link-POUpdate; builder, +which merges two Uniform style .po files together. @@ -51,23 +53,29 @@ Uniform style .po files together. -The builder belongs to &t-link-msgmerge; tool. The builder updates +The builder is set up by the &t-link-msgmerge; tool. +part of the &t-link-gettext; toolset. +The builder updates PO files with msgmerge(1), or initializes -missing PO files as described in documentation of -&t-link-msginit; tool and &b-link-POInit; builder (see also -&cv-link-POAUTOINIT;). Note, that &b-POUpdate; does not add its -targets to po-create alias as &b-link-POInit; -does. +missing PO files as described in the documentation of the +&t-link-msginit; tool and the &b-link-POInit; builder (see also +&cv-link-POAUTOINIT;). +&b-POUpdate; is a single-source builder. +The source parameter +can also be omitted if &cv-link-LINGUAS_FILE; is set. -Target nodes defined through &b-POUpdate; are not built by default -(they're Ignored from '.' node). Instead, -they are added automatically to special Alias +The target nodes are not +selected for building by default (e.g. scons .). +Instead, they are added automatically to special &f-link-Alias; ('po-update' by default). The alias name may be changed -through the &cv-link-POUPDATE_ALIAS; construction variable. You can easily -update PO files in your project by scons -po-update. +through the &cv-link-POUPDATE_ALIAS; &consvar;. You can easily +update PO files in your project by +scons po-update. +Note that &b-POUpdate; does not add its +targets to the po-create alias as &b-link-POInit; +does. @@ -77,49 +85,44 @@ Update en.po and pl.po from assuming that the later one exists or there is rule to build it (see &b-link-POTUpdate;): - - # ... - env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po] - + +env.POUpdate(['en','pl']) # messages.pot --> [en.po, pl.po] + Example 2. Update en.po and pl.po from foo.pot template: - - # ... - env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl] - + +env.POUpdate(['en', 'pl'], ['foo']) # foo.pot --> [en.po, pl.pl] + Example 3. Update en.po and pl.po from foo.pot (another version): - - # ... - env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl] - + +env.POUpdate(['en', 'pl'], POTDOMAIN='foo') # foo.pot -- > [en.po, pl.pl] + Example 4. Update files for languages defined in LINGUAS file. The files are updated from messages.pot template: - - # ... - env.POUpdate(LINGUAS_FILE = 1) # needs 'LINGUAS' file - + +env.POUpdate(LINGUAS_FILE=True) # needs 'LINGUAS' file + Example 5. Same as above, but update from foo.pot template: - - # ... - env.POUpdate(LINGUAS_FILE = 1, source = ['foo']) - + +env.POUpdate(LINGUAS_FILE=True, source=['foo']) + Example 6. @@ -127,20 +130,19 @@ Update en.po and pl.po plus files for languages defined in LINGUAS file. The files are updated from messages.pot template: - - # produce 'en.po', 'pl.po' + files defined in 'LINGUAS': - env.POUpdate(['en', 'pl' ], LINGUAS_FILE = 1) - + +# produce 'en.po', 'pl.po' + files defined in 'LINGUAS': +env.POUpdate(['en', 'pl' ], LINGUAS_FILE=True) + Example 7. Use &cv-link-POAUTOINIT; to automatically initialize PO file if it doesn't exist: - - # ... - env.POUpdate(LINGUAS_FILE = 1, POAUTOINIT = 1) - + +env.POUpdate(LINGUAS_FILE=True, POAUTOINIT=True) + Example 8. @@ -149,18 +151,16 @@ Update PO files for languages defined in foo.pot template. All necessary settings are pre-configured via environment. - - # ... - env['POAUTOINIT'] = 1 - env['LINGUAS_FILE'] = 1 - env['POTDOMAIN'] = 'foo' - env.POUpdate() - + +env['POAUTOINIT'] = True +env['LINGUAS_FILE'] = True +env['POTDOMAIN'] = 'foo' +env.POUpdate() + - @@ -170,7 +170,7 @@ See &t-link-msgmerge; tool and &b-link-POUpdate; builder. - + @@ -180,7 +180,7 @@ See &t-link-msgmerge; tool and &b-link-POUpdate; builder. - + @@ -189,17 +189,18 @@ See &t-link-msgmerge; tool and &b-link-POUpdate; builder. - + -String to be displayed when msgmerge(1) is invoked -(default: '', which means ``print &cv-link-MSGMERGECOM;''). +String to be displayed when msgmerge(1) is invoked. +The default is an empty string, +which will print the command line (&cv-link-MSGMERGECOM;). See &t-link-msgmerge; tool and &b-link-POUpdate; builder. - + diff --git a/SCons/Tool/pdf.xml b/SCons/Tool/pdf.xml index 95c5ac301..71dbdda2d 100644 --- a/SCons/Tool/pdf.xml +++ b/SCons/Tool/pdf.xml @@ -48,15 +48,17 @@ or The suffix specified by the &cv-link-PDFSUFFIX; construction variable (.pdf by default) is added automatically to the target -if it is not already present. Example: +if it is not already present. +&b-PDF; is a single-source builder. +Example: - + # builds from aaa.tex env.PDF(target = 'aaa.pdf', source = 'aaa.tex') # builds bbb.pdf from bbb.dvi env.PDF(target = 'bbb', source = 'bbb.dvi') - + diff --git a/SCons/Tool/xgettext.xml b/SCons/Tool/xgettext.xml index f8b8bb8ba..10bec3a86 100644 --- a/SCons/Tool/xgettext.xml +++ b/SCons/Tool/xgettext.xml @@ -27,10 +27,10 @@ This file is processed by the bin/SConsDoc.py module. -This scons tool is a part of scons &t-link-gettext; toolset. It provides -scons interface to xgettext(1) -program, which extracts internationalized messages from source code. The tool -provides &b-POTUpdate; builder to make PO +This tool is a part of the &t-link-gettext; toolset. It provides +&SCons; an interface to the xgettext(1) +program, which extracts internationalized messages from source code. +The tool sets up the &b-POTUpdate; builder to make PO Template files. @@ -58,15 +58,18 @@ provides &b-POTUpdate; builder to make PO -The builder belongs to &t-link-xgettext; tool. The builder updates target -POT file if exists or creates one if it doesn't. The node is -not built by default (i.e. it is Ignored from -'.'), but only on demand (i.e. when given -POT file is required or when special alias is invoked). This -builder adds its targe node (messages.pot, say) to a +The builder is set up by the &t-link-xgettext; tool, +part of the &t-link-gettext; toolset. +The builder updates the target +POT file if exists or creates it if it doesn't. +The target node is not +selected for building by default (e.g. scons .), +but only on demand (i.e. when the given +POT file is required or when special alias is invoked). +This builder adds its target node (messages.pot, say) to a special alias (pot-update by default, see &cv-link-POTUPDATE_ALIAS;) so you can update/create them easily with -scons pot-update. The file is not written until there is no +scons pot-update. The file is not written until there is no real change in internationalized messages (or in comments that enter POT file). @@ -86,86 +89,87 @@ not. Let's create po/ directory and place following SConstruct script there: - - # SConstruct in 'po/' subdir - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp']) - env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp']) - + +# SConstruct in 'po/' subdir +env = Environment(tools=['default', 'xgettext']) +env.POTUpdate(['foo'], ['../a.cpp', '../b.cpp']) +env.POTUpdate(['bar'], ['../c.cpp', '../d.cpp']) + Then invoke scons few times: - - 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. - + +$ scons # Does not create foo.pot nor bar.pot +$ scons foo.pot # Updates or creates foo.pot +$ scons pot-update # Updates or creates foo.pot and bar.pot +$ scons -c # Does not clean foo.pot nor bar.pot. + the results shall be as the comments above say. Example 2. -The &b-POTUpdate; builder may be used with no target specified, in which -case default target messages.pot will be used. The -default target may also be overridden by setting &cv-link-POTDOMAIN; construction -variable or providing it as an override to &b-POTUpdate; builder: - - - # 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 - +The target argument can be omitted, in which +case the default target name messages.pot is used. +The target may also be overridden by setting the &cv-link-POTDOMAIN; +&consvar; or providing it as an override to the &b-POTUpdate; builder: + + +# 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 3. -The sources may be specified within separate file, for example +The source parameter may also be omitted, +if it is specified in a separate file, for example POTFILES.in: - - # POTFILES.in in 'po/' subdirectory - ../a.cpp - ../b.cpp - # end of file - + +# POTFILES.in in 'po/' subdirectory +../a.cpp +../b.cpp +# end of file + The name of the file (POTFILES.in) containing the list of sources is provided via &cv-link-XGETTEXTFROM;: - - # SConstruct file in 'po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in') - + +# SConstruct file in 'po/' subdirectory +env = Environment(tools=['default', 'xgettext']) +env.POTUpdate(XGETTEXTFROM='POTFILES.in') + Example 4. -You may use &cv-link-XGETTEXTPATH; to define source search path. Assume, for -example, that you have files a.cpp, +You can use &cv-link-XGETTEXTPATH; to define the source search path. +Assume, for example, that you have files a.cpp, b.cpp, po/SConstruct, -po/POTFILES.in. Then your POT-related -files could look as below: - - - # POTFILES.in in 'po/' subdirectory - a.cpp - b.cpp - # end of file - +po/POTFILES.in. +Then your POT-related files could look like this: + + +# POTFILES.in in 'po/' subdirectory +a.cpp +b.cpp +# end of file + - - # SConstruct file in 'po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH='../') - + +# SConstruct file in 'po/' subdirectory +env = Environment(tools=['default', 'xgettext']) +env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH='../') + Example 5. -Multiple search directories may be defined within a list, i.e. -XGETTEXTPATH = ['dir1', 'dir2', ...]. The order in the list +Multiple search directories may be defined as a list, i.e. +XGETTEXTPATH=['dir1', 'dir2', ...]. The order in the list determines the search order of source files. The path to the first file found is used. @@ -173,44 +177,44 @@ is used. Let's create 0/1/po/SConstruct script: - - # SConstruct file in '0/1/po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../', '../../']) - + +# SConstruct file in '0/1/po/' subdirectory +env = Environment(tools=['default', 'xgettext']) +env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../', '../../']) + and 0/1/po/POTFILES.in: - - # POTFILES.in in '0/1/po/' subdirectory - a.cpp - # end of file - + +# POTFILES.in in '0/1/po/' subdirectory +a.cpp +# end of file + Write two *.cpp files, the first one is 0/a.cpp: - - /* 0/a.cpp */ - gettext("Hello from ../../a.cpp") - + +/* 0/a.cpp */ +gettext("Hello from ../../a.cpp") + and the second is 0/1/a.cpp: - - /* 0/1/a.cpp */ - gettext("Hello from ../a.cpp") - + +/* 0/1/a.cpp */ +gettext("Hello from ../a.cpp") + then run scons. You'll obtain 0/1/po/messages.pot with the message "Hello from ../a.cpp". When you reverse order in $XGETTEXTFOM, i.e. when you write SConscript as - - # SConstruct file in '0/1/po/' subdirectory - env = Environment( tools = ['default', 'xgettext'] ) - env.POTUpdate(XGETTEXTFROM = 'POTFILES.in', XGETTEXTPATH=['../../', '../']) - + +# SConstruct file in '0/1/po/' subdirectory +env = Environment(tools=['default', 'xgettext']) +env.POTUpdate(XGETTEXTFROM='POTFILES.in', XGETTEXTPATH=['../../', '../']) + then the messages.pot will contain msgid "Hello from ../../a.cpp" line and not @@ -220,7 +224,6 @@ then the messages.pot will contain - @@ -229,7 +232,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -239,7 +242,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -249,7 +252,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -258,7 +261,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -268,7 +271,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -277,7 +280,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -290,7 +293,7 @@ See &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -303,7 +306,7 @@ See also &t-link-xgettext; tool and &b-link-POTUpdate; builder. - + @@ -313,7 +316,7 @@ This flag is used to add single search path to - + @@ -321,7 +324,7 @@ This flag is used to add single search path to - + @@ -331,7 +334,7 @@ This flag is used to add single &cv-link-XGETTEXTFROM; file to - + @@ -339,7 +342,7 @@ This flag is used to add single &cv-link-XGETTEXTFROM; file to - + @@ -348,7 +351,7 @@ form source and target (default: '${TARGET.filebase}'). - + @@ -357,7 +360,7 @@ from the &cv-link-XGETTEXTPATH; list. - + @@ -367,8 +370,4 @@ from &cv-link-XGETTEXTFROM;. - - -- 2.11.4.GIT