usr/src/man/man1/xgettext.1

   1 '\" te
   2 .\"  Copyright (c) 1999, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH XGETTEXT 1 "Mar 23, 1999"
   7 .SH NAME
   8 xgettext \- extract gettext call strings from C programs
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBxgettext\fR [\fB-ns\fR] [\fB-a\fR [\fB-x\fR \fIexclude-file\fR]] [\fB-c\fR \fIcomment-tag\fR]
  13      [\fB-d\fR \fIdefault-domain\fR] [\fB-j\fR] [\fB-m\fR \fIprefix\fR] [\fB-M\fR \fIsuffix\fR]
  14      [\fB-p\fR \fIpathname\fR] \fB-|\fR \fIfilename\fR...
  15 .fi
  16
  17 .LP
  18 .nf
  19 \fBxgettext\fR \fB-h\fR
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .sp
  24 .LP
  25 The \fBxgettext\fR utility is used to automate the creation of portable message
  26 files (\fB\&.po\fR). A \fB\&.po\fR file contains copies of "C" strings that are
  27 found in  ANSI C source code in \fIfilename\fR or the standard input if
  28 `\fB\(mi\fR\&' is specified on the command line. The  \fB\&.po\fR file can be
  29 used as input to the  \fBmsgfmt\fR(1) utility, which produces a binary form of
  30 the message file that can be  used by application during run-time.
  31 .sp
  32 .LP
  33 \fBxgettext\fR writes \fImsgid\fR strings from \fBgettext\fR(3C) calls in
  34 \fIfilename\fR to the default output file \fBmessages.po\fR. The default output
  35 file name can be changed by  \fB-d\fR option. \fImsgid\fR strings in
  36 \fBdgettext()\fR calls are written to the output file
  37 \fBdomainname\fR\fB\&.po\fR where \fBdomainname\fR is the first parameter to
  38 the \fBdgettext()\fR call.
  39 .sp
  40 .LP
  41 By default, \fBxgettext\fR creates a  \fB\&.po\fR file in the current working
  42 directory, and each entry is in the same order that the strings are extracted
  43 from \fIfilenames\fR. When the \fB-p\fR option is specified, the  \fB\&.po\fR
  44 file is created in the  \fIpathname\fR directory. An existing \fB\&.po\fR file
  45 is overwritten.
  46 .sp
  47 .LP
  48 Duplicate  \fImsgid\fRs are written to the  \fB\&.po\fR file as comment lines.
  49 When the  \fB-s\fR option is specified, the  \fB\&.po\fR is sorted by the
  50 \fImsgid\fR string, and all duplicated \fImsgid\fRs are removed. All
  51 \fImsgstr\fR directives in the \fB\&.po\fR file are empty unless the \fB-m\fR
  52 option is used.
  53 .SH OPTIONS
  54 .sp
  55 .LP
  56 The following options are supported:
  57 .sp
  58 .ne 2
  59 .na
  60 \fB\fB-n\fR\fR
  61 .ad
  62 .RS 21n
  63 Add comment lines to the output file indicating file name and line number in
  64 the source file where each extracted string is encountered. These lines appear
  65 before each \fImsgid\fR in the following format:
  66 .sp
  67 .in +2
  68 .nf
  69 # # File: \fIfilename\fR, line: \fIline-number\fR
  70 .fi
  71 .in -2
  72 .sp
  73
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fB-s\fR\fR
  80 .ad
  81 .RS 21n
  82 Generate output sorted by  \fImsgid\fRs with all duplicate  \fImsgid\fRs
  83 removed.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fB-a\fR\fR
  90 .ad
  91 .RS 21n
  92 Extract all strings, not just those found in \fBgettext\fR(3C), and
  93 \fBdgettext()\fR () calls. Only one  \fB\&.po\fR file is created.
  94 .RE
  95
  96 .sp
  97 .ne 2
  98 .na
  99 \fB\fB-c\fR \fIcomment-tag\fR\fR
 100 .ad
 101 .RS 21n
 102 The comment block beginning with \fIcomment-tag\fR as the first token of the
 103 comment block is added to the output \fB\&.po\fR file as  \fI#\fR delimited
 104 comments. For multiple domains, \fBxgettext\fR directs comments and messages to
 105 the prevailing text domain.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fB-d\fR \fIdefault-domain\fR\fR
 112 .ad
 113 .RS 21n
 114 Rename default output file from \fBmessages.po\fR to \fIdefault-domain\fR
 115 \fB\&.po\fR.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fB-j\fR\fR
 122 .ad
 123 .RS 21n
 124 Join messages with existing message files.  If a \fB\&.po\fR file does not
 125 exist, it is created.  If a \fB\&.po\fR file does exist, new messages are
 126 appended.  Any duplicate \fBmsgid\fRs are commented out in the resulting
 127 \fB\&.po\fR file.  Domain directives in the existing \fB\&.po\fR file are
 128 ignored. Results not guaranteed if the existing message file has been edited.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fB-m\fR \fIprefix\fR\fR
 135 .ad
 136 .RS 21n
 137 Fill in the \fImsgstr\fR with  \fIprefix\fR. This is useful for debugging
 138 purposes. To make \fImsgstr\fR identical to \fImsgid\fR, use an empty string
 139 (\fB""\fR) for \fIprefix\fR.
 140 .RE
 141
 142 .sp
 143 .ne 2
 144 .na
 145 \fB\fB-M\fR \fIsuffix\fR\fR
 146 .ad
 147 .RS 21n
 148 Fill in the \fImsgstr\fR with  \fIsuffix\fR. This is useful for debugging
 149 purposes.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fB-p\fR \fIpathname\fR\fR
 156 .ad
 157 .RS 21n
 158 Specify the directory where the output files will be placed. This option
 159 overrides the current working directory.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fB-x\fR \fIexclude-file\fR\fR
 166 .ad
 167 .RS 21n
 168 Specify a  \fB\&.po\fR file that contains a list of \fImsgid\fRs that are not
 169 to be extracted from the input files. The format of \fIexclude-file\fR is
 170 identical to the \fB\&.po\fR file. However, only the \fImsgid\fR directive line
 171 in \fIexclude-file\fR is used. All other lines are simply ignored.  The
 172 \fB-x\fR option can only be used with the \fB-a\fR option.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fB-h\fR\fR
 179 .ad
 180 .RS 21n
 181 Print a help message on the standard output.
 182 .RE
 183
 184 .SH SEE ALSO
 185 .sp
 186 .LP
 187 \fBmsgfmt\fR(1), \fBgettext\fR(3C), \fBattributes\fR(5)
 188 .SH NOTES
 189 .sp
 190 .LP
 191 \fBxgettext\fR is not able to extract cast strings, for example ANSI C casts of
 192 literal strings to \fB(const char *)\fR. This is unnecessary anyway, since the
 193 prototypes in \fB<libintl.h>\fR already specify this type.
 194 .sp
 195 .LP
 196 In messages and translation notes, lines greater than 2048 characters are
 197 truncated to 2048 characters and a warning message is printed to stderr.