From f4d0a235b9a6a5de838fd6a1ea44a4cdbeed7bde Mon Sep 17 00:00:00 2001 From: Mats Wichmann Date: Fri, 20 Sep 2024 08:39:54 -0600 Subject: [PATCH 1/2] 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 8d58fd4335..218c0c66eb 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 785ef953e5..cbf061d177 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 4df22ef195..d8a69e8961 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 1606129939..a2b7c98735 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 e56c12c419..f92830ff3b 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 667ed54b61..225074d308 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 1f0437cf0f..f318d47050 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 95c5ac3013..71dbdda2d7 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 f8b8bb8bab..10bec3a86e 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;. - - From b8e3b23ed6ae4c12888daadb92575496730d9926 Mon Sep 17 00:00:00 2001 From: William Deegan Date: Sat, 21 Sep 2024 18:10:57 -0700 Subject: [PATCH 2/2] Fix typos --- SCons/Tool/gettext.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/SCons/Tool/gettext.xml b/SCons/Tool/gettext.xml index a2b7c98735..4b3eb12eb7 100644 --- a/SCons/Tool/gettext.xml +++ b/SCons/Tool/gettext.xml @@ -40,7 +40,7 @@ The toolset loads the following tools: &t-link-msginit; - initialize PO - files during initial tranlation of a project. + files during initial translation of a project. &t-link-msgmerge; - update PO files that already contain @@ -53,7 +53,7 @@ The toolset loads the following tools: -When you enable &t-gettext;, it internally loads all abovementioned tools, +When you enable &t-gettext;, it internally loads all the above-mentioned tools, so you're encouraged to see their individual documentation. @@ -89,7 +89,7 @@ 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 +account too. All other construction variables used by &b-link-POTUpdate;, and &b-link-POUpdate; work here too. @@ -144,7 +144,7 @@ factor" synchronizing these two scripts is then the content of LINGUAS file. Note, that the updated POT and PO files are usually going to be committed back to the repository, so they must be updated within the source -directory (and not in variant directories). Additionaly, the file listing of +directory (and not in variant directories). Additionally, the file listing of po/ directory contains LINGUAS file, so the source tree looks familiar to translators, and they may work with the project in their usual way.