.!
.!  File:	SED.RNH
.!
.!  Author:	Hunter Goatley
.!
.!  Date:	October 14, 1991
.!
.!  Description:
.!
.!	RUNOFF source file for GNU sed on-line help.
.!
.!	To build:	$ RUNOFF SED.RNH
.!			$ LIBR/HELP/INSERT libr SED
.!
.!  Modification history:
.!
.!	01-001		Hunter Goatley		14-OCT-1991 08:21
.!		Genesis.
.!
.noflags
.lm4 .rm72
.indent -4
1 SED
.br
SED is GNU sed, the Free Software Foundation's implementation of
sed, the UN*X stream text editor.  The command syntax is UN*X-like, not
VMS-like.
.sk
Sed reads one line at a time from the input files.  It applies the commands
from the list, in order, to each line and writes the edited line to
SYS$OUTPUT.  The default input file is SYS$INPUT.
The script of editing commands can be given on the command line or placed in
a file.  The -f option causes the script to be taken from the named file.
.sk
Note that UN*X-style indirection can be used for redirecting SYS$INPUT and
SYS$OUTPUT.
.sk
Sed outputs each line automatically (unless -n is given).  If the list of
sed commands appears on the command line, quotes may be necessary to maintain
the proper case.
.sk
Format:
.sk;.lm+1;.literal
sed [-options] [list of sed commands] [files...]
.end literal;.lm-1
.!------------------------------------------------------------------------------
.indent -4
2 Command_Format
.br
A script consists of editing commands, one per line, of the following form:
.sk;.center
[address [, address] ] function [arguments]
.sk
In essence, sed copies each line to a buffer and applies each command in
sequence to that line.  When the list is exhausted, the edited line is written
to SYS$OUTPUT (unless -n was given).
.sk
An address can be one of the following:
.sk;.list 0,"o"
.le;a decimal line number (line numbers are counted across input files; the
line counter is not reset when a new file is opened);
.le;a "$" that refers to the last line of input;
.le;a pattern containing a grep-style regular expression; if the pattern
matches the line, the command is applied to the line.
.end list
A command line with no addresses matches every line, while a command line
with one address selects each line that matches the address.  A command line
with two addresses selects the inclusive range from the first line that
matches the first address to the line that matches the second address.
.sk
The "!" function can be used to apply a command only to lines that do not
match a pattern.
.!------------------------------------------------------------------------------
.indent -4
2 List_of_Commands
.br
The valid sed commands include:
.sk
.literal
a\           append lines to output until one not ending in \
b <label>    branch to command ":label"
c\           change lines to following text as in "a"
d            delete line; read next input line
i\           insert following text before next output
l            list line, making all non-printing characters visible
p            print line
q            quit
r <file>     read <file>, copy contents to output
s/old/new/f  substitute "new" for "old".  If "f" = g, replace all
             occurrences; "f"=p, print; "f"=w file, write to "file"
t <label>    test: branch to label if substitution made to current line
w <file>     write line to <file>
y/str1/str2/ replace each character from <str1> with corresponding 
             character from <str2> (no ranges allowed)
=            print current input line number
!<cmd>       do sed <cmd> only if line is not selected
: <label>    set label for "b" and "t" commands
{            treat commands up to matching } as a group
.end literal
.sk
.!------------------------------------------------------------------------------
.indent -4
2 Options
.literal
-n           Suppress default output
-e <expr>    List of sed commands; useful if <expr> begins with -
-f <file>    File containing list of sed commands
-V           Print the version number
+version     Print the version number
+silent      Suppress default output
+quiet       Suppress default output
+expression=<expr>
+file=<file>
.end literal
.!------------------------------------------------------------------------------
.indent -4
2 Regular_Expressions
.br
The regular expression can include the following characters:
.sk
.literal
Expr    Explanation
----    -----------
c       a single (non-meta) character matches itself.
.       matches any single character except newline.
\?      postfix operator; preceeding item is optional.
*       postfix operator; preceeding item 0 or more times.
\+      postfix operator; preceeding item 1 or more times.
\|      infix operator; matches either argument.
^       matches the empty string at the beginning of a line.
$       matches the empty string at the end of a line.
\<      matches the empty string at the beginning of a word.
\>      matches the empty string at the end of a word.
[chars] match any character in the given class; if the
        first character after [ is ^, match any character
        not in the given class; a range of characters may
        be specified by "first-last"; for example, \W
        (below) is equivalent to the class [^A-Za-z0-9]
\( \)   parentheses are used to override operator precedence.
\digit  \n matches a repeat of the text matched earlier in the
        regexp by the subexpression inside the nth opening
        parenthesis.
\       any special character may be preceded by a backslash
        to match it literally.

(the following are for compatibility with GNU Emacs)

\b      matches the empty string at the edge of a word.
\B      matches the empty string if not at the edge of a word.
\w      matches word-constituent characters (letters & digits).
\W      matches characters that are not word-constituent.
.end literal
.sk
Operator precedence is (highest to lowest) ?, **, and +, concatenation,
and finally |.  All other constructs are syntactically identical to
normal characters.  For the truly interested, the file dfa.c describes
(and implements) the exact grammar understood by the parser.
.!------------------------------------------------------------------------------
.indent -4
2 Incompatibilities
.br
The following incompatibilities with UN*X sed exist:
.br;.list 1,"o"
.le;Exit statuses are different from UN*X sed:
.sk
.literal
        Meaning                  UNIX       VMS
        -------                  ----       ---
        Success                     0         1
        Programming error           1         3
        Bad input                   2        44 (SS$_ABORT)
.end literal
.end list
.!------------------------------------------------------------------------------
.!------------------------------------------------------------------------------
.indent -4
2 Availability
.br
GNU sed is free; anyone may redistribute copies of sed to anyone under the
terms stated in the  GNU General Public License, a copy of which may be found in
each copy of  "GNU Emacs". See also the comment at the beginning of the source
code file sed.c.
.sk
Copies of GNU sed may sometimes be received packaged with distributions of Unix
systems, but it is never included in the scope of any license covering those
systems.  Such inclusion violates the terms on which distribution is permitted. 
In fact, the primary purpose of the General Public License is to prohibit anyone
from attaching any other restrictions to redistribution of any of the Free
Software Foundation programs.
.!------------------------------------------------------------------------------
.indent-4
2 Authors
.br
GNU sed was written by Jay Fenlason, David J. MacKenzie, and others, and
is distributed by the Free Software Foundation.
.sk
Hunter Goatley ported sed 1.13 to VMS and produced the on-line help for VMS.
.sk;.indent -4
2 Examples
.br;
.literal
1.  $ sed 3q file.txt
.end literal
.sk
This command tells sed to print the first 3 lines of a file and quit.  It
provides a simple version of HEAD.
.sk
.literal
2.  $ sed -n "/<regexp>/p" *.txt
.end literal
.sk
This command provides the same functionality as grep, where <regexp> is a
regular expression.  Each input line that matches the <regexp> is printed
to SYS$OUTPUT.
.sk
.literal
3.  $ sed -f SYS$INPUT file.txt
    {s/old/new/g
    s"2"two"g
    a\
    An appended line
    }
    ^Z
.end literal
.sk
In this example, the script is given on multiple lines read from SYS$INPUT.
For each line, all occurrences of "old" are replaced with "new", all "2"s are
replaced with "two", and "An appended line" is appended to each line.
.sk
.literal
4.  $ sed "s/^/    /" file.txt >file2.txt
.end literal
.sk
This command indents each line of file.txt by adding 4 blanks to the beginning
of each line and writing it to FILE2.TXT.