diff --git a/doc/utl_usr.txt b/doc/utl_usr.txt index 8c9120d..df3fc80 100644 --- a/doc/utl_usr.txt +++ b/doc/utl_usr.txt @@ -1,5 +1,4 @@ -*utl_usr.txt* Plugin for executing URLs in plain text files -*utl* *utl-plugin* +*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 @@ -15,7 +14,7 @@ Version Utl v3.0a ALPHA, for Vim version 7, 2008-07-31 3. Tutorial.....................|utl-tutorial| 4. Smart Samples................|utl-smartSamples| 5. Usage Patterns...............|utl-usagePatterns| - 6. Tips, details, pittfalls.....|utl-tipsDetails| + 6. Tips, details, pitfalls......|utl-tipsDetails| 7. Configuration and Options....|utl-config| 8. Changes since Utl v2.0.......|utl-changes| 9. Todo.........................|utl-todo| @@ -60,13 +59,13 @@ Characteristics: - Stays out of the way, no side effects - Extensible -Now lets dive into the live examples. +Now let's 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! +Utl.vim's basic command to open an URL is `:Utl`. That's all you need! Live Examples now!!! @@ -80,38 +79,38 @@ You just executed your first link! you know HTML: that's analogues to a which refers to ID="abc".) The `r' in the expression stands for `reference'. -Executing :Utl on takes you to ... +Executing `:Utl` on takes you to ... some text. -The special syntax `tn=' just means that the target of the link is defined by +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 +Text Next). You can omit the `tn=` prefix and just write because the tn= is the default prefix. -Executing :Utl on takes you to the file utl.vim. +Executing `:Utl` on takes you to the file utl.vim. Please come back here again after having executed the link! -Executing :Utl on takes you to a +Executing `:Utl` on 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 will invoke your web browser with -that URL. Just try it, if you are lucky Utl.vim already knows how to open web +Executing `:Utl` on 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 embedding. Try for example: +You can leave out the embedding. Try for example: http://www.vim.org -or even +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 embedding can be a bit +existing documents in this form. Furthermore, the 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. @@ -124,11 +123,11 @@ or, a file without a suffix: 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 +There are 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 +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] @@ -138,29 +137,32 @@ footnotes. Position the cursor on the [10] in the next line and execute :Utl : 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.) +URL-based links.) From now on I will use those [] -footnotes :-) -You can also type an URL in the command line: - +You can also type an URL on the command line: +> :Utl openLink ../plugin/utl.vim # Open file that is in same directory # as current file -or in short form - +< +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. +< +Or: +> + :Utl ol www.google.com # Open web page from within vim. + # Sometimes 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 +your own links. There is no metadata and no tags file needed. It's 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. +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. ============================================================================== @@ -170,7 +172,7 @@ for you, have a look at chapter 5, Examples of use, |utl-examples| first. 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. +`:Utl` for links under the cursor. The following link, as you know, takes you to another file: @@ -192,16 +194,16 @@ The following URLs are all equivalent: -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 +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 filenames 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: +absolute path names with Vim's `:e` command. Here is an absolute URL: -An absolute URL always has a so called scheme (also called protocol) in +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: @@ -211,7 +213,7 @@ without the protocol: 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: - +> # WRONG!!! Absolute URL with relative path # is an invalid URL. @@ -223,7 +225,7 @@ 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) @@ -254,28 +256,28 @@ Windows, NFS under Unix. Windows Example: Utl converts 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 +directly passed to and edited by Vim, since SMB shares are transparent under Windows. Unix Example: Utl converts internally -into server:/sharefolder/path . (Don't really know if this makes +into server:/sharefolder/path . (Don't really know if this makes sense :-) Windows Examples: -Utl does neither care if authentication is needed on the server resource nor -does it offer direct means for authentication [20]. +Utl doesn't care if authentication is needed on the server resource, and +it doesn't offer direct means for authentication [20]. 3.5 Fragments *utl-tutfrags* --- Intro *utl-tutfragsintro* -Now lets add fragments to URLs. +Now let's 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 +extended by a fragment expression. That way, a specific position in the target file can be jumped to. Try to execute the link: @@ -286,19 +288,19 @@ the fragment expression is different: 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= +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 +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: +`#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 +out. Thus the link above will normally be written shorter: @@ -307,13 +309,13 @@ 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 +occurrence with Vim's `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, +Another fragment identifier is `#line`. It positions to the given line, e.g. (or #line=+10) @@ -324,8 +326,8 @@ can be given as well: 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: +the last line. For the `#tn` identifier there is also a "bottom-up" +possibility: the `#tp` identifier. Try and compare these two: @@ -333,7 +335,7 @@ the #tp identifier. Try and compare these two: --- Relative addressing *utl-tutfragsrel* -So far all fragment addressing was relative from top or bottom of the buffer. +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* @@ -346,20 +348,20 @@ These are URLs that only consists of a fragment. Examples: 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= +"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* +b) Non-file-oriented resources and the Vimhelp scheme *utl-tutfragsnonfile* The best example is the Vimhelp scheme, e.g. (which is -hereby introduced). When you execute this URL the Vim help for the :ls +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 + Readonly buffers are marked with `=`; see The utl.vim source code gives more realistic examples, see for instance . @@ -375,8 +377,8 @@ reference a PDF document: -To make this work a handler for .pdf type files has to be present. If you are -lucky Utl.vim already defined a handler for you. Utl.vim aims to provide a +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 @@ -407,7 +409,7 @@ An URL can also specify a folder: 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 @@ -419,12 +421,12 @@ 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: - +open a shell with CWD set to the directory. This 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 @@ -441,15 +443,15 @@ 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 +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] @@ -466,20 +468,20 @@ 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: - +Until now you know the commands `:Utl` (to open the URL under the cursor) and +`:Utl openLink myUrl` (to open a typed URL). The general command interface is: +> :Utl -:Utl (without any arguments) is the same as: - +`:Utl` (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 +since these are the default values for the three arguments. Instead of `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 @@ -487,29 +489,29 @@ Try these with the URL ! -Utl.vim provides command line completion for the arguments to save typing. I +Utl.vim provides command-line completion for the arguments to save typing. I recommend to set the 'wildmenu' option for enhanced completion [26]. Try: - +> :Utl co " or :Utl co " or :Utl " etc. -The completion works the like for second and third argument. Another aspect +The completion works similarly for the second and third arguments. 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, +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. +In addition to completion, Utl.vim supports abbreviations for the arguments. The following are equivalent: - +> :Utl openLink underCursor edit " is same as: :Utl ol uc edit " is same as: :Utl o u edit See for all abbreviations and explanation of the abbreviation rules. If you typed an abbreviation for -an argument completion does still work for further arguments, e.g. - +an argument, completion still works for further arguments, e.g. +> :Utl o u Again, verbose mode might help to figure out what's going on when playing with @@ -517,19 +519,19 @@ 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, - +character on `:Utl`: +> :Ut is possible in standard Vim 7.1 [28]. See if you consider to use mappings anyway. +mappings> if you consider using 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 --------------------- @@ -537,24 +539,24 @@ would parse out. Examples (desired URL underlined): --------- Visually select the URL, possibly copy to clipboard (with CTRL-C under -Windows), then execute - +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 +Utl.vim supports a special non-standard protocol to execute Vim commands from +within a plaintext document. It is introduced here because it's needed in the sections which follow. The general format is: - +> vimscript: Try these examples: - - " This which is the same as: - " (i.e. you can omitt the `:') +> + " This is the same as: + " (i.e. you can omit 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: @@ -567,12 +569,12 @@ encoding. Example: -The 3c is the hex value of the < character, the 3e is the hex value -of the > character. Just keep in mind that if an URL does not work, then try -to encode the characters appearing dangerous with percent encoding [30]. +The `3c` is the hex value of the `<` character, and 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 dangerous-looking characters using 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 +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. @@ -584,16 +586,16 @@ 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 +address' or so in web browser. Try for instance `:Utl cl` on and -check the * register by executing +check the `*` register by executing . @@ -601,50 +603,50 @@ NOte that the register contains an absolute URL, not a relative one. Copying links is often useful, for instance to email a link address to someone. Another nice usage is to open the current file in another Vim instance: - +> :Utl copyLink currentFile then switch to the other Vim instance and perform: - +> :Utl openLink -This example also introduced the currentFile operand (you already know -underCursor, visual, ). +This example also introduced the `currentFile` operand (you already know +`underCursor`, `visual`, ). COPYFILENAME *utl-tutCopyFileName* -Related to copyLink is copyFileName - +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: - +`:Utl copyFileName`: +> -and check the * register. Usage example: use copyFileName for a file you +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. +mail attachment and want to make it hot-linkable from within a text file. Create a new link in the text file, e.g. , then perform - +> :Utl copyFileName and paste the result into the 'save as' dialog of your mailer [31]. This can save you a lot of tedious browsing down directories in GUI programs -(especially under Windows). CopyFileName does only work for (implicit or +(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. +The filename will have slashes or backslashes 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 @@ -653,7 +655,7 @@ Windows): For reference of all available commands and arguments see: - +> :Utl help commands @@ -665,7 +667,7 @@ 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. +scheme, followed by mail and http . Let's consider http now. You already know that you can execute the links: @@ -688,10 +690,11 @@ for instance the URL: *utl-tutscmhttpwget* -This is a plain text document. Wouldn't it much better to display it in Vim? -Utl.vim provides interfacing to the non interactive download tool wget . For -this purpose the handler utl_cfg_hdl_scm_http has to be set up as: - +This is a plain text document. Wouldn't it be 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 +follows: +> :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 @@ -727,12 +730,12 @@ to define mappings that switch between the handlers, see 3.13 The mail scheme *utl-tutscmmail* -There is a special, non standard scheme for referencing specific emails +There is a special, non-standard scheme for referencing specific emails from your local mail boxes via URL. For instance, executing the link -will open the so specified email in your mailer. This can be very +will open the 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. @@ -751,14 +754,14 @@ already running!): -Currently the date is locale dependent, the above sample is for a German +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 +column ('Erhalten' in German), but without the weekday prepended. The above can be written shorter as: -since `date' is the default query [34] +since `date` is the default query [34] Examples using different mail folders are: @@ -799,8 +802,8 @@ standard schemes: *utl-tutscmothnonstd* -Moreover, besides mail, vimscript and vimhelp scheme Utl.vim introduces and -supports the following non standard schemes: +Moreover, besides the mail, vimscript and vimhelp schemes, Utl.vim introduces and +supports the following non-standard schemes: man: Accesss manual pages via URL. @@ -811,7 +814,7 @@ supports the following non standard schemes: config: - Utl specific. Ad hoc scheme for accessing Utls setup file. + Utl specific. Ad hoc scheme for accessing Utl's setup file. Not really exciting. Examples: @@ -832,10 +835,10 @@ 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 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. +read chapter 6. Tips, details, pitfalls |utl-tipsDetails|, before you write +your own scheme handler. A common misunderstanding is to create a new scheme +where adding 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* @@ -857,7 +860,7 @@ 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 +target; in the example above, it does not open the http:// link. Often [] references are used for simple footnotes: @@ -866,7 +869,7 @@ Often [] references are used for simple footnotes: . [101] but not always -In this case () style references like (*), (1),(2) might be more common, +In this case () style references like (*), (1), (2) might be more common, but this is not supported by Utl.vim. ----- @@ -874,25 +877,26 @@ 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. +_, A-Z, 0-9. Amongst other uses, this style is useful for document references. -According to common use of references the slight syntax variations for the +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 +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]. +target is found. The 102. form is used by [36_2]. -Obviously with the first form the reference source and target look the same. +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. +located at the bottom of the text, but this need not be the case. 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* @@ -927,7 +931,7 @@ 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 +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: = = [36]. Again, to see what's going on internally you can the @@ -936,7 +940,7 @@ verbose option: 3.16 Fragments to external Media Type Handlers *utl-tutextfrag* -As foretold at |utl-tutmtypes| defining a specific media type handler makes +As mentioned 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. @@ -947,13 +951,13 @@ You can execute an URL like -if you use Acrobat Reader to display PDF documents. Enable enable the specific +if you use Acrobat Reader to display PDF documents. Enable the specific handler for media type application/pdf: - Execute , - 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, + the change by `:w` , `:so %` +- Then look for a test PDF on your computer with a least 4 pages, e.g. /path/to/my.pdf - Open this file with: :Utl ol /path/to/my.pdf#page=4 @@ -962,12 +966,12 @@ handler for media type application/pdf: 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|. +Note that addressing PDF pages like 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. +Currently only `#page=` fragments are supported. ----- MS Word text search *utl-tutwordfrag* @@ -986,8 +990,8 @@ application/msword: - 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 +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: @@ -1000,8 +1004,8 @@ Addressing fragments can be quite useful for: 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, +You might use Utl.vim mostly for "defensive" purpose: there is existing +plaintext-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 @@ -1009,7 +1013,7 @@ like to have ways to quickly create URLs and links. Here are some hints: To ease creation of an URL with embedding you can define mappings in your .vimrc file ( without the trailing "> ): - +> imap xu imap xuh imap xumi @@ -1019,7 +1023,7 @@ 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, +- type `:Utl copyLink currentFile`, - go to the intended link source file, - paste from clipboard @@ -1031,10 +1035,10 @@ That's all what the current version offers [40]. ----- 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 -. +If you execute an URL which points to a non-existing file, this file +(initially 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 . ----- @@ -1043,11 +1047,12 @@ Multiline URLs *utl-multiLineURLs* You can spread URLs across several lines like this: . 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 . In order to preserve the space, you could escape it with -%20 (see |utl-uri-forbchars| about escaping), e.g. . But you could also just split at another position: +space and the '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 +. In order to preserve the space, you could escape +it with %20 (see |utl-uri-forbchars| about escaping), e.g. . But you could also just split at another +position: @@ -1068,12 +1073,12 @@ 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("") 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: @@ -1082,27 +1087,25 @@ following mapping is similar: " 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 +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 +This is implemented as a heuristic. Perform links with `utl_opt_verbose=1` to see what's going on. @@ -1116,7 +1119,7 @@ something else under Windows): -This can be convenient for files that should be backuped beyond some regular +This can be convenient for files that should be backed up beyond some regular backup. The URL is portable, you can directly implant to a file of yours. @@ -1132,17 +1135,17 @@ pdf Reader (second URL): ----- -Invoke Utls media type handlers in Vim file browser *utl-fbcallmt* +Invoke Utl's 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 +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! +For example: open an 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. - +like magic first, but isn't, it is completely straightforward 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 @@ -1171,9 +1174,8 @@ Make a bug tracker scheme with the (abritrary) name 'bt', and hence URLs like , -Implement the protocol by defining in your .vimrc the handler -function: - +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?\ @@ -1210,7 +1212,7 @@ You can also supply the server IP address to connect to: 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 +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: @@ -1240,7 +1242,7 @@ 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 @@ -1251,22 +1253,22 @@ code, see|utl-efmeddep|. ============================================================================== 5. Usage Patterns *utl-usagePatterns* -Here are some usage pattern for URLs in plain text. Although they do not exclude +Here are some usage patterns 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. +plaintext 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. +desktop tool then you might consider to 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: +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: @@ -1346,12 +1348,12 @@ 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 +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 +etc. on 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. @@ -1361,9 +1363,9 @@ 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. +is just URL. Vim's folding can also help a lot in organizing your ideas. -Collecting and organizing notes is quite related, so it might be ok to +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 @@ -1385,7 +1387,7 @@ 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 +purpose there might be better ways (like self-written tag files, session files, buffer explorer etc). The Information Directory rather contains static information. @@ -1422,10 +1424,10 @@ Example (the #-comments are only for clarification and not in the real file): ./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 +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, +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: @@ -1437,7 +1439,7 @@ in your web browser. Example: -----------------------------------} 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 +create a tag, a mapping or an URL linking to it. @@ -1466,13 +1468,13 @@ for 'url:' ----- Using a hot key *utl-hotKey* -Mappings to shorten :Utl commands have already been explained, see -[29] / . Using a hot key is -even shorter and gives perhaps more "hypertext feeling". Examples: +Mappings to shorten `:Utl` commands have already been explained, see +[29] / . Using a hot key +is even shorter and gives perhaps more "hypertext feeling". Examples: :nmap :Utl ol -Or still more radical with double click?: +Or still more radical with double click: :nmap <2-LeftMouse> :Utl ol @@ -1480,22 +1482,22 @@ Or still more radical with double click?: ----- Writing correct URLs *utl-writeUrls* -- Pittfall: Don't use backslashes +- Pitfall: Don't use backslashes Even on MS Windows do not write: - +> # bad!!! - +< Instead write: - +> # good! - Tip: Use relative URLs instead of absolute URLs whenever possible. For example, use: - +> or # same as previous line - +< instead of: @@ -1510,7 +1512,7 @@ Writing correct URLs *utl-writeUrls* Pitfall: Absolute URLs do not combine! *utl-absDontCombine* The following makes no sense: - +> # VERY BAD Here is the easy rule to keep in mind: If the protocol (`file:' in this case) @@ -1521,7 +1523,7 @@ 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 @@ -1557,9 +1559,9 @@ utl_cfg_hdl_mt_). First the scheme handler is performed Detail: Embedding and fragment interpretation depend on media-type As you already know, Utl introduces the embedding `' for plain text -files. For HTML files (.html or .htm), it makes sense to support HTMLs +files. For HTML files (.html or .htm), it makes sense to support HTML's embedding, i.e. something like `'. This means that when -editing a HTML file and executing :Utl to follow a link, utl.vim expects the +editing a HTML file and executing `:Utl` to follow a link, utl.vim expects the pattern `' under the cursor. This can be useful if editing and browsing local html files "under construction". @@ -1567,11 +1569,11 @@ 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 +If the target is a HTML file, with an IdRef expression like `#myFrag` then Utl finds the position `' (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). +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. @@ -1634,9 +1636,9 @@ Type > :let utl_ 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 +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). +might be predefined by Utl.vim (like `utl_cfg_hdl_mt_generic` under Windows). ============================================================================== @@ -1693,9 +1695,9 @@ variables around. ----- Command :Gu gone *utl-chgGuGone* -Instead +Instead of > :Gu -you have now to use +you now have to use > :Utl openLink ----- @@ -1716,7 +1718,7 @@ 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 +|utl-totfoot| [41]. Since not of big practical relevance 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 @@ -1729,7 +1731,7 @@ 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, +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: @@ -1812,7 +1814,7 @@ See |utl-tutscmmail|. ----- New verbose mode *utl-chgNewVerbose* -Set Vim variable +Set Vim variable > :let utl_opt_verbose=1 to see what's going on when executing an URL. See |utl-tutverbosemode|. @@ -2032,7 +2034,7 @@ FOOTNOTES [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 + 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 @@ -2047,17 +2049,17 @@ FOOTNOTES [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: + allowed if this gives you more Vim feeling. Examples: > :Utl openLink underCursor :edit " or :Utl openLink underCursor :e - More exotic examples are: +< 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: +< This one does unfortunately not work as expected in Utl v3.0a: > :Utl openLink underCursor :e! - Switch on verbose mode to see why. +< Switch on verbose mode to see why. -[28] Unfortunately :U is not possible because of the :UseVimball standard +[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. @@ -2069,7 +2071,7 @@ FOOTNOTES Ctrl-C is too inconvenient you could use mappings like these: -[30] You can use the Vim command :asc to get the hex value of a character, +[30] You can use the Vim command `:asc` to get the hex value of a character, see [31] Well, normally the 'save as' dialog offers the base name, you copy @@ -2085,9 +2087,9 @@ FOOTNOTES Perhaps these can serve as a starting point an implementation for mbox emails. -[34] The general query format is +[34] The general query format is > date=&from=&subject=. - But only date is currently supported in the VBS script. +< 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). @@ -2095,7 +2097,7 @@ FOOTNOTES [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 - Example: + Example: > [myopen.c] . @@ -2129,13 +2131,13 @@ FOOTNOTES * Markdown syntax : Syntax file for Markdown text-to-HTML language [36_3] - This is only the the syntax file. Markdown is a text-to-HTML conversion + This is only 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 + are magic characters. Search with \M preprended: e.g. \M[10]; see [37] You might wonder what is the difference between "[123]" and "[123]:". @@ -2148,7 +2150,7 @@ FOOTNOTES [38] This seems to be a problem in some cases. For instance it makes reference targets within comments of some programming languages - impossible: + impossible: > use Dumpvalue; # [124] . diff --git a/plugin/utl.vim b/plugin/utl.vim index 5d4c2da..938ff6d 100644 --- a/plugin/utl.vim +++ b/plugin/utl.vim @@ -1,44 +1,44 @@ " ------------------------------------------------------------------------------ -" File: plugin/utl.vim - Universal Text Linking - -" URL based Hyperlinking for plain text -" Author: Stefan Bittner -" Maintainer: Stefan Bittner +" File: plugin/utl.vim - Universal Text Linking - +" URL based Hyperlinking for plain text +" Author: Stefan Bittner +" Maintainer: Stefan Bittner " -" Licence: This program is free software; you can redistribute it and/or -" modify it under the terms of the GNU General Public License. -" See http://www.gnu.org/copyleft/gpl.txt -" This program is distributed in the hope that it will be -" useful, but WITHOUT ANY WARRANTY; without even the implied -" warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +" Licence: This program is free software; you can redistribute it and/or +" modify it under the terms of the GNU General Public License. +" See http://www.gnu.org/copyleft/gpl.txt +" This program is distributed in the hope that it will be +" useful, but WITHOUT ANY WARRANTY; without even the implied +" warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. " -" Version: 3.0a ALPHA +" Version: 3.0a ALPHA " -" Docs: for online help type: :help utl-plugin +" Docs: for online help type: :help utl-plugin " -" Files: The Utl plugin consists of the following files: -" plugin/{utl.vim,utl_scm.vim,utl_uri.vim,utl_rc.vim} -" doc/utl_usr.txt +" Files: The Utl plugin consists of the following files: +" plugin/{utl.vim,utl_scm.vim,utl_uri.vim,utl_rc.vim} +" doc/utl_usr.txt " " History: " 1.0 2001-04-26 -" First release for vim5 under the name thlnk.vim +" First release for vim5 under the name thlnk.vim " 1.1 2002-05-07 -" As plugin for vim6 with heavily revised documentation and homepage +" As plugin for vim6 with heavily revised documentation and homepage " 1.2 2002-06-14 -" Two bug fixes, better error messages, largely enhanced documentation +" Two bug fixes, better error messages, largely enhanced documentation " 1.2.1 2002-06-15 -" Bug fix. Better 'ff' setting for distribution files +" Bug fix. Better 'ff' setting for distribution files " --- Renamed plugin from Thlnk to Utl --- -" 2.0 2005-03-22 -" Configurable scheme and media type handlers, syntax -" highlighting, naked URL support, #tn as default, heuristic -" support and other new features. See ../doc/utl_usr.txt#utl-changes +" 2.0 2005-03-22 +" Configurable scheme and media type handlers, syntax +" highlighting, naked URL support, #tn as default, heuristic +" support and other new features. See ../doc/utl_usr.txt#utl-changes " 3.0a ALPHA 2008-07-31 -" New : Generic media type handler, Mail protocol, Copy Link/ -" Filename support, Foot-References [], Transparent editing of -" share files, Tracing, Enhanced scheme handler interface, -" Changed : User Interface with command :Utl, variable naming. -" Bug fixes. +" New : Generic media type handler, Mail protocol, Copy Link/ +" Filename support, Foot-References [], Transparent editing of +" share files, Tracing, Enhanced scheme handler interface, +" Changed : User Interface with command :Utl, variable naming. +" Bug fixes. " ------------------------------------------------------------------------------ if exists("loaded_utl") || &cp @@ -79,68 +79,68 @@ fu! s:completeArgs(dummy_argLead, cmdLine, dummy_cursorPos) " 1st arg to complete if len(utlArgs)==1 - return "openLink\ncopyFileName\ncopyLink\nhelp" + return "openLink\ncopyFileName\ncopyLink\nhelp" endif let utlArgs[1] = s:abbr2longArg(utlArgs[1]) " 2nd arg to complete if len(utlArgs)==2 - if utlArgs[1]=='openLink' || utlArgs[1]=='copyFileName' || utlArgs[1]=='copyLink' - if len(utlArgs)==2 - return "underCursor\nvisual\ncurrentFile\n_your_URL_here" - endif - elseif utlArgs[1]=='help' - if len(utlArgs)==2 - return "manual\ncommands" - endif - endif - " config - return '' + if utlArgs[1]=='openLink' || utlArgs[1]=='copyFileName' || utlArgs[1]=='copyLink' + if len(utlArgs)==2 + return "underCursor\nvisual\ncurrentFile\n_your_URL_here" + endif + elseif utlArgs[1]=='help' + if len(utlArgs)==2 + return "manual\ncommands" + endif + endif + " config + return '' endif " 3rd argument to complete if len(utlArgs)==3 - if utlArgs[1]=='openLink' - return "edit\nsplit\nvsplit\ntabedit\nview\nread" - elseif utlArgs[1]=='copyFileName' - return "native\nslash\nbackSlash" - endif - return '' + if utlArgs[1]=='openLink' + return "edit\nsplit\nvsplit\ntabedit\nview\nread" + elseif utlArgs[1]=='copyFileName' + return "native\nslash\nbackSlash" + endif + return '' endif return '' endfun - " [id=cmd_reference] + " [id=cmd_reference] "------------------------------------------------------------------------------- " Table of :Utl commands/arguments. The [xxx] are default values and can " be omitted. ( The table is implemented at #r=Utl ) " -" arg# 1 2 3 +" arg# 1 2 3 " -" :Utl [openLink] [underCursor] [edit] -" :Utl visual split -" :Utl currentFile vsplit -" :Utl tabedit -" :Utl view -" :Utl read +" :Utl [openLink] [underCursor] [edit] +" :Utl visual split +" :Utl currentFile vsplit +" :Utl tabedit +" :Utl view +" :Utl read " -" :Utl copyLink [underCursor] +" :Utl copyLink [underCursor] " :Utl visual " :Utl currentFile " :Utl " -" :Utl copyFileName [underCursor] [native] -" :Utl currentFile backSlash -" :Utl Visual slash -" :Utl +" :Utl copyFileName [underCursor] [native] +" :Utl currentFile backSlash +" :Utl Visual slash +" :Utl " -" :Utl help [manual] -" :Utl commands +" :Utl help [manual] +" :Utl commands - " [id=cmd_abbreviations] + " [id=cmd_abbreviations] "------------------------------------------------------------------------------- " Supported abbreviations of arguments to :Utl command. " Abbreviation conventions are: @@ -164,29 +164,29 @@ let s:d32={ 'n': 'native', 'b': 'backSlash', 'bs': 'backSlash', 's': 'slash' } " before are the :Utl args provided so far in long form. " " Args: Utl command arguments according #r=cmd_reference, where the last -" can be abbreviated. +" can be abbreviated. " Returns: Last arg converted into long arg " " Collaboration: " " Example: s:abbr2longArg('copyFileName', 'underCursor', 's') -" returns 'slash' +" returns 'slash' " fu! s:abbr2longArg(...) if ! exists('a:2') - return s:utilLookup(s:d1, a:1) + return s:utilLookup(s:d1, a:1) elseif ! exists('a:3') - if a:1=='openLink'|| a:1=='copyLink'|| a:1=='copyFileName' - return s:utilLookup(s:d21, a:2) - elseif a:1=='help' - return s:utilLookup(s:d22, a:2) - endif + if a:1=='openLink'|| a:1=='copyLink'|| a:1=='copyFileName' + return s:utilLookup(s:d21, a:2) + elseif a:1=='help' + return s:utilLookup(s:d22, a:2) + endif else - if a:1=='openLink' - return s:utilLookup(s:d31, a:3) - elseif a:1 == 'copyFileName' - return s:utilLookup(s:d32, a:3) - endif + if a:1=='openLink' + return s:utilLookup(s:d31, a:3) + elseif a:1 == 'copyFileName' + return s:utilLookup(s:d32, a:3) + endif endif endfu @@ -195,7 +195,7 @@ endfu " itself fu! s:utilLookup(dict,key) if has_key(a:dict, a:key) - return a:dict[a:key] + return a:dict[a:key] endif return a:key endfu @@ -212,60 +212,60 @@ fu! Utl(...) call Utl_trace("- arg1 (cmd) provided or by default = `".cmd."'") if cmd == 'openLink' - if exists('a:2') | let operand=s:abbr2longArg(cmd,a:2) | else | let operand='underCursor' | endif - call Utl_trace("- arg2 (operand) provided or by default = `".operand."'") - if exists('a:3') | let dispMode=s:abbr2longArg(cmd,operand,a:3) | else | let dispMode='edit' | endif - call Utl_trace("- arg3 (dispMode) provided or by default = `".dispMode."'") - if operand=='underCursor' - call s:Utl_goUrl(dispMode) - elseif operand=='visual' - let url = @* - call s:Utl_processUrl(url, dispMode) - elseif operand=='currentFile' - let url = 'file://'.Utl_utilBack2FwdSlashes( expand("%:p") ) - call s:Utl_processUrl(url, dispMode) - else " the operand is the URL - call s:Utl_processUrl(operand, dispMode) - endif + if exists('a:2') | let operand=s:abbr2longArg(cmd,a:2) | else | let operand='underCursor' | endif + call Utl_trace("- arg2 (operand) provided or by default = `".operand."'") + if exists('a:3') | let dispMode=s:abbr2longArg(cmd,operand,a:3) | else | let dispMode='edit' | endif + call Utl_trace("- arg3 (dispMode) provided or by default = `".dispMode."'") + if operand=='underCursor' + call s:Utl_goUrl(dispMode) + elseif operand=='visual' + let url = @* + call s:Utl_processUrl(url, dispMode) + elseif operand=='currentFile' + let url = 'file://'.Utl_utilBack2FwdSlashes( expand("%:p") ) + call s:Utl_processUrl(url, dispMode) + else " the operand is the URL + call s:Utl_processUrl(operand, dispMode) + endif elseif cmd=='copyFileName' || cmd=='copyLink' - if exists('a:2') | let operand=s:abbr2longArg(cmd,a:2) | else | let operand='underCursor' | endif - call Utl_trace("- arg2 (operand) provided or by default = `".operand."'") - - let suffix='' - if cmd == 'copyFileName' - if exists('a:3') | let modifier=s:abbr2longArg(cmd,operand,a:3) | else | let modifier='native' | endif - call Utl_trace("- arg3 (modifier) provided or by default = `".modifier."'") - let suffix='_'.modifier - endif - - if operand=='underCursor' - call s:Utl_goUrl(cmd.suffix) - elseif operand=='visual' - let url = @* - call s:Utl_processUrl(url, cmd.suffix) - elseif operand=='currentFile' - let url = 'file://'.Utl_utilBack2FwdSlashes( expand("%:p") ) - call s:Utl_processUrl(url, cmd.suffix) - else " the operand is the URL - call Utl_trace("- `".operand."' (arg2) is not a keyword. So is directly taken as an URL") - call s:Utl_processUrl(operand, cmd.suffix) - endif + if exists('a:2') | let operand=s:abbr2longArg(cmd,a:2) | else | let operand='underCursor' | endif + call Utl_trace("- arg2 (operand) provided or by default = `".operand."'") + + let suffix='' + if cmd == 'copyFileName' + if exists('a:3') | let modifier=s:abbr2longArg(cmd,operand,a:3) | else | let modifier='native' | endif + call Utl_trace("- arg3 (modifier) provided or by default = `".modifier."'") + let suffix='_'.modifier + endif + + if operand=='underCursor' + call s:Utl_goUrl(cmd.suffix) + elseif operand=='visual' + let url = @* + call s:Utl_processUrl(url, cmd.suffix) + elseif operand=='currentFile' + let url = 'file://'.Utl_utilBack2FwdSlashes( expand("%:p") ) + call s:Utl_processUrl(url, cmd.suffix) + else " the operand is the URL + call Utl_trace("- `".operand."' (arg2) is not a keyword. So is directly taken as an URL") + call s:Utl_processUrl(operand, cmd.suffix) + endif elseif cmd == 'help' - if exists('a:2') | let operand=s:abbr2longArg(cmd,a:2) | else | let operand='manual' | endif - call Utl_trace("- arg2 (operand) provided or by default = `".operand."'\n") " CR054_extra_nl + if exists('a:2') | let operand=s:abbr2longArg(cmd,a:2) | else | let operand='manual' | endif + call Utl_trace("- arg2 (operand) provided or by default = `".operand."'\n") " CR054_extra_nl - if operand=='manual' - help utl_usr.txt - elseif operand=='commands' - call Utl('openLink', 'file://'.Utl_utilBack2FwdSlashes(expand(g:utl__file)).'#r=cmd_reference', 'sview') - else - echohl ErrorMsg | echo "invalid argument: `".operand."'" | echohl None - endif + if operand=='manual' + help utl_usr.txt + elseif operand=='commands' + call Utl('openLink', 'file://'.Utl_utilBack2FwdSlashes(expand(g:utl__file)).'#r=cmd_reference', 'sview') + else + echohl ErrorMsg | echo "invalid argument: `".operand."'" | echohl None + endif else - echohl ErrorMsg | echo "invalid argument: `".cmd."'" | echohl None + echohl ErrorMsg | echo "invalid argument: `".cmd."'" | echohl None endif call Utl_trace("- end function Utl()",1,-1) endfu @@ -293,7 +293,7 @@ endif " nmap gv :Utl openLink underCursor view " nmap gr :Utl openLink underCursor read " -" [id=suggested_mappings_visual] +" [id=suggested_mappings_visual] " vmap ge "*y:Utl openLink visual edit " vmap gu "*y:Utl openLink visual edit " vmap gE "*y:Utl openLink visual split @@ -318,7 +318,7 @@ endif " "] -let s:utl_esccmdspecial = '%#' " keep equal to utl_scm.vim#__esc +let s:utl_esccmdspecial = '%#' " keep equal to utl_scm.vim#__esc " isfname adapted to URI Reference characters let s:isuriref="@,48-57,#,;,/,?,:,@-@,&,=,+,$,,,-,_,.,!,~,*,',(,),%" @@ -335,10 +335,10 @@ fu! s:Utl_goUrl(dispMode) call Utl_trace("- start processing (dispMode=".a:dispMode.")",1,1) let url = Utl_getUrlUnderCursor() if url == '' - let v:errmsg = "No URL under Cursor" - echohl ErrorMsg | echo v:errmsg | echohl None + let v:errmsg = "No URL under Cursor" + echohl ErrorMsg | echo v:errmsg | echohl None else - call s:Utl_processUrl(url, a:dispMode) + call s:Utl_processUrl(url, a:dispMode) endif call Utl_trace("- end processing.",1,-1) endfu @@ -352,56 +352,56 @@ fu! Utl_getUrlUnderCursor() call Utl_trace("- start getting URL under cursor",1,1) let line = getline('.') - let icurs = col('.') - 1 " `Index-Cursor' + let icurs = col('.') - 1 " `Index-Cursor' call Utl_trace("- first try: checking for URL with embedding like in current line...",1,1) let url = s:Utl_extractUrlByPattern(line, icurs, '') if url=='' - call Utl_trace("- ...no",1,-1) - call Utl_trace("- retry: checking for embedded URL spanning over range of max 5 lines...",1,1) - let lineno = line('.') - " (lineno-1/2 can be negative -> getline gives empty string -> ok) - let line = getline(lineno-2) . "\n" . getline(lineno-1) . "\n" . - \ getline(lineno) . "\n" . - \ getline(lineno+1) . "\n" . getline(lineno+2) - " `Index of Cursor' - " (icurs off by +2 because of 2 \n's, plus -1 because col() starts at 1 = +1) - let icurs = strlen(getline(lineno-2)) + strlen(getline(lineno-1)) + col('.') +1 - - let url = s:Utl_extractUrlByPattern(line, icurs, '') + call Utl_trace("- ...no",1,-1) + call Utl_trace("- retry: checking for embedded URL spanning over range of max 5 lines...",1,1) + let lineno = line('.') + " (lineno-1/2 can be negative -> getline gives empty string -> ok) + let line = getline(lineno-2) . "\n" . getline(lineno-1) . "\n" . + \ getline(lineno) . "\n" . + \ getline(lineno+1) . "\n" . getline(lineno+2) + " `Index of Cursor' + " (icurs off by +2 because of 2 \n's, plus -1 because col() starts at 1 = +1) + let icurs = strlen(getline(lineno-2)) + strlen(getline(lineno-1)) + col('.') +1 + + let url = s:Utl_extractUrlByPattern(line, icurs, '') endif if url=='' - call Utl_trace("- ...no", 1, -1) - call Utl_trace("- retry: checking if [ ] style reference...", 1, 1) - if stridx(line, '[') != -1 - let isfname_save = &isfname | let &isfname = s:isuriref " ([) - let pat = '\(\(\[[A-Z0-9_]\{-}\]\)\(#\f*\)*\)' " &isfname here in \f - let url = s:Utl_extractUrlByPattern(line, icurs, pat) - let &isfname = isfname_save " (]) - " remove trailing punctuation characters if any - if url!='' - call Utl_trace("- removing trailing punctuation chars from URL if any") - let url = substitute(url, '[.,:;!?]$', '', '') - endif - endif + call Utl_trace("- ...no", 1, -1) + call Utl_trace("- retry: checking if [ ] style reference...", 1, 1) + if stridx(line, '[') != -1 + let isfname_save = &isfname | let &isfname = s:isuriref " ([) + let pat = '\(\(\[[A-Z0-9_]\{-}\]\)\(#\f*\)*\)' " &isfname here in \f + let url = s:Utl_extractUrlByPattern(line, icurs, pat) + let &isfname = isfname_save " (]) + " remove trailing punctuation characters if any + if url!='' + call Utl_trace("- removing trailing punctuation chars from URL if any") + let url = substitute(url, '[.,:;!?]$', '', '') + endif + endif endif if url=='' - call Utl_trace("- ...no", 1,-1) - call Utl_trace("- retry: checking for unembedded URL under cursor...", 1,1) - " Take as URL. But adapt isfname to match all allowed URI Reference characters - let isfname_save = &isfname | let &isfname = s:isuriref " ([) - let url = expand("") - let &isfname = isfname_save " (]) + call Utl_trace("- ...no", 1,-1) + call Utl_trace("- retry: checking for unembedded URL under cursor...", 1,1) + " Take as URL. But adapt isfname to match all allowed URI Reference characters + let isfname_save = &isfname | let &isfname = s:isuriref " ([) + let url = expand("") + let &isfname = isfname_save " (]) endif if url!='' - call Utl_trace("- ...yes, URL found: `".url."'", 1,-1) + call Utl_trace("- ...yes, URL found: `".url."'", 1,-1) else - call Utl_trace("- ...no", 1,-1) + call Utl_trace("- ...no", 1,-1) endif call Utl_trace("- end getting URL under cursor.",1,-1) @@ -432,7 +432,7 @@ endfu " " :echo s:Utl_extractUrlByPattern('Another embedding here ', 27, '') " returns `foo bar' -" +" " Details: " - The URL embedding (or if embedding at all) depends on the context: HTML " has different embedding than a txt file. @@ -450,36 +450,36 @@ fu! s:Utl_extractUrlByPattern(linestr, icurs, pat) call Utl_trace("- start extracting URL by pattern `".pat."'",1,1) if pat == '' - call Utl_trace("- pattern is , determine based on file type") - - if &ft == 'html' - let embedType = 'html' - else - let embedType = 'txt' - endif - - " (pat has to have the Url in first \(...\) because ({) ) - if embedType == 'html' - call Utl_trace("- file type is 'html'") - " Html-Pattern: - " - can have other attributes in , like - " (before and/or behind HREF) - " - can have Whitespace embedding the `=' like - " - " Note: Url must be surrounded by `"'. But that should not be mandatory... - " Regexp-Guru please help! - let pat = '' - - else - call Utl_trace("- file type is not 'html', so use generic pattern") - " Allow different embeddings: , . - " Plus for backward compatibility utl-1.0 and future - " extension. - " ( % in pattern means that this group doesn't count as \1 ) - let pat = '<\%(URL:\|LNK:\|\)\([^<]\{-}\)>' - - endif - call Utl_trace("- will use pattern `".pat."'") + call Utl_trace("- pattern is , determine based on file type") + + if &ft == 'html' + let embedType = 'html' + else + let embedType = 'txt' + endif + + " (pat has to have the Url in first \(...\) because ({) ) + if embedType == 'html' + call Utl_trace("- file type is 'html'") + " Html-Pattern: + " - can have other attributes in , like + " (before and/or behind HREF) + " - can have Whitespace embedding the `=' like + " + " Note: Url must be surrounded by `"'. But that should not be mandatory... + " Regexp-Guru please help! + let pat = '' + + else + call Utl_trace("- file type is not 'html', so use generic pattern") + " Allow different embeddings: , . + " Plus for backward compatibility utl-1.0 and future + " extension. + " ( % in pattern means that this group doesn't count as \1 ) + let pat = '<\%(URL:\|LNK:\|\)\([^<]\{-}\)>' + + endif + call Utl_trace("- will use pattern `".pat."'") endif @@ -488,37 +488,37 @@ fu! s:Utl_extractUrlByPattern(linestr, icurs, pat) " do match() and matchend() ic (i.e. allow url: urL: Url: lnk: lnk: LnK: " . - " \_s* can't be used because a string is considered a single line.) - let ibeg = match(linestr, "[ \\t \n]*".pat) - - if ibeg == -1 || ibeg > icurs - let curl = '' - break - else - " matchstart before cursor or same col as cursor, - " look if matchend is ok (i.e. after or equal cursor) - let iend = matchend(linestr, "[ \\t \n]*".pat) -1 - if iend >= icurs - " extract the URL itself from embedding - let curl = substitute(linestr, '^.\{-}'.pat.'.*', '\1', '') " (}) - break - else - " match was before cursor. Check for a second URL in linestr; - " redo with linestr = `subline' behind the match - let linestr = strpart(linestr, iend+1, 9999) - let icurs = icurs-iend-1 - continue - endif - endif + " (A so called literal \n here (and elsewhere), see + " . + " \_s* can't be used because a string is considered a single line.) + let ibeg = match(linestr, "[ \\t \n]*".pat) + + if ibeg == -1 || ibeg > icurs + let curl = '' + break + else + " matchstart before cursor or same col as cursor, + " look if matchend is ok (i.e. after or equal cursor) + let iend = matchend(linestr, "[ \\t \n]*".pat) -1 + if iend >= icurs + " extract the URL itself from embedding + let curl = substitute(linestr, '^.\{-}'.pat.'.*', '\1', '') " (}) + break + else + " match was before cursor. Check for a second URL in linestr; + " redo with linestr = `subline' behind the match + let linestr = strpart(linestr, iend+1, 9999) + let icurs = icurs-iend-1 + continue + endif + endif endwhile - let &ignorecase = saveIgnorecase " (]) + let &ignorecase = saveIgnorecase " (]) call Utl_trace("- end extracting URL by pattern, returning URL=`".curl."'",1,-1) return curl endfu @@ -530,51 +530,51 @@ endfu fu! s:Utl_setHighl() if g:utl_opt_highlight_urls ==? 'yes' - augroup utl_highl - au! - au BufWinEnter * syn case ignore - - " [id=highl_custom] - " Highlighting of URL surrounding `' " [id=highl_surround] - "au BufWinEnter * hi link UtlTag Identifier " as of Utl v2.0 - "au BufWinEnter * hi link UtlTag Ignore " `' invisible like | | in Vim help - "au BufWinEnter * hi link UtlTag PreProc - - " Highlighting of URL itself (what is inside `' " [id=highl_inside] - " Some fixed colors ( not changing with :colorscheme, but all underlined ) - "au BufWinEnter * hi UtlUrl ctermfg=LightBlue guifg=LightBlue cterm=underline gui=underline term=reverse - "au BufWinEnter * hi UtlUrl ctermfg=Blue guifg=Blue cterm=underline gui=underline term=reverse - "au BufWinEnter * hi UtlUrl ctermfg=Cyan guifg=Cyan cterm=underline gui=underline term=reverse - " Some Standard group names (see ) - "au BufWinEnter * hi link UtlUrl Tag - "au BufWinEnter * hi link UtlUrl Constant - au BufWinEnter * hi link UtlUrl Underlined - - - au BufWinEnter * syn region UtlUrl matchgroup=UtlTag start="' " [id=highl_surround] + "au BufWinEnter * hi link UtlTag Identifier " as of Utl v2.0 + "au BufWinEnter * hi link UtlTag Ignore " `' invisible like | | in Vim help + "au BufWinEnter * hi link UtlTag PreProc + + " Highlighting of URL itself (what is inside `' " [id=highl_inside] + " Some fixed colors ( not changing with :colorscheme, but all underlined ) + "au BufWinEnter * hi UtlUrl ctermfg=LightBlue guifg=LightBlue cterm=underline gui=underline term=reverse + "au BufWinEnter * hi UtlUrl ctermfg=Blue guifg=Blue cterm=underline gui=underline term=reverse + "au BufWinEnter * hi UtlUrl ctermfg=Cyan guifg=Cyan cterm=underline gui=underline term=reverse + " Some Standard group names (see ) + "au BufWinEnter * hi link UtlUrl Tag + "au BufWinEnter * hi link UtlUrl Constant + au BufWinEnter * hi link UtlUrl Underlined + + + au BufWinEnter * syn region UtlUrl matchgroup=UtlTag start="). " 2. UtlUri_abs() does not lead to a valid absolute Url (since the base-path- - " file-component will always be discarded). + " file-component will always be discarded). " if uri == '' - call Utl_trace("- is a same document reference. Go directly to fragment processing (in mode 'rel')") - " m=go - normal m' - call s:Utl_processFragmentText( fragment, 'rel' ) - call Utl_trace("- end processing URL",1,-1) - return + call Utl_trace("- is a same document reference. Go directly to fragment processing (in mode 'rel')") + " m=go + normal m' + call s:Utl_processFragmentText( fragment, 'rel' ) + call Utl_trace("- end processing URL",1,-1) + return endif call Utl_trace("- start normalize URL to an absolute URL",1,1) let scheme = UtlUri_scheme(uri) if scheme != '' - call Utl_trace("- scheme defined (".scheme.") - so is an absolute URL") - let absuri = uri - else " `uri' is formally no absolute URI but look for some - " heuristic, e.g. prepend 'http://' to 'www.vim.org' - call Utl_trace("- scheme undefined - so is a relative URL or a heuristic URL") - call Utl_trace("- check for some heuristics like www.foo.com -> http://www.foo.com... ",0) - let absuri = s:Utl_checkHeuristicAbsUrl(uri) - if absuri != '' - let scheme = UtlUri_scheme(absuri) - call Utl_trace("yes,") | call Utl_trace(" absolute URL constructed by heuristic is `".absuri."'") - else - call Utl_trace("no") - endif + call Utl_trace("- scheme defined (".scheme.") - so is an absolute URL") + let absuri = uri + else " `uri' is formally no absolute URI but look for some + " heuristic, e.g. prepend 'http://' to 'www.vim.org' + call Utl_trace("- scheme undefined - so is a relative URL or a heuristic URL") + call Utl_trace("- check for some heuristics like www.foo.com -> http://www.foo.com... ",0) + let absuri = s:Utl_checkHeuristicAbsUrl(uri) + if absuri != '' + let scheme = UtlUri_scheme(absuri) + call Utl_trace("yes,") | call Utl_trace(" absolute URL constructed by heuristic is `".absuri."'") + else + call Utl_trace("no") + endif endif if scheme == '' - let curPath = Utl_utilBack2FwdSlashes( expand("%:p") ) - if stridx(curPath, '://') != -1 " id=url_buffer (e.g. by netrw) - call Utl_trace("- buffer's name looks like an absolute URL (has substring ://)") - call Utl_trace(" so take it as base URL.") - let base = curPath - else - call Utl_trace("- try to construct a `file://' base URL from current buffer... ",0) - " No corresponding resource to curPath known. (id=nobase) - " i.e. curPath was not retrieved through Utl. - " Now just make the usual heuristic of `file://localhost/'-Url; - " assume, that the curPath is the resource itsself. If then the - " retrieve with the so generated Url is not possible, nothing - " severe happens. - if curPath == '' - call Utl_trace("not possible, give up") - let v:errmsg = "Cannot make a base URL from unnamed buffer. Edit a file and try again" - echohl ErrorMsg | echo v:errmsg | echohl None - call Utl_trace("- end normalize URL to an absolute URL",1,-1) - call Utl_trace("- end processing URL",1,-1) - return - endif - let base = 'file://' . curPath - call Utl_trace("done,") - endif - call Utl_trace(" base URL is `".base."'") - let scheme = UtlUri_scheme(base) - call Utl_trace("- construct absolute URL from combining base URL and relative URL") - let absuri = UtlUri_abs(uri,base) + let curPath = Utl_utilBack2FwdSlashes( expand("%:p") ) + if stridx(curPath, '://') != -1 " id=url_buffer (e.g. by netrw) + call Utl_trace("- buffer's name looks like an absolute URL (has substring ://)") + call Utl_trace(" so take it as base URL.") + let base = curPath + else + call Utl_trace("- try to construct a `file://' base URL from current buffer... ",0) + " No corresponding resource to curPath known. (id=nobase) + " i.e. curPath was not retrieved through Utl. + " Now just make the usual heuristic of `file://localhost/'-Url; + " assume, that the curPath is the resource itsself. If then the + " retrieve with the so generated Url is not possible, nothing + " severe happens. + if curPath == '' + call Utl_trace("not possible, give up") + let v:errmsg = "Cannot make a base URL from unnamed buffer. Edit a file and try again" + echohl ErrorMsg | echo v:errmsg | echohl None + call Utl_trace("- end normalize URL to an absolute URL",1,-1) + call Utl_trace("- end processing URL",1,-1) + return + endif + let base = 'file://' . curPath + call Utl_trace("done,") + endif + call Utl_trace(" base URL is `".base."'") + let scheme = UtlUri_scheme(base) + call Utl_trace("- construct absolute URL from combining base URL and relative URL") + let absuri = UtlUri_abs(uri,base) endif call Utl_trace("- assertion: now have absolute URL `".absuri."' with scheme `".scheme."'") call Utl_trace("- end normalize URL to an absolute URL",1,-1) if a:dispMode==? 'copyLink' - call Utl_trace("processing mode is `copyLink'. Copy link to clipboard") - call setreg('*', absuri) - echo "Copied `".@*."' to clipboard" - call Utl_trace("- end processing URL",1,-1) - return + call Utl_trace("processing mode is `copyLink'. Copy link to clipboard") + call setreg('*', absuri) + echo "Copied `".@*."' to clipboard" + call Utl_trace("- end processing URL",1,-1) + return endif @@ -706,17 +706,17 @@ fu! s:Utl_processUrl(uriref, dispMode) " Always set a jump mark to allow get back to cursor position before " jump (see also CR051). - " m=go id=_setj + " m=go id=_setj normal m' let cbfunc = 'Utl_AddressScheme_' . scheme call Utl_trace("- constructing call back function name from scheme: `".cbfunc."'") if !exists('*'.cbfunc) - let v:errmsg = "Sorry, scheme `".scheme.":' not implemented" - echohl ErrorMsg | echo v:errmsg | echohl None + let v:errmsg = "Sorry, scheme `".scheme.":' not implemented" + echohl ErrorMsg | echo v:errmsg | echohl None call Utl_trace("- end scheme handler processing",1,-1) - call Utl_trace("- end processing URL",1,-1) - return + call Utl_trace("- end processing URL",1,-1) + return endif call Utl_trace("- calling call back function with arguments:") call Utl_trace(" arg 1 - absolute URL=`".absuri."'") @@ -724,13 +724,13 @@ fu! s:Utl_processUrl(uriref, dispMode) call Utl_trace(" arg 3 - display Mode=`".a:dispMode."'") exe 'let ret = ' cbfunc . '("'.absuri.'", "'.fragment.'", "'.a:dispMode.'")' call Utl_trace("- call back function `".cbfunc."' returned list:`". join(ret,',') ."'") - exe "normal \" | " Redraw seems necessary for non GUI Vim under Unix'es + exe 'redraw!' | " Redraw seems necessary for non GUI Vim under Unix'es if !len(ret) - call Utl_trace("- empty list -> no further processing") + call Utl_trace("- empty list -> no further processing") call Utl_trace("- end scheme handler processing",1,-1) - call Utl_trace("- end processing URL",1,-1) - return + call Utl_trace("- end processing URL",1,-1) + return endif let localPath = ret[0] @@ -740,9 +740,9 @@ fu! s:Utl_processUrl(uriref, dispMode) " Assertion if stridx(localPath, '\') != -1 - echohl ErrorMsg - call input("Internal Error: localPath `".localPath."' contains backslashes ") - echohl None + echohl ErrorMsg + call input("Internal Error: localPath `".localPath."' contains backslashes ") + echohl None endif call Utl_trace("- assertion: a local path corresponds to URL") @@ -750,29 +750,29 @@ fu! s:Utl_processUrl(uriref, dispMode) let dispMode = a:dispMode if a:dispMode == 'copyFileName_native' - if has("win32") || has("win16") || has("win64") || has("dos32") || has("dos16") - call Utl_trace("- changing dispMode `copyFileName_native' to 'copyFileName_backSlash' since under Windows") - let dispMode = 'copyFileName_backSlash' - else - call Utl_trace("- changing dispMode `copyFileName_native' to 'copyFileName_slash' since not under Windows") - let dispMode = 'copyFileName_slash' - endif + if has("win32") || has("win16") || has("win64") || has("dos32") || has("dos16") + call Utl_trace("- changing dispMode `copyFileName_native' to 'copyFileName_backSlash' since under Windows") + let dispMode = 'copyFileName_backSlash' + else + call Utl_trace("- changing dispMode `copyFileName_native' to 'copyFileName_slash' since not under Windows") + let dispMode = 'copyFileName_slash' + endif endif if dispMode == 'copyFileName_slash' - call Utl_trace("- processing mode is `copyFileName_slash': copy file name, which corresponds to link") - call Utl_trace(" (with forward slashes) to clipboard") - call setreg('*', localPath ) - echo "Copied `".@*."' to clipboard" - call Utl_trace("- end processing URL",1,-1) - return + call Utl_trace("- processing mode is `copyFileName_slash': copy file name, which corresponds to link") + call Utl_trace(" (with forward slashes) to clipboard") + call setreg('*', localPath ) + echo "Copied `".@*."' to clipboard" + call Utl_trace("- end processing URL",1,-1) + return elseif dispMode == 'copyFileName_backSlash' - call Utl_trace("- processing mode is `copyFileName_backSlash': copy file name, which corresponds to link") - call Utl_trace(" (with backslashes) to clipboard") - call setreg('*', Utl_utilFwd2BackSlashes(localPath) ) - echo "Copied `".@*."' to clipboard" - call Utl_trace("- end processing URL",1,-1) - return + call Utl_trace("- processing mode is `copyFileName_backSlash': copy file name, which corresponds to link") + call Utl_trace(" (with backslashes) to clipboard") + call setreg('*', Utl_utilFwd2BackSlashes(localPath) ) + echo "Copied `".@*."' to clipboard" + call Utl_trace("- end processing URL",1,-1) + return endif " See if media type is defined for localPath, and if yes, whether a @@ -792,71 +792,71 @@ fu! s:Utl_processUrl(uriref, dispMode) if contentType == '' call Utl_trace("no. Display local path in this Vim.") else - call Utl_trace("yes, media type is `".contentType."'.") - let slashPos = stridx(contentType, '/') - - let var_s = 'g:utl_cfg_hdl_mt_' . substitute(contentType, '[-/+.]', '_', 'g') - call Utl_trace("- constructing Vim variable for specific media type handler:") - call Utl_trace(" `".var_s."'. Now check if it exists...") - if exists(var_s) - call Utl_trace(" ...exists, and will be used") - let var = var_s - else - call Utl_trace(" ...does not exist. Now check generic media type handler variable") - let var_g = 'g:utl_cfg_hdl_mt_generic' - if exists(var_g) - call Utl_trace("- Vim variable `".var_g."' does exist and will be used") - else - call Utl_trace(" Vim variable `".var_g."' does not exist either") - endif - let var = var_g - endif - - if ! exists(var) " Entering setup - echohl WarningMsg - call input('No handler for media type '.contentType.' defined yet. Entering Setup now. ') - echohl None - call s:Utl_processUrl('config:#r=utl_cfg_hdl_mt_generic', 'split') " (recursion, setup) - call Utl_trace("- end media type handler processing",1,-1) - call Utl_trace("- end processing URL",1,-1) - return - endif - exe 'let varVal =' . var - call Utl_trace("- Variable has value `".varVal."'") - if varVal ==? 'VIM' - call Utl_trace("- value of variable is 'VIM': display in this Vim") - else - call Utl_trace("- construct command by expanding any % conversion specifiers.") - let convSpecDict= { 'p': localPath, 'P': Utl_utilFwd2BackSlashes(localPath), - \ 'f': (fragment=="" ? "" : fragment) } " '' -> '' for external handler - exe 'let [errmsg,cmd] = Utl_utilExpandConvSpec('.var.', convSpecDict)' - if errmsg != "" - echohl ErrorMsg - echo "The content of the Utl-setup variable `".var."' is invalid and has to be fixed! Reason: `".errmsg."'" - echohl None - call Utl_trace("- end media type handler processing",1,-1) - call Utl_trace("- end processing URL",1,-1) - return - endif - call Utl_trace("- constructed command is: `".cmd."'") - " Escape string to be executed as a ex command (i.e. escape some - " characters from special treatment ) - " and execute the command - let escCmd = escape(cmd, s:utl_esccmdspecial) - if escCmd != cmd - call Utl_trace("- escape characters, command changes to: `".escCmd."'") - endif - call Utl_trace("- execute command with :exe") - exe escCmd - call Utl_trace("- end media type handler processing",1,-1) - call Utl_trace("- end processing URL",1,-1) - return - endif + call Utl_trace("yes, media type is `".contentType."'.") + let slashPos = stridx(contentType, '/') + + let var_s = 'g:utl_cfg_hdl_mt_' . substitute(contentType, '[-/+.]', '_', 'g') + call Utl_trace("- constructing Vim variable for specific media type handler:") + call Utl_trace(" `".var_s."'. Now check if it exists...") + if exists(var_s) + call Utl_trace(" ...exists, and will be used") + let var = var_s + else + call Utl_trace(" ...does not exist. Now check generic media type handler variable") + let var_g = 'g:utl_cfg_hdl_mt_generic' + if exists(var_g) + call Utl_trace("- Vim variable `".var_g."' does exist and will be used") + else + call Utl_trace(" Vim variable `".var_g."' does not exist either") + endif + let var = var_g + endif + + if ! exists(var) " Entering setup + echohl WarningMsg + call input('No handler for media type '.contentType.' defined yet. Entering Setup now. ') + echohl None + call s:Utl_processUrl('config:#r=utl_cfg_hdl_mt_generic', 'split') " (recursion, setup) + call Utl_trace("- end media type handler processing",1,-1) + call Utl_trace("- end processing URL",1,-1) + return + endif + exe 'let varVal =' . var + call Utl_trace("- Variable has value `".varVal."'") + if varVal ==? 'VIM' + call Utl_trace("- value of variable is 'VIM': display in this Vim") + else + call Utl_trace("- construct command by expanding any % conversion specifiers.") + let convSpecDict= { 'p': localPath, 'P': Utl_utilFwd2BackSlashes(localPath), + \ 'f': (fragment=="" ? "" : fragment) } " '' -> '' for external handler + exe 'let [errmsg,cmd] = Utl_utilExpandConvSpec('.var.', convSpecDict)' + if errmsg != "" + echohl ErrorMsg + echo "The content of the Utl-setup variable `".var."' is invalid and has to be fixed! Reason: `".errmsg."'" + echohl None + call Utl_trace("- end media type handler processing",1,-1) + call Utl_trace("- end processing URL",1,-1) + return + endif + call Utl_trace("- constructed command is: `".cmd."'") + " Escape string to be executed as a ex command (i.e. escape some + " characters from special treatment ) + " and execute the command + let escCmd = escape(cmd, s:utl_esccmdspecial) + if escCmd != cmd + call Utl_trace("- escape characters, command changes to: `".escCmd."'") + endif + call Utl_trace("- execute command with :exe") + exe escCmd + call Utl_trace("- end media type handler processing",1,-1) + call Utl_trace("- end processing URL",1,-1) + return + endif endif call Utl_trace("- end media type handler processing",1,-1) if s:Utl_displayFile(localPath, dispMode) - call s:Utl_processFragmentText(fragment, fragMode) + call s:Utl_processFragmentText(fragment, fragMode) endif call Utl_trace("- end processing URL",1,-1) endfu @@ -875,26 +875,26 @@ fu! s:Utl_checkHeuristicAbsUrl(uri) "--- [1] -> foot:1 if match(a:uri, '^\[.\{-}\]') != -1 - return substitute(a:uri, '^\[\(.\{-}\)\]', 'foot:\1', '') + return substitute(a:uri, '^\[\(.\{-}\)\]', 'foot:\1', '') "--- www.host.domain -> http://www.host.domain elseif match(a:uri, '^www\.') != -1 - return 'http://' . a:uri + return 'http://' . a:uri "--- user@host.domain -> mailto:user@host.domain elseif match(a:uri, '@') != -1 - return 'mailto:' . a:uri + return 'mailto:' . a:uri "--- :xxx -> vimscript::xxx elseif match(a:uri, '^:') != -1 - return 'vimscript:' . a:uri + return 'vimscript:' . a:uri - " BT12084 -> BT:12084 #id=heur_example + " BT12084 -> BT:12084 #id=heur_example " This is an example of a custom heuristics which I use myself. I have a " text file which contains entries like 'BT12084' which refer to that id " 12084 in a bug tracking database. elseif match(a:uri, '^[PB]T\d\{4,}') != -1 - return substitute(a:uri, '^\([PB]T\)\(\d\+\)', 'BT:\2', '') + return substitute(a:uri, '^\([PB]T\)\(\d\+\)', 'BT:\2', '') endif @@ -923,7 +923,7 @@ fu! s:Utl_escapeCmdLineSpecialChars(fileName) " - Also escape blanks because single word needed, e.g. `:e foo bar'. " Escape spaces only if on unix (no problem on Windows) (CR033) if has("unix") - let escFileName = escape(escFileName, ' ') + let escFileName = escape(escFileName, ' ') endif return escFileName @@ -937,7 +937,7 @@ endfu " Escapes characters in localPath which have special meaning for Vim but " which must not have special meaning in URL paths. " -" - `dispMode' specification: (id=dispMode) +" - `dispMode' specification: (id=dispMode) " Resembles XML-XLink's `show' attribut. Value is taken directly as Vim " command. Examples: 'view', 'edit', 'sview', 'split', 'read', 'tabe' " @@ -952,62 +952,62 @@ endfu " . Does not explicitly set the cursor " . Does not explicitly set the ' mark " -" Example: :call s:Utl_displayFile('t.txt', 'split') +" Example: :call s:Utl_displayFile('t.txt', 'split') " fu! s:Utl_displayFile(localPath, dispMode) call Utl_trace("- start display file `".a:localPath."' in mode `".a:dispMode."'",1,1) let bwnrlp = bufwinnr(a:localPath) if bwnrlp != -1 && winnr() == bwnrlp - call Utl_trace("- file already displayed in current window") - call Utl_trace("- end display file",1,-1) - return 1 + call Utl_trace("- file already displayed in current window") + call Utl_trace("- end display file",1,-1) + return 1 endif if bwnrlp != -1 - " localPath already displayed, but not in current window - " Just make this buffer the current window. - call Utl_trace("- file already displayed, but not in other window. Move to that window") - exe bwnrlp . "wincmd w" + " localPath already displayed, but not in current window + " Just make this buffer the current window. + call Utl_trace("- file already displayed, but not in other window. Move to that window") + exe bwnrlp . "wincmd w" else " Open file - call Utl_trace("- file not yet displayed in any window") - - " Possibly alter dispMode to avoid E37 error (id=_altersa) - " If buffer cannot be ned, for given dispMode, - " silently change the dispMode to a corresponding split-dispMode. Want - " to avoid annoying E37 message when executing URL on modified buffer (CR024) - let dispMode = a:dispMode - if getbufvar(winbufnr(0),"&mod") && ! getbufvar(winbufnr(0),"&awa") && ! getbufvar(winbufnr(0),"&hid") - if dispMode == 'edit' - let dispMode = 'split' - call Utl_trace("- current window can probably not be quit, so silently change mode to `split'") - elseif dispMode == 'view' - let dispMode = 'sview' - call Utl_trace("- current window can probably not be quit, so silently change mode to `sview'") - endif - endif - - let escLocalPath = s:Utl_escapeCmdLineSpecialChars(a:localPath) - if escLocalPath != a:localPath - call Utl_trace("- Escaped one or more characters out of #,%,$ (under Unix also blank)") - call Utl_trace(" because these would else be expanded in Vim's command line") - call Utl_trace(" File name changed to: `".escLocalPath."'") - endif - - - "--- Try load file or create new buffer. Then check if buffer actually - " loaded - might fail for if E325 (swap file exists) and user abort - " - let cmd = dispMode.' '.escLocalPath - call Utl_trace("- trying to load/display file with command: `".cmd."'\n") " CR054_extra_nl - exe cmd - exe "normal \" | " Redraw seems necessary for non GUI Vim under Unix'es - - if bufwinnr(escLocalPath) != winnr() " not loaded - call Utl_trace("- not loaded.") - call Utl_trace("- end display file (not successful)",1,-1) - return 0 - endif + call Utl_trace("- file not yet displayed in any window") + + " Possibly alter dispMode to avoid E37 error (id=_altersa) + " If buffer cannot be ned, for given dispMode, + " silently change the dispMode to a corresponding split-dispMode. Want + " to avoid annoying E37 message when executing URL on modified buffer (CR024) + let dispMode = a:dispMode + if getbufvar(winbufnr(0),"&mod") && ! getbufvar(winbufnr(0),"&awa") && ! getbufvar(winbufnr(0),"&hid") + if dispMode == 'edit' + let dispMode = 'split' + call Utl_trace("- current window can probably not be quit, so silently change mode to `split'") + elseif dispMode == 'view' + let dispMode = 'sview' + call Utl_trace("- current window can probably not be quit, so silently change mode to `sview'") + endif + endif + + let escLocalPath = s:Utl_escapeCmdLineSpecialChars(a:localPath) + if escLocalPath != a:localPath + call Utl_trace("- Escaped one or more characters out of #,%,$ (under Unix also blank)") + call Utl_trace(" because these would else be expanded in Vim's command line") + call Utl_trace(" File name changed to: `".escLocalPath."'") + endif + + + "--- Try load file or create new buffer. Then check if buffer actually + " loaded - might fail for if E325 (swap file exists) and user abort + " + let cmd = dispMode.' '.escLocalPath + call Utl_trace("- trying to load/display file with command: `".cmd."'\n") " CR054_extra_nl + exe cmd + exe 'redraw!' | " Redraw seems necessary for non GUI Vim under Unix'es + + if bufwinnr(escLocalPath) != winnr() " not loaded + call Utl_trace("- not loaded.") + call Utl_trace("- end display file (not successful)",1,-1) + return 0 + endif endif @@ -1036,7 +1036,7 @@ endfu fu! s:Utl_checkMediaType(path) if isdirectory(a:path) - return "text/directory" + return "text/directory" endif let ext = fnamemodify(a:path, ":e") @@ -1055,41 +1055,41 @@ fu! s:Utl_checkMediaType(path) elseif ext==?'msg' let mt = 'application/msmsg' elseif ext==?'avi' - let mt = 'video/x-msvideo' + let mt = 'video/x-msvideo' " universal elseif ext==?'dvi' - let mt = 'application/x-dvi' + let mt = 'application/x-dvi' elseif ext==?'pdf' let mt = 'application/pdf' elseif ext==?'rtf' let mt = 'application/rtf' elseif ext==?'ai' || ext==?'eps' || ext==?'ps' - let mt = 'application/postscript' + let mt = 'application/postscript' elseif ext==?'rtf' let mt = 'application/rtf' elseif ext==?'zip' let mt = 'application/zip' elseif ext==?'mp3' || ext==?'mp2' || ext==?'mpga' - let mt = 'audio/mpeg' + let mt = 'audio/mpeg' elseif ext==?'png' - let mt = 'image/png' + let mt = 'image/png' elseif ext==?'jpeg' || ext==?'jpg' || ext==?'jpe' || ext==?'jfif' - let mt = 'image/jpeg' + let mt = 'image/jpeg' elseif ext==?'tiff' || ext==?'tif' - let mt = 'image/tiff' + let mt = 'image/tiff' elseif ext==?'gif' || ext==?'gif' - let mt = 'image/gif' + let mt = 'image/gif' elseif ext==?'mp2' || ext==?'mpe' || ext==?'mpeg' || ext==?'mpg' - let mt = 'video/mpeg' + let mt = 'video/mpeg' " id=texthtml elseif ext==?'html' || ext==?'htm' - let mt = 'text/html' + let mt = 'text/html' " unix/linux oriented elseif ext==?'fig' - let mt = 'image/x-fig' + let mt = 'image/x-fig' endif return mt @@ -1102,21 +1102,21 @@ endfu " `fragMode' which can have values 'abs' or 'rel'. " " - arg `fragment' can be: -" tn=string - searches string beginning at start position forward. -" The naked fragment (without a `xx=' as prefix defaults -" to tn=). -" tp=string - searches string beginning at start position backward. -" line=number - move cursor number lines from start position. Number -" can be positive or negative. If `fragMode' is 'abs' -" -1 denotes the last line, -2 the before last line etc. +" tn=string - searches string beginning at start position forward. +" The naked fragment (without a `xx=' as prefix defaults +" to tn=). +" tp=string - searches string beginning at start position backward. +" line=number - move cursor number lines from start position. Number +" can be positive or negative. If `fragMode' is 'abs' +" -1 denotes the last line, -2 the before last line etc. " r=identifier - (IdReference) search for id=identifier\> starting from -" begin of buffer. `fragMode' is ignored. +" begin of buffer. `fragMode' is ignored. " " - arg `fragMode' modifies the start position. Can have the values: " 'abs' = absolute: Cursor is set to begin or end of document, depending on -" fragment, then position starting from there. -" Start position for tn=, line=nnn, line=+nnn r= is begin of buffer. -" Start position for tp=, line=-nnn is end of buffer. +" fragment, then position starting from there. +" Start position for tn=, line=nnn, line=+nnn r= is begin of buffer. +" Start position for tp=, line=-nnn is end of buffer. " 'rel' = relative: Start positioning the cursor from current position. " " Details: @@ -1138,15 +1138,15 @@ fu! s:Utl_processFragmentText(fragment, fragMode) call Utl_trace("- start processing fragment `".a:fragment."' in mode `".a:fragMode."'",1,1) if a:fragment == '' || a:fragment == '' - call Utl_trace("- have no or empty fragment") - if a:fragMode=='abs' - call Utl_trace("- since mode is `abs' position cursor to begin of buffer") - call cursor(1,1) - else - call Utl_trace("- since mode is `rel' do nothing") - endif - call Utl_trace("- end processing fragment",1,-1) - return + call Utl_trace("- have no or empty fragment") + if a:fragMode=='abs' + call Utl_trace("- since mode is `abs' position cursor to begin of buffer") + call cursor(1,1) + else + call Utl_trace("- since mode is `rel' do nothing") + endif + call Utl_trace("- end processing fragment",1,-1) + return endif let ufrag = UtlUri_unescape(a:fragment) @@ -1155,32 +1155,32 @@ fu! s:Utl_processFragmentText(fragment, fragMode) endif if ufrag =~ '^line=[-+]\=[0-9]*$' - call Utl_trace("- is a `line=' fragment") - - let sign = substitute(ufrag, '^line=\([-+]\)\=\([0-9]*\)$', '\1', '') - let num = substitute(ufrag, '^line=\([-+]\)\=\([0-9]*\)$', '\2', '') - - if a:fragMode=='abs' - if sign == '-' - call Utl_trace("- negative sign in mode 'abs': position cursor up ".num." lines from end of buffer") - call cursor( line('$') - num + 1, 1 ) - else - call Utl_trace("- positive sign in mode 'abs': position cursor to line ".num) - call cursor(num,1) - endif - - else - if sign == '-' - call Utl_trace("- negative sign in mode 'rel': position cursor up ".num." lines from current position") - call cursor( line('.') - num , 1 ) - else - call Utl_trace("- positive sign in mode 'rel': position cursor down ".num." lines from current position") - call cursor( line('.') + num , 1 ) - endif - - endif - call Utl_trace("- end processing fragment",1,-1) - return + call Utl_trace("- is a `line=' fragment") + + let sign = substitute(ufrag, '^line=\([-+]\)\=\([0-9]*\)$', '\1', '') + let num = substitute(ufrag, '^line=\([-+]\)\=\([0-9]*\)$', '\2', '') + + if a:fragMode=='abs' + if sign == '-' + call Utl_trace("- negative sign in mode 'abs': position cursor up ".num." lines from end of buffer") + call cursor( line('$') - num + 1, 1 ) + else + call Utl_trace("- positive sign in mode 'abs': position cursor to line ".num) + call cursor(num,1) + endif + + else + if sign == '-' + call Utl_trace("- negative sign in mode 'rel': position cursor up ".num." lines from current position") + call cursor( line('.') - num , 1 ) + else + call Utl_trace("- positive sign in mode 'rel': position cursor down ".num." lines from current position") + call cursor( line('.') + num , 1 ) + endif + + endif + call Utl_trace("- end processing fragment",1,-1) + return endif " (the rest is positioning by search) @@ -1191,61 +1191,61 @@ fu! s:Utl_processFragmentText(fragment, fragMode) let fragMode = a:fragMode let sfwd=1 if ufrag =~ '^r=' - call Utl_trace("- is an ID reference. Construct file type dependent search pattern") - " ( \w\@! is normally the same as \> , i.e. match end of word, - " but is not the same in help windows, where 'iskeyword' is - " set to include non word characters. \w\@! is independent of - " settings ) - let val = substitute(ufrag, '^r=\(.*\)$', '\1', '') - if &ft == 'html' - call Utl_trace("- file type is 'html' - search for NAME=") - let cmd = '/\c\MNAME=\.\=' . val . '\w\@!' . "\r" - else - call Utl_trace("- file type is not 'html' - search for id=") - let cmd = '/\c\Mid=' . val . '\w\@!' . "\r" - endif - if fragMode=='rel' - call Utl_trace("- search will be with 'wrapscan' (since ID reference anywhere in text)") - let opt_wrapscan='wrapscan' - endif + call Utl_trace("- is an ID reference. Construct file type dependent search pattern") + " ( \w\@! is normally the same as \> , i.e. match end of word, + " but is not the same in help windows, where 'iskeyword' is + " set to include non word characters. \w\@! is independent of + " settings ) + let val = substitute(ufrag, '^r=\(.*\)$', '\1', '') + if &ft == 'html' + call Utl_trace("- file type is 'html' - search for NAME=") + let cmd = '/\c\MNAME=\.\=' . val . '\w\@!' . "\r" + else + call Utl_trace("- file type is not 'html' - search for id=") + let cmd = '/\c\Mid=' . val . '\w\@!' . "\r" + endif + if fragMode=='rel' + call Utl_trace("- search will be with 'wrapscan' (since ID reference anywhere in text)") + let opt_wrapscan='wrapscan' + endif elseif ufrag =~ '^tp=' " text previous - call Utl_trace("- is a `tp=' (Text Previous) fragment: search backwards") - let cmd = substitute(ufrag, '^tp=\(.*\)$', '?\\c\\M\1\r', '') - let sfwd=0 + call Utl_trace("- is a `tp=' (Text Previous) fragment: search backwards") + let cmd = substitute(ufrag, '^tp=\(.*\)$', '?\\c\\M\1\r', '') + let sfwd=0 elseif ufrag =~ '^tn=' " tn= or naked. text next - call Utl_trace("- is a `tn=' (Text Next) fragment: search forward") - let cmd = substitute(ufrag, '^tn=\(.*\)$', '/\\c\\M\1\r', '') + call Utl_trace("- is a `tn=' (Text Next) fragment: search forward") + let cmd = substitute(ufrag, '^tn=\(.*\)$', '/\\c\\M\1\r', '') else - call Utl_trace("- is a naked fragment. Is treated like `tn=' (Text Next) fragment: search forward") - let cmd = '/\c\M' . ufrag . "\r" " Note: \c\M vs \\c\\M at <#tp=substitute> + call Utl_trace("- is a naked fragment. Is treated like `tn=' (Text Next) fragment: search forward") + let cmd = '/\c\M' . ufrag . "\r" " Note: \c\M vs \\c\\M at <#tp=substitute> endif " Initialize Cursor before actual search (CR051) if fragMode=='abs' - if sfwd==1 - call Utl_trace("- forward search in mode 'abs': starting search at begin of buffer") - call cursor(1,1) - else - call Utl_trace("- backward search in mode 'abs': starting search at end of buffer") - call cursor( line('$'), col('$') ) - endif + if sfwd==1 + call Utl_trace("- forward search in mode 'abs': starting search at begin of buffer") + call cursor(1,1) + else + call Utl_trace("- backward search in mode 'abs': starting search at end of buffer") + call cursor( line('$'), col('$') ) + endif else - if sfwd==1 - call Utl_trace("- forward search in mode 'rel': starting search at end of current line") - call cursor( line('.'), col('$') ) - else - call Utl_trace("- forward search in mode 'rel': starting search at begin of current line") - call cursor( line('.'), 1) - endif + if sfwd==1 + call Utl_trace("- forward search in mode 'rel': starting search at end of current line") + call cursor( line('.'), col('$') ) + else + call Utl_trace("- forward search in mode 'rel': starting search at begin of current line") + call cursor( line('.'), 1) + endif endif if ! exists('opt_wrapscan') - let opt_wrapscan = 'nowrapscan' - call Utl_trace("- search will be with 'nowrapscan' (avoid false hit if mode='rel')") + let opt_wrapscan = 'nowrapscan' + call Utl_trace("- search will be with 'nowrapscan' (avoid false hit if mode='rel')") endif " Do text search (id=fragTextSearch) @@ -1258,11 +1258,11 @@ fu! s:Utl_processFragmentText(fragment, fragMode) let v:errmsg = "" silent! exe "keepjumps normal " . cmd if v:errmsg != "" - let v:errmsg = "fragment address #" . a:fragment . " not found in target" - echohl ErrorMsg | echo v:errmsg | echohl None + let v:errmsg = "fragment address #" . a:fragment . " not found in target" + echohl ErrorMsg | echo v:errmsg | echohl None endif - let &wrapscan = saveWrapscan "---] + let &wrapscan = saveWrapscan "---] call Utl_trace("- restored previous value for 'wrapscan'") call Utl_trace("- end processing fragment",1,-1) @@ -1280,12 +1280,12 @@ endfu " The case of conversion specifier matters, e.g. %p and '%P' are different. " " Args: -" str - string to be expanded -" convSpecDict - dictionary containing specifier - replacement entries, -" e.g. 'p' - 'c:/path/to/file' +" str - string to be expanded +" convSpecDict - dictionary containing specifier - replacement entries, +" e.g. 'p' - 'c:/path/to/file' " " Returns: List [errormessage, converted string], -" where either or the other is an empty string +" where either or the other is an empty string " fu! Utl_utilExpandConvSpec(str, convSpecDict) @@ -1293,29 +1293,29 @@ fu! Utl_utilExpandConvSpec(str, convSpecDict) let out = '' while 1 - let percentPos = stridx(rest, '%') - if percentPos != -1 - let left = strpart(rest, 0, percentPos) - let specifier = strpart(rest, percentPos+1, 1) - let rest = strpart(rest, percentPos+2) - else - let out = out . rest - break - endif - if strpart(left, percentPos-1, 1) == '\' " escaped \% - let left = strpart(left, 0, percentPos-1) - let repl = '%' . specifier - else " not escaped - if specifier == '' - return ["Unescaped % character at end of string >".a:str."<", ""] - elseif has_key(a:convSpecDict, specifier) - let repl = a:convSpecDict[specifier] - else - return ["Invalid conversion specifier `%".specifier."' in `".a:str. - \ "'. Valid specifiers are: `". join(map(keys(a:convSpecDict), '"%".v:val')), ""] - endif - endif - let out = out . left . repl + let percentPos = stridx(rest, '%') + if percentPos != -1 + let left = strpart(rest, 0, percentPos) + let specifier = strpart(rest, percentPos+1, 1) + let rest = strpart(rest, percentPos+2) + else + let out = out . rest + break + endif + if strpart(left, percentPos-1, 1) == '\' " escaped \% + let left = strpart(left, 0, percentPos-1) + let repl = '%' . specifier + else " not escaped + if specifier == '' + return ["Unescaped % character at end of string >".a:str."<", ""] + elseif has_key(a:convSpecDict, specifier) + let repl = a:convSpecDict[specifier] + else + return ["Invalid conversion specifier `%".specifier."' in `".a:str. + \ "'. Valid specifiers are: `". join(map(keys(a:convSpecDict), '"%".v:val')), ""] + endif + endif + let out = out . left . repl endwhile return ["",out] @@ -1330,40 +1330,40 @@ endfu " " - args " msg, -" [flush,] boolean, default=1 -> print msg directly +" [flush,] boolean, default=1 -> print msg directly " [incrLevel] number, values= -1 (reduce indent), 0 (unchanged), +1 (augment indent) -" default ist 0 (unchanged) +" default ist 0 (unchanged) " let s:utl_trace_buffer = '' let s:utl_trace_level = 0 fu! Utl_trace(msg, ...) if g:utl_opt_verbose == 0 - return + return endif "echo " DBG msg=`".a:msg."'" let flush=1 if exists('a:1') - let flush = a:1 + let flush = a:1 endif let incrLevel = 0 if exists('a:2') - let incrLevel = a:2 + let incrLevel = a:2 endif " If negative, do it before printing if incrLevel < 0 - let s:utl_trace_level += incrLevel - " Assertion - if s:utl_trace_level < 0 - echohl ErrorMsg - call input("Internal Error: Utl_trace: negative indent. Setting to zero ") - echohl None - let s:utl_trace_level = 0 - endif - "echo " DBG (changed,before) utl_trace_level=`".s:utl_trace_level."'" + let s:utl_trace_level += incrLevel + " Assertion + if s:utl_trace_level < 0 + echohl ErrorMsg + call input("Internal Error: Utl_trace: negative indent. Setting to zero ") + echohl None + let s:utl_trace_level = 0 + endif + "echo " DBG (changed,before) utl_trace_level=`".s:utl_trace_level."'" endif " echohl ErrorMsg @@ -1374,25 +1374,25 @@ fu! Utl_trace(msg, ...) let s:utl_trace_buffer = s:utl_trace_buffer . a:msg if flush=='1' - " construct indenting corresponding to level - let indentNum = s:utl_trace_level - let indent = '' - while indentNum - "echo " DBG indentNum=`".indentNum."'" - let indent = indent . ' ' " indent depth is two blanks - let indentNum -= 1 - endwhile - "echo " DBG indent=`".indent."'" + " construct indenting corresponding to level + let indentNum = s:utl_trace_level + let indent = '' + while indentNum + "echo " DBG indentNum=`".indentNum."'" + let indent = indent . ' ' " indent depth is two blanks + let indentNum -= 1 + endwhile + "echo " DBG indent=`".indent."'" - echo indent . s:utl_trace_buffer - let s:utl_trace_buffer = '' + echo indent . s:utl_trace_buffer + let s:utl_trace_buffer = '' endif " If positive, do it after printing if incrLevel > 0 - let s:utl_trace_level += incrLevel - "echo " DBG (changed,after) utl_trace_level=`".s:utl_trace_level."'" + let s:utl_trace_level += incrLevel + "echo " DBG (changed,after) utl_trace_level=`".s:utl_trace_level."'" endif endfu @@ -1409,7 +1409,7 @@ endfu " - Shows result to user by prompting hit-any-key " - Except for use of utl_trace function pure utility function. " -" Ret: - +" Ret: - " " fu! Utl_utilCopyExtract(srcFile, outFile, mark) @@ -1463,7 +1463,7 @@ endfu " ] -" BEGIN OF DEFINITION OF STANDARD UTL `DRIVERS' " id=utl_drivers [ +" BEGIN OF DEFINITION OF STANDARD UTL `DRIVERS' " id=utl_drivers [ "------------------------------------------------------------------------------- " Retrieve a resource from the web using the wget network retriever. @@ -1471,9 +1471,9 @@ endfu " be used via :let g:utl_cfg_hdl_scm_http="call Utl_if_hdl_scm_http__wget('%u')". " See also #r=utl_cfg_hdl_scm_http__wget " -" Arg: url - URL to be downloaded -" Ret: global Vim var g:utl__hdl_scm_ret_list set, containing one element: -" the name of a temporary file where wget downloaded into. +" Arg: url - URL to be downloaded +" Ret: global Vim var g:utl__hdl_scm_ret_list set, containing one element: +" the name of a temporary file where wget downloaded into. " " Setup: See " @@ -1490,21 +1490,21 @@ fu! Utl_if_hdl_scm_http__wget(url) " wget --save-headers -> Content-Type: text/html) let suffix = fnamemodify( UtlUri_path(a:url), ":e") if suffix == '' - let suffix = 'html' + let suffix = 'html' endif let tmpFile = Utl_utilBack2FwdSlashes( tempname() ) .'.'.suffix call Utl_trace("- tmpFile name with best guess suffix: ".tmpFile) if ! executable('wget') - call Utl_trace("- Vim variable g:utl_cfg_hdl_scm_mail does not exist") - echohl WarningMsg - let v:errmsg="No executable `wget' found." - call input( v:errmsg . " Entering Setup now. ") - echohl None - Utl openLink config:#r=utl_if_hdl_scm_http_wget_setup split - call Utl_trace("- end execution of Utl_AddressScheme_mail",1,-1) - return + call Utl_trace("- Vim variable g:utl_cfg_hdl_scm_mail does not exist") + echohl WarningMsg + let v:errmsg="No executable `wget' found." + call input( v:errmsg . " Entering Setup now. ") + echohl None + Utl openLink config:#r=utl_if_hdl_scm_http_wget_setup split + call Utl_trace("- end execution of Utl_AddressScheme_mail",1,-1) + return endif let cmd = '!wget '.a:url.' -O '.tmpFile @@ -1521,26 +1521,26 @@ endfu " be used via :let g:utl_cfg_hdl_scm_mail="call Utl_if_hdl_scm_mail__outlook('%a', " '%p','%d','%f','%s')". See also #r=utl_cfg_hdl_scm_mail__outlook " -" Args: ... -" Ret: - +" Args: ... +" Ret: - " " Setup: See fu! Utl_if_hdl_scm_mail__outlook(authority, path, date, from, subject) call Utl_trace("- start Utl_if_hdl_scm_mail__outlook(".a:authority.",".a:path.",".a:date.",".a:from.",".a:subject.")",1,1) if ! exists('g:utl__file_if_hdl_scm__outlook') - let g:utl__file_if_hdl_scm__outlook = fnamemodify(g:utl__file, ":h") . '/../utl_if_hdl_scm__outlook.vbs' - call Utl_trace("- configure interface handler variable for Outlook g:utl__file_if_hdl_scm__outlook=") - call Utl_trace(" ".g:utl__file_if_hdl_scm__outlook) + let g:utl__file_if_hdl_scm__outlook = fnamemodify(g:utl__file, ":h") . '/../utl_if_hdl_scm__outlook.vbs' + call Utl_trace("- configure interface handler variable for Outlook g:utl__file_if_hdl_scm__outlook=") + call Utl_trace(" ".g:utl__file_if_hdl_scm__outlook) endif if ! filereadable(g:utl__file_if_hdl_scm__outlook) - echohl WarningMsg - let v:errmsg="No Outlook interface found." - call input( v:errmsg . " Entering Setup now. ") - echohl None - Utl openLink config:#r=Utl_if_hdl_scm_mail__outlook_setup split - call Utl_trace("- end Utl_if_hdl_scm_mail__outlook()",1,-1) - return + echohl WarningMsg + let v:errmsg="No Outlook interface found." + call input( v:errmsg . " Entering Setup now. ") + echohl None + Utl openLink config:#r=Utl_if_hdl_scm_mail__outlook_setup split + call Utl_trace("- end Utl_if_hdl_scm_mail__outlook()",1,-1) + return endif let cmd='!start wscript "'.g:utl__file_if_hdl_scm__outlook .'" "'. a:authority.'" "'.a:path.'" "'.a:date.'" "'.a:from.'" "'.a:subject.'"' call Utl_trace("- executing cmd: `".cmd."'") @@ -1556,10 +1556,10 @@ endfu " Utl_if_hdl_mt_application_pdf_acrobat('%P', '%f')". " See also #r=utl_cfg_hdl_mt_application_pdf_acrobat. " -" Arg: path - file to be displayed in Acrobat (full path) -" fragment - fragment (without #) or empty string if no fragment +" Arg: path - file to be displayed in Acrobat (full path) +" fragment - fragment (without #) or empty string if no fragment " -" Ret: - +" Ret: - " " Setup: See " @@ -1568,28 +1568,28 @@ fu! Utl_if_hdl_mt_application_pdf_acrobat(path,fragment) call Utl_trace("- start Utl_if_hdl_mt_application_pdf_acrobat(".a:path.",".a:fragment.")",1,1) let switches = '' if a:fragment != '' - let ufrag = UtlUri_unescape(a:fragment) - if ufrag =~ '^page=' - let fval = substitute(ufrag, '^page=', '', '') - let switches = '/a page='.fval - else - echohl ErrorMsg - echo "Unsupported fragment `#".ufrag."' Valid only `#page='" - echohl None - return - endif + let ufrag = UtlUri_unescape(a:fragment) + if ufrag =~ '^page=' + let fval = substitute(ufrag, '^page=', '', '') + let switches = '/a page='.fval + else + echohl ErrorMsg + echo "Unsupported fragment `#".ufrag."' Valid only `#page='" + echohl None + return + endif endif if ! exists('g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path') " Entering setup - call Utl_trace("- Vim variable `g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path.' does not exist") - echohl WarningMsg - call input('variable g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path not defined. Entering Setup now. ') - echohl None - Utl openLink config:#r=Utl_if_hdl_mt_application_pdf_acrobat_setup split - call Utl_trace("- end Utl_if_hdl_mt_application_pdf_acrobat() (not successful)",1,-1) - return + call Utl_trace("- Vim variable `g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path.' does not exist") + echohl WarningMsg + call input('variable g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path not defined. Entering Setup now. ') + echohl None + Utl openLink config:#r=Utl_if_hdl_mt_application_pdf_acrobat_setup split + call Utl_trace("- end Utl_if_hdl_mt_application_pdf_acrobat() (not successful)",1,-1) + return endif - " id=ar_switches + " id=ar_switches let cmd = ':silent !start '.g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path.' /a page='.ufrag.' "'.a:path.'"' call Utl_trace("- executing cmd: `".cmd."'") exe cmd @@ -1605,10 +1605,10 @@ endfu " Utl_if_hdl_mt_application_msword__word('%P', '%f')". " See also #r=utl_cfg_hdl_mt_application_msword__word. " -" Arg: path - file to be displayed in Acrobat (full path) -" fragment - fragment (without #) or empty string if no fragment +" Arg: path - file to be displayed in Acrobat (full path) +" fragment - fragment (without #) or empty string if no fragment " -" Ret: - +" Ret: - " " Setup: See " @@ -1617,49 +1617,49 @@ fu! Utl_if_hdl_mt_application_msword__word(path,fragment) call Utl_trace("- start Utl_if_hdl_mt_application_msword__word(".a:path.",".a:fragment.")",1,1) if ! exists('g:utl__file_if_hdl_mt_application_msword__word') - let g:utl__file_if_hdl_mt_application_msword__word = fnamemodify(g:utl__file, ":h") . '/../utl_if_hdl_mt_application_msword__word.vbs' - call Utl_trace("- configure interface handler variable for MS-Word g:utl__file_if_hdl_mt_application_msword__word=") - call Utl_trace(" ".g:utl__file_if_hdl_mt_application_msword__word) + let g:utl__file_if_hdl_mt_application_msword__word = fnamemodify(g:utl__file, ":h") . '/../utl_if_hdl_mt_application_msword__word.vbs' + call Utl_trace("- configure interface handler variable for MS-Word g:utl__file_if_hdl_mt_application_msword__word=") + call Utl_trace(" ".g:utl__file_if_hdl_mt_application_msword__word) endif if ! filereadable(g:utl__file_if_hdl_mt_application_msword__word) - echohl WarningMsg - let v:errmsg="No Word interface found." - call input( v:errmsg . " Entering Setup now. ") - echohl None - Utl openLink config:#r=Utl_if_hdl_mt_application_msword__word_setup split - call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (not successful)",1,-1) - return + echohl WarningMsg + let v:errmsg="No Word interface found." + call input( v:errmsg . " Entering Setup now. ") + echohl None + Utl openLink config:#r=Utl_if_hdl_mt_application_msword__word_setup split + call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (not successful)",1,-1) + return endif if ! exists('g:utl_cfg_hdl_mt_application_msword__word_exe_path') " Entering setup - call Utl_trace("- Vim variable `g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path.' does not exist") - echohl WarningMsg - call input('variable g:utl_cfg_hdl_mt_application_msword__word_exe_path not defined. Entering Setup now. ') - echohl None - Utl openLink config:#r=Utl_if_hdl_mt_application_msword__word_setup split - call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (not successful)",1,-1) - return + call Utl_trace("- Vim variable `g:utl_cfg_hdl_mt_application_pdf_acrobat_exe_path.' does not exist") + echohl WarningMsg + call input('variable g:utl_cfg_hdl_mt_application_msword__word_exe_path not defined. Entering Setup now. ') + echohl None + Utl openLink config:#r=Utl_if_hdl_mt_application_msword__word_setup split + call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (not successful)",1,-1) + return endif let cmd = 'silent !start '.g:utl_cfg_hdl_mt_application_msword__word_exe_path.' "'.a:path.'"' call Utl_trace("- cmd to open document: `".cmd."'") exe cmd if a:fragment == '' - call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (successful, no fragment)",1,-1) - return + call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (successful, no fragment)",1,-1) + return endif " (CR044:frag) let ufrag = UtlUri_unescape(a:fragment) if ufrag =~ '^tn=' " text next / text previous - let fval = substitute(ufrag, '^tn=', '', '') + let fval = substitute(ufrag, '^tn=', '', '') elseif ufrag =~ '[a-z]\+=' - echohl ErrorMsg - echo 'Unsupported fragment key `'.substitute(ufrag, '\c^\([a-z]\+\).*', '\1=', '')."'. Valid only: `tn='" - echohl None - call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (not successful)",1,-1) - return + echohl ErrorMsg + echo 'Unsupported fragment key `'.substitute(ufrag, '\c^\([a-z]\+\).*', '\1=', '')."'. Valid only: `tn='" + echohl None + call Utl_trace("- end Utl_if_hdl_mt_application_msword__word() (not successful)",1,-1) + return else - let fval=ufrag " naked fragment same as tn= + let fval=ufrag " naked fragment same as tn= endif let cmd='silent !start wscript "'.g:utl__file_if_hdl_mt_application_msword__word .'" "'. a:path.'" "'.fval.'"' call Utl_trace("- cmd to address fragment: `".cmd."'") @@ -1675,7 +1675,7 @@ finish ' file: utl_if_hdl_scm__outlook.vbs ' synopsis: utl_if_hdl_scm__outlook.vbs "" "Inbox" "08.02.2008 13:31" "" "" ' collaboration: - Used by utl.vim when accessing "mail:" URLs using MS-Outlook. -' - Outlook must be running +' - Outlook must be running ' hist: ' 2008-02-29/Stb: Version for Utl.vim v3.0a Option Explicit @@ -1732,7 +1732,7 @@ Dim sFilter Dim dateMin, dateMax dateMin = CStr( DateAdd("n", -2, a_date) ) dateMax = CStr( DateAdd("n", 2, a_date) ) -' cut seconds added by DateAdd +' cut seconds added by DateAdd dateMin = Left(dateMin, Len(dateMin) -3 ) dateMax = Left(dateMax, Len(dateMax) -3 ) @@ -1743,9 +1743,9 @@ dateMax = Left(dateMax, Len(dateMax) -3 ) ' by date. ' ' -' [id=received] Change to actual column name in your Outlook +' [id=received] Change to actual column name in your Outlook ' +---------------------------------+ -' v v +' v v sFilter = "[Erhalten] > '" + dateMin + "' AND [Erhalten] < '" + dateMax + "'" Set item = folder.Items.find(sFilter) @@ -1755,9 +1755,9 @@ item.Display === FILE_WORD_VBS {{{ ' usage: utl_if_hdl_mt_application_msword__word.vbs <.doc file> ' description: Position cursor in Word document <.doc file> at string -' +' ' Collaboration: Word being started or running. Document subject to fragment -' addressing active or being opened and activated. +' addressing active or being opened and activated. ' hist: ' 2008-03-20/Stb: Version for Utl.vim v3.0a @@ -1776,10 +1776,10 @@ maxTries = 50 Do While countTries < maxTries countTries = countTries+1 On Error Resume Next - Set o = GetObject(, "Word.Application") + Set o = GetObject(, "Word.Application") If Err Then - WScript.Sleep 200 - Err.Clear + WScript.Sleep 200 + Err.Clear Else Exit Do End If