summaryrefslogtreecommitdiffstats
path: root/runtime/doc/usr_23.txt
diff options
context:
space:
mode:
Diffstat (limited to 'runtime/doc/usr_23.txt')
-rw-r--r--runtime/doc/usr_23.txt345
1 files changed, 345 insertions, 0 deletions
diff --git a/runtime/doc/usr_23.txt b/runtime/doc/usr_23.txt
new file mode 100644
index 0000000..016f742
--- /dev/null
+++ b/runtime/doc/usr_23.txt
@@ -0,0 +1,345 @@
+*usr_23.txt* For Vim version 9.1. Last change: 2020 Dec 19
+
+ VIM USER MANUAL - by Bram Moolenaar
+
+ Editing other files
+
+
+This chapter is about editing files that are not ordinary files. With Vim you
+can edit files that are compressed or encrypted. Some files need to be
+accessed over the internet. With some restrictions, binary files can be
+edited as well.
+
+|23.1| DOS, Mac and Unix files
+|23.2| Files on the internet
+|23.3| Encryption
+|23.4| Binary files
+|23.5| Compressed files
+
+ Next chapter: |usr_24.txt| Inserting quickly
+ Previous chapter: |usr_22.txt| Finding the file to edit
+Table of contents: |usr_toc.txt|
+
+==============================================================================
+*23.1* DOS, Mac and Unix files
+
+Back in the early days, the old Teletype machines used two characters to
+start a new line. One to move the carriage back to the first position
+(carriage return, <CR>), another to move the paper up (line feed, <LF>).
+ When computers came out, storage was expensive. Some people decided that
+they did not need two characters for end-of-line. The UNIX people decided
+they could use <New Line> or <NL> only for end-of-line. The Apple people
+standardized on <CR>. The Microsoft Windows folks decided to keep the old
+<CR><NL> (we use <NL> for line feed in the help text).
+ This means that if you try to move a file from one system to another, you
+have line-break problems. The Vim editor automatically recognizes the
+different file formats and handles things properly behind your back.
+ The option 'fileformats' contains the various formats that will be tried
+when a new file is edited. The following command, for example, tells Vim to
+try UNIX format first and MS-DOS format second: >
+
+ :set fileformats=unix,dos
+
+You will notice the format in the message you get when editing a file. You
+don't see anything if you edit a native file format. Thus editing a Unix file
+on Unix won't result in a remark. But when you edit a dos file, Vim will
+notify you of this:
+
+ "/tmp/test" [dos] 3L, 71C ~
+
+For a Mac file you would see "[mac]".
+ The detected file format is stored in the 'fileformat' option. To see
+which format you have, execute the following command: >
+
+ :set fileformat?
+
+The three names that Vim uses are:
+
+ unix <NL>
+ dos <CR><NL>
+ mac <CR>
+
+
+USING THE MAC FORMAT
+
+On Unix, <NL> is used to break a line. It's not unusual to have a <CR>
+character halfway a line. Incidentally, this happens quite often in Vi (and
+Vim) scripts.
+ On the Macintosh, where <CR> is the line break character, it's possible to
+have a <NL> character halfway a line.
+ The result is that it's not possible to be 100% sure whether a file
+containing both <CR> and <NL> characters is a Mac or a Unix file. Therefore,
+Vim assumes that on Unix you probably won't edit a Mac file, and doesn't check
+for this type of file. To check for this format anyway, add "mac" to
+'fileformats': >
+
+ :set fileformats+=mac
+
+Then Vim will take a guess at the file format. Watch out for situations where
+Vim guesses wrong.
+
+
+OVERRULING THE FORMAT
+
+If you use the good old Vi and try to edit an MS-DOS format file, you will
+find that each line ends with a ^M character. (^M is <CR>). The automatic
+detection avoids this. Suppose you do want to edit the file that way? Then
+you need to overrule the format: >
+
+ :edit ++ff=unix file.txt
+
+The "++" string is an item that tells Vim that an option name follows, which
+overrules the default for this single command. "++ff" is used for
+'fileformat'. You could also use "++ff=mac" or "++ff=dos".
+ This doesn't work for any option, only "++ff" and "++enc" are currently
+implemented. The full names "++fileformat" and "++encoding" also work.
+
+
+CONVERSION
+
+You can use the 'fileformat' option to convert from one file format to
+another. Suppose, for example, that you have an MS-DOS file named README.TXT
+that you want to convert to UNIX format. Start by editing the MS-DOS format
+file: >
+ vim README.TXT
+
+Vim will recognize this as a dos format file. Now change the file format to
+UNIX: >
+
+ :set fileformat=unix
+ :write
+
+The file is written in Unix format.
+
+==============================================================================
+*23.2* Files on the internet
+
+Someone sends you an e-mail message, which refers to a file by its URL. For
+example:
+
+ You can find the information here: ~
+ ftp://ftp.vim.org/pub/vim/README ~
+
+You could start a program to download the file, save it on your local disk and
+then start Vim to edit it.
+ There is a much simpler way. Move the cursor to any character of the URL.
+Then use this command: >
+
+ gf
+
+With a bit of luck, Vim will figure out which program to use for downloading
+the file, download it and edit the copy. To open the file in a new window use
+CTRL-W f.
+ If something goes wrong you will get an error message. It's possible that
+the URL is wrong, you don't have permission to read it, the network connection
+is down, etc. Unfortunately, it's hard to tell the cause of the error. You
+might want to try the manual way of downloading the file.
+
+Accessing files over the internet works with the netrw plugin. Currently URLs
+with these formats are recognized:
+
+ ftp:// uses ftp
+ rcp:// uses rcp
+ scp:// uses scp
+ http:// uses wget (reading only)
+
+Vim doesn't do the communication itself, it relies on the mentioned programs
+to be available on your computer. On most Unix systems "ftp" and "rcp" will
+be present. "scp" and "wget" might need to be installed.
+
+Vim detects these URLs for each command that starts editing a new file, also
+with ":edit" and ":split", for example. Write commands also work, except for
+http://.
+
+For more information, also about passwords, see |netrw|.
+
+==============================================================================
+*23.3* Encryption
+
+Some information you prefer to keep to yourself. For example, when writing
+a test on a computer that students also use. You don't want clever students
+to figure out a way to read the questions before the exam starts. Vim can
+encrypt the file for you, which gives you some protection.
+ To start editing a new file with encryption, use the "-x" argument to start
+Vim. Example: >
+
+ vim -x exam.txt
+
+Vim prompts you for a key used for encrypting and decrypting the file:
+
+ Enter encryption key: ~
+
+Carefully type the secret key now. You cannot see the characters you type,
+they will be replaced by stars. To avoid the situation that a typing mistake
+will cause trouble, Vim asks you to enter the key again:
+
+ Enter same key again: ~
+
+You can now edit this file normally and put in all your secrets. When you
+finish editing the file and tell Vim to exit, the file is encrypted and
+written.
+ When you edit the file with Vim, it will ask you to enter the same key
+again. You don't need to use the "-x" argument. You can also use the normal
+":edit" command. Vim adds a magic string to the file by which it recognizes
+that the file was encrypted.
+ If you try to view this file using another program, all you get is garbage.
+Also, if you edit the file with Vim and enter the wrong key, you get garbage.
+Vim does not have a mechanism to check if the key is the right one (this makes
+it much harder to break the key).
+
+
+SWITCHING ENCRYPTION ON AND OFF
+
+To disable the encryption of a file, set the 'key' option to an empty string:
+>
+ :set key=
+
+The next time you write the file this will be done without encryption.
+ Setting the 'key' option to enable encryption is not a good idea, because
+the password appears in the clear. Anyone shoulder-surfing can read your
+password.
+ To avoid this problem, the ":X" command was created. It asks you for an
+encryption key, just like the "-x" argument did: >
+
+ :X
+ Enter encryption key: ******
+ Enter same key again: ******
+
+
+LIMITS ON ENCRYPTION
+
+The encryption algorithm used by Vim is not very strong. It is good enough to
+keep out the casual prowler, but not good enough to keep out a cryptology
+expert with lots of time on his hands. The text in the swap file and the undo
+file is also encrypted. However, this is done block-by-block and may reduce
+the time needed to crack a password. You can disable the swap file, but then
+a crash will cause you to lose your work, since Vim keeps all the text in
+memory only. The undo file can be disabled with the only disadvantage that
+you can't undo after unloading the buffer.
+ To avoid using a swap file, supply the -n argument on the command line.
+For example, to edit the encrypted file "file.txt" without a swap file use the
+following command: >
+
+ vim -x -n file.txt
+
+When already editing a file, the swapfile can be disabled with: >
+
+ :setlocal noswapfile
+
+Since there is no swapfile, recovery will be impossible. Save the file a bit
+more often to avoid the risk of losing your changes.
+
+While the file is in memory, it is in plain text. Anyone with privilege can
+look in the editor's memory and discover the contents of the file.
+ If you use a viminfo file, be aware that the contents of text registers are
+written out in the clear as well.
+ If you really want to secure the contents of a file, edit it only on a
+portable computer not connected to a network, use good encryption tools, and
+keep the computer locked up in a big safe when not in use.
+
+==============================================================================
+*23.4* Binary files
+
+You can edit binary files with Vim. Vim wasn't really made for this, thus
+there are a few restrictions. But you can read a file, change a character and
+write it back, with the result that only that one character was changed and
+the file is identical otherwise.
+ To make sure that Vim does not use its clever tricks in the wrong way, add
+the "-b" argument when starting Vim: >
+
+ vim -b datafile
+
+This sets the 'binary' option. The effect of this is that unexpected side
+effects are turned off. For example, 'textwidth' is set to zero, to avoid
+automatic formatting of lines. And files are always read in Unix file format.
+
+Binary mode can be used to change a message in a program. Be careful not to
+insert or delete any characters, it would stop the program from working. Use
+"R" to enter replace mode.
+
+Many characters in the file will be unprintable. To see them in Hex format: >
+
+ :set display=uhex
+
+Otherwise, the "ga" command can be used to see the value of the character
+under the cursor. The output, when the cursor is on an <Esc>, looks like
+this:
+
+ <^[> 27, Hex 1b, Octal 033 ~
+
+There might not be many line breaks in the file. To get some overview switch
+the 'wrap' option off: >
+
+ :set nowrap
+
+
+BYTE POSITION
+
+To see on which byte you are in the file use this command: >
+
+ g CTRL-G
+
+The output is verbose:
+
+ Col 9-16 of 9-16; Line 277 of 330; Word 1806 of 2058; Byte 10580 of 12206 ~
+
+The last two numbers are the byte position in the file and the total number of
+bytes. This takes into account how 'fileformat' changes the number of bytes
+that a line break uses.
+ To move to a specific byte in the file, use the "go" command. For
+example, to move to byte 2345: >
+
+ 2345go
+
+
+USING XXD
+
+A real binary editor shows the text in two ways: as it is and in hex format.
+You can do this in Vim by first converting the file with the "xxd" program.
+This comes with Vim.
+ First edit the file in binary mode: >
+
+ vim -b datafile
+
+Now convert the file to a hex dump with xxd: >
+
+ :%!xxd
+
+The text will look like this:
+
+ 0000000: 1f8b 0808 39d7 173b 0203 7474 002b 4e49 ....9..;..tt.+NI ~
+ 0000010: 4b2c 8660 eb9c ecac c462 eb94 345e 2e30 K,.`.....b..4^.0 ~
+ 0000020: 373b 2731 0b22 0ca6 c1a2 d669 1035 39d9 7;'1.".....i.59. ~
+
+You can now view and edit the text as you like. Vim treats the information as
+ordinary text. Changing the hex does not cause the printable character to be
+changed, or the other way around.
+ Finally convert it back with:
+>
+ :%!xxd -r
+
+Only changes in the hex part are used. Changes in the printable text part on
+the right are ignored.
+
+See the manual page of xxd for more information.
+
+==============================================================================
+*23.5* Compressed files
+
+This is easy: You can edit a compressed file just like any other file. The
+"gzip" plugin takes care of decompressing the file when you edit it. And
+compressing it again when you write it.
+ These compression methods are currently supported:
+
+ .Z compress
+ .gz gzip
+ .bz2 bzip2
+
+Vim uses the mentioned programs to do the actual compression and
+decompression. You might need to install the programs first.
+
+==============================================================================
+
+Next chapter: |usr_24.txt| Inserting quickly
+
+Copyright: see |manual-copyright| vim:tw=78:ts=8:noet:ft=help:norl: