Provided by: elvis-common_2.2.0-11.1_all bug

NAME

       elvis - a clone of the ex/vi text editor

SYNOPSIS

       elvis [-V...]  [-a] [-r] [-e] [-i] [-s|-] [-b] [-R] [-S|-SS] [-f session] [-o logfile] [-G
       gui] [-c command|+command] [-t tag] [-w scroll] [-B blksize] [file]...

VERSION

       Elvis 2.2_0

DESCRIPTION

       Elvis is a text editor.  It is intended to be a modern replacement for the  classic  ex/vi
       editor  of  UNIX fame.  Elvis supports many new features, including multiple edit buffers,
       multiple windows, multiple user interfaces (including an X11 interface), and a variety  of
       display modes.

       To  exit  Elvis, you can give the command ":q" in each of its windows.  If you've modified
       the buffer in a window, and you want to abandon those changes, then give the command ":q!"
       instead.

HELP PAGES

       For  more  information  please  take a look at Elvis' help pages.  These pages should have
       been installed together with Elvis.  To view the help pages,  start  Elvis  and  give  the
       command ":help".

       If  this  does  not show you the main help file then something is wrong.  Perhaps the help
       pages were installed in  the  wrong  place.   In  that  case,  search  for  a  file  named
       "elvis.html" using either GNU's locate(1) or the standard find(1) program.  Hopefully this
       will show you where the file is located.  You can then view it with...

            :sp /directory/elvis.html

       If the help pages aren't installed on your system but you have  access  to  the  Internet,
       then you can view the help pages via HTTP by running...

            :sp http://elvis.vi-editor.org/elvisman/elvis.html

OPTIONS

       -V     "Verbose"  mode, causes Elvis to output more status messages.  You can use multiple
              -V flags to get even more detailed information.  -VVV can be handy when Elvis isn't
              initializing  itself  quite  the  way you expected.  See also the -ologfile option,
              described below.

       -a     Instructs Elvis to load all files named on the command line simultaneously  with  a
              separate window for each.

       -r     This is used for recovering an edit session after a crash.  Each Elvis process uses
              a single "session file" to store the contents of all edit buffers.  While Elvis  is
              running,  a  flag is set near the beginning of the session file so that other Elvis
              processes won't try to use  it  at  the  same  time.   If  an  Elvis  process  dies
              abnormally, though, it will leave the session file lying around with that flag set;
              the -r flag allows Elvis to open a session file even if it is marked  as  being  in
              use.

       -e     Causes  Elvis  to  start  each  window  in ex mode, instead of visual command mode.
              Invoking Elvis as "ex" implies this.

       -i     Causes Elvis to start each window in input mode, instead of  visual  command  mode.
              Novice users may prefer this.

       -b     This  sets  the  "binary"  option,  which  causes  new  buffers  to  be  marked  as
              "readeol=binary".  Without -b, Elvis will try to guess the format by examining  the
              first hundred bytes or so of the file.

       -R     This  sets  the "defaultreadonly" option, which causes all new buffers to be marked
              as "readonly" so you won't accidentally overwrite the original file.

       -S     Sets security=safer,  making  Elvis  paranoid  about  certain  potentially  harmful
              commands.   The intent is to protect the user against writing by malicious scripts.
              The ./.exrc  file  and  modelines  are  executed  with  security=safer  temporarily
              regardless  of  whether  -S  was  given.   The  -S  flag is just used to make Elvis
              permanently paranoid, for the duration of this process.

       -SS    Sets security=restricted.  This is more extreme security than "-S".  The intent  is
              to protect the system against reading by malicious users.

       -f session
              Makes  Elvis  use  the  session  file  named "session" instead of the default file.
              Session files are discussed in the description of the -r flag, above.

       -o logfile
              Redirects messages and trace  information  out  to  logfile  instead  of  going  to
              stdout/stderr  as usual.  This is useful under Windows95, where stdout/stderr don't
              show  anywhere.   If  you're  having  trouble  configuring  WinElvis,  try  running
              "WinElvis  -VVV  -o  log" and then you can find the trace and error messages in the
              file "log".

       -G gui Makes Elvis use the named gui user interface instead of the default.  To see a list
              of supported user interfaces, give the command "elvis -?".

       -c command
              After  loading the first file, interpret command as an ex command line.  Several ex
              command lines can be sent in one line, separated by "|".  This  is  good  to  know,
              because only a single -ccommand or +command flag can be used.

       -s     Read  an  ex  script  from  stdin, and execute it.  This is similar to the -Gscript
              flag, except that -s has the additional side-effect of bypassing all initialization
              scripts.

       -t tag Causes  editing  to  begin at the location where the given tag is defined.  See the
              ctags(1) command for more information about tags.

       -w scroll
              This sets the "window" option, which has very little effect in Elvis.

       -B blksize
              If a new session file is created, this causes it to use blocks of size blksize.

       In addition, the following options are also supported to maintain backward  compatibility,
       although their future use is discouraged.

       +command
              Like  -c command, this causes the ex command to be executed after the first file is
              loaded.  If the command is omitted, it is understood to be "$",  which  causes  the
              cursor to move to the last line of the file.

       -      Like -s, this causes Elvis to read a script from stdin and execute it.

TERMCAP INTERFACE

       The termcap interface is the one you'll use most often on non-graphic terminals.  It looks
       and acts a heck of a lot like the traditional vi.  The biggest addition is the support for
       multiple  windows.   For  more information on how to use multiple windows, start Elvis and
       give the command ":help ^W".  The short form of that help is: ^Ws  splits  the  screen  to
       form  an  additional  window, ^Wq closes the window, and ^W^W switches the cursor from one
       window to another.

       If your terminal supports ANSI color escape sequences,  then  you  can  use  the  ":color"
       command  to  assign  different  colors to various fonts.  You must assign a "normal" color
       first, e.g., ":color normal yellow on blue".

       The DOS and (text mode) Win32 version of the termcap interface  support  the  mouse.   The
       mouse  behaves  almost  exactly like the X11 mouse, described below.  The only differences
       are that the mouse can't be used to cut & paste to the  clipboard,  and  on  a  two-button
       mouse  you  can  simulate  a  middle  button by simultaneously pressing the left and right
       buttons.

X11 INTERFACE

       The x11 interface is used under X-Windows on UNIX systems.  It provides  a  scrollbar  and
       mouse support, and allows you to select which fonts to use.

   X11 Options
       To  specify a normal font, use -font fontname or -fn fontname.  Proportional fonts are not
       properly supported, but they aren't rejected with an error message either.  If  you  don't
       specify a normal font, then Elvis will use a font named "fixed" by default.  (This default
       can be overridden by a  "set  font=..."  command  in  the  elvis.ini  file.   The  default
       elvis.ini file does this, making the new default font be 18-point Courier.)

       To  specify  a  bold font, use -fb fontname.  The specified font should have the same size
       character cell as the normal font, but Elvis does not verify this.  If you don't specify a
       bold font, then Elvis will fake it by smearing the normal font rightward one pixel.

       To specify an italic font, use -fi fontname.  The specified font should have the same size
       character cell as the normal font, but Elvis does not verify this.  If you  don't  specify
       an  italic  font,  then  Elvis  will  fake  it  by sliding the top half of the normal font
       rightward one pixel.

       If you want to use Courier fonts, there is a shortcut: -courier size will use the  normal,
       bold, and italic versions of the Courier font in the requested size.

       You  can  force Elvis to use only black and white with the -mono flag; this is the default
       if your display only has one bitplane.  For color displays, -fg color and -bg color can be
       used to set the normal text color and the background color, respectively.

       Elvis  has  a  built-in icon, which is generally a good thing.  Some window managers won't
       allow you to assign a new icon to a program that has  a  built-in  one,  so  Elvis  has  a
       -noicon flag which disables the built-in icon.

       The  -fork client causes Elvis to run in the background, so that your shell prompt returns
       immediately.

       The -client option causes Elvis to look for an already-running Elvis process on the same X
       server  and,  if  there  is  one, send the new arguments to it.  This causes the old Elvis
       process to create new windows for file arguments.   The  new  Elvis  process  then  exits,
       leaving  the  old  one to do the real work and allowing your shell program to prompt for a
       new command immediately.  For the sake of uniformity, if -client fails to find an existing
       Elvis  process,  then  a  new  Elvis  process  starts  up as though you had used the -fork
       argument instead.

       The -client option is implemented in an interesting way: the client Elvis simply  sends  a
       series  of  ex  commands  to  an  existing window of the server Elvis.  For each file name
       argument, the client Elvis sends a ":split file" command.  For  -ttag,  the  client  Elvis
       sends  a  ":stag  tag" command.  For -ccommand, the client Elvis simply sends the command,
       and this results in some quirks.  First, the server Elvis temporarily sets  security=safer
       while  the  command is executed, for security reasons.  Second, the command is executed by
       the server's existing window, not the new one, so (for example) "elvis -client -c 20  foo"
       creates a new window for the file "foo", and then moves the OLD WINDOW's cursor to line 20
       of whatever file it was showing.

   X11 Mouse
       I've tried to reach a balance between the mouse behavior of xterm(1) and what makes  sense
       for an editor.  To do this right, Elvis has to distinguish between clicking and dragging.

       Dragging  the mouse always selects text.  Dragging with button 1 pressed (usually the left
       button) selects  characters,  dragging  with  button  2  (the  middle  button)  selects  a
       rectangular  area,  and  dragging  with  button 3 (usually the right button) selects whole
       lines.  These operations correspond to Elvis' v, ^V, and V commands,  respectively.   When
       you  release  the  button  at the end of the drag, the selected text is immediately copied
       into an X11 cut buffer, so you can paste it into another application such as  xterm.   The
       text remains selected, so you can apply an operator command to it.

       Clicking  button  1  cancels any pending selection, and moves the cursor to the clicked-on
       character.  Clicking button 3 moves the cursor without canceling  the  pending  selection;
       you can use this to extend a pending selection.

       Clicking button 2 "pastes" text from the X11 cut butter.  If you're entering an ex command
       line, the text will be pasted into the command line as though you had typed it.  If you're
       in visual command mode or input mode, the text will be pasted into your edit buffer.  When
       pasting, it doesn't matter where you click in the window; Elvis always inserts the text at
       the position of the text cursor.

       Double-clicking  button 1 simulates a ^] keystroke, causing Elvis to perform tag lookup on
       the clicked-on word.  If Elvis happens to be displaying an HTML document, then tag  lookup
       pursues  hypertext  links so you can double-click on any underlined text to view the topic
       that describes that text.  Double-clicking button 3 simulates a ^T keystroke,  taking  you
       back to where you did the last tag lookup.

       If  your  mouse  has  a  scroll  wheel,  then  Elvis  can  be  configured  to use it.  For
       instructions on doing this, start Elvis and give the command ":howto scrollwheel".

ENVIRONMENT VARIABLES

       Elvis has commands which can  examine  any  environment  variable.   Because  of  this,  a
       comprehensive  list  of environment variables isn't possible.  The following list contains
       the environment variables which have hardcoded meaning in Elvis.

       BASH or BASH_VERSION
              Under Unix/Linux, Elvis tests for the presence of these variables to decide whether
              or  not  the  /bin/sh  shell  supports process control, especially the ^Z key.  The
              values of these variables doesn't matter, only the fact that they exist.

       COLUMNS
              For the "termcap" user interface, this overrides the number of columns specified in
              the termcap/terminfo entry.

       DISPLAY
              For the "x11" user interface, this indicates which display it should run on.

       ELVISBG
              If  set  to  "light"  or  "dark",  its  value  is used as the default value for the
              background option.

       ELVISGUI
              If set, its value is used to select the default  user  interface.   You  can  still
              override it by using the -Ggui command line flag.

       ELVISPATH
              If  ELVISPATH  is  defined  in  the  environment, then its value is copied into the
              elvispath option, which is a list of directories that Elvis should  search  through
              when  looking  for  its support files.  If ELVISPATH is undefined, Elvis will use a
              default list which usually includes the your home directory, and  maybe  a  system-
              wide default location.

       EXINIT If  defined,  the  value  of this option is typically interpreted as a series of EX
              commands when Elvis starts up.  This behavior isn't built into Elvis though; it  is
              handled by the standard elvis.ini file.

       HOME   This  is  your home directory.  Its value is used as the default value for the home
              option, which is used in ~ substitution in file names.

       HOMEDRIVE and HOMEPATH
              For Windows, if HOME is unset then HOMEDRIVE and HOMEPATH are checked;  if  they're
              set then they're concatenated to form the default value of the home option.

       INCLUDE
              The "syntax" display mode uses this as a list of directories to search through when
              looking for a header file such as <stdio.h>.

       LC_ALL, LC_MESSAGES, and LANG
              If LANG  is  defined,  then  Elvis  will  look  for  its  message  translations  in
              $LANG/elvis.msg,   and   only   use   just   plain   elvis.msg  if  it  can't  find
              $LANG/elvis.msg.  The LC_MESSAGES and LC_ALL environment variables work  similarly,
              and take precedence over LANG.

       LINES  For  the  "termcap" user interface, this overrides the number of lines specified in
              the termcap/terminfo entry.

       LOGNAME
              This stores your login name.  It is used when reading  via  the  FTP  protocol,  to
              choose the default login information.

       OLDPWD This stores the name of the previous directory you were in.  Its value is stored in
              the prevdir option, which is used for ~- substitution in file names.

       PATH   The usual search path for programs.

       SESSIONPATH
              This is a list of directories where Elvis might be able to create the session file.
              Elvis uses the first writable directory from the list, and ignores all others.

       SHELL or COMSPEC
              This is the name of your command-line interpreter.  Elvis needs to know this so you
              can run programs from inside Elvis.  SHELL is used in Unix/Linux,  and  COMSPEC  is
              used in MS-DOS.

       TAGPATH
              This  is  a  path  for  tags  files, used by the :tag command.  For Microsoft it is
              semicolon-delimited; for all others it is colon-delimited.  Each entry in the  path
              can be either a filename, or the name of a directory containing a file named tags.

       TERM   For  the  termcap  interface,  this  is the name of the terminal's termcap/terminfo
              entry.  Also, if its value is "kvt" or ends with "-r" or "-rv", then the background
              option will be "light" by default; else it will be "dark".

       TERMCAP
              For  the termcap interface, this can either store the name of a termcap file or the
              actual contents of a termcap entry.

       TMP    This is where Elvis stores its temporary files other than session files.

       WINDOWID
              Elvis uses this when choosing the default value of the background option.   If  the
              WINDOWID environment variable exists, then Elvis assumes it is running in an xterm-
              like terminal emulator, and those emulators usually have a light background.

       XENVIRONMENT, XFILESEARCHPATH, and XUSERFILESEARCHPATH
              These are used by the "x11" user interface, when loading Elvis' resources.

FILES

       ~      This is your home directory.  Whenever Elvis sees a ~ at the start of  a  pathname,
              it  replaces  the  ~  with  the  value  of the "home" option.  The "home" option is
              initialized from the  HOME  environment  variable;  if  HOME  is  unset  then  some
              operating  systems  will  set  "home"  to the the directory where the Elvis program
              resides.

       lib    In this man-page, "lib" is a placeholder for the  name  of  a  directory  in  which
              Elvis'  configuration  files  reside.   The "elvispath" option's value is a list of
              directories that Elvis will check for each configuration file.

       elvis*.ses
              These are the default names for sessions files.  Session files store  the  contents
              of  all  edit  buffers  for  a given edit session.  You can instruct Elvis to use a
              specific session file via the -fsession  command-line  flag.   Note  that  sessions
              specified  via  -fsession  normally reside in the current directory, but when Elvis
              chooses its own session file name, it will place it in the first writable directory
              named in the SESSIONPATH environment variable.

       tags   This  file  stores  the  tags for the files in a directory.  It is used by the :tag
              command, among others.

       lib/elvis.ini
              This file contains EX commands which are executed whenever Elvis starts up.   Elvis
              searches through the ELVISPATH for the file.

       ~/.exrc, ~/.elvisrc, or ~\elvis.rc
              The  .exrc  or  .elvisrc  (for  UNIX)  or elvis.rc (for non-UNIX) file in your home
              directory will generally be executed as a series of EX commands, unless the  EXINIT
              environment  variable  is defined.  This behavior isn't built into Elvis though; it
              is handled by the standard elvis.ini file.

       .exrc, .elvisrc, or elvis.rc
              The .exrc or .elvisrc (for UNIX) or elvis.rc (for non-UNIX)  file  in  the  current
              directory  is  interpreted  as a series of EX commands, but only if the exrc option
              has been set.  This behavior isn't built into Elvis; it is handled by the  standard
              elvis.ini file.

       lib/elvis.brf
              This file contains EX commands which are executed Before Reading a File.  Typically
              this is used to distinguish a binary file from a text file by  examining  the  file
              name extension of the file.  The "readeol" option is then set accordingly.

       lib/elvis.arf
              This  file  contains  EX  commands which are executed After Reading a File.  If the
              current directory doesn't contain an elvis.arf file, then  Elvis  searches  through
              the  ELVISPATH  for the file.  Typically, this is used to set the bufdisplay option
              for a buffer, based on the file name extension of the file.

       lib/elvis.bwf
              This  file  contains  EX  commands  which  are  executed  Before  Writing  a  File.
              Typically,  lib/elvis.bwf  is  used  to  perform  an  RCS "checkout" command before
              writing a file.

       lib/elvis.lat
              This contains a series of ":digraph"  commands  which  set  up  the  digraph  table
              appropriately for the ISO Latin-1 symbol set.  The lib/elvis.ini file executes this
              script during initialization, except under OS/2, MS-DOS, or text-mode Win32.

       lib/elvis.pc8
              This contains a series of ":digraph"  commands  which  set  up  the  digraph  table
              appropriately  for  the PC-8 symbol set.  This is the normal symbol set for MS-DOS,
              OS/2, and text-mode Win32 (although the graphical Win32 uses  lib/elvis.lat).   The
              lib/elvis.ini file executes this script during initialization under MS-DOS.

       lib/elvis.msg
              This  file's  data is used for mapping the Elvis' terse error messages into verbose
              messages.

       lib/elvistrs.msg
              Elvis doesn't use this file directly; it is simply meant to  serve  as  a  resource
              from  which  you can extract the terse form of one of elvis' messages; you can then
              add the terse form and your own custom verbose form to the lib/elvis.msg file.

       lib/elvis.syn
              This file controls how Elvis' "syntax" display mode highlights the text for a given
              language.

       lib/elvis.x11
              This  file  contains a series of ex command.  This file is sourced by lib/elvis.ini
              if Elvis is using its X11 user interface.  It configures up the toolbar and default
              colors.

       lib/elvis.ali
              This  contains  a  set  of aliases.  If your copy of Elvis is configured to support
              aliases (i.e., if it isn't the MS-DOS version) then these aliases  will  be  loaded
              automatically.   They  are partly intended to serve as examples of what aliases can
              do and how to write them, but mostly these aliases are intended to be truly useful.
              To see a list of the aliases, give the command ":alias".

       lib/elvis*.html
              These files contain the online documentation.

       lib/*.man
              These contain the man pages -- shorter summaries of the programs, with descriptions
              of the command-line flags.

       guix11/*.xpm and guix11/elvis.xbm
              These contain icon images for use with  X-windows.   The  "elvis.xbm"  image  is  a
              2-color  bitmap,  and  it  is  compiled  into  Elvis.   The  other  files,  such as
              "elvis.xpm," contain color  images.   The  "insticon.sh"  shell  script  (which  is
              invoked  as  part  of  the  "make  install"  operation)  tries  to  copy these into
              appropriate directories.

SEE ALSO

       ex(1), vi(1), ctags(1)

       You should also view the on-line documentation, via ":help".

AUTHOR

       Steve Kirkendall
       kirkenda@cs.pdx.edu

                                                                                         elvis(1)