<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1997, v.4001-->
<!ENTITY % commonents SYSTEM "smancommon.ent">
%commonents;
<!ENTITY % booktitles SYSTEM "booktitles.ent">
%booktitles;
]>
<refentry id="xgettext-1">
<!-- @(#)xgettext.1 1.6 02/02/14 SMI; -->
<refmeta><refentrytitle>xgettext</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">23 Mar 1999</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&release;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright"> Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved</refmiscinfo>
</refmeta>
<refnamediv><refname>xgettext</refname><refpurpose>extract gettext call strings from C programs</refpurpose></refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>xgettext</command><arg><option>ns</option></arg><arg><arg choice="plain"><option>a</option></arg><arg><option>x</option>&nbsp;<replaceable>exclude-file</replaceable></arg></arg><arg><option>
c</option>&nbsp;<replaceable>comment-tag</replaceable></arg><arg><option>d</option>&nbsp;<replaceable>default-domain</replaceable></arg><arg><option>j</option></arg><arg><option>m</option>&nbsp;<replaceable>
prefix</replaceable></arg><arg><option>M</option>&nbsp;<replaceable>suffix</replaceable></arg><arg><option>p</option>&nbsp;<replaceable>pathname</replaceable></arg><arg choice="plain" rep="repeat"><option>
|</option>&nbsp;<replaceable>filename</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis><command>xgettext</command><arg choice="plain"> <option>h</option></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<indexterm significance="normal"><primary sortas="xgettext">xgettext &mdash; extract gettext call strings</primary></indexterm><indexterm significance="normal">
<primary>messages</primary><secondary sortas="extract gettext call strings">extract gettext call strings &mdash; xgettext</secondary></indexterm>
<para>The <command>xgettext</command> utility is used to automate the creation of portable message files (<literal>.po</literal>). A <literal>.po</literal> file contains copies of &ldquo;C&rdquo; strings
that are found in  ANSI C source code in <replaceable>filename</replaceable> or the standard input if  `<literal>&minus;</literal>' is specified on the command line. The  <literal>.po</literal> file can
be used as input to the  <LINK LinkEnd = "msgfmt-1"><citerefentry><refentrytitle>msgfmt</refentrytitle><manvolnum>1</manvolnum></citerefentry></LINK> utility, which produces a binary form of the message file
that can be  used by application during run-time.</para>
<para><command>xgettext</command> writes <replaceable>msgid</replaceable> strings from <OLINK TargetDocEnt="REFMAN3A" LocalInfo = "gettext-3c"><citerefentry><refentrytitle>gettext</refentrytitle><manvolnum>3C</manvolnum></citerefentry></OLINK> calls in  <replaceable>filename</replaceable> to the default output file <literal>messages.po</literal>. The default output file name can be changed by  <option>d</option>
option. <replaceable>msgid</replaceable> strings in <function>dgettext</function> calls are written to the output file <command>domainname</command><literal>.po</literal> where <command>domainname</command>
is the first parameter to the <function>dgettext</function> call.</para>
<para>By default, <command>xgettext</command> creates a  <literal>.po</literal> file in the current working directory, and each entry is in the same order that the strings are extracted from <replaceable>
filenames</replaceable>. When the <option>p</option> option is specified, the  <literal>.po</literal> file is created in the  <replaceable>pathname</replaceable> directory. An existing <literal>.po</literal>
file is overwritten.</para>
<para>Duplicate  <replaceable>msgid</replaceable>s are written to the  <literal>.po</literal> file as comment lines. When the  <option>s</option> option is specified, the  <literal>.po</literal> is sorted
by the <replaceable>msgid</replaceable> string, and all duplicated <replaceable>msgid</replaceable>s are removed. All  <replaceable>msgstr</replaceable> directives in the <literal>.po</literal> file are
empty unless the <option>m</option> option is used.</para>
</refsect1>
<refsect1><title>&opts-tt;</title>
<para>The following options are supported:</para>
<variablelist termlength="medium"><varlistentry><term remap="16"><option>n</option></term><listitem><para>Add comment lines to the output file indicating file name and line number in the source file where
each extracted string is encountered. These lines appear before each <replaceable>msgid</replaceable> in the following format:<informalexample><screen># # File: <replaceable>filename</replaceable>, line: <replaceable>
line-number</replaceable> </screen>
</informalexample></para>
</listitem></varlistentry>
<varlistentry><term><option>s</option></term><listitem><para>Generate output sorted by  <replaceable>msgid</replaceable>s with all duplicate  <replaceable>msgid</replaceable>s removed.</para>
</listitem></varlistentry>
<varlistentry><term><option>a</option></term><listitem><para>Extract all strings, not just those found in <OLINK TargetDocEnt="REFMAN3A" LocalInfo = "gettext-3c"><citerefentry><refentrytitle>gettext</refentrytitle>
<manvolnum>3C</manvolnum></citerefentry></OLINK>, and <function>dgettext</function> () calls. Only one  <literal>.po</literal> file is created.</para>
</listitem></varlistentry>
<varlistentry><term><option>c</option> <replaceable>comment-tag</replaceable></term><listitem><para>The comment block beginning with <replaceable>comment-tag</replaceable> as the first token of the comment
block is added to the output <literal>.po</literal> file as  <replaceable>#</replaceable> delimited comments. For multiple domains, <command>xgettext</command> directs comments and messages to the prevailing
text domain.</para>
</listitem></varlistentry>
<varlistentry><term><option>d</option> <replaceable>default-domain</replaceable></term><listitem><para>Rename default output file from <literal>messages.po</literal> to <replaceable>default-domain</replaceable> <literal>
.po</literal>.</para>
</listitem></varlistentry>
<varlistentry><term><option>j</option></term><listitem><para>Join messages with existing message files.  If a <literal>.po</literal> file does not exist, it is created.  If a <literal>.po</literal> file
does exist, new messages are appended.  Any duplicate <literal>msgid</literal>s are commented out in the resulting <literal>.po</literal> file.  Domain directives in the existing <literal>.po</literal>
file are ignored. Results not guaranteed if the existing message file has been edited.</para>
</listitem></varlistentry>
<varlistentry><term><option>m</option> <replaceable>prefix</replaceable></term><listitem><para>Fill in the <replaceable>msgstr</replaceable> with  <replaceable>prefix</replaceable>. This is useful for debugging
purposes. To make <replaceable>msgstr</replaceable> identical to <replaceable>msgid</replaceable>, use an empty string  (<literal>""</literal>) for <replaceable>prefix</replaceable>.</para>
</listitem></varlistentry>
<varlistentry><term><option>M</option> <replaceable>suffix</replaceable></term><listitem><para>Fill in the <replaceable>msgstr</replaceable> with  <replaceable>suffix</replaceable>. This is useful for debugging
purposes.</para>
</listitem></varlistentry>
<varlistentry><term><option>p</option> <replaceable>pathname</replaceable></term><listitem><para>Specify the directory where the output files will be placed. This option overrides the current working directory.
</para>
</listitem></varlistentry>
<varlistentry><term><option>x</option> <replaceable>exclude-file</replaceable></term><listitem><para>Specify a  <literal>.po</literal> file that contains a list of <replaceable>msgid</replaceable>s that
are not to be extracted from the input files. The format of <replaceable>exclude-file</replaceable> is identical to the <literal>.po</literal> file. However, only the <replaceable>msgid</replaceable> directive
line in <replaceable>exclude-file</replaceable> is used. All other lines are simply ignored.  The <option>x</option> option can only be used with the <option>a</option> option.</para>
</listitem></varlistentry>
<varlistentry><term><option>h</option></term><listitem><para>Print a help message on the standard output.</para>
</listitem></varlistentry>
</variablelist>
</refsect1>
<refsect1><title>&attr-tt;</title>
<para>See <OLINK TargetDocEnt="REFMAN5" LocalInfo = "attributes-5"><citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum></citerefentry></OLINK> for descriptions of the following
attributes:</para>
<informaltable frame="all" orient="port"><tgroup cols="2" colsep="1" rowsep="1"><colspec colnum="1" colname="col1" colwidth="1*" colsep="1" align="left"><colspec colnum="2" colname="col2" colwidth="1*"
align="left"><thead><row><entry rowsep="1" align="center">ATTRIBUTE TYPE</entry><entry rowsep="1" align="center">ATTRIBUTE VALUE</entry></row></thead><tbody><row><entry>Availability</entry><entry>SUNWloc
</entry></row></tbody></tgroup></informaltable>
</refsect1>
<refsect1><title>&also-tt;</title>
<para><LINK LinkEnd = "msgfmt-1"><citerefentry><refentrytitle>msgfmt</refentrytitle><manvolnum>1</manvolnum></citerefentry></LINK>, <OLINK TargetDocEnt="REFMAN3A" LocalInfo = "gettext-3c"><citerefentry><refentrytitle>
gettext</refentrytitle><manvolnum>3C</manvolnum></citerefentry></OLINK>, <OLINK TargetDocEnt="REFMAN5" LocalInfo = "attributes-5"><citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>5</manvolnum>
</citerefentry></OLINK></para>
</refsect1>
<refsect1><title>&note-tt;</title>
<para><command>xgettext</command> is not able to extract cast strings, for example ANSI C casts of literal strings to <literal>(const char *)</literal>. This is unnecessary anyway, since the prototypes
in <literal>&lt;libintl.h></literal> already specify this type.</para>
<para>In messages and translation notes, lines greater than 2048 characters are truncated to 2048 characters and a warning message is printed to stderr.</para>
</refsect1>
</refentry>
<!--end of file-->
