*usr_05.txt* For MNV version 10.0. Last change: 2026 Feb 14 MNV USER MANUAL by Bram Moolenaar Set your settings MNV can be tuned to work like you want it to. This chapter shows you how to make MNV start with options set to different values. Add plugins to extend MNV's capabilities. Or define your own macros. |05.1| The mnvrc file |05.2| The example mnvrc file explained |05.3| The defaults.mnv file explained |05.4| Simple mappings |05.5| Adding a package |05.6| Adding a plugin |05.7| Adding a help file |05.8| The option window |05.9| Often used options Next chapter: |usr_06.txt| Using syntax highlighting Previous chapter: |usr_04.txt| Making small changes Table of contents: |usr_toc.txt| ============================================================================== *05.1* The mnvrc file *mnvrc-intro* You probably got tired of typing commands that you use very often. To start MNV with all your favorite option settings and mappings, you write them in what is called the mnvrc file. MNV executes the commands in this file when it starts up. If you already have a mnvrc file (e.g., when your sysadmin has one setup for you), you can edit it this way: > :edit $MYMNVRC If you don't have a mnvrc file yet, see |mnvrc| to find out where you can create a mnvrc file. Also, the ":version" command mentions the name of the "user mnvrc file" MNV looks for. For Unix and Macintosh this file is always used and is recommended: ~/.mnvrc ~ For MS-Windows you can use one of these: $HOME/_mnvrc ~ $MNV/_mnvrc ~ If you are creating the mnvrc file for the first time, it is recommended to put this line at the top: > source $MNVRUNTIME/defaults.mnv This initializes MNV for new users (as opposed to traditional Vi users). See |defaults.mnv| for the details. The mnvrc file can contain all the commands that you type after a colon. The simplest ones are for setting options. For example, if you want MNV to always start with the 'incsearch' option on, add this line your mnvrc file: > set incsearch For this new line to take effect you need to exit MNV and start it again. Later you will learn how to do this without exiting MNV. This chapter only explains the most basic items. For more information on how to write a MNV script file: |usr_41.txt|. ============================================================================== *05.2* The example mnvrc file explained *mnvrc_example.mnv* In the first chapter was explained how the example mnvrc (included in the MNV distribution) file can be used to make MNV startup in not-compatible mode (see |not-compatible|). The file can be found here: $MNVRUNTIME/mnvrc_example.mnv ~ In this section we will explain the various commands used in this file. This will give you hints about how to set up your own preferences. Not everything will be explained though. Use the ":help" command to find out more. > " Get the defaults that most users want. source $MNVRUNTIME/defaults.mnv This loads the "defaults.mnv" file in the $MNVRUNTIME directory. This sets up MNV for how most users like it. If you are one of the few that don't, then comment out this line. The commands are explained below: |defaults.mnv-explained| > if has("vms") set nobackup else set backup if has('persistent_undo') set undofile endif endif This tells MNV to keep a backup copy of a file when overwriting it. But not on the VMS system, since it keeps old versions of files already. The backup file will have the same name as the original file with "~" added. See |07.4| This also sets the 'undofile' option, if available. This will store the multi-level undo information in a file. The result is that when you change a file, exit MNV, and then edit the file again, you can undo the changes made previously. It's a very powerful and useful feature, at the cost of storing a file. For more information see |undo-persistence|. The "if" command is very useful to set options only when some condition is met. More about that in |usr_41.txt|. > if &t_Co > 2 || has("gui_running") set hlsearch endif This switches on the 'hlsearch' option, telling MNV to highlight matches with the last used search pattern. > augroup mnvrcEx au! autocmd FileType text setlocal textwidth=78 augroup END This makes MNV break text to avoid lines getting longer than 78 characters. But only for files that have been detected to be plain text. There are actually two parts here. "autocmd FileType text" is an autocommand. This defines that when the file type is set to "text" the following command is automatically executed. "setlocal textwidth=78" sets the 'textwidth' option to 78, but only locally in one file. The wrapper with "augroup mnvrcEx" and "augroup END" makes it possible to delete the autocommand with the "au!" command. See |:augroup|. > if has('syntax') && has('eval') packadd! matchit endif This loads the "matchit" plugin if the required features are available. It makes the |%| command more powerful. This is explained at |matchit-install|. ============================================================================== *05.3* The defaults.mnv file explained *defaults.mnv-explained* The |defaults.mnv| file is loaded when the user has no mnvrc file. When you create a new mnvrc file, add this line near the top to keep using it: > source $MNVRUNTIME/defaults.mnv Or use the mnvrc_example.mnv file, as explained above. The following explains what defaults.mnv is doing. > if exists('skip_defaults_mnv') finish endif Loading defaults.mnv can be disabled with this command: > let skip_defaults_mnv = 1 This has to be done in the system mnvrc file. See |system-mnvrc|. If you have a user mnvrc this is not needed, since defaults.mnv will not be loaded automatically. > set nocompatible As mentioned in the first chapter, these manuals explain MNV working in an improved way, thus not completely Vi compatible. Setting the 'compatible' option off, thus 'nocompatible' takes care of this. > set backspace=indent,eol,start This specifies where in Insert mode the is allowed to delete the character in front of the cursor. The three items, separated by commas, tell MNV to delete the white space at the start of the line, a line break and the character before where Insert mode started. See 'backspace'. > set history=200 Keep 200 commands and 200 search patterns in the history. Use another number if you want to remember fewer or more lines. See 'history'. > set ruler Always display the current cursor position in the lower right corner of the MNV window. See 'ruler'. > set showcmd Display an incomplete command in the lower right corner of the MNV window, left of the ruler. For example, when you type "2f", MNV is waiting for you to type the character to find and "2f" is displayed. When you press "w" next, the "2fw" command is executed and the displayed "2f" is removed. +-------------------------------------------------+ |text in the MNV window | |~ | |~ | |-- VISUAL -- 2f 43,8 17% | +-------------------------------------------------+ ^^^^^^^^^^^ ^^^^^^^^ ^^^^^^^^^^ 'showmode' 'showcmd' 'ruler' > set wildmenu Display completion matches in a status line. That is when you type and there is more than one match. See 'wildmenu'. > set ttimeout set ttimeoutlen=100 This makes typing Esc take effect more quickly. Normally MNV waits a second to see if the Esc is the start of an escape sequence. If you have a very slow remote connection, increase the number. See 'ttimeout'. > set display=truncate Show @@@ in the last line if it is truncated, instead of hiding the whole line. See 'display'. > set incsearch Display the match for a search pattern when halfway typing it. See 'incsearch'. > set nrformats-=octal Do not recognize numbers starting with a zero as octal. See 'nrformats'. > map Q gq This defines a key mapping. More about that in the next section. This defines the "Q" command to do formatting with the "gq" operator. This is how it worked before MNV 5.0. Otherwise the "Q" command starts Ex mode, but you will not need it. > inoremap u CTRL-U in insert mode deletes all entered text in the current line. Use CTRL-G u to first break undo, so that you can undo CTRL-U after inserting a line break. Revert with ":iunmap ". > if has('mouse') set mouse=a endif Enable using the mouse if available. See 'mouse'. > vnoremap _g y:exe "grep /" .. escape(@", '\\/') .. "/ *.c *.h" This mapping yanks the visually selected text and searches for it in C files. You can see that a mapping can be used to do quite complicated things. Still, it is just a sequence of commands that are executed like you typed them. > syntax on Enable highlighting files in color. See |syntax|. *mnvrc-filetype* > filetype plugin indent on This switches on three very clever mechanisms: 1. Filetype detection. Whenever you start editing a file, MNV will try to figure out what kind of file this is. When you edit "main.c", MNV will see the ".c" extension and recognize this as a "c" filetype. When you edit a file that starts with "#!/bin/sh", MNV will recognize it as a "sh" filetype. The filetype detection is used for syntax highlighting and the other two items below. See |filetypes|. 2. Using filetype plugin files Many different filetypes are edited with different options. For example, when you edit a "c" file, it's very useful to set the 'cindent' option to automatically indent the lines. These commonly useful option settings are included with MNV in filetype plugins. You can also add your own, see |write-filetype-plugin|. 3. Using indent files When editing programs, the indent of a line can often be computed automatically. MNV comes with these indent rules for a number of filetypes. See |:filetype-indent-on| and 'indentexpr'. *restore-cursor* *last-position-jump* >mnv augroup RestoreCursor autocmd! autocmd BufReadPost * \ let line = line("'\"") \ | if line >= 1 && line <= line("$") && &filetype !~# 'commit' \ && index(['xxd', 'gitrebase'], &filetype) == -1 \ && !&diff \ | execute "normal! g`\"" \ | endif augroup END Another autocommand. This time it is used after reading any file. The complicated stuff after it checks if the '" mark is defined, and jumps to it if so. It doesn't do that when: - editing a commit or rebase message, which are likely a different one than last time, - using xxd(1) to filter and edit binary files, which transforms input files back and forth, causing them to have dual nature, so to speak (see also |using-xxd|) and - MNV is in diff mode The backslash at the start of a line is used to continue the command from the previous line. That avoids a line getting very long. See |line-continuation|. This only works in a MNV script file, not when typing commands at the command line. > command DiffOrig vert new | set bt=nofile | r ++edit # | 0d_ \ | diffthis | wincmd p | diffthis This adds the ":DiffOrig" command. Use this in a modified buffer to see the differences with the file it was loaded from. See |diff| and |:DiffOrig|. > set nolangremap Prevent that the langmap option applies to characters that result from a mapping. If set (default), this may break plugins (but it's backward compatible). See 'langremap'. ============================================================================== *05.4* Simple mappings A mapping enables you to bind a set of MNV commands to a single key. Suppose, for example, that you need to surround certain words with curly braces. In other words, you need to change a word such as "amount" into "{amount}". With the :map command, you can tell MNV that the F5 key does this job. The command is as follows: > :map i{ea} < Note: When entering this command, you must enter by typing four characters. Similarly, is not entered by pressing the key, but by typing five characters. Watch out for this difference when reading the manual! Let's break this down: The F5 function key. This is the trigger key that causes the command to be executed as the key is pressed. i{ Insert the { character. The key ends Insert mode. e Move to the end of the word. a} Append the } to the word. After you execute the ":map" command, all you have to do to put {} around a word is to put the cursor on the first character and press F5. In this example, the trigger is a single key; it can be any string. But when you use an existing MNV command, that command will no longer be available. You better avoid that. One key that can be used with mappings is the backslash. Since you probably want to define more than one mapping, add another character. You could map "\p" to add parentheses around a word, and "\c" to add curly braces, for example: > :map \p i(ea) :map \c i{ea} You need to type the \ and the p quickly after another, so that MNV knows they belong together. The ":map" command (with no arguments) lists your current mappings. At least the ones for Normal mode. More about mappings in section |40.1|. ============================================================================== *05.5* Adding a package *add-package* A package is a set of files that you can add to MNV. There are two kinds of packages: optional and automatically loaded on startup. The MNV distribution comes with a few packages that you can optionally use. ------------------------------------------------------------------------------ Adding the matchit package *matchit-install* *package-matchit* ------------------------------------------------------------------------------ For example, the matchit package This plugin makes the "%" command jump to matching HTML tags, if/else/endif in MNV scripts, etc. Very useful, although it's not backwards compatible (that's why it is not enabled by default). To start using the matchit plugin, add one line to your mnvrc file: > packadd! matchit That's all! After restarting MNV you can find help about this plugin: > :help matchit This works, because when `:packadd` loaded the plugin it also added the package directory in 'runtimepath', so that the help file can be found. You can find packages on the Internet in various places. It usually comes as an archive or as a repository. For an archive you can follow these steps: 1. create the package directory: > mkdir -p ~/.mnv/pack/fancy < "fancy" can be any name of your liking. Use one that describes the package. 2. unpack the archive in that directory. This assumes the top directory in the archive is "start": > cd ~/.mnv/pack/fancy unzip /tmp/fancy.zip < If the archive layout is different make sure that you end up with a path like this: ~/.mnv/pack/fancy/start/fancytext/plugin/fancy.mnv ~ Here "fancytext" is the name of the package, it can be anything else. ------------------------------------------------------------------------------ Adding the editorconfig package *editorconfig-install* *package-editorconfig* ------------------------------------------------------------------------------ Similar to the matchit package, to load the distributed editorconfig plugin when MNV starts, add the following line to your mnvrc file: > packadd! editorconfig After restarting your MNV, the plugin is active and you can read about it at: > :h editorconfig.txt ------------------------------------------------------------------------------ Adding the comment package *comment-install* *package-comment* ------------------------------------------------------------------------------ Load the plugin with this command: > packadd comment < This way you can use the plugin with the default key bindings `gc` and similar for commenting (which is a well-established mapping in the MNV community). If you add this line to your mnvrc file, then you need to restart MNV to have the package loaded. Once the package is loaded, read about it at: > :h comment.txt ------------------------------------------------------------------------------ Adding the nohlsearch package *nohlsearch-install* *package-nohlsearch* ------------------------------------------------------------------------------ Load the plugin with this command: > packadd nohlsearch < Automatically execute |:nohlsearch| after 'updatetime' or getting into |Insert| mode. Thus assuming default updatetime, hlsearch would be suspended/turned off after 4 seconds of idle time. To disable the effect of the plugin after it has been loaded: > au! nohlsearch < ------------------------------------------------------------------------------ Adding the highlight-yank package *hlyank-install* *package-hlyank* ------------------------------------------------------------------------------ Load the plugin with this command: > packadd hlyank < This package briefly highlights the affected region of the last |yank| command. See |52.6| for a simplified implementation using the |getregionpos()| function. The plugin understands the following configuration variables (the settings show the default values). To specify a different highlighting group, use: > :let g:hlyank_hlgroup = 'IncSearch' < To use a different highlighting duration, use: > :let g:hlyank_duration = 300 The unit is milliseconds, and the upper limit is 3000 ms. If you set a value higher than this, the highlighting duration will be 3000 ms. To highlight in visual mode, use: > :let g:hlyank_invisual = v:true To disable the effect of the plugin after it has been loaded: > au! hlyank ------------------------------------------------------------------------------ Adding the osc52 package *osc52-install* *package-osc52* ------------------------------------------------------------------------------ Load the plugin with this command: > packadd osc52 < The osc52.mnv package provides support for the OSC 52 terminal command, which allows an application to access the clipboard by communicating directly with your terminal. Once the package is loaded, read about it at: > :h osc52.txt More information about packages can be found here: |packages|. ============================================================================== *05.6* Adding a plugin *add-plugin* *plugin* MNV's functionality can be extended by adding plugins. A plugin is nothing more than a MNV script file that is loaded automatically when MNV starts. You can add a plugin very easily by dropping it in your plugin directory. {not available when MNV was compiled without the |+eval| feature} There are two types of plugins: global plugin: Used for all kinds of files filetype plugin: Only used for a specific type of file The global plugins will be discussed first, then the filetype ones |add-filetype-plugin|. GLOBAL PLUGINS *standard-plugin* *distributed-plugins* When you start MNV, it will automatically load a number of global plugins. You don't have to do anything for this. They add functionality that most people will want to use, but which was implemented as a MNV script instead of being compiled into MNV. You can find them listed in the help index |standard-plugin-list|. For locally installed plugins and packages (which come with a separated help file) a similar list can be found in the help section |local-additions|. Also see |load-plugins|. *add-global-plugin* You can add a global plugin to add functionality that will always be present when you use MNV. There are only two steps for adding a global plugin: 1. Get a copy of the plugin. 2. Drop it in the right directory. GETTING A GLOBAL PLUGIN Where can you find plugins? - Some are always loaded, you can see them in the directory $MNVRUNTIME/plugin. - Some come with MNV. You can find them in the directory $MNVRUNTIME/macros and its sub-directories and under $MNV/mnvfiles/pack/dist/opt/. - Download from the net. There is a large collection on http://www.mnv.org. - They are sometimes posted in a MNV |maillist|. - You could write one yourself, see |write-plugin|. Some plugins come as a mnvball archive, see |mnvball|. Some plugins can be updated automatically, see |getscript|. USING A GLOBAL PLUGIN First read the text in the plugin itself to check for any special conditions. Then copy the file to your plugin directory: system plugin directory ~ Unix ~/.mnv/plugin/ PC $HOME/mnvfiles/plugin or $MNV/mnvfiles/plugin Amiga s:mnvfiles/plugin Macintosh $MNV:mnvfiles:plugin Mac OS X ~/.mnv/plugin/ Example for Unix (assuming you didn't have a plugin directory yet): > mkdir ~/.mnv mkdir ~/.mnv/plugin cp /tmp/yourplugin.mnv ~/.mnv/plugin That's all! Now you can use the commands defined in this plugin. Instead of putting plugins directly into the plugin/ directory, you may better organize them by putting them into subdirectories under plugin/. As an example, consider using "~/.mnv/plugin/perl/*.mnv" for all your Perl plugins. FILETYPE PLUGINS *add-filetype-plugin* *ftplugins* The MNV distribution comes with a set of plugins for different filetypes that you can start using with this command: > :filetype plugin on That's all! See |mnvrc-filetype|. If you are missing a plugin for a filetype you are using, or you found a better one, you can add it. There are two steps for adding a filetype plugin: 1. Get a copy of the plugin. 2. Drop it in the right directory. GETTING A FILETYPE PLUGIN You can find them in the same places as the global plugins. Watch out if the type of file is mentioned, then you know if the plugin is a global or a filetype one. The scripts in $MNVRUNTIME/macros are global ones, the filetype plugins are in $MNVRUNTIME/ftplugin. USING A FILETYPE PLUGIN *ftplugin-name* You can add a filetype plugin by dropping it in the right directory. The name of this directory is in the same directory mentioned above for global plugins, but the last part is "ftplugin". Suppose you have found a plugin for the "stuff" filetype, and you are on Unix. Then you can move this file to the ftplugin directory: > mv thefile ~/.mnv/ftplugin/stuff.mnv If that file already exists you already have a plugin for "stuff". You might want to check if the existing plugin doesn't conflict with the one you are adding. If it's OK, you can give the new one another name: > mv thefile ~/.mnv/ftplugin/stuff_too.mnv The underscore is used to separate the name of the filetype from the rest, which can be anything. If you use "otherstuff.mnv" it wouldn't work, it would be loaded for the "otherstuff" filetype. On MS-DOS like filesystems you cannot use long filenames. You would run into trouble if you add a second plugin and the filetype has more than six characters. You can use an extra directory to get around this: > mkdir $MNV/mnvfiles/ftplugin/fortran copy thefile $MNV/mnvfiles/ftplugin/fortran/too.mnv The generic names for the filetype plugins are: > ftplugin/.mnv ftplugin/_.mnv ftplugin//.mnv Here "" can be any name that you prefer. Examples for the "stuff" filetype on Unix: > ~/.mnv/ftplugin/stuff.mnv ~/.mnv/ftplugin/stuff_def.mnv ~/.mnv/ftplugin/stuff/header.mnv The part is the name of the filetype the plugin is to be used for. Only files of this filetype will use the settings from the plugin. The part of the plugin file doesn't matter, you can use it to have several plugins for the same filetype. Note that it must end in ".mnv". Further reading: |filetype-plugins| Documentation for the filetype plugins and information about how to avoid that mappings cause problems. |load-plugins| When the global plugins are loaded during startup. |ftplugin-overrule| Overruling the settings from a global plugin. |write-plugin| How to write a plugin script. |plugin-details| For more information about using plugins or when your plugin doesn't work. |new-filetype| How to detect a new file type. ============================================================================== *05.7* Adding a help file *add-local-help* If you are lucky, the plugin you installed also comes with a help file. We will explain how to install the help file, so that you can easily find help for your new plugin. Let us use the "doit.mnv" plugin as an example. This plugin comes with documentation: "doit.txt". Let's first copy the plugin to the right directory. This time we will do it from inside MNV. (You may skip some of the "mkdir" commands if you already have the directory.) > :!mkdir ~/.mnv :!mkdir ~/.mnv/plugin :!cp /tmp/doit.mnv ~/.mnv/plugin The "cp" command is for Unix, on MS-Windows you can use "copy". Now create a "doc" directory in one of the directories in 'runtimepath'. > :!mkdir ~/.mnv/doc Copy the help file to the "doc" directory. > :!cp /tmp/doit.txt ~/.mnv/doc Now comes the trick, which allows you to jump to the subjects in the new help file: Generate the local tags file with the |:helptags| command. > :helptags ~/.mnv/doc Now you can use the > :help doit command to find help for "doit" in the help file you just added. You can see an entry for the local help file when you do: > :help local-additions The title lines from the local help files are automagically added to this section. There you can see which local help files have been added and jump to them through the tag. For writing a local help file, see |write-local-help|. ============================================================================== *05.8* The option window If you are looking for an option that does what you want, you can search in the help files here: |options|. Another way is by using this command: > :options This opens a new window, with a list of options with a one-line explanation. The options are grouped by subject. Move the cursor to a subject and press to jump there. Press again to jump back. Or use CTRL-O. You can change the value of an option. For example, move to the "displaying text" subject. Then move the cursor down to this line: set wrap nowrap ~ When you hit , the line will change to: set nowrap wrap ~ The option has now been switched off. Just above this line is a short description of the 'wrap' option. Move the cursor one line up to place it in this line. Now hit and you jump to the full help on the 'wrap' option. For options that take a number or string argument you can edit the value. Then press to apply the new value. For example, move the cursor a few lines up to this line: set so=0 ~ Position the cursor on the zero with "$". Change it into a five with "r5". Then press to apply the new value. When you now move the cursor around you will notice that the text starts scrolling before you reach the border. This is what the 'scrolloff' option does, it specifies an offset from the window border where scrolling starts. ============================================================================== *05.9* Often used options There are an awful lot of options. Most of them you will hardly ever use. Some of the more useful ones will be mentioned here. Don't forget you can find more help on these options with the ":help" command, with single quotes before and after the option name. For example: > :help 'wrap' In case you have messed up an option value, you can set it back to the default by putting an ampersand (&) after the option name. Example: > :set iskeyword& NOT WRAPPING LINES MNV normally wraps long lines, so that you can see all of the text. Sometimes it's better to let the text continue right of the window. Then you need to scroll the text left-right to see all of a long line. Switch wrapping off with this command: > :set nowrap MNV will automatically scroll the text when you move to text that is not displayed. To see a context of ten characters, do this: > :set sidescroll=10 This doesn't change the text in the file, only the way it is displayed. WRAPPING MOVEMENT COMMANDS Most commands for moving around will stop moving at the start and end of a line. You can change that with the 'whichwrap' option. This sets it to the default value: > :set whichwrap=b,s This allows the key, when used in the first position of a line, to move the cursor to the end of the previous line. And the key moves from the end of a line to the start of the next one. To allow the cursor keys and to also wrap, use this command: > :set whichwrap=b,s,<,> This is still only for Normal mode. To let and do this in Insert mode as well: > :set whichwrap=b,s,<,>,[,] There are a few other flags that can be added, see 'whichwrap'. VIEWING TABS When there are tabs in a file, you cannot see where they are. To make them visible: > :set list Now every tab is displayed as ^I. And a $ is displayed at the end of each line, so that you can spot trailing spaces that would otherwise go unnoticed. A disadvantage is that this looks ugly when there are many Tabs in a file. If you have a color terminal, or are using the GUI, MNV can show the spaces and tabs as highlighted characters. Use the 'listchars' option: > :set listchars=tab:>-,trail:- Now every tab will be displayed as ">---" (with more or less "-") and trailing white space as "-". Looks a lot better, doesn't it? KEYWORDS The 'iskeyword' option specifies which characters can appear in a word: > :set iskeyword < iskeyword=@,48-57,_,192-255 ~ The "@" stands for all alphabetic letters. "48-57" stands for ASCII characters 48 to 57, which are the numbers 0 to 9. "192-255" are the printable latin characters. Sometimes you will want to include a dash in keywords, so that commands like "w" consider "upper-case" to be one word. You can do it like this: > :set iskeyword+=- :set iskeyword < iskeyword=@,48-57,_,192-255,- ~ If you look at the new value, you will see that MNV has added a comma for you. To remove a character use "-=". For example, to remove the underscore: > :set iskeyword-=_ :set iskeyword < iskeyword=@,48-57,192-255,- ~ This time a comma is automatically deleted. ROOM FOR MESSAGES When MNV starts there is one line at the bottom that is used for messages. When a message is long, it is either truncated, thus you can only see part of it, or the text scrolls and you have to press to continue. You can set the 'cmdheight' option to the number of lines used for messages. Example: > :set cmdheight=3 This does mean there is less room to edit text, thus it's a compromise. ============================================================================== Next chapter: |usr_06.txt| Using syntax highlighting Copyright: see |manual-copyright| mnv:tw=78:ts=8:noet:ft=help:norl: