add vim conf files

[arrow.git] / conf_slk120 / vim / _vim / doc / utl_usr.txt

*utl_usr.txt* Plugin for executing URLs in plain text files\r
*utl* *utl-plugin* \r
For Vim version 6, Version: utl-2.0, $Revision: 1.1.1.1 $\r
\r
\r
                       Utl.vim User Manual\r
\r
                         By Stefan Bittner\r
                        stb@bf-consulting.de\r
\r
        Contents:\r
\r
                1. Intro........................|utl-intro|\r
                2. Getting started..............|utl-getstart|\r
                3. Tutorial.....................|utl-tutorial|\r
                4. Examples of use..............|utl-examples|\r
                5. Tips, details, pittfalls.....|utl-tipsdetails|\r
                7. Changes since Utl/Thlnk-1.2..|utl-changes|\r
                8. Todo list....................|utl-todolist|\r
                9. Credits......................|utl-credits|\r
\r
\r
See |utl_ref.txt| for some reference material.\r
See http://vim.sf.net/script.php?script_id=293 for installation instructions\r
\r
See |utl-changes| for things that have changed in this version.\r
\r
Any comments, bug reports, pachtes, fixes and suggestions are welcome, and\r
sometimes needed for my motivation. See |utl-todolist| if you want to\r
contribute to Utl.\r
\r
Happy linking,\r
Stefan Bittner <URL:mailto:stb@bf-consulting.de>\r
\r
==============================================================================\r
1. Intro                                                *utl-intro*\r
\r
Welcome to utl.vim!\r
\r
What is Utl.vim\r
---------------\r
\r
* It brings the benefits of URL-based hyperlinking to the realm of plain text,\r
  extending the URL syntax for plain text needs, in accordance with the RFC 2396\r
  URI specification.\r
\r
* It's a handy utility for you right away\r
\r
* It's fun :-)\r
  surfing text files, executing text ...\r
\r
\r
What is it good for?\r
--------------------\r
\r
* Enables Vim to be your central desktop application, for instance:\r
\r
  - Easily navigate in collections of related text files via hyperlinks\r
  - Call web browser and email client on URLs (configurable protocol handlers)\r
  - Call MS-Word on .doc files, Acrobat Reader on .pdf, Windows Explorer on\r
    directories, IrfanView on .jpg etc. (configurable media type handlers)\r
  - Maintain pictures from your digicam based on a text file\r
  - Maintain a personal info file containing hotlinks\r
\r
* Use it for project management, software development, report preparation and\r
  technical writings. For instance:\r
\r
  - Reference emails from text files\r
  - Reference bug tracker database from a text file\r
\r
* Smart usages. For instance:\r
\r
  - Embed vim commands in text files and source code.\r
  - Use it as light weight spell checker,\r
  - or for dictionary lookups.\r
  - Start programs using Utl.\r
  - Use it for relative editing and\r
  - for navigating HTML source code.\r
\r
* Use it for quality commenting of source code. For instance:\r
\r
  - Reference related code with hot links, e.g. reference the definition of a\r
    struct in C/C++\r
  - Reference design papers, UML diagrams, man pages etc from source code\r
  - Turn references like "see below" and "type zR to open the folds" into\r
    hotlinks\r
\r
\r
Utl.vim is easy \r
-----------------\r
\r
* You only need to know one single command to get started: \gu = Go URL \r
\r
  1. Type :help utl-getstart \r
  2. Hit \gu on the live examples given there \r
\r
  As a reader of texts containing URLs that's all! As an author you have to \r
  know how to write URLs. But utl.vim gives you a training. And what you \r
  will learn is 90% general knowlegde about URLs that you can use elsewhere. \r
\r
* Utl.vim is friendly: \r
  No side effects, fits seamlessly into your Vim Session, well documented. \r
\r
Want to give Utl a try? Fine, so lets just dive into the live examples:\r
\r
\r
==============================================================================\r
2. Getting started                                      *utl-start*\r
\r
Utl.vim's basic mapping is \gu which stands for "Go Url". That's all you need!\r
\r
Note: If you have changed the mapleader string your actual mapping might also\r
be ,gu or _gu or whatever, see |mapleader|.\r
\r
Live Examples now!!!\r
\r
Position the cursor on the next line:\r
    <URL:#r=here>\r
Then hit `\gu'. This should take you ...\r
    id=here.\r
\r
You just executed your first link!\r
`#r=abc' refers to a position in the document, that looks like `id=abc'. (If\r
you know HTML: that's analogues to a <A HREF="#abc"> which refers to\r
ID="abc".) The `r' in the expression stands for `reference'.\r
\r
Hitting `\gu' on <URL:#tn=some text> takes you to ... some text.\r
\r
The special syntax `tn=' just means that the target of the link is defined by\r
searching the denoted string (some text) in forward direction (tn stands for\r
Text Next). You can leave away the `tn=' prefix and just write <URL:#some\r
text> because the tn= is the default prefix.\r
\r
Hitting `\gu' on <URL:utl_ref.txt> takes you to the file utl_ref.txt.\r
\r
Please come back here again after having executed the link!\r
\r
Hitting `\gu' on <URL:utl_ref.txt#tn=^thanks for> takes you to a specific\r
position in the file utl_ref.txt. This example can be seen as the combination\r
of the two previous examples: URL + #xxx\r
\r
The #xxx suffix is called a fragment expression in URL lingo.\r
\r
Hitting `\gu' on <URL:http://www.vim.org> will invoke your web browser with\r
that URL. Just try it, Utl will assist you to set up your favorite browser.\r
\r
You can leave away the <URL:...> embedding. Try for example:\r
\r
    http://www.vim.org\r
\r
or even              +------- This is also a link which you should execute :-)\r
                     |\r
    www.vim.org [#r=foot1]\r
\r
An advantage of embeddingless links is that normally you will find URLs in\r
given documents in this form. Also, some people find the <URL:...> embedding\r
too clunky. The disadvantage is that there is no safe parsing for "naked" URLs\r
and as one consequence of this, no syntax highlighting.\r
\r
You can also type an URL in the command line:\r
\r
    :Gu utl_ref.txt     # Edit file in same directory as current file\r
    :Gu www.google.com  # Start web browser from within vim. Sometimes\r
                        # faster than from desktop :-)\r
\r
If you feel it's now time for a "hello world" test, just go ahead and write\r
your own links. There is no meta data and no tags file needed. Its nothing\r
but plain text.\r
\r
Before you seriously start using utl.vim it is recommended to continue with\r
reading the next chapter, 3, Tutorial. If you are in doubt if Utl valuable for\r
you, have a look at chapter 5, Examples of use, |utl-examples| first.\r
\r
\r
==============================================================================\r
3. Tutorial                                             *utl-tutorial*\r
\r
\r
3.1 Forth and back                                      *utl-tutforthback*\r
\r
From the previous chapter you already know how to follow links by hitting \gu\r
when a link is under the cursor.\r
\r
The following link, as you know, takes you to another file:\r
\r
    <URL:utl_ref.txt>\r
\r
Try this now! ... No, Wait! To come back here again, just use the regular\r
vim command CTRL-O. That's the BACK-Button in the "Vim browser" - and it might\r
need to be typed more than once.\r
Now do it! \r
\r
Hope you are back again.\r
\r
\r
3.2 Relative and absolute URLs                          *utl-tutrelabs*\r
\r
The following URLs are all equivalent:\r
\r
    <URL:utl_ref.txt>\r
    <URL:./utl_ref.txt>\r
    <URL:../doc/utl_ref.txt>\r
\r
These are all  _relative_  URLs. This means that the path given in the URL is\r
relative to the path of the document containing the URL. Note that this is\r
different to Vim's :e command where file names are relative to the current\r
working directory (see |:pwd|). Whenever possible you should use relative\r
URLs. But sometimes you need  _absolute_  URLs, just as you sometimes need\r
absolute path names with Vim's :e command. Here is an absolute URL[#r=foot3]:\r
\r
    <url:file:///home/stb/.vim/doc/utl_ref.txt>\r
\r
An absolute URL _always_ has a so called scheme (also called protocol) in\r
front, e.g. file: , http:, mailto: . (And, if there is a protocol in front it\r
always is an absolute URL.) What also makes sense is to write the above URL\r
without the protocol:\r
\r
    <url:/home/stb/.vim/doc/utl_ref.txt>   # equivalent to above\r
\r
This is a relative URL (because there is no protocol) ... containing an\r
absolute path. The contrary does not make sense: An absolute URL with a\r
relative path:\r
\r
    <url:file:./utl_ref.txt>    # WRONG!!! Absolute URL with relative path\r
                                #          makes an invalid URL.\r
\r
Under Windows you can specify drive letters like this:\r
\r
    <url:file://d:/path/to/foo.txt> or, which is the same,\r
    <url://d:/path/to/foo.txt>\r
\r
This is in conformance with URL specifications. Note that you always should use\r
forward slashes, no matter on what OS you are; URLs are universal and are\r
independent of the OS.\r
\r
\r
3.3 Fragments                                           *utl-tutfrags*\r
\r
Now lets add fragments to the URL.\r
The next link again references the same file as in the above examples, but is\r
extended by a fragment expression. That way a specific position in the target\r
file can be jumped to. Try to execute the link:\r
\r
    <URL:utl_ref.txt#tn=thanks for>\r
\r
and come back again with CTRL-O. The next link specifies the same file, but\r
the fragment expression is different:\r
\r
    <URL:utl_ref.txt#r=foot1>\r
\r
Execute it and come back again! It took you to about the same position as the\r
previous link, but by other means. The fragment `#r=foot1' means, that the\r
file utl_ref.txt is searched for the ID reference `foot1'. What follows r=\r
should be a simple string (an identifier to be exact).\r
\r
The #tn fragment has one big advantage over #r= fragments. It allows to\r
refer to specific positions in the target document without the need to\r
modify that target document, either because you don't want it or because you\r
don't have write access. The advantage of the ID reference fragment is that\r
the link is more robust.\r
\r
#tn= and #r= are the most important fragment specifiers in utl.vim. As\r
already said, the #tn= prefix is the default prefix, i.e. you can leave it\r
away. Thus the link above ( #tp=thanks ) will normally be written shorter:\r
\r
    <URL:utl_ref.txt#thanks for>\r
\r
This is also called a naked fragment identifier because there is no `key='\r
prefix. \r
\r
Here is an overview of the available fragment expressions:\r
\r
    #tn=text        Same as #text\r
    #tp=text        Stand for `t'ext `p'revious, i.e. define position by\r
                    searching first occurance of `text' in backward direction.\r
    #line=123       Position defined by line number. Most useful for documents\r
                    which won't change\r
    #r=identifier   Position defined by the id `identifier'\r
\r
See |utl-fragexpr| for some explanation.\r
\r
\r
3.4 Other media types                                   *utl-tutmtypes*\r
\r
URLs are not restricted to .txt files or web pages. You can, for instance,\r
reference a MS-Word document:\r
\r
    <url:foo.doc>\r
\r
To make this work you have to define a handler for .doc type files. Utl tries\r
to make this a painless as possible through a smart setup facility. Go and\r
execute the above link to see how this works. In URL and Utl terms a .doc type\r
file is said to be of media type "application/msword". You can define a\r
handler for any media type you like. See the explanations under\r
<URL:config:#r=mediaTypeHandlers>. Here is a list of other typical media\r
types for which you might want to set up handlers:\r
\r
    <url:foo.pdf>   # PDF documents\r
    <url:foo.rtf>   # Rich text format documents (emails)\r
    <url:foo.ppt>   # Powerpoint documents\r
    <url:foo.xls>   # Excel sheets\r
    <url:img_0108.jpg>   # All kinds of images\r
    <url:path/to/some/directory>\r
                    # Call Vim explorer, Windows explorer, shell  etc. on\r
                    # directory\r
\r
\r
3.5 Typing an URL                                       *utl-tuttypeurl*\r
\r
In a web browser there are two ways to go to a page:\r
\r
1. You follow a hyperlink from the page you are in.\r
2. You type an URL yourself.\r
\r
Possibility 1 corresponds to \gu in utl.vim. Possibility 2 corresponds to an\r
utl.vim command :Gu\r
\r
    :Gu utl_ref.txt\r
\r
You can use the :Gu command for editing another file which is in the same\r
directory as the current file. Example:\r
\r
    gvim /really/an/annoying/long/path/to/src/main.c\r
    :Gu option.c\r
\r
I myself use :Gu for a lot for this purpose.\r
\r
\r
3.6 Other commands to execute a link                    *utl-tutothercmds*\r
\r
-----\r
Normal mode commands\r
\r
Until now we have used \gu to execute a link. That's the most important one.\r
Utl.vim defines several other command. \gu corresponds to Vim's :edit. The\r
other commands correspond to :view :sview etc. For example, the command \gE\r
opens the URL under the cursor in a separate Vim window. Position the\r
cursor on the following line and hit \gE to try this:\r
    <URL:utl_ref.txt> \r
See |utl-commands| for the list of mappings and commands.\r
\r
-----\r
Visual-commands\r
\r
There are also visual commands |utl-gourlvis|. But you will rarely need this.\r
An example might be: `(see www.vim.org)', i.e. an URL without embedding which\r
is surrounded by characters which confuse Utl's URL parsing (the ')' in this\r
case. Highlight the URL (see |visual-use| if you don't know how) and execute\r
\gu then.\r
\r
\r
\r
3.6 Supported schemes                                   *utl-tutsuppscms*\r
\r
Currently utl.vim supports the following protocols:\r
\r
    file:       # Protocol for accessing local files.\r
                # If machine is given works like `ftp:'\r
    ftp:        # Delegates to http, assuming that the browser handles this.\r
    http:       # Delegates call to your web browser\r
    https:      # Delegates call to your web browser\r
    mailto:     # Delegates call to your mail client\r
    man:        # Unix Man Pages scheme (see |utl-usesourcecode| for usage)\r
    scp:        # If you have a scp command\r
    vimscript:  # Vim specific. A scheme for executing vim commands. See\r
                # |utl-exvs| for usage.\r
    vimhelp:    # Vim specific. About the same as vimscript:help.  See\r
                # |utl-exvimhelp| for usage.\r
    config:     # Protocol for accessing Utl's setup file\r
\r
You can easily implement your own schemes or define new ones. You just define\r
a Vim function somewhere. Utl.vim dynamically calls those functions. Have a\r
look at <URL:../plugin/utl_scm.vim#r=implscmfunc>. I recommend that you read\r
chapter 5, Tips, details, pitfalls,  before you write your own scheme handler.\r
\r
\r
3.7 Miscellaneous                                       *utl-tutmisc*\r
\r
-----\r
Creating files using Utl\r
\r
If you execute an URL which points to a non existing file, this file (more\r
exact: its Vim buffer) will be created. This is very useful when authoring:\r
You write the URL in your document and then execute it. You can try this with\r
the URL <URL:utl_foobar.txt>. People told me that this feature is useful for\r
WIKI editing.\r
\r
-----\r
Multiline URLs\r
\r
You can spread URLs across several lines like this: <URL:../plu\r
gin/utl_uri.vim>. This is sometimes useful for long URL, see examples\r
below at #r=lu. When typing an URL and Vim breaks it (beacuse it contains a\r
space and Vim's 'tw' option set) you have to be careful: Utl eliminates all\r
spaces around the line break. The above link is thus equivalent to <URL:../plu\r
    gin/utl_uri.vim>. In order to preserve the space, you could escape it with\r
%20 (see |utl-uri-forbchars| about escaping), e.g. <url:this filename\r
    %20contains blanks.txt>. But you could also just split at another position:\r
<url:this filenam\r
    e contains blanks.txt>\r
\r
\r
-----\r
Tilde support\r
\r
You can use the ~ (tilde) character in URLs. Example: <URL:~/.vim/plugin/utl.\r
vim>. The ~ is replaced by the contents of the $HOME environment variable.\r
On Unix system ~user also works. See |$HOME|.\r
\r
\r
==============================================================================\r
4. Examples of use                                      *utl-examples*\r
\r
Here comes a rich collection of Utl examples, usage patterns and smart little\r
examples. If you go another example it would be nice you mail it to me.\r
\r
\r
4.1 Use Vim as your central desktop application         *utl-usedesktop*\r
\r
4.1.1 Index File                                        *utl-useindex*\r
\r
One usage is to maintain one or more text files which serve as an index or as\r
a central point of references. Basically like this:\r
\r
    ---index.txt-----------------------{\r
    <url:./foo/bar.txt>\r
    <url:../docs/foo2.doc>\r
    <url:../../quote/times.xls>\r
    ---}\r
\r
Many people like to load such a file as buffer #1 when starting up Vim and\r
then browse from there. Well, I do not use Utl for this, I rather work with a\r
self written tags file for this purpose or with a session file (see\r
vimhelp:mks) where a file always pertains to the same buffer number.\r
\r
\r
4.1.2 Project Management\r
\r
Here is a real example. The following is the root file for a software project\r
where the task is technical subproject management. The # comments are only for\r
explanation and not in the original file. It looks something like this:\r
\r
    --- poland_project.txt ------------{\r
    file: poland_project.txt - Poland Install project\r
    hist: 13.07.04/Stb\r
\r
    References\r
    ----------\r
                      # Link to architecture working document\r
    <url:../i/rcinstall_arch.txt>\r
\r
                      # Link to installation instructions\r
    <url:../../data/PL Installation Procedure - IMS Installation.doc>\r
\r
    <url:cr.txt>        # Link to my change requests notes\r
    <url:vers.txt>      # Link to SCM related stuff\r
    <url:t.txt>         # Link to test reports\r
    <url:t.txt#r=act>   # ... direct link to current test there\r
\r
                      # Link to root in document management system\r
    <url:http://kstbx032.ww010.siemens.net/livelink/livelink.exe?func=ll&\r
    objId=1007014&objAction=browse&sort=name>                       (id=lu)\r
\r
    Iinstall:           # Link to a specific document there\r
    <url:http://kstbx032.ww010.siemens.net/livelink/livelink.exe/RC_D_\r
    INSTALLATION_COMPONENT_IF_SPEC.doc?func=doc.Fetch&nodeId=1017472&\r
    docTitle=RC_D_INSTALLATION_COMPONENT_IF_SPEC%2Edoc&vernum=1>\r
\r
                      # Hot link to the current installation CD\r
    <url://q:/projekt_511/infrastructure/installation/polen/polen-cd>\r
    .\r
    .\r
    Correspondance      # Threads of project specific correspondance\r
    --------------\r
    .\r
    .                                                             # id=emailex\r
    <url:corr/20041219_RE FormXtra 2.6 question.rtf> # Reference to a RTF email\r
    <url:corr/20041220_RE FormXtra 2.6 question.txt> # Reference to a .txt email\r
    <url:corr/20041221_RE FormXtra 2.6 question.htm> # Reference to a HTML email\r
    .\r
    .\r
    -----------------------------------}\r
\r
The referenced files also contain links. I guess I do not have even one\r
selfwritten file which does not contain URLs.\r
\r
\r
4.1.3 Personal Info File                                *utl-useinfofile*\r
\r
Quite many people maintain something like a personal info file (I also do).\r
They note there for example:\r
\r
- Installation of tools they use on the job\r
- Usage of tools they use, for instance CVS usage and commands\r
- Links to network drives, resources and documentation\r
- Web links (instead or additional to bookmarks/favorites in web browser)\r
\r
This file is much more useful if enriched with URLs!\r
\r
\r
4.1.5 Other usages\r
\r
-----\r
Address book                                            *utl-useaddressbook*\r
\r
I maintain all my contacts in a Vim written XML file. A Perl program parses\r
this file and generates a Vim tags file. This tag file serves as the database\r
for quick lookup of phone numbers, emails and addresses (contact me if you\r
would like to try this). I use URLs in this file:\r
\r
- to add references to contacts. Like order information, and emails\r
- to execute email addresses (which normally are part of the contact\r
  information)\r
- to execute web pages related to the contact\r
- link between addresses\r
- link to encrypted login and passwords\r
- ...\r
\r
\r
-----\r
Link Source Code Files                                  *utl-usesourcecode*\r
\r
This is an Utl usage of big potential in my opinion. But as Utl is currently\r
only implemented for the Vim Editor (not for Emacs etc) this usage might be of\r
real benefit only for people who have an own interest in quality source code.\r
You can use Utl to:\r
\r
- link between the source code files using fragment addressing. For\r
  instance point to a C/C++ header file where a structure/class is defined.\r
\r
- link from a source code file to Man pages using the man: scheme (Unix only).\r
  See #r=foot5 for an example \r
\r
- link from a source code file to design documents, illustration pictures\r
  etc\r
\r
The Utl source code uses URLs itself, see for instance: <URL:../plugin/utl.vim\r
#URL:vimhelp:cmdline-special>).\r
\r
\r
-----\r
Further usages\r
\r
- Is useful for technical writers.\r
  Compile changes and references for a (MS-Word) document in a text file\r
  containing URLs \r
\r
- Make a photo index file.\r
  Reference you photos from within text files which contain links to your\r
  pictures plus annotation text for the photos.\r
\r
- Bug Tracker database.\r
  Maintain a text file which has bug tracker IDs (or change requests more\r
  generally) as entries:\r
  \r
    CR001 Error 8 from replace_client_c.bat \r
      date: 27.02.2005\r
      status: implemented\r
\r
      text describing the problem...\r
      text analyzing the problem...\r
      ...including links to requirements documents, links to to emails\r
      concerning the problem, e.g. <URL:corr/Re FormXtra 2.6 question.htm>,\r
      cross references to other CR's\r
\r
    CR002 ...\r
  \r
  I maintain such a file for Utl development for instance. The Change Request\r
  IDs I choose freely. On my job I also use such files, but the IDs are given\r
  by the Bug Tracker database which we use there. Normally everything should\r
  go into the bug tracker itself (says the upper management) but reality is\r
  different. The Bug Tracker IDs have the form `BT12345' and I can execute\r
  them as an UTL hotlink (see <URL:../plugin/utl.vim#r=heur_example>). Very\r
  convenient.\r
\r
\r
4.2 Smart examples                                      *utl-smartexamples*\r
\r
-----\r
Spell Checker                                           *utl-spellchecker*\r
\r
You can use Utl's web browser integration for spell checking of words. With\r
the following in your .vimrc file:\r
\r
    nmap ,l :exe "Gu http://dict.leo.org/?search=" . expand("<cword>")\r\r
\r
you can lookup the word under the cursor in a web dictionary with the command\r
,l  . I use this quite often and this is my lightweight spell checking tool\r
(especially when I have to write english text).\r
\r
\r
-----\r
Dictionary Lookup                                       *utl-dictlookup*\r
\r
The above mapping above is also useful as dictionary lookup translation\r
english into german or vice versa. You can also make a similar mapping:\r
\r
    " Lookup of expression given on command line.\r
    " Of benefit because often faster than click click on desktop\r
    " Use %20 or \ or + to escape blanks, example:\r
    "           for%20that%matter\r
    "           for\ that\ matter \r
    "           for+that+matter \r
    nmap ,m :Gu http://dict.leo.org/?search=\r
\r
In this form you type the word to lookup in the command line.\r
\r
\r
-----\r
Gu with dot dir                                         *utl-gudotdir*\r
\r
The following command is short but very useful:\r
\r
    :Gu .\r
\r
invokes the file browser for the directory where the current file resides. The\r
file browser will typically be either Vim's file browser or Windows Explorer\r
(or Konqueror on Linux), depending on how you configured the directory\r
handler, see Config:#r=mt_dir. Both handlers are of benefit, depending on\r
what you want to do. If the Vim file explorer is configured, the following is\r
especially useful:\r
\r
    :Gu .\r
    c\r
\r
i.e. you execute the command 'c' in the Vim file explorer to change the\r
current working directory ( see vimhelp:current-directory ) accordingly. This\r
enables you to use file name completion to edit files which are in the same\r
directory as the previously edited file.\r
\r
\r
-----\r
Invoke Utl's media type handlers in file browser        *utl-fbcallmt*\r
\r
If you are in Vim's file browser you can use \gu to invoke the files and\r
directories presented there with the Utl-defined media type handlers! For\r
example open a MS Word document with MS Word, open a picture with irfanview,\r
open a directory with Windows Explorer (if directory handler configured to\r
Windows Explorer) etc. That's very convenient. Seems like magic first, but\r
isn't, is completely straight forward and no special treatment by the utl.vim\r
plugin (utl.vim is just lucky on one point: concerning directories, that they\r
are presented with forward slashes even under Windows). It might be worth to\r
note that you do not execute self written URLs here.\r
\r
\r
-----\r
Starting a program                                      *utl-startprog*\r
\r
The following starts a vncviewer client for me:\r
\r
    <url://q:/projekt_511/Iberl/vnc3.3.3R2/vnc_x86_win32/vncviewer/vncviewer.exe?>\r
\r
The question mark at the end denotes that the path in front of it should be\r
interpreted as a program to be executed. This is straight forward URL\r
techniques, Utl applies the general URL query concept to programs which are\r
directly accessible by your file system. See |utl-filequery| for some specs.\r
\r
You can also supply the server IP address to connect to:\r
\r
    <url://q:/projekt_511/Iberl/vnc3.3.3R2/vnc_x86_win32/vncviewer/vncviewer.exe?89.11.11.242>\r
\r
Or you only link to the directory in order to start the program from\r
there[#r=foot2].\r
\r
    <url://q:/projekt_511/Iberl/vnc3.3.3R2/vnc_x86_win32/vncviewer>\r
\r
Starting programs is especially useful in case of long, strange paths to the\r
program which you either forget or which is simply to ennoying to type. This\r
can be an alternative to one liner programs. A good place to keep such links\r
might be your info file, see |utl-useinfofile|.\r
\r
Here is another example using a slightly different form of query:\r
\r
    <url:my-decrypt.pl?stb-cellphone-pin%3e>\r
\r
This link is contained in my address book. It looks up the PIN number of my\r
cellphone which is GPG encrypted. My-decrypt is a small Perl program which\r
asks for the password and then writes the PIN to standard output. The %3e at\r
the end is the '>' character in escaped form (see |utl-uri-forbchars|). The\r
'>' as the last character means the following to Utl: Execute the given\r
program synchronously and write the output into a temporary file. The\r
temporary file is then displayed in Vim. In the above vncviewer example the\r
program is started asynchronously and no output is awaited.\r
\r
\r
-----\r
The vimscript scheme                                    *utl-exvs*\r
\r
The vimscript scheme is a nice example for a non standard protocol. Utl.vim\r
introduces it in the hope it will be helpful and also as a demonstration for\r
the URL concept. This URL definition is in full compliance to the URL/URI\r
specification! Try the folowing examples: \r
\r
    <URL:vimscript:ls>\r
\r
    1. <URL:vimscript:let g:utl_sav=g:colors_name>\r
    2. <URL:vimscript:colors peachpuff>\r
    3. <URL:vimscript:exe "colors ".g:utl_sav>\r
\r
    <URL:vimscript:help uganda>\r
\r
Here is an example which is derived from the minibufexpl.vim ( see\r
http://www.vim.org/scripts/script.php?script_id=159 ). This file\r
contains folds and the following hint:\r
\r
    Hint: Type zR if you don't know how to use folds\r
\r
Using UTL this could be turned into a hotlink:\r
\r
    Hint: Execute <URL:vimscript:normal zR> if you don't know how to use folds\r
\r
Execute the above URL to see how this works...and to see another example :-)\r
\r
Yet another vimscript example {{{\r
This example is derived from the vimspell.vim, see <URL:http://www.vim.org/\r
scripts/script.php?script_id=465>. This file contains the following:\r
\r
    " Section: Documentation \r
    "----------------------------\r
    "\r
    " Documentation should be available by ":help vimspell" command, once the\r
    " script has been copied in your .vim/plugin directory.\r
    "\r
    " You still can read the documentation at the end of this file. Locate it by\r
    " searching the "vimspell-contents" string (and set ft=help to have\r
    " appropriate syntaxic coloration). \r
\r
Using UTL this can be turned into a hotlinked version:\r
\r
    " Section: Documentation \r
    "----------------------------\r
    "\r
    " Documentation should be available by <url:vimhelp:vimspell> command, once the\r
    " script has been copied in your .vim/plugin directory.\r
    "\r
    " You still can read the documentation at the end of this file, see \r
    " <url:#vimspell-contents> (and execute <URL:vimscript:set ft=help> to have\r
    " appropriate syntaxic coloration). \r
\r
}}} Execute <URL:vimscript:normal zM> to close the fold again\r
\r
Regarding the above examples you might agree with me that the possibility to\r
embed vim commands and hotlinks in a document is nice and smart.\r
\r
Obviously there is one issue: As long as plain text URLs are not standard, the\r
standard user who reads the above given samples in minibufexpl.vim or\r
vimspell.vim would not be able to actually execute the URLs. But the plugin\r
authors could utilize the URL version anyway since their meaning is obvious to\r
the user. The user can execute still manually.\r
\r
Potentially vimscript URLs could also be of benefit for a community, for\r
instance in the vim@vim.org mailing list where often vim commands are\r
exchanged. Can be used at hot links for those people who can directly switch\r
to vim while reading mail.\r
\r
A historical note: \r
The vimscript URL was inspired by the javascript scheme, which is supported by\r
Mozilla/Firefox and MS Internet Explorer for example (try\r
<URL:javascript:window.alert(%27hello, worldddd%27)> for a javascript\r
example). Consider the current vimscript protocol support ( which is actually\r
one line of code, see ../plugin/utl_scm.vim#r=vimscript ) as a demo. Much more\r
sophisticated things could be achieved.\r
\r
\r
-----\r
The vimhelp scheme                                      *utl-exvimhelp*\r
\r
Linking to the Vim Help is especially useful. So Utl provides a a shorter form\r
for that. Instead <URL:vimscript:help design-documented> you can write:\r
\r
    <URL:vimhelp:design-documented>\r
\r
using the special non standard protocol vimhelp. Obviously this is the same as\r
the Vim-help reference notation |design-documented|. But with the advantage\r
that the URL version also works if the file containing the link is not part of\r
the Vim help! Another advantage is that you can use fragments in conjunction\r
with vimhelp:\r
\r
    <URL:vimhelp:design-documented#line=4>.\r
    \r
That's 4 lines downwards from the position which the URL without the fragment\r
yields. (Not 4 lines downwards from the top of the file which contains that\r
help item.) This is useful for instance for documenting Vim scripts! See\r
<URL:../plugin/utl.vim#vimhelp:expr-==> for an example. It could also be useful\r
in the Vim mailing list when Utl.vim or plain text URLs become common enough.\r
\r
\r
-----\r
Mailto URLs\r
\r
Utl supports the mailto: protocol. Try for example to execute the following\r
Links with \gu :\r
\r
    <URL:mailto:stb@bf-consulting.de>   # with embedding\r
    mailto:stb@bf-consulting.de         # without embedding\r
    stb@bf-consulting.de                # without embedding and mailto:\r
\r
Especially the latter form is useful for directly using email addresses. I\r
keep my email addresses in my text based address book and often start writing\r
emails from there. I do not maintain the address book of my mail client\r
program.\r
\r
If your mail client supports extended mailto syntax according to RFC2368 you\r
can also execute URLs like\r
\r
    <URL:mailto:stb@bf-consulting.de?Subject=mysubject&\r
        Cc=bf@bf-consulting.de&\r
        Bcc=stb2@t-email.de&>\r
\r
You might want use something like:\r
\r
    <URL:mailto:stb@bf-consulting.de?\r
    To=hans.mueller@web.de&To=martin.schmidt@t-online.de&To=otto.andres@web.de>\r
\r
to directly mail to a group of people.\r
\r
\r
-----\r
Using a hot key\r
\r
Most people prefer to have a hot key to execute \gu. For instance you could\r
use the function key F4 to execute an URL with the mapping:\r
\r
    :nmap <F4> <Leader>gu\r
\r
Or do you prefer the "real link" feeling and execute a hyperlink with double\r
click left mouse button?\r
\r
    :nmap <2-LeftMouse> <Leader>gu\r
                                                                    id=vsex\r
Execute <URL:vimscript:nmap %3c2-LeftMouse%3e %3cLeader%3egu> to try this\r
mapping. Execute <URL:vimscript:nunmap %3c2-LeftMouse%3e> to unmap it again.\r
\r
\r
\r
4.3 Referencing Emails\r
\r
Referencing emails from within a text file can be very useful (see for\r
example #r=emailex above). There is not yet a proper Utl solution, but some\r
people (including me) find already useful what is currently possible.\r
\r
-----\r
The desired solution?\r
\r
The desired solution, in my opinion, would be to have a specific scheme for\r
referencing emails which reside in one of your mail folders, something like\r
this:\r
\r
    <url:mbox:[filter expression to select one or more specific email]>\r
    \r
for instance:\r
\r
    <url:mbox:subject=abc>              # Display the thread related to subject abc\r
    <url:mbox:date=20.12.2004+12:21>    # Specify a mail by date+time\r
    <url:mbox:id=20001025234042.A29199@smith.com>\r
                                        # Specify a mail by its message ID\r
\r
The latter would probably be the most important case: to identify an email by\r
its unique message ID (RFC 822 header field "Message-ID:"). Unfortunately not\r
every mail system supports the message ID, most notably Outlook consortes. For\r
Outlook, even worse, until now I did not find any possibility to savely\r
identify an email in a way which can be used for automated lookup. I tried for\r
example to write a Windows Scripting Host (WSH) script, but it seems you\r
cannot even identify an email by date/time received because you can only\r
define filters for time ranges. Who can help here??? Perhaps can be solved\r
using VBS.\r
\r
-----\r
Experimental solution for mbox formatted mail boxes:\r
\r
For the mbox style mail box format with the Message-ID: header field present\r
in the emails I work with the following experimental to handle my private\r
emails. It uses a query URL like this:\r
\r
    <url:file:///home/stb/Mail/search?20001025234042.A29199@smith.com>\r
\r
It searches some mail folders for the email with the given Message-Id,\r
extracts it, and displays it in a Vim window. The program `search' is little\r
self written perl script (the Vim plugin <URL:http://www.vim.org/scripts/\r
script.php?script_id=25> performs a similar task.) Using existing\r
programming interfaces to access mail boxes would probably be a smarter\r
approach.\r
\r
-----\r
Referring to copies\r
\r
Here comes what I am doing over and over with my Outlook emails on the job. I\r
save important emails with "Save as" in a project specific "correspondance"\r
folder. Mostly in .rtf or .txt format. For the file name I prefix the date of\r
the email, for instance '20041204 RE MDAC 2.6 installation problem.txt'. The\r
link containing this reference looks something like:\r
\r
    <url:corr/20041220 RE MDAC 2.6 installation problem.rtf>\r
\r
The link appears for example in the bug tracker data base. Or in a text file\r
which contains items for the next revision of a technical documentation.\r
Compilation of requirements of a software engineering project is another\r
example.\r
\r
Depite the annoying step of saving the email to a file (could probably be\r
automated if I was a WSH or VBS programmer) this procedure proved to be very\r
powerful during the last years.\r
>\r
\r
==============================================================================\r
5. Tips, details, pitfalls                              *utl-tipsdetails*\r
\r
\r
5.1 Associated Base URL and Cache Mapping               *utl-tdassbcachem*\r
\r
-----\r
Associated Base URL                                     *utl-tdassb*\r
\r
Execute the link:\r
\r
    <URL:utl_ref.txt>\r
\r
and when you ARE in the other file, utl_ref.txt, then type the utl.vim\r
command:\r
\r
    \gs\r
\r
that shows you the associated base URL in Vim's message line.\r
It looks something like:\r
\r
    URL=file:///path/to/.vim/doc/utl_ref.txt\r
\r
This is the base URL, denoting the context for resolving relative URLs.\r
If \gs shows you a message which starts with `no associated URL', this means\r
that the buffer was not invoked by utl.vim, e.g. was invoked by a user\r
command like :e xyz.\r
\r
You normally do not need the \gs command. But it is sometimes useful to figure\r
out what's going on.\r
\r
\r
-----\r
The `file:' protocol is the default                     *utl-tdfileisdef*\r
\r
When \gs shows `URL= ' (empty value) you nevertheless can execute relative\r
URLs. Given a relative URL, say utl_ref.txt, utl.vim just assumes the\r
`file:' protocol, i.e. file:///path/to/currentBuffer.\r
\r
This behaviour normally gets the thing started: you are in a normal Vim\r
session and encounter a link somewhere. Just type \gu to follow the link.\r
\r
This behaviour to "urlify" the current resource is usual for systems that\r
support both, URL oriented and file system oriented resources. For example\r
Linux/KDE's web and file browser konqueror. For the konqueror the http:\r
protocol is the default.\r
\r
\r
-----\r
Cache Mapping                                           *utl-tdcachemap*\r
\r
Type now the utl.vim command:\r
\r
    \gc\r
\r
Utl.vim shows you it's internal cache-mapping: The mapping between local\r
files and their URL. That grows up more and more when you continue to\r
follow links to different URLs. At the moment \gc, like the \gs command, is\r
mainly useful to see whats going on when learning utl.vim. The cache map is\r
always looked up first when utl.vim needs a base URL. URLs that are passed\r
directly to the web browser or to the mail client are an exception. They are\r
passed to these applications before lookup and will not be visible in the\r
cache map.\r
\r
When working with local files, the URL may seem quite academic. But with\r
remote resources this changes[#r=foot4].\r
\r
\r
5.2 Writing correct URLs                                *utl-tdwriteurls*\r
\r
As already mentioned, understanding URLs is essential for using utl.vim as\r
an _author_. Using utl.vim for the _reader_ who only executes URLs requires\r
not much understanding; you just hit \gu when you encounter a link. That's a\r
difference between authoring/editing/writing on one side and\r
reading/browsing/viewing on the other side.\r
\r
Have you already read the URI primer |utl-uriprim|? Strongly recommended!\r
OK, enough moralizing. Here are some rules and hints:\r
\r
- Always use forward slashes!                           *utl-usefwslashes*\r
\r
  Even on MS Windows do not write:\r
\r
      <url:file:D:\htdocs\corephp\kalender\WebCalendar\index.php>   # bad!!!\r
\r
  Instead write:\r
\r
      <url:file://D:/htdocs/corephp/kalender/WebCalendar/index.php> # good!\r
\r
  Note that the windows drive appears where you normally expect a machine\r
  name. That is according to URI specifications. Try it out from within your\r
  web browser if you do not believe it!\r
\r
                                                        *utl-userels*\r
- Use relative URLs instead of absolute URLs whenever possible. For example,\r
  use:\r
\r
      <url:sub_dir/foo.txt> or\r
      <url:./sub_dir/foo.txt>   # same as previous line\r
\r
  instead of:\r
\r
      <URL:file:/full/path/to/sub_dir/foo.txt>\r
\r
  Other example with file which is in a directory with is parallel to the\r
  directory where the current file is in:\r
\r
      <URL:../sibbling_dir/foo.txt>\r
\r
  Normally there is no need for an explicit `file:' protocol!\r
\r
\r
- How relative URLs are combined                        *utl-howrelscombine*\r
\r
  Say you have a file foo.txt which lives in the directory /full/path/to .\r
  Thus the full pathname of foo.txt is:\r
\r
      /full/path/to/foo.txt\r
\r
  Further assume foo.txt contains an URL:\r
\r
      [foo.txt]\r
      .\r
      .\r
      <URL:sub_dir/bar.txt>\r
      .\r
      .\r
      EOF\r
\r
  When this URL is executed by utl.vim, the following happens:\r
\r
  - The URL "sub_dir/bar.txt" is recognized as a relative URL (because it does\r
    not contain a protocol).\r
\r
  - Every relative URL has to be transformed into an absolute URL. This is\r
    achieved by combining it with the base URL. The base URL is the URL of the\r
    containing document minus its file name. In our case:\r
\r
        "file:///full/path/to/"\r
\r
    (When foo.txt itself was retrieved through, say, the scp: protocol,\r
    then the base URL might read something like "scp://host.de/.../". \r
    Utl.vim's \gs command shows you the absolute URL of the current\r
    document.\r
\r
      absolute URL of file\r
      containing the URL:           file:///full/path/to/foo.txt\r
    - file component:               foo.txt\r
    --------------------------------------------------------------------\r
    = base URL:                     file:///full/path/to/\r
    + relative URL:                 sub_dir/bar.txt\r
    --------------------------------------------------------------------\r
    = absolute URL:                 file:///full/path/to/sub_dir/bar.txt\r
\r
  It's always an absolute URL which is executed by utl.vim. Relative\r
  URLs are never executed directly! They are transformed into absolute\r
  URLs in order to get executed.\r
\r
\r
5.3 Common Pitfalls                                     *utl-commonpitfalls*\r
\r
-----\r
Absolute URLs do not combine!!!!!!                      *utl-absdontcombine*\r
\r
The following makes no sense:\r
\r
  <URL:file:../do/not/do/this>      # VERY BAD\r
\r
Here is the easy rule to keep in mind: When the protocol -- `file:' in our\r
case -- is present, then it's an absolute URL! If it is absent, then it is a\r
relative URL. Be aware of this rule... although bad URLs as the above one\r
might seduce you :-)\r
\r
An absolute URL is taken as it is! The ../ in the example suggests a\r
relative path. But since the URL is absolute, the path will _not_ be\r
combined with the path of the document containing that URL. Executing this\r
link is about the same as when you type the Vim command:\r
\r
  :edit ../do/not/do/this\r
\r
That means: the result depends on the current directory, not on\r
the directory of the file containing the URL. Not what you want!\r
\r
The moral of the story is:\r
1. When you use a protocol like file: or http: in your URL, then you have\r
   to give the complete path in the URL!\r
2. Use relative URLs whenever possible!\r
\r
-----\r
Protocol and file type are different things             *utl-protvsftype*\r
\r
This is something which is important to understand, especially if you are\r
going to extend Utl by your owne protocol and media type handlers.\r
\r
Linking to a HTML file does not mean that you necessarily need the http:\r
protocol then! Protocol and file type (= media type) of the link target are\r
completely independent.\r
\r
You can have http: to retrieve a txt file:\r
\r
  <URL:http://www.ietf.org/rfc/rfc2396.txt>\r
\r
Or you can have file: to retrieve a (normally, but not necessarily local) HTML\r
file:\r
\r
  <URL:file:///usr/local/apache/htdocs/index.html>\r
\r
This second example is more important for normal utl.vim usage: for\r
example, when using utl.vim for editing your website. Utl.vim can\r
directly execute links in HTML files and it normally does that by implicitly\r
using the `file:' protocol. See also |utl-footnote-htmledit| and\r
|utl-tutmeddep|.\r
\r
\r
                                                        *utl-tdmeddep*\r
5.4 Embedding and fragment interpretation depend on the media-type\r
\r
As you already know, Utl introduces the embedding `<URL:myUrl>' for plain\r
text files. For HTML files (.html or .htm), it makes sense to support HTML's\r
embedding, i.e. something like `<A HREF="myUrl">'. This means that when you\r
are editing a HTML file and execute \gu to follow a link, utl.vim expects the\r
pattern `<A HREF...>' under the cursor.\r
\r
The URL embedding syntax relates to the media type of the source of the link.\r
The fragment expression syntax relates to the media type of the target of the\r
link. The semantics of the fragment expression depends on the media-type.\r
\r
When the target is a HTML file, with an IdRef expression like `#myFrag' then\r
Utl finds the position `<A NAME="myFrag">' (it will not parse the HTML file\r
though, merely search it; but in practice it functions as expected).  When\r
the target is any other file type (utl.vim only distinguishes HTML from all\r
others) then Utl finds the position of `id=myFrag' (case never matters).\r
\r
So you can really use Utl as a HTML-Source-Browser! That's useful\r
especially for editing and browsing your "under construction" web site.\r
\r
The other fragment expressions like line=, tn= do not depend on the file\r
type (= media-type) in utl.vim.\r
\r
\r
==============================================================================\r
6. Setup and Customization                              *utl-customization*\r
\r
Setup of web browser, mail client, media type handlers etc is triggered\r
dynamically by Utl.vim when first requested. All settings are in the file\r
<URL:../plugin/utl_rc.vim>. Refer to the explanations in the header of this\r
file. The design goal was to make getting started with Utl easy.\r
\r
Besides these setup items there is one pure customization item. You can switch\r
off Utl's syntax highlighting of URL with the following setting in your vimrc\r
file:\r
\r
    let g:utl_config_highl = 'off'\r
    " values: 'on', 'off'. Variable undefined is the same as 'on'\r
\r
\r
==============================================================================\r
7. Changes from Utl-1.2 (Thlnk-1.2)                     *utl-changes*\r
\r
\r
-----\r
Incompatible Changes                                    *utl-chgincompat*\r
\r
- #tn= fragment is now default, i.e. #tn=foo is same as #foo\r
\r
  Previously the ID-reference fragment #r=foo was the default. If you have\r
  used the naked fragment with the previous version you might want to convert\r
  your links. Use the search pattern  /<URL:.*#[^=>]*>  to find the links\r
  which need to be converted (the pattern works within Vim as well as with the\r
  grep program) and change  #  --into-->  #r= . If I receive more than five\r
  complains I will supply a converting utility :-)\r
\r
  The reason for this change was that #tn= semantics is used more often by\r
  most users.\r
\r
-----\r
Changed                                                 *utl-chgchanged*\r
\r
- Create documents on non existent local URLs (Wiki support).\r
  No longer complain. Perhaps this should be customizable. For a set of\r
  read-only documents complaining mighgt be better.\r
\r
- On http URLs no longer use the wget utility for retrieving files on the web.\r
  Instead delegate to your web browser.\r
\r
-----\r
Added                                                   *utl-chgadded*\r
\r
- Call web browser on http URLs and email client on mailto URLs (configurable\r
  scheme handlers)\r
\r
- Call MS-Word on .doc files, Acrobat Reader on .pdf, IrfanView on .jpg etc.\r
  (configurable media type handlers)\r
\r
- Syntax highlighting for URLs (can be switched off)\r
\r
- Support URL heuristics, e.g. allow www.vim.org, not only http://www.vim.org\r
\r
- Support exeuction of URLs without <URL:...> embedding (e.g. execute URLs as they\r
  mostly appear in not specifically written text like "see www.vim.org for Vim plugin"\r
\r
- Support multiline URLs\r
\r
- Smart setup and customization facility \r
\r
- Tilde Support, e.g. allow <URL:~/foo/bar> and <URL:~user/foo/bar>\r
\r
- Automatically open file in split window if current buffer cannot be\r
  abandonned (e.g. is not written) \r
\r
-----\r
Fixed                                                   *utl-fixed*\r
\r
- Yes, about 10 bugs... but probably more new bugs came in :-)\r
\r
\r
==============================================================================\r
8. Todo list                                            *utl-todo*\r
\r
-----\r
Todo list\r
\r
Please let me know which feature you would like to see in the next release.\r
\r
- Support for URL creation (authoring support)\r
  See #foot6 for an approach.\r
\r
- Dynamic call of handlers.\r
  There should be a possibility to choose media type and scheme handlers\r
  dynamically. This is most useful perhaps for links to local directories,\r
  i.e. URLs like <URL:../doc>: one time you want to call Vim's own file\r
  explorer, one time the file explorer of the system (e.g. Windows Explorer),\r
  one time the shell (or DOS box on Windows) with proper cwd. Currently you\r
  have to always invoke the setup <URL:config:#r=mt_dir> and change it.\r
\r
- Allow wget to retrieve http documents.\r
  There should be a possibility to handle http URLs in Vim (using the wget\r
  utility) as version 1.2 offered it. Currently http URLs are always delegated\r
  to an external program (normally your web browser). The issue probably\r
  depends on the previous one.\r
\r
- Make colors of URL syntax highlighting configurable.\r
\r
- Check for dangling links\r
  There should be a function to check whether all links points to existing\r
  targets. Actually I already have a hack solution. Please email if you think\r
  this would be a nice feature.\r
\r
- Follow links when searching.\r
  Add a function which searches the file tree which is defined by a file\r
  containing file URLs.\r
\r
-----\r
Known bugs                                              *utl-knownbugs*\r
\r
- The mappings \gE, \gV which split the screen when executing an URL\r
  are not respected for a reference to the same document; e.g. executing\r
  \gV on <URL:#tn=this> doesn't split the screen. The same is true\r
  when the file is the current file: e.g. <URL:utl_usr.txt#tn=this>.\r
\r
- Highlighting Bug\r
  The syntax highlighting gets confused in case of a split window, both\r
  containing the same file with URLs. Perhaps a Vim bug.\r
\r
\r
==============================================================================\r
9. Credits                                              *utl-credits*\r
\r
Wolfgang Fleig, my partner for his for his help, co-authoring, dialectical\r
    antithesis and sponsoring.\r
Ines Paegert\r
    for her impulses.\r
Bram Moolenaar <Bram at moolenaar.net>\r
    for the Vim editor.\r
Barrie Stott <G.B.Stott at bolton.ac.uk>\r
    for helping a lot with the documentation\r
REKellyIV <Feral at FireTop.Com>\r
Klaus Horsten <horsten at gmx.at>.\r
Patrik Nyman <patrik.nyman at orient.su.se>\r
Engelhard Heß <Engelhard.Hess at artofbits.de>\r
Grant Bowman <grantbow at grantbow.com>\r
Ward Fuller <wfuller at SeeBeyond.com>\r
Mark S. Thomas <Mark.Thomas at SWFWMD.STATE.FL.US>\r
William Natter <wnatter at nortelnetworks.com>\r
Alex Jakushev <Alex.Jakushev at kemek.lt>\r
Geoff Caplan <geoff at advantae.com>\r
Bruno Díaz <bruno.diaz at gmx.net>\r
Michael Lesniak <ich at mlesniak.de>\r
Janek Kozicki <janek at thenut.eti.pg.gda.pl>\r
\r
\r
==============================================================================\r
FOOTNOTES\r
\r
----- id=foot1\r
An URL like www.vim.org or stb@bf-consulting.de works via a simple heuristic\r
support of Utl which is similar to what you know from your web browser.\r
Utl completes  www.xxx.domain  into  http://www.xxx.domain  or\r
stb@bf-consulting.de  into  mailto:stb@bf-consulting.de. See <URL:../pl\r
ugin/utl.vim#r=Utl_checkHeuristicAbsUrl> for supported heuristics. You can\r
extend the heuristics defined there.\r
\r
----- id=foot2\r
This only works if you have configured Windows Explorer as text/directory\r
handler, see <URL:config:#r=mt_dir>).\r
\r
----- id=foot3\r
I try to use lower case notations <url:xxx> for URLs that cannot be executed\r
right away, whereas upper case samples <URL:xxx> should all be directly\r
executable. Note that this is only a convention used in this document, the \r
case does not matter. URL: url: Url: are all fine.\r
\r
----- id=foot4\r
In the current version of Utl the cache actually is really somewhat academic.\r
The previous version, which was Thlnk-1.2, handled web URLs (http://...) using\r
a web file retriever ( wget, see http://www.gnu.org/software/wget/wget.html ).\r
HTML files were downloaded using wget into a local cache file and displayed\r
using Vim, i.e. were always displayed as text. This was very cool for text\r
files on the web because #tn= fragment addressing could be used. Example:\r
<URL:http://www.ietf.org/rfc/rfc2396.txt#tn=^1.2.>. Within html files, which\r
were readable enough in the text-view (in Vim) relative HTML hyperlinks could\r
be executed directly through the cache. Now web URLs are handled in the\r
mainstream manner by calling the web browser. Also people had to download\r
wget. But I would like to reactivate the wget possibilities in a next version.\r
Dynamic handler selection capabilities need to be added to Utl then.\r
\r
----- id=foot5\r
You can use the man: protocol to hotlink from a program source code file to\r
the relevant man page. This makes use of the Man plugin, see |man-plugin|.\r
Example:\r
\r
[myopen.c]\r
.\r
.\r
.\r
/* Opens file "filename".\r
 * See <URL:man:open#tn=flags is one of> for possible values of the `flags' \r
 * argument.\r
 * The restrictions described under <URL:man:open#tn=^RESTRICTIONS> also\r
 * apply to this function.\r
 */\r
    int\r
myopen(char* filename, int flags)\r
{\r
    //\r
    open(filename, flags, mode);\r
    //\r
}\r
.\r
.\r
.\r
EOF\r
\r
----- id=foot6\r
You might want to try the following code:\r
\r
:map ,m :call Mark()<cr>\r
fu! Mark()\r
  let g:file = Utl_utilSlash_ExpandFullPath()\r
  "echo "DBG: g:ins= " . g:ins\r
  let g:text = getline(".") \r
endfu\r
\r
:iab XF <C-R>=g:file<cr>\r
:imap XT #tn=<C-R>=g:text<cr>\r
\r
Position the cursor at the intended target of the link and then execute the\r
command  ,m  . For inserting a link to this position type  XF  to insert the\r
file name and perhaps also  XT  to insert a fragment. \r
\r
\r
 vim:tw=78:ts=8:ft=help:norl:fdm=marker:fen\r