csp2: CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_9.html @ 68:5028fdace37b

planemo upload commit 2e9511a184a1ca667c7be0c6321a36dc4e3d116d

author	jpayne
date	Tue, 18 Mar 2025 16:23:26 -0400
parents
children

rev	line source
jpayne@68	1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
jpayne@68	2 <html>
jpayne@68	3 <!-- Created on February, 21 2024 by texi2html 1.78a -->
jpayne@68	4 <!--
jpayne@68	5 Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
jpayne@68	6 Karl Berry <karl@freefriends.org>
jpayne@68	7 Olaf Bachmann <obachman@mathematik.uni-kl.de>
jpayne@68	8 and many others.
jpayne@68	9 Maintained by: Many creative people.
jpayne@68	10 Send bugs and suggestions to <texi2html-bug@nongnu.org>
jpayne@68	11
jpayne@68	12 -->
jpayne@68	13 <head>
jpayne@68	14 <title>GNU gettext utilities: 9. Manipulating PO Files</title>
jpayne@68	15
jpayne@68	16 <meta name="description" content="GNU gettext utilities: 9. Manipulating PO Files">
jpayne@68	17 <meta name="keywords" content="GNU gettext utilities: 9. Manipulating PO Files">
jpayne@68	18 <meta name="resource-type" content="document">
jpayne@68	19 <meta name="distribution" content="global">
jpayne@68	20 <meta name="Generator" content="texi2html 1.78a">
jpayne@68	21 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
jpayne@68	22 <style type="text/css">
jpayne@68	23 <!--
jpayne@68	24 a.summary-letter {text-decoration: none}
jpayne@68	25 pre.display {font-family: serif}
jpayne@68	26 pre.format {font-family: serif}
jpayne@68	27 pre.menu-comment {font-family: serif}
jpayne@68	28 pre.menu-preformatted {font-family: serif}
jpayne@68	29 pre.smalldisplay {font-family: serif; font-size: smaller}
jpayne@68	30 pre.smallexample {font-size: smaller}
jpayne@68	31 pre.smallformat {font-family: serif; font-size: smaller}
jpayne@68	32 pre.smalllisp {font-size: smaller}
jpayne@68	33 span.roman {font-family:serif; font-weight:normal;}
jpayne@68	34 span.sansserif {font-family:sans-serif; font-weight:normal;}
jpayne@68	35 ul.toc {list-style: none}
jpayne@68	36 -->
jpayne@68	37 </style>
jpayne@68	38
jpayne@68	39
jpayne@68	40 </head>
jpayne@68	41
jpayne@68	42 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
jpayne@68	43
jpayne@68	44 <table cellpadding="1" cellspacing="1" border="0">
jpayne@68	45 <tr><td valign="middle" align="left">[<a href="gettext_8.html#SEC63" title="Beginning of this chapter or previous chapter"> << </a>]</td>
jpayne@68	46 <td valign="middle" align="left">[<a href="gettext_10.html#SEC173" title="Next chapter"> >> </a>]</td>
jpayne@68	47 <td valign="middle" align="left">   </td>
jpayne@68	48 <td valign="middle" align="left">   </td>
jpayne@68	49 <td valign="middle" align="left">   </td>
jpayne@68	50 <td valign="middle" align="left">   </td>
jpayne@68	51 <td valign="middle" align="left">   </td>
jpayne@68	52 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
jpayne@68	53 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
jpayne@68	54 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td>
jpayne@68	55 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
jpayne@68	56 </tr></table>
jpayne@68	57
jpayne@68	58 <hr size="2">
jpayne@68	59 <a name="Manipulating"></a>
jpayne@68	60 <a name="SEC87"></a>
jpayne@68	61 <h1 class="chapter"> <a href="gettext_toc.html#TOC80">9. Manipulating PO Files</a> </h1>
jpayne@68	62
jpayne@68	63 <p>Sometimes it is necessary to manipulate PO files in a way that is better
jpayne@68	64 performed automatically than by hand. GNU <code>gettext</code> includes a
jpayne@68	65 complete set of tools for this purpose.
jpayne@68	66 </p>
jpayne@68	67 <a name="IDX484"></a>
jpayne@68	68 <p>When merging two packages into a single package, the resulting POT file
jpayne@68	69 will be the concatenation of the two packages' POT files. Thus the
jpayne@68	70 maintainer must concatenate the two existing package translations into
jpayne@68	71 a single translation catalog, for each language. This is best performed
jpayne@68	72 using ‘<samp>msgcat</samp>’. It is then the translators' duty to deal with any
jpayne@68	73 possible conflicts that arose during the merge.
jpayne@68	74 </p>
jpayne@68	75 <a name="IDX485"></a>
jpayne@68	76 <p>When a translator takes over the translation job from another translator,
jpayne@68	77 but she uses a different character encoding in her locale, she will
jpayne@68	78 convert the catalog to her character encoding. This is best done through
jpayne@68	79 the ‘<samp>msgconv</samp>’ program.
jpayne@68	80 </p>
jpayne@68	81 <p>When a maintainer takes a source file with tagged messages from another
jpayne@68	82 package, he should also take the existing translations for this source
jpayne@68	83 file (and not let the translators do the same job twice). One way to do
jpayne@68	84 this is through ‘<samp>msggrep</samp>’, another is to create a POT file for
jpayne@68	85 that source file and use ‘<samp>msgmerge</samp>’.
jpayne@68	86 </p>
jpayne@68	87 <a name="IDX486"></a>
jpayne@68	88 <a name="IDX487"></a>
jpayne@68	89 <p>When a translator wants to adjust some translation catalog for a special
jpayne@68	90 dialect or orthography — for example, German as written in Switzerland
jpayne@68	91 versus German as written in Germany — she needs to apply some text
jpayne@68	92 processing to every message in the catalog. The tool for doing this is
jpayne@68	93 ‘<samp>msgfilter</samp>’.
jpayne@68	94 </p>
jpayne@68	95 <p>Another use of <code>msgfilter</code> is to produce approximately the POT file for
jpayne@68	96 which a given PO file was made. This can be done through a filter command
jpayne@68	97 like ‘<samp>msgfilter sed -e d \| sed -e '/^# /d'</samp>’. Note that the original
jpayne@68	98 POT file may have had different comments and different plural message counts,
jpayne@68	99 that's why it's better to use the original POT file if available.
jpayne@68	100 </p>
jpayne@68	101 <a name="IDX488"></a>
jpayne@68	102 <p>When a translator wants to check her translations, for example according
jpayne@68	103 to orthography rules or using a non-interactive spell checker, she can do
jpayne@68	104 so using the ‘<samp>msgexec</samp>’ program.
jpayne@68	105 </p>
jpayne@68	106 <a name="IDX489"></a>
jpayne@68	107 <p>When third party tools create PO or POT files, sometimes duplicates cannot
jpayne@68	108 be avoided. But the GNU <code>gettext</code> tools give an error when they
jpayne@68	109 encounter duplicate msgids in the same file and in the same domain.
jpayne@68	110 To merge duplicates, the ‘<samp>msguniq</samp>’ program can be used.
jpayne@68	111 </p>
jpayne@68	112 <p>‘<samp>msgcomm</samp>’ is a more general tool for keeping or throwing away
jpayne@68	113 duplicates, occurring in different files.
jpayne@68	114 </p>
jpayne@68	115 <p>‘<samp>msgcmp</samp>’ can be used to check whether a translation catalog is
jpayne@68	116 completely translated.
jpayne@68	117 </p>
jpayne@68	118 <a name="IDX490"></a>
jpayne@68	119 <p>‘<samp>msgattrib</samp>’ can be used to select and extract only the fuzzy
jpayne@68	120 or untranslated messages of a translation catalog.
jpayne@68	121 </p>
jpayne@68	122 <p>‘<samp>msgen</samp>’ is useful as a first step for preparing English translation
jpayne@68	123 catalogs. It copies each message's msgid to its msgstr.
jpayne@68	124 </p>
jpayne@68	125 <p>Finally, for those applications where all these various programs are not
jpayne@68	126 sufficient, a library ‘<samp>libgettextpo</samp>’ is provided that can be used to
jpayne@68	127 write other specialized programs that process PO files.
jpayne@68	128 </p>
jpayne@68	129
jpayne@68	130
jpayne@68	131 <a name="msgcat-Invocation"></a>
jpayne@68	132 <a name="SEC88"></a>
jpayne@68	133 <h2 class="section"> <a href="gettext_toc.html#TOC81">9.1 Invoking the <code>msgcat</code> Program</a> </h2>
jpayne@68	134
jpayne@68	135
jpayne@68	136 <table><tr><td> </td><td><pre class="example">msgcat [<var>option</var>] [<var>inputfile</var>]...
jpayne@68	137 </pre></td></tr></table>
jpayne@68	138
jpayne@68	139 <a name="IDX491"></a>
jpayne@68	140 <a name="IDX492"></a>
jpayne@68	141 <p>The <code>msgcat</code> program concatenates and merges the specified PO files.
jpayne@68	142 It finds messages which are common to two or more of the specified PO files.
jpayne@68	143 By using the <code>--more-than</code> option, greater commonality may be requested
jpayne@68	144 before messages are printed. Conversely, the <code>--less-than</code> option may be
jpayne@68	145 used to specify less commonality before messages are printed (i.e.
jpayne@68	146 ‘<samp>--less-than=2</samp>’ will only print the unique messages). Translations,
jpayne@68	147 comments, extracted comments, and file positions will be cumulated, except that
jpayne@68	148 if <code>--use-first</code> is specified, they will be taken from the first PO file
jpayne@68	149 to define them.
jpayne@68	150 </p>
jpayne@68	151 <p>To concatenate POT files, better use <code>xgettext</code>, not <code>msgcat</code>,
jpayne@68	152 because <code>msgcat</code> would choke on the undefined charsets in the specified
jpayne@68	153 POT files.
jpayne@68	154 </p>
jpayne@68	155
jpayne@68	156 <a name="SEC89"></a>
jpayne@68	157 <h3 class="subsection"> <a href="gettext_toc.html#TOC82">9.1.1 Input file location</a> </h3>
jpayne@68	158
jpayne@68	159 <dl compact="compact">
jpayne@68	160 <dt> ‘<samp><var>inputfile</var> …</samp>’</dt>
jpayne@68	161 <dd><p>Input files.
jpayne@68	162 </p>
jpayne@68	163 </dd>
jpayne@68	164 <dt> ‘<samp>-f <var>file</var></samp>’</dt>
jpayne@68	165 <dt> ‘<samp>--files-from=<var>file</var></samp>’</dt>
jpayne@68	166 <dd><a name="IDX493"></a>
jpayne@68	167 <a name="IDX494"></a>
jpayne@68	168 <p>Read the names of the input files from <var>file</var> instead of getting
jpayne@68	169 them from the command line.
jpayne@68	170 </p>
jpayne@68	171 </dd>
jpayne@68	172 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	173 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	174 <dd><a name="IDX495"></a>
jpayne@68	175 <a name="IDX496"></a>
jpayne@68	176 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	177 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	178 file will be written relative to the current directory, though.
jpayne@68	179 </p>
jpayne@68	180 </dd>
jpayne@68	181 </dl>
jpayne@68	182
jpayne@68	183 <p>If <var>inputfile</var> is ‘<samp>-</samp>’, standard input is read.
jpayne@68	184 </p>
jpayne@68	185
jpayne@68	186 <a name="SEC90"></a>
jpayne@68	187 <h3 class="subsection"> <a href="gettext_toc.html#TOC83">9.1.2 Output file location</a> </h3>
jpayne@68	188
jpayne@68	189 <dl compact="compact">
jpayne@68	190 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	191 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	192 <dd><a name="IDX497"></a>
jpayne@68	193 <a name="IDX498"></a>
jpayne@68	194 <p>Write output to specified file.
jpayne@68	195 </p>
jpayne@68	196 </dd>
jpayne@68	197 </dl>
jpayne@68	198
jpayne@68	199 <a name="IDX499"></a>
jpayne@68	200 <p>The results are written to standard output if no output file is specified
jpayne@68	201 or if it is ‘<samp>-</samp>’.
jpayne@68	202 </p>
jpayne@68	203
jpayne@68	204 <a name="SEC91"></a>
jpayne@68	205 <h3 class="subsection"> <a href="gettext_toc.html#TOC84">9.1.3 Message selection</a> </h3>
jpayne@68	206
jpayne@68	207 <dl compact="compact">
jpayne@68	208 <dt> ‘<samp>-< <var>number</var></samp>’</dt>
jpayne@68	209 <dt> ‘<samp>--less-than=<var>number</var></samp>’</dt>
jpayne@68	210 <dd><a name="IDX500"></a>
jpayne@68	211 <a name="IDX501"></a>
jpayne@68	212 <p>Print messages with less than <var>number</var> definitions, defaults to infinite
jpayne@68	213 if not set.
jpayne@68	214 </p>
jpayne@68	215 </dd>
jpayne@68	216 <dt> ‘<samp>-> <var>number</var></samp>’</dt>
jpayne@68	217 <dt> ‘<samp>--more-than=<var>number</var></samp>’</dt>
jpayne@68	218 <dd><a name="IDX502"></a>
jpayne@68	219 <a name="IDX503"></a>
jpayne@68	220 <p>Print messages with more than <var>number</var> definitions, defaults to 0 if not
jpayne@68	221 set.
jpayne@68	222 </p>
jpayne@68	223 </dd>
jpayne@68	224 <dt> ‘<samp>-u</samp>’</dt>
jpayne@68	225 <dt> ‘<samp>--unique</samp>’</dt>
jpayne@68	226 <dd><a name="IDX504"></a>
jpayne@68	227 <a name="IDX505"></a>
jpayne@68	228 <p>Shorthand for ‘<samp>--less-than=2</samp>’. Requests that only unique messages be
jpayne@68	229 printed.
jpayne@68	230 </p>
jpayne@68	231 </dd>
jpayne@68	232 </dl>
jpayne@68	233
jpayne@68	234
jpayne@68	235 <a name="SEC92"></a>
jpayne@68	236 <h3 class="subsection"> <a href="gettext_toc.html#TOC85">9.1.4 Input file syntax</a> </h3>
jpayne@68	237
jpayne@68	238 <dl compact="compact">
jpayne@68	239 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	240 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	241 <dd><a name="IDX506"></a>
jpayne@68	242 <a name="IDX507"></a>
jpayne@68	243 <p>Assume the input files are Java ResourceBundles in Java <code>.properties</code>
jpayne@68	244 syntax, not in PO file syntax.
jpayne@68	245 </p>
jpayne@68	246 </dd>
jpayne@68	247 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	248 <dd><a name="IDX508"></a>
jpayne@68	249 <p>Assume the input files are NeXTstep/GNUstep localized resource files in
jpayne@68	250 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	251 </p>
jpayne@68	252 </dd>
jpayne@68	253 </dl>
jpayne@68	254
jpayne@68	255
jpayne@68	256 <a name="SEC93"></a>
jpayne@68	257 <h3 class="subsection"> <a href="gettext_toc.html#TOC86">9.1.5 Output details</a> </h3>
jpayne@68	258
jpayne@68	259
jpayne@68	260 <dl compact="compact">
jpayne@68	261 <dt> ‘<samp>-t</samp>’</dt>
jpayne@68	262 <dt> ‘<samp>--to-code=<var>name</var></samp>’</dt>
jpayne@68	263 <dd><a name="IDX509"></a>
jpayne@68	264 <a name="IDX510"></a>
jpayne@68	265 <p>Specify encoding for output.
jpayne@68	266 </p>
jpayne@68	267 </dd>
jpayne@68	268 <dt> ‘<samp>--use-first</samp>’</dt>
jpayne@68	269 <dd><a name="IDX511"></a>
jpayne@68	270 <p>Use first available translation for each message. Don't merge several
jpayne@68	271 translations into one.
jpayne@68	272 </p>
jpayne@68	273 </dd>
jpayne@68	274 <dt> ‘<samp>--lang=<var>catalogname</var></samp>’</dt>
jpayne@68	275 <dd><a name="IDX512"></a>
jpayne@68	276 <p>Specify the ‘<samp>Language</samp>’ field to be used in the header entry. See
jpayne@68	277 <a href="gettext_6.html#SEC52">Filling in the Header Entry</a> for the meaning of this field. Note: The
jpayne@68	278 ‘<samp>Language-Team</samp>’ and ‘<samp>Plural-Forms</samp>’ fields are left unchanged.
jpayne@68	279 </p>
jpayne@68	280 </dd>
jpayne@68	281 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	282 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	283 <dd><a name="IDX513"></a>
jpayne@68	284 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	285 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	286 </p>
jpayne@68	287 </dd>
jpayne@68	288 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	289 <dd><a name="IDX514"></a>
jpayne@68	290 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	291 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	292 </p>
jpayne@68	293 </dd>
jpayne@68	294 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	295 <dd><a name="IDX515"></a>
jpayne@68	296 <p>Always write an output file even if it contains no message.
jpayne@68	297 </p>
jpayne@68	298 </dd>
jpayne@68	299 <dt> ‘<samp>-i</samp>’</dt>
jpayne@68	300 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	301 <dd><a name="IDX516"></a>
jpayne@68	302 <a name="IDX517"></a>
jpayne@68	303 <p>Write the .po file using indented style.
jpayne@68	304 </p>
jpayne@68	305 </dd>
jpayne@68	306 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	307 <dd><a name="IDX518"></a>
jpayne@68	308 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	309 </p>
jpayne@68	310 </dd>
jpayne@68	311 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	312 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	313 <dd><a name="IDX519"></a>
jpayne@68	314 <a name="IDX520"></a>
jpayne@68	315 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	316 </p>
jpayne@68	317 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	318 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	319 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	320 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	321 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	322 </p>
jpayne@68	323 </dd>
jpayne@68	324 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	325 <dd><a name="IDX521"></a>
jpayne@68	326 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	327 Uniforum format should be avoided because it doesn't support the
jpayne@68	328 GNU extensions.
jpayne@68	329 </p>
jpayne@68	330 </dd>
jpayne@68	331 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	332 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	333 <dd><a name="IDX522"></a>
jpayne@68	334 <a name="IDX523"></a>
jpayne@68	335 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	336 that this file format doesn't support plural forms and silently drops
jpayne@68	337 obsolete messages.
jpayne@68	338 </p>
jpayne@68	339 </dd>
jpayne@68	340 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	341 <dd><a name="IDX524"></a>
jpayne@68	342 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	343 Note that this file format doesn't support plural forms.
jpayne@68	344 </p>
jpayne@68	345 </dd>
jpayne@68	346 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	347 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	348 <dd><a name="IDX525"></a>
jpayne@68	349 <a name="IDX526"></a>
jpayne@68	350 <p>Set the output page width. Long strings in the output files will be
jpayne@68	351 split across multiple lines in order to ensure that each line's width
jpayne@68	352 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	353 </p>
jpayne@68	354 </dd>
jpayne@68	355 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	356 <dd><a name="IDX527"></a>
jpayne@68	357 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	358 output page width will not be split into several lines. Only file reference
jpayne@68	359 lines which are wider than the output page width will be split.
jpayne@68	360 </p>
jpayne@68	361 </dd>
jpayne@68	362 <dt> ‘<samp>-s</samp>’</dt>
jpayne@68	363 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	364 <dd><a name="IDX528"></a>
jpayne@68	365 <a name="IDX529"></a>
jpayne@68	366 <a name="IDX530"></a>
jpayne@68	367 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	368 for the translator to understand each message's context.
jpayne@68	369 </p>
jpayne@68	370 </dd>
jpayne@68	371 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	372 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	373 <dd><a name="IDX531"></a>
jpayne@68	374 <a name="IDX532"></a>
jpayne@68	375 <p>Sort output by file location.
jpayne@68	376 </p>
jpayne@68	377 </dd>
jpayne@68	378 </dl>
jpayne@68	379
jpayne@68	380
jpayne@68	381 <a name="SEC94"></a>
jpayne@68	382 <h3 class="subsection"> <a href="gettext_toc.html#TOC87">9.1.6 Informative output</a> </h3>
jpayne@68	383
jpayne@68	384 <dl compact="compact">
jpayne@68	385 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	386 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	387 <dd><a name="IDX533"></a>
jpayne@68	388 <a name="IDX534"></a>
jpayne@68	389 <p>Display this help and exit.
jpayne@68	390 </p>
jpayne@68	391 </dd>
jpayne@68	392 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	393 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	394 <dd><a name="IDX535"></a>
jpayne@68	395 <a name="IDX536"></a>
jpayne@68	396 <p>Output version information and exit.
jpayne@68	397 </p>
jpayne@68	398 </dd>
jpayne@68	399 </dl>
jpayne@68	400
jpayne@68	401
jpayne@68	402 <a name="msgconv-Invocation"></a>
jpayne@68	403 <a name="SEC95"></a>
jpayne@68	404 <h2 class="section"> <a href="gettext_toc.html#TOC88">9.2 Invoking the <code>msgconv</code> Program</a> </h2>
jpayne@68	405
jpayne@68	406
jpayne@68	407 <table><tr><td> </td><td><pre class="example">msgconv [<var>option</var>] [<var>inputfile</var>]
jpayne@68	408 </pre></td></tr></table>
jpayne@68	409
jpayne@68	410 <a name="IDX537"></a>
jpayne@68	411 <p>The <code>msgconv</code> program converts a translation catalog to a different
jpayne@68	412 character encoding.
jpayne@68	413 </p>
jpayne@68	414
jpayne@68	415 <a name="SEC96"></a>
jpayne@68	416 <h3 class="subsection"> <a href="gettext_toc.html#TOC89">9.2.1 Input file location</a> </h3>
jpayne@68	417
jpayne@68	418 <dl compact="compact">
jpayne@68	419 <dt> ‘<samp><var>inputfile</var></samp>’</dt>
jpayne@68	420 <dd><p>Input PO file.
jpayne@68	421 </p>
jpayne@68	422 </dd>
jpayne@68	423 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	424 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	425 <dd><a name="IDX538"></a>
jpayne@68	426 <a name="IDX539"></a>
jpayne@68	427 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	428 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	429 file will be written relative to the current directory, though.
jpayne@68	430 </p>
jpayne@68	431 </dd>
jpayne@68	432 </dl>
jpayne@68	433
jpayne@68	434 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read.
jpayne@68	435 </p>
jpayne@68	436
jpayne@68	437 <a name="SEC97"></a>
jpayne@68	438 <h3 class="subsection"> <a href="gettext_toc.html#TOC90">9.2.2 Output file location</a> </h3>
jpayne@68	439
jpayne@68	440 <dl compact="compact">
jpayne@68	441 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	442 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	443 <dd><a name="IDX540"></a>
jpayne@68	444 <a name="IDX541"></a>
jpayne@68	445 <p>Write output to specified file.
jpayne@68	446 </p>
jpayne@68	447 </dd>
jpayne@68	448 </dl>
jpayne@68	449
jpayne@68	450 <p>The results are written to standard output if no output file is specified
jpayne@68	451 or if it is ‘<samp>-</samp>’.
jpayne@68	452 </p>
jpayne@68	453
jpayne@68	454 <a name="SEC98"></a>
jpayne@68	455 <h3 class="subsection"> <a href="gettext_toc.html#TOC91">9.2.3 Conversion target</a> </h3>
jpayne@68	456
jpayne@68	457 <dl compact="compact">
jpayne@68	458 <dt> ‘<samp>-t</samp>’</dt>
jpayne@68	459 <dt> ‘<samp>--to-code=<var>name</var></samp>’</dt>
jpayne@68	460 <dd><a name="IDX542"></a>
jpayne@68	461 <a name="IDX543"></a>
jpayne@68	462 <p>Specify encoding for output.
jpayne@68	463 </p>
jpayne@68	464 </dd>
jpayne@68	465 </dl>
jpayne@68	466
jpayne@68	467 <p>The default encoding is the current locale's encoding.
jpayne@68	468 </p>
jpayne@68	469
jpayne@68	470 <a name="SEC99"></a>
jpayne@68	471 <h3 class="subsection"> <a href="gettext_toc.html#TOC92">9.2.4 Input file syntax</a> </h3>
jpayne@68	472
jpayne@68	473 <dl compact="compact">
jpayne@68	474 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	475 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	476 <dd><a name="IDX544"></a>
jpayne@68	477 <a name="IDX545"></a>
jpayne@68	478 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code>
jpayne@68	479 syntax, not in PO file syntax.
jpayne@68	480 </p>
jpayne@68	481 </dd>
jpayne@68	482 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	483 <dd><a name="IDX546"></a>
jpayne@68	484 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in
jpayne@68	485 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	486 </p>
jpayne@68	487 </dd>
jpayne@68	488 </dl>
jpayne@68	489
jpayne@68	490
jpayne@68	491 <a name="SEC100"></a>
jpayne@68	492 <h3 class="subsection"> <a href="gettext_toc.html#TOC93">9.2.5 Output details</a> </h3>
jpayne@68	493
jpayne@68	494
jpayne@68	495 <dl compact="compact">
jpayne@68	496 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	497 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	498 <dd><a name="IDX547"></a>
jpayne@68	499 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	500 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	501 </p>
jpayne@68	502 </dd>
jpayne@68	503 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	504 <dd><a name="IDX548"></a>
jpayne@68	505 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	506 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	507 </p>
jpayne@68	508 </dd>
jpayne@68	509 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	510 <dd><a name="IDX549"></a>
jpayne@68	511 <p>Always write an output file even if it contains no message.
jpayne@68	512 </p>
jpayne@68	513 </dd>
jpayne@68	514 <dt> ‘<samp>-i</samp>’</dt>
jpayne@68	515 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	516 <dd><a name="IDX550"></a>
jpayne@68	517 <a name="IDX551"></a>
jpayne@68	518 <p>Write the .po file using indented style.
jpayne@68	519 </p>
jpayne@68	520 </dd>
jpayne@68	521 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	522 <dd><a name="IDX552"></a>
jpayne@68	523 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	524 </p>
jpayne@68	525 </dd>
jpayne@68	526 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	527 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	528 <dd><a name="IDX553"></a>
jpayne@68	529 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	530 </p>
jpayne@68	531 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	532 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	533 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	534 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	535 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	536 </p>
jpayne@68	537 </dd>
jpayne@68	538 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	539 <dd><a name="IDX554"></a>
jpayne@68	540 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	541 Uniforum format should be avoided because it doesn't support the
jpayne@68	542 GNU extensions.
jpayne@68	543 </p>
jpayne@68	544 </dd>
jpayne@68	545 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	546 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	547 <dd><a name="IDX555"></a>
jpayne@68	548 <a name="IDX556"></a>
jpayne@68	549 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	550 that this file format doesn't support plural forms and silently drops
jpayne@68	551 obsolete messages.
jpayne@68	552 </p>
jpayne@68	553 </dd>
jpayne@68	554 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	555 <dd><a name="IDX557"></a>
jpayne@68	556 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	557 Note that this file format doesn't support plural forms.
jpayne@68	558 </p>
jpayne@68	559 </dd>
jpayne@68	560 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	561 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	562 <dd><a name="IDX558"></a>
jpayne@68	563 <a name="IDX559"></a>
jpayne@68	564 <p>Set the output page width. Long strings in the output files will be
jpayne@68	565 split across multiple lines in order to ensure that each line's width
jpayne@68	566 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	567 </p>
jpayne@68	568 </dd>
jpayne@68	569 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	570 <dd><a name="IDX560"></a>
jpayne@68	571 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	572 output page width will not be split into several lines. Only file reference
jpayne@68	573 lines which are wider than the output page width will be split.
jpayne@68	574 </p>
jpayne@68	575 </dd>
jpayne@68	576 <dt> ‘<samp>-s</samp>’</dt>
jpayne@68	577 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	578 <dd><a name="IDX561"></a>
jpayne@68	579 <a name="IDX562"></a>
jpayne@68	580 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	581 for the translator to understand each message's context.
jpayne@68	582 </p>
jpayne@68	583 </dd>
jpayne@68	584 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	585 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	586 <dd><a name="IDX563"></a>
jpayne@68	587 <a name="IDX564"></a>
jpayne@68	588 <p>Sort output by file location.
jpayne@68	589 </p>
jpayne@68	590 </dd>
jpayne@68	591 </dl>
jpayne@68	592
jpayne@68	593
jpayne@68	594 <a name="SEC101"></a>
jpayne@68	595 <h3 class="subsection"> <a href="gettext_toc.html#TOC94">9.2.6 Informative output</a> </h3>
jpayne@68	596
jpayne@68	597 <dl compact="compact">
jpayne@68	598 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	599 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	600 <dd><a name="IDX565"></a>
jpayne@68	601 <a name="IDX566"></a>
jpayne@68	602 <p>Display this help and exit.
jpayne@68	603 </p>
jpayne@68	604 </dd>
jpayne@68	605 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	606 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	607 <dd><a name="IDX567"></a>
jpayne@68	608 <a name="IDX568"></a>
jpayne@68	609 <p>Output version information and exit.
jpayne@68	610 </p>
jpayne@68	611 </dd>
jpayne@68	612 </dl>
jpayne@68	613
jpayne@68	614
jpayne@68	615 <a name="msggrep-Invocation"></a>
jpayne@68	616 <a name="SEC102"></a>
jpayne@68	617 <h2 class="section"> <a href="gettext_toc.html#TOC95">9.3 Invoking the <code>msggrep</code> Program</a> </h2>
jpayne@68	618
jpayne@68	619
jpayne@68	620 <table><tr><td> </td><td><pre class="example">msggrep [<var>option</var>] [<var>inputfile</var>]
jpayne@68	621 </pre></td></tr></table>
jpayne@68	622
jpayne@68	623 <a name="IDX569"></a>
jpayne@68	624 <p>The <code>msggrep</code> program extracts all messages of a translation catalog
jpayne@68	625 that match a given pattern or belong to some given source files.
jpayne@68	626 </p>
jpayne@68	627
jpayne@68	628 <a name="SEC103"></a>
jpayne@68	629 <h3 class="subsection"> <a href="gettext_toc.html#TOC96">9.3.1 Input file location</a> </h3>
jpayne@68	630
jpayne@68	631 <dl compact="compact">
jpayne@68	632 <dt> ‘<samp><var>inputfile</var></samp>’</dt>
jpayne@68	633 <dd><p>Input PO file.
jpayne@68	634 </p>
jpayne@68	635 </dd>
jpayne@68	636 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	637 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	638 <dd><a name="IDX570"></a>
jpayne@68	639 <a name="IDX571"></a>
jpayne@68	640 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	641 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	642 file will be written relative to the current directory, though.
jpayne@68	643 </p>
jpayne@68	644 </dd>
jpayne@68	645 </dl>
jpayne@68	646
jpayne@68	647 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read.
jpayne@68	648 </p>
jpayne@68	649
jpayne@68	650 <a name="SEC104"></a>
jpayne@68	651 <h3 class="subsection"> <a href="gettext_toc.html#TOC97">9.3.2 Output file location</a> </h3>
jpayne@68	652
jpayne@68	653 <dl compact="compact">
jpayne@68	654 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	655 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	656 <dd><a name="IDX572"></a>
jpayne@68	657 <a name="IDX573"></a>
jpayne@68	658 <p>Write output to specified file.
jpayne@68	659 </p>
jpayne@68	660 </dd>
jpayne@68	661 </dl>
jpayne@68	662
jpayne@68	663 <p>The results are written to standard output if no output file is specified
jpayne@68	664 or if it is ‘<samp>-</samp>’.
jpayne@68	665 </p>
jpayne@68	666
jpayne@68	667 <a name="SEC105"></a>
jpayne@68	668 <h3 class="subsection"> <a href="gettext_toc.html#TOC98">9.3.3 Message selection</a> </h3>
jpayne@68	669
jpayne@68	670 <table><tr><td> </td><td><pre class="example"> [-N <var>sourcefile</var>]... [-M <var>domainname</var>]...
jpayne@68	671 [-J <var>msgctxt-pattern</var>] [-K <var>msgid-pattern</var>] [-T <var>msgstr-pattern</var>]
jpayne@68	672 [-C <var>comment-pattern</var>]
jpayne@68	673 </pre></td></tr></table>
jpayne@68	674
jpayne@68	675 <p>A message is selected if
jpayne@68	676 </p><ul>
jpayne@68	677 <li> it comes from one of the specified source files,
jpayne@68	678 </li><li> or if it comes from one of the specified domains,
jpayne@68	679 </li><li> or if ‘<samp>-J</samp>’ is given and its context (msgctxt) matches
jpayne@68	680 <var>msgctxt-pattern</var>,
jpayne@68	681 </li><li> or if ‘<samp>-K</samp>’ is given and its key (msgid or msgid_plural) matches
jpayne@68	682 <var>msgid-pattern</var>,
jpayne@68	683 </li><li> or if ‘<samp>-T</samp>’ is given and its translation (msgstr) matches
jpayne@68	684 <var>msgstr-pattern</var>,
jpayne@68	685 </li><li> or if ‘<samp>-C</samp>’ is given and the translator's comment matches
jpayne@68	686 <var>comment-pattern</var>.
jpayne@68	687 </li></ul>
jpayne@68	688
jpayne@68	689 <p>When more than one selection criterion is specified, the set of selected
jpayne@68	690 messages is the union of the selected messages of each criterion.
jpayne@68	691 </p>
jpayne@68	692 <p><var>msgctxt-pattern</var> or <var>msgid-pattern</var> or <var>msgstr-pattern</var> syntax:
jpayne@68	693 </p><table><tr><td> </td><td><pre class="example"> [-E \| -F] [-e <var>pattern</var> \| -f <var>file</var>]...
jpayne@68	694 </pre></td></tr></table>
jpayne@68	695 <p><var>pattern</var>s are basic regular expressions by default, or extended regular
jpayne@68	696 expressions if -E is given, or fixed strings if -F is given.
jpayne@68	697 </p>
jpayne@68	698 <dl compact="compact">
jpayne@68	699 <dt> ‘<samp>-N <var>sourcefile</var></samp>’</dt>
jpayne@68	700 <dt> ‘<samp>--location=<var>sourcefile</var></samp>’</dt>
jpayne@68	701 <dd><a name="IDX574"></a>
jpayne@68	702 <a name="IDX575"></a>
jpayne@68	703 <p>Select messages extracted from <var>sourcefile</var>. <var>sourcefile</var> can be
jpayne@68	704 either a literal file name or a wildcard pattern.
jpayne@68	705 </p>
jpayne@68	706 </dd>
jpayne@68	707 <dt> ‘<samp>-M <var>domainname</var></samp>’</dt>
jpayne@68	708 <dt> ‘<samp>--domain=<var>domainname</var></samp>’</dt>
jpayne@68	709 <dd><a name="IDX576"></a>
jpayne@68	710 <a name="IDX577"></a>
jpayne@68	711 <p>Select messages belonging to domain <var>domainname</var>.
jpayne@68	712 </p>
jpayne@68	713 </dd>
jpayne@68	714 <dt> ‘<samp>-J</samp>’</dt>
jpayne@68	715 <dt> ‘<samp>--msgctxt</samp>’</dt>
jpayne@68	716 <dd><a name="IDX578"></a>
jpayne@68	717 <a name="IDX579"></a>
jpayne@68	718 <p>Start of patterns for the msgctxt.
jpayne@68	719 </p>
jpayne@68	720 </dd>
jpayne@68	721 <dt> ‘<samp>-K</samp>’</dt>
jpayne@68	722 <dt> ‘<samp>--msgid</samp>’</dt>
jpayne@68	723 <dd><a name="IDX580"></a>
jpayne@68	724 <a name="IDX581"></a>
jpayne@68	725 <p>Start of patterns for the msgid.
jpayne@68	726 </p>
jpayne@68	727 </dd>
jpayne@68	728 <dt> ‘<samp>-T</samp>’</dt>
jpayne@68	729 <dt> ‘<samp>--msgstr</samp>’</dt>
jpayne@68	730 <dd><a name="IDX582"></a>
jpayne@68	731 <a name="IDX583"></a>
jpayne@68	732 <p>Start of patterns for the msgstr.
jpayne@68	733 </p>
jpayne@68	734 </dd>
jpayne@68	735 <dt> ‘<samp>-C</samp>’</dt>
jpayne@68	736 <dt> ‘<samp>--comment</samp>’</dt>
jpayne@68	737 <dd><a name="IDX584"></a>
jpayne@68	738 <a name="IDX585"></a>
jpayne@68	739 <p>Start of patterns for the translator's comment.
jpayne@68	740 </p>
jpayne@68	741 </dd>
jpayne@68	742 <dt> ‘<samp>-X</samp>’</dt>
jpayne@68	743 <dt> ‘<samp>--extracted-comment</samp>’</dt>
jpayne@68	744 <dd><a name="IDX586"></a>
jpayne@68	745 <a name="IDX587"></a>
jpayne@68	746 <p>Start of patterns for the extracted comments.
jpayne@68	747 </p>
jpayne@68	748 </dd>
jpayne@68	749 <dt> ‘<samp>-E</samp>’</dt>
jpayne@68	750 <dt> ‘<samp>--extended-regexp</samp>’</dt>
jpayne@68	751 <dd><a name="IDX588"></a>
jpayne@68	752 <a name="IDX589"></a>
jpayne@68	753 <p>Specify that <var>pattern</var> is an extended regular expression.
jpayne@68	754 </p>
jpayne@68	755 </dd>
jpayne@68	756 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	757 <dt> ‘<samp>--fixed-strings</samp>’</dt>
jpayne@68	758 <dd><a name="IDX590"></a>
jpayne@68	759 <a name="IDX591"></a>
jpayne@68	760 <p>Specify that <var>pattern</var> is a set of newline-separated strings.
jpayne@68	761 </p>
jpayne@68	762 </dd>
jpayne@68	763 <dt> ‘<samp>-e <var>pattern</var></samp>’</dt>
jpayne@68	764 <dt> ‘<samp>--regexp=<var>pattern</var></samp>’</dt>
jpayne@68	765 <dd><a name="IDX592"></a>
jpayne@68	766 <a name="IDX593"></a>
jpayne@68	767 <p>Use <var>pattern</var> as a regular expression.
jpayne@68	768 </p>
jpayne@68	769 </dd>
jpayne@68	770 <dt> ‘<samp>-f <var>file</var></samp>’</dt>
jpayne@68	771 <dt> ‘<samp>--file=<var>file</var></samp>’</dt>
jpayne@68	772 <dd><a name="IDX594"></a>
jpayne@68	773 <a name="IDX595"></a>
jpayne@68	774 <p>Obtain <var>pattern</var> from <var>file</var>.
jpayne@68	775 </p>
jpayne@68	776 </dd>
jpayne@68	777 <dt> ‘<samp>-i</samp>’</dt>
jpayne@68	778 <dt> ‘<samp>--ignore-case</samp>’</dt>
jpayne@68	779 <dd><a name="IDX596"></a>
jpayne@68	780 <a name="IDX597"></a>
jpayne@68	781 <p>Ignore case distinctions.
jpayne@68	782 </p>
jpayne@68	783 </dd>
jpayne@68	784 <dt> ‘<samp>-v</samp>’</dt>
jpayne@68	785 <dt> ‘<samp>--invert-match</samp>’</dt>
jpayne@68	786 <dd><a name="IDX598"></a>
jpayne@68	787 <a name="IDX599"></a>
jpayne@68	788 <p>Output only the messages that do not match any selection criterion, instead
jpayne@68	789 of the messages that match a selection criterion.
jpayne@68	790 </p>
jpayne@68	791 </dd>
jpayne@68	792 </dl>
jpayne@68	793
jpayne@68	794
jpayne@68	795 <a name="SEC106"></a>
jpayne@68	796 <h3 class="subsection"> <a href="gettext_toc.html#TOC99">9.3.4 Input file syntax</a> </h3>
jpayne@68	797
jpayne@68	798 <dl compact="compact">
jpayne@68	799 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	800 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	801 <dd><a name="IDX600"></a>
jpayne@68	802 <a name="IDX601"></a>
jpayne@68	803 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code>
jpayne@68	804 syntax, not in PO file syntax.
jpayne@68	805 </p>
jpayne@68	806 </dd>
jpayne@68	807 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	808 <dd><a name="IDX602"></a>
jpayne@68	809 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in
jpayne@68	810 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	811 </p>
jpayne@68	812 </dd>
jpayne@68	813 </dl>
jpayne@68	814
jpayne@68	815
jpayne@68	816 <a name="SEC107"></a>
jpayne@68	817 <h3 class="subsection"> <a href="gettext_toc.html#TOC100">9.3.5 Output details</a> </h3>
jpayne@68	818
jpayne@68	819
jpayne@68	820 <dl compact="compact">
jpayne@68	821 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	822 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	823 <dd><a name="IDX603"></a>
jpayne@68	824 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	825 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	826 </p>
jpayne@68	827 </dd>
jpayne@68	828 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	829 <dd><a name="IDX604"></a>
jpayne@68	830 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	831 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	832 </p>
jpayne@68	833 </dd>
jpayne@68	834 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	835 <dd><a name="IDX605"></a>
jpayne@68	836 <p>Always write an output file even if it contains no message.
jpayne@68	837 </p>
jpayne@68	838 </dd>
jpayne@68	839 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	840 <dd><a name="IDX606"></a>
jpayne@68	841 <p>Write the .po file using indented style.
jpayne@68	842 </p>
jpayne@68	843 </dd>
jpayne@68	844 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	845 <dd><a name="IDX607"></a>
jpayne@68	846 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	847 </p>
jpayne@68	848 </dd>
jpayne@68	849 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	850 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	851 <dd><a name="IDX608"></a>
jpayne@68	852 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	853 </p>
jpayne@68	854 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	855 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	856 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	857 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	858 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	859 </p>
jpayne@68	860 </dd>
jpayne@68	861 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	862 <dd><a name="IDX609"></a>
jpayne@68	863 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	864 Uniforum format should be avoided because it doesn't support the
jpayne@68	865 GNU extensions.
jpayne@68	866 </p>
jpayne@68	867 </dd>
jpayne@68	868 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	869 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	870 <dd><a name="IDX610"></a>
jpayne@68	871 <a name="IDX611"></a>
jpayne@68	872 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	873 that this file format doesn't support plural forms and silently drops
jpayne@68	874 obsolete messages.
jpayne@68	875 </p>
jpayne@68	876 </dd>
jpayne@68	877 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	878 <dd><a name="IDX612"></a>
jpayne@68	879 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	880 Note that this file format doesn't support plural forms.
jpayne@68	881 </p>
jpayne@68	882 </dd>
jpayne@68	883 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	884 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	885 <dd><a name="IDX613"></a>
jpayne@68	886 <a name="IDX614"></a>
jpayne@68	887 <p>Set the output page width. Long strings in the output files will be
jpayne@68	888 split across multiple lines in order to ensure that each line's width
jpayne@68	889 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	890 </p>
jpayne@68	891 </dd>
jpayne@68	892 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	893 <dd><a name="IDX615"></a>
jpayne@68	894 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	895 output page width will not be split into several lines. Only file reference
jpayne@68	896 lines which are wider than the output page width will be split.
jpayne@68	897 </p>
jpayne@68	898 </dd>
jpayne@68	899 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	900 <dd><a name="IDX616"></a>
jpayne@68	901 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	902 for the translator to understand each message's context.
jpayne@68	903 </p>
jpayne@68	904 </dd>
jpayne@68	905 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	906 <dd><a name="IDX617"></a>
jpayne@68	907 <p>Sort output by file location.
jpayne@68	908 </p>
jpayne@68	909 </dd>
jpayne@68	910 </dl>
jpayne@68	911
jpayne@68	912
jpayne@68	913 <a name="SEC108"></a>
jpayne@68	914 <h3 class="subsection"> <a href="gettext_toc.html#TOC101">9.3.6 Informative output</a> </h3>
jpayne@68	915
jpayne@68	916 <dl compact="compact">
jpayne@68	917 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	918 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	919 <dd><a name="IDX618"></a>
jpayne@68	920 <a name="IDX619"></a>
jpayne@68	921 <p>Display this help and exit.
jpayne@68	922 </p>
jpayne@68	923 </dd>
jpayne@68	924 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	925 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	926 <dd><a name="IDX620"></a>
jpayne@68	927 <a name="IDX621"></a>
jpayne@68	928 <p>Output version information and exit.
jpayne@68	929 </p>
jpayne@68	930 </dd>
jpayne@68	931 </dl>
jpayne@68	932
jpayne@68	933
jpayne@68	934 <a name="SEC109"></a>
jpayne@68	935 <h3 class="subsection"> <a href="gettext_toc.html#TOC102">9.3.7 Examples</a> </h3>
jpayne@68	936
jpayne@68	937 <p>To extract the messages that come from the source files
jpayne@68	938 <code>gnulib-lib/error.c</code> and <code>gnulib-lib/getopt.c</code>:
jpayne@68	939 </p>
jpayne@68	940 <table><tr><td> </td><td><pre class="smallexample">msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po
jpayne@68	941 </pre></td></tr></table>
jpayne@68	942
jpayne@68	943 <p>To extract the messages that contain the string “Please specify” in the
jpayne@68	944 original string:
jpayne@68	945 </p>
jpayne@68	946 <table><tr><td> </td><td><pre class="smallexample">msggrep --msgid -F -e 'Please specify' input.po
jpayne@68	947 </pre></td></tr></table>
jpayne@68	948
jpayne@68	949 <p>To extract the messages that have a context specifier of either “Menu>File”
jpayne@68	950 or “Menu>Edit” or a submenu of them:
jpayne@68	951 </p>
jpayne@68	952 <table><tr><td> </td><td><pre class="smallexample">msggrep --msgctxt -E -e '^Menu>(File\|Edit)' input.po
jpayne@68	953 </pre></td></tr></table>
jpayne@68	954
jpayne@68	955 <p>To extract the messages whose translation contains one of the strings in the
jpayne@68	956 file <code>wordlist.txt</code>:
jpayne@68	957 </p>
jpayne@68	958 <table><tr><td> </td><td><pre class="smallexample">msggrep --msgstr -F -f wordlist.txt input.po
jpayne@68	959 </pre></td></tr></table>
jpayne@68	960
jpayne@68	961
jpayne@68	962 <a name="msgfilter-Invocation"></a>
jpayne@68	963 <a name="SEC110"></a>
jpayne@68	964 <h2 class="section"> <a href="gettext_toc.html#TOC103">9.4 Invoking the <code>msgfilter</code> Program</a> </h2>
jpayne@68	965
jpayne@68	966
jpayne@68	967 <table><tr><td> </td><td><pre class="example">msgfilter [<var>option</var>] <var>filter</var> [<var>filter-option</var>]
jpayne@68	968 </pre></td></tr></table>
jpayne@68	969
jpayne@68	970 <a name="IDX622"></a>
jpayne@68	971 <p>The <code>msgfilter</code> program applies a filter to all translations of a
jpayne@68	972 translation catalog.
jpayne@68	973 </p>
jpayne@68	974 <a name="IDX623"></a>
jpayne@68	975 <a name="IDX624"></a>
jpayne@68	976 <a name="IDX625"></a>
jpayne@68	977 <a name="IDX626"></a>
jpayne@68	978 <a name="IDX627"></a>
jpayne@68	979 <a name="IDX628"></a>
jpayne@68	980 <a name="IDX629"></a>
jpayne@68	981 <a name="IDX630"></a>
jpayne@68	982 <p>During each <var>filter</var> invocation, the environment variable
jpayne@68	983 <code>MSGFILTER_MSGID</code> is bound to the message's msgid, and the environment
jpayne@68	984 variable <code>MSGFILTER_LOCATION</code> is bound to the location in the PO file
jpayne@68	985 of the message. If the message has a context, the environment variable
jpayne@68	986 <code>MSGFILTER_MSGCTXT</code> is bound to the message's msgctxt, otherwise it is
jpayne@68	987 unbound. If the message has a plural form, environment variable
jpayne@68	988 <code>MSGFILTER_MSGID_PLURAL</code> is bound to the message's msgid_plural and
jpayne@68	989 <code>MSGFILTER_PLURAL_FORM</code> is bound to the order number of the plural
jpayne@68	990 actually processed (starting with 0), otherwise both are unbound.
jpayne@68	991 If the message has a previous msgid (added by <code>msgmerge</code>),
jpayne@68	992 environment variable <code>MSGFILTER_PREV_MSGCTXT</code> is bound to the
jpayne@68	993 message's previous msgctxt, <code>MSGFILTER_PREV_MSGID</code> is bound to
jpayne@68	994 the previous msgid, and <code>MSGFILTER_PREV_MSGID_PLURAL</code> is bound to
jpayne@68	995 the previous msgid_plural.
jpayne@68	996 </p>
jpayne@68	997
jpayne@68	998 <a name="SEC111"></a>
jpayne@68	999 <h3 class="subsection"> <a href="gettext_toc.html#TOC104">9.4.1 Input file location</a> </h3>
jpayne@68	1000
jpayne@68	1001 <dl compact="compact">
jpayne@68	1002 <dt> ‘<samp>-i <var>inputfile</var></samp>’</dt>
jpayne@68	1003 <dt> ‘<samp>--input=<var>inputfile</var></samp>’</dt>
jpayne@68	1004 <dd><a name="IDX631"></a>
jpayne@68	1005 <a name="IDX632"></a>
jpayne@68	1006 <p>Input PO file.
jpayne@68	1007 </p>
jpayne@68	1008 </dd>
jpayne@68	1009 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	1010 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	1011 <dd><a name="IDX633"></a>
jpayne@68	1012 <a name="IDX634"></a>
jpayne@68	1013 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	1014 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	1015 file will be written relative to the current directory, though.
jpayne@68	1016 </p>
jpayne@68	1017 </dd>
jpayne@68	1018 </dl>
jpayne@68	1019
jpayne@68	1020 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read.
jpayne@68	1021 </p>
jpayne@68	1022
jpayne@68	1023 <a name="SEC112"></a>
jpayne@68	1024 <h3 class="subsection"> <a href="gettext_toc.html#TOC105">9.4.2 Output file location</a> </h3>
jpayne@68	1025
jpayne@68	1026 <dl compact="compact">
jpayne@68	1027 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	1028 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	1029 <dd><a name="IDX635"></a>
jpayne@68	1030 <a name="IDX636"></a>
jpayne@68	1031 <p>Write output to specified file.
jpayne@68	1032 </p>
jpayne@68	1033 </dd>
jpayne@68	1034 </dl>
jpayne@68	1035
jpayne@68	1036 <p>The results are written to standard output if no output file is specified
jpayne@68	1037 or if it is ‘<samp>-</samp>’.
jpayne@68	1038 </p>
jpayne@68	1039
jpayne@68	1040 <a name="SEC113"></a>
jpayne@68	1041 <h3 class="subsection"> <a href="gettext_toc.html#TOC106">9.4.3 The filter</a> </h3>
jpayne@68	1042
jpayne@68	1043 <p>The <var>filter</var> can be any program that reads a translation from standard
jpayne@68	1044 input and writes a modified translation to standard output. A frequently
jpayne@68	1045 used filter is ‘<samp>sed</samp>’. A few particular built-in filters are also
jpayne@68	1046 recognized.
jpayne@68	1047 </p>
jpayne@68	1048 <dl compact="compact">
jpayne@68	1049 <dt> ‘<samp>--newline</samp>’</dt>
jpayne@68	1050 <dd><a name="IDX637"></a>
jpayne@68	1051 <p>Add newline at the end of each input line and also strip the ending
jpayne@68	1052 newline from the output line.
jpayne@68	1053 </p>
jpayne@68	1054 </dd>
jpayne@68	1055 </dl>
jpayne@68	1056
jpayne@68	1057 <a name="IDX638"></a>
jpayne@68	1058 <p>Note: If the filter is not a built-in filter, you have to care about encodings:
jpayne@68	1059 It is your responsibility to ensure that the <var>filter</var> can cope
jpayne@68	1060 with input encoded in the translation catalog's encoding. If the
jpayne@68	1061 <var>filter</var> wants input in a particular encoding, you can in a first step
jpayne@68	1062 convert the translation catalog to that encoding using the ‘<samp>msgconv</samp>’
jpayne@68	1063 program, before invoking ‘<samp>msgfilter</samp>’. If the <var>filter</var> wants input
jpayne@68	1064 in the locale's encoding, but you want to avoid the locale's encoding, then
jpayne@68	1065 you can first convert the translation catalog to UTF-8 using the
jpayne@68	1066 ‘<samp>msgconv</samp>’ program and then make ‘<samp>msgfilter</samp>’ work in an UTF-8
jpayne@68	1067 locale, by using the <code>LC_ALL</code> environment variable.
jpayne@68	1068 </p>
jpayne@68	1069 <a name="IDX639"></a>
jpayne@68	1070 <p>Note: Most translations in a translation catalog don't end with a
jpayne@68	1071 newline character. For this reason, unless the <code>--newline</code>
jpayne@68	1072 option is used, it is important that the <var>filter</var> recognizes its
jpayne@68	1073 last input line even if it ends without a newline, and that it doesn't
jpayne@68	1074 add an undesired trailing newline at the end. The ‘<samp>sed</samp>’ program on
jpayne@68	1075 some platforms is known to ignore the last line of input if it is not
jpayne@68	1076 terminated with a newline. You can use GNU <code>sed</code> instead; it does
jpayne@68	1077 not have this limitation.
jpayne@68	1078 </p>
jpayne@68	1079
jpayne@68	1080 <a name="SEC114"></a>
jpayne@68	1081 <h3 class="subsection"> <a href="gettext_toc.html#TOC107">9.4.4 Useful <var>filter-option</var>s when the <var>filter</var> is ‘<samp>sed</samp>’</a> </h3>
jpayne@68	1082
jpayne@68	1083 <dl compact="compact">
jpayne@68	1084 <dt> ‘<samp>-e <var>script</var></samp>’</dt>
jpayne@68	1085 <dt> ‘<samp>--expression=<var>script</var></samp>’</dt>
jpayne@68	1086 <dd><a name="IDX640"></a>
jpayne@68	1087 <a name="IDX641"></a>
jpayne@68	1088 <p>Add <var>script</var> to the commands to be executed.
jpayne@68	1089 </p>
jpayne@68	1090 </dd>
jpayne@68	1091 <dt> ‘<samp>-f <var>scriptfile</var></samp>’</dt>
jpayne@68	1092 <dt> ‘<samp>--file=<var>scriptfile</var></samp>’</dt>
jpayne@68	1093 <dd><a name="IDX642"></a>
jpayne@68	1094 <a name="IDX643"></a>
jpayne@68	1095 <p>Add the contents of <var>scriptfile</var> to the commands to be executed.
jpayne@68	1096 </p>
jpayne@68	1097 </dd>
jpayne@68	1098 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	1099 <dt> ‘<samp>--quiet</samp>’</dt>
jpayne@68	1100 <dt> ‘<samp>--silent</samp>’</dt>
jpayne@68	1101 <dd><a name="IDX644"></a>
jpayne@68	1102 <a name="IDX645"></a>
jpayne@68	1103 <a name="IDX646"></a>
jpayne@68	1104 <p>Suppress automatic printing of pattern space.
jpayne@68	1105 </p>
jpayne@68	1106 </dd>
jpayne@68	1107 </dl>
jpayne@68	1108
jpayne@68	1109
jpayne@68	1110 <a name="SEC115"></a>
jpayne@68	1111 <h3 class="subsection"> <a href="gettext_toc.html#TOC108">9.4.5 Built-in <var>filter</var>s</a> </h3>
jpayne@68	1112
jpayne@68	1113 <p>The filter ‘<samp>recode-sr-latin</samp>’ is recognized as a built-in filter.
jpayne@68	1114 The command ‘<samp>recode-sr-latin</samp>’ converts Serbian text, written in the
jpayne@68	1115 Cyrillic script, to the Latin script.
jpayne@68	1116 The command ‘<samp>msgfilter recode-sr-latin</samp>’ applies this conversion to the
jpayne@68	1117 translations of a PO file. Thus, it can be used to convert an ‘<tt>sr.po</tt>’
jpayne@68	1118 file to an ‘<tt>sr@latin.po</tt>’ file.
jpayne@68	1119 </p>
jpayne@68	1120 <a name="IDX647"></a>
jpayne@68	1121 <p>The filter ‘<samp>quot</samp>’ is recognized as a built-in filter.
jpayne@68	1122 The command ‘<samp>msgfilter quot</samp>’ converts any quotations surrounded
jpayne@68	1123 by a pair of ‘<samp>"</samp>’, ‘<samp>'</samp>’, and ‘<samp>`</samp>’.
jpayne@68	1124 </p>
jpayne@68	1125 <a name="IDX648"></a>
jpayne@68	1126 <p>The filter ‘<samp>boldquot</samp>’ is recognized as a built-in filter.
jpayne@68	1127 The command ‘<samp>msgfilter boldquot</samp>’ converts any quotations
jpayne@68	1128 surrounded by a pair of ‘<samp>"</samp>’, ‘<samp>'</samp>’, and ‘<samp>`</samp>’, also adding the
jpayne@68	1129 VT100 escape sequences to the text to decorate it as bold.
jpayne@68	1130 </p>
jpayne@68	1131 <p>The use of built-in filters is not sensitive to the current locale's encoding.
jpayne@68	1132 Moreover, when used with a built-in filter, ‘<samp>msgfilter</samp>’ can automatically
jpayne@68	1133 convert the message catalog to the UTF-8 encoding when needed.
jpayne@68	1134 </p>
jpayne@68	1135
jpayne@68	1136 <a name="SEC116"></a>
jpayne@68	1137 <h3 class="subsection"> <a href="gettext_toc.html#TOC109">9.4.6 Input file syntax</a> </h3>
jpayne@68	1138
jpayne@68	1139 <dl compact="compact">
jpayne@68	1140 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	1141 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	1142 <dd><a name="IDX649"></a>
jpayne@68	1143 <a name="IDX650"></a>
jpayne@68	1144 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code>
jpayne@68	1145 syntax, not in PO file syntax.
jpayne@68	1146 </p>
jpayne@68	1147 </dd>
jpayne@68	1148 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	1149 <dd><a name="IDX651"></a>
jpayne@68	1150 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in
jpayne@68	1151 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	1152 </p>
jpayne@68	1153 </dd>
jpayne@68	1154 </dl>
jpayne@68	1155
jpayne@68	1156
jpayne@68	1157 <a name="SEC117"></a>
jpayne@68	1158 <h3 class="subsection"> <a href="gettext_toc.html#TOC110">9.4.7 Output details</a> </h3>
jpayne@68	1159
jpayne@68	1160
jpayne@68	1161 <dl compact="compact">
jpayne@68	1162 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	1163 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	1164 <dd><a name="IDX652"></a>
jpayne@68	1165 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	1166 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	1167 </p>
jpayne@68	1168 </dd>
jpayne@68	1169 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	1170 <dd><a name="IDX653"></a>
jpayne@68	1171 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	1172 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	1173 </p>
jpayne@68	1174 </dd>
jpayne@68	1175 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	1176 <dd><a name="IDX654"></a>
jpayne@68	1177 <p>Always write an output file even if it contains no message.
jpayne@68	1178 </p>
jpayne@68	1179 </dd>
jpayne@68	1180 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	1181 <dd><a name="IDX655"></a>
jpayne@68	1182 <p>Write the .po file using indented style.
jpayne@68	1183 </p>
jpayne@68	1184 </dd>
jpayne@68	1185 <dt> ‘<samp>--keep-header</samp>’</dt>
jpayne@68	1186 <dd><a name="IDX656"></a>
jpayne@68	1187 <p>Keep the header entry, i.e. the message with ‘<samp>msgid ""</samp>’, unmodified,
jpayne@68	1188 instead of filtering it. By default, the header entry is subject to
jpayne@68	1189 filtering like any other message.
jpayne@68	1190 </p>
jpayne@68	1191 </dd>
jpayne@68	1192 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	1193 <dd><a name="IDX657"></a>
jpayne@68	1194 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	1195 </p>
jpayne@68	1196 </dd>
jpayne@68	1197 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	1198 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	1199 <dd><a name="IDX658"></a>
jpayne@68	1200 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	1201 </p>
jpayne@68	1202 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	1203 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	1204 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	1205 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	1206 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	1207 </p>
jpayne@68	1208 </dd>
jpayne@68	1209 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	1210 <dd><a name="IDX659"></a>
jpayne@68	1211 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	1212 Uniforum format should be avoided because it doesn't support the
jpayne@68	1213 GNU extensions.
jpayne@68	1214 </p>
jpayne@68	1215 </dd>
jpayne@68	1216 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	1217 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	1218 <dd><a name="IDX660"></a>
jpayne@68	1219 <a name="IDX661"></a>
jpayne@68	1220 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	1221 that this file format doesn't support plural forms and silently drops
jpayne@68	1222 obsolete messages.
jpayne@68	1223 </p>
jpayne@68	1224 </dd>
jpayne@68	1225 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	1226 <dd><a name="IDX662"></a>
jpayne@68	1227 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	1228 Note that this file format doesn't support plural forms.
jpayne@68	1229 </p>
jpayne@68	1230 </dd>
jpayne@68	1231 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	1232 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	1233 <dd><a name="IDX663"></a>
jpayne@68	1234 <a name="IDX664"></a>
jpayne@68	1235 <p>Set the output page width. Long strings in the output files will be
jpayne@68	1236 split across multiple lines in order to ensure that each line's width
jpayne@68	1237 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	1238 </p>
jpayne@68	1239 </dd>
jpayne@68	1240 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	1241 <dd><a name="IDX665"></a>
jpayne@68	1242 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	1243 output page width will not be split into several lines. Only file reference
jpayne@68	1244 lines which are wider than the output page width will be split.
jpayne@68	1245 </p>
jpayne@68	1246 </dd>
jpayne@68	1247 <dt> ‘<samp>-s</samp>’</dt>
jpayne@68	1248 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	1249 <dd><a name="IDX666"></a>
jpayne@68	1250 <a name="IDX667"></a>
jpayne@68	1251 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	1252 for the translator to understand each message's context.
jpayne@68	1253 </p>
jpayne@68	1254 </dd>
jpayne@68	1255 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	1256 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	1257 <dd><a name="IDX668"></a>
jpayne@68	1258 <a name="IDX669"></a>
jpayne@68	1259 <p>Sort output by file location.
jpayne@68	1260 </p>
jpayne@68	1261 </dd>
jpayne@68	1262 </dl>
jpayne@68	1263
jpayne@68	1264
jpayne@68	1265 <a name="SEC118"></a>
jpayne@68	1266 <h3 class="subsection"> <a href="gettext_toc.html#TOC111">9.4.8 Informative output</a> </h3>
jpayne@68	1267
jpayne@68	1268 <dl compact="compact">
jpayne@68	1269 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	1270 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	1271 <dd><a name="IDX670"></a>
jpayne@68	1272 <a name="IDX671"></a>
jpayne@68	1273 <p>Display this help and exit.
jpayne@68	1274 </p>
jpayne@68	1275 </dd>
jpayne@68	1276 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	1277 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	1278 <dd><a name="IDX672"></a>
jpayne@68	1279 <a name="IDX673"></a>
jpayne@68	1280 <p>Output version information and exit.
jpayne@68	1281 </p>
jpayne@68	1282 </dd>
jpayne@68	1283 </dl>
jpayne@68	1284
jpayne@68	1285
jpayne@68	1286 <a name="SEC119"></a>
jpayne@68	1287 <h3 class="subsection"> <a href="gettext_toc.html#TOC112">9.4.9 Examples</a> </h3>
jpayne@68	1288
jpayne@68	1289 <p>To convert German translations to Swiss orthography (in an UTF-8 locale):
jpayne@68	1290 </p>
jpayne@68	1291 <table><tr><td> </td><td><pre class="smallexample">msgconv -t UTF-8 de.po \| msgfilter sed -e 's/ß/ss/g'
jpayne@68	1292 </pre></td></tr></table>
jpayne@68	1293
jpayne@68	1294 <p>To convert Serbian translations in Cyrillic script to Latin script:
jpayne@68	1295 </p>
jpayne@68	1296 <table><tr><td> </td><td><pre class="smallexample">msgfilter recode-sr-latin < sr.po
jpayne@68	1297 </pre></td></tr></table>
jpayne@68	1298
jpayne@68	1299
jpayne@68	1300 <a name="msguniq-Invocation"></a>
jpayne@68	1301 <a name="SEC120"></a>
jpayne@68	1302 <h2 class="section"> <a href="gettext_toc.html#TOC113">9.5 Invoking the <code>msguniq</code> Program</a> </h2>
jpayne@68	1303
jpayne@68	1304
jpayne@68	1305 <table><tr><td> </td><td><pre class="example">msguniq [<var>option</var>] [<var>inputfile</var>]
jpayne@68	1306 </pre></td></tr></table>
jpayne@68	1307
jpayne@68	1308 <a name="IDX674"></a>
jpayne@68	1309 <a name="IDX675"></a>
jpayne@68	1310 <p>The <code>msguniq</code> program unifies duplicate translations in a translation
jpayne@68	1311 catalog. It finds duplicate translations of the same message ID. Such
jpayne@68	1312 duplicates are invalid input for other programs like <code>msgfmt</code>,
jpayne@68	1313 <code>msgmerge</code> or <code>msgcat</code>. By default, duplicates are merged
jpayne@68	1314 together. When using the ‘<samp>--repeated</samp>’ option, only duplicates are
jpayne@68	1315 output, and all other messages are discarded. Comments and extracted
jpayne@68	1316 comments will be cumulated, except that if ‘<samp>--use-first</samp>’ is
jpayne@68	1317 specified, they will be taken from the first translation. File positions
jpayne@68	1318 will be cumulated. When using the ‘<samp>--unique</samp>’ option, duplicates are
jpayne@68	1319 discarded.
jpayne@68	1320 </p>
jpayne@68	1321
jpayne@68	1322 <a name="SEC121"></a>
jpayne@68	1323 <h3 class="subsection"> <a href="gettext_toc.html#TOC114">9.5.1 Input file location</a> </h3>
jpayne@68	1324
jpayne@68	1325 <dl compact="compact">
jpayne@68	1326 <dt> ‘<samp><var>inputfile</var></samp>’</dt>
jpayne@68	1327 <dd><p>Input PO file.
jpayne@68	1328 </p>
jpayne@68	1329 </dd>
jpayne@68	1330 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	1331 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	1332 <dd><a name="IDX676"></a>
jpayne@68	1333 <a name="IDX677"></a>
jpayne@68	1334 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	1335 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	1336 file will be written relative to the current directory, though.
jpayne@68	1337 </p>
jpayne@68	1338 </dd>
jpayne@68	1339 </dl>
jpayne@68	1340
jpayne@68	1341 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read.
jpayne@68	1342 </p>
jpayne@68	1343
jpayne@68	1344 <a name="SEC122"></a>
jpayne@68	1345 <h3 class="subsection"> <a href="gettext_toc.html#TOC115">9.5.2 Output file location</a> </h3>
jpayne@68	1346
jpayne@68	1347 <dl compact="compact">
jpayne@68	1348 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	1349 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	1350 <dd><a name="IDX678"></a>
jpayne@68	1351 <a name="IDX679"></a>
jpayne@68	1352 <p>Write output to specified file.
jpayne@68	1353 </p>
jpayne@68	1354 </dd>
jpayne@68	1355 </dl>
jpayne@68	1356
jpayne@68	1357 <p>The results are written to standard output if no output file is specified
jpayne@68	1358 or if it is ‘<samp>-</samp>’.
jpayne@68	1359 </p>
jpayne@68	1360
jpayne@68	1361 <a name="SEC123"></a>
jpayne@68	1362 <h3 class="subsection"> <a href="gettext_toc.html#TOC116">9.5.3 Message selection</a> </h3>
jpayne@68	1363
jpayne@68	1364 <dl compact="compact">
jpayne@68	1365 <dt> ‘<samp>-d</samp>’</dt>
jpayne@68	1366 <dt> ‘<samp>--repeated</samp>’</dt>
jpayne@68	1367 <dd><a name="IDX680"></a>
jpayne@68	1368 <a name="IDX681"></a>
jpayne@68	1369 <p>Print only duplicates.
jpayne@68	1370 </p>
jpayne@68	1371 </dd>
jpayne@68	1372 <dt> ‘<samp>-u</samp>’</dt>
jpayne@68	1373 <dt> ‘<samp>--unique</samp>’</dt>
jpayne@68	1374 <dd><a name="IDX682"></a>
jpayne@68	1375 <a name="IDX683"></a>
jpayne@68	1376 <p>Print only unique messages, discard duplicates.
jpayne@68	1377 </p>
jpayne@68	1378 </dd>
jpayne@68	1379 </dl>
jpayne@68	1380
jpayne@68	1381
jpayne@68	1382 <a name="SEC124"></a>
jpayne@68	1383 <h3 class="subsection"> <a href="gettext_toc.html#TOC117">9.5.4 Input file syntax</a> </h3>
jpayne@68	1384
jpayne@68	1385 <dl compact="compact">
jpayne@68	1386 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	1387 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	1388 <dd><a name="IDX684"></a>
jpayne@68	1389 <a name="IDX685"></a>
jpayne@68	1390 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code>
jpayne@68	1391 syntax, not in PO file syntax.
jpayne@68	1392 </p>
jpayne@68	1393 </dd>
jpayne@68	1394 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	1395 <dd><a name="IDX686"></a>
jpayne@68	1396 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in
jpayne@68	1397 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	1398 </p>
jpayne@68	1399 </dd>
jpayne@68	1400 </dl>
jpayne@68	1401
jpayne@68	1402
jpayne@68	1403 <a name="SEC125"></a>
jpayne@68	1404 <h3 class="subsection"> <a href="gettext_toc.html#TOC118">9.5.5 Output details</a> </h3>
jpayne@68	1405
jpayne@68	1406
jpayne@68	1407 <dl compact="compact">
jpayne@68	1408 <dt> ‘<samp>-t</samp>’</dt>
jpayne@68	1409 <dt> ‘<samp>--to-code=<var>name</var></samp>’</dt>
jpayne@68	1410 <dd><a name="IDX687"></a>
jpayne@68	1411 <a name="IDX688"></a>
jpayne@68	1412 <p>Specify encoding for output.
jpayne@68	1413 </p>
jpayne@68	1414 </dd>
jpayne@68	1415 <dt> ‘<samp>--use-first</samp>’</dt>
jpayne@68	1416 <dd><a name="IDX689"></a>
jpayne@68	1417 <p>Use first available translation for each message. Don't merge several
jpayne@68	1418 translations into one.
jpayne@68	1419 </p>
jpayne@68	1420 </dd>
jpayne@68	1421 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	1422 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	1423 <dd><a name="IDX690"></a>
jpayne@68	1424 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	1425 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	1426 </p>
jpayne@68	1427 </dd>
jpayne@68	1428 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	1429 <dd><a name="IDX691"></a>
jpayne@68	1430 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	1431 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	1432 </p>
jpayne@68	1433 </dd>
jpayne@68	1434 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	1435 <dd><a name="IDX692"></a>
jpayne@68	1436 <p>Always write an output file even if it contains no message.
jpayne@68	1437 </p>
jpayne@68	1438 </dd>
jpayne@68	1439 <dt> ‘<samp>-i</samp>’</dt>
jpayne@68	1440 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	1441 <dd><a name="IDX693"></a>
jpayne@68	1442 <a name="IDX694"></a>
jpayne@68	1443 <p>Write the .po file using indented style.
jpayne@68	1444 </p>
jpayne@68	1445 </dd>
jpayne@68	1446 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	1447 <dd><a name="IDX695"></a>
jpayne@68	1448 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	1449 </p>
jpayne@68	1450 </dd>
jpayne@68	1451 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	1452 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	1453 <dd><a name="IDX696"></a>
jpayne@68	1454 <a name="IDX697"></a>
jpayne@68	1455 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	1456 </p>
jpayne@68	1457 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	1458 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	1459 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	1460 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	1461 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	1462 </p>
jpayne@68	1463 </dd>
jpayne@68	1464 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	1465 <dd><a name="IDX698"></a>
jpayne@68	1466 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	1467 Uniforum format should be avoided because it doesn't support the
jpayne@68	1468 GNU extensions.
jpayne@68	1469 </p>
jpayne@68	1470 </dd>
jpayne@68	1471 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	1472 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	1473 <dd><a name="IDX699"></a>
jpayne@68	1474 <a name="IDX700"></a>
jpayne@68	1475 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	1476 that this file format doesn't support plural forms and silently drops
jpayne@68	1477 obsolete messages.
jpayne@68	1478 </p>
jpayne@68	1479 </dd>
jpayne@68	1480 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	1481 <dd><a name="IDX701"></a>
jpayne@68	1482 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	1483 Note that this file format doesn't support plural forms.
jpayne@68	1484 </p>
jpayne@68	1485 </dd>
jpayne@68	1486 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	1487 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	1488 <dd><a name="IDX702"></a>
jpayne@68	1489 <a name="IDX703"></a>
jpayne@68	1490 <p>Set the output page width. Long strings in the output files will be
jpayne@68	1491 split across multiple lines in order to ensure that each line's width
jpayne@68	1492 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	1493 </p>
jpayne@68	1494 </dd>
jpayne@68	1495 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	1496 <dd><a name="IDX704"></a>
jpayne@68	1497 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	1498 output page width will not be split into several lines. Only file reference
jpayne@68	1499 lines which are wider than the output page width will be split.
jpayne@68	1500 </p>
jpayne@68	1501 </dd>
jpayne@68	1502 <dt> ‘<samp>-s</samp>’</dt>
jpayne@68	1503 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	1504 <dd><a name="IDX705"></a>
jpayne@68	1505 <a name="IDX706"></a>
jpayne@68	1506 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	1507 for the translator to understand each message's context.
jpayne@68	1508 </p>
jpayne@68	1509 </dd>
jpayne@68	1510 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	1511 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	1512 <dd><a name="IDX707"></a>
jpayne@68	1513 <a name="IDX708"></a>
jpayne@68	1514 <p>Sort output by file location.
jpayne@68	1515 </p>
jpayne@68	1516 </dd>
jpayne@68	1517 </dl>
jpayne@68	1518
jpayne@68	1519
jpayne@68	1520 <a name="SEC126"></a>
jpayne@68	1521 <h3 class="subsection"> <a href="gettext_toc.html#TOC119">9.5.6 Informative output</a> </h3>
jpayne@68	1522
jpayne@68	1523 <dl compact="compact">
jpayne@68	1524 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	1525 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	1526 <dd><a name="IDX709"></a>
jpayne@68	1527 <a name="IDX710"></a>
jpayne@68	1528 <p>Display this help and exit.
jpayne@68	1529 </p>
jpayne@68	1530 </dd>
jpayne@68	1531 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	1532 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	1533 <dd><a name="IDX711"></a>
jpayne@68	1534 <a name="IDX712"></a>
jpayne@68	1535 <p>Output version information and exit.
jpayne@68	1536 </p>
jpayne@68	1537 </dd>
jpayne@68	1538 </dl>
jpayne@68	1539
jpayne@68	1540
jpayne@68	1541 <a name="msgcomm-Invocation"></a>
jpayne@68	1542 <a name="SEC127"></a>
jpayne@68	1543 <h2 class="section"> <a href="gettext_toc.html#TOC120">9.6 Invoking the <code>msgcomm</code> Program</a> </h2>
jpayne@68	1544
jpayne@68	1545
jpayne@68	1546 <table><tr><td> </td><td><pre class="example">msgcomm [<var>option</var>] [<var>inputfile</var>]...
jpayne@68	1547 </pre></td></tr></table>
jpayne@68	1548
jpayne@68	1549 <a name="IDX713"></a>
jpayne@68	1550 <p>The <code>msgcomm</code> program finds messages which are common to two or more
jpayne@68	1551 of the specified PO files.
jpayne@68	1552 By using the <code>--more-than</code> option, greater commonality may be requested
jpayne@68	1553 before messages are printed. Conversely, the <code>--less-than</code> option may be
jpayne@68	1554 used to specify less commonality before messages are printed (i.e.
jpayne@68	1555 ‘<samp>--less-than=2</samp>’ will only print the unique messages). Translations,
jpayne@68	1556 comments and extracted comments will be preserved, but only from the first
jpayne@68	1557 PO file to define them. File positions from all PO files will be
jpayne@68	1558 cumulated.
jpayne@68	1559 </p>
jpayne@68	1560
jpayne@68	1561 <a name="SEC128"></a>
jpayne@68	1562 <h3 class="subsection"> <a href="gettext_toc.html#TOC121">9.6.1 Input file location</a> </h3>
jpayne@68	1563
jpayne@68	1564 <dl compact="compact">
jpayne@68	1565 <dt> ‘<samp><var>inputfile</var> …</samp>’</dt>
jpayne@68	1566 <dd><p>Input files.
jpayne@68	1567 </p>
jpayne@68	1568 </dd>
jpayne@68	1569 <dt> ‘<samp>-f <var>file</var></samp>’</dt>
jpayne@68	1570 <dt> ‘<samp>--files-from=<var>file</var></samp>’</dt>
jpayne@68	1571 <dd><a name="IDX714"></a>
jpayne@68	1572 <a name="IDX715"></a>
jpayne@68	1573 <p>Read the names of the input files from <var>file</var> instead of getting
jpayne@68	1574 them from the command line.
jpayne@68	1575 </p>
jpayne@68	1576 </dd>
jpayne@68	1577 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	1578 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	1579 <dd><a name="IDX716"></a>
jpayne@68	1580 <a name="IDX717"></a>
jpayne@68	1581 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	1582 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	1583 file will be written relative to the current directory, though.
jpayne@68	1584 </p>
jpayne@68	1585 </dd>
jpayne@68	1586 </dl>
jpayne@68	1587
jpayne@68	1588 <p>If <var>inputfile</var> is ‘<samp>-</samp>’, standard input is read.
jpayne@68	1589 </p>
jpayne@68	1590
jpayne@68	1591 <a name="SEC129"></a>
jpayne@68	1592 <h3 class="subsection"> <a href="gettext_toc.html#TOC122">9.6.2 Output file location</a> </h3>
jpayne@68	1593
jpayne@68	1594 <dl compact="compact">
jpayne@68	1595 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	1596 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	1597 <dd><a name="IDX718"></a>
jpayne@68	1598 <a name="IDX719"></a>
jpayne@68	1599 <p>Write output to specified file.
jpayne@68	1600 </p>
jpayne@68	1601 </dd>
jpayne@68	1602 </dl>
jpayne@68	1603
jpayne@68	1604 <p>The results are written to standard output if no output file is specified
jpayne@68	1605 or if it is ‘<samp>-</samp>’.
jpayne@68	1606 </p>
jpayne@68	1607
jpayne@68	1608 <a name="SEC130"></a>
jpayne@68	1609 <h3 class="subsection"> <a href="gettext_toc.html#TOC123">9.6.3 Message selection</a> </h3>
jpayne@68	1610
jpayne@68	1611 <dl compact="compact">
jpayne@68	1612 <dt> ‘<samp>-< <var>number</var></samp>’</dt>
jpayne@68	1613 <dt> ‘<samp>--less-than=<var>number</var></samp>’</dt>
jpayne@68	1614 <dd><a name="IDX720"></a>
jpayne@68	1615 <a name="IDX721"></a>
jpayne@68	1616 <p>Print messages with less than <var>number</var> definitions, defaults to infinite
jpayne@68	1617 if not set.
jpayne@68	1618 </p>
jpayne@68	1619 </dd>
jpayne@68	1620 <dt> ‘<samp>-> <var>number</var></samp>’</dt>
jpayne@68	1621 <dt> ‘<samp>--more-than=<var>number</var></samp>’</dt>
jpayne@68	1622 <dd><a name="IDX722"></a>
jpayne@68	1623 <a name="IDX723"></a>
jpayne@68	1624 <p>Print messages with more than <var>number</var> definitions, defaults to 1 if not
jpayne@68	1625 set.
jpayne@68	1626 </p>
jpayne@68	1627 </dd>
jpayne@68	1628 <dt> ‘<samp>-u</samp>’</dt>
jpayne@68	1629 <dt> ‘<samp>--unique</samp>’</dt>
jpayne@68	1630 <dd><a name="IDX724"></a>
jpayne@68	1631 <a name="IDX725"></a>
jpayne@68	1632 <p>Shorthand for ‘<samp>--less-than=2</samp>’. Requests that only unique messages be
jpayne@68	1633 printed.
jpayne@68	1634 </p>
jpayne@68	1635 </dd>
jpayne@68	1636 </dl>
jpayne@68	1637
jpayne@68	1638
jpayne@68	1639 <a name="SEC131"></a>
jpayne@68	1640 <h3 class="subsection"> <a href="gettext_toc.html#TOC124">9.6.4 Input file syntax</a> </h3>
jpayne@68	1641
jpayne@68	1642 <dl compact="compact">
jpayne@68	1643 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	1644 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	1645 <dd><a name="IDX726"></a>
jpayne@68	1646 <a name="IDX727"></a>
jpayne@68	1647 <p>Assume the input files are Java ResourceBundles in Java <code>.properties</code>
jpayne@68	1648 syntax, not in PO file syntax.
jpayne@68	1649 </p>
jpayne@68	1650 </dd>
jpayne@68	1651 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	1652 <dd><a name="IDX728"></a>
jpayne@68	1653 <p>Assume the input files are NeXTstep/GNUstep localized resource files in
jpayne@68	1654 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	1655 </p>
jpayne@68	1656 </dd>
jpayne@68	1657 </dl>
jpayne@68	1658
jpayne@68	1659
jpayne@68	1660 <a name="SEC132"></a>
jpayne@68	1661 <h3 class="subsection"> <a href="gettext_toc.html#TOC125">9.6.5 Output details</a> </h3>
jpayne@68	1662
jpayne@68	1663
jpayne@68	1664 <dl compact="compact">
jpayne@68	1665 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	1666 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	1667 <dd><a name="IDX729"></a>
jpayne@68	1668 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	1669 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	1670 </p>
jpayne@68	1671 </dd>
jpayne@68	1672 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	1673 <dd><a name="IDX730"></a>
jpayne@68	1674 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	1675 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	1676 </p>
jpayne@68	1677 </dd>
jpayne@68	1678 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	1679 <dd><a name="IDX731"></a>
jpayne@68	1680 <p>Always write an output file even if it contains no message.
jpayne@68	1681 </p>
jpayne@68	1682 </dd>
jpayne@68	1683 <dt> ‘<samp>-i</samp>’</dt>
jpayne@68	1684 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	1685 <dd><a name="IDX732"></a>
jpayne@68	1686 <a name="IDX733"></a>
jpayne@68	1687 <p>Write the .po file using indented style.
jpayne@68	1688 </p>
jpayne@68	1689 </dd>
jpayne@68	1690 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	1691 <dd><a name="IDX734"></a>
jpayne@68	1692 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	1693 </p>
jpayne@68	1694 </dd>
jpayne@68	1695 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	1696 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	1697 <dd><a name="IDX735"></a>
jpayne@68	1698 <a name="IDX736"></a>
jpayne@68	1699 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	1700 </p>
jpayne@68	1701 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	1702 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	1703 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	1704 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	1705 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	1706 </p>
jpayne@68	1707 </dd>
jpayne@68	1708 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	1709 <dd><a name="IDX737"></a>
jpayne@68	1710 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	1711 Uniforum format should be avoided because it doesn't support the
jpayne@68	1712 GNU extensions.
jpayne@68	1713 </p>
jpayne@68	1714 </dd>
jpayne@68	1715 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	1716 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	1717 <dd><a name="IDX738"></a>
jpayne@68	1718 <a name="IDX739"></a>
jpayne@68	1719 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	1720 that this file format doesn't support plural forms and silently drops
jpayne@68	1721 obsolete messages.
jpayne@68	1722 </p>
jpayne@68	1723 </dd>
jpayne@68	1724 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	1725 <dd><a name="IDX740"></a>
jpayne@68	1726 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	1727 Note that this file format doesn't support plural forms.
jpayne@68	1728 </p>
jpayne@68	1729 </dd>
jpayne@68	1730 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	1731 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	1732 <dd><a name="IDX741"></a>
jpayne@68	1733 <a name="IDX742"></a>
jpayne@68	1734 <p>Set the output page width. Long strings in the output files will be
jpayne@68	1735 split across multiple lines in order to ensure that each line's width
jpayne@68	1736 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	1737 </p>
jpayne@68	1738 </dd>
jpayne@68	1739 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	1740 <dd><a name="IDX743"></a>
jpayne@68	1741 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	1742 output page width will not be split into several lines. Only file reference
jpayne@68	1743 lines which are wider than the output page width will be split.
jpayne@68	1744 </p>
jpayne@68	1745 </dd>
jpayne@68	1746 <dt> ‘<samp>-s</samp>’</dt>
jpayne@68	1747 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	1748 <dd><a name="IDX744"></a>
jpayne@68	1749 <a name="IDX745"></a>
jpayne@68	1750 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	1751 for the translator to understand each message's context.
jpayne@68	1752 </p>
jpayne@68	1753 </dd>
jpayne@68	1754 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	1755 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	1756 <dd><a name="IDX746"></a>
jpayne@68	1757 <a name="IDX747"></a>
jpayne@68	1758 <p>Sort output by file location.
jpayne@68	1759 </p>
jpayne@68	1760 </dd>
jpayne@68	1761 <dt> ‘<samp>--omit-header</samp>’</dt>
jpayne@68	1762 <dd><a name="IDX748"></a>
jpayne@68	1763 <p>Don't write header with ‘<samp>msgid ""</samp>’ entry.
jpayne@68	1764 </p>
jpayne@68	1765 </dd>
jpayne@68	1766 </dl>
jpayne@68	1767
jpayne@68	1768
jpayne@68	1769 <a name="SEC133"></a>
jpayne@68	1770 <h3 class="subsection"> <a href="gettext_toc.html#TOC126">9.6.6 Informative output</a> </h3>
jpayne@68	1771
jpayne@68	1772 <dl compact="compact">
jpayne@68	1773 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	1774 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	1775 <dd><a name="IDX749"></a>
jpayne@68	1776 <a name="IDX750"></a>
jpayne@68	1777 <p>Display this help and exit.
jpayne@68	1778 </p>
jpayne@68	1779 </dd>
jpayne@68	1780 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	1781 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	1782 <dd><a name="IDX751"></a>
jpayne@68	1783 <a name="IDX752"></a>
jpayne@68	1784 <p>Output version information and exit.
jpayne@68	1785 </p>
jpayne@68	1786 </dd>
jpayne@68	1787 </dl>
jpayne@68	1788
jpayne@68	1789
jpayne@68	1790 <a name="msgcmp-Invocation"></a>
jpayne@68	1791 <a name="SEC134"></a>
jpayne@68	1792 <h2 class="section"> <a href="gettext_toc.html#TOC127">9.7 Invoking the <code>msgcmp</code> Program</a> </h2>
jpayne@68	1793
jpayne@68	1794
jpayne@68	1795 <table><tr><td> </td><td><pre class="example">msgcmp [<var>option</var>] <var>def</var>.po <var>ref</var>.pot
jpayne@68	1796 </pre></td></tr></table>
jpayne@68	1797
jpayne@68	1798 <a name="IDX753"></a>
jpayne@68	1799 <p>The <code>msgcmp</code> program compares two Uniforum style .po files to check that
jpayne@68	1800 both contain the same set of msgid strings. The <var>def</var>.po file is an
jpayne@68	1801 existing PO file with the translations. The <var>ref</var>.pot file is the last
jpayne@68	1802 created PO file, or a PO Template file (generally created by <code>xgettext</code>).
jpayne@68	1803 This is useful for checking that you have translated each and every message
jpayne@68	1804 in your program. Where an exact match cannot be found, fuzzy matching is
jpayne@68	1805 used to produce better diagnostics.
jpayne@68	1806 </p>
jpayne@68	1807
jpayne@68	1808 <a name="SEC135"></a>
jpayne@68	1809 <h3 class="subsection"> <a href="gettext_toc.html#TOC128">9.7.1 Input file location</a> </h3>
jpayne@68	1810
jpayne@68	1811 <dl compact="compact">
jpayne@68	1812 <dt> ‘<samp><var>def</var>.po</samp>’</dt>
jpayne@68	1813 <dd><p>Translations.
jpayne@68	1814 </p>
jpayne@68	1815 </dd>
jpayne@68	1816 <dt> ‘<samp><var>ref</var>.pot</samp>’</dt>
jpayne@68	1817 <dd><p>References to the sources.
jpayne@68	1818 </p>
jpayne@68	1819 </dd>
jpayne@68	1820 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	1821 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	1822 <dd><a name="IDX754"></a>
jpayne@68	1823 <a name="IDX755"></a>
jpayne@68	1824 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	1825 searched relative to this list of directories.
jpayne@68	1826 </p>
jpayne@68	1827 </dd>
jpayne@68	1828 </dl>
jpayne@68	1829
jpayne@68	1830
jpayne@68	1831 <a name="SEC136"></a>
jpayne@68	1832 <h3 class="subsection"> <a href="gettext_toc.html#TOC129">9.7.2 Operation modifiers</a> </h3>
jpayne@68	1833
jpayne@68	1834 <dl compact="compact">
jpayne@68	1835 <dt> ‘<samp>-m</samp>’</dt>
jpayne@68	1836 <dt> ‘<samp>--multi-domain</samp>’</dt>
jpayne@68	1837 <dd><a name="IDX756"></a>
jpayne@68	1838 <a name="IDX757"></a>
jpayne@68	1839 <p>Apply <var>ref</var>.pot to each of the domains in <var>def</var>.po.
jpayne@68	1840 </p>
jpayne@68	1841 </dd>
jpayne@68	1842 <dt> ‘<samp>-N</samp>’</dt>
jpayne@68	1843 <dt> ‘<samp>--no-fuzzy-matching</samp>’</dt>
jpayne@68	1844 <dd><a name="IDX758"></a>
jpayne@68	1845 <a name="IDX759"></a>
jpayne@68	1846 <p>Do not use fuzzy matching when an exact match is not found. This may speed
jpayne@68	1847 up the operation considerably.
jpayne@68	1848 </p>
jpayne@68	1849 </dd>
jpayne@68	1850 <dt> ‘<samp>--use-fuzzy</samp>’</dt>
jpayne@68	1851 <dd><a name="IDX760"></a>
jpayne@68	1852 <p>Consider fuzzy messages in the <var>def</var>.po file like translated messages.
jpayne@68	1853 Note that using this option is usually wrong, because fuzzy messages are
jpayne@68	1854 exactly those which have not been validated by a human translator.
jpayne@68	1855 </p>
jpayne@68	1856 </dd>
jpayne@68	1857 <dt> ‘<samp>--use-untranslated</samp>’</dt>
jpayne@68	1858 <dd><a name="IDX761"></a>
jpayne@68	1859 <p>Consider untranslated messages in the <var>def</var>.po file like translated
jpayne@68	1860 messages. Note that using this option is usually wrong.
jpayne@68	1861 </p>
jpayne@68	1862 </dd>
jpayne@68	1863 </dl>
jpayne@68	1864
jpayne@68	1865
jpayne@68	1866 <a name="SEC137"></a>
jpayne@68	1867 <h3 class="subsection"> <a href="gettext_toc.html#TOC130">9.7.3 Input file syntax</a> </h3>
jpayne@68	1868
jpayne@68	1869 <dl compact="compact">
jpayne@68	1870 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	1871 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	1872 <dd><a name="IDX762"></a>
jpayne@68	1873 <a name="IDX763"></a>
jpayne@68	1874 <p>Assume the input files are Java ResourceBundles in Java <code>.properties</code>
jpayne@68	1875 syntax, not in PO file syntax.
jpayne@68	1876 </p>
jpayne@68	1877 </dd>
jpayne@68	1878 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	1879 <dd><a name="IDX764"></a>
jpayne@68	1880 <p>Assume the input files are NeXTstep/GNUstep localized resource files in
jpayne@68	1881 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	1882 </p>
jpayne@68	1883 </dd>
jpayne@68	1884 </dl>
jpayne@68	1885
jpayne@68	1886
jpayne@68	1887 <a name="SEC138"></a>
jpayne@68	1888 <h3 class="subsection"> <a href="gettext_toc.html#TOC131">9.7.4 Informative output</a> </h3>
jpayne@68	1889
jpayne@68	1890 <dl compact="compact">
jpayne@68	1891 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	1892 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	1893 <dd><a name="IDX765"></a>
jpayne@68	1894 <a name="IDX766"></a>
jpayne@68	1895 <p>Display this help and exit.
jpayne@68	1896 </p>
jpayne@68	1897 </dd>
jpayne@68	1898 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	1899 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	1900 <dd><a name="IDX767"></a>
jpayne@68	1901 <a name="IDX768"></a>
jpayne@68	1902 <p>Output version information and exit.
jpayne@68	1903 </p>
jpayne@68	1904 </dd>
jpayne@68	1905 </dl>
jpayne@68	1906
jpayne@68	1907
jpayne@68	1908 <a name="msgattrib-Invocation"></a>
jpayne@68	1909 <a name="SEC139"></a>
jpayne@68	1910 <h2 class="section"> <a href="gettext_toc.html#TOC132">9.8 Invoking the <code>msgattrib</code> Program</a> </h2>
jpayne@68	1911
jpayne@68	1912
jpayne@68	1913 <table><tr><td> </td><td><pre class="example">msgattrib [<var>option</var>] [<var>inputfile</var>]
jpayne@68	1914 </pre></td></tr></table>
jpayne@68	1915
jpayne@68	1916 <a name="IDX769"></a>
jpayne@68	1917 <a name="IDX770"></a>
jpayne@68	1918 <p>The <code>msgattrib</code> program filters the messages of a translation catalog
jpayne@68	1919 according to their attributes, and manipulates the attributes.
jpayne@68	1920 </p>
jpayne@68	1921
jpayne@68	1922 <a name="SEC140"></a>
jpayne@68	1923 <h3 class="subsection"> <a href="gettext_toc.html#TOC133">9.8.1 Input file location</a> </h3>
jpayne@68	1924
jpayne@68	1925 <dl compact="compact">
jpayne@68	1926 <dt> ‘<samp><var>inputfile</var></samp>’</dt>
jpayne@68	1927 <dd><p>Input PO file.
jpayne@68	1928 </p>
jpayne@68	1929 </dd>
jpayne@68	1930 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	1931 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	1932 <dd><a name="IDX771"></a>
jpayne@68	1933 <a name="IDX772"></a>
jpayne@68	1934 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	1935 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	1936 file will be written relative to the current directory, though.
jpayne@68	1937 </p>
jpayne@68	1938 </dd>
jpayne@68	1939 </dl>
jpayne@68	1940
jpayne@68	1941 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read.
jpayne@68	1942 </p>
jpayne@68	1943
jpayne@68	1944 <a name="SEC141"></a>
jpayne@68	1945 <h3 class="subsection"> <a href="gettext_toc.html#TOC134">9.8.2 Output file location</a> </h3>
jpayne@68	1946
jpayne@68	1947 <dl compact="compact">
jpayne@68	1948 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	1949 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	1950 <dd><a name="IDX773"></a>
jpayne@68	1951 <a name="IDX774"></a>
jpayne@68	1952 <p>Write output to specified file.
jpayne@68	1953 </p>
jpayne@68	1954 </dd>
jpayne@68	1955 </dl>
jpayne@68	1956
jpayne@68	1957 <p>The results are written to standard output if no output file is specified
jpayne@68	1958 or if it is ‘<samp>-</samp>’.
jpayne@68	1959 </p>
jpayne@68	1960
jpayne@68	1961 <a name="SEC142"></a>
jpayne@68	1962 <h3 class="subsection"> <a href="gettext_toc.html#TOC135">9.8.3 Message selection</a> </h3>
jpayne@68	1963
jpayne@68	1964 <dl compact="compact">
jpayne@68	1965 <dt> ‘<samp>--translated</samp>’</dt>
jpayne@68	1966 <dd><a name="IDX775"></a>
jpayne@68	1967 <p>Keep translated messages, remove untranslated messages.
jpayne@68	1968 </p>
jpayne@68	1969 </dd>
jpayne@68	1970 <dt> ‘<samp>--untranslated</samp>’</dt>
jpayne@68	1971 <dd><a name="IDX776"></a>
jpayne@68	1972 <p>Keep untranslated messages, remove translated messages.
jpayne@68	1973 </p>
jpayne@68	1974 </dd>
jpayne@68	1975 <dt> ‘<samp>--no-fuzzy</samp>’</dt>
jpayne@68	1976 <dd><a name="IDX777"></a>
jpayne@68	1977 <p>Remove
jpayne@68	1978 ‘fuzzy’
jpayne@68	1979 marked messages.
jpayne@68	1980 </p>
jpayne@68	1981 </dd>
jpayne@68	1982 <dt> ‘<samp>--only-fuzzy</samp>’</dt>
jpayne@68	1983 <dd><a name="IDX778"></a>
jpayne@68	1984 <p>Keep
jpayne@68	1985 ‘fuzzy’
jpayne@68	1986 marked messages, remove all other messages.
jpayne@68	1987 </p>
jpayne@68	1988 </dd>
jpayne@68	1989 <dt> ‘<samp>--no-obsolete</samp>’</dt>
jpayne@68	1990 <dd><a name="IDX779"></a>
jpayne@68	1991 <p>Remove obsolete #~ messages.
jpayne@68	1992 </p>
jpayne@68	1993 </dd>
jpayne@68	1994 <dt> ‘<samp>--only-obsolete</samp>’</dt>
jpayne@68	1995 <dd><a name="IDX780"></a>
jpayne@68	1996 <p>Keep obsolete #~ messages, remove all other messages.
jpayne@68	1997 </p>
jpayne@68	1998 </dd>
jpayne@68	1999 </dl>
jpayne@68	2000
jpayne@68	2001
jpayne@68	2002 <a name="SEC143"></a>
jpayne@68	2003 <h3 class="subsection"> <a href="gettext_toc.html#TOC136">9.8.4 Attribute manipulation</a> </h3>
jpayne@68	2004
jpayne@68	2005 <p>Attributes are modified after the message selection/removal has been
jpayne@68	2006 performed. If the ‘<samp>--only-file</samp>’ or ‘<samp>--ignore-file</samp>’ option is
jpayne@68	2007 specified, the attribute modification is applied only to those messages
jpayne@68	2008 that are listed in the <var>only-file</var> and not listed in the
jpayne@68	2009 <var>ignore-file</var>.
jpayne@68	2010 </p>
jpayne@68	2011 <dl compact="compact">
jpayne@68	2012 <dt> ‘<samp>--set-fuzzy</samp>’</dt>
jpayne@68	2013 <dd><a name="IDX781"></a>
jpayne@68	2014 <p>Set all messages
jpayne@68	2015 ‘fuzzy’.
jpayne@68	2016 </p>
jpayne@68	2017 </dd>
jpayne@68	2018 <dt> ‘<samp>--clear-fuzzy</samp>’</dt>
jpayne@68	2019 <dd><a name="IDX782"></a>
jpayne@68	2020 <p>Set all messages
jpayne@68	2021 non-‘fuzzy’.
jpayne@68	2022 </p>
jpayne@68	2023 </dd>
jpayne@68	2024 <dt> ‘<samp>--set-obsolete</samp>’</dt>
jpayne@68	2025 <dd><a name="IDX783"></a>
jpayne@68	2026 <p>Set all messages obsolete.
jpayne@68	2027 </p>
jpayne@68	2028 </dd>
jpayne@68	2029 <dt> ‘<samp>--clear-obsolete</samp>’</dt>
jpayne@68	2030 <dd><a name="IDX784"></a>
jpayne@68	2031 <p>Set all messages non-obsolete.
jpayne@68	2032 </p>
jpayne@68	2033 </dd>
jpayne@68	2034 <dt> ‘<samp>--previous</samp>’</dt>
jpayne@68	2035 <dd><a name="IDX785"></a>
jpayne@68	2036 <p>When setting
jpayne@68	2037 ‘fuzzy’
jpayne@68	2038 mark, keep “previous msgid” of translated messages.
jpayne@68	2039 </p>
jpayne@68	2040 </dd>
jpayne@68	2041 <dt> ‘<samp>--clear-previous</samp>’</dt>
jpayne@68	2042 <dd><a name="IDX786"></a>
jpayne@68	2043 <p>Remove the “previous msgid” (‘<samp>#\|</samp>’) comments from all messages.
jpayne@68	2044 </p>
jpayne@68	2045 </dd>
jpayne@68	2046 <dt> ‘<samp>--empty</samp>’</dt>
jpayne@68	2047 <dd><a name="IDX787"></a>
jpayne@68	2048 <p>When removing
jpayne@68	2049 ‘fuzzy’
jpayne@68	2050 mark, also set msgstr empty.
jpayne@68	2051 </p>
jpayne@68	2052 </dd>
jpayne@68	2053 <dt> ‘<samp>--only-file=<var>file</var></samp>’</dt>
jpayne@68	2054 <dd><a name="IDX788"></a>
jpayne@68	2055 <p>Limit the attribute changes to entries that are listed in <var>file</var>.
jpayne@68	2056 <var>file</var> should be a PO or POT file.
jpayne@68	2057 </p>
jpayne@68	2058 </dd>
jpayne@68	2059 <dt> ‘<samp>--ignore-file=<var>file</var></samp>’</dt>
jpayne@68	2060 <dd><a name="IDX789"></a>
jpayne@68	2061 <p>Limit the attribute changes to entries that are not listed in <var>file</var>.
jpayne@68	2062 <var>file</var> should be a PO or POT file.
jpayne@68	2063 </p>
jpayne@68	2064 </dd>
jpayne@68	2065 <dt> ‘<samp>--fuzzy</samp>’</dt>
jpayne@68	2066 <dd><a name="IDX790"></a>
jpayne@68	2067 <p>Synonym for ‘<samp>--only-fuzzy --clear-fuzzy</samp>’: It keeps only the fuzzy
jpayne@68	2068 messages and removes their
jpayne@68	2069 ‘fuzzy’
jpayne@68	2070 mark.
jpayne@68	2071 </p>
jpayne@68	2072 </dd>
jpayne@68	2073 <dt> ‘<samp>--obsolete</samp>’</dt>
jpayne@68	2074 <dd><a name="IDX791"></a>
jpayne@68	2075 <p>Synonym for ‘<samp>--only-obsolete --clear-obsolete</samp>’: It keeps only the
jpayne@68	2076 obsolete messages and makes them non-obsolete.
jpayne@68	2077 </p>
jpayne@68	2078 </dd>
jpayne@68	2079 </dl>
jpayne@68	2080
jpayne@68	2081
jpayne@68	2082 <a name="SEC144"></a>
jpayne@68	2083 <h3 class="subsection"> <a href="gettext_toc.html#TOC137">9.8.5 Input file syntax</a> </h3>
jpayne@68	2084
jpayne@68	2085 <dl compact="compact">
jpayne@68	2086 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	2087 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	2088 <dd><a name="IDX792"></a>
jpayne@68	2089 <a name="IDX793"></a>
jpayne@68	2090 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code>
jpayne@68	2091 syntax, not in PO file syntax.
jpayne@68	2092 </p>
jpayne@68	2093 </dd>
jpayne@68	2094 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	2095 <dd><a name="IDX794"></a>
jpayne@68	2096 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in
jpayne@68	2097 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	2098 </p>
jpayne@68	2099 </dd>
jpayne@68	2100 </dl>
jpayne@68	2101
jpayne@68	2102
jpayne@68	2103 <a name="SEC145"></a>
jpayne@68	2104 <h3 class="subsection"> <a href="gettext_toc.html#TOC138">9.8.6 Output details</a> </h3>
jpayne@68	2105
jpayne@68	2106
jpayne@68	2107 <dl compact="compact">
jpayne@68	2108 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	2109 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	2110 <dd><a name="IDX795"></a>
jpayne@68	2111 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	2112 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	2113 </p>
jpayne@68	2114 </dd>
jpayne@68	2115 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	2116 <dd><a name="IDX796"></a>
jpayne@68	2117 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	2118 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	2119 </p>
jpayne@68	2120 </dd>
jpayne@68	2121 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	2122 <dd><a name="IDX797"></a>
jpayne@68	2123 <p>Always write an output file even if it contains no message.
jpayne@68	2124 </p>
jpayne@68	2125 </dd>
jpayne@68	2126 <dt> ‘<samp>-i</samp>’</dt>
jpayne@68	2127 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	2128 <dd><a name="IDX798"></a>
jpayne@68	2129 <a name="IDX799"></a>
jpayne@68	2130 <p>Write the .po file using indented style.
jpayne@68	2131 </p>
jpayne@68	2132 </dd>
jpayne@68	2133 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	2134 <dd><a name="IDX800"></a>
jpayne@68	2135 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	2136 </p>
jpayne@68	2137 </dd>
jpayne@68	2138 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	2139 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	2140 <dd><a name="IDX801"></a>
jpayne@68	2141 <a name="IDX802"></a>
jpayne@68	2142 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	2143 </p>
jpayne@68	2144 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	2145 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	2146 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	2147 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	2148 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	2149 </p>
jpayne@68	2150 </dd>
jpayne@68	2151 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	2152 <dd><a name="IDX803"></a>
jpayne@68	2153 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	2154 Uniforum format should be avoided because it doesn't support the
jpayne@68	2155 GNU extensions.
jpayne@68	2156 </p>
jpayne@68	2157 </dd>
jpayne@68	2158 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	2159 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	2160 <dd><a name="IDX804"></a>
jpayne@68	2161 <a name="IDX805"></a>
jpayne@68	2162 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	2163 that this file format doesn't support plural forms and silently drops
jpayne@68	2164 obsolete messages.
jpayne@68	2165 </p>
jpayne@68	2166 </dd>
jpayne@68	2167 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	2168 <dd><a name="IDX806"></a>
jpayne@68	2169 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	2170 Note that this file format doesn't support plural forms.
jpayne@68	2171 </p>
jpayne@68	2172 </dd>
jpayne@68	2173 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	2174 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	2175 <dd><a name="IDX807"></a>
jpayne@68	2176 <a name="IDX808"></a>
jpayne@68	2177 <p>Set the output page width. Long strings in the output files will be
jpayne@68	2178 split across multiple lines in order to ensure that each line's width
jpayne@68	2179 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	2180 </p>
jpayne@68	2181 </dd>
jpayne@68	2182 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	2183 <dd><a name="IDX809"></a>
jpayne@68	2184 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	2185 output page width will not be split into several lines. Only file reference
jpayne@68	2186 lines which are wider than the output page width will be split.
jpayne@68	2187 </p>
jpayne@68	2188 </dd>
jpayne@68	2189 <dt> ‘<samp>-s</samp>’</dt>
jpayne@68	2190 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	2191 <dd><a name="IDX810"></a>
jpayne@68	2192 <a name="IDX811"></a>
jpayne@68	2193 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	2194 for the translator to understand each message's context.
jpayne@68	2195 </p>
jpayne@68	2196 </dd>
jpayne@68	2197 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	2198 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	2199 <dd><a name="IDX812"></a>
jpayne@68	2200 <a name="IDX813"></a>
jpayne@68	2201 <p>Sort output by file location.
jpayne@68	2202 </p>
jpayne@68	2203 </dd>
jpayne@68	2204 </dl>
jpayne@68	2205
jpayne@68	2206
jpayne@68	2207 <a name="SEC146"></a>
jpayne@68	2208 <h3 class="subsection"> <a href="gettext_toc.html#TOC139">9.8.7 Informative output</a> </h3>
jpayne@68	2209
jpayne@68	2210 <dl compact="compact">
jpayne@68	2211 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	2212 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	2213 <dd><a name="IDX814"></a>
jpayne@68	2214 <a name="IDX815"></a>
jpayne@68	2215 <p>Display this help and exit.
jpayne@68	2216 </p>
jpayne@68	2217 </dd>
jpayne@68	2218 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	2219 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	2220 <dd><a name="IDX816"></a>
jpayne@68	2221 <a name="IDX817"></a>
jpayne@68	2222 <p>Output version information and exit.
jpayne@68	2223 </p>
jpayne@68	2224 </dd>
jpayne@68	2225 </dl>
jpayne@68	2226
jpayne@68	2227
jpayne@68	2228 <a name="msgen-Invocation"></a>
jpayne@68	2229 <a name="SEC147"></a>
jpayne@68	2230 <h2 class="section"> <a href="gettext_toc.html#TOC140">9.9 Invoking the <code>msgen</code> Program</a> </h2>
jpayne@68	2231
jpayne@68	2232
jpayne@68	2233 <table><tr><td> </td><td><pre class="example">msgen [<var>option</var>] <var>inputfile</var>
jpayne@68	2234 </pre></td></tr></table>
jpayne@68	2235
jpayne@68	2236 <a name="IDX818"></a>
jpayne@68	2237 <p>The <code>msgen</code> program creates an English translation catalog. The
jpayne@68	2238 input file is the last created English PO file, or a PO Template file
jpayne@68	2239 (generally created by xgettext). Untranslated entries are assigned a
jpayne@68	2240 translation that is identical to the msgid.
jpayne@68	2241 </p>
jpayne@68	2242 <p>Note: ‘<samp>msginit --no-translator --locale=en</samp>’ performs a very similar
jpayne@68	2243 task. The main difference is that <code>msginit</code> cares specially about
jpayne@68	2244 the header entry, whereas <code>msgen</code> doesn't.
jpayne@68	2245 </p>
jpayne@68	2246
jpayne@68	2247 <a name="SEC148"></a>
jpayne@68	2248 <h3 class="subsection"> <a href="gettext_toc.html#TOC141">9.9.1 Input file location</a> </h3>
jpayne@68	2249
jpayne@68	2250 <dl compact="compact">
jpayne@68	2251 <dt> ‘<samp><var>inputfile</var></samp>’</dt>
jpayne@68	2252 <dd><p>Input PO or POT file.
jpayne@68	2253 </p>
jpayne@68	2254 </dd>
jpayne@68	2255 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	2256 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	2257 <dd><a name="IDX819"></a>
jpayne@68	2258 <a name="IDX820"></a>
jpayne@68	2259 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	2260 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	2261 file will be written relative to the current directory, though.
jpayne@68	2262 </p>
jpayne@68	2263 </dd>
jpayne@68	2264 </dl>
jpayne@68	2265
jpayne@68	2266 <p>If <var>inputfile</var> is ‘<samp>-</samp>’, standard input is read.
jpayne@68	2267 </p>
jpayne@68	2268
jpayne@68	2269 <a name="SEC149"></a>
jpayne@68	2270 <h3 class="subsection"> <a href="gettext_toc.html#TOC142">9.9.2 Output file location</a> </h3>
jpayne@68	2271
jpayne@68	2272 <dl compact="compact">
jpayne@68	2273 <dt> ‘<samp>-o <var>file</var></samp>’</dt>
jpayne@68	2274 <dt> ‘<samp>--output-file=<var>file</var></samp>’</dt>
jpayne@68	2275 <dd><a name="IDX821"></a>
jpayne@68	2276 <a name="IDX822"></a>
jpayne@68	2277 <p>Write output to specified file.
jpayne@68	2278 </p>
jpayne@68	2279 </dd>
jpayne@68	2280 </dl>
jpayne@68	2281
jpayne@68	2282 <p>The results are written to standard output if no output file is specified
jpayne@68	2283 or if it is ‘<samp>-</samp>’.
jpayne@68	2284 </p>
jpayne@68	2285
jpayne@68	2286 <a name="SEC150"></a>
jpayne@68	2287 <h3 class="subsection"> <a href="gettext_toc.html#TOC143">9.9.3 Input file syntax</a> </h3>
jpayne@68	2288
jpayne@68	2289 <dl compact="compact">
jpayne@68	2290 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	2291 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	2292 <dd><a name="IDX823"></a>
jpayne@68	2293 <a name="IDX824"></a>
jpayne@68	2294 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code>
jpayne@68	2295 syntax, not in PO file syntax.
jpayne@68	2296 </p>
jpayne@68	2297 </dd>
jpayne@68	2298 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	2299 <dd><a name="IDX825"></a>
jpayne@68	2300 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in
jpayne@68	2301 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	2302 </p>
jpayne@68	2303 </dd>
jpayne@68	2304 </dl>
jpayne@68	2305
jpayne@68	2306
jpayne@68	2307 <a name="SEC151"></a>
jpayne@68	2308 <h3 class="subsection"> <a href="gettext_toc.html#TOC144">9.9.4 Output details</a> </h3>
jpayne@68	2309
jpayne@68	2310
jpayne@68	2311 <dl compact="compact">
jpayne@68	2312 <dt> ‘<samp>--lang=<var>catalogname</var></samp>’</dt>
jpayne@68	2313 <dd><a name="IDX826"></a>
jpayne@68	2314 <p>Specify the ‘<samp>Language</samp>’ field to be used in the header entry. See
jpayne@68	2315 <a href="gettext_6.html#SEC52">Filling in the Header Entry</a> for the meaning of this field. Note: The
jpayne@68	2316 ‘<samp>Language-Team</samp>’ and ‘<samp>Plural-Forms</samp>’ fields are not set by this
jpayne@68	2317 option.
jpayne@68	2318 </p>
jpayne@68	2319 </dd>
jpayne@68	2320 <dt> ‘<samp>--color</samp>’</dt>
jpayne@68	2321 <dt> ‘<samp>--color=<var>when</var></samp>’</dt>
jpayne@68	2322 <dd><a name="IDX827"></a>
jpayne@68	2323 <p>Specify whether or when to use colors and other text attributes.
jpayne@68	2324 See <a href="#SEC158">The <code>--color</code> option</a> for details.
jpayne@68	2325 </p>
jpayne@68	2326 </dd>
jpayne@68	2327 <dt> ‘<samp>--style=<var>style_file</var></samp>’</dt>
jpayne@68	2328 <dd><a name="IDX828"></a>
jpayne@68	2329 <p>Specify the CSS style rule file to use for <code>--color</code>.
jpayne@68	2330 See <a href="#SEC160">The <code>--style</code> option</a> for details.
jpayne@68	2331 </p>
jpayne@68	2332 </dd>
jpayne@68	2333 <dt> ‘<samp>--force-po</samp>’</dt>
jpayne@68	2334 <dd><a name="IDX829"></a>
jpayne@68	2335 <p>Always write an output file even if it contains no message.
jpayne@68	2336 </p>
jpayne@68	2337 </dd>
jpayne@68	2338 <dt> ‘<samp>-i</samp>’</dt>
jpayne@68	2339 <dt> ‘<samp>--indent</samp>’</dt>
jpayne@68	2340 <dd><a name="IDX830"></a>
jpayne@68	2341 <a name="IDX831"></a>
jpayne@68	2342 <p>Write the .po file using indented style.
jpayne@68	2343 </p>
jpayne@68	2344 </dd>
jpayne@68	2345 <dt> ‘<samp>--no-location</samp>’</dt>
jpayne@68	2346 <dd><a name="IDX832"></a>
jpayne@68	2347 <p>Do not write ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines.
jpayne@68	2348 </p>
jpayne@68	2349 </dd>
jpayne@68	2350 <dt> ‘<samp>-n</samp>’</dt>
jpayne@68	2351 <dt> ‘<samp>--add-location=<var>type</var></samp>’</dt>
jpayne@68	2352 <dd><a name="IDX833"></a>
jpayne@68	2353 <p>Generate ‘<samp>#: <var>filename</var>:<var>line</var></samp>’ lines (default).
jpayne@68	2354 </p>
jpayne@68	2355 <p>The optional <var>type</var> can be either ‘<samp>full</samp>’, ‘<samp>file</samp>’, or
jpayne@68	2356 ‘<samp>never</samp>’. If it is not given or ‘<samp>full</samp>’, it generates the
jpayne@68	2357 lines with both file name and line number. If it is ‘<samp>file</samp>’, the
jpayne@68	2358 line number part is omitted. If it is ‘<samp>never</samp>’, it completely
jpayne@68	2359 suppresses the lines (same as <code>--no-location</code>).
jpayne@68	2360 </p>
jpayne@68	2361 </dd>
jpayne@68	2362 <dt> ‘<samp>--strict</samp>’</dt>
jpayne@68	2363 <dd><a name="IDX834"></a>
jpayne@68	2364 <p>Write out a strict Uniforum conforming PO file. Note that this
jpayne@68	2365 Uniforum format should be avoided because it doesn't support the
jpayne@68	2366 GNU extensions.
jpayne@68	2367 </p>
jpayne@68	2368 </dd>
jpayne@68	2369 <dt> ‘<samp>-p</samp>’</dt>
jpayne@68	2370 <dt> ‘<samp>--properties-output</samp>’</dt>
jpayne@68	2371 <dd><a name="IDX835"></a>
jpayne@68	2372 <a name="IDX836"></a>
jpayne@68	2373 <p>Write out a Java ResourceBundle in Java <code>.properties</code> syntax. Note
jpayne@68	2374 that this file format doesn't support plural forms and silently drops
jpayne@68	2375 obsolete messages.
jpayne@68	2376 </p>
jpayne@68	2377 </dd>
jpayne@68	2378 <dt> ‘<samp>--stringtable-output</samp>’</dt>
jpayne@68	2379 <dd><a name="IDX837"></a>
jpayne@68	2380 <p>Write out a NeXTstep/GNUstep localized resource file in <code>.strings</code> syntax.
jpayne@68	2381 Note that this file format doesn't support plural forms.
jpayne@68	2382 </p>
jpayne@68	2383 </dd>
jpayne@68	2384 <dt> ‘<samp>-w <var>number</var></samp>’</dt>
jpayne@68	2385 <dt> ‘<samp>--width=<var>number</var></samp>’</dt>
jpayne@68	2386 <dd><a name="IDX838"></a>
jpayne@68	2387 <a name="IDX839"></a>
jpayne@68	2388 <p>Set the output page width. Long strings in the output files will be
jpayne@68	2389 split across multiple lines in order to ensure that each line's width
jpayne@68	2390 (= number of screen columns) is less or equal to the given <var>number</var>.
jpayne@68	2391 </p>
jpayne@68	2392 </dd>
jpayne@68	2393 <dt> ‘<samp>--no-wrap</samp>’</dt>
jpayne@68	2394 <dd><a name="IDX840"></a>
jpayne@68	2395 <p>Do not break long message lines. Message lines whose width exceeds the
jpayne@68	2396 output page width will not be split into several lines. Only file reference
jpayne@68	2397 lines which are wider than the output page width will be split.
jpayne@68	2398 </p>
jpayne@68	2399 </dd>
jpayne@68	2400 <dt> ‘<samp>-s</samp>’</dt>
jpayne@68	2401 <dt> ‘<samp>--sort-output</samp>’</dt>
jpayne@68	2402 <dd><a name="IDX841"></a>
jpayne@68	2403 <a name="IDX842"></a>
jpayne@68	2404 <p>Generate sorted output. Note that using this option makes it much harder
jpayne@68	2405 for the translator to understand each message's context.
jpayne@68	2406 </p>
jpayne@68	2407 </dd>
jpayne@68	2408 <dt> ‘<samp>-F</samp>’</dt>
jpayne@68	2409 <dt> ‘<samp>--sort-by-file</samp>’</dt>
jpayne@68	2410 <dd><a name="IDX843"></a>
jpayne@68	2411 <a name="IDX844"></a>
jpayne@68	2412 <p>Sort output by file location.
jpayne@68	2413 </p>
jpayne@68	2414 </dd>
jpayne@68	2415 </dl>
jpayne@68	2416
jpayne@68	2417
jpayne@68	2418 <a name="SEC152"></a>
jpayne@68	2419 <h3 class="subsection"> <a href="gettext_toc.html#TOC145">9.9.5 Informative output</a> </h3>
jpayne@68	2420
jpayne@68	2421 <dl compact="compact">
jpayne@68	2422 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	2423 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	2424 <dd><a name="IDX845"></a>
jpayne@68	2425 <a name="IDX846"></a>
jpayne@68	2426 <p>Display this help and exit.
jpayne@68	2427 </p>
jpayne@68	2428 </dd>
jpayne@68	2429 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	2430 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	2431 <dd><a name="IDX847"></a>
jpayne@68	2432 <a name="IDX848"></a>
jpayne@68	2433 <p>Output version information and exit.
jpayne@68	2434 </p>
jpayne@68	2435 </dd>
jpayne@68	2436 </dl>
jpayne@68	2437
jpayne@68	2438
jpayne@68	2439 <a name="msgexec-Invocation"></a>
jpayne@68	2440 <a name="SEC153"></a>
jpayne@68	2441 <h2 class="section"> <a href="gettext_toc.html#TOC146">9.10 Invoking the <code>msgexec</code> Program</a> </h2>
jpayne@68	2442
jpayne@68	2443
jpayne@68	2444 <table><tr><td> </td><td><pre class="example">msgexec [<var>option</var>] <var>command</var> [<var>command-option</var>]
jpayne@68	2445 </pre></td></tr></table>
jpayne@68	2446
jpayne@68	2447 <a name="IDX849"></a>
jpayne@68	2448 <p>The <code>msgexec</code> program applies a command to all translations of a
jpayne@68	2449 translation catalog.
jpayne@68	2450 The <var>command</var> can be any program that reads a translation from standard
jpayne@68	2451 input. It is invoked once for each translation. Its output becomes
jpayne@68	2452 msgexec's output. <code>msgexec</code>'s return code is the maximum return code
jpayne@68	2453 across all invocations.
jpayne@68	2454 </p>
jpayne@68	2455 <a name="IDX850"></a>
jpayne@68	2456 <p>A special builtin command called ‘<samp>0</samp>’ outputs the translation, followed
jpayne@68	2457 by a null byte. The output of ‘<samp>msgexec 0</samp>’ is suitable as input for
jpayne@68	2458 ‘<samp>xargs -0</samp>’.
jpayne@68	2459 </p>
jpayne@68	2460 <dl compact="compact">
jpayne@68	2461 <dt> ‘<samp>--newline</samp>’</dt>
jpayne@68	2462 <dd><a name="IDX851"></a>
jpayne@68	2463 <p>Add newline at the end of each input line.
jpayne@68	2464 </p>
jpayne@68	2465 </dd>
jpayne@68	2466 </dl>
jpayne@68	2467
jpayne@68	2468 <a name="IDX852"></a>
jpayne@68	2469 <a name="IDX853"></a>
jpayne@68	2470 <a name="IDX854"></a>
jpayne@68	2471 <a name="IDX855"></a>
jpayne@68	2472 <a name="IDX856"></a>
jpayne@68	2473 <a name="IDX857"></a>
jpayne@68	2474 <a name="IDX858"></a>
jpayne@68	2475 <a name="IDX859"></a>
jpayne@68	2476 <p>During each <var>command</var> invocation, the environment variable
jpayne@68	2477 <code>MSGEXEC_MSGID</code> is bound to the message's msgid, and the environment
jpayne@68	2478 variable <code>MSGEXEC_LOCATION</code> is bound to the location in the PO file
jpayne@68	2479 of the message. If the message has a context, the environment variable
jpayne@68	2480 <code>MSGEXEC_MSGCTXT</code> is bound to the message's msgctxt, otherwise it is
jpayne@68	2481 unbound. If the message has a plural form, environment variable
jpayne@68	2482 <code>MSGEXEC_MSGID_PLURAL</code> is bound to the message's msgid_plural and
jpayne@68	2483 <code>MSGEXEC_PLURAL_FORM</code> is bound to the order number of the plural
jpayne@68	2484 actually processed (starting with 0), otherwise both are unbound.
jpayne@68	2485 If the message has a previous msgid (added by <code>msgmerge</code>),
jpayne@68	2486 environment variable <code>MSGEXEC_PREV_MSGCTXT</code> is bound to the
jpayne@68	2487 message's previous msgctxt, <code>MSGEXEC_PREV_MSGID</code> is bound to
jpayne@68	2488 the previous msgid, and <code>MSGEXEC_PREV_MSGID_PLURAL</code> is bound to
jpayne@68	2489 the previous msgid_plural.
jpayne@68	2490 </p>
jpayne@68	2491 <a name="IDX860"></a>
jpayne@68	2492 <p>Note: It is your responsibility to ensure that the <var>command</var> can cope
jpayne@68	2493 with input encoded in the translation catalog's encoding. If the
jpayne@68	2494 <var>command</var> wants input in a particular encoding, you can in a first step
jpayne@68	2495 convert the translation catalog to that encoding using the ‘<samp>msgconv</samp>’
jpayne@68	2496 program, before invoking ‘<samp>msgexec</samp>’. If the <var>command</var> wants input
jpayne@68	2497 in the locale's encoding, but you want to avoid the locale's encoding, then
jpayne@68	2498 you can first convert the translation catalog to UTF-8 using the
jpayne@68	2499 ‘<samp>msgconv</samp>’ program and then make ‘<samp>msgexec</samp>’ work in an UTF-8
jpayne@68	2500 locale, by using the <code>LC_ALL</code> environment variable.
jpayne@68	2501 </p>
jpayne@68	2502
jpayne@68	2503 <a name="SEC154"></a>
jpayne@68	2504 <h3 class="subsection"> <a href="gettext_toc.html#TOC147">9.10.1 Input file location</a> </h3>
jpayne@68	2505
jpayne@68	2506 <dl compact="compact">
jpayne@68	2507 <dt> ‘<samp>-i <var>inputfile</var></samp>’</dt>
jpayne@68	2508 <dt> ‘<samp>--input=<var>inputfile</var></samp>’</dt>
jpayne@68	2509 <dd><a name="IDX861"></a>
jpayne@68	2510 <a name="IDX862"></a>
jpayne@68	2511 <p>Input PO file.
jpayne@68	2512 </p>
jpayne@68	2513 </dd>
jpayne@68	2514 <dt> ‘<samp>-D <var>directory</var></samp>’</dt>
jpayne@68	2515 <dt> ‘<samp>--directory=<var>directory</var></samp>’</dt>
jpayne@68	2516 <dd><a name="IDX863"></a>
jpayne@68	2517 <a name="IDX864"></a>
jpayne@68	2518 <p>Add <var>directory</var> to the list of directories. Source files are
jpayne@68	2519 searched relative to this list of directories. The resulting ‘<tt>.po</tt>’
jpayne@68	2520 file will be written relative to the current directory, though.
jpayne@68	2521 </p>
jpayne@68	2522 </dd>
jpayne@68	2523 </dl>
jpayne@68	2524
jpayne@68	2525 <p>If no <var>inputfile</var> is given or if it is ‘<samp>-</samp>’, standard input is read.
jpayne@68	2526 </p>
jpayne@68	2527
jpayne@68	2528 <a name="SEC155"></a>
jpayne@68	2529 <h3 class="subsection"> <a href="gettext_toc.html#TOC148">9.10.2 Input file syntax</a> </h3>
jpayne@68	2530
jpayne@68	2531 <dl compact="compact">
jpayne@68	2532 <dt> ‘<samp>-P</samp>’</dt>
jpayne@68	2533 <dt> ‘<samp>--properties-input</samp>’</dt>
jpayne@68	2534 <dd><a name="IDX865"></a>
jpayne@68	2535 <a name="IDX866"></a>
jpayne@68	2536 <p>Assume the input file is a Java ResourceBundle in Java <code>.properties</code>
jpayne@68	2537 syntax, not in PO file syntax.
jpayne@68	2538 </p>
jpayne@68	2539 </dd>
jpayne@68	2540 <dt> ‘<samp>--stringtable-input</samp>’</dt>
jpayne@68	2541 <dd><a name="IDX867"></a>
jpayne@68	2542 <p>Assume the input file is a NeXTstep/GNUstep localized resource file in
jpayne@68	2543 <code>.strings</code> syntax, not in PO file syntax.
jpayne@68	2544 </p>
jpayne@68	2545 </dd>
jpayne@68	2546 </dl>
jpayne@68	2547
jpayne@68	2548
jpayne@68	2549 <a name="SEC156"></a>
jpayne@68	2550 <h3 class="subsection"> <a href="gettext_toc.html#TOC149">9.10.3 Informative output</a> </h3>
jpayne@68	2551
jpayne@68	2552 <dl compact="compact">
jpayne@68	2553 <dt> ‘<samp>-h</samp>’</dt>
jpayne@68	2554 <dt> ‘<samp>--help</samp>’</dt>
jpayne@68	2555 <dd><a name="IDX868"></a>
jpayne@68	2556 <a name="IDX869"></a>
jpayne@68	2557 <p>Display this help and exit.
jpayne@68	2558 </p>
jpayne@68	2559 </dd>
jpayne@68	2560 <dt> ‘<samp>-V</samp>’</dt>
jpayne@68	2561 <dt> ‘<samp>--version</samp>’</dt>
jpayne@68	2562 <dd><a name="IDX870"></a>
jpayne@68	2563 <a name="IDX871"></a>
jpayne@68	2564 <p>Output version information and exit.
jpayne@68	2565 </p>
jpayne@68	2566 </dd>
jpayne@68	2567 </dl>
jpayne@68	2568
jpayne@68	2569
jpayne@68	2570 <a name="Colorizing"></a>
jpayne@68	2571 <a name="SEC157"></a>
jpayne@68	2572 <h2 class="section"> <a href="gettext_toc.html#TOC150">9.11 Highlighting parts of PO files</a> </h2>
jpayne@68	2573
jpayne@68	2574 <p>Translators are usually only interested in seeing the untranslated and
jpayne@68	2575 fuzzy messages of a PO file. Also, when a message is set fuzzy because
jpayne@68	2576 the msgid changed, they want to see the differences between the previous
jpayne@68	2577 msgid and the current one (especially if the msgid is long and only few
jpayne@68	2578 words in it have changed). Finally, it's always welcome to highlight the
jpayne@68	2579 different sections of a message in a PO file (comments, msgid, msgstr, etc.).
jpayne@68	2580 </p>
jpayne@68	2581 <p>Such highlighting is possible through the options ‘<samp>--color</samp>’ and
jpayne@68	2582 ‘<samp>--style</samp>’. They are supported by all the programs that produce
jpayne@68	2583 a PO file on standard output, such as <code>msgcat</code>, <code>msgmerge</code>,
jpayne@68	2584 and <code>msgunfmt</code>.
jpayne@68	2585 </p>
jpayne@68	2586
jpayne@68	2587
jpayne@68	2588 <a name="The-_002d_002dcolor-option"></a>
jpayne@68	2589 <a name="SEC158"></a>
jpayne@68	2590 <h3 class="subsection"> <a href="gettext_toc.html#TOC151">9.11.1 The <code>--color</code> option</a> </h3>
jpayne@68	2591
jpayne@68	2592 <p>The ‘<samp>--color=<var>when</var></samp>’ option specifies under which conditions
jpayne@68	2593 colorized output should be generated. The <var>when</var> part can be one of
jpayne@68	2594 the following:
jpayne@68	2595 </p>
jpayne@68	2596 <dl compact="compact">
jpayne@68	2597 <dt> <code>always</code></dt>
jpayne@68	2598 <dt> <code>yes</code></dt>
jpayne@68	2599 <dd><p>The output will be colorized.
jpayne@68	2600 </p>
jpayne@68	2601 </dd>
jpayne@68	2602 <dt> <code>never</code></dt>
jpayne@68	2603 <dt> <code>no</code></dt>
jpayne@68	2604 <dd><p>The output will not be colorized.
jpayne@68	2605 </p>
jpayne@68	2606 </dd>
jpayne@68	2607 <dt> <code>auto</code></dt>
jpayne@68	2608 <dt> <code>tty</code></dt>
jpayne@68	2609 <dd><p>The output will be colorized if the output device is a tty, i.e. when the
jpayne@68	2610 output goes directly to a text screen or terminal emulator window.
jpayne@68	2611 </p>
jpayne@68	2612 </dd>
jpayne@68	2613 <dt> <code>html</code></dt>
jpayne@68	2614 <dd><p>The output will be colorized and be in HTML format.
jpayne@68	2615 </p>
jpayne@68	2616 </dd>
jpayne@68	2617 <dt> <code>test</code></dt>
jpayne@68	2618 <dd><p>This is a special value, understood only by the <code>msgcat</code> program. It
jpayne@68	2619 is explained in the next section (<a href="#SEC159">The environment variable <code>TERM</code></a>).
jpayne@68	2620 </p></dd>
jpayne@68	2621 </dl>
jpayne@68	2622
jpayne@68	2623 <p>‘<samp>--color</samp>’ is equivalent to ‘<samp>--color=yes</samp>’. The default is
jpayne@68	2624 ‘<samp>--color=auto</samp>’.
jpayne@68	2625 </p>
jpayne@68	2626 <p>Thus, a command like ‘<samp>msgcat vi.po</samp>’ will produce colorized output
jpayne@68	2627 when called by itself in a command window. Whereas in a pipe, such as
jpayne@68	2628 ‘<samp>msgcat vi.po \| less -R</samp>’, it will not produce colorized output. To
jpayne@68	2629 get colorized output in this situation nevertheless, use the command
jpayne@68	2630 ‘<samp>msgcat --color vi.po \| less -R</samp>’.
jpayne@68	2631 </p>
jpayne@68	2632 <p>The ‘<samp>--color=html</samp>’ option will produce output that can be viewed in
jpayne@68	2633 a browser. This can be useful, for example, for Indic languages,
jpayne@68	2634 because the renderic of Indic scripts in browsers is usually better than
jpayne@68	2635 in terminal emulators.
jpayne@68	2636 </p>
jpayne@68	2637 <p>Note that the output produced with the <code>--color</code> option is <em>not</em>
jpayne@68	2638 a valid PO file in itself. It contains additional terminal-specific escape
jpayne@68	2639 sequences or HTML tags. A PO file reader will give a syntax error when
jpayne@68	2640 confronted with such content. Except for the ‘<samp>--color=html</samp>’ case,
jpayne@68	2641 you therefore normally don't need to save output produced with the
jpayne@68	2642 <code>--color</code> option in a file.
jpayne@68	2643 </p>
jpayne@68	2644
jpayne@68	2645 <a name="The-TERM-variable"></a>
jpayne@68	2646 <a name="SEC159"></a>
jpayne@68	2647 <h3 class="subsection"> <a href="gettext_toc.html#TOC152">9.11.2 The environment variable <code>TERM</code></a> </h3>
jpayne@68	2648
jpayne@68	2649 <p>The environment variable <code>TERM</code> contains a identifier for the text
jpayne@68	2650 window's capabilities. You can get a detailed list of these cababilities
jpayne@68	2651 by using the ‘<samp>infocmp</samp>’ command, using ‘<samp>man 5 terminfo</samp>’ as a
jpayne@68	2652 reference.
jpayne@68	2653 </p>
jpayne@68	2654 <p>When producing text with embedded color directives, <code>msgcat</code> looks
jpayne@68	2655 at the <code>TERM</code> variable. Text windows today typically support at least
jpayne@68	2656 8 colors. Often, however, the text window supports 16 or more colors,
jpayne@68	2657 even though the <code>TERM</code> variable is set to a identifier denoting only
jpayne@68	2658 8 supported colors. It can be worth setting the <code>TERM</code> variable to
jpayne@68	2659 a different value in these cases:
jpayne@68	2660 </p>
jpayne@68	2661 <dl compact="compact">
jpayne@68	2662 <dt> <code>xterm</code></dt>
jpayne@68	2663 <dd><p><code>xterm</code> is in most cases built with support for 16 colors. It can also
jpayne@68	2664 be built with support for 88 or 256 colors (but not both). You can try to
jpayne@68	2665 set <code>TERM</code> to either <code>xterm-16color</code>, <code>xterm-88color</code>, or
jpayne@68	2666 <code>xterm-256color</code>.
jpayne@68	2667 </p>
jpayne@68	2668 </dd>
jpayne@68	2669 <dt> <code>rxvt</code></dt>
jpayne@68	2670 <dd><p><code>rxvt</code> is often built with support for 16 colors. You can try to set
jpayne@68	2671 <code>TERM</code> to <code>rxvt-16color</code>.
jpayne@68	2672 </p>
jpayne@68	2673 </dd>
jpayne@68	2674 <dt> <code>konsole</code></dt>
jpayne@68	2675 <dd><p><code>konsole</code> too is often built with support for 16 colors. You can try to
jpayne@68	2676 set <code>TERM</code> to <code>konsole-16color</code> or <code>xterm-16color</code>.
jpayne@68	2677 </p></dd>
jpayne@68	2678 </dl>
jpayne@68	2679
jpayne@68	2680 <p>After setting <code>TERM</code>, you can verify it by invoking
jpayne@68	2681 ‘<samp>msgcat --color=test</samp>’ and seeing whether the output looks like a
jpayne@68	2682 reasonable color map.
jpayne@68	2683 </p>
jpayne@68	2684
jpayne@68	2685 <a name="The-_002d_002dstyle-option"></a>
jpayne@68	2686 <a name="SEC160"></a>
jpayne@68	2687 <h3 class="subsection"> <a href="gettext_toc.html#TOC153">9.11.3 The <code>--style</code> option</a> </h3>
jpayne@68	2688
jpayne@68	2689 <p>The ‘<samp>--style=<var>style_file</var></samp>’ option specifies the style file to use
jpayne@68	2690 when colorizing. It has an effect only when the <code>--color</code> option is
jpayne@68	2691 effective.
jpayne@68	2692 </p>
jpayne@68	2693 <a name="IDX872"></a>
jpayne@68	2694 <p>If the <code>--style</code> option is not specified, the environment variable
jpayne@68	2695 <code>PO_STYLE</code> is considered. It is meant to point to the user's
jpayne@68	2696 preferred style for PO files.
jpayne@68	2697 </p>
jpayne@68	2698 <p>The default style file is ‘<tt>$prefix/share/gettext/styles/po-default.css</tt>’,
jpayne@68	2699 where <code>$prefix</code> is the installation location.
jpayne@68	2700 </p>
jpayne@68	2701 <p>A few style files are predefined:
jpayne@68	2702 </p><dl compact="compact">
jpayne@68	2703 <dt> ‘<tt>po-vim.css</tt>’</dt>
jpayne@68	2704 <dd><p>This style imitates the look used by vim 7.
jpayne@68	2705 </p>
jpayne@68	2706 </dd>
jpayne@68	2707 <dt> ‘<tt>po-emacs-x.css</tt>’</dt>
jpayne@68	2708 <dd><p>This style imitates the look used by GNU Emacs 21 and 22 in an X11 window.
jpayne@68	2709 </p>
jpayne@68	2710 </dd>
jpayne@68	2711 <dt> ‘<tt>po-emacs-xterm.css</tt>’</dt>
jpayne@68	2712 <dt> ‘<tt>po-emacs-xterm16.css</tt>’</dt>
jpayne@68	2713 <dt> ‘<tt>po-emacs-xterm256.css</tt>’</dt>
jpayne@68	2714 <dd><p>This style imitates the look used by GNU Emacs 22 in a terminal of type
jpayne@68	2715 ‘<samp>xterm</samp>’ (8 colors) or ‘<samp>xterm-16color</samp>’ (16 colors) or
jpayne@68	2716 ‘<samp>xterm-256color</samp>’ (256 colors), respectively.
jpayne@68	2717 </p></dd>
jpayne@68	2718 </dl>
jpayne@68	2719
jpayne@68	2720 <p>You can use these styles without specifying a directory. They are actually
jpayne@68	2721 located in ‘<tt>$prefix/share/gettext/styles/</tt>’, where <code>$prefix</code> is the
jpayne@68	2722 installation location.
jpayne@68	2723 </p>
jpayne@68	2724 <p>You can also design your own styles. This is described in the next section.
jpayne@68	2725 </p>
jpayne@68	2726
jpayne@68	2727
jpayne@68	2728 <a name="Style-rules"></a>
jpayne@68	2729 <a name="SEC161"></a>
jpayne@68	2730 <h3 class="subsection"> <a href="gettext_toc.html#TOC154">9.11.4 Style rules for PO files</a> </h3>
jpayne@68	2731
jpayne@68	2732 <p>The same style file can be used for styling of a PO file, for terminal
jpayne@68	2733 output and for HTML output. It is written in CSS (Cascading Style Sheet)
jpayne@68	2734 syntax. See <a href="https://www.w3.org/TR/css2/cover.html">https://www.w3.org/TR/css2/cover.html</a> for a formal
jpayne@68	2735 definition of CSS. Many HTML authoring tutorials also contain explanations
jpayne@68	2736 of CSS.
jpayne@68	2737 </p>
jpayne@68	2738 <p>In the case of HTML output, the style file is embedded in the HTML output.
jpayne@68	2739 In the case of text output, the style file is interpreted by the
jpayne@68	2740 <code>msgcat</code> program. This means, in particular, that when
jpayne@68	2741 <code>@import</code> is used with relative file names, the file names are
jpayne@68	2742 </p>
jpayne@68	2743 <ul class="toc">
jpayne@68	2744 <li>-
jpayne@68	2745 relative to the resulting HTML file, in the case of HTML output,
jpayne@68	2746
jpayne@68	2747 </li><li>-
jpayne@68	2748 relative to the style sheet containing the <code>@import</code>, in the case of
jpayne@68	2749 text output. (Actually, <code>@import</code>s are not yet supported in this case,
jpayne@68	2750 due to a limitation in <code>libcroco</code>.)
jpayne@68	2751 </li></ul>
jpayne@68	2752
jpayne@68	2753 <p>CSS rules are built up from selectors and declarations. The declarations
jpayne@68	2754 specify graphical properties; the selectors specify when they apply.
jpayne@68	2755 </p>
jpayne@68	2756 <p>In PO files, the following simple selectors (based on "CSS classes", see
jpayne@68	2757 the CSS2 spec, section 5.8.3) are supported.
jpayne@68	2758 </p>
jpayne@68	2759 <ul>
jpayne@68	2760 <li>
jpayne@68	2761 Selectors that apply to entire messages:
jpayne@68	2762
jpayne@68	2763 <dl compact="compact">
jpayne@68	2764 <dt> <code>.header</code></dt>
jpayne@68	2765 <dd><p>This matches the header entry of a PO file.
jpayne@68	2766 </p>
jpayne@68	2767 </dd>
jpayne@68	2768 <dt> <code>.translated</code></dt>
jpayne@68	2769 <dd><p>This matches a translated message.
jpayne@68	2770 </p>
jpayne@68	2771 </dd>
jpayne@68	2772 <dt> <code>.untranslated</code></dt>
jpayne@68	2773 <dd><p>This matches an untranslated message (i.e. a message with empty translation).
jpayne@68	2774 </p>
jpayne@68	2775 </dd>
jpayne@68	2776 <dt> <code>.fuzzy</code></dt>
jpayne@68	2777 <dd><p>This matches a fuzzy message (i.e. a message which has a translation that
jpayne@68	2778 needs review by the translator).
jpayne@68	2779 </p>
jpayne@68	2780 </dd>
jpayne@68	2781 <dt> <code>.obsolete</code></dt>
jpayne@68	2782 <dd><p>This matches an obsolete message (i.e. a message that was translated but is
jpayne@68	2783 not needed by the current POT file any more).
jpayne@68	2784 </p></dd>
jpayne@68	2785 </dl>
jpayne@68	2786
jpayne@68	2787 </li><li>
jpayne@68	2788 Selectors that apply to parts of a message in PO syntax. Recall the general
jpayne@68	2789 structure of a message in PO syntax:
jpayne@68	2790
jpayne@68	2791 <table><tr><td> </td><td><pre class="example"><var>white-space</var>
jpayne@68	2792 # <var>translator-comments</var>
jpayne@68	2793 #. <var>extracted-comments</var>
jpayne@68	2794 #: <var>reference</var>…
jpayne@68	2795 #, <var>flag</var>…
jpayne@68	2796 #\| msgid <var>previous-untranslated-string</var>
jpayne@68	2797 msgid <var>untranslated-string</var>
jpayne@68	2798 msgstr <var>translated-string</var>
jpayne@68	2799 </pre></td></tr></table>
jpayne@68	2800
jpayne@68	2801 <dl compact="compact">
jpayne@68	2802 <dt> <code>.comment</code></dt>
jpayne@68	2803 <dd><p>This matches all comments (translator comments, extracted comments,
jpayne@68	2804 source file reference comments, flag comments, previous message comments,
jpayne@68	2805 as well as the entire obsolete messages).
jpayne@68	2806 </p>
jpayne@68	2807 </dd>
jpayne@68	2808 <dt> <code>.translator-comment</code></dt>
jpayne@68	2809 <dd><p>This matches the translator comments.
jpayne@68	2810 </p>
jpayne@68	2811 </dd>
jpayne@68	2812 <dt> <code>.extracted-comment</code></dt>
jpayne@68	2813 <dd><p>This matches the extracted comments, i.e. the comments placed by the
jpayne@68	2814 programmer at the attention of the translator.
jpayne@68	2815 </p>
jpayne@68	2816 </dd>
jpayne@68	2817 <dt> <code>.reference-comment</code></dt>
jpayne@68	2818 <dd><p>This matches the source file reference comments (entire lines).
jpayne@68	2819 </p>
jpayne@68	2820 </dd>
jpayne@68	2821 <dt> <code>.reference</code></dt>
jpayne@68	2822 <dd><p>This matches the individual source file references inside the source file
jpayne@68	2823 reference comment lines.
jpayne@68	2824 </p>
jpayne@68	2825 </dd>
jpayne@68	2826 <dt> <code>.flag-comment</code></dt>
jpayne@68	2827 <dd><p>This matches the flag comment lines (entire lines).
jpayne@68	2828 </p>
jpayne@68	2829 </dd>
jpayne@68	2830 <dt> <code>.flag</code></dt>
jpayne@68	2831 <dd><p>This matches the individual flags inside flag comment lines.
jpayne@68	2832 </p>
jpayne@68	2833 </dd>
jpayne@68	2834 <dt> <code>.fuzzy-flag</code></dt>
jpayne@68	2835 <dd><p>This matches the `fuzzy' flag inside flag comment lines.
jpayne@68	2836 </p>
jpayne@68	2837 </dd>
jpayne@68	2838 <dt> <code>.previous-comment</code></dt>
jpayne@68	2839 <dd><p>This matches the comments containing the previous untranslated string (entire
jpayne@68	2840 lines).
jpayne@68	2841 </p>
jpayne@68	2842 </dd>
jpayne@68	2843 <dt> <code>.previous</code></dt>
jpayne@68	2844 <dd><p>This matches the previous untranslated string including the string delimiters,
jpayne@68	2845 the associated keywords (<code>msgid</code> etc.) and the spaces between them.
jpayne@68	2846 </p>
jpayne@68	2847 </dd>
jpayne@68	2848 <dt> <code>.msgid</code></dt>
jpayne@68	2849 <dd><p>This matches the untranslated string including the string delimiters,
jpayne@68	2850 the associated keywords (<code>msgid</code> etc.) and the spaces between them.
jpayne@68	2851 </p>
jpayne@68	2852 </dd>
jpayne@68	2853 <dt> <code>.msgstr</code></dt>
jpayne@68	2854 <dd><p>This matches the translated string including the string delimiters,
jpayne@68	2855 the associated keywords (<code>msgstr</code> etc.) and the spaces between them.
jpayne@68	2856 </p>
jpayne@68	2857 </dd>
jpayne@68	2858 <dt> <code>.keyword</code></dt>
jpayne@68	2859 <dd><p>This matches the keywords (<code>msgid</code>, <code>msgstr</code>, etc.).
jpayne@68	2860 </p>
jpayne@68	2861 </dd>
jpayne@68	2862 <dt> <code>.string</code></dt>
jpayne@68	2863 <dd><p>This matches strings, including the string delimiters (double quotes).
jpayne@68	2864 </p></dd>
jpayne@68	2865 </dl>
jpayne@68	2866
jpayne@68	2867 </li><li>
jpayne@68	2868 Selectors that apply to parts of strings:
jpayne@68	2869
jpayne@68	2870 <dl compact="compact">
jpayne@68	2871 <dt> <code>.text</code></dt>
jpayne@68	2872 <dd><p>This matches the entire contents of a string (excluding the string delimiters,
jpayne@68	2873 i.e. the double quotes).
jpayne@68	2874 </p>
jpayne@68	2875 </dd>
jpayne@68	2876 <dt> <code>.escape-sequence</code></dt>
jpayne@68	2877 <dd><p>This matches an escape sequence (starting with a backslash).
jpayne@68	2878 </p>
jpayne@68	2879 </dd>
jpayne@68	2880 <dt> <code>.format-directive</code></dt>
jpayne@68	2881 <dd><p>This matches a format string directive (starting with a ‘<samp>%</samp>’ sign in the
jpayne@68	2882 case of most programming languages, with a ‘<samp>{</samp>’ in the case of
jpayne@68	2883 <code>java-format</code> and <code>csharp-format</code>, with a ‘<samp>~</samp>’ in the case of
jpayne@68	2884 <code>lisp-format</code> and <code>scheme-format</code>, or with ‘<samp>$</samp>’ in the case of
jpayne@68	2885 <code>sh-format</code>).
jpayne@68	2886 </p>
jpayne@68	2887 </dd>
jpayne@68	2888 <dt> <code>.invalid-format-directive</code></dt>
jpayne@68	2889 <dd><p>This matches an invalid format string directive.
jpayne@68	2890 </p>
jpayne@68	2891 </dd>
jpayne@68	2892 <dt> <code>.added</code></dt>
jpayne@68	2893 <dd><p>In an untranslated string, this matches a part of the string that was not
jpayne@68	2894 present in the previous untranslated string. (Not yet implemented in this
jpayne@68	2895 release.)
jpayne@68	2896 </p>
jpayne@68	2897 </dd>
jpayne@68	2898 <dt> <code>.changed</code></dt>
jpayne@68	2899 <dd><p>In an untranslated string or in a previous untranslated string, this matches
jpayne@68	2900 a part of the string that is changed or replaced. (Not yet implemented in
jpayne@68	2901 this release.)
jpayne@68	2902 </p>
jpayne@68	2903 </dd>
jpayne@68	2904 <dt> <code>.removed</code></dt>
jpayne@68	2905 <dd><p>In a previous untranslated string, this matches a part of the string that
jpayne@68	2906 is not present in the current untranslated string. (Not yet implemented in
jpayne@68	2907 this release.)
jpayne@68	2908 </p></dd>
jpayne@68	2909 </dl>
jpayne@68	2910 </li></ul>
jpayne@68	2911
jpayne@68	2912 <p>These selectors can be combined to hierarchical selectors. For example,
jpayne@68	2913 </p>
jpayne@68	2914 <table><tr><td> </td><td><pre class="smallexample">.msgstr .invalid-format-directive { color: red; }
jpayne@68	2915 </pre></td></tr></table>
jpayne@68	2916
jpayne@68	2917 <p>will highlight the invalid format directives in the translated strings.
jpayne@68	2918 </p>
jpayne@68	2919 <p>In text mode, pseudo-classes (CSS2 spec, section 5.11) and pseudo-elements
jpayne@68	2920 (CSS2 spec, section 5.12) are not supported.
jpayne@68	2921 </p>
jpayne@68	2922 <p>The declarations in HTML mode are not limited; any graphical attribute
jpayne@68	2923 supported by the browsers can be used.
jpayne@68	2924 </p>
jpayne@68	2925 <p>The declarations in text mode are limited to the following properties. Other
jpayne@68	2926 properties will be silently ignored.
jpayne@68	2927 </p>
jpayne@68	2928 <dl compact="compact">
jpayne@68	2929 <dt> <code>color</code> (CSS2 spec, section 14.1)</dt>
jpayne@68	2930 <dt> <code>background-color</code> (CSS2 spec, section 14.2.1)</dt>
jpayne@68	2931 <dd><p>These properties is supported. Colors will be adjusted to match the terminal's
jpayne@68	2932 capabilities. Note that many terminals support only 8 colors.
jpayne@68	2933 </p>
jpayne@68	2934 </dd>
jpayne@68	2935 <dt> <code>font-weight</code> (CSS2 spec, section 15.2.3)</dt>
jpayne@68	2936 <dd><p>This property is supported, but most terminals can only render two different
jpayne@68	2937 weights: <code>normal</code> and <code>bold</code>. Values >= 600 are rendered as
jpayne@68	2938 <code>bold</code>.
jpayne@68	2939 </p>
jpayne@68	2940 </dd>
jpayne@68	2941 <dt> <code>font-style</code> (CSS2 spec, section 15.2.3)</dt>
jpayne@68	2942 <dd><p>This property is supported. The values <code>italic</code> and <code>oblique</code> are
jpayne@68	2943 rendered the same way.
jpayne@68	2944 </p>
jpayne@68	2945 </dd>
jpayne@68	2946 <dt> <code>text-decoration</code> (CSS2 spec, section 16.3.1)</dt>
jpayne@68	2947 <dd><p>This property is supported, limited to the values <code>none</code> and
jpayne@68	2948 <code>underline</code>.
jpayne@68	2949 </p></dd>
jpayne@68	2950 </dl>
jpayne@68	2951
jpayne@68	2952
jpayne@68	2953 <a name="Customizing-less"></a>
jpayne@68	2954 <a name="SEC162"></a>
jpayne@68	2955 <h3 class="subsection"> <a href="gettext_toc.html#TOC155">9.11.5 Customizing <code>less</code> for viewing PO files</a> </h3>
jpayne@68	2956
jpayne@68	2957 <p>The ‘<samp>less</samp>’ program is a popular text file browser for use in a text
jpayne@68	2958 screen or terminal emulator. It also supports text with embedded escape
jpayne@68	2959 sequences for colors and text decorations.
jpayne@68	2960 </p>
jpayne@68	2961 <p>You can use <code>less</code> to view a PO file like this (assuming an UTF-8
jpayne@68	2962 environment):
jpayne@68	2963 </p>
jpayne@68	2964 <table><tr><td> </td><td><pre class="smallexample">msgcat --to-code=UTF-8 --color xyz.po \| less -R
jpayne@68	2965 </pre></td></tr></table>
jpayne@68	2966
jpayne@68	2967 <p>You can simplify this to this simple command:
jpayne@68	2968 </p>
jpayne@68	2969 <table><tr><td> </td><td><pre class="smallexample">less xyz.po
jpayne@68	2970 </pre></td></tr></table>
jpayne@68	2971
jpayne@68	2972 <p>after these three preparations:
jpayne@68	2973 </p>
jpayne@68	2974 <ol>
jpayne@68	2975 <li>
jpayne@68	2976 Add the options ‘<samp>-R</samp>’ and ‘<samp>-f</samp>’ to the <code>LESS</code> environment
jpayne@68	2977 variable. In sh shells:
jpayne@68	2978 <table><tr><td> </td><td><pre class="smallexample">$ LESS="$LESS -R -f"
jpayne@68	2979 $ export LESS
jpayne@68	2980 </pre></td></tr></table>
jpayne@68	2981
jpayne@68	2982 </li><li>
jpayne@68	2983 If your system does not already have the ‘<tt>lessopen.sh</tt>’ and
jpayne@68	2984 ‘<tt>lessclose.sh</tt>’ scripts, create them and set the <code>LESSOPEN</code> and
jpayne@68	2985 <code>LESSCLOSE</code> environment variables, as indicated in the manual page
jpayne@68	2986 (‘<samp>man less</samp>’).
jpayne@68	2987
jpayne@68	2988 </li><li>
jpayne@68	2989 Add to ‘<tt>lessopen.sh</tt>’ a piece of script that recognizes PO files
jpayne@68	2990 through their file extension and invokes <code>msgcat</code> on them, producing
jpayne@68	2991 a temporary file. Like this:
jpayne@68	2992
jpayne@68	2993 <table><tr><td> </td><td><pre class="smallexample">case "$1" in
jpayne@68	2994 *.po)
jpayne@68	2995 tmpfile=`mktemp "${TMPDIR-/tmp}/less.XXXXXX"`
jpayne@68	2996 msgcat --to-code=UTF-8 --color "$1" > "$tmpfile"
jpayne@68	2997 echo "$tmpfile"
jpayne@68	2998 exit 0
jpayne@68	2999 ;;
jpayne@68	3000 esac
jpayne@68	3001 </pre></td></tr></table>
jpayne@68	3002 </li></ol>
jpayne@68	3003
jpayne@68	3004
jpayne@68	3005 <a name="Other-tools"></a>
jpayne@68	3006 <a name="SEC163"></a>
jpayne@68	3007 <h2 class="section"> <a href="gettext_toc.html#TOC156">9.12 Other tools for manipulating PO files</a> </h2>
jpayne@68	3008
jpayne@68	3009 <p>The “Pology” package is a Free Software package for manipulating PO files.
jpayne@68	3010 It features, in particular:
jpayne@68	3011 </p>
jpayne@68	3012 <ul class="toc">
jpayne@68	3013 <li>
jpayne@68	3014 Examination and in-place modification of collections of PO files.
jpayne@68	3015 </li><li>
jpayne@68	3016 Format-aware diffing and patching of PO files.
jpayne@68	3017 </li><li>
jpayne@68	3018 Handling of version-control branches.
jpayne@68	3019 </li><li>
jpayne@68	3020 Fine-grained asynchronous review workflow.
jpayne@68	3021 </li><li>
jpayne@68	3022 Custom translation validation.
jpayne@68	3023 </li><li>
jpayne@68	3024 Language and project specific support.
jpayne@68	3025 </li></ul>
jpayne@68	3026
jpayne@68	3027 <p>Its home page is at <a href="http://pology.nedohodnik.net/">http://pology.nedohodnik.net/</a>.
jpayne@68	3028 </p>
jpayne@68	3029
jpayne@68	3030 <a name="libgettextpo"></a>
jpayne@68	3031 <a name="SEC164"></a>
jpayne@68	3032 <h2 class="section"> <a href="gettext_toc.html#TOC157">9.13 Writing your own programs that process PO files</a> </h2>
jpayne@68	3033
jpayne@68	3034 <p>For the tasks for which a combination of ‘<samp>msgattrib</samp>’, ‘<samp>msgcat</samp>’ etc.
jpayne@68	3035 is not sufficient, a set of C functions is provided in a library, to make it
jpayne@68	3036 possible to process PO files in your own programs. When you use this library,
jpayne@68	3037 you don't need to write routines to parse the PO file; instead, you retrieve
jpayne@68	3038 a pointer in memory to each of messages contained in the PO file. Functions
jpayne@68	3039 for writing those memory structures to a file after working with them are
jpayne@68	3040 provided too.
jpayne@68	3041 </p>
jpayne@68	3042 <p>The functions are declared in the header file ‘<samp><gettext-po.h></samp>’, and are
jpayne@68	3043 defined in a library called ‘<samp>libgettextpo</samp>’.
jpayne@68	3044 </p>
jpayne@68	3045
jpayne@68	3046 <p>The following example shows code how these functions can be used. Error
jpayne@68	3047 handling code is omitted, as its implementation is delegated to the user
jpayne@68	3048 provided functions.
jpayne@68	3049 </p>
jpayne@68	3050 <table><tr><td> </td><td><pre class="example">struct po_xerror_handler handler =
jpayne@68	3051 {
jpayne@68	3052 .xerror = …,
jpayne@68	3053 .xerror2 = …
jpayne@68	3054 };
jpayne@68	3055 const char *filename = …;
jpayne@68	3056 /* Read the file into memory. */
jpayne@68	3057 po_file_t file = po_file_read (filename, &handler);
jpayne@68	3058
jpayne@68	3059 {
jpayne@68	3060 const char * const *domains = po_file_domains (file);
jpayne@68	3061 const char * const *domainp;
jpayne@68	3062
jpayne@68	3063 /* Iterate the domains contained in the file. */
jpayne@68	3064 for (domainp = domains; *domainp; domainp++)
jpayne@68	3065 {
jpayne@68	3066 po_message_t *message;
jpayne@68	3067 const char domain = domainp;
jpayne@68	3068 po_message_iterator_t iterator = po_message_iterator (file, domain);
jpayne@68	3069
jpayne@68	3070 /* Iterate each message inside the domain. */
jpayne@68	3071 while ((message = po_next_message (iterator)) != NULL)
jpayne@68	3072 {
jpayne@68	3073 /* Read data from the message … */
jpayne@68	3074 const char *msgid = po_message_msgid (message);
jpayne@68	3075 const char *msgstr = po_message_msgstr (message);
jpayne@68	3076
jpayne@68	3077 …
jpayne@68	3078
jpayne@68	3079 /* Modify its contents … */
jpayne@68	3080 if (perform_some_tests (msgid, msgstr))
jpayne@68	3081 po_message_set_fuzzy (message, 1);
jpayne@68	3082
jpayne@68	3083 …
jpayne@68	3084 }
jpayne@68	3085 /* Always release returned po_message_iterator_t. */
jpayne@68	3086 po_message_iterator_free (iterator);
jpayne@68	3087 }
jpayne@68	3088
jpayne@68	3089 /* Write back the result. */
jpayne@68	3090 po_file_t result = po_file_write (file, filename, &handler);
jpayne@68	3091 }
jpayne@68	3092
jpayne@68	3093 /* Always release the returned po_file_t. */
jpayne@68	3094 po_file_free (file);
jpayne@68	3095 </pre></td></tr></table>
jpayne@68	3096
jpayne@68	3097
jpayne@68	3098 <a name="Error-Handling"></a>
jpayne@68	3099 <a name="SEC165"></a>
jpayne@68	3100 <h3 class="subsection"> <a href="gettext_toc.html#TOC158">9.13.1 Error Handling</a> </h3>
jpayne@68	3101
jpayne@68	3102 <p>Error management is performed through callbacks provided by the user of
jpayne@68	3103 the library. They are provided through a parameter with the following
jpayne@68	3104 type:
jpayne@68	3105 </p>
jpayne@68	3106 <dl>
jpayne@68	3107 <dt><u>Data Type:</u> <b>struct</b><i> po_xerror_handler</i>
jpayne@68	3108 <a name="IDX873"></a>
jpayne@68	3109 </dt>
jpayne@68	3110 <dd><p>Its pointer is defined as <code>po_xerror_handler_t</code>. Contains
jpayne@68	3111 two fields, <code>xerror</code> and <code>xerror2</code>, with the following function
jpayne@68	3112 signatures.
jpayne@68	3113 </p></dd></dl>
jpayne@68	3114
jpayne@68	3115 <dl>
jpayne@68	3116 <dt><u>Function:</u> void <b>xerror</b><i> (int <var>severity</var>, po_message_t <var>message</var>, const char <var>filename</var>, size_t <var>lineno</var>, size_t <var>column</var>, int <var>multiline_p</var>, const char <var>message_text</var>)</i>
jpayne@68	3117 <a name="IDX874"></a>
jpayne@68	3118 </dt>
jpayne@68	3119 <dd><p>This function is called to signal a problem of the given <var>severity</var>.
jpayne@68	3120 It <em>must not return</em> if <var>severity</var> is
jpayne@68	3121 <code>PO_SEVERITY_FATAL_ERROR</code>.
jpayne@68	3122 </p>
jpayne@68	3123 <p><var>message_text</var> is the problem description. When <var>multiline_p</var>
jpayne@68	3124 is true, it can contain multiple lines of text, each terminated with a
jpayne@68	3125 newline, otherwise a single line.
jpayne@68	3126 </p>
jpayne@68	3127 <p><var>message</var> and/or <var>filename</var> and <var>lineno</var> indicate where the
jpayne@68	3128 problem occurred:
jpayne@68	3129 </p>
jpayne@68	3130 <ul>
jpayne@68	3131 <li>
jpayne@68	3132 If <var>filename</var> is <code>NULL</code>, <var>filename</var> and <var>lineno</var> and
jpayne@68	3133 <var>column</var> should be ignored.
jpayne@68	3134
jpayne@68	3135 </li><li>
jpayne@68	3136 If <var>lineno</var> is <code>(size_t)(-1)</code>, <var>lineno</var> and <var>column</var>
jpayne@68	3137 should be ignored.
jpayne@68	3138
jpayne@68	3139 </li><li>
jpayne@68	3140 If <var>column</var> is <code>(size_t)(-1)</code>, it should be ignored.
jpayne@68	3141 </li></ul>
jpayne@68	3142 </dd></dl>
jpayne@68	3143
jpayne@68	3144 <dl>
jpayne@68	3145 <dt><u>Function:</u> void <b>xerror2</b><i> (int <var>severity</var>, po_message_t <var>message1</var>, const char <var>filename1</var>, size_t <var>lineno1</var>, size_t <var>column1</var>, int <var>multiline_p1</var>, const char <var>message_text1</var>, po_message_t <var>message2</var>, const char <var>filename2</var>, size_t <var>lineno2</var>, size_t <var>column2</var>, int <var>multiline_p2</var>, const char <var>message_text2</var>)</i>
jpayne@68	3146 <a name="IDX875"></a>
jpayne@68	3147 </dt>
jpayne@68	3148 <dd><p>This function is called to signal a problem of the given <var>severity</var>
jpayne@68	3149 that refers to two messages. It <em>must not return</em> if
jpayne@68	3150 <var>severity</var> is <code>PO_SEVERITY_FATAL_ERROR</code>.
jpayne@68	3151 </p>
jpayne@68	3152 <p>It is similar to two calls to xerror. If possible, an ellipsis can be
jpayne@68	3153 appended to <var>message_text1</var> and prepended to <var>message_text2</var>.
jpayne@68	3154 </p></dd></dl>
jpayne@68	3155
jpayne@68	3156
jpayne@68	3157 <a name="po_005ffile_005ft-API"></a>
jpayne@68	3158 <a name="SEC166"></a>
jpayne@68	3159 <h3 class="subsection"> <a href="gettext_toc.html#TOC159">9.13.2 po_file_t API</a> </h3>
jpayne@68	3160
jpayne@68	3161 <dl>
jpayne@68	3162 <dt><u>Data Type:</u> <b>po_file_t</b>
jpayne@68	3163 <a name="IDX876"></a>
jpayne@68	3164 </dt>
jpayne@68	3165 <dd><p>This is a pointer type that refers to the contents of a PO file, after it has
jpayne@68	3166 been read into memory.
jpayne@68	3167 </p></dd></dl>
jpayne@68	3168
jpayne@68	3169 <dl>
jpayne@68	3170 <dt><u>Function:</u> po_file_t <b>po_file_create</b><i> ()</i>
jpayne@68	3171 <a name="IDX877"></a>
jpayne@68	3172 </dt>
jpayne@68	3173 <dd><p>The <code>po_file_create</code> function creates an empty PO file representation in
jpayne@68	3174 memory.
jpayne@68	3175 </p></dd></dl>
jpayne@68	3176
jpayne@68	3177 <dl>
jpayne@68	3178 <dt><u>Function:</u> po_file_t <b>po_file_read</b><i> (const char <var>filename</var>, struct po_xerror_handler <var>handler</var>)</i>
jpayne@68	3179 <a name="IDX878"></a>
jpayne@68	3180 </dt>
jpayne@68	3181 <dd><p>The <code>po_file_read</code> function reads a PO file into memory. The file name
jpayne@68	3182 is given as argument. The return value is a handle to the PO file's contents,
jpayne@68	3183 valid until <code>po_file_free</code> is called on it. In case of error, the
jpayne@68	3184 functions from <var>handler</var> are called to signal it.
jpayne@68	3185 </p>
jpayne@68	3186 <p>This function is exported as ‘<samp>po_file_read_v3</samp>’ at ABI level, but is
jpayne@68	3187 defined as <code>po_file_read</code> in C code after the inclusion of
jpayne@68	3188 ‘<samp><gettext-po.h></samp>’.
jpayne@68	3189 </p></dd></dl>
jpayne@68	3190
jpayne@68	3191 <dl>
jpayne@68	3192 <dt><u>Function:</u> po_file_t <b>po_file_write</b><i> (po_file_t <var>file</var>, const char <var>filename</var>, struct po_xerror_handler <var>handler</var>)</i>
jpayne@68	3193 <a name="IDX879"></a>
jpayne@68	3194 </dt>
jpayne@68	3195 <dd><p>The <code>po_file_write</code> function writes the contents of the memory
jpayne@68	3196 structure <var>file</var> the <var>filename</var> given. The return value is
jpayne@68	3197 <var>file</var> after a successful operation. In case of error, the
jpayne@68	3198 functions from <var>handler</var> are called to signal it.
jpayne@68	3199 </p>
jpayne@68	3200 <p>This function is exported as ‘<samp>po_file_write_v2</samp>’ at ABI level, but
jpayne@68	3201 is defined as <code>po_file_write</code> in C code after the inclusion of
jpayne@68	3202 ‘<samp><gettext-po.h></samp>’.
jpayne@68	3203 </p></dd></dl>
jpayne@68	3204
jpayne@68	3205 <dl>
jpayne@68	3206 <dt><u>Function:</u> void <b>po_file_free</b><i> (po_file_t <var>file</var>)</i>
jpayne@68	3207 <a name="IDX880"></a>
jpayne@68	3208 </dt>
jpayne@68	3209 <dd><p>The <code>po_file_free</code> function frees a PO file's contents from memory,
jpayne@68	3210 including all messages that are only implicitly accessible through iterators.
jpayne@68	3211 </p></dd></dl>
jpayne@68	3212
jpayne@68	3213 <dl>
jpayne@68	3214 <dt><u>Function:</u> const char * const * <b>po_file_domains</b><i> (po_file_t <var>file</var>)</i>
jpayne@68	3215 <a name="IDX881"></a>
jpayne@68	3216 </dt>
jpayne@68	3217 <dd><p>The <code>po_file_domains</code> function returns the domains for which the given
jpayne@68	3218 PO file has messages. The return value is a <code>NULL</code> terminated array
jpayne@68	3219 which is valid as long as the <var>file</var> handle is valid. For PO files which
jpayne@68	3220 contain no ‘<samp>domain</samp>’ directive, the return value contains only one domain,
jpayne@68	3221 namely the default domain <code>"messages"</code>.
jpayne@68	3222 </p></dd></dl>
jpayne@68	3223
jpayne@68	3224
jpayne@68	3225 <a name="po_005fmessage_005fiterator_005ft-API"></a>
jpayne@68	3226 <a name="SEC167"></a>
jpayne@68	3227 <h3 class="subsection"> <a href="gettext_toc.html#TOC160">9.13.3 po_message_iterator_t API</a> </h3>
jpayne@68	3228
jpayne@68	3229 <dl>
jpayne@68	3230 <dt><u>Data Type:</u> <b>po_message_iterator_t</b>
jpayne@68	3231 <a name="IDX882"></a>
jpayne@68	3232 </dt>
jpayne@68	3233 <dd><p>This is a pointer type that refers to an iterator that produces a sequence of
jpayne@68	3234 messages.
jpayne@68	3235 </p></dd></dl>
jpayne@68	3236
jpayne@68	3237 <dl>
jpayne@68	3238 <dt><u>Function:</u> po_message_iterator_t <b>po_message_iterator</b><i> (po_file_t <var>file</var>, const char *<var>domain</var>)</i>
jpayne@68	3239 <a name="IDX883"></a>
jpayne@68	3240 </dt>
jpayne@68	3241 <dd><p>The <code>po_message_iterator</code> returns an iterator that will produce the
jpayne@68	3242 messages of <var>file</var> that belong to the given <var>domain</var>. If <var>domain</var>
jpayne@68	3243 is <code>NULL</code>, the default domain is used instead. To list the messages,
jpayne@68	3244 use the function <code>po_next_message</code> repeatedly.
jpayne@68	3245 </p></dd></dl>
jpayne@68	3246
jpayne@68	3247 <dl>
jpayne@68	3248 <dt><u>Function:</u> void <b>po_message_iterator_free</b><i> (po_message_iterator_t <var>iterator</var>)</i>
jpayne@68	3249 <a name="IDX884"></a>
jpayne@68	3250 </dt>
jpayne@68	3251 <dd><p>The <code>po_message_iterator_free</code> function frees an iterator previously
jpayne@68	3252 allocated through the <code>po_message_iterator</code> function.
jpayne@68	3253 </p></dd></dl>
jpayne@68	3254
jpayne@68	3255 <dl>
jpayne@68	3256 <dt><u>Function:</u> po_message_t <b>po_next_message</b><i> (po_message_iterator_t <var>iterator</var>)</i>
jpayne@68	3257 <a name="IDX885"></a>
jpayne@68	3258 </dt>
jpayne@68	3259 <dd><p>The <code>po_next_message</code> function returns the next message from
jpayne@68	3260 <var>iterator</var> and advances the iterator. It returns <code>NULL</code> when the
jpayne@68	3261 iterator has reached the end of its message list.
jpayne@68	3262 </p></dd></dl>
jpayne@68	3263
jpayne@68	3264
jpayne@68	3265 <a name="po_005fmessage_005ft-API"></a>
jpayne@68	3266 <a name="SEC168"></a>
jpayne@68	3267 <h3 class="subsection"> <a href="gettext_toc.html#TOC161">9.13.4 po_message_t API</a> </h3>
jpayne@68	3268
jpayne@68	3269 <dl>
jpayne@68	3270 <dt><u>Data Type:</u> <b>po_message_t</b>
jpayne@68	3271 <a name="IDX886"></a>
jpayne@68	3272 </dt>
jpayne@68	3273 <dd><p>This is a pointer type that refers to a message of a PO file, including its
jpayne@68	3274 translation.
jpayne@68	3275 </p></dd></dl>
jpayne@68	3276
jpayne@68	3277 <dl>
jpayne@68	3278 <dt><u>Function:</u> po_message_t <b>po_message_create</b><i> (void)</i>
jpayne@68	3279 <a name="IDX887"></a>
jpayne@68	3280 </dt>
jpayne@68	3281 <dd><p>Returns a freshly constructed message. To finish initializing the
jpayne@68	3282 message, you must set the <code>msgid</code> and <code>msgstr</code>. It <em>must</em> be
jpayne@68	3283 inserted into a file to manage its memory, as there is no
jpayne@68	3284 <code>po_message_free</code> available to the user of the library.
jpayne@68	3285 </p></dd></dl>
jpayne@68	3286
jpayne@68	3287 <p>The following functions access details of a <code>po_message_t</code>. Recall
jpayne@68	3288 that the results are valid as long as the <var>file</var> handle is valid.
jpayne@68	3289 </p>
jpayne@68	3290 <dl>
jpayne@68	3291 <dt><u>Function:</u> const char * <b>po_message_msgctxt</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3292 <a name="IDX888"></a>
jpayne@68	3293 </dt>
jpayne@68	3294 <dd><p>The <code>po_message_msgctxt</code> function returns the <code>msgctxt</code>, the
jpayne@68	3295 context of <var>message</var>. Returns <code>NULL</code> for a message not restricted
jpayne@68	3296 to a context.
jpayne@68	3297 </p></dd></dl>
jpayne@68	3298
jpayne@68	3299 <dl>
jpayne@68	3300 <dt><u>Function:</u> void <b>po_message_set_msgctxt</b><i> (po_message_t <var>message</var>, const char *<var>msgctxt</var>)</i>
jpayne@68	3301 <a name="IDX889"></a>
jpayne@68	3302 </dt>
jpayne@68	3303 <dd><p>The <code>po_message_set_msgctxt</code> function changes the <code>msgctxt</code>,
jpayne@68	3304 the context of the message, to the value provided through
jpayne@68	3305 <var>msgctxt</var>. The value <code>NULL</code> removes the restriction.
jpayne@68	3306 </p></dd></dl>
jpayne@68	3307
jpayne@68	3308 <dl>
jpayne@68	3309 <dt><u>Function:</u> const char * <b>po_message_msgid</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3310 <a name="IDX890"></a>
jpayne@68	3311 </dt>
jpayne@68	3312 <dd><p>The <code>po_message_msgid</code> function returns the <code>msgid</code> (untranslated
jpayne@68	3313 English string) of <var>message</var>. This is guaranteed to be non-<code>NULL</code>.
jpayne@68	3314 </p></dd></dl>
jpayne@68	3315
jpayne@68	3316 <dl>
jpayne@68	3317 <dt><u>Function:</u> void <b>po_message_set_msgid</b><i> (po_message_t <var>message</var>, const char *<var>msgid</var>)</i>
jpayne@68	3318 <a name="IDX891"></a>
jpayne@68	3319 </dt>
jpayne@68	3320 <dd><p>The <code>po_message_set_msgid</code> function changes the <code>msgid</code>
jpayne@68	3321 (untranslated English string) of <var>message</var> to the value provided through
jpayne@68	3322 <var>msgid</var>, a non-<code>NULL</code> string.
jpayne@68	3323 </p></dd></dl>
jpayne@68	3324
jpayne@68	3325 <dl>
jpayne@68	3326 <dt><u>Function:</u> const char * <b>po_message_msgid_plural</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3327 <a name="IDX892"></a>
jpayne@68	3328 </dt>
jpayne@68	3329 <dd><p>The <code>po_message_msgid_plural</code> function returns the <code>msgid_plural</code>
jpayne@68	3330 (untranslated English plural string) of <var>message</var>, a message with plurals,
jpayne@68	3331 or <code>NULL</code> for a message without plural.
jpayne@68	3332 </p></dd></dl>
jpayne@68	3333
jpayne@68	3334 <dl>
jpayne@68	3335 <dt><u>Function:</u> void <b>po_message_set_msgid_plural</b><i> (po_message_t <var>message</var>, const char *<var>msgid_plural</var>)</i>
jpayne@68	3336 <a name="IDX893"></a>
jpayne@68	3337 </dt>
jpayne@68	3338 <dd><p>The <code>po_message_set_msgid_plural</code> function changes the
jpayne@68	3339 <code>msgid_plural</code> (untranslated English plural string) of a message to
jpayne@68	3340 the value provided through <var>msgid_plural</var>, or removes the plurals if
jpayne@68	3341 <code>NULL</code> is provided as <var>msgid_plural</var>.
jpayne@68	3342 </p></dd></dl>
jpayne@68	3343
jpayne@68	3344 <dl>
jpayne@68	3345 <dt><u>Function:</u> const char * <b>po_message_msgstr</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3346 <a name="IDX894"></a>
jpayne@68	3347 </dt>
jpayne@68	3348 <dd><p>The <code>po_message_msgstr</code> function returns the <code>msgstr</code> (translation)
jpayne@68	3349 of <var>message</var>. For an untranslated message, the return value is an empty
jpayne@68	3350 string.
jpayne@68	3351 </p></dd></dl>
jpayne@68	3352
jpayne@68	3353 <dl>
jpayne@68	3354 <dt><u>Function:</u> void <b>po_message_set_msgstr</b><i> (po_message_t <var>message</var>, const char *<var>msgstr</var>)</i>
jpayne@68	3355 <a name="IDX895"></a>
jpayne@68	3356 </dt>
jpayne@68	3357 <dd><p>The <code>po_message_set_msgstr</code> function changes the <code>msgstr</code>
jpayne@68	3358 (translation) of <var>message</var> to the value provided through <var>msgstr</var>, a
jpayne@68	3359 non-<code>NULL</code> string.
jpayne@68	3360 </p></dd></dl>
jpayne@68	3361
jpayne@68	3362 <dl>
jpayne@68	3363 <dt><u>Function:</u> const char * <b>po_message_msgstr_plural</b><i> (po_message_t <var>message</var>, int <var>index</var>)</i>
jpayne@68	3364 <a name="IDX896"></a>
jpayne@68	3365 </dt>
jpayne@68	3366 <dd><p>The <code>po_message_msgstr_plural</code> function returns the
jpayne@68	3367 <code>msgstr[<var>index</var>]</code> of <var>message</var>, a message with plurals, or
jpayne@68	3368 <code>NULL</code> when the <var>index</var> is out of range or for a message without
jpayne@68	3369 plural.
jpayne@68	3370 </p></dd></dl>
jpayne@68	3371
jpayne@68	3372 <dl>
jpayne@68	3373 <dt><u>Function:</u> void <b>po_message_set_msgstr_plural</b><i> (po_message_t <var>message</var>, int <var>index</var>, const char *<var>msgstr_plural</var>)</i>
jpayne@68	3374 <a name="IDX897"></a>
jpayne@68	3375 </dt>
jpayne@68	3376 <dd><p>The <code>po_message_set_msgstr_plural</code> function changes the
jpayne@68	3377 <code>msgstr[<var>index</var>]</code> of <var>message</var>, a message with plurals, to
jpayne@68	3378 the value provided through <var>msgstr_plural</var>. <var>message</var> must be a
jpayne@68	3379 message with plurals.
jpayne@68	3380 Use <code>NULL</code> as the value of <var>msgstr_plural</var> with
jpayne@68	3381 <var>index</var> pointing to the last element to reduce the number of plural
jpayne@68	3382 forms.
jpayne@68	3383 </p></dd></dl>
jpayne@68	3384
jpayne@68	3385 <dl>
jpayne@68	3386 <dt><u>Function:</u> const char * <b>po_message_comments</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3387 <a name="IDX898"></a>
jpayne@68	3388 </dt>
jpayne@68	3389 <dd><p>The <code>po_message_comments</code> function returns the comments of <var>message</var>,
jpayne@68	3390 a multiline string, ending in a newline, or a non-<code>NULL</code> empty string.
jpayne@68	3391 </p></dd></dl>
jpayne@68	3392
jpayne@68	3393 <dl>
jpayne@68	3394 <dt><u>Function:</u> void <b>po_message_set_comments</b><i> (po_message_t <var>message</var>, const char *<var>comments</var>)</i>
jpayne@68	3395 <a name="IDX899"></a>
jpayne@68	3396 </dt>
jpayne@68	3397 <dd><p>The <code>po_message_set_comments</code> function changes the comments of
jpayne@68	3398 <var>message</var> to the value <var>comments</var>, a multiline string, ending in a
jpayne@68	3399 newline, or a non-<code>NULL</code> empty string.
jpayne@68	3400 </p></dd></dl>
jpayne@68	3401
jpayne@68	3402 <dl>
jpayne@68	3403 <dt><u>Function:</u> const char * <b>po_message_extracted_comments</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3404 <a name="IDX900"></a>
jpayne@68	3405 </dt>
jpayne@68	3406 <dd><p>The <code>po_message_extracted_comments</code> function returns the extracted
jpayne@68	3407 comments of <var>message</var>, a multiline string, ending in a newline, or a
jpayne@68	3408 non-<code>NULL</code> empty string.
jpayne@68	3409 </p></dd></dl>
jpayne@68	3410
jpayne@68	3411 <dl>
jpayne@68	3412 <dt><u>Function:</u> void <b>po_message_set_extracted_comments</b><i> (po_message_t <var>message</var>, const char *<var>extracted_comments</var>)</i>
jpayne@68	3413 <a name="IDX901"></a>
jpayne@68	3414 </dt>
jpayne@68	3415 <dd><p>The <code>po_message_set_extracted_comments</code> function changes the
jpayne@68	3416 comments of <var>message</var> to the value <var>extracted_comments</var>, a multiline
jpayne@68	3417 string, ending in a newline, or a non-<code>NULL</code> empty string.
jpayne@68	3418 </p></dd></dl>
jpayne@68	3419
jpayne@68	3420 <dl>
jpayne@68	3421 <dt><u>Function:</u> const char * <b>po_message_prev_msgctxt</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3422 <a name="IDX902"></a>
jpayne@68	3423 </dt>
jpayne@68	3424 <dd><p>The <code>po_message_prev_msgctxt</code> function returns the previous
jpayne@68	3425 <code>msgctxt</code>, the previous context of <var>message</var>. Return
jpayne@68	3426 <code>NULL</code> for a message that does not have a previous context.
jpayne@68	3427 </p></dd></dl>
jpayne@68	3428
jpayne@68	3429 <dl>
jpayne@68	3430 <dt><u>Function:</u> void <b>po_message_set_prev_msgctxt</b><i> (po_message_t <var>message</var>, const char *<var>prev_msgctxt</var>)</i>
jpayne@68	3431 <a name="IDX903"></a>
jpayne@68	3432 </dt>
jpayne@68	3433 <dd><p>The <code>po_message_set_prev_msgctxt</code> function changes the previous
jpayne@68	3434 <code>msgctxt</code>, the context of the message, to the value provided
jpayne@68	3435 through <var>prev_msgctxt</var>. The value <code>NULL</code> removes the stored
jpayne@68	3436 previous msgctxt.
jpayne@68	3437 </p></dd></dl>
jpayne@68	3438
jpayne@68	3439 <dl>
jpayne@68	3440 <dt><u>Function:</u> const char * <b>po_message_prev_msgid</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3441 <a name="IDX904"></a>
jpayne@68	3442 </dt>
jpayne@68	3443 <dd><p>The <code>po_message_prev_msgid</code> function returns the previous
jpayne@68	3444 <code>msgid</code> (untranslated English string) of <var>message</var>, or
jpayne@68	3445 <code>NULL</code> if there is no previous <code>msgid</code> stored.
jpayne@68	3446 </p></dd></dl>
jpayne@68	3447
jpayne@68	3448 <dl>
jpayne@68	3449 <dt><u>Function:</u> void <b>po_message_set_prev_msgid</b><i> (po_message_t <var>message</var>, const char *<var>prev_msgid</var>)</i>
jpayne@68	3450 <a name="IDX905"></a>
jpayne@68	3451 </dt>
jpayne@68	3452 <dd><p>The <code>po_message_set_prev_msgid</code> function changes the previous
jpayne@68	3453 <code>msgid</code> (untranslated English string) of <var>message</var> to the value
jpayne@68	3454 provided through <var>prev_msgid</var>, or removes the message when it is
jpayne@68	3455 <code>NULL</code>.
jpayne@68	3456 </p></dd></dl>
jpayne@68	3457
jpayne@68	3458 <dl>
jpayne@68	3459 <dt><u>Function:</u> const char * <b>po_message_prev_msgid_plural</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3460 <a name="IDX906"></a>
jpayne@68	3461 </dt>
jpayne@68	3462 <dd><p>The <code>po_message_prev_msgid_plural</code> function returns the previous
jpayne@68	3463 <code>msgid_plural</code> (untranslated English plural string) of
jpayne@68	3464 <var>message</var>, a message with plurals, or <code>NULL</code> for a message
jpayne@68	3465 without plural without any stored previous <code>msgid_plural</code>.
jpayne@68	3466 </p></dd></dl>
jpayne@68	3467
jpayne@68	3468 <dl>
jpayne@68	3469 <dt><u>Function:</u> void <b>po_message_set_prev_msgid_plural</b><i> (po_message_t <var>message</var>, const char *<var>prev_msgid_plural</var>)</i>
jpayne@68	3470 <a name="IDX907"></a>
jpayne@68	3471 </dt>
jpayne@68	3472 <dd><p>The <code>po_message_set_prev_msgid_plural</code> function changes the
jpayne@68	3473 previous <code>msgid_plural</code> (untranslated English plural string) of a
jpayne@68	3474 message to the value provided through <var>prev_msgid_plural</var>, or
jpayne@68	3475 removes the stored previous <code>msgid_plural</code> if <code>NULL</code> is
jpayne@68	3476 provided as <var>prev_msgid_plural</var>.
jpayne@68	3477 </p></dd></dl>
jpayne@68	3478
jpayne@68	3479 <dl>
jpayne@68	3480 <dt><u>Function:</u> int <b>po_message_is_obsolete</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3481 <a name="IDX908"></a>
jpayne@68	3482 </dt>
jpayne@68	3483 <dd><p>The <code>po_message_is_obsolete</code> function returns true when <var>message</var>
jpayne@68	3484 is marked as obsolete.
jpayne@68	3485 </p></dd></dl>
jpayne@68	3486
jpayne@68	3487 <dl>
jpayne@68	3488 <dt><u>Function:</u> void <b>po_message_set_obsolete</b><i> (po_message_t <var>message</var>, int <var>obsolete</var>)</i>
jpayne@68	3489 <a name="IDX909"></a>
jpayne@68	3490 </dt>
jpayne@68	3491 <dd><p>The <code>po_message_set_obsolete</code> function changes the obsolete mark of
jpayne@68	3492 <var>message</var>.
jpayne@68	3493 </p></dd></dl>
jpayne@68	3494
jpayne@68	3495 <dl>
jpayne@68	3496 <dt><u>Function:</u> int <b>po_message_is_fuzzy</b><i> (po_message_t <var>message</var>)</i>
jpayne@68	3497 <a name="IDX910"></a>
jpayne@68	3498 </dt>
jpayne@68	3499 <dd><p>The <code>po_message_is_fuzzy</code> function returns true when <var>message</var>
jpayne@68	3500 is marked as fuzzy.
jpayne@68	3501 </p></dd></dl>
jpayne@68	3502
jpayne@68	3503 <dl>
jpayne@68	3504 <dt><u>Function:</u> void <b>po_message_set_fuzzy</b><i> (po_message_t <var>message</var>, int <var>fuzzy</var>)</i>
jpayne@68	3505 <a name="IDX911"></a>
jpayne@68	3506 </dt>
jpayne@68	3507 <dd><p>The <code>po_message_set_fuzzy</code> function changes the fuzzy mark of
jpayne@68	3508 <var>message</var>.
jpayne@68	3509 </p></dd></dl>
jpayne@68	3510
jpayne@68	3511 <dl>
jpayne@68	3512 <dt><u>Function:</u> int <b>po_message_is_format</b><i> (po_message_t <var>message</var>, const char *<var>format_type</var>)</i>
jpayne@68	3513 <a name="IDX912"></a>
jpayne@68	3514 </dt>
jpayne@68	3515 <dd><p>The <code>po_message_is_format</code> function returns true when the message
jpayne@68	3516 is marked as being a format string of <var>format_type</var>.
jpayne@68	3517 </p></dd></dl>
jpayne@68	3518
jpayne@68	3519 <dl>
jpayne@68	3520 <dt><u>Function:</u> void <b>po_message_set_format</b><i> (po_message_t <var>message</var>, const char *<var>format_type</var>, int <var>value</var>)</i>
jpayne@68	3521 <a name="IDX913"></a>
jpayne@68	3522 </dt>
jpayne@68	3523 <dd><p>The <code>po_message_set_fuzzy</code> function changes the format mark of
jpayne@68	3524 the message for the <var>format_type</var> provided.
jpayne@68	3525 </p></dd></dl>
jpayne@68	3526
jpayne@68	3527 <dl>
jpayne@68	3528 <dt><u>Function:</u> int <b>po_message_is_range</b><i> (po_message_t <var>message</var>, int <var>minp</var>, int <var>maxp</var>)</i>
jpayne@68	3529 <a name="IDX914"></a>
jpayne@68	3530 </dt>
jpayne@68	3531 <dd><p>The <code>po_message_is_range</code> function returns true when the message
jpayne@68	3532 has a numeric range set, and stores the minimum and maximum value in the
jpayne@68	3533 locations pointed by <var>minp</var> and <var>maxp</var> respectively.
jpayne@68	3534 </p></dd></dl>
jpayne@68	3535
jpayne@68	3536 <dl>
jpayne@68	3537 <dt><u>Function:</u> void <b>po_message_set_range</b><i> (po_message_t <var>message</var>, int <var>min</var>, int <var>max</var>)</i>
jpayne@68	3538 <a name="IDX915"></a>
jpayne@68	3539 </dt>
jpayne@68	3540 <dd><p>The <code>po_message_set_range</code> function changes the numeric range of
jpayne@68	3541 the message. <var>min</var> and <var>max</var> must be non-negative, with
jpayne@68	3542 <var>min</var> < <var>max</var>. Use <var>min</var> and <var>max</var> with value <code>-1</code>
jpayne@68	3543 to remove the numeric range of <var>message</var>.
jpayne@68	3544 </p></dd></dl>
jpayne@68	3545
jpayne@68	3546
jpayne@68	3547 <a name="PO-Header-Entry-API"></a>
jpayne@68	3548 <a name="SEC169"></a>
jpayne@68	3549 <h3 class="subsection"> <a href="gettext_toc.html#TOC162">9.13.5 PO Header Entry API</a> </h3>
jpayne@68	3550
jpayne@68	3551 <p>The following functions provide an interface to extract and manipulate
jpayne@68	3552 the header entry (see section <a href="gettext_6.html#SEC52">Filling in the Header Entry</a>) from a file loaded in memory.
jpayne@68	3553 The meta information must be written back into the domain message with
jpayne@68	3554 the empty string as <code>msgid</code>.
jpayne@68	3555 </p>
jpayne@68	3556 <dl>
jpayne@68	3557 <dt><u>Function:</u> const char * <b>po_file_domain_header</b><i> (po_file_t <var>file</var>, const char *<var>domain</var>)</i>
jpayne@68	3558 <a name="IDX916"></a>
jpayne@68	3559 </dt>
jpayne@68	3560 <dd><p>Returns the header entry of a domain from <var>file</var>, a PO file loaded in
jpayne@68	3561 memory. The value <code>NULL</code> provided as <var>domain</var> denotes the
jpayne@68	3562 default domain. Returns <code>NULL</code> if there is no header entry.
jpayne@68	3563 </p></dd></dl>
jpayne@68	3564
jpayne@68	3565 <dl>
jpayne@68	3566 <dt><u>Function:</u> char * <b>po_header_field</b><i> (const char <var>header</var>, const char <var>field</var>)</i>
jpayne@68	3567 <a name="IDX917"></a>
jpayne@68	3568 </dt>
jpayne@68	3569 <dd><p>Returns the value of <var>field</var> in the <var>header</var> entry. The return
jpayne@68	3570 value is either a freshly allocated string, to be freed by the caller,
jpayne@68	3571 or <code>NULL</code>.
jpayne@68	3572 </p></dd></dl>
jpayne@68	3573
jpayne@68	3574 <dl>
jpayne@68	3575 <dt><u>Function:</u> char * <b>po_header_set_field</b><i> (const char <var>header</var>, const char <var>field</var>, const char *<var>value</var>)</i>
jpayne@68	3576 <a name="IDX918"></a>
jpayne@68	3577 </dt>
jpayne@68	3578 <dd><p>Returns a freshly allocated string which contains the entry from
jpayne@68	3579 <var>header</var> with <var>field</var> set to <var>value</var>. The field is added if
jpayne@68	3580 necessary.
jpayne@68	3581 </p></dd></dl>
jpayne@68	3582
jpayne@68	3583
jpayne@68	3584 <a name="po_005ffilepos_005ft-API"></a>
jpayne@68	3585 <a name="SEC170"></a>
jpayne@68	3586 <h3 class="subsection"> <a href="gettext_toc.html#TOC163">9.13.6 po_filepos_t API</a> </h3>
jpayne@68	3587
jpayne@68	3588 <dl>
jpayne@68	3589 <dt><u>Data Type:</u> <b>po_filepos_t</b>
jpayne@68	3590 <a name="IDX919"></a>
jpayne@68	3591 </dt>
jpayne@68	3592 <dd><p>This is a pointer type that refers to a string's position within a
jpayne@68	3593 source file.
jpayne@68	3594 </p></dd></dl>
jpayne@68	3595
jpayne@68	3596 <p>The following functions provide an interface to extract and manipulate
jpayne@68	3597 these references.
jpayne@68	3598 </p>
jpayne@68	3599 <dl>
jpayne@68	3600 <dt><u>Function:</u> po_filepos_t <b>po_message_filepos</b><i> (po_message_t <var>message</var>, int <var>index</var>)</i>
jpayne@68	3601 <a name="IDX920"></a>
jpayne@68	3602 </dt>
jpayne@68	3603 <dd><p>Returns the file reference in position <var>index</var> from the message. If
jpayne@68	3604 <var>index</var> is out of range, returns <code>NULL</code>.
jpayne@68	3605 </p></dd></dl>
jpayne@68	3606
jpayne@68	3607 <dl>
jpayne@68	3608 <dt><u>Function:</u> void <b>po_message_remove_filepos</b><i> (po_message_t <var>message</var>, int <var>index</var>)</i>
jpayne@68	3609 <a name="IDX921"></a>
jpayne@68	3610 </dt>
jpayne@68	3611 <dd><p>Removes the file reference in position <var>index</var> from the message. It
jpayne@68	3612 moves all references following <var>index</var> one position backwards.
jpayne@68	3613 </p></dd></dl>
jpayne@68	3614
jpayne@68	3615 <dl>
jpayne@68	3616 <dt><u>Function:</u> void <b>po_message_add_filepos</b><i> (po_message_t <var>message</var>, const char *<var>file</var>, size_t <var>start_line</var>)</i>
jpayne@68	3617 <a name="IDX922"></a>
jpayne@68	3618 </dt>
jpayne@68	3619 <dd><p>Adds a reference to the string from <var>file</var> starting at
jpayne@68	3620 <var>start_line</var>, if it is not already present for the message. The
jpayne@68	3621 value <code>(size_t)(-1)</code> for <var>start_line</var> denotes that the line
jpayne@68	3622 number is not available.
jpayne@68	3623 </p></dd></dl>
jpayne@68	3624
jpayne@68	3625
jpayne@68	3626 <a name="Format-Type-API"></a>
jpayne@68	3627 <a name="SEC171"></a>
jpayne@68	3628 <h3 class="subsection"> <a href="gettext_toc.html#TOC164">9.13.7 Format Type API</a> </h3>
jpayne@68	3629
jpayne@68	3630 <dl>
jpayne@68	3631 <dt><u>Function:</u> const char * const * <b>po_format_list</b><i> (void)</i>
jpayne@68	3632 <a name="IDX923"></a>
jpayne@68	3633 </dt>
jpayne@68	3634 <dd><p>Returns a <code>NULL</code> terminated array of the supported format types.
jpayne@68	3635 </p></dd></dl>
jpayne@68	3636
jpayne@68	3637 <dl>
jpayne@68	3638 <dt><u>Function:</u> const char * <b>po_format_pretty_name</b><i> (const char *<var>format_type</var>)</i>
jpayne@68	3639 <a name="IDX924"></a>
jpayne@68	3640 </dt>
jpayne@68	3641 <dd><p>Returns the pretty name associated with <var>format_type</var>. For example,
jpayne@68	3642 it returns “C#” when <var>format_type</var> is “csharp_format”.
jpayne@68	3643 Return <code>NULL</code> if <var>format_type</var> is not a supported format type.
jpayne@68	3644 </p></dd></dl>
jpayne@68	3645
jpayne@68	3646
jpayne@68	3647 <a name="Checking-API"></a>
jpayne@68	3648 <a name="SEC172"></a>
jpayne@68	3649 <h3 class="subsection"> <a href="gettext_toc.html#TOC165">9.13.8 Checking API</a> </h3>
jpayne@68	3650
jpayne@68	3651 <dl>
jpayne@68	3652 <dt><u>Function:</u> void <b>po_file_check_all</b><i> (po_file_t <var>file</var>, po_xerror_handler_t <var>handler</var>)</i>
jpayne@68	3653 <a name="IDX925"></a>
jpayne@68	3654 </dt>
jpayne@68	3655 <dd><p>Tests whether the entire <var>file</var> is valid, like <code>msgfmt</code> does it. If it
jpayne@68	3656 is invalid, passes the reasons to <var>handler</var>.
jpayne@68	3657 </p></dd></dl>
jpayne@68	3658
jpayne@68	3659 <dl>
jpayne@68	3660 <dt><u>Function:</u> void <b>po_message_check_all</b><i> (po_message_t <var>message</var>, po_message_iterator_t <var>iterator</var>, po_xerror_handler_t <var>handler</var>)</i>
jpayne@68	3661 <a name="IDX926"></a>
jpayne@68	3662 </dt>
jpayne@68	3663 <dd><p>Tests <var>message</var>, to be inserted at <var>iterator</var> in a PO file in memory,
jpayne@68	3664 like <code>msgfmt</code> does it. If it is invalid, passes the reasons to
jpayne@68	3665 <var>handler</var>. <var>iterator</var> is not modified by this call; it only
jpayne@68	3666 specifies the file and the domain.
jpayne@68	3667 </p></dd></dl>
jpayne@68	3668
jpayne@68	3669 <dl>
jpayne@68	3670 <dt><u>Function:</u> void <b>po_message_check_format</b><i> (po_message_t <var>message</var>, po_xerror_handler_t <var>handler</var>)</i>
jpayne@68	3671 <a name="IDX927"></a>
jpayne@68	3672 </dt>
jpayne@68	3673 <dd><p>Tests whether the message translation from <var>message</var> is a valid
jpayne@68	3674 format string if the message is marked as being a format string. If it
jpayne@68	3675 is invalid, passes the reasons to <var>handler</var>.
jpayne@68	3676 </p>
jpayne@68	3677 <p>This function is exported as ‘<samp>po_message_check_format_v2</samp>’ at ABI
jpayne@68	3678 level, but is defined as <code>po_message_check_format</code> in C code after
jpayne@68	3679 the inclusion of ‘<samp><gettext-po.h></samp>’.
jpayne@68	3680 </p></dd></dl>
jpayne@68	3681
jpayne@68	3682
jpayne@68	3683 <table cellpadding="1" cellspacing="1" border="0">
jpayne@68	3684 <tr><td valign="middle" align="left">[<a href="#SEC87" title="Beginning of this chapter or previous chapter"> << </a>]</td>
jpayne@68	3685 <td valign="middle" align="left">[<a href="gettext_10.html#SEC173" title="Next chapter"> >> </a>]</td>
jpayne@68	3686 <td valign="middle" align="left">   </td>
jpayne@68	3687 <td valign="middle" align="left">   </td>
jpayne@68	3688 <td valign="middle" align="left">   </td>
jpayne@68	3689 <td valign="middle" align="left">   </td>
jpayne@68	3690 <td valign="middle" align="left">   </td>
jpayne@68	3691 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
jpayne@68	3692 <td valign="middle" align="left">[<a href="gettext_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
jpayne@68	3693 <td valign="middle" align="left">[<a href="gettext_21.html#SEC389" title="Index">Index</a>]</td>
jpayne@68	3694 <td valign="middle" align="left">[<a href="gettext_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
jpayne@68	3695 </tr></table>
jpayne@68	3696 <p>
jpayne@68	3697 <font size="-1">
jpayne@68	3698 This document was generated by <em>Bruno Haible</em> on <em>February, 21 2024</em> using <a href="https://www.nongnu.org/texi2html/"><em>texi2html 1.78a</em></a>.
jpayne@68	3699 </font>
jpayne@68	3700 <br>
jpayne@68	3701
jpayne@68	3702 </p>
jpayne@68	3703 </body>
jpayne@68	3704 </html>

Mercurial > repos > rliterman > csp2

annotate CSP2/CSP2_env/env-d9b9114564458d9d-741b3de822f2aaca6c6caa4325c4afce/share/doc/gettext/gettext_9.html @ 68:5028fdace37b