1*946379e7Schristos<HTML> 2*946379e7Schristos<HEAD> 3*946379e7Schristos<!-- This HTML file has been created by texi2html 1.52b 4*946379e7Schristos from gettext.texi on 27 November 2006 --> 5*946379e7Schristos 6*946379e7Schristos<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=UTF-8"> 7*946379e7Schristos<TITLE>GNU gettext utilities - 5 Making the PO Template File</TITLE> 8*946379e7Schristos</HEAD> 9*946379e7Schristos<BODY> 10*946379e7SchristosGo to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. 11*946379e7Schristos<P><HR><P> 12*946379e7Schristos 13*946379e7Schristos 14*946379e7Schristos<H1><A NAME="SEC21" HREF="gettext_toc.html#TOC21">5 Making the PO Template File</A></H1> 15*946379e7Schristos<P> 16*946379e7Schristos<A NAME="IDX142"></A> 17*946379e7Schristos 18*946379e7Schristos</P> 19*946379e7Schristos<P> 20*946379e7SchristosAfter preparing the sources, the programmer creates a PO template file. 21*946379e7SchristosThis section explains how to use <CODE>xgettext</CODE> for this purpose. 22*946379e7Schristos 23*946379e7Schristos</P> 24*946379e7Schristos<P> 25*946379e7Schristos<CODE>xgettext</CODE> creates a file named <TT>‘<VAR>domainname</VAR>.po’</TT>. You 26*946379e7Schristosshould then rename it to <TT>‘<VAR>domainname</VAR>.pot’</TT>. (Why doesn't 27*946379e7Schristos<CODE>xgettext</CODE> create it under the name <TT>‘<VAR>domainname</VAR>.pot’</TT> 28*946379e7Schristosright away? The answer is: for historical reasons. When <CODE>xgettext</CODE> 29*946379e7Schristoswas specified, the distinction between a PO file and PO file template 30*946379e7Schristoswas fuzzy, and the suffix <SAMP>‘.pot’</SAMP> wasn't in use at that time.) 31*946379e7Schristos 32*946379e7Schristos</P> 33*946379e7Schristos 34*946379e7Schristos 35*946379e7Schristos 36*946379e7Schristos<H2><A NAME="SEC22" HREF="gettext_toc.html#TOC22">5.1 Invoking the <CODE>xgettext</CODE> Program</A></H2> 37*946379e7Schristos 38*946379e7Schristos<P> 39*946379e7Schristos<A NAME="IDX143"></A> 40*946379e7Schristos<A NAME="IDX144"></A> 41*946379e7Schristos 42*946379e7Schristos<PRE> 43*946379e7Schristosxgettext [<VAR>option</VAR>] [<VAR>inputfile</VAR>] ... 44*946379e7Schristos</PRE> 45*946379e7Schristos 46*946379e7Schristos<P> 47*946379e7SchristosThe <CODE>xgettext</CODE> program extracts translatable strings from given 48*946379e7Schristosinput files. 49*946379e7Schristos 50*946379e7Schristos</P> 51*946379e7Schristos 52*946379e7Schristos 53*946379e7Schristos<H3><A NAME="SEC23" HREF="gettext_toc.html#TOC23">5.1.1 Input file location</A></H3> 54*946379e7Schristos 55*946379e7Schristos<DL COMPACT> 56*946379e7Schristos 57*946379e7Schristos<DT><SAMP>‘<VAR>inputfile</VAR> ...’</SAMP> 58*946379e7Schristos<DD> 59*946379e7SchristosInput files. 60*946379e7Schristos 61*946379e7Schristos<DT><SAMP>‘-f <VAR>file</VAR>’</SAMP> 62*946379e7Schristos<DD> 63*946379e7Schristos<DT><SAMP>‘--files-from=<VAR>file</VAR>’</SAMP> 64*946379e7Schristos<DD> 65*946379e7Schristos<A NAME="IDX145"></A> 66*946379e7Schristos<A NAME="IDX146"></A> 67*946379e7SchristosRead the names of the input files from <VAR>file</VAR> instead of getting 68*946379e7Schristosthem from the command line. 69*946379e7Schristos 70*946379e7Schristos<DT><SAMP>‘-D <VAR>directory</VAR>’</SAMP> 71*946379e7Schristos<DD> 72*946379e7Schristos<DT><SAMP>‘--directory=<VAR>directory</VAR>’</SAMP> 73*946379e7Schristos<DD> 74*946379e7Schristos<A NAME="IDX147"></A> 75*946379e7Schristos<A NAME="IDX148"></A> 76*946379e7SchristosAdd <VAR>directory</VAR> to the list of directories. Source files are 77*946379e7Schristossearched relative to this list of directories. The resulting <TT>‘.po’</TT> 78*946379e7Schristosfile will be written relative to the current directory, though. 79*946379e7Schristos 80*946379e7Schristos</DL> 81*946379e7Schristos 82*946379e7Schristos<P> 83*946379e7SchristosIf <VAR>inputfile</VAR> is <SAMP>‘-’</SAMP>, standard input is read. 84*946379e7Schristos 85*946379e7Schristos</P> 86*946379e7Schristos 87*946379e7Schristos 88*946379e7Schristos<H3><A NAME="SEC24" HREF="gettext_toc.html#TOC24">5.1.2 Output file location</A></H3> 89*946379e7Schristos 90*946379e7Schristos<DL COMPACT> 91*946379e7Schristos 92*946379e7Schristos<DT><SAMP>‘-d <VAR>name</VAR>’</SAMP> 93*946379e7Schristos<DD> 94*946379e7Schristos<DT><SAMP>‘--default-domain=<VAR>name</VAR>’</SAMP> 95*946379e7Schristos<DD> 96*946379e7Schristos<A NAME="IDX149"></A> 97*946379e7Schristos<A NAME="IDX150"></A> 98*946379e7SchristosUse <TT>‘<VAR>name</VAR>.po’</TT> for output (instead of <TT>‘messages.po’</TT>). 99*946379e7Schristos 100*946379e7Schristos<DT><SAMP>‘-o <VAR>file</VAR>’</SAMP> 101*946379e7Schristos<DD> 102*946379e7Schristos<DT><SAMP>‘--output=<VAR>file</VAR>’</SAMP> 103*946379e7Schristos<DD> 104*946379e7Schristos<A NAME="IDX151"></A> 105*946379e7Schristos<A NAME="IDX152"></A> 106*946379e7SchristosWrite output to specified file (instead of <TT>‘<VAR>name</VAR>.po’</TT> or 107*946379e7Schristos<TT>‘messages.po’</TT>). 108*946379e7Schristos 109*946379e7Schristos<DT><SAMP>‘-p <VAR>dir</VAR>’</SAMP> 110*946379e7Schristos<DD> 111*946379e7Schristos<DT><SAMP>‘--output-dir=<VAR>dir</VAR>’</SAMP> 112*946379e7Schristos<DD> 113*946379e7Schristos<A NAME="IDX153"></A> 114*946379e7Schristos<A NAME="IDX154"></A> 115*946379e7SchristosOutput files will be placed in directory <VAR>dir</VAR>. 116*946379e7Schristos 117*946379e7Schristos</DL> 118*946379e7Schristos 119*946379e7Schristos<P> 120*946379e7Schristos<A NAME="IDX155"></A> 121*946379e7SchristosIf the output <VAR>file</VAR> is <SAMP>‘-’</SAMP> or <SAMP>‘/dev/stdout’</SAMP>, the output 122*946379e7Schristosis written to standard output. 123*946379e7Schristos 124*946379e7Schristos</P> 125*946379e7Schristos 126*946379e7Schristos 127*946379e7Schristos<H3><A NAME="SEC25" HREF="gettext_toc.html#TOC25">5.1.3 Choice of input file language</A></H3> 128*946379e7Schristos 129*946379e7Schristos<DL COMPACT> 130*946379e7Schristos 131*946379e7Schristos<DT><SAMP>‘-L <VAR>name</VAR>’</SAMP> 132*946379e7Schristos<DD> 133*946379e7Schristos<DT><SAMP>‘--language=<VAR>name</VAR>’</SAMP> 134*946379e7Schristos<DD> 135*946379e7Schristos<A NAME="IDX156"></A> 136*946379e7Schristos<A NAME="IDX157"></A> 137*946379e7Schristos<A NAME="IDX158"></A> 138*946379e7SchristosSpecifies the language of the input files. The supported languages 139*946379e7Schristosare <CODE>C</CODE>, <CODE>C++</CODE>, <CODE>ObjectiveC</CODE>, <CODE>PO</CODE>, <CODE>Python</CODE>, 140*946379e7Schristos<CODE>Lisp</CODE>, <CODE>EmacsLisp</CODE>, <CODE>librep</CODE>, <CODE>Scheme</CODE>, <CODE>Smalltalk</CODE>, 141*946379e7Schristos<CODE>Java</CODE>, <CODE>JavaProperties</CODE>, <CODE>C#</CODE>, <CODE>awk</CODE>, <CODE>YCP</CODE>, 142*946379e7Schristos<CODE>Tcl</CODE>, <CODE>Perl</CODE>, <CODE>PHP</CODE>, <CODE>GCC-source</CODE>, <CODE>NXStringTable</CODE>, 143*946379e7Schristos<CODE>RST</CODE>, <CODE>Glade</CODE>. 144*946379e7Schristos 145*946379e7Schristos<DT><SAMP>‘-C’</SAMP> 146*946379e7Schristos<DD> 147*946379e7Schristos<DT><SAMP>‘--c++’</SAMP> 148*946379e7Schristos<DD> 149*946379e7Schristos<A NAME="IDX159"></A> 150*946379e7Schristos<A NAME="IDX160"></A> 151*946379e7SchristosThis is a shorthand for <CODE>--language=C++</CODE>. 152*946379e7Schristos 153*946379e7Schristos</DL> 154*946379e7Schristos 155*946379e7Schristos<P> 156*946379e7SchristosBy default the language is guessed depending on the input file name 157*946379e7Schristosextension. 158*946379e7Schristos 159*946379e7Schristos</P> 160*946379e7Schristos 161*946379e7Schristos 162*946379e7Schristos<H3><A NAME="SEC26" HREF="gettext_toc.html#TOC26">5.1.4 Input file interpretation</A></H3> 163*946379e7Schristos 164*946379e7Schristos<DL COMPACT> 165*946379e7Schristos 166*946379e7Schristos<DT><SAMP>‘--from-code=<VAR>name</VAR>’</SAMP> 167*946379e7Schristos<DD> 168*946379e7Schristos<A NAME="IDX161"></A> 169*946379e7SchristosSpecifies the encoding of the input files. This option is needed only 170*946379e7Schristosif some untranslated message strings or their corresponding comments 171*946379e7Schristoscontain non-ASCII characters. Note that Tcl and Glade input files are 172*946379e7Schristosalways assumed to be in UTF-8, regardless of this option. 173*946379e7Schristos 174*946379e7Schristos</DL> 175*946379e7Schristos 176*946379e7Schristos<P> 177*946379e7SchristosBy default the input files are assumed to be in ASCII. 178*946379e7Schristos 179*946379e7Schristos</P> 180*946379e7Schristos 181*946379e7Schristos 182*946379e7Schristos<H3><A NAME="SEC27" HREF="gettext_toc.html#TOC27">5.1.5 Operation mode</A></H3> 183*946379e7Schristos 184*946379e7Schristos<DL COMPACT> 185*946379e7Schristos 186*946379e7Schristos<DT><SAMP>‘-j’</SAMP> 187*946379e7Schristos<DD> 188*946379e7Schristos<DT><SAMP>‘--join-existing’</SAMP> 189*946379e7Schristos<DD> 190*946379e7Schristos<A NAME="IDX162"></A> 191*946379e7Schristos<A NAME="IDX163"></A> 192*946379e7SchristosJoin messages with existing file. 193*946379e7Schristos 194*946379e7Schristos<DT><SAMP>‘-x <VAR>file</VAR>’</SAMP> 195*946379e7Schristos<DD> 196*946379e7Schristos<DT><SAMP>‘--exclude-file=<VAR>file</VAR>’</SAMP> 197*946379e7Schristos<DD> 198*946379e7Schristos<A NAME="IDX164"></A> 199*946379e7Schristos<A NAME="IDX165"></A> 200*946379e7SchristosEntries from <VAR>file</VAR> are not extracted. <VAR>file</VAR> should be a PO or 201*946379e7SchristosPOT file. 202*946379e7Schristos 203*946379e7Schristos<DT><SAMP>‘-c [<VAR>tag</VAR>]’</SAMP> 204*946379e7Schristos<DD> 205*946379e7Schristos<DT><SAMP>‘--add-comments[=<VAR>tag</VAR>]’</SAMP> 206*946379e7Schristos<DD> 207*946379e7Schristos<A NAME="IDX166"></A> 208*946379e7Schristos<A NAME="IDX167"></A> 209*946379e7SchristosPlace comment block with <VAR>tag</VAR> (or those preceding keyword lines) 210*946379e7Schristosin output file. 211*946379e7Schristos 212*946379e7Schristos</DL> 213*946379e7Schristos 214*946379e7Schristos 215*946379e7Schristos 216*946379e7Schristos<H3><A NAME="SEC28" HREF="gettext_toc.html#TOC28">5.1.6 Language specific options</A></H3> 217*946379e7Schristos 218*946379e7Schristos<DL COMPACT> 219*946379e7Schristos 220*946379e7Schristos<DT><SAMP>‘-a’</SAMP> 221*946379e7Schristos<DD> 222*946379e7Schristos<DT><SAMP>‘--extract-all’</SAMP> 223*946379e7Schristos<DD> 224*946379e7Schristos<A NAME="IDX168"></A> 225*946379e7Schristos<A NAME="IDX169"></A> 226*946379e7SchristosExtract all strings. 227*946379e7Schristos 228*946379e7SchristosThis option has an effect with most languages, namely C, C++, ObjectiveC, 229*946379e7SchristosShell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, 230*946379e7SchristosGCC-source, Glade. 231*946379e7Schristos 232*946379e7Schristos<DT><SAMP>‘-k <VAR>keywordspec</VAR>’</SAMP> 233*946379e7Schristos<DD> 234*946379e7Schristos<DT><SAMP>‘--keyword[=<VAR>keywordspec</VAR>]’</SAMP> 235*946379e7Schristos<DD> 236*946379e7Schristos<A NAME="IDX170"></A> 237*946379e7Schristos<A NAME="IDX171"></A> 238*946379e7SchristosAdditional keyword to be looked for (without <VAR>keywordspec</VAR> means not to 239*946379e7Schristosuse default keywords). 240*946379e7Schristos 241*946379e7Schristos<A NAME="IDX172"></A> 242*946379e7Schristos<A NAME="IDX173"></A> 243*946379e7SchristosIf <VAR>keywordspec</VAR> is a C identifier <VAR>id</VAR>, <CODE>xgettext</CODE> looks 244*946379e7Schristosfor strings in the first argument of each call to the function or macro 245*946379e7Schristos<VAR>id</VAR>. If <VAR>keywordspec</VAR> is of the form 246*946379e7Schristos<SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>’</SAMP>, <CODE>xgettext</CODE> looks for strings in the 247*946379e7Schristos<VAR>argnum</VAR>th argument of the call. If <VAR>keywordspec</VAR> is of the form 248*946379e7Schristos<SAMP>‘<VAR>id</VAR>:<VAR>argnum1</VAR>,<VAR>argnum2</VAR>’</SAMP>, <CODE>xgettext</CODE> looks for 249*946379e7Schristosstrings in the <VAR>argnum1</VAR>st argument and in the <VAR>argnum2</VAR>nd argument 250*946379e7Schristosof the call, and treats them as singular/plural variants for a message 251*946379e7Schristoswith plural handling. Also, if <VAR>keywordspec</VAR> is of the form 252*946379e7Schristos<SAMP>‘<VAR>id</VAR>:<VAR>contextargnum</VAR>c,<VAR>argnum</VAR>’</SAMP> or 253*946379e7Schristos<SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>,<VAR>contextargnum</VAR>c’</SAMP>, <CODE>xgettext</CODE> treats 254*946379e7Schristosstrings in the <VAR>contextargnum</VAR>th argument as a context specifier. 255*946379e7SchristosAnd, as a special-purpose support for GNOME, if <VAR>keywordspec</VAR> is of the 256*946379e7Schristosform <SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>g’</SAMP>, <CODE>xgettext</CODE> recognizes the 257*946379e7Schristos<VAR>argnum</VAR>th argument as a string with context, using the GNOME <CODE>glib</CODE> 258*946379e7Schristossyntax <SAMP>‘"msgctxt|msgid"’</SAMP>. 259*946379e7Schristos<BR> 260*946379e7SchristosFurthermore, if <VAR>keywordspec</VAR> is of the form 261*946379e7Schristos<SAMP>‘<VAR>id</VAR>:...,<VAR>totalnumargs</VAR>t’</SAMP>, <CODE>xgettext</CODE> recognizes this 262*946379e7Schristosargument specification only if the number of actual arguments is equal to 263*946379e7Schristos<VAR>totalnumargs</VAR>. This is useful for disambiguating overloaded function 264*946379e7Schristoscalls in C++. 265*946379e7Schristos<BR> 266*946379e7SchristosFinally, if <VAR>keywordspec</VAR> is of the form 267*946379e7Schristos<SAMP>‘<VAR>id</VAR>:<VAR>argnum</VAR>...,"<VAR>xcomment</VAR>"’</SAMP>, <CODE>xgettext</CODE>, when 268*946379e7Schristosextracting a message from the specified argument strings, adds an extracted 269*946379e7Schristoscomment <VAR>xcomment</VAR> to the message. Note that when used through a normal 270*946379e7Schristosshell command line, the double-quotes around the <VAR>xcomment</VAR> need to be 271*946379e7Schristosescaped. 272*946379e7Schristos 273*946379e7SchristosThis option has an effect with most languages, namely C, C++, ObjectiveC, 274*946379e7SchristosShell, Python, Lisp, EmacsLisp, librep, Java, C#, awk, Tcl, Perl, PHP, 275*946379e7SchristosGCC-source, Glade. 276*946379e7Schristos 277*946379e7SchristosThe default keyword specifications, which are always looked for if not 278*946379e7Schristosexplicitly disabled, are language dependent. They are: 279*946379e7Schristos 280*946379e7Schristos 281*946379e7Schristos<UL> 282*946379e7Schristos<LI> 283*946379e7Schristos 284*946379e7SchristosFor C, C++, and GCC-source: <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>, 285*946379e7Schristos<CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, 286*946379e7Schristos<CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>, and <CODE>pgettext:1c,2</CODE>, 287*946379e7Schristos<CODE>dpgettext:2c,3</CODE>, <CODE>dcpgettext:2c,3</CODE>, <CODE>npgettext:1c,2,3</CODE>, 288*946379e7Schristos<CODE>dnpgettext:2c,3,4</CODE>, <CODE>dcnpgettext:2c,3,4</CODE>. 289*946379e7Schristos 290*946379e7Schristos<LI> 291*946379e7Schristos 292*946379e7SchristosFor Objective C: Like for C, and also <CODE>NSLocalizedString</CODE>, <CODE>_</CODE>, 293*946379e7Schristos<CODE>NSLocalizedStaticString</CODE>, <CODE>__</CODE>. 294*946379e7Schristos 295*946379e7Schristos<LI> 296*946379e7Schristos 297*946379e7SchristosFor Shell scripts: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>eval_gettext</CODE>, 298*946379e7Schristos<CODE>eval_ngettext:1,2</CODE>. 299*946379e7Schristos 300*946379e7Schristos<LI> 301*946379e7Schristos 302*946379e7SchristosFor Python: <CODE>gettext</CODE>, <CODE>ugettext</CODE>, <CODE>dgettext:2</CODE>, 303*946379e7Schristos<CODE>ngettext:1,2</CODE>, <CODE>ungettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, <CODE>_</CODE>. 304*946379e7Schristos 305*946379e7Schristos<LI> 306*946379e7Schristos 307*946379e7SchristosFor Lisp: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>. 308*946379e7Schristos 309*946379e7Schristos<LI> 310*946379e7Schristos 311*946379e7SchristosFor EmacsLisp: <CODE>_</CODE>. 312*946379e7Schristos 313*946379e7Schristos<LI> 314*946379e7Schristos 315*946379e7SchristosFor librep: <CODE>_</CODE>. 316*946379e7Schristos 317*946379e7Schristos<LI> 318*946379e7Schristos 319*946379e7SchristosFor Scheme: <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>gettext-noop</CODE>. 320*946379e7Schristos 321*946379e7Schristos<LI> 322*946379e7Schristos 323*946379e7SchristosFor Java: <CODE>GettextResource.gettext:2</CODE>, 324*946379e7Schristos<CODE>GettextResource.ngettext:2,3</CODE>, <CODE>gettext</CODE>, <CODE>ngettext:1,2</CODE>, 325*946379e7Schristos<CODE>getString</CODE>. 326*946379e7Schristos 327*946379e7Schristos<LI> 328*946379e7Schristos 329*946379e7SchristosFor C#: <CODE>GetString</CODE>, <CODE>GetPluralString:1,2</CODE>. 330*946379e7Schristos 331*946379e7Schristos<LI> 332*946379e7Schristos 333*946379e7SchristosFor awk: <CODE>dcgettext</CODE>, <CODE>dcngettext:1,2</CODE>. 334*946379e7Schristos 335*946379e7Schristos<LI> 336*946379e7Schristos 337*946379e7SchristosFor Tcl: <CODE>::msgcat::mc</CODE>. 338*946379e7Schristos 339*946379e7Schristos<LI> 340*946379e7Schristos 341*946379e7SchristosFor Perl: <CODE>gettext</CODE>, <CODE>%gettext</CODE>, <CODE>$gettext</CODE>, <CODE>dgettext:2</CODE>, 342*946379e7Schristos<CODE>dcgettext:2</CODE>, <CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, 343*946379e7Schristos<CODE>dcngettext:2,3</CODE>, <CODE>gettext_noop</CODE>. 344*946379e7Schristos 345*946379e7Schristos<LI> 346*946379e7Schristos 347*946379e7SchristosFor PHP: <CODE>_</CODE>, <CODE>gettext</CODE>, <CODE>dgettext:2</CODE>, <CODE>dcgettext:2</CODE>, 348*946379e7Schristos<CODE>ngettext:1,2</CODE>, <CODE>dngettext:2,3</CODE>, <CODE>dcngettext:2,3</CODE>. 349*946379e7Schristos 350*946379e7Schristos<LI> 351*946379e7Schristos 352*946379e7SchristosFor Glade 1: <CODE>label</CODE>, <CODE>title</CODE>, <CODE>text</CODE>, <CODE>format</CODE>, 353*946379e7Schristos<CODE>copyright</CODE>, <CODE>comments</CODE>, <CODE>preview_text</CODE>, <CODE>tooltip</CODE>. 354*946379e7Schristos</UL> 355*946379e7Schristos 356*946379e7SchristosTo disable the default keyword specifications, the option <SAMP>‘-k’</SAMP> or 357*946379e7Schristos<SAMP>‘--keyword’</SAMP> or <SAMP>‘--keyword=’</SAMP>, without a <VAR>keywordspec</VAR>, can be 358*946379e7Schristosused. 359*946379e7Schristos 360*946379e7Schristos<DT><SAMP>‘--flag=<VAR>word</VAR>:<VAR>arg</VAR>:<VAR>flag</VAR>’</SAMP> 361*946379e7Schristos<DD> 362*946379e7Schristos<A NAME="IDX174"></A> 363*946379e7SchristosSpecifies additional flags for strings occurring as part of the <VAR>arg</VAR>th 364*946379e7Schristosargument of the function <VAR>word</VAR>. The possible flags are the possible 365*946379e7Schristosformat string indicators, such as <SAMP>‘c-format’</SAMP>, and their negations, 366*946379e7Schristossuch as <SAMP>‘no-c-format’</SAMP>, possibly prefixed with <SAMP>‘pass-’</SAMP>. 367*946379e7Schristos<BR> 368*946379e7Schristos<A NAME="IDX175"></A> 369*946379e7SchristosThe meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:<VAR>lang</VAR>-format</CODE> 370*946379e7Schristosis that in language <VAR>lang</VAR>, the specified <VAR>function</VAR> expects as 371*946379e7Schristos<VAR>arg</VAR>th argument a format string. (For those of you familiar with 372*946379e7SchristosGCC function attributes, <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:c-format</CODE> is 373*946379e7Schristosroughly equivalent to the declaration 374*946379e7Schristos<SAMP>‘__attribute__ ((__format__ (__printf__, <VAR>arg</VAR>, ...)))’</SAMP> attached 375*946379e7Schristosto <VAR>function</VAR> in a C source file.) 376*946379e7SchristosFor example, if you use the <SAMP>‘error’</SAMP> function from GNU libc, you can 377*946379e7Schristosspecify its behaviour through <CODE>--flag=error:3:c-format</CODE>. The effect of 378*946379e7Schristosthis specification is that <CODE>xgettext</CODE> will mark as format strings all 379*946379e7Schristos<CODE>gettext</CODE> invocations that occur as <VAR>arg</VAR>th argument of 380*946379e7Schristos<VAR>function</VAR>. 381*946379e7SchristosThis is useful when such strings contain no format string directives: 382*946379e7Schristostogether with the checks done by <SAMP>‘msgfmt -c’</SAMP> it will ensure that 383*946379e7Schristostranslators cannot accidentally use format string directives that would 384*946379e7Schristoslead to a crash at runtime. 385*946379e7Schristos<BR> 386*946379e7Schristos<A NAME="IDX176"></A> 387*946379e7SchristosThe meaning of <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-<VAR>lang</VAR>-format</CODE> 388*946379e7Schristosis that in language <VAR>lang</VAR>, if the <VAR>function</VAR> call occurs in a 389*946379e7Schristosposition that must yield a format string, then its <VAR>arg</VAR>th argument 390*946379e7Schristosmust yield a format string of the same type as well. (If you know GCC 391*946379e7Schristosfunction attributes, the <CODE>--flag=<VAR>function</VAR>:<VAR>arg</VAR>:pass-c-format</CODE> 392*946379e7Schristosoption is roughly equivalent to the declaration 393*946379e7Schristos<SAMP>‘__attribute__ ((__format_arg__ (<VAR>arg</VAR>)))’</SAMP> attached to <VAR>function</VAR> 394*946379e7Schristosin a C source file.) 395*946379e7SchristosFor example, if you use the <SAMP>‘_’</SAMP> shortcut for the <CODE>gettext</CODE> function, 396*946379e7Schristosyou should use <CODE>--flag=_:1:pass-c-format</CODE>. The effect of this 397*946379e7Schristosspecification is that <CODE>xgettext</CODE> will propagate a format string 398*946379e7Schristosrequirement for a <CODE>_("string")</CODE> call to its first argument, the literal 399*946379e7Schristos<CODE>"string"</CODE>, and thus mark it as a format string. 400*946379e7SchristosThis is useful when such strings contain no format string directives: 401*946379e7Schristostogether with the checks done by <SAMP>‘msgfmt -c’</SAMP> it will ensure that 402*946379e7Schristostranslators cannot accidentally use format string directives that would 403*946379e7Schristoslead to a crash at runtime. 404*946379e7Schristos<BR> 405*946379e7SchristosThis option has an effect with most languages, namely C, C++, ObjectiveC, 406*946379e7SchristosShell, Python, Lisp, EmacsLisp, librep, Scheme, Java, C#, awk, YCP, Tcl, Perl, PHP, 407*946379e7SchristosGCC-source. 408*946379e7Schristos 409*946379e7Schristos<DT><SAMP>‘-T’</SAMP> 410*946379e7Schristos<DD> 411*946379e7Schristos<DT><SAMP>‘--trigraphs’</SAMP> 412*946379e7Schristos<DD> 413*946379e7Schristos<A NAME="IDX177"></A> 414*946379e7Schristos<A NAME="IDX178"></A> 415*946379e7Schristos<A NAME="IDX179"></A> 416*946379e7SchristosUnderstand ANSI C trigraphs for input. 417*946379e7Schristos<BR> 418*946379e7SchristosThis option has an effect only with the languages C, C++, ObjectiveC. 419*946379e7Schristos 420*946379e7Schristos<DT><SAMP>‘--qt’</SAMP> 421*946379e7Schristos<DD> 422*946379e7Schristos<A NAME="IDX180"></A> 423*946379e7Schristos<A NAME="IDX181"></A> 424*946379e7SchristosRecognize Qt format strings. 425*946379e7Schristos<BR> 426*946379e7SchristosThis option has an effect only with the language C++. 427*946379e7Schristos 428*946379e7Schristos<DT><SAMP>‘--boost’</SAMP> 429*946379e7Schristos<DD> 430*946379e7Schristos<A NAME="IDX182"></A> 431*946379e7Schristos<A NAME="IDX183"></A> 432*946379e7SchristosRecognize Boost format strings. 433*946379e7Schristos<BR> 434*946379e7SchristosThis option has an effect only with the language C++. 435*946379e7Schristos 436*946379e7Schristos<DT><SAMP>‘--debug’</SAMP> 437*946379e7Schristos<DD> 438*946379e7Schristos<A NAME="IDX184"></A> 439*946379e7Schristos<A NAME="IDX185"></A> 440*946379e7SchristosUse the flags <CODE>c-format</CODE> and <CODE>possible-c-format</CODE> to show who was 441*946379e7Schristosresponsible for marking a message as a format string. The latter form is 442*946379e7Schristosused if the <CODE>xgettext</CODE> program decided, the format form is used if 443*946379e7Schristosthe programmer prescribed it. 444*946379e7Schristos 445*946379e7SchristosBy default only the <CODE>c-format</CODE> form is used. The translator should 446*946379e7Schristosnot have to care about these details. 447*946379e7Schristos 448*946379e7Schristos</DL> 449*946379e7Schristos 450*946379e7Schristos<P> 451*946379e7SchristosThis implementation of <CODE>xgettext</CODE> is able to process a few awkward 452*946379e7Schristoscases, like strings in preprocessor macros, ANSI concatenation of 453*946379e7Schristosadjacent strings, and escaped end of lines for continued strings. 454*946379e7Schristos 455*946379e7Schristos</P> 456*946379e7Schristos 457*946379e7Schristos 458*946379e7Schristos<H3><A NAME="SEC29" HREF="gettext_toc.html#TOC29">5.1.7 Output details</A></H3> 459*946379e7Schristos 460*946379e7Schristos<DL COMPACT> 461*946379e7Schristos 462*946379e7Schristos<DT><SAMP>‘--force-po’</SAMP> 463*946379e7Schristos<DD> 464*946379e7Schristos<A NAME="IDX186"></A> 465*946379e7SchristosAlways write an output file even if no message is defined. 466*946379e7Schristos 467*946379e7Schristos<DT><SAMP>‘-i’</SAMP> 468*946379e7Schristos<DD> 469*946379e7Schristos<DT><SAMP>‘--indent’</SAMP> 470*946379e7Schristos<DD> 471*946379e7Schristos<A NAME="IDX187"></A> 472*946379e7Schristos<A NAME="IDX188"></A> 473*946379e7SchristosWrite the .po file using indented style. 474*946379e7Schristos 475*946379e7Schristos<DT><SAMP>‘--no-location’</SAMP> 476*946379e7Schristos<DD> 477*946379e7Schristos<A NAME="IDX189"></A> 478*946379e7SchristosDo not write <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines. 479*946379e7Schristos 480*946379e7Schristos<DT><SAMP>‘-n’</SAMP> 481*946379e7Schristos<DD> 482*946379e7Schristos<DT><SAMP>‘--add-location’</SAMP> 483*946379e7Schristos<DD> 484*946379e7Schristos<A NAME="IDX190"></A> 485*946379e7Schristos<A NAME="IDX191"></A> 486*946379e7SchristosGenerate <SAMP>‘#: <VAR>filename</VAR>:<VAR>line</VAR>’</SAMP> lines (default). 487*946379e7Schristos 488*946379e7Schristos<DT><SAMP>‘--strict’</SAMP> 489*946379e7Schristos<DD> 490*946379e7Schristos<A NAME="IDX192"></A> 491*946379e7SchristosWrite out a strict Uniforum conforming PO file. Note that this 492*946379e7SchristosUniforum format should be avoided because it doesn't support the 493*946379e7SchristosGNU extensions. 494*946379e7Schristos 495*946379e7Schristos<DT><SAMP>‘--properties-output’</SAMP> 496*946379e7Schristos<DD> 497*946379e7Schristos<A NAME="IDX193"></A> 498*946379e7SchristosWrite out a Java ResourceBundle in Java <CODE>.properties</CODE> syntax. Note 499*946379e7Schristosthat this file format doesn't support plural forms and silently drops 500*946379e7Schristosobsolete messages. 501*946379e7Schristos 502*946379e7Schristos<DT><SAMP>‘--stringtable-output’</SAMP> 503*946379e7Schristos<DD> 504*946379e7Schristos<A NAME="IDX194"></A> 505*946379e7SchristosWrite out a NeXTstep/GNUstep localized resource file in <CODE>.strings</CODE> syntax. 506*946379e7SchristosNote that this file format doesn't support plural forms. 507*946379e7Schristos 508*946379e7Schristos<DT><SAMP>‘-w <VAR>number</VAR>’</SAMP> 509*946379e7Schristos<DD> 510*946379e7Schristos<DT><SAMP>‘--width=<VAR>number</VAR>’</SAMP> 511*946379e7Schristos<DD> 512*946379e7Schristos<A NAME="IDX195"></A> 513*946379e7Schristos<A NAME="IDX196"></A> 514*946379e7SchristosSet the output page width. Long strings in the output files will be 515*946379e7Schristossplit across multiple lines in order to ensure that each line's width 516*946379e7Schristos(= number of screen columns) is less or equal to the given <VAR>number</VAR>. 517*946379e7Schristos 518*946379e7Schristos<DT><SAMP>‘--no-wrap’</SAMP> 519*946379e7Schristos<DD> 520*946379e7Schristos<A NAME="IDX197"></A> 521*946379e7SchristosDo not break long message lines. Message lines whose width exceeds the 522*946379e7Schristosoutput page width will not be split into several lines. Only file reference 523*946379e7Schristoslines which are wider than the output page width will be split. 524*946379e7Schristos 525*946379e7Schristos<DT><SAMP>‘-s’</SAMP> 526*946379e7Schristos<DD> 527*946379e7Schristos<DT><SAMP>‘--sort-output’</SAMP> 528*946379e7Schristos<DD> 529*946379e7Schristos<A NAME="IDX198"></A> 530*946379e7Schristos<A NAME="IDX199"></A> 531*946379e7Schristos<A NAME="IDX200"></A> 532*946379e7SchristosGenerate sorted output. Note that using this option makes it much harder 533*946379e7Schristosfor the translator to understand each message's context. 534*946379e7Schristos 535*946379e7Schristos<DT><SAMP>‘-F’</SAMP> 536*946379e7Schristos<DD> 537*946379e7Schristos<DT><SAMP>‘--sort-by-file’</SAMP> 538*946379e7Schristos<DD> 539*946379e7Schristos<A NAME="IDX201"></A> 540*946379e7Schristos<A NAME="IDX202"></A> 541*946379e7SchristosSort output by file location. 542*946379e7Schristos 543*946379e7Schristos<DT><SAMP>‘--omit-header’</SAMP> 544*946379e7Schristos<DD> 545*946379e7Schristos<A NAME="IDX203"></A> 546*946379e7SchristosDon't write header with <SAMP>‘msgid ""’</SAMP> entry. 547*946379e7Schristos 548*946379e7Schristos<A NAME="IDX204"></A> 549*946379e7SchristosThis is useful for testing purposes because it eliminates a source 550*946379e7Schristosof variance for generated <CODE>.gmo</CODE> files. With <CODE>--omit-header</CODE>, 551*946379e7Schristostwo invocations of <CODE>xgettext</CODE> on the same files with the same 552*946379e7Schristosoptions at different times are guaranteed to produce the same results. 553*946379e7Schristos 554*946379e7Schristos<DT><SAMP>‘--copyright-holder=<VAR>string</VAR>’</SAMP> 555*946379e7Schristos<DD> 556*946379e7Schristos<A NAME="IDX205"></A> 557*946379e7SchristosSet the copyright holder in the output. <VAR>string</VAR> should be the 558*946379e7Schristoscopyright holder of the surrounding package. (Note that the msgstr 559*946379e7Schristosstrings, extracted from the package's sources, belong to the copyright 560*946379e7Schristosholder of the package.) Translators are expected to transfer or disclaim 561*946379e7Schristosthe copyright for their translations, so that package maintainers can 562*946379e7Schristosdistribute them without legal risk. If <VAR>string</VAR> is empty, the output 563*946379e7Schristosfiles are marked as being in the public domain; in this case, the translators 564*946379e7Schristosare expected to disclaim their copyright, again so that package maintainers 565*946379e7Schristoscan distribute them without legal risk. 566*946379e7Schristos 567*946379e7SchristosThe default value for <VAR>string</VAR> is the Free Software Foundation, Inc., 568*946379e7Schristossimply because <CODE>xgettext</CODE> was first used in the GNU project. 569*946379e7Schristos 570*946379e7Schristos<DT><SAMP>‘--foreign-user’</SAMP> 571*946379e7Schristos<DD> 572*946379e7Schristos<A NAME="IDX206"></A> 573*946379e7SchristosOmit FSF copyright in output. This option is equivalent to 574*946379e7Schristos<SAMP>‘--copyright-holder=”’</SAMP>. It can be useful for packages outside the GNU 575*946379e7Schristosproject that want their translations to be in the public domain. 576*946379e7Schristos 577*946379e7Schristos<DT><SAMP>‘--msgid-bugs-address=<VAR>email@address</VAR>’</SAMP> 578*946379e7Schristos<DD> 579*946379e7Schristos<A NAME="IDX207"></A> 580*946379e7SchristosSet the reporting address for msgid bugs. This is the email address or URL 581*946379e7Schristosto which the translators shall report bugs in the untranslated strings: 582*946379e7Schristos 583*946379e7Schristos 584*946379e7Schristos<UL> 585*946379e7Schristos<LI>Strings which are not entire sentences, see the maintainer guidelines 586*946379e7Schristos 587*946379e7Schristosin section <A HREF="gettext_4.html#SEC14">4.3 Preparing Translatable Strings</A>. 588*946379e7Schristos<LI>Strings which use unclear terms or require additional context to be 589*946379e7Schristos 590*946379e7Schristosunderstood. 591*946379e7Schristos<LI>Strings which make invalid assumptions about notation of date, time or 592*946379e7Schristos 593*946379e7Schristosmoney. 594*946379e7Schristos<LI>Pluralisation problems. 595*946379e7Schristos 596*946379e7Schristos<LI>Incorrect English spelling. 597*946379e7Schristos 598*946379e7Schristos<LI>Incorrect formatting. 599*946379e7Schristos 600*946379e7Schristos</UL> 601*946379e7Schristos 602*946379e7SchristosIt can be your email address, or a mailing list address where translators 603*946379e7Schristoscan write to without being subscribed, or the URL of a web page through 604*946379e7Schristoswhich the translators can contact you. 605*946379e7Schristos 606*946379e7SchristosThe default value is empty, which means that translators will be clueless! 607*946379e7SchristosDon't forget to specify this option. 608*946379e7Schristos 609*946379e7Schristos<DT><SAMP>‘-m [<VAR>string</VAR>]’</SAMP> 610*946379e7Schristos<DD> 611*946379e7Schristos<DT><SAMP>‘--msgstr-prefix[=<VAR>string</VAR>]’</SAMP> 612*946379e7Schristos<DD> 613*946379e7Schristos<A NAME="IDX208"></A> 614*946379e7Schristos<A NAME="IDX209"></A> 615*946379e7SchristosUse <VAR>string</VAR> (or "" if not specified) as prefix for msgstr entries. 616*946379e7Schristos 617*946379e7Schristos<DT><SAMP>‘-M [<VAR>string</VAR>]’</SAMP> 618*946379e7Schristos<DD> 619*946379e7Schristos<DT><SAMP>‘--msgstr-suffix[=<VAR>string</VAR>]’</SAMP> 620*946379e7Schristos<DD> 621*946379e7Schristos<A NAME="IDX210"></A> 622*946379e7Schristos<A NAME="IDX211"></A> 623*946379e7SchristosUse <VAR>string</VAR> (or "" if not specified) as suffix for msgstr entries. 624*946379e7Schristos 625*946379e7Schristos</DL> 626*946379e7Schristos 627*946379e7Schristos 628*946379e7Schristos 629*946379e7Schristos<H3><A NAME="SEC30" HREF="gettext_toc.html#TOC30">5.1.8 Informative output</A></H3> 630*946379e7Schristos 631*946379e7Schristos<DL COMPACT> 632*946379e7Schristos 633*946379e7Schristos<DT><SAMP>‘-h’</SAMP> 634*946379e7Schristos<DD> 635*946379e7Schristos<DT><SAMP>‘--help’</SAMP> 636*946379e7Schristos<DD> 637*946379e7Schristos<A NAME="IDX212"></A> 638*946379e7Schristos<A NAME="IDX213"></A> 639*946379e7SchristosDisplay this help and exit. 640*946379e7Schristos 641*946379e7Schristos<DT><SAMP>‘-V’</SAMP> 642*946379e7Schristos<DD> 643*946379e7Schristos<DT><SAMP>‘--version’</SAMP> 644*946379e7Schristos<DD> 645*946379e7Schristos<A NAME="IDX214"></A> 646*946379e7Schristos<A NAME="IDX215"></A> 647*946379e7SchristosOutput version information and exit. 648*946379e7Schristos 649*946379e7Schristos</DL> 650*946379e7Schristos 651*946379e7Schristos<P><HR><P> 652*946379e7SchristosGo to the <A HREF="gettext_1.html">first</A>, <A HREF="gettext_4.html">previous</A>, <A HREF="gettext_6.html">next</A>, <A HREF="gettext_25.html">last</A> section, <A HREF="gettext_toc.html">table of contents</A>. 653*946379e7Schristos</BODY> 654*946379e7Schristos</HTML> 655