summaryrefslogtreecommitdiff
path: root/src/engine/SCons/Tool/msginit.xml
blob: 3a2a969ea5af6d5c8fe5373d7d2378bf9ce401f7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
<?xml version="1.0" encoding="UTF-8"?>
<!--
Copyright (c) 2001 - 2017 The SCons Foundation

This file is processed by the bin/SConsDoc.py module.
See its __doc__ string for a discussion of the format.
-->

<!DOCTYPE sconsdoc [
<!ENTITY % scons SYSTEM '../../../../doc/scons.mod'>
%scons;
<!ENTITY % builders-mod SYSTEM '../../../../doc/generated/builders.mod'>
%builders-mod;
<!ENTITY % functions-mod SYSTEM '../../../../doc/generated/functions.mod'>
%functions-mod;
<!ENTITY % tools-mod SYSTEM '../../../../doc/generated/tools.mod'>
%tools-mod;
<!ENTITY % variables-mod SYSTEM '../../../../doc/generated/variables.mod'>
%variables-mod;
]>

<sconsdoc xmlns="http://www.scons.org/dbxsd/v1.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://www.scons.org/dbxsd/v1.0 http://www.scons.org/dbxsd/v1.0/scons.xsd">

<tool name="msginit">
<summary>
<para>
This scons tool is a part of scons &t-link-gettext; toolset. It provides
scons interface to <command>msginit(1)</command> program, which creates new
<literal>PO</literal> file, initializing the meta information with values from
user's environment (or options).
</para>
</summary>
<sets>
<item>MSGINIT</item>
<item>MSGINITCOM</item>
<item>MSGINITCOMSTR</item>
<item>MSGINITFLAGS</item>
<item>POAUTOINIT</item>
<item>POCREATE_ALIAS</item>
<item>POSUFFIX</item>
<item>POTSUFFIX</item>
<item>_MSGINITLOCALE</item>
</sets>
<uses>
<item>POTDOMAIN</item>
<item>LINGUAS_FILE</item>
<item>POAUTOINIT</item>
</uses>
</tool>

<builder name="POInit">
<summary>
<para>
This builder belongs to &t-link-msginit; tool. The builder initializes missing
<literal>PO</literal> 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
<literal>PO</literal> file should be initialized. In normal projects
<emphasis>you should not use &b-POInit; and use &b-link-POUpdate;
instead</emphasis>. &b-link-POUpdate; chooses intelligently between
<command>msgmerge(1)</command> and <command>msginit(1)</command>. &b-POInit;
always uses <command>msginit(1)</command> and should be regarded as builder for
special purposes or for temporary use (e.g. for quick, one time initialization
of a bunch of <literal>PO</literal> files) or for tests.
</para>

<para>
Target nodes defined through &b-POInit; are not built by default (they're
<literal>Ignore</literal>d from <literal>'.'</literal> node) but are added to
special <literal>Alias</literal> (<literal>'po-create'</literal> by default).
The alias name may be changed through the &cv-link-POCREATE_ALIAS;
construction variable. All <literal>PO</literal> files defined through
&b-POInit; may be easily initialized by <command>scons po-create</command>.
</para>

<para>
<emphasis>Example 1</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>messages.pot</filename>:
</para>
<example_commands>
  # ...
  env.POInit(['en', 'pl']) # messages.pot --&gt; [en.po, pl.po] 
</example_commands>

<para>
<emphasis>Example 2</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>foo.pot</filename>:
</para>
<example_commands>
  # ...
  env.POInit(['en', 'pl'], ['foo']) # foo.pot --&gt; [en.po, pl.po] 
</example_commands>

<para>
<emphasis>Example 3</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.po</filename> from
<filename>foo.pot</filename> but using &cv-link-POTDOMAIN; construction
variable:
</para>
<example_commands>
  # ...
  env.POInit(['en', 'pl'], POTDOMAIN='foo') # foo.pot --&gt; [en.po, pl.po] 
</example_commands>

<para>
<emphasis>Example 4</emphasis>.
Initialize <literal>PO</literal> files for languages defined in
<filename>LINGUAS</filename> file. The files will be initialized from template
<filename>messages.pot</filename>:
</para>
<example_commands>
  # ...
  env.POInit(LINGUAS_FILE = 1) # needs 'LINGUAS' file
</example_commands>

<para>
<emphasis>Example 5</emphasis>.
Initialize <filename>en.po</filename> and <filename>pl.pl</filename>
<literal>PO</literal> files plus files for languages defined in
<filename>LINGUAS</filename> file. The files will be initialized from template
<filename>messages.pot</filename>:
</para>
<example_commands>
  # ...
  env.POInit(['en', 'pl'], LINGUAS_FILE = 1)
</example_commands>

<para>
<emphasis>Example 6</emphasis>.
You may preconfigure your environment first, and then initialize
<literal>PO</literal> files:
</para>
<example_commands>
  # ...
  env['POAUTOINIT'] = 1
  env['LINGUAS_FILE'] = 1
  env['POTDOMAIN'] = 'foo'
  env.POInit()
</example_commands>
<para>
which has same efect as:
</para>
<example_commands>
  # ...
  env.POInit(POAUTOINIT = 1, LINGUAS_FILE = 1, POTDOMAIN = 'foo')
</example_commands>
</summary>
</builder>

<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="POCREATE_ALIAS">
<summary>
<para>
Common alias for all <literal>PO</literal> files created with &b-POInit;
builder (default: <literal>'po-create'</literal>).
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="POSUFFIX">
<summary>
<para>
Suffix used for <literal>PO</literal> files (default: <literal>'.po'</literal>)
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="MSGINIT">
<summary>
<para>
Path to <command>msginit(1)</command> program (found via
<literal>Detect()</literal>).
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="MSGINITCOM">
<summary>
<para>
Complete command line to run <command>msginit(1)</command> program.
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="MSGINITCOMSTR">
<summary>
<para>
String to display when <command>msginit(1)</command> is invoked 
(default: <literal>''</literal>, which means ``print &cv-link-MSGINITCOM;'').
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="MSGINITFLAGS">
<summary>
<para>
List of additional flags to <command>msginit(1)</command> (default:
<literal>[]</literal>).
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</summary>
</cvar>
<!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
<cvar name="_MSGINITLOCALE">
<summary>
<para>
Internal ``macro''. Computes locale (language) name based on target filename
(default: <literal>'${TARGET.filebase}' </literal>).
</para>
<para>
See &t-link-msginit; tool and &b-link-POInit; builder.
</para>
</summary>
</cvar>

</sconsdoc>