home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / vim53os2.zip / vim-5.3 / doc / editing.txt < prev    next >
Text File  |  1998-08-30  |  33KB  |  732 lines
  1. *editing.txt*   For Vim version 5.3.  Last modification: 1998 Aug 30
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Bram Moolenaar
  5.  
  6.  
  7. Editing files                        *edit-files*
  8.  
  9. 1. Introduction            |edit-intro|
  10. 2. Editing a file        |edit-a-file|
  11. 3. The argument list        |argument-list|
  12. 4. Writing and quitting        |write-quit|
  13. 5. Editing binary files        |edit-binary|
  14.  
  15. ==============================================================================
  16. 1. Introduction                        *edit-intro*
  17.  
  18. Editing a file with Vim means:
  19.  
  20. 1. reading the file into the internal buffer
  21. 2. changing the buffer with editor commands
  22. 3. writing the buffer into a file
  23.  
  24.                             *current-file*
  25. As long as you don't write the buffer, the original file remains unchanged.
  26. If you start editing a file (read a file into the buffer), the file name is
  27. remembered as the "current file name".
  28.  
  29.                             *alternate-file*
  30. If there already was a current file name, then that one becomes the alternate
  31. file name.  All file names are remembered in the file list.  When you enter a
  32. file name, for editing (e.g., with ":e filename") or writing (e.g., with (:w
  33. file name"), the file name is added to the list.  You can use this list to
  34. remember which files you edited and to quickly switch from one file to
  35. another with the CTRL-^ command (e.g., to copy text).  First type the number
  36. of the file and then hit CTRL-^.  {Vi: only one alternate file name}
  37.  
  38. CTRL-G        or                *CTRL-G* *:f* *:file*
  39. :f[ile]            Prints the current file name (as typed), the
  40.             cursor position (unless the 'ruler' option is set),
  41.             and the file status (readonly, modified).  See the
  42.             'shortmess' option about how tho make this message
  43.             shorter.  {Vi does not include column number}
  44.  
  45. {count}CTRL-G        Like CTRL-G, but prints the current file name with
  46.             full path.  If the count is higher than 1 the current
  47.             buffer number is also given.  {not in Vi}
  48.  
  49.                             *g_CTRL-G*
  50. g CTRL-G        Prints the current position of the cursor in three
  51.             ways: Column, Line and Character.  If there are
  52.             characters in the line that take more than one
  53.             position on the screen (<Tab> or special character),
  54.             both the "real" column and the screen column are
  55.             shown, separated with a dash.  See also 'ruler'
  56.             option.  {not in Vi}
  57.  
  58.                             *:file_f*
  59. :f[ile] {name}        Sets the current file name to {name}.
  60.  
  61. :buffers
  62. :files
  63. :ls            List all the currently known file names.  See
  64.             'windows.txt' |:files| |:buffers| |:ls|.  {not in
  65.             Vi}
  66.  
  67. Vim will remember the full path name of a file name that you enter.  In most
  68. cases when the file name is displayed only the name you typed is shown, but
  69. the full path name is being used if you used the ":cd" command |:cd|.
  70.  
  71.                             *home-replace*
  72. If the environment variable $HOME is set, and the file name starts with that
  73. string, it is often displayed with HOME replaced with "~".  This was done to
  74. keep file names short.  When reading or writing files the full name is still
  75. used, the "~" is only used when displaying file names.  When replacing the
  76. file name would result in just "~", "~/" is used instead (to avoid confusion
  77. with 'backupext' set to "~").
  78.  
  79. When writing the buffer, the default is to use the current file name.  Thus
  80. when you give the "ZZ" or ":wq" command, the original file will be
  81. overwritten.  If you do not want this, the buffer can be written into another
  82. file by giving a file name argument to the ":write" command.  For example:
  83.  
  84. >    vim testfile
  85. >    [change the buffer with editor commands]
  86. >    :w newfile
  87. >    :q
  88.  
  89. This will create a file "newfile", that is a modified copy of "testfile".
  90. The file "testfile" will remain unchanged.  Anyway, if the 'backup' option is
  91. set, Vim renames or copies the original file before it will be overwritten.
  92. You can use this file if you discover that you need the original file.  See
  93. also the 'patchmode' option.  The name of the backup file is normally the same
  94. as the original file with 'backupext' appended.  The default "~" is a bit
  95. strange to avoid accidently overwriting existing files.  If you prefer ".bak"
  96. change the 'backupext' option.  Extra dots are replaced with '_' on MS-DOS
  97. machines, when Vim has detected that an MS-DOS-like filesystem is being used
  98. (e.g., messydos or crossdos) or when the 'shortname' option is on.  The
  99. backup file can be placed in another directory by setting 'backupdir'.
  100.  
  101.                             *auto-shortname*
  102. Technical: On the Amiga you can use 30 characters for a file name.  But on an
  103.        MS-DOS-compatible filesystem only 8 plus 3 characters are
  104.        available.  Vim tries to detect the type of filesystem when it is
  105.        creating the .swp file.  If an MS-DOS-like filesystem is suspected,
  106.        a flag is set that has the same effect as setting the 'shortname'
  107.        option.  This flag will be reset as soon as you start editing a
  108.        new file.  The flag will be used when making the file name for the
  109.        ".swp" and ".~" files for the current file.  But when you are
  110.        editing a file in a normal filesystem and write to an MS-DOS-like
  111.        filesystem the flag will not have been set.  In that case the
  112.        creation of the ".~" file may fail and you will get an error
  113.        message.  Use the 'shortname' option in this case.
  114.  
  115. When you started editing without giving a file name, "No File" is displayed in
  116. messages.  If the ":write" command is used with a file name argument, the file
  117. name for the current file is set to that file name.  This only happens when
  118. the 'F' flag is included in 'cpoptions' (by default it is included).  This is
  119. useful when entering text in an empty buffer and then writing it to a file.
  120. If 'cpoptions' contains the 'f' flag (by default it is NOT included) the file
  121. name is set for the ":read file" command.  This is useful when starting Vim
  122. without an argument and then doing ":read file" to start editing a file.
  123. Because the file name was set without really starting to edit that file, you
  124. are protected from overwriting that file.  This is done by setting the
  125. "notedited" flag.  You can see if this flag is set with the CTRL-G or ":file"
  126. command.  It will include "[Not edited]" when the "notedited" flag is set.
  127. When writing the buffer to the current file name (with ":w!"), the "notedited"
  128. flag is reset.
  129.  
  130. Vim remembers whether you have changed the buffer.  You are protected from
  131. losing the changes you made.  If you try to quit without writing, or want to
  132. start editing another file, this will be refused.  In order to overrule this
  133. protection add a '!' to the command.  The changes will then be lost.  For
  134. example: ":q" will not work if the buffer was changed, but ":q!" will.  To see
  135. whether the buffer was changed use the "CTRL-G" command.  The message includes
  136. the string "[Modified]" if the buffer has been changed.
  137.  
  138.                             *:confirm* *:conf*
  139. :conf[irm] {command}    Execute {command}, and use a dialog when an
  140.             operation has to be confirmed.  Can be used on the
  141.             ":q", ":qa" and ":w" commands (the latter to over-ride
  142.             a read-only setting).
  143.  
  144. Examples:
  145. >  :confirm w foo
  146.     Will ask for confirmation when "foo" already exists.
  147. >  :confirm q
  148.     Will ask for confirmation when there are changes.
  149. >  :confirm qa
  150.     If any modified, unsaved buffers exist, you will be prompted to save
  151.     or abandon each one.  There are also choices to "save all" or "abandon
  152.     all".
  153.  
  154. If you want to always use ":confirm", set the 'confirm' option.
  155.  
  156.                             *:browse* *:bro*
  157. :bro[wse] {command}    Open a file selection dialog for an argument to
  158.             {command}.  At present this works for ":e", ":w",
  159.             ":r", ":sp", ":mkexrc", ":mkvimrc" and ":mksession".
  160.             {only in Win32, Motif and Athena GUI}
  161.  
  162. The syntax is best shown via some examples:
  163. >    :browse e $vim/foo
  164.         Open the browser in the $vim/foo directory, and edit the
  165.         file chosen.
  166. >    :browse e
  167.         Open the browser in the directory of the current buffer,
  168.         and edit the file chosen.
  169. >    :browse w
  170.         Open the browser in the directory of the current buffer,
  171.         with the current buffer filename as default, and save the
  172.         buffer under the filename chosen.
  173. >    :browse w C:/bar
  174.         Open the browser in the C:/bar directory, with the current
  175.         buffer filename as default, and save the buffer under the
  176.         filename chosen.
  177. Also see the |'browsedir'| option.
  178. For versions of Vim where browsing is not supported, the command is executed
  179. unmodified.
  180.  
  181. ==============================================================================
  182. 2. Editing a file                    *edit-a-file*
  183.  
  184.                             *:e* *:edit*
  185. :e[dit] [+cmd]        Edit the current file.  This is useful to re-edit the
  186.             current file, when it has been changed outside of Vim.
  187.             This fails when changes have been made to the current
  188.             buffer.  Also see |+cmd|.
  189.  
  190.                             *:edit!*
  191. :e[dit]! [+cmd]        Edit the current file always.  Discard any changes to
  192.             the current buffer.  This is useful if you want to
  193.             start all over again.  Also see |+cmd|.
  194.  
  195.                             *:edit_f*
  196. :e[dit] [+cmd] {file}    Edit {file}.  This fails when changes have been made
  197.             to the current buffer.  Also see |+cmd|.
  198.  
  199.                             *:edit!_f*
  200. :e[dit]! [+cmd] {file}    Edit {file} always.  Discard any changes to the
  201.             current buffer.  Also see |+cmd|.
  202.  
  203. :e[dit] [+cmd] #[count]    Edit the [count]th alternate file name (as shown by
  204.             :files).  This command does the same as
  205.             [count] CTRL-^.  But ":e #" doesn't work if the
  206.             alternate buffer doesn't have a file name, while
  207.             CTRL-^ still works then.  Also see |+cmd|.
  208.  
  209.                             *:ex*
  210. :ex [+cmd] [file]    Same as :edit, but also switch to "Ex" mode.  See
  211.             |Ex-mode|.
  212.  
  213.                             *:vi* *:visual*
  214. :vi[sual][!] [+cmd] [file]
  215.             When entered in Ex mode: Leave Ex mode, go back to
  216.             Normal mode.  Otherwise same as :edit.
  217.  
  218.                             *:vie* *:view*
  219. :vie[w] [+cmd] file    When entered in Ex mode: Leave Ex mode, go back to
  220.             Normal mode.  Otherwise same as :edit, but set
  221.             'readonly' option for this buffer.  {not in Vi}
  222.  
  223.                             *CTRL-^*
  224. [count]CTRL-^        Edit [count]th alternate file (equivalent to ":e
  225.             #[count]").  Without count this gets you to the
  226.             previously edited file.  This is a quick way to
  227.             toggle between two (or more) files.  If the
  228.             'autowrite' option is on and the buffer was
  229.             changed, write it.
  230.  
  231. [count]]f                        *]f*
  232. [count][f                        *[f* *gf*
  233. [count]gf        Edit the file whose name is under or after the cursor.
  234.             Mnemonic: "goto file".
  235.             Uses the 'isfname' option to find out which characters
  236.             are supposed to be in a file name.
  237.             Uses the 'path' variable as a list of directory names
  238.             to look for the file.  Also looks for the file
  239.             relative to the current file.
  240.             If a [count] is given, the count'th file that is found
  241.             in the 'path' is edited.
  242.             This command fails if the current file cannot be
  243.             abandoned |abandon-file|.
  244.             If you do want to edit a new file, use:
  245. >                :e <cfile>
  246.             To make gf always work like that:
  247. >                :map gf :e <cfile><CR>
  248.             If the name is a hypertext link, that looks like
  249.             "type://machine/path", only "/path" is used.
  250.             For Unix the '~' character is expanded, like in
  251.             "~user/file".  Environment variables are expanded too
  252.             |expand-env|.
  253.             {not in Vi}
  254.             Not available when the |+file_in_path| feature was
  255.             disabled at compile time.
  256.  
  257.                             *:cd*
  258. :cd            On non-Unix systems: Print the current directory
  259.             name.  On Unix systems: Change the current directory
  260.             to the home directory.
  261.  
  262. :cd {path}        Change the current directory to {path}.  Does not
  263.             change the meaning of an already entered file name,
  264.             because its full path name is remembered.  On MS-DOS
  265.             this also changes the active drive.
  266.  
  267.                             *:chd* *:chdir*
  268. :chd[ir] [path]        Same as :cd.
  269.  
  270.                             *:pw* *:pwd*
  271. :pw[d]            Print the current directory name.  {Vi: no pwd}
  272.  
  273. These commands are used to start editing a single file.  This means that the
  274. file is read into the buffer and the current file name is set.  You may use
  275. the ":cd" command to get to another directory, so you will not have to type
  276. that directory name in front of the file names.  One warning: After using
  277. ":cd" the full path name will be used for reading and writing files.  On some
  278. networked file systems this may cause problems.  The result of using the full
  279. path name is that the file names currently in use will remain referring to the
  280. same file.  Example: If you have a file a:test and a directory a:vim the
  281. commands ":e test" ":cd vim" ":w" will overwrite the file a:test and not write
  282. a:vim/test.  But if you do ":w test" the file a:vim/test will be written,
  283. because you gave a new file name and did not refer to a filename before the
  284. ":cd".
  285.  
  286.                             *:filename*
  287. Note for systems other than Unix and MS-DOS: When using a command that
  288. accepts a single file name (like ":edit file") spaces in the file name are
  289. allowed, but trailing spaces are ignored.  This is useful on systems that
  290. allow file names with embedded spaces (like the Amiga).  Example: The command
  291. ":e   Long File Name " will edit the file "Long File Name".  When using a
  292. command that accepts more than one file name (like ":next file1 file2")
  293. embedded spaces must be escaped with a backslash.
  294.  
  295. On Unix you can also use backticks in the file name, for example:
  296. >    :e `find . -name ver\\*.c -print`
  297. The backslashes before the star are required to prevent "ver*.c" to be
  298. expanded by the shell before executing the find program.
  299.  
  300. You can use the ":e!" command if you messed up the buffer and want to start
  301. all over again.  The ":e" command is only useful if you have changed the
  302. current file name.
  303.  
  304.                             *abandon-file*
  305. You abandon a file when you start editing another file in the same window.
  306. But the text is not unloaded, when the 'hidden' option is set, or when another
  307. window is editing the same file.  When the text will be unloaded, and there
  308. are changes in the text, Vim will protect you from accidently losing those
  309. changes.  When 'autowrite' is set, the file is written.  Otherwise you will
  310. get an error message, unless you used the '!' to force abandoning the changes.
  311. Note that ":e file" will fail if there are changes in the current buffer,
  312. also when the 'autowrite' option is on.  This is illogical, because with
  313. other commands (e.g., ":next") the current buffer would be written and
  314. abandoned, but this behaviour is compatible with Vi.  If you encounter this
  315. problem, you can use CTRL-^ to jump to the file, because the alternate file
  316. name is set to the argument of the ":e" command.
  317.  
  318.                             *+cmd* *[+cmd]*
  319. The [+cmd] argument can be used to position the cursor in the newly opened
  320. file, or execute any other command:
  321.     +        Start at the last line.
  322.     +{num}        Start at line {num}.
  323.     +/{pat}        Start at first line containing {pat}.
  324.     +{command}    Execute {command} after opening the new file.
  325.             {command} is any Ex command.
  326. To include a white space in the {pat} or {command}, precede it with a
  327. backslash.  To end with a backslash, use a double backslash.
  328.     :edit  +/The\ book       file
  329.     :edit  +/dir\ dirname\\  file
  330.  
  331.                             *file-formats*
  332. The 'fileformat' option sets the <EOL> style for a file:
  333. 'fileformat'    characters       name                ~
  334.   "dos"        <CR><NL> or <NL>   DOS format        *DOS-format*
  335.   "unix"    <NL>           Unix format        *Unix-format*
  336.   "mac"        <CR>           Mac format        *Mac-format*
  337. Previously 'textmode' was used.  It is obsolete now.
  338.  
  339. When reading a file, the mentioned characters are interpreted as the <EOL>.
  340. In DOS format (default for MS-DOS, OS/2 and Win32), <CR><NL> and <NL> are both
  341. interpreted as the <EOL>.  Note that when writing the file in DOS format,
  342. <CR> characters will be added for each single <NL>.  Also see |file-read|.
  343.  
  344. When writing a file, the mentioned characters are used for <EOL>.  For DOS
  345. format <CR><NL> is used.  Also see |DOS-format-write|.
  346.  
  347. You can read a file in DOS format and write it in Unix format.  This will
  348. replace all <CR><NL> pairs by <NL> (assuming 'fileformats' includes "dos"):
  349. >  :e file
  350. >  :set 'fileformat'=unix
  351. >  :w
  352. If you read a file in Unix format and write with DOS format, all <NL>
  353. characters will be replaced with <CR><NL> (assuming 'fileformats' includes
  354. "unix"):
  355. >  :e file
  356. >  :set 'fileformat'=dos
  357. >  :w
  358.  
  359. If you start editing a new file and the 'fileformats' option is not empty
  360. (which is the default), Vim will try to detect whether the lines in the file
  361. are separated by the specified formats.  When set to "unix,dos", Vim will
  362. check for lines with a single <NL> (as used on Unix and Amiga) or by a <CR>
  363. <NL> pair (MS-DOS).  Only when ALL lines end in <CR><NL>, 'fileformat' is set
  364. to "dos", otherwise it is set to "unix".  When 'fileformats' includes "mac",
  365. and no <NL> characters are found in the file, 'fileformat' is set to "mac".
  366.  
  367. If the 'fileformat' option is set to "dos" on non-MS-DOS systems the message
  368. "[dos format]" is shown to remind you that something unusual is happening.  On
  369. MS-DOS systems you get the message "[unix format]" if 'fileformat' is set to
  370. "unix".  On all systems but the Macintosh you get the message "[mac format]"
  371. if 'fileformat' is set to "mac".
  372.  
  373. If the 'fileformats' option is empty and DOS format is used, but while reading
  374. a file some lines did not end in <CR><NL>, "[CR missing]" will be included in
  375. the file message.
  376. If the 'fileformats' option is empty and Mac format is used, but while reading
  377. a file a <NL> was found, "[NL missing]" will be included in the file message.
  378.  
  379. If the new file does not exist, the 'fileformat' of the current buffer is used
  380. when 'fileformats' is empty.  Otherwise the first format from 'fileformats' is
  381. used for the new file.
  382.  
  383. Before editing binary, executable or Vim script files you should set the
  384. 'binary' option.  A simple way to do this is by starting Vim with the "-b"
  385. option.  This will avoid the use of 'fileformat'.  Without this you risk that
  386. single <NL> characters are unexpectedly replaced with <CR><NL>.
  387.  
  388. ==============================================================================
  389. 3. The argument list                *argument-list* *arglist*
  390.  
  391. If you give more than one file name when starting Vim, this list is
  392. remembered as the argument list.  Do not confuse this with the file list,
  393. which you can see with the ":files" command |:files|.  The argument list was
  394. already present in Vi, the file list is new in Vim.  The file names in the
  395. argument list will also be present in the file list (unless they were
  396. deleted with ":bdel").
  397.  
  398. You can use the argument list with the following commands, and with the
  399. expression functions |argc()| and |argv()|.
  400.  
  401.                             *:ar* *:args*
  402. :ar[gs]            Print the argument list, with the current file in
  403.             square brackets.
  404.  
  405.                             *:argu* *:argument*
  406. :[count]argu[ment] [count] [+cmd]
  407.             Edit file [count] in the argument list, unless
  408.             changes have been made and the 'autowrite' option is
  409.             off.  Also see |+cmd|.  {Vi: no such command}
  410.  
  411. :[count]argu[ment]! [count] [+cmd]
  412.             Edit file [count] in the argument list, discard any
  413.             changes to the current buffer.  Also see |+cmd|.  {Vi:
  414.             no such command}
  415.  
  416.                             *:n* *:next*
  417. :[count]n[ext] [+cmd]    Edit [count] next file, unless changes have been
  418.             made and the 'autowrite' option is off.  Also see
  419.             |+cmd|.  {Vi: no count}.
  420.  
  421. :[count]n[ext]! [+cmd]    Edit [count] next file, discard any changes to the
  422.             buffer.  Also see |+cmd|.  {Vi: no count}.
  423.  
  424. :ar[gs] [+cmd] {arglist}
  425. :n[ext] [+cmd] {arglist}
  426.             Define {arglist} as the new argument list and edit
  427.             the first one, unless changes have been made and the
  428.             'autowrite' option is off.  Also see |+cmd|.
  429.  
  430. :ar[gs]! [+cmd] {arglist}
  431. :n[ext]! [+cmd] {arglist}                *:next_f*
  432.             Define {arglist} as the new argument list and edit
  433.             the first one.  Discard any changes to the buffer.
  434.             Also see |+cmd|.
  435.  
  436. :[count]N[ext] [count] [+cmd]                *:Next* *:N*
  437.             Edit [count] previous file in argument list, unless
  438.             changes have been made and the 'autowrite' option is
  439.             off.  Also see |+cmd|.  {Vi: no count}.
  440.  
  441. :[count]N[ext]! [count] [+cmd]
  442.             Edit [count] previous file in argument list.  Discard
  443.             any changes to the buffer.  Also see |+cmd|.  {Vi: no
  444.             count}.
  445.  
  446. :[count]prev[ious] [count] [+cmd]            *:prev* *:previous*
  447.             Same as :Next.  Also see |+cmd|.  {Vi: only in some
  448.             versions}
  449.  
  450.                             *:rew* *:rewind*
  451. :rew[ind] [+cmd]    Start editing the first file in the argument list,
  452.             unless changes have been made and the 'autowrite'
  453.             option is off.  Also see |+cmd|.
  454.  
  455. :rew[ind]! [+cmd]    Start editing the first file in the argument list.
  456.             Discard any changes to the buffer.  Also see |+cmd|.
  457.  
  458.                             *:la* *:last*
  459. :la[st] [+cmd]        Start editing the last file in the argument list,
  460.             unless changes have been made and the 'autowrite'
  461.             option is off.  Also see |+cmd|.  {not in Vi}
  462.  
  463. :la[st]! [+cmd]        Start editing the last file in the argument list.
  464.             Discard any changes to the buffer.  Also see |+cmd|.
  465.             {not in Vi}
  466.  
  467.                             *:wn* *:wnext*
  468. :[count]wn[ext] [+cmd]    Write current file and start editing the [count]
  469.             next file.  Also see |+cmd|.  {not in Vi}
  470.  
  471. :[count]wn[ext] [+cmd] {file}
  472.             Write current file to {file} and start editing the
  473.             [count] next file, unless {file} already exists and
  474.             the 'writeany' option is off.  Also see |+cmd|.  {not
  475.             in Vi}
  476.  
  477. :[count]wn[ext]! [+cmd] {file}
  478.             Write current file to {file} and start editing the
  479.             [count] next file.  Also see |+cmd|.  {not in Vi}
  480.  
  481. :[count]wN[ext][!] [+cmd] [file]            *:wN* *:wNext*
  482. :[count]wp[revous][!] [+cmd] [file]            *:wp* *:wprevious*
  483.             Same as :wnext, but go to previous file instead of
  484.             next.  {not in Vi}
  485.  
  486. The [count] in the commands above defaults to one.  For some commands it is
  487. possible to use two counts.  The last one (rightmost one) is used.
  488.  
  489. The wildcards in the argument list are expanded and the file names are sorted.
  490. Thus you can use the command "vim *.c" to edit all the C files.  From within
  491. Vim the command ":n *.c" does the same.  On Unix you can also use backticks,
  492. for example:
  493. >    :n `find . -name \\*.c -print`
  494. The backslashes before the star are required to prevent "*.c" to be expanded
  495. by the shell before executing the find program.
  496.  
  497.                             *arglist-quit*
  498. You are protected from leaving Vim if you have not been editing the last file
  499. in the argument list.  This prevents you from forgetting that you were editing
  500. one out of several files.  To exit anyway try to exit twice.  If there are
  501. changes in the current buffer this will fail.  You can exit anyway, and save
  502. any changes, with the ":wq!" command.  To lose any changes use the ":q!"
  503. command.
  504.  
  505.                             *arglist-position*
  506. When there is an argument list you can see which file you are editing in the
  507. title of the window (if there is one and 'title' is on) and with the file
  508. message you get with the "CTRL-G" command.  You will see something like
  509.     (file 4 of 11)
  510. If 'shortmess' contains 'f' it will be
  511.     (4 of 11)
  512. If you are not really editing the file at the current position in the argument
  513. list it will be
  514.     (file (4) of 11)
  515. This means that you are position 4 in the argument list, but not editing the
  516. fourth file in the argument list.  This happens when you do ":e file".
  517.  
  518. ==============================================================================
  519. 4. Writing and quitting                *write-quit* *save-file*
  520.  
  521.                             *:w* *:write*
  522. :[range]w[rite][!]    Write the specified lines to the current file.
  523.  
  524.                             *:w_f* *:write_f*
  525. :[range]w[rite]    {file}    Write the specified lines to {file}, unless it
  526.             already exists and the 'writeany' option is off.
  527.  
  528.                             *:w!*
  529. :[range]w[rite]! {file}    Write the specified lines to {file}.  Overwrite an
  530.             existing file.
  531.  
  532.                             *:w_a* *:write_a*
  533. :[range]w[rite][!] >>    Append the specified lines to the current file.
  534.  
  535. :[range]w[rite][!] >> {file}
  536.             Append the specified lines to {file}.  '!' forces the
  537.             write even if file does not exist.
  538.  
  539.                             *:w_c* *:write_c*
  540. :[range]w[rite] !{cmd}    Execute {cmd} with [range] lines as standard input
  541.             (note the space in front of the '!').  {cmd} is
  542.             executed like with ":!{cmd}", any '!' is replaced with
  543.             the previous command |:!|.
  544.  
  545. The default [range] for the ":w" command is the whole buffer (1,$).
  546. If a file name is given with ":w" it becomes the alternate file.  This can be
  547. used, for example, when the write fails and you want to try again later with
  548. ":w #".  This can be switched off by removing the 'A' flag from the
  549. 'cpoptions' option.
  550.  
  551.                             *:up* *:update*
  552. :[range]up[date][!] [>>] [file]
  553.             Like ":write", but only write when the buffer has been
  554.             modified.  {not in Vi}
  555.  
  556.                             *:q* *:quit*
  557. :q[uit]            Quit, unless changes have been made or not editing
  558.             the last file in the argument list.
  559.  
  560. :conf[irm] q[uit]    Quit, but give prompt when changes have been made, or
  561.             not editing the last file in the argument list.  See
  562.             |:confirm| and 'confirm'.  {not in Vi}
  563.  
  564. :q[uit]!        Quit without writing, also when visible buffers have
  565.             changes.  Does not exit when there are changed hidden
  566.             buffers.  Use ":qall!" to exit always.
  567.  
  568. :cq[uit]        Quit always, without writing, and return an error
  569.             code.  See |:cq|.  Used for Manx's QuickFix mode (see
  570.             |quickfix|).  {not in Vi}
  571.  
  572.                             *:wq*
  573. :wq            Write the current file and exit (unless editing the
  574.             last file in the argument list or the file is
  575.             read-only).
  576.  
  577. :wq!            Write the current file and exit.
  578.  
  579. :wq {file}        Write to {file}.  Exit if not editing the last
  580.             file in the argument list.
  581.  
  582. :wq! {file}        Write to {file} and exit.
  583.  
  584. :[range]wq[!] [file]    Same as above, but only write the lines in [range].
  585.  
  586.                             *:x* *:xit*
  587. :[range]x[it][!] [file]
  588.             Like ":wq", but write only when changes have been
  589.             made.
  590.             When 'hidden' is set and there are more windows, the
  591.             current buffer becomes hidden, after writing the file.
  592.  
  593.                             *:exi* *:exit*
  594. :[range]exi[t][!] [file]
  595.             Same as :xit.
  596.  
  597.                             *ZZ*
  598. ZZ            Write current file, if modified, and exit (same as
  599.             ":x").  (Note: If there are several windows for the
  600.             current file, the file is written if it was modified
  601.             and the window is closed).
  602.  
  603.                             *ZQ*
  604. ZQ            Quit current file and exit (same as ":q!").  (Note: If
  605.             there are several windows for the current file, only
  606.             the window is closed).
  607.  
  608.                             *timestamp*
  609. Vim remembers the modification timestamp of a file when you begin editing it.
  610. Before writing a file the timestamp is checked.  If it has changed, Vim will
  611. ask if you really want to overwrite the file:
  612.  
  613.     WARNING: The file has been changed since reading it!!!
  614.     Do you really want to write to it (y/n)?
  615.  
  616. If you hit 'y' Vim will continue writing the file.  If you hit 'n' the write is
  617. aborted.  If you used ":wq" or "ZZ" Vim will not exit, you will get another
  618. chance to write the file.
  619.  
  620. Alternatively, after a shell command is run (|:!cmd| |suspend| |:read!| |K|)
  621. ALL timestamps are compared.   Vim will run any associated |FileChangedShell|
  622. autocommands or display the above WARNING for any files that have changed.
  623.  
  624. The message would normally mean that somebody has written to the file after
  625. the edit session started.  This could be another person, in which case you
  626. probably want to check if your changes to the file and the changes from the
  627. other person should be merged.  Write the file under another name and check for
  628. differences (the "diff" program can be used for this).
  629. It is also possible that you modified the file yourself, from another edit
  630. session or with another command (e.g., a filter command).  Then you will know
  631. which version of the file you want to keep.
  632.  
  633.                             *backup*
  634. If you write to an existing file (but do not append) while the 'backup',
  635. 'writebackup' or 'patchmode' option is on, a backup of the original file is
  636. made.  On Unix systems the file is copied, on other systems the file is
  637. renamed.  After the file has been successfully written and when the
  638. 'writebackup' option is on and the 'backup' option is off, the backup file is
  639. deleted.  When the 'patchmode' option is on the backup file may be renamed.
  640.  
  641.                             *backup-table*
  642. 'backup' 'writebackup'    action    ~
  643.    off         off    no backup made
  644.    off         on        backup current file, deleted afterwards (default)
  645.    on         off    delete old backup, backup current file
  646.    on         on        delete old backup, backup current file
  647.  
  648. When the 'backup' option is on, an old backup file (with the same name as the
  649. new backup file) will be deleted.  If 'backup' is not set, but 'writebackup' is
  650. set, an existing backup file will not be deleted.  The backup file that is made
  651. while the file is being written will have a different name.
  652.  
  653. The directories given with the 'backupdir' option is used to put the backup
  654. file in.  (default: same directory as the written file).
  655.  
  656. On Unix systems:
  657. When you write to an existing file, that file is truncated and then filled
  658. with the new text.  This means that protection bits, owner and symbolic links
  659. are unmodified.  The backup file however, is a new file, owned by the user who
  660. edited the file.  The group of the backup is set to the group of the original
  661. file.  If this fails, the protection bits for the group are made the same as
  662. for others.
  663.  
  664. If the creation of a backup file fails, the write is not done.  If you want
  665. to write anyway add a '!' to the command.
  666.  
  667.                             *write-readonly*
  668. When the 'cpoptions' option contains 'W', Vim will refuse to overwrite a
  669. readonly file.  When 'W' is not present, ":w!" will overwrite a readonly file,
  670. if the system allows it (the directory must be writable).
  671.  
  672.                             *write-fail*
  673. If the writing of the new file fails, you have to be careful not to lose
  674. your changes AND the original file.  If there is no backup file and writing
  675. the new file failed, you have already lost the original file! DON'T EXIT VIM
  676. UNTIL YOU WRITE OUT THE FILE! If a backup was made, it is put back in place
  677. of the original file (if possible).  If you exit Vim, and lose the changes
  678. you made, the original file will mostly still be there.  If putting back the
  679. original file fails, there will be an error message telling you that you
  680. lost the original file.
  681.  
  682.                         *DOS-format-write*
  683. If the 'fileformat' is "dos", <CR> <NL> is used for <EOL>.  This is default
  684. for MS-DOS, Win32 and OS/2.  On other systems the message "[dos format]" is
  685. shown to remind you that an unusual <EOL> was used.
  686.                         *Unix-format-write*
  687. If the 'fileformat' is "unix", <NL> is used for <EOL>.  On MS-DOS, Win32 and
  688. OS/2 the message "[unix format]" is shown.
  689.                         *Mac-format-write*
  690. If the 'fileformat' is "mac", <CR> is used for <EOL>.  On non-Mac systems the
  691. message "[mac format]" is shown.
  692.  
  693. See also |file-formats| and the 'fileformat' and 'fileformats' options.
  694.  
  695. ==============================================================================
  696. 5. Editing binary files                    *edit-binary*
  697.  
  698. Although Vim was made to edit text files, it is possible to edit binary
  699. files.  The "-b" Vim argument (b for binary) makes Vim do file I/O in binary
  700. mode, and sets some options for editing binary files ('binary' on, 'textwidth'
  701. to 0, 'modeline' off, 'expandtab' off).  Setting the 'binary' option has the
  702. same effect.  Don't forget to do this before reading the file.
  703.  
  704. There are a few things to remember when editing binary files:
  705. - When editing executable files the number of characters must not change.
  706.   Use only the "R" or "r" command to change text.  Do not delete characters
  707.   with "x" or by backspacing.
  708. - Set the 'textwidth' option to 0.  Otherwise lines will unexpectedly be
  709.   split in two.
  710. - When there are not many <EOL>s, the lines will become very long.  If you
  711.   want to edit a line that does not fit on the screen reset the 'wrap' option.
  712.   Horizontal scrolling is used then.  If a line becomes too long (more than
  713.   about 32767 characters on the Amiga, much more on 32-bit systems, see
  714.   |limits|) you cannot edit that line.  The line will be split when reading
  715.   the file.  It is also possible that you get an "out of memory" error when
  716.   reading the file.
  717. - Make sure the 'binary' option is set BEFORE loading the
  718.   file.  Otherwise both <CR> <NL> and <NL> are considered to end a line
  719.   and when the file is written the <NL> will be replaced with <CR> <NL>.
  720. - <Nul> characters are shown on the screen as ^@.  You can enter them with
  721.   "CTRL-V CTRL-@" or "CTRL-V 000" {Vi cannot handle <Nul> characters in the
  722.   file}
  723. - To insert a <NL> character in the file split up a line.  When writing the
  724.   buffer to a file a <NL> will be written for the <EOL>.
  725. - Vim normally appends an <EOL> at the end of the file if there is none.
  726.   Setting the 'binary' option prevents this.  If you want to add the final
  727.   <EOL>, set the 'endofline' option.  You can also read the value of this
  728.   option to see if there was an <EOL> for the last line (you cannot see this
  729.   in the text).
  730.  
  731.  vim:tw=78:ts=8:sw=8:
  732.