usr/src/man/man1/genmsg.1

   1 '\" te
   2 .\"  Portions Copyright (c) 2004, 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 GENMSG 1 "May 14, 2004"
   7 .SH NAME
   8 genmsg \- generate a message source file by extracting messages from source
   9 files
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBgenmsg\fR [\fB-abdfrntx\fR] [\fB-c\fR \fImessage-tag\fR] [\fB-g\fR \fIproject-file\fR]
  14      [\fB-l\fR \fIproject-file\fR] [\fB-m\fR \fIprefix\fR] [\fB-M\fR \fIsuffix\fR]
  15      [\fB-o\fR \fImessage-file\fR] [\fB-p\fR \fIpreprocessor\fR] [\fB-s\fR \fIset-tags\fR] \fI file\fR...
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBgenmsg\fR utility extracts message strings with calls to
  22 \fBcatgets\fR(3C) from source files and writes them in a format suitable for
  23 input to \fBgencat\fR(1).
  24 .SS "Invocation"
  25 .sp
  26 .LP
  27 \fBgenmsg\fR reads one or more input files and, by default, generates a message
  28 source file whose name is composed of the first input file name with
  29 \fB\&.msg\fR. If the \fB-o\fR option is specified, \fBgenmsg\fR uses the option
  30 argument for its output file.
  31 .sp
  32
  33 .sp
  34 .TS
  35 box;
  36 l | l
  37 l | l .
  38 \fICommand\fR   \fIOutput File\fR
  39 _
  40 \fBgenmsg prog.c\fR     prog.c.msg
  41 \fBgensmg main.c util.c tool.c\fR       main.c.msg
  42 \fBgenmsg -o prog.msg mail.c util.c\fR  prog.msg
  43 .TE
  44
  45 .sp
  46 .LP
  47 \fBgenmsg\fR also allows you to invoke a preprocessor to solve the dependencies
  48 of macros and define statements for the \fBcatgets\fR(3C) calls.
  49 .SS "Auto Message Numbering"
  50 .sp
  51 .LP
  52 \fBgenmsg\fR replaces message numbers with the calculated numbers based upon
  53 the project file if the message numbers are \fB-1\fR, and it generates copies
  54 of the input files with the new message numbers and a copy of the project file
  55 with the new maximum message numbers.
  56 .sp
  57 .LP
  58 A project file is a database that stores a list of set numbers with their
  59 maximum message numbers. Each line in a project file is composed of a set
  60 number and its maximum message number:
  61 .sp
  62 .ne 2
  63 .na
  64 \fB\fISet_number\fR\fR
  65 .ad
  66 .RS 14n
  67 \fIMaximum_message_number\fR
  68 .RE
  69
  70 .sp
  71 .LP
  72 In a project file, a line beginning with a number sign (\fB#\fR) or an
  73 \fBASCII\fR space is considered as a comment and ignored.
  74 .sp
  75 .LP
  76 \fBgenmsg\fR also has the reverse operation to replace all message numbers with
  77 \fB-1\fR.
  78 .SS "Comment Extraction"
  79 .sp
  80 .LP
  81 \fBgenmsg\fR allows you to comment about messages and set numbers to inform the
  82 translator how the messages should be translated. It extracts the comment,
  83 which is surrounded with the comment indicators and has the specified tag
  84 inside the comment, from the input file and writes it with a dollar (\fB$\fR)
  85 prefix in the output file. \fBgenmsg\fR supports the C and C++ comment
  86 indicators, '\fB/*\fR', '\fB*/\fR', and '\fB//\fR'.
  87 .SS "Testing"
  88 .sp
  89 .LP
  90 \fBgenmsg\fR generates two kinds of messages for testing, prefixed messages and
  91 long messages. Prefixed messages allow you to check that your program is
  92 retrieving the messages from the message catalog. Long messages allow you to
  93 check the appearance of your window program's initial size and position.
  94 .SH OPTIONS
  95 .sp
  96 .LP
  97 The following options are supported:
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fB-a\fR\fR
 102 .ad
 103 .RS 19n
 104 Append the output into the message file \fImessage-file\fR that is specified by
 105 the \fB-o\fR option. If two different messages that have the same set and
 106 message number are found, the message in the specified message file is kept and
 107 the other message in the input file is discarded.
 108 .RE
 109
 110 .sp
 111 .ne 2
 112 .na
 113 \fB\fB-b\fR\fR
 114 .ad
 115 .RS 19n
 116 Place the extracted comment after the corresponding message in the output file.
 117 This option changes the placement behavior of the \fB-s\fR or \fB-c\fR option.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fB-c\fR\fI message-tag\fR\fR
 124 .ad
 125 .RS 19n
 126 Extract message comments having \fImessage-tag\fR inside them from the input
 127 files and write them with a '\fB$\fR' prefix as a comment in the output file.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fB-d\fR\fR
 134 .ad
 135 .RS 19n
 136 Include an original text of a message as a comment to be preserved along with
 137 its translations. With this option, the translator can see the original
 138 messages even after they are replaced with their translations.
 139 .RE
 140
 141 .sp
 142 .ne 2
 143 .na
 144 \fB\fB-f\fR\fR
 145 .ad
 146 .RS 19n
 147 Overwrite the input files and the project file when used with the \fB-l\fR or
 148 \fB-r\fR option. With the \fB-r\fR option, \fBgenmsg\fR overwrites only the
 149 input files.
 150 .RE
 151
 152 .sp
 153 .ne 2
 154 .na
 155 \fB\fB-g\fR\fI project-file\fR\fR
 156 .ad
 157 .RS 19n
 158 Generate \fIproject-file\fR that has a list of set numbers and their maximum
 159 message numbers in the input files.
 160 .RE
 161
 162 .sp
 163 .ne 2
 164 .na
 165 \fB\fB-l\fR\fI project-file\fR\fR
 166 .ad
 167 .RS 19n
 168 Replace message numbers with the calculated numbers based upon
 169 \fIproject-file\fR if the message numbers are \fB-1\fR in the input files, and
 170 then generate copies of the input files with the new message numbers and a copy
 171 of \fIproject-file\fR with the new maximum message numbers. If
 172 \fIproject-file\fR is not found, \fBgenmsg\fR uses the maximum message number
 173 in the input file as a base number and generates \fIproject-file\fR.
 174 .RE
 175
 176 .sp
 177 .ne 2
 178 .na
 179 \fB\fB-m\fR\fI prefix\fR\fR
 180 .ad
 181 .RS 19n
 182 Fill in the message with \fIprefix\fR. This option is useful for testing.
 183 .RE
 184
 185 .sp
 186 .ne 2
 187 .na
 188 \fB\fB-M\fR\fI suffix\fR\fR
 189 .ad
 190 .RS 19n
 191 Fill in the message with \fIsuffix\fR. This option is useful for testing.
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fB-n\fR\fR
 198 .ad
 199 .RS 19n
 200 Add comment lines to the output file indicating the file name and line number
 201 in the input files where each extracted string is encountered.
 202 .RE
 203
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fB-o\fR\fI message-file\fR\fR
 208 .ad
 209 .RS 19n
 210 Write the output to \fImessage-file\fR.
 211 .RE
 212
 213 .sp
 214 .ne 2
 215 .na
 216 \fB\fB-p\fR\fI preprocessor\fR\fR
 217 .ad
 218 .RS 19n
 219 Invoke \fIpreprocessor\fR to preprocess macros and define statements for the
 220 \fBcatgets\fR(3C) calls. \fBgenmsg\fR first invokes the option argument as a
 221 preprocesser and then starts the normal process against the output from the
 222 preprocessor. \fBgenmsg\fR initiates this process for all the input files.
 223 .RE
 224
 225 .sp
 226 .ne 2
 227 .na
 228 \fB\fB-r\fR\fR
 229 .ad
 230 .RS 19n
 231 Replace message numbers with \fB-1\fR. This is the reverse operation of the
 232 \fB-l\fR option.
 233 .RE
 234
 235 .sp
 236 .ne 2
 237 .na
 238 \fB\fB-s\fR\fI set-tag\fR\fR
 239 .ad
 240 .RS 19n
 241 Extract set number comments having \fIset-tag\fR inside them from the input
 242 files and write them with a '\fB$\fR' prefix as a comment in the output file.
 243 If multiple comments are specified for one set number, the first one is
 244 extracted and the rest of them are discarded.
 245 .RE
 246
 247 .sp
 248 .ne 2
 249 .na
 250 \fB\fB-t\fR\fR
 251 .ad
 252 .RS 19n
 253 Generate a message that is three times as long as the original message. This
 254 option is useful for testing.
 255 .RE
 256
 257 .sp
 258 .ne 2
 259 .na
 260 \fB\fB-x\fR\fR
 261 .ad
 262 .RS 19n
 263 Suppress warning messages about message and set number range checks and
 264 conflicts.
 265 .RE
 266
 267 .SH OPERANDS
 268 .sp
 269 .ne 2
 270 .na
 271 \fB\fIfile\fR\fR
 272 .ad
 273 .RS 8n
 274 An input source file.
 275 .RE
 276
 277 .SH EXAMPLES
 278 .LP
 279 \fBExample 1 \fRAssigning Message Numbers and Generating New Files
 280 .sp
 281 .LP
 282 Suppose that you have the following source and project files:
 283
 284 .sp
 285 .in +2
 286 .nf
 287 example% cat test.c
 288 printf(catgets(catfd, 1, -1, "line too long\en"));
 289 printf(catgets(catfd, 2, -1, "invalid code\en"));
 290
 291 example% cat proj
 292 1   10
 293 2   20
 294 .fi
 295 .in -2
 296 .sp
 297
 298 .sp
 299 .LP
 300 The command
 301
 302 .sp
 303 .in +2
 304 .nf
 305 example% genmsg \fB-l\fR proj test.c
 306 .fi
 307 .in -2
 308 .sp
 309
 310 .sp
 311 .LP
 312 would assign the calculated message numbers based upon \fBproj\fR and generate
 313 the following files:
 314
 315 .sp
 316 .ne 2
 317 .na
 318 \fB\fBtest.c.msg\fR\fR
 319 .ad
 320 .RS 14n
 321 Message file
 322 .RE
 323
 324 .sp
 325 .ne 2
 326 .na
 327 \fB\fBproj.new\fR\fR
 328 .ad
 329 .RS 14n
 330 Updated project file
 331 .RE
 332
 333 .sp
 334 .ne 2
 335 .na
 336 \fB\fBtest.c.new\fR\fR
 337 .ad
 338 .RS 14n
 339 New source file
 340 .RE
 341
 342 .sp
 343 .in +2
 344 .nf
 345 example% cat test.c.msg
 346 $quote "
 347 $set    1
 348 11      "line too long\en"
 349 $set    2
 350 21      "invalid code\en"
 351
 352 example% cat proj.new
 353 1   11
 354 2   21
 355
 356 example% cat test.c.new
 357 printf(catgets(catfd, 1, 11, "line too long\en"));
 358 printf(catgets(catfd, 2, 21, "invalid code\en"));
 359 .fi
 360 .in -2
 361 .sp
 362
 363 .LP
 364 \fBExample 2 \fRExtracting Comments Into a File
 365 .sp
 366 .LP
 367 The command
 368
 369 .sp
 370 .in +2
 371 .nf
 372 example% genmsg \fB-s\fR SET \fB-c\fR MSG test.c
 373 example% cat test.c
 374 /* SET: tar messages */
 375 /* MSG: don't translate "tar". */
 376 catgets(catfd, 1, 1, "tar: tape write error");
 377 // MSG: don't translate "tar" and "\fB-I\fR".
 378 catgets(catfd, 1, 2, "tar: missing argument for \fB-I\fR flag");
 379 .fi
 380 .in -2
 381 .sp
 382
 383 .sp
 384 .LP
 385 would extract the comments and write them in the following output file:
 386
 387 .sp
 388 .in +2
 389 .nf
 390 example% cat test.c.msg
 391 $ /* SET: tar messages */
 392 $set    1
 393 $ /* MSG: don't translate "tar". */
 394 1       "tar: tape write error"
 395 $ // MSG: don't translate "tar" and "-I".
 396 2       "tar: missing argument for -I flag"
 397 .fi
 398 .in -2
 399 .sp
 400
 401 .LP
 402 \fBExample 3 \fRGenerating Test Messages
 403 .sp
 404 .LP
 405 The following command:
 406
 407 .sp
 408 .in +2
 409 .nf
 410 example% genmsg \fB-m\fR PRE: \fB-M\fR :FIX test.c
 411 .fi
 412 .in -2
 413 .sp
 414
 415 .sp
 416 .LP
 417 might generate the following messages for testing:
 418
 419 .sp
 420 .in +2
 421 .nf
 422 example% cat test.c.msg
 423 1       "PRE:OK:FIX"
 424 2       "PRE:Cancel:FIX"
 425 .fi
 426 .in -2
 427 .sp
 428
 429 .LP
 430 \fBExample 4 \fRParsing a Macro and Writing the Extracted Messages
 431 .sp
 432 .LP
 433 Given the following input:
 434
 435 .sp
 436 .in +2
 437 .nf
 438 example% cat example.c
 439 #include <nl_types.h>
 440 #define MSG1    "message1"
 441 #define MSG2    "message2"
 442 #define MSG3    "message3"
 443 #define MSG(n)  catgets(catd, 1, n, MSG ## n)
 444 void
 445 main(int argc, char **argv)
 446 {
 447 nl_catd catd = catopen(argv[0], NL_CAT_LOCALE);
 448 (void) printf("%s0\en, MSG(1));
 449 (void) printf("%s0\en, MSG(2));
 450 (void) printf("%s0\en, MSG(3));
 451 (void) catclose(catd);
 452 }
 453 .fi
 454 .in -2
 455 .sp
 456
 457 .sp
 458 .LP
 459 The following command:
 460
 461 .sp
 462 .in +2
 463 .nf
 464 example% genmsg \fB-p\fR "cc \fB-E\fR" \fB-o\fR example.msg example.c
 465 .fi
 466 .in -2
 467 .sp
 468
 469 .sp
 470 .LP
 471 would parse the \fBMSG\fR macros and write the extracted messages in
 472 \fBexample.msg\fR.
 473
 474 .LP
 475 \fBExample 5 \fRAssigning Calculated Message Numbers
 476 .sp
 477 .LP
 478 Suppose that you have the following header, source, and project files:
 479
 480 .sp
 481 .in +2
 482 .nf
 483 example% cat ../inc/msg.h
 484 #define WARN_SET        1
 485 #define ERR_SET 2
 486 #define WARN_MSG(id, msg) catgets(catd, WARN_SET, (id), (msg))
 487 #define ERR_MSG(id, msg)  catgets(catd, ERR_SET, (id), (msg))
 488 example% example.c
 489 #include "msg.h"
 490 printf("%s, WARN_MSG(-1, "Warning error"));
 491 printf("%s, ERR_MSG(-1, "Fatal error"));
 492 example % proj
 493 1     10
 494 2     10
 495 .fi
 496 .in -2
 497 .sp
 498
 499 .sp
 500 .LP
 501 The command
 502
 503 .sp
 504 .in +2
 505 .nf
 506 example% genmsg \fB-f\fR -p "cc \fB-E\fR \fB-I\fR../inc" \fB-l\fR proj \e
 507    \fB-o\fR example.msg example.c
 508 .fi
 509 .in -2
 510 .sp
 511
 512 .sp
 513 .LP
 514 would assign each of the \fB-1\fR message numbers a calculated number based
 515 upon  \fBproj\fR and would overwrite the results to \fBexample.c\fR and
 516 \fBproj\fR. Also, this command writes the extracted messages in
 517 \fBexample.msg\fR.
 518
 519 .SH ENVIRONMENT VARIABLES
 520 .sp
 521 .LP
 522 See \fBenviron\fR(5) for descriptions of the following environment variables
 523 that affect the execution of \fBgenmsg\fR: \fBLC_MESSAGES\fR and \fBNLSPATH\fR.
 524 .SH EXIT STATUS
 525 .sp
 526 .LP
 527 The following exit values are returned:
 528 .sp
 529 .ne 2
 530 .na
 531 \fB\fB0\fR\fR
 532 .ad
 533 .RS 6n
 534 Successful completion.
 535 .RE
 536
 537 .sp
 538 .ne 2
 539 .na
 540 \fB\fB>0\fR\fR
 541 .ad
 542 .RS 6n
 543 An error occurred.
 544 .RE
 545
 546 .SH SEE ALSO
 547 .sp
 548 .LP
 549 \fBgencat\fR(1), \fBcatgets\fR(3C), \fBcatopen\fR(3C), \fBattributes\fR(5),
 550 \fBenviron\fR(5)
 551 .SH NOTES
 552 .sp
 553 .LP
 554 \fBgenmsg\fR does not handle pointers or variables in the \fBcatgets\fR(3C)
 555 call. For example:
 556 .sp
 557 .in +2
 558 .nf
 559
 560 const int set_num = 1;
 561 extern int msg_num(const char *);
 562 const char *msg = "Hello";
 563 catgets(catd, set_num, msg_num(msg), msg);
 564 .fi
 565 .in -2
 566 .sp
 567
 568 .sp
 569 .LP
 570 When the auto message numbering is turned on with a preprocessor, if there are
 571 multiple \fB-1's\fR in the \fBcatgets\fR(3C) line, \fBgenmsg\fR replaces all of
 572 the \fB-1's\fR in the line with a calculated number. For example, given the
 573 input:
 574 .sp
 575 .in +2
 576 .nf
 577 #define MSG(id, msg) catgets(catd, 1, (id), (msg))
 578 if (ret == -1) printf("%s, MSG(-1, "Failed"));
 579 .fi
 580 .in -2
 581 .sp
 582
 583 .sp
 584 .LP
 585 the command
 586 .sp
 587 .in +2
 588 .nf
 589 genmsg \fB-l\fR proj \fB-p\fR "cc \fB-E\fR"
 590 .fi
 591 .in -2
 592 .sp
 593
 594 .sp
 595 .LP
 596 would produce:
 597 .sp
 598 .in +2
 599 .nf
 600    #define MSG(id, msg) catgets(catd, 1, (id), (msg))
 601    if (ret == 1) printf("%s, MSG(1, "Failed"));
 602 .fi
 603 .in -2
 604 .sp
 605
 606 .sp
 607 .LP
 608 The workaround would be to split it into two lines as follows:
 609 .sp
 610 .in +2
 611 .nf
 612    if (ret == -1)
 613          printf("%s, MSG(-1, "Failed"));
 614 .fi
 615 .in -2
 616 .sp
 617