From 9b411da84e7c3a4fe753cc59f709cee596c06432 Mon Sep 17 00:00:00 2001 From: Eivind Fonn Date: Wed, 11 Dec 2019 23:09:19 +0100 Subject: Use sphinx for documentation --- .gitignore | 2 + doc/Makefile | 24 +- doc/evil.pdf | Bin 246764 -> 0 bytes doc/evil.texi | 769 ----------------------------------------------- doc/fdl-1.3.texi | 506 ------------------------------- doc/macros.texi | 13 - doc/make.bat | 35 +++ doc/source/_ext/elisp.py | 297 ++++++++++++++++++ doc/source/conf.py | 84 ++++++ doc/source/extension.rst | 146 +++++++++ doc/source/hooks.rst | 16 + doc/source/index.rst | 20 ++ doc/source/indices.rst | 6 + doc/source/internals.rst | 36 +++ doc/source/keymaps.rst | 125 ++++++++ doc/source/license.rst | 447 +++++++++++++++++++++++++++ doc/source/overview.rst | 107 +++++++ doc/source/settings.rst | 185 ++++++++++++ doc/version.texi | 7 - 19 files changed, 1523 insertions(+), 1302 deletions(-) delete mode 100644 doc/evil.pdf delete mode 100644 doc/evil.texi delete mode 100644 doc/fdl-1.3.texi delete mode 100644 doc/macros.texi create mode 100644 doc/make.bat create mode 100644 doc/source/_ext/elisp.py create mode 100644 doc/source/conf.py create mode 100644 doc/source/extension.rst create mode 100644 doc/source/hooks.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/indices.rst create mode 100644 doc/source/internals.rst create mode 100644 doc/source/keymaps.rst create mode 100644 doc/source/license.rst create mode 100644 doc/source/overview.rst create mode 100644 doc/source/settings.rst delete mode 100644 doc/version.texi diff --git a/.gitignore b/.gitignore index 102d7b0..43e3062 100644 --- a/.gitignore +++ b/.gitignore @@ -17,3 +17,5 @@ typescript /doc/*.toc /doc/*.vr /doc/*.vrs +/doc/build/ +*.pyc diff --git a/doc/Makefile b/doc/Makefile index 8c3acf5..d0c3cbf 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -1,10 +1,20 @@ -.PHONY: clean +# Minimal makefile for Sphinx documentation +# -%.info: %.texi - makeinfo --no-split $< +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build -%.pdf: %.texi - texi2pdf $< +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -clean: - rm -f *.aux *.cp *.fn *.fns *.info *.ky *.log *.pg *.toc *.tp *.vr *.vrs +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/evil.pdf b/doc/evil.pdf deleted file mode 100644 index db9296e..0000000 Binary files a/doc/evil.pdf and /dev/null differ diff --git a/doc/evil.texi b/doc/evil.texi deleted file mode 100644 index 407ef7a..0000000 --- a/doc/evil.texi +++ /dev/null @@ -1,769 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@setfilename evil.info -@documentencoding ISO-8859-1 -@include version.texi -@settitle Evil-mode manual -@include macros.texi - -@copying -This manual is for Evil (version @value{VERSION} of @value{UPDATED}), -an extensible vi layer for Emacs. - -Copyright @copyright{} 2011 @authors{}. - -@quotation -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 quotation - -The Evil team thanks everyone at gmane.emacs.vim-emulation for -their feedback and contributions. -@end copying - -@dircategory Emacs -@direntry -* Evil: (evil). Extensible vi layer for Emacs. -@end direntry - -@titlepage -@title Evil -@subtitle Extensible vi layer for Emacs -@author @authors{} -@page -@insertcopying -@end titlepage - -@contents - -@ifnottex -@node Top, Overview, (dir), (dir) -@top Evil - -This is the manual for Evil, an extensible vi layer for Emacs. -@end ifnottex - -@menu -* Overview:: -* Settings:: -* Keymaps:: -* Hooks:: -* Macros:: -* Other internals:: -* GNU Free Documentation License:: -@end menu - -@node Overview -@chapter Overview - -Evil is an extensible vi layer for Emacs. It emulates the main features -of Vim,@footnote{Vim is the most popular version of @dfn{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: @uref{http://www.vim.org/}} turning Emacs into a modal editor. -Like Emacs in general, Evil is extensible in Emacs Lisp. - -@menu -* Installation:: -* Modes and states:: -@end menu - -@node Installation -@section Installation - -Evil lives in a Git repository. To download Evil, do: - -@example -git clone https://github.com/emacs-evil/evil.git -@end example - -@noindent Move Evil to @code{~/.emacs.d/evil}. Then add the following -lines to @code{~/.emacs}: - -@lisp -(add-to-list 'load-path "~/.emacs.d/evil") -(require 'evil) -(evil-mode 1) -@end lisp - -@noindent Evil requires @code{undo-tree.el} to provide linear undo -and undo branches. It is available from -EmacsWiki.@footnote{@uref{http://www.emacswiki.org/emacs/UndoTree}} -(A copy of @code{undo-tree.el} is also included in the Git repository.) - -@node Modes and states -@section Modes and states - -The next time Emacs is started, it will come up in @dfn{Normal state}, -denoted by @code{} on 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 -@code{}) in which vi keys are completely disabled. Press @kbd{C-z} -again to switch back to Normal state. - -Evil uses the term @dfn{state} for what is called a ``mode'' in vi, -since ``mode'' already has its own meaning in Emacs. Evil defines a -number of states, such as Normal state (@code{}), Insert state -(@code{}), Visual state (@code{}), Replace state (@code{}), -Operator-Pending state (@code{}), Motion state (@code{}) and Emacs -state (@code{}). Each state has its own keymaps and customization -variables. - -Meanwhile, a @dfn{mode} in Emacs is a set of key bindings for editing a -certain sort of text, like @code{emacs-lisp-mode} for Emacs Lisp. Modes -may include custom bindings for Evil states. - -@node Settings -@chapter Settings - -Evil's behavior can be adjusted by setting various variables. -The current values may be inspected by doing -@kbd{M-x customize-group RET evil RET}. - -To change the value of a variable, add a @samp{setq} form to -@code{~/.emacs}, preferably before Evil is loaded:@footnote{Strictly -speaking, the order only matters if the variable affects the way Evil is -loaded. This is the case with some of the @samp{evil-want-} variables.} - -@lisp -(setq evil-shift-width 8) -;; @r{Load Evil} -(require 'evil) @r{@dots{}} -@end lisp - -@noindent Note that if a variable is buffer-local, you must use -@samp{setq-default} instead of @samp{setq} to change its global value. - -@defvar evil-auto-indent -Whether the current line is indented when entering Insert state. -If @code{t} (the default), then the line is indented. If @code{nil}, -then the line is not indented. Buffer-local. -@end defvar - -@defvar evil-shift-width -The number of columns a line is shifted by the commands -@kbd{>} and @kbd{<}. -@end defvar - -@defvar evil-repeat-move-cursor -If @code{t} (the default), then repeating a command with @kbd{.} may -change the position of the cursor. If @code{nil}, then the original -position is preserved. -@end defvar - -@defvar evil-find-skip-newlines -If @code{t}, then @kbd{f}, @kbd{F}, @kbd{t} and @kbd{T} may skip over -newlines to find a character. If @code{nil} (the default), then they -are restricted to the current line. -@end defvar - -@defvar evil-move-cursor-back -If @code{t} (the default), then the cursor moves backwards when exiting -Insert state. If @code{nil}, then the cursor does not move. -@end defvar - -@defvar evil-want-fine-undo -If @code{t}, then a change-based action like @kbd{cw} may be undone -in several steps. If @code{nil} (the default), then it is undone in -one step. -@end defvar - -@defvar evil-regexp-search -If @code{t} (the default), then @kbd{/} and @kbd{?} use regular -expressions for searching. If @code{nil}, they use plain text. -@end defvar - -@defvar evil-search-wrap -If @code{t} (the default), then @kbd{/} and @kbd{?} wrap the search -around the buffer. If @code{nil}, then they stop at buffer boundaries. -@end defvar - -@defvar evil-flash-delay -The number of seconds to flash search matches when pressing @kbd{n} -and @kbd{N}. -@end defvar - -@defvar evil-want-C-i-jump -If @code{t} (the default), then @kbd{C-i} jumps forwards in the jump -list. If @code{nil}, then @kbd{C-i} inserts a tab. -@end defvar - -@defvar evil-want-C-u-scroll -If @code{t}, then @kbd{C-u} scrolls the buffer. If @code{nil} (the -default), then @kbd{C-u} begins a numeric prefix argument. -@end defvar - -@menu -* The cursor:: -* The initial state:: -@end menu - -@node The cursor -@section The cursor - -A state may change the cursor's appearance. The cursor settings are -stored in the variables below, which may contain a cursor type as per -the @samp{cursor-type} variable, a color string as passed to the -@samp{set-cursor-color} function, a zero-argument function for changing -the cursor, or a list of the above. For example, the following changes -the cursor in Replace state to a red box: - -@lisp -(setq evil-replace-state-cursor '("red" box)) -@end lisp - -@noindent If the state does not specify a cursor, -@samp{evil-default-cursor} is used. - -@defvar evil-default-cursor -The default cursor. -@end defvar - -@defvar evil-normal-state-cursor -The cursor for Normal state. -@end defvar - -@defvar evil-insert-state-cursor -The cursor for Insert state. -@end defvar - -@defvar evil-visual-state-cursor -The cursor for Visual state. -@end defvar - -@defvar evil-replace-state-cursor -The cursor for Replace state. -@end defvar - -@defvar evil-operator-state-cursor -The cursor for Operator-Pending state. -@end defvar - -@defvar evil-motion-state-cursor -The cursor for Motion state. -@end defvar - -@defvar evil-emacs-state-cursor -The cursor for Emacs state. -@end defvar - -@node The initial state -@section The initial state - -By default, a new buffer comes up in Normal state. This can be changed -with the function @samp{evil-set-initial-state}. - -@defun evil-set-initial-state mode state -Set the initial state for a buffer in which @var{mode} is active to -@var{state}. @var{mode} should be a major mode such as -@code{text-mode}, although minor modes work as well. -@end defun - -@node Keymaps -@chapter Keymaps - -Evil's key bindings are stored in a number of keymaps. Each state has a -@dfn{global keymap}, where the default key bindings for the state are -stored. For example, the global keymap for Normal state is -@samp{evil-normal-state-map}, and the key bindings in this map are seen -in all buffers that are currently in Normal state. - -Keymaps are modified with the Emacs function @samp{define-key}: - -@lisp -(define-key evil-normal-state-map "w" 'foo) -@end lisp - -@noindent This binds the key @kbd{w} to the command @samp{foo} -in Normal state. The file @code{evil-maps.el} contains all the -key bindings. - -@defvar evil-normal-state-map -The global keymap for Normal state. -@end defvar - -@defvar evil-insert-state-map -The global keymap for Insert state. -@end defvar - -@defvar evil-visual-state-map -The global keymap for Visual state. -@end defvar - -@defvar evil-replace-state-map -The global keymap for Replace state. -@end defvar - -@defvar evil-operator-state-map -The global keymap for Operator-Pending state. -@end defvar - -@defvar evil-motion-state-map -The global keymap for Motion state. -@end defvar - -@noindent Each state also has a @dfn{buffer-local keymap}, -which is specific to the current buffer and has precedence over -the global keymap. These maps may be changed from a mode hook. - -@defvar evil-normal-state-local-map -Buffer-local keymap for Normal state. -@end defvar - -@defvar evil-insert-state-local-map -Buffer-local keymap for Insert state. -@end defvar - -@defvar evil-visual-state-local-map -Buffer-local keymap for Visual state. -@end defvar - -@defvar evil-replace-state-local-map -Buffer-local keymap for Replace state. -@end defvar - -@defvar evil-operator-state-local-map -Buffer-local keymap for Operator-Pending state. -@end defvar - -@defvar evil-motion-state-local-map -Buffer-local keymap for Motion state. -@end defvar - -@menu -* @samp{evil-define-key}:: -@end menu - -@node @samp{evil-define-key} -@section @samp{evil-define-key} - -Finally, Evil provides the function @samp{evil-define-key} for adding -state bindings to a regular keymap. - -@defun evil-define-key state keymap key def -In @var{keymap}, create a binding from @var{key} to @var{def} in -@var{state}. @var{state} is one of @samp{normal}, @samp{insert}, -@samp{visual}, @samp{replace}, @samp{operator} and @samp{motion}. -The other parameters are like those of @samp{define-key}. -@end defun - -@noindent @samp{evil-define-key} can be used to augment existing -modes with state bindings, as well as create packages for custom -bindings. For example, the following will create a minor mode -@code{foo-mode} with Normal state bindings for the keys @kbd{w} -and @kbd{e}: - -@lisp -(define-minor-mode foo-mode - "Foo mode." - :keymap (make-sparse-keymap)) - -(evil-define-key 'normal foo-mode-map "w" 'bar) -(evil-define-key 'normal foo-mode-map "e" 'baz) -@end lisp - -@noindent This minor mode can then be enabled in any buffers where -the custom bindings are desired: - -@lisp -(add-hook 'text-mode-hook 'foo-mode) ; @r{enable alongside @code{text-mode}} -@end lisp - -@noindent If the minor mode is put into its own file @code{foo.el} -with a @code{(provide 'foo)} statement, it becomes an Emacs package. - -@node Hooks -@chapter Hooks - -A @dfn{hook} is a list of functions to execute. Hooks are modified with -the Emacs function @samp{add-hook}. Evil provides entry and exit hooks -for all of its states. - -@defvar evil-normal-state-entry-hook -Run when entering Normal state. -@end defvar - -@defvar evil-normal-state-exit-hook -Run when exiting Normal state. -@end defvar - -@defvar evil-insert-state-entry-hook -Run when entering Insert state. -@end defvar - -@defvar evil-insert-state-exit-hook -Run when exiting Insert state. -@end defvar - -@defvar evil-visual-state-entry-hook -Run when entering Visual state. -@end defvar - -@defvar evil-visual-state-exit-hook -Run when exiting Visual state. -@end defvar - -@defvar evil-replace-state-entry-hook -Run when entering Replace state. -@end defvar - -@defvar evil-replace-state-exit-hook -Run when exiting Replace state. -@end defvar - -@defvar evil-operator-state-entry-hook -Run when entering Operator-Pending state. -@end defvar - -@defvar evil-operator-state-exit-hook -Run when exiting Operator-Pending state. -@end defvar - -@defvar evil-motion-state-entry-hook -Run when entering Motion state. -@end defvar - -@defvar evil-motion-state-exit-hook -Run when exiting Motion state. -@end defvar - -@noindent When these hooks are run, the variables @samp{evil-next-state} -and @samp{evil-previous-state} hold information about the states being -switched to and from. - -@defvar evil-next-state -The state being switched to. -@end defvar - -@defvar evil-previous-state -The state being switched from. -@end defvar - -@node Macros -@chapter Macros - -Evil is implemented in terms of reusable macros. Package writers can -use these to define new commands. - -@menu -* Motions:: -* Operators:: -* Text objects:: -* Types:: -* States:: -@end menu - -@node Motions -@section Motions - -A @dfn{motion} is a command which moves the cursor, such as @kbd{w} and -@kbd{e}. Motions are defined with the macro @samp{evil-define-motion}. -Motions not defined in this way should be declared with -@samp{evil-declare-motion}. - -@defun evil-declare-motion command -Declare @var{command} to be a motion. This ensures that it works -properly in Visual state. -@end defun - -@defmac evil-define-motion motion (count args@dots{}) doc keyword-args@dots{} body@dots{} -Define a movement command @var{motion}. A motion can have any number of -arguments, but the first argument, if any, has a predefined meaning as -the @var{count}. It is a positive or negative number, or @code{nil}. -The argument list is followed by the documentation string @var{doc}, -which is followed by optional keyword arguments: - -@table @code -@item :type @var{type} -The @var{type} determines how the motion works after an operator. If -@var{type} is @samp{inclusive}, then the ending position is included in -the motion range. If @var{type} is @samp{line}, then the range is -expanded to linewise positions. If @var{type} is @samp{block}, then the -range is blockwise. The default is @samp{exclusive}, which means that -the range is used as-is. - -@item :jump @var{jump} -If @var{jump} is @code{t}, then the previous position is stored in the -jump list so it can be restored with @kbd{C-o}. The default is -@code{nil}. -@end table - -The keyword arguments are followed by the @var{body}, which is where -the motion's behavior is defined. For instance: - -@lisp -(evil-define-motion foo-forward (count) - "Move to the right by COUNT characters." - :type inclusive - (forward-char (or count 1))) -@end lisp - -For more examples, you can view the source code for any command with -@kbd{C-h k}. For instance, @samp{evil-goto-line} may be viewed by -typing @kbd{C-h k G} and following the file link. -@end defmac - -@node Operators -@section Operators - -An @dfn{operator} is a command which acts on the text moved over by a -motion, such as @kbd{c}, @kbd{d} and @kbd{y}. Operators are defined -with the macro @samp{evil-define-operator}. - -@defmac evil-define-operator operator (beg end type args@dots{}) doc keyword-args@dots{} body@dots{} -Define an operator command @var{operator}. An operator must have at -least two or three arguments, which have predefined meanings. -@var{beg} is the beginning position, @var{end} is the ending position, -and @var{type}, if given, is the type of the motion range. The argument -list is followed by the documentation string @var{doc}, which is -followed by optional keyword arguments: - -@table @code -@item :type @var{type} -Make the input range be a certain @var{type}. For example, an operator -which only works with whole lines may set @var{type} to @samp{line}. - -@item :motion @var{motion} -Use the motion @var{motion} instead of reading one from the keyboard. -This does not affect the behavior in Visual state, where the selection -boundaries are used instead. - -@item :repeat @var{repeat} -If @var{repeat} is @code{t} (the default), then @kbd{.} will repeat the -operator. If @var{repeat} is @code{nil}, then the operator will not be -repeated. - -@item :move-point @var{move-point} -If @var{move-point} is @code{t} (the default), then the cursor is -positioned at the beginning of the range. If @var{move-point} is -@code{nil}, then the original position is preserved. - -@item :keep-visual @var{keep-visual} -If @var{keep-visual} is @code{t}, then the selection is not disabled -when the operator is run in Visual state; it is up to the operator to do -this. The default is @code{nil}, which means that Visual state is -exited automatically. -@end table - -The keyword arguments are followed by the @var{body}, which is where the -operator's actions on @var{beg} and @var{end} are defined. For example, -@samp{evil-rot13}, which is bound to @kbd{g?} and performs ROT13 -encryption on the text, may be defined as: - -@lisp -(evil-define-operator evil-rot13 (beg end) - "ROT13 encrypt text." - (rot13-region beg end)) -@end lisp - -Pressing @kbd{g?w} will encrypt a word by calling @samp{rot13-region} -on the text moved over by the @kbd{w} motion. -@end defmac - -@node Text objects -@section Text objects - -A @dfn{text object} is a special kind of motion which sets a beginning -position as well as an ending position, such as @kbd{iw} and @kbd{a(}. -In Visual state, text objects alter both ends of the selection. Text -objects are defined with the macro @samp{evil-define-text-object}. - -@defmac evil-define-text-object object (count args@dots{}) doc keyword-args@dots{} body@dots{} -Define a text object @var{object}. The first argument has a predefined -meaning as the @var{count}: it is a positive or negative number. The -argument list is followed by the documentation string @var{doc}, which -is followed by optional keyword arguments: - -@table @code -@item :type @var{type} -Use the type @var{type} after an operator. In Visual state, this is the -type of the selection. - -@item :extend-selection @var{extend-selection} -If @var{extend-selection} is @code{t} (the default), then the text -object always enlarges the current selection. If @code{nil}, then the -object replaces the selection. -@end table - -The keyword arguments are followed by the @var{body}, which should -evaluate to a list @code{(@var{beg} @var{end})} of two positions in the -buffer. For example, a text object which selects three characters -following the current position could be defined as: - -@lisp -(evil-define-text-object foo (count) - "Select three characters." - (list (point) (+ (point) 3))) -@end lisp -@end defmac - -@noindent Evil provides several functions which return a list of -positions, for use in the definition of a text object. These functions -follow the rule that a positive @var{count} selects text after the -current position, while a negative @var{count} selects text before it. - -@defun evil-inner-object-range count forward backward -Return a text range @code{(@var{beg} @var{end})} of @var{count} -``inner'' text objects (e.g., @kbd{iw}, @kbd{is}). @var{forward} is a -function which moves to the end of an object, and @var{backward} is a -function which moves to the beginning. -@end defun - -@defun evil-an-object-range count forward backward -Return a text range @code{(@var{beg} @var{end})} of @var{count} text -objects with whitespace (e.g., @kbd{aw}, @kbd{as}). @var{forward} is a -function which moves to the end of an object, and @var{backward} is a -function which moves to the beginning. -@end defun - -@defun evil-paren-range count open close &optional exclusive -Return a text range @code{(@var{beg} @var{end})} of @var{count} -delimited blocks (e.g., @kbd{i(}, @kbd{a(}). @var{open} and @var{close} -are characters. If @var{exclusive} is non-nil, then the delimiters are -excluded from the range. This function uses Emacs' syntax table and is -only applicable for single-character delimiters; use -@samp{evil-regexp-range} to match multiple characters. -@end defun - -@defun evil-regexp-range count open close &optional exclusive -Return a text range @code{(@var{beg} @var{end})} of @var{count} -delimited blocks (e.g., @kbd{it}, @kbd{at}). @var{open} and @var{close} -are regular expressions. If @var{exclusive} is non-nil, then the -delimiters are excluded from the range. -@end defun - -@node Types -@section Types - -A @dfn{type} is a transformation on a pair of buffer positions. Evil -defines the types @samp{exclusive}, @samp{inclusive}, @samp{line} and -@samp{block}, which are used for motion ranges and Visual selection. -Types are defined with the macro @samp{evil-define-type}. - -@defmac evil-define-type type doc keyword-args@dots{} -Define a type @var{type}, described by the documentation string -@var{doc}. Then follows keyword arguments: - -@table @code -@item :expand @var{expand} -A function which takes two buffer positions and returns a list -@code{(@var{beg} @var{end})} of expanded positions. - -@item :contract @var{contract} -A function which takes two expanded buffer positions and returns a list -@code{(@var{beg} @var{end})} of unexpanded positions. Optional. - -@item :normalize @var{normalize} -A function which takes two unexpanded buffer positions and returns a -list @code{(@var{beg} @var{end})} of adjusted positions. Optional. - -@item :injective @var{injective} -If @code{t} (the default), then expansion is one-to-one -- i.e., -@var{expand} followed by @var{contract} always returns the original -positions. If @code{nil}, then several positions may expand to the same -(for example, the @samp{line} type is one-to-many as it expands to the -containing lines). -@end table - -Further keywords and functions may be specified. These are understood -to be transformations on buffer positions, like @var{expand} and -@var{contract}. -@end defmac - -@node States -@section States - -States are defined with the macro @samp{evil-define-state}. The macro -defines the necessary hooks, keymaps and variables for a state, as well -as a toggle function @samp{evil-@var{state}-state} for entering the -state, and a predicate function @samp{evil-@var{state}-state-p} which -returns @code{t} when the state is active, and @code{nil} otherwise. - -@defmac evil-define-state state doc keyword-args@dots{} body@dots{} -Define an Evil state @var{state}, described by the documentation string -@var{doc}. Then follows optional keyword arguments: - -@table @code -@item :tag @var{tag} -Mode line indicitor, e.g., @code{""}. -@item :message @var{message} -String shown in the echo area. -@item :cursor @var{cursor} -Cursor specification. -@item :enable @var{enable} -List of other modes and states to enable. A state may enable another -state's keymaps in addition to its own. -@end table - -This is followed the @var{body}, which is executed whenever the state is -enabled or disabled. The state's predicate function may be used to -distinguish between the two. -@end defmac - -@node Other internals -@chapter Other internals - -@menu -* Command properties:: -@end menu - -@node Command properties -@section Command properties - -Evil defines @dfn{command properties} to store information about -commands, such as whether they should be repeated. A command property -is a @code{@var{:keyword}} with an associated value, e.g., @code{:repeat -nil}. - -@defun evil-add-command-properties command &rest properties -Add @var{properties} to @var{command}. The properties should be -specified as a list of keywords and values: - -@lisp -(evil-add-command-properties 'my-command :repeat t) -@end lisp -@end defun - -@defun evil-set-command-properties command &rest properties -Like @samp{evil-add-command-properties}, but resets all -previous properties. -@end defun - -@defun evil-get-command-property command property -Return the value of a command property. -@end defun - -@defmac evil-define-command command (args@dots{}) doc keyword-args@dots{} body@dots{} -Define a command with command properties @var{keyword-args}. -@end defmac - -@noindent For setting repeat properties, Evil provides the -following functions: - -@defun evil-declare-repeat command -Declare @var{command} to be repeatable. -@end defun - -@defun evil-declare-not-repeat command -Declare @var{command} to be nonrepeatable. -@end defun - -@defun evil-declare-change-repeat command -Declare @var{command} to be repeatable by buffer changes rather than -keystrokes. -@end defun - -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@include fdl-1.3.texi - -@bye - -@c Local Variables: -@c mode: texinfo -@c TeX-master: t -@c sentence-end-double-space: t -@c End: diff --git a/doc/fdl-1.3.texi b/doc/fdl-1.3.texi deleted file mode 100644 index fc19ddd..0000000 --- a/doc/fdl-1.3.texi +++ /dev/null @@ -1,506 +0,0 @@ -@c The GNU Free Documentation License. -@center Version 1.3, 3 November 2008 - -@c This file is intended to be included within another document, -@c hence no sectioning command or @node. - -@display -Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. -@uref{http://fsf.org/} - -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. -@end display - -@enumerate 0 -@item -PREAMBLE - -The purpose of this License is to make a manual, textbook, or other -functional and useful document @dfn{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. - -@item -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, La@TeX{} 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. - -@item -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. - -@item -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. - -@item -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: - -@enumerate A -@item -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. - -@item -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. - -@item -State on the Title page the name of the publisher of the -Modified Version, as the publisher. - -@item -Preserve all the copyright notices of the Document. - -@item -Add an appropriate copyright notice for your modifications -adjacent to the other copyright notices. - -@item -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. - -@item -Preserve in that license notice the full lists of Invariant Sections -and required Cover Texts given in the Document's license notice. - -@item -Include an unaltered copy of this License. - -@item -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. - -@item -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. - -@item -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. - -@item -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. - -@item -Delete any section Entitled ``Endorsements''. Such a section -may not be included in the Modified Version. - -@item -Do not retitle any existing section to be Entitled ``Endorsements'' or -to conflict in title with any Invariant Section. - -@item -Preserve any Warranty Disclaimers. -@end enumerate - -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. - -@item -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.'' - -@item -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. - -@item -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. - -@item -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. - -@item -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. - -@item -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 -@uref{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. - -@item -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. - -@end enumerate - -@page -@heading ADDENDUM: How to use this License for your documents - -To use this License in a document you have written, include a copy of -the License in the document and put the following copyright and -license notices just after the title page: - -@smallexample -@group - Copyright (C) @var{year} @var{your name}. - 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 group -@end smallexample - -If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, -replace the ``with@dots{}Texts.'' line with this: - -@smallexample -@group - with the Invariant Sections being @var{list their titles}, with - the Front-Cover Texts being @var{list}, and with the Back-Cover Texts - being @var{list}. -@end group -@end smallexample - -If you have Invariant Sections without Cover Texts, or some other -combination of the three, merge those two alternatives to suit the -situation. - -If your document contains nontrivial examples of program code, we -recommend releasing these examples in parallel under your choice of -free software license, such as the GNU General Public License, -to permit their use in free software. - -@c Local Variables: -@c ispell-local-pdict: "ispell-dict" -@c End: - diff --git a/doc/macros.texi b/doc/macros.texi deleted file mode 100644 index 90eb1b3..0000000 --- a/doc/macros.texi +++ /dev/null @@ -1,13 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the Evil manual. -@c Copyright (C) 2011 Frank Fischer and Vegard Øye. -@c See the file evil.texi for copying conditions. - -@ifclear macros -@set macros - -@macro authors {} -Frank Fischer and Vegard Øye -@end macro - -@end ifclear diff --git a/doc/make.bat b/doc/make.bat new file mode 100644 index 0000000..6247f7e --- /dev/null +++ b/doc/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/doc/source/_ext/elisp.py b/doc/source/_ext/elisp.py new file mode 100644 index 0000000..ea7f7bd --- /dev/null +++ b/doc/source/_ext/elisp.py @@ -0,0 +1,297 @@ +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_kbd = 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 (.*)\)') + +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) + + # Substitute \[C-z] with :kbd:`C-z` + docstring = re_kbd.sub(r':kbd:`\1`', 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/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..5df3c49 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,84 @@ +# 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.13.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), +} + + +# -- 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/doc/source/extension.rst b/doc/source/extension.rst new file mode 100644 index 0000000..9cae483 --- /dev/null +++ b/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 " " + (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/doc/source/hooks.rst b/doc/source/hooks.rst new file mode 100644 index 0000000..28ade72 --- /dev/null +++ b/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/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..550d438 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,20 @@ +.. 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 + internals + license + indices diff --git a/doc/source/indices.rst b/doc/source/indices.rst new file mode 100644 index 0000000..46f687e --- /dev/null +++ b/doc/source/indices.rst @@ -0,0 +1,6 @@ +.. only:: html + + Index + ===== + + - :ref:`elispindex` diff --git a/doc/source/internals.rst b/doc/source/internals.rst new file mode 100644 index 0000000..9984f7c --- /dev/null +++ b/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/doc/source/keymaps.rst b/doc/source/keymaps.rst new file mode 100644 index 0000000..c1babad --- /dev/null +++ b/doc/source/keymaps.rst @@ -0,0 +1,125 @@ +.. _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 customg +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 diff --git a/doc/source/license.rst b/doc/source/license.rst new file mode 100644 index 0000000..39d6701 --- /dev/null +++ b/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/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 0000000..0bb1a7e --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1,107 @@ +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 and MELPA unstable. +This is the recommended way of installing Evil. + +To set up `package.el` to work with one of these repositories, you can +follow the instructions on +`melpa.org `_. + +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 `undo-tree`, `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 ```` 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 +````) 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 (````) + This is the default "resting state" of Evil, in which the main body + of vi bindings are defined. + +insert state (````) + This is the state for insertion of text, where non-modified keys + will insert the corresponding character in the buffer. + +visual state (````) + A state for selecting text regions. Motions are available for + modifying the selected region, and operators are available for + acting on it. + +replace state (````) + A special state mostly similar to insert state, except it replaces + text instead of inserting. + +operator-pending state (````) + A special state entered after launching an operator, but before + specifying the corresponding motion or text object. + +motion state (````) + A special state useful for buffers that are read-only, where motions + are available but editing operations are not. + +Emacs state (````) + 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 `_. diff --git a/doc/source/settings.rst b/doc/source/settings.rst new file mode 100644 index 0000000..9ae45c6 --- /dev/null +++ b/doc/source/settings.rst @@ -0,0 +1,185 @@ +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-regexp-search + +.. elisp:autovariable:: evil-search-wrap + +.. elisp:autovariable:: evil-flash-delay + +.. elisp:autovariable:: evil-ex-hl-update-delay + + +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 + + +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-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 + + +.. 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. diff --git a/doc/version.texi b/doc/version.texi deleted file mode 100644 index 8531f00..0000000 --- a/doc/version.texi +++ /dev/null @@ -1,7 +0,0 @@ -@c -*-texinfo-*- -@c This is part of the Evil manual. -@c Copyright (C) 2011 Frank Fischer and Vegard Øye. -@c See the file evil.texi for copying conditions. - -@set VERSION 0.1 -@set UPDATED 2011-07-30 -- cgit v1.0