doc: turn env comments into documentation

* src/env.c: Convert introductory comments...
* doc/coreutils.texi (env invocation): ...into documentation.
Suggested by Jim Meyering.

doc/coreutils.texi

@@ -14442,6 +14442,57 @@ If no command name is specified following the environment
 specifications, the resulting environment is printed.  This is like
 specifying the @command{printenv} program.
 
+For some examples, suppose the environment passed to @command{env}
+contains @samp{LOGNAME=rms}, @samp{EDITOR=emacs}, and
+@samp{PATH=.:/gnubin:/hacks}:
+
+@itemize @bullet
+
+@item
+Output the current environment.
+@example
+$ env | LC_ALL=C sort
+EDITOR=emacs
+LOGNAME=rms
+PATH=.:/gnubin:/hacks
+@end example
+
+@item
+Run @command{foo} with a reduced environment, preserving only the
+original @env{PATH} to avoid problems in locating @command{foo}.
+@example
+env - PATH="$PATH" foo
+@end example
+
+@item
+Run @command{foo} with the environment containing @samp{LOGNAME=rms},
+@samp{EDITOR=emacs}, and @samp{PATH=.:/gnubin:/hacks}, and guarantees
+that @command{foo} was found in the file system rather than a shell
+builtin.
+@example
+env foo
+@end example
+
+@item
+Run @command{nemacs} with the environment containing @samp{LOGNAME=foo},
+@samp{EDITOR=emacs}, @samp{PATH=.:/gnubin:/hacks}, and
+@samp{DISPLAY=gnu:0}.
+@example
+env DISPLAY=gnu:0 LOGNAME=foo nemacs
+@end example
+
+@item
+Attempt to run the program @command{/energy/--} (as that is the only
+possible path search result); if the command exists, the environment
+will contain @samp{LOGNAME=rms} and @samp{PATH=/energy}, and the
+arguments will be @samp{e=mc2}, @samp{bar}, and @samp{baz}.
+@example
+env -u EDITOR PATH=/energy -- e=mc2 bar baz
+@end example
+
+@end itemize
+
+
 The program accepts the following options.  Also see @ref{Common options}.
 Options must precede operands.
 

src/env.c

@@ -16,72 +16,6 @@
 
 /* Richard Mlynarik and David MacKenzie */
 
-/* Options:
-   -
-   -i
-   --ignore-environment
-        Construct a new environment from scratch; normally the
-        environment is inherited from the parent process, except as
-        modified by other options.
-
-   -u variable
-   --unset=variable
-        Unset variable VARIABLE (remove it from the environment).
-        If VARIABLE was not set, does nothing.
-
-   -0
-   --null
-        When no program is specified, output environment information
-        terminated by NUL bytes rather than newlines.
-
-   variable=value (an arg containing a "=" character)
-        Set the environment variable VARIABLE to value VALUE.  VALUE
-        may be of zero length ("variable=").  Setting a variable to a
-        zero-length value is different from unsetting it.
-
-   --
-        Indicate that the following argument is not an option.
-        This is necessary when the program's name begins with "-",
-        but does not help if the program's name contains a "=".
-
-   The first remaining argument specifies a program to invoke;
-   it is searched for according to the specification of the PATH
-   environment variable, after environment modifications.  Any
-   arguments following that are passed as arguments to that program.
-
-   If no command name is specified following the environment
-   specifications, the resulting environment is printed.
-   This is like specifying a command name of "printenv".
-
-   Examples:
-
-   If the environment passed to "env" is
-        { LOGNAME=rms EDITOR=emacs PATH=.:/gnubin:/hacks }
-
-   env - foo
-        runs "foo" in a null environment.
-
-   env foo
-        runs "foo" in the environment
-        { LOGNAME=rms EDITOR=emacs PATH=.:/gnubin:/hacks }
-
-   env DISPLAY=gnu:0 nemacs
-        runs "nemacs" in the environment
-        { LOGNAME=rms EDITOR=emacs PATH=.:/gnubin:/hacks DISPLAY=gnu:0 }
-
-   env - LOGNAME=foo /hacks/hack bar baz
-        runs the "hack" program on arguments "bar" and "baz" in an
-        environment in which the only variable is "LOGNAME".  Note that
-        the "-" option clears out the PATH variable, so one should be
-        careful to specify in which directory to find the program to
-        call.
-
-   env -u EDITOR LOGNAME=foo PATH=/energy -- e=mc2 bar baz
-        attempts to run the program "/energy/--" with arguments
-        "e=mc2", "bar" and "baz" in the environment
-        { LOGNAME=foo PATH=/energy }.
-*/
-
 #include <config.h>
 #include <stdio.h>
 #include <sys/types.h>