paper-tonic/doc/paper-tonic.txt

187 lines
6.5 KiB
Plaintext
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

*paper-tonic.txt* Plugin for maintaining colorschemes
*paper-tonic*
Author: Iron-E https://github.com/Iron-E & https://gitlab.com/Iron_E
Web: https://github.com/Iron-E/nvim-paper-tonic
|paper-tonic| is a plugin for creating and maintaining colorschemes. It can
be configured by cloning the repository and following the README, or
individually used to comprehensively highlight groups with its functions.
==============================================================================
TABLE OF CONTENTS *paper-tonic-toc*
1. Requirements ............ |paper-tonic-requirements|
2. Usage ................... |paper-tonic-usage|
3. FAQ ..................... |paper-tonic-faq|
==============================================================================
REQUIREMENTS *paper-tonic-requirements*
- Neovim 0.5+
==============================================================================
USAGE *paper-tonic-usage*
*paper-tonic.group()*
`paper-tonic`.group({group_name}) *paper-tonic-group()*
Convert a pre-existing |highlight-group| into a format that |paper-tonic|
recognizes.
Note: the |highlight-group| must have been either:
- |:highlight|ed.
- |paper-tonic-highlight|ed.
Parameters: ~
{group_name} A `string` which is the |highlight-group| to convert.
Return: ~
- A `table` which can be used as the {attributes} parameter for
|paper-tonic.highlight()|.
Example: ~
>
local paper-tonic = require('paper-tonic')
-- get the 'Error' highlight group
local hl_error = paper-tonic.group('Error')
-- Define 'ErrorMsg' as foreground = background of 'Error'
paper-tonic.highlight('ErrorMsg', {fg=hl_error.bg, bg=BG})
<
*paper-tonic.highlight()*
`paper-tonic`.highlight({group}, {attributes}) *paper-tonic-highlight()*
Highlight some {group} according to its {attributes}.
Note: this method is intended to be used instead of |:highlight|.
Parameters: ~
{group} A `string` which is the |highlight-group| to |:highlight|.
{attributes} A |lua| `table` which follows this format: >
{
-- The color for the background; or `NONE`, `FG` or `BG`
bg = <color>,
-- The color for the foreground; or `NONE`, `FG` or `BG`
fg = <color>
-- The |highlight-blend| value, if one is desired.
[, blend = <integer>]
-- Style can be from |attr-list|.
-- It can also have a color, and/or multiple <cterm>s.
[, style = <cterm>|{<cterm> (, <cterm>) [color=<color>]} ]
}
<
Return: ~
- Nothing.
Example: ~
>
local paper-tonic = require('paper-tonic')
local yellow = {'#f0df33', 220, 'yellow'}
-- Highlight a new group
paper-tonic.highlight('Todo', {fg=yellow, style={'bold', 'underline'}})
-- Link a grou
paper-tonic.highlight('Identifier', 'Todo')
<
See also: ~
|group-names| Additional semantic highlighting groups.
*paper-tonic:highlight_terminal()*
*paper-tonic-highlight_terminal()*
`paper-tonic`:highlight_terminal({terminal_ansi_colors})
Override the |terminal| colors with a new table of {terminal_ansi_colors}.
Parameters: ~
{terminal_ansi_colors} The colors to use in the |terminal|.
They are defined according to this
format: >
{
[1] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'black'
[2] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'darkred'
[3] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'darkgreen'
[4] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'darkyellow'
[5] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'darkblue'
[6] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'darkmagenta'
[7] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'darkcyan'
[8] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'gray'
[9] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'darkgray'
[10] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'red'
[11] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'green'
[12] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'yellow'
[13] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'blue'
[14] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'magenta'
[15] = {'#<hex>', bit_16, 'bit_8'}, -- overrides 'cyan'
[16] = {'#<hex>', bit_16, '<bit_8>'}, -- overrides 'white'
}
<
Return: ~
- Nothing.
Example: ~
>
local paper-tonic = require('paper-tonic')
paper-tonic:highlight_terminal({
[1] = {'#202020' , 0 , 'black'},
[2] = {'#a80000' , 124 , 'darkred'},
[3] = {'#50de60' , 83 , 'darkgreen'},
[4] = {'#ff8900' , 208 , 'darkyellow'},
[5] = {'#7090ff' , 63 , 'darkblue'},
[6] = {'#bb0099' , 126 , 'darkmagenta'},
[7] = {'#00d0c0' , 38 , 'cyan'},
[8] = {'#808080' , 244 , 'gray'},
[9] = {'#353535' , 236 , 'darkgrey'},
[10] = {'#ee4a59' , 196 , 'red'},
[11] = {'#77ff00' , 72 , 'green'},
[12] = {'#f0df33' , 220 , 'yellow'},
[13] = {'#2bff99' , 33 , 'blue'},
[14] = {'#cf55f0' , 129 , 'magenta'},
[15] = {'#33efff' , 87 , 'cyan'},
[16] = {'#c0c0c0' , 251 , 'gray'},
})
<
See also: ~
|terminal-configuration| Information about how the groups are set.
==============================================================================
FAQ *paper-tonic-faq*
E5108: Error executing lua [string ":lua"]:1: module '<colorscheme>' not found ~
Ensure your colorscheme's base folder is in Neovim's `rtp` before sourcing.
Override the highlighting of one specific highlight group in my init.vim? ~
When using this plugin, it is important to know that you cannot just run `:hi`
on a highlight group and expect that its changes will be retained. You must
attach them to the |ColorScheme| |autocmd-event|, as shown below: >
packadd nvim-paper-tonic
set termguicolors "optional
" WRONG! Don't do this.
hi! Error guifg=#000000 guibg=#FFFFFF
" Do this instead.
augroup Highlite
" You can also use `paper-tonic.highlight()` instead of `:hi!`
autocmd ColorScheme paper-tonic hi! Error guifg=#000000 guibg=#FFFFFF
augroup end
colorscheme paper-tonic
<
Of course, substitute "highlight" with the name of your colorscheme.
===============================================================================
vim:tw=78:ts=4:ft=help:norl: