*www.txt* Toolbox to open & search URLs from vim

Official repository: https://github.com/waiting-for-dev/vim-www

==============================================================================
CONTENTS                                   *vim-www* *www.vim* *www-contents*

1.  Usage .............................. |www-usage|
  1.1 Favorites and arbitrary URLs ..... |www-favorites|
  1.2 Search engines ................... |www-search_engines|
  1.3 Shortcut search engines .......... |www-shorcut_search_engines|
  1.4 Sessions ......................... |www-sessions|
2.  Defaults ........................... |www-defaults|
3.  Commands ........................... |www-commands|
4.  Mappings ........................... |www-mappings|
5.  Configuration ...................... |www-configuration|
6.  Bugs ............................... |www-bugs|
7.  Contributing ....................... |www-contributing|
8.  Version ............................ |www-version|
9.  License ............................ |www-license|
==============================================================================
USAGE                                                               *www-usage*

vim-www allows launching a web browser from vim to open arbitrary URLs,
defined favorites and search engine results.

The web browser to be used is detected automatically, but it can be manually
set through |g:www_launch_browser_command|, optionally using "{{URL}}}" as placeholder
for the actual URL. E.g.:

    let g:www_launch_browser_command = "iceweasel {{URL}} &"

In the same way, an alternative CLI browser can be set through
|g:www_launch_cli_browser_command|. In order to work,
[vim-dispatch](https://github.com/tpope/vim-dispatch) add-on must be
installed. Its purpose is to open a web, for example, in a
[tmux](https://tmux.github.io/) pane, or in a virtual terminal if
[neovim](https://github.com/neovim/neovim) and
[vim-dispatch-neovim](https://github.com/radenling/vim-dispatch-neovim) are
being used.

FAVORITES AND ARBITRARY URLS                                    *www-favorites*

|:Wopen| opens any given URL. E.g.:

    :Wopen http://vim.org

But typing and remembering full URLs is annoying, so custom favorites can be
defined in |g:www_urls| dictionary.

So, having in |vimrc|,

    let g:www_urls = {
      \ 'vim' : 'http://www.vim.org',
      \ }

following command does the same than previous one:

    :Wopen vim

Also, in normal mode, |<leader>wo| launches the browser using |WORD| under
cursor as URL. In visual mode it does the same but taking current text
selection as URL.

|:Wcopen| command and |<leader>wco| mappings do the same but using the CLI
browser.

SEARCH ENGINES                                          *www-search_engines*

|:Wsearch| queries a search engine and opens the corresponding results page:

E.g.:

    :Wsearch google how to learn vim

Previous command opens the resulting page of searching `how to learn vim`
in google.

Following search engines are provided by default:

* bitbucket
* devdocs
* duckduckgo
* google
* github
* stackoverflow
* wikipedia

More search engines can be added through |g:www_engines| dictionary. Query is
appended at the end of given URL.  E.g.:

    let g:www_engines = {
      \ 'youtube' : 'https://www.youtube.com/results?search_query=',
      \ }

In normal mode, |<leader>ws| searches |WORD| under cursor, while the same
mapping in visual mode searches current visual selection. In both cases, the
user is prompted to choose which search engine should be used. If none is
given, duckduckgo is used, but this behaviour can be changed setting
|g:www_default_search_engine| variable. E.g.:

    let g:www_default_search_engine = 'google'

|:Wcsearch| command and |<leader>wcs| mappings do the same but using the CLI
browser.

SHORTCUT SEARCH ENGINES                               *www-shorcut_search_engines*

Convenient shortcuts for commonly used search engines can be defined in
|g:www_shortcut_engines| dictionary. Having in |vimrc|:

    let g:www_engines = {
      \ 'ruby' : 'http://ruby-doc.com/search.html?q=',
    \}

    let g:www_shortcut_engines = {
      \ 'ruby': ['Docruby', '<leader>dr', 'Doccliruby', '<leader>dcr']
    \}

automatically adds :Docruby / :Doccliruby commands, and <leader>dr /
<leader>dcr mappings that work like |:Wsearch| / |:Wcsearch| and |<leader>ws|
/ |<leader>wcs| but using ruby straight away as search engine.

Remember that user defined commands must begin with an uppercase letter.

This is very convenient to use as a quick way to consult API documentation.

SESSIONS                                                       *www-sessions*

Arbitrary URLs and favorites can be grouped together under a name in
|g:www_sessions| dictionary and opened at once using |:Wsession| command.

Having in |vimrc|:

    let g:www_urls = {
      \ 'vim' : 'http://www.vim.org',
      \ }

    let g:www_sessions = {
      \ 'dev' : ['vim', 'http://stackoverflow.com'],
      \ }

Running:

    :Wsession vim

would open `http://www.vim.org` and `http://stackoverflow.com` at once.

|:Wcsession| command does the same but using the CLI browser.
==============================================================================
DEFAULTS                                                         *www-defaults*

Following search engines are present by default:

* bitbucket 
* devdocs
* duckduckgo,
* google
* github
* stackoverflow
* wikipedia.

Default search engine is duckduckgo, but it can be changed in
|g:www_default_search_engine|.
==============================================================================
COMMANDS                                                         *www-commands*

                                                                      *:Wopen*

:Wopen {url-or-favorite} [{url-or-favorite}...] Opens given URLs or favorites
in the web browser. Favorites should be defined in |g:www_urls| dictionary.
When one argument is not a favorite nor contains "://" in it, "http://" will
be prepended.

                                                                      *:Wcopen*

:Wcopen {url-or-favorite} [{url-or-favorite}...] Same than |:Wopen| but using
vim-dispatch and configured |g:www_launch_cli_browser_command| as browser.

                                                                      *:Wsearch*

:Wsearch {search-engine} {query} [{query}] Opens the web browser with the
results page of searching {query} in given {search-engine}. Search engines are
defined in |g:www_engines|. All arguments after {search-engine} are
interpreted as query words.

                                                                      *:Wcsearch*

:Wcsearch {search-engine} {query} [{query}] Same than |:Wsearch| but using
vim-dispatch and configured |g:www_launch_cli_browser_command| as browser.


                                                                     :Wsession

:Wsession {sessionname} [{sessionname}...] Opens one or more URL sessions.
Sessions should be defined at |g:www_sessions|.

                                                                     :Wcsession

:Wcsession {sessionname} [{sessionname}...] Same than |:Wcsession| but using
vim-dispatch and configured |g:www_launch_cli_browser_command| as browser.
==============================================================================
MAPPINGS                                                         *www-mappings*

                                                                  *<leader>wo*

<leader>wo In normal mode opens |WORD| under the cursor as a URL
or favorite. In visual mode, does the same with current text selection.

                                                                  *<leader>wco*

<leader>wco Same than |<leader>wo| but using vim-dispatch and configured
|g:www_launch_cli_browser_command| as browser.


                                                                  *<leader>ws*

<leader>ws In normal mode, it opens the browser with the page containing the
result of searching |WORD| under the cursor in a prompted search engine. In
visual mode, does the same with current text selection. If the prompt is left
blank, default search engine is used. Look at |g:www_default_search_engine| for
information about how to configure default search engine.

                                                                  *<leader>wcs*

<leader>wcs Same than |<leader>ws| but using vim-dispatch and configured
|g:www_launch_cli_browser_command| as browser.

==============================================================================
CONFIGURATION                                               *www-configuration*

                                                                  *g:www_urls*

A dictionary that contains user defined favorite URLs. Keys are favorite names
while values are actual URLs. E.g.:

    let g:www_urls = {
      \ 'vim': 'http://vim.org',
    \ }

                                                                  *g:www_engines*

A dictionary that contains user defined search engines. Keys are search engine
names, while values are the URL to use. Query will be appended to that URL,
unless "{{QUERY}}" is present. In such case it will be used as placeholder for
the query.

    let g:www_engines = {
      \ 'ruby' : 'http://ruby-doc.com/search.html?q=',
      \ 'youtube' : 'https://youtube.com/results?search_query={{QUERY}}',
    \ }

                                                              *g:www_sessions*

A dictionary that contains your sessions. Keys are session names and values an
array of URLs or favorites defined in |g:www_urls|. E.g.:

    let g:www_sessions = {
      \ 'vim': ['vim', 'https://stackoverflow.com']
    \ }

                                                 *g:www_default_search_engine*

Default search engine to use when user is prompted to select a search engine.
The value must be present as key in |g:www_engines|. If none is set, default
search engine is duckduckgo.

                                                *g:www_launch_browser_command*

The command that will be used to launch the browser. If it is not set ,
|vim-www| will try to make the best guess. Optionally, use "{{URL}}" placeholder to
tell where the actual URL should be. E.g.: >

    let g:www_launch_browser_command = "icewasel {{URL}} &"

                                            *g:www_launch_cli_browser_command*

The command that will be passed to vim-dispatch to launch a CLI web browser.
Optionally, use "{{URL}}" as placeholder for the actual URL. E.g.:

    let g:www_launch_cli_browser_command = "elinks"

                                                              *g:www_shortcut_engines*

A dictionary that contains convenient shortcuts for commonly used search
engines.

Keys should be keys present in |g:www_engines| or one of defaults search
engines.

Value is an array of as much as four items.  First item is the name of the
command to be used to query that search engine (like |:Wsearch| but without the
need of first parameter). Second one is the mapping to search in that engine
WORD under the cursor in normal mode or current selection in visual mode (like
|<leader>wcs| but without prompting the user for the search engine). Third and
fourth items are, respectively, the command and mapping to do the same but
using the CLI web browser. All four items are optional, and, in order no skip
one of them, an empty string should be set.

E.g.:

    let g:www_shortcut_engines = {
      \ 'google': ['Google', '<leader>g', 'Googlecli', '<leader>cg']
    \}

automatically adds :Google / :Googlecli commands, and <leader>g /
<leader>cg mappings.

Remember that user defined commands must begin with an uppercase letter.


                                                              *g:www_map_keys*

This variable should be set to 0 in order not to use |www-mappings|.
==============================================================================
BUGS                                                                 *www-bugs*

Open a bug in https://github.com/waiting-for-dev/vim-www/issues
==============================================================================
CONTRIBUTING                                                 *www-contributing*

1. Fork the project ( http://github.com/waiting-for-dev/vim-www/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request

==============================================================================
VERSION                                                           *www-version*

|vim-www| follows Semantic Versioning system 2.0 (http://semver.org/). Current
version is 1.1.0.
==============================================================================
LICENSE                                                           *www-license*

The MIT Licence
http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2014 Marc Busqué Pérez

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

  vim-www vim:tw=78:ts=8:ft=help:norl:
