gettext-tools/doc/msggrep.texi

   1 @pindex msggrep
   2 @cindex @code{msggrep} program, usage
   3 @example
   4 msggrep [@var{option}] [@var{inputfile}]
   5 @end example
   6
   7 @cindex search messages in a catalog
   8 The @code{msggrep} program extracts all messages of a translation catalog
   9 that match a given pattern or belong to some given source files.
  10
  11 @subsection Input file location
  12
  13 @table @samp
  14 @item @var{inputfile}
  15 Input PO file.
  16
  17 @item -D @var{directory}
  18 @itemx --directory=@var{directory}
  19 @opindex -D@r{, @code{msggrep} option}
  20 @opindex --directory@r{, @code{msggrep} option}
  21 Add @var{directory} to the list of directories.  Source files are
  22 searched relative to this list of directories.  The resulting @file{.po}
  23 file will be written relative to the current directory, though.
  24
  25 @end table
  26
  27 If no @var{inputfile} is given or if it is @samp{-}, standard input is read.
  28
  29 @subsection Output file location
  30
  31 @table @samp
  32 @item -o @var{file}
  33 @itemx --output-file=@var{file}
  34 @opindex -o@r{, @code{msggrep} option}
  35 @opindex --output-file@r{, @code{msggrep} option}
  36 Write output to specified file.
  37
  38 @end table
  39
  40 The results are written to standard output if no output file is specified
  41 or if it is @samp{-}.
  42
  43 @subsection Message selection
  44
  45 @example
  46   [-N @var{sourcefile}]... [-M @var{domainname}]...
  47   [-J @var{msgctxt-pattern}] [-K @var{msgid-pattern}] [-T @var{msgstr-pattern}]
  48   [-C @var{comment-pattern}]
  49 @end example
  50
  51 A message is selected if
  52 @itemize @bullet
  53 @item it comes from one of the specified source files,
  54 @item or if it comes from one of the specified domains,
  55 @item or if @samp{-J} is given and its context (msgctxt) matches
  56 @var{msgctxt-pattern},
  57 @item or if @samp{-K} is given and its key (msgid or msgid_plural) matches
  58 @var{msgid-pattern},
  59 @item or if @samp{-T} is given and its translation (msgstr) matches
  60 @var{msgstr-pattern},
  61 @item or if @samp{-C} is given and the translator's comment matches
  62 @var{comment-pattern}.
  63 @end itemize
  64
  65 When more than one selection criterion is specified, the set of selected
  66 messages is the union of the selected messages of each criterion.
  67
  68 @var{msgctxt-pattern} or @var{msgid-pattern} or @var{msgstr-pattern} syntax:
  69 @example
  70   [-E | -F] [-e @var{pattern} | -f @var{file}]...
  71 @end example
  72 @var{pattern}s are basic regular expressions by default, or extended regular
  73 expressions if -E is given, or fixed strings if -F is given.
  74
  75 @table @samp
  76 @item -N @var{sourcefile}
  77 @itemx --location=@var{sourcefile}
  78 @opindex -N@r{, @code{msggrep} option}
  79 @opindex --location@r{, @code{msggrep} option}
  80 Select messages extracted from @var{sourcefile}.  @var{sourcefile} can be
  81 either a literal file name or a wildcard pattern.
  82
  83 @item -M @var{domainname}
  84 @itemx --domain=@var{domainname}
  85 @opindex -M@r{, @code{msggrep} option}
  86 @opindex --domain@r{, @code{msggrep} option}
  87 Select messages belonging to domain @var{domainname}.
  88
  89 @item -J
  90 @itemx --msgctxt
  91 @opindex -J@r{, @code{msggrep} option}
  92 @opindex --msgctxt@r{, @code{msggrep} option}
  93 Start of patterns for the msgctxt.
  94
  95 @item -K
  96 @itemx --msgid
  97 @opindex -K@r{, @code{msggrep} option}
  98 @opindex --msgid@r{, @code{msggrep} option}
  99 Start of patterns for the msgid.
 100
 101 @item -T
 102 @itemx --msgstr
 103 @opindex -T@r{, @code{msggrep} option}
 104 @opindex --msgstr@r{, @code{msggrep} option}
 105 Start of patterns for the msgstr.
 106
 107 @item -C
 108 @itemx --comment
 109 @opindex -C@r{, @code{msggrep} option}
 110 @opindex --comment@r{, @code{msggrep} option}
 111 Start of patterns for the translator's comment.
 112
 113 @item -X
 114 @itemx --extracted-comment
 115 @opindex -X@r{, @code{msggrep} option}
 116 @opindex --extracted-comment@r{, @code{msggrep} option}
 117 Start of patterns for the extracted comments.
 118
 119 @item -E
 120 @itemx --extended-regexp
 121 @opindex -E@r{, @code{msggrep} option}
 122 @opindex --extended-regexp@r{, @code{msggrep} option}
 123 Specify that @var{pattern} is an extended regular expression.
 124
 125 @item -F
 126 @itemx --fixed-strings
 127 @opindex -F@r{, @code{msggrep} option}
 128 @opindex --fixed-strings@r{, @code{msggrep} option}
 129 Specify that @var{pattern} is a set of newline-separated strings.
 130
 131 @item -e @var{pattern}
 132 @itemx --regexp=@var{pattern}
 133 @opindex -e@r{, @code{msggrep} option}
 134 @opindex --regexp=@r{, @code{msggrep} option}
 135 Use @var{pattern} as a regular expression.
 136
 137 @item -f @var{file}
 138 @itemx --file=@var{file}
 139 @opindex -f@r{, @code{msggrep} option}
 140 @opindex --file@r{, @code{msggrep} option}
 141 Obtain @var{pattern} from @var{file}.
 142
 143 @item -i
 144 @itemx --ignore-case
 145 @opindex -i@r{, @code{msggrep} option}
 146 @opindex --ignore-case@r{, @code{msggrep} option}
 147 Ignore case distinctions.
 148
 149 @item -v
 150 @itemx --invert-match
 151 @opindex -v@r{, @code{msggrep} option}
 152 @opindex --invert-match@r{, @code{msggrep} option}
 153 Output only the messages that do not match any selection criterion, instead
 154 of the messages that match a selection criterion.
 155
 156 @end table
 157
 158 @subsection Input file syntax
 159
 160 @table @samp
 161 @item -P
 162 @itemx --properties-input
 163 @opindex -P@r{, @code{msggrep} option}
 164 @opindex --properties-input@r{, @code{msggrep} option}
 165 Assume the input file is a Java ResourceBundle in Java @code{.properties}
 166 syntax, not in PO file syntax.
 167
 168 @item --stringtable-input
 169 @opindex --stringtable-input@r{, @code{msggrep} option}
 170 Assume the input file is a NeXTstep/GNUstep localized resource file in
 171 @code{.strings} syntax, not in PO file syntax.
 172
 173 @end table
 174
 175 @subsection Output details
 176
 177 @c --no-escape and --escape omitted on purpose.  They are not useful.
 178
 179 @table @samp
 180 @item --color
 181 @itemx --color=@var{when}
 182 @opindex --color@r{, @code{msggrep} option}
 183 Specify whether or when to use colors and other text attributes.
 184 See @ref{The --color option} for details.
 185
 186 @item --style=@var{style_file}
 187 @opindex --style@r{, @code{msggrep} option}
 188 Specify the CSS style rule file to use for @code{--color}.
 189 See @ref{The --style option} for details.
 190
 191 @item --force-po
 192 @opindex --force-po@r{, @code{msggrep} option}
 193 Always write an output file even if it contains no message.
 194
 195 @item --indent
 196 @opindex --indent@r{, @code{msggrep} option}
 197 Write the .po file using indented style.
 198
 199 @item --no-location
 200 @opindex --no-location@r{, @code{msggrep} option}
 201 Do not write @samp{#: @var{filename}:@var{line}} lines.
 202
 203 @item -n
 204 @itemx --add-location=@var{type}
 205 @opindex --add-location@r{, @code{msggrep} option}
 206 Generate @samp{#: @var{filename}:@var{line}} lines (default).
 207
 208 The optional @var{type} can be either @samp{full}, @samp{file}, or
 209 @samp{never}.  If it is not given or @samp{full}, it generates the
 210 lines with both file name and line number.  If it is @samp{file}, the
 211 line number part is omitted.  If it is @samp{never}, it completely
 212 suppresses the lines (same as @code{--no-location}).
 213
 214 @item --strict
 215 @opindex --strict@r{, @code{msggrep} option}
 216 Write out a strict Uniforum conforming PO file.  Note that this
 217 Uniforum format should be avoided because it doesn't support the
 218 GNU extensions.
 219
 220 @item -p
 221 @itemx --properties-output
 222 @opindex -p@r{, @code{msggrep} option}
 223 @opindex --properties-output@r{, @code{msggrep} option}
 224 Write out a Java ResourceBundle in Java @code{.properties} syntax.  Note
 225 that this file format doesn't support plural forms and silently drops
 226 obsolete messages.
 227
 228 @item --stringtable-output
 229 @opindex --stringtable-output@r{, @code{msggrep} option}
 230 Write out a NeXTstep/GNUstep localized resource file in @code{.strings} syntax.
 231 Note that this file format doesn't support plural forms.
 232
 233 @item -w @var{number}
 234 @itemx --width=@var{number}
 235 @opindex -w@r{, @code{msggrep} option}
 236 @opindex --width@r{, @code{msggrep} option}
 237 Set the output page width.  Long strings in the output files will be
 238 split across multiple lines in order to ensure that each line's width
 239 (= number of screen columns) is less or equal to the given @var{number}.
 240
 241 @item --no-wrap
 242 @opindex --no-wrap@r{, @code{msggrep} option}
 243 Do not break long message lines.  Message lines whose width exceeds the
 244 output page width will not be split into several lines.  Only file reference
 245 lines which are wider than the output page width will be split.
 246
 247 @item --sort-output
 248 @opindex --sort-output@r{, @code{msggrep} option}
 249 Generate sorted output.  Note that using this option makes it much harder
 250 for the translator to understand each message's context.
 251
 252 @item --sort-by-file
 253 @opindex --sort-by-file@r{, @code{msggrep} option}
 254 Sort output by file location.
 255
 256 @end table
 257
 258 @subsection Informative output
 259
 260 @table @samp
 261 @item -h
 262 @itemx --help
 263 @opindex -h@r{, @code{msggrep} option}
 264 @opindex --help@r{, @code{msggrep} option}
 265 Display this help and exit.
 266
 267 @item -V
 268 @itemx --version
 269 @opindex -V@r{, @code{msggrep} option}
 270 @opindex --version@r{, @code{msggrep} option}
 271 Output version information and exit.
 272
 273 @end table
 274
 275 @subsection Examples
 276
 277 To extract the messages that come from the source files
 278 @code{gnulib-lib/error.c} and @code{gnulib-lib/getopt.c}:
 279
 280 @smallexample
 281 msggrep -N gnulib-lib/error.c -N gnulib-lib/getopt.c input.po
 282 @end smallexample
 283
 284 To extract the messages that contain the string ``Please specify'' in the
 285 original string:
 286
 287 @smallexample
 288 msggrep --msgid -F -e 'Please specify' input.po
 289 @end smallexample
 290
 291 To extract the messages that have a context specifier of either ``Menu>File''
 292 or ``Menu>Edit'' or a submenu of them:
 293
 294 @smallexample
 295 msggrep --msgctxt -E -e '^Menu>(File|Edit)' input.po
 296 @end smallexample
 297
 298 To extract the messages whose translation contains one of the strings in the
 299 file @code{wordlist.txt}:
 300
 301 @smallexample
 302 msggrep --msgstr -F -f wordlist.txt input.po
 303 @end smallexample