paper-tonic/doc/paper-tonic.txt

*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: