Same document references are often useful, for instance to turn phrases like "see above" into hotlinks. NOte that for an #r= -reference, see <#tp=ID Reference>, there is no relative addressing because only one id= target per file is assumed. b) Non file oriented resources and the Vimhelp scheme *utl-tutfragsnonfile* The best example is the Vimhelp scheme, e.g. (which is hereby introduced). When you execute this URL the Vim help for the :ls command is displayed. Although the help will normally be presented as a text file in Vim (namely doc/windows.txt) the file is not really the resource, the help item itself is the resource. It's often useful to use the Vimhelp URL and sometimes especially useful to combine it with a fragment. Example: Readonly buffers are marked with `=', see The utl.vim source code gives more realistic examples, see for instance . See for details about fragment processing. 3.6 Other media types *utl-tutmtypes* URLs are not restricted to .txt files or web pages. You can for instance reference a PDF document: To make this work a handler for .pdf type files has to be present. If you are lucky Utl.vim already defined a handler for you. Utl.vim aims to provide a generic media type handler for the most common platforms. The generic media type handler should handle a file like the system does (e.g. left (double) click to the file in the systems file explorer). The generic media type handler is implemented by the Vim variable g:utl_cfg_hdl_mt_generic . It can be overruled by a specific media type handler. For PDF files this would be g:utl_cfg_hdl_mt_application_pdf. See explanation under how to provide a specific handler. Normally the generic handler will be sufficient. A specific handler is needed for instance if fragments should be handled (see |utl-tutextfrag|). It is a good idea to test with verbose mode switched on if you want to define a specific media type handler If none of the handlers (specific and generic) is present, Utl.vim will try to make creation of a handler as painless as possible through a smart setup facility which is invoked automatically then [22]. 3.7 Link to folders *utl-tutfolders* An URL can also specify a folder: # Windows # Unix Folders also have a media type associated: text/directory. This means the specific or the generic media type handler has to be present to open a folder-URL. Utl.vim predefines the specific handler. The definition is: :let g:utl_cfg_hdl_mt_text_directory='VIM' The special value 'VIM' means that no external handler shall be called but the folder should be opened by (the current) Vim, which will use Vim's built in netrw directory browser. The special value 'VIM' can also be used for all other utl_cfg_hdl_mt_xxx handlers. Try to execute to see how that works. But what if you want to open a directory not with Vim but rather with the file explorer of your system? Well, that is easy if your generic handler is set up [23]: :let g:utl_cfg_hdl_mt_text_directory=g:utl_cfg_hdl_mt_generic Another possibility is to open a directory in a command-shell, i.e. open a shell with CWD set to the directory. Can be achieved by: :let g:utl_cfg_hdl_mt_text_directory__cmd = ':!start cmd /K cd /D "%P"' " Windows (DOS box) :let g:utl_cfg_hdl_mt_text_directory__cmd = ':!bash ... " Unix Unfortunately Utl.vim does not provide a means to dynamically choose one of these handlers, i.e. open one directory in Vim, the other in the systems explorer, the next in a command shell. But there is a workaround: Define mappings for the above assignments. See for suggested mappings. 3.8 Typing an URL *utl-tuttypeurl* In a web browser there are two ways to go to a page: - You follow a hyperlink from the page you are in. - You type an URL in the address field. Possibility 1 corresponds to ':Utl' in Utl.vim. Possibility 2 corresponds to the command. Examples: :Utl openLink ../plugin/utl.vim :Utl openLink www.vim.org You can use this for editing another file which is in the same directory as the current file. Example: gvim /really/an/annoying/long/path/to/src/main.c :Utl openLink option.c " [24] I myself use :Utl a lot for this purpose. Most often I type directory-URLs, see previous section |utl-tutfolders|. And my favorite folder is . (dot), i.e. the current directory: :Utl openLink . " or, shorter: :Utl ol . So :Utl ol . opens the directory the current file is in. Either in Vim, the systems file explorer or in the command-shell. 3.9 The Utl user interface *utl-tutUI* Until now you know the commands :Utl (to open the URL under the cursor) and :Utl openLink myUrl (to open a typed URL). The general command interface is: :Utl :Utl (without any arguments) is the same as: :Utl openLink underCursor edit since these are the default values for the three arguments. Instead edit which displays the file in Vim [25] with the Vim command :edit you might want to open the link in a split buffer or in a new tab and so on (just as you open files in Vim in many different ways): :Utl openLink underCursor split " Open link in split window :Utl openLink underCursor tabe " Open link in new tab Try these with the URL ! Utl.vim provides command line completion for the arguments to save typing. I recommend to set the 'wildmenu' option for enhanced completion [26]. Try: :Utl co " or :Utl co " or :Utl " etc. The completion works the like for second and third argument. Another aspect of completion besides saving typing is that it offers the possibilities in a menu like manner which makes it unnecessary to learn all the commands, especially those used less frequently [27]. Additionally to completion Utl.vim supports abbreviations for the arguments. The following are equivalent: :Utl openLink underCursor edit " is same as: :Utl ol uc edit " is same as: :Utl o u edit See for all abbreviations and explanation of the abbreviation rules. If you typed an abbreviation for an argument completion does still work for further arguments, e.g. :Utl o u Again, verbose mode might help to figure out what's going on when playing with abbreviations. One design goal of the Utl.vim user interface is to make mappings obsolete for the most since commands are short enough. Note that you can save one character on :Utl, :Ut is possible in standard Vim 7.1 [28]. See if you consider to use mappings anyway. 3.10 Visual URLs *utl-tutVisUrls* Sometimes you want to execute an URL which is different from what Utl.vim would parse out. Examples (desired URL underlined): ~dp0register_packages.bat " (Windows) file name not separated as (Utl) word --------------------- " Only the directory part wanted --------- Visually select the URL, possibly copy to clipboard (with CTRL-C under Windows), then execute :Utl openLink visual " or, shorter :Utl o v " [29]. 3.11 The Vimscript scheme *utl-tutVimscript* Utl.vim supports a special non standard protocol to execute Vim commands from within a plain text document. It is introduced here because needed in the sections which follow. The general format is: vimscript: Try these examples: " This which is the same as: " (i.e. you can omitt the `:') "Ex-command" is just the same as what you can type in an ex command line, for instance multiple commands can be concatenated with `|'. Example: Certain characters needed in an ex command line will collide with characters that have special meaning for URLs. In this case you have use normal URL percent encoding. Example: The 3c is the hex value of the < character, the 3e is the hex value of the > character. Just keep in mind that if an URL does not work, then try to encode the characters appearing dangerous with percent encoding [30]. Vimscript ex commands are executed in the context of a function (namely the handler, <../plugin/utl_scm.vim#r=vimscript>). This has the implication that global variables must be prefixed with g: See |utl-smartsamples|for more vimscript examples. 3.12 Other commands and options to operate on an URL *utl-tutOtherCmds* COPYLINK *utl-tutCopyLink* Until now we always opened (displayed) the target of an URL, i.e. jumped to the URL. You can also copy the link to the clipboard: :Utl copyLink " or, shorter :Utl cl This does the same as the right mouse popup function called 'copy link address' or so in web browser. Try for instance :Utl cl on and check the * register by executing . NOte that the register contains an absolute URL, not a relative one. Copying links is often useful, for instance to email a link address to someone. Another nice usage is to open the current file in another Vim instance: :Utl copyLink currentFile then switch to the other Vim instance and perform: :Utl openLink This example also introduced the currentFile operand (you already know underCursor, visual, ). COPYFILENAME *utl-tutCopyFileName* Related to copyLink is copyFileName :Utl copyFileName " or, shorter :Utl cf which copies the full path to the clipboard. Try the URL with the command :Utl copyFileName: and check the * register. Usage example: use copyFileName for a file you want to mail to someone as an attachment. Paste that file name in your mailer. Probably even more interesting is the other way round: You received a mail attachment and want to make it hot linkable from within a text file. Create a new link in the text file, e.g. , then perform :Utl copyFileName and paste the result into the 'save as' dialog of your mailer [31]. This can save you a lot of tedious browsing down directories in GUI programs (especially under Windows). CopyFileName does only work for (implicit or explicit) file:// URLs, not for example for http:// URLs. The file name will have slashes or back slashes depending on your system. But you can force the one or the other (for instance if using Cygwin under Windows): :Utl copyFileName underCursor backslash :Utl copyFileName underCursor slash (As these are positional parameters you have to provide a second argument, 'underCursor' here). For reference of all available commands and arguments see: :Utl help commands 3.13 The http scheme *utl-tutscmhttp* Until now we concentrated on local files. The scheme for a local file is (implicitly or explicitly) `file', e.g. file://path/to/file. Of course an URL can be used to retrieve other than local resources (a web page) or other resources than files (an email). Depending on what you are using Utl.vim for, file might be the most important scheme, followed by mail and http . Lets consider http now. You already know that you can execute the links: http://www.vim.org www.vim.org They are all equivalent. To make a http URL with fragment work, e.g. http://www.vim.org/download.php#unix the defined handler has to support that, which might not be the case in the default setup. You have to set up a handler that supports the %f conversion specifier. See the hints and instructions how to do this. A http URL does not necessarily mean "web browser". Consider for instance the URL: *utl-tutscmhttpwget* This is a plain text document. Wouldn't it much better to display it in Vim? Utl.vim provides interfacing to the non interactive download tool wget . For this purpose the handler utl_cfg_hdl_scm_http has to be set up as: :let g:utl_cfg_hdl_scm_http=g:utl_cfg_hdl_scm_http__wget Use this vimscript service URL to do the configuration (unless you prefer to type it in yourself :-) Now try the above link with this configuration! The RFC3986 will be displayed in Vim as a temporary file. So now you can browse the RFC3986 document directly in Vim. It gets even more interesting if you want to address a specific part in the target document. Examples: Now the ultimate combination of all techniques: retrieving a document from the web (with wget), using an external media type handler configured in Utl.vim for the ability to add a fragment: See |utl-tutpdffrag| how to make this work. In practice the one URL you want to display with your browser, the other URL using the wget handler. Again (like |utl-tutfolders|) no real dynamic switching between the handlers is possible. The suggested workaround is again to define mappings that switch between the handlers, see . 3.13 The mail scheme *utl-tutscmmail* There is a special, non standard scheme for referencing specific emails from your local mail boxes via URL. For instance, executing the link will open the so specified email in your mailer. This can be very convenient if you are using Vim for project management, software development, PDA etc. It helps you to have all relevant information at your fingertips. The only implementation of the mail scheme currently available is MS Outlook (under Windows) [32]. If you use another mailer you might consider to contribute an implementation [33]. If you don't use Outlook but like to reference emails you can workaround: save the mail as file (.txt, .rtf, .msg etc format) and create a link to this file. If your mailer is MS Outlook read on. Suppose you have an email in your Inbox, received the 2008-04-12 at 15:04 you can open the mail by executing the link (make sure that Outlook is already running!): Currently the date is locale dependent, the above sample is for a German Outlook. The date format is directly that of Outlook in the 'Received' column ('Erhalten in German), but without the week day prepended. The above can be written shorter as: since `date' is the default query [34] Examples using different mail folders are: The form /// denotes the default folder (maybe this syntax is too Outlook specific). 3.14 Other schemes *utl-tutscmoth* *utl-tutscmothstd* Besides file and http scheme Utl.vim currently Utl.vim supports the following standard schemes: ftp: Delegates to http (web browser to handle this) https: Delegates to http (web browser to handle this) mailto: Delegates call to your mail client. configurable by g:utl_cfg_hdl_scm_mailto Mailto URL specified at Examples: