dotfiles/doc/utl_usr.txt

*utl_usr.txt* Plugin for executing URLs in plain text files
*utl* *utl-plugin* 
Version Utl v3.0a ALPHA, for Vim version 7, 2008-07-31


		       Utl.vim User Manual

			 By Stefan Bittner
			stb@bf-consulting.de

	Contents:

		1. Intro........................|utl-intro|
		2. Getting started..............|utl-start|
		3. Tutorial.....................|utl-tutorial|
		4. Smart Samples................|utl-smartSamples|
		5. Usage Patterns...............|utl-usagePatterns|
		6. Tips, details, pittfalls.....|utl-tipsDetails|
		7. Configuration and Options....|utl-config|
		8. Changes since Utl v2.0.......|utl-changes|
		9. Todo.........................|utl-todo|
	       10. Credits......................|utl-credits|


See http://vim.sf.net/script.php?script_id=293 for getting and installing
Utl.vim.

See |utl-changes| for things that have changed in this version.

Any comments, bug reports, patches, fixes and suggestions are welcome.

Happy linking,
Stefan Bittner <url:mailto:stb@bf-consulting.de>


==============================================================================
1. Intro						*utl-intro*

What is Utl.vim?

It brings the benefits of URL-based hyperlinking to plain text, extending the
URL syntax for plain text needs, in accordance with the RFC 2396 (towards
current RFC 3986) URL specification.

Keywords: Hypertext, URL, URI, email, footnotes, Wiki.

Usages:
- Open any URLs found in text with appropriate handler
- Open files of any media type from within Vim (.pdf, .jpg, etc)
- Small helper utilities via embedded Vimscript
- Project management
- Organizing ideas
- Commenting source code
- Personal Wiki
- Editing HTML

Characteristics:
- Well documented and helpful verbose mode
- Is easy to get started
- Stays out of the way, no side effects
- Extensible

Now lets dive into the live examples.


=============================================================================
2. Getting started				*utl-start* *utl-getStarted*

Utl.vim's basic command to open an URL is :Utl . That's all you need!

Live Examples now!!!

Position the cursor on the next line:
    <url:#r=here>
Then type the comamnd  :Utl . This should take you ...
    id=here.

You just executed your first link!
`#r=abc' refers to a position in the document, that looks like `id=abc'. (If
you know HTML: that's analogues to a <A HREF="#abc"> which refers to
ID="abc".) The `r' in the expression stands for `reference'.

Executing  :Utl  on <url:#tn=some text> takes you to ...
						        some text.

The special syntax `tn=' just means that the target of the link is defined by
searching the denoted string 'some text' in forward direction (tn stands for
Text Next). You can omit the `tn=' prefix and just write <url:#some text>
because the tn= is the default prefix.

Executing  :Utl  on <url:../plugin/utl.vim> takes you to the file utl.vim.

Please come back here again after having executed the link!

Executing  :Utl  on <url:../plugin/utl.vim#tn=thanks for> takes you to a
specific position in the file utl.vim. This example can be seen as the
combination of the two previous examples: URL + #xxx

The #xxx suffix is called a fragment expression in URL lingo.

Executing  :Utl  on <url:http://www.vim.org> will invoke your web browser with
that URL. Just try it, if you are lucky Utl.vim already knows how to open web
pages, else Utl.vim will assist you to set up your favorite browser.

You can leave away the <url:...> embedding. Try for example:

    http://www.vim.org

or even

    www.vim.org

An advantage of embedding-less links is that normally you will find URLs in
given documents in this form. Furthermore the <url:...> embedding can be a bit
clunky. The disadvantage is that there is no safe parsing for "naked" URLs and
as one consequence of this, no syntax highlighting.

The above utl.vim link without embedding reads:
    ../plugin/utl.vim
For some file in the same directory as the current file you would have:
    ./someFile.txt
or, a file without a suffix:
    otherFile
or
    WikiWord
This means that you can use Utl.vim to turn Vim into your personal Wiki.
There a specialized Vim plugins (vimwiki, potwiki.vim), but people
told me the linking (and document creation) feature already does a good part
of the job.

Utl.vim supports links that could be called reference style links or just
footnotes. Position the cursor on the [10] in the next line and execute :Utl :

    The software can be downloaded from [10]
    .
    .
    [10] http://www.vim.org/download.php

One often encounters such references in given text. So Utl.vim does not invent
a new syntax but just supports what is there. (The same is actually true for
the for the URL based links.)

From now on I will use those [] -footnotes :-) 

You can also type an URL in the command line:

    :Utl openLink ../plugin/utl.vim	# Open file that is in same directory
					# as current file
or in short form

    :Utl ol ../plugin/utl.vim	    # same as above

Other 
    :Utl ol www.google.com	    # Open web page from within vim. Sometimes faster
				    # faster than from desktop.

If you feel it's now time for a "hello world" test, just go ahead and write
your own links. There is no meta data and no tags file needed. Its nothing
but plain text.

Before you seriously start using Utl.vim it is recommended to continue with
reading the next chapter, 3, Tutorial. If you are in doubt if Utl is valuable
for you, have a look at chapter 5, Examples of use, |utl-examples| first.


==============================================================================
3. Tutorial						*utl-tutorial*


3.1 Forth and back					*utl-tutforthback*

From the previous chapter you already know how to follow links by executing
:Utl  for links under the cursor.

The following link, as you know, takes you to another file:

    <url:../plugin/utl.vim>

Try this now! ... No, Wait! To come back here again, just use the regular
vim command CTRL-O. That's the BACK-Button in the "Vim browser" - and it might
need to be typed more than once.
Now do it! 

Hope you are back again.


3.2 Relative and absolute URLs				*utl-tutrelabs*

The following URLs are all equivalent:

    <url:utl_usr.txt>
    <url:./utl_usr.txt>
    <url:../doc/utl_usr.txt>

These are all so called relative URLs. This means that the path given in the
URL is relative to the path of the document containing the URL. NOte that this
is different to Vim's :e command where file names are relative to the current
working directory (see |:pwd|). Whenever possible you should use relative
URLs. But sometimes you need absolute URLs, just as you sometimes need
absolute path names with Vim's :e command. Here is an absolute URL:

    <url:file:///home/stb/.vim/plugin/utl.vim>

An absolute URL always has a so called scheme (also called protocol) in
front, e.g. file: , http:, mailto: . (And, if there is a protocol in front it
always is an absolute URL.) What also makes sense is to write the above URL
without the protocol:

    <url:/home/stb/.vim/plugin/utl.vim>	    # equivalent to above

This is a relative URL (because there is no protocol) ... containing an
absolute path. The contrary does not make sense: An absolute URL with a
relative path:

    <url:file:../plugin/utl.vim>    # WRONG!!! Absolute URL with relative path
				    #	       is an invalid URL.

When you try to execute this URL, the current implementation of Utl.vim opens
a file  utl.vim  in the current working directory - not a good behavior
for an URL.


3.3 Running Utl.vim in verbose mode			*utl-tutverbosemode*

Utl.vim supports a verbose mode:

    :let utl_opt_verbose=1	# Switched on
    :let utl_opt_verbose=0	# Switched off (default)

Verbose mode can be very useful to figure out what's going on. For instance
for the previous section you can see the different processing between absolute
and relative URLs and how the latter are turned into absolute URLs by
constructing a base URL. Try for example to execute:

    <url:../plugin/utl.vim>

with verbose mode switched on. Don't forget to use this feature when things
get more complicated!


3.4 Drive letters and network shares			*utl-tutdrivesshares*

Under Windows you can specify drive letters like this:

    <url:file://d:/path/to/foo.txt> or, which is the same,
    <url://d:/path/to/foo.txt>

This is in conformance with URL specifications. Note that you always should
use forward slashes, no matter on what OS you are; URLs are universal and thus
independent of the OS.

Utl supports notation for network file access, e.g. Shares under
Windows, NFS under Unix.

Windows Example: Utl converts <url://127.0.0.1/ADMIN$/System32/EULA.txt>
internally into the UNC path \\127.0.0.1\ADMIN$\System32\EULA.txt, which is
directly passed/edited to/by Vim, since SMB shares are transparent under
Windows.

Unix Example: Utl converts <url://server/sharefolder/path> internally
into  server:/sharefolder/path . (Don't really know if this makes
sense :-)

Windows Examples:
<url://89.11.11.11/testinput/cfg/sid_7_configuration_list.txt>
<url://56.240.74.41/c$/install_pers/setup.log>

Utl does neither care if authentication is needed on the server resource nor
does it offer direct means for authentication [20].


3.5 Fragments						*utl-tutfrags*

--- Intro						*utl-tutfragsintro*

Now lets add fragments to URLs.
The next link again references the same file as in the above examples, but is
extended by a fragment expression. That way a specific position in the target
file can be jumped to. Try to execute the link:

    <url:../plugin/utl.vim#tn=thanks for>

and come back again with CTRL-O. The next link specifies the same file, but
the fragment expression is different:

    <url:../plugin/utl.vim#r=foot1>

Execute it and come back again! It took you to about the same position as the
previous link, but by other means. The fragment `#r=foot1' means, that the
file utl.vim is searched for the ID reference `foot1'. What follows r=
should be a simple string (an identifier to be exact).

The #tn fragment has one big advantage over #r= fragments. It allows to
refer to specific positions in the target document without the need to
modify that target document, either because you don't want it or because you
don't have write access. The advantage of the ID reference fragment is that
the link is more robust.

#tn= and #r= are the most important fragment specifiers in Utl.vim. As
already said, the #tn= prefix is the default prefix, i.e. you can leave it
away. Thus the link above will normally be written shorter:

    <url:../plugin/utl.vim#thanks for>

This is also called a naked fragment identifier because there is no `key='
prefix. 

The found string will _not_ get the current search string (I don't know why).
This means it will not be highlighted and you cannot search the next
occurrence with Vims  n  command. But the string is one up in the search
history, so you can recall it from there.


--- Line fragment and bottom up addressing		*utl-tutfragsline*

Another fragment identifier is #line. It positions to the given line,
e.g. 

    <url:utl_usr.txt#line=10>	(or #line=+10)

This is useful for documents that won't change much. Negative numbers
can be given as well:

    <url:utl_usr.txt#line=-10>

This counts the lines from bottom of the buffer upwards, -1 specifies
the last line. For the #tn identifier there is also a "bottom-up" possibility,
the #tp identifier. Try and compare these two:

    <url:utl_usr.txt#tp=vim>
    <url:utl_usr.txt#tn=vim>


--- Relative addressing					*utl-tutfragsrel*

So far all fragment addressing was relative from top or bottom of the buffer.
It can also be relative to the current cursor position in two cases:

a) Same-document references				*utl-tutfragsdref*

These are URLs that only consists of a fragment. Examples:

    <url:#line=3>
    <url:#line=-3>
    <url:#tn=fragment>
    <url:#tp=relative>

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. <url:vimhelp::ls> (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 <url:vimhelp::ls#readonly>

The utl.vim source code gives more realistic examples, see for instance
<url:../plugin/utl.vim#since a string>.

See <url:../plugin/utl.vim#r=Utl_processFragmentText> 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:

    <url:foo.pdf>

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
<url:config:#r=mediaTypeHandlers> 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:

    <url://c:/Program Files>	    # Windows
    <url:/usr/local/bin>	    # Unix
    <url:./tmp>
    <url:.>

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 <url:.> 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 <url:config:r=#map_directory> 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 <command> <operand> <mode>

: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

    <url:../plugin/utl.vim> !

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<Tab>	" or
    :Utl co<CTRL-D>	" or
    :Utl<Tab>		" 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 <url:../plugin/utl.vim#r=cmd_abbreviations> 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<CTRL-D>

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 <url:../plugin/utl.vim#r=suggested_
mappings> 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
        ---------------------

    <url:./path/to/file.txt >	" 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:<ex-command>

Try these examples:

    <url:vimscript::ls>	    " This which is the same as:
    <url:vimscript:ls>	    " (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:

    <url:vimscript:split|call input('I will open a new window now!')>

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:

    <url:vimscript:call input('Hit %3creturn%3e to continue')>

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

    <url:../plugin/utl.vim>  and

check the * register by executing

    <url:vimscript::reg *>.

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 <URL pasted from clipboard>

This example also introduced the  currentFile  operand (you already know
underCursor, visual, <typed URL>).


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:

    <url:../plugin/utl.vim>

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.

    <url:./infos/20080523_Instructions_Workreports_ext.ppt> ,

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:

    <url:http://www.vim.org>
    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

    <url:config:#r=schemeHandlerHttp>

how to do this. A http URL does not necessarily mean "web browser". Consider
for instance the URL:

    <url:http://www.ietf.org/rfc/rfc3986.txt>
							*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 :-)
    <url:vimscript:let g:utl_cfg_hdl_scm_http=g:utl_cfg_hdl_scm_http__wget>

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:

    <url:http://www.ietf.org/rfc/rfc3986.txt#^1.1.2.  Examples>
    <url:http://www.ietf.org/rfc/rfc3986.txt#line=343>

    <url:http://www.vim.org/scripts/download_script.php?src_id=3640#horizontal or vertical>

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:

    <url:http://bullium.com/support/vim.pdf#page=3>

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
<url:config:#r=map_http>.


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

    <url:mail:///Inbox?date=12.04.2008 15:04>

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!):

    <url:mail:///Inbox?date=12.04.2008 15:04>

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:

    <url:mail:///Inbox?12.04.2008 15:04>

since `date' is the default query [34]

Examples using different mail folders are:

    <url:mail:///Sent Items?12.04.2008 15:04>
    <url:mail://archive/Inbox?12.04.2008 15:04>

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 <url:http://www.ietf.org/rfc/rfc2368>

	Examples:
	<url:mailto:stb@bf-consulting.de>
	<url:mailto:stb@bf-consulting.de?subject=otto&cc=karl.meier@web.de&body=test>
	<url:mailto:majordomo@example.com?body=subscribe%20bamboo-l>

    scp:
	Uses Vims netrw-Plugin, see |scp|
	configurable by  g:utl_cfg_hdl_scm_scp

	Syntax:
	<url:scp://hostname/path/to/file>

							*utl-tutscmothnonstd*
Moreover, besides mail, vimscript and vimhelp scheme Utl.vim introduces and
supports the following non standard schemes:

    man:
	Accesss manual pages via URL.
	Relies on the ManPageView plugin (:Man command) which needs to be
	installed [35].

	Example:
	<url:man:ls>

    config:
	Utl specific. Ad hoc scheme for accessing Utls setup file.
	Not really exciting.

	Examples:
	<url:config:>		(try it!)
	:Utl ol config:

    foot:	
	Interface to make footnotes accessible via URL. Normally not called
	directly but through heuristic form as has been explained at
	<url:foot:10>. This will be elaborated in the next section.


The schemes  http, mail, mailto, scp  are configurable by
utl_cfg_hdl_scm_<scheme>. All other schemes not (yet). See <url:../plugin/utl.
vim#r=spec_ihsv> for specification of that configuration interface.

You can easily implement your own schemes or define new ones. You just
implement a Vim function somewhere. Utl.vim dynamically calls those functions.
Have a look at <url:../plugin/utl_scm.vim#r=implscmfunc> or just hack one of
the existing functions in ../plugin/utl_scm.vim.  But I recommend that you
read chapter 5, Tips, details, pitfalls,  before you write your own scheme
handler. A common misunderstanding is to create a new scheme where support 
media type support to an existing one would be the better choice. See
|utl-privateScmHdl|for an elaborated example below.


3.15 Footnotes						*utl-tutfoot*

Now let's go into some detail with footnotes (reference style links).

As you already know (from [10]), Utl.vim supports these commonly used
references in square brackets:

    The software can be downloaded from [11]
    .
    .
    [11] http://www.vim.org/download.php

Besides given texts from elsewhere, there are some Vim plugins that create
such footnotes [36]. But AFAIK there is no tool except Utl.vim that cares
about making them executable.

Often, like in the previous example, the [] syntax is used to indirectly
reference URLs because, citing from [36_2]: "Inline URIs [...] make the text
around them obscure". Utl.vim normally does not dereference the reference
target; in the example above it does not open the http:// Link

Often [] references are used for simple footnotes:

    This is true [101] 
    .
    .
    [101] but not always

In this case () style references like (*), (1),(2) might be more common,
but this is not supported by Utl.vim.

-----
Syntax Details						*utl-tutfragsyn*

References are not restricted to numbers, you can also use mnemonics
or abbreviations like [UTL_RC]. Allowed characters inside [...] are
_, A-Z, 0-9. Amongst others this style is useful for document reference.

According to common use of references the slight syntax variations for the
reference target are supported:

    [102]	This is used most often (and in all examples so far)
    [102]:	A bit exotic, but more parse-safe [37].

NOte that  102.  (= number followed by just a point, no square brackets), is
not supported as reference target because in practice too often the wrong
target is found. The 102. form is useed by [36_2]. 

Obviously with the first form the reference source and target look the same.
And it can actually be possible to switch the roles. When searching for the
target, the source line is excluded. Often the reference target will be
located at the bottom of the text, but needs not. The reference target must
appear at the beginning of the line (after optional whitespace) [38]. ---
Don't forget to run Utl.vim in verbose mode (see |utl-tutverbosemode|) if I
confused you :-) Verbose mode also shows you the search algorithm.

-----
Footnote Fragments					*utl-tutfootfrag*

You can append a fragment to [] references. Example:

    [UTL_RC]#tn=1.3.

This will open the target of the reference, i.e. file .plugin/utl_rc.vim and
position the cursor according the fragment in this file. So adding a reference
allows you to automatically forward a [] reference. Obviously this only makes
sense if the reference target is a reference itself and not just a footnote
text. Forwarding also happens with empty fragments. Try for example to execute
this reference:

    [36_1]#

Reference fragments can be especially useful if you have more than one
references into another document, e.g. 

    [UTL_RC]#r=utl_cfg_hdl_scm_http
    [UTL_RC]#r=utl_cfg_hdl_scm_scp
    [UTL_RC]#r=utl_cfg_hdl_scm_mailto

There is no Utl.vim option or so to let you choose whether to
automatically forward or not.

Well, #-fragments appended to [] style footnotes is a new syntax introduced by
Utl, in the hope that it will be useful. 

-----
Reference Links are implemented as URLs			*utl-tutfooturl*

Inside utl.vim there is not much special treatment of [] references, they are
handled as URLs, a new non standard scheme "foot:" has been introduced. So
most of the specific code is hence in the corresponding handler outside the
kernel of utl.vim. The following Urls are equivalent: <url:foot:36> =
<url:[36]> = [36]. Again, to see what's going on internally you can the
verbose option: <url:vimscript:let g:utl_opt_verbose=1>


3.16 Fragments to external Media Type Handlers		*utl-tutextfrag*

As foretold at |utl-tutmtypes| defining a specific media type handler makes
sense if you want to address fragments in files not displayed within Vim.
Utl.vim offers limited support for PDF and MS Word documents.

-----
PDF page addressing					*utl-tutpdffrag*

You can execute an URL like

  <url:http://www.tech-invite.com/RFCs/PDF/RFC3986.pdf#page=4>

if you use Acrobat Reader to display PDF documents. Enable enable the specific
handler for media type application/pdf:

- Execute <url:config:#r=utl_cfg_hdl_mt_application_pdf__acrobat>,
- uncommment the two lines below the cursor and activate
  the change by :w , :so %
- Then look for a test PDF on you computer with a least 4 pages,
  e.g. /path/to/my.pdf
- Open this file with:
  :Utl ol /path/to/my.pdf#page=4
- follow the directives (to configure Acrobat Reader).

This can be very useful for, say, to reference technical specifications (= PDF
document) from within source code.

NOte that addressing PDF pages this is not restricted to local files. To make
the above http link work (after set up of the specific handler) you just need
to bypass your web browser (AFAIK these do not support addressing pages) and
use the wget handler as described in section |utl-tutscmhttp|.

Currently only #page= fragments are supported.

-----
MS Word text search					*utl-tutwordfrag*

Analog to PDF, to execute an URL like

    <url:my.doc#tn=textToSearch>
    <url:my.doc#textToSearch>	    (short form)

you just need to enable the specific handler for media type
application/msword:

- Execute <url:config:#r=utl_cfg_hdl_mt_application_msword__word> and
- uncommment the two lines below the cursor and activate
  the change by :w , :so %
- Then try a .doc URL (with tn= fragment) and
- follow the directives (to setup the .vbs interface and configure MS Word).

Currently only text search (#tn= fragment) is supported. 
#page= and #r= for jumping to numbered elements, section, text marks etc
would be desirable. 

Addressing fragments can be quite useful for:

- technical documentation if you use Vim for collecting and managing changes
  of your document or to use Vim as annotation system for MS Word.

- Referencing documents from within source code


3.17 Creation of URLs				    	*utl-tutcreateurls*

You might use Utl.vim mostly for "defensive" purpose: there is existing plain
text like emails (pasted into Vim or using Vim as viewer), source code,
READMEs and FAQs that contain URLs [39].

But if you use Utl.vim for your own texts, documents and source code you might
like to have ways to quickly create URLs and links. Here are some hints:

To ease creation of an URL with embedding  <url ... >  you can define mappings
in your .vimrc file ( without the trailing ">  ):

    imap xu <url:			">
    imap xuh <url:http://		">
    imap xumi <url:mail:///Inbox?	">
    imap xuh <url://c:/stb/home/	">

Another thing is to create a link to a local file or a resource which you
already have on your desktop. To create a file:// -URL for a file displayed in
Vim (same or different session) you can:
- go to the intended link target file,
- type  :Utl copyLink currentFile, 
- go to the intended link source file,
- paste from clipboard

That's all what the current version offers [40].


3.18 Miscellaneous					*utl-tutmisc*

-----
Creating files by executing a link			*utl-createFiles*

If you execute an URL which points to a non existing file, this file (firstly
its Vim buffer) will be created. This is very useful for authoring: You write
the URL in your document and then execute it. You can try this with the URL
<url:utl_foobar.txt>. 


-----
Multiline URLs						*utl-multiLineURLs*

You can spread URLs across several lines like this: <url:../plu
gin/utl_uri.vim>. This is sometimes useful for long URL, see examples
below at #r=lu. When typing an URL that Vim breaks (because it contains a
space and 'tw' option is set) you have to be careful: Utl.vim eliminates all
spaces around the line break. The above link is thus equivalent to <url:../plu
    gin/utl_uri.vim>. In order to preserve the space, you could escape it with
%20 (see |utl-uri-forbchars| about escaping), e.g. <url:this filename
    %20contains blanks.txt>. But you could also just split at another position:
<url:this filenam
    e contains blanks.txt>


-----
Tilde support						*utl-tildeSupport*

You can use the ~ (tilde) character in URLs. Example: <url:~/.vim/plugin/utl.
vim>. The ~ is replaced by the contents of the $HOME environment variable.
On Unix system ~user also works. See |$HOME|.


==============================================================================
4. Smart samples					*utl-smartSamples*

-----
Lookup word						*utl-lookupWord*

You can use Utl's web browser integration to look up the word under cursor in
the dictionary or encyclopedia of your choice with a mapping like:

    nmap ,l :exe ":Utl ol http://dict.leo.org/?search=" . expand("<cword>")

This is practical for spell checking (despite Vim built in spell checker). The
following mapping is similar:

    " Lookup of expression given on command line.
    " Of benefit because often faster than click click on desktop
    " Use %20 or \ or + to escape blanks, example:
    "		for%20that%matter
    "		for\ that\ matter 
    "		for+that+matter 
    nmap ,m :Utl ol http://dict.leo.org/?search=

is similar.


-----
Vimscript heuristic URL					*utl-vimsHeuristicUrl*

As an enthusiastic Vim user reading vim tips or receiving help by other users
you often get advices like

    To tell Vim to jump to the already open window or tab instead of
    creating a new window by some split command do:

    :set switchbuf=usetab

    See also:

    :h 'switchbuf'

With utl.vim you can execute both : lines directly. Just visually select the
line and perform the command  :Utl openLink visual  (or shorter:  :Utl ol v ).
This is implemented as a heuristic. Perform links with utl_opt_verbose=1 to
see what's going on.


-----
Using vimscript URL for backup				*utl-vimsBackup*

The following URL creates a copy of the file containing the URL under the
name <current-date>_<current_file_name> to the directory /tmp. You can
directly try the link (possibly after change of the /tmp directory to
something else under Windows):

    <url:vimscript::let dt=strftime('%Y%m%d_%H%M') | exe ':w /tmp/'.dt.'_%:t'>

This can be convenient for files that should be backuped beyond some regular
backup. The URL is portable, you can directly implant to a file of yours.


-----
Using vimscript URL for compiling			*utl-vimsCompile*

If you use LaTeX you can insert the following in a .tex file to compile it
using pdflatex (first URL) and to display it using the Utl.vim-configured
pdf Reader (second URL):

    %   <url:vimscript:!pdflatex %>
    %   <url:vimscript:exe 'Utl ol '.expand('%:r').'.pdf'>


-----
Invoke Utls media type handlers in Vim file browser	*utl-fbcallmt*

In the Vim file browser (netrw.vim) you can use  :Utl  to invoke the files and
directories presented there with the Utl-defined media type handlers! Just
useFor example open a MS Word document, show a picture, open a pdf document or
open a directory with system file explorer etc. That's very convenient. Seems
like magic first, but isn't, it is completely straight forward and without any
special treatment by Utl.vim (run with utl_opt_verbose=1 to see what's going
on). It might be worth to nOte that you do not execute self written URLs here
but URLs in the wild.

    " ========================================================================
    " Netrw Directory Listing                                    (netrw v123e)
    "   /home/stb
    "   Sorted by      name
    "   Sort sequence: [\/]$,\.h$,\.c$,\.cpp$,*,\.o$,\.obj$,\.info$,\.swp$,...
    "   Quick Help: <F1>:help  -:go up dir  D:delete  R:rename  s:sort-by  ...   
    " ========================================================================
    ../
    foo.pdf
    pic_0123.jpg
    tmp/


-----					*utl-btSample* *utl-privateScmHdl*
Reference your bug tracker database - a private scheme handler example

If you are a software developer you might use a bug tracking system.
Following the usage pattern |utl-projectManagement| information
regarding individual bug tracking issues would be tracked in the
project text file. Bug tracking issues are identified by some sort
of ID. For an example let's name them BT1234, BT4711

You can use Utl.vim to turn these references into hotlinks:

Make a bug tracker scheme with the (abritrary) name 'bt', and hence
URLs like
    <url:bt:BT1234>, <url:bt:BT4711>

Implement the protocol by defining in your .vimrc the handler
function:

    fu! Utl_AddressScheme_bt(url, fragment, dispMode)		" url= bt:BT4711
	let btId = UtlUri_unescape( UtlUri_opaque(a:url) )	" btId = BT4711
	let btUrl = 'http://server.company.com/bt/ticket/ticketView.ssp?\
		     ticket_id='.btId.'user_id=foo&user_pwd=bar'
	return  Utl_AddressScheme_http(btUrl, a:fragment, a:dispMode)
    endfu

Adapt the line specifying the web interface (btUrl=...). The call to
Utl_AddressScheme_http means that the actual work is delegated to the http
protocol handler. (See ../plugin/utl_scm.vim#r=implscmfunc for details on
writing handler function if needed.). With this definition the above URLs can
be executed. Also without embedding, e.g. just bt:BT1234. The bt: prefix is
more owed to URL syntax needs than to practical concerns. To get rid of it
define a heuristic. Currently this is only possible by hacking Utl.vim, but I
did it already for you, see ../plugin/utl.vim#r=heur_example. With heuristic
defined you can just execute a plain BT4711 anywhere in the text.


-----
Starting a program					*utl-startprog*

The following starts a vncviewer client for me:

    <url://q:/projekt_511/Iberl/vnc3.3.3R2/vnc_x86_win32/vncviewer/vncviewer.exe?>

The question mark at the end denotes that the path in front of it should be
interpreted as a program to be executed. This is straight forward URL
techniques, Utl applies the general URL query concept to programs which are
directly accessible by your file system.

You can also supply the server IP address to connect to:

    <url://q:/projekt_511/Iberl/vnc3.3.3R2/vnc_x86_win32/vncviewer/vncviewer.exe?89.11.11.242>

Starting programs is especially useful in case of long, strange paths to the
program that you either forget or which is simply to annoying to type. This
can be an alternative to one liner programs. A good place to keep such links
might be your info file, see |utl-useinfofile|.

Here is another example using a slightly different form of query:

    <url:my-decrypt.pl?stb-cellphone-pin%3e>

This link is contained in my address book. It looks up the PIN number of my
cellphone which is GPG encrypted. My-decrypt is a small Perl program which
asks for the password and then writes the PIN to standard output. The %3e at
the end is the '>' character in escaped form (see |utl-uri-forbchars|). The
'>' as the last character means the following to Utl: Execute the given
program synchronously and write the output into a temporary file. The
temporary file is then displayed in Vim. In the above vncviewer example the
program is started asynchronously and no output is awaited.
							    [id=patch]
The following line is contained in DOS script  patch.bat  that contains some
copy commands to patch a target system from the source code:

    rem <url:./patch.bat?>

This link enables you to execute the file directly from within Vim without
taking the detour to the shell.  


-----
Displaying and browsing HTML				*utl-displayHtml*

Use Utl to display a HTML file/page that you are currently editing with the
command:

    :Utl openLink currentFile	    " or shorter:
    :Utl ol cf

This will open the HTML file in your web browser (possibly after dynamic
request for configuration). Utl.vim also supports for browsing of HTML source
code, see|utl-efmeddep|.

==============================================================================
5. Usage Patterns					*utl-usagePatterns*

Here are some usage pattern for URLs in plain text. Although they do not exclude
each other and will often appear all together, they sketch different use
focuses. I worked the patterns out in the hope they are helpful in exploring
plain text URLs.

5.1 Use Vim as Desktop application			*utl-usedesktop*

If you use your text editor not only in a defensive manner (to edit program
source code what you are engaged for since you are a programmer) but
also unsolicited because you recognized that a text editor is an excellent
desktop tool then you might consider to read explore this section.

5.1.1 Project Management				*utl-projectManagement*

This pattern is about compiling lots of different informations and making them
available at your fingertips. Characteristics are:
- The information changes frequently
- Many different schemes and media types involved
The compiled information might consist of:
- references to important email threads
- web links
- links to resources (project drives, document management system links)
- links to downloaded documents
- references into bug tracker database

Example (the #-comments are only for clarification and not in the real file):

    --- install_project.txt -----------{
    file: poland_project.txt - Poland Install Project
    hist: 14.07.08/Stb

			# Link to architecture working document
    <url:../i/rcinstall_arch.txt>

			# Link to installation instructions
    <url:../../data/PL Installation Procedure - IMS Installation.doc>

    <url:cr.txt>	# Link to change requests notes
    <url:versions.txt>	# Link to SCM related stuff
    <url:t.txt>		# Link to test reports
    <url:t.txt#r=act>	# ... direct link to current test there

		        # Link to project root in document management system
    <url:http://kstbx032.ww010.mycompany.net/livelink/livelink.exe?func=ll&
    objId=1007014&objAction=browse&sort=name>			    [id=lu]

    Iinstall:		# Link to a specific document there
    <url:http://kstbx032.ww010.mycompany.net/livelink/livelink.exe/RC_D_
INSTALLATION_COMPONENT_IF_SPEC.doc?func=doc.Fetch&nodeId=1017472&
    docTitle=RC_D_INSTALLATION_COMPONENT_IF_SPEC%2Edoc&vernum=1>

			# Hot link to the current installation CD
    <url:vimscript:!net use w: %5c%5c56.123.11.73%5cc$ myAdminPassword /user:administrator>
    <url://56.123.11.73/infrastructure/installation/poland/CD>
    

    Configuration files for all deployment sites 
      <url:mail:///Inbox?14.07.2008 20:40>
      = <url:../../data/sd/20080219_all_siteconfigs>  # I use the = notation
			# for attachments or references contained in an
			# email, which data I saved locally

    Info about the CGW Tool
      <url:mail:///Inbox16.06.2008 11:21>

    Release of installer version 3.13.1.14
      ! Contained in application version 35.106, 35.107
      <url:mail:///Inbox?13.03.2008>	    Announcement Mail
      <url://d:/plInst/ws_3_13_1_14>	    Link to source code copy
      Solved issues: PT97084, PT97411, PT97460 (partly), PT97957

    Patching of integration test system
			# See <url:#r=patch> for explanation
      <url:./tools/patch.bat#>

			# Reference to bug tracker issue.
			# See |utl-btSample|
    BT4711
	<url:mail:///Sent Items?21.07.2008 22:03>

    BT4712
	Analysis of issue: <...>
	<url:mail:///Inbox?21.07.2008 10:23>	As discussed with Rob
	
    
    -----------------------------------}


5.1.2 Collecting and organizing ideas			*utl-useOrganizeIdeas*

Keywords for this section are:
Hypertext, Personal Wiki, NOtes, Mind Map, Writing in outlines.

With (executable) URLs you can build up hypertext (as you know from the
Web/HTML - where the H stands for hypertext and the implementation of that is
URLs). Here I mean self written hypertext, pieces of text that you write and
which you want to interlink because those pieces are associated somehow.

An example is software development. When you start thinking of some software
to be developed you may write down the thoughts, ideas, known requirements
etc. down to a piece of paper. Or you write it in a text file using your
favorite Vim editor because with this media you can rearrange, modify and
search the text...and because you can interlink portions of the text.

Utl.vim helps you with interlinking and associating. Especially fragment
addressing |utl-tutfrags| and also reference style links |utl-tutfoot| are
helpful in this context.

Personal Wikis [42] also serve this usage pattern. Contrary to (some of) them,
Utl.vim does not offer any text formatting (and conversion to HTML etc) - Utl
is just URL. Vims folding can also help a lot in organizing your ideas.

Collecting and organizing notes is quite related, so it might be ok to
subordinate within this section. Example is a personal info file.
You might maintain a file that contains for instance:
- Installation instructions of tools (e.g. what to modify after you installed
  a new Vim version)
- Usage of tools they use, for instance CVS usage and commands
- Links to network drives, resources and documentation
- Web links (instead or additional to bookmarks/favorites in web browser)
- HOWTO information (for instance collection of important cvs commands)
All these informations are much more useful if enriched with URLs.


5.1.3 Information Directory      			*utl-infoDir*

Keywords for this section are:
Index File, Bookmarking.

A common desktop use of Utl is to maintain a file directory of your important
files. This tends to be most helpful for files that you need less frequently
so that you don't remember their locations. Furthermore, the ability to add
comments can help to figure out in which file certain information resides.
Some people also use this technique to switch between files, but for this
purpose there might be better ways (like self written tag files, session
files, buffer explorer etc). The Information Directory rather contains static
information.

Example (the #-comments are only for clarification and not in the real file):

    --- directory.txt -----------------{
    ./apps			# NOtes related to different application areas
      ./apps/tex_app.txt
      ./apps/sys_app.txt
      ./apps/lpr_app.txt	(Unix an Windows)	# Printers

    ./p
      ./p/invoices
      ./p/privat/
	  ./p/privat/books_db.xml   Private and bf!
	  ./p/privat/running.txt    # sports
	  ./p/privat/st/
	      ./p/privat/st/st07.txt
	      ./p/privat/st/st08.txt
      ./p/data/cal_2008.txt
      ./p/org/tk_ow10/
      ./p/org/tk_ow10/tk.txt
      ./p/spendings.txt
				# correspondence
      ./p/corr/			.tex letters
	./p/corr/carla.txt
	./p/corr/alice.txt	
	./p/corr/notes.txt#r=akt

      ./p/adb/
        ./p/adb/stb_adb.xml	# address book
				Include xy-spendings!
      ./sd
        ./sd/index.txt		# link to another index file
    -----------------------------------}

Go to the line of the file you want to open and type :Utl . NOte that this
also works if the cursor is on the whitespace before a file.

A related usage is to maintain web bookmarks not in a web browser but,
in a text file. This might be more portable, or quicker than click click
in your web browser. Example:

    --- bookmarks.txt -----------------{
    http://www.vim.org				Vim Page
    http://maps.google.de/			Google
    http://de.wikipedia.org/wiki/Hauptseite	Wikipedia
    http://dict.leo.org/?lang=de&lp=ende	Dictionary
    -----------------------------------}

Of course you should create some shortcut to the bookmarks.txt file, e.g.
create a tag, a mapping or an URL linking to it
    


5.2 Link and comment source code			*utl-useSourceCode*

This is a usage of big potential IMHO. But as Utl is currently only
implemented for the Vim Editor this usage might be of real benefit only for
people who have an own interest in quality source code. You can use Utl to:

- link between the source code files using fragment addressing. For
  instance point to a C/C++ header file where a structure/class is defined.

- link from a source code file to Man pages using the man: scheme (Unix only).
  For an example see [35].

- reference design documents, technical specification papers, illustrating
  pictures etc from within source code.

The Utl source code uses URLs itself, search in <url:../plugin/utl.vim>
for 'url:'


==============================================================================
6. Tips, details, pitfalls				*utl-tipsdetails*

-----
Using a hot key						*utl-hotKey*

Mappings to shorten :Utl commands have already been explained, see
[29] / <url:../plugin/utl.vim#r=suggested_mappings_visual>. Using a hot key is
even shorter and gives perhaps more "hypertext feeling". Examples:

    :nmap <F4> :Utl ol<cr>

Or still more radical with double click?:

    :nmap <2-LeftMouse> :Utl ol<cr>


-----
Writing correct URLs					*utl-writeUrls*

- Pittfall: Don't use backslashes

  Even on MS Windows do not write:

      <url:file:D:\htdocs\corephp\kalender\WebCalendar\index.php>   # bad!!!

  Instead write:

      <url:file://D:/htdocs/corephp/kalender/WebCalendar/index.php> # good!

- Tip: Use relative URLs instead of absolute URLs whenever possible. For
  example, use:

      <url:sub_dir/foo.txt> or
      <url:./sub_dir/foo.txt>	# same as previous line

  instead of:

      <url:file:/full/path/to/sub_dir/foo.txt>

  Other example with file which is in a directory with is parallel to the
  directory where the current file is in:

      <url:../sibbling_dir/foo.txt>


-----
Pitfall: Absolute URLs do not combine!			*utl-absDontCombine*

The following makes no sense:

    <url:file:../do/not/do/this>	    # VERY BAD

Here is the easy rule to keep in mind: If the protocol (`file:' in this case)
is present, then it's an absolute URL! If it is absent, then it is a relative
URL.

An absolute URL is taken as is! The ../ in the example suggests a relative
path. But since the URL is absolute, the path will _not_ be combined with the
path of the document containing that URL. Executing the link above is about
the same as typing the Vim command:

    :edit ../do/not/do/this

That means: the result depends on the current directory, not on the directory
of the file containing the URL. Not what you want!


-----
Pitfall: Protocol and file type are different things	*utl-protvsftype*

This is really important to understand, especially if you are going to extend
Utl by your own protocol and media type handlers. People tend to create
a protocol where a media type is the better choice.

Example: Linking to a HTML file does not mean that you necessarily need the
http: protocol then! Protocol and file type (= media type) of the link target
are completely independent.

You can have `http:' to retrieve a txt file:

    <url:http://www.ietf.org/rfc/rfc2396.txt>

Or you can have `file:' to link to a local HTML file:

    <url:file:///usr/local/apache/htdocs/index.html>

Utl.vim knows scheme handlers (implemented in ../plugin/utl_scm.vim, 
function Utl_AddressScheme_<scheme>) and media type handlers (variables
utl_cfg_hdl_mt_<media-type>). First the scheme handler is performed
(download), then the media type handler (display).

							*utl-efmeddep*
-----
Detail: Embedding and fragment interpretation depend on media-type

As you already know, Utl introduces the embedding `<url:myUrl>' for plain text
files. For HTML files (.html or .htm), it makes sense to support HTMLs
embedding, i.e. something like `<A HREF="myUrl">'. This means that when
editing a HTML file and executing  :Utl  to follow a link, utl.vim expects the
pattern `<A HREF...>' under the cursor. This can be useful if editing and
browsing local html files "under construction".

The URL embedding syntax relates to the media type of the source of the link.
The fragment expression syntax relates to the media type of the target of the
link. The semantics of the fragment expression depends on the media-type.

If the target is a HTML file, with an IdRef expression like `#myFrag' then
Utl finds the position `<A NAME="myFrag">' (it will not parse the HTML file
though, merely search it; but in practice this works as expected).  When
the target is any other file type (utl.vim only distinguishes HTML from all
others) then Utl finds the position of `id=myFrag' (case never matters).

So you can really use Utl as a HTML-Source-Browser! That's useful
especially for editing and browsing your "under construction" web site.

The other fragment expressions like line=, tn= do not depend on the file
type (= media-type) in utl.vim.


==============================================================================
7. Configuration and Options				*utl-config*

All configuration and customization is done via global Vim variables.

You need not do anything in advance since missing configuration variables are
detected dynamically. Utl.vim will present you the file <url:../plugin/utl_rc.
vim> that contains template variables along with some help. You can just add
or uncomment variables there and activate the changes per ":so %".
More conventionally the variables can also reside in your vimrc file. Utl.vim
will take care to not overwrite changes done in utl_rc.vim when updating to a
newer version. The utl_rc.vim file approach has been chosen to make getting
started with Utl.vim as easy and painless as possible.

It is recommended to enclose all variables in utl_rc.vim in "if !exits(var)"
blocks. This way you can easily take any variables over into your vimrc file
without adapting utl_rc.vim.

-----
Config Variables					*utl-configcfg*

All configuration variables are named utl_cfg_*. Type: >

    :let utl_cfg_<CTRL-D>

to see all config variables. As stated you need not to know the individual
variables because they are demanded dynamically.

-----
Option Variables					*utl-configopt*

Besides config there are two option variables:

							*utl-opt_verbose*
Verbose mode on/off >

    :let g:utl_opt_verbose=0/1		    " 0=no (default), 1=yes
. 
							*utl-opt_hlighturls*
Verbose mode on/off >

    :let g:utl_opt_highlight_urls='yes'/'no'  " 'yes' is default

There is no option to customize the highlighting colors. But the source code
<url:../plugin/utl.vim#highl_custom> gives some samples you might want to try.

-----
Internal and External Utl variables			*utl-configIntExt*

Type >

    :let utl_<CTRL-D>

to see all variables Utl.vim uses. Variables which have a double underscore
in their name (like in utl_cfg_hdl_scm_http__wget), are internal to Utl and
should not be changed. All other variables you can change, even those that
might be predefined by Utl.vim (like utl_cfg_hdl_mt_generic under Windows).


==============================================================================
8. Changes since Utl-2.0              			*utl-changes*

OVERVIEW						*Utl-chgOverview*

The most important changes are:

- Added generic media type handler: open .pdf, .doc,	|utl-chgNewGenMTHdl|
  .jpg etc without the need to define handler variables.
- Added support for footnote references: make "[1]"	|utl-chgAddFootRefs|
  executable.
- Added scheme to open emails, e.g.			|utl-chgNewMailScheme|
  <mail:///Inbox?26.07.2008 16:01>
- Added verbose mode: Better figure out what's going    |utl-chgNewVerbose|
- Added 'copy link/filename to clipboard' function	|utl-chgNewOperators|
- Changed user interface: Basic Command :Utl instead	|utl-chgUI|
  only mapping \gu
- Alternate http access method: open web documents	|utl-chgNewHttpAccess|
  directly in Vim
- Support network files (shares, NFS), e.g.		|utl-chgNetworkFile|
  <file://127.0.0.1/path/to/file>
- Improved jumping back and forth			|utl-fixedBackForth|
- More versatile scheme handler interface		|utl-chgcfgscm|
- Fixed Bugs

Following the changes in detail.

INCOMPATIBLE CHANGES					*utl-chgincompat*

-----
All mappings \gu, \gE,... gone				*utl-chgUI*
It is a design goal of Utl.vim to have no side effects and to stay out
of the way. A mapping could clash with the mappings of other plugins.
Therefor mappings are no longer the standard user interface to Utl.vim;
new user interface is the command :Utl , see |utl-tutUI|.

See <url:../plugin/utl.vim#r=suggested_mappings> to define the 
mappings to :Utl commands to the get the behavior of Utl v2.0.

-----
Changed variable names					*utl-chgVarNames*

The naming scheme has been changed for a clearer scheme. All configuration
(=setup) oriented variables are now named utl_cfg_... , for instance 
utl_cfg_hdl_mt_application_msword. All option oriented variables are now
named utl_opt_, for instance utl_opt_verbose. All internal variables internal
to Utl.vim have two underscores in the name. See |utl-customization|
During installation you are guided to renaming the variables. You can check
with <url:vimscript:call Utl_finish_installation()> if there are still old
variables around.

-----
Command :Gu gone					*utl-chgGuGone*

Instead
    :Gu <url> <displayMode>
you have now to use
    :Utl openLink <url> <displayMode>

-----
Change in SCM Handler Interface				*utl-chgScmIf*

The scheme handler functions in <url:../plugin/utl_scm.vim> have got
an extra argument 'dispMode'. So in case you created or changed an
existing scheme you have to adapt this. It's normally sufficient to
add the argument to the function, e.g.

    Utl_AddressScheme_file(auri, fragment)
    --->
    Utl_AddressScheme_file(auri, fragment, dispMode)

-----
URL lookup table disabled, commands \gs, \gc gone	*utl-chgCacheGone*

V2.0 maintained a lookup table for URLs that mapped local files into URLs.
This allowed to resolve relative URLs within web pages. But the design had
conceptual problems, especially in conjunction with new footnote references
|utl-totfoot| [41]. Since not of big practical relevanve I decided to disable
the lookup table. This means that only relative URLs file:// URLs can be
resolved, e.g. ./some_file.txt -> file://path/to/file.txt. As a consequence
the commands \gs, \gc are gone as well as the file utl_arr.vim which
implemented an associative array (a data structure that was not available
in Vim 6).


CHANGED							*utl-chgchanged*

-----
More versatile scheme handler interface			*utl_chgcfgscm*

Utl 2.0 used the two variables utl_cfg_app_browser, utl_cfg_app_mailer,
which have been used to parametrize the http- and mailto- scheme handler.
This pragmatic approach has been replaced by a more consistent and
systematic interface. The above two have been renamed:

    utl_cfg_app_browser -> utl_cfg_hdl_scm_http
    utl_cfg_app_mailer  -> utl_cfg_hdl_scm_mailto

which clearly associates each variable with its scheme. New variables

    utl_cfg_hdl_scm_mail	# new for new mail: scheme
    utl_cfg_hdl_scm_scp		# now scp: scheme parametrizable

have been added. Not all supported schemes are yet parametrized though.

The interface is specified at <url:../plugin/utl_scm.vim#r=spec_ihsv>

-----
Minor: Changed syntax highlighting of URLs		*utl-chghighl*

The URL surroundings `<url' and '>' no longer highlighted, only the URL
itself.

    You can change the highlighting of the URL surrounding and the URL
    itself in the source:
	<url:../plugin/utl.vim#highl_surround>
	<url:../plugin/utl.vim#highl_inside>
    Some commented out samples are given there. (Do not forget to write down
    the changes you made in order to prevent overwriting when you install
    a new Utl.vim version.)



ADDED							*utl-chgadded*

-----
New generic media type handler for any media type	*utl-chgNewGenMTHdl*

In v2.0 for each media type an individual media type handler variable had to
be defined. Added a generic media type handler which will be called if no
specific media type handler is defined. See |utl-tutmtypes|.

-----
Added support for footnote references			*utl-chgAddFootRefs*

In given texts you often find references like:

    ----- (Example taken from <url:vimhelp:beos-timeout>)
    "Because some POSIX/UNIX features are still missing[1], there is no
     direct OS support [...]"
    .
    .
    [1]: there is no select() on file descriptors; also the termios VMIN [...]
    -----

These can be executed using Utl.vim. See |utl-tutfoot|.


-----
New operators on URLs					*utl-chgNewOperators*

- copyLink     - copy link to clipboard, see |utl-tutCopyLink|
- copyFileName - copy filename corresponding to clipboard, see |utl-tutCopyFileName|

-----
New URL operand						*utl-chgNewOperand*

- currentFile  - Operates on the current file, i.e. creates an URL from the
  current file and use it as the URL to be operated on (instead the URL under
  the cursor (operand underCursor) or an URL typed in at the command line
  (operand = the typed URL).

-----
New mail scheme						*utl-chgNewMailScheme*

Introduced a non standard scheme for referencing emails from your local mail
boxes via URL. Example: <url:mail:///Inbox?date=12.04.2008 15:04>. Currently
the only implementation for actually displaying the emails if for MS Outlook.
See |utl-tutscmmail|.

-----
New verbose mode					*utl-chgNewVerbose*

Set Vim variable
    :let utl_opt_verbose=1
to see what's going on when executing an URL. See |utl-tutverbosemode|.

-----
							*utl-chgFragAW*
Support fragment addressing for Acrobat Reader and MS Word  

If you use Acrobat Reader you can execute an URL like:
<url:http://www.tech-invite.com/RFCs/PDF/RFC3986.pdf#page=4>. See
|utl-tutpdffrag|.
If you are under Windows and use MS Word you can execute an URL like:
<url:my.doc#tn=textToSearch>. See |utl-tutwordfrag|.

-----
New HTTP-URL access method				*utl-chgNewHttpAccess*

Two standard methods are provided for accessing http URLs:
- Delegation to your internet browser and 
- Display inside Vim (using the non-interactive retriever "wget")

(1.) was the only method in Utl-V2.0, where (2.) was the only
method in Utl-v1.x
Now the one or the other method can be used, choosing it URL by URL.
See |utl-tutscmhttp| 

-----
Support network files (Shares, UNC, NFS)		*utl-chgNetworkFile*

You can now access Windows share files like
    <URL://127.0.0.1/ADMIN$/System32/EULA.txt>
or Unix shares (e.g. NFS) like
    <URL://server/sharefolder/path/to/file.txt>
See |utl-tutdrivesshares|.


-----
							*utl-chgNewFragConv*
Support %f fragment conversion specifier in media type handlers

New fragment conversion specifier %f allowed in media type variables. For
external media type handlers fragments can now be passed to the handler.
This enables URLs like the these to be performed:

    <url:./path/to/file.pdf#page=3>
    <url:./path/to/myWordDocument.doc#searchText>
    <url:./path/to/websources/mypage.html#htmlAnchor>

-----
Support negative numbers in #line= fragments.		*utl-chgLineNegative*

#line=-3 positions cursor three lines upwards. Starting either from bottom of
buffer or, if relative addressing (see |utl-tutfragsrel|) from current cursor
position.


FIXED BUGS						*utl-fixed*

-----
Allow single quotes in URLs

Example: The URL <url:vimhelp:'compatible'> did not work because single quotes
where use for quoting inside Utl.vim.

-----
Fixed fragment quirks

- In certain cases (involving for instance files already displayed in buffer
  or Vimhelp URL) the wrong cursor position was set.

- More clear when relative fragment addressing happens.
  This depended on whether file was already displayed or was displayed by the
  scheme handler. Now only for same-document references |utl-tutfragsdref| or
  for non file oriented fragment addressing |utl-tutfragsnonfile|. 

-----
Jump forth and back with ctrl-o/-i improved		*utl-fixedBackForth*

Jumping back from link target to link source with ctrl-o should be more
reliable now (added explicit context marks before certain cursor changes).

-----
Fixed visual area off by one error (Windows)

Under Windows when visually selecting an URL the character following the
visual area was taken into the URL.

-----
Fixed bug with media type to variable name mapping

Media types can contain characters . + - which must not be mapped directly
into variables. Now convert all . + - all into underscores. Example:
Variable for video/x-msvideo is utl_cfg_hdl_mt_video_x-msvideo.



==============================================================================
9. Todo     						*utl-todo*

-----
Wish list

- Better support for URL creation (authoring support)

- Check for dangling links
  Provide a function to check whether all links point to existing targets.

- Follow links when searching.
  Add a function which searches the file tree which is defined by a file
  containing file URLs.

-----
Known major bugs					*utl-knownbugs*

- Not compliant to newer URI specification [RFC3986], rather to obsoleted
  [RFC2396]. 

- Found fragment string of #somestring will not be the current search string.
  See <url:#tp=The found string>

- Jump to wrong target if URL is substring of current file.
  Have displayed a file /tmp/s.txt, which contains a folder URL <url:/tmp>.
  Executing it will display the folder /tmp but rather jump to line 1
  of current file /tmp/s.txt. Reason is that Vim function bufwinnr() is used
  to check if to be loaded file (i.e. folder /tmp) is already loaded.
  Bufwinnr takes file-patterns as arguments not full names. /tmp is a match
  for /tmp/s.txt. Utl.vim thinks the target is already displayed and just
  positions the cursor (to line 1).

- Exclamation mark in externally handled URLs to be escaped.
  In URLs that contain URLs like
  <URL:http://server.foo.com:9010/bugtracker/secure/CreateIssue!default.jspa>
  the exclamation point  !  will be expanded by Vim on the command line of the
  invoked shell. Utl.vim should escape the !, but is doesn't, so you have to 
  workaround yourself. Insert two \\ before the !, e.g.
  <URL:http://server.foo.com:9010/bugtracker/secure/CreateIssue\\!default.jspa>
  See <vimhelp::!#Any>. NOte that actually a double backslash is needed since
  Utl.vim consumes one for itself before Vims :! is invoked... probably
  another bug.

- Utl copylink does not percent encode invalid URI characters.
  For a link containing blanks (under Windows) like
  <url://c:/tmp/file name with blanks.txt> the command  :Utl copylink
  yields the URL <url:file://c:/tmp/file name with blanks.txt>. Although
  this URL can be executed within Utl itself or can be used in Windows
  Explorer etc. it is not a valid URL since the space character is not in the
  URI character set (see <[RFC3986]#tn=^2.  Characters>). Utl.vim should
  percent encode the space: <url:file://c:/tmp/file%20name%20with%20blanks.txt>.
  Other characters than space have similar problems (also under Unix).
  The invalid URLs is really a problem when you try to open the URL with
  :Utl ol file://c:/tmp/file name with blanks.txt  (in other Vim instance as
  described at <url:vimhelp:utl-tutCopyLink#Vim instance>.
  
- Spell checking in URLs.
  URLs embedded in <url: and > should not be spell checked. (Unembedded URLs
  cannot be excluded anyway because not parsesafe.)


==============================================================================
10. Credits						*utl-credits*

Tatjana Dreier, for her patience
Wolfgang Fleig, my partner, for sponsoring, testing, feedback
Ines Paegert, for her impulses.
Bram Moolenaar <Bram at moolenaar.net>, for the Vim editor.
Barrie Stott <G.B.Stott at bolton.ac.uk>, for helping a lot with the
	documentation
REKellyIV <Feral at FireTop.Com>
Klaus Horsten <horsten at gmx.at>.
Patrik Nyman <patrik.nyman at orient.su.se>
Engelhard Heß <Engelhard.Hess at artofbits.de>
Grant Bowman <grantbow at grantbow.com>
Ward Fuller <wfuller at SeeBeyond.com>
Mark S. Thomas <Mark.Thomas at SWFWMD.STATE.FL.US>
William Natter <wnatter at nortelnetworks.com>
Alex Jakushev <Alex.Jakushev at kemek.lt>
Geoff Caplan <geoff at advantae.com>
Bruno Díaz <bruno.diaz at gmx.net>
Michael Lesniak <ich at mlesniak.de>
Janek Kozicki <janek at thenut.eti.pg.gda.pl>
Olivier Teulière <ipkiss at via.ecp.fr>
Nathan Howell <nathan at atdot.ca> 
Samuel Wright <sam.wright@celoxica.com>
clemens fischer <ino-qc@spotteswoode.de.eu.org>
Gabor Grothendieck <ggrothendieck@gmail.com>
Bill Powell <bill@billpowellisalive.com>
Jeremy Cantrell <jmcantrell at gmail.com>
Charles E. Campbell <drchip@campbellfamily.biz>
Al S. Budden <abudden at gmail.com>, for Pdf page addressing and idea to use
	Windows start command as generic handler.
Alpt <alpt@freaknet.org>
Cristian Rigamonti <cri at linux.it>
Olle Romo <olleromo at metasound.ch>


==============================================================================
FOOTNOTES

[20] But you can use something like:
    <url:vimscript:!net use w: %5c%5c56.240.73.41%5cc$ myAdminPassword /user:administrator>
    to authenticate (the %5c masks the \ in the URL). The Vimscript scheme and
    masking will be explained later in the docs.

[22] It is not sufficient to provide a media type handler variable to make
    a new specific handler work. There has to be a file extension to
    media type mapping defined, see <url:config:#r=new_mt>. Again, perform
    Utl.vim with verbose mode set to get this illustrated - watch out for
    section 'start media type handler processing' in the output.
    If no mapping is defined, no handler variable will be evaluated, and
    the file will be displayed in current Vim.
    If a mapping is defined, a handler has to present (at runtime when such
    a file is performed).

[23] NOte that you cannot include this line in your .vimrc because it is
    :source'd before utl_rc.vim (which defines g:utl_cfg_hdl_mt_generic).
    So either include/change it at <url:config:#r=utl_cfg_hdl_mt_text_directory>
    or include it in the after-directory, see <url:vimhelp:after-directory#5.>

[24] If a typed URL clashes with a keyword or an abbreviated keyword
    prefix it with a ./    Example:
    If you want to open the literal URL "underCursor" use
	:Utl openLink ./underCursor

[25] The displayMode is currently only used for link targets displayed in Vim
    and are ignored if the resource is displayed by an external handler.

[26] I don't know why this isn't Vim's default...
    Check if currently set with	  <url:vimscript:set wildmenu?>
    Set it with		          <url:vimscript:set wildmenu>
    Then retry the given <Tab> examples to see the difference.
    For help see		  <url:vimhelp:'wildmenu'>

[27] For the third argument in  :Utl openLink  command (the  mode  argument)
    only a few values are offered for completion. Actually any Vim command
    that takes a file name as argument is allowed here. Colons are also
    allowed if this gives you more Vim feeling. Examples:
	:Utl openLink underCursor :edit	    " or
        :Utl openLink underCursor :e
    More exotic examples are:
	:Utl openLink underCursor :vertical diffsplit
	:Utl openLink underCursor :bad
    This one does unfortunately not work as expected in Utl v3.0a:
      :Utl openLink underCursor :e!
    Switch on verbose mode to see why.

[28] Unfortunately :U is not possible because of the :UseVimball standard
    plugin command. I think that this is unnecessary polution of the name
    space, Vimball should better have chosen an approach like Utl, e.g.
    :Vimball use. 

[29] The Ctrl-C is normally not needed under Unix. Also not needed under
    Windows if the 'guioptions' contains 'a' Autoselect flag, see
    <url:vimhelp:guioptions>.  :Utl openLink visual  just takes the
    contents of the "* register, see <url:vimscript::reg *>. If you find
    Ctrl-C is too inconvenient you could use mappings like these:
    <url:../plugin/utl.vim#r=suggested_mappings_visual>

[30] You can use the Vim command  :asc  to get the hex value of a character,
    see <url:vimscript::h asc>

[31] Well, normally the 'save as' dialog offers the base name, you copy
    this name and paste it for the construction of the link in your text
    file, and then come back with the complete path into the mailer's
    'save as' dialog.

[32] The implementation is via a VBS script that uses the OLE Automation
    capabilities of Outlook. Outlook Express does not support OLE Automation.

[33] There are two plugins that allow browsing mbox files:
    <url:http://www.vim.org/scripts/script_search_results.php?keywords=mbox>
    Perhaps these can serve as a starting point an implementation for
    mbox emails.

[34] The general query format is 
    date=<date>&from=<from>&subject=<subject>.
    But only date is currently supported in the VBS script.
    So if you received two mails within the same one or two minutes 
    you cannot properly select the correct one (resending one of them to
    yourself is a workaround).

[35] You can use the man: protocol to hotlink from a program source code file
    to the relevant man page. Utl.vim delegates to the  :Man  command, which
    is implemented by the ManPageView plugin
    <url:http://www.vim.org/scripts/script. php?script_id=489> Example:

    [myopen.c]
    .
    .
    .
    /* Opens file "filename".
     * See <url:man:open#tn=flags is one of> for possible values of the `flags' 
     * argument.
     * The restrictions described under <url:man:open#tn=^RESTRICTIONS> also
     * apply to this function.
     */
	int
    myopen(char* filename, int flags)
    {
	//
	open(filename, flags, mode);
	//
    }
    .
    .
    .
    EOF


[36]
    * VimFootnotes : Insert various types of footnotes with Vim. 
      [36_1] <url:http://www.vim.org/scripts/script.php?script_id=431>

    * uri-ref : Easily insert references to URLs in emails
      [36_2] <url:http://www.vim.org/scripts/script.php?script_id=76>

    * Markdown syntax : Syntax file for Markdown text-to-HTML language  
      [36_3] <url:http://www.vim.org/scripts/script.php?script_id=1242>
      This is only the the syntax file. Markdown is a text-to-HTML conversion
      tool and that text can contain footnote references, which are supported
      by Utl.vim

    Tip: When creating footnote references you'll often find yourself
    searching for those footnotes, which is complicated because [ and ]
    are magic characters. Search with \M preprended, e.g. \M[10], see
    <url:vimhelp:%5cM>

[37] You might wonder what is the difference between "[123]" and "[123]:".
    Of course any character can follow follow. But it is treated
    differently by utl.vim in case the reference gets forwarded
    automatically if a fragment is appended like this:
    [123]#xxx (this will be explained later). Aside from Utl.vim treatment I
    guess it is good style to have a blank or tab coming after the closing
    bracket ]. The format  [123]:  is used by the Markdown tool [36_3].

[38] This seems to be a problem in some cases. For instance it makes
    reference targets within comments of some programming languages 
    impossible:

	use Dumpvalue;	# [124] 
	.
	.
	# [124] http://perldoc.perl.org/Dumpvalue.html  <-- Does not work

[39] Keep in mind that a relative file is also an (file://) URL. Often files
    in source code systems reference each other via relative files either in
    comments or kinds of include- or call-statements. Examples:
    ./prog.c has a comment line:  /* prog.h ... */
    ./prog.c has an include statement:  #include "prog.h"
    ./script.bat contains a line:  call otherScript.bat
    ./script.sh contains a line:  source ./tools/otherScript.sh 
    Quite often these references are directly suitable for being executed by
    Utl.vim. Well, the more you use Utl.vim you get more "URL aware" and 
    get the habit of writing comments and so on which are suitable as URLs.

[40] It would be interesting to facilitate creation of links. For instance:
    - drop files into Vim window. But insert as link, not the normal behavior
      of opening and displaying the file,
    - convert Vim marks into links. Within same Vim session, create a mark
      at link target, goto to place from where you want to link, and a call
      a command like  :Utl insertLink mark  to insert a file:// URL with
      fragment.

[41] Lookup table explained: Take a web URL retrieved with wget and displayed
    in Vim (see |utl-tutscmhttp|) that contains a relative URL
    ./other_page.html. This link could be resolved in v2.0 via the lookup
    table. Problem was 1. that the implementation was buggy due to
    normalization problems with URLs and 2. conceptual problem with wrong
    scheme associations: Example: After having executed [1] (-> foot:1)
    executing a link ./some_file.txt in the same source file lead to a link
    foot:some_file.txt instead of /path/to_source_file/some_file.txt.

[42] http://www.vim.org/scripts/script_search_results.php?keywords=wiki&
     script_type=&order_by=rating&direction=descending&search=search

[RFC3986] <url:http://www.ietf.org/rfc/rfc3986.txt>
[RFC2396] <url:http://www.ietf.org/rfc/rfc2396.txt>

[UTL_RC] ../plugin/utl_rc.vim

 vim:tw=78:ts=8:ft=help:norl:fdm=marker:fen