extract(1)						      General Commands Manual							extract(1)

NAME

       extract - interactive string extract and replace

SYNOPSIS

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

OPTIONS

       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.  Add prefix to message numbers in the out-
	      put  source  program  and  source message catalog.  You can use this prefix as a mnemonic.  You must process source message catalogs
	      that contain message number prefixes using the mkcatdefs command.  Create a new source message catalog for each  input  source  pro-
	      gram.   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.  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.  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.   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 programs.  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  messages  in  your	program source file with calls to the catgets command and create a source message catalog.  At run
       time, the program reads the message 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 programs 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 character must be a dollar sign ($).  Following the identifier, you specify a number of patterns.  Each pattern begins on a
       new line and follows the regular expression syntax you use in the regexp routine.  For more information on  the	patterns  file,  see  pat-
       terns(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 con-
       tains 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 command 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 the string into the cat-
       alog file and rewrite the source using the rewrite string in the patterns file.	If the string has been encountered previously, rewrite the
       source  program using the same message number as before.  The extract command need not add the message to the source message catalog again,
       so this command saves space in catalogs.  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 by (ignore) this occurrence of this particular string.  Ignore this and all sub-
       sequent occurrences of this string during this interactive session.  Add the string to the ignore file.	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 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.  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 con-
       tains  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 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 cat-
       alog 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 command, 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
       determines 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), catgets(3), regexp(3), patterns(4)

       Writing Software for the International Market

																	extract(1)