diff options
Diffstat (limited to 'doc/julia-vim-L2U.txt')
| -rw-r--r-- | doc/julia-vim-L2U.txt | 405 |
1 files changed, 0 insertions, 405 deletions
diff --git a/doc/julia-vim-L2U.txt b/doc/julia-vim-L2U.txt deleted file mode 100644 index 8f3a852c..00000000 --- a/doc/julia-vim-L2U.txt +++ /dev/null @@ -1,405 +0,0 @@ -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 |