textobj-quote.txt

*textobj-quote.txt*	Support typographic quote characters.

==============================================================================
CONTENTS					*textobj-quote-contents*

	INTRODUCTION			|textobj-quote-introduction|
	USAGE				|textobj-quote-usage|
		INITIALIZATION		|textobj-quote-initialization|
		MOTION COMMANDS		|textobj-quote-motion-commands|
		EDUCATE			|textobj-quote-educate|
		MATCHIT			|textobj-quote-matchit|
		REPLACE			|textobj-quote-replace|
		SURROUND		|textobj-quote-surround|
		VIM-SURROUND		|textobj-quote-vim-surround|
	CONFIGURATION			|textobj-quote-configuration|
		EDUCATE CONFIGURATION	|textobj-quote-config-educate|
		MATCHIT CONFIGURATION	|textobj-quote-config-matchit|
		MOTION CONFIGURATION	|textobj-quote-config-motion|
	TIPS				|textobj-quote-tips|
		STRAIGHT QUOTES		|textobj-quote-straight-quotes|
		DIGRAPHS		|textobj-quote-digraphs|
		INTERNATIONAL USE	|textobj-quote-international-use|
		SPELL CHECKING		|textobj-quote-spell-checking|
	SEE ALSO			|textobj-quote-see-also|
	CONTRIBUTING			|textobj-quote-contributing|
	LICENSE				|textobj-quote-license|


==============================================================================
INTRODUCTION					*textobj-quote-introduction*

While Vim is renowned for its text manipulation capabilities, it nevertheless
retains a bias towards ASCII that stretches back to vi’s roots on Unix. This
can limit Vim’s appeal for those who prefer typographic characters like “curly
quotes” over ASCII "straight quotes" for prose and documentation. By extending
Vim’s |text-objects|, this plugin offers full and configurable support for
typographic quote characters.

Note: this plugin requires Kana Natsuno’s vim-textobj-user. Be sure to install
that if you don’t already have it.

https://github.com/kana/vim-textobj-user

==============================================================================
USAGE						*textobj-quote-usage*

------------------------------------------------------------------------------
INITIALIZATION					*textobj-quote-initialization*

You must explicitly initialize the plugin. That is, even after you install it,
textobj-quote does nothing by default when you start Vim. This makes sense
because you will usually write code with Vim, and typographic quotes rarely
appear in code.

You can initialize the plugin in several ways, depending on your needs: >
	" During an editing session, enter this to initialize the plugin:
	call textobj#quote#init()

	" Tell Vim when to initialize the plugin in your .vimrc:
	" - globally (most people wont’t want this)
	call textobj#quote#init()

	" - by |filetype| (requires 'filetype plugin on'):
	augroup textobj_quote
		autocmd!
		autocmd FileType markdown call textobj#quote#init()
		autocmd FileType textile call textobj#quote#init()
		autocmd FileType text call textobj#quote#init({'educate': 0})
	augroup END
<

The last |autocmd| statement initializes the plugin for buffers of text file
type, but disables the ‘educate’ feature. More on that below, in the section
on configuration (|textobj-quote-config-educate|).

------------------------------------------------------------------------------
MOTION COMMANDS					*textobj-quote-motion-commands*

The plugin provides two text objects that work with Vim’s built-in |operator|
commands. The text objects are q, for text within double typographic quotes,
and Q, for text within single typographic quotes.

For example, with the |c| change operator: >
	caq - change around “double” quotes - includes quote chars
	ciq - change inside “double” quotes - excludes quote chars
	caQ - change around ‘single’ quotes - includes quote chars
	ciQ - change inside ‘single’ quotes - excludes quote chars

	" The asterisk denotes the cursor’s position.
	“foo*bar”  " ciq -> “*”
	“foo*bar”  " caq -> *
<

In addition to |c| for change, the plugin supports |v| for visual selection,
|d| for deletion, |y| for yanking to clipboard, etc. Note that |count| isn’t
supported (due to limitations of the underlying vim-textobj-user plugin), but
repeat with |.| should work.

The plugin’s motion command is smart enough to distinguish between an
apostrophe and single closing quote, even though both are represented by the
same glyph. For example, try out viQ on the following sentence:

	‘Really, I’d rather not relive the ’70s,’ said zombie Elvis.

------------------------------------------------------------------------------
EDUCATE						*textobj-quote-educate*

After the plugin is initialized your straight quote key presses (" or ') will
be dynamically transformed into the appropriate typographic quote characters.

For example, consider the following sentence:

	"It's Dr. Evil. I didn't spend six years in Evil Medical
	School to be called 'mister,' thank you very much."

If textobj-quote is not initialized, you get straight quotes and apostrophes.

Buf if textobj-quote is initialized, the straight quotes are transformed into
the typographic equivalent as you type:

	“It’s Dr. Evil. I didn’t spend six years in Evil Medical
	School to be called ‘mister,’ thank you very much.”

------------------------------------------------------------------------------
MATCHIT						*textobj-quote-matchit*

The plugin extends |matchit| to recognize typographic quotes. This enables
you to jump from one end of a quote to the other with '%' (|matchit-%|).

------------------------------------------------------------------------------
REPLACE						*textobj-quote-replace*

You can replace straight quotes in existing text with curly quotes, and vice
versa. Add key mappings of your choice to your .vimrc: >
	map <silent> <leader>qc <Plug>ReplaceWithCurly
	map <silent> <leader>qs <Plug>ReplaceWithStraight
<

This feature supports both Normal and Visual modes.

To transform all quotes in a document, use Visual mode to select all the text
in the document.

------------------------------------------------------------------------------
SURROUND					*textobj-quote-surround*

The plugin provides an optional surround feature. Add to your .vimrc key
mappings of your choice: >
	" NOTE: these mappings clash with the vim-surround plugin!
	map <silent> Sq <Plug>SurroundWithDouble
	map <silent> SQ <Plug>SurroundWithSingle
<

Then you can use motion commands to surround text with typographic quotes. The
asterisk denotes the cursor’s position. >
	visSq - My senten*ce. => “My sentence.”
	visSQ - My senten*ce. => ‘My sentence.’
<

------------------------------------------------------------------------------
VIM-SURROUND					*textobj-quote-vim-surround*

If you already use Tim Pope’s vim-surround plugin, your text object key
mappings should be available. For example, >
	cs'q - 'Hello W*orld' => “Hello World”
	cs"q - "Hello W*orld" => “Hello World”
	cs(q - (Hello W*orld) => “Hello World”
	cs(Q - (Hello W*orld) => ‘Hello World’
<

==============================================================================
CONFIGURATION					*textobj-quote-configuration*

The educate, matchit, and motion features of textobj-quote have options that
can be configured in initialization files or changed on the fly. In each
section below, we will layout the defaults and then explain the different ways
to change those defaults.

------------------------------------------------------------------------------
EDUCATE CONFIGURATION				*textobj-quote-config-educate*

By default the educate feature is on after you initialize the plugin. You can
globally set the default to be the opposite, you can set or unset the educate
feature by filetype, or you can change it on the fly.

First, if you place one of the following in an initialization file, you
explicitly set the default behavior for educate: >
	" 0 = disable: educate off by default if textobj#quote#init() is called
	let g:textobj#quote#educate = 0
	" 1 = enable: educate on by default if textobj#quote#init() is called
	let g:textobj#quote#educate = 1
<

If one of those is in your .vimrc and you call textobj#quote#init(), the
educate feature will be on or off according to the explicit default. If you
don’t set this variable explicitly, textobj-quote assumes you want the normal
default, and educate is turned on at initialization. (Note that the variable
by itself does not turn educate on or off. The user still must call the
textobj#quote#init function.)

You can also pass a parameter to textobj#quote#init() to customize its
behavior: >
	autocmd FileType markdown call textobj#quote#init({'educate': 0})
	autocmd FileType textile call textobj#quote#init()
<

Assuming the normal default, those settings turn on the educate feature for
textile files but not markdown ones.

You can also do the reverse: turn off educate by default, but turn it on for
individual filetypes: >
	let g:textobj#quote#educate = 0
	autocmd FileType textile call textobj#quote#init({'educate': 1)
<

Finally, you can toggle the educate feature on the fly with the following
commands: >
	Educate
	NoEducate
	ToggleEducate
<

These commands can be used during an editing session if you need to switch
between modes. But they can also be used in autocommands. For example, imagine
that you want typographic quotes in markdown files, but not within code
sections of a markdown document. The following handles that automatically: >
	function! IsMarkdownCode()
		let line = line(".")
		let synstack = synstack(line, 1)
		let syn = empty(synstack) ? "" : synIDattr(synstack[0], "name")
		let is_markdown_code = syn =~# 'markdown\(Code\(Block\)\?\|Highlight*\)'
		return is_markdown_code
	endfunction

	augroup textobj_quote
		autocmd!
		autocmd FileType markdown call textobj#quote#init()
		autocmd CursorMoved,CursorMovedI,WinEnter *.md
			\ if IsMarkdownCode() |
			\ 	NoEducate |
			\ else |
			\ 	Educate |
			\ endif
	augroup END
<

------------------------------------------------------------------------------
MATCHIT CONFIGURATION				*textobj-quote-config-matchit*

By default, the plugin provides |matchit| support, as described above in
|textobj-quote-matchit|. However, you can turn this feature off globally, by
filetype, or as a one off, just as with the educate feature. Since we have
gone over the possibilities in detail for educate, we can be briefer here: >
	" Turn matchit off by default.
	let g:textobj#quote#matchit = 0 
	" Turn it on in this initialization.
	call g:textobj#quote#init({'matchit': 1})
	" Turn it on for all markdown files.
	autocmd FileType markdown call textobj#quote#init({'matchit': 1})
<

------------------------------------------------------------------------------
MOTION CONFIGURATION			*textobj-quote-config-motion*

The defaults for the typographic quote motions can also be changed in the same
ways. Here are some examples: >
	" You can explicitly set the choices to the defaults.
	let g:textobj#quote#doubleMotion = 'q'
	let g:textobj#quote#singleMotion = 'Q'
	" You can reverse the defaults if you prefer, though why would you?
	let g:textobj#quote#doubleMotion = 'Q'
	let g:textobj#quote#singleMotion = 'q'
	" You can use the keyboard characters as defaults.
	let g:textobj#quote#doubleMotion = '"'
	let g:textobj#quote#singleMotion = "'"
<

==============================================================================
TIPS						*textobj-quote-tips*

The following sections discuss less common circumstances or requirements and
how to handle them.

------------------------------------------------------------------------------
STRAIGHT QUOTES					*textobj-quote-straight-quotes*

In some cases, straight (ASCII) quotes are needed in a document that mostly
uses typographic quotes. For example, in a book about programming:

	“print "Hello World!"” is a simple program you can write in Python.

To insert a straight quote while educating, enter Ctrl-V (mnemonic is
“verbatim”) before the quote key:

	Ctrl-V followed by " - straight double quote
	Ctrl-V followed by ' - straight single quote

For more details, see |c_CTRL-V|. Also note that for units of measurement
you’ll want to use the prime symbol(s) rather than straight quotes, as in:

	Standing at 7′3″ (2.21 m), Hasheem Thabeet of the Oklahoma City
	Thunder is the tallest player in the NBA.

See below if you are unsure of how to enter prime symbols in Vim.

------------------------------------------------------------------------------
DIGRAPHS					*textobj-quote-digraphs*

Sometimes you must enter special characters (like typographic quotes)
manually, such as in a search expression. You can do so through Vim’s digraphs
or via your operating system’s keyboard shortcuts.

| Glyph | Vim Digraph | OS X               | Description
| ----- | ----------- | ------------------ | ----------------------------
| ‘     | '6          | Opt-]              | left single quote
| ’     | '9          | Shift-Opt-]        | right single quote
| “     | "6          | Opt-[              | left double quote
| ”     | "9          | Shift-Opt-[        | right double quote
| ‚     | .9          |                    | single low-9 quote
| „     | :9          | Shift-Opt-w        | double low-9 quote
| ‹     | 1<          | Opt-\              | left pointing single quote
| ›     | 1>          | Shift-Opt-\        | right pointing single quote
| «     | <<          | Opt-\              | left pointing double quote
| »     | >>          | Shift-Opt-\        | right pointing double quote
| ′     | 1'          |                    | single prime
| ″     | 2'          |                    | double prime
| –     | -N          | Opt-hyphen         | en dash
| —     | -M          | Shift-Opt-hyphen   | em dash
| …     | ..          | Opt-;              | horizontal ellipsis
|       | NS          |                    | non-breaking space
| ï     | i:          | Opt-U i            | lowercase i, umlaut
| æ     | ae          | Opt-'              | lowercase ae

To enter the Vim digraphs, you need to precede them with Ctrl-K. For example,
Ctrl-K followed by "6 will enter ”. For more information, see |digraphs| and
|c_CTRL-K|.

------------------------------------------------------------------------------
INTERNATIONAL USE				*textobj-quote-international-use*

Many international keyboards feature keys to allow you to input typographic
quote characters directly. In such cases, you won’t need to change the
behavior of the straight quote keys.

But if you do, you can override the defaults. For example, those users editing
most of their prose in German could change those defaults to: >
	let g:textobj#quote#doubleDefault = '„“'     " „doppel“
	let g:textobj#quote#singleDefault = '‚‘'     " ‚einzel‘
<

Or on a file type initialization... >
	augroup textobj_quote
		autocmd!
		autocmd FileType markdown call textobj#quote#init({ 'double':'„“', 'single':'‚‘' })
		...
	augroup END
<

Or in a key mapping... >
	nnoremap <silent> <leader>qd :call textobj#quote#init({ 'double':'„“', 'single':'‚‘' })<cr>
<

==============================================================================
SPELL CHECKING					*textobj-quote-spell-checking*

Vim’s spell checking may not support words with typographical apostrophes. For
example, Vim may consider “isn’t” to be misspelled, even though it isn’t.
There are several ways to address this, but here is one that works well. (The
example uses English spelling files, but you can substitute any language.)

First, you need to get spelling files for vim to build a dictionary. (See
|aff-dic-format|.) For example, you can find some at the following link.

	https://extensions.libreoffice.org/en/extensions/show/english-dictionaries

Copy or unpack those files to ~/.vim/spell and run this perl one-liner: >
	perl -i.bak -ne "print; print if s/'/’/g" en_US.dic
<

Then open Vim and do the following: >
	:mkspell en en_US
	" Use mkspell! if you already have a dictionary with that name.
	" See |mkspell| for further details of this command.
<

This method creates two entries for all words with apostrophes in them: one
with a straight apostrophe and one with a typographic apostrophe. Thus, Vim
will consider both “isn't” and “isn’t” to be correctly spelled. Which is great
because they both are! Now you can type one version in code comments and
another in an email, and Vim won’t bother you.

==============================================================================
SEE ALSO					*textobj-quote-see-also*

The following plugins have some overlap with textobj-quote:

	- vim-sandwich: operator and textobject plugins to add/delete/replace
	  surroundings of a sandwiched textobject, like (foo), "bar", and
	  “buzz”.
	  https://github.com/machakann/vim-sandwich
	- vim-surround: quoting/parenthesizing made simple
	  https://github.com/tpope/vim-surround

==============================================================================
CONTRIBUTING					*textobj-quote-contributing*

If you’ve spotted a problem or have an idea to improve this plugin, please
post on the project’s GitHub issue page.

	https://github.com/preservim/vim-textobj-quote/issues

We would especially like to integrate this plugin better with existing
surround plugins.

==============================================================================
LICENSE						*textobj-quote-license*

The MIT License (MIT)

Copyright (c) 2013-2020 Reed Esau

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:tw=78:ts=8:noet:ft=help:norl