2 .\" The Regents of the University of California. All rights reserved.
3 .\" Copyright (c) 1994, 1995, 1996
4 .\" Keith Bostic. All rights reserved.
6 .\" See the LICENSE file for redistribution information.
8 .\" @(#)set.opt.roff 8.66 (Berkeley) 10/10/96
12 There are a large number of options that may be set (or unset) to
13 change the editor's behavior.
14 This section describes the options, their abbreviations and their
17 In each entry below, the first part of the tag line is the full name
18 of the option, followed by any equivalent abbreviations.
19 (Regardless of the abbreviations, it is only necessary to use the
20 minimum number of characters necessary to distinguish an abbreviation
21 from all other commands for it to be accepted, in
23 Historically, only the full name and the official abbreviations
26 Using full names in your startup files and environmental variables will
27 probably make them more portable.)
28 The part in square brackets is the default value of the option.
29 Most of the options are boolean, i.e. they are either on or off,
30 and do not have an associated value.
36 modes, unless otherwise specified.
38 With a few exceptions,
39 all options are settable per screen, i.e. the
41 option can be set differently in each screen.
42 The exceptions are the
49 Changing these options modifies the respective information for all screens.
51 For information on modifying the options or to display the options and
52 their current values, see the
54 command in the section entitled
62 does word erase during text input.
63 When this option is set, text is broken up into three classes:
64 alphabetic, numeric and underscore characters, other nonblank
65 characters, and blank characters.
66 Changing from one class to another marks the end of a word.
67 In addition, the class of the first character erased is ignored
68 (which is exactly what you want when erasing pathname components).
70 .IP "autoindent, ai [off]"
71 If this option is set, whenever you create a new line (using the
92 commands) the new line is automatically indented to align the cursor with
93 the first nonblank character of the line from which you created it.
94 Lines are indented using tab characters to the extent possible (based on
97 option) and then using space characters as necessary.
98 For commands inserting text into the middle of a line, any blank characters
99 to the right of the cursor are discarded, and the first nonblank character
100 to the right of the cursor is aligned as described above.
102 The indent characters are themselves somewhat special.
103 If you do not enter more characters on the new line before moving to
104 another line, or entering
106 the indent character will be deleted and the line will be empty.
107 For example, if you enter
108 .LI <carriage-return>
110 the line created by the first
111 .LI <carriage-return>
112 will not have any characters in it,
113 regardless of the indentation of the previous or subsequent line.
115 Indent characters also require that you enter additional erase characters
118 if you have an indented line, containing only blanks, the first
120 character you enter will erase up to end of the indent characters,
121 and the second will erase back to the beginning of the line.
122 (Historically, only the
124 key would erase the indent characters.
127 key and the usual erase keys work in
129 In addition, if the cursor is positioned at the end of the indent
132 will erase all of the indent characters for the current line,
133 resetting the indentation level to 0.
136 will erase all of the indent characters for the current line,
137 leaving the indentation level for future created lines unaffected.
145 commands change from the first nonblank of the line to the end of the
146 line, instead of from the beginning of the line to the end of the line.
148 .IP "autoprint, ap [off]"
151 Cause the current line to be automatically displayed after the
165 This automatic display is suppressed during
169 commands, and for any command where optional flags are used to explicitly
172 .IP "autowrite, aw [off]"
173 If this option is set, the
191 commands automatically write the current file back to the current file name
192 if it has been modified since it was last written.
193 If the write fails, the command fails and goes no further.
195 Appending the optional force flag character
208 stops the automatic write from being attempted.
212 command ignored the optional force flag.)
229 option is ignored if the file is considered read-only for any reason.
230 .\" I cannot get a double quote to print between the square brackets
231 .\" to save my life. The ONLY way I've been able to get this to work
232 .\" is with the .tr command.
238 If this option is set, it specifies a pathname used as a backup file,
239 and, whenever a file is written, the file's current contents are copied
248 If the first character of the pathname is
250 a version number is appended to the pathname (and the
252 character is then discarded).
253 Version numbers are always incremented, and each backup file will have
254 a version number one greater than the highest version number currently
255 found in the directory.
257 Backup files must be regular files, owned by the real user ID of the
258 user running the editor, and not accessible by any other user.
260 .IP "beautify, bf [off]"
261 If this option is set, all control characters that are not currently being
262 specially interpreted, other than
268 discarded from commands read in by
270 from command files, and from input text entered to
272 (either into the file or to the colon command line).
281 .IP "cdpath [environment variable CDPATH, or current directory]"
282 This option is used to specify a colon separated list of directories
283 which are used as path prefixes for any relative path names used as
287 The value of this option defaults to the value of the environmental
290 if it is set, otherwise to the current directory.
291 For compatibility with the POSIX 1003.2 shell, the
295 check the current directory as a path prefix for relative path names
296 unless it is explicitly specified.
297 It may be so specified by entering an empty string or a
301 variable or the option value.
303 .IP "cedit [no default]"
304 This option adds the ability to edit the colon command-line history.
305 This option is set to a string.
306 Whenever the first character of that string is entered on the colon
308 you will enter a normal editing window on the collected commands that
309 you've entered on the
312 You may then modify and/or execute the commands.
313 All normal text editing is available,
314 except that you cannot use
316 to switch to an alternate screen.
318 .CO <carriage-return>
319 will execute the current line of the screen window as an ex command in
320 the context of the screen from which you created the colon command-line
322 and you will then return to that screen.
326 parsing rules, it can be difficult to set the colon command-line edit
333 .QT "set cedit=<literal-next><escape>" .
337 edit option is set to the same character as the
341 will perform colon command-line editing if the character is entered as
342 the first character of the line,
345 will perform file name expansion.
347 .IP "columns, co [80]"
348 The number of columns in the screen.
349 Setting this option causes
351 to set (or reset) the environmental variable
353 See the section entitled
354 .QB "Sizing the Screen"
360 If the first non-empty line of the file begins with the string
367 to skip to the end of that shell, C or C++ comment (probably a
368 terribly boring legal notice) before displaying the file.
370 .IP "directory, dir [environment variable TMPDIR, or /tmp]"
371 The directory where temporary files are created.
372 The environmental variable
374 is used as the default value if it exists, otherwise
378 .IP "edcompatible, ed [off]"
379 Remember the values of the
385 commands, instead of initializing them as unset for each new
387 Specifying pattern and replacement strings to the
396 The 10th's of a second
398 waits for a subsequent key to complete an
402 .IP "errorbells, eb [off]"
406 error messages are normally presented in inverse video.
407 If that is not possible for the terminal, setting this option causes
408 error messages to be announced by ringing the terminal bell.
411 If this option is turned on in the EXINIT environment variables,
412 or the system or $HOME startup files,
413 the local startup files are read,
414 unless they are the same as the system or $HOME startup files or
415 fail to pass the standard permission checks.
416 See the section entitled
417 .QB "Startup Information"
418 for more information.
421 This option causes all regular expressions to be treated as POSIX
422 1003.2 Extended Regular Expressions (which are similar to historic
426 .IP "filec [no default]"
427 This option adds the ability to do shell expansion when entering input
428 on the colon command line.
429 This option is set to a string.
430 Whenever the first character of that string is entered on the colon
432 the <blank> delimited string immediately before the cursor is expanded
433 as if it were followed by a
435 character, and file name expansion for the
437 edit command was done.
438 If no match is found, the screen is flashed and text input resumed.
439 If a single match results, that match replaces the expanded text.
440 In addition, if the single match is for a directory, a
442 character is appended and file completion is repeated.
443 If more than a single match results,
444 any unique prefix shared by the matches replaces the expanded text,
445 the matches are displayed,
446 and text input resumed.
450 parsing rules, it can be difficult to set the path completion character
451 to two command values,
458 .QT "set filec=<literal-next><escape>" .
462 .QT "set filec=\e<tab>" .
466 edit option is set to the same character as the
470 will perform colon command-line editing if the character is entered as
471 the first character of the line,
474 will perform file name expansion.
477 This option causes the screen to flash instead of beeping the keyboard,
478 on error, if the terminal has the capability.
480 .IP "hardtabs, ht [8]"
481 This option defines the spacing between hardware tab settings, i.e.
482 the tab expansion done by the operating system and/or the terminal
488 characters to the terminal, unlike historic versions of
490 this option does not currently have any affect.
495 edit option makes all Regular Expressions case-insensitive,
496 as long as an upper-case letter does not appear in the search string.
498 .IP "ignorecase, ic [off]"
499 This option causes regular expressions, both in
501 commands and in searches,
502 to be evaluated in a case-insensitive manner.
505 The 10th's of a second
507 waits for a subsequent key to complete a key mapping.
509 .IP "leftright [off]"
512 This option causes the screen to be scrolled left-right to view
513 lines longer than the screen, instead of the traditional
515 screen interface which folds long lines at the right-hand margin
521 The number of lines in the screen.
522 Setting this option causes
524 to set (or reset) the environmental variable
526 See the section entitled
527 .QB "Sizing the Screen"
528 for more information.
533 This option changes the behavior of the
542 commands to match the Lisp language.
545 option's behavior is changed to be appropriate for Lisp.
547 .i "This option is not yet implemented."
550 This option causes lines to be displayed in an unambiguous fashion.
551 Specifically, tabs are displayed as control characters, i.e.
553 and the ends of lines are marked with a
558 This option causes the editor to attempt to get an exclusive lock on
559 any file being edited, read or written.
560 Reading or writing a file that cannot be locked produces a warning
561 message, but no other effect.
562 Editing a file that cannot be locked results in a read only edit session,
565 edit option were set.
568 This option is on by default.
571 option off causes all regular expression characters except for
575 to be treated as ordinary characters.
576 To re-enable characters individually, when the
579 precede them with a backslash
582 See the section entitled
583 .QB "Regular Expressions and Replacement Strings"
584 for more information.
589 The 10th's of a second
591 pauses on the matching character when the
596 This option allows other users to contact you using the
600 utilities, while you are editing.
602 does not turn message on, i.e. if messages were turned off when the
603 editor was invoked, they will stay turned off.
604 This option only permits you to disallow messages for the edit session.
607 utility for more information.
610 This option selects a message catalog to be used to display error and
611 informational messages in a specified language.
612 If the value of this option ends with a '/', it is treated as the name
613 of a directory that contains a message catalog
619 environmental variable, if it's set, or the value of the
621 environmental variable if it's not.
622 If neither of those environmental variables are set,
623 or if the option doesn't end in a '/',
624 the option is treated as the full path name of the message catalog to use.
626 If any messages are missing from the catalog,
627 the backup text (English) is used instead.
629 See the distribution file
631 for additional information on building and installing message catalogs.
633 .IP "modelines, modeline [off]"
638 has historically scanned the first and last five lines of each file as
639 it is read for editing, looking for any
641 commands that have been placed in those lines.
642 After the startup information has been processed, and before the user
643 starts editing the file, any commands embedded in the file are executed.
645 Commands were recognized by the letters
653 at the beginning of a line or following a tab or space character,
661 This option is a security problem of immense proportions,
662 and should not be used under any circumstances.
664 .i "This option will never be implemented."
665 .\" I cannot get a double quote to print between the square brackets
666 .\" to save my life. The ONLY way I've been able to get this to work
667 .\" is with the .tr command.
673 Characters that are never handled as printable characters.
674 By default, the C library function
676 is used to determine if a character is printable or not.
677 This edit option overrides that decision.
679 .IP "number, nu [off]"
680 Precede each line displayed with its current line number.
683 Display unknown characters as octal numbers
685 instead of the default
692 If this option is not set, the
696 commands are disallowed.
698 .IP "optimize, opt [on]"
701 Throughput of text is expedited by setting the terminal not to do automatic
702 carriage returns when printing more than one (logical) line of output,
703 greatly speeding output on terminals without addressable cursors when text
704 with leading white space is printed.
706 .i "This option is not yet implemented."
708 .IP "paragraphs, para [IPLPPPQPP LIpplpipbp]"
711 Define additional paragraph boundaries for the
716 The value of this option must be a character string consisting
717 of zero or more character pairs.
719 In the text to be edited, the character string
720 .LI "<newline>.<char-pair>" ,
723 is one of the character pairs in the option's value)
724 defines a paragraph boundary.
725 For example, if the option were set to
727 then all of the following additional paragraph boundaries would be
737 The path option can be used to specify a <colon>-separated list of
738 paths, similar to the
740 environment variable in the shells.
741 If this option is set,
742 the name of the file to be edited is not an absolute pathname,
743 the first component of the filename is not
747 and the file to be edited doesn't exist in the current directory,
750 option are sequentially searched for a file of the specified name.
751 If such a file is found, it is edited.
752 .\" I cannot get a double quote to print between the square brackets
753 .\" to save my life. The ONLY way I've been able to get this to work
754 .\" is with the .tr command.
760 Characters that are always handled as printable characters.
761 By default, the C library function
763 is used to determine if a character is printable or not.
764 This edit option overrides that decision.
771 to prompt for command input with a
773 character; when it is not set, no prompt is displayed.
775 .IP "readonly, ro [off]"
776 This option causes a force flag to be required to attempt to write the file.
777 Setting this option is equivalent to using the
782 program using the name
787 edit option is not usually persistent, like other edit options.
790 command line option is set,
796 edit option is explicitly set,
797 all files edited in the screen will be marked readonly,
798 and the force flag will be required to write them.
799 However, if none of these conditions are true,
802 edit option is explicitly unset,
805 edit option will toggle based on the write permissions of the file currently
806 being edited as of when it is loaded into the edit buffer.
809 edit option will be set if the current file lacks write permissions,
810 and will not be set if the user has write permissions for the file.
812 .IP "recdir [/var/tmp/vi.recover]"
813 The directory where recovery files are stored.
815 If you change the value of
817 be careful to choose a directory whose contents are not regularly
819 Bad choices include directories in memory based filesystems,
823 as their contents are removed when the machine is rebooted.
825 Public directories like
829 are usually safe, although some sites periodically prune old files
831 There is no requirement that you use a public directory,
832 e.g. a sub-directory of your home directory will work fine.
834 Finally, if you change the value of
836 you must modify the recovery script to operate in your chosen recovery
839 See the section entitled
841 for further information.
843 .IP "redraw, re [off]"
846 The editor simulates (using great amounts of output), an intelligent
847 terminal on a dumb terminal (e.g. during insertions in
849 the characters to the right of the cursor are refreshed as each input
852 .i "This option is not yet implemented."
855 If this option is set,
856 it is possible to define macros in terms of other macros.
857 Otherwise, each key is only remapped up to one time.
872 option is set, and to
877 Set the threshold of the number of lines that need to be changed or
878 yanked before a message will be displayed to the user.
879 For everything but the yank command, the value is the largest value
880 about which the editor is silent, i.e. by default, 6 lines must be
881 deleted before the user is notified.
882 However, if the number of lines yanked is greater than
884 the set value, it is reported to the user.
889 Display a row/column ruler on the colon command line.
891 .IP "scroll, scr [(environment variable LINES - 1) / 2]"
892 Set the number of lines scrolled by the
902 command, when specified without a count, used two times the size of the
903 scroll value; the POSIX 1003.2 standard specified the window size, which
906 .IP "searchincr [off]"
909 edit option makes the search commands
913 incremental, i.e. the screen is updated and the cursor moves to the matching
914 text as the search pattern is entered.
915 If the search pattern is not found,
916 the screen is beeped and the cursor remains on the colon-command line.
917 Erasing characters from the search pattern backs the cursor up to the
918 previous matching text.
920 .IP "sections, sect [NHSHH HUnhsh]"
923 Define additional section boundaries for the
930 option should be set to a character string consisting of zero or
931 more character pairs.
932 In the text to be edited, the character string
933 .LI "<newline>.<char-pair>" ,
936 is one of the character pairs in the option's value),
937 defines a section boundary in the same manner that
939 option boundaries are defined.
944 edit option turns off all access to external programs.
945 This means that the versions of the
949 commands that filter text through other programs,
964 commands and file name expansion will not be permitted.
968 edit option may not be unset.
970 .IP "shell, sh [environment variable SHELL, or /bin/sh]"
971 Select the shell used by the editor.
972 The specified path is the pathname of the shell invoked by the
975 shell escape command and by the
979 This program is also used to resolve any shell meta-characters in
982 .\" I cannot get a double quote to print between the square brackets
983 .\" to save my life. The ONLY way I've been able to get this to work
984 .\" is with the .tr command.
986 .ds ms shellmeta [~{[*?$`'Q\e]
990 The set of characters that
992 checks for when doing file name expansion.
993 If any of the specified characters are found in the file name arguments
997 the arguments are expanded using the program defined by the
1000 The default set of characters is a union of meta characters
1001 from the Version 7 and the Berkeley C shell.
1003 .IP "shiftwidth, sw [8]"
1004 Set the autoindent and shift command indentation width.
1005 This width is used by the
1014 .IP "showmatch, sm [off]"
1023 is entered, to briefly move the cursor the matching
1029 option for more information.
1031 .IP "showmode, smd [off]"
1036 to display a string identifying the current editor mode on the colon
1038 The string is preceded by an asterisk (``*'') if the file has been
1039 modified since it was last completely written,
1041 .IP "sidescroll [16]"
1044 Sets the number of columns that are shifted to the left or right,
1047 is doing left-right scrolling and the left or right margin is
1051 option for more information.
1053 .IP "slowopen, slow [off]"
1054 This option affects the display algorithm used by
1056 holding off display updating during input of new text to improve
1057 throughput when the terminal in use is slow and unintelligent.
1059 .i "This option is not yet implemented."
1061 .IP "sourceany [off]"
1062 If this option is turned on,
1064 historically read startup files that were owned by someone other than
1066 See the section entitled
1067 .QB "Startup Information"
1068 for more information.
1069 This option is a security problem of immense proportions,
1070 and should not be used under any circumstances.
1072 .i "This option will never be implemented."
1074 .IP "tabstop, ts [8]"
1075 This option sets tab widths for the editor display.
1077 .IP "taglength, tl [0]"
1078 This option sets the maximum number of characters that are considered
1079 significant in a tag name.
1080 Setting the value to 0 makes all of the characters in the tag name
1083 .IP "tags, tag [tags /var/db/libc.tags /sys/kern/tags]"
1084 Sets the list of tags files, in search order,
1085 which are used when the editor searches for a tag.
1087 .IP "term, ttytype, tty [environment variable TERM]"
1088 Set the terminal type.
1089 Setting this option causes
1091 to set (or reset) the environmental variable
1095 This option has historically made editor messages less verbose.
1096 It has no effect in this implementation.
1099 option for more information.
1104 command to take an associated motion.
1106 .IP "timeout, to [on]"
1107 If this option is set,
1109 waits for a specific period for a subsequent key to complete a key
1113 If the option is not set, the editor waits until enough keys are
1114 entered to resolve the ambiguity, regardless of how long it takes.
1116 .IP "ttywerase [off]"
1119 This option changes how
1121 does word erase during text input.
1122 If this option is set, text is broken up into two classes,
1123 blank characters and nonblank characters.
1124 Changing from one class to another marks the end of a word.
1130 historically bells the terminal for many obvious mistakes, e.g. trying
1131 to move past the left-hand margin, or past the end of the file.
1132 If this option is set, an error message is displayed for all errors.
1134 .IP "w300 [no default]"
1137 Set the window size if the baud rate is less than 1200 baud.
1140 option for more information.
1142 .IP "w1200 [no default]"
1145 Set the window size if the baud rate is equal to 1200 baud.
1148 option for more information.
1150 .IP "w9600 [no default]"
1153 Set the window size if the baud rate is greater than 1200 baud.
1156 option for more information.
1161 This option causes a warning message to the terminal if the file has
1162 been modified, since it was last written, before a
1166 .IP "window, w, wi [environment variable LINES - 1]"
1167 This option determines the default number of lines in a screenful,
1171 It also determines the number of lines scrolled by the
1177 and the default number of lines scrolled by the
1183 The value of window can be unrelated to the real screen size,
1184 although it starts out as the number of lines on the screen.
1185 See the section entitled
1186 .QB "Sizing the Screen"
1187 for more information.
1188 Setting the value of the
1190 option is the same as using the
1192 command line option.
1196 option (as set by the
1202 options) is smaller than the actual size of the screen,
1203 large screen movements will result in displaying only that smaller
1204 number of lines on the screen.
1205 (Further movements in that same area will result in the screen being
1207 This can provide a performance improvement when viewing different
1208 places in one or more files over a slow link.
1210 Resetting the window size does not reset the default number of lines
1217 .IP "windowname [off]"
1219 changes the name of the editor's icon/window to the current file name
1220 when it's possible and not destructive, i.e.,
1221 when the editor can restore it to its original value on exit or when
1222 the icon/window will be discarded as the editor exits.
1227 will change the icon/window name even when it's destructive and the
1228 icon/window name will remain after the editor exits.
1229 (This is the case for
1232 .IP "wraplen, wl [0]"
1233 This option is identical to the
1235 option, with the exception that it specifies the number of columns
1238 margin before the line splits, not the right margin.
1248 .IP "wrapmargin, wm [0]"
1255 will split lines so that they end at least that number of columns
1256 before the right-hand margin of the screen.
1262 In a screen that is 80 columns wide, the command
1263 .QT ":set wrapmargin=8"
1264 attempts to keep the lines less than or equal to 72 columns wide.)
1266 Lines are split at the previous whitespace character closest to the
1268 Any trailing whitespace characters before that character are deleted.
1269 If the line is split because of an inserted
1273 character, and you then enter another
1275 character, it is discarded.
1277 If wrapmargin is set to 0,
1278 or if there is no blank character upon which to split the line,
1279 the line is not broken.
1289 .IP "wrapscan, ws [on]"
1290 This option causes searches to wrap around the end or the beginning
1291 of the file, and back to the starting point.
1292 Otherwise, the end or beginning of the file terminates the search.
1294 .IP "writeany, wa [off]"
1295 If this option is set, file-overwriting checks that would usually be
1300 commands, or before an automatic write (see the
1302 option), are not made.
1303 This allows a write to any file, provided the file permissions allow it.
nant's projects / dragonfly.git / blob