unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



extract(1)							   extract(1)



NAME

  extract - interactive	string extract and replace

SYNOPSIS

  extract [-i ignorefile] [-m prefix] [-n] [-p patternfile] [-s	string]	[-u]
  source-program...

OPTIONS

  -i  Ignore text strings specified in ignorefile.  By default,	the extract
      command searches for ignorefile in the current working directory,	your
      home directory, and /usr/lib/nls.

      If you omit the -i option, extract recognizes all	strings	specified in
      the patterns file.

  -m  Add prefix to message numbers in the output source program and source
      message catalog.	You can	use this prefix	as a mnemonic.	You must pro-
      cess source message catalogs that	contain	message	number prefixes	using
      the mkcatdefs command.

  -n  Create a new source message catalog for each input source	program.  By
      default, if you specify more than	one input source program on the
      extract command line, the	command	creates	one source message catalog
      for all the input	source programs.

  -p  Use patternfile to match strings in the input source program.  By
      default, the command searches for	the pattern file in the	current
      directory, your home directory, and /usr/lib/nls.

      If you omit the -p option, the extract command uses a default patterns
      file that	is stored in /usr/lib/nls/patterns.

  -s  Write string at the top of the source message catalog.  If you omit the
      -s option, extract uses the string specified in the $CATHEAD section of
      the patterns file.

  -u  Use a message file produced by a previous	run of strextract.  This file
      contains details of all the strings which	matched	the pattern file
      along with file offsets and line numbers.	 By default strextract is run
      and its output is	used to	drive extract.

DESCRIPTION

  The extract command interactively extracts text strings from source pro-
  grams.  The extract command replaces the strings it extracts with calls to
  the catgets function.	 The command also writes the string it extracts	to a
  source message catalog.  You use this	command	to replace hard-coded mes-
  sages	in your	program	source file with calls to the catgets command and
  create a source message catalog.  At run time, the program reads the mes-
  sage text from the message catalog.  By storing messages in a	message
  catalog, instead of in your program, you allow the text of messages to be
  translated to	a new language or modified without the source program being
  changed.

  In the source-program	argument, you name one or more source programs from
  which	you want messages extracted.  The extract command does not extract
  messages from	source programs	included using the #include directive.
  Therefore, you might want to name a source program and all the source	pro-
  grams	it includes on a single	extract	command	line.

  You can create a patterns file (as specified by patternfile) to control how
  the extract command extracts and replaces text.  The patterns	file is
  divided into several sections, each of which is identified by	a keyword.
  The keyword must start at the	beginning of a new line, and its first char-
  acter	must be	a dollar sign ($).  Following the identifier, you specify a
  number of patterns.  Each pattern begins on a	new line and follows the reg-
  ular expression syntax you use in the	regexp routine.	 For more information
  on the patterns file,	see patterns(4)and for more information	on the regexp
  routine, see regexp(3).

  In addition to the patterns file, you	can create a file that indicates
  strings that extract ignores.	 Each line in this ignore file contains	a
  single string	to be ignored that follows the syntax of the regexp routine.

  When you invoke the extract command, it reads	the patterns file and the
  file that contains strings it	ignores.  You can specify a patterns file and
  an ignore file on the	extract	command	line. Otherwise, the extract command
  matches all strings and uses a default patterns file.

  When you run extract,	it displays three windows on your terminal. The	first
  window contains the program source code.  The	string that matches a string
  in the patterns file is displayed in reverse video.

  The second window displays the contents of the source	message	catalog	that
  the extract command is creating.

  The third window contains a list of the commands that	are available.	The
  extract command displays the current command in reverse video.  You can
  execute the current command by pressing the RETURN key. Select another com-
  mand by typing the first letter in the command name and pressing the RETURN
  key.	The extract command is not sensitive to	the case of letters, so	you
  can use uppercase or lowercase letters to issue commands.

  You can use the following commands to	control	how extract treats the string
  displayed in the first window:

  EXTRACT
      Extract the string into the catalog file and rewrite the source using
      the rewrite string in the	patterns file.

  DUPLICATE
      If the string has	been encountered previously, rewrite the source	pro-
      gram using the same message number as before.  The extract command need
      not add the message to the source	message	catalog	again, so this com-
      mand saves space in catalogs.

  IGNORE
      Ignore this and all subsequent occurrences of this string	during this
      interactive session.  This command does not add the string to the
      ignore file.

  PASS
      Pass by (ignore) this occurrence of this particular string.

  ADD Ignore this and all subsequent occurrences of this string	during this
      interactive session.  Add	the string to the ignore file.

  COMMENT
      Add the comment you enter	to the source message catalog.	The extract
      command prompts you to be	sure the comment you entered is	correct.  You
      answer the prompt	by typing "y," "n," or "q," without pressing the
      RETURN key.

  QUIT
      Quit from	the interactive	session.  The extract command prompts you to
      be sure you want to quit.	 Answer	"y" or "n" to the prompt, without
      pressing the return key.

      The output files that extract creates up to this point are not removed
      by this command.	However, the files contain only	the result of the
      string extractions that occurred before you issued the QUIT command.

  HELP
      Display a	description of all the extract commands.

  The extract command creates two files	in your	current	working	directory.
  The command creates a	new version of the source program that contains	calls
  to the catgets function, instead of hard-coded messages.  The	new version
  of the source	program	has the	same name as the input source program, with
  the prefix nl_.  For example,	if the input source program is named
  update.c, the	output source program is named nl_update.c.

  In addition to a new source program, the extract command creates a source
  message catalog.  The	source message catalog contains	the text for each
  message extracted from your input source program.  The extract command
  names	the file by appending .msg to the name of the input source program.
  For example, the source message catalog for the update.c source program is
  named	update.msg.  You can use the source message catalog as input to	the
  gencat command.

RESTRICTIONS

  Given	the current syntax of the patterns file, you cannot cause extract to
  ignore strings in comments that are longer than one line.

  You can specify only one rewrite string for all classes of pattern matches.

  The extract command does not extract strings from files you include with
  the #include directive.  You must run	the extract commands on	these files
  separately.

  Your terminal	screen must contain at least 80	columns	and 24 lines for
  extract to display its three windows.

  The extract command does not recognize strings that extend beyond one	line.

EXAMPLES

  The following	example	shows the commands you issue to	run the	extract	com-
  mand,	create a message catalog from the source message catalog, and compile
  the output source program:

       % extract -i newignore -p c_patterns remove.c
       % gencat	remove.cat remove.msg
       % vi nl_remove.c
       % cc nl_remove.c

  In this example, the extract command uses the	newignore file to determine
  which	strings	to ignore.  The	command	uses the c_patterns file to deter-
  mines	which strings to match.	 The input source program is named remove.c.


  In response to this command, extract creates the source message catalog
  remove.msg and the output source program nl_remove.c.

  You must edit	nl_remove.c to include the appropriate catopen and catclose
  function calls.

  The gencat command creates a message catalog and the cc command creates an
  executable program.

SEE ALSO

  gencat(1), mkcatdefs(1), strextract(1), strmerge(1), catopen(3), cat-
  gets(3), regexp(3), patterns(4)

  Writing Software for the International Market