diff options
Diffstat (limited to 'elpa/evil-1.15.0/doc/source')
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/_ext/elisp.py | 309 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/conf.py | 90 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/extension.rst | 146 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/faq.rst | 118 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/hooks.rst | 16 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/index.rst | 21 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/indices.rst | 6 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/internals.rst | 36 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/keymaps.rst | 145 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/license.rst | 447 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/overview.rst | 117 | ||||
| -rw-r--r-- | elpa/evil-1.15.0/doc/source/settings.rst | 195 |
12 files changed, 1646 insertions, 0 deletions
diff --git a/elpa/evil-1.15.0/doc/source/_ext/elisp.py b/elpa/evil-1.15.0/doc/source/_ext/elisp.py new file mode 100644 index 0000000..924d026 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/_ext/elisp.py @@ -0,0 +1,309 @@ +import re +from os import path +import json + +from docutils import nodes +from docutils.parsers.rst import Directive + +from sphinx import addnodes +from sphinx.domains import Domain, ObjType, Index +from sphinx.domains.std import StandardDomain +from sphinx.directives import ObjectDescription +from sphinx.roles import XRefRole +from sphinx.util.docfields import Field +from sphinx.util.nodes import make_refnode + + +with open(path.join(path.dirname(__file__), '..', '..', 'docstringdb.json')) as f: + DATA = json.load(f) + + +re_evilcode = re.compile(r"`(evil-[^']*)'") +re_code = re.compile(r"`([^:][^ ']*)'") +re_kwd = re.compile(r"`(:[^']*)'") +re_item = re.compile(r"([^\n])\n- ") +re_sexp = re.compile(r"\([A-Z \-\.'`\[\]]+\)|[A-Z\-]+") +re_capitals = re.compile(r"[A-Z\-]+") +re_nonspace = re.compile(r"[^ ]") +re_signature = re.compile(r'\(fn (.*)\)') +re_keymap_or_kbd = re.compile(r"\\[\[<]([^\]>]*)[\]>]") + +emphasis = [ + 'thing-at-point', +] + +def emacs_is_local(var): + return DATA[var]['local'] + +def emacs_default_value(var): + default = DATA[var]['default'] + tp = DATA[var]['default-type'] + if tp == 'string': + rep = repr(default)[1:-1] + return f'"{rep}"' + return str(default) + +def process_docstring(docstring, capitals=None): + # Remove explicit signature + docstring = re_signature.sub('', docstring) + + # Add code blocks to indented sections + def blockified_lines(lines): + in_block = False + for line in lines: + try: + indented = next(re_nonspace.finditer(line)).start(0) > 3 + except StopIteration: + indented = None + if indented is True and not in_block: + yield '.. code-block:: elisp' + yield '' + in_block = True + elif indented is False: + in_block = False + yield line + docstring = '\n'.join(blockified_lines(docstring.split('\n'))) + + # Substitute `evil-alpha' with :elisp:ref:`evil-alpha` + docstring = re_evilcode.sub(r':elisp:ref:`\1`', docstring) + + # Substitute `alpha' with ``alpha`` + docstring = re_code.sub(r'``\1``', docstring) + + # Substitute `:alpha' with ``alpha`` + docstring = re_kwd.sub(r'``\1``', docstring) + + # Translate key bindings + keymap = None + def substitute_binding(match): + nonlocal keymap + if match.group(0)[1] == '<': + keymap = match.group(1) + return '' + if keymap is None: + print(docstring) + assert False + return '???' + key = DATA[keymap]['keymap-inv'][match.group(1)] + return f':kbd:`{key}`' + docstring = re_keymap_or_kbd.sub(substitute_binding, docstring) + + # Add empty line between list items + docstring = re_item.sub(r'\1\n\n- ', docstring) + + if capitals is None: + capitals = [] + else: + capitals = list(capitals) + + # Find things that look like sexps + def substitute_sexp(match): + s = match.group(0) + if re_capitals.match(s): + if s in capitals: + return f'*{s}*' + return s + else: + capitals.extend(re_capitals.findall(s)) + return f'``{s}``' + docstring = re_sexp.sub(substitute_sexp, docstring) + + # Italicize some words + for s in emphasis: + docstring = docstring.replace(s, f'*{s}*') + + return docstring + +def emacs_variable_docstring(var): + docstring = DATA[var]['var-docstring'] + return process_docstring(docstring) + +def emacs_function_docstring(var): + docstring = DATA[var]['fn-docstring'] + return process_docstring(docstring, capitals=emacs_argnames(var)) + +def emacs_argnames(var): + arglist = emacs_arglist(var) + return re_capitals.findall(arglist) + +def emacs_arglist(var): + docstring = DATA[var]['fn-docstring'] + match = re_signature.search(docstring) + if match: + return match.group(1) + + arglist = [arg.upper() for arg in DATA[var]['arglist']] + state = None + ret = '' + for arg in arglist: + if arg in ('&REST', '&OPTIONAL'): + if state == '&OPTIONAL': + ret += ']' + state = arg + ret += ' [' + continue + ret += ('' if state in ('&REST', '&OPTIONAL') else ' ') + arg + if state == '&OPTIONAL': + state += '-CONT' + if state is not None and state.startswith('&OPTIONAL'): + ret += ']' + if state == '&REST': + ret += '...]' + return ret + + +class AbstractElisp(ObjectDescription): + + def add_target_and_index(self, name, sig, signode): + anchor = f'elispobj-{sig}' + signode['ids'].append(anchor) + + objs = self.env.domaindata['elisp']['objects'] + objs[sig] = { + 'docname': self.env.docname, + 'anchor': f'elispobj-{sig}', + 'type': self.object_type, + } + + +class AbstractVariable(AbstractElisp): + object_type = 'variable' + + def handle_signature(self, sig, signode): + signode += addnodes.desc_annotation(sig, sig) + return sig + + def run(self): + extra = [] + + default = self.default_value() + if default: + extra.append(f'Default: ``{default}``') + if self.is_buffer_local(): + extra.append('buffer-local') + + self.content.data.extend(['', ', '.join(extra)]) + retval = super().run() + return retval + + +class Variable(AbstractVariable): + required_arguments = 1 + optional_arguments = 2 + + def default_value(self): + try: + return self.arguments[1] + except IndexError: + return None + + def is_buffer_local(self): + return 'bufloc' in self.arguments[1:] + + +class AutoVariable(AbstractVariable): + required_arguments = 1 + + def is_buffer_local(self): + return emacs_is_local(self.arguments[0]) + + def default_value(self): + return emacs_default_value(self.arguments[0]) + + def run(self): + docstring = emacs_variable_docstring(self.arguments[0]) + self.content.data.extend(docstring.split('\n')) + return super().run() + + +class AutoFunction(AbstractElisp): + required_arguments = 1 + + @property + def object_type(self): + return 'macro' if DATA[self.arguments[0]]['macrop'] else 'function' + + def handle_signature(self, sig, signode): + args = emacs_arglist(sig) + signode += addnodes.desc_annotation(sig, f'({sig} {args})') + return sig + + def run(self): + docstring = emacs_function_docstring(self.arguments[0]) + self.content.data.extend(docstring.split('\n')) + return super().run() + + +class ElispIndex(Index): + name = 'index' + localname = 'Emacs lisp functions and variables' + shortname = 'Elisp' + + def generate(self, docnames=None): + index = {} + for name, item in self.domain.data['objects'].items(): + if name.startswith('evil-'): + letter = name[5].upper() + else: + letter = name[0].upper() + index.setdefault(letter, []).append(( + name, + 0, + item['docname'], + item['anchor'], + item['type'], + '', + '', + )) + + index = {k: sorted(v, key=lambda k: k[0].lower()) for k, v in index.items()} + index = list(index.items()) + index = sorted(index, key=lambda k: k[0]) + return index, True + + +class Elisp(Domain): + name = 'elisp' + label = 'Emacs lisp' + + object_types = { + 'variable': ObjType('variable', 'variable', 'obj'), + 'autovariable': ObjType('autovariable', 'autovariable', 'obj'), + 'autofunction': ObjType('autofunction', 'autofunction', 'obj'), + } + + directives = { + 'variable': Variable, + 'autovariable': AutoVariable, + 'autofunction': AutoFunction, + } + + roles = { + 'ref': XRefRole(), + } + + initial_data = { + 'objects': {}, + } + + indices = { + ElispIndex, + } + + def resolve_xref(self, env, fromdocname, builder, typ, target, node, contnode): + obj = self.data['objects'].get(target, None) + if obj is None: + return None + return make_refnode(builder, fromdocname, obj['docname'], obj['anchor'], contnode, obj['anchor']) + + +def setup(app): + app.add_domain(Elisp) + StandardDomain.initial_data['labels']['elispindex'] = ('elisp-index', '', 'Emacs lisp functions and variables') + StandardDomain.initial_data['anonlabels']['elispindex'] = ('elisp-index', '') + + return { + 'version': '0.1', + 'parallel_read_safe': True, + 'parallel_write_safe': True, + } diff --git a/elpa/evil-1.15.0/doc/source/conf.py b/elpa/evil-1.15.0/doc/source/conf.py new file mode 100644 index 0000000..8e5f4ae --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/conf.py @@ -0,0 +1,90 @@ +# Configuration file for the Sphinx documentation builder. +# +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# + +import os, sys +sys.path.append(os.path.abspath("./_ext")) + + +# -- Project information ----------------------------------------------------- + +project = 'Evil' +copyright = '2011-2019, Eivind Fonn, Frank Fischer, Vegard Øye' +author = 'Eivind Fonn, Frank Fischer, Vegard Øye' + +# The full version, including alpha/beta/rc tags +release = '1.15.0' + +master_doc = 'index' + + +latex_elements = { + 'fontpkg': r'\usepackage{palatino} \usepackage{inconsolata}', + 'maketitle': r""" + \newcommand\sphinxbackoftitlepage{{ + Copyright {copyright}. + + \begin{{quote}} + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, + and no Back-Cover Texts. A copy of the license is included in + the section entitled ``GNU Free Documentation License''. + \end{{quote}} + + The Evil team thanks everyone at gmane.emacs.vim-emulation for + their feedback and contributions. + }} + \sphinxmaketitle + """.format(copyright=copyright), +} + + +texinfo_documents = [ + (master_doc, 'evil', 'Evil documentation', author, 'evil', + 'Extensible vi layer for Emacs', 'Emacs'), +] + + +# -- General configuration --------------------------------------------------- + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'elisp', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/elpa/evil-1.15.0/doc/source/extension.rst b/elpa/evil-1.15.0/doc/source/extension.rst new file mode 100644 index 0000000..9cae483 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/extension.rst @@ -0,0 +1,146 @@ +Extension +========= + +The main functionality of Evil is implemented in terms of reusable +macros. Package writers can use these to define new commands. + + +Motions +------- + +A *motion* is a command which moves the cursor, such as :kbd:`w` or +:kbd:`e`. Motions are defined with the macro +:elisp:ref:`evil-define-motion`. Motions not defined in this way +should be declared with :elisp:ref:`evil-declare-motion`. + +.. elisp:autofunction:: evil-declare-motion + +.. elisp:autofunction:: evil-define-motion + +For example, this is a motion that moves the cursor forward by a +number of characters: + +.. code-block:: elisp + + (evil-define-motion foo-forward (count) + "Move to the right by COUNT characters." + :type inclusive + (forward-char (or count 1))) + +The *type* of a motion determines how it works when used together with +an operator. Inclusive motions include the endpoint in the range +being operated on, while exclusive motions do not. Line motions +extend the whole range to linewise positions, effectively behaving as +if the endpoint were really at the end of the line. Blockwise ranges +behave as a "rectangle" on screen rather than a contiguous range of +characters. + + +Operators +--------- + +An operator is a command that acts on the text moved over by a motion, +such as :kbd:`c` (change), :kbd:`d` (delete) or :kbd:`y` (yank or +copy, not to be confused with "yank" in Emacs terminology which means +*paste*). + +.. elisp:autofunction:: evil-define-operator + +For example, this is an operator that performs ROT13 encryption on the +text under consideration: + +.. code-block:: elisp + + (evil-define-operator evil-rot13 (beg end) + "ROT13 encrypt text." + (rot13-region beg end)) + +Binding this to :kbd:`g?` (where it is by default) will cause a key +sequence such as :kbd:`g?w` to encrypt from the current cursor to the +end of the word. + + +Text objects +------------ + +Text objects are like motions in that they define a range over which +an operator may act. Unlike motions, text objects can set both a +beginning and an endpoint. In visual state, text objects alter both +ends of the selection. + +Text objects are not directly usable in normal state. Instead, they +are bound in the two keymaps ``evil-inner-text-ojects-map`` and +``evil-outer-text-objects-map``, which are available in visual and +operator-pending state under the keys :kbd:`i` and :kbd:`a` +respectively. + +.. elisp:autofunction:: evil-define-text-object + +For eample, this is a text object which selects the next three +characters after the current location: + +.. code-block:: elisp + + (evil-define-text-object foo (count) + "Select three characters." + (list (point) (+ 3 (point)))) + +For convenience, Evil provides several functions returning a list of +positions which can be used for defining text objects. All of them +follow the convention that a positive *count* selects text after the +current location, while negative *count* selects text before it. + +.. note:: + + The *thingatpt* library is used quite extensively in Evil to define + text objects, and this dependency leaks through in the following + functions. A *thing* in this context is any symbol for which there + is a function called ``forward-THING`` [#thing]_ which moves past a + number of *things*. + +.. elisp:autofunction:: evil-select-inner-object + +.. elisp:autofunction:: evil-select-an-object + +.. elisp:autofunction:: evil-select-paren + + +Range types +----------- + +A *type* is a transformation acting on a pair of buffer positions. +Evil defines the types ``inclusive``, ``line``, ``block`` and +``exclusive``, which are used for motion ranges and visual selection. +New types may be defined with the macro *evil-define-type*. + +.. elisp:autofunction:: evil-define-type + + +States +------ + +States are defined with the macro :elisp:ref:`evil-define-state`, +which takes care to define the necessary hooks, keymaps and variables, +as well as a toggle function ``evil-NAME-state`` and a predicate +function ``evil-NAME-state-p`` for checking whether the state is +active. + +.. elisp:autofunction:: evil-define-state + +For example: + +.. code-block:: elisp + + (evil-define-state test + "Test state." + :tag " <T> " + (message (if (evil-test-state-p) + "Enabling test state." + "Disabling test state."))) + + +.. rubric:: Footnotes + +.. [#thing] There are many more ways that a *thing* can be defined, + but the definition of ``forward-THING`` is perhaps the most + straightforward way to go about it. diff --git a/elpa/evil-1.15.0/doc/source/faq.rst b/elpa/evil-1.15.0/doc/source/faq.rst new file mode 100644 index 0000000..d389df0 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/faq.rst @@ -0,0 +1,118 @@ +Frequently Asked Questions +========================== + +Problems with the escape key in the terminal +-------------------------------------------- + +A common problem when using Evil in terminal mode is a certain delay +after pressing the escape key. Even more, when pressing the escape key +followed quickly by another key the command is recognized as +:kbd:`M-<key>` instead of two separate keys: :kbd:`ESC` followed by +:kbd:`<key>`. In fact, it is perfectly valid to simulate +:kbd:`M-<key>` by pressing :kbd:`ESC <key>` quickly (but see below). + +The reason for this is that in terminal mode a key sequence involving +the meta key (or alt key) always generates a so called "escape +sequence", i.e. a sequence of two events sent to Emacs, the first +being :kbd:`ESC` and the second the key pressed simultaneously. The +problem is that pressing the escape key itself also generates the +:kbd:`ESC` event. Thus, if Emacs (and therefore Evil) receives an +:kbd:`ESC` event there is no way to tell whether the escape key has +been pressed (and no further event will arrive) or a :kbd:`M-<key>` +combination has been pressed (and the :kbd:`<key>` event will arrive +soon). In order to distinguish both situations Evil does the +following. After receiving an :kbd:`ESC` event Evil waits for a short +time period (specified by the variable :elisp:ref:`evil-esc-delay` +which defaults to 0.01 seconds) for another event. If no other event +arrives Evil assumes that the plain escape key has been pressed, +otherwise it assumes a :kbd:`M-<key>` combination has been pressed and +combines the :kbd:`ESC` event with the second one. Because a +:kbd:`M-<key>` sequence usually generates both events in very quick +succession, 0.01 seconds are usually enough and the delay is hardly +noticeable by the user. + +If you use a terminal multiplexer like *tmux* or *screen* the +situation may be worse. These multiplexers have exactly the same +problem recognizing :kbd:`M-<key>` sequences and often introduce their +own delay for the :kbd:`ESC` key. There is no way for Evil to +influence this delay. In order to reduce it you must reconfigure your +terminal multiplexer. + +Note that this problem should not arise when using Evil in graphical +mode. The reason is that in this case the escape key itself generates +a different command, namely ``escape`` (a symbol) and hence Evil can +distinguish whether the escape key or a :kbd:`M-<key>` combination has +been pressed. But this also implies that pressing :kbd:`ESC` followed +by <key> cannot be used to simulate :kbd:`M-<key>` in graphical mode! + + +Underscore is not a word character +---------------------------------- + +An underscore ``_`` is a word character in Vim. This means that word +motions like :kbd:`w` skip over underlines in a sequence of letters as +if it was a letter itself. In contrast, in Evil the underscore is +often a non-word character like operators, e.g. ``+``. + +The reason is that Evil uses Emacs' definition of a word and this +definition does often not include the underscore. In Emacs word +characters are determined by the syntax-class of the buffer. The +syntax-class usually depends on the major-mode of this buffer. This +has the advantage that the definition of a "word" may be adapted to +the particular type of document being edited. Evil uses Emacs' +definition and does not simply use Vim's definition in order to be +consistent with other Emacs functions. For example, word characters +are exactly those characters that are matched by the regular +expression character class ``[:word:]``. + +If you would be satisfied by having the :kbd:`*` and :kbd:`#` searches +use symbols instead of words, this can be achieved by setting the +:elisp:ref:`evil-symbol-word-search` variable to ``t``. + +If you want the underscore to be recognised as word character for other +motions, you can modify its entry in the syntax-table: + +.. code-block:: elisp + + (modify-syntax-entry ?_ "w") + +This gives the underscore the 'word' syntax class. You can use a +mode-hook to modify the syntax-table in all buffers of some mode, +e.g.: + +.. code-block:: elisp + + (add-hook 'c-mode-common-hook + (lambda () (modify-syntax-entry ?_ "w"))) + +This gives the underscore the word syntax-class in all C-like buffers. + +Similarly to Emacs' definition of a word, the definition of a "symbol" is also +dependent on the syntax-class of the buffer, which often includes the +underscore. The default text objects keymap associates kbd::`o` with the symbol +object, making kbd::`cio` a good alternative to Vim's kbd::`ciw`, for example. +The following will swap between the word and symbol objects in the keymap: + +.. code-block:: elisp + + (define-key evil-outer-text-objects-map "w" 'evil-a-symbol) + (define-key evil-inner-text-objects-map "w" 'evil-inner-symbol) + (define-key evil-outer-text-objects-map "o" 'evil-a-word) + (define-key evil-inner-text-objects-map "o" 'evil-inner-word) + +This will not change the motion keys, however. One way to make word motions +operate as symbol motions is to alias the ``evil-word`` *thing* [#thingatpt]_ to +the ``evil-symbol`` thing: + +.. code-block:: elisp + + (defalias 'forward-evil-word 'forward-evil-symbol) + + +.. rubric:: Footnotes + +.. [#thingatpt] Many of Evil's text objects and motions are defined in + terms of the *thingatpt* library, which in this case are defined + entirely in terms of ``forward-THING`` functions. Thus aliasing + one to another should make all motions and text objects implemented + in terms of that *thing* behave the same. diff --git a/elpa/evil-1.15.0/doc/source/hooks.rst b/elpa/evil-1.15.0/doc/source/hooks.rst new file mode 100644 index 0000000..28ade72 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/hooks.rst @@ -0,0 +1,16 @@ +Hooks +===== + +A *hook* is a list of functions that are executed when certain events +happen. Hooks are modified with the Emacs function ``add-hook``. +Evil provides entry and exit hooks for all its states. For example, +when switching from normal state to insert state, all functions in +``evil-normal-state-exit-hook`` and ``evil-insert-state-entry-hook`` +are executed. + +It is guaranteed that the exit hook will be executed before the entry +hook on all state switches. + +During the hook execution, the variables ``evil-next-state`` and +``evil-previous-state`` contain information about the states being +switched to and from, respectively. diff --git a/elpa/evil-1.15.0/doc/source/index.rst b/elpa/evil-1.15.0/doc/source/index.rst new file mode 100644 index 0000000..95da7b7 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/index.rst @@ -0,0 +1,21 @@ +.. Evil documentation master file, created by + sphinx-quickstart on Thu Dec 12 10:34:49 2019. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Evil +==== + +.. toctree:: + :maxdepth: 2 + :caption: Contents + + overview + settings + keymaps + hooks + extension + faq + internals + license + indices diff --git a/elpa/evil-1.15.0/doc/source/indices.rst b/elpa/evil-1.15.0/doc/source/indices.rst new file mode 100644 index 0000000..46f687e --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/indices.rst @@ -0,0 +1,6 @@ +.. only:: html + + Index + ===== + + - :ref:`elispindex` diff --git a/elpa/evil-1.15.0/doc/source/internals.rst b/elpa/evil-1.15.0/doc/source/internals.rst new file mode 100644 index 0000000..9984f7c --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/internals.rst @@ -0,0 +1,36 @@ +Internals +========= + +Command properties +------------------ + +Evil defines *command properties* to store information about commands +[#command]_, such as whether they should be repeated. A command +property is a ``:keyword`` with an associated value, e.g. +``:repeat nil``. + +.. elisp:autofunction:: evil-add-command-properties + +.. elisp:autofunction:: evil-set-command-properties + +.. elisp:autofunction:: evil-get-command-properties + +.. elisp:autofunction:: evil-get-command-property + +.. elisp:autofunction:: evil-define-command + + +For setting repeat properties, use the following functions: + +.. elisp:autofunction:: evil-declare-repeat + +.. elisp:autofunction:: evil-declare-not-repeat + +.. elisp:autofunction:: evil-declare-change-repeat + + +.. rubric:: Footnotes + +.. [#command] In this context, a *command* may mean any Evil motion, + text object, operator or indeed other Emacs commands, which have + not been defined through the Evil machinery. diff --git a/elpa/evil-1.15.0/doc/source/keymaps.rst b/elpa/evil-1.15.0/doc/source/keymaps.rst new file mode 100644 index 0000000..36f8141 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/keymaps.rst @@ -0,0 +1,145 @@ +.. _chapter-keymaps: + +Keymaps +======= + +Evil's key bindings are stored in a number of different keymaps. Each +state has a *global keymap*, where the default bindings for that state +are stored. They are named ``evil-normal-state-map``, +``evil-insert-state-map``, and so on. The bindings in these maps are +visible in all buffers currently in the corresponding state. + +These keymaps function like ordinary Emacs keymaps and may be modified +using the Emacs function ``define-key``: + +.. code-block:: elisp + + (define-key evil-normal-state-map (kbd "w") 'some-function) + +This binds the key :kbd:`w` to the command ``some-function`` in normal +state. The use of ``kbd`` is optional for simple key sequences, like +this one, but recommended in general. + +Most of Evil's bindings are defined in the file ``evil-maps.el``. + +To facilitate shared keybindings between states, some states may +activate keybindings from other states as well. For example, motion +state bindings are visible in normal and visual state, and normal +state bindings are also visible in visual state. + +Each state also has a *buffer-local keymap* which is specific to the +current buffer, and which takes precedence over the global keymap. +These maps are most suitably modified by a mode hook. They are named +``evil-normal-state-local-map``, ``evil-insert-state-local-map``, and +so on. + +.. code-block:: elisp + + (add-hook 'some-mode-hook + (lambda () + (define-key evil-normal-state-local-map + (kbd "w") 'some-function))) + +For convenience, the functions :elisp:ref:`evil-global-set-key` and +:elisp:ref:`evil-local-set-key` are available for setting global and +local state keys. + +.. elisp:autofunction:: evil-global-set-key + +.. elisp:autofunction:: evil-local-set-key + +The above examples could therefore have been written as follows: + +.. code-block:: elisp + + (evil-global-set-key 'normal (kbd "w") 'some-function) + + (add-hook 'some-mode-hook + (lambda () + (evil-local-set-key 'normal (kbd "w") 'some-function))) + + +evil-define-key +--------------- + +Evil provides the macro :elisp:ref:`evil-define-key` for adding state +bindings to ordinary keymaps. It is quite powerful, and is the +preferred method for fine-tuning bindings to activate in specific +circumstances. + +.. elisp:autofunction:: evil-define-key + +There follows a brief overview of the main functions of this macro. + +- Define a binding in a given state + + .. code-block:: elisp + + (evil-define-key 'state 'global (kbd "key") 'target) + +- Define a binding in a given state in the current buffer + + .. code-block:: elisp + + (evil-define-key 'state 'local (kbd "key") 'target) + +- Define a binding in a given state under the *foo-mode* major mode. + + .. code-block:: elisp + + (evil-define-key 'state foo-mode-map (kbd "key") 'target) + + Note that ``foo-mode-map`` is unquoted, and that this form is safe + before ``foo-mode-map`` is loaded. + +- Define a binding in a given state under the *bar-mode* minor mode. + + .. code-block:: elisp + + (evil-define-key 'state 'bar-mode (kbd "key") 'target) + + Note that ``bar-mode`` is quoted, and that this form is safe before + ``bar-mode`` is loaded. + + +The macro :elisp:ref:`evil-define-key` can be used to augment existing +modes with state bindings, as well as creating packages with custom +bindings. For example, the following will create a minor mode +``foo-mode`` with normal state bindings for the keys :kbd:`w` and +:kbd:`e`: + +.. code-block:: elisp + + (define-minor-mode foo-mode + "Foo mode." + :keymap (make-sparse-keymap)) + + (evil-define-key 'normal 'foo-mode "w" 'bar) + (evil-define-key 'normal 'foo-mode "e" 'baz) + +This minor mode can then be enabled in any buffers where the custom +bindings are desired: + +.. code-block:: elisp + + (add-hook 'text-mode-hook 'foo-mode) ; enable alongside text-mode + + +Leader keys +----------- + +Evil supports a simple implementation of Vim's *leader* keys. To bind +a function to a leader key you can use the expression ``<leader>`` in +a key mapping, e.g. + +.. code-block:: elisp + + (evil-define-key 'normal 'global (kbd "<leader>fs") 'save-buffer) + +Likewise, you can use the expression ``<localleader>`` to mimic Vim's +local leader, which is designed for mode-specific key bindings. + +You can use the function :elisp:ref:`evil-set-leader` to designate +which key acts as the leader and the local leader. + +.. elisp:autofunction:: evil-set-leader diff --git a/elpa/evil-1.15.0/doc/source/license.rst b/elpa/evil-1.15.0/doc/source/license.rst new file mode 100644 index 0000000..39d6701 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/license.rst @@ -0,0 +1,447 @@ +The GNU Free Documentation License +================================== + +Version 1.3, 3 November 2008 + + Copyright (c) 2000, 2001, 2002, 2007, 2008 Free Software + Foundation, Inc. http://fsf.org/ + + Everyone is permitted to copy and distribute verbatim copies of + this license document, but changing it is not allowed. + + +0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document *free* in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + +1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + +2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + +3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + +4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title as + a previous version if the original publisher of that version + gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in the + Modified Version, together with at least five of the principal + authors of the Document (all of its principal authors, if it has + fewer than five), unless they release you from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified Version + under the terms of this License, in the form shown in the + Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, and + add to it an item stating at least the title, year, new authors, + and publisher of the Modified Version as given on the Title + Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document for + public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers to + gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section may + not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties---for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + +5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + +6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + +7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + +8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of + section 4. Replacing Invariant Sections with translations requires + special permission from their copyright holders, but you may + include translations of some or all Invariant Sections in addition + to the original versions of these Invariant Sections. You may + include a translation of this License, and all the license notices + in the Document, and any Warranty Disclaimers, provided that you + also include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + +9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + +10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + http://www.gnu.org/copyleft. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + +11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. diff --git a/elpa/evil-1.15.0/doc/source/overview.rst b/elpa/evil-1.15.0/doc/source/overview.rst new file mode 100644 index 0000000..af91534 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/overview.rst @@ -0,0 +1,117 @@ +Overview +======== + +Evil is an extensible vi layer for Emacs. It emulates the main +features of Vim, [#vim]_ turning Emacs into a modal editor. Like Emacs in +general, Evil is extensible in Emacs Lisp. + + +Installation via package.el +--------------------------- + +Evil is available as a package from MELPA stable, MELPA unstable and +NonGNU ELPA. This is the recommended way of installing Evil. + +To set up `package.el` to work with one of the MELPA repositories, you +can follow the instructions on `melpa.org +<https://melpa.org/#/getting-started>`_. + +Alternatively you can use NonGNU ELPA. It is part of the default +package archives as of Emacs 28. For older Emacs versions you'll need +to add it yourself: + +.. code-block:: elisp + + (add-to-list 'package-archives + (cons "nongnu" (format "http%s://elpa.nongnu.org/nongnu/" + (if (gnutls-available-p) "s" "")))) + +Once that is done, you can execute the following commands:: + + M-x package-refresh-contents + M-x package-install RET evil RET + +Finally, add the following lines to your Emacs init file: + +.. code-block:: elisp + + (require 'evil) + (evil-mode 1) + + +Manual installation +------------------- + +First, install `goto-chg` and `cl-lib`. If you have an Emacs version +of 24.3 or newer, you should already have `cl-lib`. + +Evil lives in a git repository. To download Evil, do:: + + git clone --depth 1 https://github.com/emacs-evil/evil.git + +Then add the following lines to your Emacs init file: + +.. code-block:: elisp + + (add-to-list 'load-path "path/to/evil") + (require 'evil) + (evil-mode 1) + +Ensure that your replace ``path/to/evil`` with the actual path to +where you cloned Evil. + + +Modes and states +---------------- + +The next time Emacs is started, it will come up in *normal state*, +denoted by ``<N>`` in the mode line. This is where the main vi +bindings are defined. Note that you can always disable normal state +with :kbd:`C-z`, which switches to an "Emacs state" (denoted by +``<E>``) in which vi keys are completely disabled. Press :kbd:`C-z` +again to switch back to normal state. + +state + Evil uses the term *state* for what is called a "mode" in regular vi + usage, because *modes* are understood in Emacs terms to mean + something else. + +Evil defines a number of states by default: + +normal state (``<N>``) + This is the default "resting state" of Evil, in which the main body + of vi bindings are defined. + +insert state (``<I>``) + This is the state for insertion of text, where non-modified keys + will insert the corresponding character in the buffer. + +visual state (``<V>``) + A state for selecting text regions. Motions are available for + modifying the selected region, and operators are available for + acting on it. + +replace state (``<R>``) + A special state mostly similar to insert state, except it replaces + text instead of inserting. + +operator-pending state (``<O>``) + A special state entered after launching an operator, but before + specifying the corresponding motion or text object. + +motion state (``<M>``) + A special state useful for buffers that are read-only, where motions + are available but editing operations are not. + +Emacs state (``<E>``) + A state that as closely as possible mimics default Emacs behaviour, + by eliminating all vi bindings, except for :kbd:`C-z`, to re-enter + normal state. + + +.. rubric:: Footnotes + +.. [#vim] Vim is the most popular version of *vi*, a modal text editor + with many implementations. Vim also adds some functions of its + own, like visual selection and text objects. For more information + see `the official Vim website <https://vim.org>`_. diff --git a/elpa/evil-1.15.0/doc/source/settings.rst b/elpa/evil-1.15.0/doc/source/settings.rst new file mode 100644 index 0000000..125d7d6 --- /dev/null +++ b/elpa/evil-1.15.0/doc/source/settings.rst @@ -0,0 +1,195 @@ +Settings +======== + +Evil's behaviour can be adjusted by setting some variables. The list +of all available variables and their current values can be inspected +by doing:: + + M-x customize-group RET evil RET + +To change the value of a variable, you can use this interface, or add +a ``setq`` form to your Emacs init file, preferably before Evil is +loaded. [#order]_ + +.. code-block:: elisp + + (setq evil-shift-width 0) + ;; Load Evil + (require 'evil) + +What follows is a non-exhaustive list of the most relevant +customization options. + + +The initial state +----------------- + +The initial state of a buffer is determined by its major mode. Evil +maintains an association between major modes and their corresponding +states, which is most easily modified using the function +:elisp:ref:`evil-set-initial-state`. + +.. elisp:autofunction:: evil-set-initial-state + +If no state can be found, Evil uses the default initial state. + +.. elisp:autovariable:: evil-default-state + +Alternatively, it is possible to select the initial state based on the +buffer *name* rather than its major mode. This is checked first, so +it takes precedence over the other methods for setting the state. + +.. elisp:autovariable:: evil-buffer-regexps + + +Keybindings and other behaviour +------------------------------- + +Evil comes with a rich system for modifying its key bindings +:ref:`chapter-keymaps`. For the most common tweaks, the following +variables are available. + +.. elisp:autovariable:: evil-toggle-key + +.. elisp:autovariable:: evil-want-C-i-jump + +.. elisp:autovariable:: evil-want-C-u-delete + +.. elisp:autovariable:: evil-want-C-u-scroll + +.. elisp:autovariable:: evil-want-C-d-scroll + +.. elisp:autovariable:: evil-want-C-w-delete + +.. elisp:autovariable:: evil-want-C-w-in-emacs-state + +.. elisp:autovariable:: evil-want-Y-yank-to-eol + +.. elisp:autovariable:: evil-disable-insert-state-bindings + + +Search +------ + +.. elisp:autovariable:: evil-search-module + +.. elisp:autovariable:: evil-regexp-search + +.. elisp:autovariable:: evil-search-wrap + +.. elisp:autovariable:: evil-flash-delay + +.. elisp:autovariable:: evil-ex-hl-update-delay + +.. elisp:autovariable:: evil-ex-search-incremental + + +Indentation +----------- + +.. elisp:autovariable:: evil-auto-indent + +.. elisp:autovariable:: evil-shift-width + +.. elisp:autovariable:: evil-shift-round + +.. elisp:autovariable:: evil-indent-convert-tabs + + +Cursor movement +--------------- + +In standard Emacs terms, the cursor is generally understood to be +located between two characters. In Vim, and therefore also Evil, this +is the case in insert state, but in other states the cursor is +understood to be *on* a character, and that this character is not a +newline. + +Forcing this behaviour in Emacs is the source of some potentially +surprising results (especially for traditional Emacs users---users +used to Vim may find the default behavior to their satisfaction). Many +of them can be tweaked using the following variables. + +.. elisp:autovariable:: evil-repeat-move-cursor + +.. elisp:autovariable:: evil-move-cursor-back + +.. elisp:autovariable:: evil-move-beyond-eol + +.. elisp:autovariable:: evil-cross-lines + +.. elisp:autovariable:: evil-respect-visual-line-mode + +.. elisp:autovariable:: evil-track-eol + +.. elisp:autovariable:: evil-start-of-line + + +Cursor display +-------------- + +A state may change the appearance of the cursor. Use the variable +:elisp:ref:`evil-default-cursor` to set the default cursor, and the +variables ``evil-normal-state-cursor``, ``evil-insert-state-cursor`` +etc. to set the cursors for specific states. The acceptable values +for all of them are the same. + +.. elisp:autovariable:: evil-default-cursor + + +Window management +----------------- + +.. elisp:autovariable:: evil-auto-balance-windows + +.. elisp:autovariable:: evil-split-window-below + +.. elisp:autovariable:: evil-vsplit-window-right + + +Parenthesis highlighting +------------------------ + +These settings concern the integration between Evil and +``show-paren-mode``. They take no effect if this mode is not enabled. + +.. elisp:autovariable:: evil-show-paren-range + +.. elisp:autovariable:: evil-highlight-closing-paren-at-point-states + + +Miscellaneous +------------- + +.. elisp:autovariable:: evil-want-fine-undo + +.. elisp:autovariable:: evil-undo-system + +.. elisp:autovariable:: evil-backspace-join-lines + +.. elisp:autovariable:: evil-kbd-macro-suppress-motion-error + +.. elisp:autovariable:: evil-mode-line-format + +.. elisp:autovariable:: evil-mouse-word + +.. elisp:autovariable:: evil-bigword + +.. elisp:autovariable:: evil-esc-delay + +.. elisp:autovariable:: evil-intercept-esc + +.. elisp:autovariable:: evil-kill-on-visual-paste + +.. elisp:autovariable:: evil-echo-state + +.. elisp:autovariable:: evil-complete-all-buffers + +.. elisp:autovariable:: evil-want-empty-ex-last-command + + +.. rubric:: Footnotes + +.. [#order] Strictly speaking, the order only matters if the variable + affects the way Evil is loaded. This is the case with some + variables. |