diff options
Diffstat (limited to 'doc/julia-vim-L2U.txt')
| -rw-r--r-- | doc/julia-vim-L2U.txt | 405 |
1 files changed, 405 insertions, 0 deletions
diff --git a/doc/julia-vim-L2U.txt b/doc/julia-vim-L2U.txt new file mode 100644 index 00000000..8f3a852c --- /dev/null +++ b/doc/julia-vim-L2U.txt @@ -0,0 +1,405 @@ +if !exists('g:polyglot_disabled') || index(g:polyglot_disabled, 'julia') == -1 + +*julia-vim-L2U.txt* Support for LaTeX-to-Unicode substitutions + +Author: Carlo Baldassi <carlobaldassi@gmail.com> +License: MIT license {{{ + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +}}} +CONTENTS *julia-vim-L2U* + +LaTeX-to-Unicode substitutions |julia-vim-L2U-introdction| + Via Tab key |julia-vim-L2U-tab| + As you type |julia-vim-L2U-as-you-type| + Via Keymap |julia-vim-L2U-keymap| + On different file types |julia-vim-L2U-file-types| + Enabling and disabling |julia-vim-L2U-enable-disable| +Variables |julia-vim-L2U-variables| +Functions |julia-vim-L2U-functions| + +============================================================================== +LATEX TO UNICODE *julia-vim-L2U-introduction* + +In the Julia REPL, entering a LaTeX-like sequence such as `\alpha` and pressing +the <Tab> key substitutes it with a Unicode character such as `α`. The Julia +REPL also provides partial completions, and suggestions for possible +completions upon repeated pressing of the <Tab> key. Emojis are also +available, with their names written between colons, e.g. `\:interrobang:` +produces `⁉`. + +See |julia-vim-L2U-reference| for the complete table of substitutions. + +This Vim plug-in also provides the functionality needed to convert LaTeX +input sequences into Unicode characters. There are 3 different methods +available: + + 1. The default one is the most similar to the Julia one: substitutions are + triggered by pressing the <Tab> key; if a partial match is found a list + of suggested completions is presented in a menu together with their + Unicode counterpart. The exact behaviour of this feature can be + customized, see |julia-vim-L2U-tab|. + + 2. The second one substitutes symbols on the fly as you type, but only in + |Insert| mode. See |julia-vim-L2U-as-you-type|. + + 3. The third is based on |keymap|. It also substitutes as-you-type, but it + doesn't show you the full LaTeX sequence as you're typing it, and there + is a time-out. Its main advantage over the previous one is that can be + used in more circumstances, e.g. in |Command-line| mode or when searching + for a character with |f| or |t|, as explained in |language-mapping|. See + |julia-vim-L2U-keymap|. + +All of these methods are independent and can be used together without issues. + +The default configuration is to use the first method, and it's only active +when editing Julia files. It only works in |Insert| and |Command-line| modes. + +It is possible to enable it with other file types, see +|julia-vim-L2U-file-types|, and it can be even turned on/off on the fly +regardless of the file type, see |julia-vim-L2U-enable-disable|. + +In |Command-line| mode, e.g. when searching with the |/| or |?| commands, the +default behavior is very similar to the default |Insert| mode behavior, but +slightly more limited, see |julia-vim-L2U-cmdmode|. + +These features only work as described with Vim version 7.4 or higher. Tab +completion can still be made available on lower Vim versions, see +|julia-vim-L2U-workaround|. The keymap mode might work but it hasn't been +tested. + +See |julia-vim| for the general reference about the other features of the +julia-vim plug-in. + +------------------------------------------------------------------------------ +LATEX TO UNICODE VIA TAB KEY *julia-vim-L2U-tab* + +Substitution of LaTeX sequences when pressing the <Tab> key (in |Insert| mode or +in |Command-line| modes) is active by default. Use |g:latex_to_unicode_tab| to +control it. + +When this feature is active, the julia-vim plug-in creates a mapping for the +<Tab> key (in |Insert| mode) which takes precedence on any previously defined +mapping assigned to it, such that when the <Tab> key is pressed the plug-in +looks for potential LaTeX symbol matches before the cursor, and if it fails to +find anything of interest it will fall-back to the previous mapping for <Tab> +(with default Vim settings, this means it will insert a literal <Tab>; but if +you have defined some other behavior for that key, e.g. by installing another +plug-in such as supertab (https://github.com/ervandew/supertab) than that will +be used). + +For example, entering this text in a file: +> + 1 + \alpha +< +and then pressing <Tab>, results in: +> + 1 + α +< + +This feature is associated with 'omnifunc' completion, and therefore can +always be accessed via CTRL-X CTRL-O, even when |g:latex_to_unicode_tab| is 0. + +A literal <Tab> key can always be entered by using CTRL-V before <Tab> (see +|i_CTRL-V|). + +Partial sequence recognition triggers auto-completion (performed as if the +`longest` setting was used in 'completeopt') and shows a menu of suggestions +together with their corresponding Unicode symbol (provided the `menu` setting +is included in 'completeopt', and more then one match is found). So for +example, entering `\al` and pressing <Tab> will result in the following list: +> + +-------------+ + | \aleph ℵ | + | \allequal ≌ | + | \alpha α | + +-------------+ +> +Then, pressing `p` will reduce the list to `\alpha`, pressing <Tab> will +complete it and pressing <Tab> again will perform the substitution. + +The completion menu can be disbled, and this will happen automatically if a +plug-in which is known to be incompatible with this feature is detected: see +|g:latex_to_unicode_suggestions|. + +Some LaTeX sequences can be valid both as they are and as partial matches for +other sequences, e.g. `\ne` is associated with `≠`, but it is also a partial +match for `\nequiv` (`≢`). By default, if <Tab> finds an exact match performs +the substitution, but this can be controlled by the |g:latex_to_unicode_eager| +setting. + +Command-line mode *julia-vim-L2U-cmdmode* + +In |Command-line| mode, the behavior is largely the same except that both +<Tab> and <S-Tab> are mapped by default, and the functionality is slightly +more limited. No suggestions are shown for partial completions. Pre-existing +user-defined mappings of <Tab> are overridden. In order to avoid that, the +completion can be mapped onto a defferent key combination, see +|g:latex_to_unicode_cmd_mapping|. When using <Tab>, if no matches are found +the behavior falls back to the standard Vim command-line completion. + +Vim versions lower than 7.4 *julia-vim-L2U-workaround* + +The <Tab> key remapping is not performed by default with Vim versions lower +than 7.4. However, the functionality is still available via onmicompletion, +which is accessible by the CTRL-X CTRL-O key combination. You can map some +other key combination to this by adding something like +> + inoremap <C-Tab> <C-X><C-O> +< +in your |.vimrc| file. If you'd map <Tab> directly, then you'd need to use +CTRL-V <Tab> to insert a literal <Tab>. + +The settings |g:latex_to_unicode_eager| and |g:latex_to_unicode_suggestions| +are still meaningful in this case. + +------------------------------------------------------------------------------ +LATEX TO UNICODE AS YOU TYPE *julia-vim-L2U-as-you-type* + +This feature is disabled by default, see |g:latex_to_unicode_auto|, and it is +only available with Vim version 7.4 or higher. It consists in substituting +valid LaTeX sequences with Unicode symbols automatically as the typing +progresses, as soon as the sequences is unambiguously complete. For example, +when typing: +> + \chi\^2 = 1 +< +The result is +> + χ² = 1 +< +The `\chi` is substituted right when the second backslash is entered, and the +`\^2` is substituted when the following space is entered, before the equal +sign. + +This feature does not currently work with emojis. + +This feature does not interfere with the <Tab> based substitution. + +------------------------------------------------------------------------------ +LATEX TO UNICODE VIA KEYMAP *julia-vim-L2U-keymap* + +This method is somewhat similar to the as-you-type one described above, but it +uses |keymap| to generate the mappings. This has the advantage that it works +in more circumstances, e.g. in |Command-line| mode or when searching within a +line with |f| or |t| (since it uses |language-mapping| underneath). It can +also be easily turned on or off like any other keymap (see |i_CTRL-^| and +|c_CTRL-^|). Like the as-you-type fature, it doesn't work with emojis. +The disadvantage is that you don't see the whole sequence as you're typing +it, and you can't fix mistakes with backspace, for example. +Another difference is that there is a |timeout| like for any other mapping. + +In order to use this method, set |g:latex_to_unicode_keymap| to `1`. +You can use it in parallel with the other methods, they don't interfere. For +example, typing a partial sequence and pressing <Tab> still triggers +completions and suggestions if |g:latex_to_unicode_tab| is active. + +If you use this feature, it's also useful to set |lCursor|. + +------------------------------------------------------------------------------ +LATEX TO UNICODE ON DIFFERENT FILE TYPES *julia-vim-L2U-file-types* + +By default, the LaTeX-to-Unicode substitutions are only active when editing +Julia files. However, you can use the variable |g:latex_to_unicode_file_types| +to specify for which file types this feature is active by default. The +variable must be set to a string containing a |pattern| (a regular expression) +which matches the desired file types, or to a list of such patterns. For +example, to activate the feature on all file types by default, you could put +this in your |.vimrc| file: +> + let g:latex_to_unicode_file_types = ".*" +< +To make it active only on, say, Julia and Lisp files, you could use: +> + let g:latex_to_unicode_file_types = ["julia", "lisp"] +< + +Another option, |g:latex_to_unicode_file_types_blacklist|, can be used to +exclude certain file types. For example, if you'd wish to enable the feature +in all cases except for Python and untyped files, you would use: +> + let g:latex_to_unicode_file_types = ".*" + let g:latex_to_unicode_file_types_blacklist = ["python", ""] +< + +NOTE: enabling the functionality will override the |'omnifunc'| setting, which +can be undesirable, and interfere with plug-ins for different file types. In +any case, the previous |'omnifunc'| setting is restored when the functionality +is disabled, see |julia-vim-L2U-enable-disable|. + +------------------------------------------------------------------------------ +ENABLING AND DISABLING LATEX TO UNICODE *julia-vim-L2U-enable-disable* + +The LaTeX-to-Unicode functionality can be enabled or disabled at any time, +regardless of the |'filetype'| of the file you're editing, using the functions +|LaTeXtoUnicode#Enable()|, |LaTeXtoUnicode#Disable()|, |LaTeXtoUnicode#Toggle()|. +For example, you could use a mapping like: +> + noremap <expr> <F7> LaTeXtoUnicode#Toggle() + noremap! <expr> <F7> LaTeXtoUnicode#Toggle() +< +and then use the <F7> key to quickly switch the functionality on and off as +needed (see |noremap| and |noremap!|). + +NOTE: these functions are different from the variables |g:latex_to_unicode_tab|, +|g:latex_to_unicode_auto| and |g:latex_to_unicode_keymap|: the functions +enable/disable the functionality as a whole, while the variables control +individual features (tab, auto and keymap substitution). + +============================================================================== +VARIABLES *julia-vim-L2U-variables* + + *g:latex_to_unicode_tab* +g:latex_to_unicode_tab + + Determines whether to map LaTeX-to-Unicode substitution to the + <Tab> key while in |Insert| and |Command-line| modes, see + |julia-vim-L2U-tab|. If unspecified, it is on. You can disable + the feature by default by inserting the line +> + let g:latex_to_unicode_tab = 0 +< + in your |.vimrc| file. You can change this setting at any moment + while editing, but you need to invoke |LaTeXtoUnicode#Init()| + for the change to take effect. + + *g:latex_to_unicode_suggestions* +g:latex_to_unicode_suggestions + + Determines whether the <Tab> key mapping produces suggestions + for partial matches. By default, this is set to 1 (active), + unless a plug-in which is known to be incompatible with it is + detected. Currently, known incompatible plug-ins are + YouCompleteMe (https://github.com/Valloric/YouCompleteMe), + neocomplcache (https://github.com/Shougo/neocomplcache.vim), + neocomplete (https://github.com/Shougo/neocomplete.vim) and + deoplete (https://github.com/Shougo/deoplete.nvim), + + This variable can be set at any time, changes will immediately + take effect. + + *g:latex_to_unicode_eager* +g:latex_to_unicode_eager + + Determines whether the <Tab> key mapping performs the + substitution immediately upon finding an exact match. By + default this setting is set to 1 (active), so that e.g. typing + `\ne` and pressing the <Tab> key triggers the substitution. If + this variable is set to 0, an exact match which is also a + possible partial match to some other sequence triggers the + suggestions menu first, but another <Tab> forces the + substitution, so that e.g. typing `\ne` and then <Tab> + produces a list with `\ne`, `\neg`, `\nequiv` etc., and + pressing <Tab> again performs the substitution. + + This variable can be set at any time, changes will immediately + take effect. When |g:latex_to_unicode_suggestions| is `0`, + this setting has no effect (it's like if it was always on). + + *g:latex_to_unicode_auto* +g:latex_to_unicode_auto + + Determines whether to activate LaTeX-to-Unicode substitution + on the fly as you type (in |Insert| mode), see + |julia-vim-L2U-as-you-type|. If unspecified, it is `0` (off). + You can enable the feature by default by inserting the line +> + let g:latex_to_unicode_auto = 1 +< + in your |.vimrc| file. You can change this setting at any + moment while editing, but you need to invoke + |LaTeXtoUnicode#Init()| for the change to take effect. + + + *g:latex_to_unicode_keymap* +g:latex_to_unicode_keymap + + Determines whether to activate the |keymap|-based + LaTeX-to-Unicode substitutions, see |julia-vim-L2U-keymap|. + If unspecified, it is `0` (off). You can enable the feature by + default by inserting the line +> + let g:latex_to_unicode_keymap = 1 +< + in your |.vimrc| file. You can change this setting at any + moment while editing, but you need to invoke + |LaTeXtoUnicode#Init()| for the change to take effect. + + *g:latex_to_unicode_file_types* +g:latex_to_unicode_file_types + + Contains a |pattern|, or a list of patterns, which are matched + against the |'filetype'| to determine when to enable the + LaTeX-to-Unicode functionality, see |julia-vim-L2U-file-types|. + By default, its value is `"julia"`. The patterns provided must + match the whole filetype name. See also + |g:latex_to_unicode_file_types_blacklist|. + + *g:latex_to_unicode_file_types_blacklist* +g:latex_to_unicode_file_types_blacklist + + Same as |g:latex_to_unicode_file_types|, but acts in reverse: + it disables the LaTeX-to-Unicode functionality when the + |'filetype'| matches the provided pattern (or any of the + patterns if a list is provided). By default, it contains an + unmatchable pattern, i.e. it is effectively disabled. + + *g:latex_to_unicode_cmd_mapping* +g:latex_to_unicode_cmd_mapping + + Specifies the mapping (or list of mappings) for the + substitution in |Command-line| mode. By default, it is + `['<Tab>', '<S-Tab>']`, but it can be changed to avoid + overriding other user-defined mapping, e.g. to `'<S-Tab>'` + (if your terminal suppoorts it) or `'<C-\><Tab>'`. + The `'<Tab>'` (or to be more precise the |wildchar| key) and + `'<S-Tab>'` mappings are special in that they fall back to + performing default Vim completions in case no suitable + substitutions are found. + +============================================================================== +FUNCTIONS *julia-vim-L2U-functions* + + *LaTeXtoUnicode#Init()* +LaTeXtoUnicode#Init() + + Initialize or re-initialize the LaTeX-to-Unicode substitutions + (see |julia-vim-L2U-introduction|). Must be invoked after + changing |g:latex_to_unicode_tab| or |g:latex_to_unicode_auto| + to make the changes take effect. + + *LaTeXtoUnicode#Enable()* + *LaTeXtoUnicode#Disable()* + *LaTeXtoUnicode#Toggle()* +LaTeXtoUnicode#Enable() +LaTeXtoUnicode#Disable() +LaTeXtoUnicode#Toggle() + + These functions enable/disable/toggle the LaTeX-to-Unicode + functionality, regardless of the |'filetype'| specified in + |g:latex_to_unicode_file_types| and + |g:latex_to_unicode_file_types_blacklist|. See + |julia-vim-L2U-enable-disable|. Note that LaTeXtoUnicode#Enable() + will override the |'omnifunc'| definition, if present. However, + LaTeXtoUnicode#Disable() will restore it. + These functions implicitly invoke |LaTeXtoUnicode#Init()|. + + + vim:tw=78:et:ft=help:norl: + +endif |